From cfe4212167211bd1f130aecb9a4a7780eb086ec7 Mon Sep 17 00:00:00 2001 From: Azure SDK Bot <53356347+azure-sdk@users.noreply.github.com> Date: Thu, 26 Mar 2026 11:25:21 -0700 Subject: [PATCH 01/11] Update package index with latest published versions (#52696) --- docs/azure/includes/dotnet-all.md | 18 +++++++++--------- docs/azure/includes/dotnet-new.md | 2 +- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index 65eb8a5473e12..d7c15f8dc888e 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -155,7 +155,7 @@ | Provisioning - Cdn | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Cdn/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Cdn-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Cdn_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Cdn/) | | Provisioning - Cognitive Services | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Provisioning.CognitiveServices/1.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.CognitiveServices-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CognitiveServices_1.2.0/sdk/provisioning/Azure.Provisioning.CognitiveServices/) | | Provisioning - Communication | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Provisioning.Communication/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Provisioning.Communication-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Communication_1.0.0-beta.4/sdk/provisioning/Azure.Provisioning.Communication/) | -| Provisioning - Compute | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Compute/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Compute_1.0.0-beta.1/sdk/compute/Azure.Provisioning.Compute/) | +| Provisioning - Compute | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Compute/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Compute-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Compute_1.0.0-beta.1/sdk/compute/Azure.Provisioning.Compute/) | | Provisioning - Container Registry | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.ContainerRegistry/1.1.0) | [docs](/dotnet/api/overview/azure/Provisioning.ContainerRegistry-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ContainerRegistry_1.1.0/sdk/provisioning/Azure.Provisioning.ContainerRegistry/) | | Provisioning - Container Service | NuGet [1.0.0-beta.5](https://www.nuget.org/packages/Azure.Provisioning.ContainerService/1.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Provisioning.ContainerService-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ContainerService_1.0.0-beta.5/sdk/provisioning/Azure.Provisioning.ContainerService/) | | Provisioning - CosmosDB | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Provisioning.CosmosDB/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.CosmosDB/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.CosmosDB-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CosmosDB_1.0.0/sdk/provisioning/Azure.Provisioning.CosmosDB/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CosmosDB_1.1.0-beta.1/sdk/provisioning/Azure.Provisioning.CosmosDB/) | @@ -411,13 +411,13 @@ | Resource Management - Workloadssapvirtualinstance | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.WorkloadsSapVirtualInstance/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.WorkloadsSapVirtualInstance-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.WorkloadsSapVirtualInstance_1.0.0-beta.1/sdk/workloadssapvirtualinstance/Azure.ResourceManager.WorkloadsSapVirtualInstance/) | | App Configuration Extension | NuGet [8.5.0](https://www.nuget.org/packages/Microsoft.Azure.AppConfiguration.Functions.Worker/8.5.0)
NuGet [8.6.0-preview](https://www.nuget.org/packages/Microsoft.Azure.AppConfiguration.Functions.Worker/8.6.0-preview) | | | | App Configuration Provider | NuGet [8.5.0](https://www.nuget.org/packages/Microsoft.Azure.AppConfiguration.AspNetCore/8.5.0)
NuGet [8.6.0-preview](https://www.nuget.org/packages/Microsoft.Azure.AppConfiguration.AspNetCore/8.6.0-preview) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp/1.0.0)
NuGet [2.0.0-beta.32](https://www.nuget.org/packages/Azure.Mcp/2.0.0-beta.32) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/1.0.0)
NuGet [2.0.0-beta.32](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/2.0.0-beta.32) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-x64/1.0.0)
NuGet [2.0.0-beta.32](https://www.nuget.org/packages/Azure.Mcp.linux-x64/2.0.0-beta.32) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.osx-arm64/1.0.0)
NuGet [2.0.0-beta.32](https://www.nuget.org/packages/Azure.Mcp.osx-arm64/2.0.0-beta.32) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.osx-x64/1.0.0)
NuGet [2.0.0-beta.32](https://www.nuget.org/packages/Azure.Mcp.osx-x64/2.0.0-beta.32) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.win-arm64/1.0.0)
NuGet [2.0.0-beta.32](https://www.nuget.org/packages/Azure.Mcp.win-arm64/2.0.0-beta.32) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.win-x64/1.0.0)
NuGet [2.0.0-beta.32](https://www.nuget.org/packages/Azure.Mcp.win-x64/2.0.0-beta.32) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp/1.0.0)
NuGet [2.0.0-beta.33](https://www.nuget.org/packages/Azure.Mcp/2.0.0-beta.33) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/1.0.0)
NuGet [2.0.0-beta.33](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/2.0.0-beta.33) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-x64/1.0.0)
NuGet [2.0.0-beta.33](https://www.nuget.org/packages/Azure.Mcp.linux-x64/2.0.0-beta.33) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.osx-arm64/1.0.0)
NuGet [2.0.0-beta.33](https://www.nuget.org/packages/Azure.Mcp.osx-arm64/2.0.0-beta.33) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.osx-x64/1.0.0)
NuGet [2.0.0-beta.33](https://www.nuget.org/packages/Azure.Mcp.osx-x64/2.0.0-beta.33) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.win-arm64/1.0.0)
NuGet [2.0.0-beta.33](https://www.nuget.org/packages/Azure.Mcp.win-arm64/2.0.0-beta.33) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.win-x64/1.0.0)
NuGet [2.0.0-beta.33](https://www.nuget.org/packages/Azure.Mcp.win-x64/2.0.0-beta.33) | | | | Azure MCP Types Internal | NuGet [0.2.804](https://www.nuget.org/packages/Microsoft.Azure.Mcp.AzTypes.Internal.Compact/0.2.804) | | | | Azure.Communication.Administration | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.Administration/1.0.0-beta.3) | | | | Caching - PostgreSQL | NuGet [1.2.2](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Postgres/1.2.2) | | | @@ -469,7 +469,7 @@ | Speech Extension ONNX Runtime | NuGet [1.48.2](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech.Extension.ONNX.Runtime/1.48.2) | | | | Speech Extension Telemetry | NuGet [1.48.2](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech.Extension.Telemetry/1.48.2) | | | | System Net Client Model | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/System.Net.ClientModel/1.0.0-beta.1) | | | -| WebJobs Extension Cosmos DB Mongo | NuGet [1.2.0-preview](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AzureCosmosDb.Mongo/1.2.0-preview) | | | +| WebJobs Extension Cosmos DB Mongo | NuGet [1.2.1-preview](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AzureCosmosDb.Mongo/1.2.1-preview) | | | | WebJobs Extension MySQL | NuGet [1.0.129](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.MySql/1.0.129) | | | | Anomaly Detector | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.AnomalyDetector/1.0.0) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.AnomalyDetector_1.0.0-preview.1/sdk/cognitiveservices/AnomalyDetector) | | App Service | NuGet [0.2.2-alpha](https://www.nuget.org/packages/Microsoft.Azure.AppService/0.2.2-alpha) | | | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index 202229b8cbe8c..9cc106da0f287 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -168,7 +168,7 @@ | Provisioning - Cdn | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Cdn/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Cdn-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Cdn_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Cdn/) | | Provisioning - Cognitive Services | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Provisioning.CognitiveServices/1.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.CognitiveServices-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CognitiveServices_1.2.0/sdk/provisioning/Azure.Provisioning.CognitiveServices/) | | Provisioning - Communication | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Provisioning.Communication/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Provisioning.Communication-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Communication_1.0.0-beta.4/sdk/provisioning/Azure.Provisioning.Communication/) | -| Provisioning - Compute | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Compute/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Compute_1.0.0-beta.1/sdk/compute/Azure.Provisioning.Compute/) | +| Provisioning - Compute | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Compute/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Compute-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Compute_1.0.0-beta.1/sdk/compute/Azure.Provisioning.Compute/) | | Provisioning - Container Registry | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.ContainerRegistry/1.1.0) | [docs](/dotnet/api/overview/azure/Provisioning.ContainerRegistry-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ContainerRegistry_1.1.0/sdk/provisioning/Azure.Provisioning.ContainerRegistry/) | | Provisioning - Container Service | NuGet [1.0.0-beta.5](https://www.nuget.org/packages/Azure.Provisioning.ContainerService/1.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Provisioning.ContainerService-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ContainerService_1.0.0-beta.5/sdk/provisioning/Azure.Provisioning.ContainerService/) | | Provisioning - CosmosDB | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Provisioning.CosmosDB/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.CosmosDB/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.CosmosDB-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CosmosDB_1.0.0/sdk/provisioning/Azure.Provisioning.CosmosDB/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CosmosDB_1.1.0-beta.1/sdk/provisioning/Azure.Provisioning.CosmosDB/) | From 073c9b26b279f556a816e97287ca5aee57f13985 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 10:07:41 -0400 Subject: [PATCH 02/11] Fix outdated SIMD platform support documentation (#52694) * Initial plan * Fix outdated SIMD platform support docs: replace 64-bit/RyuJIT claim with IsHardwareAccelerated guidance Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> Agent-Logs-Url: https://github.com/dotnet/docs/sessions/43c922c8-e396-4b06-aca8-6de16c099b10 * Apply suggestion from @BillWagner --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> Co-authored-by: Bill Wagner --- docs/standard/simd.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/standard/simd.md b/docs/standard/simd.md index ce3fcab6ae251..cbe484c6cbd73 100644 --- a/docs/standard/simd.md +++ b/docs/standard/simd.md @@ -3,7 +3,7 @@ title: SIMD-accelerated types in .NET description: This article describes SIMD-enabled types in .NET and demonstrates how to use hardware SIMD operations in C# and .NET. author: FIVIL ms.author: tagoo -ms.date: 03/17/2026 +ms.date: 03/26/2026 ai-usage: ai-assisted --- @@ -28,7 +28,7 @@ The .NET SIMD-accelerated types include the following types: > [!NOTE] > The type is not included in the .NET Framework. You must install the [System.Numerics.Vectors](https://www.nuget.org/packages/System.Numerics.Vectors) NuGet package to get access to this type. -The SIMD-accelerated types are implemented in such a way that they can be used with non-SIMD-accelerated hardware or JIT compilers. To take advantage of SIMD instructions, your 64-bit apps must be run by the runtime that uses the **RyuJIT** compiler. A **RyuJIT** compiler is included in .NET Core and in .NET Framework 4.6 and later. SIMD support is only provided when targeting 64-bit processors. +The SIMD-accelerated types are implemented in such a way that they can be used with non-SIMD-accelerated hardware or JIT compilers. To determine whether SIMD acceleration is available at runtime, use . If that property returns `true`, at least some APIs use hardware-accelerated SIMD operations. If it returns `false`, no APIs are hardware accelerated. ## How to use SIMD? From 56c52f647f1c8f4d2cd50c0f2390217c8f6ab634 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 11:20:44 -0400 Subject: [PATCH 03/11] Add IntPtr and UIntPtr to blittable types list in native interop best practices (#52695) * Initial plan * Add IntPtr and UIntPtr to blittable types list in native interop best practices Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> Agent-Logs-Url: https://github.com/dotnet/docs/sessions/1c687208-58c3-4de4-9014-61ade3b54d29 * Update docs/standard/native-interop/best-practices.md * Update docs/standard/native-interop/best-practices.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/standard/native-interop/best-practices.md Co-authored-by: Aaron R Robinson * Update docs/standard/native-interop/best-practices.md --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> Co-authored-by: Bill Wagner Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Jan Kotas Co-authored-by: Aaron R Robinson --- docs/standard/native-interop/best-practices.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/standard/native-interop/best-practices.md b/docs/standard/native-interop/best-practices.md index 44828e01e708d..325a0b0a3a0ea 100644 --- a/docs/standard/native-interop/best-practices.md +++ b/docs/standard/native-interop/best-practices.md @@ -1,7 +1,8 @@ --- title: Native interoperability best practices - .NET description: Learn the best practices for interfacing with native components in .NET. -ms.date: 07/09/2025 +ms.date: 03/26/2026 +ai-usage: ai-assisted --- # Native interoperability best practices @@ -106,7 +107,8 @@ Blittable types are types that have the same bit-level representation in managed **Blittable types:** -- `byte`, `sbyte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `single`, `double` +- `byte`, `sbyte`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `single`, `double`, `nint`, `nuint` +- unmanaged pointers (for example, `int*`) - structs with fixed layout that only have blittable value types for instance fields - fixed layout requires `[StructLayout(LayoutKind.Sequential)]` or `[StructLayout(LayoutKind.Explicit)]` - structs are `LayoutKind.Sequential` by default From 9608629295626c42d16bc9e6a5aff787d2a6e06b Mon Sep 17 00:00:00 2001 From: Azure SDK Bot <53356347+azure-sdk@users.noreply.github.com> Date: Fri, 27 Mar 2026 12:18:51 -0700 Subject: [PATCH 04/11] Update package index with latest published versions (#52705) --- docs/azure/includes/dotnet-all.md | 7 ++++--- docs/azure/includes/dotnet-new.md | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index d7c15f8dc888e..3e332a9878cb5 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -152,6 +152,7 @@ | Provisioning - App Containers | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Provisioning.AppContainers/1.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.AppContainers-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppContainers_1.2.0/sdk/provisioning/Azure.Provisioning.AppContainers/) | | Provisioning - App Service | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Provisioning.AppService/1.3.1)
NuGet [1.4.0-beta.2](https://www.nuget.org/packages/Azure.Provisioning.AppService/1.4.0-beta.2) | [docs](/dotnet/api/overview/azure/Provisioning.AppService-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppService_1.3.1/sdk/provisioning/Azure.Provisioning.AppService/)
GitHub [1.4.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppService_1.4.0-beta.2/sdk/provisioning/Azure.Provisioning.AppService/) | | Provisioning - Application Insights | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.ApplicationInsights/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.ApplicationInsights/1.2.0-beta.1) | [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/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ApplicationInsights_1.2.0-beta.1/sdk/provisioning/Azure.Provisioning.ApplicationInsights/) | +| Provisioning - Batch | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Batch/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Batch-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Batch_1.0.0-beta.1/sdk/batch/Azure.Provisioning.Batch/) | | Provisioning - Cdn | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Cdn/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Cdn-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Cdn_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Cdn/) | | Provisioning - Cognitive Services | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Provisioning.CognitiveServices/1.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.CognitiveServices-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CognitiveServices_1.2.0/sdk/provisioning/Azure.Provisioning.CognitiveServices/) | | Provisioning - Communication | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Provisioning.Communication/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Provisioning.Communication-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Communication_1.0.0-beta.4/sdk/provisioning/Azure.Provisioning.Communication/) | @@ -168,7 +169,7 @@ | Provisioning - Kubernetes | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Provisioning.Kubernetes/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Provisioning.Kubernetes-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.Kubernetes_1.0.0-beta.3/sdk/provisioning/Azure.Provisioning.Kubernetes/) | | Provisioning - Kubernetes Configuration | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Provisioning.KubernetesConfiguration/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Provisioning.KubernetesConfiguration-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.KubernetesConfiguration_1.0.0-beta.3/sdk/provisioning/Azure.Provisioning.KubernetesConfiguration/) | | Provisioning - Kusto | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Provisioning.Kusto/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Provisioning.Kusto-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Kusto_1.0.0-beta.2/sdk/provisioning/Azure.Provisioning.Kusto/) | -| Provisioning - Network | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Provisioning.Network/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Network/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Network-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Network_1.0.0/sdk/provisioning/Azure.Provisioning.Network/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Network_1.1.0-beta.1/sdk/provisioning/Azure.Provisioning.Network/) | +| Provisioning - Network | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Provisioning.Network/1.0.0)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.Provisioning.Network/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/Provisioning.Network-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Network_1.0.0/sdk/provisioning/Azure.Provisioning.Network/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Network_1.1.0-beta.2/sdk/provisioning/Azure.Provisioning.Network/) | | Provisioning - Operational Insights | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.OperationalInsights/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.OperationalInsights/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.OperationalInsights-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.OperationalInsights_1.1.0/sdk/provisioning/Azure.Provisioning.OperationalInsights/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.OperationalInsights_1.2.0-beta.1/sdk/provisioning/Azure.Provisioning.OperationalInsights/) | | Provisioning - PostgreSQL | NuGet [1.1.1](https://www.nuget.org/packages/Azure.Provisioning.PostgreSql/1.1.1)
NuGet [1.2.0-beta.2](https://www.nuget.org/packages/Azure.Provisioning.PostgreSql/1.2.0-beta.2) | [docs](/dotnet/api/overview/azure/Provisioning.PostgreSql-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.PostgreSql_1.1.1/sdk/provisioning/Azure.Provisioning.PostgreSql/)
GitHub [1.2.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.PostgreSql_1.2.0-beta.2/sdk/provisioning/Azure.Provisioning.PostgreSql/) | | Provisioning - Private DNS | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Provisioning.PrivateDns/1.0.0) | [docs](/dotnet/api/overview/azure/Provisioning.PrivateDns-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.PrivateDns_1.0.0/sdk/provisioning/Azure.Provisioning.PrivateDns/) | @@ -198,7 +199,7 @@ | Resource Management - Authorization | NuGet [1.1.6](https://www.nuget.org/packages/Azure.ResourceManager.Authorization/1.1.6) | [docs](/dotnet/api/overview/azure/ResourceManager.Authorization-readme) | GitHub [1.1.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Authorization_1.1.6/sdk/authorization/Azure.ResourceManager.Authorization/) | | Resource Management - Automanage | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.Automanage/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Automanage-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Automanage_1.1.1/sdk/automanage/Azure.ResourceManager.Automanage/) | | Resource Management - Automation | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.Automation/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Automation-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Automation_1.1.1/sdk/automation/Azure.ResourceManager.Automation/) | -| Resource Management - Azure AI Search | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.3.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Search-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.3.0/sdk/search/Azure.ResourceManager.Search/) | +| Resource Management - Azure AI Search | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.3.0)
NuGet [1.4.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.4.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Search-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.3.0/sdk/search/Azure.ResourceManager.Search/)
GitHub [1.4.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.4.0-beta.1/sdk/search/Azure.ResourceManager.Search/) | | Resource Management - Azure Stack HCI | NuGet [1.2.1](https://www.nuget.org/packages/Azure.ResourceManager.Hci/1.2.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Hci-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Hci_1.2.1/sdk/azurestackhci/Azure.ResourceManager.Hci/) | | Resource Management - Azure VMware Solution | NuGet [1.6.0](https://www.nuget.org/packages/Azure.ResourceManager.Avs/1.6.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Avs-readme) | GitHub [1.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Avs_1.6.0/sdk/avs/Azure.ResourceManager.Avs/) | | Resource Management - Batch | NuGet [1.6.0](https://www.nuget.org/packages/Azure.ResourceManager.Batch/1.6.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Batch-readme) | GitHub [1.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Batch_1.6.0/sdk/batch/Azure.ResourceManager.Batch/) | @@ -227,7 +228,7 @@ | 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.4.0](https://www.nuget.org/packages/Azure.ResourceManager.ContainerRegistry/1.4.0)
NuGet [1.5.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ContainerRegistry/1.5.0-beta.2) | [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/)
GitHub [1.5.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerRegistry_1.5.0-beta.2/sdk/containerregistry/Azure.ResourceManager.ContainerRegistry/) | -| Resource Management - Container Service | NuGet [1.3.1](https://www.nuget.org/packages/Azure.ResourceManager.ContainerService/1.3.1)
NuGet [1.4.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ContainerService/1.4.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerService-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerService_1.3.1/sdk/containerservice/Azure.ResourceManager.ContainerService/)
GitHub [1.4.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerService_1.4.0-beta.1/sdk/containerservice/Azure.ResourceManager.ContainerService/) | +| Resource Management - Container Service | NuGet [1.4.0](https://www.nuget.org/packages/Azure.ResourceManager.ContainerService/1.4.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerService-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerService_1.4.0/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 - Containerregistry.Tasks | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ContainerRegistry.Tasks/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerRegistry.Tasks-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.ContainerRegistry.Tasks_1.0.0-beta.1/sdk/containerregistry/Azure.ResourceManager.ContainerRegistry.Tasks/) | | Resource Management - Content Delivery Network | NuGet [1.5.1](https://www.nuget.org/packages/Azure.ResourceManager.Cdn/1.5.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Cdn-readme) | GitHub [1.5.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Cdn_1.5.1/sdk/cdn/Azure.ResourceManager.Cdn/) | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index 9cc106da0f287..f9e07bcbc1e24 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -165,6 +165,7 @@ | Provisioning - App Containers | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Provisioning.AppContainers/1.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.AppContainers-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppContainers_1.2.0/sdk/provisioning/Azure.Provisioning.AppContainers/) | | Provisioning - App Service | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Provisioning.AppService/1.3.1)
NuGet [1.4.0-beta.2](https://www.nuget.org/packages/Azure.Provisioning.AppService/1.4.0-beta.2) | [docs](/dotnet/api/overview/azure/Provisioning.AppService-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppService_1.3.1/sdk/provisioning/Azure.Provisioning.AppService/)
GitHub [1.4.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppService_1.4.0-beta.2/sdk/provisioning/Azure.Provisioning.AppService/) | | Provisioning - Application Insights | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.ApplicationInsights/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.ApplicationInsights/1.2.0-beta.1) | [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/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ApplicationInsights_1.2.0-beta.1/sdk/provisioning/Azure.Provisioning.ApplicationInsights/) | +| Provisioning - Batch | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Batch/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Batch-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Batch_1.0.0-beta.1/sdk/batch/Azure.Provisioning.Batch/) | | Provisioning - Cdn | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Cdn/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Cdn-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Cdn_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Cdn/) | | Provisioning - Cognitive Services | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Provisioning.CognitiveServices/1.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.CognitiveServices-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CognitiveServices_1.2.0/sdk/provisioning/Azure.Provisioning.CognitiveServices/) | | Provisioning - Communication | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Provisioning.Communication/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Provisioning.Communication-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Communication_1.0.0-beta.4/sdk/provisioning/Azure.Provisioning.Communication/) | @@ -181,7 +182,7 @@ | Provisioning - Kubernetes | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Provisioning.Kubernetes/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Provisioning.Kubernetes-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.Kubernetes_1.0.0-beta.3/sdk/provisioning/Azure.Provisioning.Kubernetes/) | | Provisioning - Kubernetes Configuration | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Provisioning.KubernetesConfiguration/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Provisioning.KubernetesConfiguration-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.KubernetesConfiguration_1.0.0-beta.3/sdk/provisioning/Azure.Provisioning.KubernetesConfiguration/) | | Provisioning - Kusto | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Provisioning.Kusto/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Provisioning.Kusto-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Kusto_1.0.0-beta.2/sdk/provisioning/Azure.Provisioning.Kusto/) | -| Provisioning - Network | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Provisioning.Network/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Network/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Network-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Network_1.0.0/sdk/provisioning/Azure.Provisioning.Network/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Network_1.1.0-beta.1/sdk/provisioning/Azure.Provisioning.Network/) | +| Provisioning - Network | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Provisioning.Network/1.0.0)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.Provisioning.Network/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/Provisioning.Network-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Network_1.0.0/sdk/provisioning/Azure.Provisioning.Network/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Network_1.1.0-beta.2/sdk/provisioning/Azure.Provisioning.Network/) | | Provisioning - Operational Insights | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.OperationalInsights/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.OperationalInsights/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.OperationalInsights-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.OperationalInsights_1.1.0/sdk/provisioning/Azure.Provisioning.OperationalInsights/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.OperationalInsights_1.2.0-beta.1/sdk/provisioning/Azure.Provisioning.OperationalInsights/) | | Provisioning - PostgreSQL | NuGet [1.1.1](https://www.nuget.org/packages/Azure.Provisioning.PostgreSql/1.1.1)
NuGet [1.2.0-beta.2](https://www.nuget.org/packages/Azure.Provisioning.PostgreSql/1.2.0-beta.2) | [docs](/dotnet/api/overview/azure/Provisioning.PostgreSql-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.PostgreSql_1.1.1/sdk/provisioning/Azure.Provisioning.PostgreSql/)
GitHub [1.2.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.PostgreSql_1.2.0-beta.2/sdk/provisioning/Azure.Provisioning.PostgreSql/) | | Provisioning - Private DNS | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Provisioning.PrivateDns/1.0.0) | [docs](/dotnet/api/overview/azure/Provisioning.PrivateDns-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.PrivateDns_1.0.0/sdk/provisioning/Azure.Provisioning.PrivateDns/) | @@ -213,7 +214,7 @@ | Resource Management - Authorization | NuGet [1.1.6](https://www.nuget.org/packages/Azure.ResourceManager.Authorization/1.1.6) | [docs](/dotnet/api/overview/azure/ResourceManager.Authorization-readme) | GitHub [1.1.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Authorization_1.1.6/sdk/authorization/Azure.ResourceManager.Authorization/) | | Resource Management - Automanage | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.Automanage/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Automanage-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Automanage_1.1.1/sdk/automanage/Azure.ResourceManager.Automanage/) | | Resource Management - Automation | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.Automation/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Automation-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Automation_1.1.1/sdk/automation/Azure.ResourceManager.Automation/) | -| Resource Management - Azure AI Search | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.3.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Search-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.3.0/sdk/search/Azure.ResourceManager.Search/) | +| Resource Management - Azure AI Search | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.3.0)
NuGet [1.4.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.4.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Search-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.3.0/sdk/search/Azure.ResourceManager.Search/)
GitHub [1.4.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.4.0-beta.1/sdk/search/Azure.ResourceManager.Search/) | | Resource Management - Azure Stack HCI | NuGet [1.2.1](https://www.nuget.org/packages/Azure.ResourceManager.Hci/1.2.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Hci-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Hci_1.2.1/sdk/azurestackhci/Azure.ResourceManager.Hci/) | | Resource Management - Azure VMware Solution | NuGet [1.6.0](https://www.nuget.org/packages/Azure.ResourceManager.Avs/1.6.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Avs-readme) | GitHub [1.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Avs_1.6.0/sdk/avs/Azure.ResourceManager.Avs/) | | Resource Management - Batch | NuGet [1.6.0](https://www.nuget.org/packages/Azure.ResourceManager.Batch/1.6.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Batch-readme) | GitHub [1.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Batch_1.6.0/sdk/batch/Azure.ResourceManager.Batch/) | @@ -242,7 +243,7 @@ | 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.4.0](https://www.nuget.org/packages/Azure.ResourceManager.ContainerRegistry/1.4.0)
NuGet [1.5.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ContainerRegistry/1.5.0-beta.2) | [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/)
GitHub [1.5.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerRegistry_1.5.0-beta.2/sdk/containerregistry/Azure.ResourceManager.ContainerRegistry/) | -| Resource Management - Container Service | NuGet [1.3.1](https://www.nuget.org/packages/Azure.ResourceManager.ContainerService/1.3.1)
NuGet [1.4.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ContainerService/1.4.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerService-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerService_1.3.1/sdk/containerservice/Azure.ResourceManager.ContainerService/)
GitHub [1.4.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerService_1.4.0-beta.1/sdk/containerservice/Azure.ResourceManager.ContainerService/) | +| Resource Management - Container Service | NuGet [1.4.0](https://www.nuget.org/packages/Azure.ResourceManager.ContainerService/1.4.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerService-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerService_1.4.0/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 - Containerregistry.Tasks | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ContainerRegistry.Tasks/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerRegistry.Tasks-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.ContainerRegistry.Tasks_1.0.0-beta.1/sdk/containerregistry/Azure.ResourceManager.ContainerRegistry.Tasks/) | | Resource Management - Content Delivery Network | NuGet [1.5.1](https://www.nuget.org/packages/Azure.ResourceManager.Cdn/1.5.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Cdn-readme) | GitHub [1.5.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Cdn_1.5.1/sdk/cdn/Azure.ResourceManager.Cdn/) | From b1bb31c3de0fc8bfce6316c2d45c38b341d8ce0f Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Fri, 27 Mar 2026 16:04:55 -0700 Subject: [PATCH 05/11] [adegeo] Freshness updates March (#52303) * Migrate snippets 1 * Remove old code * Refresh uninstall tool * Add result comments in snippets * Fix the empty lines and correct the comments * Remove the the --- .../uninstall-tool-overview.md | 12 +-- ...ation-constructs-in-regular-expressions.md | 20 ++--- .../csharp/Program.cs | 79 ++++++++++++++++ .../csharp/csharp.csproj | 10 +++ .../vb/Program.vb | 90 +++++++++++++++++++ .../vb/vb.vbproj | 9 ++ .../cs/alternation1.cs | 28 ------ .../cs/alternation2.cs | 20 ----- .../cs/alternation3.cs | 20 ----- .../cs/alternation4.cs | 20 ----- .../cs/alternation5.cs | 20 ----- .../vb/alternation1.vb | 33 ------- .../vb/alternation2.vb | 21 ----- .../vb/alternation3.vb | 21 ----- .../vb/alternation4.vb | 17 ---- .../vb/alternation5.vb | 21 ----- 16 files changed, 204 insertions(+), 237 deletions(-) create mode 100644 docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/csharp/Program.cs create mode 100644 docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/csharp/csharp.csproj create mode 100644 docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/vb/Program.vb create mode 100644 docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/vb/vb.vbproj delete mode 100644 samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation1.cs delete mode 100644 samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation2.cs delete mode 100644 samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation3.cs delete mode 100644 samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation4.cs delete mode 100644 samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation5.cs delete mode 100644 samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation1.vb delete mode 100644 samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation2.vb delete mode 100644 samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation3.vb delete mode 100644 samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation4.vb delete mode 100644 samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation5.vb diff --git a/docs/core/additional-tools/uninstall-tool-overview.md b/docs/core/additional-tools/uninstall-tool-overview.md index 95a61a804b481..27f28fd8c9533 100644 --- a/docs/core/additional-tools/uninstall-tool-overview.md +++ b/docs/core/additional-tools/uninstall-tool-overview.md @@ -3,7 +3,7 @@ title: .NET Uninstall Tool overview description: An overview of .NET Uninstall Tool. This tool is a guided command-line tool that removes .NET SDKs and runtimes. author: adegeo ms.custom: devdivchpfy22 -ms.date: 08/04/2024 +ms.date: 03/20/2026 zone_pivot_groups: operating-systems-set-three --- @@ -51,19 +51,19 @@ winget install --id Microsoft.DotNet.UninstallTool --source winget ### Install with the MSI installer -1. Download the _dotnet-core-uninstall-\*.msi_ installer from the [the GitHub releases page](https://aka.ms/dotnet-core-uninstall-tool). +1. Download the _dotnet-core-uninstall-\*.msi_ installer from the [GitHub releases page](https://aka.ms/dotnet-core-uninstall-tool). 1. Run the installer. ::: zone-end ::: zone pivot="os-macos" -01. Download the _dotnet-core-uninstall.tar.gz_ tarball from the [the GitHub releases page](https://aka.ms/dotnet-core-uninstall-tool). -01. Run the following shell script to extract the tarball to a directory named _dotnet-core-uninstall_ in your home directory: +01. Download the _dotnet-core-uninstall-\*.tar.gz_ tarball from the [GitHub releases page](https://aka.ms/dotnet-core-uninstall-tool). +01. Run the following shell script to extract the tarball to a directory named _dotnet-core-uninstall_ in your home directory. The following example extracts the Arm64 version of the tool: ```bash mkdir -p ~/dotnet-core-uninstall - tar -zxf dotnet-core-uninstall.tar.gz -C ~/dotnet-core-uninstall + tar -zxf dotnet-core-uninstall-osx-arm64.tar.gz -C ~/dotnet-core-uninstall ``` ::: zone-end @@ -96,7 +96,7 @@ To manually uninstall the tool, perform the following steps: ::: zone pivot="os-macos" -If you extracted the _dotnet-core-uninstall.tar.gz_ tarball, delete the extracted files. +If you extracted the _dotnet-core-uninstall-\*.tar.gz_ tarball, delete the extracted files. ::: zone-end diff --git a/docs/standard/base-types/alternation-constructs-in-regular-expressions.md b/docs/standard/base-types/alternation-constructs-in-regular-expressions.md index 3169c628713a1..84ef6a8419819 100644 --- a/docs/standard/base-types/alternation-constructs-in-regular-expressions.md +++ b/docs/standard/base-types/alternation-constructs-in-regular-expressions.md @@ -31,8 +31,8 @@ You can use the vertical bar (`|`) character to match any one of a series of pat Like the positive character class, the `|` character can be used to match any one of a number of single characters. The following example uses both a positive character class and either/or pattern matching with the `|` character to locate occurrences of the words "gray" or "grey" in a string. In this case, the `|` character produces a regular expression that is more verbose. -[!code-csharp[RegularExpressions.Language.Alternation#1](~/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation1.cs#1)] -[!code-vb[RegularExpressions.Language.Alternation#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation1.vb#1)] +:::code language="csharp" source="./snippets/alternation-constructs-in-regular-expressions/csharp/Program.cs" id="EitherOrCharacterClass"::: +:::code language="vb" source="./snippets/alternation-constructs-in-regular-expressions/vb/Program.vb" id="EitherOrCharacterClass"::: The regular expression that uses the `|` character, `\bgr(a|e)y\b`, is interpreted as shown in the following table: @@ -45,8 +45,8 @@ The regular expression that uses the `|` character, `\bgr(a|e)y\b`, is interpret The `|` character can also be used to perform an either/or match with multiple characters or subexpressions, which can include any combination of character literals and regular expression language elements. (The character class does not provide this functionality.) The following example uses the `|` character to extract either a U.S. Social Security Number (SSN), which is a 9-digit number with the format *ddd*-*dd*-*dddd*, or a U.S. Employer Identification Number (EIN), which is a 9-digit number with the format *dd*-*ddddddd*. -[!code-csharp[RegularExpressions.Language.Alternation#2](~/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation2.cs#2)] -[!code-vb[RegularExpressions.Language.Alternation#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation2.vb#2)] +:::code language="csharp" source="./snippets/alternation-constructs-in-regular-expressions/csharp/Program.cs" id="EitherOrPatterns"::: +:::code language="vb" source="./snippets/alternation-constructs-in-regular-expressions/vb/Program.vb" id="EitherOrPatterns"::: The regular expression `\b(\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b` is interpreted as shown in the following table: @@ -79,8 +79,8 @@ where `(?=`*expression*`)` is a zero-width assertion construct. (For more inform The following example is a variation of the example that appears in the [Either/Or Pattern Matching with |](#Either_Or) section. It uses conditional matching to determine whether the first three characters after a word boundary are two digits followed by a hyphen. If they are, it attempts to match a U.S. Employer Identification Number (EIN). If not, it attempts to match a U.S. Social Security Number (SSN). -[!code-csharp[RegularExpressions.Language.Alternation#3](~/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation3.cs#3)] -[!code-vb[RegularExpressions.Language.Alternation#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation3.vb#3)] +:::code language="csharp" source="./snippets/alternation-constructs-in-regular-expressions/csharp/Program.cs" id="ConditionalExpression"::: +:::code language="vb" source="./snippets/alternation-constructs-in-regular-expressions/vb/Program.vb" id="ConditionalExpression"::: The regular expression pattern `\b(?(\d{2}-)\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b` is interpreted as shown in the following table: @@ -118,8 +118,8 @@ If *name* does not correspond to the name of a capturing group that is used in t The following example is a variation of the example that appears in the [Either/Or Pattern Matching with |](#Either_Or) section. It uses a capturing group named `n2` that consists of two digits followed by a hyphen. The alternation construct tests whether this capturing group has been matched in the input string. If it has, the alternation construct attempts to match the last seven digits of a nine-digit U.S. Employer Identification Number (EIN). If it has not, it attempts to match a nine-digit U.S. Social Security Number (SSN). -[!code-csharp[RegularExpressions.Language.Alternation#4](~/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation4.cs#4)] -[!code-vb[RegularExpressions.Language.Alternation#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation4.vb#4)] +:::code language="csharp" source="./snippets/alternation-constructs-in-regular-expressions/csharp/Program.cs" id="ConditionalNamedGroup"::: +:::code language="vb" source="./snippets/alternation-constructs-in-regular-expressions/vb/Program.vb" id="ConditionalNamedGroup"::: The regular expression pattern `\b(?\d{2}-)?(?(n2)\d{7}|\d{3}-\d{2}-\d{4})\b` is interpreted as shown in the following table: @@ -134,8 +134,8 @@ The regular expression pattern `\b(?\d{2}-)?(?(n2)\d{7}|\d{3}-\d{2}-\d{4})\b A variation of this example that uses a numbered group instead of a named group is shown in the following example. Its regular expression pattern is `\b(\d{2}-)?(?(1)\d{7}|\d{3}-\d{2}-\d{4})\b`. -[!code-csharp[RegularExpressions.Language.Alternation#5](~/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation5.cs#5)] -[!code-vb[RegularExpressions.Language.Alternation#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation5.vb#5)] +:::code language="csharp" source="./snippets/alternation-constructs-in-regular-expressions/csharp/Program.cs" id="ConditionalNumberedGroup"::: +:::code language="vb" source="./snippets/alternation-constructs-in-regular-expressions/vb/Program.vb" id="ConditionalNumberedGroup"::: ## See also diff --git a/docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/csharp/Program.cs b/docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/csharp/Program.cs new file mode 100644 index 0000000000000..81f305f573501 --- /dev/null +++ b/docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/csharp/Program.cs @@ -0,0 +1,79 @@ +using System.Text.RegularExpressions; + +// +string pattern1 = @"\bgr[ae]y\b"; +string pattern2 = @"\bgr(a|e)y\b"; + +string input = "The gray wolf blended in among the grey rocks."; +foreach (Match match in Regex.Matches(input, pattern1)) + Console.WriteLine($"'{match.Value}' found at position {match.Index}"); +Console.WriteLine(); +foreach (Match match in Regex.Matches(input, pattern2)) + Console.WriteLine($"'{match.Value}' found at position {match.Index}"); + +// The example displays the following output: +// 'gray' found at position 4 +// 'grey' found at position 35 +// +// 'gray' found at position 4 +// 'grey' found at position 35 +// + +Console.WriteLine(); + +// +string eitherOrPattern = @"\b(\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b"; +string eitherOrInput = "01-9999999 020-333333 777-88-9999"; +Console.WriteLine($"Matches for {eitherOrPattern}:"); +foreach (Match match in Regex.Matches(eitherOrInput, eitherOrPattern)) + Console.WriteLine($" {match.Value} at position {match.Index}"); + +// The example displays the following output: +// Matches for \b(\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b: +// 01-9999999 at position 0 +// 777-88-9999 at position 22 +// + +Console.WriteLine(); + +// +string condExprPattern = @"\b(?(\d{2}-)\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b"; +string condExprInput = "01-9999999 020-333333 777-88-9999"; +Console.WriteLine($"Matches for {condExprPattern}:"); +foreach (Match match in Regex.Matches(condExprInput, condExprPattern)) + Console.WriteLine($" {match.Value} at position {match.Index}"); + +// The example displays the following output: +// Matches for \b(?(\d{2}-)\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b: +// 01-9999999 at position 0 +// 777-88-9999 at position 22 +// + +Console.WriteLine(); + +// +string namedGroupPattern = @"\b(?\d{2}-)?(?(n2)\d{7}|\d{3}-\d{2}-\d{4})\b"; +string namedGroupInput = "01-9999999 020-333333 777-88-9999"; +Console.WriteLine($"Matches for {namedGroupPattern}:"); +foreach (Match match in Regex.Matches(namedGroupInput, namedGroupPattern)) + Console.WriteLine($" {match.Value} at position {match.Index}"); + +// The example displays the following output: +// Matches for \b(?\d{2}-)?(?(n2)\d{7}|\d{3}-\d{2}-\d{4})\b: +// 01-9999999 at position 0 +// 777-88-9999 at position 22 +// + +Console.WriteLine(); + +// +string numberedGroupPattern = @"\b(\d{2}-)?(?(1)\d{7}|\d{3}-\d{2}-\d{4})\b"; +string numberedGroupInput = "01-9999999 020-333333 777-88-9999"; +Console.WriteLine($"Matches for {numberedGroupPattern}:"); +foreach (Match match in Regex.Matches(numberedGroupInput, numberedGroupPattern)) + Console.WriteLine($" {match.Value} at position {match.Index}"); +// The example displays the following output: +// Matches for \b(\d{2}-)?(?(1)\d{7}|\d{3}-\d{2}-\d{4})\b: +// 01-9999999 at position 0 +// 777-88-9999 at position 22 +// diff --git a/docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/csharp/csharp.csproj b/docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/csharp/csharp.csproj new file mode 100644 index 0000000000000..ed9781c223ab9 --- /dev/null +++ b/docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/csharp/csharp.csproj @@ -0,0 +1,10 @@ + + + + Exe + net10.0 + enable + enable + + + diff --git a/docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/vb/Program.vb b/docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/vb/Program.vb new file mode 100644 index 0000000000000..71245f0c22924 --- /dev/null +++ b/docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/vb/Program.vb @@ -0,0 +1,90 @@ +Imports System.Text.RegularExpressions + +Module Program + Sub Main(args As String()) + ' + Dim pattern1 As String = "\bgr[ae]y\b" + Dim pattern2 As String = "\bgr(a|e)y\b" + + Dim input As String = "The gray wolf blended in among the grey rocks." + For Each match As Match In Regex.Matches(input, pattern1) + Console.WriteLine($"'{match.Value}' found at position {match.Index}") + Next + Console.WriteLine() + For Each match As Match In Regex.Matches(input, pattern2) + Console.WriteLine($"'{match.Value}' found at position {match.Index}") + Next + + ' The example displays the following output: + ' 'gray' found at position 4 + ' 'grey' found at position 35 + ' + ' 'gray' found at position 4 + ' 'grey' found at position 35 + ' + + Console.WriteLine() + + ' + Dim eitherOrPattern As String = "\b(\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b" + Dim eitherOrInput As String = "01-9999999 020-333333 777-88-9999" + Console.WriteLine($"Matches for {eitherOrPattern}:") + For Each match As Match In Regex.Matches(eitherOrInput, eitherOrPattern) + Console.WriteLine($" {match.Value} at position {match.Index}") + Next + + ' The example displays the following output: + ' Matches for \b(\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b: + ' 01-9999999 at position 0 + ' 777-88-9999 at position 22 + ' + + Console.WriteLine() + + ' + Dim condExprPattern As String = "\b(?(\d{2}-)\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b" + Dim condExprInput As String = "01-9999999 020-333333 777-88-9999" + Console.WriteLine($"Matches for {condExprPattern}:") + For Each match As Match In Regex.Matches(condExprInput, condExprPattern) + Console.WriteLine($" {match.Value} at position {match.Index}") + Next + + ' The example displays the following output: + ' Matches for \b(?(\d{2}-)\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b: + ' 01-9999999 at position 0 + ' 777-88-9999 at position 22 + ' + + Console.WriteLine() + + ' + Dim namedGroupPattern As String = "\b(?\d{2}-)?(?(n2)\d{7}|\d{3}-\d{2}-\d{4})\b" + Dim namedGroupInput As String = "01-9999999 020-333333 777-88-9999" + Console.WriteLine($"Matches for {namedGroupPattern}:") + For Each match As Match In Regex.Matches(namedGroupInput, namedGroupPattern) + Console.WriteLine($" {match.Value} at position {match.Index}") + Next + + ' The example displays the following output: + ' Matches for \b(?\d{2}-)?(?(n2)\d{7}|\d{3}-\d{2}-\d{4})\b: + ' 01-9999999 at position 0 + ' 777-88-9999 at position 22 + ' + + Console.WriteLine() + + ' + Dim numberedGroupPattern As String = "\b(\d{2}-)?(?(1)\d{7}|\d{3}-\d{2}-\d{4})\b" + Dim numberedGroupInput As String = "01-9999999 020-333333 777-88-9999" + Console.WriteLine($"Matches for {numberedGroupPattern}:") + For Each match As Match In Regex.Matches(numberedGroupInput, numberedGroupPattern) + Console.WriteLine($" {match.Value} at position {match.Index}") + Next + + ' The example displays the following output: + ' Matches for \b(\d{2}-)?(?(1)\d{7}|\d{3}-\d{2}-\d{4})\b: + ' 01-9999999 at position 0 + ' 777-88-9999 at position 22 + ' + End Sub +End Module diff --git a/docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/vb/vb.vbproj b/docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/vb/vb.vbproj new file mode 100644 index 0000000000000..c54e4d3031486 --- /dev/null +++ b/docs/standard/base-types/snippets/alternation-constructs-in-regular-expressions/vb/vb.vbproj @@ -0,0 +1,9 @@ + + + + Exe + vb + net10.0 + + + diff --git a/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation1.cs b/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation1.cs deleted file mode 100644 index 235d5bddf91b1..0000000000000 --- a/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation1.cs +++ /dev/null @@ -1,28 +0,0 @@ -// -using System; -using System.Text.RegularExpressions; - -public class Example -{ - public static void Main() - { - // Regular expression using character class. - string pattern1 = @"\bgr[ae]y\b"; - // Regular expression using either/or. - string pattern2 = @"\bgr(a|e)y\b"; - - string input = "The gray wolf blended in among the grey rocks."; - foreach (Match match in Regex.Matches(input, pattern1)) - Console.WriteLine($"'{match.Value}' found at position {match.Index}"); - Console.WriteLine(); - foreach (Match match in Regex.Matches(input, pattern2)) - Console.WriteLine($"'{match.Value}' found at position {match.Index}"); - } -} -// The example displays the following output: -// 'gray' found at position 4 -// 'grey' found at position 35 -// -// 'gray' found at position 4 -// 'grey' found at position 35 -// diff --git a/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation2.cs b/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation2.cs deleted file mode 100644 index ac43a7d3ef10b..0000000000000 --- a/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation2.cs +++ /dev/null @@ -1,20 +0,0 @@ -// -using System; -using System.Text.RegularExpressions; - -public class Example -{ - public static void Main() - { - string pattern = @"\b(\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b"; - string input = "01-9999999 020-333333 777-88-9999"; - Console.WriteLine($"Matches for {pattern}:"); - foreach (Match match in Regex.Matches(input, pattern)) - Console.WriteLine($" {match.Value} at position {match.Index}"); - } -} -// The example displays the following output: -// Matches for \b(\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b: -// 01-9999999 at position 0 -// 777-88-9999 at position 22 -// diff --git a/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation3.cs b/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation3.cs deleted file mode 100644 index 42b2d1fbf5fbc..0000000000000 --- a/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation3.cs +++ /dev/null @@ -1,20 +0,0 @@ -// -using System; -using System.Text.RegularExpressions; - -public class Example -{ - public static void Main() - { - string pattern = @"\b(?(\d{2}-)\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b"; - string input = "01-9999999 020-333333 777-88-9999"; - Console.WriteLine($"Matches for {pattern}:"); - foreach (Match match in Regex.Matches(input, pattern)) - Console.WriteLine($" {match.Value} at position {match.Index}"); - } -} -// The example displays the following output: -// Matches for \b(\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b: -// 01-9999999 at position 0 -// 777-88-9999 at position 22 -// diff --git a/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation4.cs b/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation4.cs deleted file mode 100644 index 21d94a242146c..0000000000000 --- a/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation4.cs +++ /dev/null @@ -1,20 +0,0 @@ -// -using System; -using System.Text.RegularExpressions; - -public class Example -{ - public static void Main() - { - string pattern = @"\b(?\d{2}-)?(?(n2)\d{7}|\d{3}-\d{2}-\d{4})\b"; - string input = "01-9999999 020-333333 777-88-9999"; - Console.WriteLine($"Matches for {pattern}:"); - foreach (Match match in Regex.Matches(input, pattern)) - Console.WriteLine($" {match.Value} at position {match.Index}"); - } -} -// The example displays the following output: -// Matches for \b(?\d{2}-)?(?(n2)\d{7}|\d{3}-\d{2}-\d{4})\b: -// 01-9999999 at position 0 -// 777-88-9999 at position 22 -// diff --git a/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation5.cs b/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation5.cs deleted file mode 100644 index 95aa224b776d0..0000000000000 --- a/samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.alternation/cs/alternation5.cs +++ /dev/null @@ -1,20 +0,0 @@ -// -using System; -using System.Text.RegularExpressions; - -public class Example -{ - public static void Main() - { - string pattern = @"\b(\d{2}-)?(?(1)\d{7}|\d{3}-\d{2}-\d{4})\b"; - string input = "01-9999999 020-333333 777-88-9999"; - Console.WriteLine($"Matches for {pattern}:"); - foreach (Match match in Regex.Matches(input, pattern)) - Console.WriteLine($" {match.Value} at position {match.Index}"); - } -} -// The example display the following output: -// Matches for \b(\d{2}-)?(?(1)\d{7}|\d{3}-\d{2}-\d{4})\b: -// 01-9999999 at position 0 -// 777-88-9999 at position 22 -// diff --git a/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation1.vb b/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation1.vb deleted file mode 100644 index ef4e6fbe5a1cf..0000000000000 --- a/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation1.vb +++ /dev/null @@ -1,33 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Text.RegularExpressions - -Module Example - Public Sub Main() - ' Regular expression using character class. - Dim pattern1 As String = "\bgr[ae]y\b" - ' Regular expression using either/or. - Dim pattern2 As String = "\bgr(a|e)y\b" - - Dim input As String = "The gray wolf blended in among the grey rocks." - For Each match As Match In Regex.Matches(input, pattern1) - Console.WriteLine("'{0}' found at position {1}", _ - match.Value, match.Index) - Next - Console.WriteLine() - For Each match As Match In Regex.Matches(input, pattern2) - Console.WriteLine("'{0}' found at position {1}", _ - match.Value, match.Index) - Next - End Sub -End Module -' The example displays the following output: -' 'gray' found at position 4 -' 'grey' found at position 35 -' -' 'gray' found at position 4 -' 'grey' found at position 35 -' - diff --git a/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation2.vb b/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation2.vb deleted file mode 100644 index 43ae84a4b5bd3..0000000000000 --- a/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation2.vb +++ /dev/null @@ -1,21 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Text.RegularExpressions - -Module Example - Public Sub Main() - Dim pattern As String = "\b(\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b" - Dim input As String = "01-9999999 020-333333 777-88-9999" - Console.WriteLine("Matches for {0}:", pattern) - For Each match As Match In Regex.Matches(input, pattern) - Console.WriteLine(" {0} at position {1}", match.Value, match.Index) - Next - End Sub -End Module -' The example displays the following output: -' Matches for \b(\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b: -' 01-9999999 at position 0 -' 777-88-9999 at position 22 -' diff --git a/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation3.vb b/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation3.vb deleted file mode 100644 index b9f8c8b47cab9..0000000000000 --- a/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation3.vb +++ /dev/null @@ -1,21 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Text.RegularExpressions - -Module Example - Public Sub Main() - Dim pattern As String = "\b(?(\d{2}-)\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b" - Dim input As String = "01-9999999 020-333333 777-88-9999" - Console.WriteLine("Matches for {0}:", pattern) - For Each match As Match In Regex.Matches(input, pattern) - Console.WriteLine(" {0} at position {1}", match.Value, match.Index) - Next - End Sub -End Module -' The example displays the following output: -' Matches for \b(?(\d{2}-)\d{2}-\d{7}|\d{3}-\d{2}-\d{4})\b: -' 01-9999999 at position 0 -' 777-88-9999 at position 22 -' diff --git a/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation4.vb b/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation4.vb deleted file mode 100644 index 8ffb7c5722e58..0000000000000 --- a/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation4.vb +++ /dev/null @@ -1,17 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Text.RegularExpressions - -Module Example - Public Sub Main() - Dim pattern As String = "\b(?\d{2}-)?(?(n2)\d{7}|\d{3}-\d{2}-\d{4})\b" - Dim input As String = "01-9999999 020-333333 777-88-9999" - Console.WriteLine("Matches for {0}:", pattern) - For Each match As Match In Regex.Matches(input, pattern) - Console.WriteLine(" {0} at position {1}", match.Value, match.Index) - Next - End Sub -End Module -' diff --git a/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation5.vb b/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation5.vb deleted file mode 100644 index bd3ad609b7199..0000000000000 --- a/samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.alternation/vb/alternation5.vb +++ /dev/null @@ -1,21 +0,0 @@ -' Visual Basic .NET Document -Option Strict On - -' -Imports System.Text.RegularExpressions - -Module Example - Public Sub Main() - Dim pattern As String = "\b(\d{2}-)?(?(1)\d{7}|\d{3}-\d{2}-\d{4})\b" - Dim input As String = "01-9999999 020-333333 777-88-9999" - Console.WriteLine("Matches for {0}:", pattern) - For Each match As Match In Regex.Matches(input, pattern) - Console.WriteLine(" {0} at position {1}", match.Value, match.Index) - Next - End Sub -End Module -' The example displays the following output: -' Matches for \b(\d{2}-)?(?(1)\d{7}|\d{3}-\d{2}-\d{4})\b: -' 01-9999999 at position 0 -' 777-88-9999 at position 22 -' From 938ac84162f0985489248d4b18e90a4d56135b07 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Fri, 27 Mar 2026 16:08:35 -0700 Subject: [PATCH 06/11] GHCP Update with latest design (#52595) * Update with latest design * remove four stage wording * Minor edits * feedback * Update docs/core/porting/github-copilot-app-modernization/how-to-upgrade-with-github-copilot.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --------- Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .../how-to-upgrade-with-github-copilot.md | 32 +++++++++---------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/core/porting/github-copilot-app-modernization/how-to-upgrade-with-github-copilot.md b/docs/core/porting/github-copilot-app-modernization/how-to-upgrade-with-github-copilot.md index 14c99ba079a22..db0bbcc03f2f8 100644 --- a/docs/core/porting/github-copilot-app-modernization/how-to-upgrade-with-github-copilot.md +++ b/docs/core/porting/github-copilot-app-modernization/how-to-upgrade-with-github-copilot.md @@ -2,7 +2,7 @@ title: How to upgrade a .NET app with GitHub Copilot modernization description: "Learn how to upgrade your .NET applications to newer versions using GitHub Copilot modernization. This step-by-step guide covers the three-stage workflow: assessment, planning, and execution." ms.topic: how-to -ms.date: 03/04/2026 +ms.date: 03/23/2026 ai-usage: ai-assisted #customer intent: As a developer, I want to upgrade my .NET app using GitHub Copilot modernization so that I can modernize my codebase efficiently with AI assistance through a structured three-stage process. @@ -25,19 +25,19 @@ To start an upgrade, use the `modernize-dotnet` agent in Copilot: [!INCLUDE[github-copilot-how-to-initiate](./includes/how-to-initiate.md)] -When you start the upgrade, Copilot prompts you to create a new branch if you're working in a Git repository. Copilot then runs a three-stage workflow, writing a Markdown file for each stage under `.github/upgrades` in your repository. If `.github/upgrades` already exists from a prior attempt, Copilot asks whether to continue or start fresh. +When you start the upgrade, Copilot collects pre-initialization information: the target framework version, Git branching strategy, and workflow mode (automatic or guided by you). Copilot then runs a three-stage workflow, writing a Markdown file for each stage under `.github/upgrades/{scenarioId}` in your repository. The `{scenarioId}` is a unique identifier for the upgrade type, such as `dotnet-version-upgrade`. If `.github/upgrades/{scenarioId}` already exists from a prior attempt, Copilot asks whether to continue or start fresh. The three stages are: -- **Assessment stage** - Copilot examines your project to identify breaking changes, compatibility problems, and upgrade requirements. -- **Planning stage** - Copilot creates a detailed specification explaining how to resolve every problem. -- **Execution stage** - Copilot breaks the plan into sequential tasks and performs the upgrade. +- **Assessment stage** — Copilot examines your project to identify breaking changes, compatibility problems, and upgrade requirements. +- **Planning stage** — Copilot creates a detailed specification explaining how to resolve every problem. +- **Execution stage** — Copilot breaks the plan into sequential tasks and performs the upgrade. ## Start assessment and review results -The assessment stage examines your project structure, dependencies, and code patterns to identify what needs to change. Copilot automatically starts this stage and generates an `assessment.md` file in `.github/upgrades`. +The assessment stage examines your project structure, dependencies, and code patterns to identify what needs to change. Copilot automatically starts this stage and generates an `assessment.md` file in `.github/upgrades/{scenarioId}`. -The assessment lists breaking changes, API compatibility problems, deprecated patterns, and the upgrade scope so you know what needs attention. The following example shows part of an assessment for an ASP.NET Core project upgrading from .NET 6.0 to .NET 10.0: +The assessment lists breaking changes, API compatibility problems, deprecated patterns, and the upgrade scope. The following example shows part of an assessment for an ASP.NET Core project upgrading from .NET 6.0 to .NET 10.0: ```markdown # Projects and dependencies analysis @@ -70,14 +70,14 @@ This document provides a comprehensive overview of the projects and their depend To review and customize the assessment: -1. Open the `assessment.md` file in `.github/upgrades`. +1. Open the `assessment.md` file in `.github/upgrades/{scenarioId}`. 1. Review the identified breaking changes and compatibility problems. 1. Add any project-specific context or concerns to the document. 1. Tell Copilot to move to the planning stage. ## Start planning and review the plan -The planning stage converts the assessment into a detailed specification that explains how to resolve every issue. When you tell Copilot to proceed to planning, it generates a `plan.md` file in `.github/upgrades`. +The planning stage converts the assessment into a detailed specification that explains how to resolve every issue. When you tell Copilot to proceed to planning, it generates a `plan.md` file in `.github/upgrades/{scenarioId}`. The plan documents upgrade strategies, refactoring approaches, dependency upgrade paths, and risk mitigations. The following example shows part of a plan for an ASP.NET Core project: @@ -116,18 +116,18 @@ Upgrade all projects in the MvcMovieNet6 solution from .NET 6 to .NET 10 (Long T To review and customize the plan: -1. Open the `plan.md` file in `.github/upgrades`. +1. Open the `plan.md` file in `.github/upgrades/{scenarioId}`. 1. Review the upgrade strategies and dependency updates. 1. Edit the plan to adjust upgrade steps or add context if needed. > [!CAUTION] - > The plan is based on project interdependencies. The upgrade won't succeed if you modify the plan in such a way that the migration path can't complete. For example, if **Project A** depends on **Project B** and you remove **Project B** from the upgrade plan, upgrading **Project A** might fail. + > The plan is based on project interdependencies. The upgrade doesn't succeed if you modify the plan in such a way that the migration path can't complete. For example, if **Project A** depends on **Project B** and you remove **Project B** from the upgrade plan, upgrading **Project A** might fail. 1. Tell Copilot to move to the execution stage. ## Start execution and run the upgrade -The execution stage breaks the plan into sequential, concrete tasks with validation criteria. When you tell Copilot to proceed to execution, it generates a `tasks.md` file in `.github/upgrades`. +The execution stage breaks the plan into sequential, concrete tasks with validation criteria. When you tell Copilot to proceed to execution, it generates a `tasks.md` file in `.github/upgrades/{scenarioId}`. The task list describes each task and how Copilot validates success. The following example shows the task list for a solution containing ASP.NET Core and WPF projects: @@ -183,15 +183,13 @@ To run the upgrade: 1. Tell Copilot to start the upgrade. 1. Monitor progress by reviewing the `tasks.md` file as Copilot updates task statuses. 1. If Copilot encounters a problem it can't resolve, provide the requested help. -1. Copilot learns from your changes and continues the upgrade. +1. Based on your decisions and changes, Copilot adapts its strategy to the remaining tasks and continues the upgrade. -The tool creates a Git commit for every portion of the process, so you can easily roll back changes or get detailed information about what changed. +Copilot commits changes according to the Git strategy you configured during pre-initialization: per task, per group of tasks, or at the end. ## Verify the upgrade -When the upgrade finishes, Copilot shows recommended next steps in the chat response. Review the `tasks.md` file for the status of every step. - -The tool creates a Git commit for every portion of the upgrade process, so you can easily roll back changes or get detailed information about what changed. +When the upgrade finishes, Copilot shows recommended next steps in the chat response. Review the `tasks.md` file in `.github/upgrades/{scenarioId}` for the status of every step. The following example shows completed tasks for an ASP.NET Core project upgrade: From 892efa55d7dcbd5d6652134d85b49517dac4184a Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 22:25:50 -0400 Subject: [PATCH 07/11] Rewrite covariance/contravariance definitions to be user-focused (#52120) * Initial plan * Improve covariance/contravariance definitions to be more user-focused Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> * Address review: use 'type argument' terminology and put invariant first Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Apply suggestions from code review --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> Co-authored-by: Bill Wagner Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../generics/covariance-and-contravariance.md | 37 ++++++++----------- 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/docs/standard/generics/covariance-and-contravariance.md b/docs/standard/generics/covariance-and-contravariance.md index db5aa04d30fa9..ab9ebbf65e76f 100644 --- a/docs/standard/generics/covariance-and-contravariance.md +++ b/docs/standard/generics/covariance-and-contravariance.md @@ -1,7 +1,8 @@ --- title: "Covariance and Contravariance in Generics" description: Learn about covariance, which allows you to use a more derived type, and contravariance, which allows you to use a less derived type, in .NET generics. -ms.date: "03/30/2017" +ms.date: "03/09/2026" +ai-usage: ai-assisted dev_langs: - "csharp" - "vb" @@ -14,27 +15,21 @@ ms.assetid: 2678dc63-c7f9-4590-9ddc-0a4df684d42e --- # Covariance and contravariance in generics -*Covariance* and *contravariance* are terms that refer to the ability to use a more derived type (more specific) or a less derived type (less specific) than originally specified. Generic type parameters support covariance and contravariance to provide greater flexibility in assigning and using generic types. +*Covariance* and *contravariance* describe how reference conversions work between constructed generic types when their type arguments are related by inheritance, for example, between `IEnumerable` and `IEnumerable`. Variance is a property of a generic interface or delegate type's type parameter, and it controls which implicit conversions exist between constructed types that use different type arguments. By default, generic type parameters are *invariant*—even if one type argument derives from another, the corresponding constructed generic types, such as `List` and `List`, are unrelated unless the type parameter is explicitly declared as *covariant* or *contravariant*. -When you're referring to a type system, covariance, contravariance, and invariance have the following definitions. The examples assume a base class named `Base` and a derived class named `Derived`. - -- `Covariance` - - Enables you to use a more derived type than originally specified. - - You can assign an instance of `IEnumerable` to a variable of type `IEnumerable`. - -- `Contravariance` - - Enables you to use a more generic (less derived) type than originally specified. - - You can assign an instance of `Action` to a variable of type `Action`. - -- `Invariance` - - Means that you can use only the type originally specified. An invariant generic type parameter is neither covariant nor contravariant. - - You cannot assign an instance of `List` to a variable of type `List` or vice versa. +The following definitions and examples assume a base class named `Base` and a derived class named `Derived`. + +- *Invariant* type arguments require you to use exactly the type specified. You can't substitute a derived or base type. + + For example, you can't assign an instance of `List` to a variable of type `List`, or vice versa. + +- *Covariant* type parameters let you substitute a more derived type for the original type argument. + + For example, you can assign an instance of `IEnumerable` to a variable of type `IEnumerable`. + +- *Contravariant* type parameters let you substitute a base type for a derived type argument instead of the original. + + For example, you can assign an instance of `Action` to a variable of type `Action`. Covariant type parameters enable you to make assignments that look much like ordinary [Polymorphism](../../csharp/fundamentals/object-oriented/polymorphism.md), as shown in the following code. From c8ce29ed4fe11c692661ae416b1c6d1e5ec34196 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Fri, 27 Mar 2026 22:30:04 -0400 Subject: [PATCH 08/11] Doc: Add constructed generic type notation to type name specification article (#52704) * Initial plan * Add documentation for specifying constructed generic types in type name strings Agent-Logs-Url: https://github.com/dotnet/docs/sessions/e4564aec-04c6-4558-8641-48ee1411b24f Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Address reviewer feedback: broaden GenericArgument grammar rule and update assembly name to System.Private.CoreLib Agent-Logs-Url: https://github.com/dotnet/docs/sessions/3bde682b-2d60-4842-a2ef-9e110d714f9b Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> Co-authored-by: Bill Wagner Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../specifying-fully-qualified-type-names.md | 35 +++++++++++++++++-- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/docs/fundamentals/reflection/specifying-fully-qualified-type-names.md b/docs/fundamentals/reflection/specifying-fully-qualified-type-names.md index 7e589deb9c9f7..ddd64225f1673 100644 --- a/docs/fundamentals/reflection/specifying-fully-qualified-type-names.md +++ b/docs/fundamentals/reflection/specifying-fully-qualified-type-names.md @@ -1,7 +1,8 @@ --- title: Specify fully qualified type name description: For valid input to reflection operations, use fully qualified type names, which have assembly name specifications, namespace specifications, and type names. -ms.date: 02/21/2019 +ms.date: 03/27/2026 +ai-usage: ai-assisted helpviewer_keywords: - "names [.NET], fully qualified type names" - "reflection, fully qualified type names" @@ -43,7 +44,19 @@ SimpleTypeSpec ; GenericTypeSpec - : SimpleTypeSpec ` NUMBER + : SimpleTypeSpec ` NUMBER + | SimpleTypeSpec ` NUMBER '[' GenericArguments ']' + ; + +GenericArguments + : GenericArgument + | GenericArguments ',' GenericArgument + ; + +GenericArgument + : TypeSpec + | '[' TypeSpec ']' + ; PointerTypeSpec : SimpleTypeSpec '*' @@ -183,7 +196,23 @@ com.microsoft.crypto, Culture=en, PublicKeyToken=a5d015c7d5a0b012, ## Specify generic types -SimpleTypeSpec\`NUMBER represents an open generic type with from 1 to *n* generic type parameters. For example, to get reference to the open generic type `List` or the closed generic type `List`, use ``Type.GetType("System.Collections.Generic.List`1")`` To get a reference to the generic type `Dictionary`, use ``Type.GetType("System.Collections.Generic.Dictionary`2")``. +``SimpleTypeSpec`NUMBER`` represents a generic type definition with 1 to *n* generic type parameters. For example, to get a reference to the open generic type `List`, use ``Type.GetType("System.Collections.Generic.List`1")``. To get a reference to the open generic type `Dictionary`, use ``Type.GetType("System.Collections.Generic.Dictionary`2")``. + +To specify a *constructed* generic type—one where the type parameters are replaced with specific types—append the type arguments in square brackets after the arity: ``SimpleTypeSpec`NUMBER[TypeArg1,TypeArg2]``. For example, to get a reference to `List`, use ``Type.GetType("System.Collections.Generic.List`1[System.String]")``. To get a reference to `Dictionary`, use ``Type.GetType("System.Collections.Generic.Dictionary`2[System.String,System.Int32]")``. + +When a type argument is assembly-qualified, enclose it in its own square brackets to prevent the commas in the assembly name from being misinterpreted as type argument separators. For example: + +``` +"System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib],[System.Int32, System.Private.CoreLib]]" +``` + +Unbracketed type arguments can't include an assembly qualifier. To mix assembly-qualified and unqualified type arguments, wrap only the assembly-qualified ones in brackets: + +``` +"System.Collections.Generic.Dictionary`2[System.String,[MyNamespace.MyType, MyAssembly]]" +``` + +The property returns a type's name in the format that `Type.GetType` accepts. Use it to obtain a correctly formatted string for any constructed generic type. For example, `typeof(Dictionary).AssemblyQualifiedName` returns the fully qualified, correctly escaped name you can pass to `Type.GetType`. ## Specify pointers From 6e25c3be15d3ec2a0f0441614e95c8da356d8dc2 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Sat, 28 Mar 2026 02:32:47 +0000 Subject: [PATCH 09/11] Add IIS single-file deployment limitation note (#52680) * Initial plan * Add note that IIS doesn't support single-file deployments Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> Agent-Logs-Url: https://github.com/dotnet/docs/sessions/53374ddc-8038-48d0-8b50-fbb35f30c772 * Update docs/core/deploying/single-file/overview.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/core/deploying/single-file/overview.md Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> Co-authored-by: Bill Wagner Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> --- docs/core/deploying/single-file/overview.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/core/deploying/single-file/overview.md b/docs/core/deploying/single-file/overview.md index a8f77464478c5..341b31c1994fc 100644 --- a/docs/core/deploying/single-file/overview.md +++ b/docs/core/deploying/single-file/overview.md @@ -2,7 +2,7 @@ title: Create a single file for application deployment description: Learn what single file application is and why you should consider using this application deployment model. author: lakshanf -ms.date: 10/22/2025 +ms.date: 03/25/2026 ms.custom: kr2b-contr-experiment ai-usage: ai-assisted --- @@ -147,6 +147,9 @@ For example, add the following property to the project file of an assembly to em ## Other considerations +> [!IMPORTANT] +> IIS doesn't support hosting ASP.NET Core apps that use single-file deployment with the in-process hosting model. If you host an ASP.NET Core app in IIS, publish your app using the standard folder deployment model, or use the out-of-process hosting model instead. For more information, see [Host ASP.NET Core on Windows with IIS](/aspnet/core/host-and-deploy/iis). + Single file applications have all related PDB files alongside the application, not bundled by default. If you want to include PDBs inside the assembly for projects you build, set the `DebugType` to `embedded`. See [Include PDB files inside the bundle](#include-pdb-files-inside-the-bundle). Managed C++ components aren't well suited for single file deployment. We recommend that you write applications in C# or another non-managed C++ language to be single file compatible. From 0856a0724cbb23de9da69213fca761980f72222d Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Sat, 28 Mar 2026 02:42:34 +0000 Subject: [PATCH 10/11] Add string.Create documentation to "Create new strings in .NET" (#52316) * Initial plan * Add string.Create documentation to creating-new.md with C# and VB snippets Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Co-authored-by: Bill Wagner * Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Apply suggestion from @BillWagner * Code-fence all H3 method headings (Format, Concat, Join, Insert, CopyTo) to match String.Create Agent-Logs-Url: https://github.com/dotnet/docs/sessions/a7a2b1b2-b0fa-4d50-9011-bebb40a65c00 Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com> Co-authored-by: Bill Wagner Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/standard/base-types/creating-new.md | 196 ++++++++++-------- .../snippets/creating-new/csharp/Program.cs | 28 +++ .../creating-new/csharp/creating-new.csproj | 11 + .../snippets/creating-new/vb/Program.vb | 15 ++ .../creating-new/vb/creating-new.vbproj | 10 + 5 files changed, 175 insertions(+), 85 deletions(-) create mode 100644 docs/standard/base-types/snippets/creating-new/csharp/Program.cs create mode 100644 docs/standard/base-types/snippets/creating-new/csharp/creating-new.csproj create mode 100644 docs/standard/base-types/snippets/creating-new/vb/Program.vb create mode 100644 docs/standard/base-types/snippets/creating-new/vb/creating-new.vbproj diff --git a/docs/standard/base-types/creating-new.md b/docs/standard/base-types/creating-new.md index 6cd9906e023a7..9c494a44a289c 100644 --- a/docs/standard/base-types/creating-new.md +++ b/docs/standard/base-types/creating-new.md @@ -1,85 +1,111 @@ ---- -title: "Creating New Strings" -description: Learn to create strings using assignment, class constructors, or System.String methods that combine several strings, arrays of strings, or objects in .NET. -ms.date: "03/30/2017" -dev_langs: - - "csharp" - - "vb" -helpviewer_keywords: - - "CopyTo method" - - "Join method" - - "Format method" - - "Concat method" - - "strings [.NET], creating" - - "Insert method" ---- -# Create new strings in .NET - -.NET allows strings to be created using simple assignment, and also overloads a class constructor to support string creation using a number of different parameters. .NET also provides several methods in the class that create new string objects by combining several strings, arrays of strings, or objects. - -## Create strings using assignment - - The easiest way to create a new object is simply to assign a string literal to a object. - -## Create strings using a class constructor - - You can use overloads of the class constructor to create strings from character arrays. You can also create a new string by duplicating a particular character a specified number of times. - -## Methods that return strings - - The following table lists several useful methods that return new string objects. - -| Method name | Use | -|-------------------------------------------------------------|--------------------------------------------------------| -| | Builds a formatted string from a set of input objects. | -| | Builds strings from two or more strings. | -| | Builds a new string by combining an array of strings. | -| | Builds a new string by inserting a string into the specified index of an existing string. | -| | Copies specified characters in a string into a specified position in an array of characters. | - -### Format - - You can use the `String.Format` method to create formatted strings and concatenate strings representing multiple objects. This method automatically converts any passed object into a string. For example, if your application must display an `Int32` value and a `DateTime` value to the user, you can easily construct a string to represent these values using the `Format` method. For information about formatting conventions used with this method, see the section on [composite formatting](composite-formatting.md). - - The following example uses the `Format` method to create a string that uses an integer variable. - - [!code-csharp[Strings.Creating#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#1)] - [!code-vb[Strings.Creating#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#1)] - - In this example, displays the current date and time in a manner specified by the culture associated with the current thread. - -### Concat - - The `String.Concat` method can be used to easily create a new string object from two or more existing objects. It provides a language-independent way to concatenate strings. This method accepts any class that derives from `System.Object`. The following example creates a string from two existing string objects and a separating character. - - [!code-csharp[Strings.Creating#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#2)] - [!code-vb[Strings.Creating#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#2)] - -### Join - - The `String.Join` method creates a new string from an array of strings and a separator string. This method is useful if you want to concatenate multiple strings together, making a list perhaps separated by a comma. - - The following example uses a space to bind a string array. - - [!code-csharp[Strings.Creating#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#3)] - [!code-vb[Strings.Creating#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#3)] - -### Insert - - The `String.Insert` method creates a new string by inserting a string into a specified position in another string. This method uses a zero-based index. The following example inserts a string into the fifth index position of `MyString` and creates a new string with this value. - - [!code-csharp[Strings.Creating#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#4)] - [!code-vb[Strings.Creating#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#4)] - -### CopyTo - - The `String.CopyTo` method copies portions of a string into an array of characters. You can specify both the beginning index of the string and the number of characters to be copied. This method takes the source index, an array of characters, the destination index, and the number of characters to copy. All indexes are zero-based. - - The following example uses the `CopyTo` method to copy the characters of the word "Hello" from a string object to the first index position of an array of characters. - - [!code-csharp[Strings.Creating#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#5)] - [!code-vb[Strings.Creating#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#5)] - -## See also - -- [Composite Formatting](composite-formatting.md) +--- +title: "Creating New Strings" +description: Learn to create strings using assignment, class constructors, or System.String methods that combine several strings, arrays of strings, or objects in .NET. +ms.date: "03/16/2026" +ai-usage: ai-assisted +dev_langs: + - "csharp" + - "vb" +helpviewer_keywords: + - "CopyTo method" + - "Join method" + - "Format method" + - "Concat method" + - "strings [.NET], creating" + - "Insert method" + - "Create method" +--- +# Create new strings in .NET + +.NET allows strings to be created using simple assignment, and also overloads a class constructor to support string creation using a number of different parameters. .NET also provides several methods in the class that create new string objects by combining several strings, arrays of strings, or objects. + +## Create strings using assignment + +The easiest way to create a new object is simply to assign a string literal to a object. + +## Create strings using a class constructor + +You can use overloads of the class constructor to create strings from character arrays. You can also create a new string by duplicating a particular character a specified number of times. The constructor overload accepts a or a stack-allocated of characters and avoids allocating an intermediate character array on the managed heap when you build small strings of a known size, although the resulting string instance is still allocated on the managed heap. + +## Methods that return strings + +The following table lists several useful methods that return new string objects. + +| Method name | Use | +|---------------------------------------------------------------|--------------------------------------------------------| +| | Builds a formatted string from a set of input objects. | +| | Builds strings from two or more strings. | +| | Builds a new string by combining an array of strings. | +| | Builds a new string by inserting a string into the specified index of an existing string. | +| | Copies specified characters in a string into a specified position in an array of characters. | +| | Creates a new string of a specified length, populating characters via a callback that receives a writable and a caller-supplied state object. | + +### `String.Format` + +You can use the `String.Format` method to create formatted strings and concatenate strings representing multiple objects. This method automatically converts any passed object into a string. For example, if your application must display an `Int32` value and a `DateTime` value to the user, you can easily construct a string to represent these values using the `Format` method. For information about formatting conventions used with this method, see the section on [composite formatting](composite-formatting.md). + +The following example uses the `Format` method to create a string that uses an integer variable. + +[!code-csharp[Strings.Creating#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#1)] +[!code-vb[Strings.Creating#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#1)] + +In this example, displays the current date and time in a manner specified by the culture associated with the current thread. + +### `String.Concat` + +The `String.Concat` method can be used to easily create a new string object from two or more existing objects. It provides a language-independent way to concatenate strings. This method accepts any class that derives from `System.Object`. The following example creates a string from two existing string objects and a separating character. + +[!code-csharp[Strings.Creating#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#2)] +[!code-vb[Strings.Creating#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#2)] + +### `String.Join` + +The `String.Join` method creates a new string from an array of strings and a separator string. This method is useful if you want to concatenate multiple strings together, making a list perhaps separated by a comma. + +The following example uses a space to bind a string array. + +[!code-csharp[Strings.Creating#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#3)] +[!code-vb[Strings.Creating#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#3)] + +### `String.Insert` + +The `String.Insert` method creates a new string by inserting a string into a specified position in another string. This method uses a zero-based index. The following example inserts a string into the fifth index position of `MyString` and creates a new string with this value. + +[!code-csharp[Strings.Creating#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#4)] +[!code-vb[Strings.Creating#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#4)] + +### `String.CopyTo` + +The `String.CopyTo` method copies portions of a string into an array of characters. You can specify both the beginning index of the string and the number of characters to be copied. This method takes the source index, an array of characters, the destination index, and the number of characters to copy. All indexes are zero-based. + +The following example uses the `CopyTo` method to copy the characters of the word "Hello" from a string object to the first index position of an array of characters. + +[!code-csharp[Strings.Creating#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#5)] +[!code-vb[Strings.Creating#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#5)] + +### `String.Create` + +The method lets you programmatically fill a new string's characters using a callback. The callback receives a writable of characters and a caller-supplied state object, so you can build the string's content without allocating intermediate character buffers. The callback itself might still allocate, for example if it captures local variables or calls other allocation-heavy APIs. + +The following example uses `String.Create` to build a five-character string from consecutive alphabet characters: + +:::code language="csharp" source="./snippets/creating-new/csharp/Program.cs" id="UsingStringCreate"::: +:::code language="vb" source="./snippets/creating-new/vb/Program.vb" id="UsingStringCreate"::: + +`String.Create` is designed for performance-sensitive scenarios where you know the final string length in advance and want to avoid allocating intermediate character buffers. The runtime allocates a new string, passes its backing buffer directly to your callback as a `Span`, and returns the immutable string once the callback returns. No copy of the data occurs after the callback completes. + +#### `String.Create` vs. `new String(Span)` + +Another option for building strings efficiently is to allocate a character buffer with `stackalloc`, fill it, and pass it to the `String(ReadOnlySpan)` constructor: + +:::code language="csharp" source="./snippets/creating-new/csharp/Program.cs" id="UsingSpanConstructor"::: + +Both approaches allocate the final string exactly once. The key differences are: + +- **`stackalloc` + `new string(span)`** places the working buffer on the stack. This is fastest for *small, fixed-size* buffers, but the stack is a finite resource; large or deeply nested allocations can cause a `StackOverflowException`. This example shows the C# `stackalloc` pattern; Visual Basic doesn't support `stackalloc`, but it can still call the `String(ReadOnlySpan)` constructor when you have a `ReadOnlySpan`. +- **`String.Create`** allocates the working buffer on the heap as part of the string object itself, so there's no stack pressure. It also accepts a typed state parameter that the runtime passes to your callback without boxing, avoiding boxing allocations when the state is a reference type or a non-captured struct. +In general, prefer `stackalloc` + `new String(span)` for small strings (typically fewer than a few hundred characters) with a known, bounded size. Use `String.Create` when the size might be large, when you want to avoid stack pressure, or when passing state into the callback without boxing. + +## See also + +- [Composite Formatting](composite-formatting.md) diff --git a/docs/standard/base-types/snippets/creating-new/csharp/Program.cs b/docs/standard/base-types/snippets/creating-new/csharp/Program.cs new file mode 100644 index 0000000000000..4ef617dfa64b7 --- /dev/null +++ b/docs/standard/base-types/snippets/creating-new/csharp/Program.cs @@ -0,0 +1,28 @@ +using System; + +// +static string CreateStringFromSpan() +{ + Span span = stackalloc char[5]; + for (int i = 0; i < 5; i++) + { + span[i] = (char)('a' + i); + } + return new string(span); +} + +Console.WriteLine(CreateStringFromSpan()); // abcde +// + +// +string result = string.Create(5, 'a', (span, firstChar) => +{ + for (int i = 0; i < span.Length; i++) + { + span[i] = (char)(firstChar + i); + } +}); + +Console.WriteLine(result); // abcde +// + diff --git a/docs/standard/base-types/snippets/creating-new/csharp/creating-new.csproj b/docs/standard/base-types/snippets/creating-new/csharp/creating-new.csproj new file mode 100644 index 0000000000000..f5599093400c6 --- /dev/null +++ b/docs/standard/base-types/snippets/creating-new/csharp/creating-new.csproj @@ -0,0 +1,11 @@ + + + + Exe + net10.0 + creating_new + enable + enable + + + diff --git a/docs/standard/base-types/snippets/creating-new/vb/Program.vb b/docs/standard/base-types/snippets/creating-new/vb/Program.vb new file mode 100644 index 0000000000000..f9526c6763620 --- /dev/null +++ b/docs/standard/base-types/snippets/creating-new/vb/Program.vb @@ -0,0 +1,15 @@ +Imports System + +' +Module Program + Sub Main() + Dim result As String = String.Create(5, "a"c, Sub(span, firstChar) + For i As Integer = 0 To span.Length - 1 + span(i) = ChrW(AscW(firstChar) + i) + Next + End Sub) + + Console.WriteLine(result) ' abcde + End Sub +End Module +' diff --git a/docs/standard/base-types/snippets/creating-new/vb/creating-new.vbproj b/docs/standard/base-types/snippets/creating-new/vb/creating-new.vbproj new file mode 100644 index 0000000000000..cc8f63307ca35 --- /dev/null +++ b/docs/standard/base-types/snippets/creating-new/vb/creating-new.vbproj @@ -0,0 +1,10 @@ + + + + Exe + creating_new + net10.0 + on + + + From 156931bb4ec1e81b028c76ea983553f2e9778bdd Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Sun, 29 Mar 2026 16:41:50 -0700 Subject: [PATCH 11/11] Replace encodings in xrefs (#52699) --- .../blazor-for-web-forms-developers/config.md | 2 +- .../infrastructure-resiliency-azure.md | 2 +- docs/architecture/maui/validation.md | 4 +- ...ry-to-implement-resilient-http-requests.md | 4 +- .../domain-model-layer-validations.md | 2 +- .../background-tasks-with-ihostedservice.md | 2 +- ...tion-net-microservices-web-applications.md | 4 +- .../index.md | 2 +- .../develop-asp-net-core-mvc-apps.md | 2 +- .../work-with-data-in-asp-net-core-apps.md | 2 +- docs/azure/sdk/aspnetcore-guidance.md | 6 +- .../sdk/authentication/best-practices.md | 8 +- ...te-token-credentials-from-configuration.md | 4 +- .../sdk/authentication/credential-chains.md | 2 +- .../local-development-broker.md | 2 +- docs/azure/sdk/configure-proxy.md | 4 +- docs/azure/sdk/dependency-injection.md | 10 +- docs/azure/sdk/logging.md | 16 +- docs/azure/sdk/pagination.md | 32 +- .../azure/sdk/protocol-convenience-methods.md | 4 +- docs/azure/sdk/unit-testing-mocking.md | 10 +- ...2015-finalizers-for-memorymanager-types.md | 4 +- ...-ctor-arg-should-be-taskcreationoptions.md | 6 +- .../10.0/sigterm-signal-handler.md | 2 +- .../sve-nonfaulting-loads-mask-parameter.md | 2 +- .../11/ziparchive-createasync-eager-load.md | 2 +- .../5.0/code-access-security-apis-obsolete.md | 4 +- ...ntersetinstance-throws-invalidoperation.md | 8 +- ...nment-osversion-returns-correct-version.md | 2 +- .../intptr-uintptr-implement-iformattable.md | 4 +- ...dexof-improved-handling-of-empty-values.md | 10 +- .../obsolete-apis-with-custom-diagnostics.md | 14 +- ...erby-firstordefault-complexity-increase.md | 14 +- .../5.0/thread-abort-obsolete.md | 16 +- .../5.0/utf-7-code-paths-obsolete.md | 16 +- .../5.0/vector-lerp-behavior-change.md | 2 +- .../vectort-throws-notsupportedexception.md | 12 +- ...itional-linq-queryable-method-overloads.md | 20 +- .../debug-assert-conditional-evaluation.md | 2 +- .../6.0/file-replace-exceptions-on-unix.md | 12 +- .../filestream-doesnt-sync-offset-with-os.md | 2 +- ...s-after-readasync-writeasync-completion.md | 8 +- .../nullable-ref-type-annotation-changes.md | 12 +- .../obsolete-apis-with-custom-diagnostics.md | 8 +- .../6.0/parameter-name-changes.md | 12 +- .../6.0/partial-byte-reads-in-streams.md | 14 +- .../stringbuilder-append-evaluation-order.md | 10 +- .../6.0/task-fromresult-returns-singleton.md | 12 +- .../6.0/xnodereader-getattribute.md | 2 +- .../core-libraries/7.0/equals-nan.md | 36 +- .../7.0/filestream-compat-switch.md | 2 +- .../max-precision-numeric-format-strings.md | 4 +- .../7.0/memorycache-tracking.md | 2 +- .../obsolete-apis-with-custom-diagnostics.md | 4 +- .../7.0/patterncontext-generic-constraint.md | 8 +- .../core-libraries/7.0/regex-ranges.md | 14 +- .../8.0/activity-operation-name.md | 6 +- .../core-libraries/8.0/bool-backed-enum.md | 12 +- .../core-libraries/8.0/complex-format.md | 10 +- .../8.0/console-readkey-legacy.md | 8 +- .../8.0/decodefromutf8-whitespace.md | 2 +- .../8.0/drive-current-dir-paths.md | 26 +- .../core-libraries/8.0/enumerable-sum.md | 4 +- .../core-libraries/8.0/file-path-backslash.md | 8 +- .../8.0/filestream-disposed-pipe.md | 4 +- .../core-libraries/8.0/getfolderpath-unix.md | 2 +- .../8.0/getgeneration-return-value.md | 6 +- .../obsolete-apis-with-custom-diagnostics.md | 20 +- .../8.0/parameterinfo-hasdefaultvalue.md | 2 +- .../8.0/processstartinfo-windowstyle.md | 2 +- .../9.0/compressionlevel-bits.md | 2 +- .../core-libraries/9.0/getsubarray-return.md | 6 +- .../9.0/inmemorydirinfo-prepends-rootdir.md | 2 +- .../obsolete-apis-with-custom-diagnostics.md | 6 +- .../cryptography/7.0/decrypt-envelopedcms.md | 2 +- .../cryptography/8.0/aesgcm-auth-tag-size.md | 10 +- .../8.0/rsa-encrypt-decrypt-value-obsolete.md | 2 +- .../cryptography/9.0/x509-certificates.md | 2 +- .../backgroundservice-executeasync-task.md | 4 +- ...console-json-logging-duplicate-messages.md | 2 +- .../6.0/service-provider-disposed.md | 2 +- .../7.0/contentrootpath-hosted-app.md | 6 +- ...ivatorutilities-createinstance-behavior.md | 8 +- ...rutilities-createinstance-null-provider.md | 8 +- .../8.0/configurationbinder-exceptions.md | 2 +- .../5.0/icu-globalization-api.md | 12 +- .../uax29-compliant-grapheme-enumeration.md | 6 +- .../unicode-categories-for-latin1-chars.md | 10 +- .../6.0/culture-creation-invariant-mode.md | 6 +- .../7.0/icu-globalization-api.md | 12 +- .../8.0/twodigityearmax-default.md | 26 +- ...ulticastoption-group-doesnt-accept-null.md | 2 +- ...eam-dont-fail-on-successive-begin-calls.md | 8 +- .../7.0/ping-custom-payload-linux.md | 2 +- .../7.0/socket-end-closed-sockets.md | 8 +- .../networking/8.0/sendfile-connectionless.md | 20 +- .../10/ireflect-damt-annotations.md | 2 +- ...ormatter-deserialize-rewraps-exceptions.md | 8 +- .../binaryformatter-serialization-obsolete.md | 8 +- ...son-into-char-requires-single-character.md | 2 +- ...lizer-allows-reading-numbers-as-strings.md | 6 +- ...ows-argumentnullexception-for-null-type.md | 4 +- ...nstructors-not-used-for-deserialization.md | 6 +- ...onored-when-serializing-key-value-pairs.md | 22 +- .../6.0/iasyncenumerable-serialization.md | 18 +- ...onserializer-source-generator-overloads.md | 2 +- .../6.0/timespan-serialization-format.md | 2 +- .../binaryformatter-apis-produce-errors.md | 8 +- .../datacontractserializer-negative-sign.md | 4 +- .../deserialize-version-with-whitespace.md | 4 +- .../7.0/polymorphic-serialization.md | 8 +- .../serialization/7.0/reflection-fallback.md | 14 +- .../serialization/8.0/metadata-resolving.md | 2 +- docs/core/compatibility/unsupported-apis.md | 44 +- .../6.0/duplex-synchronization-context.md | 6 +- ...tring-field-of-textformatflags-obsolete.md | 2 +- .../6.0/listview-invalidoperationexception.md | 4 +- .../9.0/componentdesigner-initialize.md | 10 +- .../wpf/9.0/xml-namespace-maps.md | 4 +- .../dependency-loading/collect-details.md | 2 +- .../dependency-loading/default-probing.md | 2 +- .../dependency-loading/loading-managed.md | 22 +- .../dependency-loading/loading-resources.md | 4 +- .../dependency-loading/loading-unmanaged.md | 2 +- .../understanding-assemblyloadcontext.md | 8 +- .../trimming/trim-warnings/il2032.md | 2 +- .../trimming/trim-warnings/il2058.md | 6 +- .../trimming/trim-warnings/il2061.md | 2 +- .../deploying/trimming/trimming-options.md | 2 +- .../ambient-metadata/application-metadata.md | 2 +- .../built-in-metrics-diagnostics.md | 2 +- .../diagnostics/built-in-metrics-runtime.md | 12 +- .../diagnostic-exception-summary.md | 6 +- .../diagnostics/diagnostic-health-checks.md | 12 +- .../diagnostic-resource-monitoring.md | 6 +- .../diagnosticsource-diagnosticlistener.md | 2 +- .../distributed-tracing-builtin-activities.md | 2 +- ...ributed-tracing-collection-walkthroughs.md | 4 +- .../distributed-tracing-concepts.md | 10 +- ...ed-tracing-instrumentation-walkthroughs.md | 10 +- docs/core/diagnostics/event-counter-perf.md | 2 +- docs/core/diagnostics/event-counters.md | 14 +- .../eventsource-collect-and-view-traces.md | 8 +- .../eventsource-instrumentation.md | 10 +- docs/core/diagnostics/index.md | 2 +- docs/core/diagnostics/logging-tracing.md | 2 +- docs/core/diagnostics/metrics-collection.md | 4 +- .../diagnostics/metrics-instrumentation.md | 46 +- .../diagnostics/observability-with-otel.md | 2 +- .../enrichment/application-log-enricher.md | 2 +- docs/core/extensions/async-state.md | 10 +- docs/core/extensions/caching.md | 78 +- docs/core/extensions/channels.md | 40 +- .../extensions/configuration-generator.md | 8 +- .../extensions/configuration-providers.md | 10 +- docs/core/extensions/create-resource-files.md | 6 +- .../custom-configuration-provider.md | 2 +- .../dependency-injection/auto-activation.md | 6 +- .../extensions/dependency-injection/basics.md | 2 +- .../dependency-injection/guidelines.md | 16 +- .../dependency-injection/overview.md | 4 +- .../dependency-injection/service-lifetimes.md | 8 +- .../service-registration.md | 14 +- docs/core/extensions/file-globbing.md | 12 +- docs/core/extensions/generic-host.md | 44 +- docs/core/extensions/globalization-icu.md | 4 +- docs/core/extensions/globalization.md | 14 +- docs/core/extensions/http-ratelimiter.md | 6 +- .../extensions/httpclient-factory-keyed-di.md | 8 +- .../httpclient-factory-troubleshooting.md | 6 +- docs/core/extensions/httpclient-factory.md | 40 +- docs/core/extensions/httpclient-http3.md | 2 +- docs/core/extensions/localizability-review.md | 2 +- docs/core/extensions/localization.md | 12 +- .../logging/console-log-formatter.md | 18 +- .../logging/high-performance-logging.md | 14 +- .../extensions/logging/library-guidance.md | 6 +- docs/core/extensions/logging/log-buffering.md | 4 +- docs/core/extensions/logging/log-sampling.md | 4 +- docs/core/extensions/logging/overview.md | 34 +- docs/core/extensions/logging/providers.md | 10 +- .../extensions/logging/source-generation.md | 6 +- .../extensions/options-library-authors.md | 34 +- .../options-validation-generator.md | 4 +- docs/core/extensions/options.md | 18 +- ...orming-culture-insensitive-case-changes.md | 10 +- ...-culture-insensitive-string-comparisons.md | 10 +- ...insensitive-string-operations-in-arrays.md | 6 +- ...sitive-string-operations-in-collections.md | 6 +- ...g-culture-insensitive-string-operations.md | 8 +- docs/core/extensions/primitives.md | 8 +- docs/core/extensions/queue-service.md | 4 +- docs/core/extensions/retrieve-resources.md | 8 +- docs/core/extensions/scoped-service.md | 2 +- docs/core/extensions/service-discovery.md | 6 +- .../extensions/sslstream-best-practices.md | 8 +- docs/core/extensions/timer-service.md | 6 +- docs/core/extensions/windows-service.md | 4 +- .../work-with-resx-files-programmatically.md | 10 +- docs/core/extensions/workers.md | 6 +- docs/core/get-started.md | 2 +- .../porting/net-framework-tech-unavailable.md | 6 +- docs/core/resilience/http-resilience.md | 6 +- docs/core/runtime-config/index.md | 2 +- docs/core/runtime-config/threading.md | 6 +- .../testing/mstest-analyzers/mstest0038.md | 4 +- .../testing/mstest-analyzers/mstest0051.md | 2 +- .../testing/mstest-analyzers/mstest0055.md | 2 +- ...esting-mstest-writing-tests-data-driven.md | 8 +- docs/core/tools/dotnet-watch.md | 8 +- docs/core/tutorials/debug-console-app.md | 8 +- docs/core/tutorials/test-class-library.md | 2 +- .../cordebugblockingreason-enumeration.md | 2 +- ...frame3-getreturnvalueforiloffset-method.md | 2 +- ...agedcallback3-customnotification-method.md | 2 +- ...rgedassemblyrecord-getsimplename-method.md | 2 +- ...ess3-setenablecustomnotification-method.md | 2 +- .../icordebug/icordebugprocess6-interface.md | 2 +- ...bugprocess6-markdebuggerattached-method.md | 6 +- ...tadataimport-enummethodsemantics-method.md | 2 +- docs/core/whats-new/dotnet-10/libraries.md | 2 +- docs/core/whats-new/dotnet-11/libraries.md | 14 +- docs/core/whats-new/dotnet-6.md | 46 +- docs/core/whats-new/dotnet-7.md | 10 +- docs/core/whats-new/dotnet-8/runtime.md | 40 +- docs/core/whats-new/dotnet-8/sdk.md | 6 +- docs/core/whats-new/dotnet-9/libraries.md | 68 +- docs/core/whats-new/dotnet-9/overview.md | 6 +- docs/core/whats-new/dotnet-9/runtime.md | 2 +- docs/core/whats-new/dotnet-9/sdk.md | 2 +- docs/core/whats-new/dotnet-core-2-1.md | 22 +- docs/core/whats-new/dotnet-core-3-0.md | 2 +- .../expression-trees-building.md | 2 +- .../expression-trees-execution.md | 10 +- .../expression-trees-translating.md | 2 +- .../advanced-topics/expression-trees/index.md | 4 +- .../static-virtual-interface-members.md | 6 +- .../how-to-access-office-interop-objects.md | 6 +- ...d-properties-in-com-interop-programming.md | 6 +- ...ptional-arguments-in-office-programming.md | 10 +- ...ough-creating-and-using-dynamic-objects.md | 4 +- .../interop/walkthrough-office-programming.md | 4 +- .../advanced-topics/performance/index.md | 2 +- .../interpolated-string-handler.md | 4 +- .../generics-and-reflection.md | 44 +- ...-assembly-metadata-with-reflection-linq.md | 4 +- .../reflection-and-attributes/index.md | 4 +- .../async-return-types.md | 32 +- .../async-scenarios.md | 14 +- ...cancel-an-async-task-or-a-list-of-tasks.md | 2 +- ...ncel-async-tasks-after-a-period-of-time.md | 2 +- .../generate-consume-asynchronous-stream.md | 16 +- docs/csharp/asynchronous-programming/index.md | 10 +- ...tasks-and-process-them-as-they-complete.md | 16 +- .../task-asynchronous-programming-model.md | 28 +- .../using-async-for-file-access.md | 10 +- docs/csharp/delegates-strongly-typed.md | 6 +- docs/csharp/event-pattern.md | 2 +- .../coding-style/coding-conventions.md | 4 +- .../creating-and-throwing-exceptions.md | 8 +- ...w-to-execute-cleanup-code-using-finally.md | 6 +- ...-to-handle-an-exception-using-try-catch.md | 4 +- .../exceptions/using-exceptions.md | 4 +- .../fundamentals/functional/deconstruct.md | 2 +- .../functional/pattern-matching.md | 2 +- .../fundamentals/object-oriented/index.md | 56 +- .../object-oriented/inheritance.md | 10 +- .../fundamentals/object-oriented/objects.md | 8 +- docs/csharp/fundamentals/tutorials/classes.md | 2 +- .../fundamentals/tutorials/inheritance.md | 16 +- .../tutorials/system-command-line.md | 4 +- .../fundamentals/types/anonymous-types.md | 4 +- docs/csharp/fundamentals/types/enums.md | 6 +- docs/csharp/fundamentals/types/generics.md | 2 +- docs/csharp/fundamentals/types/interfaces.md | 6 +- docs/csharp/how-to/compare-strings.md | 12 +- .../how-to/concatenate-multiple-strings.md | 12 +- .../how-to-catch-a-non-cls-exception.md | 42 +- docs/csharp/how-to/modify-string-contents.md | 16 +- .../how-to/parse-strings-using-split.md | 8 +- docs/csharp/how-to/search-strings.md | 8 +- docs/csharp/iterators.md | 2 +- .../attributes/caller-information.md | 2 +- .../language-reference/attributes/general.md | 6 +- .../builtin-types/arrays.md | 4 +- .../builtin-types/collections.md | 20 +- .../builtin-types/default-values.md | 2 +- .../language-reference/builtin-types/enum.md | 6 +- .../builtin-types/nullable-reference-types.md | 2 +- .../builtin-types/nullable-value-types.md | 28 +- .../builtin-types/record.md | 10 +- .../builtin-types/ref-struct.md | 8 +- .../builtin-types/reference-types.md | 6 +- .../builtin-types/struct.md | 2 +- .../builtin-types/value-tuples.md | 2 +- .../array-declaration-errors.md | 4 +- .../compiler-messages/async-await-errors.md | 14 +- .../compiler-messages/cs0465.md | 48 +- .../expression-tree-restrictions.md | 2 +- .../compiler-messages/inline-array-errors.md | 4 +- .../compiler-messages/iterator-yield.md | 2 +- .../overloaded-operator-errors.md | 8 +- .../using-statement-declaration-errors.md | 4 +- .../compiler-options/code-generation.md | 2 +- .../compiler-options/language.md | 6 +- .../language-reference/keywords/async.md | 2 +- .../language-reference/keywords/event.md | 2 +- .../keywords/from-clause.md | 8 +- .../keywords/group-clause.md | 24 +- .../keywords/in-generic-modifier.md | 4 +- .../language-reference/keywords/interface.md | 2 +- .../language-reference/keywords/into.md | 6 +- .../keywords/join-clause.md | 6 +- .../keywords/method-parameters.md | 16 +- .../keywords/orderby-clause.md | 6 +- .../keywords/out-generic-modifier.md | 4 +- .../keywords/select-clause.md | 6 +- .../keywords/where-clause.md | 6 +- .../keywords/where-generic-type-constraint.md | 4 +- .../operators/arithmetic-operators.md | 8 +- .../language-reference/operators/await.md | 12 +- .../operators/collection-expressions.md | 34 +- .../operators/comparison-operators.md | 6 +- .../operators/delegate-operator.md | 2 +- .../operators/equality-operators.md | 14 +- .../operators/lambda-expressions.md | 14 +- .../operators/member-access-operators.md | 2 +- .../operators/null-coalescing-operator.md | 2 +- .../language-reference/operators/patterns.md | 8 +- .../language-reference/operators/sizeof.md | 6 +- .../operators/stackalloc.md | 10 +- .../operators/type-testing-and-cast.md | 8 +- .../statements/declarations.md | 6 +- .../exception-handling-statements.md | 4 +- .../language-reference/statements/fixed.md | 8 +- .../statements/iteration-statements.md | 10 +- .../statements/jump-statements.md | 2 +- .../language-reference/statements/yield.md | 6 +- .../language-reference/tokens/interpolated.md | 8 +- docs/csharp/language-reference/unsafe-code.md | 4 +- .../get-started/features-that-support-linq.md | 10 +- .../introduction-to-linq-queries.md | 122 +- .../get-started/query-expression-basics.md | 4 +- ...-relationships-in-linq-query-operations.md | 8 +- .../linq/get-started/write-linq-queries.md | 28 +- .../linq/how-to-build-dynamic-queries.md | 28 +- docs/csharp/linq/how-to-extend-linq.md | 16 +- docs/csharp/linq/how-to-query-collections.md | 8 +- .../how-to-query-files-and-directories.md | 12 +- docs/csharp/linq/how-to-query-strings.md | 6 +- docs/csharp/linq/includes/linq-syntax.md | 2 +- docs/csharp/linq/index.md | 28 +- .../converting-data-types.md | 22 +- .../filtering-data.md | 4 +- .../standard-query-operators/grouping-data.md | 8 +- .../linq/standard-query-operators/index.md | 28 +- .../join-operations.md | 30 +- .../partitioning-data.md | 10 +- .../projection-operations.md | 12 +- .../quantifier-operations.md | 8 +- .../set-operations.md | 22 +- .../standard-query-operators/sorting-data.md | 12 +- docs/csharp/methods.md | 4 +- docs/csharp/misc/cs0119.md | 42 +- docs/csharp/misc/cs0202.md | 138 +- docs/csharp/misc/cs0280.md | 90 +- docs/csharp/misc/cs1720.md | 54 +- docs/csharp/nullable-references.md | 6 +- .../classes-and-structs/constructors.md | 4 +- .../classes-and-structs/extension-methods.md | 6 +- .../classes-and-structs/finalizers.md | 4 +- ...ictionary-with-a-collection-initializer.md | 18 +- .../how-to-override-the-tostring-method.md | 56 +- .../classes-and-structs/methods.md | 6 +- .../named-and-optional-arguments.md | 2 +- .../object-and-collection-initializers.md | 8 +- .../static-constructors.md | 4 +- .../covariance-contravariance/index.md | 132 +- ...e-in-interfaces-for-generic-collections.md | 196 +-- .../variance-in-delegates.md | 364 +++--- .../variance-in-generic-interfaces.md | 24 +- .../programming-guide/concepts/iterators.md | 16 +- .../constraints-on-type-parameters.md | 4 +- .../generics/generic-classes.md | 104 +- .../generics/generic-interfaces.md | 8 +- .../generics/generic-methods.md | 70 +- .../generics/generics-and-arrays.md | 14 +- .../generics/generics-in-the-run-time.md | 10 +- .../equality-comparisons.md | 58 +- .../expression-bodied-members.md | 4 +- ...how-to-define-value-equality-for-a-type.md | 72 +- ...to-test-for-reference-equality-identity.md | 28 +- .../csharp/programming-guide/strings/index.md | 10 +- .../types/casting-and-type-conversions.md | 4 +- .../how-to-convert-a-string-to-a-number.md | 12 +- ...n-hexadecimal-strings-and-numeric-types.md | 78 +- .../get-started/semantic-analysis.md | 4 +- .../roslyn-sdk/get-started/syntax-analysis.md | 4 +- .../get-started/syntax-transformation.md | 6 +- .../how-to-write-csharp-analyzer-code-fix.md | 2 +- docs/csharp/roslyn-sdk/work-with-syntax.md | 14 +- .../tour-of-csharp/tutorials/hello-world.md | 16 +- .../tutorials/list-collection.md | 20 +- docs/csharp/tutorials/console-webapiclient.md | 12 +- docs/csharp/tutorials/ranges-indexes.md | 8 +- docs/csharp/tutorials/records.md | 4 +- docs/csharp/tutorials/string-interpolation.md | 6 +- docs/csharp/tutorials/top-level-statements.md | 2 +- docs/csharp/tutorials/working-with-linq.md | 20 +- docs/csharp/whats-new/csharp-12.md | 12 +- docs/csharp/whats-new/csharp-13.md | 6 +- .../whats-new/csharp-version-history.md | 4 +- docs/framework/64-bit-apps.md | 2 +- ...vicemodel.channels.message.bodytostring.md | 2 +- ...odel.channels.message.writestartheaders.md | 2 +- ...itingcancelled-event-system-windows-xps.md | 2 +- .../app-domains/application-domains.md | 16 +- .../how-to-configure-an-application-domain.md | 2 +- ...d-assemblies-into-an-application-domain.md | 14 +- ...ve-first-chance-exception-notifications.md | 6 +- .../how-to-unload-an-application-domain.md | 2 +- .../app-domains/shadow-copy-assemblies.md | 26 +- .../file-schema/compiler/compiler-element.md | 2 +- .../file-schema/compiler/compilers-element.md | 2 +- .../file-schema/compiler/index.md | 2 +- .../compiler/provideroption-element.md | 2 +- .../compiler/system-codedom-element.md | 6 +- .../cryptography/cryptoclass-element.md | 2 +- .../cryptography/cryptoclasses-element.md | 2 +- .../cryptographysettings-element.md | 2 +- .../cryptography/cryptonamemapping-element.md | 2 +- ...orlib-element-for-cryptography-settings.md | 4 +- .../cryptography/nameentry-element.md | 4 +- ...-authenticationmodules-network-settings.md | 2 +- ...r-connectionmanagement-network-settings.md | 2 +- ...element-for-schemesettings-uri-settings.md | 2 +- ...-for-webrequestmodules-network-settings.md | 4 +- ...element-for-schemesettings-uri-settings.md | 2 +- .../defaultproxy-element-network-settings.md | 2 +- .../httplistener-element-network-settings.md | 14 +- ...httpwebrequest-element-network-settings.md | 2 +- .../network/ipv6-element-network-settings.md | 4 +- .../module-element-network-settings.md | 2 +- .../network-element-network-settings.md | 6 +- .../network/proxy-element-network-settings.md | 2 +- ...element-for-schemesettings-uri-settings.md | 2 +- .../schemesettings-element-uri-settings.md | 2 +- .../socket-element-network-settings.md | 6 +- .../alwaysflowimpersonationpolicy-element.md | 6 +- .../appcontextswitchoverrides-element.md | 20 +- .../appdomainmanagerassembly-element.md | 8 +- .../runtime/appdomainmanagertype-element.md | 8 +- .../appdomainresourcemonitoring-element.md | 4 +- .../bypasstrustedappstrongnames-element.md | 2 +- .../runtime/compatsortnlsversion-element.md | 2 +- ...sablefusionupdatesfromadmanager-element.md | 6 +- .../enableampmparseadjustment-element.md | 12 +- .../file-schema/runtime/index.md | 2 +- .../legacyimpersonationpolicy-element.md | 2 +- .../runtime/loadfromremotesources-element.md | 6 +- .../memorycache-element-cache-settings.md | 4 +- .../namedcaches-element-cache-settings.md | 4 +- ...comparergethashcode-longstrings-element.md | 10 +- .../runtime/qualifyassembly-element.md | 2 +- .../file-schema/runtime/runtime-element.md | 4 +- .../throwunobservedtaskexceptions-element.md | 2 +- .../timespan-legacyformatmode-element.md | 2 +- ...serandomizedstringhashalgorithm-element.md | 10 +- .../add-element-for-listeners-for-source.md | 8 +- .../add-element-for-listeners-for-trace.md | 4 +- .../add-element-for-sharedlisteners.md | 2 +- .../file-schema/trace-debug/assert-element.md | 2 +- .../clear-element-for-listeners-for-trace.md | 6 +- ...lement-for-add-for-listeners-for-source.md | 2 +- ...element-for-add-for-listeners-for-trace.md | 2 +- ...ter-element-for-add-for-sharedlisteners.md | 2 +- .../file-schema/trace-debug/index.md | 58 +- .../listeners-element-for-source.md | 2 +- .../performancecounters-element.md | 2 +- ...remove-element-for-listeners-for-source.md | 4 +- .../remove-element-for-listeners-for-trace.md | 2 +- .../file-schema/trace-debug/source-element.md | 2 +- .../trace-debug/system-diagnostics-element.md | 2 +- .../file-schema/trace-debug/trace-element.md | 2 +- .../file-schema/wcf/add-of-allowaccounts.md | 4 +- .../wcf/add-of-allowedaudienceuris.md | 8 +- .../wcf/add-of-authorizationpolicies.md | 4 +- .../file-schema/wcf/add-of-baseaddresses.md | 2 +- .../add-of-claimtyperequirements-element.md | 4 +- .../wcf/add-of-claimtyperequirements.md | 4 +- .../file-schema/wcf/add-of-filters.md | 2 +- .../wcf/add-of-knowncertificates.md | 8 +- .../wcf/add-of-scopedcertificates-element.md | 4 +- .../file-schema/wcf/allowaccounts.md | 4 +- .../file-schema/wcf/allowedaudienceuris.md | 8 +- ...entication-of-clientcertificate-element.md | 4 +- ...ntication-of-servicecertificate-element.md | 2 +- .../file-schema/wcf/authorizationpolicies.md | 4 +- .../file-schema/wcf/baseaddresses.md | 2 +- .../wcf/bytestreammessageencoding.md | 2 +- .../file-schema/wcf/certificate-element.md | 4 +- .../wcf/certificate-for-identity.md | 2 +- ...ertificate-of-clientcertificate-element.md | 4 +- .../file-schema/wcf/certificate-of-peer.md | 4 +- .../wcf/certificatereference-for-identity.md | 2 +- .../file-schema/wcf/channelpoolsettings.md | 4 +- .../wcf/claimtyperequirements-element.md | 4 +- .../wcf/claimtyperequirements-for-message.md | 4 +- .../clear-of-claimtyperequirements-element.md | 4 +- ...ertificate-of-clientcredentials-element.md | 4 +- ...clientcertificate-of-servicecredentials.md | 4 +- .../configure-apps/file-schema/wcf/custom.md | 2 +- .../file-schema/wcf/custombinding.md | 2 +- .../file-schema/wcf/declaredtypes.md | 2 +- .../wcf/defaultcertificate-element.md | 2 +- .../file-schema/wcf/discoveryendpoint.md | 2 +- .../configure-apps/file-schema/wcf/dns.md | 2 +- .../configure-apps/file-schema/wcf/filters.md | 2 +- .../file-schema/wcf/headers-element.md | 4 +- .../configure-apps/file-schema/wcf/headers.md | 2 +- .../file-schema/wcf/httpdigest-element.md | 4 +- .../file-schema/wcf/identity.md | 2 +- ...kenauthentication-of-servicecredentials.md | 8 +- .../file-schema/wcf/knowncertificates.md | 8 +- .../wcf/localclientsettings-element.md | 4 +- .../file-schema/wcf/localissuer.md | 2 +- .../wcf/localservicesettings-element.md | 4 +- .../wcf/message-element-of-nettcpbinding.md | 4 +- ...-element-of-ws2007federationhttpbinding.md | 4 +- ...sage-element-of-wsfederationhttpbinding.md | 4 +- .../wcf/message-of-basichttpbinding.md | 4 +- .../wcf/message-of-netmsmqbinding.md | 4 +- .../wcf/message-of-ws2007httpbinding.md | 6 +- .../wcf/message-of-wsdualhttpbinding.md | 4 +- .../wcf/message-of-wshttpbinding.md | 4 +- .../file-schema/wcf/messagelogging.md | 2 +- .../messagesenderauthentication-element.md | 4 +- .../wcf/messagesenderauthentication.md | 4 +- .../file-schema/wcf/mexhttpbinding.md | 2 +- .../file-schema/wcf/mexhttpsbinding.md | 2 +- .../file-schema/wcf/mexnamedpipebinding.md | 2 +- .../file-schema/wcf/mextcpbinding.md | 2 +- .../file-schema/wcf/msmqintegrationbinding.md | 10 +- .../file-schema/wcf/netmsmqbinding.md | 10 +- .../file-schema/wcf/netnamedpipebinding.md | 2 +- .../file-schema/wcf/nettcpbinding.md | 2 +- .../file-schema/wcf/nettcpcontextbinding.md | 2 +- .../file-schema/wcf/parameter.md | 4 +- .../wcf/peer-of-clientcredentials-element.md | 4 +- .../wcf/peer-of-servicecredentials.md | 4 +- .../wcf/peerauthentication-element.md | 4 +- .../file-schema/wcf/peerauthentication.md | 4 +- ...remove-of-claimtyperequirements-element.md | 4 +- .../configure-apps/file-schema/wcf/rsa.md | 2 +- .../wcf/scopedcertificates-element.md | 4 +- ...tionauthentication-of-servicecredential.md | 4 +- .../wcf/secureconversationbootstrap.md | 2 +- ...-element-of-ws2007federationhttpbinding.md | 4 +- .../wcf/security-of-basichttpbinding.md | 4 +- .../wcf/security-of-msmqintegrationbinding.md | 4 +- .../wcf/security-of-nethttpbinding.md | 4 +- .../wcf/security-of-netmsmqbinding.md | 4 +- .../wcf/security-of-netnamedpipebinding.md | 4 +- .../wcf/security-of-netpeerbinding.md | 4 +- .../wcf/security-of-nettcpbinding.md | 4 +- .../wcf/security-of-webhttpbinding.md | 4 +- .../wcf/security-of-ws2007httpbinding.md | 4 +- .../security-of-wsfederationhttpbinding.md | 4 +- .../wcf/security-of-wshttpbinding.md | 4 +- ...ertificate-of-clientcredentials-element.md | 4 +- ...ervicecertificate-of-servicecredentials.md | 4 +- .../file-schema/wcf/servicemetadata.md | 6 +- .../file-schema/wcf/serviceprincipalname.md | 2 +- .../wcf/transport-of-basichttpbinding.md | 4 +- .../transport-of-msmqintegrationbinding.md | 4 +- .../wcf/transport-of-netmsmqbinding.md | 4 +- .../wcf/transport-of-netnamedpipebinding.md | 4 +- .../wcf/transport-of-netpeertcpbinding.md | 4 +- .../wcf/transport-of-nettcpbinding.md | 4 +- .../wcf/transport-of-peertransport.md | 2 +- .../wcf/transport-of-webhttpbinding.md | 4 +- .../wcf/transport-of-ws2007httpbinding.md | 4 +- .../wcf/transport-of-wshttpbinding.md | 4 +- .../file-schema/wcf/userprincipalname.md | 2 +- .../windows-of-clientcredentials-element.md | 4 +- ...owsauthentication-of-servicecredentials.md | 4 +- .../file-schema/wcf/ws2007httpbinding.md | 2 +- .../trackingprofile.md | 2 +- ...algorithm-names-to-cryptography-classes.md | 8 +- .../data/adonet/ado-net-code-examples.md | 2 +- .../data/adonet/asynchronous-programming.md | 42 +- .../data/adonet/commands-and-parameters.md | 42 +- .../comparing-datarows-linq-to-dataset.md | 54 +- ...ing-parameters-and-parameter-data-types.md | 6 +- .../data/adonet/connection-events.md | 2 +- .../data/adonet/connection-string-syntax.md | 2 +- ...nection-strings-and-configuration-files.md | 12 +- ...-datatable-from-a-query-linq-to-dataset.md | 112 +- ...ating-a-dataview-object-linq-to-dataset.md | 110 +- .../cross-table-queries-linq-to-dataset.md | 34 +- .../data/adonet/dataadapter-parameters.md | 6 +- .../acceptchanges-and-rejectchanges.md | 2 +- .../adding-a-datatable-to-a-dataset.md | 6 +- .../adding-columns-to-a-datatable.md | 2 +- .../adding-data-to-a-datatable.md | 2 +- .../adding-datarelations.md | 2 +- .../annotating-typed-datasets.md | 2 +- .../childviews-and-relations.md | 2 +- .../copying-dataset-contents.md | 8 +- .../creating-a-datareader.md | 38 +- .../creating-a-dataset.md | 30 +- .../creating-a-datatable-from-a-dataview.md | 6 +- .../creating-a-datatable.md | 2 +- .../creating-a-dataview.md | 2 +- .../creating-autoincrement-columns.md | 2 +- .../creating-expression-columns.md | 4 +- .../datarow-deletion.md | 4 +- .../datarows-and-datarowviews.md | 4 +- .../datatable-constraints.md | 2 +- .../datatable-edits.md | 2 +- .../datatable-schema-definition.md | 2 +- .../datatablereaders.md | 2 +- .../dataset-datatable-dataview/dataviews.md | 2 +- .../defining-primary-keys.md | 2 +- .../finding-rows.md | 2 +- .../generating-strongly-typed-datasets.md | 2 +- .../handling-dataset-events.md | 90 +- .../handling-datatable-events.md | 128 +- ...g-dataset-relational-structure-from-xml.md | 78 +- .../loading-a-dataset-from-xml.md | 6 +- .../merging-dataset-contents.md | 10 +- .../modifying-dataviews.md | 4 +- .../navigating-datatables.md | 2 +- .../row-error-information.md | 2 +- .../row-states-and-row-versions.md | 164 +-- .../sorting-and-filtering-data.md | 8 +- .../the-load-method.md | 2 +- .../viewing-data-in-a-datatable.md | 4 +- ...cific-operator-examples-linq-to-dataset.md | 58 +- .../data/adonet/dataview-performance.md | 144 +-- .../dbconnection-dbcommand-and-dbexception.md | 98 +- .../data/adonet/distributed-transactions.md | 2 +- ...lient-provider-for-the-entity-framework.md | 4 +- ...uery-that-returns-primitivetype-results.md | 2 +- ...te-a-query-that-returns-reftype-results.md | 2 +- ...ery-that-returns-structuraltype-results.md | 2 +- .../ef/language-reference/cast-entity-sql.md | 2 +- ...lr-method-to-canonical-function-mapping.md | 4 +- .../compiled-queries-linq-to-entities.md | 6 +- .../language-reference/entity-sql-language.md | 2 +- .../language-reference/entity-sql-overview.md | 2 +- .../how-to-call-canonical-functions.md | 36 +- .../how-to-call-custom-database-functions.md | 6 +- .../how-to-call-database-functions.md | 32 +- ...del-defined-functions-as-object-methods.md | 16 +- ...call-model-defined-functions-in-queries.md | 2 +- ...-and-considerations-in-linq-to-entities.md | 108 +- .../ef/language-reference/linq-to-entities.md | 168 +-- ...ery-syntax-examples-aggregate-operators.md | 220 ++-- ...-based-query-syntax-examples-conversion.md | 62 +- ...query-syntax-examples-element-operators.md | 30 +- ...d-based-query-syntax-examples-filtering.md | 94 +- ...ed-query-syntax-examples-join-operators.md | 66 +- ...yntax-examples-navigating-relationships.md | 4 +- ...od-based-query-syntax-examples-ordering.md | 46 +- ...ased-query-syntax-examples-partitioning.md | 66 +- ...-based-query-syntax-examples-projection.md | 66 +- .../ef/language-reference/null-comparisons.md | 68 +- .../queries-in-linq-to-entities.md | 116 +- .../ef/language-reference/query-execution.md | 154 +-- ...ion-syntax-examples-aggregate-operators.md | 144 +-- ...ssion-syntax-examples-element-operators.md | 30 +- ...ry-expression-syntax-examples-filtering.md | 94 +- ...pression-syntax-examples-join-operators.md | 60 +- ...yntax-examples-navigating-relationships.md | 2 +- ...ery-expression-syntax-examples-ordering.md | 88 +- ...expression-syntax-examples-partitioning.md | 46 +- ...y-expression-syntax-examples-projection.md | 86 +- .../ef/language-reference/query-results.md | 44 +- ...y-operators-in-linq-to-entities-queries.md | 148 +-- ...supported-linq-methods-linq-to-entities.md | 244 ++-- .../adonet/ef/migration-considerations.md | 6 +- .../adonet/ef/performance-considerations.md | 22 +- .../data/adonet/ef/security-considerations.md | 10 +- docs/framework/data/adonet/ef/terminology.md | 4 +- .../working-with-data-definition-language.md | 74 +- .../data/adonet/executing-a-command.md | 54 +- ...filtering-with-dataview-linq-to-dataset.md | 148 +-- ...enerating-commands-with-commandbuilders.md | 2 +- ...ld-and-setfield-methods-linq-to-dataset.md | 10 +- .../getschema-and-schema-collections.md | 2 +- ...opytodatatable-where-type-not-a-datarow.md | 6 +- .../data/adonet/linq-to-dataset-examples.md | 86 +- .../data/adonet/linq-to-dataset-overview.md | 40 +- .../data/adonet/local-transactions.md | 64 +- ...od-based-query-examples-linq-to-dataset.md | 56 +- ...ery-syntax-examples-aggregate-operators.md | 250 ++-- ...ry-syntax-examples-conversion-operators.md | 74 +- ...query-syntax-examples-element-operators.md | 46 +- ...ry-syntax-examples-join-linq-to-dataset.md | 56 +- ...yntax-examples-ordering-linq-to-dataset.md | 74 +- ...query-syntax-examples-partitioning-linq.md | 110 +- ...-based-query-syntax-examples-projection.md | 68 +- ...sed-query-syntax-examples-set-operators.md | 90 +- .../modifying-data-with-a-dbdataadapter.md | 56 +- .../adonet/obtaining-a-dbproviderfactory.md | 12 +- ...btaining-a-single-value-from-a-database.md | 2 +- .../data/adonet/oracle-data-type-mappings.md | 8 +- .../data/adonet/oracle-ref-cursors.md | 6 +- ...ing-batch-operations-using-dataadapters.md | 6 +- ...populating-a-dataset-from-a-dataadapter.md | 338 ++--- .../programming-guide-linq-to-dataset.md | 88 +- .../data/adonet/queries-in-linq-to-dataset.md | 88 +- ...ery-expression-examples-linq-to-dataset.md | 50 +- ...ion-syntax-examples-aggregate-operators.md | 156 +-- ...ssion-syntax-examples-element-operators.md | 58 +- ...pression-syntax-examples-join-operators.md | 72 +- ...yntax-examples-ordering-linq-to-dataset.md | 98 +- ...expression-syntax-examples-partitioning.md | 58 +- ...tax-examples-projection-linq-to-dataset.md | 88 +- ...ax-examples-restriction-linq-to-dataset.md | 70 +- ...he-datarowview-collection-in-a-dataview.md | 22 +- .../data/adonet/querying-typed-datasets.md | 2 +- .../retrieving-data-using-a-datareader.md | 4 +- .../retrieving-database-schema-information.md | 22 +- ...etrieving-identity-or-autonumber-values.md | 16 +- .../data/adonet/schema-restrictions.md | 2 +- .../data/adonet/side-by-side-execution.md | 4 +- .../single-table-queries-linq-to-dataset.md | 8 +- .../sorting-with-dataview-linq-to-dataset.md | 130 +- .../adonet/sql-server-connection-pooling.md | 6 +- .../adonet/sql-server-data-type-mappings.md | 86 +- .../sql/aspnet-apps-using-wait-handles.md | 10 +- .../adonet/sql/asynchronous-operations.md | 38 +- .../sql/database-mirroring-in-sql-server.md | 2 +- .../data/adonet/sql/date-and-time-data.md | 42 +- .../detecting-changes-with-sqldependency.md | 2 +- .../sql/enabling-query-notifications.md | 2 +- .../enumerating-instances-of-sql-server.md | 222 ++-- .../data/adonet/sql/handling-null-values.md | 250 ++-- docs/framework/data/adonet/sql/large-udts.md | 24 +- .../sql/linq/ado-net-and-linq-to-sql.md | 84 +- .../data/adonet/sql/linq/aggregate-queries.md | 80 +- .../sql/linq/attribute-based-mapping.md | 276 ++-- .../linq/communicating-with-the-database.md | 24 +- ...the-sum-of-values-in-a-numeric-sequence.md | 50 +- .../sql/linq/concatenate-two-sequences.md | 32 +- .../convert-a-sequence-to-a-generic-list.md | 16 +- .../linq/convert-a-sequence-to-an-array.md | 16 +- ...convert-a-type-to-a-generic-ienumerable.md | 20 +- ...nt-the-number-of-elements-in-a-sequence.md | 34 +- .../data/adonet/sql/linq/data-binding.md | 34 +- ...d-cud-operations-in-n-tier-applications.md | 18 +- .../linq/deferred-versus-immediate-loading.md | 38 +- ...ments-in-a-sequence-satisfy-a-condition.md | 6 +- ...nate-duplicate-elements-from-a-sequence.md | 16 +- ...the-maximum-value-in-a-numeric-sequence.md | 2 +- ...the-minimum-value-in-a-numeric-sequence.md | 2 +- .../sql/linq/group-elements-in-a-sequence.md | 12 +- .../sql/linq/how-to-connect-to-a-database.md | 46 +- ...trol-how-much-related-data-is-retrieved.md | 20 +- ...entity-classes-by-using-the-code-editor.md | 90 +- .../how-to-delete-rows-from-the-database.md | 2 +- .../how-to-directly-execute-sql-commands.md | 16 +- .../how-to-directly-execute-sql-queries.md | 4 +- .../sql/linq/how-to-display-a-changeset.md | 20 +- .../how-to-display-linq-to-sql-commands.md | 70 +- .../how-to-dynamically-create-a-database.md | 10 +- .../sql/linq/how-to-filter-related-data.md | 16 +- ...-object-model-in-visual-basic-or-csharp.md | 46 +- .../how-to-insert-rows-into-the-database.md | 2 +- .../linq/how-to-map-database-relationships.md | 12 +- .../how-to-map-inheritance-hierarchies.md | 70 +- ...w-to-represent-columns-as-class-members.md | 28 +- .../linq/how-to-represent-computed-columns.md | 24 +- .../how-to-represent-tables-as-classes.md | 28 +- ...ow-to-retrieve-information-as-read-only.md | 24 +- .../how-to-retrieve-many-objects-at-once.md | 16 +- ...to-retrieve-member-conflict-information.md | 20 +- ...o-specify-concurrency-conflict-checking.md | 16 +- .../how-to-specify-database-data-types.md | 24 +- .../sql/linq/how-to-specify-database-names.md | 24 +- .../how-to-specify-private-storage-fields.md | 20 +- ...-when-concurrency-exceptions-are-thrown.md | 34 +- .../how-to-submit-changes-to-the-database.md | 42 +- .../linq/how-to-turn-off-deferred-loading.md | 20 +- .../how-to-update-rows-in-the-database.md | 2 +- ...dures-mapped-for-multiple-result-shapes.md | 52 +- ...implementing-business-logic-linq-to-sql.md | 344 ++--- .../insert-update-and-delete-operations.md | 4 +- .../linq-to-sql-n-tier-with-web-services.md | 60 +- .../data/adonet/sql/linq/null-semantics.md | 18 +- .../linq/object-states-and-change-tracking.md | 32 +- .../linq/optimistic-concurrency-overview.md | 150 +-- .../data/adonet/sql/linq/query-examples.md | 132 +- .../adonet/sql/linq/querying-the-database.md | 70 +- .../sql/linq/remote-vs-local-execution.md | 68 +- ...eveloper-in-overriding-default-behavior.md | 32 +- ...rieving-objects-from-the-identity-cache.md | 102 +- .../return-or-skip-elements-in-a-sequence.md | 24 +- ...e-average-value-from-a-numeric-sequence.md | 2 +- .../return-the-first-element-in-a-sequence.md | 42 +- ...he-set-difference-between-two-sequences.md | 20 +- ...n-the-set-intersection-of-two-sequences.md | 20 +- .../return-the-set-union-of-two-sequences.md | 22 +- .../adonet/sql/linq/sequence-operators.md | 72 +- .../data/adonet/sql/linq/serialization.md | 2 +- .../sql/linq/sort-elements-in-a-sequence.md | 4 +- .../sql/linq/sql-clr-custom-type-mappings.md | 2 +- .../adonet/sql/linq/sql-clr-type-mapping.md | 32 +- .../standard-query-operator-translation.md | 56 +- .../adonet/sql/linq/system-convert-methods.md | 14 +- .../sql/linq/system-datetime-methods.md | 78 +- .../sql/linq/system-datetimeoffset-methods.md | 34 +- .../adonet/sql/linq/system-math-methods.md | 32 +- .../adonet/sql/linq/system-object-methods.md | 10 +- .../adonet/sql/linq/system-string-methods.md | 92 +- .../sql/linq/system-timespan-methods.md | 48 +- .../adonet/sql/linq/transaction-support.md | 32 +- .../data/adonet/sql/linq/troubleshooting.md | 10 +- .../sql/linq/unsupported-functionality.md | 32 +- .../walkthrough-manipulating-data-csharp.md | 320 ++--- ...kthrough-manipulating-data-visual-basic.md | 366 +++--- ...gh-querying-across-relationships-csharp.md | 168 +-- ...rying-across-relationships-visual-basic.md | 174 +-- ...gh-simple-object-model-and-query-csharp.md | 2 +- ...ple-object-model-and-query-visual-basic.md | 2 +- .../linq/what-you-can-do-with-linq-to-sql.md | 70 +- .../sql/modifying-large-value-max-data.md | 464 +++---- .../sql/provider-statistics-for-sql-server.md | 8 +- .../adonet/sql/single-bulk-copy-operations.md | 6 +- .../sql/snapshot-isolation-in-sql-server.md | 2 +- .../data/adonet/sql/sql-xml-column-values.md | 20 +- ...for-high-availability-disaster-recovery.md | 4 +- .../adonet/sql/table-valued-parameters.md | 514 ++++---- .../transaction-and-bulk-copy-operations.md | 2 +- .../windows-applications-using-callbacks.md | 4 +- .../adonet/sqlclient-streaming-support.md | 30 +- ...ransactions-integration-with-sql-server.md | 8 +- ...updating-data-sources-with-dataadapters.md | 4 +- docs/framework/data/adonet/whats-new.md | 2 +- ...saction-in-single-phase-and-multi-phase.md | 16 +- .../data/transactions/diagnostic-traces.md | 2 +- ...ources-as-participants-in-a-transaction.md | 22 +- .../implementing-a-resource-manager.md | 4 +- ...ransaction-using-committabletransaction.md | 146 +-- ...cit-transaction-using-transaction-scope.md | 232 ++-- ...nterprise-services-and-com-transactions.md | 136 +- ...g-concurrency-with-dependenttransaction.md | 128 +- .../optimization-spc-and-promotable-spn.md | 20 +- .../data/transactions/performing-recovery.md | 50 +- ...ity-trust-levels-in-accessing-resources.md | 8 +- .../asynchronousthreadabort-mda.md | 6 +- .../debug-trace-profile/bindingfailure-mda.md | 14 +- .../debug-trace-profile/code-contracts.md | 38 +- .../dangerousthreadingapi-mda.md | 10 +- .../datetimeinvalidlocalformat-mda.md | 8 +- .../enabling-jit-attach-debugging.md | 6 +- ...ng-with-the-debugger-display-attributes.md | 4 +- .../fatalexecutionengineerror-mda.md | 2 +- .../gcmanagedtounmanaged-mda.md | 4 +- ...dd-trace-statements-to-application-code.md | 16 +- ...o-create-and-initialize-trace-listeners.md | 4 +- ...-to-create-and-initialize-trace-sources.md | 2 +- ...initialize-and-configure-trace-switches.md | 2 +- ...source-and-filters-with-trace-listeners.md | 2 +- .../illegalprepareconstrainedregion-mda.md | 10 +- .../invalidapartmentstatechange-mda.md | 2 +- .../debug-trace-profile/invalidcercall-mda.md | 2 +- .../invalidgchandlecookie-mda.md | 2 +- .../invalidoverlappedtopinvoke-mda.md | 2 +- .../debug-trace-profile/loaderlock-mda.md | 2 +- .../loadfromcontext-mda.md | 10 +- .../moduloobjecthashcode-mda.md | 10 +- .../opengenericcercall-mda.md | 2 +- .../performance-counters.md | 10 +- .../raceonrcwcleanup-mda.md | 4 +- .../releasehandlefailed-mda.md | 20 +- .../reportavoncomrelease-mda.md | 4 +- .../streamwriterbuffereddatalost-mda.md | 8 +- .../debug-trace-profile/trace-listeners.md | 2 +- .../debug-trace-profile/trace-switches.md | 8 +- .../tracing-and-instrumenting-applications.md | 10 +- .../debug-trace-profile/virtualcercall-mda.md | 4 +- .../best-practices-for-assembly-loading.md | 54 +- .../how-the-runtime-locates-assemblies.md | 12 +- .../in-process-side-by-side-execution.md | 2 +- ...-determine-which-versions-are-installed.md | 4 +- .../install/versions-and-dependencies.md | 2 +- .../interop/default-marshalling-behavior.md | 2 +- .../default-marshalling-for-objects.md | 6 +- ...how-to-migrate-managed-code-dcom-to-wcf.md | 812 ++++++------ docs/framework/interop/interop-marshalling.md | 2 +- ...rshalling-classes-structures-and-unions.md | 8 +- ...-equivalence-and-embedded-interop-types.md | 10 +- ...filter-prefiltermessage-implementations.md | 10 +- ...alization-of-objects-across-app-domains.md | 2 +- .../mitigation-path-colon-checks.md | 42 +- .../mitigation-png-frames-in-icon-objects.md | 40 +- .../mitigation-product-versioning.md | 6 +- ...gation-serialization-control-characters.md | 4 +- ...services-and-certificate-authentication.md | 2 +- ...09certificateclaimset-findclaims-method.md | 48 +- ...ziparchiveentry-fullname-path-separator.md | 58 +- .../net-framework-4-migration-issues.md | 52 +- ...-net-peertopeer-collaboration-namespace.md | 60 +- .../basic-and-digest-authentication.md | 40 +- .../best-practices-for-system-net-classes.md | 2 +- ...che-management-for-network-applications.md | 52 +- .../network-programming/cache-policy.md | 2 +- .../certificate-selection-and-validation.md | 92 +- .../configuring-internet-applications.md | 2 +- docs/framework/network-programming/ftp.md | 4 +- ...how-to-list-directory-contents-with-ftp.md | 4 +- ...authentication-with-extended-protection.md | 284 ++--- .../internet-authentication.md | 12 +- .../network-programming/pnrp-clouds.md | 44 +- .../time-based-cache-policies.md | 2 +- .../constrained-execution-regions.md | 216 ++-- ...ents-in-task-parallel-library-and-plinq.md | 2 +- ...-perform-lazy-initialization-of-objects.md | 6 +- .../performance/lazy-initialization.md | 56 +- .../framework/performance/performance-tips.md | 46 +- .../performance/reliability-best-practices.md | 32 +- ...gramming-and-host-protection-attributes.md | 116 +- .../writing-large-responsive-apps.md | 20 +- ...piling-source-code-from-a-codedom-graph.md | 20 +- .../how-to-create-a-class-using-codedom.md | 16 +- ...an-xml-documentation-file-using-codedom.md | 6 +- ...mblies-into-the-reflection-only-context.md | 12 +- .../reflection-for-windows-store-apps.md | 4 +- .../security-considerations-for-reflection.md | 4 +- .../security-issues-in-reflection-emit.md | 8 +- ...mitting-code-in-partial-trust-scenarios.md | 12 +- .../framework/tools/al-exe-assembly-linker.md | 2 +- .../tools/installutil-exe-installer-tool.md | 10 +- docs/framework/tools/mgmtclassgen-exe.md | 4 +- .../tools/ngen-exe-native-image-generator.md | 10 +- .../regasm-exe-assembly-registration-tool.md | 2 +- ...xe-windows-runtime-metadata-export-tool.md | 68 +- ...inres-exe-windows-forms-resource-editor.md | 2 +- ...ntent-to-a-text-box-using-ui-automation.md | 2 +- .../caching-in-ui-automation-clients.md | 34 +- ...e-ui-automation-provider-implementation.md | 4 +- ...on-in-a-ui-automation-fragment-provider.md | 2 +- ...n-element-based-on-a-property-condition.md | 4 +- ...a-ui-automation-element-for-a-list-item.md | 2 +- ...upported-ui-automation-control-patterns.md | 6 +- ...tate-of-a-check-box-using-ui-automation.md | 2 +- .../get-ui-automation-element-properties.md | 4 +- ...ation-providers-in-a-client-application.md | 2 +- ...-the-ui-automation-dock-control-pattern.md | 4 +- ...tomation-expandcollapse-control-pattern.md | 14 +- ...-the-ui-automation-grid-control-pattern.md | 14 +- ...-ui-automation-griditem-control-pattern.md | 12 +- ...he-ui-automation-invoke-control-pattern.md | 6 +- ...automation-multipleview-control-pattern.md | 10 +- ...i-automation-rangevalue-control-pattern.md | 4 +- ...he-ui-automation-scroll-control-pattern.md | 28 +- ...i-automation-scrollitem-control-pattern.md | 4 +- ...ui-automation-selection-control-pattern.md | 6 +- ...utomation-selectionitem-control-pattern.md | 10 +- ...the-ui-automation-table-control-pattern.md | 6 +- ...ui-automation-tableitem-control-pattern.md | 4 +- ...he-ui-automation-toggle-control-pattern.md | 2 +- ...ui-automation-transform-control-pattern.md | 12 +- ...the-ui-automation-value-control-pattern.md | 10 +- ...he-ui-automation-window-control-pattern.md | 18 +- .../invoke-a-control-using-ui-automation.md | 4 +- ...-ui-automation-elements-with-treewalker.md | 4 +- ...t-attribute-details-using-ui-automation.md | 2 +- .../obtaining-ui-automation-elements.md | 18 +- ...se-events-from-a-ui-automation-provider.md | 2 +- ...e-ui-automation-provider-implementation.md | 28 +- .../subscribe-to-ui-automation-events.md | 8 +- ...ol-patterns-in-a-ui-automation-provider.md | 4 +- ...xtpattern-and-embedded-objects-overview.md | 52 +- .../traverse-text-using-ui-automation.md | 2 +- ...tion-and-microsoft-active-accessibility.md | 14 +- .../ui-automation-and-screen-scaling.md | 14 +- ...automation-control-patterns-for-clients.md | 6 +- ...ui-automation-control-patterns-overview.md | 2 +- .../ui-automation-control-types-overview.md | 2 +- .../ui-automation-events-for-clients.md | 20 +- .../ui-automation-events-overview.md | 6 +- .../ui-automation/ui-automation-overview.md | 2 +- .../ui-automation-properties-for-clients.md | 34 +- .../ui-automation-properties-overview.md | 72 +- ...ation-support-for-the-edit-control-type.md | 12 +- ...n-support-for-the-listitem-control-type.md | 2 +- ...upport-for-the-progressbar-control-type.md | 10 +- ...n-support-for-the-treeitem-control-type.md | 2 +- .../ui-automation-textpattern-overview.md | 8 +- .../ui-automation-threading-issues.md | 4 +- .../ui-automation-tree-overview.md | 2 +- .../use-caching-in-ui-automation.md | 24 +- .../use-the-automationid-property.md | 2 +- ...clr-debugging-process-flags-enumeration.md | 2 +- .../guid-managedname-attribute.md | 102 +- .../hosting/corbindtoruntime-function.md | 150 +-- .../hosting/corbindtoruntimeex-function.md | 232 ++-- .../einitializenewdomainflags-enumeration.md | 74 +- .../hosting/iappdomainsetup-interface.md | 78 +- ...ourcemonitor-getcurrentallocated-method.md | 92 +- ...esourcemonitor-getcurrentcputime-method.md | 90 +- ...sourcemonitor-getcurrentsurvived-method.md | 106 +- .../iclrappdomainresourcemonitor-interface.md | 10 +- ...nmanager-setappdomainmanagertype-method.md | 110 +- ...lrruntimehost-executeinappdomain-method.md | 104 +- ...untimehost-getcurrentappdomainid-method.md | 92 +- .../iclrruntimehost-unloadappdomain-method.md | 100 +- .../hosting/iclrtask-reset-method.md | 124 +- ...ostassemblystore-provideassembly-method.md | 128 +- ...curitymanager-setsecuritycontext-method.md | 104 +- .../hosting/ihosttask-alert-method.md | 82 +- .../hosting/ihosttask-setpriority-method.md | 132 +- ...ttaskmanager-beginthreadaffinity-method.md | 78 +- .../ihosttaskmanager-setlocale-method.md | 94 +- .../ihosttaskmanager-setuilocale-method.md | 94 +- .../hosting/ihosttaskmanager-sleep-method.md | 100 +- ...dpoolmanager-getavailablethreads-method.md | 96 +- ...tthreadpoolmanager-getmaxthreads-method.md | 100 +- ...tthreadpoolmanager-getminthreads-method.md | 96 +- ...eadpoolmanager-queueuserworkitem-method.md | 110 +- ...tthreadpoolmanager-setmaxthreads-method.md | 96 +- ...tthreadpoolmanager-setminthreads-method.md | 96 +- .../hosting/loadstringrcex-function.md | 124 +- .../hosting/startup-flags-enumeration.md | 2 +- .../clr-profilers-and-windows-store-apps.md | 2 +- .../cor-prf-gc-reason-enumeration.md | 68 +- .../cor-prf-module-flags-enumeration.md | 94 +- ...ck7-moduleinmemorysymbolsupdated-method.md | 76 +- ...icorprofilerinfo3-getmoduleinfo2-method.md | 2 +- .../accessing-services-using-a-wcf-client.md | 2 +- ...best-practices-data-contract-versioning.md | 164 +-- docs/framework/wcf/building-clients.md | 68 +- .../wcf/configuring-client-behaviors.md | 78 +- .../wcf/configuring-wcf-services-in-code.md | 4 +- ...e-consumption-and-improving-performance.md | 10 +- ...asic-profile-1-1-interoperable-services.md | 56 +- .../wcf/defining-and-specifying-faults.md | 124 +- .../wcf/designing-service-contracts.md | 4 +- .../dynamically-enabling-analytic-tracing.md | 62 +- ...ecurity-calls-not-authorized-per-second.md | 18 +- .../endpoint-security-calls-not-authorized.md | 8 +- .../performance-counters/instances.md | 24 +- ...ecurity-calls-not-authorized-per-second.md | 18 +- .../security-calls-not-authorized.md | 8 +- ...ecurity-calls-not-authorized-per-second.md | 18 +- .../service-security-calls-not-authorized.md | 8 +- .../wcf/diagnostics/tracing/activity.md | 2 +- ...spnetcompatibilityrequirementsattribute.md | 66 +- .../wcf/diagnostics/wmi/behavior-class.md | 62 +- .../wcf/endpoint-creation-overview.md | 10 +- ...c-provider-x509-certificate-private-key.md | 14 +- .../wcf/extending/channel-model-overview.md | 140 +- .../choosing-a-message-exchange-pattern.md | 170 +-- .../client-channel-factories-and-channels.md | 110 +- .../client-channel-level-programming.md | 78 +- .../configuration-and-metadata-support.md | 492 +++---- ...nd-extending-the-runtime-with-behaviors.md | 22 +- .../extending/creating-a-bindingelement.md | 132 +- .../creating-user-defined-bindings.md | 10 +- .../wcf/extending/custom-bindings.md | 2 +- .../wcf/extending/custom-encoders.md | 176 +-- .../extending/custom-message-formatters.md | 48 +- .../wcf/extending/custom-stream-upgrades.md | 22 +- .../wcf/extending/data-contract-surrogates.md | 390 +++--- ...ing-custom-metadata-for-a-wcf-extension.md | 68 +- .../wcf/extending/extending-clients.md | 40 +- .../wcf/extending/extending-dispatchers.md | 38 +- ...ending-hosting-using-servicehostfactory.md | 128 +- ...servicehost-and-the-service-model-layer.md | 44 +- .../wcf/extending/extensible-objects.md | 28 +- .../handling-exceptions-and-faults.md | 742 +++++------ .../wcf/extending/how-to-compare-claims.md | 12 +- ...e-a-custom-ws-metadata-exchange-binding.md | 198 +-- ...tom-authorization-manager-for-a-service.md | 10 +- ...to-create-a-custom-authorization-policy.md | 122 +- .../extending/how-to-create-a-custom-claim.md | 112 +- ...reate-a-custom-client-identity-verifier.md | 12 +- ...w-to-create-a-custom-principal-identity.md | 66 +- ...e-a-custom-security-token-authenticator.md | 80 +- .../extending/how-to-create-a-custom-token.md | 240 ++-- ...-employs-a-custom-certificate-validator.md | 224 ++-- ...-to-customize-a-system-provided-binding.md | 70 +- .../how-to-export-custom-policy-assertions.md | 70 +- .../how-to-import-custom-policy-assertions.md | 96 +- .../extending/how-to-import-custom-wsdl.md | 58 +- ...pect-and-modify-messages-on-the-service.md | 54 +- ...nspect-or-modify-messages-on-the-client.md | 220 ++-- .../how-to-inspect-or-modify-parameters.md | 54 +- ...o-lock-down-endpoints-in-the-enterprise.md | 2 +- ...certificates-for-signing-and-encryption.md | 12 +- ...ing-custom-metadata-for-a-wcf-extension.md | 80 +- ...trieving-metadata-over-a-custom-binding.md | 40 +- .../service-channel-level-programming.md | 102 +- .../service-channel-listeners-and-channels.md | 4 +- .../extending/understanding-state-changes.md | 322 ++--- ...g-custom-client-and-service-credentials.md | 30 +- .../accessing-services-using-a-client.md | 166 +-- ...ervices-with-a-windows-store-client-app.md | 308 ++--- .../anticipating-adopting-wcf-migration.md | 224 ++-- .../architecture-of-syndication.md | 134 +- .../auditing-security-events.md | 190 +-- .../feature-details/authentication-in-wcf.md | 2 +- ...best-practices-for-queued-communication.md | 158 +-- .../best-practices-for-reliable-sessions.md | 8 +- .../best-practices-for-security-in-wcf.md | 82 +- ...ching-support-for-wcf-web-http-services.md | 10 +- ...a-rest-style-service-from-a-wcf-service.md | 2 +- ...rt-val-diff-https-ssl-over-tcp-and-soap.md | 64 +- ...ache-sharing-levels-for-send-activities.md | 296 ++--- .../channel-factory-and-caching.md | 18 +- .../wcf/feature-details/choosing-a-filter.md | 2 +- .../choosing-a-message-encoder.md | 84 +- .../claim-creation-and-resource-values.md | 62 +- .../claims-and-denying-access-to-resources.md | 10 +- .../wcf/feature-details/claims-and-tokens.md | 22 +- .../feature-details/client-architecture.md | 18 +- .../feature-details/client-configuration.md | 156 +-- .../collection-types-in-data-contracts.md | 60 +- ...eb-services-to-wcf-based-on-development.md | 6 +- ...ng-transactions-in-com-and-servicemodel.md | 22 +- ...fig-wcf-service-with-aspnet-web-service.md | 64 +- ...uration-based-activation-in-iis-and-was.md | 2 +- ...uring-discovery-in-a-configuration-file.md | 2 +- ...ing-serialization-in-a-workflow-service.md | 2 +- .../configuring-system-provided-bindings.md | 128 +- .../context-exchange-protocol.md | 114 +- ...eate-a-service-arbitrary-data-using-wcf.md | 368 +++--- ...eating-wcf-ajax-services-without-aspnet.md | 188 +-- .../creating-wcf-services-for-aspnet-ajax.md | 2 +- .../data-contract-equivalence.md | 88 +- .../data-contract-known-types.md | 292 ++--- .../feature-details/data-contract-names.md | 14 +- .../data-contract-schema-reference.md | 4 +- .../data-contract-versioning.md | 214 ++-- .../wcf/feature-details/data-member-order.md | 94 +- .../data-transfer-architectural-overview.md | 6 +- ...debugging-windows-authentication-errors.md | 256 ++-- .../delegation-and-impersonation-with-wcf.md | 376 +++--- .../wcf/feature-details/denial-of-service.md | 154 +-- .../discovery-find-and-findcriteria.md | 8 +- .../discoveryclient-and-dynamicendpoint.md | 176 +-- .../distributed-application-security.md | 4 +- .../wcf/feature-details/duplex-services.md | 2 +- .../durable-duplex-correlation.md | 4 +- .../feature-details/elevation-of-privilege.md | 150 +-- .../encryption-of-digital-signatures.md | 30 +- .../wcf/feature-details/endpoint-addresses.md | 262 ++-- ...points-addresses-bindings-and-contracts.md | 6 +- .../enumeration-types-in-data-contracts.md | 166 +-- .../exporting-and-importing-metadata.md | 6 +- .../exporting-schemas-from-classes.md | 90 +- .../feature-details/federation-and-trust.md | 56 +- .../wcf/feature-details/filtering.md | 168 +-- .../finding-claims-in-a-claimset.md | 14 +- ...tions-into-and-out-of-workflow-services.md | 582 ++++----- .../forward-compatible-data-contracts.md | 52 +- ...osting-in-a-windows-service-application.md | 50 +- .../hosting-workflow-services.md | 2 +- ...ess-a-wse-3-0-service-with-a-wcf-client.md | 86 +- ...ax-endpoint-without-using-configuration.md | 164 +-- ...low-metadata-requests-while-authorizing.md | 44 +- .../how-to-audit-wcf-security-events.md | 136 +- ...henticate-with-a-user-name-and-password.md | 4 +- ...-asynchronously-using-a-channel-factory.md | 4 +- ...l-wcf-service-operations-asynchronously.md | 4 +- .../how-to-configure-a-local-issuer.md | 10 +- ...nt-to-interoperate-with-wse3-0-services.md | 86 +- ...igure-a-wcf-service-to-use-port-sharing.md | 86 +- ...ure-credentials-on-a-federation-service.md | 24 +- ...-idle-behavior-with-workflowservicehost.md | 2 +- ...es-to-interoperate-with-wse-3-0-clients.md | 6 +- .../how-to-control-service-instancing.md | 34 +- ...-to-create-a-basic-wcf-web-http-service.md | 4 +- ...nd-use-it-to-create-and-manage-channels.md | 16 +- ...inding-using-the-securitybindingelement.md | 190 +-- .../how-to-create-a-duplex-contract.md | 100 +- .../how-to-create-a-federated-client.md | 24 +- ...rity-context-token-for-a-secure-session.md | 184 +-- ...ent-for-a-specified-authentication-mode.md | 24 +- ...ow-to-create-a-service-endpoint-in-code.md | 58 +- ...create-a-service-that-requires-sessions.md | 46 +- .../how-to-create-a-supporting-credential.md | 150 +-- .../how-to-create-a-transactional-service.md | 394 +++--- ...how-to-create-a-wsfederationhttpbinding.md | 6 +- ...he-discovery-version-of-a-probe-request.md | 4 +- ...isable-encryption-of-digital-signatures.md | 28 +- .../feature-details/how-to-dynamic-update.md | 6 +- .../how-to-enable-message-replay-detection.md | 168 +-- ...-export-metadata-from-service-endpoints.md | 76 +- ...pose-a-contract-to-soap-and-web-clients.md | 4 +- ...cf-service-in-a-managed-windows-service.md | 2 +- .../how-to-implement-a-discovery-proxy.md | 18 +- ...-import-metadata-into-service-endpoints.md | 52 +- ...ajax-enabled-aspnet-web-services-to-wcf.md | 2 +- ...overability-to-a-wcf-service-and-client.md | 4 +- ...blish-metadata-for-a-service-using-code.md | 122 +- ...adata-and-implement-a-compliant-service.md | 86 +- ...etrieve-the-thumbprint-of-a-certificate.md | 56 +- ...ure-a-service-with-an-x-509-certificate.md | 124 +- .../how-to-secure-metadata-endpoints.md | 10 +- ...-to-serialize-and-deserialize-json-data.md | 4 +- .../how-to-set-a-max-clock-skew.md | 134 +- .../how-to-set-up-a-signature-confirmation.md | 6 +- ...guration-to-add-an-aspnet-ajax-endpoint.md | 162 +-- ...dataexchangeclient-to-retrieve-metadata.md | 52 +- ...ltiple-security-tokens-of-the-same-type.md | 78 +- ...util-exe-to-download-metadata-documents.md | 4 +- ...the-aspnet-role-provider-with-a-service.md | 2 +- .../how-to-use-the-channelfactory.md | 26 +- ...nsport-security-and-message-credentials.md | 32 +- ...-view-certificates-with-the-mmc-snap-in.md | 32 +- ...-get-requests-for-aspnet-ajax-endpoints.md | 136 +- .../importing-schema-to-generate-classes.md | 328 ++--- .../feature-details/information-disclosure.md | 2 +- ...prise-services-transactional-components.md | 150 +-- ...ing-with-com-plus-applications-overview.md | 2 +- .../interoperability-with-pox-applications.md | 14 +- .../interoperable-object-references.md | 112 +- .../large-data-and-streaming.md | 4 +- .../limiting-message-distribution.md | 2 +- ...d-authorization-with-the-identity-model.md | 12 +- .../wcf/feature-details/message-filters.md | 256 ++-- ...s-client-without-credential-negotiation.md | 2 +- .../feature-details/messaging-activities.md | 6 +- .../metadata-architecture-overview.md | 16 +- .../middle-tier-client-applications.md | 6 +- .../migrating-wse-3-0-web-services-to-wcf.md | 2 +- .../feature-details/net-tcp-port-sharing.md | 82 +- .../wcf/feature-details/one-way-services.md | 82 +- ...-of-messages-in-single-concurrency-mode.md | 28 +- .../out-of-order-message-processing.md | 50 +- .../partial-trust-best-practices.md | 8 +- .../partial-trust-feature-compatibility.md | 4 +- ...n-a-wcf-service-is-hosted-in-a-web-farm.md | 10 +- .../programming-wcf-security.md | 172 +-- .../feature-details/publishing-metadata.md | 4 +- .../wcf/feature-details/queuing-in-wcf.md | 246 ++-- .../reliable-sessions-overview.md | 4 +- .../request-reply-correlation.md | 180 +-- .../feature-details/retrieving-metadata.md | 2 +- .../feature-details/routing-introduction.md | 12 +- .../wcf/feature-details/routing-service.md | 2 +- .../feature-details/saml-tokens-and-claims.md | 52 +- ...ecure-conversations-and-secure-sessions.md | 12 +- ...ecuring-messages-using-message-security.md | 108 +- ...uring-messages-using-transport-security.md | 180 +-- .../securing-peer-channel-applications.md | 76 +- .../security-considerations-for-data.md | 44 +- ...rity-considerations-for-secure-sessions.md | 24 +- .../security-considerations-with-metadata.md | 4 +- .../security-negotiation-and-timeouts.md | 4 +- .../security-protocols-version-1-0.md | 2 +- .../wcf/feature-details/security-protocols.md | 2 +- ...ritybindingelement-authentication-modes.md | 38 +- .../selecting-a-credential-type.md | 212 +-- .../wcf/feature-details/serializable-types.md | 60 +- .../serialization-and-deserialization.md | 492 +++---- .../service-identity-and-authentication.md | 4 +- ...ibutes-and-servicedescription-reference.md | 208 +-- .../servicemodel-transaction-attributes.md | 12 +- .../servicemodel-transaction-configuration.md | 104 +- .../sessions-instancing-and-concurrency.md | 190 +-- ...-side-versioning-in-workflowservicehost.md | 296 ++--- ...e-authority-chain-verify-signatures-wcf.md | 40 +- ...ying-data-transfer-in-service-contracts.md | 1136 ++++++++--------- .../stand-alone-json-serialization.md | 10 +- .../wcf/feature-details/standard-endpoints.md | 8 +- ...nt-applications-using-the-xmlserializer.md | 4 +- .../streaming-message-transfer.md | 2 +- .../syndication-extensibility.md | 72 +- .../wcf/feature-details/tampering.md | 18 +- .../transport-security-overview.md | 10 +- ...port-security-with-basic-authentication.md | 188 +-- .../troubleshooting-correlation.md | 8 +- .../troubleshooting-queued-messaging.md | 14 +- ...pported-by-the-data-contract-serializer.md | 10 +- .../understanding-generated-client-code.md | 142 +-- .../feature-details/unsupported-scenarios.md | 8 +- .../uritemplate-and-uritemplatetable.md | 576 ++++----- ...nding-with-the-discovery-client-channel.md | 62 +- .../using-a-data-contract-resolver.md | 150 +-- .../using-contracts-in-workflow.md | 44 +- ...ues-to-handle-message-transfer-failures.md | 114 +- .../using-message-contracts.md | 892 ++++++------- ...vior-to-control-wcf-service-performance.md | 10 +- .../using-the-discovery-client-channel.md | 94 +- .../using-the-message-class.md | 56 +- .../using-the-xmlserializer-class.md | 14 +- .../wcf-and-internationalized-domain-names.md | 60 +- .../wcf/feature-details/wcf-and-websockets.md | 22 +- .../wcf-discovery-object-model.md | 14 +- .../feature-details/wcf-discovery-overview.md | 182 +-- .../wcf-services-and-aspnet.md | 4 +- .../wcf-web-http-error-handling.md | 64 +- .../wcf-web-http-formatting.md | 288 ++--- ...wcf-web-http-programming-model-overview.md | 2 +- .../wcf-web-http-service-help-page.md | 458 +++---- .../workflow-service-host-extensibility.md | 6 +- .../workflow-service-host-internals.md | 76 +- .../workflow-services-overview.md | 10 +- .../working-with-certificates.md | 18 +- ...xml-and-ado-net-types-in-data-contracts.md | 398 +++--- ...-to-declare-faults-in-service-contracts.md | 4 +- .../how-to-examine-the-security-context.md | 80 +- ...-a-wcf-service-in-a-managed-application.md | 8 +- ...how-to-host-and-run-a-basic-wcf-service.md | 2 +- ...ow-to-impersonate-a-client-on-a-service.md | 52 +- ...ement-an-asynchronous-service-operation.md | 62 +- ...-the-principalpermissionattribute-class.md | 134 +- ...cure-a-service-with-windows-credentials.md | 12 +- .../wcf/how-to-set-the-security-mode.md | 2 +- ...how-to-specify-client-credential-values.md | 6 +- ...w-to-specify-the-client-credential-type.md | 84 +- docs/framework/wcf/load-balancing.md | 162 +-- docs/framework/wcf/privacy-information.md | 8 +- .../wcf/samples/authorization-policy.md | 4 +- .../wcf/samples/basic-http-service.md | 6 +- docs/framework/wcf/samples/channel-factory.md | 2 +- .../samples/configuration-channel-factory.md | 8 +- .../wcf/samples/configuration-sample.md | 2 +- .../wcf/samples/custom-channel-dispatcher.md | 4 +- .../wcf/samples/custom-find-criteria.md | 4 +- docs/framework/wcf/samples/custom-lifetime.md | 26 +- ...tom-message-encoder-compression-encoder.md | 6 +- ...tom-message-encoder-custom-text-encoder.md | 4 +- .../wcf/samples/custom-message-filter.md | 8 +- .../wcf/samples/datacontractresolver.md | 2 +- .../samples/datacontractserializer-sample.md | 2 +- .../wcf/samples/dead-letter-queues.md | 8 +- .../wcf/samples/default-service-behavior.md | 16 +- .../samples/discovery-with-scopes-sample.md | 2 +- .../wcf/samples/dispatch-by-body-element.md | 10 +- .../samples/durable-issued-token-provider.md | 2 +- ...ntrol-over-error-handling-and-reporting.md | 6 +- docs/framework/wcf/samples/fault-contract.md | 4 +- .../wcf/samples/httpcookiesession.md | 4 +- .../wcf/samples/instancing-initialization.md | 12 +- .../loosely-typed-extensions-sample.md | 6 +- .../wcf/samples/message-correlation.md | 2 +- .../wcf/samples/message-inspectors.md | 18 +- .../wcf/samples/message-queuing-to-wcf.md | 4 +- .../wcf/samples/message-security-anonymous.md | 2 +- .../wcf/samples/message-security-windows.md | 2 +- .../samples/metadata-publishing-behavior.md | 2 +- .../samples/net-tcp-port-sharing-sample.md | 2 +- docs/framework/wcf/samples/one-way.md | 2 +- ...ration-formatter-and-operation-selector.md | 12 +- .../wcf/samples/operationcontextscope.md | 6 +- .../poison-message-handling-in-msmq-4-0.md | 2 +- docs/framework/wcf/samples/pooling.md | 14 +- .../wcf/samples/saml-token-provider.md | 2 +- .../wcf/samples/service-description.md | 2 +- docs/framework/wcf/samples/services.md | 2 +- .../wcf/samples/sessions-and-queues.md | 8 +- .../setting-the-use-and-style-properties.md | 4 +- .../strongly-typed-extensions-sample.md | 8 +- .../wcf/samples/token-authenticator.md | 2 +- docs/framework/wcf/samples/token-provider.md | 2 +- .../wcf/samples/transacted-msmq-binding.md | 6 +- docs/framework/wcf/samples/transport-udp.md | 8 +- .../wcf/samples/two-way-communication.md | 4 +- .../wcf/samples/uritemplate-sample.md | 4 +- .../uritemplate-table-dispatcher-sample.md | 2 +- .../wcf/samples/uritemplate-table-sample.md | 2 +- .../samples/volatile-queued-communication.md | 4 +- .../weakly-typed-json-serialization-sample.md | 2 +- .../wcf/samples/ws-transaction-flow.md | 4 +- .../wcf/samples/wsstreamedhttpbinding.md | 2 +- .../framework/wcf/samples/xmlreader-sample.md | 2 +- .../wcf/samples/xmlserializer-faults.md | 4 +- docs/framework/wcf/securing-clients.md | 230 ++-- docs/framework/wcf/securing-services.md | 2 +- .../wcf/sending-and-receiving-faults.md | 32 +- docs/framework/wcf/service-versioning.md | 370 +++--- .../wcf/services-and-transactions.md | 130 +- .../wcf/specifying-an-endpoint-address.md | 14 +- ...ndling-faults-in-contracts-and-services.md | 14 +- .../specifying-client-run-time-behavior.md | 8 +- .../specifying-service-run-time-behavior.md | 10 +- ...synchronous-and-asynchronous-operations.md | 8 +- docs/framework/wcf/using-sessions.md | 18 +- docs/framework/wcf/wcf-client-overview.md | 14 +- docs/framework/wcf/wcf-error-handling.md | 76 +- .../wcf/wcf-simplification-features.md | 20 +- .../wcf/wcf-troubleshooting-quickstart.md | 418 +++--- docs/framework/wcf/whats-new.md | 14 +- docs/framework/whats-new/index.md | 154 +-- docs/framework/whats-new/obsolete-members.md | 752 +++++------ docs/framework/whats-new/obsolete-types.md | 20 +- .../whats-new/whats-new-in-accessibility.md | 8 +- ...-installers-to-your-service-application.md | 78 +- ...continue-a-windows-service-visual-basic.md | 76 +- .../how-to-create-windows-services.md | 98 +- ...w-to-debug-windows-service-applications.md | 184 +-- .../how-to-log-information-about-services.md | 22 +- ...to-pause-a-windows-service-visual-basic.md | 74 +- ...ecify-the-security-context-for-services.md | 50 +- .../windows-services/how-to-start-services.md | 4 +- .../how-to-write-services-programmatically.md | 6 +- ...duction-to-windows-service-applications.md | 112 +- ...ce-application-programming-architecture.md | 22 +- ...ubleshooting-debugging-windows-services.md | 10 +- ...ooting-service-application-wont-install.md | 14 +- ...e-application-in-the-component-designer.md | 16 +- .../activity-authoring-options-in-wf.md | 10 +- ...ivity-definition-scoping-and-visibility.md | 128 +- .../activity-tree-inspection.md | 68 +- .../architecture.md | 80 +- ...s-and-expressions-using-imperative-code.md | 30 +- ...activity-property-to-a-designer-control.md | 8 +- .../windows-workflow-foundation/bookmarks.md | 212 +-- .../collection-activities-in-wf.md | 818 ++++++------ .../compensation.md | 16 +- .../configuring-tracking-for-a-workflow.md | 2 +- .../consuming-odata-feeds-from-a-workflow.md | 24 +- ...ract-first-workflow-service-development.md | 8 +- .../control-flow-activities-in-wf.md | 34 +- ...ctivity-at-runtime-with-dynamicactivity.md | 4 +- .../creating-asynchronous-activities-in-wf.md | 86 +- ...creating-custom-flow-control-activities.md | 44 +- .../csharp-expressions.md | 4 +- .../custom-tracking-records.md | 2 +- .../declarative-constraints.md | 302 ++--- .../dynamic-update.md | 10 +- .../windows-workflow-foundation/exceptions.md | 6 +- .../exposing-data-with-cachemetadata.md | 16 +- .../expressions.md | 4 +- .../feature-specifics.md | 20 +- .../flowchart-activities-in-wf.md | 16 +- .../flowchart-workflows.md | 8 +- .../getting-started-tutorial.md | 52 +- ...ow-to-create-a-custom-activity-designer.md | 2 +- ...ow-to-create-a-custom-activity-template.md | 2 +- .../how-to-create-a-custom-instance-store.md | 14 +- ...create-a-custom-persistence-participant.md | 60 +- .../how-to-create-a-sequential-workflow.md | 2 +- .../how-to-create-a-state-machine-workflow.md | 320 ++--- .../how-to-create-an-activity.md | 4 +- ...to-deserialize-instance-data-properties.md | 2 +- ...alidation-errors-in-a-rehosted-designer.md | 64 +- ...nce-for-workflows-and-workflow-services.md | 2 +- ...nce-for-workflows-and-workflow-services.md | 8 +- .../how-to-run-a-workflow.md | 6 +- .../imperative-code-based-validation.md | 8 +- .../instance-locked-exception-action.md | 28 +- .../instance-stores.md | 36 +- .../invoking-activity-validation.md | 18 +- ...ling-cancellation-behavior-in-workflows.md | 174 +-- .../nativeactivity-base-class.md | 24 +- ...ework-3-0-wf-in-net-framework-4-interop.md | 4 +- .../windows-workflow-foundation/overview.md | 6 +- .../pausing-and-resuming-a-workflow.md | 4 +- .../performance.md | 6 +- .../persistence-best-practices.md | 160 +-- .../persistence-participants.md | 100 +- .../pick-activity.md | 4 +- .../procedural-workflows.md | 52 +- .../properties-vs-arguments.md | 20 +- .../required-arguments-and-overload-groups.md | 2 +- .../samples/accessing-operationcontext.md | 4 +- .../samples/activity-library.md | 40 +- .../samples/corporate-purchase-process.md | 14 +- ...reating-and-running-a-workflow-instance.md | 2 +- .../custom-composite-using-native-activity.md | 10 +- .../samples/custom-tracking.md | 4 +- .../samples/database-access-activities.md | 14 +- .../samples/designer-rehosting.md | 2 +- ...-in-a-flowchart-activity-using-trycatch.md | 2 +- .../samples/get-workflowinstanceid.md | 2 +- .../samples/hiring-process.md | 4 +- .../samples/load-from-xaml.md | 2 +- .../samples/non-generic-foreach.md | 10 +- .../samples/non-generic-parallelforeach.md | 14 +- .../samples/property-grid-extensibility.md | 6 +- .../samples/sendmail-custom-activity.md | 18 +- .../samples/throttled-parallel-foreach.md | 2 +- .../samples/using-editing-scope.md | 8 +- .../samples/wpf-and-wf-integration-in-xaml.md | 6 +- ...rkflows-and-activities-to-and-from-xaml.md | 12 +- .../state-machine-workflows.md | 184 +-- .../store-extensibility.md | 2 +- .../tracking-participants.md | 4 +- .../tracking-records.md | 102 +- .../using-a-custom-activity.md | 2 +- .../using-a-custom-expression-editor.md | 540 ++++---- .../using-activity-delegates.md | 14 +- .../using-the-modelitem-editing-context.md | 274 ++-- .../using-workflowidentity-and-versioning.md | 8 +- ...workflowinvoker-and-workflowapplication.md | 176 +-- .../variables-and-arguments.md | 18 +- ...tures-in-the-rehosted-workflow-designer.md | 4 +- .../whats-new-in-wf-in-dotnet.md | 12 +- .../windows-workflow-foundation/whats-new.md | 6 +- ...-authoring-using-the-codeactivity-class.md | 10 +- .../workflow-execution-properties.md | 294 ++--- .../workflow-transactions.md | 6 +- docs/fsharp/language-reference/assertions.md | 2 +- .../language-reference/async-expressions.md | 4 +- docs/fsharp/language-reference/byrefs.md | 2 +- .../computation-expressions.md | 4 +- .../functions/external-functions.md | 2 +- .../interpolated-strings.md | 2 +- .../nullable-value-types.md | 2 +- .../language-reference/query-expressions.md | 2 +- docs/fsharp/language-reference/sequences.md | 4 +- docs/fsharp/language-reference/slices.md | 4 +- .../arithmetic-operators.md | 14 +- .../language-reference/task-expressions.md | 12 +- .../language-reference/type-extensions.md | 6 +- docs/fsharp/tutorials/async.md | 12 +- docs/fsharp/whats-new/fsharp-45.md | 2 +- ...fix-binaryformatter-serializationbinder.md | 2 +- docs/fundamentals/code-analysis/overview.md | 6 +- .../code-analysis/quality-rules/ca1001.md | 2 +- .../code-analysis/quality-rules/ca1002.md | 16 +- .../code-analysis/quality-rules/ca1003.md | 8 +- .../code-analysis/quality-rules/ca1010.md | 20 +- .../code-analysis/quality-rules/ca1021.md | 2 +- .../code-analysis/quality-rules/ca1033.md | 2 +- .../code-analysis/quality-rules/ca1036.md | 12 +- .../code-analysis/quality-rules/ca1041.md | 6 +- .../code-analysis/quality-rules/ca1046.md | 2 +- .../code-analysis/quality-rules/ca1047.md | 2 +- .../code-analysis/quality-rules/ca1063.md | 2 +- .../code-analysis/quality-rules/ca1065.md | 12 +- .../code-analysis/quality-rules/ca1066.md | 8 +- .../code-analysis/quality-rules/ca1067.md | 8 +- .../code-analysis/quality-rules/ca1303.md | 2 +- .../code-analysis/quality-rules/ca1304.md | 8 +- .../code-analysis/quality-rules/ca1305.md | 12 +- .../code-analysis/quality-rules/ca1309.md | 2 +- .../code-analysis/quality-rules/ca1416.md | 4 +- .../code-analysis/quality-rules/ca1510.md | 4 +- .../code-analysis/quality-rules/ca1512.md | 20 +- .../code-analysis/quality-rules/ca1513.md | 4 +- .../code-analysis/quality-rules/ca1514.md | 2 +- .../code-analysis/quality-rules/ca1700.md | 2 +- .../code-analysis/quality-rules/ca1710.md | 8 +- .../code-analysis/quality-rules/ca1711.md | 4 +- .../code-analysis/quality-rules/ca1801.md | 2 +- .../code-analysis/quality-rules/ca1806.md | 6 +- .../code-analysis/quality-rules/ca1812.md | 2 +- .../code-analysis/quality-rules/ca1813.md | 2 +- .../code-analysis/quality-rules/ca1815.md | 10 +- .../code-analysis/quality-rules/ca1816.md | 22 +- .../code-analysis/quality-rules/ca1819.md | 4 +- .../code-analysis/quality-rules/ca1820.md | 8 +- .../code-analysis/quality-rules/ca1825.md | 4 +- .../code-analysis/quality-rules/ca1826.md | 14 +- .../code-analysis/quality-rules/ca1827.md | 2 +- .../code-analysis/quality-rules/ca1828.md | 6 +- .../code-analysis/quality-rules/ca1829.md | 16 +- .../code-analysis/quality-rules/ca1830.md | 2 +- .../code-analysis/quality-rules/ca1831.md | 4 +- .../code-analysis/quality-rules/ca1832.md | 6 +- .../code-analysis/quality-rules/ca1833.md | 6 +- .../code-analysis/quality-rules/ca1834.md | 2 +- .../code-analysis/quality-rules/ca1836.md | 6 +- .../code-analysis/quality-rules/ca1838.md | 4 +- .../code-analysis/quality-rules/ca1841.md | 4 +- .../code-analysis/quality-rules/ca1842.md | 2 +- .../code-analysis/quality-rules/ca1843.md | 2 +- .../code-analysis/quality-rules/ca1844.md | 2 +- .../code-analysis/quality-rules/ca1845.md | 2 +- .../code-analysis/quality-rules/ca1846.md | 6 +- .../code-analysis/quality-rules/ca1848.md | 2 +- .../code-analysis/quality-rules/ca1851.md | 4 +- .../code-analysis/quality-rules/ca1853.md | 6 +- .../code-analysis/quality-rules/ca1855.md | 6 +- .../code-analysis/quality-rules/ca1858.md | 6 +- .../code-analysis/quality-rules/ca1860.md | 4 +- .../code-analysis/quality-rules/ca1862.md | 6 +- .../code-analysis/quality-rules/ca1864.md | 8 +- .../code-analysis/quality-rules/ca1868.md | 8 +- .../code-analysis/quality-rules/ca1869.md | 2 +- .../code-analysis/quality-rules/ca1870.md | 4 +- .../code-analysis/quality-rules/ca1872.md | 10 +- .../code-analysis/quality-rules/ca1873.md | 4 +- .../code-analysis/quality-rules/ca1874.md | 6 +- .../code-analysis/quality-rules/ca1875.md | 4 +- .../code-analysis/quality-rules/ca1877.md | 6 +- .../code-analysis/quality-rules/ca2000.md | 4 +- .../code-analysis/quality-rules/ca2007.md | 6 +- .../code-analysis/quality-rules/ca2008.md | 8 +- .../code-analysis/quality-rules/ca2009.md | 30 +- .../code-analysis/quality-rules/ca2013.md | 4 +- .../code-analysis/quality-rules/ca2015.md | 6 +- .../code-analysis/quality-rules/ca2021.md | 10 +- .../code-analysis/quality-rules/ca2026.md | 6 +- .../code-analysis/quality-rules/ca2100.md | 4 +- .../code-analysis/quality-rules/ca2109.md | 2 +- .../code-analysis/quality-rules/ca2213.md | 8 +- .../code-analysis/quality-rules/ca2215.md | 10 +- .../code-analysis/quality-rules/ca2216.md | 6 +- .../code-analysis/quality-rules/ca2218.md | 18 +- .../code-analysis/quality-rules/ca2224.md | 10 +- .../code-analysis/quality-rules/ca2227.md | 2 +- .../code-analysis/quality-rules/ca2229.md | 2 +- .../code-analysis/quality-rules/ca2231.md | 6 +- .../code-analysis/quality-rules/ca2241.md | 4 +- .../code-analysis/quality-rules/ca2242.md | 4 +- .../code-analysis/quality-rules/ca2247.md | 2 +- .../code-analysis/quality-rules/ca2249.md | 6 +- .../code-analysis/quality-rules/ca2251.md | 6 +- .../code-analysis/quality-rules/ca2253.md | 2 +- .../code-analysis/quality-rules/ca2254.md | 2 +- .../code-analysis/quality-rules/ca2261.md | 6 +- .../code-analysis/quality-rules/ca2264.md | 2 +- .../code-analysis/quality-rules/ca2350.md | 2 +- .../code-analysis/quality-rules/ca2351.md | 4 +- .../code-analysis/quality-rules/ca2355.md | 6 +- .../code-analysis/quality-rules/ca2361.md | 4 +- .../code-analysis/quality-rules/ca3012.md | 2 +- .../code-analysis/quality-rules/ca3075.md | 10 +- .../code-analysis/quality-rules/ca3076.md | 4 +- .../code-analysis/quality-rules/ca5360.md | 46 +- .../code-analysis/quality-rules/ca5361.md | 4 +- .../code-analysis/quality-rules/ca5366.md | 6 +- .../code-analysis/quality-rules/ca5368.md | 2 +- .../code-analysis/quality-rules/ca5369.md | 8 +- .../code-analysis/quality-rules/ca5370.md | 2 +- .../code-analysis/quality-rules/ca5371.md | 8 +- .../code-analysis/quality-rules/ca5373.md | 8 +- .../code-analysis/quality-rules/ca5378.md | 4 +- .../code-analysis/quality-rules/ca5382.md | 2 +- .../code-analysis/quality-rules/ca5383.md | 2 +- .../code-analysis/quality-rules/ca5384.md | 2 +- .../code-analysis/quality-rules/ca5385.md | 8 +- .../code-analysis/quality-rules/ca5387.md | 4 +- .../code-analysis/quality-rules/ca5388.md | 4 +- .../code-analysis/quality-rules/ca5389.md | 8 +- .../code-analysis/quality-rules/ca5390.md | 6 +- .../code-analysis/quality-rules/ca5391.md | 2 +- .../code-analysis/quality-rules/ca5401.md | 6 +- .../code-analysis/quality-rules/ca5402.md | 6 +- .../code-analysis/quality-rules/ca5403.md | 2 +- .../quality-rules/design-warnings.md | 4 +- .../code-analysis/quality-rules/index.md | 48 +- .../quality-rules/performance-warnings.md | 38 +- .../quality-rules/reliability-warnings.md | 8 +- .../quality-rules/usage-warnings.md | 6 +- .../code-analysis/style-rules/ide0070.md | 2 +- .../code-analysis/style-rules/ide0120.md | 24 +- .../code-analysis/style-rules/ide0304.md | 2 +- ...tnet-style-prefer-collection-expression.md | 2 +- .../code-analysis/style-rules/index.md | 2 +- .../runtime-loader-binder-events.md | 2 +- .../networking/http/httpclient.md | 56 +- .../networking/includes/ip-endpoint.md | 4 +- .../networking/sockets/socket-services.md | 16 +- .../networking/sockets/sockets-overview.md | 2 +- .../networking/sockets/tcp-classes.md | 18 +- .../networking/telemetry/events.md | 2 +- .../networking/telemetry/metrics.md | 4 +- .../networking/telemetry/tracing.md | 6 +- .../reflection/accessing-custom-attributes.md | 10 +- .../dynamically-loading-and-using-types.md | 16 +- .../reflection/get-type-member-information.md | 2 +- ...e-a-generic-method-with-reflection-emit.md | 32 +- ...ine-a-generic-type-with-reflection-emit.md | 16 +- ...w-to-define-and-execute-dynamic-methods.md | 4 +- ...stantiate-generic-types-with-reflection.md | 14 +- ...-to-hook-up-a-delegate-using-reflection.md | 18 +- docs/fundamentals/reflection/overview.md | 4 +- .../reflection-and-generic-types.md | 26 +- .../specifying-fully-qualified-type-names.md | 8 +- .../reflection/viewing-type-information.md | 8 +- .../system-collections-generic-list{t}.md | 4 +- .../runtime-libraries/system-console.md | 2 +- .../runtime-libraries/system-enum.md | 2 +- .../system-globalization-compareinfo.md | 2 +- ...lobalization-cultureinfo-currentculture.md | 2 +- ...system-globalization-datetimeformatinfo.md | 2 +- .../system-globalization-numberformatinfo.md | 2 +- .../system-globalization-sortkey.md | 2 +- .../system-invalidoperationexception.md | 10 +- .../system-linq-expressions-expression-add.md | 2 +- .../system-net-httplistener.md | 2 +- .../system-object-gethashcode.md | 2 +- ...lection-context-customreflectioncontext.md | 8 +- .../system-reflection-emit-dynamicilinfo.md | 6 +- ...n-emit-dynamicmethod-issecuritycritical.md | 2 +- .../runtime-libraries/system-string.md | 2 +- .../system-text-regularexpressions-regex.md | 2 +- .../system-threading-tasks-task.md | 2 +- .../experimental-overview.md | 2 +- .../obsoletions-overview.md | 10 +- .../syslib-diagnostics/syslib0001.md | 2 +- .../syslib-diagnostics/syslib0003.md | 4 +- .../syslib-diagnostics/syslib0004.md | 2 +- .../syslib-diagnostics/syslib0006.md | 4 +- .../syslib-diagnostics/syslib0009.md | 6 +- .../syslib-diagnostics/syslib0011.md | 6 +- .../syslib-diagnostics/syslib0014.md | 6 +- .../syslib-diagnostics/syslib0016.md | 2 +- .../syslib-diagnostics/syslib0018.md | 2 +- .../syslib-diagnostics/syslib0021.md | 2 +- .../syslib-diagnostics/syslib0026.md | 4 +- .../syslib-diagnostics/syslib0036.md | 4 +- .../syslib-diagnostics/syslib0045.md | 4 +- .../syslib-diagnostics/syslib0048.md | 2 +- .../syslib-diagnostics/syslib0049.md | 4 +- .../syslib-diagnostics/syslib0052.md | 2 +- .../syslib-diagnostics/syslib0053.md | 2 +- .../syslib-diagnostics/syslib0054.md | 6 +- .../syslib-diagnostics/syslib0056.md | 4 +- .../syslib-diagnostics/syslib0057.md | 4 +- .../syslib-diagnostics/syslib1034.md | 2 +- .../how-to-use-the-automl-api.md | 72 +- .../inspect-intermediate-data-ml-net.md | 12 +- ...chine-learning-model-predictions-ml-net.md | 12 +- .../how-to-guides/prepare-data-ml-net.md | 2 +- .../how-to-guides/retrain-model-ml-net.md | 2 +- ...ave-load-machine-learning-models-ml-net.md | 2 +- ...model-serverless-azure-functions-ml-net.md | 2 +- .../serve-model-web-api-ml-net.md | 2 +- ...-learning-model-cross-validation-ml-net.md | 4 +- .../train-machine-learning-model-ml-net.md | 10 +- docs/machine-learning/resources/glossary.md | 4 +- docs/machine-learning/resources/tasks.md | 2 +- docs/machine-learning/resources/transforms.md | 136 +- .../tutorials/github-issue-classification.md | 12 +- ...ge-classification-api-transfer-learning.md | 16 +- .../tutorials/image-classification.md | 2 +- .../tutorials/iris-clustering.md | 6 +- .../movie-recommendation-model-builder.md | 2 +- .../tutorials/movie-recommendation.md | 6 +- .../object-detection-custom-vision-onnx.md | 2 +- .../tutorials/object-detection-onnx.md | 4 +- .../phone-calls-anomaly-detection.md | 6 +- .../tutorials/predict-prices.md | 4 +- .../tutorials/sales-anomaly-detection.md | 2 +- .../sentiment-analysis-model-builder.md | 16 +- .../tutorials/sentiment-analysis.md | 8 +- .../tutorials/text-classification-tf.md | 4 +- .../time-series-demand-forecasting.md | 6 +- docs/orleans/deployment/consul-deployment.md | 4 +- docs/orleans/deployment/handling-failures.md | 2 +- docs/orleans/deployment/kubernetes.md | 2 +- docs/orleans/deployment/service-fabric.md | 14 +- docs/orleans/grains/cancellation-tokens.md | 14 +- docs/orleans/grains/code-generation.md | 2 +- .../event-sourcing-configuration.md | 2 +- .../immediate-vs-delayed-confirmation.md | 12 +- docs/orleans/grains/event-sourcing/index.md | 2 +- .../event-sourcing/journaledgrain-basics.md | 14 +- .../journaledgrain-diagnostics.md | 2 +- .../log-consistency-providers.md | 10 +- .../grains/event-sourcing/notifications.md | 2 +- .../event-sourcing/replicated-instances.md | 6 +- .../grains/external-tasks-and-grains.md | 10 +- docs/orleans/grains/grain-extensions.md | 6 +- docs/orleans/grains/grain-identity.md | 2 +- docs/orleans/grains/grain-lifecycle.md | 14 +- .../grains/grain-persistence/azure-storage.md | 12 +- .../grain-persistence/dynamodb-storage.md | 2 +- .../orleans/grains/grain-persistence/index.md | 58 +- .../grain-persistence/relational-storage.md | 2 +- docs/orleans/grains/grain-references.md | 2 +- docs/orleans/grains/grainservices.md | 4 +- docs/orleans/grains/index.md | 28 +- docs/orleans/grains/observers.md | 16 +- docs/orleans/grains/oneway.md | 2 +- docs/orleans/grains/request-context.md | 4 +- docs/orleans/grains/timers-and-reminders.md | 12 +- docs/orleans/grains/transactions.md | 10 +- docs/orleans/host/client.md | 6 +- .../activation-collection.md | 2 +- .../list-of-options-classes.md | 2 +- .../local-development-configuration.md | 4 +- .../serialization-configuration.md | 4 +- .../serialization-customization.md | 14 +- .../serialization-immutability.md | 10 +- .../host/configuration-guide/serialization.md | 20 +- .../server-configuration.md | 4 +- .../shutting-down-orleans.md | 4 +- docs/orleans/host/monitoring/index.md | 258 ++-- docs/orleans/host/silo-lifecycle.md | 6 +- docs/orleans/host/transport-layer-security.md | 20 +- .../implementation/cluster-management.md | 6 +- .../implementation/orleans-lifecycle.md | 2 +- docs/orleans/implementation/scheduler.md | 2 +- .../streams-implementation/index.md | 2 +- docs/orleans/migration-guide.md | 4 +- docs/orleans/overview.md | 2 +- .../build-your-first-orleans-app.md | 2 +- docs/orleans/resources/best-practices.md | 8 +- docs/orleans/streaming/broadcast-channel.md | 6 +- docs/orleans/streaming/stream-providers.md | 2 +- .../streaming/streams-programming-apis.md | 32 +- docs/orleans/streaming/streams-quick-start.md | 12 +- docs/orleans/streaming/streams-why.md | 2 +- .../custom-grain-storage.md | 16 +- docs/orleans/tutorials-and-samples/index.md | 2 +- .../tutorials-and-samples/tutorial-1.md | 2 +- .../analyzers/platform-compat-analyzer.md | 8 +- .../assembly/create-use-strong-named.md | 2 +- .../disable-strong-name-bypass-feature.md | 2 +- .../assembly/embed-types-visual-studio.md | 2 +- .../assembly/find-fully-qualified-name.md | 4 +- docs/standard/assembly/identify.md | 8 +- docs/standard/assembly/index.md | 2 +- ...pect-contents-using-metadataloadcontext.md | 2 +- docs/standard/assembly/load-unload.md | 4 +- docs/standard/assembly/names.md | 4 +- .../standard/assembly/reference-assemblies.md | 6 +- .../assembly/reference-strong-named.md | 4 +- docs/standard/assembly/resolve-loads.md | 24 +- docs/standard/assembly/set-attributes.md | 4 +- docs/standard/assembly/type-forwarding.md | 2 +- docs/standard/assembly/unloadability.md | 6 +- .../asynchronous-programming-model-apm.md | 88 +- ...ng-the-event-based-asynchronous-pattern.md | 22 +- ...-execution-by-ending-an-async-operation.md | 32 +- ...tion-execution-using-an-asyncwaithandle.md | 32 +- ...ling-synchronous-methods-asynchronously.md | 8 +- ...ts-the-event-based-asynchronous-pattern.md | 422 +++--- ...ing-the-task-based-asynchronous-pattern.md | 62 +- ...ent-based-asynchronous-pattern-overview.md | 212 +-- ...ng-the-event-based-asynchronous-pattern.md | 2 +- ...ing-the-task-based-asynchronous-pattern.md | 24 +- ...h-other-asynchronous-patterns-and-types.md | 126 +- ...the-status-of-an-asynchronous-operation.md | 26 +- .../task-based-asynchronous-pattern-tap.md | 294 ++--- ...asynccallback-delegate-and-state-object.md | 18 +- ...legate-to-end-an-asynchronous-operation.md | 32 +- ...ieving-information-stored-in-attributes.md | 12 +- .../attributes/writing-custom-attributes.md | 8 +- .../anchors-in-regular-expressions.md | 214 ++-- ...rence-constructs-in-regular-expressions.md | 2 +- .../backtracking-in-regular-expressions.md | 16 +- .../base-types/best-practices-display-data.md | 12 +- .../base-types/best-practices-regex.md | 8 +- .../base-types/best-practices-strings.md | 90 +- docs/standard/base-types/changing-case.md | 28 +- ...haracter-classes-in-regular-expressions.md | 16 +- .../character-encoding-introduction.md | 20 +- .../standard/base-types/character-encoding.md | 42 +- .../choosing-between-anonymous-and-tuple.md | 4 +- .../standard/base-types/common-type-system.md | 8 +- docs/standard/base-types/comparing.md | 50 +- ...lation-and-reuse-in-regular-expressions.md | 2 +- .../base-types/composite-formatting.md | 28 +- docs/standard/base-types/creating-new.md | 222 ++-- .../custom-date-and-time-format-strings.md | 38 +- .../custom-numeric-format-strings.md | 12 +- .../custom-timespan-format-strings.md | 48 +- .../details-of-regular-expression-behavior.md | 2 +- docs/standard/base-types/divide-up-strings.md | 18 +- .../base-types/enumeration-format-strings.md | 6 +- docs/standard/base-types/formatting-types.md | 60 +- ...uping-constructs-in-regular-expressions.md | 28 +- ...and-use-custom-numeric-format-providers.md | 118 +- ...isplay-dates-in-non-gregorian-calendars.md | 124 +- ...ay-milliseconds-in-date-and-time-values.md | 10 +- ...t-a-protocol-and-port-number-from-a-url.md | 50 +- ...he-day-of-the-week-from-a-specific-date.md | 106 +- .../how-to-pad-a-number-with-leading-zeros.md | 2 +- .../how-to-round-trip-date-and-time-values.md | 4 +- ...-strip-invalid-characters-from-a-string.md | 20 +- ...-that-strings-are-in-valid-email-format.md | 2 +- ...neous-constructs-in-regular-expressions.md | 2 +- docs/standard/base-types/padding.md | 14 +- docs/standard/base-types/parsing-datetime.md | 24 +- docs/standard/base-types/parsing-numeric.md | 18 +- .../quantifiers-in-regular-expressions.md | 474 +++---- ...xpression-example-changing-date-formats.md | 68 +- ...r-expression-example-scanning-for-hrefs.md | 8 +- ...lar-expression-language-quick-reference.md | 2 +- .../base-types/regular-expression-options.md | 16 +- .../base-types/regular-expressions.md | 160 +-- .../standard-date-and-time-format-strings.md | 154 +-- .../standard-numeric-format-strings.md | 94 +- .../standard-timespan-format-strings.md | 178 +-- docs/standard/base-types/stringbuilder.md | 22 +- .../substitutions-in-regular-expressions.md | 350 ++--- .../the-regular-expression-object-model.md | 44 +- docs/standard/base-types/trimming.md | 12 +- docs/standard/base-types/type-conversion.md | 4 +- docs/standard/building-console-apps.md | 4 +- docs/standard/class-library-overview.md | 4 +- .../commonly-used-collection-types.md | 90 +- ...omparisons-and-sorts-within-collections.md | 26 +- ...shtable-and-dictionary-collection-types.md | 40 +- docs/standard/collections/index.md | 34 +- .../selecting-a-collection-class.md | 32 +- .../collections/sorted-collection-types.md | 26 +- .../blockingcollection-overview.md | 136 +- .../how-to-add-and-remove-items.md | 26 +- .../thread-safe/how-to-add-and-take-items.md | 30 +- .../how-to-add-bounding-and-blocking.md | 30 +- .../how-to-create-an-object-pool.md | 6 +- ...ow-to-use-arrays-of-blockingcollections.md | 18 +- .../how-to-use-foreach-to-remove.md | 10 +- .../standard/collections/thread-safe/index.md | 24 +- .../when-to-use-a-thread-safe-collection.md | 98 +- .../when-to-use-generic-collections.md | 42 +- .../data/sqlite/adonet-limitations.md | 2 +- docs/standard/data/sqlite/backup.md | 2 +- docs/standard/data/sqlite/batching.md | 2 +- docs/standard/data/sqlite/collation.md | 2 +- docs/standard/data/sqlite/database-errors.md | 6 +- docs/standard/data/sqlite/extensions.md | 2 +- docs/standard/data/sqlite/metadata.md | 2 +- docs/standard/data/sqlite/transactions.md | 4 +- .../data/sqlite/user-defined-functions.md | 4 +- .../xml/accessing-attributes-in-the-dom.md | 2 +- ...gly-typed-xml-data-using-xpathnavigator.md | 342 ++--- ...ce-node-navigation-using-xpathnavigator.md | 164 +-- .../standard/data/xml/building-xml-schemas.md | 12 +- .../data/xml/compiled-xpath-expressions.md | 212 +-- ...ting-nodes-from-one-document-to-another.md | 52 +- .../data/xml/create-new-nodes-in-the-dom.md | 74 +- ...-new-attributes-for-elements-in-the-dom.md | 12 +- docs/standard/data/xml/editing-xml-schemas.md | 34 +- ...-xpath-expressions-using-xpathnavigator.md | 66 +- docs/standard/data/xml/extending-the-dom.md | 8 +- .../extract-xml-data-using-xpathnavigator.md | 296 ++--- .../how-to-migrate-your-xsltransform-code.md | 130 +- ...slt-transformation-by-using-an-assembly.md | 312 ++--- .../xml/how-to-transform-a-node-fragment.md | 70 +- .../xml/including-or-importing-xml-schemas.md | 8 +- .../inferring-schemas-from-xml-documents.md | 8 +- ...nputs-to-the-xslcompiledtransform-class.md | 74 +- .../insert-xml-data-using-xpathnavigator.md | 76 +- .../data/xml/load-data-from-a-reader.md | 32 +- .../managing-namespaces-in-an-xml-document.md | 130 +- .../matching-nodes-using-xpathnavigator.md | 44 +- .../migrating-from-the-xsltransform-class.md | 10 +- .../modify-xml-data-using-xpathnavigator.md | 24 +- ...s-content-and-values-in-an-xml-document.md | 66 +- ...ode-set-navigation-using-xpathnavigator.md | 82 +- .../object-comparison-using-xmlnametable.md | 76 +- ...tions-on-the-xslcompiledtransform-class.md | 10 +- .../xml/post-schema-compilation-infoset.md | 18 +- .../reading-an-xml-document-into-the-dom.md | 110 +- .../xml/reading-and-writing-xml-schemas.md | 6 +- ...ata-using-xpathdocument-and-xmldocument.md | 124 +- .../remove-xml-data-using-xpathnavigator.md | 350 ++--- ...ributes-from-an-element-node-in-the-dom.md | 52 +- .../xml/removing-node-content-in-the-dom.md | 4 +- .../data/xml/removing-nodes-from-the-dom.md | 16 +- ...ternal-resources-during-xslt-processing.md | 60 +- ...ferring-schema-node-types-and-structure.md | 18 +- .../data/xml/saving-and-writing-a-document.md | 154 +-- .../schema-validation-using-xpathnavigator.md | 696 +++++----- .../xml/script-blocks-using-msxsl-script.md | 4 +- .../select-nodes-using-xpath-navigation.md | 290 ++--- .../select-xml-data-using-xpathnavigator.md | 100 +- ...-matching-xml-data-using-xpathnavigator.md | 44 +- .../data/xml/traversing-xml-schemas.md | 32 +- .../type-support-in-the-system-xml-classes.md | 52 +- docs/standard/data/xml/types-of-xml-nodes.md | 66 +- ...ordered-node-retrieval-by-name-or-index.md | 198 +-- .../user-defined-functions-and-variables.md | 4 +- .../using-the-xslcompiledtransform-class.md | 56 +- .../validating-an-xml-document-in-the-dom.md | 20 +- ...xdr-validation-with-xmlschemacollection.md | 4 +- .../data/xml/xml-processing-options.md | 40 +- .../xml/xml-schema-object-model-overview.md | 52 +- ...xsd-validation-with-xmlschemacollection.md | 378 +++--- ...schema-xsd-validation-with-xmlschemaset.md | 8 +- .../xml-type-support-implementation-notes.md | 66 +- .../xmlschemaset-for-schema-compilation.md | 500 ++++---- ...mlschemavalidator-push-based-validation.md | 132 +- .../data/xml/xpath-namespace-navigation.md | 100 +- .../data/xml/xpath-queries-and-namespaces.md | 130 +- .../data/xml/xslt-extension-objects.md | 48 +- docs/standard/data/xml/xslt-parameters.md | 112 +- .../data/xml/xslt-security-considerations.md | 90 +- .../standard/datetime/access-utc-and-local.md | 14 +- .../datetime/choosing-between-datetime.md | 14 +- .../converting-between-datetime-and-offset.md | 40 +- .../datetime/converting-between-time-zones.md | 28 +- ...create-time-zones-with-adjustment-rules.md | 20 +- ...ate-time-zones-without-adjustment-rules.md | 10 +- .../standard/datetime/enumerate-time-zones.md | 10 +- .../finding-the-time-zones-on-local-system.md | 8 +- .../datetime/how-to-use-dateonly-timeonly.md | 14 +- .../datetime/instantiate-time-zone-info.md | 8 +- .../instantiating-a-datetimeoffset-object.md | 18 +- .../let-users-resolve-ambiguous-times.md | 10 +- .../performing-arithmetic-operations.md | 18 +- .../datetime/resolve-ambiguous-times.md | 12 +- ...re-time-zones-from-an-embedded-resource.md | 16 +- ...save-time-zones-to-an-embedded-resource.md | 20 +- .../saving-and-restoring-time-zones.md | 8 +- .../datetime/system-text-json-support.md | 14 +- docs/standard/datetime/time-zone-overview.md | 14 +- .../datetime/use-time-zones-in-arithmetic.md | 4 +- .../datetime/working-with-calendars.md | 32 +- docs/standard/delegates-lambdas.md | 2 +- ...tractions-abstract-types-and-interfaces.md | 2 +- docs/standard/design-guidelines/attributes.md | 4 +- ...e-classes-for-implementing-abstractions.md | 2 +- .../dependency-properties.md | 4 +- .../design-guidelines/dispose-pattern.md | 10 +- .../design-guidelines/equality-operators.md | 2 +- docs/standard/design-guidelines/event.md | 2 +- .../exceptions-and-performance.md | 4 +- .../design-guidelines/extension-methods.md | 2 +- .../guidelines-for-collections.md | 16 +- docs/standard/design-guidelines/interface.md | 4 +- .../design-guidelines/operator-overloads.md | 2 +- .../design-guidelines/parameter-design.md | 4 +- docs/standard/design-guidelines/property.md | 4 +- .../design-guidelines/serialization.md | 6 +- docs/standard/design-guidelines/struct.md | 4 +- .../design-guidelines/usage-guidelines.md | 8 +- ...-multiple-events-using-event-properties.md | 2 +- .../events/how-to-implement-a-provider.md | 72 +- .../events/how-to-implement-an-observer.md | 56 +- docs/standard/events/index.md | 6 +- .../observer-design-pattern-best-practices.md | 22 +- .../events/observer-design-pattern.md | 28 +- .../best-practices-for-exceptions.md | 24 +- .../handling-com-interop-exceptions.md | 24 +- .../app-domain-resource-monitoring.md | 16 +- .../garbage-collection/fundamentals.md | 4 +- .../implementing-dispose.md | 48 +- .../implementing-disposeasync.md | 6 +- docs/standard/garbage-collection/index.md | 48 +- docs/standard/garbage-collection/induced.md | 48 +- .../garbage-collection/large-object-heap.md | 2 +- docs/standard/garbage-collection/latency.md | 6 +- .../garbage-collection/notifications.md | 24 +- .../garbage-collection/performance.md | 4 +- docs/standard/garbage-collection/unmanaged.md | 18 +- .../garbage-collection/using-objects.md | 12 +- .../garbage-collection/weak-references.md | 74 +- docs/standard/generics.md | 4 +- docs/standard/generics/collections.md | 18 +- .../generics/covariance-and-contravariance.md | 188 +-- ...gates-for-manipulating-arrays-and-lists.md | 44 +- docs/standard/generics/index.md | 20 +- docs/standard/generics/interfaces.md | 56 +- docs/standard/generics/math.md | 90 +- docs/standard/io/asynchronous-file-i-o.md | 4 +- docs/standard/io/buffers.md | 22 +- docs/standard/io/common-i-o-tasks.md | 36 +- docs/standard/io/composing-streams.md | 14 +- docs/standard/io/file-path-formats.md | 4 +- docs/standard/io/handling-io-errors.md | 8 +- ...d-or-remove-access-control-list-entries.md | 8 +- ...-space-conditions-with-isolated-storage.md | 6 +- .../io/how-to-compress-and-extract-files.md | 2 +- ...etween-dotnet-streams-and-winrt-streams.md | 38 +- ...les-and-directories-in-isolated-storage.md | 30 +- ...les-and-directories-in-isolated-storage.md | 4 +- ...ow-to-delete-stores-in-isolated-storage.md | 2 +- .../how-to-enumerate-directories-and-files.md | 70 +- ...o-enumerate-stores-for-isolated-storage.md | 18 +- ...les-and-directories-in-isolated-storage.md | 6 +- ...w-to-obtain-stores-for-isolated-storage.md | 16 +- .../how-to-open-and-append-to-a-log-file.md | 40 +- ...-and-write-to-a-newly-created-data-file.md | 2 +- .../how-to-read-characters-from-a-string.md | 2 +- .../io/how-to-read-text-from-a-file.md | 8 +- ...-for-network-interprocess-communication.md | 2 +- .../io/how-to-write-characters-to-a-string.md | 44 +- .../io/how-to-write-text-to-a-file.md | 38 +- docs/standard/io/index.md | 6 +- docs/standard/io/isolated-storage.md | 4 +- docs/standard/io/memory-mapped-files.md | 252 ++-- docs/standard/io/pipelines.md | 42 +- docs/standard/io/types-of-isolation.md | 8 +- docs/standard/language-independence.md | 4 +- .../add-elements-attributes-nodes-xml-tree.md | 8 +- .../linq/atomized-xname-xnamespace-objects.md | 2 +- .../linq/basic-queries-linq-to-xml.md | 24 +- docs/standard/linq/catch-parsing-errors.md | 4 +- docs/standard/linq/chain-axis-method-calls.md | 8 +- ...chain-standard-query-operators-together.md | 6 +- .../linq/change-namespace-entire-xml-tree.md | 2 +- .../linq/comparison-xpath-linq-xml.md | 20 +- ...s-terminology-functional-transformation.md | 2 +- .../linq/control-namespace-prefixes.md | 2 +- docs/standard/linq/control-type-projection.md | 6 +- .../linq/create-document-namespaces-csharp.md | 2 +- .../linq/debug-empty-query-results-sets.md | 2 +- .../deferred-execution-lazy-evaluation.md | 4 +- docs/standard/linq/filter-element-names.md | 18 +- docs/standard/linq/filter-optional-element.md | 8 +- docs/standard/linq/find-attribute-parent.md | 2 +- .../find-attributes-siblings-specific-name.md | 2 +- docs/standard/linq/find-child-element.md | 4 +- .../find-child-elements-based-position.md | 4 +- .../linq/find-default-paragraph-style.md | 2 +- .../linq/find-descendants-child-element.md | 4 +- .../find-descendants-specific-element-name.md | 4 +- .../linq/find-element-specific-attribute.md | 4 +- .../find-element-specific-child-element.md | 4 +- .../linq/find-elements-specific-attribute.md | 2 +- .../linq/find-immediate-preceding-sibling.md | 4 +- .../standard/linq/find-list-child-elements.md | 2 +- docs/standard/linq/find-preceding-siblings.md | 2 +- docs/standard/linq/find-sibling-nodes.md | 2 +- ...nd-single-descendant-descendants-method.md | 4 +- .../linq/find-union-two-location-paths.md | 4 +- docs/standard/linq/functional-construction.md | 2 +- .../linq/intermediate-materialization.md | 6 +- .../standard/linq/language-integrated-axes.md | 6 +- docs/standard/linq/linq-xml-annotations.md | 10 +- docs/standard/linq/linq-xml-axes-overview.md | 28 +- .../linq/linq-xml-classes-overview.md | 2 +- docs/standard/linq/linq-xml-overview.md | 2 +- docs/standard/linq/linq-xml-security.md | 10 +- docs/standard/linq/linq-xml-vs-dom.md | 2 +- docs/standard/linq/load-xml-file.md | 4 +- .../linq/maintain-name-value-pairs.md | 26 +- .../mixed-declarative-imperative-code-bugs.md | 8 +- ...dify-elements-attributes-nodes-xml-tree.md | 26 +- ...streaming-transform-large-xml-documents.md | 2 +- .../linq/performance-chained-queries.md | 6 +- .../linq/populate-xml-tree-xmlwriter.md | 6 +- ...reserve-white-space-loading-parsing-xml.md | 8 +- .../linq/preserve-white-space-serializing.md | 8 +- docs/standard/linq/program-nodes.md | 4 +- docs/standard/linq/project-new-type.md | 4 +- docs/standard/linq/project-object-graph.md | 6 +- docs/standard/linq/query-linq-xml-xpath.md | 2 +- .../linq/query-xdocument-vs-query-xelement.md | 8 +- .../linq/read-write-encoded-document.md | 8 +- .../linq/refactor-extension-method.md | 2 +- docs/standard/linq/refactor-pure-functions.md | 2 +- ...move-elements-attributes-nodes-xml-tree.md | 22 +- .../linq/retrieve-collection-attributes.md | 2 +- .../linq/retrieve-collection-elements.md | 2 +- .../linq/retrieve-paragraphs-styles.md | 4 +- .../linq/retrieve-shallow-value-element.md | 2 +- .../linq/retrieve-single-attribute.md | 4 +- .../linq/retrieve-single-child-element.md | 2 +- .../standard/linq/retrieve-text-paragraphs.md | 4 +- .../standard/linq/retrieve-value-attribute.md | 2 +- docs/standard/linq/retrieve-value-element.md | 16 +- .../standard/linq/scope-default-namespaces.md | 2 +- .../serialize-files-textwriters-xmlwriters.md | 10 +- .../linq/serialize-xml-declaration.md | 2 +- .../linq/serialize-xmlreader-invoke-xslt.md | 2 +- .../linq/statically-compiled-queries.md | 4 +- ...xml-fragments-access-header-information.md | 4 +- .../linq/stream-xml-fragments-xmlreader.md | 4 +- .../linq/use-xslt-transform-xml-tree.md | 4 +- ...alid-content-xelement-xdocument-objects.md | 30 +- docs/standard/linq/validate-xsd.md | 4 +- .../linq/work-dictionaries-linq-xml.md | 4 +- .../linq/write-queries-complex-filtering.md | 4 +- ...rite-query-finds-elements-based-context.md | 8 +- docs/standard/linq/xelement-class-overview.md | 4 +- ...tributed-programming-model-overview-mef.md | 2 +- docs/standard/mef/index.md | 6 +- docs/standard/memory-and-spans/index.md | 28 +- .../memory-t-usage-guidelines.md | 60 +- .../standard/native-interop/best-practices.md | 10 +- .../custom-marshalling-source-generation.md | 4 +- .../native-interop/native-library-loading.md | 4 +- docs/standard/native-interop/preserve-sig.md | 2 +- docs/standard/numerics.md | 8 +- .../attached-and-detached-child-tasks.md | 130 +- ...ining-tasks-by-using-continuation-tasks.md | 44 +- .../custom-partitioners-for-plinq-and-tpl.md | 62 +- .../data-parallelism-task-parallel-library.md | 68 +- ...ata-structures-for-parallel-programming.md | 112 +- .../dataflow-task-parallel-library.md | 492 +++---- ...xception-handling-task-parallel-library.md | 26 +- .../how-to-cancel-a-dataflow-block.md | 6 +- ...o-cancel-a-parallel-for-or-foreach-loop.md | 4 +- .../how-to-cancel-a-plinq-query.md | 2 +- .../how-to-cancel-a-task-and-its-children.md | 12 +- ...ne-parallel-and-sequential-linq-queries.md | 28 +- ...ow-to-control-ordering-in-a-plinq-query.md | 2 +- ...create-and-execute-a-simple-plinq-query.md | 22 +- .../how-to-create-pre-computed-tasks.md | 6 +- ...-to-handle-exceptions-in-parallel-loops.md | 26 +- ...t-a-partitioner-for-static-partitioning.md | 16 +- ...nt-a-producer-consumer-dataflow-pattern.md | 8 +- .../how-to-implement-dynamic-partitions.md | 16 +- ...-to-iterate-file-directories-with-plinq.md | 38 +- ...ile-directories-with-the-parallel-class.md | 30 +- ...ion-when-a-dataflow-block-receives-data.md | 44 +- ...child-task-from-attaching-to-its-parent.md | 22 +- .../how-to-return-a-value-from-a-task.md | 22 +- ...fy-a-task-scheduler-in-a-dataflow-block.md | 14 +- ...gree-of-parallelism-in-a-dataflow-block.md | 28 +- ...-to-specify-the-execution-mode-in-plinq.md | 32 +- .../how-to-speed-up-small-loop-bodies.md | 18 +- ...verse-a-binary-tree-with-parallel-tasks.md | 18 +- .../how-to-unlink-dataflow-blocks.md | 22 +- .../how-to-unwrap-a-nested-task.md | 48 +- ...lock-to-read-data-from-multiple-sources.md | 28 +- ...l-invoke-to-execute-parallel-operations.md | 4 +- .../how-to-wrap-eap-patterns-in-a-task.md | 14 +- ...write-a-custom-plinq-aggregate-function.md | 30 +- ...el-for-loop-with-thread-local-variables.md | 54 +- ...ach-loop-with-partition-local-variables.md | 18 +- ...how-to-write-a-simple-parallel-for-loop.md | 18 +- ...to-write-a-simple-parallel-foreach-loop.md | 10 +- ...and-read-messages-from-a-dataflow-block.md | 10 +- .../introduction-to-plinq.md | 48 +- .../lambda-expressions-in-plinq-and-tpl.md | 6 +- .../merge-options-in-plinq.md | 100 +- .../order-preservation-in-plinq.md | 208 +-- ...l-pitfalls-in-data-and-task-parallelism.md | 128 +- .../potential-pitfalls-with-plinq.md | 10 +- .../task-based-asynchronous-programming.md | 92 +- .../parallel-programming/task-cancellation.md | 44 +- .../task-parallel-library-tpl.md | 26 +- .../tpl-and-traditional-async-programming.md | 174 +-- .../understanding-speedup-in-plinq.md | 138 +- ...h-creating-a-custom-dataflow-block-type.md | 60 +- ...alkthrough-creating-a-dataflow-pipeline.md | 170 +-- ...-batchedjoinblock-to-improve-efficiency.md | 8 +- ...dataflow-in-a-windows-forms-application.md | 220 ++-- .../security/cross-platform-cryptography.md | 12 +- .../security/cryptographic-services.md | 2 +- .../security/cryptographic-signatures.md | 6 +- docs/standard/security/cryptography-model.md | 8 +- docs/standard/security/decrypting-data.md | 2 +- docs/standard/security/encrypting-data.md | 2 +- ...ting-keys-for-encryption-and-decryption.md | 122 +- ...w-to-access-hardware-encryption-devices.md | 4 +- ...how-to-create-a-windowsprincipal-object.md | 112 +- ...crypt-xml-elements-with-asymmetric-keys.md | 104 +- ...ecrypt-xml-elements-with-symmetric-keys.md | 108 +- ...pt-xml-elements-with-x-509-certificates.md | 94 +- ...crypt-xml-elements-with-asymmetric-keys.md | 38 +- ...ncrypt-xml-elements-with-symmetric-keys.md | 132 +- ...pt-xml-elements-with-x-509-certificates.md | 162 +-- ...n-xml-documents-with-digital-signatures.md | 164 +-- ...tore-asymmetric-keys-in-a-key-container.md | 10 +- .../security/how-to-use-data-protection.md | 54 +- ...the-digital-signatures-of-xml-documents.md | 98 +- .../security/impersonating-and-reverting.md | 84 +- .../security/key-security-concepts.md | 4 +- ...gh-creating-a-cryptographic-application.md | 2 +- .../binaryformatter-event-source.md | 4 +- .../read-nrbf-payloads.md | 10 +- ...ling-xml-serialization-using-attributes.md | 4 +- .../examples-of-xml-serialization.md | 16 +- .../how-to-chunk-serialized-data.md | 68 +- .../how-to-deserialize-an-object.md | 10 +- .../how-to-serialize-an-object.md | 68 +- ...lternate-element-name-for-an-xml-stream.md | 4 +- .../system-text-json/configure-options.md | 6 +- .../system-text-json/converters-how-to.md | 24 +- .../system-text-json/custom-contracts.md | 4 +- .../system-text-json/customize-properties.md | 6 +- .../system-text-json/deserialization.md | 6 +- .../serialization/system-text-json/fields.md | 2 +- .../serialization/system-text-json/how-to.md | 6 +- .../system-text-json/httpclient-extensions.md | 2 +- .../system-text-json/ignore-properties.md | 2 +- .../system-text-json/invalid-json.md | 2 +- .../migrate-from-newtonsoft.md | 14 +- .../system-text-json/preserve-references.md | 12 +- .../system-text-json/required-properties.md | 2 +- .../system-text-json/source-generation.md | 18 +- .../system-text-json/supported-types.md | 108 +- .../serialization/system-text-json/use-dom.md | 14 +- .../system-text-json/use-utf8jsonreader.md | 16 +- .../system-text-json/use-utf8jsonwriter.md | 12 +- .../system-text-json/visual-basic-support.md | 4 +- .../xml-schema-definition-tool-xsd-exe.md | 4 +- docs/standard/simd.md | 8 +- docs/standard/threading/barrier.md | 56 +- .../cancellation-in-managed-threads.md | 22 +- docs/standard/threading/countdownevent.md | 58 +- ...-threads-and-passing-data-at-start-time.md | 8 +- docs/standard/threading/destroying-threads.md | 84 +- docs/standard/threading/eventwaithandle.md | 90 +- .../exceptions-in-managed-threads.md | 42 +- .../foreground-and-background-threads.md | 26 +- ...en-for-cancellation-requests-by-polling.md | 26 +- ...sten-for-multiple-cancellation-requests.md | 30 +- ...ter-callbacks-for-cancellation-requests.md | 8 +- ...-spinlock-for-low-level-synchronization.md | 24 +- ...to-implement-a-two-phase-wait-operation.md | 26 +- ...aged-and-unmanaged-threading-in-windows.md | 82 +- .../managed-threading-best-practices.md | 22 +- docs/standard/threading/mutexes.md | 24 +- .../overview-of-synchronization-primitives.md | 34 +- .../threading/pausing-and-resuming-threads.md | 40 +- .../threading/semaphore-and-semaphoreslim.md | 12 +- docs/standard/threading/spinwait.md | 26 +- .../synchronizing-data-for-multithreading.md | 6 +- .../threading/the-managed-thread-pool.md | 82 +- ...d-relative-static-fields-and-data-slots.md | 12 +- docs/standard/threading/timers.md | 8 +- .../threading/using-threads-and-threading.md | 34 +- docs/standard/value-tuples.md | 22 +- ...ding-the-visual-basic-application-model.md | 46 +- .../accessing-application-forms.md | 28 +- .../programming/accessing-user-data.md | 26 +- ...create-property-grids-for-user-settings.md | 64 +- .../accessing-the-computer-s-ports.md | 68 +- .../accessing-the-keyboard.md | 32 +- .../getting-information-about-the-computer.md | 12 +- ...create-a-registry-key-and-set-its-value.md | 6 +- .../how-to-delete-a-registry-key.md | 62 +- ...to-dial-modems-attached-to-serial-ports.md | 82 +- .../how-to-download-a-file.md | 4 +- ...ow-to-receive-strings-from-serial-ports.md | 106 +- .../how-to-send-strings-to-serial-ports.md | 50 +- ...t-an-application-and-send-it-keystrokes.md | 14 +- .../how-to-upload-a-file.md | 64 +- .../programming/computer-resources/index.md | 18 +- .../performing-network-operations.md | 58 +- .../computer-resources/playing-sounds.md | 108 +- .../port-operations-in-the-net-framework.md | 2 +- ...try-using-the-microsoft-win32-namespace.md | 56 +- ...-data-to-and-reading-from-the-clipboard.md | 114 +- ...t-framework-file-io-and-the-file-system.md | 8 +- ...leting-and-moving-files-and-directories.md | 188 +-- .../how-to-append-to-text-files.md | 60 +- ...o-copy-a-directory-to-another-directory.md | 4 +- ...-with-a-specific-pattern-to-a-directory.md | 94 +- ...copy-of-a-file-in-a-different-directory.md | 84 +- ...-a-copy-of-a-file-in-the-same-directory.md | 98 +- .../how-to-create-a-directory.md | 60 +- .../how-to-create-a-file.md | 76 +- ...w-to-find-files-with-a-specific-pattern.md | 68 +- ...-subdirectories-with-a-specific-pattern.md | 4 +- ...-the-collection-of-files-in-a-directory.md | 72 +- .../how-to-move-a-file.md | 80 +- .../how-to-parse-file-paths.md | 50 +- .../how-to-read-from-binary-files.md | 78 +- ...to-read-from-comma-delimited-text-files.md | 82 +- ...how-to-read-from-fixed-width-text-files.md | 86 +- ...d-from-text-files-with-multiple-formats.md | 18 +- .../how-to-read-from-text-files.md | 8 +- ...ead-text-from-files-with-a-streamreader.md | 46 +- .../how-to-rename-a-file.md | 6 +- ...-contents-of-the-my-documents-directory.md | 20 +- ...-to-files-in-the-my-documents-directory.md | 70 +- ...write-text-to-files-with-a-streamwriter.md | 44 +- .../how-to-write-text-to-files.md | 84 +- .../how-to-write-to-binary-files.md | 4 +- ...t-files-with-the-textfieldparser-object.md | 70 +- .../reading-from-files.md | 104 +- ...ough-manipulating-files-and-directories.md | 280 ++-- ...ng-files-by-using-net-framework-methods.md | 2 +- .../writing-to-files.md | 92 +- .../log-info/how-to-log-exceptions.md | 110 +- ...en-the-application-starts-or-shuts-down.md | 90 +- ...-write-event-information-to-a-text-file.md | 6 +- .../log-info/how-to-write-log-messages.md | 4 +- ...ow-to-write-to-an-application-event-log.md | 4 +- .../log-info/troubleshooting-log-listeners.md | 50 +- ...lkthrough-creating-custom-log-listeners.md | 4 +- ...ugh-filtering-my-application-log-output.md | 2 +- .../log-info/working-with-application-logs.md | 4 +- .../constants-and-enumerations.md | 128 +- .../data-types/char-data-type.md | 18 +- .../data-types/date-data-type.md | 4 +- .../data-types/decimal-data-type.md | 4 +- .../language-reference/data-types/index.md | 100 +- .../data-types/object-data-type.md | 2 +- .../data-types/string-data-type.md | 116 +- ...alid-comment-token-for-delimited-fields.md | 10 +- .../a-startup-form-has-not-been-specified.md | 30 +- .../error-messages/bad-file-name-or-number.md | 36 +- .../error-messages/bad-record-length.md | 42 +- .../error-messages/bc2012.md | 4 +- .../error-messages/bc42358.md | 4 +- ...irst-be-called-with-a-pathname-argument.md | 2 +- ...ntname-is-obsolete-visual-basic-warning.md | 4 +- ...ype-typename-which-is-a-restricted-type.md | 2 +- ...e-cannot-be-the-target-of-an-assignment.md | 4 +- ...xpression-of-type-type-is-not-queryable.md | 2 +- .../error-messages/file-already-open.md | 2 +- ...-is-too-large-to-read-into-a-byte-array.md | 14 +- ...licit-call-to-mybase-new-or-myclass-new.md | 2 +- .../for-each-on-type-typename-is-ambiguous.md | 6 +- .../error-messages/input-past-end-of-file.md | 26 +- ...d-resolution-runtime-errors-could-occur.md | 2 +- ...ot-be-used-as-operands-of-the-addressof.md | 8 +- .../name-name-is-not-declared.md | 4 +- .../some-subkeys-cannot-be-deleted.md | 14 +- .../error-messages/subscript-out-of-range.md | 16 +- ...er-is-unable-to-complete-read-operation.md | 16 +- ...type-of-variablename-cannot-be-inferred.md | 2 +- .../functions/conversion-functions.md | 18 +- .../functions/math-functions.md | 110 +- .../return-values-for-the-cstr-function.md | 28 +- .../functions/string-functions.md | 58 +- .../functions/type-conversion-functions.md | 34 +- .../keywords/arrays-summary.md | 20 +- .../keywords/collection-object-summary.md | 22 +- .../keywords/control-flow-summary.md | 22 +- .../keywords/conversion-summary.md | 34 +- .../keywords/data-types-summary.md | 18 +- .../keywords/dates-and-times-summary.md | 24 +- .../declarations-and-constants-summary.md | 30 +- .../keywords/directories-and-files-summary.md | 40 +- .../keywords/errors-summary.md | 24 +- .../keywords/financial-summary.md | 26 +- .../information-and-interaction-summary.md | 26 +- .../keywords/input-and-output-summary.md | 36 +- .../keywords/math-summary.md | 24 +- .../keywords/my-reference.md | 32 +- .../keywords/registry-summary.md | 22 +- .../keywords/string-manipulation-summary.md | 38 +- .../language-reference/modifiers/async.md | 2 +- .../modifiers/in-generic-modifier.md | 8 +- .../language-reference/modifiers/iterator.md | 80 +- .../language-reference/modifiers/key.md | 84 +- .../modifiers/out-generic-modifier.md | 2 +- .../language-reference/modifiers/shared.md | 6 +- .../language-reference/objects/index.md | 68 +- .../objects/my-computer-clipboard-object.md | 38 +- .../objects/my-forms-object.md | 8 +- .../objects/my-resources-object.md | 6 +- .../objects/my-user-object.md | 28 +- .../operators/await-operator.md | 10 +- .../operators/comparison-operators.md | 28 +- .../operators/ctype-operator.md | 16 +- .../operators/directcast-operator.md | 66 +- .../operators/gettype-operator.md | 92 +- .../operators/getxmlnamespace-operator.md | 2 +- .../operators/if-operator.md | 2 +- .../operators/like-operator.md | 176 +-- .../operators/mod-operator.md | 4 +- .../operators/null-conditional-operators.md | 2 +- .../language-reference/properties.md | 32 +- .../queries/aggregate-clause.md | 96 +- .../queries/select-clause.md | 80 +- .../runtime-library-members.md | 360 +++--- .../statements/class-statement.md | 182 +-- .../statements/const-statement.md | 14 +- .../statements/declare-statement.md | 2 +- .../statements/do-loop-statement.md | 2 +- .../statements/end-statement.md | 72 +- .../statements/enum-statement.md | 4 +- .../statements/error-statement.md | 104 +- .../statements/for-each-next-statement.md | 20 +- .../statements/for-next-statement.md | 2 +- .../statements/function-statement.md | 6 +- .../statements/if-then-else-statement.md | 4 +- .../statements/inherits-statement.md | 100 +- .../statements/mid-statement.md | 114 +- .../statements/of-clause.md | 84 +- .../statements/on-error-statement.md | 34 +- .../statements/option-compare-statement.md | 138 +- .../statements/raiseevent-statement.md | 104 +- .../statements/select-case-statement.md | 112 +- .../statements/sub-statement.md | 4 +- .../statements/throw-statement.md | 2 +- .../statements/try-catch-finally-statement.md | 10 +- .../statements/using-statement.md | 34 +- .../statements/while-end-while-statement.md | 2 +- .../statements/with-end-with-statement.md | 2 +- .../statements/yield-statement.md | 166 +-- .../xml-axis/extension-indexer-property.md | 86 +- .../xml-axis/xml-attribute-axis-property.md | 2 +- .../xml-axis/xml-child-axis-property.md | 2 +- .../xml-axis/xml-descendant-axis-property.md | 2 +- .../xml-axis/xml-value-property.md | 18 +- .../xml-literals/xml-cdata-literal.md | 90 +- .../xml-literals/xml-comment-literal.md | 84 +- .../xml-literals/xml-document-literal.md | 84 +- .../xml-literals/xml-element-literal.md | 2 +- .../xml-processing-instruction-literal.md | 96 +- ...er-cannot-be-nothing-or-an-empty-string.md | 16 +- ...-last-element-must-be-greater-than-zero.md | 20 +- ...eady-registered-a-source-with-this-name.md | 20 +- ...ent-basepath-must-be-a-path-to-a-folder.md | 18 +- ...me-cannot-be-nothing-or-an-empty-string.md | 20 +- docs/visual-basic/misc/bc30456.md | 22 +- docs/visual-basic/misc/bc30532.md | 20 +- docs/visual-basic/misc/bc30533.md | 20 +- docs/visual-basic/misc/bc30668.md | 24 +- docs/visual-basic/misc/bc30768.md | 24 +- docs/visual-basic/misc/bc30911.md | 32 +- docs/visual-basic/misc/bc30912.md | 28 +- docs/visual-basic/misc/bc30917.md | 24 +- docs/visual-basic/misc/bc30918.md | 28 +- docs/visual-basic/misc/bc30919.md | 24 +- docs/visual-basic/misc/bc30954.md | 28 +- docs/visual-basic/misc/bc31075.md | 20 +- docs/visual-basic/misc/bc31521.md | 26 +- docs/visual-basic/misc/bc31526.md | 32 +- docs/visual-basic/misc/bc31529.md | 32 +- docs/visual-basic/misc/bc31530.md | 28 +- docs/visual-basic/misc/bc32115.md | 26 +- docs/visual-basic/misc/bc36010.md | 24 +- docs/visual-basic/misc/bc36012.md | 24 +- docs/visual-basic/misc/bc36610.md | 28 +- docs/visual-basic/misc/bc36625.md | 60 +- docs/visual-basic/misc/bc40000.md | 28 +- docs/visual-basic/misc/bc40019.md | 36 +- docs/visual-basic/misc/bc40020.md | 32 +- docs/visual-basic/misc/bc41000.md | 26 +- docs/visual-basic/misc/bc41001.md | 28 +- docs/visual-basic/misc/bc41002.md | 32 +- docs/visual-basic/misc/bc41003.md | 28 +- docs/visual-basic/misc/bc41004.md | 32 +- docs/visual-basic/misc/bc41006.md | 32 +- ...annot-be-deleted-because-it-has-subkeys.md | 14 +- ...tlogsource-is-registered-to-another-log.md | 16 +- ...-argumentname-must-be-a-positive-number.md | 20 +- ...e-must-be-greater-than-or-equal-to-1000.md | 20 +- ...an-only-be-done-when-the-file-is-closed.md | 14 +- .../unable-to-obtain-a-stream-for-the-log.md | 28 +- ...uce-free-disk-space-below-reservedspace.md | 38 +- ...ld-cause-it-to-exceed-maximumsize-value.md | 38 +- .../walkthrough-office-programming.md | 4 +- .../concepts/async/async-return-types.md | 14 +- ...cancel-an-async-task-or-a-list-of-tasks.md | 6 +- ...ncel-async-tasks-after-a-period-of-time.md | 2 +- ...ining-async-tasks-after-one-is-complete.md | 12 +- .../async/control-flow-in-async-programs.md | 2 +- .../fine-tuning-your-async-application.md | 60 +- .../handling-reentrancy-in-async-apps.md | 4 +- ...async-walkthrough-by-using-task-whenall.md | 12 +- ...ts-in-parallel-by-using-async-and-await.md | 4 +- .../programming-guide/concepts/async/index.md | 18 +- ...tasks-and-process-them-as-they-complete.md | 390 +++--- .../async/using-async-for-file-access.md | 310 ++--- ...essing-the-web-by-using-async-and-await.md | 10 +- .../concepts/caller-information.md | 134 +- .../programming-guide/concepts/collections.md | 36 +- .../covariance-contravariance/index.md | 2 +- ...e-in-interfaces-for-generic-collections.md | 6 +- .../variance-in-delegates.md | 12 +- .../variance-in-generic-interfaces.md | 20 +- .../how-to-execute-expression-trees.md | 72 +- .../how-to-modify-expression-trees.md | 2 +- ...pression-trees-to-build-dynamic-queries.md | 28 +- .../concepts/expression-trees/index.md | 4 +- .../programming-guide/concepts/iterators.md | 16 +- .../concepts/linq/aggregation-operations.md | 116 +- .../concepts/linq/basic-query-operations.md | 268 ++-- ...-query-operators-by-manner-of-execution.md | 102 +- .../concepts/linq/concatenation-operations.md | 28 +- .../concepts/linq/converting-data-types.md | 22 +- .../concepts/linq/element-operations.md | 34 +- ...nabling-a-data-source-for-linq-querying.md | 16 +- .../concepts/linq/equality-operations.md | 16 +- .../linq/features-that-support-linq.md | 174 +-- .../concepts/linq/filtering-data.md | 4 +- .../concepts/linq/generation-operations.md | 26 +- .../concepts/linq/grouping-data.md | 106 +- ...-to-add-custom-methods-for-linq-queries.md | 18 +- ...e-column-values-in-a-csv-text-file-linq.md | 2 +- ...-occurrences-of-a-word-in-a-string-linq.md | 2 +- ...e-set-difference-between-two-lists-linq.md | 90 +- .../how-to-group-files-by-extension-linq.md | 170 +-- .../how-to-query-an-arraylist-with-linq.md | 4 +- ...ssembly-s-metadata-with-reflection-linq.md | 54 +- ...o-query-for-characters-in-a-string-linq.md | 2 +- ...s-that-contain-a-specified-set-of-words.md | 4 +- ...rgest-file-or-files-in-a-directory-tree.md | 218 ++-- ...tal-number-of-bytes-in-a-set-of-folders.md | 126 +- ...-reorder-the-fields-of-a-delimited-file.md | 2 +- .../concepts/linq/introduction-to-linq.md | 48 +- .../concepts/linq/join-operations.md | 34 +- .../concepts/linq/linq-and-strings.md | 98 +- .../concepts/linq/linq-to-objects.md | 68 +- .../concepts/linq/partitioning-data.md | 88 +- .../concepts/linq/projection-operations.md | 8 +- .../concepts/linq/quantifier-operations.md | 54 +- ...ion-syntax-for-standard-query-operators.md | 64 +- .../concepts/linq/set-operations.md | 14 +- .../concepts/linq/sorting-data.md | 10 +- .../linq/standard-query-operators-overview.md | 14 +- .../type-relationships-in-query-operations.md | 2 +- .../linq/writing-your-first-linq-query.md | 12 +- .../arrays/array-dimensions.md | 4 +- .../arrays/how-to-sort-an-array.md | 8 +- .../language-features/arrays/index.md | 30 +- .../arrays/troubleshooting-arrays.md | 90 +- ...method-used-by-a-collection-initializer.md | 30 +- .../collection-initializers/index.md | 6 +- ...ng-associated-with-an-enumeration-value.md | 22 +- .../how-to-iterate-through-an-enumeration.md | 18 +- ...lkthrough-implementing-ienumerable-of-t.md | 48 +- ...ersions-between-strings-and-other-types.md | 52 +- .../data-types/efficient-use-of-data-types.md | 10 +- .../data-types/generic-procedures.md | 82 +- .../data-types/generic-types.md | 8 +- .../data-types/how-to-use-a-generic-class.md | 34 +- .../data-types/nullable-value-types.md | 16 +- .../data-types/structures-and-classes.md | 144 +-- .../data-types/troubleshooting-data-types.md | 10 +- .../language-features/data-types/tuples.md | 2 +- .../value-types-and-reference-types.md | 116 +- ...-property-or-method-using-a-string-name.md | 56 +- .../determining-object-type.md | 60 +- .../early-late-binding/index.md | 36 +- ...ough-creating-and-using-dynamic-objects.md | 4 +- ...declare-custom-events-to-avoid-blocking.md | 32 +- ...alkthrough-declaring-and-raising-events.md | 118 +- ...o-call-a-stored-procedure-by-using-linq.md | 2 +- ...modify-data-in-a-database-by-using-linq.md | 2 +- .../linq/introduction-to-linq.md | 276 ++-- .../anonymous-type-definition.md | 4 +- .../objects-and-classes/anonymous-types.md | 236 ++-- ...nd-types-in-anonymous-type-declarations.md | 2 +- .../objects-and-classes/index.md | 14 +- ...e-how-objects-are-created-and-destroyed.md | 16 +- .../arithmetic-operators.md | 158 +-- .../procedures/function-procedures.md | 2 +- ...-procedure-that-does-not-return-a-value.md | 32 +- ...o-call-a-procedure-that-returns-a-value.md | 62 +- .../how-to-call-a-property-procedure.md | 74 +- .../how-to-create-a-lambda-expression.md | 186 +-- ...-to-declare-and-call-a-default-property.md | 130 +- .../how-to-pass-arguments-to-a-procedure.md | 54 +- .../how-to-put-a-value-in-a-property.md | 40 +- ...w-to-use-a-class-that-defines-operators.md | 46 +- .../procedures/parameter-arrays.md | 82 +- .../strings/how-culture-affects-strings.md | 140 +- .../how-to-access-characters-in-strings.md | 36 +- ...vert-a-string-to-an-array-of-characters.md | 26 +- ...convert-an-array-of-bytes-into-a-string.md | 52 +- ...-convert-hexadecimal-strings-to-numbers.md | 6 +- ...-convert-strings-into-an-array-of-bytes.md | 52 +- .../strings/how-to-search-within-a-string.md | 10 +- .../how-to-validate-file-names-and-paths.md | 18 +- ...e-strings-that-represent-dates-or-times.md | 28 +- .../strings/interpolated-strings.md | 2 +- .../types-of-string-manipulation-methods.md | 4 +- ...ressions-with-the-maskedtextbox-control.md | 92 +- .../zero-based-vs-one-based-string-access.md | 26 +- .../how-to-access-members-of-an-object.md | 2 +- ...-what-type-an-object-variable-refers-to.md | 10 +- ...termine-whether-two-objects-are-related.md | 16 +- .../variables/object-variable-values.md | 110 +- .../xml/how-to-access-xml-attributes.md | 14 +- .../xml/how-to-access-xml-child-elements.md | 24 +- .../how-to-access-xml-descendant-elements.md | 24 +- ...-declare-and-use-xml-namespace-prefixes.md | 24 +- ...o-load-xml-from-a-file-string-or-stream.md | 14 +- .../xml/how-to-modify-xml-literals.md | 14 +- .../xml/how-to-transform-xml-by-using-linq.md | 4 +- .../program-structure/main-procedure.md | 8 +- .../program-structure/naming-conventions.md | 46 +- .../command-line-compiler/resource.md | 70 +- .../command-line-compiler/rootnamespace.md | 2 +- docs/visual-basic/whats-new/index.md | 2 +- 2644 files changed, 48958 insertions(+), 48958 deletions(-) diff --git a/docs/architecture/blazor-for-web-forms-developers/config.md b/docs/architecture/blazor-for-web-forms-developers/config.md index 8586d9f3ea1d4..ea637371f2dbe 100644 --- a/docs/architecture/blazor-for-web-forms-developers/config.md +++ b/docs/architecture/blazor-for-web-forms-developers/config.md @@ -144,7 +144,7 @@ Individual configuration settings can be read by specifying the configuration se var mySetting = Configuration["section1:key0"]; ``` -You can fetch entire configuration sections by using the method to retrieve a collection of keys at a specific location with a syntax similar to `GetSection("section1")` to retrieve the configuration for section1 from the earlier example. +You can fetch entire configuration sections by using the method to retrieve a collection of keys at a specific location with a syntax similar to `GetSection("section1")` to retrieve the configuration for section1 from the earlier example. ## Strongly typed configuration diff --git a/docs/architecture/cloud-native/infrastructure-resiliency-azure.md b/docs/architecture/cloud-native/infrastructure-resiliency-azure.md index 71adb7a11543b..6415087e81685 100644 --- a/docs/architecture/cloud-native/infrastructure-resiliency-azure.md +++ b/docs/architecture/cloud-native/infrastructure-resiliency-azure.md @@ -89,7 +89,7 @@ We encouraged the best practice of implementing programmatic retry operations in - *Azure Redis Cache.* The Redis StackExchange client uses a connection manager class that includes retries on failed attempts. The number of retries, specific retry policy and wait time are all configurable. -- *Azure Service Bus.* The Service Bus client exposes a [RetryPolicy class](xref:Microsoft.ServiceBus.RetryPolicy) that can be configured with a back-off interval, retry count, and , which specifies the maximum time an operation can take. The default policy is nine maximum retry attempts with a 30-second backoff period between attempts. +- *Azure Service Bus.* The Service Bus client exposes a [RetryPolicy class](xref:Microsoft.ServiceBus.RetryPolicy) that can be configured with a back-off interval, retry count, and , which specifies the maximum time an operation can take. The default policy is nine maximum retry attempts with a 30-second backoff period between attempts. - *Azure SQL Database.* Retry support is provided when using the [Entity Framework Core](/ef/core/miscellaneous/connection-resiliency) library. diff --git a/docs/architecture/maui/validation.md b/docs/architecture/maui/validation.md index 9f4b0c2c2de5b..1b15db1575f84 100644 --- a/docs/architecture/maui/validation.md +++ b/docs/architecture/maui/validation.md @@ -105,7 +105,7 @@ public class EmailRule : IValidationRule } ``` -The `Check` method returns a boolean indicating whether or not the value argument is a valid email address. This is achieved by searching the value argument for the first occurrence of the regular expression pattern specified in the `Regex` constructor. Whether the regular expression pattern has been found in the input string can be determined by checking the `value` against . +The `Check` method returns a boolean indicating whether or not the value argument is a valid email address. This is achieved by searching the value argument for the first occurrence of the regular expression pattern specified in the `Regex` constructor. Whether the regular expression pattern has been found in the input string can be determined by checking the `value` against . > [!NOTE] > Property validation can sometimes involve dependent properties. An example of dependent properties is when the set of valid values for property A depends on the particular value that has been set in property B. To check that the value of property A is one of the allowed values would involve retrieving the value of property B. In addition, when the value of property B changes, property A would need to be revalidated. @@ -224,7 +224,7 @@ The eShop multi-platform app notifies the user of any validation errors by highl Command="{Binding ValidateCommand}" /> - diff --git a/docs/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests.md b/docs/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests.md index 164cedd628ffd..b775c7e5c38c7 100644 --- a/docs/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests.md +++ b/docs/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests.md @@ -66,9 +66,9 @@ The following diagram shows how Typed Clients are used with `IHttpClientFactory` **Figure 8-4**. Using `IHttpClientFactory` with Typed Client classes. -In the above image, a `ClientService` (used by a controller or client code) uses an `HttpClient` created by the registered `IHttpClientFactory`. This factory assigns an `HttpMessageHandler` from a pool to the `HttpClient`. The `HttpClient` can be configured with Polly's policies when registering the `IHttpClientFactory` in the DI container with the extension method . +In the above image, a `ClientService` (used by a controller or client code) uses an `HttpClient` created by the registered `IHttpClientFactory`. This factory assigns an `HttpMessageHandler` from a pool to the `HttpClient`. The `HttpClient` can be configured with Polly's policies when registering the `IHttpClientFactory` in the DI container with the extension method . -To configure the above structure, add in your application by installing the `Microsoft.Extensions.Http` NuGet package that includes the extension method for . This extension method registers the internal `DefaultHttpClientFactory` class to be used as a singleton for the interface `IHttpClientFactory`. It defines a transient configuration for the . This message handler ( object), taken from a pool, is used by the `HttpClient` returned from the factory. +To configure the above structure, add in your application by installing the `Microsoft.Extensions.Http` NuGet package that includes the extension method for . This extension method registers the internal `DefaultHttpClientFactory` class to be used as a singleton for the interface `IHttpClientFactory`. It defines a transient configuration for the . This message handler ( object), taken from a pool, is used by the `HttpClient` returned from the factory. In the next snippet, you can see how `AddHttpClient()` can be used to register Typed Clients (Service Agents) that need to use `HttpClient`. diff --git a/docs/architecture/microservices/microservice-ddd-cqrs-patterns/domain-model-layer-validations.md b/docs/architecture/microservices/microservice-ddd-cqrs-patterns/domain-model-layer-validations.md index dd994461978f7..e14b5626a262a 100644 --- a/docs/architecture/microservices/microservice-ddd-cqrs-patterns/domain-model-layer-validations.md +++ b/docs/architecture/microservices/microservice-ddd-cqrs-patterns/domain-model-layer-validations.md @@ -50,7 +50,7 @@ A similar approach can be used in the entity's constructor, raising an exception ### Use validation attributes in the model based on data annotations -Data annotations, like the Required or MaxLength attributes, can be used to configure EF Core database field properties, as explained in detail in the [Table mapping](infrastructure-persistence-layer-implementation-entity-framework-core.md#table-mapping) section, but [they no longer work for entity validation in EF Core](https://github.com/dotnet/efcore/issues/3680) (neither does the method), as they have done since EF 4.x in .NET Framework. +Data annotations, like the Required or MaxLength attributes, can be used to configure EF Core database field properties, as explained in detail in the [Table mapping](infrastructure-persistence-layer-implementation-entity-framework-core.md#table-mapping) section, but [they no longer work for entity validation in EF Core](https://github.com/dotnet/efcore/issues/3680) (neither does the method), as they have done since EF 4.x in .NET Framework. Data annotations and the interface can still be used for model validation during model binding, prior to the controller's actions invocation as usual, but that model is meant to be a ViewModel or DTO and that's an MVC or API concern not a domain model concern. diff --git a/docs/architecture/microservices/multi-container-microservice-net-applications/background-tasks-with-ihostedservice.md b/docs/architecture/microservices/multi-container-microservice-net-applications/background-tasks-with-ihostedservice.md index a427eff8e3040..d2119fb3b3250 100644 --- a/docs/architecture/microservices/multi-container-microservice-net-applications/background-tasks-with-ihostedservice.md +++ b/docs/architecture/microservices/multi-container-microservice-net-applications/background-tasks-with-ihostedservice.md @@ -41,7 +41,7 @@ SignalR is one example of an artifact using hosted services, but you can also us You can basically offload any of those actions to a background task that implements `IHostedService`. -The way you add one or multiple `IHostedServices` into your `WebHost` or `Host` is by registering them up through the  extension method in an ASP.NET Core `WebHost` (or in a `Host` in .NET Core 2.1 and above). Basically, you have to register the hosted services within application startup in _Program.cs_. +The way you add one or multiple `IHostedServices` into your `WebHost` or `Host` is by registering them up through the  extension method in an ASP.NET Core `WebHost` (or in a `Host` in .NET Core 2.1 and above). Basically, you have to register the hosted services within application startup in _Program.cs_. ```csharp //Other DI registrations; diff --git a/docs/architecture/microservices/secure-net-microservices-web-applications/authorization-net-microservices-web-applications.md b/docs/architecture/microservices/secure-net-microservices-web-applications/authorization-net-microservices-web-applications.md index d31c6d5694676..0580f0c96606f 100644 --- a/docs/architecture/microservices/secure-net-microservices-web-applications/authorization-net-microservices-web-applications.md +++ b/docs/architecture/microservices/secure-net-microservices-web-applications/authorization-net-microservices-web-applications.md @@ -94,13 +94,13 @@ As shown in the example, policies can be associated with different types of requ In the previous example, the first AddPolicy call is just an alternative way of authorizing by role. If `[Authorize(Policy="AdministratorsOnly")]` is applied to an API, only users in the Administrator role will be able to access it. -The second call demonstrates an easy way to require that a particular claim should be present for the user. The method also optionally takes expected values for the claim. If values are specified, the requirement is met only if the user has both a claim of the correct type and one of the specified values. If you're using the JWT bearer authentication middleware, all JWT properties will be available as user claims. +The second call demonstrates an easy way to require that a particular claim should be present for the user. The method also optionally takes expected values for the claim. If values are specified, the requirement is met only if the user has both a claim of the correct type and one of the specified values. If you're using the JWT bearer authentication middleware, all JWT properties will be available as user claims. The most interesting policy shown here is in the third `AddPolicy` method, because it uses a custom authorization requirement. By using custom authorization requirements, you can have a great deal of control over how authorization is performed. For this to work, you must implement these types: - A Requirements type that derives from and that contains fields specifying the details of the requirement. In the example, this is an age field for the sample `MinimumAgeRequirement` type. -- A handler that implements , where T is the type of that the handler can satisfy. The handler must implement the method, which checks whether a specified context that contains information about the user satisfies the requirement. +- A handler that implements , where T is the type of that the handler can satisfy. The handler must implement the method, which checks whether a specified context that contains information about the user satisfies the requirement. If the user meets the requirement, a call to `context.Succeed` will indicate that the user is authorized. If there are multiple ways that a user might satisfy an authorization requirement, multiple handlers can be created. diff --git a/docs/architecture/microservices/secure-net-microservices-web-applications/index.md b/docs/architecture/microservices/secure-net-microservices-web-applications/index.md index 65943faba86f3..b0469abe6dace 100644 --- a/docs/architecture/microservices/secure-net-microservices-web-applications/index.md +++ b/docs/architecture/microservices/secure-net-microservices-web-applications/index.md @@ -217,7 +217,7 @@ If you prefer to issue security tokens for local ASP.NET Core Identity users rat - The storage mechanism for user information, such as [ASP.NET Core Identity](https://identityserver4.readthedocs.io/en/latest/quickstarts/0_overview.html) or an alternative. -When you specify clients and resources for IdentityServer4 to use, you can pass an collection of the appropriate type to methods that take in-memory client or resource stores. Or for more complex scenarios, you can provide client or resource provider types via Dependency Injection. +When you specify clients and resources for IdentityServer4 to use, you can pass an collection of the appropriate type to methods that take in-memory client or resource stores. Or for more complex scenarios, you can provide client or resource provider types via Dependency Injection. A sample configuration for IdentityServer4 to use in-memory resources and clients provided by a custom IClientStore type might look like the following example: diff --git a/docs/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps.md b/docs/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps.md index 4cc5a6a499e9c..35de18d6eab35 100644 --- a/docs/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps.md +++ b/docs/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps.md @@ -533,7 +533,7 @@ In web-based authentication, there are typically up to five actions that may be There are a number of common techniques for performing authentication in web applications. These are referred to as schemes. A given scheme will define actions for some or all of the above options. Some schemes only support a subset of actions, and may require a separate scheme to perform those it does not support. For example, the OpenId-Connect (OIDC) scheme doesn't support Sign-in or Sign-out, but is commonly configured to use Cookie authentication for this persistence. -In your ASP.NET Core application, you can configure a `DefaultAuthenticateScheme` as well as optional specific schemes for each of the actions described above. For example, `DefaultChallengeScheme` and `DefaultForbidScheme`. Calling configures a number of aspects of the application and adds many required services. It also includes this call to configure the authentication scheme: +In your ASP.NET Core application, you can configure a `DefaultAuthenticateScheme` as well as optional specific schemes for each of the actions described above. For example, `DefaultChallengeScheme` and `DefaultForbidScheme`. Calling configures a number of aspects of the application and adds many required services. It also includes this call to configure the authentication scheme: ```csharp builder.Services.AddAuthentication(options => diff --git a/docs/architecture/modern-web-apps-azure/work-with-data-in-asp-net-core-apps.md b/docs/architecture/modern-web-apps-azure/work-with-data-in-asp-net-core-apps.md index 7dde778f799d1..73e05819fb223 100644 --- a/docs/architecture/modern-web-apps-azure/work-with-data-in-asp-net-core-apps.md +++ b/docs/architecture/modern-web-apps-azure/work-with-data-in-asp-net-core-apps.md @@ -278,7 +278,7 @@ The first DbContext is the `_catalogContext` and the second DbContext is within While EF Core is a great choice for managing persistence, and for the most part encapsulates database details from application developers, it isn't the only choice. Another popular open-source alternative is [Dapper](https://github.com/StackExchange/Dapper), a so-called micro-ORM. A micro-ORM is a lightweight, less full-featured tool for mapping objects to data structures. In the case of Dapper, its design goals focus on performance, rather than fully encapsulating the underlying queries it uses to retrieve and update data. Because it doesn't abstract SQL from the developer, Dapper is "closer to the metal" and lets developers write the exact queries they want to use for a given data access operation. -EF Core has two significant features it provides which separate it from Dapper but also add to its performance overhead. The first is the translation from LINQ expressions into SQL. These translations are cached, but even so there is overhead in performing them the first time. The second is change tracking on entities (so that efficient update statements can be generated). This behavior can be turned off for specific queries by using the extension. EF Core also generates SQL queries that usually are very efficient and in any case perfectly acceptable from a performance standpoint, but if you need fine control over the precise query to be executed, you can pass in custom SQL (or execute a stored procedure) using EF Core, too. In this case, Dapper still outperforms EF Core, but only very slightly. Current performance benchmark data for a variety of data access methods can be found on [the Dapper site](https://github.com/StackExchange/Dapper). +EF Core has two significant features it provides which separate it from Dapper but also add to its performance overhead. The first is the translation from LINQ expressions into SQL. These translations are cached, but even so there is overhead in performing them the first time. The second is change tracking on entities (so that efficient update statements can be generated). This behavior can be turned off for specific queries by using the extension. EF Core also generates SQL queries that usually are very efficient and in any case perfectly acceptable from a performance standpoint, but if you need fine control over the precise query to be executed, you can pass in custom SQL (or execute a stored procedure) using EF Core, too. In this case, Dapper still outperforms EF Core, but only very slightly. Current performance benchmark data for a variety of data access methods can be found on [the Dapper site](https://github.com/StackExchange/Dapper). To see how the syntax for Dapper varies from EF Core, consider these two versions of the same method for retrieving a list of items: diff --git a/docs/azure/sdk/aspnetcore-guidance.md b/docs/azure/sdk/aspnetcore-guidance.md index 7bf1fc58e02cb..f1a2c37666c9d 100644 --- a/docs/azure/sdk/aspnetcore-guidance.md +++ b/docs/azure/sdk/aspnetcore-guidance.md @@ -45,7 +45,7 @@ Complete the following steps to register the services you need: dotnet add package Azure.Messaging.ServiceBus ``` -3. In the `Program.cs` file of your app, invoke the extension method from the `Microsoft.Extensions.Azure` library to register a client to communicate with each Azure service. Some client libraries provide additional [subclients](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-subclients) for specific subgroups of Azure service functionality. You can register such subclients for dependency injection via the extension method. +3. In the `Program.cs` file of your app, invoke the extension method from the `Microsoft.Extensions.Azure` library to register a client to communicate with each Azure service. Some client libraries provide additional [subclients](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-subclients) for specific subgroups of Azure service functionality. You can register such subclients for dependency injection via the extension method. :::code language="csharp" source="snippets/aspnetcore-guidance/BlazorSample/Program.cs" range="11-30" highlight="4-7,13-15"::: @@ -80,7 +80,7 @@ Use the [Azure Identity](/dotnet/api/overview/azure/identity-readme) library for dotnet add package Azure.Identity ``` -1. In the `Program.cs` file of your app, invoke the extension method from the `Microsoft.Extensions.Azure` library to set a shared `DefaultAzureCredential` instance for all registered Azure service clients: +1. In the `Program.cs` file of your app, invoke the extension method from the `Microsoft.Extensions.Azure` library to set a shared `DefaultAzureCredential` instance for all registered Azure service clients: :::code language="csharp" source="snippets/aspnetcore-guidance/BlazorSample/Program.cs" range="11-30" ::: @@ -126,7 +126,7 @@ You may want to change default Azure client configurations globally or for a spe ## Configure logging -The Azure SDK for .NET client libraries can log client library operations to monitor requests and responses to Azure services. Client libraries can also log a variety of other events, including retries, token retrieval, and service-specific events from various clients. When you register an Azure SDK client using the extension method, the is registered with the dependency injection container. The `AzureEventSourceLogForwarder` forwards log messages from Azure SDK event sources to to enables you to use the standard ASP.NET Core logging configuration for logging. +The Azure SDK for .NET client libraries can log client library operations to monitor requests and responses to Azure services. Client libraries can also log a variety of other events, including retries, token retrieval, and service-specific events from various clients. When you register an Azure SDK client using the extension method, the is registered with the dependency injection container. The `AzureEventSourceLogForwarder` forwards log messages from Azure SDK event sources to to enables you to use the standard ASP.NET Core logging configuration for logging. The following table depicts how the Azure SDK for .NET `EventLevel` maps to the ASP.NET Core `LogLevel`. For more information on these topics and other scenarios, see [Logging with the Azure SDK for .NET](logging.md) and [Dependency injection with the Azure SDK for .NET](dependency-injection.md). diff --git a/docs/azure/sdk/authentication/best-practices.md b/docs/azure/sdk/authentication/best-practices.md index 15b889fd623ff..4dd61c7b792fa 100644 --- a/docs/azure/sdk/authentication/best-practices.md +++ b/docs/azure/sdk/authentication/best-practices.md @@ -45,7 +45,7 @@ The recommended credential reuse strategy differs by .NET application type. # [ASP.NET Core](#tab/aspdotnet) -To implement credential reuse, use the method from `Microsoft.Extensions.Azure`. Consider an ASP.NET Core app hosted on Azure App Service in both production and staging environments. Environment variable `ASPNETCORE_ENVIRONMENT` is set to either `Production` or `Staging` to differentiate between these two non-development environments. In both production and staging, the user-assigned variant of `ManagedIdentityCredential` is used to authenticate the Key Vault Secrets and Blob Storage clients. +To implement credential reuse, use the method from `Microsoft.Extensions.Azure`. Consider an ASP.NET Core app hosted on Azure App Service in both production and staging environments. Environment variable `ASPNETCORE_ENVIRONMENT` is set to either `Production` or `Staging` to differentiate between these two non-development environments. In both production and staging, the user-assigned variant of `ManagedIdentityCredential` is used to authenticate the Key Vault Secrets and Blob Storage clients. When the app runs on a local development machine, where `ASPNETCORE_ENVIRONMENT` is set to `Development`, a chained sequence of developer tool credentials is used instead. This approach ensures environment-appropriate credentials are used, enhancing security and simplifying credential management. @@ -65,7 +65,7 @@ In non-ASP.NET Core apps, credential reuse is accomplished by passing the same c If you use an Azure Identity library credential outside the context of [an Azure SDK client library that depends on Azure Core](../packages.md#libraries-using-azurecore), it becomes your responsibility to manage [token lifetime](/entra/identity-platform/access-tokens#token-lifetime) and caching behavior in your app. -The property on `AccessToken`, which provides a hint to consumers as to when token refresh can be attempted, will be automatically used by Azure SDK client libraries that depend on the Azure Core library to refresh the token. For direct usage of Azure Identity library [credentials that support token caching](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/samples/TokenCache.md#credentials-supporting-token-caching), the underlying MSAL cache automatically refreshes proactively when the `RefreshOn` time occurs. This design allows the client code to call `GetToken` each time a token is needed and delegate the refresh to the library. +The property on `AccessToken`, which provides a hint to consumers as to when token refresh can be attempted, will be automatically used by Azure SDK client libraries that depend on the Azure Core library to refresh the token. For direct usage of Azure Identity library [credentials that support token caching](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/samples/TokenCache.md#credentials-supporting-token-caching), the underlying MSAL cache automatically refreshes proactively when the `RefreshOn` time occurs. This design allows the client code to call `GetToken` each time a token is needed and delegate the refresh to the library. To only call `GetToken` when necessary, observe the `RefreshOn` date and proactively attempt to refresh the token after that time. The specific implementation is up to the customer. @@ -86,7 +86,7 @@ The Azure Identity library for .NET allows you to authenticate via managed ident - **When to use:** For production scenarios where resilience is important - **How to activate:** Take one of the following approaches: - Use `DefaultAzureCredential` with environment variable `AZURE_TOKEN_CREDENTIALS` set to `ManagedIdentityCredential` - + > [!IMPORTANT] > This `DefaultAzureCredential` approach only operates in resilient mode when using `Azure.Identity` package version 1.16.0 or later. In earlier versions, this approach operates in "fail fast" mode. @@ -94,7 +94,7 @@ The Azure Identity library for .NET allows you to authenticate via managed ident - Use `ManagedIdentityCredential` directly - **How it works:** The time interval between retries starts at 0.8 seconds, and a maximum of five retries are attempted with exponential backoff, by default. This mode is optimized for resilience but introduces potentially unwanted delays in the development inner loop. - To change the default retry settings, use the property on `DefaultAzureCredentialOptions` or `ManagedIdentityCredentialOptions`. For example, retry a maximum of three times, with a starting interval of 0.5 seconds: + To change the default retry settings, use the property on `DefaultAzureCredentialOptions` or `ManagedIdentityCredentialOptions`. For example, retry a maximum of three times, with a starting interval of 0.5 seconds: :::code language="csharp" source="../snippets/authentication/best-practices/CCA/Program.cs" id="snippet_retries" highlight="5-9"::: diff --git a/docs/azure/sdk/authentication/create-token-credentials-from-configuration.md b/docs/azure/sdk/authentication/create-token-credentials-from-configuration.md index 58112c00ed7bd..48bfa7b2f5dba 100644 --- a/docs/azure/sdk/authentication/create-token-credentials-from-configuration.md +++ b/docs/azure/sdk/authentication/create-token-credentials-from-configuration.md @@ -25,7 +25,7 @@ The following credentials can be created via configuration: ## Configure Azure credentials -Azure service clients registered with the method are automatically configured with an instance of `DefaultAzureCredential` if no explicit credential is supplied via the extension method. You can also override the global `DefaultAzureCredential` using credential values from configuration files when registering a client to create a specific credential: +Azure service clients registered with the method are automatically configured with an instance of `DefaultAzureCredential` if no explicit credential is supplied via the extension method. You can also override the global `DefaultAzureCredential` using credential values from configuration files when registering a client to create a specific credential: ```csharp builder.Services.AddAzureClients(clientBuilder => @@ -114,7 +114,7 @@ The resource ID takes the form { "credential": "managedidentity", "managedIdentityObjectId": "" -} +} ``` > [!IMPORTANT] diff --git a/docs/azure/sdk/authentication/credential-chains.md b/docs/azure/sdk/authentication/credential-chains.md index 944f5c06fe996..543e7a608c40f 100644 --- a/docs/azure/sdk/authentication/credential-chains.md +++ b/docs/azure/sdk/authentication/credential-chains.md @@ -88,7 +88,7 @@ In the preceding code sample, `EnvironmentCredential`, `ManagedIdentityCredentia :::image type="content" source="../media/mermaidjs/default-azure-credential-excludes.svg" alt-text="DefaultAzureCredential using Excludes properties"::: > [!NOTE] -> `InteractiveBrowserCredential` is excluded by default and therefore isn't shown in the preceding diagram. To include `InteractiveBrowserCredential`, either pass `true` to constructor or set property to `false`. +> `InteractiveBrowserCredential` is excluded by default and therefore isn't shown in the preceding diagram. To include `InteractiveBrowserCredential`, either pass `true` to constructor or set property to `false`. As more `Exclude`-prefixed properties are set to `true` (credential exclusions are configured), the advantages of using `DefaultAzureCredential` diminish. In such cases, `ChainedTokenCredential` is a better choice and requires less code. To illustrate, these two code samples behave the same way: diff --git a/docs/azure/sdk/authentication/local-development-broker.md b/docs/azure/sdk/authentication/local-development-broker.md index 6a2b9376a4652..42af9a51e69e1 100644 --- a/docs/azure/sdk/authentication/local-development-broker.md +++ b/docs/azure/sdk/authentication/local-development-broker.md @@ -104,7 +104,7 @@ The Azure Identity library provide interactive brokered authentication using [!TIP] > View the [complete sample app code](https://github.com/dotnet/docs/tree/main/docs/azure/sdk/snippets/authentication/brokered) in the .NET docs GitHub repository. -In the preceding example, property is set to `true`, which opts into a silent, brokered authentication flow with the default system account. In this way, the user doesn't have to repeatedly select the same account. If silent, brokered authentication fails, or `UseDefaultBrokerAccount` is set to `false`, `InteractiveBrowserCredential` falls back to interactive, brokered authentication. +In the preceding example, property is set to `true`, which opts into a silent, brokered authentication flow with the default system account. In this way, the user doesn't have to repeatedly select the same account. If silent, brokered authentication fails, or `UseDefaultBrokerAccount` is set to `false`, `InteractiveBrowserCredential` falls back to interactive, brokered authentication. :::zone target="docs" pivot="os-windows" diff --git a/docs/azure/sdk/configure-proxy.md b/docs/azure/sdk/configure-proxy.md index 5d857c56c62c9..804bfde41876c 100644 --- a/docs/azure/sdk/configure-proxy.md +++ b/docs/azure/sdk/configure-proxy.md @@ -1,5 +1,5 @@ --- -title: Configure a proxy when using the Azure SDK for .NET +title: Configure a proxy when using the Azure SDK for .NET description: Learn different approaches for configuring a proxy for use with the Azure SDK for .NET client libraries. ms.topic: concept-article ms.custom: devx-track-dotnet, engagement-fy23 @@ -20,7 +20,7 @@ The proxy can be configured via code or via an environment variable. The approac To programmatically configure a proxy, complete the following steps: 1. Create an object whose `Proxy` property is set. -1. Create a service client options object whose property is set to an `HttpClientTransport` object accepting the `HttpClientHandler` instance. +1. Create a service client options object whose property is set to an `HttpClientTransport` object accepting the `HttpClientHandler` instance. 1. Pass the service client options object to the service client constructor. Using the Azure Key Vault Secrets library as an example, you'd have the following code: diff --git a/docs/azure/sdk/dependency-injection.md b/docs/azure/sdk/dependency-injection.md index fb1f859f675d3..c4af08efc5556 100644 --- a/docs/azure/sdk/dependency-injection.md +++ b/docs/azure/sdk/dependency-injection.md @@ -39,7 +39,7 @@ dotnet add package OpenAI A service client is the entry point to the API for an Azure service – from it, library users can invoke all operations the service provides and can easily implement the most common scenarios. Where it will simplify an API's design, groups of service calls can be organized around smaller subclient types. For example, `ServiceBusClient` can register additional `ServiceBusSender` subclients for publishing messages or `ServiceBusReceiver` subclients for consuming messages. -In the *Program.cs* file, invoke the extension method to register a client for each service. The following code samples provide guidance on application builders from the `Microsoft.AspNetCore.Builder` and `Microsoft.Extensions.Hosting` namespaces. +In the *Program.cs* file, invoke the extension method to register a client for each service. The following code samples provide guidance on application builders from the `Microsoft.AspNetCore.Builder` and `Microsoft.Extensions.Hosting` namespaces. ### [WebApplicationBuilder](#tab/web-app-builder) @@ -57,10 +57,10 @@ In the *Program.cs* file, invoke the , and , respectively. The `Uri`- and `string`-typed arguments are passed. To avoid specifying these URLs explicitly, see the [Store configuration separately from code](#store-configuration-separately-from-code) section. +* Key Vault Secrets, Blob Storage, and Service Bus clients are registered using the , and , respectively. The `Uri`- and `string`-typed arguments are passed. To avoid specifying these URLs explicitly, see the [Store configuration separately from code](#store-configuration-separately-from-code) section. * Each registered client automatically uses for `TokenCredential` unless you configure a different type of credential (for example, using `WithCredential`). * Service Bus subclients are registered for each queue on the service using the subclient and corresponding options types. The queue names for the subclients are retrieved using a separate method outside of the service registration because the `GetQueuesAsync` method must be run asynchronously. -* A `ResponsesClient` is registered using a custom client factory via the method, which provides control over how a client instance is created. Custom client factories are useful in the following cases: +* A `ResponsesClient` is registered using a custom client factory via the method, which provides control over how a client instance is created. Custom client factories are useful in the following cases: * You need to use other dependencies during the client construction. * A registration extension method doesn't exist for the service client you want to register. @@ -209,7 +209,7 @@ In the preceding JSON sample: ## Configure multiple service clients with different names -Imagine you have two storage accounts: one for private information and another for public information. Your app transfers data from the public to the private storage account after some operation. You need to have two storage service clients. To differentiate those two clients, use the extension method: +Imagine you have two storage accounts: one for private information and another for public information. Your app transfers data from the public to the private storage account after some operation. You need to have two storage service clients. To differentiate those two clients, use the extension method: ```csharp builder.Services.AddAzureClients(clientBuilder => @@ -223,7 +223,7 @@ builder.Services.AddAzureClients(clientBuilder => }); ``` -Using an ASP.NET Core controller as an example, access the named service client using the interface: +Using an ASP.NET Core controller as an example, access the named service client using the interface: ```csharp public class HomeController : Controller diff --git a/docs/azure/sdk/logging.md b/docs/azure/sdk/logging.md index 30313d1038b86..85572897242ae 100644 --- a/docs/azure/sdk/logging.md +++ b/docs/azure/sdk/logging.md @@ -64,7 +64,7 @@ The SDK includes the extension method: +1. In *Program.cs*, register the Azure SDK library's client via a call to the extension method: ```csharp using Azure.Identity; using Microsoft.Extensions.Azure; - + // code omitted for brevity - + builder.Services.AddAzureClients(azureBuilder => { azureBuilder.AddServiceBusClient( @@ -177,7 +177,7 @@ In these scenarios, complete the following steps: :::code language="csharp" source="snippets/logging/Program.cs" id="RegisterServiceWithDI" highlight="8"::: -1. Fetch the log forwarder service from the DI container and invoke its method. For example, using constructor injection in an ASP.NET Core Razor Pages page model class: +1. Fetch the log forwarder service from the DI container and invoke its method. For example, using constructor injection in an ASP.NET Core Razor Pages page model class: :::code language="csharp" source="snippets/logging/Pages/Index.cshtml.cs" id="FetchServiceAndStart" highlight="6-7"::: @@ -225,12 +225,12 @@ When troubleshooting unexpected behavior with a client library, it's helpful to By default, logging of the aforementioned content is disabled. To enable logging of the HTTP request and response bodies, complete the following steps: -1. Set the client options object's property to `true`, and pass the options object to the client's constructor. For example, to log HTTP requests and responses for the Azure Key Vault Secrets library: +1. Set the client options object's property to `true`, and pass the options object to the client's constructor. For example, to log HTTP requests and responses for the Azure Key Vault Secrets library: ```csharp var clientOptions = new SecretClientOptions { - Diagnostics = + Diagnostics = { IsLoggingContentEnabled = true } diff --git a/docs/azure/sdk/pagination.md b/docs/azure/sdk/pagination.md index 7fd7441b64bf7..c6d160504979c 100644 --- a/docs/azure/sdk/pagination.md +++ b/docs/azure/sdk/pagination.md @@ -7,7 +7,7 @@ ms.custom: devx-track-dotnet # Pagination with the Azure SDK for .NET -In this article, you'll learn how to use the Azure SDK for .NET pagination functionality to work efficiently and productively with large data sets. Pagination is the act of dividing large data sets into pages, making it easier for the consumer to iterate through smaller amounts of data. Starting with C# 8, you can create and consume streams asynchronously using [Asynchronous (async) streams](../../csharp/language-reference/statements/iteration-statements.md#await-foreach). Async streams are based on the interface. The Azure SDK for .NET exposes an implementation of `IAsyncEnumerable` with its `AsyncPageable` class. +In this article, you'll learn how to use the Azure SDK for .NET pagination functionality to work efficiently and productively with large data sets. Pagination is the act of dividing large data sets into pages, making it easier for the consumer to iterate through smaller amounts of data. Starting with C# 8, you can create and consume streams asynchronously using [Asynchronous (async) streams](../../csharp/language-reference/statements/iteration-statements.md#await-foreach). Async streams are based on the interface. The Azure SDK for .NET exposes an implementation of `IAsyncEnumerable` with its `AsyncPageable` class. All of the samples in this article rely on the following NuGet packages: @@ -29,8 +29,8 @@ Clients instantiated from the Azure SDK for .NET can return the following pageab | Type | Description | |----------------------------------------------------|----------------------------------------------------------| -| [`Pageable`](xref:Azure.Pageable%601) | A collection of values retrieved in pages | -| [`AsyncPageable`](xref:Azure.AsyncPageable%601) | A collection of values asynchronously retrieved in pages | +| [`Pageable`](xref:Azure.Pageable`1) | A collection of values retrieved in pages | +| [`AsyncPageable`](xref:Azure.AsyncPageable`1) | A collection of values asynchronously retrieved in pages | Most of the samples in this article are asynchronous, using variations of the `AsyncPageable` type. Using asynchronous programming for I/O-bound operations is ideal. A perfect use case is using the async APIs from the Azure SDK for .NET as these operations represent HTTP/S network calls. @@ -42,7 +42,7 @@ To iterate over an `AsyncPageable` using the [`await foreach`](/dotnet/csharp In the preceding C# code: -- The method is invoked and returns an `AsyncPageable` object. +- The method is invoked and returns an `AsyncPageable` object. - In an `await foreach` loop, each `SecretProperties` is asynchronously yielded. - As each `secret` is materialized, its `Name` is written to the console. @@ -54,27 +54,27 @@ To iterate over an `AsyncPageable` when the `await foreach` syntax isn't avai In the preceding C# code: -- The method is invoked, and returns an `AsyncPageable` object. -- The method is invoked, returning an `IAsyncEnumerator`. -- The method is invoked repeatedly until there are no items to return. +- The method is invoked, and returns an `AsyncPageable` object. +- The method is invoked, returning an `IAsyncEnumerator`. +- The method is invoked repeatedly until there are no items to return. ## Iterate over `AsyncPageable` pages -If you want control over receiving pages of values from the service, use the [`AsyncPageable.AsPages`](xref:Azure.AsyncPageable%601.AsPages%2A) method: +If you want control over receiving pages of values from the service, use the [`AsyncPageable.AsPages`](xref:Azure.AsyncPageable`1.AsPages%2A) method: :::code source="snippets/pagination/Program.cs" range="67-81"::: In the preceding C# code: -- The method is invoked and returns an `AsyncPageable` object. -- The method is invoked and returns an `IAsyncEnumerable>`. +- The method is invoked and returns an `AsyncPageable` object. +- The method is invoked and returns an `IAsyncEnumerable>`. - Each page is iterated over asynchronously, using `await foreach`. -- Each page has a set of , which represents an `IReadOnlyList` that's iterated over with a synchronous `foreach`. -- Each page also contains a , which can be used to request the next page. +- Each page has a set of , which represents an `IReadOnlyList` that's iterated over with a synchronous `foreach`. +- Each page also contains a , which can be used to request the next page. ## Use `System.Linq.Async` with `AsyncPageable` -The [`System.Linq.Async`](https://www.nuget.org/packages/System.Linq.Async) package provides a set of [LINQ](../../standard/linq/index.md) methods that operate on type. Because `AsyncPageable` implements [`IAsyncEnumerable`](xref:System.Collections.Generic.IAsyncEnumerable%601), you can use `System.Linq.Async` to query and transform the data. +The [`System.Linq.Async`](https://www.nuget.org/packages/System.Linq.Async) package provides a set of [LINQ](../../standard/linq/index.md) methods that operate on type. Because `AsyncPageable` implements [`IAsyncEnumerable`](xref:System.Collections.Generic.IAsyncEnumerable`1), you can use `System.Linq.Async` to query and transform the data. ### Convert to a `List` @@ -84,7 +84,7 @@ Use `ToListAsync` to convert an `AsyncPageable` to a `List`. This method m In the preceding C# code: -- The method is invoked and returns an `AsyncPageable` object. +- The method is invoked and returns an `AsyncPageable` object. - The `ToListAsync` method is awaited, which materializes a new `List` instance. ### Take the first N elements @@ -113,7 +113,7 @@ int expensiveSecretCount = ## As an observable sequence -The [`System.Linq.Async`](https://www.nuget.org/packages/System.Linq.Async) package is primarily used to provide observer pattern capabilities over `IAsyncEnumerable` sequences. Asynchronous streams are pull-based. As their items are iterated over, the next available item is *pulled*. This approach is in juxtaposition with the observer pattern, which is push-based. As items become available, they're *pushed* to subscribers who act as observers. The `System.Linq.Async` package provides the `ToObservable` extension method that lets you convert an `IAsyncEnumerable` to an [`IObservable`](xref:System.IObservable%601). +The [`System.Linq.Async`](https://www.nuget.org/packages/System.Linq.Async) package is primarily used to provide observer pattern capabilities over `IAsyncEnumerable` sequences. Asynchronous streams are pull-based. As their items are iterated over, the next available item is *pulled*. This approach is in juxtaposition with the observer pattern, which is push-based. As items become available, they're *pushed* to subscribers who act as observers. The `System.Linq.Async` package provides the `ToObservable` extension method that lets you convert an `IAsyncEnumerable` to an [`IObservable`](xref:System.IObservable`1). Imagine an `IObserver` implementation: @@ -125,7 +125,7 @@ You could consume the `ToObservable` extension method as follows: In the preceding C# code: -- The method is invoked and returns an `AsyncPageable` object. +- The method is invoked and returns an `AsyncPageable` object. - The `ToObservable()` method is called on the `AsyncPageable` instance, returning an `IObservable`. - The `observable` is subscribed to, passing in the observer implementation, returning the subscription to the caller. - The subscription is an `IDisposable`. When it's disposed, the subscription ends. diff --git a/docs/azure/sdk/protocol-convenience-methods.md b/docs/azure/sdk/protocol-convenience-methods.md index e2974c8333b4a..dee3cac7b5be0 100644 --- a/docs/azure/sdk/protocol-convenience-methods.md +++ b/docs/azure/sdk/protocol-convenience-methods.md @@ -34,7 +34,7 @@ The following table compares some of the request and response types used by prot | Request body | | | | Advanced request options | | | | Raw HTTP response | | | -| Return type with output model | | | +| Return type with output model | | | The sections ahead provide implementation examples of these concepts. @@ -69,7 +69,7 @@ The preceding code demonstrates the following `Azure.Core` protocol method patte 1. **Invoke the protocol method**, using a `RequestContext` object to configure request options. 1. **Handle the response** by reading: - The HTTP status code from the `Response` object to determine success or failure. - - Data from the `Response` object's content into a [dynamic](../../csharp/advanced-topics/interop/using-type-dynamic.md) type using . For more information, see [Announcing dynamic JSON in the Azure Core library for .NET](https://devblogs.microsoft.com/azure-sdk/dynamic-json-in-azure-core/). + - Data from the `Response` object's content into a [dynamic](../../csharp/advanced-topics/interop/using-type-dynamic.md) type using . For more information, see [Announcing dynamic JSON in the Azure Core library for .NET](https://devblogs.microsoft.com/azure-sdk/dynamic-json-in-azure-core/). > [!NOTE] > The preceding code configures the [ErrorOptions.NoThrow](/dotnet/api/azure.erroroptions) behavior. This option prevents non-success service responses status codes from throwing an exception, which means the app code should manually handle the response status code checks. diff --git a/docs/azure/sdk/unit-testing-mocking.md b/docs/azure/sdk/unit-testing-mocking.md index 23552038852cb..4ce3e07eaa91e 100644 --- a/docs/azure/sdk/unit-testing-mocking.md +++ b/docs/azure/sdk/unit-testing-mocking.md @@ -69,7 +69,7 @@ KeyVaultSecret keyVaultSecret = SecretModelFactory.KeyVaultSecret( ``` > [!NOTE] -> Some input models have read-only properties that are only populated when the model is returned by the service. In this case, a model factory method will be available that allows setting these properties. For example, . +> Some input models have read-only properties that are only populated when the model is returned by the service. In this case, a model factory method will be available that allows setting these properties. For example, . ```csharp // CreatedOn is a read-only property and can only be @@ -98,7 +98,7 @@ The `Response` class is abstract, which means there are many members to override --- -Some services also support using the type, which is a class that contains a model and the HTTP response that returned it. To create a test instance of `Response`, use the static `Response.FromValue` method: +Some services also support using the type, which is a class that contains a model and the HTTP response that returned it. To create a test instance of `Response`, use the static `Response.FromValue` method: ## [Non-library](#tab/csharp) @@ -116,7 +116,7 @@ Some services also support using the type, which is a ### Explore paging -The class is used as a building block in service methods that invoke operations returning results in multiple pages. The `Page` is rarely returned from APIs directly but is useful to create the `AsyncPageable` and `Pageable` instances in the next section. To create a `Page` instance, use the method, passing a list of items, a continuation token, and the `Response`. +The class is used as a building block in service methods that invoke operations returning results in multiple pages. The `Page` is rarely returned from APIs directly but is useful to create the `AsyncPageable` and `Pageable` instances in the next section. To create a `Page` instance, use the method, passing a list of items, a continuation token, and the `Response`. The `continuationToken` parameter is used to retrieve the next page from the service. For unit testing purposes, it should be set to `null` for the last page and should be nonempty for other pages. @@ -134,9 +134,9 @@ The `continuationToken` parameter is used to retrieve the next page from the ser --- - and are classes that represent collections of models returned by the service in pages. The only difference between them is that one is used with synchronous methods while the other is used with asynchronous methods. + and are classes that represent collections of models returned by the service in pages. The only difference between them is that one is used with synchronous methods while the other is used with asynchronous methods. -To create a test instance of `Pageable` or `AsyncPageable`, use the static method: +To create a test instance of `Pageable` or `AsyncPageable`, use the static method: ## [Non-library](#tab/csharp) diff --git a/docs/core/compatibility/code-analysis/5.0/ca2015-finalizers-for-memorymanager-types.md b/docs/core/compatibility/code-analysis/5.0/ca2015-finalizers-for-memorymanager-types.md index 1e2f46b791a4c..aa47e4c0b59c4 100644 --- a/docs/core/compatibility/code-analysis/5.0/ca2015-finalizers-for-memorymanager-types.md +++ b/docs/core/compatibility/code-analysis/5.0/ca2015-finalizers-for-memorymanager-types.md @@ -5,13 +5,13 @@ ms.date: 09/03/2020 --- # Warning CA2015: Do not define finalizers for types derived from MemoryManager\ -.NET code analyzer rule [CA2015](/visualstudio/code-quality/ca2015) is enabled, by default, starting in .NET 5. It produces a build warning for any types that derive from that define a finalizer. +.NET code analyzer rule [CA2015](/visualstudio/code-quality/ca2015) is enabled, by default, starting in .NET 5. It produces a build warning for any types that derive from that define a finalizer. ## Change description Starting in .NET 5, the .NET SDK includes [.NET source code analyzers](../../../../fundamentals/code-analysis/overview.md). Several of these rules are enabled, by default, including [CA2015](/visualstudio/code-quality/ca2015). If your project contains code that violates this rule and is configured to treat warnings as errors, this change could break your build. -Rule CA2015 flags types that derive from that define a finalizer. Adding a finalizer to a type that derives from is likely an indication of a bug. It suggests that a native resource that could have been obtained in a is getting cleaned up, potentially while it's still in use by the . +Rule CA2015 flags types that derive from that define a finalizer. Adding a finalizer to a type that derives from is likely an indication of a bug. It suggests that a native resource that could have been obtained in a is getting cleaned up, potentially while it's still in use by the . ## Version introduced diff --git a/docs/core/compatibility/code-analysis/5.0/ca2247-ctor-arg-should-be-taskcreationoptions.md b/docs/core/compatibility/code-analysis/5.0/ca2247-ctor-arg-should-be-taskcreationoptions.md index 10c9e5d9d63ce..25d6b29ebf2ba 100644 --- a/docs/core/compatibility/code-analysis/5.0/ca2247-ctor-arg-should-be-taskcreationoptions.md +++ b/docs/core/compatibility/code-analysis/5.0/ca2247-ctor-arg-should-be-taskcreationoptions.md @@ -5,13 +5,13 @@ ms.date: 09/03/2020 --- # Warning CA2247: Argument to TaskCompletionSource constructor should be TaskCreationOptions value -.NET code analyzer rule [CA2247](/visualstudio/code-quality/ca2247) is enabled, by default, starting in .NET 5. It produces a build warning for calls to the constructor that pass an argument of type . +.NET code analyzer rule [CA2247](/visualstudio/code-quality/ca2247) is enabled, by default, starting in .NET 5. It produces a build warning for calls to the constructor that pass an argument of type . ## Change description Starting in .NET 5, the .NET SDK includes [.NET source code analyzers](../../../../fundamentals/code-analysis/overview.md). Several of these rules are enabled, by default, including [CA2247](/visualstudio/code-quality/ca2247). If your project contains code that violates this rule and is configured to treat warnings as errors, this change could break your build. -Rule CA2247 finds calls to the constructor that pass an argument of type . The type has a constructor that accepts a value, and another constructor that accepts an . If you accidentally pass a value instead of a value, the constructor with the parameter is called at runtime. Your code will compile and run but won't have the intended behavior. +Rule CA2247 finds calls to the constructor that pass an argument of type . The type has a constructor that accepts a value, and another constructor that accepts an . If you accidentally pass a value instead of a value, the constructor with the parameter is called at runtime. Your code will compile and run but won't have the intended behavior. ## Version introduced @@ -25,7 +25,7 @@ Rule CA2247 finds calls to the +- +> It is highly recommended that you specify a trace source name that is unique to your custom channel to help trace output readers understand where the output came from. + +#### Integrating with the Trace Viewer + + Traces generated by your channel can be output in a format readable by the [Service Trace Viewer Tool (SvcTraceViewer.exe)](../service-trace-viewer-tool-svctraceviewer-exe.md) by using as the trace listener. This is not something you, as the channel developer, need to do. Rather, it is the application user (or the person troubleshooting the application) that needs to configure this trace listener in the application's configuration file. For example, the following configuration outputs trace information from both and `Microsoft.Samples.Udp` to the file named `TraceEventsFile.e2e`: + +```xml + + + + - - - - - - - - - - - - - - - - - - -``` - -#### Tracing Structured Data - - has a method that takes one or more objects that are to be included in the trace entry. In general, the method is called on each object and the resulting string is written as part of the trace entry. When using to output traces, you can pass an as the data object to . The resulting trace entry includes the XML provided by the . Here is an example entry with XML application data: - -```xml - - - 12 - 3 - 0 - 8 - - - + propagateActivity="true"> + + + + + + + + + + + + + + + + + + +``` + +#### Tracing Structured Data + + has a method that takes one or more objects that are to be included in the trace entry. In general, the method is called on each object and the resulting string is written as part of the trace entry. When using to output traces, you can pass an as the data object to . The resulting trace entry includes the XML provided by the . Here is an example entry with XML application data: + +```xml + + + 12 + 3 + 0 + 8 + + + - - COMPUTER-LT01 - - - - - + ProcessID="3348" ThreadID="4" /> + + COMPUTER-LT01 + + + + + - some trace id - EndReceive called - UdpTestConsole.exe - UdpInputChannel - - - - - -``` - + Severity="Information" + xmlns="…"> + some trace id + EndReceive called + UdpTestConsole.exe + UdpInputChannel + + + + + +``` + The WCF trace viewer understands the schema of the `TraceRecord` element shown previously and extracts the data from its child elements and displays it in a tabular format. Your channel should use this schema when tracing structured application data to help Svctraceviewer.exe users read the data. diff --git a/docs/framework/wcf/extending/how-to-compare-claims.md b/docs/framework/wcf/extending/how-to-compare-claims.md index a3f642aeaff7e..c79221de710c0 100644 --- a/docs/framework/wcf/extending/how-to-compare-claims.md +++ b/docs/framework/wcf/extending/how-to-compare-claims.md @@ -19,18 +19,18 @@ Claim comparison involves comparing the three parts of a claim (type, right, and [!code-csharp[c_CustomClaimComparison#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customclaimcomparison/cs/c_customclaimcomparison.cs#9)] [!code-vb[c_CustomClaimComparison#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customclaimcomparison/vb/source.vb#9)] -Both claims have a claim type of , a right of , and a resource of the string "someone". As all three parts of the claim are equal, the claims themselves are equal. +Both claims have a claim type of , a right of , and a resource of the string "someone". As all three parts of the claim are equal, the claims themselves are equal. -The built-in claim types are compared using the method. Claim-specific comparison code is used where necessary. For example, given the following two user principal name (UPN) claims, the comparison code in the method returns `true`, assuming `example\someone` identifies the same domain user as `someone@example.com`. +The built-in claim types are compared using the method. Claim-specific comparison code is used where necessary. For example, given the following two user principal name (UPN) claims, the comparison code in the method returns `true`, assuming `example\someone` identifies the same domain user as `someone@example.com`. [!code-csharp[c_CustomClaimComparison#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customclaimcomparison/cs/c_customclaimcomparison.cs#4)] [!code-vb[c_CustomClaimComparison#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customclaimcomparison/vb/source.vb#4)] -Custom claim types can also be compared using the method. However, in cases where the type returned by the property of the claim is something other than a primitive type, the returns `true` only if the values returned by the `Resource` properties are equal according to the method. In cases where this is not appropriate, the custom type returned by the `Resource` property should override the and methods to perform whatever custom processing is necessary. +Custom claim types can also be compared using the method. However, in cases where the type returned by the property of the claim is something other than a primitive type, the returns `true` only if the values returned by the `Resource` properties are equal according to the method. In cases where this is not appropriate, the custom type returned by the `Resource` property should override the and methods to perform whatever custom processing is necessary. ## Comparing built-in claims -1. Given two instances of the class, use the to make the comparison, as shown in the following code. +1. Given two instances of the class, use the to make the comparison, as shown in the following code. [!code-csharp[c_CustomClaimComparison#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customclaimcomparison/cs/c_customclaimcomparison.cs#5)] [!code-vb[c_CustomClaimComparison#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customclaimcomparison/vb/source.vb#5)] @@ -42,14 +42,14 @@ Custom claim types can also be compared using the method. +2. For custom claims with structure or class based resource types, the resource type should override the method. 3. First check whether the `obj` parameter is `null`, and if so, return `false`. [!code-csharp[c_CustomClaimComparison#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customclaimcomparison/cs/c_customclaimcomparison.cs#7)] [!code-vb[c_CustomClaimComparison#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customclaimcomparison/vb/source.vb#7)] -4. Next call and pass `this` and `obj` as parameters. If it returns `true`, then return `true`. +4. Next call and pass `this` and `obj` as parameters. If it returns `true`, then return `true`. [!code-csharp[c_CustomClaimComparison#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customclaimcomparison/cs/c_customclaimcomparison.cs#8)] [!code-vb[c_CustomClaimComparison#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customclaimcomparison/vb/source.vb#8)] diff --git a/docs/framework/wcf/extending/how-to-configure-a-custom-ws-metadata-exchange-binding.md b/docs/framework/wcf/extending/how-to-configure-a-custom-ws-metadata-exchange-binding.md index 8250b0cf84bde..6266534e38af0 100644 --- a/docs/framework/wcf/extending/how-to-configure-a-custom-ws-metadata-exchange-binding.md +++ b/docs/framework/wcf/extending/how-to-configure-a-custom-ws-metadata-exchange-binding.md @@ -2,113 +2,113 @@ description: "Learn more about: How to: Configure a Custom WS-Metadata Exchange Binding" title: "How to: Configure a Custom WS-Metadata Exchange Binding" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "WS-Metadata Exchange [WCF]" - "WS-Metadata Exchange [WCF], configuring a custom binding" ms.assetid: cdba4d73-da64-4805-bc56-9822becfd1e4 --- # How to: Configure a Custom WS-Metadata Exchange Binding -This article explains how to configure a custom WS-Metadata exchange binding. Windows Communication Foundation (WCF) includes four system-defined metadata bindings, but you can publish metadata using any binding you want. This article shows you how to publish metadata using the `wsHttpBinding`. This binding gives you the option of exposing metadata in a secure way. The code in this article is based on the [Getting Started](../samples/getting-started-sample.md). - -### Using a configuration file - -1. In the service's configuration file, add a service behavior that contains the `serviceMetadata` tag: - - ```xml - - - - - - - - ``` - -2. Add a `behaviorConfiguration` attribute to the service tag that references this new behavior: - - ```xml - + + + + + + + ``` + +2. Add a `behaviorConfiguration` attribute to the service tag that references this new behavior: + + ```xml + - ``` - -3. Add a metadata endpoint specifying mex as the address, `wsHttpBinding` as the binding, and as the contract: - - ```xml - - ``` - -4. To verify the metadata exchange endpoint is working correctly, add an endpoint tag in the client configuration file: - - ```xml - - ``` - -5. In the client's Main() method, create a new instance, set its property to `true`, call and then iterate through the collection of metadata returned: - + ``` + +3. Add a metadata endpoint specifying mex as the address, `wsHttpBinding` as the binding, and as the contract: + + ```xml + + ``` + +4. To verify the metadata exchange endpoint is working correctly, add an endpoint tag in the client configuration file: + + ```xml + + ``` + +5. In the client's Main() method, create a new instance, set its property to `true`, call and then iterate through the collection of metadata returned: + + ```csharp + string mexAddress = "http://localhost:8000/servicemodelsamples/service/mex"; + + MetadataExchangeClient mexClient = new MetadataExchangeClient("MyMexEndpoint"); + mexClient.ResolveMetadataReferences = true; + MetadataSet mdSet = mexClient.GetMetadata(new EndpointAddress(mexAddress)); + foreach (MetadataSection section in mdSet.MetadataSections) + Console.WriteLine("Metadata section: " + section.Dialect.ToString()); + ``` + +### Configuring by code + +1. Create a binding instance: + ```csharp - string mexAddress = "http://localhost:8000/servicemodelsamples/service/mex"; - - MetadataExchangeClient mexClient = new MetadataExchangeClient("MyMexEndpoint"); - mexClient.ResolveMetadataReferences = true; - MetadataSet mdSet = mexClient.GetMetadata(new EndpointAddress(mexAddress)); - foreach (MetadataSection section in mdSet.MetadataSections) - Console.WriteLine("Metadata section: " + section.Dialect.ToString()); - ``` - -### Configuring by code - -1. Create a binding instance: - - ```csharp - WSHttpBinding binding = new WSHttpBinding(); - ``` - -2. Create a instance: - - ```csharp - ServiceHost serviceHost = new ServiceHost(typeof(CalculatorService), baseAddress); - ``` - -3. Add a service endpoint and add a instance: - - ```csharp - serviceHost.AddServiceEndpoint(typeof(ICalculator), binding, baseAddress); - ServiceMetadataBehavior smb = new ServiceMetadataBehavior(); - smb.HttpGetEnabled = true; - serviceHost.Description.Behaviors.Add(smb); - ``` - -4. Add a metadata exchange endpoint, specifying the created earlier: - - ```csharp - serviceHost.AddServiceEndpoint(typeof(IMetadataExchange), binding, mexAddress); - ``` - -5. To verify that the metadata exchange endpoint is working correctly, add an endpoint tag in the client configuration file: - - ```xml - - ``` - -6. In the client's Main() method, create a new instance, set the property to `true`, call and then iterate through the collection of metadata returned: - - ```csharp - string mexAddress = "http://localhost:8000/servicemodelsamples/service/mex"; - - MetadataExchangeClient mexClient = new MetadataExchangeClient("MyMexEndpoint"); - mexClient.ResolveMetadataReferences = true; - MetadataSet mdSet = mexClient.GetMetadata(new EndpointAddress(mexAddress)); - foreach (MetadataSection section in mdSet.MetadataSections) - Console.WriteLine("Metadata section: " + section.Dialect.ToString()); - ``` - + WSHttpBinding binding = new WSHttpBinding(); + ``` + +2. Create a instance: + + ```csharp + ServiceHost serviceHost = new ServiceHost(typeof(CalculatorService), baseAddress); + ``` + +3. Add a service endpoint and add a instance: + + ```csharp + serviceHost.AddServiceEndpoint(typeof(ICalculator), binding, baseAddress); + ServiceMetadataBehavior smb = new ServiceMetadataBehavior(); + smb.HttpGetEnabled = true; + serviceHost.Description.Behaviors.Add(smb); + ``` + +4. Add a metadata exchange endpoint, specifying the created earlier: + + ```csharp + serviceHost.AddServiceEndpoint(typeof(IMetadataExchange), binding, mexAddress); + ``` + +5. To verify that the metadata exchange endpoint is working correctly, add an endpoint tag in the client configuration file: + + ```xml + + ``` + +6. In the client's Main() method, create a new instance, set the property to `true`, call and then iterate through the collection of metadata returned: + + ```csharp + string mexAddress = "http://localhost:8000/servicemodelsamples/service/mex"; + + MetadataExchangeClient mexClient = new MetadataExchangeClient("MyMexEndpoint"); + mexClient.ResolveMetadataReferences = true; + MetadataSet mdSet = mexClient.GetMetadata(new EndpointAddress(mexAddress)); + foreach (MetadataSection section in mdSet.MetadataSections) + Console.WriteLine("Metadata section: " + section.Dialect.ToString()); + ``` + ## See also - [Metadata Publishing Behavior](../samples/metadata-publishing-behavior.md) diff --git a/docs/framework/wcf/extending/how-to-create-a-custom-authorization-manager-for-a-service.md b/docs/framework/wcf/extending/how-to-create-a-custom-authorization-manager-for-a-service.md index c38601ae0d18a..eaeddac97904f 100644 --- a/docs/framework/wcf/extending/how-to-create-a-custom-authorization-manager-for-a-service.md +++ b/docs/framework/wcf/extending/how-to-create-a-custom-authorization-manager-for-a-service.md @@ -14,9 +14,9 @@ ms.assetid: 6214afde-44c1-4bf5-ba07-5ad6493620ea The Identity Model infrastructure in Windows Communication Foundation (WCF) supports an extensible claims-based authorization model. Claims are extracted from tokens and optionally processed by custom authorization policies and then placed into an . An authorization manager examines the claims in the to make authorization decisions. -By default, authorization decisions are made by the class; however these decisions can be overridden by creating a custom authorization manager. To create a custom authorization manager, create a class that derives from and implement method. Authorization decisions are made in the method, which returns `true` when access is granted and `false` when access is denied. +By default, authorization decisions are made by the class; however these decisions can be overridden by creating a custom authorization manager. To create a custom authorization manager, create a class that derives from and implement method. Authorization decisions are made in the method, which returns `true` when access is granted and `false` when access is denied. -If the authorization decision depends on the contents of the message body, use the method. +If the authorization decision depends on the contents of the message body, use the method. Because of performance issues, if possible you should redesign your application so that the authorization decision does not require access to the message body. @@ -40,9 +40,9 @@ Registration of the custom authorization manager for a service can be done in co ### To register a custom authorization manager using code -1. Create an instance of the custom authorization manager and assign it to the property. +1. Create an instance of the custom authorization manager and assign it to the property. - The can be accessed using property. + The can be accessed using property. The following code example registers the `MyServiceAuthorizationManager` custom authorization manager. @@ -109,7 +109,7 @@ Registration of the custom authorization manager for a service can be done in co ## Example -The following code example demonstrates a basic implementation of a class that includes overriding the method. The example code examines the for a custom claim and returns `true` when the resource for that custom claim matches the action value from the . For a more complete implementation of a class, see [Authorization Policy](../samples/authorization-policy.md). +The following code example demonstrates a basic implementation of a class that includes overriding the method. The example code examines the for a custom claim and returns `true` when the resource for that custom claim matches the action value from the . For a more complete implementation of a class, see [Authorization Policy](../samples/authorization-policy.md). [!code-csharp[c_CustomAuthMgr#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customauthmgr/cs/c_customauthmgr.cs#2)] [!code-vb[c_CustomAuthMgr#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customauthmgr/vb/c_customauthmgr.vb#2)] diff --git a/docs/framework/wcf/extending/how-to-create-a-custom-authorization-policy.md b/docs/framework/wcf/extending/how-to-create-a-custom-authorization-policy.md index c5142ae0b0ae3..6aae5d9310cf9 100644 --- a/docs/framework/wcf/extending/how-to-create-a-custom-authorization-policy.md +++ b/docs/framework/wcf/extending/how-to-create-a-custom-authorization-policy.md @@ -2,76 +2,76 @@ description: "Learn more about: How to: Create a Custom Authorization Policy" title: "How to: Create a Custom Authorization Policy" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 05b0549b-882d-4660-b6f0-5678543e5475 --- # How to: Create a Custom Authorization Policy -The Identity Model infrastructure in Windows Communication Foundation (WCF) supports a claim-based authorization model. Claims are extracted from tokens, optionally processed by custom authorization policy, and then placed into an that can then be examined to make authorization decisions. A custom policy can be used to transform claims from incoming tokens into claims expected by the application. In this way, the application layer can be insulated from the details on the differing claims served up by the different token types that WCF supports. This topic shows how to implement a custom authorization policy and how to add that policy to the collection of policies used by a service. - -### To implement a custom authorization policy - -1. Define a new class that derives from . - -2. Implement the read-only property by generating a unique string in the constructor for the class and returning that string whenever the property is accessed. - -3. Implement the read-only property by returning a that represents the policy issuer. This could be a `ClaimSet` that represents the application or a built-in `ClaimSet` (for example, the `ClaimSet` returned by the static property. - -4. Implement the method as described in the following procedure. - -### To implement the Evaluate method - -1. Two parameters are passed to this method: an instance of the class and an object reference. - -2. If the custom authorization policy adds instances without regard to the current content of the , then add each `ClaimSet` by calling the method and return `true` from the method. Returning `true` indicates to the authorization infrastructure that the authorization policy has performed its work and does not need to be called again. - -3. If the custom authorization policy adds claim sets only if certain claims are already present in the `EvaluationContext`, then look for those claims by examining the `ClaimSet` instances returned by the property. If the claims are present, then add the new claim sets by calling the method and, if no more claim sets are to be added, return `true`, indicating to the authorization infrastructure that the authorization policy has completed its work. If the claims are not present, return `false`, indicating that the authorization policy should be called again if other authorization policies add more claim sets to the `EvaluationContext`. - -4. In more complex processing scenarios, the second parameter of the method is used to store a state variable that the authorization infrastructure will pass back during each subsequent call to the method for a particular evaluation. - -### To specify a custom authorization policy through configuration - -1. Specify the type of the custom authorization policy in the `policyType` attribute in the `add` element in the `authorizationPolicies` element in the `serviceAuthorization` element. - - ```xml - - - - - - - - - - - - ``` - -### To specify a custom authorization policy through code - -1. Create a of . - -2. Create an instance of the custom authorization policy. - -3. Add the authorization policy instance to the list. - -4. Repeat steps 2 and 3 for each custom authorization policy. - -5. Assign a read-only version of the list to the property. - +The Identity Model infrastructure in Windows Communication Foundation (WCF) supports a claim-based authorization model. Claims are extracted from tokens, optionally processed by custom authorization policy, and then placed into an that can then be examined to make authorization decisions. A custom policy can be used to transform claims from incoming tokens into claims expected by the application. In this way, the application layer can be insulated from the details on the differing claims served up by the different token types that WCF supports. This topic shows how to implement a custom authorization policy and how to add that policy to the collection of policies used by a service. + +### To implement a custom authorization policy + +1. Define a new class that derives from . + +2. Implement the read-only property by generating a unique string in the constructor for the class and returning that string whenever the property is accessed. + +3. Implement the read-only property by returning a that represents the policy issuer. This could be a `ClaimSet` that represents the application or a built-in `ClaimSet` (for example, the `ClaimSet` returned by the static property. + +4. Implement the method as described in the following procedure. + +### To implement the Evaluate method + +1. Two parameters are passed to this method: an instance of the class and an object reference. + +2. If the custom authorization policy adds instances without regard to the current content of the , then add each `ClaimSet` by calling the method and return `true` from the method. Returning `true` indicates to the authorization infrastructure that the authorization policy has performed its work and does not need to be called again. + +3. If the custom authorization policy adds claim sets only if certain claims are already present in the `EvaluationContext`, then look for those claims by examining the `ClaimSet` instances returned by the property. If the claims are present, then add the new claim sets by calling the method and, if no more claim sets are to be added, return `true`, indicating to the authorization infrastructure that the authorization policy has completed its work. If the claims are not present, return `false`, indicating that the authorization policy should be called again if other authorization policies add more claim sets to the `EvaluationContext`. + +4. In more complex processing scenarios, the second parameter of the method is used to store a state variable that the authorization infrastructure will pass back during each subsequent call to the method for a particular evaluation. + +### To specify a custom authorization policy through configuration + +1. Specify the type of the custom authorization policy in the `policyType` attribute in the `add` element in the `authorizationPolicies` element in the `serviceAuthorization` element. + + ```xml + + + + + + + + + + + + ``` + +### To specify a custom authorization policy through code + +1. Create a of . + +2. Create an instance of the custom authorization policy. + +3. Add the authorization policy instance to the list. + +4. Repeat steps 2 and 3 for each custom authorization policy. + +5. Assign a read-only version of the list to the property. + [!code-csharp[c_CustomAuthPol#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customauthpol/cs/c_customauthpol.cs#8)] - [!code-vb[c_CustomAuthPol#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customauthpol/vb/source.vb#8)] - -## Example + [!code-vb[c_CustomAuthPol#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customauthpol/vb/source.vb#8)] + +## Example + + The following example shows a complete implementation. - The following example shows a complete implementation. - [!code-csharp[c_CustomAuthPol#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customauthpol/cs/c_customauthpol.cs#5)] - [!code-vb[c_CustomAuthPol#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customauthpol/vb/source.vb#5)] - + [!code-vb[c_CustomAuthPol#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customauthpol/vb/source.vb#5)] + ## See also - diff --git a/docs/framework/wcf/extending/how-to-create-a-custom-claim.md b/docs/framework/wcf/extending/how-to-create-a-custom-claim.md index 65ef93d2b7a66..416a1ff968c46 100644 --- a/docs/framework/wcf/extending/how-to-create-a-custom-claim.md +++ b/docs/framework/wcf/extending/how-to-create-a-custom-claim.md @@ -2,75 +2,75 @@ title: "How to: Create a Custom Claim" description: Learn how to create a custom claim in WCF. WCF supports a variety of built-in claims and some applications may require custom claims. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: d619976b-eda3-475e-ac23-c7988a2dceb0 --- # How to: Create a Custom Claim -The Identity Model infrastructure in Windows Communication Foundation (WCF) provides a set of built-in claim types and rights with the helper functions for creating instances with those types and rights. These built-in claims are designed to model information found in client credential types that WCF supports by default. In many cases, the built-in claims are sufficient; however some applications may require custom claims. A claim consists of the claim type, the resource for which the claim applies to and the right that is asserted over that resource. This topic describes how to create a custom claim. - -### To create a custom claim that is based on a primitive data type - -1. Create a custom claim by passing the claim type, resource value and right to the constructor. - - 1. Decide on a unique value for the claim type. - - The claim type is a unique string identifier. It is the custom claim designer's responsibility to ensure that the string identifier that is used for the claim type is unique. For a list of claim types that are defined by WCF, see the class. - - 2. Choose the primitive data type and value for the resource. - - A resource is an object. The CLR type of the resource can be a primitive, such as or , or any serializable type. The CLR type of the resource must be serializable, because claims are serialized at various points by WCF. Primitive types are serializable. - - 3. Choose a right that is defined by WCF or a unique value for a custom right. - - A right is a unique string identifier. The rights that are defined by WCF are defined in the class. - - It is the custom claim designer's responsibility to ensure that the string identifier that is used for the right is unique. - - The following code example creates a custom claim with a claim type of `http://example.org/claims/simplecustomclaim`, for a resource named `Driver's License`, and with the right. - +The Identity Model infrastructure in Windows Communication Foundation (WCF) provides a set of built-in claim types and rights with the helper functions for creating instances with those types and rights. These built-in claims are designed to model information found in client credential types that WCF supports by default. In many cases, the built-in claims are sufficient; however some applications may require custom claims. A claim consists of the claim type, the resource for which the claim applies to and the right that is asserted over that resource. This topic describes how to create a custom claim. + +### To create a custom claim that is based on a primitive data type + +1. Create a custom claim by passing the claim type, resource value and right to the constructor. + + 1. Decide on a unique value for the claim type. + + The claim type is a unique string identifier. It is the custom claim designer's responsibility to ensure that the string identifier that is used for the claim type is unique. For a list of claim types that are defined by WCF, see the class. + + 2. Choose the primitive data type and value for the resource. + + A resource is an object. The CLR type of the resource can be a primitive, such as or , or any serializable type. The CLR type of the resource must be serializable, because claims are serialized at various points by WCF. Primitive types are serializable. + + 3. Choose a right that is defined by WCF or a unique value for a custom right. + + A right is a unique string identifier. The rights that are defined by WCF are defined in the class. + + It is the custom claim designer's responsibility to ensure that the string identifier that is used for the right is unique. + + The following code example creates a custom claim with a claim type of `http://example.org/claims/simplecustomclaim`, for a resource named `Driver's License`, and with the right. + [!code-csharp[c_CustomClaim#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customclaim/cs/c_customclaim.cs#4)] - [!code-vb[c_CustomClaim#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customclaim/vb/c_customclaim.vb#4)] - -### To create a custom claim that is based on a non-primitive data type - -1. Create a custom claim by passing the claim type, resource value and right to the constructor. - - 1. Decide on a unique value for the claim type. - - The claim type is a unique string identifier. It is the custom claim designer's responsibility to ensure that the string identifier that is used for the claim type is unique. For a list of claim types that are defined by WCF, see the class. - - 2. Choose or define a serializable non-primitive type for the resource. - - A resource is an object. The CLR type of the resource must be serializable, because claims are serialized at various points by WCF. Primitive types are already serializable. - - When a new type is defined, apply the to the class. Also apply the attribute to the all members of the new type that need to be serialized as part of the claim. - - The following code example defines a custom resource type named `MyResourceType`. - + [!code-vb[c_CustomClaim#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customclaim/vb/c_customclaim.vb#4)] + +### To create a custom claim that is based on a non-primitive data type + +1. Create a custom claim by passing the claim type, resource value and right to the constructor. + + 1. Decide on a unique value for the claim type. + + The claim type is a unique string identifier. It is the custom claim designer's responsibility to ensure that the string identifier that is used for the claim type is unique. For a list of claim types that are defined by WCF, see the class. + + 2. Choose or define a serializable non-primitive type for the resource. + + A resource is an object. The CLR type of the resource must be serializable, because claims are serialized at various points by WCF. Primitive types are already serializable. + + When a new type is defined, apply the to the class. Also apply the attribute to the all members of the new type that need to be serialized as part of the claim. + + The following code example defines a custom resource type named `MyResourceType`. + [!code-csharp[c_CustomClaim#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customclaim/cs/c_customclaim.cs#2)] [!code-vb[c_CustomClaim#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customclaim/vb/c_customclaim.vb#2)] - - 3. Choose a right that is defined by WCF or a unique value for a custom right. - - A right is a unique string identifier. The rights that are defined by WCF are defined in the class. - - It is the custom claim designer's responsibility to ensure that the string identifier that is used for the right is unique. - - The following code example creates a custom claim with a claim type of `http://example.org/claims/complexcustomclaim`, a custom resource type of `MyResourceType`, and with the right. - + + 3. Choose a right that is defined by WCF or a unique value for a custom right. + + A right is a unique string identifier. The rights that are defined by WCF are defined in the class. + + It is the custom claim designer's responsibility to ensure that the string identifier that is used for the right is unique. + + The following code example creates a custom claim with a claim type of `http://example.org/claims/complexcustomclaim`, a custom resource type of `MyResourceType`, and with the right. + [!code-csharp[c_CustomClaim#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customclaim/cs/c_customclaim.cs#5)] [!code-vb[c_CustomClaim#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customclaim/vb/c_customclaim.vb#5)] - -## Example - The following code example demonstrates how to create a custom claim with a primitive resource type and a custom claim with a non-primitive resource type. - +## Example + + The following code example demonstrates how to create a custom claim with a primitive resource type and a custom claim with a non-primitive resource type. + [!code-csharp[c_CustomClaim#0](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customclaim/cs/c_customclaim.cs#0)] - [!code-vb[c_CustomClaim#0](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customclaim/vb/c_customclaim.vb#0)] - + [!code-vb[c_CustomClaim#0](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customclaim/vb/c_customclaim.vb#0)] + ## See also - diff --git a/docs/framework/wcf/extending/how-to-create-a-custom-client-identity-verifier.md b/docs/framework/wcf/extending/how-to-create-a-custom-client-identity-verifier.md index b4d73708fc0ff..14320d0dfa3bb 100644 --- a/docs/framework/wcf/extending/how-to-create-a-custom-client-identity-verifier.md +++ b/docs/framework/wcf/extending/how-to-create-a-custom-client-identity-verifier.md @@ -29,18 +29,18 @@ The *identity* feature of Windows Communication Foundation (WCF) enables a clien [!code-csharp[c_HowToSetCustomClientIdentity#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howtosetcustomclientidentity/cs/source.cs#7)] [!code-vb[c_HowToSetCustomClientIdentity#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howtosetcustomclientidentity/vb/source.vb#7)] -2. Override the method. The method determines whether the identity check succeeded or failed. +2. Override the method. The method determines whether the identity check succeeded or failed. 3. The `CheckAccess` method has two parameters. The first is an instance of the class. The second is an instance of the class. - In the method implementation, examine the collection of claims returned by the property of the class, and perform authentication checks as required. This example begins by finding any claim that is of type "Distinguished Name" and then compares the name to the extension of the (`OrgEndpointIdentity`). + In the method implementation, examine the collection of claims returned by the property of the class, and perform authentication checks as required. This example begins by finding any claim that is of type "Distinguished Name" and then compares the name to the extension of the (`OrgEndpointIdentity`). [!code-csharp[c_HowToSetCustomClientIdentity#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howtosetcustomclientidentity/cs/source.cs#1)] [!code-vb[c_HowToSetCustomClientIdentity#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howtosetcustomclientidentity/vb/source.vb#1)] ### To implement the TryGetIdentity method -1. Implement the method, which determines whether an instance of the class can be returned by the client. The WCF infrastructure calls the implementation of the `TryGetIdentity` method first to retrieve the service's identity from the message. Next, the infrastructure calls the `CheckAccess` implementation with the returned `EndpointIdentity` and . +1. Implement the method, which determines whether an instance of the class can be returned by the client. The WCF infrastructure calls the implementation of the `TryGetIdentity` method first to retrieve the service's identity from the message. Next, the infrastructure calls the `CheckAccess` implementation with the returned `EndpointIdentity` and . 2. In the `TryGetIdentity` method, put the following code: @@ -49,13 +49,13 @@ The *identity* feature of Windows Communication Foundation (WCF) enables a clien ### To implement a custom binding and set the custom IdentityVerifier -1. Create a method that returns a object. This example begins creates an instance of the class and sets its security mode to , and its to . +1. Create a method that returns a object. This example begins creates an instance of the class and sets its security mode to , and its to . -2. Create a using the method. +2. Create a using the method. 3. Return the from the collection and cast it to a variable. -4. Set the property of the class to a new instance of the `CustomIdentityVerifier` class created previously. +4. Set the property of the class to a new instance of the `CustomIdentityVerifier` class created previously. [!code-csharp[c_HowToSetCustomClientIdentity#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howtosetcustomclientidentity/cs/source.cs#3)] [!code-vb[c_HowToSetCustomClientIdentity#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howtosetcustomclientidentity/vb/source.vb#3)] diff --git a/docs/framework/wcf/extending/how-to-create-a-custom-principal-identity.md b/docs/framework/wcf/extending/how-to-create-a-custom-principal-identity.md index 5b8532d526cc5..00ed46ea21509 100644 --- a/docs/framework/wcf/extending/how-to-create-a-custom-principal-identity.md +++ b/docs/framework/wcf/extending/how-to-create-a-custom-principal-identity.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Create a Custom Principal Identity" title: "How to: Create a Custom Principal Identity" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "IPrincipal" - "IAuthorizationPolicy" - "PrincipalPermissionMode" @@ -14,39 +14,39 @@ ms.assetid: c4845fca-0ed9-4adf-bbdc-10812be69b61 --- # How to: Create a Custom Principal Identity -The is a declarative means of controlling access to service methods. When using this attribute, the enumeration specifies the mode for performing authorization checks. When this mode is set to , it enables the user to specify a custom class returned by the property. This topic illustrates the scenario when is used in combination with a custom authorization policy and a custom principal. - - For more information about using the , see [How to: Restrict Access with the PrincipalPermissionAttribute Class](../how-to-restrict-access-with-the-principalpermissionattribute-class.md). - -## Example +The is a declarative means of controlling access to service methods. When using this attribute, the enumeration specifies the mode for performing authorization checks. When this mode is set to , it enables the user to specify a custom class returned by the property. This topic illustrates the scenario when is used in combination with a custom authorization policy and a custom principal. + + For more information about using the , see [How to: Restrict Access with the PrincipalPermissionAttribute Class](../how-to-restrict-access-with-the-principalpermissionattribute-class.md). + +## Example [!code-csharp[PrincipalPermissionMode#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/principalpermissionmode/cs/source.cs#8)] - [!code-vb[PrincipalPermissionMode#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/principalpermissionmode/vb/source.vb#8)] - -## Compiling the Code - - References to the following namespaces are needed to compile the code: - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - + [!code-vb[PrincipalPermissionMode#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/principalpermissionmode/vb/source.vb#8)] + +## Compiling the Code + + References to the following namespaces are needed to compile the code: + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + ## See also - diff --git a/docs/framework/wcf/extending/how-to-create-a-custom-security-token-authenticator.md b/docs/framework/wcf/extending/how-to-create-a-custom-security-token-authenticator.md index cdafdcc42fa9a..0a8734487cb2f 100644 --- a/docs/framework/wcf/extending/how-to-create-a-custom-security-token-authenticator.md +++ b/docs/framework/wcf/extending/how-to-create-a-custom-security-token-authenticator.md @@ -2,57 +2,57 @@ description: "Learn more about: How to: create a custom security token authenticator" title: "How to: create a custom security token authenticator" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "WCF, authentication" ms.assetid: 10e245f7-d31e-42e7-82a2-d5780325d372 --- # How to: create a custom security token authenticator -This topic shows how to create a custom security token authenticator and how to integrate it with a custom security token manager. A security token authenticator validates the content of a security token provided with an incoming message. If the validation succeeds, the authenticator returns a collection of instances that, when evaluated, returns a set of claims. - +This topic shows how to create a custom security token authenticator and how to integrate it with a custom security token manager. A security token authenticator validates the content of a security token provided with an incoming message. If the validation succeeds, the authenticator returns a collection of instances that, when evaluated, returns a set of claims. + To use a custom security token authenticator in Windows Communication Foundation (WCF), you must first create custom credentials and security token manager implementations. For more information about creating custom credentials and a security token manager, see [Walkthrough: Creating Custom Client and Service Credentials](walkthrough-creating-custom-client-and-service-credentials.md). - -## Procedures - -#### To create a custom security token authenticator - -1. Define a new class derived from the class. - -2. Override the method. The method returns `true` or `false` depending on whether the custom authenticator can validate the incoming token type or not. - -3. Override the method. This method needs to validate the token contents appropriately. If the token passes the validation step, it returns a collection of instances. The following example uses a custom authorization policy implementation that will be created in the next procedure. - + +## Procedures + +#### To create a custom security token authenticator + +1. Define a new class derived from the class. + +2. Override the method. The method returns `true` or `false` depending on whether the custom authenticator can validate the incoming token type or not. + +3. Override the method. This method needs to validate the token contents appropriately. If the token passes the validation step, it returns a collection of instances. The following example uses a custom authorization policy implementation that will be created in the next procedure. + [!code-csharp[C_CustomTokenAuthenticator#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtokenauthenticator/cs/source.cs#1)] - [!code-vb[C_CustomTokenAuthenticator#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtokenauthenticator/vb/source.vb#1)] - - The previous code returns a collection of authorization policies in the method. WCF does not provide a public implementation of this interface. The following procedure shows how to do so for your own requirements. - -#### To create a custom authorization policy - -1. Define a new class implementing the interface. - -2. Implement the read-only property. One way to implement this property is to generate a globally unique identifier (GUID) in the class constructor and return it every time the value for this property is requested. - -3. Implement the read-only property. This property needs to return an issuer of the claim sets that are obtained from the token. This issuer should correspond to the issuer of the token or an authority that is responsible for validating the token contents. The following example uses the issuer claim that passed to this class from the custom security token authenticator created in the previous procedure. The custom security token authenticator uses the system-provided claim set (returned by the property) to represent the issuer of the username token. - -4. Implement the method. This method populates an instance of the class (passed in as an argument) with claims that are based on the incoming security token content. The method returns `true` when it is done with the evaluation. In cases when the implementation relies on the presence of other authorization policies that provide additional information to the evaluation context, this method can return `false` if the required information is not present yet in the evaluation context. In that case, WCF will call the method again after evaluating all other authorization policies generated for the incoming message if at least one of those authorization policies modified the evaluation context. - + [!code-vb[C_CustomTokenAuthenticator#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtokenauthenticator/vb/source.vb#1)] + + The previous code returns a collection of authorization policies in the method. WCF does not provide a public implementation of this interface. The following procedure shows how to do so for your own requirements. + +#### To create a custom authorization policy + +1. Define a new class implementing the interface. + +2. Implement the read-only property. One way to implement this property is to generate a globally unique identifier (GUID) in the class constructor and return it every time the value for this property is requested. + +3. Implement the read-only property. This property needs to return an issuer of the claim sets that are obtained from the token. This issuer should correspond to the issuer of the token or an authority that is responsible for validating the token contents. The following example uses the issuer claim that passed to this class from the custom security token authenticator created in the previous procedure. The custom security token authenticator uses the system-provided claim set (returned by the property) to represent the issuer of the username token. + +4. Implement the method. This method populates an instance of the class (passed in as an argument) with claims that are based on the incoming security token content. The method returns `true` when it is done with the evaluation. In cases when the implementation relies on the presence of other authorization policies that provide additional information to the evaluation context, this method can return `false` if the required information is not present yet in the evaluation context. In that case, WCF will call the method again after evaluating all other authorization policies generated for the incoming message if at least one of those authorization policies modified the evaluation context. + [!code-csharp[c_CustomTokenAuthenticator#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtokenauthenticator/cs/source.cs#3)] - [!code-vb[c_CustomTokenAuthenticator#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtokenauthenticator/vb/source.vb#3)] - - [Walkthrough: Creating Custom Client and Service Credentials](walkthrough-creating-custom-client-and-service-credentials.md) describes how to create custom credentials and a custom security token manager. To use the custom security token authenticator created here, an implementation of the security token manager is modified to return the custom authenticator from the method. The method returns an authenticator when an appropriate security token requirement is passed in. - -#### To integrate a custom security token authenticator with a custom security token manager - -1. Override the method in your custom security token manager implementation. - -2. Add logic to the method to enable it to return your custom security token authenticator based on the parameter. The following example returns a custom security token authenticator if the token requirements token type is a user name (represented by the property) and the message direction for which the security token authenticator is being requested is input (represented by the field). - + [!code-vb[c_CustomTokenAuthenticator#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtokenauthenticator/vb/source.vb#3)] + + [Walkthrough: Creating Custom Client and Service Credentials](walkthrough-creating-custom-client-and-service-credentials.md) describes how to create custom credentials and a custom security token manager. To use the custom security token authenticator created here, an implementation of the security token manager is modified to return the custom authenticator from the method. The method returns an authenticator when an appropriate security token requirement is passed in. + +#### To integrate a custom security token authenticator with a custom security token manager + +1. Override the method in your custom security token manager implementation. + +2. Add logic to the method to enable it to return your custom security token authenticator based on the parameter. The following example returns a custom security token authenticator if the token requirements token type is a user name (represented by the property) and the message direction for which the security token authenticator is being requested is input (represented by the field). + [!code-csharp[c_CustomTokenAuthenticator#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtokenauthenticator/cs/source.cs#2)] - [!code-vb[c_CustomTokenAuthenticator#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtokenauthenticator/vb/source.vb#2)] + [!code-vb[c_CustomTokenAuthenticator#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtokenauthenticator/vb/source.vb#2)] ## See also diff --git a/docs/framework/wcf/extending/how-to-create-a-custom-token.md b/docs/framework/wcf/extending/how-to-create-a-custom-token.md index 9150c98d82e48..b608c3b7eb01d 100644 --- a/docs/framework/wcf/extending/how-to-create-a-custom-token.md +++ b/docs/framework/wcf/extending/how-to-create-a-custom-token.md @@ -2,10 +2,10 @@ title: "How to: Create a Custom Token" description: Learn how to create a custom security token in WCF using the SecurityToken class and how to integrate it with a security token provider and an authenticator. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "SecurityTokenParameters class" - "security [WCF], creating custom tokens" - "WSSecurityTokenSerializer class" @@ -14,137 +14,137 @@ ms.assetid: 6d892973-1558-4115-a9e1-696777776125 --- # How to: Create a Custom Token -This topic shows how to create a custom security token using the class, and how to integrate it with a custom security token provider and authenticator. For a complete code example see the [Custom Token](../samples/custom-token.md) sample. - - A *security token* is essentially an XML element that is used by the Windows Communication Foundation (WCF) security framework to represent claims about a sender inside the SOAP message. WCF security provides various tokens for system-provided authentication modes. Examples include an X.509 certificate security token represented by the class or a Username security token represented by the class. - - Sometimes an authentication mode or credential is not supported by the provided types. In that case, it is necessary to create a custom security token to provide an XML representation of the custom credential inside the SOAP message. - - The following procedures show how to create a custom security token and how to integrate it with the WCF security infrastructure. This topic creates a credit card token that is used to pass information about the client's credit card to the server. - - For more information about custom credentials and security token manager, see [Walkthrough: Creating Custom Client and Service Credentials](walkthrough-creating-custom-client-and-service-credentials.md). - - See the namespace for more classes that represent security tokens. - -## Procedures - - A client application must be provided with a way to specify credit card information for the security infrastructure. This information is made available to the application by a custom client credentials class. The first step is to create a class to represent the credit card information for custom client credentials. - -#### To create a class that represents credit card information inside client credentials - -1. Define a new class that represents the credit card information for the application. The following example names the class `CreditCardInfo`. - -2. Add appropriate properties to the class to allow an application set the necessary information required for the custom token. In this example, the class has three properties: `CardNumber`, `CardIssuer`, and `ExpirationDate`. - +This topic shows how to create a custom security token using the class, and how to integrate it with a custom security token provider and authenticator. For a complete code example see the [Custom Token](../samples/custom-token.md) sample. + + A *security token* is essentially an XML element that is used by the Windows Communication Foundation (WCF) security framework to represent claims about a sender inside the SOAP message. WCF security provides various tokens for system-provided authentication modes. Examples include an X.509 certificate security token represented by the class or a Username security token represented by the class. + + Sometimes an authentication mode or credential is not supported by the provided types. In that case, it is necessary to create a custom security token to provide an XML representation of the custom credential inside the SOAP message. + + The following procedures show how to create a custom security token and how to integrate it with the WCF security infrastructure. This topic creates a credit card token that is used to pass information about the client's credit card to the server. + + For more information about custom credentials and security token manager, see [Walkthrough: Creating Custom Client and Service Credentials](walkthrough-creating-custom-client-and-service-credentials.md). + + See the namespace for more classes that represent security tokens. + +## Procedures + + A client application must be provided with a way to specify credit card information for the security infrastructure. This information is made available to the application by a custom client credentials class. The first step is to create a class to represent the credit card information for custom client credentials. + +#### To create a class that represents credit card information inside client credentials + +1. Define a new class that represents the credit card information for the application. The following example names the class `CreditCardInfo`. + +2. Add appropriate properties to the class to allow an application set the necessary information required for the custom token. In this example, the class has three properties: `CardNumber`, `CardIssuer`, and `ExpirationDate`. + [!code-csharp[c_CustomToken#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs#4)] - [!code-vb[c_CustomToken#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#4)] - - Next, a class that represents the custom security token must be created. This class is used by the security token provider, authenticator, and serializer classes to pass information about the security token to and from the WCF security infrastructure. - -#### To create a custom security token class - -1. Define a new class derived from the class. This example creates a class named `CreditCardToken`. - -2. Override the property. This property is used to get the local identifier of the security token that is used to point to the security token XML representation from other elements inside the SOAP message. In this example, a token identifier can be either passed to it as a constructor parameter or a new random one is generated every time a security token instance is created. - -3. Implement the property. This property returns a collection of security keys that the security token instance represents. Such keys can be used by WCF to sign or encrypt parts of the SOAP message. In this example, the credit card security token cannot contain any security keys; therefore, the implementation always returns an empty collection. - -4. Override the and properties. These properties are used by WCF to determine the validity of the security token instance. In this example, the credit card security token has only an expiration date, so the `ValidFrom` property returns a that represents the date and time of the instance creation. - + [!code-vb[c_CustomToken#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#4)] + + Next, a class that represents the custom security token must be created. This class is used by the security token provider, authenticator, and serializer classes to pass information about the security token to and from the WCF security infrastructure. + +#### To create a custom security token class + +1. Define a new class derived from the class. This example creates a class named `CreditCardToken`. + +2. Override the property. This property is used to get the local identifier of the security token that is used to point to the security token XML representation from other elements inside the SOAP message. In this example, a token identifier can be either passed to it as a constructor parameter or a new random one is generated every time a security token instance is created. + +3. Implement the property. This property returns a collection of security keys that the security token instance represents. Such keys can be used by WCF to sign or encrypt parts of the SOAP message. In this example, the credit card security token cannot contain any security keys; therefore, the implementation always returns an empty collection. + +4. Override the and properties. These properties are used by WCF to determine the validity of the security token instance. In this example, the credit card security token has only an expiration date, so the `ValidFrom` property returns a that represents the date and time of the instance creation. + [!code-csharp[c_CustomToken#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs#1)] - [!code-vb[c_CustomToken#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#1)] - - When a new security token type is created, it requires an implementation of the class. The implementation is used in the security binding element configuration to represent the new token type. The security token parameters class serves as a template that is used to match the actual security token instance to when a message is processed. The template provides additional properties that an application can use to specify criteria that the security token must match to be used or authenticated. The following example does not add any additional properties, so only the security token type is matched when the WCF infrastructure searches for a security token instance to use or to validate. - -#### To create a custom security token parameters class - -1. Define a new class derived from the class. - -2. Implement the method. Copy all internal fields defined in your class, if any. This example does not define any additional fields. - -3. Implement the read-only property. This property returns `true` if the security token type represented by this class can be used to authenticate a client to a service. In this example, the credit card security token can be used to authenticate a client to a service. - -4. Implement the read-only property. This property returns `true` if the security token type represented by this class can be used to authenticate a service to a client. In this example, the credit card security token cannot be used to authenticate a service to a client. - -5. Implement the read-only property. This property returns `true` if the security token type represented by this class can be mapped to a Windows account. If so, the authentication result is represented by a class instance. In this example, the token cannot be mapped to a Windows account. - -6. Implement the method. This method is called by WCF security framework when it requires a reference to the security token instance represented by this security token parameters class. Both the actual security token instance and that specifies the type of the reference that is being requested are passed to this method as arguments. In this example, only internal references are supported by the credit card security token. The class has functionality to create internal references; therefore, the implementation does not require additional code. - -7. Implement the method. This method is called by WCF to convert the security token parameters class instance into an instance of the class. The result is used by security token providers to create the appropriate security token instance. - + [!code-vb[c_CustomToken#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#1)] + + When a new security token type is created, it requires an implementation of the class. The implementation is used in the security binding element configuration to represent the new token type. The security token parameters class serves as a template that is used to match the actual security token instance to when a message is processed. The template provides additional properties that an application can use to specify criteria that the security token must match to be used or authenticated. The following example does not add any additional properties, so only the security token type is matched when the WCF infrastructure searches for a security token instance to use or to validate. + +#### To create a custom security token parameters class + +1. Define a new class derived from the class. + +2. Implement the method. Copy all internal fields defined in your class, if any. This example does not define any additional fields. + +3. Implement the read-only property. This property returns `true` if the security token type represented by this class can be used to authenticate a client to a service. In this example, the credit card security token can be used to authenticate a client to a service. + +4. Implement the read-only property. This property returns `true` if the security token type represented by this class can be used to authenticate a service to a client. In this example, the credit card security token cannot be used to authenticate a service to a client. + +5. Implement the read-only property. This property returns `true` if the security token type represented by this class can be mapped to a Windows account. If so, the authentication result is represented by a class instance. In this example, the token cannot be mapped to a Windows account. + +6. Implement the method. This method is called by WCF security framework when it requires a reference to the security token instance represented by this security token parameters class. Both the actual security token instance and that specifies the type of the reference that is being requested are passed to this method as arguments. In this example, only internal references are supported by the credit card security token. The class has functionality to create internal references; therefore, the implementation does not require additional code. + +7. Implement the method. This method is called by WCF to convert the security token parameters class instance into an instance of the class. The result is used by security token providers to create the appropriate security token instance. + [!code-csharp[c_CustomToken#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs#2)] - [!code-vb[c_CustomToken#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#2)] - - Security tokens are transmitted inside SOAP messages, which requires a translation mechanism between the in-memory security token representation and the on-the-wire representation. WCF uses a security token serializer to accomplish this task. Every custom token must be accompanied by a custom security token serializer that can serialize and deserialize the custom security token from the SOAP message. - + [!code-vb[c_CustomToken#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#2)] + + Security tokens are transmitted inside SOAP messages, which requires a translation mechanism between the in-memory security token representation and the on-the-wire representation. WCF uses a security token serializer to accomplish this task. Every custom token must be accompanied by a custom security token serializer that can serialize and deserialize the custom security token from the SOAP message. + > [!NOTE] -> Derived keys are enabled by default. If you create a custom security token and use it as the primary token, WCF derives a key from it. While doing so, it calls the custom security token serializer to write the for the custom security token while serializing the `DerivedKeyToken` to the wire. On the receiving end, when deserializing the token off the wire, the `DerivedKeyToken` serializer expects a `SecurityTokenReference` element as the top-level child under itself. If the custom security token serializer did not add a `SecurityTokenReference` element while serializing its clause type, an exception is thrown. - -#### To create a custom security token serializer - -1. Define a new class derived from the class. - -2. Override the method, which relies on an to read the XML stream. The method returns `true` if the serializer implementation can deserialize the security token based given its current element. In this example, this method checks whether the XML reader's current XML element has the correct element name and namespace. If it does not, it calls the base class implementation of this method to handle the XML element. - -3. Override the method. This method reads the XML content of the security token and constructs the appropriate in-memory representation for it. If it does not recognize the XML element on which the passed-in XML reader is standing, it calls the base class implementation to process the system-provided token types. - -4. Override the method. This method returns `true` if it can convert the in-memory token representation (passed in as an argument) to the XML representation. If it cannot convert, it calls the base class implementation. - -5. Override the method. This method converts an in-memory security token representation into an XML representation. If the method cannot convert, it calls the base class implementation. - +> Derived keys are enabled by default. If you create a custom security token and use it as the primary token, WCF derives a key from it. While doing so, it calls the custom security token serializer to write the for the custom security token while serializing the `DerivedKeyToken` to the wire. On the receiving end, when deserializing the token off the wire, the `DerivedKeyToken` serializer expects a `SecurityTokenReference` element as the top-level child under itself. If the custom security token serializer did not add a `SecurityTokenReference` element while serializing its clause type, an exception is thrown. + +#### To create a custom security token serializer + +1. Define a new class derived from the class. + +2. Override the method, which relies on an to read the XML stream. The method returns `true` if the serializer implementation can deserialize the security token based given its current element. In this example, this method checks whether the XML reader's current XML element has the correct element name and namespace. If it does not, it calls the base class implementation of this method to handle the XML element. + +3. Override the method. This method reads the XML content of the security token and constructs the appropriate in-memory representation for it. If it does not recognize the XML element on which the passed-in XML reader is standing, it calls the base class implementation to process the system-provided token types. + +4. Override the method. This method returns `true` if it can convert the in-memory token representation (passed in as an argument) to the XML representation. If it cannot convert, it calls the base class implementation. + +5. Override the method. This method converts an in-memory security token representation into an XML representation. If the method cannot convert, it calls the base class implementation. + [!code-csharp[c_CustomToken#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs#3)] - [!code-vb[c_CustomToken#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#3)] - - After completing the four previous procedures, integrate the custom security token with the security token provider, authenticator, manager, and client and service credentials. - -#### To integrate the custom security token with a security token provider - -1. The security token provider creates, modifies (if necessary), and returns an instance of the token. To create a custom provider for the custom security token, create a class that inherits from the class. The following example overrides the method to return an instance of the `CreditCardToken`. For more information about custom security token providers, see [How to: Create a Custom Security Token Provider](how-to-create-a-custom-security-token-provider.md). - + [!code-vb[c_CustomToken#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#3)] + + After completing the four previous procedures, integrate the custom security token with the security token provider, authenticator, manager, and client and service credentials. + +#### To integrate the custom security token with a security token provider + +1. The security token provider creates, modifies (if necessary), and returns an instance of the token. To create a custom provider for the custom security token, create a class that inherits from the class. The following example overrides the method to return an instance of the `CreditCardToken`. For more information about custom security token providers, see [How to: Create a Custom Security Token Provider](how-to-create-a-custom-security-token-provider.md). + [!code-csharp[c_CustomToken#6](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs#6)] - [!code-vb[c_CustomToken#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#6)] - -#### To integrate the custom security token with a security token authenticator - -1. The security token authenticator validates the content of the security token when it is extracted from the message. To create a custom authenticator for the custom security token, create a class that inherits from the class. The following example overrides the method. For more information about custom security token authenticators, see [How to: Create a Custom Security Token Authenticator](how-to-create-a-custom-security-token-authenticator.md). - + [!code-vb[c_CustomToken#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#6)] + +#### To integrate the custom security token with a security token authenticator + +1. The security token authenticator validates the content of the security token when it is extracted from the message. To create a custom authenticator for the custom security token, create a class that inherits from the class. The following example overrides the method. For more information about custom security token authenticators, see [How to: Create a Custom Security Token Authenticator](how-to-create-a-custom-security-token-authenticator.md). + [!code-csharp[c_CustomToken#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs#7)] - [!code-vb[c_CustomToken#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#7)] - + [!code-vb[c_CustomToken#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#7)] + [!code-csharp[c_CustomToken#12](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs#12)] - [!code-vb[c_CustomToken#12](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#12)] - -#### To integrate the custom security token with a security token manager - -1. The security token manager creates the appropriate token provider, security authenticator, and token serializer instances. To create a custom token manager, create a class that inherits from the class. The primary methods of the class use a to create the appropriate provider and client or service credentials. For more information about custom security token managers, see [Walkthrough: Creating Custom Client and Service Credentials](walkthrough-creating-custom-client-and-service-credentials.md). - + [!code-vb[c_CustomToken#12](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#12)] + +#### To integrate the custom security token with a security token manager + +1. The security token manager creates the appropriate token provider, security authenticator, and token serializer instances. To create a custom token manager, create a class that inherits from the class. The primary methods of the class use a to create the appropriate provider and client or service credentials. For more information about custom security token managers, see [Walkthrough: Creating Custom Client and Service Credentials](walkthrough-creating-custom-client-and-service-credentials.md). + [!code-csharp[c_CustomToken#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs#8)] - [!code-vb[c_CustomToken#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#8)] - + [!code-vb[c_CustomToken#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#8)] + [!code-csharp[c_CustomToken#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs#9)] - [!code-vb[c_CustomToken#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#9)] - -#### To integrate the custom security token with custom client and service credentials - -1. The custom client and service credentials must be added to provide an API for the application to allow specifying custom token information that is used by the custom security token infrastructure created previously to provide and authenticate the custom security token content. The following samples show how this can be done. For more information about custom client and service credentials, see [Walkthrough: Creating Custom Client and Service Credentials](walkthrough-creating-custom-client-and-service-credentials.md). - + [!code-vb[c_CustomToken#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#9)] + +#### To integrate the custom security token with custom client and service credentials + +1. The custom client and service credentials must be added to provide an API for the application to allow specifying custom token information that is used by the custom security token infrastructure created previously to provide and authenticate the custom security token content. The following samples show how this can be done. For more information about custom client and service credentials, see [Walkthrough: Creating Custom Client and Service Credentials](walkthrough-creating-custom-client-and-service-credentials.md). + [!code-csharp[c_CustomToken#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs#10)] - [!code-vb[c_CustomToken#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#10)] - + [!code-vb[c_CustomToken#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#10)] + [!code-csharp[c_customToken#11](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs#11)] - [!code-vb[c_customToken#11](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#11)] - - The custom security token parameters class created previously is used to tell the WCF security framework that a custom security token must be used when communicating with a service. The following procedure shows how this can be done. - -#### To integrate the custom security token with the binding - -1. The custom security token parameters class must be specified in one of the token parameters collections that are exposed on the class. The following example uses the collection returned by `SignedEncrypted`. The code adds the credit card custom token to every message sent from the client to the service with its content automatically signed and encrypted. - + [!code-vb[c_customToken#11](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#11)] + + The custom security token parameters class created previously is used to tell the WCF security framework that a custom security token must be used when communicating with a service. The following procedure shows how this can be done. + +#### To integrate the custom security token with the binding + +1. The custom security token parameters class must be specified in one of the token parameters collections that are exposed on the class. The following example uses the collection returned by `SignedEncrypted`. The code adds the credit card custom token to every message sent from the client to the service with its content automatically signed and encrypted. + [!code-csharp[c_CustomToken#13](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs#13)] - [!code-vb[c_CustomToken#13](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#13)] - - This topic shows the various pieces of code necessary to implement and use a custom token. To see a complete example of how all these pieces of code fit together see, [Custom Token](../samples/custom-token.md). - + [!code-vb[c_CustomToken#13](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb#13)] + + This topic shows the various pieces of code necessary to implement and use a custom token. To see a complete example of how all these pieces of code fit together see, [Custom Token](../samples/custom-token.md). + ## See also - diff --git a/docs/framework/wcf/extending/how-to-create-a-service-that-employs-a-custom-certificate-validator.md b/docs/framework/wcf/extending/how-to-create-a-service-that-employs-a-custom-certificate-validator.md index cab177f652fd4..6ccacddd59042 100644 --- a/docs/framework/wcf/extending/how-to-create-a-service-that-employs-a-custom-certificate-validator.md +++ b/docs/framework/wcf/extending/how-to-create-a-service-that-employs-a-custom-certificate-validator.md @@ -2,132 +2,132 @@ description: "Learn more about: How to: Create a Service that Employs a Custom Certificate Validator" title: "How to: Create a Service that Employs a Custom Certificate Validator" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "WCF, authentication" ms.assetid: bb0190ff-0738-4e54-8d22-c97d343708bf ms.custom: sfi-ropc-nochange --- # How to: Create a Service that Employs a Custom Certificate Validator -This topic shows how to implement a custom certificate validator and how to configure client or service credentials to replace the default certificate validation logic with the custom certificate validator. - - If the X.509 certificate is used to authenticate a client or service, Windows Communication Foundation (WCF) by default uses the Windows certificate store and Crypto API to validate the certificate and to ensure that it is trusted. Sometimes the built-in certificate validation functionality is not enough and must be changed. WCF provides an easy way to change the validation logic by allowing users to add a custom certificate validator. If a custom certificate validator is specified, WCF does not use the built-in certificate validation logic but relies on the custom validator instead. - -## Procedures - -#### To create a custom certificate validator - -1. Define a new class derived from . - -2. Implement the abstract method. The certificate that must be validated is passed as an argument to the method. If the passed certificate is not valid according to the validation logic, this method throws a . If the certificate is valid, the method returns to the caller. - +This topic shows how to implement a custom certificate validator and how to configure client or service credentials to replace the default certificate validation logic with the custom certificate validator. + + If the X.509 certificate is used to authenticate a client or service, Windows Communication Foundation (WCF) by default uses the Windows certificate store and Crypto API to validate the certificate and to ensure that it is trusted. Sometimes the built-in certificate validation functionality is not enough and must be changed. WCF provides an easy way to change the validation logic by allowing users to add a custom certificate validator. If a custom certificate validator is specified, WCF does not use the built-in certificate validation logic but relies on the custom validator instead. + +## Procedures + +#### To create a custom certificate validator + +1. Define a new class derived from . + +2. Implement the abstract method. The certificate that must be validated is passed as an argument to the method. If the passed certificate is not valid according to the validation logic, this method throws a . If the certificate is valid, the method returns to the caller. + > [!NOTE] - > To return authentication errors back to the client, throw a in the method. - + > To return authentication errors back to the client, throw a in the method. + [!code-csharp[c_CustomCertificateValidator#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customcertificatevalidator/cs/source.cs#2)] - [!code-vb[c_CustomCertificateValidator#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customcertificatevalidator/vb/source.vb#2)] - -#### To specify a custom certificate validator in service configuration - -1. Add a [\](../../configure-apps/file-schema/wcf/behaviors.md) element and a [\](../../configure-apps/file-schema/wcf/servicebehaviors.md) to the [\](../../configure-apps/file-schema/wcf/system-servicemodel.md) element. - -2. Add a [\](../../configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) and set the `name` attribute to an appropriate value. - -3. Add a [\](../../configure-apps/file-schema/wcf/servicecredentials.md) to the `` element. - -4. Add a `` element to the `` element. - -5. Add an [\](../../configure-apps/file-schema/wcf/authentication-of-clientcertificate-element.md) to the `` element. - -6. Set the `customCertificateValidatorType` attribute to the validator type. The following example sets the attribute to the namespace and name of the type. - -7. Set the `certificateValidationMode` attribute to `Custom`. - - ```xml - - - - - - - - - - - - - - - - ``` - -#### To specify a custom certificate validator using configuration on the client - -1. Add a [\](../../configure-apps/file-schema/wcf/behaviors.md) element and a [\](../../configure-apps/file-schema/wcf/servicebehaviors.md) to the [\](../../configure-apps/file-schema/wcf/system-servicemodel.md) element. - -2. Add an [\](../../configure-apps/file-schema/wcf/endpointbehaviors.md) element. - -3. Add a `` element and set the `name` attribute to an appropriate value. - -4. Add a [\](../../configure-apps/file-schema/wcf/clientcredentials.md) element. - -5. Add a [\](../../configure-apps/file-schema/wcf/servicecertificate-of-clientcredentials-element.md). - -6. Add an [\](../../configure-apps/file-schema/wcf/authentication-of-servicecertificate-element.md) as shown on the following example. - -7. Set the `customCertificateValidatorType` attribute to the validator type. - -8. Set the `certificateValidationMode` attribute to `Custom`. The following example sets the attribute to the namespace and name of the type. - - ```xml - - - - - - - + [!code-vb[c_CustomCertificateValidator#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customcertificatevalidator/vb/source.vb#2)] + +#### To specify a custom certificate validator in service configuration + +1. Add a [\](../../configure-apps/file-schema/wcf/behaviors.md) element and a [\](../../configure-apps/file-schema/wcf/servicebehaviors.md) to the [\](../../configure-apps/file-schema/wcf/system-servicemodel.md) element. + +2. Add a [\](../../configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) and set the `name` attribute to an appropriate value. + +3. Add a [\](../../configure-apps/file-schema/wcf/servicecredentials.md) to the `` element. + +4. Add a `` element to the `` element. + +5. Add an [\](../../configure-apps/file-schema/wcf/authentication-of-clientcertificate-element.md) to the `` element. + +6. Set the `customCertificateValidatorType` attribute to the validator type. The following example sets the attribute to the namespace and name of the type. + +7. Set the `certificateValidationMode` attribute to `Custom`. + + ```xml + + + + + + + + + + + + + + + + ``` + +#### To specify a custom certificate validator using configuration on the client + +1. Add a [\](../../configure-apps/file-schema/wcf/behaviors.md) element and a [\](../../configure-apps/file-schema/wcf/servicebehaviors.md) to the [\](../../configure-apps/file-schema/wcf/system-servicemodel.md) element. + +2. Add an [\](../../configure-apps/file-schema/wcf/endpointbehaviors.md) element. + +3. Add a `` element and set the `name` attribute to an appropriate value. + +4. Add a [\](../../configure-apps/file-schema/wcf/clientcredentials.md) element. + +5. Add a [\](../../configure-apps/file-schema/wcf/servicecertificate-of-clientcredentials-element.md). + +6. Add an [\](../../configure-apps/file-schema/wcf/authentication-of-servicecertificate-element.md) as shown on the following example. + +7. Set the `customCertificateValidatorType` attribute to the validator type. + +8. Set the `certificateValidationMode` attribute to `Custom`. The following example sets the attribute to the namespace and name of the type. + + ```xml + + + + + + + - - - - - - - - ``` - -#### To specify a custom certificate validator using code on the service - -1. Specify the custom certificate validator on the property. You can access the service credentials using the property. - -2. Set the property to . - + customCertificateValidatorType= + "Samples.CustomX509CertificateValidator, client"/> + + + + + + + + ``` + +#### To specify a custom certificate validator using code on the service + +1. Specify the custom certificate validator on the property. You can access the service credentials using the property. + +2. Set the property to . + [!code-csharp[c_CustomCertificateValidator#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customcertificatevalidator/cs/source.cs#1)] - [!code-vb[c_CustomCertificateValidator#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customcertificatevalidator/vb/source.vb#1)] - -#### To specify a custom certificate validator using code on the client - -1. Specify the custom certificate validator using the property. You can access the client credentials using the property. (The client class generated by [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) always derives from the class.) - -2. Set the property to . - -## Example - -### Description - - The following sample shows an implementation of a custom certificate validator and its usage on the service. - -### Code + [!code-vb[c_CustomCertificateValidator#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customcertificatevalidator/vb/source.vb#1)] + +#### To specify a custom certificate validator using code on the client + +1. Specify the custom certificate validator using the property. You can access the client credentials using the property. (The client class generated by [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) always derives from the class.) + +2. Set the property to . + +## Example + +### Description + + The following sample shows an implementation of a custom certificate validator and its usage on the service. + +### Code [!code-csharp[c_CustomCertificateValidator#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customcertificatevalidator/cs/source.cs#3)] - [!code-vb[c_CustomCertificateValidator#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customcertificatevalidator/vb/source.vb#3)] - + [!code-vb[c_CustomCertificateValidator#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customcertificatevalidator/vb/source.vb#3)] + ## See also - diff --git a/docs/framework/wcf/extending/how-to-customize-a-system-provided-binding.md b/docs/framework/wcf/extending/how-to-customize-a-system-provided-binding.md index a858426823244..406819735288a 100644 --- a/docs/framework/wcf/extending/how-to-customize-a-system-provided-binding.md +++ b/docs/framework/wcf/extending/how-to-customize-a-system-provided-binding.md @@ -2,50 +2,50 @@ description: "Learn more about: How to: Customize a System-Provided Binding" title: "How to: Customize a System-Provided Binding" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: f8b97862-e8bb-470d-8b96-07733c21fe26 --- # How to: Customize a System-Provided Binding -Windows Communication Foundation (WCF) includes several system-provided bindings that allow you to configure some of the properties of the underlying binding elements, but not all of the properties. This topic demonstrates how to set properties on the binding elements to create a custom binding. - - For more information about how to directly create and configure binding elements without using the system-provided bindings, see [Custom Bindings](custom-bindings.md). - - For more information about creating and extending custom bindings, see [Extending Bindings](extending-bindings.md). - - In WCF all bindings are made up of *binding elements*. Each binding element derives from the class. System-provided bindings such as create and configure their own binding elements. This topic shows you how to access and change the properties of these binding elements, which are not directly exposed on the binding; specifically, the class. - - The individual binding elements are contained in a collection represented by the class and are added in this order: Transaction Flow, Reliable Session, Security, Composite Duplex, One-way, Stream Security, Message Encoding, and Transport. Note that not all the binding elements listed are required in every binding. User-defined binding elements can also appear in this binding element collection and must appear in the same order as previously described. For example, a user-defined transport must be the last element of the binding element collection. - - The class contains three binding elements: - -1. An optional security binding element, either the class used with the HTTP transport (message level security) or the class, which is used when the transport layer provides security, in which case the HTTPS transport is used. - -2. A required message encoder binding element, either or . - -3. A required transport binding element, either , or . - - In this example we create an instance of the binding, generate a *custom binding* from it, examine the binding elements in the custom binding, and when we find the HTTP binding element, we set its `KeepAliveEnabled` property to `false`. The `KeepAliveEnabled` property is not exposed directly on the `BasicHttpBinding`, so we must create a custom binding to navigate down to the binding element and set this property. - -### To modify a system-provided binding - -1. Create an instance of the class and set its security mode to message-level. - +Windows Communication Foundation (WCF) includes several system-provided bindings that allow you to configure some of the properties of the underlying binding elements, but not all of the properties. This topic demonstrates how to set properties on the binding elements to create a custom binding. + + For more information about how to directly create and configure binding elements without using the system-provided bindings, see [Custom Bindings](custom-bindings.md). + + For more information about creating and extending custom bindings, see [Extending Bindings](extending-bindings.md). + + In WCF all bindings are made up of *binding elements*. Each binding element derives from the class. System-provided bindings such as create and configure their own binding elements. This topic shows you how to access and change the properties of these binding elements, which are not directly exposed on the binding; specifically, the class. + + The individual binding elements are contained in a collection represented by the class and are added in this order: Transaction Flow, Reliable Session, Security, Composite Duplex, One-way, Stream Security, Message Encoding, and Transport. Note that not all the binding elements listed are required in every binding. User-defined binding elements can also appear in this binding element collection and must appear in the same order as previously described. For example, a user-defined transport must be the last element of the binding element collection. + + The class contains three binding elements: + +1. An optional security binding element, either the class used with the HTTP transport (message level security) or the class, which is used when the transport layer provides security, in which case the HTTPS transport is used. + +2. A required message encoder binding element, either or . + +3. A required transport binding element, either , or . + + In this example we create an instance of the binding, generate a *custom binding* from it, examine the binding elements in the custom binding, and when we find the HTTP binding element, we set its `KeepAliveEnabled` property to `false`. The `KeepAliveEnabled` property is not exposed directly on the `BasicHttpBinding`, so we must create a custom binding to navigate down to the binding element and set this property. + +### To modify a system-provided binding + +1. Create an instance of the class and set its security mode to message-level. + [!code-csharp[C_HowTo_ChangeStandardBinding#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howto_changestandardbinding/cs/program.cs#1)] - [!code-vb[C_HowTo_ChangeStandardBinding#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_changestandardbinding/vb/program.vb#1)] - -2. Create a custom binding from the binding and create a class from one of the custom binding's properties. - + [!code-vb[C_HowTo_ChangeStandardBinding#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_changestandardbinding/vb/program.vb#1)] + +2. Create a custom binding from the binding and create a class from one of the custom binding's properties. + [!code-csharp[C_HowTo_ChangeStandardBinding#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howto_changestandardbinding/cs/program.cs#2)] - [!code-vb[C_HowTo_ChangeStandardBinding#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_changestandardbinding/vb/program.vb#2)] - -3. Loop through the class, and when you find the class, set its property to `false`. - + [!code-vb[C_HowTo_ChangeStandardBinding#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_changestandardbinding/vb/program.vb#2)] + +3. Loop through the class, and when you find the class, set its property to `false`. + [!code-csharp[C_HowTo_ChangeStandardBinding#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howto_changestandardbinding/cs/program.cs#3)] - [!code-vb[C_HowTo_ChangeStandardBinding#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_changestandardbinding/vb/program.vb#3)] - + [!code-vb[C_HowTo_ChangeStandardBinding#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_changestandardbinding/vb/program.vb#3)] + ## See also - diff --git a/docs/framework/wcf/extending/how-to-export-custom-policy-assertions.md b/docs/framework/wcf/extending/how-to-export-custom-policy-assertions.md index fb55dce7c26c8..c560fe3ee674c 100644 --- a/docs/framework/wcf/extending/how-to-export-custom-policy-assertions.md +++ b/docs/framework/wcf/extending/how-to-export-custom-policy-assertions.md @@ -2,49 +2,49 @@ description: "Learn more about: How to: Export Custom Policy Assertions" title: "How to: Export Custom Policy Assertions" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 99030386-43b0-4f7b-866d-17ea307f5cbd --- # How to: Export Custom Policy Assertions -Policy assertions describe the capabilities and requirements of a service endpoint. Service applications can use custom policy assertions in service metadata to communicate endpoint, binding or contract customization information to the client application. You can use Windows Communication Foundation (WCF) to export assertions in policy expressions attached in WSDL bindings at the endpoint, operation, or message subjects, depending upon the capabilities or requirements you are communicating. - - Custom policy assertions are exported by implementing the interface on a and either inserting the binding element directly into the binding of the service endpoint or by registering the binding element in your application configuration file. Your policy export implementation should add your custom policy assertion as a instance to the appropriate on the passed into the method. - - In addition you must check the property of the class and export nested policy expressions and policy framework attributes in the correct namespace based on the policy version specified. - - To import custom policy assertions, see and [How to: Import Custom Policy Assertions](how-to-import-custom-policy-assertions.md). - -### To export custom policy assertions - -1. Implement the interface on a . The following code example shows the implementation of a custom policy assertion at the binding level. - +Policy assertions describe the capabilities and requirements of a service endpoint. Service applications can use custom policy assertions in service metadata to communicate endpoint, binding or contract customization information to the client application. You can use Windows Communication Foundation (WCF) to export assertions in policy expressions attached in WSDL bindings at the endpoint, operation, or message subjects, depending upon the capabilities or requirements you are communicating. + + Custom policy assertions are exported by implementing the interface on a and either inserting the binding element directly into the binding of the service endpoint or by registering the binding element in your application configuration file. Your policy export implementation should add your custom policy assertion as a instance to the appropriate on the passed into the method. + + In addition you must check the property of the class and export nested policy expressions and policy framework attributes in the correct namespace based on the policy version specified. + + To import custom policy assertions, see and [How to: Import Custom Policy Assertions](how-to-import-custom-policy-assertions.md). + +### To export custom policy assertions + +1. Implement the interface on a . The following code example shows the implementation of a custom policy assertion at the binding level. + [!code-csharp[CustomPolicySample#14](../../../../samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/policyexporter.cs#14)] - [!code-vb[CustomPolicySample#14](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/policyexporter.vb#14)] - -2. Insert the binding element into the endpoint binding either programmatically or using an application configuration file. See the following procedures. - -### To insert a binding element using an application configuration file - -1. Implement for your custom policy assertion binding element. - -2. Add the binding element extension to the configuration file using the [\](../../configure-apps/file-schema/wcf/bindingelementextensions.md) element. - -3. Build a custom binding using the . - -### To insert a binding element programmatically - -1. Create a new and add it to a . - -2. Add the custom binding from step 1. to a new endpoint and add that new service endpoint to the by calling the method. - -3. Open the . The following code example shows the creation of a custom binding and the programmatic insertion of binding elements. - + [!code-vb[CustomPolicySample#14](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/policyexporter.vb#14)] + +2. Insert the binding element into the endpoint binding either programmatically or using an application configuration file. See the following procedures. + +### To insert a binding element using an application configuration file + +1. Implement for your custom policy assertion binding element. + +2. Add the binding element extension to the configuration file using the [\](../../configure-apps/file-schema/wcf/bindingelementextensions.md) element. + +3. Build a custom binding using the . + +### To insert a binding element programmatically + +1. Create a new and add it to a . + +2. Add the custom binding from step 1. to a new endpoint and add that new service endpoint to the by calling the method. + +3. Open the . The following code example shows the creation of a custom binding and the programmatic insertion of binding elements. + [!code-csharp[s_imperative#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_imperative/cs/service.cs#1)] - [!code-vb[s_imperative#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_imperative/vb/service.vb#1)] - + [!code-vb[s_imperative#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_imperative/vb/service.vb#1)] + ## See also - diff --git a/docs/framework/wcf/extending/how-to-import-custom-policy-assertions.md b/docs/framework/wcf/extending/how-to-import-custom-policy-assertions.md index 4b3fc3319941e..98938a288e9bc 100644 --- a/docs/framework/wcf/extending/how-to-import-custom-policy-assertions.md +++ b/docs/framework/wcf/extending/how-to-import-custom-policy-assertions.md @@ -2,63 +2,63 @@ description: "Learn more about: How to: Import Custom Policy Assertions" title: "How to: Import Custom Policy Assertions" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 1f41d787-accb-4a10-bfc6-a807671d1581 --- # How to: Import Custom Policy Assertions -Policy assertions describe the capabilities and requirements of a service endpoint. Client applications can use policy assertions in service metadata to configure the client binding or to customize the service contract for a service endpoint. - - Custom policy assertions are imported by implementing the interface and passing that object to the metadata system or by registering the implementation type in your application configuration file. Implementations of the interface must provide a parameterless constructor. - -### To import custom policy assertions - -1. Implement the interface on a class. See the following procedures. - -2. Insert the custom policy importer either by: - -3. Using a configuration file. See the following procedures. - -4. Using a configuration file with [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). See the following procedures. - -5. Programmatically inserting the policy importer. See the following procedures. - -### To implement the System.ServiceModel.Description.IPolicyImportExtension interface on any class - -1. In the method, for each policy subject that you are interested in, find the policy assertions that you want to import by calling the appropriate method (depending upon the scope of the assertion that you want) on the object passed to the method. The following code example shows how to use the method to locate the custom policy assertion and remove it from the collection in one step. If you use the remove method to locate and remove the assertion, you do not have to perform step 4. - +Policy assertions describe the capabilities and requirements of a service endpoint. Client applications can use policy assertions in service metadata to configure the client binding or to customize the service contract for a service endpoint. + + Custom policy assertions are imported by implementing the interface and passing that object to the metadata system or by registering the implementation type in your application configuration file. Implementations of the interface must provide a parameterless constructor. + +### To import custom policy assertions + +1. Implement the interface on a class. See the following procedures. + +2. Insert the custom policy importer either by: + +3. Using a configuration file. See the following procedures. + +4. Using a configuration file with [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). See the following procedures. + +5. Programmatically inserting the policy importer. See the following procedures. + +### To implement the System.ServiceModel.Description.IPolicyImportExtension interface on any class + +1. In the method, for each policy subject that you are interested in, find the policy assertions that you want to import by calling the appropriate method (depending upon the scope of the assertion that you want) on the object passed to the method. The following code example shows how to use the method to locate the custom policy assertion and remove it from the collection in one step. If you use the remove method to locate and remove the assertion, you do not have to perform step 4. + [!code-csharp[CustomPolicySample#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/policyimporter.cs#9)] - [!code-vb[CustomPolicySample#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/policyimporter.vb#9)] - -2. Process the policy assertions. Note that the policy system does not normalize nested policies and `wsp:optional`. You must process these constructs in your policy import extension implementation. - -3. Perform the customization to the binding or contract that supports the capability or requirement specified by the policy assertion. Typically assertions indicate that a binding requires a particular configuration or a specific binding element. Make these modifications by accessing the property. Other assertions require that you modify the contract. You can access and modify the contract using the property. Note that your policy importer may get called multiple times for the same binding and contract, but different policy alternatives if importing a policy alternative fails. Your code should be resilient to this behavior. - -4. Remove the custom policy assertion from the assertion collection. If you do not remove the assertion Windows Communication Foundation (WCF) assumes that the policy import was unsuccessful and does not import the associated binding. If you used the method to locate the custom policy assertion and remove it from the collection in one step you do not have to perform this step. - -### To insert the custom policy importer into the metadata System using a configuration file - -1. Add the importer type to the `` element inside the [\](../../configure-apps/file-schema/wcf/policyimporters.md) element in the client configuration file. - + [!code-vb[CustomPolicySample#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/policyimporter.vb#9)] + +2. Process the policy assertions. Note that the policy system does not normalize nested policies and `wsp:optional`. You must process these constructs in your policy import extension implementation. + +3. Perform the customization to the binding or contract that supports the capability or requirement specified by the policy assertion. Typically assertions indicate that a binding requires a particular configuration or a specific binding element. Make these modifications by accessing the property. Other assertions require that you modify the contract. You can access and modify the contract using the property. Note that your policy importer may get called multiple times for the same binding and contract, but different policy alternatives if importing a policy alternative fails. Your code should be resilient to this behavior. + +4. Remove the custom policy assertion from the assertion collection. If you do not remove the assertion Windows Communication Foundation (WCF) assumes that the policy import was unsuccessful and does not import the associated binding. If you used the method to locate the custom policy assertion and remove it from the collection in one step you do not have to perform this step. + +### To insert the custom policy importer into the metadata System using a configuration file + +1. Add the importer type to the `` element inside the [\](../../configure-apps/file-schema/wcf/policyimporters.md) element in the client configuration file. + [!code-xml[CustomPolicySample#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/client.exe.config#7)] - -2. In the client application, use the or to resolve the metadata and the importer is invoked automatically. - + +2. In the client application, use the or to resolve the metadata and the importer is invoked automatically. + [!code-csharp[CustomPolicySample#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/client.cs#10)] - [!code-vb[CustomPolicySample#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/client.vb#10)] - -### To insert the custom policy importer into the metadata system using Svcutil.exe - -1. Add the importer type to the `` element inside the [\](../../configure-apps/file-schema/wcf/policyimporters.md) element in the Svcutil.exe.config configuration file. You can also point Svcutil.exe to load policy importer types registered in a different configuration file by using the `/svcutilConfig` option. - -2. Use [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to import the metadata and the importer is invoked automatically. - -### To insert the custom policy importer into the metadata system programmatically - -1. Add the importer to the property (for example, if you are using the ) prior to importing the metadata. - + [!code-vb[CustomPolicySample#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/client.vb#10)] + +### To insert the custom policy importer into the metadata system using Svcutil.exe + +1. Add the importer type to the `` element inside the [\](../../configure-apps/file-schema/wcf/policyimporters.md) element in the Svcutil.exe.config configuration file. You can also point Svcutil.exe to load policy importer types registered in a different configuration file by using the `/svcutilConfig` option. + +2. Use [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to import the metadata and the importer is invoked automatically. + +### To insert the custom policy importer into the metadata system programmatically + +1. Add the importer to the property (for example, if you are using the ) prior to importing the metadata. + ## See also - diff --git a/docs/framework/wcf/extending/how-to-import-custom-wsdl.md b/docs/framework/wcf/extending/how-to-import-custom-wsdl.md index a0463041a35c3..b7e68e3a8bb79 100644 --- a/docs/framework/wcf/extending/how-to-import-custom-wsdl.md +++ b/docs/framework/wcf/extending/how-to-import-custom-wsdl.md @@ -6,12 +6,12 @@ ms.assetid: ddc3718d-ce60-44f6-92af-a5c67477dd99 --- # How to: Import Custom WSDL -This topic describes how to import custom WSDL. To handle the custom WSDL, you must implement the interface. - -### To import custom WSDL - -1. Implement . Implement the method to modify the metadata before it is imported. Implement the and methods to modify contracts and endpoints imported from the metadata. To access the imported contract or endpoint, use the corresponding context object ( or ): - +This topic describes how to import custom WSDL. To handle the custom WSDL, you must implement the interface. + +### To import custom WSDL + +1. Implement . Implement the method to modify the metadata before it is imported. Implement the and methods to modify contracts and endpoints imported from the metadata. To access the imported contract or endpoint, use the corresponding context object ( or ): + ```csharp public class WsdlDocumentationImporter : IWsdlImportExtension { @@ -47,33 +47,33 @@ This topic describes how to import custom WSDL. To handle the custom WSDL, you m } } ``` - -2. Configure the client application to use the custom WSDL importer. Note that if you are using Svcutil.exe, you should add this configuration to the configuration file for Svcutil.exe (Svcutil.exe.config): - - ```xml - - + +2. Configure the client application to use the custom WSDL importer. Note that if you are using Svcutil.exe, you should add this configuration to the configuration file for Svcutil.exe (Svcutil.exe.config): + + ```xml + + - - - - - - - - ``` - -3. Create a new instance (passing in the instance that contains the WSDL documents that you want to import), and call : - + binding="wsHttpBinding" + contract="IFibonacci" + /> + + + + + + + + ``` + +3. Create a new instance (passing in the instance that contains the WSDL documents that you want to import), and call : + ```csharp WsdlImporter importer = new WsdlImporter(metaDocs); - System.Collections.ObjectModel.Collection contracts = importer.ImportAllContracts(); - ``` - + System.Collections.ObjectModel.Collection contracts = importer.ImportAllContracts(); + ``` + ## See also - [Metadata](../feature-details/metadata.md) diff --git a/docs/framework/wcf/extending/how-to-inspect-and-modify-messages-on-the-service.md b/docs/framework/wcf/extending/how-to-inspect-and-modify-messages-on-the-service.md index 68b3e02469199..60aa8ed1f8d87 100644 --- a/docs/framework/wcf/extending/how-to-inspect-and-modify-messages-on-the-service.md +++ b/docs/framework/wcf/extending/how-to-inspect-and-modify-messages-on-the-service.md @@ -2,41 +2,41 @@ description: "Learn more about: How to: Inspect and Modify Messages on the Service" title: "How to: Inspect and Modify Messages on the Service" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 9c5b1cc7-84f3-45f8-9226-d59c278e8c42 --- # How to: Inspect and Modify Messages on the Service -You can inspect or modify the incoming or outgoing messages across a Windows Communication Foundation (WCF) service by implementing a and inserting it into the service runtime. For more information, see [Extending Dispatchers](extending-dispatchers.md). The equivalent feature on the client is the . - -### To inspect or modify messages - -1. Implement the interface. - -2. Implement a , , or interface depending upon the scope at which you want to easily insert your service message inspector. - -3. Insert your behavior prior to calling the method on the . For details, see [Configuring and Extending the Runtime with Behaviors](configuring-and-extending-the-runtime-with-behaviors.md). - -## Example - - The following code examples show, in order: - -- A service inspector implementation. - -- A service behavior that inserts the inspector. - -- A configuration file that loads and runs the behavior in a service application. - +You can inspect or modify the incoming or outgoing messages across a Windows Communication Foundation (WCF) service by implementing a and inserting it into the service runtime. For more information, see [Extending Dispatchers](extending-dispatchers.md). The equivalent feature on the client is the . + +### To inspect or modify messages + +1. Implement the interface. + +2. Implement a , , or interface depending upon the scope at which you want to easily insert your service message inspector. + +3. Insert your behavior prior to calling the method on the . For details, see [Configuring and Extending the Runtime with Behaviors](configuring-and-extending-the-runtime-with-behaviors.md). + +## Example + + The following code examples show, in order: + +- A service inspector implementation. + +- A service behavior that inserts the inspector. + +- A configuration file that loads and runs the behavior in a service application. + [!code-csharp[Interceptors#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#7)] - [!code-vb[Interceptors#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#7)] - + [!code-vb[Interceptors#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#7)] + [!code-csharp[Interceptors#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#8)] - [!code-vb[Interceptors#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#8)] - - [!code-xml[Interceptors#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/hostapplication.exe.config#9)] - + [!code-vb[Interceptors#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#8)] + + [!code-xml[Interceptors#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/hostapplication.exe.config#9)] + ## See also - diff --git a/docs/framework/wcf/extending/how-to-inspect-or-modify-messages-on-the-client.md b/docs/framework/wcf/extending/how-to-inspect-or-modify-messages-on-the-client.md index 59794fe529d43..0b08df622d810 100644 --- a/docs/framework/wcf/extending/how-to-inspect-or-modify-messages-on-the-client.md +++ b/docs/framework/wcf/extending/how-to-inspect-or-modify-messages-on-the-client.md @@ -6,123 +6,123 @@ ms.assetid: b8256335-f1c2-419f-b862-9f220ccad84c --- # How to: Inspect or Modify Messages on the Client -You can inspect or modify the incoming or outgoing messages across a WCF client by implementing a and inserting it into the client runtime. For more information, see [Extending Clients](extending-clients.md). The equivalent feature on the service is the . For a complete code example see the [Message Inspectors](../samples/message-inspectors.md) sample. - -### To inspect or modify messages - -1. Implement the interface. - -2. Implement a or depending upon the scope at which you want to insert the client message inspector. allows you to change behavior at the endpoint level. allows you to change behavior at the contract level. - -3. Insert the behavior prior to calling the or the method on the . For details, see [Configuring and Extending the Runtime with Behaviors](configuring-and-extending-the-runtime-with-behaviors.md). - -## Example - - The following code examples show, in order: - -- A client inspector implementation. - -- An endpoint behavior that inserts the inspector. - -- A - derived class that allows you to add the behavior in a configuration file. - -- A configuration file that adds the endpoint behavior which inserts the client message inspector into the client runtime. - -```csharp -// Client message inspector -public class SimpleMessageInspector : IClientMessageInspector -{ - public void AfterReceiveReply(ref System.ServiceModel.Channels.Message reply, object correlationState) - { - // Implement this method to inspect/modify messages after a message +You can inspect or modify the incoming or outgoing messages across a WCF client by implementing a and inserting it into the client runtime. For more information, see [Extending Clients](extending-clients.md). The equivalent feature on the service is the . For a complete code example see the [Message Inspectors](../samples/message-inspectors.md) sample. + +### To inspect or modify messages + +1. Implement the interface. + +2. Implement a or depending upon the scope at which you want to insert the client message inspector. allows you to change behavior at the endpoint level. allows you to change behavior at the contract level. + +3. Insert the behavior prior to calling the or the method on the . For details, see [Configuring and Extending the Runtime with Behaviors](configuring-and-extending-the-runtime-with-behaviors.md). + +## Example + + The following code examples show, in order: + +- A client inspector implementation. + +- An endpoint behavior that inserts the inspector. + +- A - derived class that allows you to add the behavior in a configuration file. + +- A configuration file that adds the endpoint behavior which inserts the client message inspector into the client runtime. + +```csharp +// Client message inspector +public class SimpleMessageInspector : IClientMessageInspector +{ + public void AfterReceiveReply(ref System.ServiceModel.Channels.Message reply, object correlationState) + { + // Implement this method to inspect/modify messages after a message // is received but prior to passing it back to the client - Console.WriteLine("AfterReceiveReply called"); - } - - public object BeforeSendRequest(ref System.ServiceModel.Channels.Message request, IClientChannel channel) - { + Console.WriteLine("AfterReceiveReply called"); + } + + public object BeforeSendRequest(ref System.ServiceModel.Channels.Message request, IClientChannel channel) + { // Implement this method to inspect/modify messages before they - // are sent to the service - Console.WriteLine("BeforeSendRequest called"); - return null; - } -} -``` - -```csharp -// Endpoint behavior -public class SimpleEndpointBehavior : IEndpointBehavior -{ - public void AddBindingParameters(ServiceEndpoint endpoint, System.ServiceModel.Channels.BindingParameterCollection bindingParameters) - { - // No implementation necessary - } - - public void ApplyClientBehavior(ServiceEndpoint endpoint, ClientRuntime clientRuntime) - { - clientRuntime.MessageInspectors.Add(new SimpleMessageInspector()); - } - - public void ApplyDispatchBehavior(ServiceEndpoint endpoint, EndpointDispatcher endpointDispatcher) - { - // No implementation necessary - } - - public void Validate(ServiceEndpoint endpoint) - { - // No implementation necessary - } -} -``` - -```csharp + // are sent to the service + Console.WriteLine("BeforeSendRequest called"); + return null; + } +} +``` + +```csharp +// Endpoint behavior +public class SimpleEndpointBehavior : IEndpointBehavior +{ + public void AddBindingParameters(ServiceEndpoint endpoint, System.ServiceModel.Channels.BindingParameterCollection bindingParameters) + { + // No implementation necessary + } + + public void ApplyClientBehavior(ServiceEndpoint endpoint, ClientRuntime clientRuntime) + { + clientRuntime.MessageInspectors.Add(new SimpleMessageInspector()); + } + + public void ApplyDispatchBehavior(ServiceEndpoint endpoint, EndpointDispatcher endpointDispatcher) + { + // No implementation necessary + } + + public void Validate(ServiceEndpoint endpoint) + { + // No implementation necessary + } +} +``` + +```csharp // Configuration element -public class SimpleBehaviorExtensionElement : BehaviorExtensionElement -{ - public override Type BehaviorType - { - get { return typeof(SimpleEndpointBehavior); } - } - - protected override object CreateBehavior() - { - // Create the endpoint behavior that will insert the message - // inspector into the client runtime - return new SimpleEndpointBehavior(); - } -} -``` - +public class SimpleBehaviorExtensionElement : BehaviorExtensionElement +{ + public override Type BehaviorType + { + get { return typeof(SimpleEndpointBehavior); } + } + + protected override object CreateBehavior() + { + // Create the endpoint behavior that will insert the message + // inspector into the client runtime + return new SimpleEndpointBehavior(); + } +} +``` + ```xml - - - - + + + + - - - - - - - - - - - - - - - - -``` - + contract="ServiceReference1.IService1" + name="WSHttpBinding_IService1"/> + + + + + + + + + + + + + + + + +``` + ## See also - diff --git a/docs/framework/wcf/extending/how-to-inspect-or-modify-parameters.md b/docs/framework/wcf/extending/how-to-inspect-or-modify-parameters.md index aed2338510e78..653e2186670e7 100644 --- a/docs/framework/wcf/extending/how-to-inspect-or-modify-parameters.md +++ b/docs/framework/wcf/extending/how-to-inspect-or-modify-parameters.md @@ -2,41 +2,41 @@ description: "Learn more about: How to: Inspect or Modify Parameters" title: "How to: Inspect or Modify Parameters" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: ab6c0ac7-aac4-45ba-93d6-a0e9afd1756f --- # How to: Inspect or Modify Parameters -You can inspect or modify the incoming or outgoing messages for a single operation on a Windows Communication Foundation (WCF) client object or a WCF service by implementing the interface and inserting it into the client or service runtime. Typically an operation behavior is used to add parameter inspectors for a single operation; other behaviors can be used to provide easy access to the runtime at a greater scope. For more information, see [Extending Clients](extending-clients.md) and [Extending Dispatchers](extending-dispatchers.md). - -### Inspecting or Modifying Parameters - -1. Implement the interface. - -2. Implement a , , or (depending upon the required scope) to add your parameter inspector to either the or properties. - -3. Insert your behavior prior to calling or the method on the . For details, see [Configuring and Extending the Runtime with Behaviors](configuring-and-extending-the-runtime-with-behaviors.md). - -## Example - - The following code examples show, in order: - -- A parameter inspector implementation. - -- The behavior implementation that inserts the parameter inspector using a , , and an . - -- A configuration file that loads and runs the endpoint behavior in a client application to insert the parameter inspector on the client. - +You can inspect or modify the incoming or outgoing messages for a single operation on a Windows Communication Foundation (WCF) client object or a WCF service by implementing the interface and inserting it into the client or service runtime. Typically an operation behavior is used to add parameter inspectors for a single operation; other behaviors can be used to provide easy access to the runtime at a greater scope. For more information, see [Extending Clients](extending-clients.md) and [Extending Dispatchers](extending-dispatchers.md). + +### Inspecting or Modifying Parameters + +1. Implement the interface. + +2. Implement a , , or (depending upon the required scope) to add your parameter inspector to either the or properties. + +3. Insert your behavior prior to calling or the method on the . For details, see [Configuring and Extending the Runtime with Behaviors](configuring-and-extending-the-runtime-with-behaviors.md). + +## Example + + The following code examples show, in order: + +- A parameter inspector implementation. + +- The behavior implementation that inserts the parameter inspector using a , , and an . + +- A configuration file that loads and runs the endpoint behavior in a client application to insert the parameter inspector on the client. + [!code-csharp[Interceptors#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#4)] - [!code-vb[Interceptors#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#4)] - + [!code-vb[Interceptors#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#4)] + [!code-csharp[Interceptors#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#5)] - [!code-vb[Interceptors#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#5)] - - [!code-xml[Interceptors#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/client.exe.config#3)] - + [!code-vb[Interceptors#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#5)] + + [!code-xml[Interceptors#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/client.exe.config#3)] + ## See also - [Configuring and Extending the Runtime with Behaviors](configuring-and-extending-the-runtime-with-behaviors.md) diff --git a/docs/framework/wcf/extending/how-to-lock-down-endpoints-in-the-enterprise.md b/docs/framework/wcf/extending/how-to-lock-down-endpoints-in-the-enterprise.md index 32ecc6bc649ae..67a6b6fb8f755 100644 --- a/docs/framework/wcf/extending/how-to-lock-down-endpoints-in-the-enterprise.md +++ b/docs/framework/wcf/extending/how-to-lock-down-endpoints-in-the-enterprise.md @@ -21,7 +21,7 @@ In this case, the validator is a client validator because this endpoint behavior ### To create the endpoint validator -1. Create an with the desired validation steps in the method. The following code provides an example. (The `InternetClientValidatorBehavior` is taken from the [Security Validation](../samples/security-validation.md) sample.) +1. Create an with the desired validation steps in the method. The following code provides an example. (The `InternetClientValidatorBehavior` is taken from the [Security Validation](../samples/security-validation.md) sample.) [!code-csharp[LockdownValidation#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/lockdownvalidation/cs/internetclientvalidatorbehavior.cs#2)] diff --git a/docs/framework/wcf/extending/how-to-use-separate-x-509-certificates-for-signing-and-encryption.md b/docs/framework/wcf/extending/how-to-use-separate-x-509-certificates-for-signing-and-encryption.md index 06ec94f21e62a..1aba70ed3819c 100644 --- a/docs/framework/wcf/extending/how-to-use-separate-x-509-certificates-for-signing-and-encryption.md +++ b/docs/framework/wcf/extending/how-to-use-separate-x-509-certificates-for-signing-and-encryption.md @@ -24,11 +24,11 @@ The following diagram shows the main classes used, the classes they inherit from - Its properties shown in the diagram all return instances of . - - Its method returns an instance of `MyClientCredentialsSecurityTokenManager`. + - Its method returns an instance of `MyClientCredentialsSecurityTokenManager`. - `MyClientCredentialsSecurityTokenManager` is a custom implementation of . - - Its method returns an instance of . + - Its method returns an instance of . ![Chart showing how client credentials are used](./media/e4971edd-a59f-4571-b36f-7e6b2f0d610f.gif "e4971edd-a59f-4571-b36f-7e6b2f0d610f") @@ -44,22 +44,22 @@ For more information about creating a custom identity verifier, see How to: [How ### To use separate certificates for signing and encryption -1. Define a new client credentials class that inherits from the class. Implement four new properties to allow multiple certificates specification: `ClientSigningCertificate`, `ClientEncryptingCertificate`, `ServiceSigningCertificate`, and `ServiceEncryptingCertificate`. Also override the method to return an instance of the customized class that is defined in the next step. +1. Define a new client credentials class that inherits from the class. Implement four new properties to allow multiple certificates specification: `ClientSigningCertificate`, `ClientEncryptingCertificate`, `ServiceSigningCertificate`, and `ServiceEncryptingCertificate`. Also override the method to return an instance of the customized class that is defined in the next step. [!code-csharp[c_FourCerts#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_fourcerts/cs/source.cs#1)] [!code-vb[c_FourCerts#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_fourcerts/vb/source.vb#1)] -2. Define a new client security token manager that inherits from the class. Override the method to create an appropriate security token provider. The `requirement` parameter (a ) provides the message direction and key usage. +2. Define a new client security token manager that inherits from the class. Override the method to create an appropriate security token provider. The `requirement` parameter (a ) provides the message direction and key usage. [!code-csharp[c_FourCerts#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_fourcerts/cs/source.cs#2)] [!code-vb[c_FourCerts#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_fourcerts/vb/source.vb#2)] -3. Define a new service credentials class that inherits from the class. Implement four new properties to allow multiple certificates specification: `ClientSigningCertificate`, `ClientEncryptingCertificate`, `ServiceSigningCertificate`, and `ServiceEncryptingCertificate`. Also override the method to return an instance of the customized class that is defined in the next step. +3. Define a new service credentials class that inherits from the class. Implement four new properties to allow multiple certificates specification: `ClientSigningCertificate`, `ClientEncryptingCertificate`, `ServiceSigningCertificate`, and `ServiceEncryptingCertificate`. Also override the method to return an instance of the customized class that is defined in the next step. [!code-csharp[c_FourCerts#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_fourcerts/cs/source.cs#3)] [!code-vb[c_FourCerts#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_fourcerts/vb/source.vb#3)] -4. Define a new service security token manager that inherits from the class. Override the method to create an appropriate security token provider given the passed-in message direction and key usage. +4. Define a new service security token manager that inherits from the class. Override the method to create an appropriate security token provider given the passed-in message direction and key usage. [!code-csharp[c_FourCerts#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_fourcerts/cs/source.cs#4)] [!code-vb[c_FourCerts#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_fourcerts/vb/source.vb#4)] diff --git a/docs/framework/wcf/extending/importing-custom-metadata-for-a-wcf-extension.md b/docs/framework/wcf/extending/importing-custom-metadata-for-a-wcf-extension.md index 016048eddf00f..bd0948391c4e3 100644 --- a/docs/framework/wcf/extending/importing-custom-metadata-for-a-wcf-extension.md +++ b/docs/framework/wcf/extending/importing-custom-metadata-for-a-wcf-extension.md @@ -6,47 +6,47 @@ ms.assetid: 78beb28f-408a-4c75-9c3c-caefe9595b1a --- # Importing Custom Metadata for a WCF Extension -In Windows Communication Foundation (WCF), metadata import is the process of generating an abstract representation of a service or its component parts from its metadata. For example, WCF can import instances, instances or instances from a WSDL document for a service. To import service metadata in WCF, use an implementation of the abstract class. Types that derive from the class implement support for importing metadata formats that take advantage of the WS-Policy import logic in WCF. - - Custom metadata consists of XML elements that the system-provided metadata importers cannot import. Typically, this includes custom WSDL extensions and custom policy assertions. - - This section describes how to import custom WSDL extensions and policy assertions. It does not focus on the importing process itself. For more information about how to use the types that export and import metadata regardless of whether the metadata is custom or system-supported, see [Exporting and Importing Metadata](../feature-details/exporting-and-importing-metadata.md). - -## Overview - - The type is the implementation of the abstract class included with WCF. The type imports WSDL metadata with attached policies that are bundled in a object. Policy assertions and WSDL extensions that the default importers do not recognize are passed to any registered custom policy and WSDL importers for importing. Typically, importers are implemented to support user-defined binding elements or to modify the imported contract. - - This section describes: - -1. How to implement and use the interface, which exposes the WSDL data to custom importers prior to the generation of descriptions and the generation of code. You can use this interface to examine or modify the description types and code compilation performed using a given set of metadata. - -2. How to implement and use the interface, which exposes policy assertions to importers prior to the generation of description objects. You can use this interface to examine or modify the binding or contract based on the downloaded policies. - - For more information about exporting custom WSDL and policy assertions, see [Exporting Custom Metadata for a WCF Extension](exporting-custom-metadata-for-a-wcf-extension.md). - -## Importing Custom WSDL Extensions - - To add support for importing WSDL extensions, implement the interface and then add your implementation to the property. The can also load implementations of the interface registered in your application configuration file. Note that a number of WSDL importers are registered by default and the order of the registered WSDL importers is significant. - - When the custom WSDL importer is loaded and used by the , first the method is called to enable the modification of metadata prior to the import process. Next, the contracts are imported after which the method is called to enable the modification of the contracts imported from the metadata. Finally, the method is called to enable the modification of the imported endpoints. - - For more information, see [How to: Import Custom WSDL](how-to-import-custom-wsdl.md). - -### Importing Custom Policy Assertions - - The type and the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) automatically handle processing a variety of policy assertion types in policy expressions attached to WSDL documents. These tools collect, normalize, and merge policy expressions attached to WSDL bindings and WSDL ports. - - To add support for importing custom policy assertions, implement the interface and then add your implementation to the property. The can also load implementations of the interface registered in your application configuration file. Note that a number of policy importers are registered by default and the order of the registered policy importers is significant. - - The metadata system repeatedly calls the method on all registered policy import extensions for each combination of policy alternatives attached to the message, operation, and endpoint policy subjects. When importing a WSDL port, policies attached to the port and to the corresponding WSDL binding are merged before calling into the policy import extensions. The policy alternatives are made available through a as objects. Each is a collection of policy assertions represented by objects. - - The and properties on the object expose the and objects that were imported from the WSDL. Policy import extensions process policy assertions by finding instances of a particular policy assertion type, making corresponding changes to the or objects and then removing the policy assertions from the corresponding instance. - - The `wsp:Optional` attribute and nested policy expressions are not normalized, so policy import extensions must handle these policy constructs. Also, policy import extensions may be called multiple times with the same and objects, so policy import extensions should be robust to this behavior. - +In Windows Communication Foundation (WCF), metadata import is the process of generating an abstract representation of a service or its component parts from its metadata. For example, WCF can import instances, instances or instances from a WSDL document for a service. To import service metadata in WCF, use an implementation of the abstract class. Types that derive from the class implement support for importing metadata formats that take advantage of the WS-Policy import logic in WCF. + + Custom metadata consists of XML elements that the system-provided metadata importers cannot import. Typically, this includes custom WSDL extensions and custom policy assertions. + + This section describes how to import custom WSDL extensions and policy assertions. It does not focus on the importing process itself. For more information about how to use the types that export and import metadata regardless of whether the metadata is custom or system-supported, see [Exporting and Importing Metadata](../feature-details/exporting-and-importing-metadata.md). + +## Overview + + The type is the implementation of the abstract class included with WCF. The type imports WSDL metadata with attached policies that are bundled in a object. Policy assertions and WSDL extensions that the default importers do not recognize are passed to any registered custom policy and WSDL importers for importing. Typically, importers are implemented to support user-defined binding elements or to modify the imported contract. + + This section describes: + +1. How to implement and use the interface, which exposes the WSDL data to custom importers prior to the generation of descriptions and the generation of code. You can use this interface to examine or modify the description types and code compilation performed using a given set of metadata. + +2. How to implement and use the interface, which exposes policy assertions to importers prior to the generation of description objects. You can use this interface to examine or modify the binding or contract based on the downloaded policies. + + For more information about exporting custom WSDL and policy assertions, see [Exporting Custom Metadata for a WCF Extension](exporting-custom-metadata-for-a-wcf-extension.md). + +## Importing Custom WSDL Extensions + + To add support for importing WSDL extensions, implement the interface and then add your implementation to the property. The can also load implementations of the interface registered in your application configuration file. Note that a number of WSDL importers are registered by default and the order of the registered WSDL importers is significant. + + When the custom WSDL importer is loaded and used by the , first the method is called to enable the modification of metadata prior to the import process. Next, the contracts are imported after which the method is called to enable the modification of the contracts imported from the metadata. Finally, the method is called to enable the modification of the imported endpoints. + + For more information, see [How to: Import Custom WSDL](how-to-import-custom-wsdl.md). + +### Importing Custom Policy Assertions + + The type and the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) automatically handle processing a variety of policy assertion types in policy expressions attached to WSDL documents. These tools collect, normalize, and merge policy expressions attached to WSDL bindings and WSDL ports. + + To add support for importing custom policy assertions, implement the interface and then add your implementation to the property. The can also load implementations of the interface registered in your application configuration file. Note that a number of policy importers are registered by default and the order of the registered policy importers is significant. + + The metadata system repeatedly calls the method on all registered policy import extensions for each combination of policy alternatives attached to the message, operation, and endpoint policy subjects. When importing a WSDL port, policies attached to the port and to the corresponding WSDL binding are merged before calling into the policy import extensions. The policy alternatives are made available through a as objects. Each is a collection of policy assertions represented by objects. + + The and properties on the object expose the and objects that were imported from the WSDL. Policy import extensions process policy assertions by finding instances of a particular policy assertion type, making corresponding changes to the or objects and then removing the policy assertions from the corresponding instance. + + The `wsp:Optional` attribute and nested policy expressions are not normalized, so policy import extensions must handle these policy constructs. Also, policy import extensions may be called multiple times with the same and objects, so policy import extensions should be robust to this behavior. + > [!IMPORTANT] -> Invalid or improper metadata can be passed to the importer. Ensure that custom importers are robust to all forms of XML. - +> Invalid or improper metadata can be passed to the importer. Ensure that custom importers are robust to all forms of XML. + ## See also - [How to: Import Custom WSDL](how-to-import-custom-wsdl.md) diff --git a/docs/framework/wcf/extending/publishing-and-retrieving-metadata-over-a-custom-binding.md b/docs/framework/wcf/extending/publishing-and-retrieving-metadata-over-a-custom-binding.md index 5870b5739f77f..0d0a4e39bc5e3 100644 --- a/docs/framework/wcf/extending/publishing-and-retrieving-metadata-over-a-custom-binding.md +++ b/docs/framework/wcf/extending/publishing-and-retrieving-metadata-over-a-custom-binding.md @@ -6,26 +6,26 @@ ms.assetid: 904e11b4-d90e-45c6-9ee5-c3472c90008c --- # Publishing and Retrieving Metadata Over a Custom Binding -The provides support for adding metadata endpoint to a service. These metadata endpoints can respond to HTTP GET requests at a URL that has a `?wsdl` querystring and to WS-Transfer GET requests as defined in the WS-MetadataExchange (MEX) specification. MEX endpoints implement the contract. - -## Publishing Metadata Over a Custom Binding - - The HTTP GET metadata endpoints and HTTPS GET metadata endpoints are enabled by setting the or properties to `true`. The bindings for these endpoints cannot be configured. - - The contract, however, can be used with any endpoint, including those that use custom bindings, because endpoints are identical to any other Windows Communication Foundation (WCF) service endpoint. If you know how to modify the configuration of a system-provided binding, or you know how to configure a , then you can configure a binding for use with an endpoint. - -## Retrieving Metadata Over a Custom Binding - - Metadata can be retrieved from HTTP Get and HTTPS Get metadata endpoints using standard HTTP or HTTPS GET requests. - - To retrieve metadata from a MEX metadata endpoint you can generally use one of the standard MEX bindings supported by WCF. For more information, see . The type and the Svcutil.exe tool automatically select one of these standard MEX bindings based on the address of the specified metadata endpoint. - - If a MEX metadata endpoint uses a different binding than one of the standard MEX bindings, you can configure the binding used by the using code or by providing an client endpoint configuration. The Svcutil.exe tool automatically loads from its configuration file an client endpoint configuration that has the same name as the URI scheme for the metadata endpoint address. - -## Security - - When publishing metadata over a custom binding, ensure that the binding provides the security support that your metadata requires. For example, to prevent information disclosure and ensure your client has the right to obtain the metadata, you can make your metadata and your application more secure by configuring your endpoint to require authentication and encryption. The sample [Custom Secure Metadata Endpoint](../samples/custom-secure-metadata-endpoint.md) demonstrates this scenario. - +The provides support for adding metadata endpoint to a service. These metadata endpoints can respond to HTTP GET requests at a URL that has a `?wsdl` querystring and to WS-Transfer GET requests as defined in the WS-MetadataExchange (MEX) specification. MEX endpoints implement the contract. + +## Publishing Metadata Over a Custom Binding + + The HTTP GET metadata endpoints and HTTPS GET metadata endpoints are enabled by setting the or properties to `true`. The bindings for these endpoints cannot be configured. + + The contract, however, can be used with any endpoint, including those that use custom bindings, because endpoints are identical to any other Windows Communication Foundation (WCF) service endpoint. If you know how to modify the configuration of a system-provided binding, or you know how to configure a , then you can configure a binding for use with an endpoint. + +## Retrieving Metadata Over a Custom Binding + + Metadata can be retrieved from HTTP Get and HTTPS Get metadata endpoints using standard HTTP or HTTPS GET requests. + + To retrieve metadata from a MEX metadata endpoint you can generally use one of the standard MEX bindings supported by WCF. For more information, see . The type and the Svcutil.exe tool automatically select one of these standard MEX bindings based on the address of the specified metadata endpoint. + + If a MEX metadata endpoint uses a different binding than one of the standard MEX bindings, you can configure the binding used by the using code or by providing an client endpoint configuration. The Svcutil.exe tool automatically loads from its configuration file an client endpoint configuration that has the same name as the URI scheme for the metadata endpoint address. + +## Security + + When publishing metadata over a custom binding, ensure that the binding provides the security support that your metadata requires. For example, to prevent information disclosure and ensure your client has the right to obtain the metadata, you can make your metadata and your application more secure by configuring your endpoint to require authentication and encryption. The sample [Custom Secure Metadata Endpoint](../samples/custom-secure-metadata-endpoint.md) demonstrates this scenario. + ## See also - [Securing Services](../securing-services.md) diff --git a/docs/framework/wcf/extending/service-channel-level-programming.md b/docs/framework/wcf/extending/service-channel-level-programming.md index 02836b99d56cb..538be09016384 100644 --- a/docs/framework/wcf/extending/service-channel-level-programming.md +++ b/docs/framework/wcf/extending/service-channel-level-programming.md @@ -2,62 +2,62 @@ description: "Learn more about: Service Channel-Level Programming" title: "Service Channel-Level Programming" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 8d8dcd85-0a05-4c44-8861-4a0b3b90cca9 --- # Service Channel-Level Programming -This topic describes how to write a Windows Communication Foundation (WCF) service application without using the and its associated object model. - -## Receiving Messages - - To be ready to receive and process messages, the following steps are required: - -1. Create a binding. - -2. Build a channel listener. - -3. Open the channel listener. - -4. Read the request and send a reply. - -5. Close all channel objects. - -#### Creating a Binding - - The first step in listening for and receiving messages is creating a binding. WCF ships with several built-in or system-provided bindings that can be used directly by instantiating one of them. In addition, you can also create your own custom binding by instantiating a CustomBinding class which is what the code in listing 1 does. - - The code example below creates an instance of and adds an to its Elements collection which is a collection of binding elements that are used to build the channel stack. In this example, because the elements collection has only the , the resulting channel stack has only the HTTP transport channel. - -#### Building a ChannelListener - - After creating a binding, we call to build the channel listener where the type parameter is the channel shape to create. In this example we are using because we want to listen for incoming messages in a request/reply message exchange pattern. - - is used for receiving request messages and sending back reply messages. Calling returns an , which can be used to receive the request message and to send back a reply message. - - When creating the listener, we pass the network address on which it listens, in this case `http://localhost:8080/channelapp`. In general, each transport channel supports one or possibly several address schemes, for example, the HTTP transport supports both http and https schemes. - - We also pass an empty when creating the listener. A binding parameter is a mechanism to pass parameters that control how the listener should be built. In our example, we are not using any such parameters so we pass an empty collection. - -#### Listening for Incoming Messages - - We then call on the listener and start accepting channels. The behavior of depends on whether the transport is connection-oriented or connection-less. For connection-oriented transports, blocks until a new connection request comes in at which point it returns a new channel that represents that new connection. For connection-less transports, such as HTTP, returns immediately with the one and only channel that the transport listener creates. - - In this example, the listener returns a channel that implements . To receive messages on this channel we first call on it to place it in a state ready for communication. We then call which blocks until a message arrives. - -#### Reading the Request and Sending a Reply - - When returns a , we get the received message using its property. We write out the message’s action and body content, (which we assume is a string). - - To send a reply, we create a new reply message in this case passing back the string data we received in the request. We then call to send the reply message. - -#### Closing Objects - - To avoid leaking resources, it is very important to close objects used in communications when they are no longer required. In this example we close the request message, the request context, the channel and the listener. - - The following code example shows a basic service in which a channel listener receives only one message. A real service keeps accepting channels and receiving messages until the service exits. - +This topic describes how to write a Windows Communication Foundation (WCF) service application without using the and its associated object model. + +## Receiving Messages + + To be ready to receive and process messages, the following steps are required: + +1. Create a binding. + +2. Build a channel listener. + +3. Open the channel listener. + +4. Read the request and send a reply. + +5. Close all channel objects. + +#### Creating a Binding + + The first step in listening for and receiving messages is creating a binding. WCF ships with several built-in or system-provided bindings that can be used directly by instantiating one of them. In addition, you can also create your own custom binding by instantiating a CustomBinding class which is what the code in listing 1 does. + + The code example below creates an instance of and adds an to its Elements collection which is a collection of binding elements that are used to build the channel stack. In this example, because the elements collection has only the , the resulting channel stack has only the HTTP transport channel. + +#### Building a ChannelListener + + After creating a binding, we call to build the channel listener where the type parameter is the channel shape to create. In this example we are using because we want to listen for incoming messages in a request/reply message exchange pattern. + + is used for receiving request messages and sending back reply messages. Calling returns an , which can be used to receive the request message and to send back a reply message. + + When creating the listener, we pass the network address on which it listens, in this case `http://localhost:8080/channelapp`. In general, each transport channel supports one or possibly several address schemes, for example, the HTTP transport supports both http and https schemes. + + We also pass an empty when creating the listener. A binding parameter is a mechanism to pass parameters that control how the listener should be built. In our example, we are not using any such parameters so we pass an empty collection. + +#### Listening for Incoming Messages + + We then call on the listener and start accepting channels. The behavior of depends on whether the transport is connection-oriented or connection-less. For connection-oriented transports, blocks until a new connection request comes in at which point it returns a new channel that represents that new connection. For connection-less transports, such as HTTP, returns immediately with the one and only channel that the transport listener creates. + + In this example, the listener returns a channel that implements . To receive messages on this channel we first call on it to place it in a state ready for communication. We then call which blocks until a message arrives. + +#### Reading the Request and Sending a Reply + + When returns a , we get the received message using its property. We write out the message’s action and body content, (which we assume is a string). + + To send a reply, we create a new reply message in this case passing back the string data we received in the request. We then call to send the reply message. + +#### Closing Objects + + To avoid leaking resources, it is very important to close objects used in communications when they are no longer required. In this example we close the request message, the request context, the channel and the listener. + + The following code example shows a basic service in which a channel listener receives only one message. A real service keeps accepting channels and receiving messages until the service exits. + [!code-csharp[ChannelProgrammingBasic#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/channelprogrammingbasic/cs/serviceprogram.cs#1)] [!code-vb[ChannelProgrammingBasic#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/channelprogrammingbasic/vb/serviceprogram.vb#1)] diff --git a/docs/framework/wcf/extending/service-channel-listeners-and-channels.md b/docs/framework/wcf/extending/service-channel-listeners-and-channels.md index 1ecc02825207c..bacdcdfae6c42 100644 --- a/docs/framework/wcf/extending/service-channel-listeners-and-channels.md +++ b/docs/framework/wcf/extending/service-channel-listeners-and-channels.md @@ -43,8 +43,8 @@ message = UdpConstants.MessageEncoder.ReadMessage( ); ``` -Because the same datagram channel represents messages that arrive from a number of sources, the `UdpChannelListener` is a singleton listener. There is at most one active associated with this listener at a time. The sample generates another one only if a channel that is returned by the method is subsequently disposed. When a message is received, it's enqueued into this singleton channel. +Because the same datagram channel represents messages that arrive from a number of sources, the `UdpChannelListener` is a singleton listener. There is at most one active associated with this listener at a time. The sample generates another one only if a channel that is returned by the method is subsequently disposed. When a message is received, it's enqueued into this singleton channel. ### UdpInputChannel -The `UdpInputChannel` class implements . It consists of a queue of incoming messages that is populated by the `UdpChannelListener`'s socket. These messages are dequeued by the method. +The `UdpInputChannel` class implements . It consists of a queue of incoming messages that is populated by the `UdpChannelListener`'s socket. These messages are dequeued by the method. diff --git a/docs/framework/wcf/extending/understanding-state-changes.md b/docs/framework/wcf/extending/understanding-state-changes.md index 78c51abc68bd4..d2aefc5d8932f 100644 --- a/docs/framework/wcf/extending/understanding-state-changes.md +++ b/docs/framework/wcf/extending/understanding-state-changes.md @@ -6,168 +6,168 @@ ms.assetid: a79ed2aa-e49a-47a8-845a-c9f436ec9987 --- # Understanding State Changes -This topic discusses the states and transitions that channels have, the types used to structure channel states, and how to implement them. - -## State Machines and Channels - - Objects that deal with communication, for example sockets, usually present a state machine whose state transitions relate to allocating network resources, making or accepting connections, closing connections and terminating communication. The channel state machine provides a uniform model of the states of a communication object that abstracts the underlying implementation of that object. The interface provides a set of states, state transition methods and state transition events. All channels, channel factories and channel listeners implement the channel state machine. - - The events Closed, Closing, Faulted, Opened and Opening signal an external observer after a state transition occurs. - - The methods Abort, Close, and Open (and their asynchronous equivalents) cause state transitions. - - The state property returns the current state as defined by : - -## ICommunicationObject, CommunicationObject, and States and State Transition - - An starts out in the Created state where its various properties can be configured. Once in the Opened state, the object is usable for sending and receiving messages but its properties are considered immutable. Once in the Closing state, the object can no longer process new send or receive requests, but existing requests have a chance to complete until the Close timeout is reached. If an unrecoverable error occurs, the object transitions to the Faulted state where it can be inspected for information about the error and ultimately closed. When in the Closed state the object has essentially reached the end of the state machine. Once an object transitions from one state to the next, it does not go back to a previous state. - - The following diagram shows the states and state transitions. State transitions can be caused by calling one of the three methods: Abort, Open, or Close. They could also be caused by calling other implementation-specific methods. Transitioning to the Faulted state could happen as a result of errors while opening or after having opened the communication object. - - Every starts out in the Created state. In this state, an application can configure the object by setting its properties. Once an object is in a state other than Created, it is considered immutable. - - ![Dataflow diagram of the channel state transition.](./media/understanding-state-changes/channel-state-transitions.gif) -Figure 1. The ICommunicationObject State Machine. - - Windows Communication Foundation (WCF) provides an abstract base class named that implements and the channel state machine. The following graphic is a modified state diagram that is specific to . In addition to the state machine, it shows the timing when additional methods are invoked. - +This topic discusses the states and transitions that channels have, the types used to structure channel states, and how to implement them. + +## State Machines and Channels + + Objects that deal with communication, for example sockets, usually present a state machine whose state transitions relate to allocating network resources, making or accepting connections, closing connections and terminating communication. The channel state machine provides a uniform model of the states of a communication object that abstracts the underlying implementation of that object. The interface provides a set of states, state transition methods and state transition events. All channels, channel factories and channel listeners implement the channel state machine. + + The events Closed, Closing, Faulted, Opened and Opening signal an external observer after a state transition occurs. + + The methods Abort, Close, and Open (and their asynchronous equivalents) cause state transitions. + + The state property returns the current state as defined by : + +## ICommunicationObject, CommunicationObject, and States and State Transition + + An starts out in the Created state where its various properties can be configured. Once in the Opened state, the object is usable for sending and receiving messages but its properties are considered immutable. Once in the Closing state, the object can no longer process new send or receive requests, but existing requests have a chance to complete until the Close timeout is reached. If an unrecoverable error occurs, the object transitions to the Faulted state where it can be inspected for information about the error and ultimately closed. When in the Closed state the object has essentially reached the end of the state machine. Once an object transitions from one state to the next, it does not go back to a previous state. + + The following diagram shows the states and state transitions. State transitions can be caused by calling one of the three methods: Abort, Open, or Close. They could also be caused by calling other implementation-specific methods. Transitioning to the Faulted state could happen as a result of errors while opening or after having opened the communication object. + + Every starts out in the Created state. In this state, an application can configure the object by setting its properties. Once an object is in a state other than Created, it is considered immutable. + + ![Dataflow diagram of the channel state transition.](./media/understanding-state-changes/channel-state-transitions.gif) +Figure 1. The ICommunicationObject State Machine. + + Windows Communication Foundation (WCF) provides an abstract base class named that implements and the channel state machine. The following graphic is a modified state diagram that is specific to . In addition to the state machine, it shows the timing when additional methods are invoked. + ![Dataflow diagram of CommunicationObject implementation state changes.](./media/understanding-state-changes/communicationobject-implementation-state-machine.gif) -Figure 2. The CommunicationObject implementation of the ICommunicationObject state machine including calls to events and protected methods. - -### ICommunicationObject Events - - exposes the five events defined by . These events are designed for code using the communication object to be notified of state transitions. As shown in Figure 2 above, each event is fired once after the object’s state transitions to the state named by the event. All five events are of the `EventHandler` type which is defined as: - - `public delegate void EventHandler(object sender, EventArgs e);` - - In the implementation, the sender is either the itself or whatever was passed in as the sender to the constructor (if that constructor overload was used). The EventArgs parameter, `e`, is always `EventArgs.Empty`. - -### Derived Object Callbacks - - In addition to the five events, declares eight protected virtual methods designed to allow a derived object to be called back before and after state transitions occur. - - The and methods have three such callbacks associated with each of them. For example, corresponding to there is , , and . Associated with are the , , and methods. - - Similarly, the method has a corresponding . - - While , , and have no default implementation, the other callbacks do have a default implementation which is necessary for state machine correctness. If you override those methods be sure to call the base implementation or correctly replace it. - - , and fire the corresponding , and events. and set the object state to Opened and Closed respectively then fire the corresponding and events. - -### State Transition Methods - - provides implementations of Abort, Close and Open. It also provides a Fault method which causes a state transition to the Faulted state. Figure 2 shows the state machine with each transition labeled by the method that causes it (unlabeled transitions happen inside the implementation of the method that caused the last labeled transition). - +Figure 2. The CommunicationObject implementation of the ICommunicationObject state machine including calls to events and protected methods. + +### ICommunicationObject Events + + exposes the five events defined by . These events are designed for code using the communication object to be notified of state transitions. As shown in Figure 2 above, each event is fired once after the object’s state transitions to the state named by the event. All five events are of the `EventHandler` type which is defined as: + + `public delegate void EventHandler(object sender, EventArgs e);` + + In the implementation, the sender is either the itself or whatever was passed in as the sender to the constructor (if that constructor overload was used). The EventArgs parameter, `e`, is always `EventArgs.Empty`. + +### Derived Object Callbacks + + In addition to the five events, declares eight protected virtual methods designed to allow a derived object to be called back before and after state transitions occur. + + The and methods have three such callbacks associated with each of them. For example, corresponding to there is , , and . Associated with are the , , and methods. + + Similarly, the method has a corresponding . + + While , , and have no default implementation, the other callbacks do have a default implementation which is necessary for state machine correctness. If you override those methods be sure to call the base implementation or correctly replace it. + + , and fire the corresponding , and events. and set the object state to Opened and Closed respectively then fire the corresponding and events. + +### State Transition Methods + + provides implementations of Abort, Close and Open. It also provides a Fault method which causes a state transition to the Faulted state. Figure 2 shows the state machine with each transition labeled by the method that causes it (unlabeled transitions happen inside the implementation of the method that caused the last labeled transition). + > [!NOTE] -> All implementations of communication state gets/sets are thread-synchronized. - - Constructor - - provides three constructors, all of which leave the object in the Created state. The constructors are defined as: - - The first constructor is a parameterless constructor that delegates to the constructor overload that takes an object: - - `protected CommunicationObject() : this(new object()) { … }` - - The constructor that takes an object uses that parameter as the object to be locked when synchronizing access to communication object state: - - `protected CommunicationObject(object mutex) { … }` - - Finally, a third constructor takes an additional parameter that is used as the sender argument when events are fired. - - `protected CommunicationObject(object mutex, object eventSender) { … }` - - The previous two constructors set the sender to this. - - Open Method - - Precondition: State is Created. - - Post-condition: State is Opened or Faulted. May throw an exception. - - The Open() method will try to open the communication object and set the state to Opened. If it encounters an error, it will set the state to Faulted. - - The method first checks that the current state is Created. If the current state is Opening or Opened it throws an . If the current state is Closing or Closed, it throws a if the object has been terminated and otherwise. If the current state is Faulted, it throws a . - - It then sets the state to Opening and calls OnOpening() (which raises the Opening event), OnOpen() and OnOpened() in that order. OnOpened() sets the state to Opened and raises the Opened event. If any of these throws an exception, Open()calls Fault() and lets the exception bubble up. The following diagram shows the Open process in more detail. - - ![Dataflow diagram of ICommunicationObject.Open state changes.](./media/understanding-state-changes/ico-open-process-override-onopen.gif) -Override the OnOpen method to implement custom open logic such as opening an inner communication object. - - Close Method - - Precondition: None. - - Post-condition: State is Closed. May throw an exception. - - The Close() method can be called at any state. It tries to close the object normally. If an error is encountered, it terminates the object. The method does nothing if the current state is Closing or Closed. Otherwise it sets the state to Closing. If the original state was Created, Opening or Faulted, it calls Abort() (see the following diagram). If the original state was Opened, it calls OnClosing() (which raises the Closing event), OnClose() and OnClosed() in that order. If any of these throws an exception, Close()calls Abort() and lets the exception bubble up. OnClosed() sets the state to Closed and raises the Closed event. The following diagram shows the Close process in more detail. - - ![Dataflow diagram of ICommunicationObject.Close state changes.](./media/understanding-state-changes/ico-close-process-override-onclose.gif) -Override the OnClose method to implement custom close logic, such as closing an inner communication object. All graceful closing logic that may block for a long time (for example, waiting for the other side to respond) should be implemented in OnClose() because it takes a timeout parameter and because it is not called as part of Abort(). - - Abort - - Precondition: None. -Post-condition: State is Closed. May throw an exception. - - The Abort() method does nothing if the current state is Closed or if the object has been terminated before (for example, possibly by having Abort() executing on another thread). Otherwise it sets the state to Closing and calls OnClosing() (which raises the Closing event), OnAbort(), and OnClosed() in that order (does not call OnClose because the object is being terminated, not closed). OnClosed() sets the state to Closed and raises the Closed event. If any of these throw an exception, it is re-thrown to the caller of Abort. Implementations of OnClosing(), OnClosed() and OnAbort() should not block (for example, on input/output). The following diagram shows the Abort process in more detail. - - ![Dataflow diagram of ICommunicationObject.Abort state changes.](./media/understanding-state-changes/ico-abort-process-override-onabort.gif) -Override the OnAbort method to implement custom terminate logic such as terminating an inner communication object. - - Fault - - The Fault method is specific to and is not part of the interface. It is included here for completeness. - - Precondition: None. - - Post-condition: State is Faulted. May throw an exception. - - The Fault() method does nothing if the current state is Faulted or Closed. Otherwise it sets the state to Faulted and call OnFaulted(), which raises the Faulted event. If OnFaulted throws an exception it is re-thrown. - -### ThrowIfXxx Methods - - CommunicationObject has three protected methods that can be used to throw exceptions if the object is in a specific state. - - throws an exception if the state is Closing, Closed or Faulted. - - throws an exception if the state is not Created. - - throws an exception if the state is not Opened. - - The exceptions thrown depend on the state. The following table shows the different states and the corresponding exception type thrown by calling a ThrowIfXxx that throws on that state. - -|State|Has Abort been called?|Exception| -|-----------|----------------------------|---------------| -|Created|N/A|| -|Opening|N/A|| -|Opened|N/A|| -|Closing|Yes|| -|Closing|No|| -|Closed|Yes| in the case that an object was closed by a previous and explicit call of Abort. If you call Close on the object then an is thrown.| -|Closed|No|| -|Faulted|N/A|| - -### Timeouts - - Several of the methods we discussed take timeout parameters. These are Close, Open (certain overloads and asynchronous versions), OnClose and OnOpen. These methods are designed to allow for lengthy operations (for example, blocking on input/output while gracefully closing down a connection) so the timeout parameter indicates how long such operations can take before being interrupted. Implementations of any of these methods should use the supplied timeout value to ensure it returns to the caller within that timeout. Implementations of other methods that do not take a timeout are not designed for lengthy operations and should not block on input/output. - - The exception are the Open() and Close() overloads that do not take a timeout. These use a default timeout value supplied by the derived class. exposes two protected abstract properties named and defined as: - - `protected abstract TimeSpan DefaultCloseTimeout { get; }` - - `protected abstract TimeSpan DefaultOpenTimeout { get; }` - - A derived class implements these properties to provide the default timeout for the Open() and Close() overloads that do not take a timeout value. Then the Open() and Close() implementations delegate to the overload that takes a timeout passing it the default timeout value, for example: - - `public void Open()` - - `{` - - `this.Open(this.DefaultOpenTimeout);` - - `}` - -#### IDefaultCommunicationTimeouts +> All implementations of communication state gets/sets are thread-synchronized. + + Constructor + + provides three constructors, all of which leave the object in the Created state. The constructors are defined as: + + The first constructor is a parameterless constructor that delegates to the constructor overload that takes an object: + + `protected CommunicationObject() : this(new object()) { … }` + + The constructor that takes an object uses that parameter as the object to be locked when synchronizing access to communication object state: + + `protected CommunicationObject(object mutex) { … }` + + Finally, a third constructor takes an additional parameter that is used as the sender argument when events are fired. + + `protected CommunicationObject(object mutex, object eventSender) { … }` + + The previous two constructors set the sender to this. + + Open Method + + Precondition: State is Created. + + Post-condition: State is Opened or Faulted. May throw an exception. + + The Open() method will try to open the communication object and set the state to Opened. If it encounters an error, it will set the state to Faulted. + + The method first checks that the current state is Created. If the current state is Opening or Opened it throws an . If the current state is Closing or Closed, it throws a if the object has been terminated and otherwise. If the current state is Faulted, it throws a . + + It then sets the state to Opening and calls OnOpening() (which raises the Opening event), OnOpen() and OnOpened() in that order. OnOpened() sets the state to Opened and raises the Opened event. If any of these throws an exception, Open()calls Fault() and lets the exception bubble up. The following diagram shows the Open process in more detail. + + ![Dataflow diagram of ICommunicationObject.Open state changes.](./media/understanding-state-changes/ico-open-process-override-onopen.gif) +Override the OnOpen method to implement custom open logic such as opening an inner communication object. + + Close Method + + Precondition: None. + + Post-condition: State is Closed. May throw an exception. + + The Close() method can be called at any state. It tries to close the object normally. If an error is encountered, it terminates the object. The method does nothing if the current state is Closing or Closed. Otherwise it sets the state to Closing. If the original state was Created, Opening or Faulted, it calls Abort() (see the following diagram). If the original state was Opened, it calls OnClosing() (which raises the Closing event), OnClose() and OnClosed() in that order. If any of these throws an exception, Close()calls Abort() and lets the exception bubble up. OnClosed() sets the state to Closed and raises the Closed event. The following diagram shows the Close process in more detail. + + ![Dataflow diagram of ICommunicationObject.Close state changes.](./media/understanding-state-changes/ico-close-process-override-onclose.gif) +Override the OnClose method to implement custom close logic, such as closing an inner communication object. All graceful closing logic that may block for a long time (for example, waiting for the other side to respond) should be implemented in OnClose() because it takes a timeout parameter and because it is not called as part of Abort(). + + Abort + + Precondition: None. +Post-condition: State is Closed. May throw an exception. + + The Abort() method does nothing if the current state is Closed or if the object has been terminated before (for example, possibly by having Abort() executing on another thread). Otherwise it sets the state to Closing and calls OnClosing() (which raises the Closing event), OnAbort(), and OnClosed() in that order (does not call OnClose because the object is being terminated, not closed). OnClosed() sets the state to Closed and raises the Closed event. If any of these throw an exception, it is re-thrown to the caller of Abort. Implementations of OnClosing(), OnClosed() and OnAbort() should not block (for example, on input/output). The following diagram shows the Abort process in more detail. + + ![Dataflow diagram of ICommunicationObject.Abort state changes.](./media/understanding-state-changes/ico-abort-process-override-onabort.gif) +Override the OnAbort method to implement custom terminate logic such as terminating an inner communication object. + + Fault + + The Fault method is specific to and is not part of the interface. It is included here for completeness. + + Precondition: None. + + Post-condition: State is Faulted. May throw an exception. + + The Fault() method does nothing if the current state is Faulted or Closed. Otherwise it sets the state to Faulted and call OnFaulted(), which raises the Faulted event. If OnFaulted throws an exception it is re-thrown. + +### ThrowIfXxx Methods + + CommunicationObject has three protected methods that can be used to throw exceptions if the object is in a specific state. + + throws an exception if the state is Closing, Closed or Faulted. + + throws an exception if the state is not Created. + + throws an exception if the state is not Opened. + + The exceptions thrown depend on the state. The following table shows the different states and the corresponding exception type thrown by calling a ThrowIfXxx that throws on that state. + +|State|Has Abort been called?|Exception| +|-----------|----------------------------|---------------| +|Created|N/A|| +|Opening|N/A|| +|Opened|N/A|| +|Closing|Yes|| +|Closing|No|| +|Closed|Yes| in the case that an object was closed by a previous and explicit call of Abort. If you call Close on the object then an is thrown.| +|Closed|No|| +|Faulted|N/A|| + +### Timeouts + + Several of the methods we discussed take timeout parameters. These are Close, Open (certain overloads and asynchronous versions), OnClose and OnOpen. These methods are designed to allow for lengthy operations (for example, blocking on input/output while gracefully closing down a connection) so the timeout parameter indicates how long such operations can take before being interrupted. Implementations of any of these methods should use the supplied timeout value to ensure it returns to the caller within that timeout. Implementations of other methods that do not take a timeout are not designed for lengthy operations and should not block on input/output. + + The exception are the Open() and Close() overloads that do not take a timeout. These use a default timeout value supplied by the derived class. exposes two protected abstract properties named and defined as: + + `protected abstract TimeSpan DefaultCloseTimeout { get; }` + + `protected abstract TimeSpan DefaultOpenTimeout { get; }` + + A derived class implements these properties to provide the default timeout for the Open() and Close() overloads that do not take a timeout value. Then the Open() and Close() implementations delegate to the overload that takes a timeout passing it the default timeout value, for example: + + `public void Open()` + + `{` + + `this.Open(this.DefaultOpenTimeout);` + + `}` + +#### IDefaultCommunicationTimeouts This interface has four read-only properties for providing default timeout values for open, send, receive, and close. Each implementation is responsible for obtaining the default values in whatever manner appropriate. As a convenience, and default these values to 1 minute each. diff --git a/docs/framework/wcf/extending/walkthrough-creating-custom-client-and-service-credentials.md b/docs/framework/wcf/extending/walkthrough-creating-custom-client-and-service-credentials.md index dd83395e84b66..763947ae34832 100644 --- a/docs/framework/wcf/extending/walkthrough-creating-custom-client-and-service-credentials.md +++ b/docs/framework/wcf/extending/walkthrough-creating-custom-client-and-service-credentials.md @@ -51,12 +51,12 @@ Creating a custom credentials class is only the first step, because the reason f 2. Optional. Add new methods or properties for new credential types. If you do not add new credential types, skip this step. The following example adds a `CreditCardNumber` property. -3. Override the method. This method is automatically called by WCF security infrastructure when the custom client credential is used. This method is responsible for creating and returning an instance of an implementation of the class. +3. Override the method. This method is automatically called by WCF security infrastructure when the custom client credential is used. This method is responsible for creating and returning an instance of an implementation of the class. > [!IMPORTANT] - > It is important to note that the method is overridden to create a custom security token manager. The security token manager, derived from , must return a custom security token provider, derived from , to create the actual security token. If you do not follow this pattern for creating security tokens, your application may function incorrectly when objects are cached (which is the default behavior for WCF client proxies), potentially resulting in an elevation of privilege attack. The custom credential object is cached as part of the . However, the custom is created on every invocation, which mitigates the security threat as long as the token creation logic is placed in the . + > It is important to note that the method is overridden to create a custom security token manager. The security token manager, derived from , must return a custom security token provider, derived from , to create the actual security token. If you do not follow this pattern for creating security tokens, your application may function incorrectly when objects are cached (which is the default behavior for WCF client proxies), potentially resulting in an elevation of privilege attack. The custom credential object is cached as part of the . However, the custom is created on every invocation, which mitigates the security threat as long as the token creation logic is placed in the . -4. Override the method. +4. Override the method. [!code-csharp[c_CustomCredentials#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customcredentials/cs/source.cs#1)] [!code-vb[c_CustomCredentials#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customcredentials/vb/client/client.vb#1)] @@ -69,7 +69,7 @@ Creating a custom credentials class is only the first step, because the reason f 3. Optional. Override the method if a custom implementation must be created. For more information about custom security token authenticators, see [How to: Create a Custom Security Token Authenticator](how-to-create-a-custom-security-token-authenticator.md). -4. Optional. Override the method if a custom must be created. For more information about custom security tokens and custom security token serializers, see [How to: Create a Custom Token](how-to-create-a-custom-token.md). +4. Optional. Override the method if a custom must be created. For more information about custom security tokens and custom security token serializers, see [How to: Create a Custom Token](how-to-create-a-custom-token.md). [!code-csharp[c_CustomCredentials#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customcredentials/cs/source.cs#2)] [!code-vb[c_CustomCredentials#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customcredentials/vb/client/client.vb#2)] @@ -78,9 +78,9 @@ Creating a custom credentials class is only the first step, because the reason f 1. Either create an instance of the generated client that represents the service interface, or create an instance of the pointing to a service you want to communicate with. -2. Remove the system-provided client credentials behavior from the collection, which can be accessed through the property. +2. Remove the system-provided client credentials behavior from the collection, which can be accessed through the property. -3. Create a new instance of a custom client credentials class and add it to the collection, which can be accessed through the property. +3. Create a new instance of a custom client credentials class and add it to the collection, which can be accessed through the property. [!code-csharp[c_CustomCredentials#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customcredentials/cs/source.cs#3)] [!code-vb[c_CustomCredentials#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customcredentials/vb/client/client.vb#3)] @@ -95,11 +95,11 @@ The next procedure describes how to provide support for configuration of custom 2. Optional. Add properties for all additional configuration parameters that you want to expose through application configuration. The example below adds one property named `CreditCardNumber`. -3. Override the property to return the type of the custom client credentials class created with the configuration element. +3. Override the property to return the type of the custom client credentials class created with the configuration element. -4. Override the method. The method is responsible for creating and returning an instance of the custom credential class based on the settings loaded from the configuration file. Call the base method from this method to retrieve the system-provided credentials settings loaded into your custom client credentials instance. +4. Override the method. The method is responsible for creating and returning an instance of the custom credential class based on the settings loaded from the configuration file. Call the base method from this method to retrieve the system-provided credentials settings loaded into your custom client credentials instance. -5. Optional. If you added additional properties in step 2, you need to override the property in order to register your additional configuration settings for the configuration framework to recognize them. Combine your properties with the base class properties to allow the system-provided settings to be configured through this custom client credentials configuration element. +5. Optional. If you added additional properties in step 2, you need to override the property in order to register your additional configuration settings for the configuration framework to recognize them. Combine your properties with the base class properties to allow the system-provided settings to be configured through this custom client credentials configuration element. [!code-csharp[c_CustomCredentials#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customcredentials/cs/source.cs#7)] [!code-vb[c_CustomCredentials#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customcredentials/vb/service/service.vb#7)] @@ -142,9 +142,9 @@ Once you have the configuration handler class, it can be integrated into the WCF 2. Optional. Add new properties to provide APIs for new credential values that are being added. If you do not add new credential values, skip this step. The following example adds an `AdditionalCertificate` property. -3. Override the method. This method is automatically called by the WCF infrastructure when the custom client credential is used. The method is responsible for creating and returning an instance of an implementation of the class (described in the next procedure). +3. Override the method. This method is automatically called by the WCF infrastructure when the custom client credential is used. The method is responsible for creating and returning an instance of an implementation of the class (described in the next procedure). -4. Optional. Override the method. This is required only if adding new properties or internal fields to the custom client credentials implementation. +4. Optional. Override the method. This is required only if adding new properties or internal fields to the custom client credentials implementation. [!code-csharp[c_CustomCredentials#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customcredentials/cs/source.cs#4)] [!code-vb[c_CustomCredentials#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customcredentials/vb/service/service.vb#4)] @@ -153,9 +153,9 @@ Once you have the configuration handler class, it can be integrated into the WCF 1. Define a new class derived from the class. -2. Optional. Override the method if a custom implementation must be created. For more information about custom security token providers, see [How to: Create a Custom Security Token Provider](how-to-create-a-custom-security-token-provider.md). +2. Optional. Override the method if a custom implementation must be created. For more information about custom security token providers, see [How to: Create a Custom Security Token Provider](how-to-create-a-custom-security-token-provider.md). -3. Optional. Override the method if a custom implementation must be created. For more information about custom security token authenticators, see [How to: Create a Custom Security Token Authenticator](how-to-create-a-custom-security-token-authenticator.md) topic. +3. Optional. Override the method if a custom implementation must be created. For more information about custom security token authenticators, see [How to: Create a Custom Security Token Authenticator](how-to-create-a-custom-security-token-authenticator.md) topic. 4. Optional. Override the method if a custom must be created. For more information about custom security tokens and custom security token serializers, see [How to: Create a Custom Token](how-to-create-a-custom-token.md). @@ -166,9 +166,9 @@ Once you have the configuration handler class, it can be integrated into the WCF 1. Create an instance of the . -2. Remove the system-provided service credentials behavior from the collection. +2. Remove the system-provided service credentials behavior from the collection. -3. Create a new instance of the custom service credentials class and add it to the collection. +3. Create a new instance of the custom service credentials class and add it to the collection. [!code-csharp[c_CustomCredentials#6](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_customcredentials/cs/source.cs#6)] [!code-vb[c_CustomCredentials#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_customcredentials/vb/service/service.vb#6)] diff --git a/docs/framework/wcf/feature-details/accessing-services-using-a-client.md b/docs/framework/wcf/feature-details/accessing-services-using-a-client.md index 6106478933eab..979cf31ee20c6 100644 --- a/docs/framework/wcf/feature-details/accessing-services-using-a-client.md +++ b/docs/framework/wcf/feature-details/accessing-services-using-a-client.md @@ -2,99 +2,99 @@ description: "Learn more about: Accessing Services Using a Client" title: "Accessing Services Using a Client" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: c8329832-bf66-4064-9034-bf39f153fc2d --- # Accessing Services Using a Client -Client applications must create, configure, and use WCF client or channel objects to communicate with services. The [WCF Client Overview](../wcf-client-overview.md) topic provides an overview of the objects and steps involved in creating basic client and channel objects and using them. - - This topic provides in-depth information about some of the issues with client applications and client and channel objects that may be useful depending upon your scenario. - -## Overview - - This topic describes behavior and issues relating to: - -- Channel and session lifetimes. - -- Handling exceptions. - -- Understanding blocking issues. - -- Initializing channels interactively. - -### Channel and Session Lifetimes - - Windows Communication Foundation (WCF) applications includes two categories of channels, datagram and sessionful. - - A *datagram* channel is a channel in which all messages are uncorrelated. With a datagram channel, if an input or output operation fails, the next operation is typically unaffected, and the same channel can be reused. Because of this, datagram channels typically do not fault. - - *Sessionful* channels, however, are channels with a connection to the other endpoint. Messages in a session on one side are always correlated with the same session on the other side. In addition, both participants in a session must agree that the requirements of their conversation were met for that session to be considered successful. If they cannot agree, the sessionful channel may fault. - - Open clients explicitly or implicitly by calling the first operation. - +Client applications must create, configure, and use WCF client or channel objects to communicate with services. The [WCF Client Overview](../wcf-client-overview.md) topic provides an overview of the objects and steps involved in creating basic client and channel objects and using them. + + This topic provides in-depth information about some of the issues with client applications and client and channel objects that may be useful depending upon your scenario. + +## Overview + + This topic describes behavior and issues relating to: + +- Channel and session lifetimes. + +- Handling exceptions. + +- Understanding blocking issues. + +- Initializing channels interactively. + +### Channel and Session Lifetimes + + Windows Communication Foundation (WCF) applications includes two categories of channels, datagram and sessionful. + + A *datagram* channel is a channel in which all messages are uncorrelated. With a datagram channel, if an input or output operation fails, the next operation is typically unaffected, and the same channel can be reused. Because of this, datagram channels typically do not fault. + + *Sessionful* channels, however, are channels with a connection to the other endpoint. Messages in a session on one side are always correlated with the same session on the other side. In addition, both participants in a session must agree that the requirements of their conversation were met for that session to be considered successful. If they cannot agree, the sessionful channel may fault. + + Open clients explicitly or implicitly by calling the first operation. + > [!NOTE] -> Trying to explicitly detect faulted sessionful channels is not typically useful, because when you are notified depends upon the session implementation. For example, because the (with the reliable session disabled) surfaces the session of the TCP connection, if you listen to the event on the service or the client you are likely to be notified quickly in the event of a network failure. But reliable sessions (established by bindings in which the is enabled) are designed to insulate services from small network failures. If the session can be reestablished within a reasonable period of time, the same binding—configured for reliable sessions—might not fault until the interruption continued for a longer period of time. - - Most of the system-provided bindings (which expose channels to the application layer) use sessions by default, but the does not. For more information, see [Using Sessions](../using-sessions.md). - -### The Proper Use of Sessions - - Sessions provide a way to know if the entire message exchange is complete, and if both sides considered it successful. It is recommended that a calling application open the channel, use it, and close the channel inside one try block. If a session channel is open, and the method is called once, and that call returns successfully, then the session was successful. Successful in this case means that all delivery guarantees the binding specified were met, and the other side did not call on the channel before calling . - - The following section provides an example of this client approach. - -### Handling Exceptions - - Handling exceptions in client applications is straightforward. If a channel is opened, used, and closed inside a try block, then the conversation has succeeded, unless an exception is thrown. Typically, if an exception is thrown the conversation is aborted. - +> Trying to explicitly detect faulted sessionful channels is not typically useful, because when you are notified depends upon the session implementation. For example, because the (with the reliable session disabled) surfaces the session of the TCP connection, if you listen to the event on the service or the client you are likely to be notified quickly in the event of a network failure. But reliable sessions (established by bindings in which the is enabled) are designed to insulate services from small network failures. If the session can be reestablished within a reasonable period of time, the same binding—configured for reliable sessions—might not fault until the interruption continued for a longer period of time. + + Most of the system-provided bindings (which expose channels to the application layer) use sessions by default, but the does not. For more information, see [Using Sessions](../using-sessions.md). + +### The Proper Use of Sessions + + Sessions provide a way to know if the entire message exchange is complete, and if both sides considered it successful. It is recommended that a calling application open the channel, use it, and close the channel inside one try block. If a session channel is open, and the method is called once, and that call returns successfully, then the session was successful. Successful in this case means that all delivery guarantees the binding specified were met, and the other side did not call on the channel before calling . + + The following section provides an example of this client approach. + +### Handling Exceptions + + Handling exceptions in client applications is straightforward. If a channel is opened, used, and closed inside a try block, then the conversation has succeeded, unless an exception is thrown. Typically, if an exception is thrown the conversation is aborted. + > [!NOTE] -> Use of the `using` statement (`Using` in Visual Basic) is not recommended. This is because the end of the `using` statement can cause exceptions that can mask other exceptions you may need to know about. For more information, see [Use Close and Abort to release WCF client resources](../samples/use-close-abort-release-wcf-client-resources.md). - - The following code example shows the recommended client pattern using a try/catch block and not the `using` statement. - +> Use of the `using` statement (`Using` in Visual Basic) is not recommended. This is because the end of the `using` statement can cause exceptions that can mask other exceptions you may need to know about. For more information, see [Use Close and Abort to release WCF client resources](../samples/use-close-abort-release-wcf-client-resources.md). + + The following code example shows the recommended client pattern using a try/catch block and not the `using` statement. + [!code-csharp[FaultContractAttribute#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/faultcontractattribute/cs/client.cs#3)] - [!code-vb[FaultContractAttribute#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/client.vb#3)] - + [!code-vb[FaultContractAttribute#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/client.vb#3)] + > [!NOTE] -> Checking the value of the property is a race condition and is not recommended to determine whether to reuse or close a channel. - - Datagram channels never fault even if exceptions occur when they are closed. In addition, non-duplex clients that fail to authenticate using a secure conversation typically throw a . However if the duplex client using a secure conversation fails to authenticate, the client receives a instead. - - For more complete information about working with error information at the application level, see [Specifying and Handling Faults in Contracts and Services](../specifying-and-handling-faults-in-contracts-and-services.md). [Expected Exceptions](../samples/expected-exceptions.md) describes expected exceptions and shows how to handle them. For more information about how to handle errors when developing channels, see [Handling Exceptions and Faults](../extending/handling-exceptions-and-faults.md). - -### Client Blocking and Performance - - When an application synchronously calls a request-reply operation, the client blocks until a return value is received or an exception (such as a ) is thrown. This behavior is similar to local behavior. When an application synchronously invokes an operation on a WCF client object or channel, the client does not return until the channel layer can write the data to the network or until an exception is thrown. And while the one-way message exchange pattern (specified by marking an operation with set to `true`) can make some clients more responsive, one-way operations can also block, depending upon the binding and what messages have already been sent. One-way operations are only about the message exchange, no more and no less. For more information, see [One-Way Services](one-way-services.md). - - Large data chunks can slow client processing no matter what the message exchange pattern. To understand how to handle these issues, see [Large Data and Streaming](large-data-and-streaming.md). - - If your application must do more work while an operation completes, you should create an asynchronous method pair on the service contract interface that your WCF client implements. The easiest way to do this is to use the `/async` switch on the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). For an example, see [How to: Call Service Operations Asynchronously](how-to-call-wcf-service-operations-asynchronously.md). - - For more information about increasing client performance, see [Middle-Tier Client Applications](middle-tier-client-applications.md). - -### Enabling the User to Select Credentials Dynamically - - The interface enables applications to display a user interface that enables the user to choose credentials with which a channel is created before the timeout timers start. - - Application developers can make use of an inserted in two ways. The client application can call either or (or an asynchronous version) prior to opening the channel (the *explicit* approach) or call the first operation (the *implicit* approach). - - If using the implicit approach, the application must call the first operation on a or extension. If it calls anything other than the first operation, an exception is thrown. - - If using the explicit approach, the application must perform the following steps in order: - -1. Call either or (or an asynchronous version). - -2. When the initializers have returned, call either the method on the object or on the object returned from the property. - -3. Call operations. - - It is recommended that production-quality applications control the user-interface process by adopting the explicit approach. - - Applications that use the implicit approach invoke the user-interface initializers, but if the user of the application fails to respond within the send timeout period of the binding, an exception is thrown when the user interface returns. - +> Checking the value of the property is a race condition and is not recommended to determine whether to reuse or close a channel. + + Datagram channels never fault even if exceptions occur when they are closed. In addition, non-duplex clients that fail to authenticate using a secure conversation typically throw a . However if the duplex client using a secure conversation fails to authenticate, the client receives a instead. + + For more complete information about working with error information at the application level, see [Specifying and Handling Faults in Contracts and Services](../specifying-and-handling-faults-in-contracts-and-services.md). [Expected Exceptions](../samples/expected-exceptions.md) describes expected exceptions and shows how to handle them. For more information about how to handle errors when developing channels, see [Handling Exceptions and Faults](../extending/handling-exceptions-and-faults.md). + +### Client Blocking and Performance + + When an application synchronously calls a request-reply operation, the client blocks until a return value is received or an exception (such as a ) is thrown. This behavior is similar to local behavior. When an application synchronously invokes an operation on a WCF client object or channel, the client does not return until the channel layer can write the data to the network or until an exception is thrown. And while the one-way message exchange pattern (specified by marking an operation with set to `true`) can make some clients more responsive, one-way operations can also block, depending upon the binding and what messages have already been sent. One-way operations are only about the message exchange, no more and no less. For more information, see [One-Way Services](one-way-services.md). + + Large data chunks can slow client processing no matter what the message exchange pattern. To understand how to handle these issues, see [Large Data and Streaming](large-data-and-streaming.md). + + If your application must do more work while an operation completes, you should create an asynchronous method pair on the service contract interface that your WCF client implements. The easiest way to do this is to use the `/async` switch on the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). For an example, see [How to: Call Service Operations Asynchronously](how-to-call-wcf-service-operations-asynchronously.md). + + For more information about increasing client performance, see [Middle-Tier Client Applications](middle-tier-client-applications.md). + +### Enabling the User to Select Credentials Dynamically + + The interface enables applications to display a user interface that enables the user to choose credentials with which a channel is created before the timeout timers start. + + Application developers can make use of an inserted in two ways. The client application can call either or (or an asynchronous version) prior to opening the channel (the *explicit* approach) or call the first operation (the *implicit* approach). + + If using the implicit approach, the application must call the first operation on a or extension. If it calls anything other than the first operation, an exception is thrown. + + If using the explicit approach, the application must perform the following steps in order: + +1. Call either or (or an asynchronous version). + +2. When the initializers have returned, call either the method on the object or on the object returned from the property. + +3. Call operations. + + It is recommended that production-quality applications control the user-interface process by adopting the explicit approach. + + Applications that use the implicit approach invoke the user-interface initializers, but if the user of the application fails to respond within the send timeout period of the binding, an exception is thrown when the user interface returns. + ## See also - [Duplex Services](duplex-services.md) diff --git a/docs/framework/wcf/feature-details/accessing-wcf-services-with-a-windows-store-client-app.md b/docs/framework/wcf/feature-details/accessing-wcf-services-with-a-windows-store-client-app.md index 08058abf776db..149d386301e36 100644 --- a/docs/framework/wcf/feature-details/accessing-wcf-services-with-a-windows-store-client-app.md +++ b/docs/framework/wcf/feature-details/accessing-wcf-services-with-a-windows-store-client-app.md @@ -6,177 +6,177 @@ ms.assetid: e2002ef4-5dee-4a54-9d87-03b33d35fc52 --- # Access WCF Services with a Windows Store Client App -Windows 8 introduces a new type of application called Windows Store applications. These applications are designed around a touch screen interface. .NET Framework 4.5 enables Windows Store applications to call WCF services. - -## WCF Support in Windows Store Applications +Windows 8 introduces a new type of application called Windows Store applications. These applications are designed around a touch screen interface. .NET Framework 4.5 enables Windows Store applications to call WCF services. + +## WCF Support in Windows Store Applications + + A subset of WCF functionality is available from within a Windows Store application, see the following sections for more details. - A subset of WCF functionality is available from within a Windows Store application, see the following sections for more details. - > [!IMPORTANT] -> Use the WinRT syndication APIs instead of those exposed by WCF. For more information see, [WinRT Syndication API](xref:Windows.Web.Syndication) - +> Use the WinRT syndication APIs instead of those exposed by WCF. For more information see, [WinRT Syndication API](xref:Windows.Web.Syndication) + > [!WARNING] -> Using Add Service Reference to add a web service reference to a Windows Runtime Component isn't supported. - -### Supported Bindings - - The following WCF bindings are supported in Windows Store Applications: - -1. - -2. - -3. - +> Using Add Service Reference to add a web service reference to a Windows Runtime Component isn't supported. + +### Supported Bindings + + The following WCF bindings are supported in Windows Store Applications: + +1. + +2. + +3. + 4. - - The following binding elements are supported in Windows Store Applications - -1. - -2. - -3. - -4. - -5. - -6. - -7. - -8. - -9. - - Both Text and Binary encodings are supported. All WCF transfer modes are supported. For more information see, [Streaming Message Transfer](streaming-message-transfer.md). - -### Add Service Reference - - To call a WCF service from a Windows Store application, use the Add Service Reference feature of Visual Studio 2012. You will notice a few changes in the functionality of Add Service Reference when done within a Windows Store application. First no configuration file is generated. Windows Store applications do not use configuration files, so they must be configured in code. This configuration code can be found in the References.cs file generated by Add Service Reference. To see this file, make sure to select "Show All Files" in the solution explorer. The file will be located under the Service References and then Reference.svcmap nodes within the project. All operations generated for WCF services within a Windows Store application will be asynchronous using the Task-based asynchronous pattern. For more information, see [Async Tasks - Simplify Asynchronous Programming with Tasks](/archive/msdn-magazine/2010/september/async-tasks-simplify-asynchronous-programming-with-tasks). - - Because configuration is now generated in code, any changes made in the Reference.cs file would be overwritten every time the service reference is updated. To remedy this situation the configuration code is generated within a partial method, which you can implement in your client proxy class. The partial method is declared as follows: - -```csharp -static partial void Configure(System.ServiceModel.Description.ServiceEndpoint serviceEndpoint, - System.ServiceModel.Description.ClientCredentials clientCredentials); -``` - - You can then implement this partial method and change the binding or endpoint in your client proxy class as follows: - -```csharp -public partial class Service1Client : System.ServiceModel.ClientBase, MetroWcfClient.ServiceRefMultiEndpt.IService1 + + The following binding elements are supported in Windows Store Applications + +1. + +2. + +3. + +4. + +5. + +6. + +7. + +8. + +9. + + Both Text and Binary encodings are supported. All WCF transfer modes are supported. For more information see, [Streaming Message Transfer](streaming-message-transfer.md). + +### Add Service Reference + + To call a WCF service from a Windows Store application, use the Add Service Reference feature of Visual Studio 2012. You will notice a few changes in the functionality of Add Service Reference when done within a Windows Store application. First no configuration file is generated. Windows Store applications do not use configuration files, so they must be configured in code. This configuration code can be found in the References.cs file generated by Add Service Reference. To see this file, make sure to select "Show All Files" in the solution explorer. The file will be located under the Service References and then Reference.svcmap nodes within the project. All operations generated for WCF services within a Windows Store application will be asynchronous using the Task-based asynchronous pattern. For more information, see [Async Tasks - Simplify Asynchronous Programming with Tasks](/archive/msdn-magazine/2010/september/async-tasks-simplify-asynchronous-programming-with-tasks). + + Because configuration is now generated in code, any changes made in the Reference.cs file would be overwritten every time the service reference is updated. To remedy this situation the configuration code is generated within a partial method, which you can implement in your client proxy class. The partial method is declared as follows: + +```csharp +static partial void Configure(System.ServiceModel.Description.ServiceEndpoint serviceEndpoint, + System.ServiceModel.Description.ClientCredentials clientCredentials); +``` + + You can then implement this partial method and change the binding or endpoint in your client proxy class as follows: + +```csharp +public partial class Service1Client : System.ServiceModel.ClientBase, MetroWcfClient.ServiceRefMultiEndpt.IService1 { static partial void Configure(System.ServiceModel.Description.ServiceEndpoint serviceEndpoint, - System.ServiceModel.Description.ClientCredentials clientCredentials) - { + System.ServiceModel.Description.ClientCredentials clientCredentials) + { if (serviceEndpoint.Name == - ServiceRefMultiEndpt.Service1Client.EndpointConfiguration.BasicHttpBinding_IService1.ToString()) - { - serviceEndpoint.Binding.SendTimeout = new System.TimeSpan(0, 1, 0); - } + ServiceRefMultiEndpt.Service1Client.EndpointConfiguration.BasicHttpBinding_IService1.ToString()) + { + serviceEndpoint.Binding.SendTimeout = new System.TimeSpan(0, 1, 0); + } else if (serviceEndpoint.Name == - ServiceRefMultiEndpt.Service1Client.EndpointConfiguration.BasicHttpBinding_IService11.ToString()) - { - serviceEndpoint.Binding.SendTimeout = new System.TimeSpan(0, 1, 0); - clientCredentials.UserName.UserName = "username1"; - clientCredentials.UserName.Password = "password"; - } + ServiceRefMultiEndpt.Service1Client.EndpointConfiguration.BasicHttpBinding_IService11.ToString()) + { + serviceEndpoint.Binding.SendTimeout = new System.TimeSpan(0, 1, 0); + clientCredentials.UserName.UserName = "username1"; + clientCredentials.UserName.Password = "password"; + } else if (serviceEndpoint.Name == - ServiceRefMultiEndpt.Service1Client.EndpointConfiguration.NetTcpBinding_IService1.ToString()) - { - serviceEndpoint.Binding.Name = "MyTcpBinding"; - serviceEndpoint.Address = new System.ServiceModel.EndpointAddress("net.tcp://localhost/tcp"); - } - } - } -``` - -### Serialization - - The following serializers are supported in Windows Store applications: - -1. DataContractSerializer - -2. DataContractJsonSerializer - -3. XmlSerializer - + ServiceRefMultiEndpt.Service1Client.EndpointConfiguration.NetTcpBinding_IService1.ToString()) + { + serviceEndpoint.Binding.Name = "MyTcpBinding"; + serviceEndpoint.Address = new System.ServiceModel.EndpointAddress("net.tcp://localhost/tcp"); + } + } + } +``` + +### Serialization + + The following serializers are supported in Windows Store applications: + +1. DataContractSerializer + +2. DataContractJsonSerializer + +3. XmlSerializer + > [!WARNING] -> XmlDictionaryWriter.Write(DateTime) now writes the DateTime object as a string. - -### Security +> XmlDictionaryWriter.Write(DateTime) now writes the DateTime object as a string. + +### Security The following security modes are supported in Windows Store applications: - -1. - -2. - + +1. + +2. + 3. - + 4. - + The following client credential types are supported in Windows Store applications: - -1. None - -2. Basic - -3. Digest - -4. Negotiate - -5. NTLM - -6. Windows - -7. Username (Message Security) - -8. Windows (Transport Security) - - In order for Windows Store applications to access and send default Windows credentials, you must enable this functionality within the Package.appmanifest file. Open this file and select the Capabilities tab and select "Default Windows Credentials". This allows the application to connect to intranet resources that require domain credentials. - + +1. None + +2. Basic + +3. Digest + +4. Negotiate + +5. NTLM + +6. Windows + +7. Username (Message Security) + +8. Windows (Transport Security) + + In order for Windows Store applications to access and send default Windows credentials, you must enable this functionality within the Package.appmanifest file. Open this file and select the Capabilities tab and select "Default Windows Credentials". This allows the application to connect to intranet resources that require domain credentials. + > [!IMPORTANT] -> In order for Windows Store applications to make cross machine calls you must enable another capability called "Home/Work Networking". This setting is also in the Package.appmanifest file under the Capabilities tab. Select the Home/Work Networking checkbox. This gives your application inbound and outbound access to the networks of the user's trusted places like home and work. Inbound critical ports are always blocked. For accessing services on the internet you must also enable Internet (Client) capability. - -### Misc - - The use of the following classes is supported for Windows Store Applications: - -1. - -2. - -3. - -### Defining Service Contracts - - We recommend only defining asynchronous service operations using the task-based async pattern. This ensures Windows Store applications remain responsive while calling a service operation. - +> In order for Windows Store applications to make cross machine calls you must enable another capability called "Home/Work Networking". This setting is also in the Package.appmanifest file under the Capabilities tab. Select the Home/Work Networking checkbox. This gives your application inbound and outbound access to the networks of the user's trusted places like home and work. Inbound critical ports are always blocked. For accessing services on the internet you must also enable Internet (Client) capability. + +### Misc + + The use of the following classes is supported for Windows Store Applications: + +1. + +2. + +3. + +### Defining Service Contracts + + We recommend only defining asynchronous service operations using the task-based async pattern. This ensures Windows Store applications remain responsive while calling a service operation. + > [!WARNING] -> While no exception will be thrown if you define a synchronous operation, it is strongly recommended to only define asynchronous operations. - -### Calling WCF Services from Windows Store Applications - - As mentioned before all configuration must be done in code in the GetBindingForEndpoint method in the generated proxy class. Calling a service operation is done the same as calling any task-based asynchronous method as shown in the following code snippet. - -```csharp -void async SomeMethod() -{ - ServiceClient proxy = new ServiceClient(); - Task results = await proxy.CallAsync(param1, param2); - T result = results.Result; - if (result.Success) - { - // Do something with result - } -} -``` - - Notice the use of the async keyword on the method making the asynchronous call and the await keyword when calling the asynchronous method. - +> While no exception will be thrown if you define a synchronous operation, it is strongly recommended to only define asynchronous operations. + +### Calling WCF Services from Windows Store Applications + + As mentioned before all configuration must be done in code in the GetBindingForEndpoint method in the generated proxy class. Calling a service operation is done the same as calling any task-based asynchronous method as shown in the following code snippet. + +```csharp +void async SomeMethod() +{ + ServiceClient proxy = new ServiceClient(); + Task results = await proxy.CallAsync(param1, param2); + T result = results.Result; + if (result.Success) + { + // Do something with result + } +} +``` + + Notice the use of the async keyword on the method making the asynchronous call and the await keyword when calling the asynchronous method. + ## See also - [Programming WCF Security](programming-wcf-security.md) diff --git a/docs/framework/wcf/feature-details/anticipating-adopting-wcf-migration.md b/docs/framework/wcf/feature-details/anticipating-adopting-wcf-migration.md index 72964879fc15e..4b774f01825f8 100644 --- a/docs/framework/wcf/feature-details/anticipating-adopting-wcf-migration.md +++ b/docs/framework/wcf/feature-details/anticipating-adopting-wcf-migration.md @@ -6,125 +6,125 @@ ms.assetid: f49664d9-e9e0-425c-a259-93f0a569d01b --- # Anticipating Adopting the Windows Communication Foundation: Easing Future Migration -To ensure an easier future migration of new ASP.NET applications to WCF, follow the preceding recommendations as well as the following recommendations. - -## Protocols - - Disable ASP.NET 2.0’s support for SOAP 1.2: - -```xml - - - - - +To ensure an easier future migration of new ASP.NET applications to WCF, follow the preceding recommendations as well as the following recommendations. + +## Protocols + + Disable ASP.NET 2.0’s support for SOAP 1.2: + +```xml + + + + + - + - -``` - - Doing so is advisable because WCF requires messages conforming to different protocols, like SOAP 1.1 and SOAP 1.2, to go by using different endpoints. If an ASP.NET 2.0 Web service is configured to support both SOAP 1.1 and SOAP 1.2, which is the default configuration, then it cannot be migrated forward to a single WCF endpoint at the original address that would be certainly be compatible with all of the ASP.NET Web service’s existing clients. Also choosing SOAP 1.2 instead of 1.1 will more severely restrict the clientele of the service. - -## Service Development - - WCF allows you to define service contracts by applying the either to interfaces or to classes. It is recommended to apply the attribute to an interface rather than to a class, because doing so creates a definition of a contract that can be variously implemented by any number of classes. ASP.NET 2.0 supports the option of applying the attribute to interfaces as well as classes. However, as mentioned already, there is a defect in ASP.NET 2.0, by which the Namespace parameter of the attribute has no effect when that attribute is applied to an interface rather than a class. Since it is generally advisable to modify the namespace of a service from the default value, `http://tempuri.org`, using the Namespace parameter of the attribute, one should continue defining ASP.NET Web Services by applying the attribute either to interfaces or to classes. - -- Have as little code as possible in the methods by which those interfaces are defined. Have them delegate their work to other classes. New WCF service types could then also delegate their substantive work to those classes. - -- Provide explicit names for the operations of a service using the `MessageName` parameter of the . - - ```csharp - [WebMethod(MessageName="ExplicitName")] - string Echo(string input); - ``` - - Doing so is important, because the default names for operations in ASP.NET are different from the default names supplied by WCF. By providing explicit names, you avoid relying on the default ones. - -- Do not implement ASP.NET Web service operations with polymorphic methods, because WCF does not support implementing operations with polymorphic methods. - -- Use the to provide explicit values for the SOAPAction HTTP headers by which HTTP requests will be routed to methods. - - ```csharp - [WebMethod] - [SoapDocumentMethod(RequestElementName="ExplicitAction")] - string Echo(string input); - ``` - - Taking this approach will circumvent having to rely on the default SOAPAction values used by ASP.NET and WCF being the same. - -- Avoid using SOAP extensions. If SOAP extensions are required, then determine whether the purpose for which they are being considered is a feature that is already provided by WCF. If that is indeed the case, then reconsider the choice to not adopt WCF right away. - -## State Management - - Avoid having to maintain state in services. Not only does maintaining state tend to compromise the scalability of an application, but the state management mechanisms of ASP.NET and WCF are very different, although WCF does support the ASP.NET mechanisms in ASP.NET compatibility mode. - -## Exception Handling - - In designing the structures of the data types to be sent and received by a service, also design structures to represent the various types of exceptions that might occur within a service that one might wish to convey to a client. - -```csharp -[Serializable] -[XmlRoot(Namespace="ExplicitNamespace", IsNullable=true)] + +``` + + Doing so is advisable because WCF requires messages conforming to different protocols, like SOAP 1.1 and SOAP 1.2, to go by using different endpoints. If an ASP.NET 2.0 Web service is configured to support both SOAP 1.1 and SOAP 1.2, which is the default configuration, then it cannot be migrated forward to a single WCF endpoint at the original address that would be certainly be compatible with all of the ASP.NET Web service’s existing clients. Also choosing SOAP 1.2 instead of 1.1 will more severely restrict the clientele of the service. + +## Service Development + + WCF allows you to define service contracts by applying the either to interfaces or to classes. It is recommended to apply the attribute to an interface rather than to a class, because doing so creates a definition of a contract that can be variously implemented by any number of classes. ASP.NET 2.0 supports the option of applying the attribute to interfaces as well as classes. However, as mentioned already, there is a defect in ASP.NET 2.0, by which the Namespace parameter of the attribute has no effect when that attribute is applied to an interface rather than a class. Since it is generally advisable to modify the namespace of a service from the default value, `http://tempuri.org`, using the Namespace parameter of the attribute, one should continue defining ASP.NET Web Services by applying the attribute either to interfaces or to classes. + +- Have as little code as possible in the methods by which those interfaces are defined. Have them delegate their work to other classes. New WCF service types could then also delegate their substantive work to those classes. + +- Provide explicit names for the operations of a service using the `MessageName` parameter of the . + + ```csharp + [WebMethod(MessageName="ExplicitName")] + string Echo(string input); + ``` + + Doing so is important, because the default names for operations in ASP.NET are different from the default names supplied by WCF. By providing explicit names, you avoid relying on the default ones. + +- Do not implement ASP.NET Web service operations with polymorphic methods, because WCF does not support implementing operations with polymorphic methods. + +- Use the to provide explicit values for the SOAPAction HTTP headers by which HTTP requests will be routed to methods. + + ```csharp + [WebMethod] + [SoapDocumentMethod(RequestElementName="ExplicitAction")] + string Echo(string input); + ``` + + Taking this approach will circumvent having to rely on the default SOAPAction values used by ASP.NET and WCF being the same. + +- Avoid using SOAP extensions. If SOAP extensions are required, then determine whether the purpose for which they are being considered is a feature that is already provided by WCF. If that is indeed the case, then reconsider the choice to not adopt WCF right away. + +## State Management + + Avoid having to maintain state in services. Not only does maintaining state tend to compromise the scalability of an application, but the state management mechanisms of ASP.NET and WCF are very different, although WCF does support the ASP.NET mechanisms in ASP.NET compatibility mode. + +## Exception Handling + + In designing the structures of the data types to be sent and received by a service, also design structures to represent the various types of exceptions that might occur within a service that one might wish to convey to a client. + +```csharp +[Serializable] +[XmlRoot(Namespace="ExplicitNamespace", IsNullable=true)] public partial class AnticipatedException { - private string anticipatedExceptionInformationField; + private string anticipatedExceptionInformationField; public string AnticipatedExceptionInformation - { + { get { - return this.anticipatedExceptionInformationField; - } - set { - this.anticipatedExceptionInformationField = value; - } - } -} -``` - - Give such classes the ability to serialize themselves to XML: - -```csharp -public XmlNode ToXML() -{ - XmlSerializer serializer = new XmlSerializer( - typeof(AnticipatedException)); - MemoryStream memoryStream = new MemoryStream(); - XmlTextWriter writer = new XmlTextWriter( - memoryStream, UnicodeEncoding.UTF8); - serializer.Serialize(writer, this); - XmlDocument document = new XmlDocument(); - document.LoadXml(new string( - UnicodeEncoding.UTF8.GetChars( - memoryStream.GetBuffer())).Trim()); - return document.DocumentElement; -} -``` - - The classes can then be used to provide the details for explicitly thrown instances: - -```csharp -AnticipatedException exception = new AnticipatedException(); -exception.AnticipatedExceptionInformation = "…"; -throw new SoapException( - "Fault occurred", - SoapException.ClientFaultCode, - Context.Request.Url.AbsoluteUri, - exception.ToXML()); -``` - - These exception classes will be readily reusable with the WCF class to throw a new `FaultException(anticipatedException);` - -## Security - - The following are some security recommendations. - -- Avoid using ASP.NET 2.0 Profiles, as using them would restrict the use of ASP.NET Integration Mode if the service was migrated to WCF. - -- Avoid using ACLs to control access to services, as ASP.NET Web services supports ACLs using Internet Information Services (IIS), WCF does not—because ASP.NET Web services depend on IIS for hosting, and WCF does not necessarily have to be hosted in IIS. - -- Do consider using ASP.NET 2.0 Role Providers for authorizing access to the resources of a service. - + return this.anticipatedExceptionInformationField; + } + set { + this.anticipatedExceptionInformationField = value; + } + } +} +``` + + Give such classes the ability to serialize themselves to XML: + +```csharp +public XmlNode ToXML() +{ + XmlSerializer serializer = new XmlSerializer( + typeof(AnticipatedException)); + MemoryStream memoryStream = new MemoryStream(); + XmlTextWriter writer = new XmlTextWriter( + memoryStream, UnicodeEncoding.UTF8); + serializer.Serialize(writer, this); + XmlDocument document = new XmlDocument(); + document.LoadXml(new string( + UnicodeEncoding.UTF8.GetChars( + memoryStream.GetBuffer())).Trim()); + return document.DocumentElement; +} +``` + + The classes can then be used to provide the details for explicitly thrown instances: + +```csharp +AnticipatedException exception = new AnticipatedException(); +exception.AnticipatedExceptionInformation = "…"; +throw new SoapException( + "Fault occurred", + SoapException.ClientFaultCode, + Context.Request.Url.AbsoluteUri, + exception.ToXML()); +``` + + These exception classes will be readily reusable with the WCF class to throw a new `FaultException(anticipatedException);` + +## Security + + The following are some security recommendations. + +- Avoid using ASP.NET 2.0 Profiles, as using them would restrict the use of ASP.NET Integration Mode if the service was migrated to WCF. + +- Avoid using ACLs to control access to services, as ASP.NET Web services supports ACLs using Internet Information Services (IIS), WCF does not—because ASP.NET Web services depend on IIS for hosting, and WCF does not necessarily have to be hosted in IIS. + +- Do consider using ASP.NET 2.0 Role Providers for authorizing access to the resources of a service. + ## See also - [Anticipating Adopting the Windows Communication Foundation: Easing Future Integration](anticipating-adopting-the-wcf-easing-future-integration.md) diff --git a/docs/framework/wcf/feature-details/architecture-of-syndication.md b/docs/framework/wcf/feature-details/architecture-of-syndication.md index b63bd75a24556..02f4eb69329a8 100644 --- a/docs/framework/wcf/feature-details/architecture-of-syndication.md +++ b/docs/framework/wcf/feature-details/architecture-of-syndication.md @@ -6,74 +6,74 @@ ms.assetid: ed4ca86e-e3d8-4acb-87aa-1921fbc353be --- # Architecture of Syndication -The Syndication API is designed to provide a format-neutral programming model that allows syndicated content to be written on to the wire in a variety of formats. The abstract data model consists of the following classes: - -- - -- - -- - -- - -- - - These classes map closely to the constructs defined in the Atom 1.0 specification, although some of the names are different. - - In Windows Communication Foundation (WCF), syndication feeds are modeled as another type of service operation, one where the return type is one of the derived classes of . The retrieval of a feed is modeled as a request-response message exchange. A client sends a request to the service and the service responds. The request message is set over an infrastructure protocol (for example, raw HTTP) and the response message contains a payload that consists of a commonly understood syndication format (RSS 2.0 or Atom 1.0). Services that implement these message exchanges are referred to as syndication services. - - The contract for a syndication service consists of a set of operations that returns an instance of the class. The following example demonstrates an interface declaration for a syndication service. - - [!code-csharp[S_UE_SyndicationBoth#0](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_ue_syndicationboth/cs/service.cs#0)] - - Syndication support is built on top of the WCF REST Programming Model that defines the binding, which is used in conjunction with to make feeds available as services. For more information about the WCF REST Programming Model, see [WCF Web HTTP Programming Model Overview](wcf-web-http-programming-model-overview.md). - +The Syndication API is designed to provide a format-neutral programming model that allows syndicated content to be written on to the wire in a variety of formats. The abstract data model consists of the following classes: + +- + +- + +- + +- + +- + + These classes map closely to the constructs defined in the Atom 1.0 specification, although some of the names are different. + + In Windows Communication Foundation (WCF), syndication feeds are modeled as another type of service operation, one where the return type is one of the derived classes of . The retrieval of a feed is modeled as a request-response message exchange. A client sends a request to the service and the service responds. The request message is set over an infrastructure protocol (for example, raw HTTP) and the response message contains a payload that consists of a commonly understood syndication format (RSS 2.0 or Atom 1.0). Services that implement these message exchanges are referred to as syndication services. + + The contract for a syndication service consists of a set of operations that returns an instance of the class. The following example demonstrates an interface declaration for a syndication service. + + [!code-csharp[S_UE_SyndicationBoth#0](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_ue_syndicationboth/cs/service.cs#0)] + + Syndication support is built on top of the WCF REST Programming Model that defines the binding, which is used in conjunction with to make feeds available as services. For more information about the WCF REST Programming Model, see [WCF Web HTTP Programming Model Overview](wcf-web-http-programming-model-overview.md). + > [!NOTE] -> The Atom 1.0 specification allows for fractional seconds to be specified in any of its date constructs. When serializing and deserializing the WCF implementation ignores the fractional seconds. - -## Object Model - - The object model for syndication consists of the groups of classes in the following tables. - - Formatting Classes: - -|Class|Description| -|-----------|-----------------| -||A class that serializes a instance to Atom 1.0 format.| -||A class that serializes derived classes to Atom 1.0 format.| -||A class that serializes a instance to Atom 1.0 format.| -||A class that serializes derived classes to Atom 1.0 format.| -||A class that serializes a instance to RSS 2.0 format.| -||A class that serializes derived classes to RSS 2.0 format.| -||A class that serializes a instance to RSS 2.0 format.| -||A class that serializes derived classes to RSS 2.0 format.| - - Object Model Classes: - -|Class|Description| -|-----------|-----------------| -||A class that represents the category of a syndication feed.| -||A base class that represents syndication content.| -||A class that represents a syndication element extension.| -||A collection of objects.| -||A class that represents a top-level feed object.| -||A class that represents a feed item.| -||A class that represents a link within a syndication feed or item.| -||A class that represents an Atom Person construct.| -||A class that represents the supported syndication protocol versions.| -||A class that represents any content to be displayed to an end user.| -||An enumeration that represents the different types of text syndication content supported.| -||A class that represents syndication content that consists of a URL to another resource.| -||A class that represents syndication content that is not to be displayed in a browser.| - - The core data abstractions in the object model are Feed and Item, which correspond to the and classes. A Feed exposes some feed-level metadata (for example, Title, Description, and Author), a location to store unknown extensions, and a set of items that make up the rest of the feed's information content. An Item makes available some item-level metadata (for example, Title, Summary, and PublicationDate), a location to store unknown extensions, and a content element that contains the rest of the item's information content. The core abstractions of Feed and Item are supported by additional classes that represent common data constructs referenced in the Atom 1.0 and RSS specifications. - - The information carried in a Feed instance can be converted to a variety of XML formats. The process of converting to and from XML is managed by the class. This class is abstract; concrete implementations are provided for Atom 1.0 and RSS 2.0, and . To use derived Feed classes, use either or as they allow you to specify a derived Feed class. To use derived item classes use either or as they allow you to specify a derived item class Third parties can derive their own implementation of to support different syndication formats. - -## Extensibility - -- A key feature of syndication protocols is extensibility. Both Atom 1.0 and RSS 2.0 allow you to add attributes and elements to syndication feeds that are not defined in the specifications. The WCF syndication programming model provides two ways of working with custom attributes and extensions: deriving a new class and loosely-typed access. For more information, see [Syndication Extensibility](syndication-extensibility.md). - +> The Atom 1.0 specification allows for fractional seconds to be specified in any of its date constructs. When serializing and deserializing the WCF implementation ignores the fractional seconds. + +## Object Model + + The object model for syndication consists of the groups of classes in the following tables. + + Formatting Classes: + +|Class|Description| +|-----------|-----------------| +||A class that serializes a instance to Atom 1.0 format.| +||A class that serializes derived classes to Atom 1.0 format.| +||A class that serializes a instance to Atom 1.0 format.| +||A class that serializes derived classes to Atom 1.0 format.| +||A class that serializes a instance to RSS 2.0 format.| +||A class that serializes derived classes to RSS 2.0 format.| +||A class that serializes a instance to RSS 2.0 format.| +||A class that serializes derived classes to RSS 2.0 format.| + + Object Model Classes: + +|Class|Description| +|-----------|-----------------| +||A class that represents the category of a syndication feed.| +||A base class that represents syndication content.| +||A class that represents a syndication element extension.| +||A collection of objects.| +||A class that represents a top-level feed object.| +||A class that represents a feed item.| +||A class that represents a link within a syndication feed or item.| +||A class that represents an Atom Person construct.| +||A class that represents the supported syndication protocol versions.| +||A class that represents any content to be displayed to an end user.| +||An enumeration that represents the different types of text syndication content supported.| +||A class that represents syndication content that consists of a URL to another resource.| +||A class that represents syndication content that is not to be displayed in a browser.| + + The core data abstractions in the object model are Feed and Item, which correspond to the and classes. A Feed exposes some feed-level metadata (for example, Title, Description, and Author), a location to store unknown extensions, and a set of items that make up the rest of the feed's information content. An Item makes available some item-level metadata (for example, Title, Summary, and PublicationDate), a location to store unknown extensions, and a content element that contains the rest of the item's information content. The core abstractions of Feed and Item are supported by additional classes that represent common data constructs referenced in the Atom 1.0 and RSS specifications. + + The information carried in a Feed instance can be converted to a variety of XML formats. The process of converting to and from XML is managed by the class. This class is abstract; concrete implementations are provided for Atom 1.0 and RSS 2.0, and . To use derived Feed classes, use either or as they allow you to specify a derived Feed class. To use derived item classes use either or as they allow you to specify a derived item class Third parties can derive their own implementation of to support different syndication formats. + +## Extensibility + +- A key feature of syndication protocols is extensibility. Both Atom 1.0 and RSS 2.0 allow you to add attributes and elements to syndication feeds that are not defined in the specifications. The WCF syndication programming model provides two ways of working with custom attributes and extensions: deriving a new class and loosely-typed access. For more information, see [Syndication Extensibility](syndication-extensibility.md). + ## See also - [WCF Syndication Overview](wcf-syndication-overview.md) diff --git a/docs/framework/wcf/feature-details/auditing-security-events.md b/docs/framework/wcf/feature-details/auditing-security-events.md index 0903065d2872f..368d1e0ebf6fd 100644 --- a/docs/framework/wcf/feature-details/auditing-security-events.md +++ b/docs/framework/wcf/feature-details/auditing-security-events.md @@ -2,107 +2,107 @@ description: "Learn more about: Auditing Security Events" title: "Auditing Security Events" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "auditing security events [WCF]" ms.assetid: 5633f61c-a3c9-40dd-8070-1c373b66a716 --- # Auditing Security Events -Applications created with Windows Communication Foundation (WCF) can log security events (either success, failure, or both) with the auditing feature. The events are written to the Windows system event log and can be examined using the Event Viewer. - - Auditing provides a way for an administrator to detect an attack that has already occurred or is in progress. In addition, auditing can help a developer to debug security-related problems. For example, if an error in the configuration of the authorization or checking policy accidentally denies access to an authorized user, a developer can quickly discover and isolate the cause of this error by examining the event log. - - For more information about WCF security, see [Security Overview](security-overview.md). For more information about programming WCF, see [Basic WCF Programming](../basic-wcf-programming.md). - -## Audit Level and Behavior - - Two levels of security audits exist: - -- Service authorization level, in which a caller is authorized. - -- Message level, in which WCF checks for message validity and authenticates the caller. - - You can check both audit levels for success or failure, which is known as the *audit behavior*. - -## Audit Log Location - - Once you determine an audit level and behavior, you (or an administrator) can specify a location for the audit log. The three choices include: Default, Application, and Security. When you specify Default, the actual log depends on which system you are using and whether the system supports writing to the security log. For more information, see the "Operating System" section later in this topic. - - To write to the Security log requires the `SeAuditPrivilege`. By default, only Local System and Network Service accounts have this privilege. To manage the Security log functions `read` and `delete` requires the `SeSecurityPrivilege`. By default, only administrators have this privilege. - - In contrast, authenticated users can read and write to the Application log. Windows XP writes audit events to the Application log by default. The log can also contain personal information that is visible to all authenticated users. - -## Suppressing Audit Failures - - Another option during auditing is whether to suppress any audit failure. By default, an audit failure does not affect an application. If required, however, you can set the option to `false`, which causes an exception to be thrown. - -## Programming Auditing - - You can specify auditing behavior either programmatically or through configuration. - -### Auditing Classes - - The following table describes the classes and properties used to program auditing behavior. - -|Class|Description| -|-----------|-----------------| -||Enables setting options for auditing as a service behavior.| -||Enumeration to specify which log to write to. The possible values are Default, Application, and Security. When you select Default, the operating system determines the actual log location. See the "Application or Security Event Log Choice" section later in this topic.| -||Specifies which types of message authentication events are audited at the message level. The choices are `None`, `Failure`, `Success`, and `SuccessOrFailure`.| -||Specifies which types of service authorization events are audited at the service level. The choices are `None`, `Failure`, `Success`, and `SuccessOrFailure`.| -||Specifies what happens to the client request when auditing fails. For example, when the service attempts to write to the security log, but does not have `SeAuditPrivilege`. The default value of `true` indicates that failures are ignored, and the client request is processed normally.| - - For an example of setting up an application to log audit events, see [How to: Audit Security Events](how-to-audit-wcf-security-events.md). - -### Configuration - - You can also use configuration to specify auditing behavior by adding a [\](../../configure-apps/file-schema/wcf/servicesecurityaudit.md) under the [\](../../configure-apps/file-schema/wcf/behaviors.md). You must add the element under a [\](../../configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) as shown in the following code. - -```xml - - - - - - |Enables setting options for auditing as a service behavior.| +||Enumeration to specify which log to write to. The possible values are Default, Application, and Security. When you select Default, the operating system determines the actual log location. See the "Application or Security Event Log Choice" section later in this topic.| +||Specifies which types of message authentication events are audited at the message level. The choices are `None`, `Failure`, `Success`, and `SuccessOrFailure`.| +||Specifies which types of service authorization events are audited at the service level. The choices are `None`, `Failure`, `Success`, and `SuccessOrFailure`.| +||Specifies what happens to the client request when auditing fails. For example, when the service attempts to write to the security log, but does not have `SeAuditPrivilege`. The default value of `true` indicates that failures are ignored, and the client request is processed normally.| + + For an example of setting up an application to log audit events, see [How to: Audit Security Events](how-to-audit-wcf-security-events.md). + +### Configuration + + You can also use configuration to specify auditing behavior by adding a [\](../../configure-apps/file-schema/wcf/servicesecurityaudit.md) under the [\](../../configure-apps/file-schema/wcf/behaviors.md). You must add the element under a [\](../../configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) as shown in the following code. + +```xml + + + + + + - - - - -``` - - If auditing is enabled and an `auditLogLocation` is not specified, the default log name is "Security" log for the platform supporting writing to the Security log; otherwise, it is "Application" log. Only the Windows Server 2003 and Windows Vista operating systems support writing to the Security log. For more information, see the "Operating System" section later in this topic. - -## Security Considerations - - If a malicious user knows that auditing is enabled, that attacker can send invalid messages that cause audit entries to be written. If the audit log is filled in this manner, the auditing system fails. To mitigate this, set the property to `true` and use the properties of the Event Viewer to control the auditing behavior. - - Audit events that are written to the Application Log on Windows XP are visible to any authenticated user. - -## Choosing Between Application and Security Event Logs - - The following tables provide information to help you choose whether to log into the Application or the Security event log. - -#### Operating System - -|System|Application log|Security log| -|------------|---------------------|------------------| -|Windows XP SP2 or later|Supported|Not supported| -|Windows Server 2003 SP1 and Windows Vista|Supported|Thread context must possess `SeAuditPrivilege`| - -#### Other Factors - - In addition to the operating system, the following table describes other settings that control the enablement of logging. - -|Factor|Application log|Security log| -|------------|---------------------|------------------| -|Audit policy management|Not applicable.|Along with configuration, the Security log is also controlled by the local security authority (LSA) policy. The "Audit object access" category must also be enabled.| -|Default user experience|All authenticated users can write to the Application log, so no additional permission step is needed for application processes.|The application process (context) must have `SeAuditPrivilege`.| - + + + + +``` + + If auditing is enabled and an `auditLogLocation` is not specified, the default log name is "Security" log for the platform supporting writing to the Security log; otherwise, it is "Application" log. Only the Windows Server 2003 and Windows Vista operating systems support writing to the Security log. For more information, see the "Operating System" section later in this topic. + +## Security Considerations + + If a malicious user knows that auditing is enabled, that attacker can send invalid messages that cause audit entries to be written. If the audit log is filled in this manner, the auditing system fails. To mitigate this, set the property to `true` and use the properties of the Event Viewer to control the auditing behavior. + + Audit events that are written to the Application Log on Windows XP are visible to any authenticated user. + +## Choosing Between Application and Security Event Logs + + The following tables provide information to help you choose whether to log into the Application or the Security event log. + +#### Operating System + +|System|Application log|Security log| +|------------|---------------------|------------------| +|Windows XP SP2 or later|Supported|Not supported| +|Windows Server 2003 SP1 and Windows Vista|Supported|Thread context must possess `SeAuditPrivilege`| + +#### Other Factors + + In addition to the operating system, the following table describes other settings that control the enablement of logging. + +|Factor|Application log|Security log| +|------------|---------------------|------------------| +|Audit policy management|Not applicable.|Along with configuration, the Security log is also controlled by the local security authority (LSA) policy. The "Audit object access" category must also be enabled.| +|Default user experience|All authenticated users can write to the Application log, so no additional permission step is needed for application processes.|The application process (context) must have `SeAuditPrivilege`.| + ## See also - diff --git a/docs/framework/wcf/feature-details/authentication-in-wcf.md b/docs/framework/wcf/feature-details/authentication-in-wcf.md index 4327623991f94..78946141d41f2 100644 --- a/docs/framework/wcf/feature-details/authentication-in-wcf.md +++ b/docs/framework/wcf/feature-details/authentication-in-wcf.md @@ -20,7 +20,7 @@ The following topics show a number of different mechanisms in Windows Communicat As an extra safeguard, a client can authenticate the service by specifying the expected *identity* of the service. If the expected identity and the identity returned by the service do not match, authentication fails. [Security Negotiation and Timeouts](security-negotiation-and-timeouts.md) - Describes how to use the property in the class. + Describes how to use the property in the class. [Debugging Windows Authentication Errors](debugging-windows-authentication-errors.md) Focuses on common problems encountered when using Windows authentication. diff --git a/docs/framework/wcf/feature-details/best-practices-for-queued-communication.md b/docs/framework/wcf/feature-details/best-practices-for-queued-communication.md index 11b444103ed2a..8cd5f89b5b305 100644 --- a/docs/framework/wcf/feature-details/best-practices-for-queued-communication.md +++ b/docs/framework/wcf/feature-details/best-practices-for-queued-communication.md @@ -2,91 +2,91 @@ description: "Learn more about: Best Practices for Queued Communication" title: "Best Practices for Queued Communication" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "queues [WCF], best practices" - "best practices [WCF], queued communication" ms.assetid: 446a6383-cae3-4338-b193-a33c14a49948 --- # Best Practices for Queued Communication -This topic provides recommended practices for queued communication in Windows Communication Foundation (WCF). The following sections discuss recommended practices from a scenario perspective. - -## Fast, Best-Effort Queued Messaging - - For scenarios that require separation that queued messaging provides and fast, high-performance messaging with best-effort assurances, use a non-transactional queue and set the property to `false`. - - In addition, you can choose not to incur the cost of disk writes by setting the property to `false`. - - Security has implications on performance. For more information, see [Performance Considerations](performance-considerations.md). - -## Reliable End-to-End Queued Messaging - - The following sections describe recommended practices for scenarios that require end-to-end reliable messaging. - -### Basic Reliable Transfer - - For end-to-end reliability, set the property to `true` to ensure transfer. The property can be set to `true` or `false` depending on your requirements (the default is `true`). Generally, the property is set to `true` as part of end-to-end reliability. The compromise is a performance cost, but makes the message durable so that the message is not lost if a queue manager crashes. - -### Use of Transactions - - You must use transactions to ensure end-to-end reliability. `ExactlyOnce` assurances only ensure that messages are delivered to the target queue. To ensure that the message is received, use transactions. Without transactions, if the service crashes, you lose the message that is being delivered but is actually delivered to the application. - -### Use of Dead-letter Queues - - Dead-letter queues ensure that you are notified if a message fails to be delivered to the target queue. You can use the system-provided dead-letter queue or a custom dead-letter queue. In general, using a custom dead-letter queue is best because it enables you to send dead-letter messages from one application into a single dead-letter queue. Otherwise, all dead-letter messages that occur for all applications running on the system are delivered to a single queue. Each application must then search though the dead-letter queue to find the dead-letter messages that are relevant to that application. Sometimes, using a custom dead-letter queue is not feasible, such as when using MSMQ 3.0. - - Turning off dead-letter queues for end-to-end reliable communication is not recommended. - - For more information, see [Using Dead-Letter Queues to Handle Message Transfer Failures](using-dead-letter-queues-to-handle-message-transfer-failures.md). - -### Use of Poison-Message Handling - - Poison-message handling provides the ability to recover from the failure to process messages. - - When using the poison-message handling feature, ensure that the property is set to the appropriate value. Setting it to means the data is lost. On the other hand, setting it to faults the service host when it detects a poison message. Using MSMQ 3.0, is the best option to avoid data loss and move the poison message out of the way. Using MSMQ 4.0, is the recommended approach. moves a poisoned message out of the queue so the service can continue to process new messages. The poison-message service can then process the poison message separately. - - For more information, see [Poison Message Handling](poison-message-handling.md). - -## Achieving High Throughput - - To achieve high throughput on a single endpoint, use the following: - -- Transacted batching. Transacted batching ensures that many messages can be read in a single transaction. This optimizes transaction commits, increasing overall performance. The cost of batching is that if a failure occurs in a single message within a batch, then the entire batch is rolled back and the messages must be processed one at a time until it is safe to batch again. In most cases, poison messages are rare, so batching is the preferred way to increase system performance, particularly when you have other resource managers that participate in the transaction. For more information, see [Batching Messages in a Transaction](batching-messages-in-a-transaction.md). - -- Concurrency. Concurrency increases throughput, but concurrency also affects contention to shared resources. For more information, see [Concurrency](../samples/concurrency.md). - -- Throttling. For optimal performance, throttle the number of messages in the dispatcher pipeline. For an example of how to do this, see [Throttling](../samples/throttling.md). - - When using batching, be aware that concurrency and throttling translate to concurrent batches. - - To achieve higher throughput and availability, use a farm of WCF services that read from the queue. This requires that all of these services expose the same contract on the same endpoint. The farm approach works best for applications that have high production rates of messages because it enables a number of services to all read from the same queue. - - When using farms, be aware that MSMQ 3.0 does not support remote transacted reads. MSMQ 4.0 does support remote transacted reads. - - For more information, see [Batching Messages in a Transaction](batching-messages-in-a-transaction.md). - -## Queuing with Unit of Work Semantics - - In some scenarios a group of messages in a queue may be related and, therefore, the ordering of these messages is significant. In such scenarios, process a group of related messages together as a single unit: either all of the messages are processed successfully or none are. To implement such behavior, use sessions with queues. - - For more information, see [Grouping Queued Messages in a Session](grouping-queued-messages-in-a-session.md). - -## Correlating Request-Reply Messages - - Though queues are typically one-way, in some scenarios you may want to correlate a reply received to a request sent earlier. If you require such correlation, it is recommended that you apply your own SOAP message header that contains correlation information with the message. Typically, the sender attaches this header with the message, and the receiver, upon processing the message and replying back with a new message on a reply queue, attaches the sender's message header that contains the correlation information so that the sender can identify the reply message with the request message. - -## Integrating with Non-WCF Applications - - Use `MsmqIntegrationBinding` when integrating WCF services or clients with non-WCF services or clients. The non-WCF application can be an MSMQ application written using System.Messaging, COM+, Visual Basic, or C++. - - When using `MsmqIntegrationBinding`, be aware of the following: - -- A WCF message body is not the same as a MSMQ message body. When sending a WCF message using a queued binding, the WCF message body is placed inside of a MSMQ message. The MSMQ infrastructure is oblivious to this extra information; it sees only the MSMQ message. - -- `MsmqIntegrationBinding` supports popular serialization types. Based on the serialization type, the body type of the generic message, , takes different type parameters. For example, requires `MsmqMessage\` and requires `MsmqMessage`. - -- With XML serialization, you can specify the known type using the `KnownTypes` attribute on the [\](../../configure-apps/file-schema/wcf/behavior-of-servicebehaviors.md) element that is then used to determine how to deserialize the XML message. - +This topic provides recommended practices for queued communication in Windows Communication Foundation (WCF). The following sections discuss recommended practices from a scenario perspective. + +## Fast, Best-Effort Queued Messaging + + For scenarios that require separation that queued messaging provides and fast, high-performance messaging with best-effort assurances, use a non-transactional queue and set the property to `false`. + + In addition, you can choose not to incur the cost of disk writes by setting the property to `false`. + + Security has implications on performance. For more information, see [Performance Considerations](performance-considerations.md). + +## Reliable End-to-End Queued Messaging + + The following sections describe recommended practices for scenarios that require end-to-end reliable messaging. + +### Basic Reliable Transfer + + For end-to-end reliability, set the property to `true` to ensure transfer. The property can be set to `true` or `false` depending on your requirements (the default is `true`). Generally, the property is set to `true` as part of end-to-end reliability. The compromise is a performance cost, but makes the message durable so that the message is not lost if a queue manager crashes. + +### Use of Transactions + + You must use transactions to ensure end-to-end reliability. `ExactlyOnce` assurances only ensure that messages are delivered to the target queue. To ensure that the message is received, use transactions. Without transactions, if the service crashes, you lose the message that is being delivered but is actually delivered to the application. + +### Use of Dead-letter Queues + + Dead-letter queues ensure that you are notified if a message fails to be delivered to the target queue. You can use the system-provided dead-letter queue or a custom dead-letter queue. In general, using a custom dead-letter queue is best because it enables you to send dead-letter messages from one application into a single dead-letter queue. Otherwise, all dead-letter messages that occur for all applications running on the system are delivered to a single queue. Each application must then search though the dead-letter queue to find the dead-letter messages that are relevant to that application. Sometimes, using a custom dead-letter queue is not feasible, such as when using MSMQ 3.0. + + Turning off dead-letter queues for end-to-end reliable communication is not recommended. + + For more information, see [Using Dead-Letter Queues to Handle Message Transfer Failures](using-dead-letter-queues-to-handle-message-transfer-failures.md). + +### Use of Poison-Message Handling + + Poison-message handling provides the ability to recover from the failure to process messages. + + When using the poison-message handling feature, ensure that the property is set to the appropriate value. Setting it to means the data is lost. On the other hand, setting it to faults the service host when it detects a poison message. Using MSMQ 3.0, is the best option to avoid data loss and move the poison message out of the way. Using MSMQ 4.0, is the recommended approach. moves a poisoned message out of the queue so the service can continue to process new messages. The poison-message service can then process the poison message separately. + + For more information, see [Poison Message Handling](poison-message-handling.md). + +## Achieving High Throughput + + To achieve high throughput on a single endpoint, use the following: + +- Transacted batching. Transacted batching ensures that many messages can be read in a single transaction. This optimizes transaction commits, increasing overall performance. The cost of batching is that if a failure occurs in a single message within a batch, then the entire batch is rolled back and the messages must be processed one at a time until it is safe to batch again. In most cases, poison messages are rare, so batching is the preferred way to increase system performance, particularly when you have other resource managers that participate in the transaction. For more information, see [Batching Messages in a Transaction](batching-messages-in-a-transaction.md). + +- Concurrency. Concurrency increases throughput, but concurrency also affects contention to shared resources. For more information, see [Concurrency](../samples/concurrency.md). + +- Throttling. For optimal performance, throttle the number of messages in the dispatcher pipeline. For an example of how to do this, see [Throttling](../samples/throttling.md). + + When using batching, be aware that concurrency and throttling translate to concurrent batches. + + To achieve higher throughput and availability, use a farm of WCF services that read from the queue. This requires that all of these services expose the same contract on the same endpoint. The farm approach works best for applications that have high production rates of messages because it enables a number of services to all read from the same queue. + + When using farms, be aware that MSMQ 3.0 does not support remote transacted reads. MSMQ 4.0 does support remote transacted reads. + + For more information, see [Batching Messages in a Transaction](batching-messages-in-a-transaction.md). + +## Queuing with Unit of Work Semantics + + In some scenarios a group of messages in a queue may be related and, therefore, the ordering of these messages is significant. In such scenarios, process a group of related messages together as a single unit: either all of the messages are processed successfully or none are. To implement such behavior, use sessions with queues. + + For more information, see [Grouping Queued Messages in a Session](grouping-queued-messages-in-a-session.md). + +## Correlating Request-Reply Messages + + Though queues are typically one-way, in some scenarios you may want to correlate a reply received to a request sent earlier. If you require such correlation, it is recommended that you apply your own SOAP message header that contains correlation information with the message. Typically, the sender attaches this header with the message, and the receiver, upon processing the message and replying back with a new message on a reply queue, attaches the sender's message header that contains the correlation information so that the sender can identify the reply message with the request message. + +## Integrating with Non-WCF Applications + + Use `MsmqIntegrationBinding` when integrating WCF services or clients with non-WCF services or clients. The non-WCF application can be an MSMQ application written using System.Messaging, COM+, Visual Basic, or C++. + + When using `MsmqIntegrationBinding`, be aware of the following: + +- A WCF message body is not the same as a MSMQ message body. When sending a WCF message using a queued binding, the WCF message body is placed inside of a MSMQ message. The MSMQ infrastructure is oblivious to this extra information; it sees only the MSMQ message. + +- `MsmqIntegrationBinding` supports popular serialization types. Based on the serialization type, the body type of the generic message, , takes different type parameters. For example, requires `MsmqMessage\` and requires `MsmqMessage`. + +- With XML serialization, you can specify the known type using the `KnownTypes` attribute on the [\](../../configure-apps/file-schema/wcf/behavior-of-servicebehaviors.md) element that is then used to determine how to deserialize the XML message. + ## See also - [Queuing in WCF](queuing-in-wcf.md) diff --git a/docs/framework/wcf/feature-details/best-practices-for-reliable-sessions.md b/docs/framework/wcf/feature-details/best-practices-for-reliable-sessions.md index 60596da358f2c..0e1e80a67eae7 100644 --- a/docs/framework/wcf/feature-details/best-practices-for-reliable-sessions.md +++ b/docs/framework/wcf/feature-details/best-practices-for-reliable-sessions.md @@ -11,7 +11,7 @@ This topic discusses best practices for reliable sessions. ## Setting MaxTransferWindowSize -Reliable sessions in Windows Communication Foundation (WCF) use a transfer window to hold messages on the client and service. The configurable property indicates how many messages the transfer window can hold. +Reliable sessions in Windows Communication Foundation (WCF) use a transfer window to hold messages on the client and service. The configurable property indicates how many messages the transfer window can hold. On the sender, this indicates how many messages the transfer window can hold while waiting for acknowledgements; on the receiver, it indicates how many messages to buffer for the service. @@ -25,7 +25,7 @@ In this context, the term *network* corresponds to everything used as the basis Efficient use of the network ensures that network capacity is fully used. Both the amount of data that can be transferred per second over the network (*data rate*) and the time it takes to transfer data from the sender to the receiver (*latency*) impact how effectively the network is utilized. -On the sender, the property indicates how many messages its transfer window can hold while waiting for acknowledgements. If the network latency is high and in order to ensure a responsive sender and effective network utilization, you should increase the transfer window size. +On the sender, the property indicates how many messages its transfer window can hold while waiting for acknowledgements. If the network latency is high and in order to ensure a responsive sender and effective network utilization, you should increase the transfer window size. For example even if the sender keeps up with data rate, latency could be high if several intermediaries exist between the sender and receiver or the data must pass through a lossy intermediary or network. Thus, the sender has to wait for acknowledgements for the messages in its transfer window before accepting new messages to send on the wire. The smaller the buffer with high latency, the less effective the network utilization. On the other hand, too high a transfer window size may impact the service because the service may need to catch up to the high rate of data sent by the client. @@ -41,7 +41,7 @@ We recommended that you use the same `MaxTransferWindowSize` on both the sender *Flow control* is a mechanism that ensures that the sender and receiver keep pace with each other, that is, the messages are consumed and acted upon as fast as they're produced. The transfer window size on the client and service ensures that the sender and receiver are within a reasonable window of synchronization. -We highly recommended that you set the property to `true` when you're using a reliable session between a WCF client and a WCF service. +We highly recommended that you set the property to `true` when you're using a reliable session between a WCF client and a WCF service. ## Setting MaxPendingChannels @@ -55,7 +55,7 @@ It's also possible that the pending channels in the queue remain in the queue fo When writing a service that services multiple clients simultaneously, you should set a value that's suitable for your needs. Setting too high a value for the `MaxPendingChannels` property impacts your working set. -The default value for is four channels. +The default value for is four channels. ## Reliable sessions and hosting diff --git a/docs/framework/wcf/feature-details/best-practices-for-security-in-wcf.md b/docs/framework/wcf/feature-details/best-practices-for-security-in-wcf.md index 19e14342762d9..9b287bd796209 100644 --- a/docs/framework/wcf/feature-details/best-practices-for-security-in-wcf.md +++ b/docs/framework/wcf/feature-details/best-practices-for-security-in-wcf.md @@ -2,66 +2,66 @@ description: "Learn more about: Best Practices for Security in WCF" title: "Best Practices for Security in WCF" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "best practices [WCF], security" ms.assetid: 3639de41-1fa7-4875-a1d7-f393e4c8bd69 --- # Best Practices for Security in WCF -The following sections list the best practices to consider when creating secure applications using Windows Communication Foundation (WCF). For more information about security, see [Security Considerations](security-considerations-in-wcf.md), [Security Considerations for Data](security-considerations-for-data.md), and [Security Considerations with Metadata](security-considerations-with-metadata.md). - -## Identify Services Performing Windows Authentication with SPNs +The following sections list the best practices to consider when creating secure applications using Windows Communication Foundation (WCF). For more information about security, see [Security Considerations](security-considerations-in-wcf.md), [Security Considerations for Data](security-considerations-for-data.md), and [Security Considerations with Metadata](security-considerations-with-metadata.md). - Services can be identified with either user principal names (UPNs) or service principal names (SPNs). Services running under machine accounts such as network service have an SPN identity corresponding to the machine they're running. Services running under user accounts have a UPN identity corresponding to the user they're running as, although the `setspn` tool can be used to assign an SPN to the user account. Configuring a service so it can be identified via SPN and configuring the clients connecting to the service to use that SPN can make certain attacks more difficult. This guidance applies to bindings using Kerberos or SSPI negotiation. Clients should still specify an SPN in the case where SSPI falls back to NTLM. - -## Verify Service Identities in WSDL +## Identify Services Performing Windows Authentication with SPNs - WS-SecurityPolicy allows services to publish information about their own identities in metadata. When retrieved via `svcutil` or other methods such as , this identity information is translated to the identity properties of the WCF service endpoint addresses. Clients which do not verify that these service identities are correct and valid effectively bypass service authentication. A malicious service can exploit such clients to execute credential forwarding and other "man in the middle" attacks by changing the identity claimed in its WSDL. - -## Use X509 Certificates Instead of NTLM + Services can be identified with either user principal names (UPNs) or service principal names (SPNs). Services running under machine accounts such as network service have an SPN identity corresponding to the machine they're running. Services running under user accounts have a UPN identity corresponding to the user they're running as, although the `setspn` tool can be used to assign an SPN to the user account. Configuring a service so it can be identified via SPN and configuring the clients connecting to the service to use that SPN can make certain attacks more difficult. This guidance applies to bindings using Kerberos or SSPI negotiation. Clients should still specify an SPN in the case where SSPI falls back to NTLM. - WCF offers two mechanisms for peer-to-peer authentication: X509 certificates (used by peer channel) and Windows authentication where an SSPI negotiation downgrades from Kerberos to NTLM. Certificate-based authentication using key sizes of 1024 bits or more is preferred to NTLM for several reasons: - -- the availability of mutual authentication, - -- the use of stronger cryptographic algorithms, and - -- the greater difficulty of utilizing forwarded X509 credentials. +## Verify Service Identities in WSDL -## Always Revert After Impersonation + WS-SecurityPolicy allows services to publish information about their own identities in metadata. When retrieved via `svcutil` or other methods such as , this identity information is translated to the identity properties of the WCF service endpoint addresses. Clients which do not verify that these service identities are correct and valid effectively bypass service authentication. A malicious service can exploit such clients to execute credential forwarding and other "man in the middle" attacks by changing the identity claimed in its WSDL. + +## Use X509 Certificates Instead of NTLM + + WCF offers two mechanisms for peer-to-peer authentication: X509 certificates (used by peer channel) and Windows authentication where an SSPI negotiation downgrades from Kerberos to NTLM. Certificate-based authentication using key sizes of 1024 bits or more is preferred to NTLM for several reasons: + +- the availability of mutual authentication, + +- the use of stronger cryptographic algorithms, and + +- the greater difficulty of utilizing forwarded X509 credentials. + +## Always Revert After Impersonation + + When using APIs that enable impersonation of a client, be sure to revert to the original identity. For example, when using the and , use the C# `using` statement or the Visual Basic `Using` statement, as shown in the following code. The class implements the interface, and therefore the common language runtime (CLR) automatically reverts to the original identity once the code leaves the `using` block. - When using APIs that enable impersonation of a client, be sure to revert to the original identity. For example, when using the and , use the C# `using` statement or the Visual Basic `Using` statement, as shown in the following code. The class implements the interface, and therefore the common language runtime (CLR) automatically reverts to the original identity once the code leaves the `using` block. - [!code-csharp[c_SecurityBestPractices#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_securitybestpractices/cs/source.cs#1)] - [!code-vb[c_SecurityBestPractices#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securitybestpractices/vb/source.vb#1)] - -## Impersonate Only as Needed + [!code-vb[c_SecurityBestPractices#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securitybestpractices/vb/source.vb#1)] + +## Impersonate Only as Needed + + Using the method of the class, it is possible to use impersonation in a very controlled scope. This is in contrast to using the property of the , which allows impersonation for the scope of the entire operation. Whenever possible, control the scope of impersonation by using the more precise method. + +## Obtain Metadata from Trusted Sources + + Be sure you trust the source of your metadata and make sure that no one has tampered with the metadata. Metadata retrieved using the HTTP protocol is sent in clear text and can be tampered with. If the service uses the and properties, use the URL supplied by the service creator to download the data using the HTTPS protocol. + +## Publish Metadata Using Security + + To prevent tampering with a service's published metadata, secure the metadata exchange endpoint with transport or message-level security. For more information, see [Publishing Metadata Endpoints](../publishing-metadata-endpoints.md) and [How to: Publish Metadata for a Service Using Code](how-to-publish-metadata-for-a-service-using-code.md). + +## Ensure Use of Local Issuer - Using the method of the class, it is possible to use impersonation in a very controlled scope. This is in contrast to using the property of the , which allows impersonation for the scope of the entire operation. Whenever possible, control the scope of impersonation by using the more precise method. - -## Obtain Metadata from Trusted Sources + If an issuer address and binding are specified for a given binding, the local issuer is not used for endpoints that use that binding. Clients who expect to always use the local issuer should ensure that they do not use such a binding or that they modify the binding such that the issuer address is null. - Be sure you trust the source of your metadata and make sure that no one has tampered with the metadata. Metadata retrieved using the HTTP protocol is sent in clear text and can be tampered with. If the service uses the and properties, use the URL supplied by the service creator to download the data using the HTTPS protocol. - -## Publish Metadata Using Security +## SAML Token Size Quotas - To prevent tampering with a service's published metadata, secure the metadata exchange endpoint with transport or message-level security. For more information, see [Publishing Metadata Endpoints](../publishing-metadata-endpoints.md) and [How to: Publish Metadata for a Service Using Code](how-to-publish-metadata-for-a-service-using-code.md). - -## Ensure Use of Local Issuer + When Security Assertions Markup Language (SAML) tokens are serialized in messages, either when they are issued by a Security Token Service (STS) or when clients present them to services as part of authentication, the maximum message size quota must be sufficiently large to accommodate the SAML token and the other message parts. In normal cases, the default message size quotas are sufficient. However, in cases where a SAML token is large because it contains hundreds of claims, the quotas should be increased to accommodate the serialized token. For more information about quotas, see [Security Considerations for Data](security-considerations-for-data.md). - If an issuer address and binding are specified for a given binding, the local issuer is not used for endpoints that use that binding. Clients who expect to always use the local issuer should ensure that they do not use such a binding or that they modify the binding such that the issuer address is null. - -## SAML Token Size Quotas +## Set SecurityBindingElement.IncludeTimestamp to True on Custom Bindings - When Security Assertions Markup Language (SAML) tokens are serialized in messages, either when they are issued by a Security Token Service (STS) or when clients present them to services as part of authentication, the maximum message size quota must be sufficiently large to accommodate the SAML token and the other message parts. In normal cases, the default message size quotas are sufficient. However, in cases where a SAML token is large because it contains hundreds of claims, the quotas should be increased to accommodate the serialized token. For more information about quotas, see [Security Considerations for Data](security-considerations-for-data.md). - -## Set SecurityBindingElement.IncludeTimestamp to True on Custom Bindings + When you create a custom binding, you must set to `true`. Otherwise, if is set to `false`, and the client is using an asymmetric key-based token such as an X509 certificate, the message will not be signed. - When you create a custom binding, you must set to `true`. Otherwise, if is set to `false`, and the client is using an asymmetric key-based token such as an X509 certificate, the message will not be signed. - ## See also - [Security Considerations](security-considerations-in-wcf.md) diff --git a/docs/framework/wcf/feature-details/caching-support-for-wcf-web-http-services.md b/docs/framework/wcf/feature-details/caching-support-for-wcf-web-http-services.md index 82770069271e9..4efc8cfc9c25c 100644 --- a/docs/framework/wcf/feature-details/caching-support-for-wcf-web-http-services.md +++ b/docs/framework/wcf/feature-details/caching-support-for-wcf-web-http-services.md @@ -10,7 +10,7 @@ ms.custom: sfi-ropc-nochange ## Basic Web HTTP Service Caching - To enable WEB HTTP service caching, you must first enable ASP.NET compatibility by applying the to the service setting to or . + To enable WEB HTTP service caching, you must first enable ASP.NET compatibility by applying the to the service setting to or . .NET Framework 4 introduces a new attribute called that allows you to specify a cache profile name. This attribute is applied to a service operation. The following example applies the to a service to enable ASP.NET compatibility and configures the `GetCustomer` operation for caching. The attribute specifies a cache profile that contains the cache settings to be used. @@ -126,13 +126,13 @@ Then, enable SQL cache dependency within a `` element within the ` takes an ETag value and checks it against the If-None-Match header of the request. If the header is present and there is a match, a with an HTTP status code 304 (Not Modified) is thrown and an ETag header is added to the response with the matching ETag. + For GET and HEAD requests, takes an ETag value and checks it against the If-None-Match header of the request. If the header is present and there is a match, a with an HTTP status code 304 (Not Modified) is thrown and an ETag header is added to the response with the matching ETag. - One overload of the method takes a last modified date and checks it against the If-Modified-Since header of the request. If the header is present and the resource has not been modified since, a with an HTTP status code 304 (Not Modified) is thrown. + One overload of the method takes a last modified date and checks it against the If-Modified-Since header of the request. If the header is present and the resource has not been modified since, a with an HTTP status code 304 (Not Modified) is thrown. - For PUT, POST, and DELETE requests, takes the current ETag value of a resource. If the current ETag value is null, the method checks that the If-None- Match header has a value of "*". If the current ETag value is not a default value, then the method checks the current ETag value against the If- Match header of the request. In either case, the method throws a with an HTTP status code 412 (Precondition Failed) if the expected header is not present in the request or its value does not satisfy the conditional check and sets the ETag header of the response to the current ETag value. + For PUT, POST, and DELETE requests, takes the current ETag value of a resource. If the current ETag value is null, the method checks that the If-None- Match header has a value of "*". If the current ETag value is not a default value, then the method checks the current ETag value against the If- Match header of the request. In either case, the method throws a with an HTTP status code 412 (Precondition Failed) if the expected header is not present in the request or its value does not satisfy the conditional check and sets the ETag header of the response to the current ETag value. - Both the `CheckConditional` methods and the method ensures that the ETag value set on the response header is a valid ETag according to the HTTP specification. This includes surrounding the ETag value in double quotes if they are not already present and properly escaping any internal double quote characters. Weak ETag comparison is not supported. + Both the `CheckConditional` methods and the method ensures that the ETag value set on the response header is a valid ETag according to the HTTP specification. This includes surrounding the ETag value in double quotes if they are not already present and properly escaping any internal double quote characters. Weak ETag comparison is not supported. The following example shows how to use these methods. diff --git a/docs/framework/wcf/feature-details/calling-a-rest-style-service-from-a-wcf-service.md b/docs/framework/wcf/feature-details/calling-a-rest-style-service-from-a-wcf-service.md index 1579826a9e943..53312b46e149b 100644 --- a/docs/framework/wcf/feature-details/calling-a-rest-style-service-from-a-wcf-service.md +++ b/docs/framework/wcf/feature-details/calling-a-rest-style-service-from-a-wcf-service.md @@ -82,7 +82,7 @@ public class NormalService : INormalInterface ## Create the client proxy for the REST-style service -Using to implement the client proxy. For each method called, a new is created and used to call the operation. +Using to implement the client proxy. For each method called, a new is created and used to call the operation. ```csharp public class MyRestClient : ClientBase, IRestInterface diff --git a/docs/framework/wcf/feature-details/cert-val-diff-https-ssl-over-tcp-and-soap.md b/docs/framework/wcf/feature-details/cert-val-diff-https-ssl-over-tcp-and-soap.md index a1e81096e7f74..f4a9ff3fa345c 100644 --- a/docs/framework/wcf/feature-details/cert-val-diff-https-ssl-over-tcp-and-soap.md +++ b/docs/framework/wcf/feature-details/cert-val-diff-https-ssl-over-tcp-and-soap.md @@ -2,51 +2,51 @@ title: "Certificate Validation Differences Between HTTPS, SSL over TCP, and SOAP Security" description: Learn about certificates with message-layer (SOAP) security that WCF offers in addition to HTTPS or TCP, and how WCF validates such certificates. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "certificates [WCF], validation differences" ms.assetid: 953a219f-4745-4019-9894-c70704f352e6 --- # Certificate Validation Differences Between HTTPS, SSL over TCP, and SOAP Security -You can use certificates in Windows Communication Foundation (WCF) with message-layer (SOAP) security in addition to transport-layer security (TLS) over HTTP (HTTPS) or TCP. This topic describes differences in the way such certificates are validated. - -## Validation of HTTPS Client Certificates +You can use certificates in Windows Communication Foundation (WCF) with message-layer (SOAP) security in addition to transport-layer security (TLS) over HTTP (HTTPS) or TCP. This topic describes differences in the way such certificates are validated. - When using HTTPS to communicate between a client and a service, the certificate that the client uses to authenticate to the service must support chain trust. That is, it must chain to a trusted root certificate authority. If not, the HTTP layer raises a with the message "The remote server returned an error: (403) Forbidden." WCF surfaces this exception as a . - -## Validation of HTTPS Service Certificates +## Validation of HTTPS Client Certificates + + When using HTTPS to communicate between a client and a service, the certificate that the client uses to authenticate to the service must support chain trust. That is, it must chain to a trusted root certificate authority. If not, the HTTP layer raises a with the message "The remote server returned an error: (403) Forbidden." WCF surfaces this exception as a . + +## Validation of HTTPS Service Certificates + + When using HTTPS to communicate between a client and a service, the certificate that the server authenticates with must support chain trust by default. That is, it must chain to a trusted root certificate authority. No online check is performed to see whether the certificate has been revoked. You can override this behavior by registering a callback, as shown in the following code. - When using HTTPS to communicate between a client and a service, the certificate that the server authenticates with must support chain trust by default. That is, it must chain to a trusted root certificate authority. No online check is performed to see whether the certificate has been revoked. You can override this behavior by registering a callback, as shown in the following code. - [!code-csharp[c_CertificateValidationDifferences#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_certificatevalidationdifferences/cs/source.cs#1)] - [!code-vb[c_CertificateValidationDifferences#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_certificatevalidationdifferences/vb/source.vb#1)] - - where the signature for `ValidateServerCertificate` is as follows: - + [!code-vb[c_CertificateValidationDifferences#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_certificatevalidationdifferences/vb/source.vb#1)] + + where the signature for `ValidateServerCertificate` is as follows: + [!code-csharp[c_CertificateValidationDifferences#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_certificatevalidationdifferences/cs/source.cs#2)] - [!code-vb[c_CertificateValidationDifferences#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_certificatevalidationdifferences/vb/source.vb#2)] - - Implementing `ValidateServerCertificate` can perform any checks that the client application developer deems necessary to validate the service certificate. - -## Validation of Client Certificates in SSL over TCP or SOAP Security - - When using Secure Sockets Layer (SSL) over TCP or message (SOAP) security, client certificates are validated according to the property value of the class. The property is set to one of the values. Revocation checking is performed according to the values of the property value of the class. The property is set to one of the values. - + [!code-vb[c_CertificateValidationDifferences#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_certificatevalidationdifferences/vb/source.vb#2)] + + Implementing `ValidateServerCertificate` can perform any checks that the client application developer deems necessary to validate the service certificate. + +## Validation of Client Certificates in SSL over TCP or SOAP Security + + When using Secure Sockets Layer (SSL) over TCP or message (SOAP) security, client certificates are validated according to the property value of the class. The property is set to one of the values. Revocation checking is performed according to the values of the property value of the class. The property is set to one of the values. + [!code-csharp[c_CertificateValidationDifferences#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_certificatevalidationdifferences/cs/source.cs#3)] - [!code-vb[c_CertificateValidationDifferences#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_certificatevalidationdifferences/vb/source.vb#3)] - -## Validation of Service Certificate in SSL over TCP and SOAP Security - - When using SSL over TCP or (SOAP) message security, service certificates are validated according to the property value of the class. The property is set to one of the values. - - Revocation checking is performed according to the values of the property value of the class. The property is set to one of the values. - + [!code-vb[c_CertificateValidationDifferences#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_certificatevalidationdifferences/vb/source.vb#3)] + +## Validation of Service Certificate in SSL over TCP and SOAP Security + + When using SSL over TCP or (SOAP) message security, service certificates are validated according to the property value of the class. The property is set to one of the values. + + Revocation checking is performed according to the values of the property value of the class. The property is set to one of the values. + [!code-csharp[c_CertificateValidationDifferences#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_certificatevalidationdifferences/cs/source.cs#4)] - [!code-vb[c_CertificateValidationDifferences#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_certificatevalidationdifferences/vb/source.vb#4)] - + [!code-vb[c_CertificateValidationDifferences#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_certificatevalidationdifferences/vb/source.vb#4)] + ## See also - diff --git a/docs/framework/wcf/feature-details/changing-the-cache-sharing-levels-for-send-activities.md b/docs/framework/wcf/feature-details/changing-the-cache-sharing-levels-for-send-activities.md index 70ed9b7fab4d3..eb7b59f743425 100644 --- a/docs/framework/wcf/feature-details/changing-the-cache-sharing-levels-for-send-activities.md +++ b/docs/framework/wcf/feature-details/changing-the-cache-sharing-levels-for-send-activities.md @@ -6,170 +6,170 @@ ms.assetid: 03926a64-753d-460e-ac06-2a4ff8e1bbf5 --- # Changing the Cache Sharing Levels for Send Activities -The extension enables you to customize the cache sharing levels, the settings of the channel factory cache, and the settings of the channel cache for workflows that send messages to service endpoints using messaging activities. These workflows are typically client workflows but could also be workflow services that are hosted in a . The channel factory cache contains cached objects. The channel cache contains cached channels. - +The extension enables you to customize the cache sharing levels, the settings of the channel factory cache, and the settings of the channel cache for workflows that send messages to service endpoints using messaging activities. These workflows are typically client workflows but could also be workflow services that are hosted in a . The channel factory cache contains cached objects. The channel cache contains cached channels. + > [!NOTE] -> Workflows can use messaging activities to send either messages or parameters. The workflow runtime adds channel factories to the cache that create channels of type when you use a activity with a activity, and an when just using a activity (no ). - -## The Cache Sharing Levels - - By default, in a workflow hosted by a the cache used by messaging activities is shared across all workflow instances in the (host-level caching). For a client workflow that is not hosted by a , the cache is available only to the workflow instance (instance-level caching). The cache is only available for activities that do not use endpoints defined in configuration unless unsafe caching is enabled. - - The following are the different cache sharing levels available for activities in a workflow and their recommended use: - -- **Host Level**: In the host sharing level, the cache is available only to the workflow instances hosted in the workflow service host. A cache can also be shared between workflow service hosts in a process-wide cache. - -- **Instance Level**: In the instance sharing level, the cache is available to a particular workflow instance throughout its lifetime but the cache is not available to other workflow instances. - -- **No Cache**: The cache is turned off by default if you have a workflow that uses endpoints defined in configuration. It is also recommended to keep the cache turned off in this case because turning it on could be unsecure. For example, if a different identity (different credentials or using impersonation) is required for each send. - -## Changing the Cache Sharing Level for a Client Workflow - - To set the cache sharing in a client workflow, add an instance of the class as an extension to the desired set of workflow instances. This results in sharing the cache across all the workflow instances. The following code examples show how to perform these steps. - - First, declare an instance of type . - -```csharp -// Create an instance of SendMessageChannelCache with default cache settings. -static SendMessageChannelCache sharedChannelCacheExtension = - new SendMessageChannelCache(); -``` - - Next, add the cache extension to each client workflow instance. - +> Workflows can use messaging activities to send either messages or parameters. The workflow runtime adds channel factories to the cache that create channels of type when you use a activity with a activity, and an when just using a activity (no ). + +## The Cache Sharing Levels + + By default, in a workflow hosted by a the cache used by messaging activities is shared across all workflow instances in the (host-level caching). For a client workflow that is not hosted by a , the cache is available only to the workflow instance (instance-level caching). The cache is only available for activities that do not use endpoints defined in configuration unless unsafe caching is enabled. + + The following are the different cache sharing levels available for activities in a workflow and their recommended use: + +- **Host Level**: In the host sharing level, the cache is available only to the workflow instances hosted in the workflow service host. A cache can also be shared between workflow service hosts in a process-wide cache. + +- **Instance Level**: In the instance sharing level, the cache is available to a particular workflow instance throughout its lifetime but the cache is not available to other workflow instances. + +- **No Cache**: The cache is turned off by default if you have a workflow that uses endpoints defined in configuration. It is also recommended to keep the cache turned off in this case because turning it on could be unsecure. For example, if a different identity (different credentials or using impersonation) is required for each send. + +## Changing the Cache Sharing Level for a Client Workflow + + To set the cache sharing in a client workflow, add an instance of the class as an extension to the desired set of workflow instances. This results in sharing the cache across all the workflow instances. The following code examples show how to perform these steps. + + First, declare an instance of type . + +```csharp +// Create an instance of SendMessageChannelCache with default cache settings. +static SendMessageChannelCache sharedChannelCacheExtension = + new SendMessageChannelCache(); +``` + + Next, add the cache extension to each client workflow instance. + ```csharp -WorkflowApplication clientInstance1 = new WorkflowApplication(new clientWorkflow1()); -WorkflowApplication clientInstance2 = new WorkflowApplication(new clientWorkflow2()); - +WorkflowApplication clientInstance1 = new WorkflowApplication(new clientWorkflow1()); +WorkflowApplication clientInstance2 = new WorkflowApplication(new clientWorkflow2()); + // Share the cache extension object - -clientInstance1.Extensions.Add(sharedChannelCacheExtension); -clientInstance2.Extensions.Add(sharedChannelCacheExtension); -``` - -## Changing the Cache Sharing Level for a Hosted Workflow Service - - To set the cache sharing in a hosted workflow service, add an instance of the class as an extension to all the workflow service hosts. This results in sharing the cache across all the workflow service hosts. The following code examples show to perform these steps. - - First, declare an instance of type at the class level. - -```csharp -// Create static instance of SendMessageChannelCache with default cache settings. -static SendMessageChannelCache sharedChannelCacheExtension = new - SendMessageChannelCache(); -``` - - Next, add the static cache extension to each workflow service host. - -```csharp -WorkflowServiceHost host1 = new WorkflowServiceHost(new serviceWorkflow1(), new Uri(baseAddress1)); -WorkflowServiceHost host2 = new WorkflowServiceHost(new serviceWorkflow2(), new Uri(baseAddress2)); - -// Share the static cache to get an AppDomain level cache. -host1.WorkflowExtensions.Add(sharedChannelCacheExtension); -host2.WorkflowExtensions.Add(sharedChannelCacheExtension); -``` - - To set the cache sharing in a hosted workflow service to the instance level, add a `Func` delegate as an extension to the workflow service host and assign this delegate to the code that instantiates a new instance of the class. This results in a different cache for each individual workflow instance, instead of a single cache shared by all workflow instances in the workflow service host. The following code example shows how to achieve this by using a lambda expression to directly define the extension that the delegate points to. - + +clientInstance1.Extensions.Add(sharedChannelCacheExtension); +clientInstance2.Extensions.Add(sharedChannelCacheExtension); +``` + +## Changing the Cache Sharing Level for a Hosted Workflow Service + + To set the cache sharing in a hosted workflow service, add an instance of the class as an extension to all the workflow service hosts. This results in sharing the cache across all the workflow service hosts. The following code examples show to perform these steps. + + First, declare an instance of type at the class level. + +```csharp +// Create static instance of SendMessageChannelCache with default cache settings. +static SendMessageChannelCache sharedChannelCacheExtension = new + SendMessageChannelCache(); +``` + + Next, add the static cache extension to each workflow service host. + +```csharp +WorkflowServiceHost host1 = new WorkflowServiceHost(new serviceWorkflow1(), new Uri(baseAddress1)); +WorkflowServiceHost host2 = new WorkflowServiceHost(new serviceWorkflow2(), new Uri(baseAddress2)); + +// Share the static cache to get an AppDomain level cache. +host1.WorkflowExtensions.Add(sharedChannelCacheExtension); +host2.WorkflowExtensions.Add(sharedChannelCacheExtension); +``` + + To set the cache sharing in a hosted workflow service to the instance level, add a `Func` delegate as an extension to the workflow service host and assign this delegate to the code that instantiates a new instance of the class. This results in a different cache for each individual workflow instance, instead of a single cache shared by all workflow instances in the workflow service host. The following code example shows how to achieve this by using a lambda expression to directly define the extension that the delegate points to. + ```csharp -serviceHost.WorkflowExtensions.Add(() => new SendMessageChannelCache -{ - // Use FactorySettings property to add custom factory cache settings. +serviceHost.WorkflowExtensions.Add(() => new SendMessageChannelCache +{ + // Use FactorySettings property to add custom factory cache settings. FactorySettings = new ChannelCacheSettings - { MaxItemsInCache = 5, }, - // Use ChannelSettings property to add custom channel cache settings. + { MaxItemsInCache = 5, }, + // Use ChannelSettings property to add custom channel cache settings. ChannelSettings = new ChannelCacheSettings - { MaxItemsInCache = 10 }, -}); -``` - -## Customizing Cache Settings - - You can customize the cache settings for the channel factory cache and the channel cache. The cache settings are defined in the class. The class defines default cache settings for the channel factory cache and the channel cache in its parameterless constructor. The following table lists the default values of these cache settings for each type of cache. - -|Settings|LeaseTimeout (min)|IdleTimeout (min)|MaxItemsInCache| -|-|-|-|-| -|Factory Cache Default|TimeSpan.MaxValue|2|16| -|Channel Cache Default|5|2|16| - - To customize the factory cache and channel cache settings, instantiate the class using the parameterized constructor and pass a new instance of the with custom values to each of the `factorySettings` and `channelSettings` parameters. Next, add the new instance of this class as an extension to a workflow service host or a workflow instance. The following code example shows how to perform these steps for a workflow instance. - -```csharp -ChannelCacheSettings factorySettings = new ChannelCacheSettings{ + { MaxItemsInCache = 10 }, +}); +``` + +## Customizing Cache Settings + + You can customize the cache settings for the channel factory cache and the channel cache. The cache settings are defined in the class. The class defines default cache settings for the channel factory cache and the channel cache in its parameterless constructor. The following table lists the default values of these cache settings for each type of cache. + +|Settings|LeaseTimeout (min)|IdleTimeout (min)|MaxItemsInCache| +|-|-|-|-| +|Factory Cache Default|TimeSpan.MaxValue|2|16| +|Channel Cache Default|5|2|16| + + To customize the factory cache and channel cache settings, instantiate the class using the parameterized constructor and pass a new instance of the with custom values to each of the `factorySettings` and `channelSettings` parameters. Next, add the new instance of this class as an extension to a workflow service host or a workflow instance. The following code example shows how to perform these steps for a workflow instance. + +```csharp +ChannelCacheSettings factorySettings = new ChannelCacheSettings{ MaxItemsInCache = 5, IdleTimeout = TimeSpan.FromMinutes(5), - LeaseTimeout = TimeSpan.FromMinutes(20)}; - -ChannelCacheSettings channelSettings = new ChannelCacheSettings{ + LeaseTimeout = TimeSpan.FromMinutes(20)}; + +ChannelCacheSettings channelSettings = new ChannelCacheSettings{ MaxItemsInCache = 5, - IdleTimeout = TimeSpan.FromMinutes(2), - LeaseTimeout = TimeSpan.FromMinutes(10) }; - + IdleTimeout = TimeSpan.FromMinutes(2), + LeaseTimeout = TimeSpan.FromMinutes(10) }; + SendMessageChannelCache customChannelCacheExtension = - new SendMessageChannelCache(factorySettings, channelSettings); - -clientInstance.Extensions.Add(customChannelCacheExtension); -``` - - To enable caching when your workflow service has endpoints defined in configuration, instantiate the class using the parameterized constructor with the `allowUnsafeCaching` parameter set to `true`. Next, add the new instance of this class as an extension to a workflow service host or a workflow instance. The following code example shows how to enable caching for a workflow instance. - -```csharp + new SendMessageChannelCache(factorySettings, channelSettings); + +clientInstance.Extensions.Add(customChannelCacheExtension); +``` + + To enable caching when your workflow service has endpoints defined in configuration, instantiate the class using the parameterized constructor with the `allowUnsafeCaching` parameter set to `true`. Next, add the new instance of this class as an extension to a workflow service host or a workflow instance. The following code example shows how to enable caching for a workflow instance. + +```csharp SendMessageChannelCache customChannelCacheExtension = - new SendMessageChannelCache{ AllowUnsafeCaching = true }; - -clientInstance.Extensions.Add(customChannelCacheExtension); -``` - - To disable the cache completely for the channel factories and the channels, disable the channel factory cache. Doing so also turns off the channel cache as the channels are owned by their corresponding channel factories. To disable the channel factory cache, pass the `factorySettings` parameter to the constructor initialized to a instance with a value of 0. The following code example shows this. - -```csharp -// Disable the factory cache. This results in the channel cache to be turned off as well. -ChannelCacheSettings factorySettings = new ChannelCacheSettings - { MaxItemsInCache = 0 }; - -ChannelCacheSettings channelSettings = new ChannelCacheSettings(); - + new SendMessageChannelCache{ AllowUnsafeCaching = true }; + +clientInstance.Extensions.Add(customChannelCacheExtension); +``` + + To disable the cache completely for the channel factories and the channels, disable the channel factory cache. Doing so also turns off the channel cache as the channels are owned by their corresponding channel factories. To disable the channel factory cache, pass the `factorySettings` parameter to the constructor initialized to a instance with a value of 0. The following code example shows this. + +```csharp +// Disable the factory cache. This results in the channel cache to be turned off as well. +ChannelCacheSettings factorySettings = new ChannelCacheSettings + { MaxItemsInCache = 0 }; + +ChannelCacheSettings channelSettings = new ChannelCacheSettings(); + SendMessageChannelCache customChannelCacheExtension = new SendMessageChannelCache(factorySettings, channelSettings); - -clientInstance.Extensions.Add(customChannelCacheExtension); -``` - - You can choose to use only the channel factory cache and disable the channel cache by passing the `channelSettings` parameter to the constructor initialized to a instance with a value of 0. The following code example shows this. - -```csharp -ChannelCacheSettings factorySettings = new ChannelCacheSettings(); -// Disable only the channel cache. -ChannelCacheSettings channelSettings = new ChannelCacheSettings - { MaxItemsInCache = 0}; - + +clientInstance.Extensions.Add(customChannelCacheExtension); +``` + + You can choose to use only the channel factory cache and disable the channel cache by passing the `channelSettings` parameter to the constructor initialized to a instance with a value of 0. The following code example shows this. + +```csharp +ChannelCacheSettings factorySettings = new ChannelCacheSettings(); +// Disable only the channel cache. +ChannelCacheSettings channelSettings = new ChannelCacheSettings + { MaxItemsInCache = 0}; + SendMessageChannelCache customChannelCacheExtension = new SendMessageChannelCache(factorySettings, channelSettings); - -clientInstance.Extensions.Add(customChannelCacheExtension); -``` - - In a hosted workflow service, you can specify the factory cache and channel cache settings in the application configuration file. To do so, add a service behavior that contains the cache settings for the factory and channel cache and add this service behavior to your service. The following example shows the contents of a configuration file that contains the `MyChannelCacheBehavior` service behavior with the custom factory cache and channel cache settings. This service behavior is added to the service through the `behaviorConfiguration` attribute. - -```xml + +clientInstance.Extensions.Add(customChannelCacheExtension); +``` + + In a hosted workflow service, you can specify the factory cache and channel cache settings in the application configuration file. To do so, add a service behavior that contains the cache settings for the factory and channel cache and add this service behavior to your service. The following example shows the contents of a configuration file that contains the `MyChannelCacheBehavior` service behavior with the custom factory cache and channel cache settings. This service behavior is added to the service through the `behaviorConfiguration` attribute. + +```xml - + - - - - + + + + - - - - - - - - - - - + + + + + + + + + + + ``` diff --git a/docs/framework/wcf/feature-details/channel-factory-and-caching.md b/docs/framework/wcf/feature-details/channel-factory-and-caching.md index 9f58f9974e768..aaf65ae0718c3 100644 --- a/docs/framework/wcf/feature-details/channel-factory-and-caching.md +++ b/docs/framework/wcf/feature-details/channel-factory-and-caching.md @@ -6,7 +6,7 @@ ms.assetid: 954f030e-091c-4c0e-a7a2-10f9a6b1f529 --- # Channel Factory and Caching -WCF client applications use the class to create a communication channel with a WCF service. Creating instances incurs some overhead because it involves the following operations: +WCF client applications use the class to create a communication channel with a WCF service. Creating instances incurs some overhead because it involves the following operations: - Constructing the tree @@ -19,21 +19,21 @@ WCF client applications use the cl To help minimize this overhead, WCF can cache channel factories when you are using a WCF client proxy. > [!TIP] -> You have direct control over channel factory creation when you use the class directly. +> You have direct control over channel factory creation when you use the class directly. -WCF client proxies generated with [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) are derived from . defines a static property that defines channel factory caching behavior. Cache settings are made for a specific type. For example, setting `ClientBase.CacheSettings` to one of the values defined below will affect only those proxy/ClientBase of type `ITest`. The cache setting for a particular is immutable as soon as the first proxy/ClientBase instance is created. +WCF client proxies generated with [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) are derived from . defines a static property that defines channel factory caching behavior. Cache settings are made for a specific type. For example, setting `ClientBase.CacheSettings` to one of the values defined below will affect only those proxy/ClientBase of type `ITest`. The cache setting for a particular is immutable as soon as the first proxy/ClientBase instance is created. ## Specifying Caching Behavior -Caching behavior is specified by setting the property to one of the following values. +Caching behavior is specified by setting the property to one of the following values. |Cache Setting Value|Description| |-------------------------|-----------------| -||All instances of within the app-domain can participate in caching. The developer has determined that there are no adverse security implications to caching. Caching will not be turned off even if "security-sensitive" properties on are accessed. The "security-sensitive" properties of are , and .| -||Only instances of created from endpoints defined in configuration files participate in caching within the app-domain. Any instances of created programmatically within that app-domain will not participate in caching. Also, caching will be disabled for an instance of once any of its "security-sensitive" properties is accessed.| -||Caching is turned off for all instances of of a particular type within the app-domain in question.| +||All instances of within the app-domain can participate in caching. The developer has determined that there are no adverse security implications to caching. Caching will not be turned off even if "security-sensitive" properties on are accessed. The "security-sensitive" properties of are , and .| +||Only instances of created from endpoints defined in configuration files participate in caching within the app-domain. Any instances of created programmatically within that app-domain will not participate in caching. Also, caching will be disabled for an instance of once any of its "security-sensitive" properties is accessed.| +||Caching is turned off for all instances of of a particular type within the app-domain in question.| -The following code snippets illustrate how to use the property. +The following code snippets illustrate how to use the property. ```csharp class Program @@ -110,7 +110,7 @@ In the example above, all instances of `TestClient` would use different channel ## See also -- +- - [Building Clients](../building-clients.md) - [Clients](clients.md) - [Accessing Services Using a WCF Client](../accessing-services-using-a-wcf-client.md) diff --git a/docs/framework/wcf/feature-details/choosing-a-filter.md b/docs/framework/wcf/feature-details/choosing-a-filter.md index 7ac0e81ddb9f0..120bddf7d5e6b 100644 --- a/docs/framework/wcf/feature-details/choosing-a-filter.md +++ b/docs/framework/wcf/feature-details/choosing-a-filter.md @@ -14,7 +14,7 @@ When selecting the filters that are used by the Routing Service, it is important ### Action -The Action filter inspects the property. If the contents of the Action header in the message match the filter data value specified in the filter configuration, then this filter returns `true`. The following example defines a `FilterElement` that uses the Action filter to match messages with an action header that contains a value of `http://namespace/contract/operation/`. +The Action filter inspects the property. If the contents of the Action header in the message match the filter data value specified in the filter configuration, then this filter returns `true`. The following example defines a `FilterElement` that uses the Action filter to match messages with an action header that contains a value of `http://namespace/contract/operation/`. ```xml diff --git a/docs/framework/wcf/feature-details/choosing-a-message-encoder.md b/docs/framework/wcf/feature-details/choosing-a-message-encoder.md index 1ea926f44a1f7..fe935ff93f3e9 100644 --- a/docs/framework/wcf/feature-details/choosing-a-message-encoder.md +++ b/docs/framework/wcf/feature-details/choosing-a-message-encoder.md @@ -6,40 +6,40 @@ ms.assetid: 2204d82d-d962-4922-a79e-c9a231604f19 --- # Choose a Message Encoder -This article discusses criteria for choosing among the message encoders that are included in Windows Communication Foundation (WCF): binary, text, and Message Transmission Optimization Mechanism (MTOM). - - In WCF, you specify how to transfer data across a network between endpoints by means of a *binding*, which is made up of a sequence of *binding elements*. A message encoder is represented by a message encoding binding element in the binding stack. A binding includes optional protocol binding elements, such as a security binding element or reliable messaging binding element, a required message encoding binding element, and a required transport binding element. - - The message encoding binding element sits below the optional protocol binding elements and above the required transport binding element. On the outgoing side, a message encoder serializes the outgoing and passes it to the transport. On the incoming side, a message encoder receives the serialized form of a from the transport and passes it to the higher protocol layer, if present, or to the application, if not. - - When connecting to a pre-existing client or server, you may not have a choice about using a particular message encoding since you need to encode your messages in a way that the other side is expecting. However, if you are writing a WCF service, you can expose your service through multiple endpoints, each using a different message encoding. This allows clients to choose the best encoding for talking to your service over the endpoint that is best for them, as well as giving your clients the flexibility to choose the encoding that is best for them. Using multiple endpoints also allows you to combine the advantages of different message encodings with other binding elements. - -## System-Provided Encoders - - WCF includes three message encoders, which are represented by the following three classes: - -- , the text message encoder, supports both plain XML encoding and SOAP encoding. The plain XML encoding mode of the text message encoder is called "plain old XML" (POX) to distinguish it from text-based SOAP encoding. To enable POX, set the property to . Use the text message encoder to interoperate with non-WCF endpoints. - -- , the binary message encoder, uses a compact binary format and is optimized for WCF to WCF communication, and hence is not interoperable. This is also the most performant encoder of all the encoders WCF provides. - -- , the binding element, specifies the character encoding and message versioning for messages using MTOM encoding. MTOM is an efficient technology for transmitting binary data in WCF messages. The MTOM encoder attempts to create a balance between efficiency and interoperability. The MTOM encoding transmits most XML in textual form, but optimizes large blocks of binary data by transmitting them as-is, without conversion to text. In terms of efficiency, among the encoders WCF provides, MTOM is in-between text (the slowest) and binary (the fastest). - -## How to Choose a Message Encoder - - The following table describes common factors used to choose a message encoder. Prioritize the factors that are important for your application, and then choose the message encoders that work best with these factors. Be sure to consider any additional factors not listed in this table and any custom message encoders that may be required in your application. - -|Factor|Description|Encoders that support this factor| -|------------|-----------------|---------------------------------------| -|Supported Character Sets| and support only the UTF8 and UTF16 Unicode (*big-endian* and *little-endian*) encodings. If other encodings are required, such as UTF7 or ASCII, a custom encoder must be used. For a sample custom encoder, see [Custom Message Encoder](../samples/custom-message-encoder-custom-text-encoder.md).|Text| -|Inspection|Inspection is the ability to examine messages during transmission. Text encodings, either with or without the use of SOAP, allow messages to be inspected and analyzed by many applications without the use of specialized tools. The use of transfer security, at either the message or transport level, affects your ability to inspect messages. Confidentiality protects a message from being examined and integrity protects a message from being modified.|Text| -|Reliability|Reliability is the resiliency of an encoder to transmission errors. Reliability can also be provided at the message, transport, or application layer. All of the standard WCF encoders assume that another layer is providing reliability. The encoder has little ability to recover from a transmission error.|None| -|Simplicity|Simplicity represents the ease with which you can create encoders and decoders for an encoding specification. Text encodings are particularly advantageous for simplicity, and the POX text encoding has the additional advantage of not requiring support for processing SOAP.|Text (POX)| -|Size|The encoding determines the amount of overhead imposed on content. The size of encoded messages is directly related to the maximum throughput of service operations. Binary encodings are generally more compact than text encodings. When message size is at a premium, consider also compressing the message contents during encoding. However, compression adds processing costs for both the message sender and receiver.|Binary| -|Streaming|Streaming allows applications to begin processing a message before the entire message has arrived. Effectively using streaming requires that the important data for a message be available at the beginning of the message so that the receiving application is not required to wait for it to arrive. Moreover, applications that use streamed transfer must organize data in the message incrementally so that the content does not have forward dependencies. In many cases, you must compromise between streaming content and having the smallest possible transfer size for that content.|None| -|Third-Party Tool Support|Support areas for an encoding include development and diagnosis. Third-party developers have made a large investment in libraries and toolkits for handling messages encoded in the POX format.|Text (POX)| -|Interoperability|This factor refers to the ability of a WCF encoder to interoperate with non-WCF services.|Text

MTOM (partial)| - -Note: When using the Binary Encoder, using the IgnoreWhitespace setting when creating a XMLReader will have no effect. For example, if you do the following inside a service operation: +This article discusses criteria for choosing among the message encoders that are included in Windows Communication Foundation (WCF): binary, text, and Message Transmission Optimization Mechanism (MTOM). + + In WCF, you specify how to transfer data across a network between endpoints by means of a *binding*, which is made up of a sequence of *binding elements*. A message encoder is represented by a message encoding binding element in the binding stack. A binding includes optional protocol binding elements, such as a security binding element or reliable messaging binding element, a required message encoding binding element, and a required transport binding element. + + The message encoding binding element sits below the optional protocol binding elements and above the required transport binding element. On the outgoing side, a message encoder serializes the outgoing and passes it to the transport. On the incoming side, a message encoder receives the serialized form of a from the transport and passes it to the higher protocol layer, if present, or to the application, if not. + + When connecting to a pre-existing client or server, you may not have a choice about using a particular message encoding since you need to encode your messages in a way that the other side is expecting. However, if you are writing a WCF service, you can expose your service through multiple endpoints, each using a different message encoding. This allows clients to choose the best encoding for talking to your service over the endpoint that is best for them, as well as giving your clients the flexibility to choose the encoding that is best for them. Using multiple endpoints also allows you to combine the advantages of different message encodings with other binding elements. + +## System-Provided Encoders + + WCF includes three message encoders, which are represented by the following three classes: + +- , the text message encoder, supports both plain XML encoding and SOAP encoding. The plain XML encoding mode of the text message encoder is called "plain old XML" (POX) to distinguish it from text-based SOAP encoding. To enable POX, set the property to . Use the text message encoder to interoperate with non-WCF endpoints. + +- , the binary message encoder, uses a compact binary format and is optimized for WCF to WCF communication, and hence is not interoperable. This is also the most performant encoder of all the encoders WCF provides. + +- , the binding element, specifies the character encoding and message versioning for messages using MTOM encoding. MTOM is an efficient technology for transmitting binary data in WCF messages. The MTOM encoder attempts to create a balance between efficiency and interoperability. The MTOM encoding transmits most XML in textual form, but optimizes large blocks of binary data by transmitting them as-is, without conversion to text. In terms of efficiency, among the encoders WCF provides, MTOM is in-between text (the slowest) and binary (the fastest). + +## How to Choose a Message Encoder + + The following table describes common factors used to choose a message encoder. Prioritize the factors that are important for your application, and then choose the message encoders that work best with these factors. Be sure to consider any additional factors not listed in this table and any custom message encoders that may be required in your application. + +|Factor|Description|Encoders that support this factor| +|------------|-----------------|---------------------------------------| +|Supported Character Sets| and support only the UTF8 and UTF16 Unicode (*big-endian* and *little-endian*) encodings. If other encodings are required, such as UTF7 or ASCII, a custom encoder must be used. For a sample custom encoder, see [Custom Message Encoder](../samples/custom-message-encoder-custom-text-encoder.md).|Text| +|Inspection|Inspection is the ability to examine messages during transmission. Text encodings, either with or without the use of SOAP, allow messages to be inspected and analyzed by many applications without the use of specialized tools. The use of transfer security, at either the message or transport level, affects your ability to inspect messages. Confidentiality protects a message from being examined and integrity protects a message from being modified.|Text| +|Reliability|Reliability is the resiliency of an encoder to transmission errors. Reliability can also be provided at the message, transport, or application layer. All of the standard WCF encoders assume that another layer is providing reliability. The encoder has little ability to recover from a transmission error.|None| +|Simplicity|Simplicity represents the ease with which you can create encoders and decoders for an encoding specification. Text encodings are particularly advantageous for simplicity, and the POX text encoding has the additional advantage of not requiring support for processing SOAP.|Text (POX)| +|Size|The encoding determines the amount of overhead imposed on content. The size of encoded messages is directly related to the maximum throughput of service operations. Binary encodings are generally more compact than text encodings. When message size is at a premium, consider also compressing the message contents during encoding. However, compression adds processing costs for both the message sender and receiver.|Binary| +|Streaming|Streaming allows applications to begin processing a message before the entire message has arrived. Effectively using streaming requires that the important data for a message be available at the beginning of the message so that the receiving application is not required to wait for it to arrive. Moreover, applications that use streamed transfer must organize data in the message incrementally so that the content does not have forward dependencies. In many cases, you must compromise between streaming content and having the smallest possible transfer size for that content.|None| +|Third-Party Tool Support|Support areas for an encoding include development and diagnosis. Third-party developers have made a large investment in libraries and toolkits for handling messages encoded in the POX format.|Text (POX)| +|Interoperability|This factor refers to the ability of a WCF encoder to interoperate with non-WCF services.|Text

MTOM (partial)| + +Note: When using the Binary Encoder, using the IgnoreWhitespace setting when creating a XMLReader will have no effect. For example, if you do the following inside a service operation: ```csharp public void OperationContract(XElement input) @@ -55,18 +55,18 @@ public void OperationContract(XElement input) Console.WriteLine("Read {0} lines with reader", counter); } -``` - -The IgnoreWhitespace setting is ignored. - +``` + +The IgnoreWhitespace setting is ignored. + ## Compression and the Binary Encoder -Beginning with WCF 4.5 the WCF binary encoder adds support for compression. This enables you to use the gzip/deflate algorithm for sending compressed messages from a WCF client and also respond with compressed messages from a self-hosted WCF service. This feature enables compression on both the HTTP and TCP transports. An IIS hosted WCF service can always be enabled for sending compressed responses by configuring the IIS host server. The type of compression is configured with the property. This property is set to one of the enum values: +Beginning with WCF 4.5 the WCF binary encoder adds support for compression. This enables you to use the gzip/deflate algorithm for sending compressed messages from a WCF client and also respond with compressed messages from a self-hosted WCF service. This feature enables compression on both the HTTP and TCP transports. An IIS hosted WCF service can always be enabled for sending compressed responses by configuring the IIS host server. The type of compression is configured with the property. This property is set to one of the enum values: - - - - + Since this property is only exposed on the binaryMessageEncodingBindingElement, you will need to create a custom binding like the following to use this feature: ```xml @@ -78,8 +78,8 @@ Since this property is only exposed on the binaryMessageEncodingBindingElement, ``` -Both the client and the service need to agree to send and receive compressed messages and therefore the compressionFormat property must be configured on the binaryMessageEncoding element on both client and service. A ProtocolException is thrown if either the service or client is not configured for compression, but the other side is. Enabling compression should be carefully considered. Compression is mostly useful if network bandwidth is a bottleneck. In the case where the CPU is the bottleneck, compression will decrease throughput. Appropriate testing must be done in a simulated environment to find out if this benefits the application - +Both the client and the service need to agree to send and receive compressed messages and therefore the compressionFormat property must be configured on the binaryMessageEncoding element on both client and service. A ProtocolException is thrown if either the service or client is not configured for compression, but the other side is. Enabling compression should be carefully considered. Compression is mostly useful if network bandwidth is a bottleneck. In the case where the CPU is the bottleneck, compression will decrease throughput. Appropriate testing must be done in a simulated environment to find out if this benefits the application + ## See also - [Bindings](bindings.md) diff --git a/docs/framework/wcf/feature-details/claim-creation-and-resource-values.md b/docs/framework/wcf/feature-details/claim-creation-and-resource-values.md index 4fc266fdd2cf3..ff04a5e921897 100644 --- a/docs/framework/wcf/feature-details/claim-creation-and-resource-values.md +++ b/docs/framework/wcf/feature-details/claim-creation-and-resource-values.md @@ -2,42 +2,42 @@ description: "Learn more about: Claim Creation and Resource Values" title: "Claim Creation and Resource Values" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "claims [WCF], creation and resource values" ms.assetid: 30431f76-cbe7-4bad-bad7-8e43e23a82d4 --- # Claim Creation and Resource Values -The class provides several methods for creating instances of built-in claims types. Of these methods, the following perform no semantic or format checking on the supplied resource: - -- - -- (does not check the length or content of the byte array) - -- - -- - -- (does not check the length or content of the byte array) - -- - - Care should be taken when calling the above methods to ensure that the resource values passed in are of the correct format or contain the correct kind of information (or both). - - The following methods take specific types: - -- - -- - -- - -- - -- - -- - +The class provides several methods for creating instances of built-in claims types. Of these methods, the following perform no semantic or format checking on the supplied resource: + +- + +- (does not check the length or content of the byte array) + +- + +- + +- (does not check the length or content of the byte array) + +- + + Care should be taken when calling the above methods to ensure that the resource values passed in are of the correct format or contain the correct kind of information (or both). + + The following methods take specific types: + +- + +- + +- + +- + +- + +- + ## See also - diff --git a/docs/framework/wcf/feature-details/claims-and-denying-access-to-resources.md b/docs/framework/wcf/feature-details/claims-and-denying-access-to-resources.md index 54cf96016d04c..f18c3417a6aa7 100644 --- a/docs/framework/wcf/feature-details/claims-and-denying-access-to-resources.md +++ b/docs/framework/wcf/feature-details/claims-and-denying-access-to-resources.md @@ -2,16 +2,16 @@ description: "Learn more about: Claims and Denying Access to Resources" title: "Claims and Denying Access to Resources" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "claims [WCF], denying access to resources" ms.assetid: 145ebb41-680e-4256-b14c-1efb4af1e982 --- # Claims and Denying Access to Resources -Windows Communication Foundation (WCF) supports a claims-based authorization mechanism. As well as allowing access to resources based on the presence of claims, systems often deny access to resources based on the presence of claims. Such systems should examine the for claims that result in access being denied before looking for claims that result in access being allowed. - - For example, a system might deny access to a resource to anyone who has a claim with a type of `Age`, a right of , and a resource value of `Under 21` only when that identity also has a claim of type `Name`, a right of , and a resource value of `Mallory`. Put another way, the system denies access to anyone who is under 21 years old and grants access when the name is Mallory. To correctly implement this semantic, it is important to look for the `Age` claim first and determine whether the age is under 21 years old. Otherwise, if Mallory is under 21, then the resource may be granted access solely on the basis of the `Name` claim. - +Windows Communication Foundation (WCF) supports a claims-based authorization mechanism. As well as allowing access to resources based on the presence of claims, systems often deny access to resources based on the presence of claims. Such systems should examine the for claims that result in access being denied before looking for claims that result in access being allowed. + + For example, a system might deny access to a resource to anyone who has a claim with a type of `Age`, a right of , and a resource value of `Under 21` only when that identity also has a claim of type `Name`, a right of , and a resource value of `Mallory`. Put another way, the system denies access to anyone who is under 21 years old and grants access when the name is Mallory. To correctly implement this semantic, it is important to look for the `Age` claim first and determine whether the age is under 21 years old. Otherwise, if Mallory is under 21, then the resource may be granted access solely on the basis of the `Name` claim. + ## See also - [Managing Claims and Authorization with the Identity Model](managing-claims-and-authorization-with-the-identity-model.md) diff --git a/docs/framework/wcf/feature-details/claims-and-tokens.md b/docs/framework/wcf/feature-details/claims-and-tokens.md index 94769adfacfcb..036440379818d 100644 --- a/docs/framework/wcf/feature-details/claims-and-tokens.md +++ b/docs/framework/wcf/feature-details/claims-and-tokens.md @@ -11,11 +11,11 @@ This topic describes the various claim types that Windows Communication Foundati You can examine the claims of a client credential by using the and classes. The `ClaimSet` contains a collection of `Claim` objects. Each `Claim` has the following important members: -- The property returns a Uniform Resource Identifier (URI) that specifies the type of claim being made. For example, a claim type may be a thumbprint of a certificate, in which case the URI is `http://schemas.microsoft.com/ws/20005/05/identity/claims/thumprint`. +- The property returns a Uniform Resource Identifier (URI) that specifies the type of claim being made. For example, a claim type may be a thumbprint of a certificate, in which case the URI is `http://schemas.microsoft.com/ws/20005/05/identity/claims/thumprint`. -- The property returns a URI that specifies the right of the claim. Predefined rights are found in the class (, ). +- The property returns a URI that specifies the right of the claim. Predefined rights are found in the class (, ). -- The property returns the resource associated with the claim. +- The property returns the resource associated with the claim. Each also has an property, which represents the of the `Issuer`. @@ -27,19 +27,19 @@ Where a client credential maps to a Windows user account, the resulting with a value of security identifier (SID), a property value of `Identity`, and a that returns the actual SID value. A SID is a unique value the domain controller issues to every user. The SID is used to identify the user in interactions with Windows security. + - A with a value of security identifier (SID), a property value of `Identity`, and a that returns the actual SID value. A SID is a unique value the domain controller issues to every user. The SID is used to identify the user in interactions with Windows security. - - A with a value of SID, a of `PossessProperty`, and a of the SID value. + - A with a value of SID, a of `PossessProperty`, and a of the SID value. - - A with a of , a of `PossessProperty` and a of string containing the user name (for example, "MYMACHINE\Bob"). + - A with a of , a of `PossessProperty` and a of string containing the user name (for example, "MYMACHINE\Bob"). - - Additional SID claims with for the various groups the user belongs to. + - Additional SID claims with for the various groups the user belongs to. ## Certificates Where the client credential is a certificate, the resulting has the following values: -- For self-issued certificates, the `Issuer` is the itself. The returns a of , a of `Identity`, and a value that is a array containing the thumbprint of the certificate. +- For self-issued certificates, the `Issuer` is the itself. The returns a of , a of `Identity`, and a value that is a array containing the thumbprint of the certificate. - For a certificate issued by a certification authority, the issuer is the `ClaimSet` representing the certification authority’s certificate. @@ -51,15 +51,15 @@ Where the client credential is a certificate, the resulting property of the `ClaimSet` class. The `ClaimSet` contains an `Identity` claim of type whose resource is the user name the client provides. A corresponding claim has a `Right` of `PossessProperty`. +Where the client credential is a user name/password (or equivalent) that does not map to a Windows account, the resulting `ClaimSet` is issued by the static property of the `ClaimSet` class. The `ClaimSet` contains an `Identity` claim of type whose resource is the user name the client provides. A corresponding claim has a `Right` of `PossessProperty`. ## RSA Keys -Where an RSA key not associated with a certificate is used, the resulting `ClaimSet` is self-issued and contains an `Identity` claim of type whose resource is the RSA key. A corresponding claim has a `Right` of `PossessProperty`. +Where an RSA key not associated with a certificate is used, the resulting `ClaimSet` is self-issued and contains an `Identity` claim of type whose resource is the RSA key. A corresponding claim has a `Right` of `PossessProperty`. ## SAML -Where the client authenticates with a Security Assertions Markup Language (SAML) token, the resulting `ClaimSet` is issued by the entity that signed the SAML token, often the certificate of the security token service (STS) that issued the SAML token. The `ClaimSet` contains various claims as found in the SAML token. If the SAML token contains a `SamlSubject` with a non-`null` name, then an `Identity` claim with a type of and a resource type of are created. +Where the client authenticates with a Security Assertions Markup Language (SAML) token, the resulting `ClaimSet` is issued by the entity that signed the SAML token, often the certificate of the security token service (STS) that issued the SAML token. The `ClaimSet` contains various claims as found in the SAML token. If the SAML token contains a `SamlSubject` with a non-`null` name, then an `Identity` claim with a type of and a resource type of are created. ## Identity Claims and ServiceSecurityContext.IsAnonymous diff --git a/docs/framework/wcf/feature-details/client-architecture.md b/docs/framework/wcf/feature-details/client-architecture.md index 3c6077999ce22..128f9f32d3f2c 100644 --- a/docs/framework/wcf/feature-details/client-architecture.md +++ b/docs/framework/wcf/feature-details/client-architecture.md @@ -18,23 +18,23 @@ Applications use Windows Communication Foundation (WCF) client objects to invoke - A client channel that is built based on the configuration settings specified by the used binding. - Applications can create such clients on demand, either through a or by creating an instance of a derived class as it is generated by the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). These ready-built client classes encapsulate and delegate to a client channel implementation that is dynamically constructed by a . Therefore, the client channel and the channel factory that produces them are the focal point of interest for this discussion. + Applications can create such clients on demand, either through a or by creating an instance of a derived class as it is generated by the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). These ready-built client classes encapsulate and delegate to a client channel implementation that is dynamically constructed by a . Therefore, the client channel and the channel factory that produces them are the focal point of interest for this discussion. ## Client Objects and Client Channels - The base interface of WCF clients is the interface, which exposes core client functionality as well as the basic communication object functionality of , the context functionality of , and the extensible behavior of . + The base interface of WCF clients is the interface, which exposes core client functionality as well as the basic communication object functionality of , the context functionality of , and the extensible behavior of . The interface, however, does not define a service contract itself. Those are declared by the service contract interface (typically generated from service metadata using a tool like the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md)). WCF client types extend both and the target service contract interface to enable applications to call operations directly and also have access to client-side runtime functionality. Creating an WCF client provides WCF objects with the information necessary to create a runtime that can connect and interact with the configured service endpoint. - As mentioned earlier, the two WCF client types must be configured before you can use them. The simplest WCF client types are objects that derive from (or if the service contract is a duplex contract). You can create these types by using a constructor, configured programmatically, or by using a configuration file, and then called directly to invoke service operations. For a basic overview of objects, see [WCF Client Overview](../wcf-client-overview.md). + As mentioned earlier, the two WCF client types must be configured before you can use them. The simplest WCF client types are objects that derive from (or if the service contract is a duplex contract). You can create these types by using a constructor, configured programmatically, or by using a configuration file, and then called directly to invoke service operations. For a basic overview of objects, see [WCF Client Overview](../wcf-client-overview.md). - The second type is generated at runtime from a call to the method. Applications concerned with tight control of the communication specifics typically use this client type, called a *client channel object*, because it enables more direct interaction than the underlying client runtime and channel system. + The second type is generated at runtime from a call to the method. Applications concerned with tight control of the communication specifics typically use this client type, called a *client channel object*, because it enables more direct interaction than the underlying client runtime and channel system. ## Channel Factories - The class that is responsible for creating the underlying runtime that supports client invocations is the class. Both WCF client objects and WCF client channel objects use a object to create instances; the derived client object encapsulates the handling of the channel factory, but for a number of scenarios it is perfectly reasonable to use the channel factory directly. The common scenario for this is if you want to repeatedly create new client channels from an existing factory. If you are using a client object, you can obtain the underlying channel factory from a WCF client object by calling the property. + The class that is responsible for creating the underlying runtime that supports client invocations is the class. Both WCF client objects and WCF client channel objects use a object to create instances; the derived client object encapsulates the handling of the channel factory, but for a number of scenarios it is perfectly reasonable to use the channel factory directly. The common scenario for this is if you want to repeatedly create new client channels from an existing factory. If you are using a client object, you can obtain the underlying channel factory from a WCF client object by calling the property. - The important thing to remember about channel factories is that they create new instances of client channels for the configuration provided to them prior to calling . Once you call (or , , or any operation on a WCF client object), you cannot modify the channel factory and expect to get channels to different service instances, even if you are merely changing the target endpoint address. If you want to create a client object or client channel with a different configuration, you must create a new channel factory first. + The important thing to remember about channel factories is that they create new instances of client channels for the configuration provided to them prior to calling . Once you call (or , , or any operation on a WCF client object), you cannot modify the channel factory and expect to get channels to different service instances, even if you are merely changing the target endpoint address. If you want to create a client object or client channel with a different configuration, you must create a new channel factory first. For more information about various issues using WCF client objects and WCF client channels, see [Accessing Services Using a WCF Client](accessing-services-using-a-client.md). @@ -46,15 +46,15 @@ Applications use Windows Communication Foundation (WCF) client objects to invoke [!code-csharp[C_GeneratedCodeFiles#12](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#12)] - To connect to an `ISampleService` service, use the generated contract interface directly with a channel factory (). Once you create and configure a channel factory for a particular contract, you can call the method to return client channel objects that you can use to communicate with an `ISampleService` service. + To connect to an `ISampleService` service, use the generated contract interface directly with a channel factory (). Once you create and configure a channel factory for a particular contract, you can call the method to return client channel objects that you can use to communicate with an `ISampleService` service. - When using the class with a service contract interface, you must cast to the interface to explicitly open, close, or abort the channel. To make it easier to work with, the Svcutil.exe tool also generates a helper interface that implements both the service contract interface and to enable you to interact with the client channel infrastructure without having to cast. The following code shows the definition of a helper client channel that implements the preceding service contract. + When using the class with a service contract interface, you must cast to the interface to explicitly open, close, or abort the channel. To make it easier to work with, the Svcutil.exe tool also generates a helper interface that implements both the service contract interface and to enable you to interact with the client channel infrastructure without having to cast. The following code shows the definition of a helper client channel that implements the preceding service contract. [!code-csharp[C_GeneratedCodeFiles#13](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#13)] #### Creating a New WCF Client Channel Object - To use a client channel to connect to an `ISampleService` service, use the generated contract interface (or the helper version) directly with a channel factory, passing the type of the contract interface as the type parameter. Once a channel factory for a particular contract has been created and configured, you can call the method to return client channel objects that you can use to communicate with an `ISampleService` service. + To use a client channel to connect to an `ISampleService` service, use the generated contract interface (or the helper version) directly with a channel factory, passing the type of the contract interface as the type parameter. Once a channel factory for a particular contract has been created and configured, you can call the method to return client channel objects that you can use to communicate with an `ISampleService` service. When created, the client channel objects implement and the contract interface. Therefore, you can use them directly to call operations that interact with a service that supports that contract. diff --git a/docs/framework/wcf/feature-details/client-configuration.md b/docs/framework/wcf/feature-details/client-configuration.md index 0b540b0693cb7..232e02fc35dac 100644 --- a/docs/framework/wcf/feature-details/client-configuration.md +++ b/docs/framework/wcf/feature-details/client-configuration.md @@ -6,91 +6,91 @@ ms.topic: how-to --- # Client Configuration -You can use the Windows Communication Foundation (WCF) client configuration to specify the address, binding, behavior, and contract, the "ABC" properties of the client endpoint, which clients use to connect to service endpoints. The [\](../../configure-apps/file-schema/wcf/client.md) element has an [\](../../configure-apps/file-schema/wcf/endpoint-of-client.md) element whose attributes are used to configure the endpoint ABCs. These attributes are discussed in the [Configuring Endpoints](#configuring-endpoints) section. - - The [\](../../configure-apps/file-schema/wcf/endpoint-of-client.md) element also contains a [\](../../configure-apps/file-schema/wcf/metadata.md) element that is used to specify settings for importing and exporting metadata, a [\](../../configure-apps/file-schema/wcf/headers.md) element that contains a collection of custom address headers, and an [\](../../configure-apps/file-schema/wcf/identity.md) element that enables the authentication of an endpoint by other endpoints exchanging messages with it. The [\](../../configure-apps/file-schema/wcf/headers.md) and [\](../../configure-apps/file-schema/wcf/identity.md) elements are part of the and are discussed in the [Addresses](endpoint-addresses.md) article. Links to topics that explain the use of metadata extensions are provided in the [Configuring Metadata](#configuring-metadata) section. - -## Configuring Endpoints - - The client configuration is designed to allow the client to specify one or more endpoints, each with its own name, address, and contract, with each referencing the [\](../../configure-apps/file-schema/wcf/bindings.md) and [\](../../configure-apps/file-schema/wcf/behaviors.md) elements in the client configuration to be used to configure that endpoint. The client configuration file should be named "App.config" because this is the name that the WCF runtime expects. The following example shows a client configuration file. - -```xml - - - - - - - - - - - - - - - - +You can use the Windows Communication Foundation (WCF) client configuration to specify the address, binding, behavior, and contract, the "ABC" properties of the client endpoint, which clients use to connect to service endpoints. The [\](../../configure-apps/file-schema/wcf/client.md) element has an [\](../../configure-apps/file-schema/wcf/endpoint-of-client.md) element whose attributes are used to configure the endpoint ABCs. These attributes are discussed in the [Configuring Endpoints](#configuring-endpoints) section. + + The [\](../../configure-apps/file-schema/wcf/endpoint-of-client.md) element also contains a [\](../../configure-apps/file-schema/wcf/metadata.md) element that is used to specify settings for importing and exporting metadata, a [\](../../configure-apps/file-schema/wcf/headers.md) element that contains a collection of custom address headers, and an [\](../../configure-apps/file-schema/wcf/identity.md) element that enables the authentication of an endpoint by other endpoints exchanging messages with it. The [\](../../configure-apps/file-schema/wcf/headers.md) and [\](../../configure-apps/file-schema/wcf/identity.md) elements are part of the and are discussed in the [Addresses](endpoint-addresses.md) article. Links to topics that explain the use of metadata extensions are provided in the [Configuring Metadata](#configuring-metadata) section. + +## Configuring Endpoints + + The client configuration is designed to allow the client to specify one or more endpoints, each with its own name, address, and contract, with each referencing the [\](../../configure-apps/file-schema/wcf/bindings.md) and [\](../../configure-apps/file-schema/wcf/behaviors.md) elements in the client configuration to be used to configure that endpoint. The client configuration file should be named "App.config" because this is the name that the WCF runtime expects. The following example shows a client configuration file. + +```xml + + + + + + + + + + + + + + + + - - //Configure another endpoint here. - - - + + //Configure another endpoint here. + + + - - + + - + hostNameComparisonMode="StrongWildcard"> + - + enabled="false" /> + - - - - - - - + + + + + + + - - - - - - - - - - -``` - - The optional `name` attribute uniquely identifies an endpoint for a given contract. It is used by the or by the to specify which endpoint in the client configuration is being targeted and must be loaded when a channel is created to service. A wildcard endpoint configuration name "\*" is available and indicates to the method that it should load any endpoint configuration in the file, provided there is precisely one available, and otherwise throws an exception. If this attribute is omitted, the corresponding endpoint is used as the default endpoint associated with the specified contract type. The default value for the `name` attribute is an empty string which is matched like any other name. - - Every endpoint must have an address associated with it to locate and identify the endpoint. The `address` attribute can be used to specify the URL that provides the location of the endpoint. But the address for a service endpoint can also be specified in code by creating a Uniform Resource Identifier (URI) and is added to the using one of the methods. For more information, see [Addresses](endpoint-addresses.md). As the introduction indicates, the [\](../../configure-apps/file-schema/wcf/headers.md) and [\](../../configure-apps/file-schema/wcf/identity.md) elements are part of the and are also discussed in the [Addresses](endpoint-addresses.md) topic. - - The `binding` attribute indicates the type of binding the endpoint expects to use when connecting to a service. The type must have a registered configuration section if it is to be referenced. In the previous example, this is the [\](../../configure-apps/file-schema/wcf/wshttpbinding.md) section, which indicates that the endpoint uses a . But there may be more than one binding of a given type that the endpoint can use. Each of these has its own [\](../../configure-apps/file-schema/wcf/bindings.md) element within the (binding) type element. The `bindingconfiguration` attribute is used to distinguish between bindings of the same type. Its value is matched with the `name` attribute of the [\](../../configure-apps/file-schema/wcf/bindings.md) element. For more information about how to configure a client binding using configuration, see [How to: Specify a Client Binding in Configuration](../how-to-specify-a-client-binding-in-configuration.md). - - The `behaviorConfiguration` attribute is used to specify which [\](../../configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) of the [\](../../configure-apps/file-schema/wcf/endpointbehaviors.md) the endpoint should use. Its value is matched with the `name` attribute of the [\](../../configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element. For an example of using configuration to specify client behaviors, see [Configuring Client Behaviors](../configuring-client-behaviors.md). - - The `contract` attribute specifies which contract the endpoint is exposing. This value maps to the of the . The default value is the full type name of the class that implements the service. - -### Configuring Metadata - - The [\](../../configure-apps/file-schema/wcf/metadata.md) element is used to specify settings used to register metadata import extensions. For more information about extending the metadata system, see [Extending the Metadata System](../extending/extending-the-metadata-system.md). - + + + + + + + + + + +``` + + The optional `name` attribute uniquely identifies an endpoint for a given contract. It is used by the or by the to specify which endpoint in the client configuration is being targeted and must be loaded when a channel is created to service. A wildcard endpoint configuration name "\*" is available and indicates to the method that it should load any endpoint configuration in the file, provided there is precisely one available, and otherwise throws an exception. If this attribute is omitted, the corresponding endpoint is used as the default endpoint associated with the specified contract type. The default value for the `name` attribute is an empty string which is matched like any other name. + + Every endpoint must have an address associated with it to locate and identify the endpoint. The `address` attribute can be used to specify the URL that provides the location of the endpoint. But the address for a service endpoint can also be specified in code by creating a Uniform Resource Identifier (URI) and is added to the using one of the methods. For more information, see [Addresses](endpoint-addresses.md). As the introduction indicates, the [\](../../configure-apps/file-schema/wcf/headers.md) and [\](../../configure-apps/file-schema/wcf/identity.md) elements are part of the and are also discussed in the [Addresses](endpoint-addresses.md) topic. + + The `binding` attribute indicates the type of binding the endpoint expects to use when connecting to a service. The type must have a registered configuration section if it is to be referenced. In the previous example, this is the [\](../../configure-apps/file-schema/wcf/wshttpbinding.md) section, which indicates that the endpoint uses a . But there may be more than one binding of a given type that the endpoint can use. Each of these has its own [\](../../configure-apps/file-schema/wcf/bindings.md) element within the (binding) type element. The `bindingconfiguration` attribute is used to distinguish between bindings of the same type. Its value is matched with the `name` attribute of the [\](../../configure-apps/file-schema/wcf/bindings.md) element. For more information about how to configure a client binding using configuration, see [How to: Specify a Client Binding in Configuration](../how-to-specify-a-client-binding-in-configuration.md). + + The `behaviorConfiguration` attribute is used to specify which [\](../../configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) of the [\](../../configure-apps/file-schema/wcf/endpointbehaviors.md) the endpoint should use. Its value is matched with the `name` attribute of the [\](../../configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element. For an example of using configuration to specify client behaviors, see [Configuring Client Behaviors](../configuring-client-behaviors.md). + + The `contract` attribute specifies which contract the endpoint is exposing. This value maps to the of the . The default value is the full type name of the class that implements the service. + +### Configuring Metadata + + The [\](../../configure-apps/file-schema/wcf/metadata.md) element is used to specify settings used to register metadata import extensions. For more information about extending the metadata system, see [Extending the Metadata System](../extending/extending-the-metadata-system.md). + ## See also - [Endpoints: Addresses, Bindings, and Contracts](endpoints-addresses-bindings-and-contracts.md) diff --git a/docs/framework/wcf/feature-details/collection-types-in-data-contracts.md b/docs/framework/wcf/feature-details/collection-types-in-data-contracts.md index 02a99abb31e1a..4390ff54a5726 100644 --- a/docs/framework/wcf/feature-details/collection-types-in-data-contracts.md +++ b/docs/framework/wcf/feature-details/collection-types-in-data-contracts.md @@ -13,15 +13,15 @@ ms.assetid: 9b45b28e-0a82-4ea3-8c33-ec0094aff9d5 --- # Collection Types in Data Contracts -A *collection* is a list of items of a certain type. In the .NET Framework, such lists can be represented using arrays or a variety of other types (Generic List, Generic , , or ). For example, a collection may hold a list of Addresses for a given Customer. These collections are called *list collections*, regardless of their actual type. +A *collection* is a list of items of a certain type. In the .NET Framework, such lists can be represented using arrays or a variety of other types (Generic List, Generic , , or ). For example, a collection may hold a list of Addresses for a given Customer. These collections are called *list collections*, regardless of their actual type. A special form of collection exists that represents an association between one item (the "key") and another (the "value"). In the .NET Framework, these are represented by types such as and the generic dictionary. For example, an association collection may map a city ("key") to its population ("value"). These collections are called *dictionary collections*, regardless of their actual type. Collections receive special treatment in the data contract model. -Types that implement the interface, including arrays and generic collections, are recognized as collections. Of those, types that implement the or Generic interfaces are dictionary collections; all others are list collections. +Types that implement the interface, including arrays and generic collections, are recognized as collections. Of those, types that implement the or Generic interfaces are dictionary collections; all others are list collections. -Additional requirements on collection types, such as having a method called `Add` and a parameterless constructor, are discussed in detail in the following sections. This ensures that collection types can be both serialized and deserialized. This means that some collections are not directly supported, such as the Generic (because it has no parameterless constructor). However, for information about circumventing these restrictions, see the section "Using Collection Interface Types and Read-Only Collections" later in this topic. +Additional requirements on collection types, such as having a method called `Add` and a parameterless constructor, are discussed in detail in the following sections. This ensures that collection types can be both serialized and deserialized. This means that some collections are not directly supported, such as the Generic (because it has no parameterless constructor). However, for information about circumventing these restrictions, see the section "Using Collection Interface Types and Read-Only Collections" later in this topic. The types contained in collections must be data contract types, or be otherwise serializable. For more information, see [Types Supported by the Data Contract Serializer](types-supported-by-the-data-contract-serializer.md). @@ -60,16 +60,16 @@ Similar to list collections, all dictionary collections that have the same key a Only the data contract type matters as far as collection equivalence is concerned, not .NET types. That is, a collection of Type1 is considered equivalent to a collection of Type2 if Type1 and Type2 have equivalent data contracts. -Non-generic collections are considered to have the same data contract as generic collections of type `Object`. (For example, the data contracts for and Generic of `Object` are the same.) +Non-generic collections are considered to have the same data contract as generic collections of type `Object`. (For example, the data contracts for and Generic of `Object` are the same.) ## Using Collection Interface Types and Read-Only Collections -Collection interface types (, , generic , or interfaces derived from these interfaces) are also considered as having collection data contracts, equivalent to collection data contracts for actual collection types. Thus, it is possible to declare the type being serialized as a collection interface type and the results are the same as if an actual collection type had been used. For example, the following data contracts are equivalent. +Collection interface types (, , generic , or interfaces derived from these interfaces) are also considered as having collection data contracts, equivalent to collection data contracts for actual collection types. Thus, it is possible to declare the type being serialized as a collection interface type and the results are the same as if an actual collection type had been used. For example, the following data contracts are equivalent. [!code-csharp[c_collection_types_in_data_contracts#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_collection_types_in_data_contracts/cs/program.cs#1)] [!code-vb[c_collection_types_in_data_contracts#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_collection_types_in_data_contracts/vb/program.vb#1)] -During serialization, when the declared type is an interface, the actual instance type used can be any type that implements that interface. Restrictions discussed previously (having a parameterless constructor and an `Add` method) do not apply. For example, you can set addresses in Customer2 to an instance of Generic of Address, even though you cannot directly declare a data member of type Generic . +During serialization, when the declared type is an interface, the actual instance type used can be any type that implements that interface. Restrictions discussed previously (having a parameterless constructor and an `Add` method) do not apply. For example, you can set addresses in Customer2 to an instance of Generic of Address, even though you cannot directly declare a data member of type Generic . During deserialization, when the declared type is an interface, the serialization engine chooses a type that implements the declared interface, and the type is instantiated. The known types mechanism (described in [Data Contract Known Types](data-contract-known-types.md)) has no effect here; the choice of type is built into WCF. @@ -147,7 +147,7 @@ List collections contain repeating entries. Normally, each repeating entry is re In the `CustomerList` examples, the collections contained strings. The data contract name for the string primitive type is "string", so the repeating element was "\". -However, using the property on the attribute, this repeating element name can be customized. For an example, see the following type. +However, using the property on the attribute, this repeating element name can be customized. For an example, see the following type. [!code-csharp[c_collection_types_in_data_contracts#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_collection_types_in_data_contracts/cs/program.cs#4)] [!code-vb[c_collection_types_in_data_contracts#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_collection_types_in_data_contracts/vb/program.vb#4)] @@ -167,9 +167,9 @@ The namespace of the repeating element is always the same as the namespace of th ### Customizing Dictionary Collections -Dictionary collections are essentially lists of entries, where each entry has a key followed by a value. Just as with regular lists, you can change the element name that corresponds to the repeating element by using the property. +Dictionary collections are essentially lists of entries, where each entry has a key followed by a value. Just as with regular lists, you can change the element name that corresponds to the repeating element by using the property. -Additionally, you can change the element names that represent the key and the value by using the and properties. The namespaces for these elements are the same as the namespace of the collection data contract. +Additionally, you can change the element names that represent the key and the value by using the and properties. The namespaces for these elements are the same as the namespace of the collection data contract. For an example, see the following type. @@ -225,13 +225,13 @@ Customized collection types, collection interfaces, and arrays are still treated ## Collections and Schema -All equivalent collections have the same representation in XML Schema definition language (XSD) schema. Because of this, you normally do not get the same collection type in the generated client code as the one on the server. For example, the server may use a data contract with a Generic of Integer data member, but in the generated client code the same data member may become an array of integers. +All equivalent collections have the same representation in XML Schema definition language (XSD) schema. Because of this, you normally do not get the same collection type in the generated client code as the one on the server. For example, the server may use a data contract with a Generic of Integer data member, but in the generated client code the same data member may become an array of integers. Dictionary collections are marked with a WCF-specific schema annotation that indicate that they are dictionaries; otherwise, they are indistinguishable from simple lists that contain entries with a key and a value. For an exact description of how collections are represented in data contract schema, see [Data Contract Schema Reference](data-contract-schema-reference.md). By default, types are not generated for non-customized collections in imported code. Data members of list collection types are imported as arrays, and data members of dictionary collection types are imported as Generic Dictionary. -However, for customized collections, separate types are generated, marked with the attribute. (A customized collection type in the schema is one that does not use the default namespace, name, repeating element name, or key/value element names.) These types are empty types that derive from Generic for list types and Generic Dictionary for dictionary types. +However, for customized collections, separate types are generated, marked with the attribute. (A customized collection type in the schema is one that does not use the default namespace, name, repeating element name, or key/value element names.) These types are empty types that derive from Generic for list types and Generic Dictionary for dictionary types. For example, you may have the following types on the server. @@ -243,16 +243,16 @@ When the schema is exported and imported back again, the generated client code i [!code-csharp[c_collection_types_in_data_contracts#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_collection_types_in_data_contracts/cs/program.cs#8)] [!code-vb[c_collection_types_in_data_contracts#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_collection_types_in_data_contracts/vb/program.vb#8)] -You may want to use different types in generated code than the default ones. For example, you may want to use Generic instead of regular arrays for your data members to make it easier to bind them to user interface components. +You may want to use different types in generated code than the default ones. For example, you may want to use Generic instead of regular arrays for your data members to make it easier to bind them to user interface components. -To choose collection types to generate, pass a list of collection types you want to use into the property of the object when importing schema. These types are called *referenced collection types*. +To choose collection types to generate, pass a list of collection types you want to use into the property of the object when importing schema. These types are called *referenced collection types*. When generic types are being referenced, they must either be fully-open generics or fully-closed generics. > [!NOTE] > When using the Svcutil.exe tool, this reference can be accomplished by using the **/collectionType** command-line switch (short form: **/ct**). Keep in mind that you must also specify the assembly for the referenced collection types using the **/reference** switch (short form: **/r**). If the type is generic, it must be followed by a back quote and the number of generic parameters. The back quote (\`) is not to be confused with the single quote (‘) character. You can specify multiple referenced collection types by using the **/collectionType** switch more than once. -For example, to cause all lists to be imported as Generic . +For example, to cause all lists to be imported as Generic . ```console svcutil.exe MyService.wsdl MyServiceSchema.xsd /r:C:\full_path_to_system_dll\System.dll /ct:System.Collections.Generic.List`1 @@ -260,14 +260,14 @@ svcutil.exe MyService.wsdl MyServiceSchema.xsd /r:C:\full_path_to_system_dll\Sys When importing any collection, this list of referenced collection types is scanned, and the best-matching collection is used if one is found, either as a data member type (for non-customized collections) or as a base type to derive from (for customized collections). Dictionaries are only matched against dictionaries, while lists are matched against lists. -For example, if you add the Generic and to the list of referenced types, the generated client code for the preceding example is similar to the following. +For example, if you add the Generic and to the list of referenced types, the generated client code for the preceding example is similar to the following. [!code-csharp[c_collection_types_in_data_contracts#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_collection_types_in_data_contracts/cs/program.cs#9)] [!code-vb[c_collection_types_in_data_contracts#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_collection_types_in_data_contracts/vb/program.vb#9)] You can specify collection interface types as part of your referenced collection types, but you cannot specify invalid collection types (such as ones with no `Add` method or public constructor). -A closed generic is considered to be the best match. (Non-generic types are considered equivalent to closed generics of `Object`). For example, if the types Generic of , Generic (open generic), and are the referenced collection types, the following is generated. +A closed generic is considered to be the best match. (Non-generic types are considered equivalent to closed generics of `Object`). For example, if the types Generic of , Generic (open generic), and are the referenced collection types, the following is generated. [!code-csharp[c_collection_types_in_data_contracts#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_collection_types_in_data_contracts/cs/program.cs#10)] [!code-vb[c_collection_types_in_data_contracts#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_collection_types_in_data_contracts/vb/program.vb#10)] @@ -283,7 +283,7 @@ For list collections, only the cases in the following table are supported. If a type implements more than one list collection interface, the following restrictions apply: -- If the type implements Generic (or its derived interfaces) multiple times for different types, the type is not considered a valid referenced collection type and is ignored. This is true even if some implementations are invalid or use open generics. For example, a type that implements Generic of `int` and Generic of T would never be used as a referenced collection of `int` or any other type, regardless of whether the type has an `Add` method accepting `int` or an `Add` method accepting a parameter of type T, or both. +- If the type implements Generic (or its derived interfaces) multiple times for different types, the type is not considered a valid referenced collection type and is ignored. This is true even if some implementations are invalid or use open generics. For example, a type that implements Generic of `int` and Generic of T would never be used as a referenced collection of `int` or any other type, regardless of whether the type has an `Add` method accepting `int` or an `Add` method accepting a parameter of type T, or both. - If the type implements a generic collection interface as well as , the type is never used as a referenced collection type unless the generic collection interface is a closed generic of type . @@ -292,16 +292,16 @@ For dictionary collections, only the cases in the following table are supported. |Referenced type|Interface implemented by referenced type|Example|Type treated as| |---------------------|----------------------------------------------|-------------|---------------------| |Non-generic or closed generic (any number of parameters)||`MyType : IDictionary`

or

`MyType : IDictionary` where T=`int`|Closed generic `IDictionary`| -|Closed generic (any number of parameters)|, closed|`MyType : IDictionary` where T=`int`|Closed generic (for example, `IDictionary`)| -|Closed generic (any number of parameters)|Generic , one of either key or value is closed, the other is open and uses one of type’s parameters|`MyType : IDictionary` where T=`int`, U=`float`,V=`bool`

or

`MyType : IDictionary` where Z=`string`|Closed generic (For example, `IDictionary`)| -|Closed generic (any number of parameters)|Generic , both key and value are open and each uses one of the type’s parameters|`MyType : IDictionary` where T=`int`, U=`bool`, V=`string`|Closed generic (for example, `IDictionary`)| -|Open generic (two parameters)|Generic , open, uses both of the type’s generic parameters in the order they appear|`MyType : IDictionary`, K and V both open|Open generic (for example, `IDictionary`)| +|Closed generic (any number of parameters)|, closed|`MyType : IDictionary` where T=`int`|Closed generic (for example, `IDictionary`)| +|Closed generic (any number of parameters)|Generic , one of either key or value is closed, the other is open and uses one of type’s parameters|`MyType : IDictionary` where T=`int`, U=`float`,V=`bool`

or

`MyType : IDictionary` where Z=`string`|Closed generic (For example, `IDictionary`)| +|Closed generic (any number of parameters)|Generic , both key and value are open and each uses one of the type’s parameters|`MyType : IDictionary` where T=`int`, U=`bool`, V=`string`|Closed generic (for example, `IDictionary`)| +|Open generic (two parameters)|Generic , open, uses both of the type’s generic parameters in the order they appear|`MyType : IDictionary`, K and V both open|Open generic (for example, `IDictionary`)| -If the type implements both and Generic , only Generic is considered. +If the type implements both and Generic , only Generic is considered. Referencing partial generic types is not supported. -Duplicates are not allowed, for example, you cannot add both the Generic of `Integer` and the Generic Collection of `Integer` to , because this makes it impossible to determine which one to use when a list of integers is found in the schema. Duplicates are detected only if there is a type in the schema that exposes the duplicates problem. For example, if the schema being imported does not contain lists of integers, it is allowed to have both the Generic of `Integer` and the Generic Collection of `Integer` in the , but neither has any effect. +Duplicates are not allowed, for example, you cannot add both the Generic of `Integer` and the Generic Collection of `Integer` to , because this makes it impossible to determine which one to use when a list of integers is found in the schema. Duplicates are detected only if there is a type in the schema that exposes the duplicates problem. For example, if the schema being imported does not contain lists of integers, it is allowed to have both the Generic of `Integer` and the Generic Collection of `Integer` in the , but neither has any effect. ## Advanced Collection Rules @@ -327,19 +327,19 @@ The following is a list of collection rules for serialization: |Collection type implements|Method(s) called on serialization|Method(s) called on deserialization| |--------------------------------|-----------------------------------------|-------------------------------------------| -|Generic |`get_Keys`, `get_Values`|Generic Add| +|Generic |`get_Keys`, `get_Values`|Generic Add| ||`get_Keys`, `get_Values`|`Add`| -|Generic |Generic indexer|Generic Add| -|Generic |Enumerator|Generic Add| +|Generic |Generic indexer|Generic Add| +|Generic |Enumerator|Generic Add| || Indexer|`Add`| -|Generic |`GetEnumerator`|A non-static method called `Add` that takes one parameter of the appropriate type (the type of the generic parameter or one of its base types). Such a method must exist for the serializer to treat a collection type as a collection during both serialization and deserialization.| +|Generic |`GetEnumerator`|A non-static method called `Add` that takes one parameter of the appropriate type (the type of the generic parameter or one of its base types). Such a method must exist for the serializer to treat a collection type as a collection during both serialization and deserialization.| | (and thus , which derives from it)|`GetEnumerator`|A non-static method called `Add` that takes one parameter of type `Object`. Such a method must exist for the serializer to treat a collection type as a collection during both serialization and deserialization.| -The preceding table lists collection interfaces in descending order of precedence. This means, for example, that if a type implements both and Generic , the collection is serialized and deserialized according to the rules: +The preceding table lists collection interfaces in descending order of precedence. This means, for example, that if a type implements both and Generic , the collection is serialized and deserialized according to the rules: - At deserialization, all collections are deserialized by first creating an instance of the type by calling the parameterless constructor, which must be present for the serializer to treat a collection type as a collection during both serialization and deserialization. -- If the same generic collection interface is implemented more than once (for example, if a type implements both Generic of `Integer` and Generic of ) and no higher-precedence interface is found, the collection is not treated as a valid collection. +- If the same generic collection interface is implemented more than once (for example, if a type implements both Generic of `Integer` and Generic of ) and no higher-precedence interface is found, the collection is not treated as a valid collection. - Collection types can have the attribute applied to them and can implement the interface. Both of these are ignored. However, if the type does not fully meet collection type requirements (for example, the `Add` method is missing), the type is not considered a collection type, and thus the attribute and the interface are used to determine whether the type can be serialized. @@ -371,7 +371,7 @@ The following uses of the attribute to a non-collection type. -- Attempting to set or on a attribute applied to a non-dictionary type. +- Attempting to set or on a attribute applied to a non-dictionary type. ### Polymorphism Rules diff --git a/docs/framework/wcf/feature-details/comparing-aspnet-web-services-to-wcf-based-on-development.md b/docs/framework/wcf/feature-details/comparing-aspnet-web-services-to-wcf-based-on-development.md index 5a2019891859c..7ac6b4e002539 100644 --- a/docs/framework/wcf/feature-details/comparing-aspnet-web-services-to-wcf-based-on-development.md +++ b/docs/framework/wcf/feature-details/comparing-aspnet-web-services-to-wcf-based-on-development.md @@ -314,7 +314,7 @@ public class DerivativesCalculatorServiceType: IDerivativesCalculator Some behaviors, like , are attributes. Others, the ones with properties that administrators would want to set, can be modified in the configuration of an application. -In programming service types, frequent use is made of the class. Its static property provides access to information about the context in which an operation is running. is similar to both the and classes. +In programming service types, frequent use is made of the class. Its static property provides access to information about the context in which an operation is running. is similar to both the and classes. ## Hosting @@ -570,7 +570,7 @@ In ASP.NET Web services, unhandled exceptions are returned to clients as SOAP fa In WCF services, unhandled exceptions are not returned to clients as SOAP faults to prevent sensitive information being inadvertently exposed through the exceptions. A configuration setting is provided to have unhandled exceptions returned to clients for the purpose of debugging. -To return SOAP faults to clients, you can throw instances of the generic type, , using the data contract type as the generic type. You can also add attributes to operations to specify the faults that an operation might yield. +To return SOAP faults to clients, you can throw instances of the generic type, , using the data contract type as the generic type. You can also add attributes to operations to specify the faults that an operation might yield. ```csharp [DataContract] @@ -626,7 +626,7 @@ In that case, the class can be programmed to use the is actually stored. It may be stored in cookies, in a database, in the memory of the current server, or in the memory of a designated server. The choice is made in the service’s configuration file. -The WCF provides extensible objects for state management. Extensible objects are objects that implement . The most important extensible objects are and . `ServiceHostBase` allows you to maintain state that all of the instances of all of the service types on the same host can access, while `InstanceContext` allows you to maintain state that can be accessed by any code running within the same instance of a service type. +The WCF provides extensible objects for state management. Extensible objects are objects that implement . The most important extensible objects are and . `ServiceHostBase` allows you to maintain state that all of the instances of all of the service types on the same host can access, while `InstanceContext` allows you to maintain state that can be accessed by any code running within the same instance of a service type. Here, the service type, `TradingSystem`, has a that specifies that all calls from the same WCF client instance are routed to the same instance of the service type. diff --git a/docs/framework/wcf/feature-details/comparing-transactions-in-com-and-servicemodel.md b/docs/framework/wcf/feature-details/comparing-transactions-in-com-and-servicemodel.md index 1704d3ac5b994..2f8a3731c5358 100644 --- a/docs/framework/wcf/feature-details/comparing-transactions-in-com-and-servicemodel.md +++ b/docs/framework/wcf/feature-details/comparing-transactions-in-com-and-servicemodel.md @@ -6,16 +6,16 @@ ms.assetid: e493bcdd-b91a-4486-853f-83dbcd1931b7 --- # Comparing Transactions in COM+ and ServiceModel -This topic discusses how to simulate the behavior of a transactional COM+ service using the Windows Communication Foundation (WCF) attributes the namespace provides. - -## Emulating COM+ Using ServiceModel Attributes +This topic discusses how to simulate the behavior of a transactional COM+ service using the Windows Communication Foundation (WCF) attributes the namespace provides. - The following table compares the enumeration used to create an `EnterpriseServices` transaction and how they correlate to the WCF attributes the namespace provides. - -|COM+ attribute|WCF attributes| -|---------------------|------------------------------------------------------------------------| -|RequiresNew| is set to .

is `true`.

The `TransactionFlow` attribute in the binding element is `false`.| -|Required| is set to .

is `true`.

The `TransactionFlow` attribute in the binding element is `true`.| -|Supported|There is no direct equivalent. In general, you should adopt the behavior specified for `Required` instead.| -|NotSupported| is `false`.

The `TransactionFlow` attribute in the binding element is `false`.| +## Emulating COM+ Using ServiceModel Attributes + + The following table compares the enumeration used to create an `EnterpriseServices` transaction and how they correlate to the WCF attributes the namespace provides. + +|COM+ attribute|WCF attributes| +|---------------------|------------------------------------------------------------------------| +|RequiresNew| is set to .

is `true`.

The `TransactionFlow` attribute in the binding element is `false`.| +|Required| is set to .

is `true`.

The `TransactionFlow` attribute in the binding element is `true`.| +|Supported|There is no direct equivalent. In general, you should adopt the behavior specified for `Required` instead.| +|NotSupported| is `false`.

The `TransactionFlow` attribute in the binding element is `false`.| |Disabled|There is no direct equivalent. In general, you should adopt the behavior specified for `NotSupported` instead.| diff --git a/docs/framework/wcf/feature-details/config-wcf-service-with-aspnet-web-service.md b/docs/framework/wcf/feature-details/config-wcf-service-with-aspnet-web-service.md index aa7eca88486d5..43d5d331c7f4f 100644 --- a/docs/framework/wcf/feature-details/config-wcf-service-with-aspnet-web-service.md +++ b/docs/framework/wcf/feature-details/config-wcf-service-with-aspnet-web-service.md @@ -3,46 +3,46 @@ description: "Learn more about: How to: Configure WCF Service to Interoperate wi title: "How to: Configure WCF Service to Interoperate with ASP.NET Web Service Clients" ms.date: "03/30/2017" ms.topic: how-to -dev_langs: +dev_langs: - "csharp" - "vb" --- # How to: Configure WCF Service to Interoperate with ASP.NET Web Service Clients -To configure a Windows Communication Foundation (WCF) service endpoint to be interoperable with ASP.NET Web service clients, use the type as the binding type for your service endpoint. - - You can optionally enable support for HTTPS and transport-level client authentication on the binding. ASP.NET Web service clients do not support MTOM message encoding, so the property should be left as its default value, which is . ASP.NET Web Service clients do not support WS-Security, so the should be set to . - - To make the metadata for a WCF service available to ASP.NET Web service proxy generation tools (that is, [Web Services Description Language Tool (Wsdl.exe)](/previous-versions/dotnet/netframework-4.0/7h3ystb6(v=vs.100)), [Web Services Discovery Tool (Disco.exe)](/previous-versions/dotnet/netframework-4.0/cy2a3ybs(v=vs.100)), and the **Add Web Reference** feature in Visual Studio), you should expose an HTTP/GET metadata endpoint. - -## Add an endpoint in code - -1. Create a new instance - -2. Optionally enable transport security for this service endpoint binding by setting the security mode for the binding to . For details, see [Transport Security](transport-security.md). - -3. Add a new application endpoint to your service host using the binding instance that you just created. For details about how to add a service endpoint in code, see the [How to: Create a Service Endpoint in Code](how-to-create-a-service-endpoint-in-code.md). - -4. Enable an HTTP/GET metadata endpoint for your service. For details see [How to: Publish Metadata for a Service Using Code](how-to-publish-metadata-for-a-service-using-code.md). - -## Add an endpoint in a configuration file - -1. Create a new binding configuration. For details, see the [How to: Specify a Service Binding in Configuration](../how-to-specify-a-service-binding-in-configuration.md). - -2. Optionally enable transport security for this service endpoint binding configuration by setting the security mode for the binding to . For details, see [Transport Security](transport-security.md). - -3. Configure a new application endpoint for your service using the binding configuration that you just created. For details about how to add a service endpoint in a configuration file, see the [How to: Create a Service Endpoint in Configuration](how-to-create-a-service-endpoint-in-configuration.md). - -4. Enable an HTTP/GET metadata endpoint for your service. For details see the [How to: Publish Metadata for a Service Using a Configuration File](how-to-publish-metadata-for-a-service-using-a-configuration-file.md). - -## Example - - The following example code demonstrates how to add a WCF endpoint that is compatible with ASP.NET Web service clients in code and alternatively in configuration files. - +To configure a Windows Communication Foundation (WCF) service endpoint to be interoperable with ASP.NET Web service clients, use the type as the binding type for your service endpoint. + + You can optionally enable support for HTTPS and transport-level client authentication on the binding. ASP.NET Web service clients do not support MTOM message encoding, so the property should be left as its default value, which is . ASP.NET Web Service clients do not support WS-Security, so the should be set to . + + To make the metadata for a WCF service available to ASP.NET Web service proxy generation tools (that is, [Web Services Description Language Tool (Wsdl.exe)](/previous-versions/dotnet/netframework-4.0/7h3ystb6(v=vs.100)), [Web Services Discovery Tool (Disco.exe)](/previous-versions/dotnet/netframework-4.0/cy2a3ybs(v=vs.100)), and the **Add Web Reference** feature in Visual Studio), you should expose an HTTP/GET metadata endpoint. + +## Add an endpoint in code + +1. Create a new instance + +2. Optionally enable transport security for this service endpoint binding by setting the security mode for the binding to . For details, see [Transport Security](transport-security.md). + +3. Add a new application endpoint to your service host using the binding instance that you just created. For details about how to add a service endpoint in code, see the [How to: Create a Service Endpoint in Code](how-to-create-a-service-endpoint-in-code.md). + +4. Enable an HTTP/GET metadata endpoint for your service. For details see [How to: Publish Metadata for a Service Using Code](how-to-publish-metadata-for-a-service-using-code.md). + +## Add an endpoint in a configuration file + +1. Create a new binding configuration. For details, see the [How to: Specify a Service Binding in Configuration](../how-to-specify-a-service-binding-in-configuration.md). + +2. Optionally enable transport security for this service endpoint binding configuration by setting the security mode for the binding to . For details, see [Transport Security](transport-security.md). + +3. Configure a new application endpoint for your service using the binding configuration that you just created. For details about how to add a service endpoint in a configuration file, see the [How to: Create a Service Endpoint in Configuration](how-to-create-a-service-endpoint-in-configuration.md). + +4. Enable an HTTP/GET metadata endpoint for your service. For details see the [How to: Publish Metadata for a Service Using a Configuration File](how-to-publish-metadata-for-a-service-using-a-configuration-file.md). + +## Example + + The following example code demonstrates how to add a WCF endpoint that is compatible with ASP.NET Web service clients in code and alternatively in configuration files. + [!code-csharp[C_HowTo-WCFServiceAndASMXClient#0](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howto-wcfserviceandasmxclient/cs/program.cs#0)] [!code-vb[C_HowTo-WCFServiceAndASMXClient#0](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto-wcfserviceandasmxclient/vb/program.vb#0)] [!code-xml[C_HowTo-WCFServiceAndASMXClient#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howto-wcfserviceandasmxclient/common/app.config#1)] - + ## See also - [How to: Create a Service Endpoint in Code](how-to-create-a-service-endpoint-in-code.md) diff --git a/docs/framework/wcf/feature-details/configuration-based-activation-in-iis-and-was.md b/docs/framework/wcf/feature-details/configuration-based-activation-in-iis-and-was.md index d6a7a028c03b0..989f5472a083f 100644 --- a/docs/framework/wcf/feature-details/configuration-based-activation-in-iis-and-was.md +++ b/docs/framework/wcf/feature-details/configuration-based-activation-in-iis-and-was.md @@ -37,7 +37,7 @@ Configuration-based activation takes the metadata that used to be placed in the ## See also -- +- - [Hosting Services](../hosting-services.md) - [Hosting Workflow Services Overview](hosting-workflow-services-overview.md) - [\](../../configure-apps/file-schema/wcf/servicehostingenvironment.md) diff --git a/docs/framework/wcf/feature-details/configuring-discovery-in-a-configuration-file.md b/docs/framework/wcf/feature-details/configuring-discovery-in-a-configuration-file.md index a123061c7e323..5c9709478fcb6 100644 --- a/docs/framework/wcf/feature-details/configuring-discovery-in-a-configuration-file.md +++ b/docs/framework/wcf/feature-details/configuring-discovery-in-a-configuration-file.md @@ -142,7 +142,7 @@ There are four major groups of configuration settings used in discovery. This to ## Binding Element Configuration - Binding element configuration is most interesting on the client side. You can use configuration to specify the find criteria used to discover services from a WCF client application. The following example creates a custom binding with the channel and specifies find criteria that includes a type and scope. In addition it specifies values for the and properties. + Binding element configuration is most interesting on the client side. You can use configuration to specify the find criteria used to discover services from a WCF client application. The following example creates a custom binding with the channel and specifies find criteria that includes a type and scope. In addition it specifies values for the and properties. ```xml diff --git a/docs/framework/wcf/feature-details/configuring-serialization-in-a-workflow-service.md b/docs/framework/wcf/feature-details/configuring-serialization-in-a-workflow-service.md index 024e2cf7fa630..d5217c5b8a5fb 100644 --- a/docs/framework/wcf/feature-details/configuring-serialization-in-a-workflow-service.md +++ b/docs/framework/wcf/feature-details/configuring-serialization-in-a-workflow-service.md @@ -31,7 +31,7 @@ Receive approveExpense = new Receive ![Screenshot of the Type Collections Editor.](./media/configuring-serialization-in-a-workflow-service/type-collection-editor.gif) - Click the **Add new type** link and use the drop down to select or search for a type to add to the known types collection. To specify known types in code use the property as shown in the following example. + Click the **Add new type** link and use the drop down to select or search for a type to add to the known types collection. To specify known types in code use the property as shown in the following example. ```csharp Receive approveExpense = new Receive diff --git a/docs/framework/wcf/feature-details/configuring-system-provided-bindings.md b/docs/framework/wcf/feature-details/configuring-system-provided-bindings.md index 7979d75afdc2f..d3c8773e4a855 100644 --- a/docs/framework/wcf/feature-details/configuring-system-provided-bindings.md +++ b/docs/framework/wcf/feature-details/configuring-system-provided-bindings.md @@ -2,7 +2,7 @@ description: "Learn more about: Configuring System-Provided Bindings" title: "Configuring System-Provided Bindings" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "Windows Communication Foundation [WCF], system-provided bindings" - "WCF [WCF], system-provided bindings" - "bindings [WCF], system-provided" @@ -10,71 +10,71 @@ ms.topic: how-to --- # Configuring System-Provided Bindings -Bindings specify the communication mechanism to use when talking to an endpoint and indicate how to connect to an endpoint. Bindings consist of elements that define how the Windows Communication Foundation (WCF) channels are layered up to provide the required communication features. A binding contains three types of elements: - -- Protocol channel binding elements, which determine the security, reliability, context flow settings, or user-defined protocols to use with messages that are sent to the endpoint. - -- Transport channel binding elements, which determine the underlying transport protocol to use when sending messages to the endpoint, for example, TCP or HTTP. - -- Message encoding binding elements, which determine the wire encoding to use for messages that are sent to the endpoint, for example, text/XML, binary, or Message Transmission Optimization Mechanism (MTOM). - - This topic presents all of the system-provided Windows Communication Foundation (WCF) bindings. If none of these meets the exact requirements for your application, you can create a binding using the class. For more information about creating custom bindings, see [Custom Bindings](../extending/custom-bindings.md). - +Bindings specify the communication mechanism to use when talking to an endpoint and indicate how to connect to an endpoint. Bindings consist of elements that define how the Windows Communication Foundation (WCF) channels are layered up to provide the required communication features. A binding contains three types of elements: + +- Protocol channel binding elements, which determine the security, reliability, context flow settings, or user-defined protocols to use with messages that are sent to the endpoint. + +- Transport channel binding elements, which determine the underlying transport protocol to use when sending messages to the endpoint, for example, TCP or HTTP. + +- Message encoding binding elements, which determine the wire encoding to use for messages that are sent to the endpoint, for example, text/XML, binary, or Message Transmission Optimization Mechanism (MTOM). + + This topic presents all of the system-provided Windows Communication Foundation (WCF) bindings. If none of these meets the exact requirements for your application, you can create a binding using the class. For more information about creating custom bindings, see [Custom Bindings](../extending/custom-bindings.md). + > [!IMPORTANT] -> Select a binding that has security enabled. By default, all bindings, except the binding, have security enabled. If you do not select a secure binding, or if you disable security, be sure your network exchanges are protected in some other manner, such as being in a secured data center or on an isolated network. - +> Select a binding that has security enabled. By default, all bindings, except the binding, have security enabled. If you do not select a secure binding, or if you disable security, be sure your network exchanges are protected in some other manner, such as being in a secured data center or on an isolated network. + > [!IMPORTANT] -> Do not use duplex contracts with bindings that do not support security, or that have security disabled, unless the network exchange is secured by some other means. - -## System-Provided Bindings - - The following bindings are shipped with WCF. - -|Binding|Configuration Element|Description| -|-------------|---------------------------|-----------------| -||[\](../../configure-apps/file-schema/wcf/basichttpbinding.md)|A binding that is suitable for communicating with WS-Basic Profile conformant Web services, for example, ASP.NET Web services (ASMX)-based services. This binding uses HTTP as the transport and text/XML as the default message encoding.| -||[\](../../configure-apps/file-schema/wcf/wshttpbinding.md)|A secure and interoperable binding that is suitable for non-duplex service contracts.| -||[\](../../configure-apps/file-schema/wcf/ws2007httpbinding.md)|A secure and interoperable binding that provides support for the correct versions of the , , and binding elements.| -||[\](../../configure-apps/file-schema/wcf/wsdualhttpbinding.md)|A secure and interoperable binding that is suitable for duplex service contracts or communication through SOAP intermediaries.| -||[\](../../configure-apps/file-schema/wcf/wsfederationhttpbinding.md)|A secure and interoperable binding that supports the WS-Federation protocol, enabling organizations that are in a federation to efficiently authenticate and authorize users.| -||[\](../../configure-apps/file-schema/wcf/ws2007federationhttpbinding.md)|A secure and interoperable binding that derives from and supports federated security.| -||[\](../../configure-apps/file-schema/wcf/nettcpbinding.md)|A secure and optimized binding suitable for cross-machine communication between WCF applications.| -||[\](../../configure-apps/file-schema/wcf/netnamedpipebinding.md)|A secure, reliable, optimized binding that is suitable for on-machine communication between WCF applications.| -||[\](../../configure-apps/file-schema/wcf/netmsmqbinding.md)|A queued binding that is suitable for cross-machine communication between WCF applications.| -||[\](../../configure-apps/file-schema/wcf/netpeertcpbinding.md)|A binding that enables secure, multi-machine communication.| -||[\](../../configure-apps/file-schema/wcf/webhttpbinding.md)|A binding used to configure endpoints for WCF Web services that are exposed through HTTP requests instead of SOAP messages.| -||[\](../../configure-apps/file-schema/wcf/msmqintegrationbinding.md)|A binding that is suitable for cross-machine communication between a WCF application and existing Message Queuing (also known as MSMQ) applications.| - -## Binding Features - - The next table shows some of the key features each of the system-provided bindings provided. The bindings are listed in the first column and information regarding the features is described in the table. The following table provides a key for the binding abbreviations used. To select a binding, determine which column satisfies all of the row features you need. - -|Binding|Interoperability|Mode of Security (Default)|Session

(Default)|Transactions|Duplex| -|-------------|----------------------|----------------------------------|-----------------------------|------------------|------------| -||Basic Profile 1.1|(None), Transport, Message, Mixed|None, (None)|(None)|n/a| -||WS|None, Transport, (Message), Mixed|(None), Transport, Reliable Session|(None), Yes|n/a| -||WS-Security, WS-Trust, WS-SecureConversation, WS-SecurityPolicy|None, Transport, (Message), Mixed|(None), Transport, Reliable Session|(None), Yes|n/a| -||WS|None, (Message)|(Reliable Session)|(None), Yes|Yes| -||WS-Federation|None, (Message), Mixed|(None), Reliable Session|(None), Yes|No| -||WS-Federation|None, (Message), Mixed|(None), Reliable Session|(None), Yes|No| -||.NET|None, (Transport), Message,

Mixed|Reliable Session, (Transport)|(None), Yes|Yes| -||.NET|None,

(Transport)|None, (Transport)|(None), Yes|Yes| -||.NET|None, Message, (Transport), Both|(None)|(None), Yes|No| -||Peer|None, Message, (Transport), Mixed|(None)|(None)|Yes| -||.Net|None, Transport, TransportCredentialOnly|(None)|(None)|n/a| -||MSMQ|None, (Transport)|(None)|(None), Yes|n/a| - - The following table explains the features found in the previous table. - -|Feature|Description| -|-------------|-----------------| -|Interoperability Type|Names the protocol or technology with which the binding ensures interoperation.| -|Security|Specifies how the channel is secured:

- None: The SOAP message is not secured and the client is not authenticated.
- Transport: Security requirements are satisfied at the transport layer.
- Message: Security requirements are satisfied at the message layer.
- Mixed: This security mode is known as `TransportWithMessageCredentials`. It handles credentials at the message level, and integrity and confidentiality requirements are satisfied by the transport layer.
- Both: Both message level and transport level security are used. This ability is unique to the .| -|Session|Specifies whether this binding supports session contracts.| -|Transactions|Specifies whether transactions are enabled.| -|Duplex|Specifies whether duplex contracts are supported. Note this feature requires support for Sessions in the binding.| -|Streaming|Specifies whether the message streaming is supported.| - +> Do not use duplex contracts with bindings that do not support security, or that have security disabled, unless the network exchange is secured by some other means. + +## System-Provided Bindings + + The following bindings are shipped with WCF. + +|Binding|Configuration Element|Description| +|-------------|---------------------------|-----------------| +||[\](../../configure-apps/file-schema/wcf/basichttpbinding.md)|A binding that is suitable for communicating with WS-Basic Profile conformant Web services, for example, ASP.NET Web services (ASMX)-based services. This binding uses HTTP as the transport and text/XML as the default message encoding.| +||[\](../../configure-apps/file-schema/wcf/wshttpbinding.md)|A secure and interoperable binding that is suitable for non-duplex service contracts.| +||[\](../../configure-apps/file-schema/wcf/ws2007httpbinding.md)|A secure and interoperable binding that provides support for the correct versions of the , , and binding elements.| +||[\](../../configure-apps/file-schema/wcf/wsdualhttpbinding.md)|A secure and interoperable binding that is suitable for duplex service contracts or communication through SOAP intermediaries.| +||[\](../../configure-apps/file-schema/wcf/wsfederationhttpbinding.md)|A secure and interoperable binding that supports the WS-Federation protocol, enabling organizations that are in a federation to efficiently authenticate and authorize users.| +||[\](../../configure-apps/file-schema/wcf/ws2007federationhttpbinding.md)|A secure and interoperable binding that derives from and supports federated security.| +||[\](../../configure-apps/file-schema/wcf/nettcpbinding.md)|A secure and optimized binding suitable for cross-machine communication between WCF applications.| +||[\](../../configure-apps/file-schema/wcf/netnamedpipebinding.md)|A secure, reliable, optimized binding that is suitable for on-machine communication between WCF applications.| +||[\](../../configure-apps/file-schema/wcf/netmsmqbinding.md)|A queued binding that is suitable for cross-machine communication between WCF applications.| +||[\](../../configure-apps/file-schema/wcf/netpeertcpbinding.md)|A binding that enables secure, multi-machine communication.| +||[\](../../configure-apps/file-schema/wcf/webhttpbinding.md)|A binding used to configure endpoints for WCF Web services that are exposed through HTTP requests instead of SOAP messages.| +||[\](../../configure-apps/file-schema/wcf/msmqintegrationbinding.md)|A binding that is suitable for cross-machine communication between a WCF application and existing Message Queuing (also known as MSMQ) applications.| + +## Binding Features + + The next table shows some of the key features each of the system-provided bindings provided. The bindings are listed in the first column and information regarding the features is described in the table. The following table provides a key for the binding abbreviations used. To select a binding, determine which column satisfies all of the row features you need. + +|Binding|Interoperability|Mode of Security (Default)|Session

(Default)|Transactions|Duplex| +|-------------|----------------------|----------------------------------|-----------------------------|------------------|------------| +||Basic Profile 1.1|(None), Transport, Message, Mixed|None, (None)|(None)|n/a| +||WS|None, Transport, (Message), Mixed|(None), Transport, Reliable Session|(None), Yes|n/a| +||WS-Security, WS-Trust, WS-SecureConversation, WS-SecurityPolicy|None, Transport, (Message), Mixed|(None), Transport, Reliable Session|(None), Yes|n/a| +||WS|None, (Message)|(Reliable Session)|(None), Yes|Yes| +||WS-Federation|None, (Message), Mixed|(None), Reliable Session|(None), Yes|No| +||WS-Federation|None, (Message), Mixed|(None), Reliable Session|(None), Yes|No| +||.NET|None, (Transport), Message,

Mixed|Reliable Session, (Transport)|(None), Yes|Yes| +||.NET|None,

(Transport)|None, (Transport)|(None), Yes|Yes| +||.NET|None, Message, (Transport), Both|(None)|(None), Yes|No| +||Peer|None, Message, (Transport), Mixed|(None)|(None)|Yes| +||.Net|None, Transport, TransportCredentialOnly|(None)|(None)|n/a| +||MSMQ|None, (Transport)|(None)|(None), Yes|n/a| + + The following table explains the features found in the previous table. + +|Feature|Description| +|-------------|-----------------| +|Interoperability Type|Names the protocol or technology with which the binding ensures interoperation.| +|Security|Specifies how the channel is secured:

- None: The SOAP message is not secured and the client is not authenticated.
- Transport: Security requirements are satisfied at the transport layer.
- Message: Security requirements are satisfied at the message layer.
- Mixed: This security mode is known as `TransportWithMessageCredentials`. It handles credentials at the message level, and integrity and confidentiality requirements are satisfied by the transport layer.
- Both: Both message level and transport level security are used. This ability is unique to the .| +|Session|Specifies whether this binding supports session contracts.| +|Transactions|Specifies whether transactions are enabled.| +|Duplex|Specifies whether duplex contracts are supported. Note this feature requires support for Sessions in the binding.| +|Streaming|Specifies whether the message streaming is supported.| + ## See also - [Endpoint Creation Overview](../endpoint-creation-overview.md) diff --git a/docs/framework/wcf/feature-details/context-exchange-protocol.md b/docs/framework/wcf/feature-details/context-exchange-protocol.md index dc560b04cc355..0e7bc5c816262 100644 --- a/docs/framework/wcf/feature-details/context-exchange-protocol.md +++ b/docs/framework/wcf/feature-details/context-exchange-protocol.md @@ -6,65 +6,65 @@ ms.assetid: 3dfd38e0-ae52-491c-94f4-7a862b9843d4 --- # Context Exchange Protocol -This section describes the context exchange protocol introduced in Windows Communication Foundation (WCF) release .NET Framework version 3.5. This protocol allows the client channel to accept a context supplied by a service and apply it to all subsequent requests to that service sent over the same client channel instance. The implementation of the context exchange protocol can use one of the following two mechanisms to propagate the context between the server and the client: HTTP cookies or a SOAP header. - - The context exchange protocol is implemented in a custom channel layer. The channel communicates the context to and from the application layer using a property. For transmission between endpoints, the value of the context is either serialized as a SOAP header at the channel layer, or converted to or from the message properties that represent a HTTP request and response. In the latter case, it is expected that one of the underlying channel layers converts the HTTP request and response message properties to and from HTTP cookies, respectively. The choice of the mechanism used to exchange the context is done using the property on the . Valid values are `HttpCookie` or `SoapHeader`. - - On the client, an instance of a channel can operate in two modes based on the settings on the channel property, . - -## Mode 1: Channel Context Management - - This is the default mode where is set to `true`. In this mode the context channel manages the context and caches the context during its lifetime. Context can be retrieved from the channel through channel property `IContextManager` by calling the `GetContext` method. The channel can also be pre-initialized with specific context before being opened by calling the `SetContext` method on the channel property. Once the channel is initialized with context it cannot be reset. - - The following is a list of invariants in this mode: - -- Any attempt to reset the context using `SetContext` after the channel has been opened throws an . - -- Any attempt to send context by using the in an outgoing message throws an . - -- If a message is received from server with a specific context, when the channel has already been initialized with a specific context, this results in a . - +This section describes the context exchange protocol introduced in Windows Communication Foundation (WCF) release .NET Framework version 3.5. This protocol allows the client channel to accept a context supplied by a service and apply it to all subsequent requests to that service sent over the same client channel instance. The implementation of the context exchange protocol can use one of the following two mechanisms to propagate the context between the server and the client: HTTP cookies or a SOAP header. + + The context exchange protocol is implemented in a custom channel layer. The channel communicates the context to and from the application layer using a property. For transmission between endpoints, the value of the context is either serialized as a SOAP header at the channel layer, or converted to or from the message properties that represent a HTTP request and response. In the latter case, it is expected that one of the underlying channel layers converts the HTTP request and response message properties to and from HTTP cookies, respectively. The choice of the mechanism used to exchange the context is done using the property on the . Valid values are `HttpCookie` or `SoapHeader`. + + On the client, an instance of a channel can operate in two modes based on the settings on the channel property, . + +## Mode 1: Channel Context Management + + This is the default mode where is set to `true`. In this mode the context channel manages the context and caches the context during its lifetime. Context can be retrieved from the channel through channel property `IContextManager` by calling the `GetContext` method. The channel can also be pre-initialized with specific context before being opened by calling the `SetContext` method on the channel property. Once the channel is initialized with context it cannot be reset. + + The following is a list of invariants in this mode: + +- Any attempt to reset the context using `SetContext` after the channel has been opened throws an . + +- Any attempt to send context by using the in an outgoing message throws an . + +- If a message is received from server with a specific context, when the channel has already been initialized with a specific context, this results in a . + > [!NOTE] - > It is appropriate to receive an initial context from the server only if the channel is opened without any context set explicitly. - -- The on incoming message is always null. - -## Mode 2: Application Context Management - - This is the mode when is set to `false`. In this mode the context channel does not manage context. It is the application's responsibility to retrieve, manage and apply context by using the . Any attempt to call `GetContext` or `SetContext` results in an . - - No matter which mode is chosen the client channel factory supports , , and message exchange patterns. - - On the service, an instance of the channel is responsible for converting the context supplied by the client on incoming messages to the . The message property can then be accessed by the application layer or other channels further up in the call stack. The service channels also allow the application layer to specify a new context value to be propagated back to the client by attaching a to the response message. This property is converted to the SOAP header or HTTP cookie that contains the context, which depends on the configuration of the binding. The service channel listener supports , , and message exchange patterns. - - The context exchange protocol introduces a new `wsc:Context` SOAP header to represent the context information when HTTP cookies are not used to propagate the context. The context header schema allows for any number of child elements, each with a string key and string content. The following is an example of a context header. - - `` - - `context-2` - - `` - - When in `HttpCookie` mode, cookies are set using the `SetCookie` header. The cookie name is `WscContext`. The value of the cookie is the Base64 encoding of the `wsc:Context` header. This value is enclosed in quotes. - - The value of the context must be protected from modification while in transit for the same reason WS-Addressing headers are protected – the header is used to determine where to dispatch the request to on the service. The `wsc:Context` header is therefore required to be digitally signed or signed and encrypted at either the SOAP or transport level when the binding offers message protection capability. When HTTP cookies are used to propagate context, they should be protected using transport security. - - Service endpoints that require support for the context exchange protocol can make it explicit in the published policy. Two new policy assertions have been introduced to represent the requirement for the client to support the context exchange protocol at the SOAP level or to enable HTTP cookie support. Generation of these assertions into the policy on the service is controlled by the value of the property as follows: - -- For , the following assertion is generated: - - ```xml + > It is appropriate to receive an initial context from the server only if the channel is opened without any context set explicitly. + +- The on incoming message is always null. + +## Mode 2: Application Context Management + + This is the mode when is set to `false`. In this mode the context channel does not manage context. It is the application's responsibility to retrieve, manage and apply context by using the . Any attempt to call `GetContext` or `SetContext` results in an . + + No matter which mode is chosen the client channel factory supports , , and message exchange patterns. + + On the service, an instance of the channel is responsible for converting the context supplied by the client on incoming messages to the . The message property can then be accessed by the application layer or other channels further up in the call stack. The service channels also allow the application layer to specify a new context value to be propagated back to the client by attaching a to the response message. This property is converted to the SOAP header or HTTP cookie that contains the context, which depends on the configuration of the binding. The service channel listener supports , , and message exchange patterns. + + The context exchange protocol introduces a new `wsc:Context` SOAP header to represent the context information when HTTP cookies are not used to propagate the context. The context header schema allows for any number of child elements, each with a string key and string content. The following is an example of a context header. + + `` + + `context-2` + + `` + + When in `HttpCookie` mode, cookies are set using the `SetCookie` header. The cookie name is `WscContext`. The value of the cookie is the Base64 encoding of the `wsc:Context` header. This value is enclosed in quotes. + + The value of the context must be protected from modification while in transit for the same reason WS-Addressing headers are protected – the header is used to determine where to dispatch the request to on the service. The `wsc:Context` header is therefore required to be digitally signed or signed and encrypted at either the SOAP or transport level when the binding offers message protection capability. When HTTP cookies are used to propagate context, they should be protected using transport security. + + Service endpoints that require support for the context exchange protocol can make it explicit in the published policy. Two new policy assertions have been introduced to represent the requirement for the client to support the context exchange protocol at the SOAP level or to enable HTTP cookie support. Generation of these assertions into the policy on the service is controlled by the value of the property as follows: + +- For , the following assertion is generated: + + ```xml - ``` - -- For , the following assertion is generated: - - ```xml - - ``` - + xmlns="http://schemas.microsoft.com/ws/2006/05/context" + protectionLevel="Sign" /> + ``` + +- For , the following assertion is generated: + + ```xml + + ``` + ## See also - [Web Services Protocols Interoperability Guide](web-services-protocols-interoperability-guide.md) diff --git a/docs/framework/wcf/feature-details/create-a-service-arbitrary-data-using-wcf.md b/docs/framework/wcf/feature-details/create-a-service-arbitrary-data-using-wcf.md index 8230a863d4fb3..9eaabed0ce750 100644 --- a/docs/framework/wcf/feature-details/create-a-service-arbitrary-data-using-wcf.md +++ b/docs/framework/wcf/feature-details/create-a-service-arbitrary-data-using-wcf.md @@ -7,190 +7,190 @@ ms.assetid: e566c15a-b600-4e4a-be3a-4af43e767dae --- # How to: Create a Service That Accepts Arbitrary Data using the WCF REST Programming Model -Sometimes developers must have full control of how data is returned from a service operation. This is the case when a service operation must return data in a format not supported byWCF. This topic discusses using the WCF REST Programming Model to create a service that receives arbitrary data. - -### To implement the service contract - -1. Define the service contract. The operation that receives the arbitrary data must have a parameter of type . In addition, this parameter must be the only parameter passed in the body of the request. The operation described in this example also takes a filename parameter. This parameter is passed within the URL of the request. You can specify that a parameter is passed within the URL by specifying a in the . In this case the URI used to call this method ends in "UploadFile/Some-Filename". The "{filename}" portion of the URI template specifies that the filename parameter for the operation is passed within the URI used to call the operation. - - ```csharp - [ServiceContract] - public interface IReceiveData - { - [WebInvoke(UriTemplate = "UploadFile/{fileName}")] - void UploadFile(string fileName, Stream fileContents); - } - ``` - -2. Implement the service contract. The contract has only one method, `UploadFile` that receives a file of arbitrary data in a stream. The operation reads the stream counting the number of bytes read and then displays the filename and the number of bytes read. - - ```csharp - public class RawDataService : IReceiveData - { - public void UploadFile(string fileName, Stream fileContents) - { - byte[] buffer = new byte[10000]; - int bytesRead, totalBytesRead = 0; - do - { - bytesRead = fileContents.Read(buffer, 0, buffer.Length); - totalBytesRead += bytesRead; - } while (bytesRead > 0); - Console.WriteLine("Service: Received file {0} with {1} bytes", fileName, totalBytesRead); - } - } - ``` - -### To host the service - -1. Create a console application to host the service. - - ```csharp - class Program - { - static void Main(string[] args) - { - } - } - ``` - -2. Create a variable to hold the base address for the service within the `Main` method. - - ```csharp - string baseAddress = "http://" + Environment.MachineName + ":8000/Service"; - ``` - -3. Create a instance for the service that specifies the service class and the base address. - - ```csharp - ServiceHost host = new ServiceHost(typeof(RawDataService), new Uri(baseAddress)); - ``` - -4. Add an endpoint that specifies the contract, , and . - - ```csharp - host.AddServiceEndpoint(typeof(IReceiveData), new WebHttpBinding(), "").Behaviors.Add(new WebHttpBehavior()); - ``` - -5. Open the service host. The service is now ready to receive requests. - - ```csharp - host.Open(); - Console.WriteLine("Host opened"); - ``` - -### To call the service programmatically - -1. Create a with the URI used to call the service. In this code, the base address is combined with `"/UploadFile/Text"`. The `"UploadFile"` portion of the URI specifies the operation to call. The `"Test.txt"` portion of the URI specifies the filename parameter to pass to the `UploadFile` operation. Both of these items map to the applied to the operation contract. - - ```csharp - HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create(baseAddress + "/UploadFile/Test.txt"); - ``` - -2. Set the property of the to `POST` and the property to `"text/plain"`. This tells the service that the code is sending data and that data is in plain text. - - ```csharp - req.Method = "POST"; - req.ContentType = "text/plain"; - ``` - -3. Call to get the request stream, create the data to send, write that data to the request stream, and close the stream. - - ```csharp - Stream reqStream = req.GetRequestStream(); - byte[] fileToSend = new byte[12345]; - for (int i = 0; i < fileToSend.Length; i++) - { - fileToSend[i] = (byte)('a' + (i % 26)); - } - reqStream.Write(fileToSend, 0, fileToSend.Length); - reqStream.Close(); - ``` - -4. Get the response from the service by calling and display the response data to the console. - - ```csharp - HttpWebResponse resp = (HttpWebResponse)req.GetResponse(); - Console.WriteLine("Client: Receive Response HTTP/{0} {1} {2}", resp.ProtocolVersion, (int)resp.StatusCode, resp.StatusDescription); - ``` - -5. Close the service host. - - ```csharp - host.Close(); - ``` - -## Example - - The following is a complete listing of the code for this example. - -```csharp -using System; -using System.Collections.Generic; -using System.Text; -using System.ServiceModel; -using System.ServiceModel.Web; -using System.ServiceModel.Description; -using System.IO; -using System.Net; - -namespace ReceiveRawData -{ - [ServiceContract] - public interface IReceiveData - { - [WebInvoke(UriTemplate = "UploadFile/{fileName}")] - void UploadFile(string fileName, Stream fileContents); - } - public class RawDataService : IReceiveData - { - public void UploadFile(string fileName, Stream fileContents) - { - byte[] buffer = new byte[10000]; - int bytesRead, totalBytesRead = 0; - do - { - bytesRead = fileContents.Read(buffer, 0, buffer.Length); - totalBytesRead += bytesRead; - } while (bytesRead > 0); - Console.WriteLine("Service: Received file {0} with {1} bytes", fileName, totalBytesRead); - } - } - - class Program - { - static void Main(string[] args) - { - string baseAddress = "http://" + Environment.MachineName + ":8000/Service"; - ServiceHost host = new ServiceHost(typeof(RawDataService), new Uri(baseAddress)); - host.AddServiceEndpoint(typeof(IReceiveData), new WebHttpBinding(), "").Behaviors.Add(new WebHttpBehavior()); - host.Open(); - Console.WriteLine("Host opened"); - - HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create(baseAddress + "/UploadFile/Test.txt"); - req.Method = "POST"; - req.ContentType = "text/plain"; - Stream reqStream = req.GetRequestStream(); - byte[] fileToSend = new byte[12345]; - for (int i = 0; i < fileToSend.Length; i++) - { - fileToSend[i] = (byte)('a' + (i % 26)); - } - reqStream.Write(fileToSend, 0, fileToSend.Length); - reqStream.Close(); - HttpWebResponse resp = (HttpWebResponse)req.GetResponse(); - Console.WriteLine("Client: Receive Response HTTP/{0} {1} {2}", resp.ProtocolVersion, (int)resp.StatusCode, resp.StatusDescription); - host.Close(); - - } - } -} -``` - -## Compiling the Code - -- When compiling the code reference System.ServiceModel.dll and System.ServiceModel.Web.dll - +Sometimes developers must have full control of how data is returned from a service operation. This is the case when a service operation must return data in a format not supported byWCF. This topic discusses using the WCF REST Programming Model to create a service that receives arbitrary data. + +### To implement the service contract + +1. Define the service contract. The operation that receives the arbitrary data must have a parameter of type . In addition, this parameter must be the only parameter passed in the body of the request. The operation described in this example also takes a filename parameter. This parameter is passed within the URL of the request. You can specify that a parameter is passed within the URL by specifying a in the . In this case the URI used to call this method ends in "UploadFile/Some-Filename". The "{filename}" portion of the URI template specifies that the filename parameter for the operation is passed within the URI used to call the operation. + + ```csharp + [ServiceContract] + public interface IReceiveData + { + [WebInvoke(UriTemplate = "UploadFile/{fileName}")] + void UploadFile(string fileName, Stream fileContents); + } + ``` + +2. Implement the service contract. The contract has only one method, `UploadFile` that receives a file of arbitrary data in a stream. The operation reads the stream counting the number of bytes read and then displays the filename and the number of bytes read. + + ```csharp + public class RawDataService : IReceiveData + { + public void UploadFile(string fileName, Stream fileContents) + { + byte[] buffer = new byte[10000]; + int bytesRead, totalBytesRead = 0; + do + { + bytesRead = fileContents.Read(buffer, 0, buffer.Length); + totalBytesRead += bytesRead; + } while (bytesRead > 0); + Console.WriteLine("Service: Received file {0} with {1} bytes", fileName, totalBytesRead); + } + } + ``` + +### To host the service + +1. Create a console application to host the service. + + ```csharp + class Program + { + static void Main(string[] args) + { + } + } + ``` + +2. Create a variable to hold the base address for the service within the `Main` method. + + ```csharp + string baseAddress = "http://" + Environment.MachineName + ":8000/Service"; + ``` + +3. Create a instance for the service that specifies the service class and the base address. + + ```csharp + ServiceHost host = new ServiceHost(typeof(RawDataService), new Uri(baseAddress)); + ``` + +4. Add an endpoint that specifies the contract, , and . + + ```csharp + host.AddServiceEndpoint(typeof(IReceiveData), new WebHttpBinding(), "").Behaviors.Add(new WebHttpBehavior()); + ``` + +5. Open the service host. The service is now ready to receive requests. + + ```csharp + host.Open(); + Console.WriteLine("Host opened"); + ``` + +### To call the service programmatically + +1. Create a with the URI used to call the service. In this code, the base address is combined with `"/UploadFile/Text"`. The `"UploadFile"` portion of the URI specifies the operation to call. The `"Test.txt"` portion of the URI specifies the filename parameter to pass to the `UploadFile` operation. Both of these items map to the applied to the operation contract. + + ```csharp + HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create(baseAddress + "/UploadFile/Test.txt"); + ``` + +2. Set the property of the to `POST` and the property to `"text/plain"`. This tells the service that the code is sending data and that data is in plain text. + + ```csharp + req.Method = "POST"; + req.ContentType = "text/plain"; + ``` + +3. Call to get the request stream, create the data to send, write that data to the request stream, and close the stream. + + ```csharp + Stream reqStream = req.GetRequestStream(); + byte[] fileToSend = new byte[12345]; + for (int i = 0; i < fileToSend.Length; i++) + { + fileToSend[i] = (byte)('a' + (i % 26)); + } + reqStream.Write(fileToSend, 0, fileToSend.Length); + reqStream.Close(); + ``` + +4. Get the response from the service by calling and display the response data to the console. + + ```csharp + HttpWebResponse resp = (HttpWebResponse)req.GetResponse(); + Console.WriteLine("Client: Receive Response HTTP/{0} {1} {2}", resp.ProtocolVersion, (int)resp.StatusCode, resp.StatusDescription); + ``` + +5. Close the service host. + + ```csharp + host.Close(); + ``` + +## Example + + The following is a complete listing of the code for this example. + +```csharp +using System; +using System.Collections.Generic; +using System.Text; +using System.ServiceModel; +using System.ServiceModel.Web; +using System.ServiceModel.Description; +using System.IO; +using System.Net; + +namespace ReceiveRawData +{ + [ServiceContract] + public interface IReceiveData + { + [WebInvoke(UriTemplate = "UploadFile/{fileName}")] + void UploadFile(string fileName, Stream fileContents); + } + public class RawDataService : IReceiveData + { + public void UploadFile(string fileName, Stream fileContents) + { + byte[] buffer = new byte[10000]; + int bytesRead, totalBytesRead = 0; + do + { + bytesRead = fileContents.Read(buffer, 0, buffer.Length); + totalBytesRead += bytesRead; + } while (bytesRead > 0); + Console.WriteLine("Service: Received file {0} with {1} bytes", fileName, totalBytesRead); + } + } + + class Program + { + static void Main(string[] args) + { + string baseAddress = "http://" + Environment.MachineName + ":8000/Service"; + ServiceHost host = new ServiceHost(typeof(RawDataService), new Uri(baseAddress)); + host.AddServiceEndpoint(typeof(IReceiveData), new WebHttpBinding(), "").Behaviors.Add(new WebHttpBehavior()); + host.Open(); + Console.WriteLine("Host opened"); + + HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create(baseAddress + "/UploadFile/Test.txt"); + req.Method = "POST"; + req.ContentType = "text/plain"; + Stream reqStream = req.GetRequestStream(); + byte[] fileToSend = new byte[12345]; + for (int i = 0; i < fileToSend.Length; i++) + { + fileToSend[i] = (byte)('a' + (i % 26)); + } + reqStream.Write(fileToSend, 0, fileToSend.Length); + reqStream.Close(); + HttpWebResponse resp = (HttpWebResponse)req.GetResponse(); + Console.WriteLine("Client: Receive Response HTTP/{0} {1} {2}", resp.ProtocolVersion, (int)resp.StatusCode, resp.StatusDescription); + host.Close(); + + } + } +} +``` + +## Compiling the Code + +- When compiling the code reference System.ServiceModel.dll and System.ServiceModel.Web.dll + ## See also - [UriTemplate and UriTemplateTable](uritemplate-and-uritemplatetable.md) diff --git a/docs/framework/wcf/feature-details/creating-wcf-ajax-services-without-aspnet.md b/docs/framework/wcf/feature-details/creating-wcf-ajax-services-without-aspnet.md index 14df2652b7497..4cf89d9e2c896 100644 --- a/docs/framework/wcf/feature-details/creating-wcf-ajax-services-without-aspnet.md +++ b/docs/framework/wcf/feature-details/creating-wcf-ajax-services-without-aspnet.md @@ -6,105 +6,105 @@ ms.assetid: ba4a7d1b-e277-4978-9f62-37684e6dc934 --- # Creating WCF AJAX Services without ASP.NET -Windows Communication Foundation (WCF) AJAX services can be accessed from any JavaScript-enabled Web page, without requiring ASP.NET AJAX. This topic describes how to create such a WCF service. - - For instructions on using WCF with ASP.NET AJAX, see [Creating WCF Services for ASP.NET AJAX](creating-wcf-services-for-aspnet-ajax.md). - - There are three parts to a creating a WCF AJAX service: - -- Creating an AJAX endpoint that can be accessed from the browser. - -- Creating an AJAX-compatible service contract. - -- Accessing WCF AJAX services. - -## Creating an AJAX Endpoint - - The most basic way to enable AJAX support in a WCF service is to use the in the .svc file associated with the service, as in the following example. - +Windows Communication Foundation (WCF) AJAX services can be accessed from any JavaScript-enabled Web page, without requiring ASP.NET AJAX. This topic describes how to create such a WCF service. + + For instructions on using WCF with ASP.NET AJAX, see [Creating WCF Services for ASP.NET AJAX](creating-wcf-services-for-aspnet-ajax.md). + + There are three parts to a creating a WCF AJAX service: + +- Creating an AJAX endpoint that can be accessed from the browser. + +- Creating an AJAX-compatible service contract. + +- Accessing WCF AJAX services. + +## Creating an AJAX Endpoint + + The most basic way to enable AJAX support in a WCF service is to use the in the .svc file associated with the service, as in the following example. + ```text <%ServiceHost - language=c# - Debug="true" - Service="Microsoft.Ajax.Samples.CityService" - Factory=System.ServiceModel.Activation.WebServiceHostFactory -%> -``` - - Alternatively, you can also use configuration to add an AJAX endpoint. Use the on the service endpoint and configure that endpoint with the as shown in the following code snippet. - -```xml - - - - - - - - - - - + language=c# + Debug="true" + Service="Microsoft.Ajax.Samples.CityService" + Factory=System.ServiceModel.Activation.WebServiceHostFactory +%> +``` + + Alternatively, you can also use configuration to add an AJAX endpoint. Use the on the service endpoint and configure that endpoint with the as shown in the following code snippet. + +```xml + + + + + + + + + + + - - - - -``` - - For a working example, see the [AJAX Service with JSON and XML](../samples/ajax-service-with-json-and-xml-sample.md). - -## Creating an AJAX-Compatible Service Contract - - By default, service contracts exposed over an AJAX endpoint return data in the XML format. Also, by default service operations are accessible through HTTP POST requests to URLs that include the endpoint address followed by the operation name, as shown in the following example. - + address="ajaxEndpoint" + behaviorConfiguration="AjaxBehavior" + binding="webHttpBinding" + contract="Microsoft.Ajax.Samples.ICityService" /> + + + + +``` + + For a working example, see the [AJAX Service with JSON and XML](../samples/ajax-service-with-json-and-xml-sample.md). + +## Creating an AJAX-Compatible Service Contract + + By default, service contracts exposed over an AJAX endpoint return data in the XML format. Also, by default service operations are accessible through HTTP POST requests to URLs that include the endpoint address followed by the operation name, as shown in the following example. + ```csharp -[OperationContract] -string[] GetCities(string firstLetters); -``` - - This operation is accessible using an HTTP POST to `http://serviceaddress/endpointaddress/GetCities` and return an XML message. - - You can use the full Web Programming Model to customize these basic aspects. For example, you can use the or attributes to control the HTTP verb to which the operation responds or use the `UriTemplate` property of these respective attributes to specify custom URIs. For more information, see the [WCF Web HTTP Programming Model](wcf-web-http-programming-model.md) topic. - - The JSON data format is often used in AJAX services. To create an operation that returns JSON instead of XML, set the (or the ) property to . The [Stand-Alone JSON Serialization](stand-alone-json-serialization.md) topic shows how built-in .NET types and data contract types map to JSON. - - Normally, JSON requests and responses consist of just one item. For the preceding `GetCities` operation, the request resembles the following statement. - +[OperationContract] +string[] GetCities(string firstLetters); +``` + + This operation is accessible using an HTTP POST to `http://serviceaddress/endpointaddress/GetCities` and return an XML message. + + You can use the full Web Programming Model to customize these basic aspects. For example, you can use the or attributes to control the HTTP verb to which the operation responds or use the `UriTemplate` property of these respective attributes to specify custom URIs. For more information, see the [WCF Web HTTP Programming Model](wcf-web-http-programming-model.md) topic. + + The JSON data format is often used in AJAX services. To create an operation that returns JSON instead of XML, set the (or the ) property to . The [Stand-Alone JSON Serialization](stand-alone-json-serialization.md) topic shows how built-in .NET types and data contract types map to JSON. + + Normally, JSON requests and responses consist of just one item. For the preceding `GetCities` operation, the request resembles the following statement. + +```json +"na" +``` + + The response to that request resembles the following statement. + ```json -"na" -``` - - The response to that request resembles the following statement. - +["Nairobi", "Naples", "Nashville"] +``` + + If the operation takes an extra parameter, the request style must be wrapped to wrap both parameters in a single JSON object. An example of this style JSON message is in the following example. + ```json -["Nairobi", "Naples", "Nashville"] -``` - - If the operation takes an extra parameter, the request style must be wrapped to wrap both parameters in a single JSON object. An example of this style JSON message is in the following example. - -```json -{"firstLetters": "na", "maxNumber": 2} -``` - - The following contract accepts this message. - +{"firstLetters": "na", "maxNumber": 2} +``` + + The following contract accepts this message. + ```csharp -[WebInvoke(BodyStyle=WebMessageBodyStyle.WrappedRequest, ResponseFormat=WebMessageFormat.Json)] -[OperationContract] -string[] GetCities(string firstLetters, int maxNumber); -``` - -## Accessing AJAX Services - - WCF AJAX endpoints always accept both JSON and XML requests. - - HTTP POST requests with a content-type of "application/json" are treated as JSON, and those with content-type that indicate XML (for example, "text/xml") are treated as XML. - - HTTP GET requests contain all the request parameters in the URL itself. - +[WebInvoke(BodyStyle=WebMessageBodyStyle.WrappedRequest, ResponseFormat=WebMessageFormat.Json)] +[OperationContract] +string[] GetCities(string firstLetters, int maxNumber); +``` + +## Accessing AJAX Services + + WCF AJAX endpoints always accept both JSON and XML requests. + + HTTP POST requests with a content-type of "application/json" are treated as JSON, and those with content-type that indicate XML (for example, "text/xml") are treated as XML. + + HTTP GET requests contain all the request parameters in the URL itself. + It is up to the user to decide how to create the HTTP request to the endpoint. Also, the user has full control over constructing the JSON that forms the body of the request. For an example of creating a request from JavaScript, see the [AJAX Service with JSON and XML](../samples/ajax-service-with-json-and-xml-sample.md). diff --git a/docs/framework/wcf/feature-details/creating-wcf-services-for-aspnet-ajax.md b/docs/framework/wcf/feature-details/creating-wcf-services-for-aspnet-ajax.md index e66b434ebd3ff..c56140bb4e226 100644 --- a/docs/framework/wcf/feature-details/creating-wcf-services-for-aspnet-ajax.md +++ b/docs/framework/wcf/feature-details/creating-wcf-services-for-aspnet-ajax.md @@ -24,7 +24,7 @@ The Web Programming Model described in the [WCF Web HTTP Programming Model Overv - You can use the and attributes to select between HTTP GET and HTTP POST verbs. If used correctly, this may significantly improve your application’s performance. For more information, see [How to: Choose between HTTP POST and HTTP GET requests for ASP.NET AJAX Endpoints](http-post-and-http-get-requests-for-aspnet-ajax-endpoints.md). -- You can use the and properties to cause your service to return XML data instead of the default JavaScript Object Notation (JSON). Doing this with the ASP.NET AJAX framework causes the JavaScript client to receive an XML DOM object. +- You can use the and properties to cause your service to return XML data instead of the default JavaScript Object Notation (JSON). Doing this with the ASP.NET AJAX framework causes the JavaScript client to receive an XML DOM object. > [!WARNING] > Your operation must set the content type to text/xml for this to work. Otherwise, the JavaScript client will receive a string containing the XML instead of an XML DOM object. diff --git a/docs/framework/wcf/feature-details/data-contract-equivalence.md b/docs/framework/wcf/feature-details/data-contract-equivalence.md index d448ed4879686..426f6218b119b 100644 --- a/docs/framework/wcf/feature-details/data-contract-equivalence.md +++ b/docs/framework/wcf/feature-details/data-contract-equivalence.md @@ -2,62 +2,62 @@ description: "Learn more about: Data Contract Equivalence" title: "Data Contract Equivalence" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "data contracts [WCF], equivalence" ms.assetid: f06f3c7e-c235-4ec1-b200-68142edf1ed1 --- # Data Contract Equivalence -For a client to successfully send data of a certain type to a service, or a service to successfully send data to a client, the sent type does not necessarily have to exist on the receiving end. The only requirement is that the data contracts of both types be equivalent. (Sometimes, strict equivalence is not required, as discussed in [Data Contract Versioning](data-contract-versioning.md).) - - For data contracts to be equivalent, they must have the same namespace and name. Additionally, each data member on one side must have an equivalent data member on the other side. - - For data members to be equivalent, they must have the same name. Additionally, they must represent the same type of data; that is, their data contracts must be equivalent. - +For a client to successfully send data of a certain type to a service, or a service to successfully send data to a client, the sent type does not necessarily have to exist on the receiving end. The only requirement is that the data contracts of both types be equivalent. (Sometimes, strict equivalence is not required, as discussed in [Data Contract Versioning](data-contract-versioning.md).) + + For data contracts to be equivalent, they must have the same namespace and name. Additionally, each data member on one side must have an equivalent data member on the other side. + + For data members to be equivalent, they must have the same name. Additionally, they must represent the same type of data; that is, their data contracts must be equivalent. + > [!NOTE] -> Note that data contract names and namespaces, as well as data member names, are case-sensitive. - - For more information about data contract names and namespaces, as well as data member names, see [Data Contract Names](data-contract-names.md). - - If two types exist on the same side (sender or receiver) and their data contracts are not equivalent (for example, they have different data members), you should not give them the same name and namespace. Doing so may cause exceptions to be thrown. - - The data contracts for the following types are equivalent: - +> Note that data contract names and namespaces, as well as data member names, are case-sensitive. + + For more information about data contract names and namespaces, as well as data member names, see [Data Contract Names](data-contract-names.md). + + If two types exist on the same side (sender or receiver) and their data contracts are not equivalent (for example, they have different data members), you should not give them the same name and namespace. Doing so may cause exceptions to be thrown. + + The data contracts for the following types are equivalent: + [!code-csharp[C_DataContractNames#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractnames/cs/source.cs#5)] - [!code-vb[C_DataContractNames#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractnames/vb/source.vb#5)] - -## Data Member Order and Data Contract equivalence - - Using the property of the class may affect data contract equivalence. The data contracts must have members that appear in the same order to be equivalent. The default order is alphabetical. For more information, see [Data Member Order](data-member-order.md). - - For example, the following code results in equivalent data contracts. - + [!code-vb[C_DataContractNames#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractnames/vb/source.vb#5)] + +## Data Member Order and Data Contract equivalence + + Using the property of the class may affect data contract equivalence. The data contracts must have members that appear in the same order to be equivalent. The default order is alphabetical. For more information, see [Data Member Order](data-member-order.md). + + For example, the following code results in equivalent data contracts. + [!code-csharp[C_DataContractNames#6](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractnames/cs/source.cs#6)] - [!code-vb[C_DataContractNames#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractnames/vb/source.vb#6)] - - However, the following does not result in an equivalent data contract. - + [!code-vb[C_DataContractNames#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractnames/vb/source.vb#6)] + + However, the following does not result in an equivalent data contract. + [!code-csharp[C_DataContractNames#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractnames/cs/source.cs#7)] - [!code-vb[C_DataContractNames#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractnames/vb/source.vb#7)] - -## Inheritance, Interfaces, and Data Contract Equivalence - - When determining equivalence, a data contract that inherits from another data contract is treated as if it is just one data contract that includes all of the data members from the base type. Keep in mind that the order of the data members must match and that base type members precede derived type members in the order. Furthermore, if, as in the following code example, two data members have the same order value, the ordering for those data members is alphabetical. For more information, see [Data Member Order](data-member-order.md). - - In the following example, the data contract for type `Employee` is equivalent to the data contract for the type `Worker`. - + [!code-vb[C_DataContractNames#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractnames/vb/source.vb#7)] + +## Inheritance, Interfaces, and Data Contract Equivalence + + When determining equivalence, a data contract that inherits from another data contract is treated as if it is just one data contract that includes all of the data members from the base type. Keep in mind that the order of the data members must match and that base type members precede derived type members in the order. Furthermore, if, as in the following code example, two data members have the same order value, the ordering for those data members is alphabetical. For more information, see [Data Member Order](data-member-order.md). + + In the following example, the data contract for type `Employee` is equivalent to the data contract for the type `Worker`. + [!code-csharp[C_DataContractNames#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractnames/cs/source.cs#8)] - [!code-vb[C_DataContractNames#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractnames/vb/source.vb#8)] - - When passing parameters and return values between a client and a service, a data contract from a base class cannot be sent when the receiving endpoint expects a data contract from a derived class. This is in accordance with object-oriented programming tenets. In the previous example, an object of type `Person` cannot be sent when an `Employee` is expected. - - A data contract from a derived class can be sent when a data contract from a base class is expected, but only if the receiving endpoint "knows" of the derived type using the . For more information, see [Data Contract Known Types](data-contract-known-types.md). In the previous example, an object of type `Employee` can be sent when a `Person` is expected, but only if the receiver code employs the to include it in the list of known types. - - When passing parameters and return values between applications, if the expected type is an interface, it is equivalent to the expected type being of type . Because every type ultimately derives from , every data contract ultimately derives from the data contract for . Thus, any data contract type can be passed when an interface is expected. Additional steps are required to successfully work with interfaces; for more information, see [Data Contract Known Types](data-contract-known-types.md). - + [!code-vb[C_DataContractNames#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractnames/vb/source.vb#8)] + + When passing parameters and return values between a client and a service, a data contract from a base class cannot be sent when the receiving endpoint expects a data contract from a derived class. This is in accordance with object-oriented programming tenets. In the previous example, an object of type `Person` cannot be sent when an `Employee` is expected. + + A data contract from a derived class can be sent when a data contract from a base class is expected, but only if the receiving endpoint "knows" of the derived type using the . For more information, see [Data Contract Known Types](data-contract-known-types.md). In the previous example, an object of type `Employee` can be sent when a `Person` is expected, but only if the receiver code employs the to include it in the list of known types. + + When passing parameters and return values between applications, if the expected type is an interface, it is equivalent to the expected type being of type . Because every type ultimately derives from , every data contract ultimately derives from the data contract for . Thus, any data contract type can be passed when an interface is expected. Additional steps are required to successfully work with interfaces; for more information, see [Data Contract Known Types](data-contract-known-types.md). + ## See also - diff --git a/docs/framework/wcf/feature-details/data-contract-known-types.md b/docs/framework/wcf/feature-details/data-contract-known-types.md index 23ecc31649a46..7d00f99adefd7 100644 --- a/docs/framework/wcf/feature-details/data-contract-known-types.md +++ b/docs/framework/wcf/feature-details/data-contract-known-types.md @@ -2,10 +2,10 @@ title: "Data Contract Known Types" description: Learn how the data contract model uses the KnownTypeAttribute class to specify the types to include during deserialization in WCF. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "data contracts [WCF], known types" - "KnownTypeAttribute [WCF]" - "KnownTypes [WCF]" @@ -13,173 +13,173 @@ ms.assetid: 1a0baea1-27b7-470d-9136-5bbad86c4337 --- # Data Contract Known Types -The class allows you to specify, in advance, the types that should be included for consideration during deserialization. For a working example, see the [Known Types](../samples/known-types.md) example. - - Normally, when passing parameters and return values between a client and a service, both endpoints share all of the data contracts of the data to be transmitted. However, this is not the case in the following circumstances: - -- The sent data contract is derived from the expected data contract. For more information, see the section about inheritance in [Data Contract Equivalence](data-contract-equivalence.md)). In that case, the transmitted data does not have the same data contract as expected by the receiving endpoint. - -- The declared type for the information to be transmitted is an interface, as opposed to a class, structure, or enumeration. Therefore, it cannot be known in advance which type that implements the interface is actually sent and therefore, the receiving endpoint cannot determine in advance the data contract for the transmitted data. - -- The declared type for the information to be transmitted is . Because every type inherits from , and it cannot be known in advance which type is actually sent, the receiving endpoint cannot determine in advance the data contract for the transmitted data. This is a special case of the first item: Every data contract derives from the default, a blank data contract that is generated for . - -- Some types, which include .NET Framework types, have members that are in one of the preceding three categories. For example, uses to store the actual objects in the hash table. When serializing these types, the receiving side cannot determine in advance the data contract for these members. - -## The KnownTypeAttribute Class - - When data arrives at a receiving endpoint, the WCF runtime attempts to deserialize the data into an instance of a common language runtime (CLR) type. The type that is instantiated for deserialization is chosen by first inspecting the incoming message to determine the data contract to which the contents of the message conform. The deserialization engine then attempts to find a CLR type that implements a data contract compatible with the message contents. The set of candidate types that the deserialization engine allows for during this process is referred to as the deserializer's set of "known types." - - One way to let the deserialization engine know about a type is by using the . The attribute cannot be applied to individual data members, only to whole data contract types. The attribute is applied to an *outer type* that can be a class or a structure. In its most basic usage, applying the attribute specifies a type as a "known type." This causes the known type to be a part of the set of known types whenever an object of the outer type or any object referred to through its members is being deserialized. More than one attribute can be applied to the same type. - -## Known Types and Primitives - - Primitive types, as well as certain types treated as primitives (for example, and ) are always "known" and never have to be added through this mechanism. However, arrays of primitive types have to be added explicitly. Most collections are considered equivalent to arrays. (Non-generic collections are considered equivalent to arrays of ). For an example of the using primitives, primitive arrays, and primitive collections, see Example 4. - +The class allows you to specify, in advance, the types that should be included for consideration during deserialization. For a working example, see the [Known Types](../samples/known-types.md) example. + + Normally, when passing parameters and return values between a client and a service, both endpoints share all of the data contracts of the data to be transmitted. However, this is not the case in the following circumstances: + +- The sent data contract is derived from the expected data contract. For more information, see the section about inheritance in [Data Contract Equivalence](data-contract-equivalence.md)). In that case, the transmitted data does not have the same data contract as expected by the receiving endpoint. + +- The declared type for the information to be transmitted is an interface, as opposed to a class, structure, or enumeration. Therefore, it cannot be known in advance which type that implements the interface is actually sent and therefore, the receiving endpoint cannot determine in advance the data contract for the transmitted data. + +- The declared type for the information to be transmitted is . Because every type inherits from , and it cannot be known in advance which type is actually sent, the receiving endpoint cannot determine in advance the data contract for the transmitted data. This is a special case of the first item: Every data contract derives from the default, a blank data contract that is generated for . + +- Some types, which include .NET Framework types, have members that are in one of the preceding three categories. For example, uses to store the actual objects in the hash table. When serializing these types, the receiving side cannot determine in advance the data contract for these members. + +## The KnownTypeAttribute Class + + When data arrives at a receiving endpoint, the WCF runtime attempts to deserialize the data into an instance of a common language runtime (CLR) type. The type that is instantiated for deserialization is chosen by first inspecting the incoming message to determine the data contract to which the contents of the message conform. The deserialization engine then attempts to find a CLR type that implements a data contract compatible with the message contents. The set of candidate types that the deserialization engine allows for during this process is referred to as the deserializer's set of "known types." + + One way to let the deserialization engine know about a type is by using the . The attribute cannot be applied to individual data members, only to whole data contract types. The attribute is applied to an *outer type* that can be a class or a structure. In its most basic usage, applying the attribute specifies a type as a "known type." This causes the known type to be a part of the set of known types whenever an object of the outer type or any object referred to through its members is being deserialized. More than one attribute can be applied to the same type. + +## Known Types and Primitives + + Primitive types, as well as certain types treated as primitives (for example, and ) are always "known" and never have to be added through this mechanism. However, arrays of primitive types have to be added explicitly. Most collections are considered equivalent to arrays. (Non-generic collections are considered equivalent to arrays of ). For an example of the using primitives, primitive arrays, and primitive collections, see Example 4. + > [!NOTE] -> Unlike other primitive types, the structure is not a known type by default, so it must be manually added to the list of known types. - -## Examples +> Unlike other primitive types, the structure is not a known type by default, so it must be manually added to the list of known types. + +## Examples + + The following examples show the class in use. - The following examples show the class in use. - -#### Example 1 +#### Example 1 + + There are three classes with an inheritance relationship. - There are three classes with an inheritance relationship. - [!code-csharp[C_KnownTypeAttribute#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_knowntypeattribute/cs/source.cs#1)] - [!code-vb[C_KnownTypeAttribute#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#1)] - - The following `CompanyLogo` class can be serialized, but cannot be deserialized if the `ShapeOfLogo` member is set to either a `CircleType` or a `TriangleType` object, because the deserialization engine does not recognize any types with data contract names "Circle" or "Triangle." - + [!code-vb[C_KnownTypeAttribute#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#1)] + + The following `CompanyLogo` class can be serialized, but cannot be deserialized if the `ShapeOfLogo` member is set to either a `CircleType` or a `TriangleType` object, because the deserialization engine does not recognize any types with data contract names "Circle" or "Triangle." + [!code-csharp[C_KnownTypeAttribute#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_knowntypeattribute/cs/source.cs#2)] - [!code-vb[C_KnownTypeAttribute#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#2)] - - The correct way to write the `CompanyLogo` type is shown in the following code. - + [!code-vb[C_KnownTypeAttribute#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#2)] + + The correct way to write the `CompanyLogo` type is shown in the following code. + [!code-csharp[C_KnownTypeAttribute#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_knowntypeattribute/cs/source.cs#3)] - [!code-vb[C_KnownTypeAttribute#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#3)] - - Whenever the outer type `CompanyLogo2` is being deserialized, the deserialization engine knows about `CircleType` and `TriangleType` and, therefore, is able to find matching types for the "Circle" and "Triangle" data contracts. - -#### Example 2 - - In the following example, even though both `CustomerTypeA` and `CustomerTypeB` have the `Customer` data contract, an instance of `CustomerTypeB` is created whenever a `PurchaseOrder` is deserialized, because only `CustomerTypeB` is known to the deserialization engine. - + [!code-vb[C_KnownTypeAttribute#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#3)] + + Whenever the outer type `CompanyLogo2` is being deserialized, the deserialization engine knows about `CircleType` and `TriangleType` and, therefore, is able to find matching types for the "Circle" and "Triangle" data contracts. + +#### Example 2 + + In the following example, even though both `CustomerTypeA` and `CustomerTypeB` have the `Customer` data contract, an instance of `CustomerTypeB` is created whenever a `PurchaseOrder` is deserialized, because only `CustomerTypeB` is known to the deserialization engine. + [!code-csharp[C_KnownTypeAttribute#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_knowntypeattribute/cs/source.cs#4)] - [!code-vb[C_KnownTypeAttribute#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#4)] - -#### Example 3 + [!code-vb[C_KnownTypeAttribute#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#4)] + +#### Example 3 + + In the following example, a stores its contents internally as . To successfully deserialize a hash table, the deserialization engine must know the set of possible types that can occur there. In this case, we know in advance that only `Book` and `Magazine` objects are stored in the `Catalog`, so those are added using the attribute. - In the following example, a stores its contents internally as . To successfully deserialize a hash table, the deserialization engine must know the set of possible types that can occur there. In this case, we know in advance that only `Book` and `Magazine` objects are stored in the `Catalog`, so those are added using the attribute. - [!code-csharp[C_KnownTypeAttribute#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_knowntypeattribute/cs/source.cs#5)] - [!code-vb[C_KnownTypeAttribute#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#5)] - -#### Example 4 + [!code-vb[C_KnownTypeAttribute#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#5)] + +#### Example 4 + + In the following example, a data contract stores a number and an operation to perform on the number. The `Numbers` data member can be an integer, an array of integers, or a that contains integers. - In the following example, a data contract stores a number and an operation to perform on the number. The `Numbers` data member can be an integer, an array of integers, or a that contains integers. - > [!CAUTION] -> This will only work on the client side if SVCUTIL.EXE is used to generate a WCF proxy. SVCUTIL.EXE retrieves metadata from the service including any known types. Without this information a client will not be able to deserialize the types. - +> This will only work on the client side if SVCUTIL.EXE is used to generate a WCF proxy. SVCUTIL.EXE retrieves metadata from the service including any known types. Without this information a client will not be able to deserialize the types. + [!code-csharp[C_KnownTypeAttribute#6](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_knowntypeattribute/cs/source.cs#6)] - [!code-vb[C_KnownTypeAttribute#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#6)] - - This is the application code. - + [!code-vb[C_KnownTypeAttribute#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#6)] + + This is the application code. + [!code-csharp[C_KnownTypeAttribute#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_knowntypeattribute/cs/source.cs#7)] - [!code-vb[C_KnownTypeAttribute#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#7)] - -## Known Types, Inheritance, and Interfaces + [!code-vb[C_KnownTypeAttribute#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#7)] + +## Known Types, Inheritance, and Interfaces + + When a known type is associated with a particular type using the `KnownTypeAttribute` attribute, the known type is also associated with all of the derived types of that type. For example, see the following code. - When a known type is associated with a particular type using the `KnownTypeAttribute` attribute, the known type is also associated with all of the derived types of that type. For example, see the following code. - [!code-csharp[C_KnownTypeAttribute#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_knowntypeattribute/cs/source.cs#8)] - [!code-vb[C_KnownTypeAttribute#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#8)] - - The `DoubleDrawing` class does not require the `KnownTypeAttribute` attribute to use `Square` and `Circle` in the `AdditionalShape` field, because the base class (`Drawing`) already has these attributes applied. - - Known types can be associated only with classes and structures, not interfaces. - -## Known Types Using Open Generic Methods - - It may be necessary to add a generic type as a known type. However, an open generic type cannot be passed as a parameter to the `KnownTypeAttribute` attribute. - - This problem can be solved by using an alternative mechanism: Write a method that returns a list of types to add to the known types collection. The name of the method is then specified as a string argument to the `KnownTypeAttribute` attribute due to some restrictions. - - The method must exist on the type to which the `KnownTypeAttribute` attribute is applied, must be static, must accept no parameters, and must return an object that can be assigned to of . - - You cannot combine the `KnownTypeAttribute` attribute with a method name and `KnownTypeAttribute` attributes with actual types on the same type. Furthermore, you cannot apply more than one `KnownTypeAttribute` with a method name to the same type. - - See the following class. - + [!code-vb[C_KnownTypeAttribute#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#8)] + + The `DoubleDrawing` class does not require the `KnownTypeAttribute` attribute to use `Square` and `Circle` in the `AdditionalShape` field, because the base class (`Drawing`) already has these attributes applied. + + Known types can be associated only with classes and structures, not interfaces. + +## Known Types Using Open Generic Methods + + It may be necessary to add a generic type as a known type. However, an open generic type cannot be passed as a parameter to the `KnownTypeAttribute` attribute. + + This problem can be solved by using an alternative mechanism: Write a method that returns a list of types to add to the known types collection. The name of the method is then specified as a string argument to the `KnownTypeAttribute` attribute due to some restrictions. + + The method must exist on the type to which the `KnownTypeAttribute` attribute is applied, must be static, must accept no parameters, and must return an object that can be assigned to of . + + You cannot combine the `KnownTypeAttribute` attribute with a method name and `KnownTypeAttribute` attributes with actual types on the same type. Furthermore, you cannot apply more than one `KnownTypeAttribute` with a method name to the same type. + + See the following class. + [!code-csharp[C_KnownTypeAttribute#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_knowntypeattribute/cs/source.cs#9)] - [!code-vb[C_KnownTypeAttribute#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#9)] - - The `theDrawing` field contains instances of a generic class `ColorDrawing` and a generic class `BlackAndWhiteDrawing`, both of which inherit from a generic class `Drawing`. Normally, both must be added to known types, but the following is not valid syntax for attributes. - -```csharp -// Invalid syntax for attributes: -// [KnownType(typeof(ColorDrawing))] -// [KnownType(typeof(BlackAndWhiteDrawing))] -``` - -```vb -' Invalid syntax for attributes: -' -``` - - Thus, a method must be created to return these types. The correct way to write this type, then, is shown in the following code. - + [!code-vb[C_KnownTypeAttribute#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#9)] + + The `theDrawing` field contains instances of a generic class `ColorDrawing` and a generic class `BlackAndWhiteDrawing`, both of which inherit from a generic class `Drawing`. Normally, both must be added to known types, but the following is not valid syntax for attributes. + +```csharp +// Invalid syntax for attributes: +// [KnownType(typeof(ColorDrawing))] +// [KnownType(typeof(BlackAndWhiteDrawing))] +``` + +```vb +' Invalid syntax for attributes: +' +``` + + Thus, a method must be created to return these types. The correct way to write this type, then, is shown in the following code. + [!code-csharp[C_KnownTypeAttribute#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_knowntypeattribute/cs/source.cs#10)] - [!code-vb[C_KnownTypeAttribute#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#10)] - -## Additional Ways to Add Known Types - - Additionally, known types can be added through a configuration file. This is useful when you do not control the type that requires known types for proper deserialization, such as when using third-party type libraries with Windows Communication Foundation (WCF). - - The following configuration file shows how to specify a known type in a configuration file. - - `` - - `` - - `` - - `` - - `` - - `` - - `` - - `` - - `` - - `` - - `` - - In the preceding configuration file a data contract type called `MyCompany.Library.Shape` is declared to have `MyCompany.Library.Circle` as a known type. - + [!code-vb[C_KnownTypeAttribute#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_knowntypeattribute/vb/source.vb#10)] + +## Additional Ways to Add Known Types + + Additionally, known types can be added through a configuration file. This is useful when you do not control the type that requires known types for proper deserialization, such as when using third-party type libraries with Windows Communication Foundation (WCF). + + The following configuration file shows how to specify a known type in a configuration file. + + `` + + `` + + `` + + `` + + `` + + `` + + `` + + `` + + `` + + `` + + `` + + In the preceding configuration file a data contract type called `MyCompany.Library.Shape` is declared to have `MyCompany.Library.Circle` as a known type. + ## See also - - - - -- +- - [Known Types](../samples/known-types.md) - [Data Contract Equivalence](data-contract-equivalence.md) - [Designing Service Contracts](../designing-service-contracts.md) diff --git a/docs/framework/wcf/feature-details/data-contract-names.md b/docs/framework/wcf/feature-details/data-contract-names.md index bc646d106c87e..7502d0870c24d 100644 --- a/docs/framework/wcf/feature-details/data-contract-names.md +++ b/docs/framework/wcf/feature-details/data-contract-names.md @@ -2,10 +2,10 @@ title: "Data Contract Names" description: Discover data contract and member naming rules and default behavior of the WCF infrastructure, which support communication by using equivalent data contracts. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "data contracts [WCF], naming" ms.assetid: 31f87e6c-247b-48f5-8e94-b9e1e33d8d09 --- @@ -27,7 +27,7 @@ Basic rules regarding naming data contracts include: A data contract namespace takes the form of a Uniform Resource Identifier (URI). The URI can be either absolute or relative. By default, data contracts for a particular type are assigned a namespace that comes from the common language runtime (CLR) namespace of that type. -By default, any given CLR namespace (in the format *Clr.Namespace*) is mapped to the namespace `http://schemas.datacontract.org/2004/07/Clr.Namespace`. To override this default, apply the attribute to the entire module or assembly. Alternatively, to control the data contract namespace for each type, set the property of the . +By default, any given CLR namespace (in the format *Clr.Namespace*) is mapped to the namespace `http://schemas.datacontract.org/2004/07/Clr.Namespace`. To override this default, apply the attribute to the entire module or assembly. Alternatively, to control the data contract namespace for each type, set the property of the . > [!NOTE] > The `http://schemas.microsoft.com/2003/10/Serialization` namespace is reserved and cannot be used as a data contract namespace. @@ -37,11 +37,11 @@ By default, any given CLR namespace (in the format *Clr.Namespace*) is mapped to ## Data Contract Names -The default name of a data contract for a given type is the name of that type. To override the default, set the property of the to an alternative name. Special rules for generic types are described in "Data Contract Names for Generic Types" later in this topic. +The default name of a data contract for a given type is the name of that type. To override the default, set the property of the to an alternative name. Special rules for generic types are described in "Data Contract Names for Generic Types" later in this topic. ## Data Member Names -The default name of a data member for a given field or property is the name of that field or property. To override the default, set the property of the to an alternative value. +The default name of a data member for a given field or property is the name of that field or property. To override the default, set the property of the to an alternative value. ### Examples @@ -65,14 +65,14 @@ In this example, the type `Drawing` has the data contrac ## Customizing data contract names for generic types -Sometimes, the data contract names generated for generic types, as described previously, are unacceptable. For example, you may know in advance that you will not run into name collisions and may want to remove the hash. In this case, you can use the property to specify a different way to generate names. You can use numbers in curly braces inside of the `Name` property to refer to data contract names of the generic parameters. (0 refers to the first parameter, 1 refers to the second, and so on.) You can use a number (#) sign inside curly braces to refer to the hash. You can use each of these references multiple times or not at all. +Sometimes, the data contract names generated for generic types, as described previously, are unacceptable. For example, you may know in advance that you will not run into name collisions and may want to remove the hash. In this case, you can use the property to specify a different way to generate names. You can use numbers in curly braces inside of the `Name` property to refer to data contract names of the generic parameters. (0 refers to the first parameter, 1 refers to the second, and so on.) You can use a number (#) sign inside curly braces to refer to the hash. You can use each of these references multiple times or not at all. For example, the preceding generic `Drawing` type could have been declared as shown in the following example. [!code-csharp[c_DataContractNames#3](~/samples/snippets/csharp/VS_Snippets_CFX/c_datacontractnames/cs/source.cs#3)] [!code-vb[c_DataContractNames#3](~/samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractnames/vb/source.vb#3)] -In this case, the type `Drawing` has the data contract name "Drawing_using_RedBrush_brush_and_Square_shape". Note that because there is a "{#}" in the property, the hash is not a part of the name, and thus the type is susceptible to naming collisions; for example, the type `Drawing` would have exactly the same data contract name. +In this case, the type `Drawing` has the data contract name "Drawing_using_RedBrush_brush_and_Square_shape". Note that because there is a "{#}" in the property, the hash is not a part of the name, and thus the type is susceptible to naming collisions; for example, the type `Drawing` would have exactly the same data contract name. ## See also diff --git a/docs/framework/wcf/feature-details/data-contract-schema-reference.md b/docs/framework/wcf/feature-details/data-contract-schema-reference.md index 43368ee6a5fcf..7ec73cf3c7989 100644 --- a/docs/framework/wcf/feature-details/data-contract-schema-reference.md +++ b/docs/framework/wcf/feature-details/data-contract-schema-reference.md @@ -160,7 +160,7 @@ The rules for the `ref`, `block`, `default`, `fixed`, `form`, and `id` attribute |Attribute|Schema| |---------------|------------| -|`name`|Supported, maps to the property in the `CollectionDataContractAttribute` attribute.| +|`name`|Supported, maps to the property in the `CollectionDataContractAttribute` attribute.| |`type`|Supported, maps to the type stored in the collection.| |`maxOccurs`|Greater than 1 or "unbounded". The DC schema should use "unbounded".| |`minOccurs`|Ignored.| @@ -619,7 +619,7 @@ The following should be noted: ## Importing non-DataContract schemas -`DataContractSerializer` has the `ImportXmlTypes` option to allow import of schemas that do not conform to the `DataContractSerializer` XSD profile (see the property). Setting this option to `true` enables acceptance of non-conforming schema types and mapping them to the following implementation, wrapping an array of (only the class name differs). +`DataContractSerializer` has the `ImportXmlTypes` option to allow import of schemas that do not conform to the `DataContractSerializer` XSD profile (see the property). Setting this option to `true` enables acceptance of non-conforming schema types and mapping them to the following implementation, wrapping an array of (only the class name differs). ```csharp [GeneratedCodeAttribute("System.Runtime.Serialization", "3.0.0.0")] diff --git a/docs/framework/wcf/feature-details/data-contract-versioning.md b/docs/framework/wcf/feature-details/data-contract-versioning.md index 9765e68a554eb..298cec0b9699b 100644 --- a/docs/framework/wcf/feature-details/data-contract-versioning.md +++ b/docs/framework/wcf/feature-details/data-contract-versioning.md @@ -2,10 +2,10 @@ description: "Learn more about: Data Contract Versioning" title: "Data Contract Versioning" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "versioning [WCF], data contracts" - "versioning [WCF]" - "data contracts [WCF], versioning" @@ -13,119 +13,119 @@ ms.assetid: 4a0700cb-5f5f-4137-8705-3a3ecf06461f --- # Data Contract Versioning -As applications evolve, you may also have to change the data contracts the services use. This topic explains how to version data contracts. This topic describes the data contract versioning mechanisms. For a complete overview and prescriptive versioning guidance, see [Best Practices: Data Contract Versioning](../best-practices-data-contract-versioning.md). - -## Breaking vs. Nonbreaking Changes +As applications evolve, you may also have to change the data contracts the services use. This topic explains how to version data contracts. This topic describes the data contract versioning mechanisms. For a complete overview and prescriptive versioning guidance, see [Best Practices: Data Contract Versioning](../best-practices-data-contract-versioning.md). + +## Breaking vs. Nonbreaking Changes + + Changes to a data contract can be breaking or nonbreaking. When a data contract is changed in a nonbreaking way, an application using the older version of the contract can communicate with an application using the newer version, and an application using the newer version of the contract can communicate with an application using the older version. On the other hand, a breaking change prevents communication in one or both directions. + + Any changes to a type that do not affect how it is transmitted and received are nonbreaking. Such changes do not change the data contract, only the underlying type. For example, you can change the name of a field in a nonbreaking way if you then set the property of the to the older version name. The following code shows version 1 of a data contract. - Changes to a data contract can be breaking or nonbreaking. When a data contract is changed in a nonbreaking way, an application using the older version of the contract can communicate with an application using the newer version, and an application using the newer version of the contract can communicate with an application using the older version. On the other hand, a breaking change prevents communication in one or both directions. - - Any changes to a type that do not affect how it is transmitted and received are nonbreaking. Such changes do not change the data contract, only the underlying type. For example, you can change the name of a field in a nonbreaking way if you then set the property of the to the older version name. The following code shows version 1 of a data contract. - [!code-csharp[C_DataContractVersioning#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractversioning/cs/source.cs#1)] - [!code-vb[C_DataContractVersioning#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractversioning/vb/source.vb#1)] - - The following code shows a nonbreaking change. - + [!code-vb[C_DataContractVersioning#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractversioning/vb/source.vb#1)] + + The following code shows a nonbreaking change. + [!code-csharp[C_DataContractVersioning#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractversioning/cs/source.cs#2)] - [!code-vb[C_DataContractVersioning#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractversioning/vb/source.vb#2)] - - Some changes do modify the transmitted data, but may or may not be breaking. The following changes are always breaking: - -- Changing the or value of a data contract. - -- Changing the order of data members by using the property of the . - -- Renaming a data member. - -- Changing the data contract of a data member. For example, changing the type of data member from an integer to a string, or from a type with a data contract named "Customer" to a type with a data contract named "Person". - - The following changes are also possible. - -## Adding and Removing Data Members - - In most cases, adding or removing a data member is not a breaking change, unless you require strict schema validity (new instances validating against the old schema). - - When a type with an extra field is deserialized into a type with a missing field, the extra information is ignored. (It may also be stored for round-tripping purposes; for more information, see [Forward-Compatible Data Contracts](forward-compatible-data-contracts.md)). - - When a type with a missing field is deserialized into a type with an extra field, the extra field is left at its default value, usually zero or `null`. (The default value may be changed; for more information, see [Version-Tolerant Serialization Callbacks](version-tolerant-serialization-callbacks.md).) - - For example, you can use the `CarV1` class on a client and the `CarV2` class on a service, or you can use the `CarV1` class on a service and the `CarV2` class on a client. - + [!code-vb[C_DataContractVersioning#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractversioning/vb/source.vb#2)] + + Some changes do modify the transmitted data, but may or may not be breaking. The following changes are always breaking: + +- Changing the or value of a data contract. + +- Changing the order of data members by using the property of the . + +- Renaming a data member. + +- Changing the data contract of a data member. For example, changing the type of data member from an integer to a string, or from a type with a data contract named "Customer" to a type with a data contract named "Person". + + The following changes are also possible. + +## Adding and Removing Data Members + + In most cases, adding or removing a data member is not a breaking change, unless you require strict schema validity (new instances validating against the old schema). + + When a type with an extra field is deserialized into a type with a missing field, the extra information is ignored. (It may also be stored for round-tripping purposes; for more information, see [Forward-Compatible Data Contracts](forward-compatible-data-contracts.md)). + + When a type with a missing field is deserialized into a type with an extra field, the extra field is left at its default value, usually zero or `null`. (The default value may be changed; for more information, see [Version-Tolerant Serialization Callbacks](version-tolerant-serialization-callbacks.md).) + + For example, you can use the `CarV1` class on a client and the `CarV2` class on a service, or you can use the `CarV1` class on a service and the `CarV2` class on a client. + [!code-csharp[C_DataContractVersioning#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractversioning/cs/source.cs#3)] - [!code-vb[C_DataContractVersioning#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractversioning/vb/source.vb#3)] - - The version 2 endpoint can successfully send data to the version 1 endpoint. Serializing version 2 of the `Car` data contract yields XML similar to the following. - -```xml - - Porsche - 300 - -``` - - The deserialization engine on V1 does not find a matching data member for the `HorsePower` field, and discards that data. - - Also, the version 1 endpoint can send data to the version 2 endpoint. Serializing version 1 of the `Car` data contract yields XML similar to the following. - -```xml - - Porsche - -``` - - The version 2 deserializer does not know what to set the `HorsePower` field to, because there is no matching data in the incoming XML. Instead, the field is set to the default value of 0. - -## Required Data Members - - A data member may be marked as being required by setting the property of the to `true`. If required data is missing while deserializing, an exception is thrown instead of setting the data member to its default value. - - Adding a required data member is a breaking change. That is, the newer type can still be sent to endpoints with the older type, but not the other way around. Removing a data member that was marked as required in any prior version is also a breaking change. - - Changing the property value from `true` to `false` is not breaking, but changing it from `false` to `true` may be breaking if any prior versions of the type do not have the data member in question. - + [!code-vb[C_DataContractVersioning#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractversioning/vb/source.vb#3)] + + The version 2 endpoint can successfully send data to the version 1 endpoint. Serializing version 2 of the `Car` data contract yields XML similar to the following. + +```xml + + Porsche + 300 + +``` + + The deserialization engine on V1 does not find a matching data member for the `HorsePower` field, and discards that data. + + Also, the version 1 endpoint can send data to the version 2 endpoint. Serializing version 1 of the `Car` data contract yields XML similar to the following. + +```xml + + Porsche + +``` + + The version 2 deserializer does not know what to set the `HorsePower` field to, because there is no matching data in the incoming XML. Instead, the field is set to the default value of 0. + +## Required Data Members + + A data member may be marked as being required by setting the property of the to `true`. If required data is missing while deserializing, an exception is thrown instead of setting the data member to its default value. + + Adding a required data member is a breaking change. That is, the newer type can still be sent to endpoints with the older type, but not the other way around. Removing a data member that was marked as required in any prior version is also a breaking change. + + Changing the property value from `true` to `false` is not breaking, but changing it from `false` to `true` may be breaking if any prior versions of the type do not have the data member in question. + > [!NOTE] -> Although the property is set to `true`, the incoming data may be null or zero, and a type must be prepared to handle this possibility. Do not use as a security mechanism to protect against bad incoming data. - -## Omitted Default Values - - It is possible (although not recommended) to set the `EmitDefaultValue` property on the DataMemberAttribute attribute to `false`, as described in [Data Member Default Values](data-member-default-values.md). If this setting is `false`, the data member will not be emitted if it is set to its default value (usually null or zero). This is not compatible with required data members in different versions in two ways: - -- A data contract with a data member that is required in one version cannot receive default (null or zero) data from a different version in which the data member has `EmitDefaultValue` set to `false`. - -- A required data member that has `EmitDefaultValue` set to `false` cannot be used to serialize its default (null or zero) value, but can receive such a value on deserialization. This creates a round-tripping problem (data can be read in but the same data cannot then be written out). Therefore, if `IsRequired` is `true` and `EmitDefaultValue` is `false` in one version, the same combination should apply to all other versions such that no version of the data contract would be able to produce a value that does not result in a round trip. - -## Schema Considerations - - For an explanation of what schema is produced for data contract types, see [Data Contract Schema Reference](data-contract-schema-reference.md). - - The schema WCF produces for data contract types makes no provisions for versioning. That is, the schema exported from a certain version of a type contains only those data members present in that version. Implementing the interface does not change the schema for a type. - - Data members are exported to the schema as optional elements by default. That is, the `minOccurs` (XML attribute) value is set to 0. Required data members are exported with `minOccurs` set to 1. - - Many of the changes considered to be nonbreaking are actually breaking if strict adherence to the schema is required. In the preceding example, a `CarV1` instance with just the `Model` element would validate against the `CarV2` schema (which has both `Model` and `Horsepower`, but both are optional). However, the reverse is not true: a `CarV2` instance would fail validation against the `CarV1` schema. - - Round-tripping also entails some additional considerations. For more information, see the "Schema Considerations" section in [Forward-Compatible Data Contracts](forward-compatible-data-contracts.md). - -### Other Permitted Changes - - Implementing the interface is a nonbreaking change. However, round-tripping support does not exist for versions of the type prior to the version in which was implemented. For more information, see [Forward-Compatible Data Contracts](forward-compatible-data-contracts.md). - -## Enumerations - - Adding or removing an enumeration member is a breaking change. Changing the name of an enumeration member is breaking, unless its contract name is kept the same as in the old version by using the `EnumMemberAttribute` attribute. For more information, see [Enumeration Types in Data Contracts](enumeration-types-in-data-contracts.md). - -## Collections - - Most collection changes are nonbreaking because most collection types are interchangeable with each other in the data contract model. However, making a noncustomized collection customized or vice versa is a breaking change. Also, changing the collection's customization settings is a breaking change; that is, changing its data contract name and namespace, repeating element name, key element name, and value element name. For more information about collection customization, see [Collection Types in Data Contracts](collection-types-in-data-contracts.md). -Naturally, changing the data contract of contents of a collection (for example, changing from a list of integers to a list of strings) is a breaking change. - +> Although the property is set to `true`, the incoming data may be null or zero, and a type must be prepared to handle this possibility. Do not use as a security mechanism to protect against bad incoming data. + +## Omitted Default Values + + It is possible (although not recommended) to set the `EmitDefaultValue` property on the DataMemberAttribute attribute to `false`, as described in [Data Member Default Values](data-member-default-values.md). If this setting is `false`, the data member will not be emitted if it is set to its default value (usually null or zero). This is not compatible with required data members in different versions in two ways: + +- A data contract with a data member that is required in one version cannot receive default (null or zero) data from a different version in which the data member has `EmitDefaultValue` set to `false`. + +- A required data member that has `EmitDefaultValue` set to `false` cannot be used to serialize its default (null or zero) value, but can receive such a value on deserialization. This creates a round-tripping problem (data can be read in but the same data cannot then be written out). Therefore, if `IsRequired` is `true` and `EmitDefaultValue` is `false` in one version, the same combination should apply to all other versions such that no version of the data contract would be able to produce a value that does not result in a round trip. + +## Schema Considerations + + For an explanation of what schema is produced for data contract types, see [Data Contract Schema Reference](data-contract-schema-reference.md). + + The schema WCF produces for data contract types makes no provisions for versioning. That is, the schema exported from a certain version of a type contains only those data members present in that version. Implementing the interface does not change the schema for a type. + + Data members are exported to the schema as optional elements by default. That is, the `minOccurs` (XML attribute) value is set to 0. Required data members are exported with `minOccurs` set to 1. + + Many of the changes considered to be nonbreaking are actually breaking if strict adherence to the schema is required. In the preceding example, a `CarV1` instance with just the `Model` element would validate against the `CarV2` schema (which has both `Model` and `Horsepower`, but both are optional). However, the reverse is not true: a `CarV2` instance would fail validation against the `CarV1` schema. + + Round-tripping also entails some additional considerations. For more information, see the "Schema Considerations" section in [Forward-Compatible Data Contracts](forward-compatible-data-contracts.md). + +### Other Permitted Changes + + Implementing the interface is a nonbreaking change. However, round-tripping support does not exist for versions of the type prior to the version in which was implemented. For more information, see [Forward-Compatible Data Contracts](forward-compatible-data-contracts.md). + +## Enumerations + + Adding or removing an enumeration member is a breaking change. Changing the name of an enumeration member is breaking, unless its contract name is kept the same as in the old version by using the `EnumMemberAttribute` attribute. For more information, see [Enumeration Types in Data Contracts](enumeration-types-in-data-contracts.md). + +## Collections + + Most collection changes are nonbreaking because most collection types are interchangeable with each other in the data contract model. However, making a noncustomized collection customized or vice versa is a breaking change. Also, changing the collection's customization settings is a breaking change; that is, changing its data contract name and namespace, repeating element name, key element name, and value element name. For more information about collection customization, see [Collection Types in Data Contracts](collection-types-in-data-contracts.md). +Naturally, changing the data contract of contents of a collection (for example, changing from a list of integers to a list of strings) is a breaking change. + ## See also -- +- - -- -- -- +- +- +- - - - diff --git a/docs/framework/wcf/feature-details/data-member-order.md b/docs/framework/wcf/feature-details/data-member-order.md index 005e520b8d170..088406c616a59 100644 --- a/docs/framework/wcf/feature-details/data-member-order.md +++ b/docs/framework/wcf/feature-details/data-member-order.md @@ -2,64 +2,64 @@ title: "Data Member Order" description: Learn about data member order in WCF. Applications might need to know or change the order in which data members are sent or expected. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "data contracts [WCF], ordering members" ms.assetid: 0658a47d-b6e5-4ae0-ba72-ababc3c6ff33 --- # Data Member Order -In some applications, it is useful to know the order in which data from the various data members is sent or is expected to be received (such as the order in which data appears in the serialized XML). Sometimes it may be necessary to change this order. This topic explains the ordering rules. - -## Basic Rules - - The basic rules for data ordering include: - -- If a data contract type is a part of an inheritance hierarchy, data members of its base types are always first in the order. - -- Next in order are the current type’s data members that do not have the property of the attribute set, in alphabetical order. - -- Next are any data members that have the property of the attribute set. These are ordered by the value of the `Order` property first and then alphabetically if there is more than one member of a certain `Order` value. Order values may be skipped. - - Alphabetical order is established by calling the method. - -## Examples - - Consider the following code. - +In some applications, it is useful to know the order in which data from the various data members is sent or is expected to be received (such as the order in which data appears in the serialized XML). Sometimes it may be necessary to change this order. This topic explains the ordering rules. + +## Basic Rules + + The basic rules for data ordering include: + +- If a data contract type is a part of an inheritance hierarchy, data members of its base types are always first in the order. + +- Next in order are the current type’s data members that do not have the property of the attribute set, in alphabetical order. + +- Next are any data members that have the property of the attribute set. These are ordered by the value of the `Order` property first and then alphabetically if there is more than one member of a certain `Order` value. Order values may be skipped. + + Alphabetical order is established by calling the method. + +## Examples + + Consider the following code. + [!code-csharp[C_DataContractNames#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractnames/cs/source.cs#4)] - [!code-vb[C_DataContractNames#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractnames/vb/source.vb#4)] - - The XML produced is similar to the following. - -```xml - - + [!code-vb[C_DataContractNames#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractnames/vb/source.vb#4)] + + The XML produced is similar to the following. + +```xml + + - - - - - + + + + + - - - - - - - - - - - + + + + + + + + + + + - -``` - + +``` + ## See also - diff --git a/docs/framework/wcf/feature-details/data-transfer-architectural-overview.md b/docs/framework/wcf/feature-details/data-transfer-architectural-overview.md index cf9432ab4a6ec..018b121fbe2df 100644 --- a/docs/framework/wcf/feature-details/data-transfer-architectural-overview.md +++ b/docs/framework/wcf/feature-details/data-transfer-architectural-overview.md @@ -102,7 +102,7 @@ Windows Communication Foundation (WCF) can be thought of as a messaging infrastr Unlike the message body and message headers (which normally map to the SOAP body and SOAP headers, respectively), message properties are normally not sent or received along with the messages. Message properties exist primarily as a communication mechanism to pass data about the message between the various channels in the channel stack, and between the channel stack and the service model. - For example, the HTTP transport channel included as part of WCF is capable of producing various HTTP status codes, such as "404 (Not Found)" and "500 (Internal Server Error)," when it sends replies to clients. Before sending a reply message, it checks to see whether the `Properties` of the `Message` contain a property called "httpResponse" that contains an object of type . If such a property is found, it will look at the property and use that status code. If it is not found, the default "200 (OK)" code is used. + For example, the HTTP transport channel included as part of WCF is capable of producing various HTTP status codes, such as "404 (Not Found)" and "500 (Internal Server Error)," when it sends replies to clients. Before sending a reply message, it checks to see whether the `Properties` of the `Message` contain a property called "httpResponse" that contains an object of type . If such a property is found, it will look at the property and use that status code. If it is not found, the default "200 (OK)" code is used. For more information, see [Using the Message Class](using-the-message-class.md). @@ -283,11 +283,11 @@ Windows Communication Foundation (WCF) can be thought of as a messaging infrastr ## Serialization - Whenever you use message contracts or parameters to describe message contents, you must use serialization to convert between .NET Framework types and XML Infoset representation. Serialization is used in other places in WCF, for example, has a Generic method that you can use to read the entire body of the message deserialized into an object. + Whenever you use message contracts or parameters to describe message contents, you must use serialization to convert between .NET Framework types and XML Infoset representation. Serialization is used in other places in WCF, for example, has a Generic method that you can use to read the entire body of the message deserialized into an object. WCF supports two serialization technologies "out of the box" for serializing and deserializing parameters and message parts: the and the `XmlSerializer`. Additionally, you can write custom serializers. However, other parts of WCF (such as the Generic `GetBody` method or SOAP fault serialization) may be restricted to use only the subclasses ( and , but not the ), or may even be hard-coded to use only the . - The `XmlSerializer` is the serialization engine used in ASP.NET Web services. The `DataContractSerializer` is the new serialization engine that understands the new data contract programming model. `DataContractSerializer` is the default choice, and the choice to use the `XmlSerializer` can be made on a per-operation basis using the attribute. + The `XmlSerializer` is the serialization engine used in ASP.NET Web services. The `DataContractSerializer` is the new serialization engine that understands the new data contract programming model. `DataContractSerializer` is the default choice, and the choice to use the `XmlSerializer` can be made on a per-operation basis using the attribute. and are the operation behaviors responsible for plugging in the message formatters for the `DataContractSerializer` and the `XmlSerializer`, respectively. The behavior can actually operate with any serializer that derives from , including the (described in detail in Using Stand-Alone Serialization). The behavior calls one of the `CreateSerializer` virtual method overloads to obtain the serializer. To plug in a different serializer, create a new subclass and override both `CreateSerializer` overloads. diff --git a/docs/framework/wcf/feature-details/debugging-windows-authentication-errors.md b/docs/framework/wcf/feature-details/debugging-windows-authentication-errors.md index 8242fccf28f44..b1281509efdcd 100644 --- a/docs/framework/wcf/feature-details/debugging-windows-authentication-errors.md +++ b/docs/framework/wcf/feature-details/debugging-windows-authentication-errors.md @@ -2,10 +2,10 @@ description: "Learn more about: Debug Windows authentication errors" title: "Debugging Windows Authentication Errors" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "WCF, authentication" - "WCF, Windows authentication" ms.assetid: 181be4bd-79b1-4a66-aee2-931887a6d7cc @@ -13,151 +13,151 @@ ms.custom: sfi-ropc-nochange --- # Debug Windows authentication errors -When using Windows authentication as a security mechanism, the Security Support Provider Interface (SSPI) handles security processes. When security errors occur at the SSPI layer, they are surfaced by Windows Communication Foundation (WCF). This topic provides a framework and set of questions to help diagnose the errors. - - For an overview of the Kerberos protocol, see [Kerberos Explained](/previous-versions/windows/it-pro/windows-2000-server/bb742516(v=technet.10)); for an overview of SSPI, see [SSPI](/windows/win32/secauthn/sspi). - - For Windows authentication, WCF typically uses the *Negotiate* Security Support Provider (SSP), which performs Kerberos mutual authentication between the client and service. If the Kerberos protocol is not available, by default WCF falls back to NT LAN Manager (NTLM). However, you can configure WCF to use only the Kerberos protocol (and to throw an exception if Kerberos is not available). You can also configure WCF to use restricted forms of the Kerberos protocol. - -## Debugging Methodology - - The basic method is as follows: - -1. Determine whether you are using Windows authentication. If you are using any other scheme, this topic does not apply. - -2. If you are sure you are using Windows authentication, determine whether your WCF configuration uses Kerberos direct or Negotiate. - -3. Once you have determined whether your configuration is using the Kerberos protocol or NTLM, you can understand error messages in the correct context. - -### Availability of the Kerberos Protocol and NTLM - - The Kerberos SSP requires a domain controller to act as the Kerberos Key Distribution Center (KDC). The Kerberos protocol is available only when both the client and service are using domain identities. In other account combinations, NTLM is used, as summarized in the following table. - - The table headers show possible account types used by the server. The left column shows possible account types used by the client. - +When using Windows authentication as a security mechanism, the Security Support Provider Interface (SSPI) handles security processes. When security errors occur at the SSPI layer, they are surfaced by Windows Communication Foundation (WCF). This topic provides a framework and set of questions to help diagnose the errors. + + For an overview of the Kerberos protocol, see [Kerberos Explained](/previous-versions/windows/it-pro/windows-2000-server/bb742516(v=technet.10)); for an overview of SSPI, see [SSPI](/windows/win32/secauthn/sspi). + + For Windows authentication, WCF typically uses the *Negotiate* Security Support Provider (SSP), which performs Kerberos mutual authentication between the client and service. If the Kerberos protocol is not available, by default WCF falls back to NT LAN Manager (NTLM). However, you can configure WCF to use only the Kerberos protocol (and to throw an exception if Kerberos is not available). You can also configure WCF to use restricted forms of the Kerberos protocol. + +## Debugging Methodology + + The basic method is as follows: + +1. Determine whether you are using Windows authentication. If you are using any other scheme, this topic does not apply. + +2. If you are sure you are using Windows authentication, determine whether your WCF configuration uses Kerberos direct or Negotiate. + +3. Once you have determined whether your configuration is using the Kerberos protocol or NTLM, you can understand error messages in the correct context. + +### Availability of the Kerberos Protocol and NTLM + + The Kerberos SSP requires a domain controller to act as the Kerberos Key Distribution Center (KDC). The Kerberos protocol is available only when both the client and service are using domain identities. In other account combinations, NTLM is used, as summarized in the following table. + + The table headers show possible account types used by the server. The left column shows possible account types used by the client. + | | Local User | Local System | Domain User | Domain Machine | | ------------------ | -------------- | -------------- | -------------- | -------------- | | **Local User** | NTLM | NTLM | NTLM | NTLM | | **Local System** | Anonymous NTLM | Anonymous NTLM | Anonymous NTLM | Anonymous NTLM | | **Domain User** | NTLM | NTLM | Kerberos | Kerberos | | **Domain Machine** | NTLM | NTLM | Kerberos | Kerberos | - - Specifically, the four account types include: - -- Local User: Machine-only user profile. For example: `MachineName\Administrator` or `MachineName\ProfileName`. - -- Local System: The built-in account SYSTEM on a machine that is not joined to a domain. - -- Domain User: A user account on a Windows domain. For example: `DomainName\ProfileName`. - -- Domain Machine: A process with machine identity running on a machine joined to a Windows domain. For example: `MachineName\Network Service`. - + + Specifically, the four account types include: + +- Local User: Machine-only user profile. For example: `MachineName\Administrator` or `MachineName\ProfileName`. + +- Local System: The built-in account SYSTEM on a machine that is not joined to a domain. + +- Domain User: A user account on a Windows domain. For example: `DomainName\ProfileName`. + +- Domain Machine: A process with machine identity running on a machine joined to a Windows domain. For example: `MachineName\Network Service`. + > [!NOTE] -> The service credential is captured when the method of the class is called. The client credential is read whenever the client sends a message. - -## Common Windows Authentication Problems - - This section discusses some common Windows authentication problems and possible remedies. - -### Kerberos Protocol - -#### SPN/UPN Problems with the Kerberos Protocol - - When using Windows authentication, and the Kerberos protocol is used or negotiated by SSPI, the URL the client endpoint uses must include the fully qualified domain name of the service's host inside the service URL. This assumes that the account under which the service is running has access to the machine (default) service principal name (SPN) key that is created when the computer is added to the Active Directory domain, which is most commonly done by running the service under the Network Service account. If the service does not have access to the machine SPN key, you must supply the correct SPN or user principal name (UPN) of the account under which the service is running in the client's endpoint identity. For more information about how WCF works with SPN and UPN, see [Service Identity and Authentication](service-identity-and-authentication.md). - - In load-balancing scenarios, such as Web farms or Web gardens, a common practice is to define a unique account for each application, assign an SPN to that account, and ensure that all of the application's services run in that account. - - To obtain an SPN for your service's account, you need to be an Active Directory domain administrator. For more information, see [Kerberos Technical Supplement for Windows](/previous-versions/msp-n-p/ff649429(v=pandp.10)). - -#### Kerberos Protocol Direct Requires the Service to Run Under a Domain Machine Account - - This occurs when the `ClientCredentialType` property is set to `Windows` and the property is set to `false`, as shown in the following code. - +> The service credential is captured when the method of the class is called. The client credential is read whenever the client sends a message. + +## Common Windows Authentication Problems + + This section discusses some common Windows authentication problems and possible remedies. + +### Kerberos Protocol + +#### SPN/UPN Problems with the Kerberos Protocol + + When using Windows authentication, and the Kerberos protocol is used or negotiated by SSPI, the URL the client endpoint uses must include the fully qualified domain name of the service's host inside the service URL. This assumes that the account under which the service is running has access to the machine (default) service principal name (SPN) key that is created when the computer is added to the Active Directory domain, which is most commonly done by running the service under the Network Service account. If the service does not have access to the machine SPN key, you must supply the correct SPN or user principal name (UPN) of the account under which the service is running in the client's endpoint identity. For more information about how WCF works with SPN and UPN, see [Service Identity and Authentication](service-identity-and-authentication.md). + + In load-balancing scenarios, such as Web farms or Web gardens, a common practice is to define a unique account for each application, assign an SPN to that account, and ensure that all of the application's services run in that account. + + To obtain an SPN for your service's account, you need to be an Active Directory domain administrator. For more information, see [Kerberos Technical Supplement for Windows](/previous-versions/msp-n-p/ff649429(v=pandp.10)). + +#### Kerberos Protocol Direct Requires the Service to Run Under a Domain Machine Account + + This occurs when the `ClientCredentialType` property is set to `Windows` and the property is set to `false`, as shown in the following code. + [!code-csharp[C_DebuggingWindowsAuth#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_debuggingwindowsauth/cs/source.cs#1)] - [!code-vb[C_DebuggingWindowsAuth#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_debuggingwindowsauth/vb/source.vb#1)] - - To remedy, run the service using a Domain Machine account, such as Network Service, on a domain joined machine. - -### Delegation Requires Credential Negotiation - - To use the Kerberos authentication protocol with delegation, you must implement the Kerberos protocol with credential negotiation (sometimes called "multi-leg" or "multi-step" Kerberos). If you implement Kerberos authentication without credential negotiation (sometimes called "one-shot" or "single-leg" Kerberos), an exception will be thrown. - - To implement Kerberos with credential negotiation, do the following steps: - -1. Implement delegation by setting to . - -2. Require SSPI negotiation: - - 1. If you are using standard bindings, set the `NegotiateServiceCredential` property to `true`. - - 2. If you are using custom bindings, set the `AuthenticationMode` attribute of the `Security` element to `SspiNegotiated`. - -3. Require the SSPI negotiation to use Kerberos by disallowing the use of NTLM: - - 1. Do this in code, with the following statement: `ChannelFactory.Credentials.Windows.AllowNtlm = false` - - 2. Or you can do this in the configuration file by setting the `allowNtlm` attribute to `false`. This attribute is contained in the [\](../../configure-apps/file-schema/wcf/windows-of-clientcredentials-element.md). - -### NTLM Protocol - -#### Negotiate SSP Falls Back to NTLM, but NTLM Is Disabled - - The property is set to `false`, which causes Windows Communication Foundation (WCF) to make a best-effort to throw an exception if NTLM is used. Setting this property to `false` may not prevent NTLM credentials from being sent over the wire. - - The following shows how to disable fallback to NTLM. - + [!code-vb[C_DebuggingWindowsAuth#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_debuggingwindowsauth/vb/source.vb#1)] + + To remedy, run the service using a Domain Machine account, such as Network Service, on a domain joined machine. + +### Delegation Requires Credential Negotiation + + To use the Kerberos authentication protocol with delegation, you must implement the Kerberos protocol with credential negotiation (sometimes called "multi-leg" or "multi-step" Kerberos). If you implement Kerberos authentication without credential negotiation (sometimes called "one-shot" or "single-leg" Kerberos), an exception will be thrown. + + To implement Kerberos with credential negotiation, do the following steps: + +1. Implement delegation by setting to . + +2. Require SSPI negotiation: + + 1. If you are using standard bindings, set the `NegotiateServiceCredential` property to `true`. + + 2. If you are using custom bindings, set the `AuthenticationMode` attribute of the `Security` element to `SspiNegotiated`. + +3. Require the SSPI negotiation to use Kerberos by disallowing the use of NTLM: + + 1. Do this in code, with the following statement: `ChannelFactory.Credentials.Windows.AllowNtlm = false` + + 2. Or you can do this in the configuration file by setting the `allowNtlm` attribute to `false`. This attribute is contained in the [\](../../configure-apps/file-schema/wcf/windows-of-clientcredentials-element.md). + +### NTLM Protocol + +#### Negotiate SSP Falls Back to NTLM, but NTLM Is Disabled + + The property is set to `false`, which causes Windows Communication Foundation (WCF) to make a best-effort to throw an exception if NTLM is used. Setting this property to `false` may not prevent NTLM credentials from being sent over the wire. + + The following shows how to disable fallback to NTLM. + [!code-csharp[C_DebuggingWindowsAuth#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_debuggingwindowsauth/cs/source.cs#4)] - [!code-vb[C_DebuggingWindowsAuth#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_debuggingwindowsauth/vb/source.vb#4)] - -#### NTLM Logon Fails - - The client credentials are not valid on the service. Check that the user name and password are correctly set and correspond to an account that is known to the computer where the service is running. NTLM uses the specified credentials to log on to the service's computer. While the credentials may be valid on the computer where the client is running, this logon will fail if the credentials are not valid on the service's computer. - -#### Anonymous NTLM Logon Occurs, but Anonymous Logons Are Disabled by Default - - When creating a client, the property is set to , as shown in the following example, but by default the server disallows anonymous logons. This occurs because the default value of the property of the class is `false`. - - The following client code attempts to enable anonymous logons (note that the default property is `Identification`). - + [!code-vb[C_DebuggingWindowsAuth#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_debuggingwindowsauth/vb/source.vb#4)] + +#### NTLM Logon Fails + + The client credentials are not valid on the service. Check that the user name and password are correctly set and correspond to an account that is known to the computer where the service is running. NTLM uses the specified credentials to log on to the service's computer. While the credentials may be valid on the computer where the client is running, this logon will fail if the credentials are not valid on the service's computer. + +#### Anonymous NTLM Logon Occurs, but Anonymous Logons Are Disabled by Default + + When creating a client, the property is set to , as shown in the following example, but by default the server disallows anonymous logons. This occurs because the default value of the property of the class is `false`. + + The following client code attempts to enable anonymous logons (note that the default property is `Identification`). + [!code-csharp[C_DebuggingWindowsAuth#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_debuggingwindowsauth/cs/source.cs#5)] - [!code-vb[C_DebuggingWindowsAuth#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_debuggingwindowsauth/vb/source.vb#5)] - - The following service code changes the default to enable anonymous logons by the server. - + [!code-vb[C_DebuggingWindowsAuth#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_debuggingwindowsauth/vb/source.vb#5)] + + The following service code changes the default to enable anonymous logons by the server. + [!code-csharp[C_DebuggingWindowsAuth#6](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_debuggingwindowsauth/cs/source.cs#6)] - [!code-vb[C_DebuggingWindowsAuth#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_debuggingwindowsauth/vb/source.vb#6)] - - For more information about impersonation, see [Delegation and Impersonation](delegation-and-impersonation-with-wcf.md). - - Alternatively, the client is running as a Windows service, using the built-in account SYSTEM. - -### Other Problems - -#### Client Credentials Are Not Set Correctly - - Windows authentication uses the instance returned by the property of the class, not the . The following shows an incorrect example. - + [!code-vb[C_DebuggingWindowsAuth#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_debuggingwindowsauth/vb/source.vb#6)] + + For more information about impersonation, see [Delegation and Impersonation](delegation-and-impersonation-with-wcf.md). + + Alternatively, the client is running as a Windows service, using the built-in account SYSTEM. + +### Other Problems + +#### Client Credentials Are Not Set Correctly + + Windows authentication uses the instance returned by the property of the class, not the . The following shows an incorrect example. + [!code-csharp[C_DebuggingWindowsAuth#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_debuggingwindowsauth/cs/source.cs#2)] - [!code-vb[C_DebuggingWindowsAuth#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_debuggingwindowsauth/vb/source.vb#2)] - - The following shows the correct example. - + [!code-vb[C_DebuggingWindowsAuth#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_debuggingwindowsauth/vb/source.vb#2)] + + The following shows the correct example. + [!code-csharp[C_DebuggingWindowsAuth#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_debuggingwindowsauth/cs/source.cs#3)] - [!code-vb[C_DebuggingWindowsAuth#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_debuggingwindowsauth/vb/source.vb#3)] - -#### SSPI Is Not Available + [!code-vb[C_DebuggingWindowsAuth#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_debuggingwindowsauth/vb/source.vb#3)] + +#### SSPI Is Not Available + + The following operating systems do not support Windows authentication when used as a server: Windows XP Home Edition, Windows XP Media Center Edition, and Windows Vista Home editions. + +#### Developing and Deploying with Different Identities - The following operating systems do not support Windows authentication when used as a server: Windows XP Home Edition, Windows XP Media Center Edition, and Windows Vista Home editions. - -#### Developing and Deploying with Different Identities + If you develop your application on one machine, and deploy on another, and use different account types to authenticate on each machine, you may experience different behavior. For example, suppose you develop your application on a Windows XP Pro machine using the `SSPI Negotiated` authentication mode. If you use a local user account to authenticate with, then NTLM protocol will be used. Once the application is developed, you deploy the service to a Windows Server 2003 machine where it runs under a domain account. At this point, the client will not be able to authenticate the service because it will be using Kerberos and a domain controller. - If you develop your application on one machine, and deploy on another, and use different account types to authenticate on each machine, you may experience different behavior. For example, suppose you develop your application on a Windows XP Pro machine using the `SSPI Negotiated` authentication mode. If you use a local user account to authenticate with, then NTLM protocol will be used. Once the application is developed, you deploy the service to a Windows Server 2003 machine where it runs under a domain account. At this point, the client will not be able to authenticate the service because it will be using Kerberos and a domain controller. - ## See also - - - -- +- - [Delegation and Impersonation](delegation-and-impersonation-with-wcf.md) - [Unsupported Scenarios](unsupported-scenarios.md) diff --git a/docs/framework/wcf/feature-details/delegation-and-impersonation-with-wcf.md b/docs/framework/wcf/feature-details/delegation-and-impersonation-with-wcf.md index 540ab78262224..f116f868e7b0d 100644 --- a/docs/framework/wcf/feature-details/delegation-and-impersonation-with-wcf.md +++ b/docs/framework/wcf/feature-details/delegation-and-impersonation-with-wcf.md @@ -2,228 +2,228 @@ title: "Delegation and Impersonation with WCF" description: Learn about the methods of impersonation and delegation that WCF uses to restrict client access to the resources of a service domain. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "impersonation [WCF]" - "delegation [WCF]" ms.assetid: 110e60f7-5b03-4b69-b667-31721b8e3152 --- # Delegation and Impersonation with WCF -*Impersonation* is a common technique that services use to restrict client access to a service domain's resources. Service domain resources can either be machine resources, such as local files (impersonation), or a resource on another machine, such as a file share (delegation). For a sample application, see [Impersonating the Client](../samples/impersonating-the-client.md). For an example of how to use impersonation, see [How to: Impersonate a Client on a Service](../how-to-impersonate-a-client-on-a-service.md). - +*Impersonation* is a common technique that services use to restrict client access to a service domain's resources. Service domain resources can either be machine resources, such as local files (impersonation), or a resource on another machine, such as a file share (delegation). For a sample application, see [Impersonating the Client](../samples/impersonating-the-client.md). For an example of how to use impersonation, see [How to: Impersonate a Client on a Service](../how-to-impersonate-a-client-on-a-service.md). + > [!IMPORTANT] -> Be aware that when impersonating a client on a service, the service runs with the client's credentials, which may have higher privileges than the server process. - -## Overview - - Typically, clients call a service to have the service perform some action on the client’s behalf. Impersonation allows the service to act as the client while performing the action. Delegation allows a front-end service to forward the client’s request to a back-end service in such a way that the back-end service can also impersonate the client. Impersonation is most commonly used as a way of checking whether a client is authorized to perform a particular action, while delegation is a way of flowing impersonation capabilities, along with the client’s identity, to a back-end service. Delegation is a Windows domain feature that can be used when Kerberos-based authentication is performed. Delegation is distinct from identity flow and, because delegation transfers the ability to impersonate the client without possession of the client’s password, it is a much higher privileged operation than identity flow. - - Both impersonation and delegation require that the client have a Windows identity. If a client does not possess a Windows identity, then the only option available is to flow the client’s identity to the second service. - -## Impersonation Basics - - Windows Communication Foundation (WCF) supports impersonation for a variety of client credentials. This topic describes service model support for impersonating the caller during the implementation of a service method. Also discussed are common deployment scenarios involving impersonation and SOAP security and WCF options in these scenarios. - - This topic focuses on impersonation and delegation in WCF when using SOAP security. You can also use impersonation and delegation with WCF when using transport security, as described in [Using Impersonation with Transport Security](using-impersonation-with-transport-security.md). - -## Two Methods - - WCF SOAP security has two distinct methods for performing impersonation. The method used depends on the binding. One is impersonation from a Windows token obtained from the Security Support Provider Interface (SSPI) or Kerberos authentication, which is then cached on the service. The second is impersonation from a Windows token obtained from the Kerberos extensions, collectively called *Service-for-User* (S4U). - -### Cached Token Impersonation - - You can perform cached-token impersonation with the following: - -- , , and with a Windows client credential. - -- with a set to the credential, or any other standard binding where the client presents a user name credential that the service can map to a valid Windows account. - -- Any that uses a Windows client credential with the `requireCancellation` set to `true`. (The property is available on the following classes: , , and .) If a secure conversation is used on the binding, it must also have the `requireCancellation` property set to `true`. - -- Any where the client presents a user name credential. If secure conversation is used on the binding, it must also have the `requireCancellation` property set to `true`. - -### S4U-Based Impersonation - - You can perform S4U-based impersonation with the following: - -- , , and with a certificate client credential that the service can map to a valid Windows account. - -- Any that uses a Windows client credential with the `requireCancellation` property set to `false`. - -- Any that uses a user name or Windows client credential and secure conversation with the `requireCancellation` property set to `false`. - - The extent to which the service can impersonate the client depends on the privileges the service account holds when it attempts impersonation, the type of impersonation used, and possibly the extent of impersonation the client permits. - +> Be aware that when impersonating a client on a service, the service runs with the client's credentials, which may have higher privileges than the server process. + +## Overview + + Typically, clients call a service to have the service perform some action on the client’s behalf. Impersonation allows the service to act as the client while performing the action. Delegation allows a front-end service to forward the client’s request to a back-end service in such a way that the back-end service can also impersonate the client. Impersonation is most commonly used as a way of checking whether a client is authorized to perform a particular action, while delegation is a way of flowing impersonation capabilities, along with the client’s identity, to a back-end service. Delegation is a Windows domain feature that can be used when Kerberos-based authentication is performed. Delegation is distinct from identity flow and, because delegation transfers the ability to impersonate the client without possession of the client’s password, it is a much higher privileged operation than identity flow. + + Both impersonation and delegation require that the client have a Windows identity. If a client does not possess a Windows identity, then the only option available is to flow the client’s identity to the second service. + +## Impersonation Basics + + Windows Communication Foundation (WCF) supports impersonation for a variety of client credentials. This topic describes service model support for impersonating the caller during the implementation of a service method. Also discussed are common deployment scenarios involving impersonation and SOAP security and WCF options in these scenarios. + + This topic focuses on impersonation and delegation in WCF when using SOAP security. You can also use impersonation and delegation with WCF when using transport security, as described in [Using Impersonation with Transport Security](using-impersonation-with-transport-security.md). + +## Two Methods + + WCF SOAP security has two distinct methods for performing impersonation. The method used depends on the binding. One is impersonation from a Windows token obtained from the Security Support Provider Interface (SSPI) or Kerberos authentication, which is then cached on the service. The second is impersonation from a Windows token obtained from the Kerberos extensions, collectively called *Service-for-User* (S4U). + +### Cached Token Impersonation + + You can perform cached-token impersonation with the following: + +- , , and with a Windows client credential. + +- with a set to the credential, or any other standard binding where the client presents a user name credential that the service can map to a valid Windows account. + +- Any that uses a Windows client credential with the `requireCancellation` set to `true`. (The property is available on the following classes: , , and .) If a secure conversation is used on the binding, it must also have the `requireCancellation` property set to `true`. + +- Any where the client presents a user name credential. If secure conversation is used on the binding, it must also have the `requireCancellation` property set to `true`. + +### S4U-Based Impersonation + + You can perform S4U-based impersonation with the following: + +- , , and with a certificate client credential that the service can map to a valid Windows account. + +- Any that uses a Windows client credential with the `requireCancellation` property set to `false`. + +- Any that uses a user name or Windows client credential and secure conversation with the `requireCancellation` property set to `false`. + + The extent to which the service can impersonate the client depends on the privileges the service account holds when it attempts impersonation, the type of impersonation used, and possibly the extent of impersonation the client permits. + > [!NOTE] -> When the client and service are running on the same computer and the client is running under a system account (for example, `Local System` or `Network Service`), the client cannot be impersonated when a secure session is established with stateful Security Context tokens. A Windows Form or console application typically runs under the currently logged-in account, so that account can be impersonated by default. However, when the client is an ASP.NET page and that page is hosted in IIS 6.0 or IIS 7.0, then the client does run under the `Network Service` account by default. All of the system-provided bindings that support secure sessions use a stateless security context token (SCT) by default. However, if the client is an ASP.NET page, and secure sessions with stateful SCTs are used, the client cannot be impersonated. For more information about using stateful SCTs in a secure session, see [How to: Create a Security Context Token for a Secure Session](how-to-create-a-security-context-token-for-a-secure-session.md). - -## Impersonation in a Service Method: Declarative Model +> When the client and service are running on the same computer and the client is running under a system account (for example, `Local System` or `Network Service`), the client cannot be impersonated when a secure session is established with stateful Security Context tokens. A Windows Form or console application typically runs under the currently logged-in account, so that account can be impersonated by default. However, when the client is an ASP.NET page and that page is hosted in IIS 6.0 or IIS 7.0, then the client does run under the `Network Service` account by default. All of the system-provided bindings that support secure sessions use a stateless security context token (SCT) by default. However, if the client is an ASP.NET page, and secure sessions with stateful SCTs are used, the client cannot be impersonated. For more information about using stateful SCTs in a secure session, see [How to: Create a Security Context Token for a Secure Session](how-to-create-a-security-context-token-for-a-secure-session.md). + +## Impersonation in a Service Method: Declarative Model + + Most impersonation scenarios involve executing the service method in the caller context. WCF provides an impersonation feature that makes this easy to do by allowing the user to specify the impersonation requirement in the attribute. For example, in the following code, the WCF infrastructure impersonates the caller before executing the `Hello` method. Any attempt to access native resources inside the `Hello` method succeed only if the access control list (ACL) of the resource allows the caller access privileges. To enable impersonation, set the property to one of the enumeration values, either or , as shown in the following example. - Most impersonation scenarios involve executing the service method in the caller context. WCF provides an impersonation feature that makes this easy to do by allowing the user to specify the impersonation requirement in the attribute. For example, in the following code, the WCF infrastructure impersonates the caller before executing the `Hello` method. Any attempt to access native resources inside the `Hello` method succeed only if the access control list (ACL) of the resource allows the caller access privileges. To enable impersonation, set the property to one of the enumeration values, either or , as shown in the following example. - > [!NOTE] -> When a service has higher credentials than the remote client, the credentials of the service are used if the property is set to . That is, if a low-privileged user provides its credentials, a higher-privileged service executes the method with the credentials of the service, and can use resources that the low-privileged user would otherwise not be able to use. - +> When a service has higher credentials than the remote client, the credentials of the service are used if the property is set to . That is, if a low-privileged user provides its credentials, a higher-privileged service executes the method with the credentials of the service, and can use resources that the low-privileged user would otherwise not be able to use. + [!code-csharp[c_ImpersonationAndDelegation#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_impersonationanddelegation/cs/source.cs#1)] - [!code-vb[c_ImpersonationAndDelegation#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_impersonationanddelegation/vb/source.vb#1)] - - The WCF infrastructure can impersonate the caller only if the caller is authenticated with credentials that can be mapped to a Windows user account. If the service is configured to authenticate using a credential that cannot be mapped to a Windows account, the service method is not executed. - + [!code-vb[c_ImpersonationAndDelegation#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_impersonationanddelegation/vb/source.vb#1)] + + The WCF infrastructure can impersonate the caller only if the caller is authenticated with credentials that can be mapped to a Windows user account. If the service is configured to authenticate using a credential that cannot be mapped to a Windows account, the service method is not executed. + > [!NOTE] -> On Windows XP, impersonation fails if a stateful SCT is created, resulting in an . For more information, see [Unsupported Scenarios](unsupported-scenarios.md). - -## Impersonation in a Service Method: Imperative Model +> On Windows XP, impersonation fails if a stateful SCT is created, resulting in an . For more information, see [Unsupported Scenarios](unsupported-scenarios.md). + +## Impersonation in a Service Method: Imperative Model + + Sometimes a caller does not need to impersonate the entire service method to function, but for only a portion of it. In this case, obtain the Windows identity of the caller inside the service method and imperatively perform the impersonation. Do this by using the property of the to return an instance of the class and calling the method before using the instance. - Sometimes a caller does not need to impersonate the entire service method to function, but for only a portion of it. In this case, obtain the Windows identity of the caller inside the service method and imperatively perform the impersonation. Do this by using the property of the to return an instance of the class and calling the method before using the instance. - > [!NOTE] -> Be sure to use the Visual Basic`Using` statement or the C# `using` statement to automatically revert the impersonation action. If you do not use the statement, or if you use a programming language other than Visual Basic or C#, be sure to revert the impersonation level. Failure to do this can form the basis for denial of service and elevation of privilege attacks. - +> Be sure to use the Visual Basic`Using` statement or the C# `using` statement to automatically revert the impersonation action. If you do not use the statement, or if you use a programming language other than Visual Basic or C#, be sure to revert the impersonation level. Failure to do this can form the basis for denial of service and elevation of privilege attacks. + [!code-csharp[c_ImpersonationAndDelegation#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_impersonationanddelegation/cs/source.cs#2)] - [!code-vb[c_ImpersonationAndDelegation#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_impersonationanddelegation/vb/source.vb#2)] - -## Impersonation for All Service Methods + [!code-vb[c_ImpersonationAndDelegation#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_impersonationanddelegation/vb/source.vb#2)] + +## Impersonation for All Service Methods + + In some cases, you must perform all the methods of a service in the caller’s context. Instead of explicitly enabling this feature on a per-method basis, use the . As shown in the following code, set the property to `true`. The is retrieved from the collections of behaviors of the class. Also note that the `Impersonation` property of the applied to each method must also be set to either or . - In some cases, you must perform all the methods of a service in the caller’s context. Instead of explicitly enabling this feature on a per-method basis, use the . As shown in the following code, set the property to `true`. The is retrieved from the collections of behaviors of the class. Also note that the `Impersonation` property of the applied to each method must also be set to either or . - [!code-csharp[c_ImpersonationAndDelegation#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_impersonationanddelegation/cs/source.cs#3)] - [!code-vb[c_ImpersonationAndDelegation#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_impersonationanddelegation/vb/source.vb#3)] - - The following table describes WCF behavior for all possible combinations of `ImpersonationOption` and `ImpersonateCallerForAllServiceOperations`. - -|`ImpersonationOption`|`ImpersonateCallerForAllServiceOperations`|Behavior| -|---------------------------|------------------------------------------------|--------------| -|Required|n/a|WCF impersonates the caller| -|Allowed|false|WCF does not impersonate the caller| -|Allowed|true|WCF impersonates the caller| -|NotAllowed|false|WCF does not impersonate the caller| -|NotAllowed|true|Disallowed. (An is thrown.)| - -## Impersonation Level Obtained from Windows Credentials and Cached Token Impersonation - - In some scenarios the client has partial control over the level of impersonation the service performs when a Windows client credential is used. One scenario occurs when the client specifies an Anonymous impersonation level. The other occurs when performing impersonation with a cached token. This is done by setting the property of the class, which is accessed as a property of the generic class. - + [!code-vb[c_ImpersonationAndDelegation#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_impersonationanddelegation/vb/source.vb#3)] + + The following table describes WCF behavior for all possible combinations of `ImpersonationOption` and `ImpersonateCallerForAllServiceOperations`. + +|`ImpersonationOption`|`ImpersonateCallerForAllServiceOperations`|Behavior| +|---------------------------|------------------------------------------------|--------------| +|Required|n/a|WCF impersonates the caller| +|Allowed|false|WCF does not impersonate the caller| +|Allowed|true|WCF impersonates the caller| +|NotAllowed|false|WCF does not impersonate the caller| +|NotAllowed|true|Disallowed. (An is thrown.)| + +## Impersonation Level Obtained from Windows Credentials and Cached Token Impersonation + + In some scenarios the client has partial control over the level of impersonation the service performs when a Windows client credential is used. One scenario occurs when the client specifies an Anonymous impersonation level. The other occurs when performing impersonation with a cached token. This is done by setting the property of the class, which is accessed as a property of the generic class. + > [!NOTE] -> Specifying an impersonation level of Anonymous causes the client to log on to the service anonymously. The service must therefore allow anonymous logons, regardless of whether impersonation is performed. - - The client can specify the impersonation level as , , , or . Only a token at the specified level is produced, as shown in the following code. - +> Specifying an impersonation level of Anonymous causes the client to log on to the service anonymously. The service must therefore allow anonymous logons, regardless of whether impersonation is performed. + + The client can specify the impersonation level as , , , or . Only a token at the specified level is produced, as shown in the following code. + [!code-csharp[c_ImpersonationAndDelegation#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_impersonationanddelegation/cs/source.cs#4)] - [!code-vb[c_ImpersonationAndDelegation#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_impersonationanddelegation/vb/source.vb#4)] - - The following table specifies the impersonation level the service obtains when impersonating from a cached token. - -|`AllowedImpersonationLevel` value|Service has `SeImpersonatePrivilege`|Service and client are capable of delegation|Cached token `ImpersonationLevel`| -|---------------------------------------|------------------------------------------|--------------------------------------------------|---------------------------------------| -|Anonymous|Yes|n/a|Impersonation| -|Anonymous|No|n/a|Identification| -|Identification|n/a|n/a|Identification| -|Impersonation|Yes|n/a|Impersonation| -|Impersonation|No|n/a|Identification| -|Delegation|Yes|Yes|Delegation| -|Delegation|Yes|No|Impersonation| -|Delegation|No|n/a|Identification| - -## Impersonation Level Obtained from User Name Credentials and Cached Token Impersonation - - By passing the service its user name and password, a client enables WCF to log on as that user, which is equivalent to setting the `AllowedImpersonationLevel` property to . (The `AllowedImpersonationLevel` is available on the and classes.) The following table provides the impersonation level obtained when the service receives user name credentials. - -|`AllowedImpersonationLevel`|Service has `SeImpersonatePrivilege`|Service and client are capable of delegation|Cached token `ImpersonationLevel`| -|---------------------------------|------------------------------------------|--------------------------------------------------|---------------------------------------| -|n/a|Yes|Yes|Delegation| -|n/a|Yes|No|Impersonation| -|n/a|No|n/a|Identification| - -## Impersonation Level Obtained from S4U-Based Impersonation - -|Service has `SeTcbPrivilege`|Service has `SeImpersonatePrivilege`|Service and client are capable of delegation|Cached token `ImpersonationLevel`| -|----------------------------------|------------------------------------------|--------------------------------------------------|---------------------------------------| -|Yes|Yes|n/a|Impersonation| -|Yes|No|n/a|Identification| -|No|n/a|n/a|Identification| - -## Mapping a Client Certificate to a Windows Account - - It is possible for a client to authenticate itself to a service using a certificate, and to have the service map the client to an existing account through Active Directory. The following XML shows how to configure the service to map the certificate. - -```xml - - - - - - - - - - - -``` - - The following code shows how to configure the service. - + [!code-vb[c_ImpersonationAndDelegation#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_impersonationanddelegation/vb/source.vb#4)] + + The following table specifies the impersonation level the service obtains when impersonating from a cached token. + +|`AllowedImpersonationLevel` value|Service has `SeImpersonatePrivilege`|Service and client are capable of delegation|Cached token `ImpersonationLevel`| +|---------------------------------------|------------------------------------------|--------------------------------------------------|---------------------------------------| +|Anonymous|Yes|n/a|Impersonation| +|Anonymous|No|n/a|Identification| +|Identification|n/a|n/a|Identification| +|Impersonation|Yes|n/a|Impersonation| +|Impersonation|No|n/a|Identification| +|Delegation|Yes|Yes|Delegation| +|Delegation|Yes|No|Impersonation| +|Delegation|No|n/a|Identification| + +## Impersonation Level Obtained from User Name Credentials and Cached Token Impersonation + + By passing the service its user name and password, a client enables WCF to log on as that user, which is equivalent to setting the `AllowedImpersonationLevel` property to . (The `AllowedImpersonationLevel` is available on the and classes.) The following table provides the impersonation level obtained when the service receives user name credentials. + +|`AllowedImpersonationLevel`|Service has `SeImpersonatePrivilege`|Service and client are capable of delegation|Cached token `ImpersonationLevel`| +|---------------------------------|------------------------------------------|--------------------------------------------------|---------------------------------------| +|n/a|Yes|Yes|Delegation| +|n/a|Yes|No|Impersonation| +|n/a|No|n/a|Identification| + +## Impersonation Level Obtained from S4U-Based Impersonation + +|Service has `SeTcbPrivilege`|Service has `SeImpersonatePrivilege`|Service and client are capable of delegation|Cached token `ImpersonationLevel`| +|----------------------------------|------------------------------------------|--------------------------------------------------|---------------------------------------| +|Yes|Yes|n/a|Impersonation| +|Yes|No|n/a|Identification| +|No|n/a|n/a|Identification| + +## Mapping a Client Certificate to a Windows Account + + It is possible for a client to authenticate itself to a service using a certificate, and to have the service map the client to an existing account through Active Directory. The following XML shows how to configure the service to map the certificate. + +```xml + + + + + + + + + + + +``` + + The following code shows how to configure the service. + ```csharp -// Create a binding that sets a certificate as the client credential type. -WSHttpBinding b = new WSHttpBinding(); -b.Security.Message.ClientCredentialType = MessageCredentialType.Certificate; - -// Create a service host that maps the certificate to a Windows account. -Uri httpUri = new Uri("http://localhost/Calculator"); -ServiceHost sh = new ServiceHost(typeof(HelloService), httpUri); -sh.Credentials.ClientCertificate.Authentication.MapClientCertificateToWindowsAccount = true; -``` - -## Delegation - - To delegate to a back-end service, a service must perform Kerberos multi-leg (SSPI without NTLM fallback) or Kerberos direct authentication to the back-end service using the client’s Windows identity. To delegate to a back-end service, create a and a channel, and then communicate through the channel while impersonating the client. With this form of delegation, the distance at which the back-end service can be located from the front-end service depends on the impersonation level achieved by the front-end service. When the impersonation level is , the front-end and back-end services must be running on the same machine. When the impersonation level is , the front-end and back-end services can be on separate machines or on the same machine. Enabling delegation-level impersonation requires that Windows domain policy be configured to permit delegation. For more information about configuring Active Directory for delegation support, see [Enabling Delegated Authentication](/previous-versions/windows/it-pro/windows-server-2003/cc780217(v=ws.10)). - +// Create a binding that sets a certificate as the client credential type. +WSHttpBinding b = new WSHttpBinding(); +b.Security.Message.ClientCredentialType = MessageCredentialType.Certificate; + +// Create a service host that maps the certificate to a Windows account. +Uri httpUri = new Uri("http://localhost/Calculator"); +ServiceHost sh = new ServiceHost(typeof(HelloService), httpUri); +sh.Credentials.ClientCertificate.Authentication.MapClientCertificateToWindowsAccount = true; +``` + +## Delegation + + To delegate to a back-end service, a service must perform Kerberos multi-leg (SSPI without NTLM fallback) or Kerberos direct authentication to the back-end service using the client’s Windows identity. To delegate to a back-end service, create a and a channel, and then communicate through the channel while impersonating the client. With this form of delegation, the distance at which the back-end service can be located from the front-end service depends on the impersonation level achieved by the front-end service. When the impersonation level is , the front-end and back-end services must be running on the same machine. When the impersonation level is , the front-end and back-end services can be on separate machines or on the same machine. Enabling delegation-level impersonation requires that Windows domain policy be configured to permit delegation. For more information about configuring Active Directory for delegation support, see [Enabling Delegated Authentication](/previous-versions/windows/it-pro/windows-server-2003/cc780217(v=ws.10)). + > [!NOTE] -> When a client authenticates to the front-end service using a user name and password that correspond to a Windows account on the back-end service, the front-end service can authenticate to the back-end service by reusing the client’s user name and password. This is a particularly powerful form of identity flow, because passing user name and password to the back-end service enables the back-end service to perform impersonation, but it does not constitute delegation because Kerberos is not used. Active Directory controls on delegation do not apply to user name and password authentication. - -### Delegation Ability as a Function of Impersonation Level - -|Impersonation level|Service can perform cross-process delegation|Service can perform cross-machine delegation| -|-------------------------|---------------------------------------------------|---------------------------------------------------| -||No|No| -||Yes|No| -||Yes|Yes| - - The following code example demonstrates how to use delegation. - +> When a client authenticates to the front-end service using a user name and password that correspond to a Windows account on the back-end service, the front-end service can authenticate to the back-end service by reusing the client’s user name and password. This is a particularly powerful form of identity flow, because passing user name and password to the back-end service enables the back-end service to perform impersonation, but it does not constitute delegation because Kerberos is not used. Active Directory controls on delegation do not apply to user name and password authentication. + +### Delegation Ability as a Function of Impersonation Level + +|Impersonation level|Service can perform cross-process delegation|Service can perform cross-machine delegation| +|-------------------------|---------------------------------------------------|---------------------------------------------------| +||No|No| +||Yes|No| +||Yes|Yes| + + The following code example demonstrates how to use delegation. + [!code-csharp[c_delegation#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_delegation/cs/source.cs#1)] - [!code-vb[c_delegation#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_delegation/vb/source.vb#1)] - -### How to Configure an Application to Use Constrained Delegation - - Before you can use constrained delegation, the sender, receiver, and the domain controller must be configured to do so. The following procedure lists the steps that enable constrained delegation. For details about the differences between delegation and constrained delegation, see the portion of [Windows Server 2003 Kerberos Extensions](/previous-versions/windows/it-pro/windows-server-2003/cc738207(v=ws.10)) that discusses constrained discussion. - -1. On the domain controller, clear the **Account is sensitive and cannot be delegated** check box for the account under which the client application is running. - -2. On the domain controller, select the **Account is trusted for delegation** check box for the account under which the client application is running. - -3. On the domain controller, configure the middle tier computer so that it is trusted for delegation, by clicking the **Trust computer for delegation** option. - -4. On the domain controller, configure the middle tier computer to use constrained delegation, by clicking the **Trust this computer for delegation to specified services only** option. - + [!code-vb[c_delegation#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_delegation/vb/source.vb#1)] + +### How to Configure an Application to Use Constrained Delegation + + Before you can use constrained delegation, the sender, receiver, and the domain controller must be configured to do so. The following procedure lists the steps that enable constrained delegation. For details about the differences between delegation and constrained delegation, see the portion of [Windows Server 2003 Kerberos Extensions](/previous-versions/windows/it-pro/windows-server-2003/cc738207(v=ws.10)) that discusses constrained discussion. + +1. On the domain controller, clear the **Account is sensitive and cannot be delegated** check box for the account under which the client application is running. + +2. On the domain controller, select the **Account is trusted for delegation** check box for the account under which the client application is running. + +3. On the domain controller, configure the middle tier computer so that it is trusted for delegation, by clicking the **Trust computer for delegation** option. + +4. On the domain controller, configure the middle tier computer to use constrained delegation, by clicking the **Trust this computer for delegation to specified services only** option. + For more detailed instructions about configuring constrained delegation, see [Kerberos Protocol Transition and Constrained Delegation](/previous-versions/windows/it-pro/windows-server-2003/cc739587(v=ws.10)). - + ## See also - -- +- - -- +- - - - -- +- - -- +- - -- +- - - [Using Impersonation with Transport Security](using-impersonation-with-transport-security.md) - [Impersonating the Client](../samples/impersonating-the-client.md) diff --git a/docs/framework/wcf/feature-details/denial-of-service.md b/docs/framework/wcf/feature-details/denial-of-service.md index 6f2fdb8a9662e..dd74560a5e489 100644 --- a/docs/framework/wcf/feature-details/denial-of-service.md +++ b/docs/framework/wcf/feature-details/denial-of-service.md @@ -2,89 +2,89 @@ description: "Learn more about: Denial of Service" title: "Denial of Service" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "denial of service [WCF]" ms.assetid: dfb150f3-d598-4697-a5e6-6779e4f9b600 --- # Denial of Service -Denial of service occurs when a system is overwhelmed in such a way that messages cannot be processed, or they are processed extremely slowly. - -## Excess Memory Consumption - - A problem can occur when reading an XML document with a large number of unique local names, namespaces, or prefixes. If you are using a class that derives from , and you call either the , or property for each item, the returned string is added to a . The collection held by the never decreases in size, creating a virtual "memory leak" of the string handles. - - Mitigations include: - -- Derive from the class and enforce a maximum size quota. (You cannot prevent the use of a or switch the when it is full.) - -- Avoid using the properties mentioned and instead use the method with the method where possible; those methods do not return strings and thus avoid the problem of overfilling the collection. - -## Malicious Client Sends Excessive License Requests to Service - - If a malicious client bombards a service with excessive license requests, it can cause the server to use excessive memory. - - Mitigation: Use the following properties of the class: - -- : controls the maximum number of time-bounded `SecurityContextToken`s that the server caches after `SPNego` or `SSL` negotiation. - -- : controls the lifetime of the `SecurityContextTokens` that the server issues following `SPNego` or `SSL` negotiation. The server caches the `SecurityContextToken`s for this period of time. - -- : controls the maximum number of secure conversations that are established at the server but for which no application messages have been processed. This quota prevents clients from establishing secure conversations at the service, thereby causing the service to maintain state per client, but never using them. - -- : controls the maximum time the service keeps a secure conversation alive without receiving an application message from the client for the conversation. This quota prevents clients from establishing secure conversations at the service, thereby causing the service to maintain state per client, but never using them. - -## WSDualHttpBinding or Dual Custom Bindings Require Client Authentication - - By default, the has security enabled. It is possible, however, that if the client authentication is disabled by setting the property to , a malicious user can cause a denial of service attack on a third service. This can occur because a malicious client can direct the service to send a stream of messages to a third service. - - To mitigate this, do not set the property to `None`. Also be aware of this possibility when creating a custom binding that has a dual message pattern. - -## Auditing Event Log Can Be Filled - - If a malicious user understands that auditing is enabled, that attacker can send invalid messages that cause audit entries to be written. If the audit log is filled in this manner, the auditing system fails. - - To mitigate this, set the property to `true` and use the properties of the Event Viewer to control the auditing behavior. For more information about using the Event Viewer to view and manage event logs, see [Event Viewer](/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc766042(v=ws.11)). For more information, see [Auditing](auditing-security-events.md). - -## Invalid Implementations of IAuthorizationPolicy Can Cause Service to Become Unresponsive - - Calling the method on a faulty implementation of the interface can cause the service to become unresponsive. - - Mitigation: Use only trusted code. That is, use only code that you have written and tested, or that comes from a trusted provider. Do not allow untrusted extensions of to be plugged into your code without due consideration. This applies to all extensions used in a service implementation. WCF does not make any distinction between application code and foreign code that is plugged in using extensibility points. - -## Kerberos Maximum Token Size May Need Resizing - - If a client belongs to a large number of groups (approximately 900, although the actual number varies depending on the groups), a problem may occur when a message header's block exceeds 64 kilobytes. In that case, you can increase the maximum Kerberos token size. You may also need to increase the maximum WCF message size to accommodate the larger Kerberos token. - -## Autoenrollment Results in Multiple Certificates with Same Subject Name for Machine - - *Autoenrollment* is the capability of Windows Server 2003 to automatically enroll users and computers for certificates. When a machine is on a domain with the feature enabled, an X.509 certificate with the intended purpose of client authentication is automatically created and inserted into the local computer's Personal certificates store whenever a new machine is joined to the network. However, autoenrollment uses the same subject name for all certificates it creates in the cache. - - The impact is that WCF services may fail to open on domains with autoenrollment. This occurs because the default service X.509 credential search criteria might be ambiguous because multiple certificates with the machine's fully qualified Domain Name System (DNS) name exist. One certificate originates from autoenrollment; the other might be a self-issued certificate. - - To mitigate this, reference the exact certificate to use by using a more precise search criterion on the [\](../../configure-apps/file-schema/wcf/servicecredentials.md). For example, use the option, and specify the certificate by its unique thumbprint (hash). - - For more information about the autoenrollment feature, see [Certificate Autoenrollment in Windows Server 2003](/previous-versions/windows/it-pro/windows-server-2003/cc778954(v=ws.10)). - -## Last of Multiple Alternative Subject Names Used for Authorization - - In the rare case when an X.509 certificate contains multiple alternative subject names, and you authorize using the alternative subject name, authorization may fail. - -## Protect Configuration Files with ACLs - - You can specify required and optional claims in code and configuration files for CardSpace issued tokens. This results in corresponding elements being emitted in `RequestSecurityToken` messages that are sent to the security token service. An attacker can modify code or configuration to remove required or optional claims, potentially getting the security token service to issue a token that does not allow access to the target service. - - To mitigate: Require access to the computer to modify the configuration file. Use file access control lists (ACLs) to secure configuration files. WCF requires that code be in the application directory or the global assembly cache before it will allow such code to be loaded from configuration. Use directory ACLs to secure directories. - -## Maximum Number of Secure Sessions for a Service Is Reached - - When a client is successfully authenticated by a service and a secure session is established with the service, the service keeps track of the session until the client cancels it or the session expires. Every established session counts against the limit for the maximum number of active simultaneous sessions with a service. When this limit is reached, clients that attempt to create a new session with that service are rejected until one or more active sessions expire or are canceled by a client. A client can have multiple sessions with a service, and each one of those sessions counts toward the limit. - +Denial of service occurs when a system is overwhelmed in such a way that messages cannot be processed, or they are processed extremely slowly. + +## Excess Memory Consumption + + A problem can occur when reading an XML document with a large number of unique local names, namespaces, or prefixes. If you are using a class that derives from , and you call either the , or property for each item, the returned string is added to a . The collection held by the never decreases in size, creating a virtual "memory leak" of the string handles. + + Mitigations include: + +- Derive from the class and enforce a maximum size quota. (You cannot prevent the use of a or switch the when it is full.) + +- Avoid using the properties mentioned and instead use the method with the method where possible; those methods do not return strings and thus avoid the problem of overfilling the collection. + +## Malicious Client Sends Excessive License Requests to Service + + If a malicious client bombards a service with excessive license requests, it can cause the server to use excessive memory. + + Mitigation: Use the following properties of the class: + +- : controls the maximum number of time-bounded `SecurityContextToken`s that the server caches after `SPNego` or `SSL` negotiation. + +- : controls the lifetime of the `SecurityContextTokens` that the server issues following `SPNego` or `SSL` negotiation. The server caches the `SecurityContextToken`s for this period of time. + +- : controls the maximum number of secure conversations that are established at the server but for which no application messages have been processed. This quota prevents clients from establishing secure conversations at the service, thereby causing the service to maintain state per client, but never using them. + +- : controls the maximum time the service keeps a secure conversation alive without receiving an application message from the client for the conversation. This quota prevents clients from establishing secure conversations at the service, thereby causing the service to maintain state per client, but never using them. + +## WSDualHttpBinding or Dual Custom Bindings Require Client Authentication + + By default, the has security enabled. It is possible, however, that if the client authentication is disabled by setting the property to , a malicious user can cause a denial of service attack on a third service. This can occur because a malicious client can direct the service to send a stream of messages to a third service. + + To mitigate this, do not set the property to `None`. Also be aware of this possibility when creating a custom binding that has a dual message pattern. + +## Auditing Event Log Can Be Filled + + If a malicious user understands that auditing is enabled, that attacker can send invalid messages that cause audit entries to be written. If the audit log is filled in this manner, the auditing system fails. + + To mitigate this, set the property to `true` and use the properties of the Event Viewer to control the auditing behavior. For more information about using the Event Viewer to view and manage event logs, see [Event Viewer](/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc766042(v=ws.11)). For more information, see [Auditing](auditing-security-events.md). + +## Invalid Implementations of IAuthorizationPolicy Can Cause Service to Become Unresponsive + + Calling the method on a faulty implementation of the interface can cause the service to become unresponsive. + + Mitigation: Use only trusted code. That is, use only code that you have written and tested, or that comes from a trusted provider. Do not allow untrusted extensions of to be plugged into your code without due consideration. This applies to all extensions used in a service implementation. WCF does not make any distinction between application code and foreign code that is plugged in using extensibility points. + +## Kerberos Maximum Token Size May Need Resizing + + If a client belongs to a large number of groups (approximately 900, although the actual number varies depending on the groups), a problem may occur when a message header's block exceeds 64 kilobytes. In that case, you can increase the maximum Kerberos token size. You may also need to increase the maximum WCF message size to accommodate the larger Kerberos token. + +## Autoenrollment Results in Multiple Certificates with Same Subject Name for Machine + + *Autoenrollment* is the capability of Windows Server 2003 to automatically enroll users and computers for certificates. When a machine is on a domain with the feature enabled, an X.509 certificate with the intended purpose of client authentication is automatically created and inserted into the local computer's Personal certificates store whenever a new machine is joined to the network. However, autoenrollment uses the same subject name for all certificates it creates in the cache. + + The impact is that WCF services may fail to open on domains with autoenrollment. This occurs because the default service X.509 credential search criteria might be ambiguous because multiple certificates with the machine's fully qualified Domain Name System (DNS) name exist. One certificate originates from autoenrollment; the other might be a self-issued certificate. + + To mitigate this, reference the exact certificate to use by using a more precise search criterion on the [\](../../configure-apps/file-schema/wcf/servicecredentials.md). For example, use the option, and specify the certificate by its unique thumbprint (hash). + + For more information about the autoenrollment feature, see [Certificate Autoenrollment in Windows Server 2003](/previous-versions/windows/it-pro/windows-server-2003/cc778954(v=ws.10)). + +## Last of Multiple Alternative Subject Names Used for Authorization + + In the rare case when an X.509 certificate contains multiple alternative subject names, and you authorize using the alternative subject name, authorization may fail. + +## Protect Configuration Files with ACLs + + You can specify required and optional claims in code and configuration files for CardSpace issued tokens. This results in corresponding elements being emitted in `RequestSecurityToken` messages that are sent to the security token service. An attacker can modify code or configuration to remove required or optional claims, potentially getting the security token service to issue a token that does not allow access to the target service. + + To mitigate: Require access to the computer to modify the configuration file. Use file access control lists (ACLs) to secure configuration files. WCF requires that code be in the application directory or the global assembly cache before it will allow such code to be loaded from configuration. Use directory ACLs to secure directories. + +## Maximum Number of Secure Sessions for a Service Is Reached + + When a client is successfully authenticated by a service and a secure session is established with the service, the service keeps track of the session until the client cancels it or the session expires. Every established session counts against the limit for the maximum number of active simultaneous sessions with a service. When this limit is reached, clients that attempt to create a new session with that service are rejected until one or more active sessions expire or are canceled by a client. A client can have multiple sessions with a service, and each one of those sessions counts toward the limit. + > [!NOTE] -> When you use stateful sessions, the previous paragraph does not apply. For more information about stateful sessions, see [How to: Create a Security Context Token for a Secure Session](how-to-create-a-security-context-token-for-a-secure-session.md). - - To mitigate this, set the limit for the maximum number of active sessions and the maximum lifetime for a session by setting the property of the class. - +> When you use stateful sessions, the previous paragraph does not apply. For more information about stateful sessions, see [How to: Create a Security Context Token for a Secure Session](how-to-create-a-security-context-token-for-a-secure-session.md). + + To mitigate this, set the limit for the maximum number of active sessions and the maximum lifetime for a session by setting the property of the class. + ## See also - [Security Considerations](security-considerations-in-wcf.md) diff --git a/docs/framework/wcf/feature-details/discovery-find-and-findcriteria.md b/docs/framework/wcf/feature-details/discovery-find-and-findcriteria.md index b08fc82af6264..bef3ae5994c80 100644 --- a/docs/framework/wcf/feature-details/discovery-find-and-findcriteria.md +++ b/docs/framework/wcf/feature-details/discovery-find-and-findcriteria.md @@ -10,7 +10,7 @@ A discovery find operation is initiated by a client to discover one or more serv ## DiscoveryClient -The class provides the mechanism to perform find operations and makes performing discovery client operations easy. It contains a method, which performs a (blocking) synchronous find, and a method, which initiates a non-blocking asynchronous find. Both methods take a parameter, and provide results to the user through a object. +The class provides the mechanism to perform find operations and makes performing discovery client operations easy. It contains a method, which performs a (blocking) synchronous find, and a method, which initiates a non-blocking asynchronous find. Both methods take a parameter, and provide results to the user through a object. ## FindCriteria @@ -22,7 +22,7 @@ Search criteria include: - - Optional. Scopes are absolute URIs that are used to categorize individual service endpoints. You may want to use this in scenarios where multiple endpoints expose the same contract and you want a way to search for a subset of the endpoints. If more than one scope is specified, only service endpoints matching ALL scopes reply. -- - Specifies the matching algorithm to use while matching the scopes in the Probe message with that of the endpoint. There are five supported scope-matching rules: +- - Specifies the matching algorithm to use while matching the scopes in the Probe message with that of the endpoint. There are five supported scope-matching rules: - does a basic case-sensitive string comparison. @@ -38,9 +38,9 @@ Search criteria include: Termination criteria include: -1. - The maximum time to wait for replies from services on the network. The default duration is 20 seconds. +1. - The maximum time to wait for replies from services on the network. The default duration is 20 seconds. -2. - The maximum number of replies to wait for. If replies are received before has elapsed, the find operation ends. +2. - The maximum number of replies to wait for. If replies are received before has elapsed, the find operation ends. ## FindResponse diff --git a/docs/framework/wcf/feature-details/discoveryclient-and-dynamicendpoint.md b/docs/framework/wcf/feature-details/discoveryclient-and-dynamicendpoint.md index b91541ccc6302..04ad4a5c30d7c 100644 --- a/docs/framework/wcf/feature-details/discoveryclient-and-dynamicendpoint.md +++ b/docs/framework/wcf/feature-details/discoveryclient-and-dynamicendpoint.md @@ -6,103 +6,103 @@ ms.assetid: 7cd418f0-0eab-48d1-a493-7eb907867ec3 --- # DiscoveryClient and DynamicEndpoint - and are two classes used on the client side to search for services. provides you with a list of services that match a specific set of criteria and allows you to connect to the services. performs the same operation and in addition, automatically connects to one of the services that was found. Any endpoint can be made into a , the search criteria can also be added in configuration, thus is useful when you need discovery in your solution but do not want to modify the client logic – you only need to modify the endpoints. on the other hand can be used to gain finer control over your search operation. The uses and benefits of each are elaborated below. - -## DiscoveryClient + and are two classes used on the client side to search for services. provides you with a list of services that match a specific set of criteria and allows you to connect to the services. performs the same operation and in addition, automatically connects to one of the services that was found. Any endpoint can be made into a , the search criteria can also be added in configuration, thus is useful when you need discovery in your solution but do not want to modify the client logic – you only need to modify the endpoints. on the other hand can be used to gain finer control over your search operation. The uses and benefits of each are elaborated below. + +## DiscoveryClient + + The defines synchronous and asynchronous Find methods, and events. It also defines synchronous and asynchronous Resolve methods and a event. Use the or methods to search for services. Both of these methods take a instance that allows you to specify contract type names, scopes, maximum number of results requested, and scope matching rules. The and events can be used when calling the method. is fired whenever the receives a response from a service. It can be used to display a progress bar showing the progress of the find operation. It can also be used to act on find responses as they are received. The event is fired when the find operation completes. This may happen because the maximum number of responses has been received or if the has elapsed. When the find operation completes the results are returned in a instance. The contains a collection of which contains the addresses, contract type names, extensions, listen URIs, and scopes of the matching services. You can then use this information to connect to and call one of the matching services. The following example shows how to call the System.ServiceModel.Discovery.DiscoveryClient.Find(System.ServiceModel.Discovery.FindCriteria) method and use the returned metadata to call the found service. A benefit of using is that you can cache the list of endpoints you’ve found and use them at a later time. With this cache, you can build custom logic to handle various failure conditions. - The defines synchronous and asynchronous Find methods, and events. It also defines synchronous and asynchronous Resolve methods and a event. Use the or methods to search for services. Both of these methods take a instance that allows you to specify contract type names, scopes, maximum number of results requested, and scope matching rules. The and events can be used when calling the method. is fired whenever the receives a response from a service. It can be used to display a progress bar showing the progress of the find operation. It can also be used to act on find responses as they are received. The event is fired when the find operation completes. This may happen because the maximum number of responses has been received or if the has elapsed. When the find operation completes the results are returned in a instance. The contains a collection of which contains the addresses, contract type names, extensions, listen URIs, and scopes of the matching services. You can then use this information to connect to and call one of the matching services. The following example shows how to call the System.ServiceModel.Discovery.DiscoveryClient.Find(System.ServiceModel.Discovery.FindCriteria) method and use the returned metadata to call the found service. A benefit of using is that you can cache the list of endpoints you’ve found and use them at a later time. With this cache, you can build custom logic to handle various failure conditions. - ```csharp -DiscoveryClient dc = new DiscoveryClient(new UdpDiscoveryEndpoint()); - -FindCriteria criteria = new FindCriteria(typeof(ICalculatorService)); -FindResponse fr = dc.Find(criteria); - -if (fr.Endpoints.Count > 0) -{ - EndpointAddress ep = fr.Endpoints[0].Address; - CalculatorServiceClient client = new CalculatorServiceClient(); - - // Connect to the discovered service endpoint - client.Endpoint.Address = endpointAddress; - Console.WriteLine("Invoking CalculatorService at {0}", endpointAddress); - - double value1 = 100.00D; - double value2 = 15.99D; - - // Call the Add service operation. - double result = client.Add(value1, value2); - Console.WriteLine("Add({0},{1}) = {2}", value1, value2, result); -} -else - Console.WriteLine("No matching endpoints found"); -``` - - The following example shows how to perform a find operation asynchronously. - +DiscoveryClient dc = new DiscoveryClient(new UdpDiscoveryEndpoint()); + +FindCriteria criteria = new FindCriteria(typeof(ICalculatorService)); +FindResponse fr = dc.Find(criteria); + +if (fr.Endpoints.Count > 0) +{ + EndpointAddress ep = fr.Endpoints[0].Address; + CalculatorServiceClient client = new CalculatorServiceClient(); + + // Connect to the discovered service endpoint + client.Endpoint.Address = endpointAddress; + Console.WriteLine("Invoking CalculatorService at {0}", endpointAddress); + + double value1 = 100.00D; + double value2 = 15.99D; + + // Call the Add service operation. + double result = client.Add(value1, value2); + Console.WriteLine("Add({0},{1}) = {2}", value1, value2, result); +} +else + Console.WriteLine("No matching endpoints found"); +``` + + The following example shows how to perform a find operation asynchronously. + ```csharp -static void FindServiceAsync() -{ +static void FindServiceAsync() +{ DiscoveryClient dc = new DiscoveryClient(new UdpDiscoveryEndpoint()); - dc.FindCompleted += new EventHandler( discoveryClient_FindCompleted); - dc.FindProgressChanged += new EventHandler(discoveryClient_FindProgressChanged); + dc.FindCompleted += new EventHandler( discoveryClient_FindCompleted); + dc.FindProgressChanged += new EventHandler(discoveryClient_FindProgressChanged); dc.FindAsync(new FindCriteria(typeof(ICalculatorService))); } -static void discoveryClient_FindProgressChanged(object sender, FindProgressChangedEventArgs e) -{ - Console.WriteLine("Found service at: " + e.EndpointDiscoveryMetadata.Address +static void discoveryClient_FindProgressChanged(object sender, FindProgressChangedEventArgs e) +{ + Console.WriteLine("Found service at: " + e.EndpointDiscoveryMetadata.Address } - -static void discoveryClient_FindCompleted(object sender, FindCompletedEventArgs e) + +static void discoveryClient_FindCompleted(object sender, FindCompletedEventArgs e) { - if (e.Result.Endpoints.Count > 0) - { - EndpointAddress ep = e.Result.Endpoints[0].Address; - CalculatorServiceClient client = new CalculatorServiceClient(); - - // Connect to the discovered service endpoint - client.Endpoint.Address = ep; - Console.WriteLine("Invoking CalculatorService at {0}", ep); - - double value1 = 100.00D; - double value2 = 15.99D; - - double result = client.Add(value1, value2); - Console.WriteLine("Add({0},{1}) = {2}", value1, value2, result); - } - else - Console.WriteLine("No matching endpoints found"); - - } + if (e.Result.Endpoints.Count > 0) + { + EndpointAddress ep = e.Result.Endpoints[0].Address; + CalculatorServiceClient client = new CalculatorServiceClient(); + + // Connect to the discovered service endpoint + client.Endpoint.Address = ep; + Console.WriteLine("Invoking CalculatorService at {0}", ep); + + double value1 = 100.00D; + double value2 = 15.99D; + + double result = client.Add(value1, value2); + Console.WriteLine("Add({0},{1}) = {2}", value1, value2, result); + } + else + Console.WriteLine("No matching endpoints found"); + + } +``` + + Use the and methods to locate a service based on its endpoint address. This is useful when the endpoint address is not network addressable. The Resolve methods take an instance of which allows you to specify the endpoint address of the service you are resolving, the maximum duration of the resolve operation, and a set of extensions. The following example shows how to use the method to resolve a service. + +```csharp +DiscoveryClient dc = new DiscoveryClient(new UdpDiscoveryEndpoint()); +ResolveCriteria criteria = new ResolveCriteria(endpointAddress); +ResolveResponse response = dc.Resolve(criteria); +EndpointAddress newEp = response.EndpointDiscoveryMetadata.Address; +``` + +## DynamicEndpoint + + is a standard endpoint (For more information, see [Standard Endpoints](standard-endpoints.md)) which performs discovery and automatically selects a matching service. Just create a passing in the contract to search for and the binding to use and pass the instance to the WCF client. The following example shows how to create and use a to call the calculator service. The discovery is performed every time the client is opened. Any endpoint defined in configuration can also be turned into a by adding the `kind ="dynamicEndpoint"` attribute to the endpoint configuration element. + +```csharp +DynamicEndpoint dynamicEndpoint = new DynamicEndpoint(ContractDescription.GetContract(typeof(ICalculatorService)), new WSHttpBinding()); +CalculatorServiceClient client = new CalculatorServiceClient(dynamicEndpoint); + +Console.WriteLine("Invoking CalculatorService"); +Console.WriteLine(); + +double value1 = 100.00D; +double value2 = 15.99D; + +double result = client.Add(value1, value2); +Console.WriteLine("Add({0},{1}) = {2}", value1, value2, result); ``` - - Use the and methods to locate a service based on its endpoint address. This is useful when the endpoint address is not network addressable. The Resolve methods take an instance of which allows you to specify the endpoint address of the service you are resolving, the maximum duration of the resolve operation, and a set of extensions. The following example shows how to use the method to resolve a service. - -```csharp -DiscoveryClient dc = new DiscoveryClient(new UdpDiscoveryEndpoint()); -ResolveCriteria criteria = new ResolveCriteria(endpointAddress); -ResolveResponse response = dc.Resolve(criteria); -EndpointAddress newEp = response.EndpointDiscoveryMetadata.Address; -``` - -## DynamicEndpoint - - is a standard endpoint (For more information, see [Standard Endpoints](standard-endpoints.md)) which performs discovery and automatically selects a matching service. Just create a passing in the contract to search for and the binding to use and pass the instance to the WCF client. The following example shows how to create and use a to call the calculator service. The discovery is performed every time the client is opened. Any endpoint defined in configuration can also be turned into a by adding the `kind ="dynamicEndpoint"` attribute to the endpoint configuration element. - -```csharp -DynamicEndpoint dynamicEndpoint = new DynamicEndpoint(ContractDescription.GetContract(typeof(ICalculatorService)), new WSHttpBinding()); -CalculatorServiceClient client = new CalculatorServiceClient(dynamicEndpoint); - -Console.WriteLine("Invoking CalculatorService"); -Console.WriteLine(); - -double value1 = 100.00D; -double value2 = 15.99D; - -double result = client.Add(value1, value2); -Console.WriteLine("Add({0},{1}) = {2}", value1, value2, result); -``` - + ## See also - [Discovery with Scopes](../samples/discovery-with-scopes-sample.md) diff --git a/docs/framework/wcf/feature-details/distributed-application-security.md b/docs/framework/wcf/feature-details/distributed-application-security.md index c795218a229df..cbbbcd877c861 100644 --- a/docs/framework/wcf/feature-details/distributed-application-security.md +++ b/docs/framework/wcf/feature-details/distributed-application-security.md @@ -88,7 +88,7 @@ Windows Communication Foundation (WCF) security is broken into three major funct For each of the client credential types, the WCF programming model allows you to specify the credential values and credential validators by using service behaviors and channel behaviors. - WCF security has two types of credentials: service credential behaviors and channel credential behaviors. Credential behaviors in WCF specify the actual data, namely, credentials used to meet the security requirements expressed through bindings. In WCF, a client class is the runtime component that converts between operation invocation and messages. All clients inherit from the class. The property on the base class allows you to specify various values of client credentials. + WCF security has two types of credentials: service credential behaviors and channel credential behaviors. Credential behaviors in WCF specify the actual data, namely, credentials used to meet the security requirements expressed through bindings. In WCF, a client class is the runtime component that converts between operation invocation and messages. All clients inherit from the class. The property on the base class allows you to specify various values of client credentials. In WCF, service behaviors are attributes applied to the class implementing a service contract (interface) to programmatically control the service. The class allows you to specify certificates for service credential and client validation settings for various client credential types. @@ -96,7 +96,7 @@ Windows Communication Foundation (WCF) security is broken into three major funct The message security mode allows you to perform transfer security so that the service credential is configured at the client out of band. For example, if you are using a certificate stored in the Windows certificate store, you must use a tool such as a Microsoft Management Console (MMC) snap-in. - The message security mode also allows you to perform transfer security so that the service credential is exchanged with the client as part of an initial negotiation. To enable negotiation, set the property to `true`. + The message security mode also allows you to perform transfer security so that the service credential is exchanged with the client as part of an initial negotiation. To enable negotiation, set the property to `true`. ## See also diff --git a/docs/framework/wcf/feature-details/duplex-services.md b/docs/framework/wcf/feature-details/duplex-services.md index 01c32b104e66d..248b1b1029558 100644 --- a/docs/framework/wcf/feature-details/duplex-services.md +++ b/docs/framework/wcf/feature-details/duplex-services.md @@ -11,7 +11,7 @@ ms.assetid: 396b875a-d203-4ebe-a3a1-6a330d962e95 A duplex service contract is a message exchange pattern in which both endpoints can send messages to the other independently. A duplex service, therefore, can send messages back to the client endpoint, providing event-like behavior. Duplex communication occurs when a client connects to a service and provides the service with a channel on which the service can send messages back to the client. Note that the event-like behavior of duplex services only works within a session. -To create a duplex contract you create a pair of interfaces. The first is the service contract interface that describes the operations that a client can invoke. That service contract must specify a *callback contract* in the property. The callback contract is the interface that defines the operations that the service can call on the client endpoint. A duplex contract does not require a session, although the system-provided duplex bindings make use of them. +To create a duplex contract you create a pair of interfaces. The first is the service contract interface that describes the operations that a client can invoke. That service contract must specify a *callback contract* in the property. The callback contract is the interface that defines the operations that the service can call on the client endpoint. A duplex contract does not require a session, although the system-provided duplex bindings make use of them. The following is an example of a duplex contract. diff --git a/docs/framework/wcf/feature-details/durable-duplex-correlation.md b/docs/framework/wcf/feature-details/durable-duplex-correlation.md index 0d3384a78a086..7a121c3ac8eee 100644 --- a/docs/framework/wcf/feature-details/durable-duplex-correlation.md +++ b/docs/framework/wcf/feature-details/durable-duplex-correlation.md @@ -10,10 +10,10 @@ Durable duplex correlation, also known as callback correlation, is useful when a ## Using Durable Duplex Correlation - To use durable duplex correlation, the two services must use a context-enabled binding that supports two-way operations, such as or . The calling service registers a with the desired binding on their client . The receiving service receives this data in the initial call and then uses it on its own in the activity that makes the call back to the calling service. In this example, two services communicate with each other. The first service invokes a method on the second service and then waits for a reply. The second service knows the name of the callback method, but the endpoint of the service that implements this method isn't known at design time. + To use durable duplex correlation, the two services must use a context-enabled binding that supports two-way operations, such as or . The calling service registers a with the desired binding on their client . The receiving service receives this data in the initial call and then uses it on its own in the activity that makes the call back to the calling service. In this example, two services communicate with each other. The first service invokes a method on the second service and then waits for a reply. The second service knows the name of the callback method, but the endpoint of the service that implements this method isn't known at design time. > [!NOTE] -> Durable duplex can only be used when the of the endpoint is configured with . If it's not, then an exception is thrown with the following message: "The message contains a callback context header with an endpoint reference for AddressingVersion. Callback context can only be transmitted when the AddressingVersion is configured with 'WSAddressing10'." +> Durable duplex can only be used when the of the endpoint is configured with . If it's not, then an exception is thrown with the following message: "The message contains a callback context header with an endpoint reference for AddressingVersion. Callback context can only be transmitted when the AddressingVersion is configured with 'WSAddressing10'." In the following example, a workflow service is hosted that creates a callback using . diff --git a/docs/framework/wcf/feature-details/elevation-of-privilege.md b/docs/framework/wcf/feature-details/elevation-of-privilege.md index efb655900ac81..af171242b96e6 100644 --- a/docs/framework/wcf/feature-details/elevation-of-privilege.md +++ b/docs/framework/wcf/feature-details/elevation-of-privilege.md @@ -2,7 +2,7 @@ description: "Learn more about: Elevation of Privilege" title: "Elevation of Privilege" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "elevation of privilege [WCF]" - "security [WCF], elevation of privilege" ms.assetid: 146e1c66-2a76-4ed3-98a5-fd77851a06d9 @@ -10,81 +10,81 @@ ms.custom: sfi-ropc-nochange --- # Elevation of Privilege -*Elevation of privilege* results from giving an attacker authorization permissions beyond those initially granted. For example, an attacker with a privilege set of "read only" permissions somehow elevates the set to include "read and write." - -## Trusted STS Should Sign SAML Token Claims - - A Security Assertions Markup Language (SAML) token is a generic XML token that is the default type for issued tokens. A SAML token can be constructed by a Security Token Service (STS) that the end Web service trusts in a typical exchange. SAML tokens contain claims in statements. An attacker may copy the claims from a valid token, create a new SAML token, and sign it with a different issuer. The intent is to determine whether the server is validating issuers and, if not, utilize the weakness to construct SAML tokens that allow privileges beyond those intended by a trusted STS. - - The class verifies the digital signature contained within a SAML token, and the default requires that SAML tokens be signed by an X.509 certificate that is valid when the of the class is set to . `ChainTrust` mode alone is insufficient to determine whether the issuer of the SAML token is trusted. Services that require a more granular trust model can either use authorization and enforcement policies to check the issuer of the claim sets produced by issued token authentication or use the X.509 validation settings on to restrict the set of allowed signing certificates. For more information, see [Managing Claims and Authorization with the Identity Model](managing-claims-and-authorization-with-the-identity-model.md) and [Federation and Issued Tokens](federation-and-issued-tokens.md). - -## Switching Identity Without a Security Context - - The following applies only to WinFX. - - When a connection is established between a client and server, the identity of the client does not change, except in one situation: after the WCF client is opened, if all of the following conditions are true: - -- The procedures to establish a security context (using a transport security session or message security session) is switched off ( property is set to `false` in case of message security or transport not capable of establishing security sessions is used in transport security case. HTTPS is one example of such transport). - -- You are using Windows authentication. - -- You do not explicitly set the credential. - -- You are calling the service under the impersonated security context. - - If these conditions are true, the identity used to authenticate the client to the service might change (it might not be the impersonated identity but the process identity instead) after the WCF client is opened. This occurs because the Windows credential used to authenticate the client to the service is transmitted with every message, and the credential used for authentication is obtained from the current thread's Windows identity. If the Windows identity of the current thread changes (for example, by impersonating a different caller), the credential that is attached to the message and used to authenticate the client to the service might also change. - - If you want to have deterministic behavior when using Windows authentication together with impersonation you need to explicitly set the Windows credential or you need to establish a security context with the service. To do this, use a message security session or a transport security session. For example, the net.tcp transport can provide a transport security session. Additionally, you must use only a synchronous version of client operations when calling the service. If you establish a message security context, you should not keep the connection to the service open longer than the configured session renewal period, because the identity can also change during the session renewal process. - -### Credentials Capture - - The following applies to .NET Framework 3.5, and subsequent versions. - - Credentials used by the client or the service are based on the current context thread. The credentials are obtained when the `Open` method (or `BeginOpen`, for asynchronous calls) of the client or service is called. For both the and classes, the `Open` and `BeginOpen` methods inherit from the and methods of the class. - +*Elevation of privilege* results from giving an attacker authorization permissions beyond those initially granted. For example, an attacker with a privilege set of "read only" permissions somehow elevates the set to include "read and write." + +## Trusted STS Should Sign SAML Token Claims + + A Security Assertions Markup Language (SAML) token is a generic XML token that is the default type for issued tokens. A SAML token can be constructed by a Security Token Service (STS) that the end Web service trusts in a typical exchange. SAML tokens contain claims in statements. An attacker may copy the claims from a valid token, create a new SAML token, and sign it with a different issuer. The intent is to determine whether the server is validating issuers and, if not, utilize the weakness to construct SAML tokens that allow privileges beyond those intended by a trusted STS. + + The class verifies the digital signature contained within a SAML token, and the default requires that SAML tokens be signed by an X.509 certificate that is valid when the of the class is set to . `ChainTrust` mode alone is insufficient to determine whether the issuer of the SAML token is trusted. Services that require a more granular trust model can either use authorization and enforcement policies to check the issuer of the claim sets produced by issued token authentication or use the X.509 validation settings on to restrict the set of allowed signing certificates. For more information, see [Managing Claims and Authorization with the Identity Model](managing-claims-and-authorization-with-the-identity-model.md) and [Federation and Issued Tokens](federation-and-issued-tokens.md). + +## Switching Identity Without a Security Context + + The following applies only to WinFX. + + When a connection is established between a client and server, the identity of the client does not change, except in one situation: after the WCF client is opened, if all of the following conditions are true: + +- The procedures to establish a security context (using a transport security session or message security session) is switched off ( property is set to `false` in case of message security or transport not capable of establishing security sessions is used in transport security case. HTTPS is one example of such transport). + +- You are using Windows authentication. + +- You do not explicitly set the credential. + +- You are calling the service under the impersonated security context. + + If these conditions are true, the identity used to authenticate the client to the service might change (it might not be the impersonated identity but the process identity instead) after the WCF client is opened. This occurs because the Windows credential used to authenticate the client to the service is transmitted with every message, and the credential used for authentication is obtained from the current thread's Windows identity. If the Windows identity of the current thread changes (for example, by impersonating a different caller), the credential that is attached to the message and used to authenticate the client to the service might also change. + + If you want to have deterministic behavior when using Windows authentication together with impersonation you need to explicitly set the Windows credential or you need to establish a security context with the service. To do this, use a message security session or a transport security session. For example, the net.tcp transport can provide a transport security session. Additionally, you must use only a synchronous version of client operations when calling the service. If you establish a message security context, you should not keep the connection to the service open longer than the configured session renewal period, because the identity can also change during the session renewal process. + +### Credentials Capture + + The following applies to .NET Framework 3.5, and subsequent versions. + + Credentials used by the client or the service are based on the current context thread. The credentials are obtained when the `Open` method (or `BeginOpen`, for asynchronous calls) of the client or service is called. For both the and classes, the `Open` and `BeginOpen` methods inherit from the and methods of the class. + > [!NOTE] -> When using the `BeginOpen` method, the credentials captured cannot be guaranteed to be the credentials of the process that calls the method. - -## Token Caches Allow Replay Using Obsolete Data - - WCF uses the local security authority (LSA) `LogonUser` function to authenticate users by user name and password. Because the logon function is a costly operation, WCF allows you to cache tokens that represent authenticated users to increase performance. The caching mechanism saves the results from `LogonUser` for subsequent uses. This mechanism is disabled by default; to enable it, set the property to `true`, or use the `cacheLogonTokens` attribute of the [\](../../configure-apps/file-schema/wcf/usernameauthentication.md). - - You can set a Time to Live (TTL) for the cached tokens by setting the property to a , or use the `cachedLogonTokenLifetime` attribute of the `userNameAuthentication` element; the default is 15 minutes. Note that while a token is cached, any client that presents the same user name and password can use the token, even if the user account is deleted from Windows or if its password has been changed. Until the TTL expires and the token is removed from the cache, WCF allows the (possibly malicious) user to authenticate. - - To mitigate this: Decrease the attack window by setting the `cachedLogonTokenLifetime` value to the shortest time span your users need. - -## Issued Token Authorization: Expiration Reset to Large Value - - Under certain conditions, the property of the may be set to an unexpectedly larger value (the field value minus one day, or December 20, 9999). - - This occurs when using the and any of the system-provided bindings that have an issued token as the client credential type. - - This also occurs when you create custom bindings by using one of the following methods: - -- - -- - -- - -- - - To mitigate this, the authorization policy must check the action and the expiration time of each authorization policy. - -## The Service Uses a Different Certificate Than the Client Intended - - Under certain conditions, a client can digitally sign a message with an X.509 certificate and have the service retrieve a different certificate than the intended one. - - This can occur under the following circumstances: - -- The client digitally signs a message using an X.509 certificate and does not attach the X.509 certificate to the message, but rather just references the certificate using its subject key identifier. - -- The service's computer contains two or more certificates with the same public key, but they contain different information. - -- The service retrieves a certificate that matches the subject key identifier, but it is not the one the client intended to use. When WCF receives the message and verifies the signature, WCF maps the information in the unintended X.509 certificate to a set of claims that are different and potentially elevated from what the client expected. - - To mitigate this, reference the X.509 certificate another way, such as using . - +> When using the `BeginOpen` method, the credentials captured cannot be guaranteed to be the credentials of the process that calls the method. + +## Token Caches Allow Replay Using Obsolete Data + + WCF uses the local security authority (LSA) `LogonUser` function to authenticate users by user name and password. Because the logon function is a costly operation, WCF allows you to cache tokens that represent authenticated users to increase performance. The caching mechanism saves the results from `LogonUser` for subsequent uses. This mechanism is disabled by default; to enable it, set the property to `true`, or use the `cacheLogonTokens` attribute of the [\](../../configure-apps/file-schema/wcf/usernameauthentication.md). + + You can set a Time to Live (TTL) for the cached tokens by setting the property to a , or use the `cachedLogonTokenLifetime` attribute of the `userNameAuthentication` element; the default is 15 minutes. Note that while a token is cached, any client that presents the same user name and password can use the token, even if the user account is deleted from Windows or if its password has been changed. Until the TTL expires and the token is removed from the cache, WCF allows the (possibly malicious) user to authenticate. + + To mitigate this: Decrease the attack window by setting the `cachedLogonTokenLifetime` value to the shortest time span your users need. + +## Issued Token Authorization: Expiration Reset to Large Value + + Under certain conditions, the property of the may be set to an unexpectedly larger value (the field value minus one day, or December 20, 9999). + + This occurs when using the and any of the system-provided bindings that have an issued token as the client credential type. + + This also occurs when you create custom bindings by using one of the following methods: + +- + +- + +- + +- + + To mitigate this, the authorization policy must check the action and the expiration time of each authorization policy. + +## The Service Uses a Different Certificate Than the Client Intended + + Under certain conditions, a client can digitally sign a message with an X.509 certificate and have the service retrieve a different certificate than the intended one. + + This can occur under the following circumstances: + +- The client digitally signs a message using an X.509 certificate and does not attach the X.509 certificate to the message, but rather just references the certificate using its subject key identifier. + +- The service's computer contains two or more certificates with the same public key, but they contain different information. + +- The service retrieves a certificate that matches the subject key identifier, but it is not the one the client intended to use. When WCF receives the message and verifies the signature, WCF maps the information in the unintended X.509 certificate to a set of claims that are different and potentially elevated from what the client expected. + + To mitigate this, reference the X.509 certificate another way, such as using . + ## See also - [Security Considerations](security-considerations-in-wcf.md) diff --git a/docs/framework/wcf/feature-details/encryption-of-digital-signatures.md b/docs/framework/wcf/feature-details/encryption-of-digital-signatures.md index 0a4c17e476cdd..566dde80b55c6 100644 --- a/docs/framework/wcf/feature-details/encryption-of-digital-signatures.md +++ b/docs/framework/wcf/feature-details/encryption-of-digital-signatures.md @@ -2,7 +2,7 @@ description: "Learn more about: Encryption of Digital Signatures" title: "Encryption of Digital Signatures" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "encryption of digital signatures [WCF]" - "digital signatures [WCF], encryption" - "digital signatures [WCF]" @@ -10,20 +10,20 @@ ms.assetid: 0868866d-40b4-4341-8e42-eee3b7f15b69 --- # Encryption of Digital Signatures -By default, a message is signed and encrypted, and the signature is digitally encrypted. You can control this by creating a custom binding with an instance of the or the and then setting the `MessageProtectionOrder` property of either class to a enumeration value. The default is . This process takes 10 to 40 percent longer than simply signing and encrypting. Disabling encryption of the signature, however, might allow an attacker to guess the contents of the message. This is possible because the signature element contains the hash code of the plain text of every signed part in the message. For example, although the message body is encrypted by default, the unencrypted signature contains the hash code of the message body. If the message is small, an attacker might be able to deduce the contents. Encrypting the signature reduces or eliminates this possibility. - - Therefore, disable encryption of the signature only when the value of the content is low, and the performance gain will be significant, for example, when sending large binary files that have no security implications. - -### To disable digital signing - -1. Create a . For more information, see [How to: Create a Custom Binding Using the SecurityBindingElement](how-to-create-a-custom-binding-using-the-securitybindingelement.md). - -2. Add either an or a to the binding collection. - -3. Set the property to , or set the property to . - - For more information about creating custom bindings, see [Creating User-Defined Bindings](../extending/creating-user-defined-bindings.md). For more information about creating a custom binding for a specific authentication mode, see [How to: Create a SecurityBindingElement for a Specified Authentication Mode](how-to-create-a-securitybindingelement-for-a-specified-authentication-mode.md). - +By default, a message is signed and encrypted, and the signature is digitally encrypted. You can control this by creating a custom binding with an instance of the or the and then setting the `MessageProtectionOrder` property of either class to a enumeration value. The default is . This process takes 10 to 40 percent longer than simply signing and encrypting. Disabling encryption of the signature, however, might allow an attacker to guess the contents of the message. This is possible because the signature element contains the hash code of the plain text of every signed part in the message. For example, although the message body is encrypted by default, the unencrypted signature contains the hash code of the message body. If the message is small, an attacker might be able to deduce the contents. Encrypting the signature reduces or eliminates this possibility. + + Therefore, disable encryption of the signature only when the value of the content is low, and the performance gain will be significant, for example, when sending large binary files that have no security implications. + +### To disable digital signing + +1. Create a . For more information, see [How to: Create a Custom Binding Using the SecurityBindingElement](how-to-create-a-custom-binding-using-the-securitybindingelement.md). + +2. Add either an or a to the binding collection. + +3. Set the property to , or set the property to . + + For more information about creating custom bindings, see [Creating User-Defined Bindings](../extending/creating-user-defined-bindings.md). For more information about creating a custom binding for a specific authentication mode, see [How to: Create a SecurityBindingElement for a Specified Authentication Mode](how-to-create-a-securitybindingelement-for-a-specified-authentication-mode.md). + ## See also - diff --git a/docs/framework/wcf/feature-details/endpoint-addresses.md b/docs/framework/wcf/feature-details/endpoint-addresses.md index 5589181a7d4cf..54a5597b44fe4 100644 --- a/docs/framework/wcf/feature-details/endpoint-addresses.md +++ b/docs/framework/wcf/feature-details/endpoint-addresses.md @@ -2,7 +2,7 @@ description: "Learn more about: Endpoint Addresses" title: "Endpoint Addresses" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "addresses [WCF]" - "Windows Communication Foundation [WCF], addresses" - "WCF [WCF], addresses" @@ -10,140 +10,140 @@ ms.assetid: 13f269e3-ebb1-433c-86cf-54fbd866a627 --- # Endpoint Addresses -Every endpoint has an address associated with it, which is used to locate and identify the endpoint. This address consists primarily of a Uniform Resource Identifier (URI), which specifies the location of the endpoint. The endpoint address is represented in the Windows Communication Foundation (WCF) programming model by the class, which contains an optional property that enables the authentication of the endpoint by other endpoints that exchange messages with it, and a set of optional properties, which define any other SOAP headers required to reach the service. The optional headers provide additional and more detailed addressing information to identify or interact with the service endpoint. The address of an endpoint is represented on the wire as a WS-Addressing endpoint reference (EPR). - -## URI Structure of an Address +Every endpoint has an address associated with it, which is used to locate and identify the endpoint. This address consists primarily of a Uniform Resource Identifier (URI), which specifies the location of the endpoint. The endpoint address is represented in the Windows Communication Foundation (WCF) programming model by the class, which contains an optional property that enables the authentication of the endpoint by other endpoints that exchange messages with it, and a set of optional properties, which define any other SOAP headers required to reach the service. The optional headers provide additional and more detailed addressing information to identify or interact with the service endpoint. The address of an endpoint is represented on the wire as a WS-Addressing endpoint reference (EPR). + +## URI Structure of an Address + + The address URI for most transports has four parts. For example, the four parts of the URI `http://www.fabrikam.com:322/mathservice.svc/secureEndpoint` can be itemized as follows: - The address URI for most transports has four parts. For example, the four parts of the URI `http://www.fabrikam.com:322/mathservice.svc/secureEndpoint` can be itemized as follows: - - Scheme: `http:` - -- Machine: `www.fabrikam.com` - -- (optional) Port: 322 - -- Path: /mathservice.svc/secureEndpoint - -## Defining an Address for a Service - - The endpoint address for a service can be specified either imperatively using code or declaratively through configuration. Defining endpoints in code is usually not practical because the bindings and addresses for a deployed service are typically different from those used while the service is being developed. Generally, it is more practical to define service endpoints using configuration rather than code. Keeping the binding and addressing information out of the code allows them to change without having to recompile or redeploy the application. - -### Defining an Address in Configuration - - To define an endpoint in a configuration file, use the [\](../../configure-apps/file-schema/wcf/endpoint-element.md) element. For details and an example, see [Specifying an Endpoint Address](../specifying-an-endpoint-address.md). - -### Defining an Address in Code - - An endpoint address can be created in code with the class. For details and an example, see [Specifying an Endpoint Address](../specifying-an-endpoint-address.md). - -### Endpoints in WSDL - - An endpoint address can also be represented in WSDL as a WS-Addressing EPR element inside the corresponding endpoint's `wsdl:port` element. The EPR contains the endpoint's address as well as any address properties. For details and an example, see [Specifying an Endpoint Address](../specifying-an-endpoint-address.md). - -## Multiple IIS Binding Support in .NET Framework 3.5 - - Internet service providers often host many applications on the same server and site to increase the site density and lower total cost of ownership. These applications are typically bound to different base addresses. An Internet Information Services (IIS) Web site can contain multiple applications. The applications in a site can be accessed through one or more IIS bindings. - - IIS bindings provide two pieces of information: a binding protocol, and binding information. The binding protocol defines the scheme over which communication occurs, and binding information is the information used to access the site. - - The following example shows the components that can be present in an IIS binding: - -- Binding protocol: HTTP - -- Binding Information: IP Address, Port, Host header - - IIS can specify multiple bindings for each site, which results in multiple base addresses for each scheme. Prior to .NET Framework 3.5, WCF did not support multiple addresses for a schema and, if they were specified, threw a during activation. - - The .NET Framework 3.5 enables Internet service providers to host multiple applications with different base addresses for the same scheme on the same site. - - For example, a site could contain the following base addresses: - + +- Machine: `www.fabrikam.com` + +- (optional) Port: 322 + +- Path: /mathservice.svc/secureEndpoint + +## Defining an Address for a Service + + The endpoint address for a service can be specified either imperatively using code or declaratively through configuration. Defining endpoints in code is usually not practical because the bindings and addresses for a deployed service are typically different from those used while the service is being developed. Generally, it is more practical to define service endpoints using configuration rather than code. Keeping the binding and addressing information out of the code allows them to change without having to recompile or redeploy the application. + +### Defining an Address in Configuration + + To define an endpoint in a configuration file, use the [\](../../configure-apps/file-schema/wcf/endpoint-element.md) element. For details and an example, see [Specifying an Endpoint Address](../specifying-an-endpoint-address.md). + +### Defining an Address in Code + + An endpoint address can be created in code with the class. For details and an example, see [Specifying an Endpoint Address](../specifying-an-endpoint-address.md). + +### Endpoints in WSDL + + An endpoint address can also be represented in WSDL as a WS-Addressing EPR element inside the corresponding endpoint's `wsdl:port` element. The EPR contains the endpoint's address as well as any address properties. For details and an example, see [Specifying an Endpoint Address](../specifying-an-endpoint-address.md). + +## Multiple IIS Binding Support in .NET Framework 3.5 + + Internet service providers often host many applications on the same server and site to increase the site density and lower total cost of ownership. These applications are typically bound to different base addresses. An Internet Information Services (IIS) Web site can contain multiple applications. The applications in a site can be accessed through one or more IIS bindings. + + IIS bindings provide two pieces of information: a binding protocol, and binding information. The binding protocol defines the scheme over which communication occurs, and binding information is the information used to access the site. + + The following example shows the components that can be present in an IIS binding: + +- Binding protocol: HTTP + +- Binding Information: IP Address, Port, Host header + + IIS can specify multiple bindings for each site, which results in multiple base addresses for each scheme. Prior to .NET Framework 3.5, WCF did not support multiple addresses for a schema and, if they were specified, threw a during activation. + + The .NET Framework 3.5 enables Internet service providers to host multiple applications with different base addresses for the same scheme on the same site. + + For example, a site could contain the following base addresses: + - `http://payroll.myorg.com/Service.svc` - + - `http://shipping.myorg.com/Service.svc` - - With .NET Framework 3.5, you specify a prefix filter at the AppDomain level in the configuration file. You do this with the [\](../../configure-apps/file-schema/wcf/baseaddressprefixfilters.md) element, which contains a list of prefixes. The incoming base addresses, supplied by IIS, are filtered based on the optional prefix list. By default, when a prefix is not specified, all addresses are passed through. Specifying the prefix results in only the matching base address for that scheme to be passed through. - - The following is an example of configuration code that uses the prefix filters. - -```xml - - - - - - - - -``` - - In the preceding example, `net.tcp://payroll.myorg.com:8000` and `http://shipping.myorg.com:8000` are the only base addresses, for their respective schemes, which are passed through. - - The `baseAddressPrefixFilter` does not support wildcards. - - The base addresses supplied by IIS may have addresses bound to other schemes not present in `baseAddressPrefixFilters` list. These addresses are not filtered out. - -## Multiple IIS Binding Support in .NET Framework 4 and later - - Starting in .NET 4, you can enable support for multiple bindings in IIS without having to pick a single base address, by setting ’s setting to true. This support is limited to HTTP protocol schemes. - - The following is an example of configuration code that uses multipleSiteBindingsEnabled on [\](../../configure-apps/file-schema/wcf/servicehostingenvironment.md). - -```xml - - - - -``` - - Any baseAddressPrefixFilters settings are ignored, for both HTTP and non-HTTP protocols, when multiple site bindings are enabled using this setting. - - For details and examples, see [Supporting Multiple IIS Site Bindings](supporting-multiple-iis-site-bindings.md) and . - -## Extending Addressing in WCF Services - - The default addressing model of WCF services uses the endpoint address URI for the following purposes: - -- To specify the service listening address, the location at which the endpoint listens for messages, - -- To specify the SOAP address filter, the address an endpoint expects as a SOAP header. - - The values for each of these purposes can be specified separately, allowing several extensions of addressing that cover useful scenarios: - -- SOAP intermediaries: a message sent by a client traverses one or more additional services that process the message before it reaches its final destination. SOAP intermediaries can perform various tasks, such as caching, routing, load-balancing, or schema validation on the messages. This scenario is accomplished by sending messages to a separate physical address (`via`) that targets the intermediary rather than just to a logical address (`wsa:To`) that targets the ultimate destination. - -- The listening address of the endpoint is a private URI and is set to a different value than its `listenURI` property. - - The transport address that the `via` specifies is the location to which a message should initially be sent on its way to some other remote address specified by the `to` parameter at which the service is located. In most Internet scenarios, the `via` URI is the same as the property of the final `to` address of the service. You only distinguish between these two addresses when you must do manual routing. - -### Addressing Headers - - An endpoint can be addressed by one or more SOAP headers in addition to its basic URI. One set of scenarios where this is useful is a set of SOAP intermediary scenarios where an endpoint requires clients of that endpoint to include SOAP headers targeted at intermediaries. - - You can define custom address headers in two ways—by using either code or configuration: - -- In code, create custom address headers by using the class, and then used in the construction of an . - -- In configuration, custom [\](../../configure-apps/file-schema/wcf/headers.md) are specified as children of the [\](../../configure-apps/file-schema/wcf/endpoint-of-client.md) element. - - Configuration is generally preferable to code, as it allows you to change the headers after deployment. - -### Custom Listening Addresses - - You can set the listening address to a different value than the endpoint’s URI. This is useful in intermediary scenarios where the SOAP address to be exposed is that of a public SOAP intermediary, whereas the address where the endpoint actually listens is a private network address. - - You can specify a custom listening address by using either code or configuration: - -- In code, specify a custom listening address by adding a class to the endpoint’s behavior collection. - -- In configuration, specify a custom listening address with the `ListenUri` attribute of the service [\](../../configure-apps/file-schema/wcf/endpoint-element.md) element. - -### Custom SOAP Address Filter - - The is used in conjunction with any property to define an endpoint’s SOAP address filter (). By default, this filter verifies that an incoming message has a `To` message header that matches the endpoint’s URI and that all of the required endpoint headers are present in the message. - - In some scenarios, an endpoint receives all messages that arrive on the underlying transport, and not just those with the appropriate `To` header. To enable this, the user can use the class. - + + With .NET Framework 3.5, you specify a prefix filter at the AppDomain level in the configuration file. You do this with the [\](../../configure-apps/file-schema/wcf/baseaddressprefixfilters.md) element, which contains a list of prefixes. The incoming base addresses, supplied by IIS, are filtered based on the optional prefix list. By default, when a prefix is not specified, all addresses are passed through. Specifying the prefix results in only the matching base address for that scheme to be passed through. + + The following is an example of configuration code that uses the prefix filters. + +```xml + + + + + + + + +``` + + In the preceding example, `net.tcp://payroll.myorg.com:8000` and `http://shipping.myorg.com:8000` are the only base addresses, for their respective schemes, which are passed through. + + The `baseAddressPrefixFilter` does not support wildcards. + + The base addresses supplied by IIS may have addresses bound to other schemes not present in `baseAddressPrefixFilters` list. These addresses are not filtered out. + +## Multiple IIS Binding Support in .NET Framework 4 and later + + Starting in .NET 4, you can enable support for multiple bindings in IIS without having to pick a single base address, by setting ’s setting to true. This support is limited to HTTP protocol schemes. + + The following is an example of configuration code that uses multipleSiteBindingsEnabled on [\](../../configure-apps/file-schema/wcf/servicehostingenvironment.md). + +```xml + + + + +``` + + Any baseAddressPrefixFilters settings are ignored, for both HTTP and non-HTTP protocols, when multiple site bindings are enabled using this setting. + + For details and examples, see [Supporting Multiple IIS Site Bindings](supporting-multiple-iis-site-bindings.md) and . + +## Extending Addressing in WCF Services + + The default addressing model of WCF services uses the endpoint address URI for the following purposes: + +- To specify the service listening address, the location at which the endpoint listens for messages, + +- To specify the SOAP address filter, the address an endpoint expects as a SOAP header. + + The values for each of these purposes can be specified separately, allowing several extensions of addressing that cover useful scenarios: + +- SOAP intermediaries: a message sent by a client traverses one or more additional services that process the message before it reaches its final destination. SOAP intermediaries can perform various tasks, such as caching, routing, load-balancing, or schema validation on the messages. This scenario is accomplished by sending messages to a separate physical address (`via`) that targets the intermediary rather than just to a logical address (`wsa:To`) that targets the ultimate destination. + +- The listening address of the endpoint is a private URI and is set to a different value than its `listenURI` property. + + The transport address that the `via` specifies is the location to which a message should initially be sent on its way to some other remote address specified by the `to` parameter at which the service is located. In most Internet scenarios, the `via` URI is the same as the property of the final `to` address of the service. You only distinguish between these two addresses when you must do manual routing. + +### Addressing Headers + + An endpoint can be addressed by one or more SOAP headers in addition to its basic URI. One set of scenarios where this is useful is a set of SOAP intermediary scenarios where an endpoint requires clients of that endpoint to include SOAP headers targeted at intermediaries. + + You can define custom address headers in two ways—by using either code or configuration: + +- In code, create custom address headers by using the class, and then used in the construction of an . + +- In configuration, custom [\](../../configure-apps/file-schema/wcf/headers.md) are specified as children of the [\](../../configure-apps/file-schema/wcf/endpoint-of-client.md) element. + + Configuration is generally preferable to code, as it allows you to change the headers after deployment. + +### Custom Listening Addresses + + You can set the listening address to a different value than the endpoint’s URI. This is useful in intermediary scenarios where the SOAP address to be exposed is that of a public SOAP intermediary, whereas the address where the endpoint actually listens is a private network address. + + You can specify a custom listening address by using either code or configuration: + +- In code, specify a custom listening address by adding a class to the endpoint’s behavior collection. + +- In configuration, specify a custom listening address with the `ListenUri` attribute of the service [\](../../configure-apps/file-schema/wcf/endpoint-element.md) element. + +### Custom SOAP Address Filter + + The is used in conjunction with any property to define an endpoint’s SOAP address filter (). By default, this filter verifies that an incoming message has a `To` message header that matches the endpoint’s URI and that all of the required endpoint headers are present in the message. + + In some scenarios, an endpoint receives all messages that arrive on the underlying transport, and not just those with the appropriate `To` header. To enable this, the user can use the class. + ## See also - [Specifying an Endpoint Address](../specifying-an-endpoint-address.md) diff --git a/docs/framework/wcf/feature-details/endpoints-addresses-bindings-and-contracts.md b/docs/framework/wcf/feature-details/endpoints-addresses-bindings-and-contracts.md index b6fe015bb3e68..1287207dd09e4 100644 --- a/docs/framework/wcf/feature-details/endpoints-addresses-bindings-and-contracts.md +++ b/docs/framework/wcf/feature-details/endpoints-addresses-bindings-and-contracts.md @@ -30,9 +30,9 @@ Each endpoint consists of the following: - Address: The address uniquely identifies the endpoint and tells potential consumers of the service where it is located. It is represented in the WCF object model by the class. An class contains: - - A property, which represents the address of the service. + - A property, which represents the address of the service. - - An property, which represents the security identity of the service and a collection of optional message headers. The optional message headers are used to provide additional and more detailed addressing information to identify or interact with the endpoint. + - An property, which represents the security identity of the service and a collection of optional message headers. The optional message headers are used to provide additional and more detailed addressing information to identify or interact with the endpoint. For more information, see [Specifying an Endpoint Address](../specifying-an-endpoint-address.md). @@ -58,7 +58,7 @@ Each endpoint consists of the following: For more information about defining a contract, see [Designing Service Contracts](../designing-service-contracts.md). -- Behaviors: You can use endpoint behaviors to customize the local behavior of the service endpoint. Endpoint behaviors achieve this by participating in the process of building a WCF runtime. An example of an endpoint behavior is the property, which allows you to specify a different listening address than the SOAP or Web Services Description Language (WSDL) address. For more information, see [ClientViaBehavior](../diagnostics/wmi/clientviabehavior.md). +- Behaviors: You can use endpoint behaviors to customize the local behavior of the service endpoint. Endpoint behaviors achieve this by participating in the process of building a WCF runtime. An example of an endpoint behavior is the property, which allows you to specify a different listening address than the SOAP or Web Services Description Language (WSDL) address. For more information, see [ClientViaBehavior](../diagnostics/wmi/clientviabehavior.md). ## Defining Endpoints diff --git a/docs/framework/wcf/feature-details/enumeration-types-in-data-contracts.md b/docs/framework/wcf/feature-details/enumeration-types-in-data-contracts.md index 8d88e6cbf85e5..7b44969da74a3 100644 --- a/docs/framework/wcf/feature-details/enumeration-types-in-data-contracts.md +++ b/docs/framework/wcf/feature-details/enumeration-types-in-data-contracts.md @@ -2,103 +2,103 @@ title: "Enumeration Types in Data Contracts" description: Learn about how the data contract model expresses enumerations as part of the WFC programming model. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "data contracts [WCF], enumeration types" ms.assetid: b5d694da-68cb-4b74-a5fb-75108a68ec3b --- # Enumeration Types in Data Contracts -Enumerations can be expressed in the data contract model. This topic walks through several examples that explain the programming model. - -## Enumeration Basics +Enumerations can be expressed in the data contract model. This topic walks through several examples that explain the programming model. + +## Enumeration Basics + + One way to use enumeration types in the data contract model is to apply the attribute to the type. You must then apply the attribute to each member that must be included in the data contract. + + The following example shows two classes. The first uses the enumeration and the second defines the enumeration. - One way to use enumeration types in the data contract model is to apply the attribute to the type. You must then apply the attribute to each member that must be included in the data contract. - - The following example shows two classes. The first uses the enumeration and the second defines the enumeration. - [!code-csharp[c_DataContractEnumerations#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractenumerations/cs/source.cs#1)] - [!code-vb[c_DataContractEnumerations#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractenumerations/vb/source.vb#1)] - - An instance of the `Car` class can be sent or received only if the `condition` field is set to one of the values `New`, `Used`, or `Rental`. If the `condition` is `Broken` or `Stolen`, a is thrown. - - You can use the properties ( and ) as usual for enumeration data contracts. - -### Enumeration Member Values - - Generally the data contract includes enumeration member names, not numerical values. However, when using the data contract model, if the receiving side is a WCF client, the exported schema preserves the numerical values. Note that this is not the case when using the [Using the XmlSerializer Class](using-the-xmlserializer-class.md). - - In the preceding example, if `condition` is set to `Used` and the data is serialized to XML, the resulting XML is `Used` and not `1`. Therefore, the following data contract is equivalent to the data contract of `CarConditionEnum`. - + [!code-vb[c_DataContractEnumerations#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractenumerations/vb/source.vb#1)] + + An instance of the `Car` class can be sent or received only if the `condition` field is set to one of the values `New`, `Used`, or `Rental`. If the `condition` is `Broken` or `Stolen`, a is thrown. + + You can use the properties ( and ) as usual for enumeration data contracts. + +### Enumeration Member Values + + Generally the data contract includes enumeration member names, not numerical values. However, when using the data contract model, if the receiving side is a WCF client, the exported schema preserves the numerical values. Note that this is not the case when using the [Using the XmlSerializer Class](using-the-xmlserializer-class.md). + + In the preceding example, if `condition` is set to `Used` and the data is serialized to XML, the resulting XML is `Used` and not `1`. Therefore, the following data contract is equivalent to the data contract of `CarConditionEnum`. + [!code-csharp[c_DataContractEnumerations#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractenumerations/cs/source.cs#2)] - [!code-vb[c_DataContractEnumerations#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractenumerations/vb/source.vb#2)] - - For example, you can use `CarConditionEnum` on the sending side and `CarConditionWithNumbers` on the receiving side. Although the sending side uses the value "1" for `Used` and the receiving side uses the value "20," the XML representation is `Used` for both sides. - - To be included in the data contract, you must apply the attribute. In the .NET Framework, you can always apply the special value 0 (zero) to an enumeration, which is also the default value for any enumeration. However, even this special zero value cannot be serialized unless it is marked with the attribute. - - There are two exceptions to this: - -- Flag enumerations (discussed later in this topic). - -- Enumeration data members with the property set to `false` (in which case, the enumeration with the value zero is omitted from the serialized data). - -### Customizing Enumeration Member Values - - You can customize the enumeration member value that forms a part of the data contract by using the property of the attribute. - - For example, the following data contract is also equivalent to the data contract of the `CarConditionEnum`. - + [!code-vb[c_DataContractEnumerations#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractenumerations/vb/source.vb#2)] + + For example, you can use `CarConditionEnum` on the sending side and `CarConditionWithNumbers` on the receiving side. Although the sending side uses the value "1" for `Used` and the receiving side uses the value "20," the XML representation is `Used` for both sides. + + To be included in the data contract, you must apply the attribute. In the .NET Framework, you can always apply the special value 0 (zero) to an enumeration, which is also the default value for any enumeration. However, even this special zero value cannot be serialized unless it is marked with the attribute. + + There are two exceptions to this: + +- Flag enumerations (discussed later in this topic). + +- Enumeration data members with the property set to `false` (in which case, the enumeration with the value zero is omitted from the serialized data). + +### Customizing Enumeration Member Values + + You can customize the enumeration member value that forms a part of the data contract by using the property of the attribute. + + For example, the following data contract is also equivalent to the data contract of the `CarConditionEnum`. + [!code-csharp[c_DataContractEnumerations#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractenumerations/cs/source.cs#3)] - [!code-vb[c_DataContractEnumerations#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractenumerations/vb/source.vb#3)] - - When serialized, the value of `PreviouslyOwned` has the XML representation `Used`. - -## Simple Enumerations - - You can also serialize enumeration types to which the attribute has not been applied. Such enumeration types are treated exactly as previously described, except that every member (that does not have the attribute applied) is treated as if the attribute has been applied. For example, the following enumeration implicitly has a data contract equivalent to the preceding `CarConditionEnum` example. - + [!code-vb[c_DataContractEnumerations#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractenumerations/vb/source.vb#3)] + + When serialized, the value of `PreviouslyOwned` has the XML representation `Used`. + +## Simple Enumerations + + You can also serialize enumeration types to which the attribute has not been applied. Such enumeration types are treated exactly as previously described, except that every member (that does not have the attribute applied) is treated as if the attribute has been applied. For example, the following enumeration implicitly has a data contract equivalent to the preceding `CarConditionEnum` example. + [!code-csharp[c_DataContractEnumerations#6](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractenumerations/cs/source.cs#6)] - [!code-vb[c_DataContractEnumerations#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractenumerations/vb/source.vb#6)] - - You can use simple enumerations when you do not need to customize the enumeration's data contract name and namespace and the enumeration member values. - -#### Notes on Simple Enumerations - - Applying the attribute to simple enumerations has no effect. - - It makes no difference whether or not the attribute is applied to the enumeration. - - The fact that the class honors the attribute applied to enumeration members is different from the behavior of the and the . Both of those serializers ignore the attribute. - -## Flag Enumerations - - You can apply the attribute to enumerations. In that case, a list of zero or more enumeration values can be sent or received simultaneously. - - To do so, apply the attribute to the flag enumeration and then mark all the members that are powers of two with the attribute. Note that to use a flag enumeration, the progression must be an uninterrupted sequence of powers of 2 (for example, 1, 2, 4, 8, 16, 32, 64). - - The following steps apply to sending a flag's enumeration value: - -1. Attempt to find an enumeration member (with the attribute applied) that maps to the numeric value. If found, send a list that contains just that member. - -2. Attempt to break the numeric value into a sum such that there are enumeration members (each with the attribute applied) that map to each part of the sum. Send the list of all these members. Note that the *greedy algorithm* is used to find such a sum, and thus there is no guarantee that such a sum is found even if it is present. To avoid this problem, make sure that the numeric values of the enumeration members are powers of two. - -3. If the preceding two steps fail, and the numeric value is nonzero, throw a . If the numeric value is zero, send the empty list. - -### Example - - The following enumeration example can be used in a flag operation. - + [!code-vb[c_DataContractEnumerations#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractenumerations/vb/source.vb#6)] + + You can use simple enumerations when you do not need to customize the enumeration's data contract name and namespace and the enumeration member values. + +#### Notes on Simple Enumerations + + Applying the attribute to simple enumerations has no effect. + + It makes no difference whether or not the attribute is applied to the enumeration. + + The fact that the class honors the attribute applied to enumeration members is different from the behavior of the and the . Both of those serializers ignore the attribute. + +## Flag Enumerations + + You can apply the attribute to enumerations. In that case, a list of zero or more enumeration values can be sent or received simultaneously. + + To do so, apply the attribute to the flag enumeration and then mark all the members that are powers of two with the attribute. Note that to use a flag enumeration, the progression must be an uninterrupted sequence of powers of 2 (for example, 1, 2, 4, 8, 16, 32, 64). + + The following steps apply to sending a flag's enumeration value: + +1. Attempt to find an enumeration member (with the attribute applied) that maps to the numeric value. If found, send a list that contains just that member. + +2. Attempt to break the numeric value into a sum such that there are enumeration members (each with the attribute applied) that map to each part of the sum. Send the list of all these members. Note that the *greedy algorithm* is used to find such a sum, and thus there is no guarantee that such a sum is found even if it is present. To avoid this problem, make sure that the numeric values of the enumeration members are powers of two. + +3. If the preceding two steps fail, and the numeric value is nonzero, throw a . If the numeric value is zero, send the empty list. + +### Example + + The following enumeration example can be used in a flag operation. + [!code-csharp[c_DataContractEnumerations#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractenumerations/cs/source.cs#4)] - [!code-vb[c_DataContractEnumerations#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractenumerations/vb/source.vb#4)] - - The following example values are serialized as indicated. - + [!code-vb[c_DataContractEnumerations#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractenumerations/vb/source.vb#4)] + + The following example values are serialized as indicated. + [!code-csharp[c_DataContractEnumerations#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontractenumerations/cs/source.cs#5)] - [!code-vb[c_DataContractEnumerations#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractenumerations/vb/source.vb#5)] - + [!code-vb[c_DataContractEnumerations#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontractenumerations/vb/source.vb#5)] + ## See also - diff --git a/docs/framework/wcf/feature-details/exporting-and-importing-metadata.md b/docs/framework/wcf/feature-details/exporting-and-importing-metadata.md index dc599486ba9f9..d9e4fee7fe4a6 100644 --- a/docs/framework/wcf/feature-details/exporting-and-importing-metadata.md +++ b/docs/framework/wcf/feature-details/exporting-and-importing-metadata.md @@ -27,11 +27,11 @@ In Windows Communication Foundation (WCF), exporting metadata is the process of The type gives you control over how to import the metadata. You can import all of the endpoints, all of the bindings, or all of the contracts. You can import all of the endpoints associated with a specific WSDL service, binding, or port type. You can also import the endpoint for a specific WSDL port, the binding for a specific WSDL binding or the contract for a specific WSDL port type. - The also exposes a property that allows you to specify a set of contracts that do not need to be imported. The uses the contracts in the property instead of importing a contract with the same qualified name from the metadata. + The also exposes a property that allows you to specify a set of contracts that do not need to be imported. The uses the contracts in the property instead of importing a contract with the same qualified name from the metadata. ### Importing Policies - The type collects the policy expressions attached to the message, operation, and endpoint policy subjects and then uses the implementations in the collection to import the policy expressions. + The type collects the policy expressions attached to the message, operation, and endpoint policy subjects and then uses the implementations in the collection to import the policy expressions. The policy import logic automatically handles policy references to policy expressions in the same WSDL document and is identified with a `wsu:Id` or `xml:id` attribute. The policy import logic protects applications against circular policy references by limiting the size of a policy expression to 4096 nodes, where a node is a one of the following elements: `wsp:Policy`, `wsp:All`, `wsp:ExactlyOne`, `wsp:policyReference`. @@ -43,7 +43,7 @@ In Windows Communication Foundation (WCF), exporting metadata is the process of Both the and the types expose an `Errors` property that can contain a collection of error and warning messages encountered during the export and import processes, respectively, that can be used when implementing tools. - The type generally throws an exception for an exception caught during the import process and adds a corresponding error to its `Errors` property. The , , , and methods, however, do not throw these exceptions, so you must check the `Errors` property to determine if any issues occurred when calling these methods. + The type generally throws an exception for an exception caught during the import process and adds a corresponding error to its `Errors` property. The , , , and methods, however, do not throw these exceptions, so you must check the `Errors` property to determine if any issues occurred when calling these methods. The type rethrows any exceptions caught during the export process. These exceptions are not captured as errors in the `Errors` property. Once the throws an exception, it is in a faulted state and cannot be reused. The does add warnings to its `Errors` property when an operation cannot be exported because it uses wildcard actions and when duplicate binding names are encountered. diff --git a/docs/framework/wcf/feature-details/exporting-schemas-from-classes.md b/docs/framework/wcf/feature-details/exporting-schemas-from-classes.md index 88949bcd1e431..94254bb88ef76 100644 --- a/docs/framework/wcf/feature-details/exporting-schemas-from-classes.md +++ b/docs/framework/wcf/feature-details/exporting-schemas-from-classes.md @@ -2,7 +2,7 @@ description: "Learn more about: Exporting Schemas from Classes" title: "Exporting Schemas from Classes" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "WCF, schema import and export" - "schemas [WCF], exporting from classes" - "schemas [WCF]" @@ -12,51 +12,51 @@ ms.assetid: bb57b962-70c1-45a9-93d5-e721e340a13f --- # Exporting Schemas from Classes -To generate XML Schema definition language (XSD) schemas from classes that are used in the data contract model, use the class. This topic describes the process for creating schemas. - -## The Export Process - - The schema export process starts with one or more types and produces an that describes the XML projection of these types. - - The `XmlSchemaSet` is part of the .NET Framework’s Schema Object Model (SOM) that represents a set of XSD Schema documents. To create XSD documents from an `XmlSchemaSet`, use the collection of schemas from the property of the `XmlSchemaSet` class. Then serialize each object using the . - -#### To export schemas - -1. Create an instance of the . - -2. Optional. Pass an in the constructor. In this case, the schema generated during the schema export is added to this instance instead of starting with a blank . - -3. Optional. Call one of the methods. The method determines whether the specified type can be exported. The method has the same overloads as the `Export` method in the next step. - -4. Call one of the methods. There are three overloads taking a , a of `Type` objects, or a of objects. In the last case, all types in all the given assemblies are exported. - - Multiple calls to the `Export` method results in multiple items being added to the same `XmlSchemaSet`. A type is not generated into the `XmlSchemaSet` if it already exists there. Therefore, calling `Export` multiple times on the same `XsdDataContractExporter` is preferable to creating multiple instances of the `XsdDataContractExporter` class. This avoids duplicate schema types from being generated. - +To generate XML Schema definition language (XSD) schemas from classes that are used in the data contract model, use the class. This topic describes the process for creating schemas. + +## The Export Process + + The schema export process starts with one or more types and produces an that describes the XML projection of these types. + + The `XmlSchemaSet` is part of the .NET Framework’s Schema Object Model (SOM) that represents a set of XSD Schema documents. To create XSD documents from an `XmlSchemaSet`, use the collection of schemas from the property of the `XmlSchemaSet` class. Then serialize each object using the . + +#### To export schemas + +1. Create an instance of the . + +2. Optional. Pass an in the constructor. In this case, the schema generated during the schema export is added to this instance instead of starting with a blank . + +3. Optional. Call one of the methods. The method determines whether the specified type can be exported. The method has the same overloads as the `Export` method in the next step. + +4. Call one of the methods. There are three overloads taking a , a of `Type` objects, or a of objects. In the last case, all types in all the given assemblies are exported. + + Multiple calls to the `Export` method results in multiple items being added to the same `XmlSchemaSet`. A type is not generated into the `XmlSchemaSet` if it already exists there. Therefore, calling `Export` multiple times on the same `XsdDataContractExporter` is preferable to creating multiple instances of the `XsdDataContractExporter` class. This avoids duplicate schema types from being generated. + > [!NOTE] - > If there is a failure during export, the `XmlSchemaSet` will be in an unpredictable state. - -5. Access the through the property. - -## Export Options - - You can set the property of the to an instance of the class to control various aspects of the export process. Specifically, you can set the following options: - -- . This collection of `Type` represents the known types for the types being exported. (For more information, see [Data Contract Known Types](data-contract-known-types.md).) These known types are exported on every `Export` call in addition to the types passed to the `Export` method. - -- . An can be supplied through this property that will customize the export process. For more information, see [Data Contract Surrogates](../extending/data-contract-surrogates.md). By default, no surrogate is used. - -## Helper Methods - - In addition to its primary role of exporting schema, the `XsdDataContractExporter` provides several useful helper methods that provide information about types. These include: - -- method. This method takes a `Type` and returns an that represents the root element name and namespace that would be used if this type were serialized as the root object. - -- method. This method takes a `Type` and returns an that represents the name of the XSD schema type that would be used if this type were exported to the schema. For types represented as anonymous types in the schema, this method returns `null`. - -- method. This method works only with types that are represented as anonymous types in the schema, and returns `null` for all other types. For anonymous types, this method returns an that represents a given `Type`. - - Export options affect all of these methods. - + > If there is a failure during export, the `XmlSchemaSet` will be in an unpredictable state. + +5. Access the through the property. + +## Export Options + + You can set the property of the to an instance of the class to control various aspects of the export process. Specifically, you can set the following options: + +- . This collection of `Type` represents the known types for the types being exported. (For more information, see [Data Contract Known Types](data-contract-known-types.md).) These known types are exported on every `Export` call in addition to the types passed to the `Export` method. + +- . An can be supplied through this property that will customize the export process. For more information, see [Data Contract Surrogates](../extending/data-contract-surrogates.md). By default, no surrogate is used. + +## Helper Methods + + In addition to its primary role of exporting schema, the `XsdDataContractExporter` provides several useful helper methods that provide information about types. These include: + +- method. This method takes a `Type` and returns an that represents the root element name and namespace that would be used if this type were serialized as the root object. + +- method. This method takes a `Type` and returns an that represents the name of the XSD schema type that would be used if this type were exported to the schema. For types represented as anonymous types in the schema, this method returns `null`. + +- method. This method works only with types that are represented as anonymous types in the schema, and returns `null` for all other types. For anonymous types, this method returns an that represents a given `Type`. + + Export options affect all of these methods. + ## See also - diff --git a/docs/framework/wcf/feature-details/federation-and-trust.md b/docs/framework/wcf/feature-details/federation-and-trust.md index d46d6ef1e21b5..35534e0594630 100644 --- a/docs/framework/wcf/feature-details/federation-and-trust.md +++ b/docs/framework/wcf/feature-details/federation-and-trust.md @@ -2,41 +2,41 @@ description: "Learn more about: Federation and Trust" title: "Federation and Trust" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "federation [WCF], and trust" ms.assetid: 4bdec4f2-f8a2-4512-bdcf-14ef54b5877a --- # Federation and Trust -This topic covers various aspects related to federated applications, trust boundaries and configuration, and use of issued tokens in Windows Communication Foundation (WCF). - -## Services, Security Token Services, and Trust +This topic covers various aspects related to federated applications, trust boundaries and configuration, and use of issued tokens in Windows Communication Foundation (WCF). + +## Services, Security Token Services, and Trust + + Services that expose federated endpoints typically expect clients to authenticate using a token provided by a specific issuer. It is important that the service is configured with the correct credentials for the issuer; otherwise, it will not be able to verify signatures over the issued tokens, and the client will be unable to communicate with the service. For more information about configuring issuer credentials on the service, see [How to: Configure Credentials on a Federation Service](how-to-configure-credentials-on-a-federation-service.md). + + Similarly, when using symmetric keys, the keys are encrypted for the target service, so you must configure the security token service with the correct credentials for the target service; otherwise, it will be unable to encrypt the key for the target service, and again, the client will be unable to communicate with the service. + + WCF services use the value of the property on the [SecurityBindingElement](../diagnostics/wmi/securitybindingelement.md) to allow for clock skew between the client and service. In federation, the `MaxClockSkew` setting applies to clock skews between both the client and the security token service from where the client obtained the issued token. Therefore, security token services need not make clock-skew allowances when setting the issued token's effective and expiration times. - Services that expose federated endpoints typically expect clients to authenticate using a token provided by a specific issuer. It is important that the service is configured with the correct credentials for the issuer; otherwise, it will not be able to verify signatures over the issued tokens, and the client will be unable to communicate with the service. For more information about configuring issuer credentials on the service, see [How to: Configure Credentials on a Federation Service](how-to-configure-credentials-on-a-federation-service.md). - - Similarly, when using symmetric keys, the keys are encrypted for the target service, so you must configure the security token service with the correct credentials for the target service; otherwise, it will be unable to encrypt the key for the target service, and again, the client will be unable to communicate with the service. - - WCF services use the value of the property on the [SecurityBindingElement](../diagnostics/wmi/securitybindingelement.md) to allow for clock skew between the client and service. In federation, the `MaxClockSkew` setting applies to clock skews between both the client and the security token service from where the client obtained the issued token. Therefore, security token services need not make clock-skew allowances when setting the issued token's effective and expiration times. - > [!NOTE] -> The importance of clock skew increases as the lifetime of the issued token shortens. In most cases, clock skew is not a significant issue if the token lifetime is 30 minutes or more. Scenarios with shorter lifetimes or where the exact validity time of the token is important should be designed to take clock skew into account. - -## Federated Endpoints and Time-Outs - - When a client communicates with a federated endpoint, it must first acquire an appropriate token from a security token service. If the security token service exposes a federated endpoint, the client must first obtain a token from the issuer for that endpoint. Each token acquisition takes time, and that time is subject to the overall time-out for sending the actual message to the final endpoint. - - For example, the time-out on the client-side channel is set to 30 seconds. Two token issuers need to be called to retrieve tokens before sending the message to the final endpoint, and each takes 15 seconds to issue a token. In this case, the attempt will fail and a is thrown. Thus, you need to set the value on the client channel to a value large enough to include the time taken to retrieve all issued tokens. In the case where a value is not specified for the property, the property or the property (or both) need to be set to a value large enough to include the time taken to retrieve all issued tokens. - -## Token Lifetime and Renewal - - WCF clients do not check the issued token when making an initial request to a service. Rather, WCF trusts the security token service to issue a token with appropriate effective and expiration times. If the token is cached by the client and reused, the token lifetime is checked on subsequent requests and the client automatically renews the token if necessary. For more information about token caching, see [How to: Create a Federated Client](how-to-create-a-federated-client.md). - - Specifying short lifetimes, on the order of 30 seconds or less for issued tokens or security context tokens, may result in negotiation time-outs or other exceptions being thrown by WCF clients when requesting issued tokens or when negotiating or renewing security context tokens. - -## Issued Tokens and InclusionMode - - Whether an issued token is serialized in a message sent from a client to a federated endpoint or not is controlled by setting the property of the class. This property can be set to one of the enumeration values, but it is not useful in most federated scenarios. The `SecurityTokenInclusionMode.Never` and `SecurityTokenInclusionMode.AlwaysToInitiator` values cause the client to send a reference to the token issued by the security token service to the relying party. Unless the relying party possesses a copy of the issued token, authentication will fail because the token reference is not resolvable. WCF treats `SecurityTokenInclusionMode.Once` as equivalent to `SecurityTokenInclusionMode.AlwaysToRecipient`. - +> The importance of clock skew increases as the lifetime of the issued token shortens. In most cases, clock skew is not a significant issue if the token lifetime is 30 minutes or more. Scenarios with shorter lifetimes or where the exact validity time of the token is important should be designed to take clock skew into account. + +## Federated Endpoints and Time-Outs + + When a client communicates with a federated endpoint, it must first acquire an appropriate token from a security token service. If the security token service exposes a federated endpoint, the client must first obtain a token from the issuer for that endpoint. Each token acquisition takes time, and that time is subject to the overall time-out for sending the actual message to the final endpoint. + + For example, the time-out on the client-side channel is set to 30 seconds. Two token issuers need to be called to retrieve tokens before sending the message to the final endpoint, and each takes 15 seconds to issue a token. In this case, the attempt will fail and a is thrown. Thus, you need to set the value on the client channel to a value large enough to include the time taken to retrieve all issued tokens. In the case where a value is not specified for the property, the property or the property (or both) need to be set to a value large enough to include the time taken to retrieve all issued tokens. + +## Token Lifetime and Renewal + + WCF clients do not check the issued token when making an initial request to a service. Rather, WCF trusts the security token service to issue a token with appropriate effective and expiration times. If the token is cached by the client and reused, the token lifetime is checked on subsequent requests and the client automatically renews the token if necessary. For more information about token caching, see [How to: Create a Federated Client](how-to-create-a-federated-client.md). + + Specifying short lifetimes, on the order of 30 seconds or less for issued tokens or security context tokens, may result in negotiation time-outs or other exceptions being thrown by WCF clients when requesting issued tokens or when negotiating or renewing security context tokens. + +## Issued Tokens and InclusionMode + + Whether an issued token is serialized in a message sent from a client to a federated endpoint or not is controlled by setting the property of the class. This property can be set to one of the enumeration values, but it is not useful in most federated scenarios. The `SecurityTokenInclusionMode.Never` and `SecurityTokenInclusionMode.AlwaysToInitiator` values cause the client to send a reference to the token issued by the security token service to the relying party. Unless the relying party possesses a copy of the issued token, authentication will fail because the token reference is not resolvable. WCF treats `SecurityTokenInclusionMode.Once` as equivalent to `SecurityTokenInclusionMode.AlwaysToRecipient`. + ## See also - diff --git a/docs/framework/wcf/feature-details/filtering.md b/docs/framework/wcf/feature-details/filtering.md index 7059c85a72727..b33efd2dc1d52 100644 --- a/docs/framework/wcf/feature-details/filtering.md +++ b/docs/framework/wcf/feature-details/filtering.md @@ -6,90 +6,90 @@ ms.assetid: 4002946c-e34a-4356-8cfb-e25912a4be63 --- # Filtering -The Windows Communication Foundation (WCF) filtering system can use declarative filters to match messages and make operational decisions. You can use filters to determine what to do with a message by examining part of the message. A queuing process, for example, can use an XPath 1.0 query to check the priority element of a known header to determine whether to move a message to the front of the queue. - - The filtering system is composed of a set of classes that can efficiently determine which of a set of filters are `true` for a particular WCF message. - - The filtering system is a core component of WCF messaging; it is designed to be extremely fast. Each filter implementation has been optimized for a particular kind of matching against WCF messages. - - The filtering system is not thread safe. The application must handle any locking semantics. It does, however, support a multi-reader, single writer. - -## Where Filtering Fits - - Filtering is performed after a message is received and is part of the process of dispatching the message to the proper application component. The design of the filtering system addresses the requirements of several WCF subsystems, including messaging, routing, security, event handling, and system management. - -## Filters - - The filter engine has two primary components, filters and filter tables. A filter makes Boolean decisions about a message based on user-specified logical conditions. Filters implement the class. - - The methods are used to determine if a message satisfies a filter. One of the methods tests the message's header, but cannot inspect the message body. The other method takes a *message buffer* as an input parameter and can inspect the message body. - - Filters are not usually tested individually, but as part of a filter table, which is a generic class that the method creates. - - The several kinds of filters each specialize in matching on a particular kind of Boolean condition. Once you construct a filter, you cannot change the criteria that a filter uses; to modify a filter's criteria, construct a new one and delete the existing filter. - -### Action Filters - - The contains a list of action strings. If any of the actions in the filter’s list matches the Action header in the message or message buffer, the `Match` method returns `true`. If the list is empty, the filter is considered a match-all filter and any message or message buffer matches and `Match` returns `true`. If none of the actions in the filter’s list matches the Action header in the message or message buffer, `Match` returns `false`. If there is no action in the message and the filter’s list is non-empty, then `Match` returns `false`. - -### Endpoint Address Filters - - The filters messages and message buffers based on an endpoint address, as represented in their header collection. For a message to pass such a filter, the following conditions must be met: - -- The filter’s address Uniform Resource Identifier (URI) must be the same as the one in the message To header. - -- Each endpoint parameter in the address of the filter (`address.Headers` collection) must find a header in the message to map on. Extra headers in the message or message buffer are acceptable for the match to remain `true`. - -### Prefix Endpoint Address Filters - -1. The functions just like the filter, except that the match can be on a prefix of the message URI. For example, a filter specifying the address `http://www.adatum.com` matches messages addressed to `http://www.adatum.com/userA`. - -### XPath Message Filters - - An uses an XPath expression to determine whether an XML document contains specific elements, attributes, text, or other XML syntactic constructs. The filter is optimized to be extremely efficient for a strict subset of XPath. The XML Path Language is described in the [W3C XML Path Language 1.0 specification](https://www.w3.org/TR/xpath/all/). - - Typically, an application uses an at an endpoint to query the contents of a SOAP message and then takes the appropriate action based on the results of that query. A queuing process, for example, may use an XPath query to inspect the priority element of a known header to decide whether to move a message to the front of the queue. - -## Filter Tables - - Filter tables are used to store key-value pairs, where a filter is the key and some associated data is the value. The filter data can be used to indicate what actions to take if a message matches the filter and the type of the filter data is the generic parameter for the filter table class. The filter data can consist of routing rules, session security state, listeners on a channel, and so on. The data can be used where data flow control is necessary. - - Filter tables implement the generic interface . - - Filter tables have several methods that match a message against all the filters in the table and return an unordered collection of matching filters or data. Some of the match methods are multiple-match and return all matching items. Others are single-match, returning only one item, and throw a if more than one filter matches. - -### Message Filter Table - - The is the most general implementation of . You can store filters of all types in the table. - - You can assign numeric priorities to filters, where the highest priority is signified by the highest number. Multiple types of filters can have the same priority. A particular type of filter can appear in more than one priority level. - - Matching is done starting with the highest priority, and once matching filters are found with a given priority, no filters with lower priorities are examined. Therefore, if you are using a single-filter match method, and more than one filter matches a message, but each matching filter has a different priority, then no exception is thrown and the filter with the highest priority is returned. Similarly, a multiple-filter match method returns only those matching filters with the highest priority. - -### XPath Message Filter Table - - The is optimized for declarative XPath filters, so the table key is a . - - The class optimizes matching for a subset of XPath that covers most of the messaging scenarios and also supports the full XPath 1.0 grammar. It has optimized algorithms for efficient parallel matching. - - This table has several specialized `Match` methods that operate over an and a . A extends the class by adding a property. This property allows positions within the XML document to be saved and loaded quickly without having to clone the navigator, an expensive memory allocation that the requires for such an operation. The WCF XPath engine must frequently record the position of the cursor in the course of executing queries on XML documents, so the provides an important optimization for message processing. - -## Customer Scenarios - - You can use filtering any time you want to send a message to different processing modules depending on data contained in the message. Two typical scenarios are routing a message based on its action code and de-multiplexing a stream of messages based on the messages' endpoint address. - -### Routing - - The listener of an endpoint listens for messages that have one or more action codes in the message's SOAP header. You implement this by creating an by passing an array that contains the action codes to its constructor. It uses that filter to register with the `ListenerFactory`, so only messages whose action matches one of those in the filter get to that particular endpoint. - -### De-multiplexing - - When multiple endpoints fan out from the same `ServiceListener` off the wire, the only way to de-multiplex messages and know whether they belong to a certain endpoint address, is to use s, which select messages toward the registered endpoints by performing a lookup on the information stored in the headers. In these filters, only those messages that pass have all necessary headers that correspond to both: - -- The URI in the `EndpointAddress`. - -- The rest of the endpoint parameters in the `EndpointAddress` as specified in the . - +The Windows Communication Foundation (WCF) filtering system can use declarative filters to match messages and make operational decisions. You can use filters to determine what to do with a message by examining part of the message. A queuing process, for example, can use an XPath 1.0 query to check the priority element of a known header to determine whether to move a message to the front of the queue. + + The filtering system is composed of a set of classes that can efficiently determine which of a set of filters are `true` for a particular WCF message. + + The filtering system is a core component of WCF messaging; it is designed to be extremely fast. Each filter implementation has been optimized for a particular kind of matching against WCF messages. + + The filtering system is not thread safe. The application must handle any locking semantics. It does, however, support a multi-reader, single writer. + +## Where Filtering Fits + + Filtering is performed after a message is received and is part of the process of dispatching the message to the proper application component. The design of the filtering system addresses the requirements of several WCF subsystems, including messaging, routing, security, event handling, and system management. + +## Filters + + The filter engine has two primary components, filters and filter tables. A filter makes Boolean decisions about a message based on user-specified logical conditions. Filters implement the class. + + The methods are used to determine if a message satisfies a filter. One of the methods tests the message's header, but cannot inspect the message body. The other method takes a *message buffer* as an input parameter and can inspect the message body. + + Filters are not usually tested individually, but as part of a filter table, which is a generic class that the method creates. + + The several kinds of filters each specialize in matching on a particular kind of Boolean condition. Once you construct a filter, you cannot change the criteria that a filter uses; to modify a filter's criteria, construct a new one and delete the existing filter. + +### Action Filters + + The contains a list of action strings. If any of the actions in the filter’s list matches the Action header in the message or message buffer, the `Match` method returns `true`. If the list is empty, the filter is considered a match-all filter and any message or message buffer matches and `Match` returns `true`. If none of the actions in the filter’s list matches the Action header in the message or message buffer, `Match` returns `false`. If there is no action in the message and the filter’s list is non-empty, then `Match` returns `false`. + +### Endpoint Address Filters + + The filters messages and message buffers based on an endpoint address, as represented in their header collection. For a message to pass such a filter, the following conditions must be met: + +- The filter’s address Uniform Resource Identifier (URI) must be the same as the one in the message To header. + +- Each endpoint parameter in the address of the filter (`address.Headers` collection) must find a header in the message to map on. Extra headers in the message or message buffer are acceptable for the match to remain `true`. + +### Prefix Endpoint Address Filters + +1. The functions just like the filter, except that the match can be on a prefix of the message URI. For example, a filter specifying the address `http://www.adatum.com` matches messages addressed to `http://www.adatum.com/userA`. + +### XPath Message Filters + + An uses an XPath expression to determine whether an XML document contains specific elements, attributes, text, or other XML syntactic constructs. The filter is optimized to be extremely efficient for a strict subset of XPath. The XML Path Language is described in the [W3C XML Path Language 1.0 specification](https://www.w3.org/TR/xpath/all/). + + Typically, an application uses an at an endpoint to query the contents of a SOAP message and then takes the appropriate action based on the results of that query. A queuing process, for example, may use an XPath query to inspect the priority element of a known header to decide whether to move a message to the front of the queue. + +## Filter Tables + + Filter tables are used to store key-value pairs, where a filter is the key and some associated data is the value. The filter data can be used to indicate what actions to take if a message matches the filter and the type of the filter data is the generic parameter for the filter table class. The filter data can consist of routing rules, session security state, listeners on a channel, and so on. The data can be used where data flow control is necessary. + + Filter tables implement the generic interface . + + Filter tables have several methods that match a message against all the filters in the table and return an unordered collection of matching filters or data. Some of the match methods are multiple-match and return all matching items. Others are single-match, returning only one item, and throw a if more than one filter matches. + +### Message Filter Table + + The is the most general implementation of . You can store filters of all types in the table. + + You can assign numeric priorities to filters, where the highest priority is signified by the highest number. Multiple types of filters can have the same priority. A particular type of filter can appear in more than one priority level. + + Matching is done starting with the highest priority, and once matching filters are found with a given priority, no filters with lower priorities are examined. Therefore, if you are using a single-filter match method, and more than one filter matches a message, but each matching filter has a different priority, then no exception is thrown and the filter with the highest priority is returned. Similarly, a multiple-filter match method returns only those matching filters with the highest priority. + +### XPath Message Filter Table + + The is optimized for declarative XPath filters, so the table key is a . + + The class optimizes matching for a subset of XPath that covers most of the messaging scenarios and also supports the full XPath 1.0 grammar. It has optimized algorithms for efficient parallel matching. + + This table has several specialized `Match` methods that operate over an and a . A extends the class by adding a property. This property allows positions within the XML document to be saved and loaded quickly without having to clone the navigator, an expensive memory allocation that the requires for such an operation. The WCF XPath engine must frequently record the position of the cursor in the course of executing queries on XML documents, so the provides an important optimization for message processing. + +## Customer Scenarios + + You can use filtering any time you want to send a message to different processing modules depending on data contained in the message. Two typical scenarios are routing a message based on its action code and de-multiplexing a stream of messages based on the messages' endpoint address. + +### Routing + + The listener of an endpoint listens for messages that have one or more action codes in the message's SOAP header. You implement this by creating an by passing an array that contains the action codes to its constructor. It uses that filter to register with the `ListenerFactory`, so only messages whose action matches one of those in the filter get to that particular endpoint. + +### De-multiplexing + + When multiple endpoints fan out from the same `ServiceListener` off the wire, the only way to de-multiplex messages and know whether they belong to a certain endpoint address, is to use s, which select messages toward the registered endpoints by performing a lookup on the information stored in the headers. In these filters, only those messages that pass have all necessary headers that correspond to both: + +- The URI in the `EndpointAddress`. + +- The rest of the endpoint parameters in the `EndpointAddress` as specified in the . + ## See also - [Data Transfer and Serialization](data-transfer-and-serialization.md) diff --git a/docs/framework/wcf/feature-details/finding-claims-in-a-claimset.md b/docs/framework/wcf/feature-details/finding-claims-in-a-claimset.md index ff80cb679bc06..f8ae5eb54505b 100644 --- a/docs/framework/wcf/feature-details/finding-claims-in-a-claimset.md +++ b/docs/framework/wcf/feature-details/finding-claims-in-a-claimset.md @@ -2,23 +2,23 @@ description: "Learn more about: Finding Claims in a ClaimSet" title: "Finding Claims in a ClaimSet" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "claims [WCF], finding in a claimset" - "claims [WCF]" ms.assetid: a76ce107-aeb3-47d0-bfa9-134c53664e20 --- # Finding Claims in a ClaimSet -Examining the content of a for particular types of claims is a common task when using claim-based authorization. To examine a for the presence of particular claims, use the method. This method provides better performance than iterating directly over the . The following example demonstrates this usage. Note that the `claimType` and `claimRight` parameters can be `null`. In that case, the parameters will match all claim types and claim rights. - -## Example +Examining the content of a for particular types of claims is a common task when using claim-based authorization. To examine a for the presence of particular claims, use the method. This method provides better performance than iterating directly over the . The following example demonstrates this usage. Note that the `claimType` and `claimRight` parameters can be `null`. In that case, the parameters will match all claim types and claim rights. + +## Example [!code-csharp[c_FindClaimsPerf#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_findclaimsperf/cs/c_findclaimsperf.cs#2)] - [!code-vb[c_FindClaimsPerf#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_findclaimsperf/vb/c_findclaimsperf.vb#2)] - + [!code-vb[c_FindClaimsPerf#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_findclaimsperf/vb/c_findclaimsperf.vb#2)] + ## See also - [Managing Claims and Authorization with the Identity Model](managing-claims-and-authorization-with-the-identity-model.md) diff --git a/docs/framework/wcf/feature-details/flowing-transactions-into-and-out-of-workflow-services.md b/docs/framework/wcf/feature-details/flowing-transactions-into-and-out-of-workflow-services.md index c00ac7f419ffa..d16fc8070df3b 100644 --- a/docs/framework/wcf/feature-details/flowing-transactions-into-and-out-of-workflow-services.md +++ b/docs/framework/wcf/feature-details/flowing-transactions-into-and-out-of-workflow-services.md @@ -6,307 +6,307 @@ ms.assetid: 03ced70e-b540-4dd9-86c8-87f7bd61f609 --- # Flowing Transactions into and out of Workflow Services -Workflow services and clients can participate in transactions. For a service operation to become part of an ambient transaction, place a activity within a activity. Any calls made by a or a activity within the will also be made within the ambient transaction. A workflow client application can create an ambient transaction by using the activity and call service operations using the ambient transaction. This topic walks you through creating a workflow service and workflow client that participate in transactions. - +Workflow services and clients can participate in transactions. For a service operation to become part of an ambient transaction, place a activity within a activity. Any calls made by a or a activity within the will also be made within the ambient transaction. A workflow client application can create an ambient transaction by using the activity and call service operations using the ambient transaction. This topic walks you through creating a workflow service and workflow client that participate in transactions. + > [!WARNING] -> If a workflow service instance is loaded within a transaction and the workflow contains a activity, the workflow instance will block until the transaction times out. - +> If a workflow service instance is loaded within a transaction and the workflow contains a activity, the workflow instance will block until the transaction times out. + > [!IMPORTANT] -> Whenever you use a it is recommended to place all Receives in the workflow within activities. - +> Whenever you use a it is recommended to place all Receives in the workflow within activities. + > [!IMPORTANT] -> When using and messages arrive in the incorrect order, the workflow will be aborted when trying to deliver the first out of order message. You must make sure your workflow is always at a consistent stopping point when the workflow idles. This will allow you to restart the workflow from a previous persistence point should the workflow be aborted. - -### Create a shared library - -1. Create a new empty Visual Studio Solution. - -2. Add a new class library project called `Common`. Add references to the following assemblies: - - - System.Activities.dll - - - System.ServiceModel.dll - - - System.ServiceModel.Activities.dll - - - System.Transactions.dll - -3. Add a new class called `PrintTransactionInfo` to the `Common` project. This class is derived from and overloads the method. - +> When using and messages arrive in the incorrect order, the workflow will be aborted when trying to deliver the first out of order message. You must make sure your workflow is always at a consistent stopping point when the workflow idles. This will allow you to restart the workflow from a previous persistence point should the workflow be aborted. + +### Create a shared library + +1. Create a new empty Visual Studio Solution. + +2. Add a new class library project called `Common`. Add references to the following assemblies: + + - System.Activities.dll + + - System.ServiceModel.dll + + - System.ServiceModel.Activities.dll + + - System.Transactions.dll + +3. Add a new class called `PrintTransactionInfo` to the `Common` project. This class is derived from and overloads the method. + ```csharp - using System; - using System; - using System.Activities; - using System.Transactions; - - namespace Common - { - public class PrintTransactionInfo : NativeActivity - { - protected override void Execute(NativeActivityContext context) - { - RuntimeTransactionHandle rth = context.Properties.Find(typeof(RuntimeTransactionHandle).FullName) as RuntimeTransactionHandle; - - if (rth == null) - { - Console.WriteLine("There is no ambient RuntimeTransactionHandle"); - } - - Transaction t = rth.GetCurrentTransaction(context); - - if (t == null) - { - Console.WriteLine("There is no ambient transaction"); - } - else - { - Console.WriteLine("Transaction: {0} is {1}", t.TransactionInformation.DistributedIdentifier, t.TransactionInformation.Status); - } - } - } - - } - ``` - - This is a native activity that displays information about the ambient transaction and is used in both the service and client workflows used in this topic. Build the solution to make this activity available in the **Common** section of the **Toolbox**. - -### Implement the workflow service - -1. Add a new WCF Workflow Service, called `WorkflowService` to the `Common` project. To do this right click the `Common` project, select **Add**, **New Item ...**, Select **Workflow** under **Installed Templates** and select **WCF Workflow Service**. - - ![Adding a Workflow Service](./media/flowing-transactions-into-and-out-of-workflow-services/add-workflow-service.jpg) - -2. Delete the default `ReceiveRequest` and `SendResponse` activities. - -3. Drag and drop a activity into the `Sequential Service` activity. Set the text property to `"Workflow Service starting ..."` as shown in the following example. - - ![Adding a WriteLine activity to the Sequential Service activity(./media/flowing-transactions-into-and-out-of-workflow-services/add-writeline-sequential-service.jpg) - -4. Drag and drop a after the activity. The activity can be found in the **Messaging** section of the **Toolbox**. The activity is composed of two sections **Request** and **Body**. The **Request** section contains the activity. The **Body** section contains the activities to execute within a transaction after a message has been received. - - ![Adding a TransactedReceiveScope activity](./media/flowing-transactions-into-and-out-of-workflow-services/transactedreceivescope-activity.jpg) - -5. Select the activity and click the **Variables** button. Add the following variables. - - ![Adding variables to the TransactedReceiveScope](./media/flowing-transactions-into-and-out-of-workflow-services/add-transactedreceivescope-variables.jpg) - + using System; + using System; + using System.Activities; + using System.Transactions; + + namespace Common + { + public class PrintTransactionInfo : NativeActivity + { + protected override void Execute(NativeActivityContext context) + { + RuntimeTransactionHandle rth = context.Properties.Find(typeof(RuntimeTransactionHandle).FullName) as RuntimeTransactionHandle; + + if (rth == null) + { + Console.WriteLine("There is no ambient RuntimeTransactionHandle"); + } + + Transaction t = rth.GetCurrentTransaction(context); + + if (t == null) + { + Console.WriteLine("There is no ambient transaction"); + } + else + { + Console.WriteLine("Transaction: {0} is {1}", t.TransactionInformation.DistributedIdentifier, t.TransactionInformation.Status); + } + } + } + + } + ``` + + This is a native activity that displays information about the ambient transaction and is used in both the service and client workflows used in this topic. Build the solution to make this activity available in the **Common** section of the **Toolbox**. + +### Implement the workflow service + +1. Add a new WCF Workflow Service, called `WorkflowService` to the `Common` project. To do this right click the `Common` project, select **Add**, **New Item ...**, Select **Workflow** under **Installed Templates** and select **WCF Workflow Service**. + + ![Adding a Workflow Service](./media/flowing-transactions-into-and-out-of-workflow-services/add-workflow-service.jpg) + +2. Delete the default `ReceiveRequest` and `SendResponse` activities. + +3. Drag and drop a activity into the `Sequential Service` activity. Set the text property to `"Workflow Service starting ..."` as shown in the following example. + + ![Adding a WriteLine activity to the Sequential Service activity(./media/flowing-transactions-into-and-out-of-workflow-services/add-writeline-sequential-service.jpg) + +4. Drag and drop a after the activity. The activity can be found in the **Messaging** section of the **Toolbox**. The activity is composed of two sections **Request** and **Body**. The **Request** section contains the activity. The **Body** section contains the activities to execute within a transaction after a message has been received. + + ![Adding a TransactedReceiveScope activity](./media/flowing-transactions-into-and-out-of-workflow-services/transactedreceivescope-activity.jpg) + +5. Select the activity and click the **Variables** button. Add the following variables. + + ![Adding variables to the TransactedReceiveScope](./media/flowing-transactions-into-and-out-of-workflow-services/add-transactedreceivescope-variables.jpg) + > [!NOTE] - > You can delete the data variable that is there by default. You can also use the existing handle variable. - -6. Drag and drop a activity within the **Request** section of the activity. Set the following properties: - - |Property|Value| - |--------------|-----------| - |CanCreateInstance|True (check the checkbox)| - |OperationName|StartSample| - |ServiceContractName|ITransactionSample| - - The workflow should look like this: - - ![Adding a Receive activity](./media/flowing-transactions-into-and-out-of-workflow-services/add-receive-activity.jpg) - -7. Click the **Define...** link in the activity and make the following settings: - - ![Setting message settings for the Receive activity](./media/flowing-transactions-into-and-out-of-workflow-services/receive-message-settings.jpg) - -8. Drag and drop a activity into the Body section of the . Within the activity drag and drop two activities and set the properties as shown in the following table. - - |Activity|Value| - |--------------|-----------| - |1st WriteLine|"Service: Receive Completed"| - |2nd WriteLine|"Service: Received = " + requestMessage| - - The workflow should now look like this: - - ![Sequence after adding WriteLine activities](./media/flowing-transactions-into-and-out-of-workflow-services/after-adding-writelines.jpg) - -9. Drag and drop the `PrintTransactionInfo` activity after the second activity in the **Body** in the activity. - - ![Sequence after adding PrintTransactionInfo](./media/flowing-transactions-into-and-out-of-workflow-services/after-adding-printtransactioninfo.jpg ) - -10. Drag and drop an activity after the `PrintTransactionInfo` activity and set its properties according to the following table. - - |Property|Value| - |--------------|-----------| - |To|replyMessage| - |Value|"Service: Sending reply."| - -11. Drag and drop a activity after the activity and set its property to "Service: Begin reply." - - The workflow should now look like this: - - ![After adding Assign and WriteLine](./media/flowing-transactions-into-and-out-of-workflow-services/after-adding-sbr-writeline.jpg) - -12. Right click the activity and select **Create SendReply** and paste it after the last activity. Click the **Define...** link in the `SendReplyToReceive` activity and make the following settings. - - ![Reply message settings](./media/flowing-transactions-into-and-out-of-workflow-services/reply-message-settings.jpg) - -13. Drag and drop a activity after the `SendReplyToReceive` activity and set it’s property to "Service: Reply sent." - -14. Drag and drop a activity at the bottom of the workflow and set its property to "Service: Workflow ends, press ENTER to exit." - - The completed service workflow should look like this: - - ![Complete Service Workflow](./media/flowing-transactions-into-and-out-of-workflow-services/service-complete-workflow.jpg) - -### Implement the workflow client - -1. Add a new WCF Workflow application, called `WorkflowClient` to the `Common` project. To do this right click the `Common` project, select **Add**, **New Item ...**, Select **Workflow** under **Installed Templates** and select **Activity**. - - ![Add an Activity project](./media/flowing-transactions-into-and-out-of-workflow-services/add-activity-project.jpg) - -2. Drag and drop a activity onto the design surface. - -3. Within the activity drag and drop a activity and set its property to `"Client: Workflow starting"`. The workflow should now look like this: - - ![Add a WriteLine activity](./media/flowing-transactions-into-and-out-of-workflow-services/add-writeline-activity.jpg) - -4. Drag and drop a activity after the activity. Select the activity, click the Variables button and add the following variables. - - ![Add variables to the TransactionScope](./media/flowing-transactions-into-and-out-of-workflow-services/transactionscope-variables.jpg) - -5. Drag and drop a activity into the body of the activity. - -6. Drag and drop a `PrintTransactionInfo` activity within the - -7. Drag and drop a activity after the `PrintTransactionInfo` activity and set its property to "Client: Beginning Send". The workflow should now look like this: - - ![Adding Client: Beginning Send activities](./media/flowing-transactions-into-and-out-of-workflow-services/client-add-cbs-writeline.jpg) - -8. Drag and drop a activity after the activity and set the following properties: - - |Property|Value| - |--------------|-----------| - |EndpointConfigurationName|workflowServiceEndpoint| - |OperationName|StartSample| - |ServiceContractName|ITransactionSample| - - The workflow should now look like this: - - ![Setting the Send activity properties](./media/flowing-transactions-into-and-out-of-workflow-services/client-send-activity-settings.jpg) - -9. Click the **Define...** link and make the following settings: - - ![Send activity message settings](./media/flowing-transactions-into-and-out-of-workflow-services/send-message-settings.jpg) - -10. Right click the activity and select **Create ReceiveReply**. The activity will be automatically placed after the activity. - -11. Click the Define... link on the ReceiveReplyForSend activity and make the following settings: - - ![Setting the ReceiveForSend message settings](./media/flowing-transactions-into-and-out-of-workflow-services/client-reply-message-settings.jpg) - -12. Drag and drop a activity between the and activities and set its property to "Client: Send complete." - -13. Drag and drop a activity after the activity and set its property to "Client side: Reply received = " + replyMessage - -14. Drag and drop a `PrintTransactionInfo` activity after the activity. - -15. Drag and drop a activity at the end of the workflow and set its property to "Client workflow ends." The completed client workflow should look like the following diagram. - - ![The completed client workflow](./media/flowing-transactions-into-and-out-of-workflow-services/client-complete-workflow.jpg) - -16. Build the solution. - -### Create the Service application - -1. Add a new Console Application project called `Service` to the solution. Add references to the following assemblies: - - 1. System.Activities.dll - - 2. System.ServiceModel.dll - - 3. System.ServiceModel.Activities.dll - -2. Open the generated Program.cs file and the following code: - + > You can delete the data variable that is there by default. You can also use the existing handle variable. + +6. Drag and drop a activity within the **Request** section of the activity. Set the following properties: + + |Property|Value| + |--------------|-----------| + |CanCreateInstance|True (check the checkbox)| + |OperationName|StartSample| + |ServiceContractName|ITransactionSample| + + The workflow should look like this: + + ![Adding a Receive activity](./media/flowing-transactions-into-and-out-of-workflow-services/add-receive-activity.jpg) + +7. Click the **Define...** link in the activity and make the following settings: + + ![Setting message settings for the Receive activity](./media/flowing-transactions-into-and-out-of-workflow-services/receive-message-settings.jpg) + +8. Drag and drop a activity into the Body section of the . Within the activity drag and drop two activities and set the properties as shown in the following table. + + |Activity|Value| + |--------------|-----------| + |1st WriteLine|"Service: Receive Completed"| + |2nd WriteLine|"Service: Received = " + requestMessage| + + The workflow should now look like this: + + ![Sequence after adding WriteLine activities](./media/flowing-transactions-into-and-out-of-workflow-services/after-adding-writelines.jpg) + +9. Drag and drop the `PrintTransactionInfo` activity after the second activity in the **Body** in the activity. + + ![Sequence after adding PrintTransactionInfo](./media/flowing-transactions-into-and-out-of-workflow-services/after-adding-printtransactioninfo.jpg ) + +10. Drag and drop an activity after the `PrintTransactionInfo` activity and set its properties according to the following table. + + |Property|Value| + |--------------|-----------| + |To|replyMessage| + |Value|"Service: Sending reply."| + +11. Drag and drop a activity after the activity and set its property to "Service: Begin reply." + + The workflow should now look like this: + + ![After adding Assign and WriteLine](./media/flowing-transactions-into-and-out-of-workflow-services/after-adding-sbr-writeline.jpg) + +12. Right click the activity and select **Create SendReply** and paste it after the last activity. Click the **Define...** link in the `SendReplyToReceive` activity and make the following settings. + + ![Reply message settings](./media/flowing-transactions-into-and-out-of-workflow-services/reply-message-settings.jpg) + +13. Drag and drop a activity after the `SendReplyToReceive` activity and set it’s property to "Service: Reply sent." + +14. Drag and drop a activity at the bottom of the workflow and set its property to "Service: Workflow ends, press ENTER to exit." + + The completed service workflow should look like this: + + ![Complete Service Workflow](./media/flowing-transactions-into-and-out-of-workflow-services/service-complete-workflow.jpg) + +### Implement the workflow client + +1. Add a new WCF Workflow application, called `WorkflowClient` to the `Common` project. To do this right click the `Common` project, select **Add**, **New Item ...**, Select **Workflow** under **Installed Templates** and select **Activity**. + + ![Add an Activity project](./media/flowing-transactions-into-and-out-of-workflow-services/add-activity-project.jpg) + +2. Drag and drop a activity onto the design surface. + +3. Within the activity drag and drop a activity and set its property to `"Client: Workflow starting"`. The workflow should now look like this: + + ![Add a WriteLine activity](./media/flowing-transactions-into-and-out-of-workflow-services/add-writeline-activity.jpg) + +4. Drag and drop a activity after the activity. Select the activity, click the Variables button and add the following variables. + + ![Add variables to the TransactionScope](./media/flowing-transactions-into-and-out-of-workflow-services/transactionscope-variables.jpg) + +5. Drag and drop a activity into the body of the activity. + +6. Drag and drop a `PrintTransactionInfo` activity within the + +7. Drag and drop a activity after the `PrintTransactionInfo` activity and set its property to "Client: Beginning Send". The workflow should now look like this: + + ![Adding Client: Beginning Send activities](./media/flowing-transactions-into-and-out-of-workflow-services/client-add-cbs-writeline.jpg) + +8. Drag and drop a activity after the activity and set the following properties: + + |Property|Value| + |--------------|-----------| + |EndpointConfigurationName|workflowServiceEndpoint| + |OperationName|StartSample| + |ServiceContractName|ITransactionSample| + + The workflow should now look like this: + + ![Setting the Send activity properties](./media/flowing-transactions-into-and-out-of-workflow-services/client-send-activity-settings.jpg) + +9. Click the **Define...** link and make the following settings: + + ![Send activity message settings](./media/flowing-transactions-into-and-out-of-workflow-services/send-message-settings.jpg) + +10. Right click the activity and select **Create ReceiveReply**. The activity will be automatically placed after the activity. + +11. Click the Define... link on the ReceiveReplyForSend activity and make the following settings: + + ![Setting the ReceiveForSend message settings](./media/flowing-transactions-into-and-out-of-workflow-services/client-reply-message-settings.jpg) + +12. Drag and drop a activity between the and activities and set its property to "Client: Send complete." + +13. Drag and drop a activity after the activity and set its property to "Client side: Reply received = " + replyMessage + +14. Drag and drop a `PrintTransactionInfo` activity after the activity. + +15. Drag and drop a activity at the end of the workflow and set its property to "Client workflow ends." The completed client workflow should look like the following diagram. + + ![The completed client workflow](./media/flowing-transactions-into-and-out-of-workflow-services/client-complete-workflow.jpg) + +16. Build the solution. + +### Create the Service application + +1. Add a new Console Application project called `Service` to the solution. Add references to the following assemblies: + + 1. System.Activities.dll + + 2. System.ServiceModel.dll + + 3. System.ServiceModel.Activities.dll + +2. Open the generated Program.cs file and the following code: + ```csharp - static void Main() - { - Console.WriteLine("Building the server."); - using (WorkflowServiceHost host = new WorkflowServiceHost(new DeclarativeServiceWorkflow(), new Uri("net.tcp://localhost:8000/TransactedReceiveService/Declarative"))) + static void Main() + { + Console.WriteLine("Building the server."); + using (WorkflowServiceHost host = new WorkflowServiceHost(new DeclarativeServiceWorkflow(), new Uri("net.tcp://localhost:8000/TransactedReceiveService/Declarative"))) { - //Start the server - host.Open(); - Console.WriteLine("Service started."); - - Console.WriteLine(); - Console.ReadLine(); - //Shutdown - host.Close(); + //Start the server + host.Open(); + Console.WriteLine("Service started."); + + Console.WriteLine(); + Console.ReadLine(); + //Shutdown + host.Close(); }; - } - ``` - -3. Add the following app.config file to the project. - - ```xml - - - - - - - - - - - - ``` - -### Create the client application - -1. Add a new Console Application project called `Client` to the solution. Add a reference to System.Activities.dll. - -2. Open the program.cs file and add the following code. - + } + ``` + +3. Add the following app.config file to the project. + + ```xml + + + + + + + + + + + + ``` + +### Create the client application + +1. Add a new Console Application project called `Client` to the solution. Add a reference to System.Activities.dll. + +2. Open the program.cs file and add the following code. + ```csharp - class Program - { - - private static AutoResetEvent syncEvent = new AutoResetEvent(false); - - static void Main(string[] args) - { - //Build client - Console.WriteLine("Building the client."); - WorkflowApplication client = new WorkflowApplication(new DeclarativeClientWorkflow()); - client.Completed = Program.Completed; - client.Aborted = Program.Aborted; - client.OnUnhandledException = Program.OnUnhandledException; - //Wait for service to start - Console.WriteLine("Press ENTER once service is started."); - Console.ReadLine(); - + class Program + { + + private static AutoResetEvent syncEvent = new AutoResetEvent(false); + + static void Main(string[] args) + { + //Build client + Console.WriteLine("Building the client."); + WorkflowApplication client = new WorkflowApplication(new DeclarativeClientWorkflow()); + client.Completed = Program.Completed; + client.Aborted = Program.Aborted; + client.OnUnhandledException = Program.OnUnhandledException; + //Wait for service to start + Console.WriteLine("Press ENTER once service is started."); + Console.ReadLine(); + //Start the client - Console.WriteLine("Starting the client."); - client.Run(); - syncEvent.WaitOne(); - - //Sample complete - Console.WriteLine(); - Console.WriteLine("Client complete. Press ENTER to exit."); - Console.ReadLine(); - } - - private static void Completed(WorkflowApplicationCompletedEventArgs e) - { - Program.syncEvent.Set(); - } - - private static void Aborted(WorkflowApplicationAbortedEventArgs e) - { - Console.WriteLine("Client Aborted: {0}", e.Reason); - Program.syncEvent.Set(); - } - - private static UnhandledExceptionAction OnUnhandledException(WorkflowApplicationUnhandledExceptionEventArgs e) - { - Console.WriteLine("Client had an unhandled exception: {0}", e.UnhandledException); - return UnhandledExceptionAction.Cancel; - } - } - ``` - + Console.WriteLine("Starting the client."); + client.Run(); + syncEvent.WaitOne(); + + //Sample complete + Console.WriteLine(); + Console.WriteLine("Client complete. Press ENTER to exit."); + Console.ReadLine(); + } + + private static void Completed(WorkflowApplicationCompletedEventArgs e) + { + Program.syncEvent.Set(); + } + + private static void Aborted(WorkflowApplicationAbortedEventArgs e) + { + Console.WriteLine("Client Aborted: {0}", e.Reason); + Program.syncEvent.Set(); + } + + private static UnhandledExceptionAction OnUnhandledException(WorkflowApplicationUnhandledExceptionEventArgs e) + { + Console.WriteLine("Client had an unhandled exception: {0}", e.UnhandledException); + return UnhandledExceptionAction.Cancel; + } + } + ``` + ## See also - [Workflow Services](workflow-services.md) diff --git a/docs/framework/wcf/feature-details/forward-compatible-data-contracts.md b/docs/framework/wcf/feature-details/forward-compatible-data-contracts.md index cfc02aff0b824..0cfce3f49bfc2 100644 --- a/docs/framework/wcf/feature-details/forward-compatible-data-contracts.md +++ b/docs/framework/wcf/feature-details/forward-compatible-data-contracts.md @@ -2,43 +2,43 @@ description: "Learn more about: Forward-Compatible Data Contracts" title: "Forward-Compatible Data Contracts" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "data contracts [WCF], forward compatibility" ms.assetid: 413c9044-26f8-4ecb-968c-18495ea52cd9 --- # Forward-Compatible Data Contracts -A feature of the Windows Communication Foundation (WCF) data contract system is that contracts can evolve over time in nonbreaking ways. That is, a client with an older version of a data contract can communicate with a service with a newer version of the same data contract, or a client with a newer version of a data contract can communicate with an older version of the same data contract. For more information, see [Best Practices: Data Contract Versioning](../best-practices-data-contract-versioning.md). - - You can apply most of the versioning features on an as-needed basis when new versions of an existing data contract are created. However, one versioning feature, *round-tripping*, must be built into the type from the first version in order to work properly. - -## Round-Tripping +A feature of the Windows Communication Foundation (WCF) data contract system is that contracts can evolve over time in nonbreaking ways. That is, a client with an older version of a data contract can communicate with a service with a newer version of the same data contract, or a client with a newer version of a data contract can communicate with an older version of the same data contract. For more information, see [Best Practices: Data Contract Versioning](../best-practices-data-contract-versioning.md). - Round-tripping occurs when data passes from a new version to an old version and back to the new version of a data contract. Round-tripping guarantees that no data is lost. Enabling round-tripping makes the type forward-compatible with any future changes supported by the data contract versioning model. - - To enable round-tripping for a particular type, the type must implement the interface. The interface contains one property, (returning the type). The property stores any data from future versions of the data contract that is unknown to the current version. - -### Example + You can apply most of the versioning features on an as-needed basis when new versions of an existing data contract are created. However, one versioning feature, *round-tripping*, must be built into the type from the first version in order to work properly. + +## Round-Tripping + + Round-tripping occurs when data passes from a new version to an old version and back to the new version of a data contract. Round-tripping guarantees that no data is lost. Enabling round-tripping makes the type forward-compatible with any future changes supported by the data contract versioning model. + + To enable round-tripping for a particular type, the type must implement the interface. The interface contains one property, (returning the type). The property stores any data from future versions of the data contract that is unknown to the current version. + +### Example + + The following data contract is not forward-compatible with future changes. - The following data contract is not forward-compatible with future changes. - [!code-csharp[C_DataContract#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontract/cs/source.cs#7)] - [!code-vb[C_DataContract#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontract/vb/source.vb#7)] - - To make the type compatible with future changes (such as adding a new data member named "phoneNumber"), implement the interface. - + [!code-vb[C_DataContract#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontract/vb/source.vb#7)] + + To make the type compatible with future changes (such as adding a new data member named "phoneNumber"), implement the interface. + [!code-csharp[C_DataContract#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_datacontract/cs/source.cs#8)] - [!code-vb[C_DataContract#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontract/vb/source.vb#8)] - - When the WCF infrastructure encounters data that is not part of the original data contract, the data is stored in the property and preserved. It is not processed in any other way except for temporary storage. If the object is returned back to where it originated, the original (unknown) data is also returned. Therefore, the data has made a round trip to and from the originating endpoint without loss. Note, however, that if the originating endpoint required the data to be processed, that expectation is unmet, and the endpoint must somehow detect and accommodate the change. - - The type contains no public methods or properties. Thus, it is impossible to get direct access to the data stored inside the property. - - The round-tripping feature may be turned off, either by setting `ignoreExtensionDataObject` to `true` in the constructor or by setting the property to `true` on the . When this feature is off, the deserializer will not populate the property, and the serializer will not emit the contents of the property. - + [!code-vb[C_DataContract#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_datacontract/vb/source.vb#8)] + + When the WCF infrastructure encounters data that is not part of the original data contract, the data is stored in the property and preserved. It is not processed in any other way except for temporary storage. If the object is returned back to where it originated, the original (unknown) data is also returned. Therefore, the data has made a round trip to and from the originating endpoint without loss. Note, however, that if the originating endpoint required the data to be processed, that expectation is unmet, and the endpoint must somehow detect and accommodate the change. + + The type contains no public methods or properties. Thus, it is impossible to get direct access to the data stored inside the property. + + The round-tripping feature may be turned off, either by setting `ignoreExtensionDataObject` to `true` in the constructor or by setting the property to `true` on the . When this feature is off, the deserializer will not populate the property, and the serializer will not emit the contents of the property. + ## See also - diff --git a/docs/framework/wcf/feature-details/hosting-in-a-windows-service-application.md b/docs/framework/wcf/feature-details/hosting-in-a-windows-service-application.md index 6ed575dea80f0..d4ce4ccfd7b3c 100644 --- a/docs/framework/wcf/feature-details/hosting-in-a-windows-service-application.md +++ b/docs/framework/wcf/feature-details/hosting-in-a-windows-service-application.md @@ -6,32 +6,32 @@ ms.assetid: f4199998-27f3-4dd9-aee4-0a4addfa9f24 --- # Hosting in a Windows Service Application -Windows services (formerly known as Windows NT services) provide a process model particularly suited to applications that must live in a long-running executable and do not display any form of user interface. The process lifetime of a Windows service application is managed by the service control manager (SCM), which allows you to start, stop, and pause Windows service applications. You can configure a Windows service process to start automatically when the computer starts, making it a suitable hosting environment for "always on" applications. For more information about Windows service applications, see [Windows Service Applications](../../windows-services/introduction-to-windows-service-applications.md). - - Applications that host long-running Windows Communication Foundation (WCF) services share many characteristics with Windows services. In particular, WCF services are long-running server executables that do not interact directly with the user and therefore do not implement any form of user interface. As such, hosting WCF services inside of a Windows service application is one option for building robust, long-running, WCF applications. - - Often, WCF developers must decide whether to host their WCF application inside of a Windows service application or inside of the Internet Information Services (IIS) or Windows Process Activation Service (WAS) hosting environment. You should consider using Windows service applications under the following conditions: - -- Your application requires explicit activation. For example, you should use Windows services when your application must start automatically when the server starts instead of being dynamically started in response to the first incoming message. - -- The process that hosts your application must remain running once started. Once started, a Windows service process remains running unless explicitly shut down by a server administrator using the service control manager. Applications hosted in IIS or WAS may be started and stopped dynamically to make optimal use of system resources. Applications that require explicit control over the lifetime of their hosting process should use Windows services instead of IIS or WAS. - -- Your WCF service must run on Windows Server 2003 and use transports other than HTTP. On Windows Server 2003, the IIS 6.0 hosting environment is restricted to HTTP communication only. Windows service applications are not subject to this restriction and can use any transport WCF supports, including net.tcp, net.pipe, and net.msmq. - +Windows services (formerly known as Windows NT services) provide a process model particularly suited to applications that must live in a long-running executable and do not display any form of user interface. The process lifetime of a Windows service application is managed by the service control manager (SCM), which allows you to start, stop, and pause Windows service applications. You can configure a Windows service process to start automatically when the computer starts, making it a suitable hosting environment for "always on" applications. For more information about Windows service applications, see [Windows Service Applications](../../windows-services/introduction-to-windows-service-applications.md). + + Applications that host long-running Windows Communication Foundation (WCF) services share many characteristics with Windows services. In particular, WCF services are long-running server executables that do not interact directly with the user and therefore do not implement any form of user interface. As such, hosting WCF services inside of a Windows service application is one option for building robust, long-running, WCF applications. + + Often, WCF developers must decide whether to host their WCF application inside of a Windows service application or inside of the Internet Information Services (IIS) or Windows Process Activation Service (WAS) hosting environment. You should consider using Windows service applications under the following conditions: + +- Your application requires explicit activation. For example, you should use Windows services when your application must start automatically when the server starts instead of being dynamically started in response to the first incoming message. + +- The process that hosts your application must remain running once started. Once started, a Windows service process remains running unless explicitly shut down by a server administrator using the service control manager. Applications hosted in IIS or WAS may be started and stopped dynamically to make optimal use of system resources. Applications that require explicit control over the lifetime of their hosting process should use Windows services instead of IIS or WAS. + +- Your WCF service must run on Windows Server 2003 and use transports other than HTTP. On Windows Server 2003, the IIS 6.0 hosting environment is restricted to HTTP communication only. Windows service applications are not subject to this restriction and can use any transport WCF supports, including net.tcp, net.pipe, and net.msmq. + ## How-to - -1. Create a Windows service application. You can write Windows service applications in managed code using the classes in the namespace. This application must include one class that inherits from . - -2. Link the lifetime of the WCF services to the lifetime of the Windows service application. Typically, you want WCF services hosted in a Windows service application to become active when the hosting service starts, stop listening for messages when the hosting service is stopped, and shut down the hosting process when the WCF service encounters an error. This can be accomplished as follows: - - - Override to open one or more instances of . A single Windows service application can host multiple WCF services that start and stop as a group. - - - Override to call on the any running WCF services that were started during . - - - Subscribe to the event of and use the class to shut down the Windows service application in case of error. - - Windows service applications that host WCF services are deployed and managed in the same way as Windows service applications that do not make use of WCF. - + +1. Create a Windows service application. You can write Windows service applications in managed code using the classes in the namespace. This application must include one class that inherits from . + +2. Link the lifetime of the WCF services to the lifetime of the Windows service application. Typically, you want WCF services hosted in a Windows service application to become active when the hosting service starts, stop listening for messages when the hosting service is stopped, and shut down the hosting process when the WCF service encounters an error. This can be accomplished as follows: + + - Override to open one or more instances of . A single Windows service application can host multiple WCF services that start and stop as a group. + + - Override to call on the any running WCF services that were started during . + + - Subscribe to the event of and use the class to shut down the Windows service application in case of error. + + Windows service applications that host WCF services are deployed and managed in the same way as Windows service applications that do not make use of WCF. + ## See also - diff --git a/docs/framework/wcf/feature-details/hosting-workflow-services.md b/docs/framework/wcf/feature-details/hosting-workflow-services.md index 672ef48be10ef..9918a7e5c81fc 100644 --- a/docs/framework/wcf/feature-details/hosting-workflow-services.md +++ b/docs/framework/wcf/feature-details/hosting-workflow-services.md @@ -10,7 +10,7 @@ A workflow service must be hosted for it to respond to incoming messages. Workfl ## Hosting in a managed application - To host a workflow service in a managed application, use the class. The constructor allows you to specify a singleton workflow service instance, a workflow service definition, or an activity that uses the workflow messaging activities. Calling causes the service to start listening for incoming messages. + To host a workflow service in a managed application, use the class. The constructor allows you to specify a singleton workflow service instance, a workflow service definition, or an activity that uses the workflow messaging activities. Calling causes the service to start listening for incoming messages. ## Hosting under IIS or WAS diff --git a/docs/framework/wcf/feature-details/how-to-access-a-wse-3-0-service-with-a-wcf-client.md b/docs/framework/wcf/feature-details/how-to-access-a-wse-3-0-service-with-a-wcf-client.md index 1c96dc4d69732..41569f1816f99 100644 --- a/docs/framework/wcf/feature-details/how-to-access-a-wse-3-0-service-with-a-wcf-client.md +++ b/docs/framework/wcf/feature-details/how-to-access-a-wse-3-0-service-with-a-wcf-client.md @@ -2,60 +2,60 @@ description: "Learn more about: How to: Access a WSE 3.0 Service with a WCF Client" title: "How to: Access a WSE 3.0 Service with a WCF Client" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 1f9bcd9b-8f8f-47fa-8f1e-0d47236eb800 --- # How to: Access a WSE 3.0 Service with a WCF Client -Windows Communication Foundation (WCF) clients are wire-level compatible with Web Services Enhancements (WSE) 3.0 for Microsoft .NET services when WCF clients are configured to use the August 2004 version of the WS-Addressing specification. However, WSE 3.0 services do not support the metadata exchange (MEX) protocol, so when you use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to create a WCF client class, the security settings are not applied to the generated WCF client. Therefore, you must specify the security settings that the WSE 3.0 service requires after the WCF client is generated. - - You can apply these security settings by using a custom binding to take into account the WSE 3.0 service's requirements and the interoperable requirements between a WSE 3.0 service and a WCF client. These interoperability requirements include the aforementioned use of the August 2004 WS-Addressing specification and the WSE 3.0default message protection of . The default message protection for WCF is . This topic details how to create a WCF binding that interoperates with a WSE 3.0 service. WCF also provides a sample that incorporates this binding. For more information about this sample, see [Interoperating with ASMX Web Services](../samples/interoperating-with-asmx-web-services.md). - -### To access a WSE 3.0 Web service with a WCF client - -1. Run the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to create a WCF client for the WSE 3.0 Web service. - - For a WSE 3.0 Web service, a WCF client is created. Because WSE 3.0 does not support the MEX protocol, you cannot use the tool to retrieve the security requirements for the Web service. The application developer must add the security settings for the client. - - For more information about creating a WCF client, see the [How to: Create a Client](../how-to-create-a-wcf-client.md). - -2. Create a class that represents a binding that can communicate with WSE 3.0 Web services. - - The following class is part of the [Interoperating with WSE](/previous-versions/dotnet/netframework-3.5/ms752257(v=vs.90)) sample: - - 1. Create a class that derives from the class. - - The following code example creates a class named `WseHttpBinding` that derives from the class. - +Windows Communication Foundation (WCF) clients are wire-level compatible with Web Services Enhancements (WSE) 3.0 for Microsoft .NET services when WCF clients are configured to use the August 2004 version of the WS-Addressing specification. However, WSE 3.0 services do not support the metadata exchange (MEX) protocol, so when you use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to create a WCF client class, the security settings are not applied to the generated WCF client. Therefore, you must specify the security settings that the WSE 3.0 service requires after the WCF client is generated. + + You can apply these security settings by using a custom binding to take into account the WSE 3.0 service's requirements and the interoperable requirements between a WSE 3.0 service and a WCF client. These interoperability requirements include the aforementioned use of the August 2004 WS-Addressing specification and the WSE 3.0default message protection of . The default message protection for WCF is . This topic details how to create a WCF binding that interoperates with a WSE 3.0 service. WCF also provides a sample that incorporates this binding. For more information about this sample, see [Interoperating with ASMX Web Services](../samples/interoperating-with-asmx-web-services.md). + +### To access a WSE 3.0 Web service with a WCF client + +1. Run the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to create a WCF client for the WSE 3.0 Web service. + + For a WSE 3.0 Web service, a WCF client is created. Because WSE 3.0 does not support the MEX protocol, you cannot use the tool to retrieve the security requirements for the Web service. The application developer must add the security settings for the client. + + For more information about creating a WCF client, see the [How to: Create a Client](../how-to-create-a-wcf-client.md). + +2. Create a class that represents a binding that can communicate with WSE 3.0 Web services. + + The following class is part of the [Interoperating with WSE](/previous-versions/dotnet/netframework-3.5/ms752257(v=vs.90)) sample: + + 1. Create a class that derives from the class. + + The following code example creates a class named `WseHttpBinding` that derives from the class. + [!code-csharp[c_WCFClientToWSEService#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_wcfclienttowseservice/cs/wsehttpbinding.cs#1)] - [!code-vb[c_WCFClientToWSEService#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/wsehttpbinding.vb#1)] - - 2. Add properties to the class that specify the WSE turnkey assertion used by the WSE service, whether derived keys are required, whether secure sessions are used, whether signature confirmations are required, and the message protection settings. In WSE 3.0, a turnkey assertion specifies the security requirements for a client or Web service—similar to the authentication mode of a binding in WCF. - - The following code example defines the `SecurityAssertion`, `RequireDerivedKeys`, `EstablishSecurityContext`, and `MessageProtectionOrder` properties that specify the WSE turnkey assertion, whether derived keys are required, whether secure sessions are used, whether signature confirmations are required, and the message protection settings, respectively. - + [!code-vb[c_WCFClientToWSEService#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/wsehttpbinding.vb#1)] + + 2. Add properties to the class that specify the WSE turnkey assertion used by the WSE service, whether derived keys are required, whether secure sessions are used, whether signature confirmations are required, and the message protection settings. In WSE 3.0, a turnkey assertion specifies the security requirements for a client or Web service—similar to the authentication mode of a binding in WCF. + + The following code example defines the `SecurityAssertion`, `RequireDerivedKeys`, `EstablishSecurityContext`, and `MessageProtectionOrder` properties that specify the WSE turnkey assertion, whether derived keys are required, whether secure sessions are used, whether signature confirmations are required, and the message protection settings, respectively. + [!code-csharp[c_WCFClientToWSEService#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_wcfclienttowseservice/cs/wsehttpbinding.cs#3)] - [!code-vb[c_WCFClientToWSEService#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/wsehttpbinding.vb#3)] - - 3. Override the method to set the binding properties. - - The following code example specifies the transport, message encoding, and message protection settings by getting the values of the `SecurityAssertion` and `MessageProtectionOrder` properties. - + [!code-vb[c_WCFClientToWSEService#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/wsehttpbinding.vb#3)] + + 3. Override the method to set the binding properties. + + The following code example specifies the transport, message encoding, and message protection settings by getting the values of the `SecurityAssertion` and `MessageProtectionOrder` properties. + [!code-csharp[c_WCFClientToWSEService#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_wcfclienttowseservice/cs/wsehttpbinding.cs#2)] - [!code-vb[c_WCFClientToWSEService#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/wsehttpbinding.vb#2)] - -3. In the client application code, add code to set the binding properties. - - The following code example specifies that the WCF client must use message protection and authentication as defined by the WSE 3.0 `AnonymousForCertificate` turnkey security assertion. Additionally, secure sessions and derived keys are required. - + [!code-vb[c_WCFClientToWSEService#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/wsehttpbinding.vb#2)] + +3. In the client application code, add code to set the binding properties. + + The following code example specifies that the WCF client must use message protection and authentication as defined by the WSE 3.0 `AnonymousForCertificate` turnkey security assertion. Additionally, secure sessions and derived keys are required. + [!code-csharp[c_WCFClientToWSEService#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_wcfclienttowseservice/cs/client.cs#4)] - [!code-vb[c_WCFClientToWSEService#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/client.vb#4)] - -## Example + [!code-vb[c_WCFClientToWSEService#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/client.vb#4)] + +## Example - The following code example defines a custom binding that exposes properties that correspond to the properties of a WSE 3.0 turnkey security assertion. That custom binding, which is named `WseHttpBinding`, is then used to specify the binding properties for a WCF client that communicates with the WSSecurityAnonymous WSE 3.0 QuickStart sample. + The following code example defines a custom binding that exposes properties that correspond to the properties of a WSE 3.0 turnkey security assertion. That custom binding, which is named `WseHttpBinding`, is then used to specify the binding properties for a WCF client that communicates with the WSSecurityAnonymous WSE 3.0 QuickStart sample. ## See also diff --git a/docs/framework/wcf/feature-details/how-to-add-an-aspnet-ajax-endpoint-without-using-configuration.md b/docs/framework/wcf/feature-details/how-to-add-an-aspnet-ajax-endpoint-without-using-configuration.md index f6507d5b1ea7d..8a4d9bdcbb482 100644 --- a/docs/framework/wcf/feature-details/how-to-add-an-aspnet-ajax-endpoint-without-using-configuration.md +++ b/docs/framework/wcf/feature-details/how-to-add-an-aspnet-ajax-endpoint-without-using-configuration.md @@ -6,92 +6,92 @@ ms.assetid: b05c1742-8d0a-4673-9d71-725b18a3008e --- # How to: Add an ASP.NET AJAX Endpoint Without Using Configuration -Windows Communication Foundation (WCF) allows you to create a service that exposes an ASP.NET AJAX-enabled endpoint that can be called from JavaScript on a client Web site. To create such an endpoint, you can either use a configuration file, as with all other WCF endpoints, or use a method that does not require any configuration elements. This topic demonstrates the second approach. - - To create services with ASP.NET AJAX endpoints without configuration, the services must be hosted by Internet Information Services (IIS). To activate an ASP.NET AJAX endpoint using this approach, specify the as the Factory parameter in the [\@ServiceHost](../../configure-apps/file-schema/wcf-directive/servicehost.md) directive in the .svc file. This custom factory is the component that automatically configures an ASP.NET AJAX endpoint so that it can be called from JavaScript on a client Web site. - - For a working example, see the [AJAX Service Without Configuration](../samples/ajax-service-without-configuration.md). - - For an outline of how to configure an ASP.NET AJAX endpoint using configuration elements, see [How to: Use Configuration to Add an ASP.NET AJAX Endpoint](how-to-use-configuration-to-add-an-aspnet-ajax-endpoint.md). - -### To create a basic WCF service - -1. Define a basic WCF service contract with an interface marked with the attribute. Mark each operation with the . Be sure to set the property. - - ```csharp - [ServiceContract(Namespace = "MyService")]] - public interface ICalculator - { - [OperationContract] - // This operation returns the sum of d1 and d2. - double Add(double n1, double n2); - - //Other operations omitted… - - } - ``` - -2. Implement the `ICalculator` service contract with a `CalculatorService`. - - ```csharp - public class CalculatorService : ICalculator - { - public double Add(double n1, double n2) - { - return n1 + n2; - } - - //Other operations omitted… - ``` - -3. Define a namespace for the `ICalculator` and `CalculatorService` implementations by wrapping them in a namespace block. - - ```csharp - Namespace Microsoft.Ajax.Samples - { - //Include the code for ICalculator and Calculator here. - } - ``` - -### To host the service in Internet Information Services without configuration - -1. Create a new file named service with a .svc extension in the application. Edit this file by adding the appropriate [\@ServiceHost](../../configure-apps/file-schema/wcf-directive/servicehost.md) directive information for the service. Specify that the is to be used in the [\@ServiceHost](../../configure-apps/file-schema/wcf-directive/servicehost.md) directive to automatically configure an ASP.NET AJAX endpoint. - +Windows Communication Foundation (WCF) allows you to create a service that exposes an ASP.NET AJAX-enabled endpoint that can be called from JavaScript on a client Web site. To create such an endpoint, you can either use a configuration file, as with all other WCF endpoints, or use a method that does not require any configuration elements. This topic demonstrates the second approach. + + To create services with ASP.NET AJAX endpoints without configuration, the services must be hosted by Internet Information Services (IIS). To activate an ASP.NET AJAX endpoint using this approach, specify the as the Factory parameter in the [\@ServiceHost](../../configure-apps/file-schema/wcf-directive/servicehost.md) directive in the .svc file. This custom factory is the component that automatically configures an ASP.NET AJAX endpoint so that it can be called from JavaScript on a client Web site. + + For a working example, see the [AJAX Service Without Configuration](../samples/ajax-service-without-configuration.md). + + For an outline of how to configure an ASP.NET AJAX endpoint using configuration elements, see [How to: Use Configuration to Add an ASP.NET AJAX Endpoint](how-to-use-configuration-to-add-an-aspnet-ajax-endpoint.md). + +### To create a basic WCF service + +1. Define a basic WCF service contract with an interface marked with the attribute. Mark each operation with the . Be sure to set the property. + + ```csharp + [ServiceContract(Namespace = "MyService")]] + public interface ICalculator + { + [OperationContract] + // This operation returns the sum of d1 and d2. + double Add(double n1, double n2); + + //Other operations omitted… + + } + ``` + +2. Implement the `ICalculator` service contract with a `CalculatorService`. + + ```csharp + public class CalculatorService : ICalculator + { + public double Add(double n1, double n2) + { + return n1 + n2; + } + + //Other operations omitted… + ``` + +3. Define a namespace for the `ICalculator` and `CalculatorService` implementations by wrapping them in a namespace block. + + ```csharp + Namespace Microsoft.Ajax.Samples + { + //Include the code for ICalculator and Calculator here. + } + ``` + +### To host the service in Internet Information Services without configuration + +1. Create a new file named service with a .svc extension in the application. Edit this file by adding the appropriate [\@ServiceHost](../../configure-apps/file-schema/wcf-directive/servicehost.md) directive information for the service. Specify that the is to be used in the [\@ServiceHost](../../configure-apps/file-schema/wcf-directive/servicehost.md) directive to automatically configure an ASP.NET AJAX endpoint. + ```text <%@ServiceHost language=c# Debug="true" - Service="Microsoft.Ajax.Samples.CalculatorService" - Factory=System.ServiceModel.Activation.WebScriptServiceHostFactory - %> - ``` - -2. Build the service and call it from the client. Internet Information Services (IIS) activates the service when called. For more information about hosting in IIS, see [How to: Host a WCF Service in IIS](how-to-host-a-wcf-service-in-iis.md). - -### To call the service - -1. The endpoint is configured at an empty address relative to the .svc file, so the service is now available and can be invoked by sending requests to service.svc/\ - for example, service.svc/Add for the `Add` operation. You can use it by entering the service URL into the Scripts collection of the ASP.NET AJAX Script Manager control. For an example, see the [AJAX Service Without Configuration](../samples/ajax-service-without-configuration.md). - -## Example - - The automatically-configured endpoint is created at an empty address relative to the base URL. A configuration file can also be added and used with this approach. If the configuration file contains endpoint definitions, these endpoints are added to the automatically-configured endpoint. - - For example, service.svc uses the and the service directory contains a Web.config file that defines an endpoint for the same service using the at the "soap" relative address. In this case, the service contains two endpoints: one at service.svc (which responds to ASP.NET AJAX requests) and another at service.svc/soap (which responds to SOAP requests). - - If the configuration file defines an endpoint at an empty relative address and the is used, an exception is thrown and the service fails to start. - - You cannot use configuration to modify settings on the automatically-configured endpoint. If any setting (such as a reader quota) must be modified, you must not use the configuration-free approach by removing the from the .svc file and creating a configuration entry for the endpoint. - - If your service requires ASP.NET Compatibility Mode - for example, if it uses the class or ASP.NET authorization mechanisms - a configuration file is still required to turn on this mode. The configuration element required is the [\](../../configure-apps/file-schema/wcf/servicehostingenvironment.md) element, which must be added as follows. - - `` - - ` ` - - For more information, see the [WCF Services and ASP.NET](wcf-services-and-aspnet.md) topic. - - The class is a derived class of . For a detailed explanation of the service host factory mechanism, see the [Extending Hosting Using ServiceHostFactory](../extending/extending-hosting-using-servicehostfactory.md) topic. - + Service="Microsoft.Ajax.Samples.CalculatorService" + Factory=System.ServiceModel.Activation.WebScriptServiceHostFactory + %> + ``` + +2. Build the service and call it from the client. Internet Information Services (IIS) activates the service when called. For more information about hosting in IIS, see [How to: Host a WCF Service in IIS](how-to-host-a-wcf-service-in-iis.md). + +### To call the service + +1. The endpoint is configured at an empty address relative to the .svc file, so the service is now available and can be invoked by sending requests to service.svc/\ - for example, service.svc/Add for the `Add` operation. You can use it by entering the service URL into the Scripts collection of the ASP.NET AJAX Script Manager control. For an example, see the [AJAX Service Without Configuration](../samples/ajax-service-without-configuration.md). + +## Example + + The automatically-configured endpoint is created at an empty address relative to the base URL. A configuration file can also be added and used with this approach. If the configuration file contains endpoint definitions, these endpoints are added to the automatically-configured endpoint. + + For example, service.svc uses the and the service directory contains a Web.config file that defines an endpoint for the same service using the at the "soap" relative address. In this case, the service contains two endpoints: one at service.svc (which responds to ASP.NET AJAX requests) and another at service.svc/soap (which responds to SOAP requests). + + If the configuration file defines an endpoint at an empty relative address and the is used, an exception is thrown and the service fails to start. + + You cannot use configuration to modify settings on the automatically-configured endpoint. If any setting (such as a reader quota) must be modified, you must not use the configuration-free approach by removing the from the .svc file and creating a configuration entry for the endpoint. + + If your service requires ASP.NET Compatibility Mode - for example, if it uses the class or ASP.NET authorization mechanisms - a configuration file is still required to turn on this mode. The configuration element required is the [\](../../configure-apps/file-schema/wcf/servicehostingenvironment.md) element, which must be added as follows. + + `` + + ` ` + + For more information, see the [WCF Services and ASP.NET](wcf-services-and-aspnet.md) topic. + + The class is a derived class of . For a detailed explanation of the service host factory mechanism, see the [Extending Hosting Using ServiceHostFactory](../extending/extending-hosting-using-servicehostfactory.md) topic. + ## See also - [Creating WCF Services for ASP.NET AJAX](creating-wcf-services-for-aspnet-ajax.md) diff --git a/docs/framework/wcf/feature-details/how-to-allow-metadata-requests-while-authorizing.md b/docs/framework/wcf/feature-details/how-to-allow-metadata-requests-while-authorizing.md index bbcfe09cd2730..6c3cce1269319 100644 --- a/docs/framework/wcf/feature-details/how-to-allow-metadata-requests-while-authorizing.md +++ b/docs/framework/wcf/feature-details/how-to-allow-metadata-requests-while-authorizing.md @@ -2,36 +2,36 @@ description: "Learn more about: How To: Allow Metadata Requests While Authorizing" title: "How To: Allow Metadata Requests While Authorizing" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "allowing metadata requests while authorizing [WCF]" ms.assetid: 90cec34f-b619-452b-a056-8b1c0de49d05 --- # How To: Allow Metadata Requests While Authorizing -During custom authorization, it may be necessary to allow a request for metadata to be processed. The following topic walks through the steps to validate such a request. - - For more information about Windows Communication Foundation (WCF) authorization, see [Authorization](authorization-in-wcf.md). - -### To allow metadata requests during authorization - -1. Create an extension of the class. - -2. Override the method. The method returns `true` or `false` depending on whether authorization is allowed. Information about the current procedure is found in the passed as a parameter to the method. - -3. In the override, check the contract name, namespace, and the action as shown in the following example. If the conditions are valid, then return `true.` - -4. Use the extensibility point to employ the class. For more information, see [How to: Create a Custom Authorization Manager for a Service](../extending/how-to-create-a-custom-authorization-manager-for-a-service.md). - -## Example - - The following example shows an override of the method. - +During custom authorization, it may be necessary to allow a request for metadata to be processed. The following topic walks through the steps to validate such a request. + + For more information about Windows Communication Foundation (WCF) authorization, see [Authorization](authorization-in-wcf.md). + +### To allow metadata requests during authorization + +1. Create an extension of the class. + +2. Override the method. The method returns `true` or `false` depending on whether authorization is allowed. Information about the current procedure is found in the passed as a parameter to the method. + +3. In the override, check the contract name, namespace, and the action as shown in the following example. If the conditions are valid, then return `true.` + +4. Use the extensibility point to employ the class. For more information, see [How to: Create a Custom Authorization Manager for a Service](../extending/how-to-create-a-custom-authorization-manager-for-a-service.md). + +## Example + + The following example shows an override of the method. + [!code-csharp[C_HowtoCheckForMexRequestsInAuthorization#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howtocheckformexrequestsinauthorization/cs/source.cs#1)] - [!code-vb[C_HowtoCheckForMexRequestsInAuthorization#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howtocheckformexrequestsinauthorization/vb/source.vb#1)] - + [!code-vb[C_HowtoCheckForMexRequestsInAuthorization#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howtocheckformexrequestsinauthorization/vb/source.vb#1)] + ## See also - diff --git a/docs/framework/wcf/feature-details/how-to-audit-wcf-security-events.md b/docs/framework/wcf/feature-details/how-to-audit-wcf-security-events.md index baddfb753fd9a..d96df1f5f976e 100644 --- a/docs/framework/wcf/feature-details/how-to-audit-wcf-security-events.md +++ b/docs/framework/wcf/feature-details/how-to-audit-wcf-security-events.md @@ -2,92 +2,92 @@ description: "Learn more about: How to: Audit Windows Communication Foundation Security Events" title: "How to: Audit Windows Communication Foundation Security Events" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "security [WCF], auditing events" ms.assetid: e71e9587-3336-46a2-9a9e-d72a1743ecec --- # How to: Audit Windows Communication Foundation Security Events -Windows Communication Foundation (WCF) allows you to log security events to the Windows event log, which can be viewed using the Windows Event Viewer. This topic explains how to set up an application so that it logs security events. For more information about WCF auditing, see [Auditing](auditing-security-events.md). - -### To audit security events in code - -1. Specify the audit log location. To do this, set the property of the class to one of the enumeration values, as shown in the following code. - +Windows Communication Foundation (WCF) allows you to log security events to the Windows event log, which can be viewed using the Windows Event Viewer. This topic explains how to set up an application so that it logs security events. For more information about WCF auditing, see [Auditing](auditing-security-events.md). + +### To audit security events in code + +1. Specify the audit log location. To do this, set the property of the class to one of the enumeration values, as shown in the following code. + [!code-csharp[AuditingSecurityEvents#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/auditingsecurityevents/cs/auditingsecurityevents.cs#2)] - [!code-vb[AuditingSecurityEvents#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/auditingsecurityevents/vb/auditingsecurityevents.vb#2)] - - The enumeration has three values: `Application`, `Security`, or `Default`. The value specifies one of the logs visible in the Event Viewer, either the Security log or the Application log. If you use the `Default` value, the actual log will depend on the operating system the application is running on. If auditing is enabled and the log location is not specified, the default is the `Security` log for platforms that support writing to the Security log; otherwise, it will write to the `Application` log. Only Windows Server 2003 and Windows Vista support writing to the Security log by default. - -2. Set up the types of events to audit. You can simultaneously audit service-level events or message-level authorization events. To do this, set the property or the property to one of the enumeration values, as shown in the following code. - + [!code-vb[AuditingSecurityEvents#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/auditingsecurityevents/vb/auditingsecurityevents.vb#2)] + + The enumeration has three values: `Application`, `Security`, or `Default`. The value specifies one of the logs visible in the Event Viewer, either the Security log or the Application log. If you use the `Default` value, the actual log will depend on the operating system the application is running on. If auditing is enabled and the log location is not specified, the default is the `Security` log for platforms that support writing to the Security log; otherwise, it will write to the `Application` log. Only Windows Server 2003 and Windows Vista support writing to the Security log by default. + +2. Set up the types of events to audit. You can simultaneously audit service-level events or message-level authorization events. To do this, set the property or the property to one of the enumeration values, as shown in the following code. + [!code-csharp[AuditingSecurityEvents#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/auditingsecurityevents/cs/auditingsecurityevents.cs#3)] - [!code-vb[AuditingSecurityEvents#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/auditingsecurityevents/vb/auditingsecurityevents.vb#3)] - -3. Specify whether to suppress or expose failures to the application regarding log audit events. Set the property to either `true` or `false`, as shown in the following code. - + [!code-vb[AuditingSecurityEvents#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/auditingsecurityevents/vb/auditingsecurityevents.vb#3)] + +3. Specify whether to suppress or expose failures to the application regarding log audit events. Set the property to either `true` or `false`, as shown in the following code. + [!code-csharp[AuditingSecurityEvents#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/auditingsecurityevents/cs/auditingsecurityevents.cs#4)] - [!code-vb[AuditingSecurityEvents#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/auditingsecurityevents/vb/auditingsecurityevents.vb#4)] - - The default `SuppressAuditFailure` property is `true`, so that the failure to audit does not affect the application. Otherwise, an exception is thrown. For any successful audit, a verbose trace is written. For any failure to audit, the trace is written at the Error level. - -4. Delete the existing from the collection of behaviors found in the description of a . The behavior collection is accessed by the property, which in turn is accessed from the property. Then add the new to the same collection, as shown in the following code. - + [!code-vb[AuditingSecurityEvents#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/auditingsecurityevents/vb/auditingsecurityevents.vb#4)] + + The default `SuppressAuditFailure` property is `true`, so that the failure to audit does not affect the application. Otherwise, an exception is thrown. For any successful audit, a verbose trace is written. For any failure to audit, the trace is written at the Error level. + +4. Delete the existing from the collection of behaviors found in the description of a . The behavior collection is accessed by the property, which in turn is accessed from the property. Then add the new to the same collection, as shown in the following code. + [!code-csharp[AuditingSecurityEvents#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/auditingsecurityevents/cs/auditingsecurityevents.cs#5)] - [!code-vb[AuditingSecurityEvents#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/auditingsecurityevents/vb/auditingsecurityevents.vb#5)] - -### To set up auditing in configuration - -1. To set up auditing in configuration, add a [\](../../configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element to the [\](../../configure-apps/file-schema/wcf/behaviors.md) section of the web.config file. Then add a [\](../../configure-apps/file-schema/wcf/servicesecurityaudit.md) element and set the various attributes, as shown in the following example. - - ```xml - - - ](../../configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element to the [\](../../configure-apps/file-schema/wcf/behaviors.md) section of the web.config file. Then add a [\](../../configure-apps/file-schema/wcf/servicesecurityaudit.md) element and set the various attributes, as shown in the following example. + + ```xml + + + - - - ``` - -2. You must specify the behavior for the service, as shown in the following example. - - ```xml - + messageAuthenticationAuditLevel="SuccessOrFailure" /> + + + ``` + +2. You must specify the behavior for the service, as shown in the following example. + + ```xml + - + - - - ``` - -## Example - - The following code creates an instance of the class and adds a new to its collection of behaviors. - + contract="WCS.Samples.Service.IEcho" /> + + + ``` + +## Example + + The following code creates an instance of the class and adds a new to its collection of behaviors. + [!code-csharp[AuditingSecurityEvents#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/auditingsecurityevents/cs/auditingsecurityevents.cs#1)] - [!code-vb[AuditingSecurityEvents#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/auditingsecurityevents/vb/auditingsecurityevents.vb#1)] - -## .NET Framework Security - - Setting the property to `true`, suppresses any failure to generate security audits (if set to `false`, an exception is thrown). However, if you enable the following Windows **Local Security Setting** property, a failure to generate audit events will cause Windows to shut down immediately: - - **Audit: Shut down system immediately if unable to log security audits** - - To set the property, open the **Local Security Settings** dialog box. Under **Security Settings**, click **Local Policies**. Then click **Security Options**. - - If the property is set to and **Audit Object Access** is not set in the **Local Security Policy**, audit events will not be written to the Security log. Note that no failure is returned, but audit entries are not written to the Security log. - + [!code-vb[AuditingSecurityEvents#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/auditingsecurityevents/vb/auditingsecurityevents.vb#1)] + +## .NET Framework Security + + Setting the property to `true`, suppresses any failure to generate security audits (if set to `false`, an exception is thrown). However, if you enable the following Windows **Local Security Setting** property, a failure to generate audit events will cause Windows to shut down immediately: + + **Audit: Shut down system immediately if unable to log security audits** + + To set the property, open the **Local Security Settings** dialog box. Under **Security Settings**, click **Local Policies**. Then click **Security Options**. + + If the property is set to and **Audit Object Access** is not set in the **Local Security Policy**, audit events will not be written to the Security log. Note that no failure is returned, but audit entries are not written to the Security log. + ## See also -- +- - - - [Auditing](auditing-security-events.md) diff --git a/docs/framework/wcf/feature-details/how-to-authenticate-with-a-user-name-and-password.md b/docs/framework/wcf/feature-details/how-to-authenticate-with-a-user-name-and-password.md index e7f3aba094070..d785909efa149 100644 --- a/docs/framework/wcf/feature-details/how-to-authenticate-with-a-user-name-and-password.md +++ b/docs/framework/wcf/feature-details/how-to-authenticate-with-a-user-name-and-password.md @@ -85,8 +85,8 @@ On the client, you must prompt the user for the username and password and specif - - - -- -- +- +- - [Transport Security with Basic Authentication](transport-security-with-basic-authentication.md) - [Distributed Application Security](distributed-application-security.md) - [\](../../configure-apps/file-schema/wcf/wshttpbinding.md) diff --git a/docs/framework/wcf/feature-details/how-to-call-operations-asynchronously-using-a-channel-factory.md b/docs/framework/wcf/feature-details/how-to-call-operations-asynchronously-using-a-channel-factory.md index d753bed65fb51..390c9fa99c954 100644 --- a/docs/framework/wcf/feature-details/how-to-call-operations-asynchronously-using-a-channel-factory.md +++ b/docs/framework/wcf/feature-details/how-to-call-operations-asynchronously-using-a-channel-factory.md @@ -9,7 +9,7 @@ ms.assetid: cc17dd47-b9ad-451c-a362-e36e0aac7ba0 --- # How to: Call Operations Asynchronously Using a Channel Factory -This topic covers how a client can access a service operation asynchronously when using a -based client application. (When using a object to invoke a service you can use the event-driven asynchronous calling model. For more information, see [How to: Call Service Operations Asynchronously](how-to-call-wcf-service-operations-asynchronously.md). For more information about the event-based asynchronous calling model, see [Event-based Asynchronous Pattern (EAP)](../../../standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md).) +This topic covers how a client can access a service operation asynchronously when using a -based client application. (When using a object to invoke a service you can use the event-driven asynchronous calling model. For more information, see [How to: Call Service Operations Asynchronously](how-to-call-wcf-service-operations-asynchronously.md). For more information about the event-based asynchronous calling model, see [Event-based Asynchronous Pattern (EAP)](../../../standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md).) The service in this topic implements the `ICalculator` interface. The client can call the operations on this interface asynchronously, which means that operations like `Add` are split into two methods, `BeginAdd` and `EndAdd`, the former of which initiates the call and the latter of which retrieves the result when the operation completes. For an example showing how to implement an operation asynchronously in a service, see [How to: Implement an Asynchronous Service Operation](../how-to-implement-an-asynchronous-service-operation.md). For details about synchronous and asynchronous operations, see [Synchronous and Asynchronous Operations](../synchronous-and-asynchronous-operations.md). @@ -39,7 +39,7 @@ This topic covers how a client can access a service operation asynchronously whe ## Example - The service that is used with the client code that is used in the preceding procedure implements the `ICalculator` interface as shown in the following code. On the service side, the `Add` and `Subtract` operations of the contract are invoked synchronously by the Windows Communication Foundation (WCF) runtime, even though the preceding client steps are invoked asynchronously on the client. The `Multiply` and `Divide` operations are used to invoke the service asynchronously on the service side, even if the client invokes them synchronously. This example sets the property to `true`. This property setting, in combination with the implementation of the .NET Framework asynchronous pattern, tells the runtime to invoke the operation asynchronously. + The service that is used with the client code that is used in the preceding procedure implements the `ICalculator` interface as shown in the following code. On the service side, the `Add` and `Subtract` operations of the contract are invoked synchronously by the Windows Communication Foundation (WCF) runtime, even though the preceding client steps are invoked asynchronously on the client. The `Multiply` and `Divide` operations are used to invoke the service asynchronously on the service side, even if the client invokes them synchronously. This example sets the property to `true`. This property setting, in combination with the implementation of the .NET Framework asynchronous pattern, tells the runtime to invoke the operation asynchronously. [!code-csharp[C_How_To_CF_Async#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_how_to_cf_async/cs/service.cs#4)] [!code-vb[C_How_To_CF_Async#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_how_to_cf_async/vb/service.vb#4)] diff --git a/docs/framework/wcf/feature-details/how-to-call-wcf-service-operations-asynchronously.md b/docs/framework/wcf/feature-details/how-to-call-wcf-service-operations-asynchronously.md index e2823cf285a0b..9eaf2e085628d 100644 --- a/docs/framework/wcf/feature-details/how-to-call-wcf-service-operations-asynchronously.md +++ b/docs/framework/wcf/feature-details/how-to-call-wcf-service-operations-asynchronously.md @@ -12,7 +12,7 @@ ms.assetid: 0face17f-43ca-417b-9b33-737c0fc360df This article covers how a client can access a service operation asynchronously. The service in this article implements the `ICalculator` interface. The client can call the operations on this interface asynchronously by using the event-driven asynchronous calling model. (For more information about the event-based asynchronous calling model, see [Multithreaded Programming with the Event-based Asynchronous Pattern](../../../standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md)). For an example that shows how to implement an operation asynchronously in a service, see [How to: Implement an Asynchronous Service Operation](../how-to-implement-an-asynchronous-service-operation.md). For more information about synchronous and asynchronous operations, see [Synchronous and Asynchronous Operations](../synchronous-and-asynchronous-operations.md). > [!NOTE] -> The event-driven asynchronous calling model is not supported when using a . For information about making asynchronous calls using the , see [How to: Call Operations Asynchronously Using a Channel Factory](how-to-call-operations-asynchronously-using-a-channel-factory.md). +> The event-driven asynchronous calling model is not supported when using a . For information about making asynchronous calls using the , see [How to: Call Operations Asynchronously Using a Channel Factory](how-to-call-operations-asynchronously-using-a-channel-factory.md). ## Procedure @@ -46,7 +46,7 @@ This article covers how a client can access a service operation asynchronously. [!code-csharp[EventAsync#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/eventasync/cs/client.cs#4)] [!code-vb[EventAsync#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/eventasync/vb/client.vb#4)] -3. Prior to calling the operation, use a new generic of type ```EventArgs` to add the handler method (created in the preceding step) to the ```Completed` event. Then call the ```Async` method. For example: +3. Prior to calling the operation, use a new generic of type ```EventArgs` to add the handler method (created in the preceding step) to the ```Completed` event. Then call the ```Async` method. For example: [!code-csharp[EventAsync#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/eventasync/cs/client.cs#5)] [!code-vb[EventAsync#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/eventasync/vb/client.vb#5)] diff --git a/docs/framework/wcf/feature-details/how-to-configure-a-local-issuer.md b/docs/framework/wcf/feature-details/how-to-configure-a-local-issuer.md index d3037af863f19..3eb1073776a3d 100644 --- a/docs/framework/wcf/feature-details/how-to-configure-a-local-issuer.md +++ b/docs/framework/wcf/feature-details/how-to-configure-a-local-issuer.md @@ -19,18 +19,18 @@ Often, when a client communicates with a federated service, the service specifie Windows Communication Foundation (WCF) uses a local issuer in cases where the issuer address of a federated binding is `http://schemas.microsoft.com/2005/12/ServiceModel/Addressing/Anonymous` or `null`. In such cases, you must configure the with the address of the local issuer and the binding to use to communicate with that issuer. > [!NOTE] -> If the property of the `ClientCredentials` class is set to `true`, a local issuer address is not specified, and the issuer address specified by the [\](../../configure-apps/file-schema/wcf/wsfederationhttpbinding.md) or other federated binding is `http://schemas.xmlsoap.org/ws/2005/05/identity/issuer/self`, `http://schemas.microsoft.com/2005/12/ServiceModel/Addressing/Anonymous`, or is `null`, then the Windows CardSpace issuer is used. +> If the property of the `ClientCredentials` class is set to `true`, a local issuer address is not specified, and the issuer address specified by the [\](../../configure-apps/file-schema/wcf/wsfederationhttpbinding.md) or other federated binding is `http://schemas.xmlsoap.org/ws/2005/05/identity/issuer/self`, `http://schemas.microsoft.com/2005/12/ServiceModel/Addressing/Anonymous`, or is `null`, then the Windows CardSpace issuer is used. ## To configure the local issuer in code 1. Create a variable of type -2. Set the variable to the instance returned from the property of the `ClientCredentials` class. That instance is returned by the property of the client (inherited from ) or the property of the : +2. Set the variable to the instance returned from the property of the `ClientCredentials` class. That instance is returned by the property of the client (inherited from ) or the property of the : [!code-csharp[c_CreateSTS#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_creatests/cs/source.cs#9)] [!code-vb[c_CreateSTS#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#9)] -3. Set the property to a new instance of the , with the address of the local issuer as an argument to the constructor. +3. Set the property to a new instance of the , with the address of the local issuer as an argument to the constructor. [!code-csharp[c_CreateSTS#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_creatests/cs/source.cs#10)] [!code-vb[c_CreateSTS#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#10)] @@ -45,12 +45,12 @@ Windows Communication Foundation (WCF) uses a local issuer in cases where the is [!code-csharp[c_CreateSTS#12](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_creatests/cs/source.cs#12)] [!code-vb[c_CreateSTS#12](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#12)] -4. Set the binding for the local issuer using the property. +4. Set the binding for the local issuer using the property. [!code-csharp[c_CreateSTS#13](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_creatests/cs/source.cs#13)] [!code-vb[c_CreateSTS#13](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#13)] -5. Optional. Add configured endpoint behaviors for the local issuer by adding such behaviors to the collection returned by the property. +5. Optional. Add configured endpoint behaviors for the local issuer by adding such behaviors to the collection returned by the property. [!code-csharp[c_CreateSTS#14](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_creatests/cs/source.cs#14)] [!code-vb[c_CreateSTS#14](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#14)] diff --git a/docs/framework/wcf/feature-details/how-to-configure-a-wcf-client-to-interoperate-with-wse3-0-services.md b/docs/framework/wcf/feature-details/how-to-configure-a-wcf-client-to-interoperate-with-wse3-0-services.md index 62d55fa657569..ac721cfb595e7 100644 --- a/docs/framework/wcf/feature-details/how-to-configure-a-wcf-client-to-interoperate-with-wse3-0-services.md +++ b/docs/framework/wcf/feature-details/how-to-configure-a-wcf-client-to-interoperate-with-wse3-0-services.md @@ -2,62 +2,62 @@ description: "Learn more about: How to: Configure a WCF Client to interoperate with WSE3.0 Services" title: "How to: Configure a WCF Client to interoperate with WSE3.0 Services" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 3dadd7f1-d207-4ea5-a73b-3e8aa44407f8 --- # How to: Configure a WCF Client to interoperate with WSE3.0 Services -Windows Communication Foundation (WCF) clients are wire-level compatible with Web Services Enhancements 3.0 for Microsoft .NET (WSE) services when WCF clients are configured to use the August 2004 version of the WS-Addressing specification. - -### To configure a WCF client to interoperate with a WSE 3.0 Web service - -1. Run the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to create a WCF client for the WSE 3.0 Web service. - - For a WSE Web service, a WCF client class is created. - - For details about creating a WCF client, see the [How to: Create a Client](../how-to-create-a-wcf-client.md). - -2. Create a class that represents a binding that can communicate with WSE 3.0 Web services. - - The following class is part of the [Interoperating with WSE](/previous-versions/dotnet/netframework-3.5/ms752257(v=vs.90)) sample. - - 1. Create a class that derives from the class. - - The following code example creates a class named `WseHttpBinding` that derives from the class. - +Windows Communication Foundation (WCF) clients are wire-level compatible with Web Services Enhancements 3.0 for Microsoft .NET (WSE) services when WCF clients are configured to use the August 2004 version of the WS-Addressing specification. + +### To configure a WCF client to interoperate with a WSE 3.0 Web service + +1. Run the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to create a WCF client for the WSE 3.0 Web service. + + For a WSE Web service, a WCF client class is created. + + For details about creating a WCF client, see the [How to: Create a Client](../how-to-create-a-wcf-client.md). + +2. Create a class that represents a binding that can communicate with WSE 3.0 Web services. + + The following class is part of the [Interoperating with WSE](/previous-versions/dotnet/netframework-3.5/ms752257(v=vs.90)) sample. + + 1. Create a class that derives from the class. + + The following code example creates a class named `WseHttpBinding` that derives from the class. + [!code-csharp[c_WCFClientToWSEService#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_wcfclienttowseservice/cs/wsehttpbinding.cs#1)] - [!code-vb[c_WCFClientToWSEService#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/wsehttpbinding.vb#1)] - - 2. Add properties to the class that specify the WSE turnkey assertion, whether derived keys are required, whether secure sessions are used, whether signature confirmations are required, and the message protection settings. - - The following code example defines the `SecurityAssertion`, `RequireDerivedKeys`, `EstablishSecurityContext`, and `MessageProtectionOrder` properties. They specify the WSE turnkey assertion, whether derived keys are required, whether secure sessions are used, whether signature confirmations are required, and the message protection settings, respectively. - + [!code-vb[c_WCFClientToWSEService#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/wsehttpbinding.vb#1)] + + 2. Add properties to the class that specify the WSE turnkey assertion, whether derived keys are required, whether secure sessions are used, whether signature confirmations are required, and the message protection settings. + + The following code example defines the `SecurityAssertion`, `RequireDerivedKeys`, `EstablishSecurityContext`, and `MessageProtectionOrder` properties. They specify the WSE turnkey assertion, whether derived keys are required, whether secure sessions are used, whether signature confirmations are required, and the message protection settings, respectively. + [!code-csharp[c_WCFClientToWSEService#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_wcfclienttowseservice/cs/wsehttpbinding.cs#3)] - [!code-vb[c_WCFClientToWSEService#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/wsehttpbinding.vb#3)] - - 3. Override the method to set the binding properties. - - The following code example specifies the transport, message encoding, and message protection settings by getting the values of the `SecurityAssertion` and `MessageProtectionOrder` properties. - + [!code-vb[c_WCFClientToWSEService#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/wsehttpbinding.vb#3)] + + 3. Override the method to set the binding properties. + + The following code example specifies the transport, message encoding, and message protection settings by getting the values of the `SecurityAssertion` and `MessageProtectionOrder` properties. + [!code-csharp[c_WCFClientToWSEService#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_wcfclienttowseservice/cs/wsehttpbinding.cs#2)] - [!code-vb[c_WCFClientToWSEService#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/wsehttpbinding.vb#2)] - -3. In the client application code, add code to set the binding properties. - - The following code example specifies that the WCF client must use message protection and authentication as defined by the WSE 3.0 `AnonymousForCertificate` turnkey security assertion. Additionally, secure sessions and derived keys are required. - + [!code-vb[c_WCFClientToWSEService#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/wsehttpbinding.vb#2)] + +3. In the client application code, add code to set the binding properties. + + The following code example specifies that the WCF client must use message protection and authentication as defined by the WSE 3.0 `AnonymousForCertificate` turnkey security assertion. Additionally, secure sessions and derived keys are required. + [!code-csharp[c_WCFClientToWSEService#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_wcfclienttowseservice/cs/client.cs#4)] - [!code-vb[c_WCFClientToWSEService#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/client.vb#4)] - -## Example + [!code-vb[c_WCFClientToWSEService#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/client.vb#4)] - The following code example defines a custom binding that exposes properties that correspond to the properties of a WSE 3.0 turnkey security assertion. The custom binding, which is named `WseHttpBinding`, is then used to specify the binding properties for a WCF client. +## Example + + The following code example defines a custom binding that exposes properties that correspond to the properties of a WSE 3.0 turnkey security assertion. The custom binding, which is named `WseHttpBinding`, is then used to specify the binding properties for a WCF client. [!code-csharp[c_WCFClientToWSEService#0](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_wcfclienttowseservice/cs/client.cs#0)] -[!code-vb[c_WCFClientToWSEService#0](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/client.vb#0)] - +[!code-vb[c_WCFClientToWSEService#0](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wcfclienttowseservice/vb/client.vb#0)] + ## See also - diff --git a/docs/framework/wcf/feature-details/how-to-configure-a-wcf-service-to-use-port-sharing.md b/docs/framework/wcf/feature-details/how-to-configure-a-wcf-service-to-use-port-sharing.md index 2d1bf758b7784..19cd4434a60f8 100644 --- a/docs/framework/wcf/feature-details/how-to-configure-a-wcf-service-to-use-port-sharing.md +++ b/docs/framework/wcf/feature-details/how-to-configure-a-wcf-service-to-use-port-sharing.md @@ -2,60 +2,60 @@ description: "Learn more about: How to: Configure a Windows Communication Foundation Service to Use Port Sharing" title: "How to: Configure a Windows Communication Foundation Service to Use Port Sharing" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 6400bc71-a858-4ac2-8d5a-caa72d3b5482 --- # How to: Configure a Windows Communication Foundation Service to Use Port Sharing -The easiest way to use net.tcp:// port sharing in your Windows Communication Foundation (WCF) application is to expose a service using the . - - This binding provides a property that controls whether net.tcp:// port sharing is enabled for the service being configured with this binding. - - The following procedure shows how to use the class to open an endpoint at the Uniform Resource Identifier (URI) net.tcp://localhost/MyService, first in code and then by using configuration elements. - -### To enable net.tcp:// port sharing on a NetTcpBinding in code - -1. Create a service to implement a contract called `IMyService` and call it `MyService`, . - +The easiest way to use net.tcp:// port sharing in your Windows Communication Foundation (WCF) application is to expose a service using the . + + This binding provides a property that controls whether net.tcp:// port sharing is enabled for the service being configured with this binding. + + The following procedure shows how to use the class to open an endpoint at the Uniform Resource Identifier (URI) net.tcp://localhost/MyService, first in code and then by using configuration elements. + +### To enable net.tcp:// port sharing on a NetTcpBinding in code + +1. Create a service to implement a contract called `IMyService` and call it `MyService`, . + [!code-csharp[c_ConfigurePortSharing#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_configureportsharing/cs/source.cs#1)] - [!code-vb[c_ConfigurePortSharing#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_configureportsharing/vb/source.vb#1)] - -2. Create an instance of the class and set the property to `true`. - + [!code-vb[c_ConfigurePortSharing#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_configureportsharing/vb/source.vb#1)] + +2. Create an instance of the class and set the property to `true`. + [!code-csharp[c_ConfigurePortSharing#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_configureportsharing/cs/source.cs#2)] - [!code-vb[c_ConfigurePortSharing#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_configureportsharing/vb/source.vb#2)] - -3. Create a and add the service endpoint to it for `MyService` that uses the port sharing-enabled and that listens at the endpoint address URI "net.tcp://localhost/MyService". - + [!code-vb[c_ConfigurePortSharing#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_configureportsharing/vb/source.vb#2)] + +3. Create a and add the service endpoint to it for `MyService` that uses the port sharing-enabled and that listens at the endpoint address URI "net.tcp://localhost/MyService". + [!code-csharp[c_ConfigurePortSharing#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_configureportsharing/cs/source.cs#3)] - [!code-vb[c_ConfigurePortSharing#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_configureportsharing/vb/source.vb#3)] - + [!code-vb[c_ConfigurePortSharing#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_configureportsharing/vb/source.vb#3)] + > [!NOTE] - > This example uses the default TCP port of 808 because the endpoint address URI does not specify a different port number. Because port sharing is explicitly enabled on the transport binding, this service can share port 808 with other services in other processes. If port sharing were not allowed and another application were already using port 808, this service would throw an when it was opened. - -### To enable net.tcp:// port sharing on a NetTcpBinding in configuration - -1. The following example shows how to enable port sharing and add the service endpoint using configuration elements. - -```xml - - + > This example uses the default TCP port of 808 because the endpoint address URI does not specify a different port number. Because port sharing is explicitly enabled on the transport binding, this service can share port 808 with other services in other processes. If port sharing were not allowed and another application were already using port 808, this service would throw an when it was opened. + +### To enable net.tcp:// port sharing on a NetTcpBinding in configuration + +1. The following example shows how to enable port sharing and add the service endpoint using configuration elements. + +```xml + + - - - - - - - -``` - + portSharingEnabled="true" /> + + + + + + + +``` + ## See also - [Net.TCP Port Sharing](net-tcp-port-sharing.md) diff --git a/docs/framework/wcf/feature-details/how-to-configure-credentials-on-a-federation-service.md b/docs/framework/wcf/feature-details/how-to-configure-credentials-on-a-federation-service.md index 75ace57ca2c3c..385023d9f044f 100644 --- a/docs/framework/wcf/feature-details/how-to-configure-credentials-on-a-federation-service.md +++ b/docs/framework/wcf/feature-details/how-to-configure-credentials-on-a-federation-service.md @@ -22,22 +22,22 @@ In Windows Communication Foundation (WCF), creating a federated service consists ### To set the properties of IssuedTokenServiceCredential in code -1. Use the property of the class to return a reference to an instance. The property is accessed from the property of the class. +1. Use the property of the class to return a reference to an instance. The property is accessed from the property of the class. -2. Set the property to `true` if self-issued tokens such as CardSpace cards are to be authenticated. The default is `false`. +2. Set the property to `true` if self-issued tokens such as CardSpace cards are to be authenticated. The default is `false`. -3. Populate the collection returned by the property with instances of the class. Each instance represents an issuer from which the service will authenticate tokens. +3. Populate the collection returned by the property with instances of the class. Each instance represents an issuer from which the service will authenticate tokens. > [!NOTE] - > Unlike the client-side collection returned by the property, the known certificates collection is not a keyed collection. The service accepts the tokens that the specified certificates issue regardless of the address of the client that sent the message containing the issued token (subject to the further constraints, which are described later in this topic). + > Unlike the client-side collection returned by the property, the known certificates collection is not a keyed collection. The service accepts the tokens that the specified certificates issue regardless of the address of the client that sent the message containing the issued token (subject to the further constraints, which are described later in this topic). -4. Set the property to one of the enumeration values. This can be done only in code. The default is . +4. Set the property to one of the enumeration values. This can be done only in code. The default is . -5. If the property is set to , then assign an instance of the custom class to the property. +5. If the property is set to , then assign an instance of the custom class to the property. -6. If the is set to `ChainTrust` or `PeerOrChainTrust`, set the property to an appropriate value from the enumeration. Note that the revocation mode is not used in `PeerTrust` or `Custom` validation modes. +6. If the is set to `ChainTrust` or `PeerOrChainTrust`, set the property to an appropriate value from the enumeration. Note that the revocation mode is not used in `PeerTrust` or `Custom` validation modes. -7. If needed, assign an instance of a custom class to the property. A custom Security Assertions Markup Language (SAML) serializer is needed, for example, for parsing custom SAML assertions. +7. If needed, assign an instance of a custom class to the property. A custom Security Assertions Markup Language (SAML) serializer is needed, for example, for parsing custom SAML assertions. ### To set the properties of IssuedTokenServiceCredential in configuration @@ -60,13 +60,13 @@ In Windows Communication Foundation (WCF), creating a federated service consists In order for a federated service to authenticate a client, the following must be true about the issued token: -- When the issued token’s digital signature uses an RSA security key identifier, the property must be `true`. +- When the issued token’s digital signature uses an RSA security key identifier, the property must be `true`. -- When the issued token’s signature uses an X.509 issuer serial number, X.509 subject key identifier, or X.509 thumbprint security identifier, the issued token must be signed by a certificate in the collection returned by the property of the class. +- When the issued token’s signature uses an X.509 issuer serial number, X.509 subject key identifier, or X.509 thumbprint security identifier, the issued token must be signed by a certificate in the collection returned by the property of the class. -- When the issued token is signed using an X.509 certificate, the certificate must validate per the semantics specified by the value of the property, regardless of whether the certificate was sent to the relying party as a or was obtained from the property. For more information about X.509 certificate validation, see [Working with Certificates](working-with-certificates.md). +- When the issued token is signed using an X.509 certificate, the certificate must validate per the semantics specified by the value of the property, regardless of whether the certificate was sent to the relying party as a or was obtained from the property. For more information about X.509 certificate validation, see [Working with Certificates](working-with-certificates.md). - For example, setting the to would authenticate any issued token whose signing certificate is in the `TrustedPeople` certificate store. In that case, set the property to either or . You can select other modes, including . When `Custom` is selected, you must assign an instance of the class to the property. The custom validator can validate certificates using any criteria it likes. For more information, see [How to: Create a Service that Employs a Custom Certificate Validator](../extending/how-to-create-a-service-that-employs-a-custom-certificate-validator.md). + For example, setting the to would authenticate any issued token whose signing certificate is in the `TrustedPeople` certificate store. In that case, set the property to either or . You can select other modes, including . When `Custom` is selected, you must assign an instance of the class to the property. The custom validator can validate certificates using any criteria it likes. For more information, see [How to: Create a Service that Employs a Custom Certificate Validator](../extending/how-to-create-a-service-that-employs-a-custom-certificate-validator.md). ## See also diff --git a/docs/framework/wcf/feature-details/how-to-configure-idle-behavior-with-workflowservicehost.md b/docs/framework/wcf/feature-details/how-to-configure-idle-behavior-with-workflowservicehost.md index 4aca3c304a24d..6e50531aa9dfe 100644 --- a/docs/framework/wcf/feature-details/how-to-configure-idle-behavior-with-workflowservicehost.md +++ b/docs/framework/wcf/feature-details/how-to-configure-idle-behavior-with-workflowservicehost.md @@ -9,7 +9,7 @@ ms.assetid: 1bb93652-d687-46ff-bff6-69ecdcf97437 --- # How to: Configure Idle Behavior with WorkflowServiceHost -Workflows go idle when they encounter a bookmark that must be resumed by some external stimulus, for example when the workflow instance is waiting for a message to be delivered using a activity. is a behavior that allows you to specify the time between when a service instance goes idle and when the instance is persisted or unloaded. It contains two properties that enable you to set these time spans. specifies the time span between when a workflow service instance goes idle and when the workflow service instance is persisted. specifies the time span between when a workflow service instance goes idle and when the workflow service instance is unloaded, where unload means persisting the instance to the instance store and removing it from memory. This topic explains how to configure the in a configuration file. +Workflows go idle when they encounter a bookmark that must be resumed by some external stimulus, for example when the workflow instance is waiting for a message to be delivered using a activity. is a behavior that allows you to specify the time between when a service instance goes idle and when the instance is persisted or unloaded. It contains two properties that enable you to set these time spans. specifies the time span between when a workflow service instance goes idle and when the workflow service instance is persisted. specifies the time span between when a workflow service instance goes idle and when the workflow service instance is unloaded, where unload means persisting the instance to the instance store and removing it from memory. This topic explains how to configure the in a configuration file. ### To configure WorkflowIdleBehavior diff --git a/docs/framework/wcf/feature-details/how-to-configure-wcf-services-to-interoperate-with-wse-3-0-clients.md b/docs/framework/wcf/feature-details/how-to-configure-wcf-services-to-interoperate-with-wse-3-0-clients.md index 9abb907e65670..860acf3386a3f 100644 --- a/docs/framework/wcf/feature-details/how-to-configure-wcf-services-to-interoperate-with-wse-3-0-clients.md +++ b/docs/framework/wcf/feature-details/how-to-configure-wcf-services-to-interoperate-with-wse-3-0-clients.md @@ -33,12 +33,12 @@ Windows Communication Foundation (WCF) services are wire-level compatible with W \* One of the primary differences between the `mutualCertificate10Security` and `mutualCertificate11Security` turnkey security assertions is the version of the WS-Security specification that WSE uses to secure the SOAP messages. For `mutualCertificate10Security`, WS-Security 1.0 is used, whereas WS-Security 1.1 is used for `mutualCertificate11Security`. For WCF, the version of the WS-Security specification is specified in the `messageSecurityVersion` attribute of the [\](../../configure-apps/file-schema/wcf/security-of-custombinding.md). - To set the version of the WS-Security specification that is used to secure SOAP messages, set the `messageSecurityVersion` attribute of the [\](../../configure-apps/file-schema/wcf/security-of-custombinding.md). To interoperate with WSE 3.0, set the value of the `messageSecurityVersion` attribute to . + To set the version of the WS-Security specification that is used to secure SOAP messages, set the `messageSecurityVersion` attribute of the [\](../../configure-apps/file-schema/wcf/security-of-custombinding.md). To interoperate with WSE 3.0, set the value of the `messageSecurityVersion` attribute to . - 4. Specify that the August 2004 version of the WS-Addressing specification is used by WCF by adding a [\](../../configure-apps/file-schema/wcf/textmessageencoding.md) and set the `messageVersion` to its value to . + 4. Specify that the August 2004 version of the WS-Addressing specification is used by WCF by adding a [\](../../configure-apps/file-schema/wcf/textmessageencoding.md) and set the `messageVersion` to its value to . > [!NOTE] - > When you are using SOAP 1.2, set the `messageVersion` attribute to . + > When you are using SOAP 1.2, set the `messageVersion` attribute to . 2. Specify that the service uses the custom binding. diff --git a/docs/framework/wcf/feature-details/how-to-control-service-instancing.md b/docs/framework/wcf/feature-details/how-to-control-service-instancing.md index ea841a9dec4a4..39d46d4a858eb 100644 --- a/docs/framework/wcf/feature-details/how-to-control-service-instancing.md +++ b/docs/framework/wcf/feature-details/how-to-control-service-instancing.md @@ -2,34 +2,34 @@ description: "Learn more about: How to: Control Service Instancing" title: "How to: Control Service Instancing" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: e0b12b34-8004-443a-a46d-83a5c00f2601 --- # How to: Control Service Instancing -Setting the instance mode of a service enables you to specify when a (and its associated user-defined service object) is created. See the enumeration for the possible modes. For more information about behaviors, see [Configuring and Extending the Runtime with Behaviors](../extending/configuring-and-extending-the-runtime-with-behaviors.md). For working examples, see [Behaviors](../samples/behaviors.md). - -### To control the service instance lifetime using code - -1. Apply the to the service class. - -2. Set the property to one of the following values: , , or . - +Setting the instance mode of a service enables you to specify when a (and its associated user-defined service object) is created. See the enumeration for the possible modes. For more information about behaviors, see [Configuring and Extending the Runtime with Behaviors](../extending/configuring-and-extending-the-runtime-with-behaviors.md). For working examples, see [Behaviors](../samples/behaviors.md). + +### To control the service instance lifetime using code + +1. Apply the to the service class. + +2. Set the property to one of the following values: , , or . + [!code-csharp[C_ControlServiceInstancing#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_controlserviceinstancing/cs/source.cs#1)] - [!code-vb[C_ControlServiceInstancing#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_controlserviceinstancing/vb/source.vb#1)] - -## Example + [!code-vb[C_ControlServiceInstancing#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_controlserviceinstancing/vb/source.vb#1)] + +## Example + + The following code example sets the property of the attribute to . - The following code example sets the property of the attribute to . - [!code-csharp[c_ControlServiceInstancing#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_controlserviceinstancing/cs/source.cs#2)] - [!code-vb[c_ControlServiceInstancing#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_controlserviceinstancing/vb/source.vb#2)] - + [!code-vb[c_ControlServiceInstancing#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_controlserviceinstancing/vb/source.vb#2)] + ## See also - -- +- - - [Service: Behaviors Samples](../samples/behaviors.md) diff --git a/docs/framework/wcf/feature-details/how-to-create-a-basic-wcf-web-http-service.md b/docs/framework/wcf/feature-details/how-to-create-a-basic-wcf-web-http-service.md index 655a06f6e2425..7453f642302a7 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-basic-wcf-web-http-service.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-basic-wcf-web-http-service.md @@ -75,12 +75,12 @@ Windows Communication Foundation (WCF) allows you to create a service that expos ## To call service operations in code -1. Create an instance of within a `using` block. +1. Create an instance of within a `using` block. [!code-csharp[htBasicService#6](~/samples/snippets/csharp/VS_Snippets_CFX/htbasicservice/cs/service.cs#6)] [!code-vb[htBasicService#6](~/samples/snippets/visualbasic/VS_Snippets_CFX/htbasicservice/vb/service.vb#6)] -2. Add to the endpoint the calls. +2. Add to the endpoint the calls. [!code-csharp[htBasicService#7](~/samples/snippets/csharp/VS_Snippets_CFX/htbasicservice/cs/service.cs#7)] [!code-vb[htBasicService#7](~/samples/snippets/visualbasic/VS_Snippets_CFX/htbasicservice/vb/service.vb#7)] diff --git a/docs/framework/wcf/feature-details/how-to-create-a-channel-factory-and-use-it-to-create-and-manage-channels.md b/docs/framework/wcf/feature-details/how-to-create-a-channel-factory-and-use-it-to-create-and-manage-channels.md index b9b995d14fc2b..c3e671e242bcd 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-channel-factory-and-use-it-to-create-and-manage-channels.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-channel-factory-and-use-it-to-create-and-manage-channels.md @@ -6,14 +6,14 @@ ms.assetid: 018dcc30-9f61-419e-af8e-412a85e8d282 --- # How to: Create a Channel Factory and Use it to Create and Manage Channels -The class provides the means to create and manage duplex channels of different types that clients use to send and receive messages to and from service endpoints. - -## Example +The class provides the means to create and manage duplex channels of different types that clients use to send and receive messages to and from service endpoints. + +## Example + + The following code shows how to create a channel factory and use it to create and manage channels. + + [!code-csharp[S_CustomAuthentication#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_customauthentication/cs/instance.cs#1)] - The following code shows how to create a channel factory and use it to create and manage channels. - - [!code-csharp[S_CustomAuthentication#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_customauthentication/cs/instance.cs#1)] - ## See also -- +- diff --git a/docs/framework/wcf/feature-details/how-to-create-a-custom-binding-using-the-securitybindingelement.md b/docs/framework/wcf/feature-details/how-to-create-a-custom-binding-using-the-securitybindingelement.md index 6f12fec330d6b..c114337b8c262 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-custom-binding-using-the-securitybindingelement.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-custom-binding-using-the-securitybindingelement.md @@ -2,111 +2,111 @@ description: "Learn more about: How to: Create a Custom Binding Using the SecurityBindingElement" title: "How to: Create a Custom Binding Using the SecurityBindingElement" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "security [WCF], creating custom bindings" ms.assetid: 203a9f9e-3a73-427c-87aa-721c56265b29 --- # How to: Create a Custom Binding Using the SecurityBindingElement -Windows Communication Foundation (WCF) includes several system-provided bindings that can be configured but do not provide full flexibility when configuring all the security options that WCF supports. This topic demonstrates how to create a custom binding directly from individual binding elements and highlights some of the security settings that can be specified when creating such a binding. For more information about creating custom bindings, see [Extending Bindings](../extending/extending-bindings.md). - +Windows Communication Foundation (WCF) includes several system-provided bindings that can be configured but do not provide full flexibility when configuring all the security options that WCF supports. This topic demonstrates how to create a custom binding directly from individual binding elements and highlights some of the security settings that can be specified when creating such a binding. For more information about creating custom bindings, see [Extending Bindings](../extending/extending-bindings.md). + > [!WARNING] -> does not support the channel shape, which is the default channel shape use by the TCP transport when is set to . You must set to in order to use in this scenario. - -## Creating a Custom Binding - - In WCF all bindings are made up of *binding elements*. Each binding element derives from the class. For the standard system-provided bindings, the binding elements are created and configured for you, although you can customize some of the property settings. - - In contrast, to create a custom binding, binding elements are created and configured and a is created from the binding elements. - - To do this, you add the individual binding elements to a collection represented by an instance of the class, and then set the `Elements` property of the `CustomBinding` equal to that object. You must add the binding elements in the following order: Transaction Flow, Reliable Session, Security, Composite Duplex, One-way, Stream Security, Message Encoding, and Transport. Note that not all the binding elements listed are required in every binding. - -## SecurityBindingElement - - Three binding elements relate to message level security, all of which derive from the class. The three are , , and . The is used to provide Mixed mode security. The other two elements are used when the message layer provides security. - - Additional classes are used when transport level security is provided: - -- - -- - -- - -## Required Binding Elements - - There are a large number of possible binding elements that can be combined into a binding. Not all of these combinations are valid. This section describes the required elements that must be present in a security binding. - - Valid security bindings depend on many factors, including the following: - -- Security mode. - -- Transport protocol. - -- The message exchange pattern (MEP) specified in the contract. - - The following table shows the valid binding element stack configurations for each combination of the preceding factors. Note that these are minimal requirements. You can add additional binding elements to the binding, such as message encoding binding elements, transaction binding elements, and other binding elements. - -|Security Mode|Transport|Contract Message Exchange Pattern|Contract Message Exchange Pattern|Contract Message Exchange Pattern| -|-------------------|---------------|---------------------------------------|---------------------------------------|---------------------------------------| -|||`Datagram`|`Request Reply`|`Duplex`| -|Transport|Https|||| -|||OneWayBindingElement||| -|||HttpsTransportBindingElement|HttpsTransportBindingElement|| -||TCP|||| -|||OneWayBindingElement||| -|||SSL or Windows StreamSecurityBindingElement|SSL or Windows StreamSecurityBindingElement|SSL or Windows StreamSecurityBindingElement| -|||TcpTransportBindingElement|TcpTransportBindingElement|TcpTransportBindingElement| -|Message|Http|SymmetricSecurityBindingElement|SymmetricSecurityBindingElement|SymmetricSecurityBindingElement (authentication mode = SecureConversation)| -|||||CompositeDuplexBindingElement| -|||OneWayBindingElement||OneWayBindingElement| -|||HttpTransportBindingElement|HttpTransportBindingElement|HttpTransportBindingElement| -||Tcp|SecurityBindingElement|SecurityBindingElement|SymmetricSecurityBindingElement (authentication mode = SecureConversation)| -|||TcpTransportBindingElement|TcpTransportBindingElement|TcpTransportBindingElement| -|Mixed (transport with message credentials)|Https|TransportSecurityBindingElement|TransportSecurityBindingElement|| -|||OneWayBindingElement||| -|||HttpsTransportBindingElement|HttpsTransportBindingElement|| -||TCP|TransportSecurityBindingElement|SymmetricSecurityBindingElement (authentication mode = SecureConversation)|SymmetricSecurityBindingElement (authentication mode = SecureConversation)| -|||OneWayBindingElement||| -|||SSL or Windows StreamSecurityBindingElement|SSL or Windows StreamSecurityBindingElement|SSL or Windows StreamSecurityBindingElement| -|||TcpTransportBindingElement|TcpTransportBindingElement|TcpTransportBindingElement| - - Note that there are many configurable settings on the SecurityBindingElements. For more information, see [SecurityBindingElement Authentication Modes](securitybindingelement-authentication-modes.md). - - For more information, see [Secure Conversations and Secure Sessions](secure-conversations-and-secure-sessions.md). - -## Procedures - -#### To create a custom binding that uses a SymmetricSecurityBindingElement - -1. Create an instance of the class with the name `outputBec`. - -2. Call the static method `M:System.ServiceModel.Channels.SecurityBindingElement.CreateSspiNegotiationBindingElement(true)`, which returns an instance of the class. - -3. Add the to the collection (`outputBec`) by calling the `Add` method of the of class. - -4. Create an instance of the class and add it to the collection (`outputBec`). This specifies the encoding used by the binding. - -5. Create a and add it to the collection (`outputBec`). This specifies that the binding uses the HTTP transport. - -6. Create a new custom binding by creating an instance of the class and passing the collection `outputBec` to the constructor. - -7. The resulting custom binding shares many of the same characteristics as the standard . It specifies message-level security and Windows credentials but disables secure sessions, requires that the service credential be specified out-of-band, and does not encrypt signatures. The last can be controlled only by setting the property as shown in step 4. The other two can be controlled using settings on the standard binding. - -## Example - -### Description - - The following example provides a complete function to create a custom binding that uses a . - -### Code +> does not support the channel shape, which is the default channel shape use by the TCP transport when is set to . You must set to in order to use in this scenario. + +## Creating a Custom Binding + + In WCF all bindings are made up of *binding elements*. Each binding element derives from the class. For the standard system-provided bindings, the binding elements are created and configured for you, although you can customize some of the property settings. + + In contrast, to create a custom binding, binding elements are created and configured and a is created from the binding elements. + + To do this, you add the individual binding elements to a collection represented by an instance of the class, and then set the `Elements` property of the `CustomBinding` equal to that object. You must add the binding elements in the following order: Transaction Flow, Reliable Session, Security, Composite Duplex, One-way, Stream Security, Message Encoding, and Transport. Note that not all the binding elements listed are required in every binding. + +## SecurityBindingElement + + Three binding elements relate to message level security, all of which derive from the class. The three are , , and . The is used to provide Mixed mode security. The other two elements are used when the message layer provides security. + + Additional classes are used when transport level security is provided: + +- + +- + +- + +## Required Binding Elements + + There are a large number of possible binding elements that can be combined into a binding. Not all of these combinations are valid. This section describes the required elements that must be present in a security binding. + + Valid security bindings depend on many factors, including the following: + +- Security mode. + +- Transport protocol. + +- The message exchange pattern (MEP) specified in the contract. + + The following table shows the valid binding element stack configurations for each combination of the preceding factors. Note that these are minimal requirements. You can add additional binding elements to the binding, such as message encoding binding elements, transaction binding elements, and other binding elements. + +|Security Mode|Transport|Contract Message Exchange Pattern|Contract Message Exchange Pattern|Contract Message Exchange Pattern| +|-------------------|---------------|---------------------------------------|---------------------------------------|---------------------------------------| +|||`Datagram`|`Request Reply`|`Duplex`| +|Transport|Https|||| +|||OneWayBindingElement||| +|||HttpsTransportBindingElement|HttpsTransportBindingElement|| +||TCP|||| +|||OneWayBindingElement||| +|||SSL or Windows StreamSecurityBindingElement|SSL or Windows StreamSecurityBindingElement|SSL or Windows StreamSecurityBindingElement| +|||TcpTransportBindingElement|TcpTransportBindingElement|TcpTransportBindingElement| +|Message|Http|SymmetricSecurityBindingElement|SymmetricSecurityBindingElement|SymmetricSecurityBindingElement (authentication mode = SecureConversation)| +|||||CompositeDuplexBindingElement| +|||OneWayBindingElement||OneWayBindingElement| +|||HttpTransportBindingElement|HttpTransportBindingElement|HttpTransportBindingElement| +||Tcp|SecurityBindingElement|SecurityBindingElement|SymmetricSecurityBindingElement (authentication mode = SecureConversation)| +|||TcpTransportBindingElement|TcpTransportBindingElement|TcpTransportBindingElement| +|Mixed (transport with message credentials)|Https|TransportSecurityBindingElement|TransportSecurityBindingElement|| +|||OneWayBindingElement||| +|||HttpsTransportBindingElement|HttpsTransportBindingElement|| +||TCP|TransportSecurityBindingElement|SymmetricSecurityBindingElement (authentication mode = SecureConversation)|SymmetricSecurityBindingElement (authentication mode = SecureConversation)| +|||OneWayBindingElement||| +|||SSL or Windows StreamSecurityBindingElement|SSL or Windows StreamSecurityBindingElement|SSL or Windows StreamSecurityBindingElement| +|||TcpTransportBindingElement|TcpTransportBindingElement|TcpTransportBindingElement| + + Note that there are many configurable settings on the SecurityBindingElements. For more information, see [SecurityBindingElement Authentication Modes](securitybindingelement-authentication-modes.md). + + For more information, see [Secure Conversations and Secure Sessions](secure-conversations-and-secure-sessions.md). + +## Procedures + +#### To create a custom binding that uses a SymmetricSecurityBindingElement + +1. Create an instance of the class with the name `outputBec`. + +2. Call the static method `M:System.ServiceModel.Channels.SecurityBindingElement.CreateSspiNegotiationBindingElement(true)`, which returns an instance of the class. + +3. Add the to the collection (`outputBec`) by calling the `Add` method of the of class. + +4. Create an instance of the class and add it to the collection (`outputBec`). This specifies the encoding used by the binding. + +5. Create a and add it to the collection (`outputBec`). This specifies that the binding uses the HTTP transport. + +6. Create a new custom binding by creating an instance of the class and passing the collection `outputBec` to the constructor. + +7. The resulting custom binding shares many of the same characteristics as the standard . It specifies message-level security and Windows credentials but disables secure sessions, requires that the service credential be specified out-of-band, and does not encrypt signatures. The last can be controlled only by setting the property as shown in step 4. The other two can be controlled using settings on the standard binding. + +## Example + +### Description + + The following example provides a complete function to create a custom binding that uses a . + +### Code [!code-csharp[c_CustomBinding#20](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#20)] - [!code-vb[c_CustomBinding#20](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_custombinding/vb/source.vb#20)] - + [!code-vb[c_CustomBinding#20](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_custombinding/vb/source.vb#20)] + ## See also - diff --git a/docs/framework/wcf/feature-details/how-to-create-a-duplex-contract.md b/docs/framework/wcf/feature-details/how-to-create-a-duplex-contract.md index 3f83554c6b328..55b3f779ec67c 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-duplex-contract.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-duplex-contract.md @@ -2,68 +2,68 @@ title: "How to: Create a Duplex Contract" description: Learn how to make a duplex contract, which allows WCF clients and servers to communicate with each other independently. Either can initiate calls to the other. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "duplex contracts [WCF]" ms.assetid: 500a75b6-998a-47d5-8e3b-24e3aba2a434 --- # How to: Create a Duplex Contract -This topic shows the basic steps to create methods that use a duplex (two-way) contract. A duplex contract allows clients and servers to communicate with each other independently so that either can initiate calls to the other. The duplex contract is one of three message patterns available to Windows Communication Foundation (WCF) services. The other two message patterns are one-way and request-reply. A duplex contract consists of two one-way contracts between the client and the server and does not require that the method calls be correlated. Use this kind of contract when your service must query the client for more information or explicitly raise events on the client. For more information about creating a client application for a duplex contract, see [How to: Access Services with a Duplex Contract](how-to-access-services-with-a-duplex-contract.md). For a working sample, see the [Duplex](../samples/duplex.md) sample. - -### To create a duplex contract - -1. Create the interface that makes up the server side of the duplex contract. - -2. Apply the class to the interface. - +This topic shows the basic steps to create methods that use a duplex (two-way) contract. A duplex contract allows clients and servers to communicate with each other independently so that either can initiate calls to the other. The duplex contract is one of three message patterns available to Windows Communication Foundation (WCF) services. The other two message patterns are one-way and request-reply. A duplex contract consists of two one-way contracts between the client and the server and does not require that the method calls be correlated. Use this kind of contract when your service must query the client for more information or explicitly raise events on the client. For more information about creating a client application for a duplex contract, see [How to: Access Services with a Duplex Contract](how-to-access-services-with-a-duplex-contract.md). For a working sample, see the [Duplex](../samples/duplex.md) sample. + +### To create a duplex contract + +1. Create the interface that makes up the server side of the duplex contract. + +2. Apply the class to the interface. + [!code-csharp[S_WS_DualHttp#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_ws_dualhttp/cs/service.cs#3)] - [!code-vb[S_WS_DualHttp#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_ws_dualhttp/vb/service.vb#3)] - -3. Declare the method signatures in the interface. - -4. Apply the class to each method signature that must be part of the public contract. - -5. Create the callback interface that defines the set of operations that the service can invoke on the client. - + [!code-vb[S_WS_DualHttp#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_ws_dualhttp/vb/service.vb#3)] + +3. Declare the method signatures in the interface. + +4. Apply the class to each method signature that must be part of the public contract. + +5. Create the callback interface that defines the set of operations that the service can invoke on the client. + [!code-csharp[S_WS_DualHttp#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_ws_dualhttp/cs/service.cs#4)] - [!code-vb[S_WS_DualHttp#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_ws_dualhttp/vb/service.vb#4)] - -6. Declare the method signatures in the callback interface. - -7. Apply the class to each method signature that must be part of the public contract. - -8. Link the two interfaces into a duplex contract by setting the property in the primary interface to the type of the callback interface. - -### To call methods on the client - -1. In the service's implementation of the primary contract, declare a variable for the callback interface. - -2. Set the variable to the object reference returned by the method of the class. - + [!code-vb[S_WS_DualHttp#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_ws_dualhttp/vb/service.vb#4)] + +6. Declare the method signatures in the callback interface. + +7. Apply the class to each method signature that must be part of the public contract. + +8. Link the two interfaces into a duplex contract by setting the property in the primary interface to the type of the callback interface. + +### To call methods on the client + +1. In the service's implementation of the primary contract, declare a variable for the callback interface. + +2. Set the variable to the object reference returned by the method of the class. + [!code-csharp[S_WS_DualHttp#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_ws_dualhttp/cs/service.cs#1)] - [!code-vb[S_WS_DualHttp#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_ws_dualhttp/vb/service.vb#1)] - + [!code-vb[S_WS_DualHttp#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_ws_dualhttp/vb/service.vb#1)] + [!code-csharp[S_WS_DualHttp#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_ws_dualhttp/cs/service.cs#2)] - [!code-vb[S_WS_DualHttp#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_ws_dualhttp/vb/service.vb#2)] - -3. Call the methods defined by the callback interface. - -## Example - - The following code example demonstrates duplex communication. The service’s contract contains service operations for moving forward and backward. The client’s contract contains a service operation for reporting its position. - + [!code-vb[S_WS_DualHttp#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_ws_dualhttp/vb/service.vb#2)] + +3. Call the methods defined by the callback interface. + +## Example + + The following code example demonstrates duplex communication. The service’s contract contains service operations for moving forward and backward. The client’s contract contains a service operation for reporting its position. + [!code-csharp[S_WS_DualHttp#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_ws_dualhttp/cs/service.cs#5)] - [!code-vb[S_WS_DualHttp#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_ws_dualhttp/vb/service.vb#5)] - -- Applying the and attributes allows the automatic generation of service contract definitions in the Web Services Description Language (WSDL). - -- Use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to retrieve the WSDL document and (optional) code and configuration for a client. - -- Endpoints exposing duplex services must be secured. When a service receives a duplex message, it looks at the ReplyTo in that incoming message to determine where to send the reply. If the channel is not secured, then an untrusted client could send a malicious message with a target machine's ReplyTo, leading to a denial of service of the target machine. With regular request-reply messages, this is not an issue, because the ReplyTo is ignored and the response is sent on the channel the original message came in on. - + [!code-vb[S_WS_DualHttp#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_ws_dualhttp/vb/service.vb#5)] + +- Applying the and attributes allows the automatic generation of service contract definitions in the Web Services Description Language (WSDL). + +- Use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to retrieve the WSDL document and (optional) code and configuration for a client. + +- Endpoints exposing duplex services must be secured. When a service receives a duplex message, it looks at the ReplyTo in that incoming message to determine where to send the reply. If the channel is not secured, then an untrusted client could send a malicious message with a target machine's ReplyTo, leading to a denial of service of the target machine. With regular request-reply messages, this is not an issue, because the ReplyTo is ignored and the response is sent on the channel the original message came in on. + ## See also - diff --git a/docs/framework/wcf/feature-details/how-to-create-a-federated-client.md b/docs/framework/wcf/feature-details/how-to-create-a-federated-client.md index 5aecb11ac2c5e..94b3e22aa22d9 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-federated-client.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-federated-client.md @@ -21,7 +21,7 @@ In Windows Communication Foundation (WCF), creating a client for a *federated se 3. Set the properties of the , which allows certificates needed to communicate securely with given endpoints, such as security token services. > [!NOTE] -> A might be thrown when a client uses impersonated credentials, the binding or a custom-issued token, and asymmetric keys. Asymmetric keys are used with the binding and custom-issued tokens when the and properties, respectively, are set to . The is thrown when the client attempts to send a message and a user profile doesn’t exist for the identity that the client is impersonating. To mitigate this issue, log on to the client computer or call `LoadUserProfile` before sending the message. +> A might be thrown when a client uses impersonated credentials, the binding or a custom-issued token, and asymmetric keys. Asymmetric keys are used with the binding and custom-issued tokens when the and properties, respectively, are set to . The is thrown when the client attempts to send a message and a user profile doesn’t exist for the identity that the client is impersonating. To mitigate this issue, log on to the client computer or call `LoadUserProfile` before sending the message. This topic provides detailed information about these procedures. For more information about creating an appropriate binding, see [How to: Create a WSFederationHttpBinding](how-to-create-a-wsfederationhttpbinding.md). For more information about how a federated service works, see [Federation](federation.md). @@ -42,14 +42,14 @@ In Windows Communication Foundation (WCF), creating a client for a *federated se ### To configure an IssuedTokenClientCredential in code -1. Access the through the property of the class (returned by the property of the class, or through the class), as shown in the following example code. +1. Access the through the property of the class (returned by the property of the class, or through the class), as shown in the following example code. [!code-csharp[c_CreateSTS#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_creatests/cs/source.cs#9)] [!code-vb[c_CreateSTS#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#9)] -2. If token caching is not required, set the property to `false`. The property controls whether such tokens from a security token service are cached. If this property is set to `false`, the client requests a new token from the security token service whenever it must re-authenticate itself to the federated service, regardless of whether a previous token is still valid. If this property is set to `true`, the client reuses an existing token whenever it must re-authenticate itself to the federated service (as long as the token has not expired). The default is `true`. +2. If token caching is not required, set the property to `false`. The property controls whether such tokens from a security token service are cached. If this property is set to `false`, the client requests a new token from the security token service whenever it must re-authenticate itself to the federated service, regardless of whether a previous token is still valid. If this property is set to `true`, the client reuses an existing token whenever it must re-authenticate itself to the federated service (as long as the token has not expired). The default is `true`. -3. If a time limit is required on cached tokens, set the property to a value. The property specifies how long a token can be cached. After the specified time span has elapsed, the token is removed from the client cache. By default, tokens are cached indefinitely. The following example sets the time span to 10 minutes. +3. If a time limit is required on cached tokens, set the property to a value. The property specifies how long a token can be cached. After the specified time span has elapsed, the token is removed from the client cache. By default, tokens are cached indefinitely. The following example sets the time span to 10 minutes. [!code-csharp[c_CreateSTS#15](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_creatests/cs/source.cs#15)] [!code-vb[c_CreateSTS#15](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#15)] @@ -61,13 +61,13 @@ In Windows Communication Foundation (WCF), creating a client for a *federated se The renewal interval determined by the token validity period and the `IssuedTokenRenewalThresholdPercentage` value is overridden by the `MaxIssuedTokenCachingTime` value in cases where the caching time is shorter than the renewal threshold time. For example, if the product of `IssuedTokenRenewalThresholdPercentage` and the token's duration is eight hours, and the `MaxIssuedTokenCachingTime` value is 10 minutes, the client contacts the security token service for an updated token every 10 minutes. -5. If a key entropy mode other than is needed on a binding that does not use message security or transport security with message credentials (for example. the binding does not have a ), set the property to an appropriate value. The *entropy* mode determines whether symmetric keys can be controlled using the property. This default is , where both the client and the token issuer provide data that is combined to produce the actual key. Other values are and , which means the entire key is specified by the client or the server, respectively. The following example sets the property to use only the server data for the key. +5. If a key entropy mode other than is needed on a binding that does not use message security or transport security with message credentials (for example. the binding does not have a ), set the property to an appropriate value. The *entropy* mode determines whether symmetric keys can be controlled using the property. This default is , where both the client and the token issuer provide data that is combined to produce the actual key. Other values are and , which means the entire key is specified by the client or the server, respectively. The following example sets the property to use only the server data for the key. [!code-csharp[c_CreateSTS#17](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_creatests/cs/source.cs#17)] [!code-vb[c_CreateSTS#17](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#17)] > [!NOTE] - > If a is present in a security token service or service binding, the set on is overridden by the property of the `SecurityBindingElement`. + > If a is present in a security token service or service binding, the set on is overridden by the property of the `SecurityBindingElement`. 6. Configure any issuer-specific endpoint behaviors by adding them to the collection returned by the property. @@ -105,17 +105,17 @@ In Windows Communication Foundation (WCF), creating a client for a *federated se ### To configure an X509CertificateRecipientClientCredential in code -1. Access the through the property of the property of the class or the property. +1. Access the through the property of the property of the class or the property. [!code-csharp[c_CreateSTS#18](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_creatests/cs/source.cs#18)] [!code-vb[c_CreateSTS#18](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#18)] -2. If an instance is available for the certificate for a given endpoint, use the method of the collection returned by the property. +2. If an instance is available for the certificate for a given endpoint, use the method of the collection returned by the property. [!code-csharp[c_CreateSTS#19](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_creatests/cs/source.cs#19)] [!code-vb[c_CreateSTS#19](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#19)] -3. If an instance is not available, use the method of the class as shown in the following example. +3. If an instance is not available, use the method of the class as shown in the following example. [!code-csharp[c_CreateSTS#20](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_creatests/cs/source.cs#20)] [!code-vb[c_CreateSTS#20](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#20)] @@ -151,14 +151,14 @@ In Windows Communication Foundation (WCF), creating a client for a *federated se If clients are expected to always use a local issuer, note the following: the default output of Svcutil.exe results in the local issuer not being used if the second-to-last security token service in the chain specifies an issuer address or issuer metadata address. - For more information about setting the , , and properties of the class, see [How to: Configure a Local Issuer](how-to-configure-a-local-issuer.md). + For more information about setting the , , and properties of the class, see [How to: Configure a Local Issuer](how-to-configure-a-local-issuer.md). ## Scoped Certificates - If service certificates must be specified for communicating with any of the security token services, typically because certificate negotiation is not being used, they can be specified using the property of the class. The method takes a and an as parameters. The specified certificate is used when communicating with endpoints at the specified URI. Alternatively, you can use the method to add a certificate to the collection returned by the property. + If service certificates must be specified for communicating with any of the security token services, typically because certificate negotiation is not being used, they can be specified using the property of the class. The method takes a and an as parameters. The specified certificate is used when communicating with endpoints at the specified URI. Alternatively, you can use the method to add a certificate to the collection returned by the property. > [!NOTE] -> The client idea of certificates that are scoped to a given URI applies only to applications that are making outbound calls to services that expose endpoints at those URIs. It does not apply to certificates that are used to sign issued tokens, such as those configured on the server in the collection returned by the of the class. For more information, see [How to: Configure Credentials on a Federation Service](how-to-configure-credentials-on-a-federation-service.md). +> The client idea of certificates that are scoped to a given URI applies only to applications that are making outbound calls to services that expose endpoints at those URIs. It does not apply to certificates that are used to sign issued tokens, such as those configured on the server in the collection returned by the of the class. For more information, see [How to: Configure Credentials on a Federation Service](how-to-configure-credentials-on-a-federation-service.md). ## See also diff --git a/docs/framework/wcf/feature-details/how-to-create-a-security-context-token-for-a-secure-session.md b/docs/framework/wcf/feature-details/how-to-create-a-security-context-token-for-a-secure-session.md index b7a99f0350347..46c7909a534e3 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-security-context-token-for-a-secure-session.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-security-context-token-for-a-secure-session.md @@ -2,113 +2,113 @@ description: "Learn more about: How to: Create a Security Context Token for a Secure Session" title: "How to: Create a Security Context Token for a Secure Session" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 640676b6-c75a-4ff7-aea4-b1a1524d71b2 --- # How to: Create a Security Context Token for a Secure Session -By using a stateful security context token (SCT) in a secure session, the session can withstand the service being recycled. For instance, when a stateless SCT is used in a secure session and Internet Information Services (IIS) is reset, then the session data that is associated with the service is lost. This session data includes an SCT token cache. So, the next time a client sends the service a stateless SCT, an error is returned, because the key that is associated with the SCT cannot be retrieved. If, however, a stateful SCT is used, then the key that is associated with the SCT is contained within the SCT. Because the key is contained within the SCT and thus contained within the message, the secure session is not affected by the service being recycled. By default, Windows Communication Foundation (WCF) uses stateless SCTs in a secure session. This topic details how to use stateful SCTs in a secure session. - +By using a stateful security context token (SCT) in a secure session, the session can withstand the service being recycled. For instance, when a stateless SCT is used in a secure session and Internet Information Services (IIS) is reset, then the session data that is associated with the service is lost. This session data includes an SCT token cache. So, the next time a client sends the service a stateless SCT, an error is returned, because the key that is associated with the SCT cannot be retrieved. If, however, a stateful SCT is used, then the key that is associated with the SCT is contained within the SCT. Because the key is contained within the SCT and thus contained within the message, the secure session is not affected by the service being recycled. By default, Windows Communication Foundation (WCF) uses stateless SCTs in a secure session. This topic details how to use stateful SCTs in a secure session. + > [!NOTE] -> Stateful SCTs cannot be used in a secure session that involves a contract that derives from . - +> Stateful SCTs cannot be used in a secure session that involves a contract that derives from . + > [!NOTE] -> For applications that use stateful SCTs in a secure session, the thread identity for the service must be a user account that has an associated user profile. When the service is run under an account that does not have a user profile, such as `Local Service`, an exception may be thrown. - +> For applications that use stateful SCTs in a secure session, the thread identity for the service must be a user account that has an associated user profile. When the service is run under an account that does not have a user profile, such as `Local Service`, an exception may be thrown. + > [!NOTE] -> When impersonation is required on Windows XP, use a secure session without a stateful SCT. When stateful SCTs are used with impersonation, an is thrown. For more information, see [Unsupported Scenarios](unsupported-scenarios.md). - -### To use stateful SCTs in a secure session - -- Create a custom binding that specifies that SOAP messages are protected by a secure session that uses a stateful SCT. - - 1. Define a custom binding, by adding a [\](../../configure-apps/file-schema/wcf/custombinding.md) to the configuration file for the service. - - ```xml - +> When impersonation is required on Windows XP, use a secure session without a stateful SCT. When stateful SCTs are used with impersonation, an is thrown. For more information, see [Unsupported Scenarios](unsupported-scenarios.md). + +### To use stateful SCTs in a secure session + +- Create a custom binding that specifies that SOAP messages are protected by a secure session that uses a stateful SCT. + + 1. Define a custom binding, by adding a [\](../../configure-apps/file-schema/wcf/custombinding.md) to the configuration file for the service. + + ```xml + - ``` - - 2. Add a [\](../../configure-apps/file-schema/wcf/bindings.md) child element to the [\](../../configure-apps/file-schema/wcf/custombinding.md). - - Specify a binding name by setting the `name` attribute to a unique name within the configuration file. - - ```xml - + ``` + + 2. Add a [\](../../configure-apps/file-schema/wcf/bindings.md) child element to the [\](../../configure-apps/file-schema/wcf/custombinding.md). + + Specify a binding name by setting the `name` attribute to a unique name within the configuration file. + + ```xml + - ``` - - 3. Specify the authentication mode for messages sent to and from this service by adding a [\](../../configure-apps/file-schema/wcf/security-of-custombinding.md) child element to the [\](../../configure-apps/file-schema/wcf/custombinding.md). - - Specify that a secure session is used by setting the `authenticationMode` attribute to `SecureConversation`. Specify that stateful SCTs are used by setting the `requireSecurityContextCancellation` attribute to `false`. - - ```xml - ](../../configure-apps/file-schema/wcf/security-of-custombinding.md) child element to the [\](../../configure-apps/file-schema/wcf/custombinding.md). + + Specify that a secure session is used by setting the `authenticationMode` attribute to `SecureConversation`. Specify that stateful SCTs are used by setting the `requireSecurityContextCancellation` attribute to `false`. + + ```xml + + + ``` + + 4. Specify how the client is authenticated while the secure session is established by adding a [\](../../configure-apps/file-schema/wcf/secureconversationbootstrap.md) child element to the [\](../../configure-apps/file-schema/wcf/security-of-custombinding.md). + + Specify how the client is authenticated by setting the `authenticationMode` attribute. + + ```xml + + ``` + + 5. Specify the message encoding by adding an encoding element, such as [\](../../configure-apps/file-schema/wcf/textmessageencoding.md). + + ```xml + + ``` + + 6. Specify the transport by adding a transport element, such as the [\](../../configure-apps/file-schema/wcf/httptransport.md). + + ```xml + + ``` + + The following code example uses configuration to specify a custom binding that messages can use with stateful SCTs in a secure session. + + ```xml + + + + - ``` - - 4. Specify how the client is authenticated while the secure session is established by adding a [\](../../configure-apps/file-schema/wcf/secureconversationbootstrap.md) child element to the [\](../../configure-apps/file-schema/wcf/security-of-custombinding.md). - - Specify how the client is authenticated by setting the `authenticationMode` attribute. - - ```xml - - ``` - - 5. Specify the message encoding by adding an encoding element, such as [\](../../configure-apps/file-schema/wcf/textmessageencoding.md). - - ```xml - - ``` - - 6. Specify the transport by adding a transport element, such as the [\](../../configure-apps/file-schema/wcf/httptransport.md). - - ```xml - - ``` - - The following code example uses configuration to specify a custom binding that messages can use with stateful SCTs in a secure session. - - ```xml - - - - - - - - - - ``` - -## Example - - The following code example creates a custom binding that uses the authentication mode to bootstrap a secure session. - + + + + + ``` + +## Example + + The following code example creates a custom binding that uses the authentication mode to bootstrap a secure session. + [!code-csharp[c_CreateStatefulSCT#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_createstatefulsct/cs/secureservice.cs#2)] - [!code-vb[c_CreateStatefulSCT#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_createstatefulsct/vb/secureservice.vb#2)] - - When Windows authentication is used in combination with a stateful SCT, WCF does not populate the property with the actual caller's identity but instead sets the property to anonymous. Because WCF security must re-create the content of the service security context for every request from the incoming SCT, the server does not keep track of the security session in the memory. Because it is impossible to serialize the instance into the SCT, the property returns an anonymous identity. - - The following configuration exhibits this behavior. - -```xml - - - + [!code-vb[c_CreateStatefulSCT#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_createstatefulsct/vb/secureservice.vb#2)] + + When Windows authentication is used in combination with a stateful SCT, WCF does not populate the property with the actual caller's identity but instead sets the property to anonymous. Because WCF security must re-create the content of the service security context for every request from the incoming SCT, the server does not keep track of the security session in the memory. Because it is impossible to serialize the instance into the SCT, the property returns an anonymous identity. + + The following configuration exhibits this behavior. + +```xml + + + - - - - - -``` - + requireSecurityContextCancellation="false"> + + + + + +``` + ## See also - [\](../../configure-apps/file-schema/wcf/custombinding.md) diff --git a/docs/framework/wcf/feature-details/how-to-create-a-securitybindingelement-for-a-specified-authentication-mode.md b/docs/framework/wcf/feature-details/how-to-create-a-securitybindingelement-for-a-specified-authentication-mode.md index e9b609623774c..22a9aa56fcbd0 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-securitybindingelement-for-a-specified-authentication-mode.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-securitybindingelement-for-a-specified-authentication-mode.md @@ -2,27 +2,27 @@ description: "Learn more about: How to: Create a SecurityBindingElement for a Specified Authentication Mode" title: "How to: Create a SecurityBindingElement for a Specified Authentication Mode" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: a7c7747a-5b8c-463f-8493-7266dac75066 --- # How to: Create a SecurityBindingElement for a Specified Authentication Mode -Windows Communication Foundation (WCF) provides several modes by which clients and services authenticate to one another. You can create security binding elements for these authentication modes by using static methods on the class or through configuration, as shown in the following example. - - For more information about the 18 authentication modes, see [SecurityBindingElement Authentication Modes](securitybindingelement-authentication-modes.md). - -## Example +Windows Communication Foundation (WCF) provides several modes by which clients and services authenticate to one another. You can create security binding elements for these authentication modes by using static methods on the class or through configuration, as shown in the following example. + + For more information about the 18 authentication modes, see [SecurityBindingElement Authentication Modes](securitybindingelement-authentication-modes.md). + +## Example + + The following code example shows methods for creating bindings for the various authentication modes. - The following code example shows methods for creating bindings for the various authentication modes. - > [!NOTE] -> Once an instance of the object is created, a number of properties are immutable, such as and . Calling `set` on such properties does not change them. - +> Once an instance of the object is created, a number of properties are immutable, such as and . Calling `set` on such properties does not change them. + [!code-csharp[c_CustomBindingsAuthMode#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombindingsauthmode/cs/source.cs#2)] - [!code-vb[c_CustomBindingsAuthMode#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_custombindingsauthmode/vb/source.vb#2)] - + [!code-vb[c_CustomBindingsAuthMode#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_custombindingsauthmode/vb/source.vb#2)] + ## See also - [SecurityBindingElement Authentication Modes](securitybindingelement-authentication-modes.md) diff --git a/docs/framework/wcf/feature-details/how-to-create-a-service-endpoint-in-code.md b/docs/framework/wcf/feature-details/how-to-create-a-service-endpoint-in-code.md index 0ed95235b29cb..c47a08368a278 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-service-endpoint-in-code.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-service-endpoint-in-code.md @@ -2,46 +2,46 @@ title: "How to: Create a Service Endpoint in Code" description: Learn how to implement a service in a class and define its endpoint programmatically. In WCF, endpoints are usually defined in a configuration file. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 3fbb22fa-2930-48b8-b437-def1de87c6a0 --- # How to: Create a Service Endpoint in Code -In this example, an `ICalculator` contract is defined for a calculator service, the service is implemented in the `CalculatorService` class, and then its endpoint is defined in code, where it is specified that the service must use the class. - - It is usually the best practice to specify the binding and address information declaratively in configuration rather than imperatively in code. Defining endpoints in code is usually not practical because the bindings and addresses for a deployed service are typically different from those used while the service is being developed. More generally, keeping the binding and addressing information out of the code allows them to change without having to recompile or redeploy the application. - -#### To create a service endpoint in code - -1. Create the interface that defines the service contract. - +In this example, an `ICalculator` contract is defined for a calculator service, the service is implemented in the `CalculatorService` class, and then its endpoint is defined in code, where it is specified that the service must use the class. + + It is usually the best practice to specify the binding and address information declaratively in configuration rather than imperatively in code. Defining endpoints in code is usually not practical because the bindings and addresses for a deployed service are typically different from those used while the service is being developed. More generally, keeping the binding and addressing information out of the code allows them to change without having to recompile or redeploy the application. + +#### To create a service endpoint in code + +1. Create the interface that defines the service contract. + [!code-csharp[c_HowTo_CodeServiceBinding#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howto_codeservicebinding/cs/source.cs#1)] - [!code-vb[c_HowTo_CodeServiceBinding#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_codeservicebinding/vb/source.vb#1)] - -2. Implement the service contract defined in step 1. - + [!code-vb[c_HowTo_CodeServiceBinding#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_codeservicebinding/vb/source.vb#1)] + +2. Implement the service contract defined in step 1. + [!code-csharp[c_HowTo_CodeServiceBinding#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howto_codeservicebinding/cs/source.cs#2)] - [!code-vb[c_HowTo_CodeServiceBinding#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_codeservicebinding/vb/source.vb#2)] - -3. In the hosting application, create the base address for the service and the binding to be used with the service. - + [!code-vb[c_HowTo_CodeServiceBinding#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_codeservicebinding/vb/source.vb#2)] + +3. In the hosting application, create the base address for the service and the binding to be used with the service. + [!code-csharp[c_HowTo_CodeServiceBinding#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howto_codeservicebinding/cs/source.cs#3)] - [!code-vb[c_HowTo_CodeServiceBinding#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_codeservicebinding/vb/source.vb#3)] - -4. Create the host and call or one of the other overloads to add the service endpoint for the host. - + [!code-vb[c_HowTo_CodeServiceBinding#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_codeservicebinding/vb/source.vb#3)] + +4. Create the host and call or one of the other overloads to add the service endpoint for the host. + [!code-csharp[c_HowTo_CodeServiceBinding#6](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howto_codeservicebinding/cs/source.cs#6)] - [!code-vb[c_HowTo_CodeServiceBinding#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_codeservicebinding/vb/source.vb#6)] - - To specify the binding in code but to use the default endpoints provided by the runtime, pass the base address into the constructor when creating the , and do not call . - + [!code-vb[c_HowTo_CodeServiceBinding#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_codeservicebinding/vb/source.vb#6)] + + To specify the binding in code but to use the default endpoints provided by the runtime, pass the base address into the constructor when creating the , and do not call . + [!code-csharp[c_HowTo_CodeServiceBinding#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howto_codeservicebinding/cs/source.cs#7)] - [!code-vb[c_HowTo_CodeServiceBinding#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_codeservicebinding/vb/source.vb#7)] - - For more information about default endpoints, see [Simplified Configuration](../simplified-configuration.md) and [Simplified Configuration for WCF Services](../samples/simplified-configuration-for-wcf-services.md). - + [!code-vb[c_HowTo_CodeServiceBinding#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_codeservicebinding/vb/source.vb#7)] + + For more information about default endpoints, see [Simplified Configuration](../simplified-configuration.md) and [Simplified Configuration for WCF Services](../samples/simplified-configuration-for-wcf-services.md). + ## See also - [How to: Specify a Service Binding in Code](../how-to-specify-a-service-binding-in-code.md) diff --git a/docs/framework/wcf/feature-details/how-to-create-a-service-that-requires-sessions.md b/docs/framework/wcf/feature-details/how-to-create-a-service-that-requires-sessions.md index bd4d0eca527f7..74622514406ea 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-service-that-requires-sessions.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-service-that-requires-sessions.md @@ -2,41 +2,41 @@ description: "Learn more about: How to: Create a Service That Requires Sessions" title: "How to: Create a Service That Requires Sessions" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 8a7613ef-0df9-47c3-b8dc-47f42cb1fd8b --- # How to: Create a Service That Requires Sessions -Sessions create a shared state between two or more endpoints that enables useful features such as callbacks, multi-hop security, and associations between clients and service instances. For more information about sessions in Windows Communication Foundation (WCF) applications, see [Using Sessions](../using-sessions.md). - -### To specify that a contract require its binding to support sessions - -1. Create a service contract with at least one operation. For an example of how to create a service contract, see [How to: Define a Service Contract](../how-to-define-a-wcf-service-contract.md). - -2. Modify the that declares the contract by setting the property to either: - - - if this contract must be run within a session. - - - if this contract can be run within a session. - - - if this contract must not be run within a session. - -3. Configure your service endpoint to use a binding that supports sessions. The following configuration example shows the use of the , which supports a WS`-`ReliableMessaging session. - +Sessions create a shared state between two or more endpoints that enables useful features such as callbacks, multi-hop security, and associations between clients and service instances. For more information about sessions in Windows Communication Foundation (WCF) applications, see [Using Sessions](../using-sessions.md). + +### To specify that a contract require its binding to support sessions + +1. Create a service contract with at least one operation. For an example of how to create a service contract, see [How to: Define a Service Contract](../how-to-define-a-wcf-service-contract.md). + +2. Modify the that declares the contract by setting the property to either: + + - if this contract must be run within a session. + + - if this contract can be run within a session. + + - if this contract must not be run within a session. + +3. Configure your service endpoint to use a binding that supports sessions. The following configuration example shows the use of the , which supports a WS`-`ReliableMessaging session. + [!code-xml[SCA.Session#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/sca.session/cs/hostapplication.exe.config#2)] - -## Example - The following example code shows how to specify a contract-level session requirement and use a configuration file to support that requirement with the binding. - +## Example + + The following example code shows how to specify a contract-level session requirement and use a configuration file to support that requirement with the binding. + [!code-csharp[SCA.Session#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/sca.session/cs/services.cs#1)] [!code-vb[SCA.Session#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/sca.session/vb/services.vb#1)] [!code-xml[SCA.Session#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/sca.session/cs/hostapplication.exe.config#2)] - + ## See also - -- +- - diff --git a/docs/framework/wcf/feature-details/how-to-create-a-supporting-credential.md b/docs/framework/wcf/feature-details/how-to-create-a-supporting-credential.md index e3d18bec29b5f..82deb2d5a77e8 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-supporting-credential.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-supporting-credential.md @@ -6,82 +6,82 @@ ms.assetid: d0952919-8bb4-4978-926c-9cc108f89806 --- # How to: Create a Supporting Credential -It is possible to have a custom security scheme that requires more than one credential. For example, a service may demand from the client not just a user name and password, but also a credential that proves the client is over the age of 18. The second credential is a *supporting credential*. This topic explains how to implement such credentials in an Windows Communication Foundation (WCF) client. - +It is possible to have a custom security scheme that requires more than one credential. For example, a service may demand from the client not just a user name and password, but also a credential that proves the client is over the age of 18. The second credential is a *supporting credential*. This topic explains how to implement such credentials in an Windows Communication Foundation (WCF) client. + > [!NOTE] -> The specification for supporting credentials is part of the WS-SecurityPolicy specification. For more information, see [Web Services Security Specifications](/previous-versions/dotnet/articles/ms951273(v=msdn.10)). - -## Supporting Tokens - - In brief, when you use message security, a *primary credential* is always used to secure the message (for example, an X.509 certificate or a Kerberos ticket). - - As defined by the specification, a security binding uses *tokens* to secure the message exchange. A *token* is a representation of a security credential. - - The security binding uses a primary token identified in the security binding policy to create a signature. This signature is referred to as the *message signature*. - - Additional tokens can be specified to augment the claims provided by the token associated with the message signature. - -## Endorsing, Signing, and Encrypting - - A supporting credential results in a *supporting token* transmitted inside the message. The WS-SecurityPolicy specification defines four ways to attach a supporting token to the message, as described in the following table. - -|Purpose|Description| -|-------------|-----------------| -|Signed|The supporting token is included in the security header and is signed by the message signature.| -|Endorsing|An *endorsing token* signs the message signature.| -|Signed and Endorsing|Signed, endorsing tokens sign the entire `ds:Signature` element produced from the message signature and are themselves signed by that message signature; that is, both tokens (the token used for the message signature and the signed endorsing token) sign each other.| -|Signed and Encrypting|Signed, encrypted supporting tokens are signed supporting tokens that are also encrypted when they appear in the `wsse:SecurityHeader`.| - -## Programming Supporting Credentials - - To create a service that uses supporting tokens you must create a [\](../../configure-apps/file-schema/wcf/custombinding.md). (For more information, see [How to: Create a Custom Binding Using the SecurityBindingElement](how-to-create-a-custom-binding-using-the-securitybindingelement.md).) - - The first step when creating a custom binding is to create a security binding element, which can be one of three types: - -- - -- - -- - - All classes inherit from the , which includes four relevant properties: - -- - -- - -- - -- - -#### Scopes - - Two scopes exist for supporting credentials: - -- *Endpoint supporting tokens* support all operations of an endpoint. That is, the credential that the supporting token represents can be used whenever any endpoint operations are invoked. - -- *Operation supporting tokens* support only a specific endpoint operation. - - As indicated by the property names, supporting credentials can be either required or optional. That is, if the supporting credential is used if it is present, although it is not necessary, but the authentication will not fail if it is not present. - -## Procedures - -#### To create a custom binding that includes supporting credentials - -1. Create a security binding element. The example below creates a with the `UserNameForCertificate` authentication mode. Use the method. - -2. Add the supporting parameter to the collection of types returned by the appropriate property (`Endorsing`, `Signed`, `SignedEncrypted`, or `SignedEndorsed`). The types in the namespace include commonly used types, such as the . - -## Example - -### Description - - The following example creates an instance of the and adds an instance of the class to the collection the Endorsing property returned. - -### Code - - [!code-csharp[c_SupportingCredential#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_supportingcredential/cs/source.cs#1)] - +> The specification for supporting credentials is part of the WS-SecurityPolicy specification. For more information, see [Web Services Security Specifications](/previous-versions/dotnet/articles/ms951273(v=msdn.10)). + +## Supporting Tokens + + In brief, when you use message security, a *primary credential* is always used to secure the message (for example, an X.509 certificate or a Kerberos ticket). + + As defined by the specification, a security binding uses *tokens* to secure the message exchange. A *token* is a representation of a security credential. + + The security binding uses a primary token identified in the security binding policy to create a signature. This signature is referred to as the *message signature*. + + Additional tokens can be specified to augment the claims provided by the token associated with the message signature. + +## Endorsing, Signing, and Encrypting + + A supporting credential results in a *supporting token* transmitted inside the message. The WS-SecurityPolicy specification defines four ways to attach a supporting token to the message, as described in the following table. + +|Purpose|Description| +|-------------|-----------------| +|Signed|The supporting token is included in the security header and is signed by the message signature.| +|Endorsing|An *endorsing token* signs the message signature.| +|Signed and Endorsing|Signed, endorsing tokens sign the entire `ds:Signature` element produced from the message signature and are themselves signed by that message signature; that is, both tokens (the token used for the message signature and the signed endorsing token) sign each other.| +|Signed and Encrypting|Signed, encrypted supporting tokens are signed supporting tokens that are also encrypted when they appear in the `wsse:SecurityHeader`.| + +## Programming Supporting Credentials + + To create a service that uses supporting tokens you must create a [\](../../configure-apps/file-schema/wcf/custombinding.md). (For more information, see [How to: Create a Custom Binding Using the SecurityBindingElement](how-to-create-a-custom-binding-using-the-securitybindingelement.md).) + + The first step when creating a custom binding is to create a security binding element, which can be one of three types: + +- + +- + +- + + All classes inherit from the , which includes four relevant properties: + +- + +- + +- + +- + +#### Scopes + + Two scopes exist for supporting credentials: + +- *Endpoint supporting tokens* support all operations of an endpoint. That is, the credential that the supporting token represents can be used whenever any endpoint operations are invoked. + +- *Operation supporting tokens* support only a specific endpoint operation. + + As indicated by the property names, supporting credentials can be either required or optional. That is, if the supporting credential is used if it is present, although it is not necessary, but the authentication will not fail if it is not present. + +## Procedures + +#### To create a custom binding that includes supporting credentials + +1. Create a security binding element. The example below creates a with the `UserNameForCertificate` authentication mode. Use the method. + +2. Add the supporting parameter to the collection of types returned by the appropriate property (`Endorsing`, `Signed`, `SignedEncrypted`, or `SignedEndorsed`). The types in the namespace include commonly used types, such as the . + +## Example + +### Description + + The following example creates an instance of the and adds an instance of the class to the collection the Endorsing property returned. + +### Code + + [!code-csharp[c_SupportingCredential#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_supportingcredential/cs/source.cs#1)] + ## See also - [How to: Create a Custom Binding Using the SecurityBindingElement](how-to-create-a-custom-binding-using-the-securitybindingelement.md) diff --git a/docs/framework/wcf/feature-details/how-to-create-a-transactional-service.md b/docs/framework/wcf/feature-details/how-to-create-a-transactional-service.md index f3b8f902bb389..4f697331a4661 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-transactional-service.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-transactional-service.md @@ -6,211 +6,211 @@ ms.assetid: 1bd2e4ed-a557-43f9-ba98-4c70cb75c154 --- # How to: Create a Transactional Service -This sample demonstrates various aspects of creating a transactional service and the use of a client-initiated transaction to coordinate service operations. - -### Creating a transactional service - -1. Create a service contract and annotate the operations with the desired setting from the enumeration to specify the incoming transaction requirements. Note that you can also place the on the service class being implemented. This allows for a single implementation of an interface to use these transaction settings, instead of every implementation. - +This sample demonstrates various aspects of creating a transactional service and the use of a client-initiated transaction to coordinate service operations. + +### Creating a transactional service + +1. Create a service contract and annotate the operations with the desired setting from the enumeration to specify the incoming transaction requirements. Note that you can also place the on the service class being implemented. This allows for a single implementation of an interface to use these transaction settings, instead of every implementation. + ```csharp - [ServiceContract] - public interface ICalculator - { - [OperationContract] - // Use this to require an incoming transaction - [TransactionFlow(TransactionFlowOption.Mandatory)] - double Add(double n1, double n2); - [OperationContract] - // Use this to permit an incoming transaction - [TransactionFlow(TransactionFlowOption.Allowed)] - double Subtract(double n1, double n2); - } - ``` - -2. Create an implementation class, and use the to optionally specify a and a . You should note that in many cases, the default of 60 seconds and the default of `Unspecified` are appropriate. For each operation, you can use the attribute to specify whether work performed within the method should occur within the scope of a transaction scope according to the value of the attribute. In this case, the transaction used for the `Add` method is the same as the mandatory incoming transaction that is flowed from the client, and the transaction used for the `Subtract` method is either the same as the incoming transaction if one was flowed from the client, or a new implicitly and locally created transaction. - + [ServiceContract] + public interface ICalculator + { + [OperationContract] + // Use this to require an incoming transaction + [TransactionFlow(TransactionFlowOption.Mandatory)] + double Add(double n1, double n2); + [OperationContract] + // Use this to permit an incoming transaction + [TransactionFlow(TransactionFlowOption.Allowed)] + double Subtract(double n1, double n2); + } + ``` + +2. Create an implementation class, and use the to optionally specify a and a . You should note that in many cases, the default of 60 seconds and the default of `Unspecified` are appropriate. For each operation, you can use the attribute to specify whether work performed within the method should occur within the scope of a transaction scope according to the value of the attribute. In this case, the transaction used for the `Add` method is the same as the mandatory incoming transaction that is flowed from the client, and the transaction used for the `Subtract` method is either the same as the incoming transaction if one was flowed from the client, or a new implicitly and locally created transaction. + ```csharp - [ServiceBehavior( - TransactionIsolationLevel = System.Transactions.IsolationLevel.Serializable, - TransactionTimeout = "00:00:45")] - public class CalculatorService : ICalculator - { - [OperationBehavior(TransactionScopeRequired = true)] - public double Add(double n1, double n2) - { - // Perform transactional operation + [ServiceBehavior( + TransactionIsolationLevel = System.Transactions.IsolationLevel.Serializable, + TransactionTimeout = "00:00:45")] + public class CalculatorService : ICalculator + { + [OperationBehavior(TransactionScopeRequired = true)] + public double Add(double n1, double n2) + { + // Perform transactional operation RecordToLog($"Adding {n1} to {n2}"); - return n1 + n2; - } - - [OperationBehavior(TransactionScopeRequired = true)] - public double Subtract(double n1, double n2) - { - // Perform transactional operation + return n1 + n2; + } + + [OperationBehavior(TransactionScopeRequired = true)] + public double Subtract(double n1, double n2) + { + // Perform transactional operation RecordToLog($"Subtracting {n2} from {n1}"); - return n1 - n2; - } - - private static void RecordToLog(string recordText) - { - // Database operations omitted for brevity - // This is where the transaction provides specific benefit - // - changes to the database will be committed only when - // the transaction completes. - } - } - ``` - -3. Configure the bindings in the configuration file, specifying that the transaction context should be flowed, and the protocols to be used to do so. For more information, see [ServiceModel Transaction Configuration](servicemodel-transaction-configuration.md). Specifically, the binding type is specified in the endpoint element’s `binding` attribute. The [\](../../configure-apps/file-schema/wcf/endpoint-element.md) element contains a `bindingConfiguration` attribute that references a binding configuration named `transactionalOleTransactionsTcpBinding`, as shown in the following sample configuration. - - ```xml - - - - ``` - - Transaction flow is enabled at the configuration level by using the `transactionFlow` attribute, and the transaction protocol is specified using the `transactionProtocol` attribute, as shown in the following configuration. - - ```xml - - - - - - ``` - -### Supporting multiple transaction protocols - -1. For optimal performance, you should use the OleTransactions protocol for scenarios involving a client and service written using Windows Communication Foundation (WCF). However, the WS-AtomicTransaction (WS-AT) protocol is useful for scenarios when interoperability with third-party protocol stacks is required. You can configure WCF services to accept both protocols by providing multiple endpoints with appropriate protocol-specific bindings, as shown in the following sample configuration. - - ```xml - - - - - ``` - - The transaction protocol is specified using the `transactionProtocol` attribute. However, this attribute is absent from the system-provided `wsHttpBinding`, because this binding can only use the WS-AT protocol. - - ```xml - - - - - - - - - ``` - -### Controlling the completion of a transaction - -1. By default, WCF operations automatically complete transactions if no unhandled exceptions are thrown. You can modify this behavior by using the property and the method. When an operation is required to occur within the same transaction as another operation (for example, a debit and credit operation), you can disable the autocomplete behavior by setting the property to `false` as shown in the following `Debit` operation example. The transaction the `Debit` operation uses is not completed until a method with the property set to `true` is called, as shown in the operation `Credit1`, or when the method is called to explicitly mark the transaction as complete, as shown in the operation `Credit2`. Note that the two credit operations are shown for illustration purposes, and that a single credit operation would be more typical. - + return n1 - n2; + } + + private static void RecordToLog(string recordText) + { + // Database operations omitted for brevity + // This is where the transaction provides specific benefit + // - changes to the database will be committed only when + // the transaction completes. + } + } + ``` + +3. Configure the bindings in the configuration file, specifying that the transaction context should be flowed, and the protocols to be used to do so. For more information, see [ServiceModel Transaction Configuration](servicemodel-transaction-configuration.md). Specifically, the binding type is specified in the endpoint element’s `binding` attribute. The [\](../../configure-apps/file-schema/wcf/endpoint-element.md) element contains a `bindingConfiguration` attribute that references a binding configuration named `transactionalOleTransactionsTcpBinding`, as shown in the following sample configuration. + + ```xml + + + + ``` + + Transaction flow is enabled at the configuration level by using the `transactionFlow` attribute, and the transaction protocol is specified using the `transactionProtocol` attribute, as shown in the following configuration. + + ```xml + + + + + + ``` + +### Supporting multiple transaction protocols + +1. For optimal performance, you should use the OleTransactions protocol for scenarios involving a client and service written using Windows Communication Foundation (WCF). However, the WS-AtomicTransaction (WS-AT) protocol is useful for scenarios when interoperability with third-party protocol stacks is required. You can configure WCF services to accept both protocols by providing multiple endpoints with appropriate protocol-specific bindings, as shown in the following sample configuration. + + ```xml + + + + + ``` + + The transaction protocol is specified using the `transactionProtocol` attribute. However, this attribute is absent from the system-provided `wsHttpBinding`, because this binding can only use the WS-AT protocol. + + ```xml + + + + + + + + + ``` + +### Controlling the completion of a transaction + +1. By default, WCF operations automatically complete transactions if no unhandled exceptions are thrown. You can modify this behavior by using the property and the method. When an operation is required to occur within the same transaction as another operation (for example, a debit and credit operation), you can disable the autocomplete behavior by setting the property to `false` as shown in the following `Debit` operation example. The transaction the `Debit` operation uses is not completed until a method with the property set to `true` is called, as shown in the operation `Credit1`, or when the method is called to explicitly mark the transaction as complete, as shown in the operation `Credit2`. Note that the two credit operations are shown for illustration purposes, and that a single credit operation would be more typical. + ```csharp - [ServiceBehavior] - public class CalculatorService : IAccount - { - [OperationBehavior( - TransactionScopeRequired = true, TransactionAutoComplete = false)] - public void Debit(double n) - { - // Perform debit operation - - return; - } - - [OperationBehavior( - TransactionScopeRequired = true, TransactionAutoComplete = true)] - public void Credit1(double n) - { - // Perform credit operation - - return; - } - - [OperationBehavior( - TransactionScopeRequired = true, TransactionAutoComplete = false)] - public void Credit2(double n) - { - // Perform alternate credit operation - - OperationContext.Current.SetTransactionComplete(); - return; - } - } - ``` - -2. For the purposes of transaction correlation, setting the property to `false` requires the use of a sessionful binding. This requirement is specified with the `SessionMode` property on the . - + [ServiceBehavior] + public class CalculatorService : IAccount + { + [OperationBehavior( + TransactionScopeRequired = true, TransactionAutoComplete = false)] + public void Debit(double n) + { + // Perform debit operation + + return; + } + + [OperationBehavior( + TransactionScopeRequired = true, TransactionAutoComplete = true)] + public void Credit1(double n) + { + // Perform credit operation + + return; + } + + [OperationBehavior( + TransactionScopeRequired = true, TransactionAutoComplete = false)] + public void Credit2(double n) + { + // Perform alternate credit operation + + OperationContext.Current.SetTransactionComplete(); + return; + } + } + ``` + +2. For the purposes of transaction correlation, setting the property to `false` requires the use of a sessionful binding. This requirement is specified with the `SessionMode` property on the . + ```csharp - [ServiceContract(SessionMode = SessionMode.Required)] - public interface IAccount - { - [OperationContract] - [TransactionFlow(TransactionFlowOption.Allowed)] - void Debit(double n); - [OperationContract] - [TransactionFlow(TransactionFlowOption.Allowed)] - void Credit1(double n); - [OperationContract] - [TransactionFlow(TransactionFlowOption.Allowed)] - void Credit2(double n); - } - ``` - -### Controlling the lifetime of a transactional service instance - -1. WCF uses the property to specify whether the underlying service instance is released when a transaction completes. Since this defaults to `true`, unless configured otherwise, WCF exhibits an efficient and predictable "just-in-time" activation behavior. Calls to a service on a subsequent transaction are assured a new service instance with no remnants of the previous transaction's state. While this is often useful, sometimes you may want to maintain state within the service instance beyond the transaction completion. Examples of this would be when required state or handles to resources are expensive to retrieve or reconstitute. You can do this by setting the property to `false`. With that setting, the instance and any associated state will be available on subsequent calls. When using this, give careful consideration to when and how state and transactions will be cleared and completed. The following sample demonstrates how to do this by maintaining the instance with the `runningTotal` variable. - + [ServiceContract(SessionMode = SessionMode.Required)] + public interface IAccount + { + [OperationContract] + [TransactionFlow(TransactionFlowOption.Allowed)] + void Debit(double n); + [OperationContract] + [TransactionFlow(TransactionFlowOption.Allowed)] + void Credit1(double n); + [OperationContract] + [TransactionFlow(TransactionFlowOption.Allowed)] + void Credit2(double n); + } + ``` + +### Controlling the lifetime of a transactional service instance + +1. WCF uses the property to specify whether the underlying service instance is released when a transaction completes. Since this defaults to `true`, unless configured otherwise, WCF exhibits an efficient and predictable "just-in-time" activation behavior. Calls to a service on a subsequent transaction are assured a new service instance with no remnants of the previous transaction's state. While this is often useful, sometimes you may want to maintain state within the service instance beyond the transaction completion. Examples of this would be when required state or handles to resources are expensive to retrieve or reconstitute. You can do this by setting the property to `false`. With that setting, the instance and any associated state will be available on subsequent calls. When using this, give careful consideration to when and how state and transactions will be cleared and completed. The following sample demonstrates how to do this by maintaining the instance with the `runningTotal` variable. + ```csharp - [ServiceBehavior(TransactionIsolationLevel = [ServiceBehavior( - ReleaseServiceInstanceOnTransactionComplete = false)] - public class CalculatorService : ICalculator - { - double runningTotal = 0; - - [OperationBehavior(TransactionScopeRequired = true)] - public double Add(double n) - { - // Perform transactional operation + [ServiceBehavior(TransactionIsolationLevel = [ServiceBehavior( + ReleaseServiceInstanceOnTransactionComplete = false)] + public class CalculatorService : ICalculator + { + double runningTotal = 0; + + [OperationBehavior(TransactionScopeRequired = true)] + public double Add(double n) + { + // Perform transactional operation RecordToLog($"Adding {n} to {runningTotal}"); - runningTotal = runningTotal + n; - return runningTotal; - } - - [OperationBehavior(TransactionScopeRequired = true)] - public double Subtract(double n) - { - // Perform transactional operation + runningTotal = runningTotal + n; + return runningTotal; + } + + [OperationBehavior(TransactionScopeRequired = true)] + public double Subtract(double n) + { + // Perform transactional operation RecordToLog($"Subtracting {n} from {runningTotal}"); - runningTotal = runningTotal - n; - return runningTotal; - } - - private static void RecordToLog(string recordText) - { - // Database operations omitted for brevity - } - } - ``` - + runningTotal = runningTotal - n; + return runningTotal; + } + + private static void RecordToLog(string recordText) + { + // Database operations omitted for brevity + } + } + ``` + > [!NOTE] > Since the instance lifetime is a behavior that is internal to the service, and controlled through the property, no modification to the service configuration or service contract is required to set the instance behavior. In addition, the wire will contain no representation of this. diff --git a/docs/framework/wcf/feature-details/how-to-create-a-wsfederationhttpbinding.md b/docs/framework/wcf/feature-details/how-to-create-a-wsfederationhttpbinding.md index 37d31ed490fa4..002d75f333526 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-wsfederationhttpbinding.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-wsfederationhttpbinding.md @@ -42,9 +42,9 @@ In Windows Communication Foundation (WCF), the . -2. Set the property to or as required. If an algorithm suite other than is required, set the property to a value taken from . +2. Set the property to or as required. If an algorithm suite other than is required, set the property to a value taken from . -3. Set the property as appropriate. +3. Set the property as appropriate. 4. Set the property to `SymmetricKey` or .`AsymmetricKey` as required. @@ -56,7 +56,7 @@ In Windows Communication Foundation (WCF), the instance for the metadata of the security token service and assign it to the `IssuerMetadataAddress` property. -9. Optional on both the client and the service. Create and add one or more instances to the collection returned by the property. +9. Optional on both the client and the service. Create and add one or more instances to the collection returned by the property. 10. Optional on both the client and the service. Create and add one or more instances to the collection returned by the property. diff --git a/docs/framework/wcf/feature-details/how-to-determine-the-discovery-version-of-a-probe-request.md b/docs/framework/wcf/feature-details/how-to-determine-the-discovery-version-of-a-probe-request.md index 3bba1ee5f4208..d1916ade301af 100644 --- a/docs/framework/wcf/feature-details/how-to-determine-the-discovery-version-of-a-probe-request.md +++ b/docs/framework/wcf/feature-details/how-to-determine-the-discovery-version-of-a-probe-request.md @@ -10,7 +10,7 @@ A discovery proxy may expose multiple discovery endpoints using different discov ## To Determine the Discovery Version of a Probe Request -In the method that responds to a Probe request (for example ) use the static property to search for a , as shown in the following code. +In the method that responds to a Probe request (for example ) use the static property to search for a , as shown in the following code. ```csharp DiscoveryOperationContextExtension doce = OperationContext.Current.Extensions.Find(); @@ -20,5 +20,5 @@ doce.DiscoveryVersion; ## See also -- +- - [Implementing a Discovery Proxy](implementing-a-discovery-proxy.md) diff --git a/docs/framework/wcf/feature-details/how-to-disable-encryption-of-digital-signatures.md b/docs/framework/wcf/feature-details/how-to-disable-encryption-of-digital-signatures.md index 368118b593a44..7425597dcd222 100644 --- a/docs/framework/wcf/feature-details/how-to-disable-encryption-of-digital-signatures.md +++ b/docs/framework/wcf/feature-details/how-to-disable-encryption-of-digital-signatures.md @@ -6,21 +6,21 @@ ms.assetid: fd174313-ad81-4dca-898a-016ccaff8187 --- # How to: Disable Encryption of Digital Signatures -By default, a message is signed and the signature is digitally encrypted. This is controlled by creating a custom binding with an instance of the or the and setting the `MessageProtectionOrder` property of either class to a enumeration value. The default is . This process consumes up to 30 percent more time than simply signing and encrypting based on the overall message size (the smaller the message, the greater the performance impact). Disabling encryption of the signature, however, might allow an attacker to guess the content of the message. This is possible because the signature element contains the hash code of the plain text of every signed part in the message. For example, although the message body is encrypted by default, the unencrypted signature contains the hash code of the message body before the encryption. If the set of possible values for the signed and encrypted part is small, an attacker might be able to deduce the contents by looking at the hash value. Encrypting the signature mitigates this attack vector. - - Therefore, disable encryption of the signature only when the value of the content is low or the set of possible content values is large and nondeterministic, and the performance gain is more important than mitigating the attack described above. - +By default, a message is signed and the signature is digitally encrypted. This is controlled by creating a custom binding with an instance of the or the and setting the `MessageProtectionOrder` property of either class to a enumeration value. The default is . This process consumes up to 30 percent more time than simply signing and encrypting based on the overall message size (the smaller the message, the greater the performance impact). Disabling encryption of the signature, however, might allow an attacker to guess the content of the message. This is possible because the signature element contains the hash code of the plain text of every signed part in the message. For example, although the message body is encrypted by default, the unencrypted signature contains the hash code of the message body before the encryption. If the set of possible values for the signed and encrypted part is small, an attacker might be able to deduce the contents by looking at the hash value. Encrypting the signature mitigates this attack vector. + + Therefore, disable encryption of the signature only when the value of the content is low or the set of possible content values is large and nondeterministic, and the performance gain is more important than mitigating the attack described above. + > [!NOTE] -> If there is nothing in the message that is encrypted, the signature element is not encrypted, even when the or property is set to . This behavior occurs even with system-provided bindings; all system-provided bindings have the message protection order set to `SignBeforeEncryptAndEncryptSignature`. However, the Web Services Description Language (WSDL) WCF generates will still contain the `` assertion. - -### To disable digital signing - -1. Create a . For more information, see [How to: Create a Custom Binding Using the SecurityBindingElement](how-to-create-a-custom-binding-using-the-securitybindingelement.md). - -2. Add either an or a to the binding collection. - -3. Set the property to , or set the property to . - +> If there is nothing in the message that is encrypted, the signature element is not encrypted, even when the or property is set to . This behavior occurs even with system-provided bindings; all system-provided bindings have the message protection order set to `SignBeforeEncryptAndEncryptSignature`. However, the Web Services Description Language (WSDL) WCF generates will still contain the `` assertion. + +### To disable digital signing + +1. Create a . For more information, see [How to: Create a Custom Binding Using the SecurityBindingElement](how-to-create-a-custom-binding-using-the-securitybindingelement.md). + +2. Add either an or a to the binding collection. + +3. Set the property to , or set the property to . + ## See also - [Security Capabilities with Custom Bindings](security-capabilities-with-custom-bindings.md) diff --git a/docs/framework/wcf/feature-details/how-to-dynamic-update.md b/docs/framework/wcf/feature-details/how-to-dynamic-update.md index 05dfc6fc038e6..95d6726ccdb25 100644 --- a/docs/framework/wcf/feature-details/how-to-dynamic-update.md +++ b/docs/framework/wcf/feature-details/how-to-dynamic-update.md @@ -14,7 +14,7 @@ This topic outlines the basic steps required to create and dynamically update th > [!NOTE] > Dynamic updates occur only in memory, and do not result in the modification of configuration files. - Both regularCalc and roundingCalc support the same operations of add, subtract, multiply and divide; however, roundingCalc rounds all calculations to the nearest integer value before returning. A configuration file is used to configure the service to route all messages to the regularCalc service. After the Routing Service has been started, is used to reconfigure the service to route messages to the roundingCalc service. + Both regularCalc and roundingCalc support the same operations of add, subtract, multiply and divide; however, roundingCalc rounds all calculations to the nearest integer value before returning. A configuration file is used to configure the service to route all messages to the regularCalc service. After the Routing Service has been started, is used to reconfigure the service to route messages to the roundingCalc service. ### Implement Initial Configuration @@ -75,7 +75,7 @@ This topic outlines the basic steps required to create and dynamically update th ## Implement Dynamic Configuration - Dynamic configuration of the Routing Service can only be performed in code by creating a new and using to replace the current configuration. For this example, the Routing Service is self-hosted within a console application. After the application has started, you can modify the routing configuration by entering ‘regular’ or ‘rounding’ at the console window to configure the destination endpoint that messages are routed to; regularCalc when ‘regular’ is entered, otherwise roundingCalc when ‘rounding’ is entered. + Dynamic configuration of the Routing Service can only be performed in code by creating a new and using to replace the current configuration. For this example, the Routing Service is self-hosted within a console application. After the application has started, you can modify the routing configuration by entering ‘regular’ or ‘rounding’ at the console window to configure the destination endpoint that messages are routed to; regularCalc when ‘regular’ is entered, otherwise roundingCalc when ‘rounding’ is entered. 1. The following `using` directives must be added in order to support the Routing Service. @@ -114,7 +114,7 @@ This topic outlines the basic steps required to create and dynamically update th } ``` -3. To dynamically update the routing configuration, a new routing configuration must be created. This must contain all endpoints, filters and filter tables that are required for the new routing configuration, as it will completely replace the existing routing configuration. In order to use the new routing configuration, you must invoke and pass the new configuration. +3. To dynamically update the routing configuration, a new routing configuration must be created. This must contain all endpoints, filters and filter tables that are required for the new routing configuration, as it will completely replace the existing routing configuration. In order to use the new routing configuration, you must invoke and pass the new configuration. Add the following code to the while loop defined previously to allow the service to be reconfigured based on user input. diff --git a/docs/framework/wcf/feature-details/how-to-enable-message-replay-detection.md b/docs/framework/wcf/feature-details/how-to-enable-message-replay-detection.md index 248e4c9af7c14..457c470d2a64b 100644 --- a/docs/framework/wcf/feature-details/how-to-enable-message-replay-detection.md +++ b/docs/framework/wcf/feature-details/how-to-enable-message-replay-detection.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Enable Message Replay Detection" title: "How to: Enable Message Replay Detection" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "WCF security" - "replay detection [WCF]" - "WCF, custom bindings" @@ -14,93 +14,93 @@ ms.assetid: 8b847e91-69a3-49e1-9e5f-0c455e50d804 --- # How to: Enable Message Replay Detection -A replay attack occurs when an attacker copies a stream of messages between two parties and replays the stream to one or more of the parties. Unless mitigated, the computers subject to the attack will process the stream as legitimate messages, resulting in a range of bad consequences, such as redundant orders of an item. - - For more information about message replay detection, see [Message Replay Detection](/previous-versions/msp-n-p/ff649371(v=pandp.10)). - - The following procedure demonstrates various properties that you can use to control replay detection using Windows Communication Foundation (WCF). - -### To control replay detection on the client using code - -1. Create a to use in a . For more information, see [How to: Create a Custom Binding Using the SecurityBindingElement](how-to-create-a-custom-binding-using-the-securitybindingelement.md). The following example uses a created with the of the class. - -2. Use the property to return a reference to the class and set any of the following properties, as appropriate: - - 1. `DetectReplay`. A Boolean value. This governs whether the client should detect replays from the server. The default is `true`. - - 2. `MaxClockSkew`. A value. Governs how much time skew the replay mechanism can tolerate between the client and the server. The security mechanism examines the time stamp sent and determines whether it was sent too far back in the past. The default is 5 minutes. - - 3. `ReplayWindow`. A `TimeSpan` value. This governs how long a message can live in the network after the server sends it (through intermediaries) before reaching the client. The client tracks the signatures of the messages sent within the latest `ReplayWindow` for the purposes of replay detection. - - 4. `ReplayCacheSize`. An integer value. The client stores the signatures of the message in a cache. This setting specifies how many signatures the cache can store. If the number of messages sent within the last replay window reaches the cache limit, new messages are rejected until the oldest cached signatures reach the time limit. The default is 500000. - -### To control replay detection on the service using code - -1. Create a to use in a . - -2. Use the property to return a reference to the class, and set the properties as described previously. - -### To control replay detection in configuration for the client or service - -1. Create a [\](../../configure-apps/file-schema/wcf/custombinding.md). - -2. Create a `` element. - -3. Create a [\](../../configure-apps/file-schema/wcf/localclientsettings-element.md) or [\](../../configure-apps/file-schema/wcf/localservicesettings-element.md). - -4. Set the following attribute values, as appropriate: `detectReplays`, `maxClockSkew`, `replayWindow`, and `replayCacheSize`. The following example sets the attributes of both a `` and a `` element: - - ```xml - - - - +A replay attack occurs when an attacker copies a stream of messages between two parties and replays the stream to one or more of the parties. Unless mitigated, the computers subject to the attack will process the stream as legitimate messages, resulting in a range of bad consequences, such as redundant orders of an item. + + For more information about message replay detection, see [Message Replay Detection](/previous-versions/msp-n-p/ff649371(v=pandp.10)). + + The following procedure demonstrates various properties that you can use to control replay detection using Windows Communication Foundation (WCF). + +### To control replay detection on the client using code + +1. Create a to use in a . For more information, see [How to: Create a Custom Binding Using the SecurityBindingElement](how-to-create-a-custom-binding-using-the-securitybindingelement.md). The following example uses a created with the of the class. + +2. Use the property to return a reference to the class and set any of the following properties, as appropriate: + + 1. `DetectReplay`. A Boolean value. This governs whether the client should detect replays from the server. The default is `true`. + + 2. `MaxClockSkew`. A value. Governs how much time skew the replay mechanism can tolerate between the client and the server. The security mechanism examines the time stamp sent and determines whether it was sent too far back in the past. The default is 5 minutes. + + 3. `ReplayWindow`. A `TimeSpan` value. This governs how long a message can live in the network after the server sends it (through intermediaries) before reaching the client. The client tracks the signatures of the messages sent within the latest `ReplayWindow` for the purposes of replay detection. + + 4. `ReplayCacheSize`. An integer value. The client stores the signatures of the message in a cache. This setting specifies how many signatures the cache can store. If the number of messages sent within the last replay window reaches the cache limit, new messages are rejected until the oldest cached signatures reach the time limit. The default is 500000. + +### To control replay detection on the service using code + +1. Create a to use in a . + +2. Use the property to return a reference to the class, and set the properties as described previously. + +### To control replay detection in configuration for the client or service + +1. Create a [\](../../configure-apps/file-schema/wcf/custombinding.md). + +2. Create a `` element. + +3. Create a [\](../../configure-apps/file-schema/wcf/localclientsettings-element.md) or [\](../../configure-apps/file-schema/wcf/localservicesettings-element.md). + +4. Set the following attribute values, as appropriate: `detectReplays`, `maxClockSkew`, `replayWindow`, and `replayCacheSize`. The following example sets the attributes of both a `` and a `` element: + + ```xml + + + + + maxClockSkew="00:03:00" + replayWindow="00:03:00" /> - - - - - - ``` - -## Example - - The following example creates a using the method, and sets the replay properties of the binding. - + maxClockSkew="00:03:00" + replayWindow="00:03:00" /> + + + + + + ``` + +## Example + + The following example creates a using the method, and sets the replay properties of the binding. + [!code-csharp[c_ReplayDetection#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_replaydetection/cs/source.cs#1)] - [!code-vb[c_ReplayDetection#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_replaydetection/vb/source.vb#1)] - -## Scope of Replay: Message Security Only - - Note that the following procedures apply only to Message security mode. For Transport and Transport with Message Credential modes, the transport mechanisms detect replays. - -## Secure Conversation Notes - - For bindings that enable secure conversations, you can adjust these settings both for the application channel as well as for the secure conversation bootstrap binding. For example, you can turn off replays for the application channel but enable them for the bootstrap channel that establishes the secure conversation. - - If you do not use secure conversation sessions, replay detection does not guarantee detecting replays in server farm scenarios and when the process is recycled. This applies to the following system-provided bindings: - -- . - -- with the property set to `false`. - -## Compiling the Code - -- The following namespaces are required to compile the code: - -- - -- - -- - + [!code-vb[c_ReplayDetection#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_replaydetection/vb/source.vb#1)] + +## Scope of Replay: Message Security Only + + Note that the following procedures apply only to Message security mode. For Transport and Transport with Message Credential modes, the transport mechanisms detect replays. + +## Secure Conversation Notes + + For bindings that enable secure conversations, you can adjust these settings both for the application channel as well as for the secure conversation bootstrap binding. For example, you can turn off replays for the application channel but enable them for the bootstrap channel that establishes the secure conversation. + + If you do not use secure conversation sessions, replay detection does not guarantee detecting replays in server farm scenarios and when the process is recycled. This applies to the following system-provided bindings: + +- . + +- with the property set to `false`. + +## Compiling the Code + +- The following namespaces are required to compile the code: + +- + +- + +- + ## See also - diff --git a/docs/framework/wcf/feature-details/how-to-export-metadata-from-service-endpoints.md b/docs/framework/wcf/feature-details/how-to-export-metadata-from-service-endpoints.md index ba8d3c596e9f9..b0a70770eb848 100644 --- a/docs/framework/wcf/feature-details/how-to-export-metadata-from-service-endpoints.md +++ b/docs/framework/wcf/feature-details/how-to-export-metadata-from-service-endpoints.md @@ -2,57 +2,57 @@ description: "Learn more about: How to: Export Metadata from Service Endpoints" title: "How to: Export Metadata from Service Endpoints" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: b6c4dfd0-f270-43ec-961a-e16eb6af2f2c --- # How to: Export Metadata from Service Endpoints -This topic explains how to export metadata from service endpoints. - -### To export metadata from service endpoints - -1. Create a new Visual Studio Console App Project. Add the code shown in the following steps in the generated Program.cs file within the main() method. - -2. Create a . - +This topic explains how to export metadata from service endpoints. + +### To export metadata from service endpoints + +1. Create a new Visual Studio Console App Project. Add the code shown in the following steps in the generated Program.cs file within the main() method. + +2. Create a . + [!code-csharp[S_UEWsdlExporter#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_uewsdlexporter/cs/program.cs#1)] - [!code-vb[S_UEWsdlExporter#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdlexporter/vb/program.vb#1)] - -3. Set the property to one of the values from the enumeration. This sample sets the value to which corresponds to WS-Policy 1.5. - + [!code-vb[S_UEWsdlExporter#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdlexporter/vb/program.vb#1)] + +3. Set the property to one of the values from the enumeration. This sample sets the value to which corresponds to WS-Policy 1.5. + [!code-csharp[S_UEWsdlExporter#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_uewsdlexporter/cs/program.cs#2)] - [!code-vb[S_UEWsdlExporter#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdlexporter/vb/program.vb#2)] - -4. Create an array of objects. - + [!code-vb[S_UEWsdlExporter#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdlexporter/vb/program.vb#2)] + +4. Create an array of objects. + [!code-csharp[S_UEWsdlExporter#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_uewsdlexporter/cs/program.cs#3)] - [!code-vb[S_UEWsdlExporter#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdlexporter/vb/program.vb#3)] - -5. Export metadata for each service endpoint. - + [!code-vb[S_UEWsdlExporter#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdlexporter/vb/program.vb#3)] + +5. Export metadata for each service endpoint. + [!code-csharp[S_UEWsdlExporter#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_uewsdlexporter/cs/program.cs#4)] - [!code-vb[S_UEWsdlExporter#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdlexporter/vb/program.vb#4)] - -6. Check to make sure no errors occurred during the export process and retrieve the metadata. - + [!code-vb[S_UEWsdlExporter#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdlexporter/vb/program.vb#4)] + +6. Check to make sure no errors occurred during the export process and retrieve the metadata. + [!code-csharp[S_UEWsdlExporter#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_uewsdlexporter/cs/program.cs#5)] - [!code-vb[S_UEWsdlExporter#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdlexporter/vb/program.vb#5)] - -7. You can now use the metadata, such as write it to a file by calling the method. - -## Example - - The following is the full code listing for this example. - + [!code-vb[S_UEWsdlExporter#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdlexporter/vb/program.vb#5)] + +7. You can now use the metadata, such as write it to a file by calling the method. + +## Example + + The following is the full code listing for this example. + [!code-csharp[S_UEWsdlExporter#0](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_uewsdlexporter/cs/program.cs#0)] - [!code-vb[S_UEWsdlExporter#0](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdlexporter/vb/program.vb#0)] - -## Compiling the Code + [!code-vb[S_UEWsdlExporter#0](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdlexporter/vb/program.vb#0)] + +## Compiling the Code + + When compiling Program.cs reference System.ServiceModel.dll. - When compiling Program.cs reference System.ServiceModel.dll. - ## See also - [Metadata Architecture Overview](metadata-architecture-overview.md) diff --git a/docs/framework/wcf/feature-details/how-to-expose-a-contract-to-soap-and-web-clients.md b/docs/framework/wcf/feature-details/how-to-expose-a-contract-to-soap-and-web-clients.md index 382d8f5fbdac8..178ed260284e6 100644 --- a/docs/framework/wcf/feature-details/how-to-expose-a-contract-to-soap-and-web-clients.md +++ b/docs/framework/wcf/feature-details/how-to-expose-a-contract-to-soap-and-web-clients.md @@ -2,7 +2,7 @@ title: "How to: Expose a Contract to SOAP and Web Clients" description: Learn how to make a WFC server endpoint available to both SOAP and non-SOAP clients. By default, endpoints are available only to SOAP clients. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: bb765a48-12f2-430d-a54d-6f0c20f2a23a @@ -54,7 +54,7 @@ By default, Windows Communication Foundation (WCF) makes endpoints available onl ## To call service operations on the Web endpoint in code -1. Create an instance of within a `using` block, as shown in the following code. +1. Create an instance of within a `using` block, as shown in the following code. [!code-csharp[htSoapWeb#6](../../../../samples/snippets/csharp/VS_Snippets_CFX/htsoapweb/cs/program.cs#6)] [!code-vb[htSoapWeb#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htsoapweb/vb/program.vb#6)] diff --git a/docs/framework/wcf/feature-details/how-to-host-a-wcf-service-in-a-managed-windows-service.md b/docs/framework/wcf/feature-details/how-to-host-a-wcf-service-in-a-managed-windows-service.md index 7b4c6f59c49c4..854c2d46a6d67 100644 --- a/docs/framework/wcf/feature-details/how-to-host-a-wcf-service-in-a-managed-windows-service.md +++ b/docs/framework/wcf/feature-details/how-to-host-a-wcf-service-in-a-managed-windows-service.md @@ -54,7 +54,7 @@ The service code includes a service implementation of the service contract, a Wi [!code-csharp[c_HowTo_HostInNTService#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howto_hostinntservice/cs/service.cs#4)] [!code-vb[c_HowTo_HostInNTService#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_hostinntservice/vb/service.vb#4)] -10. Override the method closing the as shown in the following code. +10. Override the method closing the as shown in the following code. [!code-csharp[c_HowTo_HostInNTService#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howto_hostinntservice/cs/service.cs#5)] [!code-vb[c_HowTo_HostInNTService#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howto_hostinntservice/vb/service.vb#5)] diff --git a/docs/framework/wcf/feature-details/how-to-implement-a-discovery-proxy.md b/docs/framework/wcf/feature-details/how-to-implement-a-discovery-proxy.md index 18c60f43abbdd..fc131d3d1708b 100644 --- a/docs/framework/wcf/feature-details/how-to-implement-a-discovery-proxy.md +++ b/docs/framework/wcf/feature-details/how-to-implement-a-discovery-proxy.md @@ -221,7 +221,7 @@ This topic explains how to implement a discovery proxy. For more information abo ### To define the methods that implement the discovery proxy functionality -1. Override the method. This method is called when the discovery proxy receives an online announcement message. +1. Override the method. This method is called when the discovery proxy receives an online announcement message. ```csharp // OnBeginOnlineAnnouncement method is called when a Hello message is received by the Proxy @@ -232,7 +232,7 @@ This topic explains how to implement a discovery proxy. For more information abo } ``` -2. Override the method. This method is called when the discovery proxy finishes processing an announcement message. +2. Override the method. This method is called when the discovery proxy finishes processing an announcement message. ```csharp protected override void OnEndOnlineAnnouncement(IAsyncResult result) @@ -241,7 +241,7 @@ This topic explains how to implement a discovery proxy. For more information abo } ``` -3. Override the method. This method is called with the discovery proxy receives an offline announcement message. +3. Override the method. This method is called with the discovery proxy receives an offline announcement message. ```csharp // OnBeginOfflineAnnouncement method is called when a Bye message is received by the Proxy @@ -252,7 +252,7 @@ This topic explains how to implement a discovery proxy. For more information abo } ``` -4. Override the method. This method is called when the discovery proxy finishes processing an offline announcement message. +4. Override the method. This method is called when the discovery proxy finishes processing an offline announcement message. ```csharp protected override void OnEndOfflineAnnouncement(IAsyncResult result) @@ -261,7 +261,7 @@ This topic explains how to implement a discovery proxy. For more information abo } ``` -5. Override the method. This method is called when the discovery proxy receives a find request. +5. Override the method. This method is called when the discovery proxy receives a find request. ```csharp // OnBeginFind method is called when a Probe request message is received by the Proxy @@ -280,7 +280,7 @@ This topic explains how to implement a discovery proxy. For more information abo } ``` -6. Override the method. This method is called when the discovery proxy finishes processing a find request. +6. Override the method. This method is called when the discovery proxy finishes processing a find request. ```csharp protected override void OnEndFind(IAsyncResult result) @@ -289,7 +289,7 @@ This topic explains how to implement a discovery proxy. For more information abo } ``` -7. Override the method. This method is called when the discovery proxy receives a resolve message. +7. Override the method. This method is called when the discovery proxy receives a resolve message. ```csharp // OnBeginFind method is called when a Resolve request message is received by the Proxy @@ -306,7 +306,7 @@ This topic explains how to implement a discovery proxy. For more information abo } ``` -8. Override the method. This method is called when the discovery proxy finishes processing a resolve message. +8. Override the method. This method is called when the discovery proxy finishes processing a resolve message. ```csharp protected override EndpointDiscoveryMetadata OnEndResolve(IAsyncResult result) @@ -315,7 +315,7 @@ This topic explains how to implement a discovery proxy. For more information abo } ``` -The OnBegin.. / OnEnd.. methods provide the logic for the subsequent discovery operations. For example the and methods implement the find logic for discovery proxy. When the discovery proxy receives a probe message these methods are executed to send a response back to the client. You may modify the find logic as you wish, for example you can incorporate custom scope matching by algorithms or application specific XML metadata parsing as part of your find operation. +The OnBegin.. / OnEnd.. methods provide the logic for the subsequent discovery operations. For example the and methods implement the find logic for discovery proxy. When the discovery proxy receives a probe message these methods are executed to send a response back to the client. You may modify the find logic as you wish, for example you can incorporate custom scope matching by algorithms or application specific XML metadata parsing as part of your find operation. ### To implement the AsyncResult class diff --git a/docs/framework/wcf/feature-details/how-to-import-metadata-into-service-endpoints.md b/docs/framework/wcf/feature-details/how-to-import-metadata-into-service-endpoints.md index 364cc61a0ef27..100cfa4af5e52 100644 --- a/docs/framework/wcf/feature-details/how-to-import-metadata-into-service-endpoints.md +++ b/docs/framework/wcf/feature-details/how-to-import-metadata-into-service-endpoints.md @@ -6,33 +6,33 @@ ms.assetid: b69dbe20-92a1-4911-89d8-ffbc3dad4663 --- # How to: Import Metadata into Service Endpoints -This topic explains how to import metadata into a collection of service endpoints and use the service defined in the [Getting Started](../samples/getting-started-sample.md). This topic show how to create a client application that imports metadata from the service and then calls the `Add` method on the service. - -### To import metadata into service endpoints - -1. Declare an object and initialize it with the Uniform Resource Identifier (URI) for the metadata exchange (MEX) address of the service. - - [!code-csharp[UE_ImportMetadata#0](../../../../samples/snippets/csharp/VS_Snippets_CFX/ue_importmetadata/cs/client.cs#0)] - -2. Create a , passing in the MEX address, and call . This retrieves the metadata from the service. - - [!code-csharp[UE_ImportMetadata#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/ue_importmetadata/cs/client.cs#1)] - -3. Create a , passing in the metadata previously retrieved, and call . This generates a collection of objects. You could also call or , depending upon your needs. - - [!code-csharp[UE_ImportMetadata#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/ue_importmetadata/cs/client.cs#2)] - +This topic explains how to import metadata into a collection of service endpoints and use the service defined in the [Getting Started](../samples/getting-started-sample.md). This topic show how to create a client application that imports metadata from the service and then calls the `Add` method on the service. + +### To import metadata into service endpoints + +1. Declare an object and initialize it with the Uniform Resource Identifier (URI) for the metadata exchange (MEX) address of the service. + + [!code-csharp[UE_ImportMetadata#0](../../../../samples/snippets/csharp/VS_Snippets_CFX/ue_importmetadata/cs/client.cs#0)] + +2. Create a , passing in the MEX address, and call . This retrieves the metadata from the service. + + [!code-csharp[UE_ImportMetadata#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/ue_importmetadata/cs/client.cs#1)] + +3. Create a , passing in the metadata previously retrieved, and call . This generates a collection of objects. You could also call or , depending upon your needs. + + [!code-csharp[UE_ImportMetadata#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/ue_importmetadata/cs/client.cs#2)] + > [!NOTE] - > After you have imported the metadata, you will not be able to create a client channel or export the metadata. This is because no type information is available at this point. Type information is required to actually interact with the service or export metadata. To generate the type information, you need to generate code, shown in steps 4 and 5. Alternatively, you could use the helper class. For more information, see [How to: Use MetadataResolver to Obtain Binding Metadata Dynamically](how-to-use-metadataresolver-to-obtain-binding-metadata-dynamically.md). - -4. Generate type information for each contract. - - [!code-csharp[UE_ImportMetadata#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/ue_importmetadata/cs/client.cs#3)] - -5. Now you can use this information. The following sample generates C# source code. - - [!code-csharp[UE_ImportMetadata#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/ue_importmetadata/cs/client.cs#4)] - + > After you have imported the metadata, you will not be able to create a client channel or export the metadata. This is because no type information is available at this point. Type information is required to actually interact with the service or export metadata. To generate the type information, you need to generate code, shown in steps 4 and 5. Alternatively, you could use the helper class. For more information, see [How to: Use MetadataResolver to Obtain Binding Metadata Dynamically](how-to-use-metadataresolver-to-obtain-binding-metadata-dynamically.md). + +4. Generate type information for each contract. + + [!code-csharp[UE_ImportMetadata#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/ue_importmetadata/cs/client.cs#3)] + +5. Now you can use this information. The following sample generates C# source code. + + [!code-csharp[UE_ImportMetadata#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/ue_importmetadata/cs/client.cs#4)] + ## See also - [Metadata](metadata.md) diff --git a/docs/framework/wcf/feature-details/how-to-migrate-ajax-enabled-aspnet-web-services-to-wcf.md b/docs/framework/wcf/feature-details/how-to-migrate-ajax-enabled-aspnet-web-services-to-wcf.md index f4f241192678d..7957ed4973e12 100644 --- a/docs/framework/wcf/feature-details/how-to-migrate-ajax-enabled-aspnet-web-services-to-wcf.md +++ b/docs/framework/wcf/feature-details/how-to-migrate-ajax-enabled-aspnet-web-services-to-wcf.md @@ -83,7 +83,7 @@ This topic outlines procedures to migrate a basic ASP.NET AJAX service to an equ { … } ``` -7. Add the to the `HelloWorld` operation and set the property to return . Note that, if not set, the default return type is . +7. Add the to the `HelloWorld` operation and set the property to return . Note that, if not set, the default return type is . ```csharp [OperationContract] diff --git a/docs/framework/wcf/feature-details/how-to-programmatically-add-discoverability-to-a-wcf-service-and-client.md b/docs/framework/wcf/feature-details/how-to-programmatically-add-discoverability-to-a-wcf-service-and-client.md index 4d9c57ab805f0..efed61e492f71 100644 --- a/docs/framework/wcf/feature-details/how-to-programmatically-add-discoverability-to-a-wcf-service-and-client.md +++ b/docs/framework/wcf/feature-details/how-to-programmatically-add-discoverability-to-a-wcf-service-and-client.md @@ -90,14 +90,14 @@ This topic explains how to make a Windows Communication Foundation (WCF) service This tells WCF that the class should use the standard UDP discovery endpoint to send and receive discovery messages. -8. On the next line, call the method and specify a instance that contains the service contract you want to search for. In this case, specify `ICalculator`. +8. On the next line, call the method and specify a instance that contains the service contract you want to search for. In this case, specify `ICalculator`. ```csharp // Find ICalculatorService endpoints FindResponse findResponse = discoveryClient.Find(new FindCriteria(typeof(ICalculator))); ``` -9. After the call to , check to see if there is at least one matching service and return the of the first matching service. Otherwise return `null`. +9. After the call to , check to see if there is at least one matching service and return the of the first matching service. Otherwise return `null`. ```csharp if (findResponse.Endpoints.Count > 0) diff --git a/docs/framework/wcf/feature-details/how-to-publish-metadata-for-a-service-using-code.md b/docs/framework/wcf/feature-details/how-to-publish-metadata-for-a-service-using-code.md index 13ead1c4d9351..2c046bab34e0e 100644 --- a/docs/framework/wcf/feature-details/how-to-publish-metadata-for-a-service-using-code.md +++ b/docs/framework/wcf/feature-details/how-to-publish-metadata-for-a-service-using-code.md @@ -2,87 +2,87 @@ description: "Learn more about: How to: Publish Metadata for a Service Using Code" title: "How to: Publish Metadata for a Service Using Code" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 51407e6d-4d87-42d5-be7c-9887b8652006 --- # How to: Publish Metadata for a Service Using Code -This is one of two how-to topics that discuss publishing metadata for a Windows Communication Foundation (WCF) service. There are two ways to specify how a service should publish metadata, using a configuration file and using code. This topic shows how to publish metadata for a service using a code. - +This is one of two how-to topics that discuss publishing metadata for a Windows Communication Foundation (WCF) service. There are two ways to specify how a service should publish metadata, using a configuration file and using code. This topic shows how to publish metadata for a service using a code. + > [!CAUTION] -> This topic shows how to publish metadata in an unsecure manner. Any client can retrieve the metadata from the service. If you require your service to publish metadata in a secure manner. see [Custom Secure Metadata Endpoint](../samples/custom-secure-metadata-endpoint.md). - - For more information about publishing metadata in a configuration file, see [How to: Publish Metadata for a Service Using a Configuration File](how-to-publish-metadata-for-a-service-using-a-configuration-file.md). Publishing metadata allows clients to retrieve the metadata using a WS-Transfer GET request or an HTTP/GET request using the `?wsdl` query string. To be sure that the code is working you must create a basic WCF service. A basic self-hosted service is provided in the following code. - +> This topic shows how to publish metadata in an unsecure manner. Any client can retrieve the metadata from the service. If you require your service to publish metadata in a secure manner. see [Custom Secure Metadata Endpoint](../samples/custom-secure-metadata-endpoint.md). + + For more information about publishing metadata in a configuration file, see [How to: Publish Metadata for a Service Using a Configuration File](how-to-publish-metadata-for-a-service-using-a-configuration-file.md). Publishing metadata allows clients to retrieve the metadata using a WS-Transfer GET request or an HTTP/GET request using the `?wsdl` query string. To be sure that the code is working you must create a basic WCF service. A basic self-hosted service is provided in the following code. + [!code-csharp[htPublishMetadataCode#0](../../../../samples/snippets/csharp/VS_Snippets_CFX/htpublishmetadatacode/cs/program.cs#0)] - [!code-vb[htPublishMetadataCode#0](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#0)] - -### To publish metadata in code - -1. Within the main method of a console application, instantiate a object by passing in the service type and the base address. - + [!code-vb[htPublishMetadataCode#0](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#0)] + +### To publish metadata in code + +1. Within the main method of a console application, instantiate a object by passing in the service type and the base address. + [!code-csharp[htPublishMetadataCode#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/htpublishmetadatacode/cs/program.cs#1)] - [!code-vb[htPublishMetadataCode#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#1)] - -2. Create a try block immediately below the code for step 1, this catches any exceptions that get thrown while the service is running. - + [!code-vb[htPublishMetadataCode#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#1)] + +2. Create a try block immediately below the code for step 1, this catches any exceptions that get thrown while the service is running. + [!code-csharp[htPublishMetadataCode#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/htpublishmetadatacode/cs/program.cs#2)] - [!code-vb[htPublishMetadataCode#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#2)] - + [!code-vb[htPublishMetadataCode#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#2)] + [!code-csharp[htPublishMetadataCode#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/htpublishmetadatacode/cs/program.cs#3)] - [!code-vb[htPublishMetadataCode#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#3)] - -3. Check to see whether the service host already contains a , if not, create a new instance. - + [!code-vb[htPublishMetadataCode#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#3)] + +3. Check to see whether the service host already contains a , if not, create a new instance. + [!code-csharp[htPublishMetadataCode#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/htpublishmetadatacode/cs/program.cs#4)] - [!code-vb[htPublishMetadataCode#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#4)] - -4. Set the property to `true.` - + [!code-vb[htPublishMetadataCode#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#4)] + +4. Set the property to `true.` + [!code-csharp[htPublishMetadataCode#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/htpublishmetadatacode/cs/program.cs#5)] - [!code-vb[htPublishMetadataCode#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#5)] - -5. The contains a property. The contains a property. Set the value of the property to . The property can also be set to . When set to the metadata exporter generates policy information with the metadata that" conforms to WS-Policy 1.5. When set to the metadata exporter generates policy information that conforms to WS-Policy 1.2. - + [!code-vb[htPublishMetadataCode#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#5)] + +5. The contains a property. The contains a property. Set the value of the property to . The property can also be set to . When set to the metadata exporter generates policy information with the metadata that" conforms to WS-Policy 1.5. When set to the metadata exporter generates policy information that conforms to WS-Policy 1.2. + [!code-csharp[htPublishMetadataCode#6](../../../../samples/snippets/csharp/VS_Snippets_CFX/htpublishmetadatacode/cs/program.cs#6)] - [!code-vb[htPublishMetadataCode#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#6)] - -6. Add the instance to the service host's behaviors collection. - + [!code-vb[htPublishMetadataCode#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#6)] + +6. Add the instance to the service host's behaviors collection. + [!code-csharp[htPublishMetadataCode#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/htpublishmetadatacode/cs/program.cs#7)] - [!code-vb[htPublishMetadataCode#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#7)] - -7. Add the metadata exchange endpoint to the service host. - + [!code-vb[htPublishMetadataCode#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#7)] + +7. Add the metadata exchange endpoint to the service host. + [!code-csharp[htPublishMetadataCode#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/htpublishmetadatacode/cs/program.cs#8)] - [!code-vb[htPublishMetadataCode#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#8)] - -8. Add an application endpoint to the service host. - + [!code-vb[htPublishMetadataCode#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#8)] + +8. Add an application endpoint to the service host. + [!code-csharp[htPublishMetadataCode#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/htpublishmetadatacode/cs/program.cs#9)] - [!code-vb[htPublishMetadataCode#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#9)] - + [!code-vb[htPublishMetadataCode#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#9)] + > [!NOTE] - > If you do not add any endpoints to the service, the runtime adds default endpoints for you. In this example, because the service has a set to `true`, the service has publishing metadata enabled. For more information about default endpoints, see [Simplified Configuration](../simplified-configuration.md) and [Simplified Configuration for WCF Services](../samples/simplified-configuration-for-wcf-services.md). - -9. Open the service host and wait for incoming calls. When the user presses ENTER, close the service host. - + > If you do not add any endpoints to the service, the runtime adds default endpoints for you. In this example, because the service has a set to `true`, the service has publishing metadata enabled. For more information about default endpoints, see [Simplified Configuration](../simplified-configuration.md) and [Simplified Configuration for WCF Services](../samples/simplified-configuration-for-wcf-services.md). + +9. Open the service host and wait for incoming calls. When the user presses ENTER, close the service host. + [!code-csharp[htPublishMetadataCode#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/htpublishmetadatacode/cs/program.cs#10)] - [!code-vb[htPublishMetadataCode#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#10)] - -10. Build and run the console application. - -11. Browse to the base address of the service (`http://localhost:8001/MetadataSample` in this sample) and verify that the metadata publishing is turned on. You should see a Web page displayed that says "Simple Service" at the top and immediately below "You have created a service." If not, a message at the top of the resulting page displays: "Metadata publishing for this service is currently disabled." - -## Example - - The following code example shows the implementation of a basic WCF service that publishes metadata for the service in code. - + [!code-vb[htPublishMetadataCode#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#10)] + +10. Build and run the console application. + +11. Browse to the base address of the service (`http://localhost:8001/MetadataSample` in this sample) and verify that the metadata publishing is turned on. You should see a Web page displayed that says "Simple Service" at the top and immediately below "You have created a service." If not, a message at the top of the resulting page displays: "Metadata publishing for this service is currently disabled." + +## Example + + The following code example shows the implementation of a basic WCF service that publishes metadata for the service in code. + [!code-csharp[htPublishMetadataCode#11](../../../../samples/snippets/csharp/VS_Snippets_CFX/htpublishmetadatacode/cs/program.cs#11)] - [!code-vb[htPublishMetadataCode#11](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#11)] - + [!code-vb[htPublishMetadataCode#11](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/htpublishmetadatacode/vb/program.vb#11)] + ## See also - [How to: Host a WCF Service in a Managed Application](../how-to-host-a-wcf-service-in-a-managed-application.md) diff --git a/docs/framework/wcf/feature-details/how-to-retrieve-metadata-and-implement-a-compliant-service.md b/docs/framework/wcf/feature-details/how-to-retrieve-metadata-and-implement-a-compliant-service.md index 2ac1b23a4d247..c7e943ec2d083 100644 --- a/docs/framework/wcf/feature-details/how-to-retrieve-metadata-and-implement-a-compliant-service.md +++ b/docs/framework/wcf/feature-details/how-to-retrieve-metadata-and-implement-a-compliant-service.md @@ -6,48 +6,48 @@ ms.assetid: f6f3a2b9-c8aa-4b0b-832c-ec2927bf1163 --- # How to: Retrieve Metadata and Implement a Compliant Service -Often, the same person does not design and implement services. In environments where interoperating applications are important, contracts can be designed or described in Web Services Description Language (WSDL) and a developer must implement a service that complies with the provided contract. You may also want to migrate an existing service to Windows Communication Foundation (WCF) but preserve the wire format. In addition, duplex contracts require callers to implement a callback contract as well. - - In these cases, you must use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) (or an equivalent tool) to generate a service contract interface in a managed language that you can implement to fulfill the requirements of the contract. Typically the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) is used to acquire a service contract that is used with a channel factory or a WCF client type as well as with a client configuration file that sets up the correct binding and address. To use the generated configuration file, you must change it into a service configuration file. You may also need to modify the service contract. - -### To retrieve data and implement a compliant service - -1. Use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) against metadata files or a metadata endpoint to generate a code file. - -2. Search for the portion of the output code file that contains the interface of interest (in case there is more than one) that is marked with the attribute. The following code example shows the two interfaces generated by [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). The first (`ISampleService`) is the service contract interface that you implement to create a compliant service. The second (`ISampleServiceChannel`) is a helper interface for client use that extends both the service contract interface and and is for use in a client application. - - [!code-csharp[ClientProxyCodeSample#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/clientproxycodesample/cs/proxycode.cs#2)] - -3. If the WSDL does not specify a reply action for all of the operations, the generated operation contracts may have the property set to the wildcard character (*). Remove this property setting. Otherwise, when you implement the service contract metadata, the metadata cannot be exported for those operations. - -4. Implement the interface on a class and host the service. For an example, see [How to: Implement a Service Contract](../how-to-implement-a-wcf-contract.md), or see a simple implementation below in the Example section. - -5. In the client configuration file that the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) generates, change the [\](../../configure-apps/file-schema/wcf/client.md) configuration section to a [\](../../configure-apps/file-schema/wcf/services.md) configuration section. (For an example of a generated client application configuration file, see the following "Example" section.) - -6. Within the [\](../../configure-apps/file-schema/wcf/services.md) configuration section, create a `name` attribute in the [\](../../configure-apps/file-schema/wcf/services.md) configuration section for your service implementation. - -7. Set the service `name` attribute to the configuration name for your service implementation. - -8. Add the endpoint configuration elements that use the implemented service contract to the service configuration section. - -## Example - - The following code example shows the majority of a code file generated by running the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) against metadata files. - - The following code shows: - -- The service contract interface that, when implemented, complies with the contract requirements (`ISampleService`). - -- The helper interface for client use that extends both the service contract interface and and is for use in a client application (`ISampleServiceChannel`). - -- The helper class that extends and is for use in a client application (`SampleServiceClient`). - -- The configuration file generated from the service. - -- A simple `ISampleService` service implementation. - -- A conversion of the client-side configuration file to a service-side version. - +Often, the same person does not design and implement services. In environments where interoperating applications are important, contracts can be designed or described in Web Services Description Language (WSDL) and a developer must implement a service that complies with the provided contract. You may also want to migrate an existing service to Windows Communication Foundation (WCF) but preserve the wire format. In addition, duplex contracts require callers to implement a callback contract as well. + + In these cases, you must use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) (or an equivalent tool) to generate a service contract interface in a managed language that you can implement to fulfill the requirements of the contract. Typically the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) is used to acquire a service contract that is used with a channel factory or a WCF client type as well as with a client configuration file that sets up the correct binding and address. To use the generated configuration file, you must change it into a service configuration file. You may also need to modify the service contract. + +### To retrieve data and implement a compliant service + +1. Use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) against metadata files or a metadata endpoint to generate a code file. + +2. Search for the portion of the output code file that contains the interface of interest (in case there is more than one) that is marked with the attribute. The following code example shows the two interfaces generated by [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). The first (`ISampleService`) is the service contract interface that you implement to create a compliant service. The second (`ISampleServiceChannel`) is a helper interface for client use that extends both the service contract interface and and is for use in a client application. + + [!code-csharp[ClientProxyCodeSample#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/clientproxycodesample/cs/proxycode.cs#2)] + +3. If the WSDL does not specify a reply action for all of the operations, the generated operation contracts may have the property set to the wildcard character (*). Remove this property setting. Otherwise, when you implement the service contract metadata, the metadata cannot be exported for those operations. + +4. Implement the interface on a class and host the service. For an example, see [How to: Implement a Service Contract](../how-to-implement-a-wcf-contract.md), or see a simple implementation below in the Example section. + +5. In the client configuration file that the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) generates, change the [\](../../configure-apps/file-schema/wcf/client.md) configuration section to a [\](../../configure-apps/file-schema/wcf/services.md) configuration section. (For an example of a generated client application configuration file, see the following "Example" section.) + +6. Within the [\](../../configure-apps/file-schema/wcf/services.md) configuration section, create a `name` attribute in the [\](../../configure-apps/file-schema/wcf/services.md) configuration section for your service implementation. + +7. Set the service `name` attribute to the configuration name for your service implementation. + +8. Add the endpoint configuration elements that use the implemented service contract to the service configuration section. + +## Example + + The following code example shows the majority of a code file generated by running the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) against metadata files. + + The following code shows: + +- The service contract interface that, when implemented, complies with the contract requirements (`ISampleService`). + +- The helper interface for client use that extends both the service contract interface and and is for use in a client application (`ISampleServiceChannel`). + +- The helper class that extends and is for use in a client application (`SampleServiceClient`). + +- The configuration file generated from the service. + +- A simple `ISampleService` service implementation. + +- A conversion of the client-side configuration file to a service-side version. + [!code-csharp[ClientProxyCodeSample#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/clientproxycodesample/cs/proxycode.cs#1)] [!code-xml[ClientProxyCodeSample#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/clientproxycodesample/cs/client.exe.config#10)] @@ -55,7 +55,7 @@ Often, the same person does not design and implement services. In environments w [!code-csharp[ClientProxyCodeSample#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/clientproxycodesample/cs/hostapplication.cs#5)] [!code-xml[ClientProxyCodeSample#20](../../../../samples/snippets/csharp/VS_Snippets_CFX/clientproxycodesample/cs/hostapplication.exe.config#20)] - + ## See also - [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) diff --git a/docs/framework/wcf/feature-details/how-to-retrieve-the-thumbprint-of-a-certificate.md b/docs/framework/wcf/feature-details/how-to-retrieve-the-thumbprint-of-a-certificate.md index f069eebfbacef..c4128e4c11eaf 100644 --- a/docs/framework/wcf/feature-details/how-to-retrieve-the-thumbprint-of-a-certificate.md +++ b/docs/framework/wcf/feature-details/how-to-retrieve-the-thumbprint-of-a-certificate.md @@ -2,42 +2,42 @@ title: "How to: Retrieve the Thumbprint of a Certificate" description: Learn how to specify claims found in an X.509 certificate, which is necessary when developing a WCF application that uses certificates for authentication. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "certificates [WCF], retrieving thumbprint" ms.assetid: da3101aa-78cd-4c34-9652-d1f24777eeab --- # How to: Retrieve the Thumbprint of a Certificate -When writing a Windows Communication Foundation (WCF) application that uses an X.509 certificate for authentication, it is often necessary to specify claims found in the certificate. For example, you must supply a thumbprint claim when using the enumeration in the method. Finding the claim value requires two steps. First, open the Microsoft Management Console (MMC) snap-in for certificates. (See [How to: View Certificates with the MMC Snap-in](how-to-view-certificates-with-the-mmc-snap-in.md).) Second, as described here, find an appropriate certificate and copy its thumbprint (or other claim values). - - If you are using a certificate for service authentication, it is important to note the value of the **Issued To** column (the first column in the console). When using Secure Sockets Layer (SSL) as a transport security, one of the first checks done is to compare the base address Uniform Resource Identifier (URI) of a service to the **Issued To** value. The values must match or the authentication process is halted. - - You can also use the PowerShell New-SelfSignedCertificate cmdlet to create temporary certificates for use only during development. By default, however, such a certificate is not issued by a certification authority and is unusable for production purposes. For more information, see [How to: Create Temporary Certificates for Use During Development](how-to-create-temporary-certificates-for-use-during-development.md). - -### To retrieve a certificate's thumbprint - -1. Open the Microsoft Management Console (MMC) snap-in for certificates. (See [How to: View Certificates with the MMC Snap-in](how-to-view-certificates-with-the-mmc-snap-in.md).) - -2. In the **Console Root** window's left pane, click **Certificates (Local Computer)**. - -3. Click the **Personal** folder to expand it. - -4. Click the **Certificates** folder to expand it. - -5. In the list of certificates, note the **Intended Purposes** heading. Find a certificate that lists **Client Authentication** as an intended purpose. - -6. Double-click the certificate. - -7. In the **Certificate** dialog box, click the **Details** tab. - -8. Scroll through the list of fields and click **Thumbprint**. - -9. Copy the hexadecimal characters from the box. If this thumbprint is used in code for the `X509FindType`, remove the spaces between the hexadecimal numbers. For example, the thumbprint "a9 09 50 2d d8 2a e4 14 33 e6 f8 38 86 b0 0d 42 77 a3 2a 7b" should be specified as "a909502dd82ae41433e6f83886b00d4277a32a7b" in code. - +When writing a Windows Communication Foundation (WCF) application that uses an X.509 certificate for authentication, it is often necessary to specify claims found in the certificate. For example, you must supply a thumbprint claim when using the enumeration in the method. Finding the claim value requires two steps. First, open the Microsoft Management Console (MMC) snap-in for certificates. (See [How to: View Certificates with the MMC Snap-in](how-to-view-certificates-with-the-mmc-snap-in.md).) Second, as described here, find an appropriate certificate and copy its thumbprint (or other claim values). + + If you are using a certificate for service authentication, it is important to note the value of the **Issued To** column (the first column in the console). When using Secure Sockets Layer (SSL) as a transport security, one of the first checks done is to compare the base address Uniform Resource Identifier (URI) of a service to the **Issued To** value. The values must match or the authentication process is halted. + + You can also use the PowerShell New-SelfSignedCertificate cmdlet to create temporary certificates for use only during development. By default, however, such a certificate is not issued by a certification authority and is unusable for production purposes. For more information, see [How to: Create Temporary Certificates for Use During Development](how-to-create-temporary-certificates-for-use-during-development.md). + +### To retrieve a certificate's thumbprint + +1. Open the Microsoft Management Console (MMC) snap-in for certificates. (See [How to: View Certificates with the MMC Snap-in](how-to-view-certificates-with-the-mmc-snap-in.md).) + +2. In the **Console Root** window's left pane, click **Certificates (Local Computer)**. + +3. Click the **Personal** folder to expand it. + +4. Click the **Certificates** folder to expand it. + +5. In the list of certificates, note the **Intended Purposes** heading. Find a certificate that lists **Client Authentication** as an intended purpose. + +6. Double-click the certificate. + +7. In the **Certificate** dialog box, click the **Details** tab. + +8. Scroll through the list of fields and click **Thumbprint**. + +9. Copy the hexadecimal characters from the box. If this thumbprint is used in code for the `X509FindType`, remove the spaces between the hexadecimal numbers. For example, the thumbprint "a9 09 50 2d d8 2a e4 14 33 e6 f8 38 86 b0 0d 42 77 a3 2a 7b" should be specified as "a909502dd82ae41433e6f83886b00d4277a32a7b" in code. + ## See also - -- +- - [How to: Configure a Port with an SSL Certificate](how-to-configure-a-port-with-an-ssl-certificate.md) - [How to: View Certificates with the MMC Snap-in](how-to-view-certificates-with-the-mmc-snap-in.md) - [How to: Create Temporary Certificates for Use During Development](how-to-create-temporary-certificates-for-use-during-development.md) diff --git a/docs/framework/wcf/feature-details/how-to-secure-a-service-with-an-x-509-certificate.md b/docs/framework/wcf/feature-details/how-to-secure-a-service-with-an-x-509-certificate.md index 8e6a0724451fe..441600fba2abd 100644 --- a/docs/framework/wcf/feature-details/how-to-secure-a-service-with-an-x-509-certificate.md +++ b/docs/framework/wcf/feature-details/how-to-secure-a-service-with-an-x-509-certificate.md @@ -2,84 +2,84 @@ description: "Learn more about: How to: Secure a Service with an X.509 Certificate" title: "How to: Secure a Service with an X.509 Certificate" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 2d06c2aa-d0d7-4e5e-ad7e-77416aa1c10b --- # How to: Secure a Service with an X.509 Certificate -Securing a service with an X.509 certificate is a basic technique that most bindings in Windows Communication Foundation (WCF) use. This topic walks through the steps of configuring a self-hosted service with an X.509 certificate. - - A prerequisite is a valid certificate that can be used to authenticate the server. The certificate must be issued to the server by a trusted certificate authority. If the certificate is not valid, any client trying to use the service will not trust the service, and consequently no connection will be made. For more information about using certificates, see [Working with Certificates](working-with-certificates.md). - -### To configure a service with a certificate using code - -1. Create the service contract and the implemented service. For more information, see [Designing and Implementing Services](../designing-and-implementing-services.md). - -2. Create an instance of the class and set its security mode to , as shown in the following code. - +Securing a service with an X.509 certificate is a basic technique that most bindings in Windows Communication Foundation (WCF) use. This topic walks through the steps of configuring a self-hosted service with an X.509 certificate. + + A prerequisite is a valid certificate that can be used to authenticate the server. The certificate must be issued to the server by a trusted certificate authority. If the certificate is not valid, any client trying to use the service will not trust the service, and consequently no connection will be made. For more information about using certificates, see [Working with Certificates](working-with-certificates.md). + +### To configure a service with a certificate using code + +1. Create the service contract and the implemented service. For more information, see [Designing and Implementing Services](../designing-and-implementing-services.md). + +2. Create an instance of the class and set its security mode to , as shown in the following code. + [!code-csharp[C_SecureWithCertificate#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_securewithcertificate/cs/source.cs#1)] - [!code-vb[C_SecureWithCertificate#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#1)] - -3. Create two variables, one each for the contract type and the implemented contract, as shown in the following code. - + [!code-vb[C_SecureWithCertificate#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#1)] + +3. Create two variables, one each for the contract type and the implemented contract, as shown in the following code. + [!code-csharp[C_SecureWithCertificate#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_securewithcertificate/cs/source.cs#2)] - [!code-vb[C_SecureWithCertificate#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#2)] - -4. Create an instance of the class for the base address of the service. Because the `WSHttpBinding` uses the HTTP transport, the Uniform Resource Identifier (URI) must begin with that schema, or Windows Communication Foundation (WCF) will throw an exception when the service is opened. - + [!code-vb[C_SecureWithCertificate#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#2)] + +4. Create an instance of the class for the base address of the service. Because the `WSHttpBinding` uses the HTTP transport, the Uniform Resource Identifier (URI) must begin with that schema, or Windows Communication Foundation (WCF) will throw an exception when the service is opened. + [!code-csharp[C_SecureWithCertificate#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_securewithcertificate/cs/source.cs#3)] - [!code-vb[C_SecureWithCertificate#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#3)] - -5. Create a new instance of the class with the implemented contract type variable and the URI. - + [!code-vb[C_SecureWithCertificate#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#3)] + +5. Create a new instance of the class with the implemented contract type variable and the URI. + [!code-csharp[C_SecureWithCertificate#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_securewithcertificate/cs/source.cs#4)] - [!code-vb[C_SecureWithCertificate#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#4)] - -6. Add a to the service using the method. Pass the contract, binding, and an endpoint address to the constructor, as shown in the following code. - + [!code-vb[C_SecureWithCertificate#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#4)] + +6. Add a to the service using the method. Pass the contract, binding, and an endpoint address to the constructor, as shown in the following code. + [!code-csharp[C_SecureWithCertificate#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_securewithcertificate/cs/source.cs#5)] - [!code-vb[C_SecureWithCertificate#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#5)] - -7. Optional. To retrieve metadata from the service, create a new object and set the property to `true`. - + [!code-vb[C_SecureWithCertificate#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#5)] + +7. Optional. To retrieve metadata from the service, create a new object and set the property to `true`. + [!code-csharp[C_SecureWithCertificate#6](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_securewithcertificate/cs/source.cs#6)] - [!code-vb[C_SecureWithCertificate#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#6)] - -8. Use the method of the class to add the valid certificate to the service. The method can use one of several methods to find a certificate. This example uses the enumeration. The enumeration specifies that the supplied value is the name of the entity that the certificate was issued to. - + [!code-vb[C_SecureWithCertificate#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#6)] + +8. Use the method of the class to add the valid certificate to the service. The method can use one of several methods to find a certificate. This example uses the enumeration. The enumeration specifies that the supplied value is the name of the entity that the certificate was issued to. + [!code-csharp[C_SecureWithCertificate#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_securewithcertificate/cs/source.cs#7)] - [!code-vb[C_SecureWithCertificate#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#7)] - -9. Call the method to start the service listening. If you are creating a console application, call the method to keep the service in the listening state. - + [!code-vb[C_SecureWithCertificate#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#7)] + +9. Call the method to start the service listening. If you are creating a console application, call the method to keep the service in the listening state. + [!code-csharp[C_SecureWithCertificate#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_securewithcertificate/cs/source.cs#8)] - [!code-vb[C_SecureWithCertificate#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#8)] - -## Example + [!code-vb[C_SecureWithCertificate#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#8)] + +## Example + + The following example uses the method to configure a service with an X.509 certificate. - The following example uses the method to configure a service with an X.509 certificate. - [!code-csharp[C_SecureWithCertificate#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_securewithcertificate/cs/source.cs#9)] - [!code-vb[C_SecureWithCertificate#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#9)] - -## Compiling the Code - - The following namespaces are required to compile the code: - -- - -- - -- - -- - -- - -- - + [!code-vb[C_SecureWithCertificate#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewithcertificate/vb/source.vb#9)] + +## Compiling the Code + + The following namespaces are required to compile the code: + +- + +- + +- + +- + +- + +- + ## See also - [Working with Certificates](working-with-certificates.md) diff --git a/docs/framework/wcf/feature-details/how-to-secure-metadata-endpoints.md b/docs/framework/wcf/feature-details/how-to-secure-metadata-endpoints.md index b11ee2d2f01a0..4532bd849f206 100644 --- a/docs/framework/wcf/feature-details/how-to-secure-metadata-endpoints.md +++ b/docs/framework/wcf/feature-details/how-to-secure-metadata-endpoints.md @@ -24,11 +24,11 @@ This topic walks through the steps to create an endpoint secured by a Secure Soc 2. Create a new instance of the class. -3. Set the property of the class to `true`. +3. Set the property of the class to `true`. -4. Set the property to an appropriate URL. Note that if you specify an absolute address, the URL must begin with the scheme `https://`. If you specify a relative address, you must supply an HTTPS base address for your service host. If this property is not set, the default address is "", or directly at the HTTPS base address for the service. +4. Set the property to an appropriate URL. Note that if you specify an absolute address, the URL must begin with the scheme `https://`. If you specify a relative address, you must supply an HTTPS base address for your service host. If this property is not set, the default address is "", or directly at the HTTPS base address for the service. -5. Add the instance to the behaviors collection that the property of the class returns, as shown in the following code. +5. Add the instance to the behaviors collection that the property of the class returns, as shown in the following code. [!code-csharp[c_HowToSecureEndpoint#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howtosecureendpoint/cs/source.cs#1)] [!code-vb[c_HowToSecureEndpoint#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howtosecureendpoint/vb/source.vb#1)] @@ -92,9 +92,9 @@ The code example uses the following namespaces: ## See also -- +- - -- +- - [How to: Configure a Port with an SSL Certificate](how-to-configure-a-port-with-an-ssl-certificate.md) - [Working with Certificates](working-with-certificates.md) - [Security Considerations with Metadata](security-considerations-with-metadata.md) diff --git a/docs/framework/wcf/feature-details/how-to-serialize-and-deserialize-json-data.md b/docs/framework/wcf/feature-details/how-to-serialize-and-deserialize-json-data.md index 9d4581b915842..d2525c1b5a0f9 100644 --- a/docs/framework/wcf/feature-details/how-to-serialize-and-deserialize-json-data.md +++ b/docs/framework/wcf/feature-details/how-to-serialize-and-deserialize-json-data.md @@ -53,7 +53,7 @@ This article is based on the [DataContractJsonSerializer sample](../samples/json var ser = new DataContractJsonSerializer(typeof(Person)); ``` -3. Use the method to write JSON data to the stream. +3. Use the method to write JSON data to the stream. ```csharp ser.WriteObject(stream1, p); @@ -70,7 +70,7 @@ This article is based on the [DataContractJsonSerializer sample](../samples/json ## To deserialize an instance of type Person from JSON -1. Deserialize the JSON-encoded data into a new instance of `Person` by using the method of the . +1. Deserialize the JSON-encoded data into a new instance of `Person` by using the method of the . ```csharp stream1.Position = 0; diff --git a/docs/framework/wcf/feature-details/how-to-set-a-max-clock-skew.md b/docs/framework/wcf/feature-details/how-to-set-a-max-clock-skew.md index 022bf89acc3ef..b8e65f72910a7 100644 --- a/docs/framework/wcf/feature-details/how-to-set-a-max-clock-skew.md +++ b/docs/framework/wcf/feature-details/how-to-set-a-max-clock-skew.md @@ -2,84 +2,84 @@ description: "Learn more about: How to: Set a Max Clock Skew" title: "How to: Set a Max Clock Skew" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "MaxClockSkew property" - "WCF, custom bindings" ms.assetid: 491d1705-eb29-43c2-a44c-c0cf996f74eb --- # How to: Set a Max Clock Skew -Time-critical functions can be derailed if the clock settings on two computers are different. To mitigate this possibility, you can set the `MaxClockSkew` property to a . This property is available on two classes: - - - - - +Time-critical functions can be derailed if the clock settings on two computers are different. To mitigate this possibility, you can set the `MaxClockSkew` property to a . This property is available on two classes: + + + + + > [!IMPORTANT] -> For a secure conversation, changes to the `MaxClockSkew` property must be made when the service or client is bootstrapped. To do this, you must set the property on the returned by the property. - - To change the property on one of the system-provided bindings, you must find the security binding element in the collection of bindings and set the `MaxClockSkew` property to a new value. Two classes derive from the : and . When retrieving the security binding from the collection, you must cast to one of these types in order to correctly set the `MaxClockSkew` property. The following example uses a , which uses the . For a list that specifies which type of security binding to use in each system-provided binding, see [System-Provided Bindings](../system-provided-bindings.md). - -## To create a custom binding with a new clock skew value in code - +> For a secure conversation, changes to the `MaxClockSkew` property must be made when the service or client is bootstrapped. To do this, you must set the property on the returned by the property. + + To change the property on one of the system-provided bindings, you must find the security binding element in the collection of bindings and set the `MaxClockSkew` property to a new value. Two classes derive from the : and . When retrieving the security binding from the collection, you must cast to one of these types in order to correctly set the `MaxClockSkew` property. The following example uses a , which uses the . For a list that specifies which type of security binding to use in each system-provided binding, see [System-Provided Bindings](../system-provided-bindings.md). + +## To create a custom binding with a new clock skew value in code + > [!WARNING] -> Add references to the following namespaces in your code: , , , and . - -1. Create an instance of a class and set its security mode to . - -2. Create a new instance of the class by calling the method. - -3. Use the method of the class to find the security binding element. - -4. When using the method, cast to the actual type. The example below casts to the type. - -5. Set the property on the security binding element. - -6. Create a with an appropriate service type and base address. - -7. Use the method to add an endpoint and include the . - +> Add references to the following namespaces in your code: , , , and . + +1. Create an instance of a class and set its security mode to . + +2. Create a new instance of the class by calling the method. + +3. Use the method of the class to find the security binding element. + +4. When using the method, cast to the actual type. The example below casts to the type. + +5. Set the property on the security binding element. + +6. Create a with an appropriate service type and base address. + +7. Use the method to add an endpoint and include the . + [!code-csharp[c_MaxClockSkew#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_maxclockskew/cs/source.cs#1)] - [!code-vb[c_MaxClockSkew#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_maxclockskew/vb/source.vb#1)] - -## To set the MaxClockSkew in configuration - -1. Create a [\](../../configure-apps/file-schema/wcf/custombinding.md) in the [\](../../configure-apps/file-schema/wcf/bindings.md) element section. - -2. Create a [\](../../configure-apps/file-schema/wcf/bindings.md) element and set the `name` attribute to an appropriate value. The following example sets it to `MaxClockSkewBinding`. - -3. Add an encoding element. The example below adds a [\](../../configure-apps/file-schema/wcf/textmessageencoding.md). - -4. Add a [\](../../configure-apps/file-schema/wcf/security-of-custombinding.md) element and set the `authenticationMode` attribute to an appropriate setting. The following example set the attribute to `Kerberos` to specify that the service use Windows authentication. - -5. Add a [\](../../configure-apps/file-schema/wcf/localservicesettings-element.md) and set the `maxClockSkew` attribute to a value in the form of `"##:##:##"`. The following example sets it to 7 minutes. Optionally, add a [\](../../configure-apps/file-schema/wcf/localservicesettings-element.md) and set the `maxClockSkew` attribute to an appropriate setting. - -6. Add a transport element. The following example uses an [\](../../configure-apps/file-schema/wcf/httptransport.md). - -7. For a secure conversation, the security settings must occur at the bootstrap in the [\](../../configure-apps/file-schema/wcf/secureconversationbootstrap.md) element. - - ```xml - - - - - - - - - - - - - - - - - ``` - + [!code-vb[c_MaxClockSkew#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_maxclockskew/vb/source.vb#1)] + +## To set the MaxClockSkew in configuration + +1. Create a [\](../../configure-apps/file-schema/wcf/custombinding.md) in the [\](../../configure-apps/file-schema/wcf/bindings.md) element section. + +2. Create a [\](../../configure-apps/file-schema/wcf/bindings.md) element and set the `name` attribute to an appropriate value. The following example sets it to `MaxClockSkewBinding`. + +3. Add an encoding element. The example below adds a [\](../../configure-apps/file-schema/wcf/textmessageencoding.md). + +4. Add a [\](../../configure-apps/file-schema/wcf/security-of-custombinding.md) element and set the `authenticationMode` attribute to an appropriate setting. The following example set the attribute to `Kerberos` to specify that the service use Windows authentication. + +5. Add a [\](../../configure-apps/file-schema/wcf/localservicesettings-element.md) and set the `maxClockSkew` attribute to a value in the form of `"##:##:##"`. The following example sets it to 7 minutes. Optionally, add a [\](../../configure-apps/file-schema/wcf/localservicesettings-element.md) and set the `maxClockSkew` attribute to an appropriate setting. + +6. Add a transport element. The following example uses an [\](../../configure-apps/file-schema/wcf/httptransport.md). + +7. For a secure conversation, the security settings must occur at the bootstrap in the [\](../../configure-apps/file-schema/wcf/secureconversationbootstrap.md) element. + + ```xml + + + + + + + + + + + + + + + + + ``` + ## See also - diff --git a/docs/framework/wcf/feature-details/how-to-set-up-a-signature-confirmation.md b/docs/framework/wcf/feature-details/how-to-set-up-a-signature-confirmation.md index 7a756bde8a180..981b714b6d439 100644 --- a/docs/framework/wcf/feature-details/how-to-set-up-a-signature-confirmation.md +++ b/docs/framework/wcf/feature-details/how-to-set-up-a-signature-confirmation.md @@ -22,7 +22,7 @@ The following procedures specify how to enable signature confirmation using an < 2. Create an instance of the class. -3. Set the to `true`. +3. Set the to `true`. 4. Add the security element to the binding collection. @@ -58,7 +58,7 @@ The following procedures specify how to enable signature confirmation using an < ## Example -The following code creates an instance of the and sets the property to `true`. Note that this example does not use the `` element shown in the preceding example. This example demonstrates signature confirmation when using a Windows (Kerberos protocol) token. In this case, the signature of the client is returned in all responses from the service and is confirmed by the client. +The following code creates an instance of the and sets the property to `true`. Note that this example does not use the `` element shown in the preceding example. This example demonstrates signature confirmation when using a Windows (Kerberos protocol) token. In this case, the signature of the client is returned in all responses from the service and is confirmed by the client. [!code-csharp[c_SignatureConfirmation#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_signatureconfirmation/cs/source.cs#1)] [!code-vb[c_SignatureConfirmation#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_signatureconfirmation/vb/source.vb#1)] @@ -67,6 +67,6 @@ The following code creates an instance of the - -- +- - [How to: Create a Custom Binding Using the SecurityBindingElement](how-to-create-a-custom-binding-using-the-securitybindingelement.md) - [How to: Create a SecurityBindingElement for a Specified Authentication Mode](how-to-create-a-securitybindingelement-for-a-specified-authentication-mode.md) diff --git a/docs/framework/wcf/feature-details/how-to-use-configuration-to-add-an-aspnet-ajax-endpoint.md b/docs/framework/wcf/feature-details/how-to-use-configuration-to-add-an-aspnet-ajax-endpoint.md index 364ac3c3d0b80..0e7f3c5a784a3 100644 --- a/docs/framework/wcf/feature-details/how-to-use-configuration-to-add-an-aspnet-ajax-endpoint.md +++ b/docs/framework/wcf/feature-details/how-to-use-configuration-to-add-an-aspnet-ajax-endpoint.md @@ -6,100 +6,100 @@ ms.assetid: 7cd0099e-dc3a-47e4-a38c-6e10f997f6ea --- # How to: Use Configuration to Add an ASP.NET AJAX Endpoint -Windows Communication Foundation (WCF) allows you to create a service that makes an ASP.NET AJAX-enabled endpoint available that can be called from JavaScript on a client Web site. To create such an endpoint, you can either use a configuration file, as with all other Windows Communication Foundation (WCF) endpoints, or use a method that does not require any configuration elements. This topic demonstrates the configuration approach. - - The part of the procedure that enables the service endpoint to become ASP.NET AJAX-enabled consists of configuring the endpoint to use the and to add the [\](../../configure-apps/file-schema/wcf/enablewebscript.md) endpoint behavior. After configuring the endpoint, the steps to implement and host the service are similar to those used by any WCF service. For a working example, see the [AJAX Service Using HTTP POST](../samples/ajax-service-using-http-post.md). - - For more information about how to configure an ASP.NET AJAX endpoint without using configuration, see [How to: Add an ASP.NET AJAX Endpoint Without Using Configuration](how-to-add-an-aspnet-ajax-endpoint-without-using-configuration.md). - -## To create a basic WCF service - -1. Define a basic WCF service contract with an interface marked with the attribute. Mark each operation with the . Be sure to set the property. - +Windows Communication Foundation (WCF) allows you to create a service that makes an ASP.NET AJAX-enabled endpoint available that can be called from JavaScript on a client Web site. To create such an endpoint, you can either use a configuration file, as with all other Windows Communication Foundation (WCF) endpoints, or use a method that does not require any configuration elements. This topic demonstrates the configuration approach. + + The part of the procedure that enables the service endpoint to become ASP.NET AJAX-enabled consists of configuring the endpoint to use the and to add the [\](../../configure-apps/file-schema/wcf/enablewebscript.md) endpoint behavior. After configuring the endpoint, the steps to implement and host the service are similar to those used by any WCF service. For a working example, see the [AJAX Service Using HTTP POST](../samples/ajax-service-using-http-post.md). + + For more information about how to configure an ASP.NET AJAX endpoint without using configuration, see [How to: Add an ASP.NET AJAX Endpoint Without Using Configuration](how-to-add-an-aspnet-ajax-endpoint-without-using-configuration.md). + +## To create a basic WCF service + +1. Define a basic WCF service contract with an interface marked with the attribute. Mark each operation with the . Be sure to set the property. + ```csharp - [ServiceContract(Namespace = "MyService")] - public interface ICalculator - { - [OperationContract] - // This operation returns the sum of d1 and d2. - double Add(double n1, double n2); - - //Other operations omitted… - - } - ``` - -2. Implement the `ICalculator` service contract with a `CalculatorService`. - + [ServiceContract(Namespace = "MyService")] + public interface ICalculator + { + [OperationContract] + // This operation returns the sum of d1 and d2. + double Add(double n1, double n2); + + //Other operations omitted… + + } + ``` + +2. Implement the `ICalculator` service contract with a `CalculatorService`. + ```csharp - public class CalculatorService : ICalculator - { - public double Add(double n1, double n2) - { - return n1 + n2; + public class CalculatorService : ICalculator + { + public double Add(double n1, double n2) + { + return n1 + n2; } // Other operations omitted… } - ``` - -3. Define a namespace for the `ICalculator` and `CalculatorService` implementations by wrapping them in a namespace block. - + ``` + +3. Define a namespace for the `ICalculator` and `CalculatorService` implementations by wrapping them in a namespace block. + ```csharp namespace Microsoft.Ajax.Samples - { - //Include the code for ICalculator and Calculator here. - } - ``` - -## To create an ASP.NET AJAX endpoint for the service - -1. Create a behavior configuration and specify the [\](../../configure-apps/file-schema/wcf/enablewebscript.md) behavior for ASP.NET AJAX-enabled endpoints of the service. - - ```xml - - - - - - - - - - ``` - -2. Create an endpoint for the service that uses the and the ASP.NET AJAX behavior defined in the previous step. - - ```xml - - - - ](../../configure-apps/file-schema/wcf/enablewebscript.md) behavior for ASP.NET AJAX-enabled endpoints of the service. + + ```xml + + + + + + + + + + ``` + +2. Create an endpoint for the service that uses the and the ASP.NET AJAX behavior defined in the previous step. + + ```xml + + + + - - + binding="webHttpBinding" + contract="Microsoft.Ajax.Samples.ICalculator" /> + + - ``` - -## To host the service in IIS - -1. To host the service in IIS, create a new file named service with a .svc extension in the application. Edit this file by adding the appropriate [\@ServiceHost](../../configure-apps/file-schema/wcf-directive/servicehost.md) directive information for the service. For example, the content in the service file for the `CalculatorService` sample contains the following information. - + ``` + +## To host the service in IIS + +1. To host the service in IIS, create a new file named service with a .svc extension in the application. Edit this file by adding the appropriate [\@ServiceHost](../../configure-apps/file-schema/wcf-directive/servicehost.md) directive information for the service. For example, the content in the service file for the `CalculatorService` sample contains the following information. + ```aspx-csharp <%@ServiceHost language=c# Debug="true" - Service="Microsoft.Ajax.Samples.CalculatorService" - %> - ``` - -2. For more information about hosting in IIS, see [How to: Host a WCF Service in IIS](how-to-host-a-wcf-service-in-iis.md). - -## To call the service - -1. The endpoint is configured at an empty address relative to the .svc file, so the service is now available and can be invoked by sending requests to service.svc/\ - for example, service.svc/Add for the `Add` operation. You can use it by entering the endpoint URL into the Scripts collection of the ASP.NET AJAX Script Manager control. For an example, see the [AJAX Service Using HTTP POST](../samples/ajax-service-using-http-post.md). - + Service="Microsoft.Ajax.Samples.CalculatorService" + %> + ``` + +2. For more information about hosting in IIS, see [How to: Host a WCF Service in IIS](how-to-host-a-wcf-service-in-iis.md). + +## To call the service + +1. The endpoint is configured at an empty address relative to the .svc file, so the service is now available and can be invoked by sending requests to service.svc/\ - for example, service.svc/Add for the `Add` operation. You can use it by entering the endpoint URL into the Scripts collection of the ASP.NET AJAX Script Manager control. For an example, see the [AJAX Service Using HTTP POST](../samples/ajax-service-using-http-post.md). + ## See also - [Creating WCF Services for ASP.NET AJAX](creating-wcf-services-for-aspnet-ajax.md) diff --git a/docs/framework/wcf/feature-details/how-to-use-metadataexchangeclient-to-retrieve-metadata.md b/docs/framework/wcf/feature-details/how-to-use-metadataexchangeclient-to-retrieve-metadata.md index b80295ac9fbef..61d5c1e198503 100644 --- a/docs/framework/wcf/feature-details/how-to-use-metadataexchangeclient-to-retrieve-metadata.md +++ b/docs/framework/wcf/feature-details/how-to-use-metadataexchangeclient-to-retrieve-metadata.md @@ -6,33 +6,33 @@ ms.assetid: 0754e9dc-13c5-45c2-81b5-f3da466e5a87 --- # How to: Use MetadataExchangeClient to Retrieve Metadata -Use the class to download metadata using the WS-MetadataExchange (MEX) protocol. The retrieved metadata files are returned as a object. The returned object contains a collection of objects, each of which contains a specific metadata dialect and an identifier. You can write the returned metadata to files or, if the returned metadata contains Web Services Description Language (WSDL) documents, you can import the metadata using the . - - The constructors that take an address use the binding on the static class that matches the Uniform Resource Identifier (URI) scheme of the address. You can alternatively use the constructor that allows you to explicitly specify the binding to use. The specified binding is used to resolve all metadata references. - - Just like any other Windows Communication Foundation (WCF) client, the type provides a constructor for loading client endpoint configurations using the endpoint configuration name. The specified endpoint configuration must specify the contract. The address in the endpoint configuration is not loaded, so you must use one of the overloads that take an address. When you specify the metadata address using an instance, the assumes that the address points to a MEX endpoint. If you specify the metadata address as a URL, then you need to also specify which to use, MEX or HTTP GET. - +Use the class to download metadata using the WS-MetadataExchange (MEX) protocol. The retrieved metadata files are returned as a object. The returned object contains a collection of objects, each of which contains a specific metadata dialect and an identifier. You can write the returned metadata to files or, if the returned metadata contains Web Services Description Language (WSDL) documents, you can import the metadata using the . + + The constructors that take an address use the binding on the static class that matches the Uniform Resource Identifier (URI) scheme of the address. You can alternatively use the constructor that allows you to explicitly specify the binding to use. The specified binding is used to resolve all metadata references. + + Just like any other Windows Communication Foundation (WCF) client, the type provides a constructor for loading client endpoint configurations using the endpoint configuration name. The specified endpoint configuration must specify the contract. The address in the endpoint configuration is not loaded, so you must use one of the overloads that take an address. When you specify the metadata address using an instance, the assumes that the address points to a MEX endpoint. If you specify the metadata address as a URL, then you need to also specify which to use, MEX or HTTP GET. + > [!IMPORTANT] -> By default, the resolves all references for you, including WSDL and XML Schema imports and includes. You can disable this functionality by setting the property to `false`. You can control the maximum number of references to resolve using the property. You can use this property in conjunction with the `MaxReceivedMessageSize` property on the binding to control how much metadata is retrieved. - -### To use MetadataExchangeClient to obtain metadata - -1. Create a new object by explicitly specifying a binding, an endpoint configuration name, or the address of the metadata. - -2. Configure the to suit your needs. For example, you can specify credentials to use when requesting metadata, control how metadata references are resolved, and set the property to control how long the metadata request has to return before it times out. - -3. Obtain the object that contains the retrieved metadata by calling one of the methods. Note that you can only use the overload that takes no arguments if you explicitly specified an address when constructing the . - -## Example - - The following code example shows how to use to download and enumerate metadata files. - - [!code-csharp[MetadataResolver#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/metadataresolver/cs/client.cs#3)] - -## Compiling the Code - - To compile this code example, you must reference the System.ServiceModel.dll assembly and import the namespace. - +> By default, the resolves all references for you, including WSDL and XML Schema imports and includes. You can disable this functionality by setting the property to `false`. You can control the maximum number of references to resolve using the property. You can use this property in conjunction with the `MaxReceivedMessageSize` property on the binding to control how much metadata is retrieved. + +### To use MetadataExchangeClient to obtain metadata + +1. Create a new object by explicitly specifying a binding, an endpoint configuration name, or the address of the metadata. + +2. Configure the to suit your needs. For example, you can specify credentials to use when requesting metadata, control how metadata references are resolved, and set the property to control how long the metadata request has to return before it times out. + +3. Obtain the object that contains the retrieved metadata by calling one of the methods. Note that you can only use the overload that takes no arguments if you explicitly specified an address when constructing the . + +## Example + + The following code example shows how to use to download and enumerate metadata files. + + [!code-csharp[MetadataResolver#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/metadataresolver/cs/client.cs#3)] + +## Compiling the Code + + To compile this code example, you must reference the System.ServiceModel.dll assembly and import the namespace. + ## See also - diff --git a/docs/framework/wcf/feature-details/how-to-use-multiple-security-tokens-of-the-same-type.md b/docs/framework/wcf/feature-details/how-to-use-multiple-security-tokens-of-the-same-type.md index d40cd4791e619..6c1ce91fe38a5 100644 --- a/docs/framework/wcf/feature-details/how-to-use-multiple-security-tokens-of-the-same-type.md +++ b/docs/framework/wcf/feature-details/how-to-use-multiple-security-tokens-of-the-same-type.md @@ -6,42 +6,42 @@ ms.assetid: cf179f48-4ed4-4caa-86a5-ef8eecc231cd --- # How to: Use Multiple Security Tokens of the Same Type -- In .NET Framework 3.0, a client message only contained one token of any given type. Now client messages can contain multiple tokens of a type. This topic shows how to include multiple tokens of the same type in a client message. - -- Note that you cannot configure a service in this way: a service can contain only one supporting token. - -### To use multiple security tokens of the same type - -1. Create an empty binding element collection to be populated. - - [!code-csharp[C_CustomBinding#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#9)] - -2. Create a by calling . - - [!code-csharp[C_CustomBinding#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#10)] - -3. Create a collection. - - [!code-csharp[C_CustomBinding#11](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#11)] - -4. Add SAML tokens to the collection. - - [!code-csharp[C_CustomBinding#12](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#12)] - -5. Add the collection to the . - - [!code-csharp[C_CustomBinding#13](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#13)] - -6. Add binding elements to the binding element collection. - - [!code-csharp[C_CustomBinding#14](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#14)] - -7. Return a new custom binding created from the binding element collection. - - [!code-csharp[C_CustomBinding#15](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#15)] - -## Example - - The following is the entire method described by the preceding procedure. - - [!code-csharp[C_CustomBinding#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#7)] +- In .NET Framework 3.0, a client message only contained one token of any given type. Now client messages can contain multiple tokens of a type. This topic shows how to include multiple tokens of the same type in a client message. + +- Note that you cannot configure a service in this way: a service can contain only one supporting token. + +### To use multiple security tokens of the same type + +1. Create an empty binding element collection to be populated. + + [!code-csharp[C_CustomBinding#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#9)] + +2. Create a by calling . + + [!code-csharp[C_CustomBinding#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#10)] + +3. Create a collection. + + [!code-csharp[C_CustomBinding#11](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#11)] + +4. Add SAML tokens to the collection. + + [!code-csharp[C_CustomBinding#12](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#12)] + +5. Add the collection to the . + + [!code-csharp[C_CustomBinding#13](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#13)] + +6. Add binding elements to the binding element collection. + + [!code-csharp[C_CustomBinding#14](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#14)] + +7. Return a new custom binding created from the binding element collection. + + [!code-csharp[C_CustomBinding#15](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#15)] + +## Example + + The following is the entire method described by the preceding procedure. + + [!code-csharp[C_CustomBinding#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombinding/cs/c_custombinding.cs#7)] diff --git a/docs/framework/wcf/feature-details/how-to-use-svcutil-exe-to-download-metadata-documents.md b/docs/framework/wcf/feature-details/how-to-use-svcutil-exe-to-download-metadata-documents.md index 88f4f0c3c83c4..a03835b5e4e30 100644 --- a/docs/framework/wcf/feature-details/how-to-use-svcutil-exe-to-download-metadata-documents.md +++ b/docs/framework/wcf/feature-details/how-to-use-svcutil-exe-to-download-metadata-documents.md @@ -14,8 +14,8 @@ You can use Svcutil.exe to download metadata from running services and to save t > When running Svcutil.exe to get metadata for a service that exposes two different service contracts that each contain an operation of the same name, Svcutil.exe displays an error saying, "Cannot obtain Metadata from ...." For example, if you have a service that exposes a service contract called `ICarService` that has an operation `Get(Car c)` and the same service exposes a service contract called `IBookService` that has an operation `Get(Book b)`. To work around this issue, do one of the following: > > - Rename one of the operations. -> - Set the to a different name. -> - Set one of the operations' namespaces to a different namespace using the property. +> - Set the to a different name. +> - Set one of the operations' namespaces to a different namespace using the property. ## To download metadata using Svcutil.exe diff --git a/docs/framework/wcf/feature-details/how-to-use-the-aspnet-role-provider-with-a-service.md b/docs/framework/wcf/feature-details/how-to-use-the-aspnet-role-provider-with-a-service.md index db3756f77046c..a564c7ef9123d 100644 --- a/docs/framework/wcf/feature-details/how-to-use-the-aspnet-role-provider-with-a-service.md +++ b/docs/framework/wcf/feature-details/how-to-use-the-aspnet-role-provider-with-a-service.md @@ -10,7 +10,7 @@ The ASP.NET role provider (in conjunction with the ASP.NET membership provider) For a sample application, see [Membership and Role Provider](../samples/membership-and-role-provider.md). For more information about the ASP.NET membership provider feature, see [How to: Use the ASP.NET Membership Provider](how-to-use-the-aspnet-membership-provider.md). -The role provider feature uses a SQL Server database to store user information. Windows Communication Foundation (WCF) developers can take advantage of these features for security purposes. When integrated into a WCF application, users must supply a user name/password combination to the WCF client application. To enable WCF to use the database, you must create an instance of the class, set its property to , and add the instance to the collection of behaviors to the that is hosting the service. +The role provider feature uses a SQL Server database to store user information. Windows Communication Foundation (WCF) developers can take advantage of these features for security purposes. When integrated into a WCF application, users must supply a user name/password combination to the WCF client application. To enable WCF to use the database, you must create an instance of the class, set its property to , and add the instance to the collection of behaviors to the that is hosting the service. ## Configure the role provider diff --git a/docs/framework/wcf/feature-details/how-to-use-the-channelfactory.md b/docs/framework/wcf/feature-details/how-to-use-the-channelfactory.md index 949ad2baf6a63..249440284920f 100644 --- a/docs/framework/wcf/feature-details/how-to-use-the-channelfactory.md +++ b/docs/framework/wcf/feature-details/how-to-use-the-channelfactory.md @@ -1,25 +1,25 @@ --- title: "How to: Use the ChannelFactory" -description: Learn how to create a channel factory to create more than one channel for accessing services by using a WCF client. +description: Learn how to create a channel factory to create more than one channel for accessing services by using a WCF client. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: d48f01b5-582b-4c8b-b547-8adddae7e371 --- # How to: Use the ChannelFactory -The generic class is used in advanced scenarios that require the creation of a channel factory that can be used to create more than one channel. - -### To create and use the ChannelFactory class - -1. Build and run an Windows Communication Foundation (WCF) service. For more information, see [Designing and Implementing Services](../designing-and-implementing-services.md), [Configuring Services](../configuring-services.md), and [Hosting Services](../hosting-services.md). - -2. Use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to generate the contract (interface) for the client. - -3. In the client code, use the class to create multiple endpoint listeners. - -## Example +The generic class is used in advanced scenarios that require the creation of a channel factory that can be used to create more than one channel. + +### To create and use the ChannelFactory class + +1. Build and run an Windows Communication Foundation (WCF) service. For more information, see [Designing and Implementing Services](../designing-and-implementing-services.md), [Configuring Services](../configuring-services.md), and [Hosting Services](../hosting-services.md). + +2. Use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to generate the contract (interface) for the client. + +3. In the client code, use the class to create multiple endpoint listeners. + +## Example [!code-csharp[c_HowToUseChannelFactory#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_howtousechannelfactory/cs/source.cs#1)] [!code-vb[c_HowToUseChannelFactory#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_howtousechannelfactory/vb/source.vb#1)] diff --git a/docs/framework/wcf/feature-details/how-to-use-transport-security-and-message-credentials.md b/docs/framework/wcf/feature-details/how-to-use-transport-security-and-message-credentials.md index d8a3b40ab3730..1cac5ea56a470 100644 --- a/docs/framework/wcf/feature-details/how-to-use-transport-security-and-message-credentials.md +++ b/docs/framework/wcf/feature-details/how-to-use-transport-security-and-message-credentials.md @@ -17,61 +17,61 @@ Securing a service with both transport and message credentials uses the best of If the transport is HTTP (using the ), SSL over HTTP provides the transport-level security. In that case, you must configure the computer hosting the service with an SSL certificate bound to a port, as shown later in this topic. - If the transport is TCP (using the ), by default the transport-level security provided is Windows security, or SSL over TCP. When using SSL over TCP, you must specify the certificate using the method, as shown later in this topic. + If the transport is TCP (using the ), by default the transport-level security provided is Windows security, or SSL over TCP. When using SSL over TCP, you must specify the certificate using the method, as shown later in this topic. ### To use the WSHttpBinding with a certificate for transport security (in code) 1. Use the HttpCfg.exe tool to bind an SSL certificate to a port on the machine. For more information, see [How to: Configure a Port with an SSL Certificate](how-to-configure-a-port-with-an-ssl-certificate.md). -2. Create an instance of the class and set the property to . +2. Create an instance of the class and set the property to . -3. Set the property to an appropriate value. (For more information, see [Selecting a Credential Type](selecting-a-credential-type.md).) The following code uses the value. +3. Set the property to an appropriate value. (For more information, see [Selecting a Credential Type](selecting-a-credential-type.md).) The following code uses the value. 4. Create an instance of the class with an appropriate base address. Note that the address must use the "HTTPS" scheme and must contain the actual name of the machine and the port number that the SSL certificate is bound to. (Alternatively, you can set the base address in configuration.) -5. Add a service endpoint using the method. +5. Add a service endpoint using the method. -6. Create the instance of the and call the method, as shown in the following code. +6. Create the instance of the and call the method, as shown in the following code. [!code-csharp[c_SettingSecurityMode#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_settingsecuritymode/cs/source.cs#7)] [!code-vb[c_SettingSecurityMode#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_settingsecuritymode/vb/source.vb#7)] ### To use the NetTcpBinding with a certificate for transport security (in code) -1. Create an instance of the class and set the property to . +1. Create an instance of the class and set the property to . -2. Set the to an appropriate value. The following code uses the value. +2. Set the to an appropriate value. The following code uses the value. 3. Create an instance of the class with an appropriate base address. Note that the address must use the "net.tcp" scheme. (Alternatively, you can set the base address in configuration.) 4. Create the instance of the class. -5. Use the method of the class to explicitly set the X.509 certificate for the service. +5. Use the method of the class to explicitly set the X.509 certificate for the service. -6. Add a service endpoint using the method. +6. Add a service endpoint using the method. -7. Call the method, as shown in the following code. +7. Call the method, as shown in the following code. [!code-csharp[c_SettingSecurityMode#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_settingsecuritymode/cs/source.cs#8)] [!code-vb[c_SettingSecurityMode#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_settingsecuritymode/vb/source.vb#8)] ### To use the NetTcpBinding with Windows for transport security (in code) -1. Create an instance of the class and set the property to . +1. Create an instance of the class and set the property to . -2. Set the transport security to use Windows by setting the to . (Note that this is the default.) +2. Set the transport security to use Windows by setting the to . (Note that this is the default.) -3. Set the to an appropriate value. The following code uses the value. +3. Set the to an appropriate value. The following code uses the value. 4. Create an instance of the class with an appropriate base address. Note that the address must use the "net.tcp" scheme. (Alternatively, you can set the base address in configuration.) 5. Create the instance of the class. -6. Use the method of the class to explicitly set the X.509 certificate for the service. +6. Use the method of the class to explicitly set the X.509 certificate for the service. -7. Add a service endpoint using the method. +7. Add a service endpoint using the method. -8. Call the method, as shown in the following code. +8. Call the method, as shown in the following code. [!code-csharp[c_SettingSecurityMode#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_settingsecuritymode/cs/source.cs#9)] [!code-vb[c_SettingSecurityMode#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_settingsecuritymode/vb/source.vb#9)] diff --git a/docs/framework/wcf/feature-details/how-to-view-certificates-with-the-mmc-snap-in.md b/docs/framework/wcf/feature-details/how-to-view-certificates-with-the-mmc-snap-in.md index e9d5452341bd1..51486afd356f8 100644 --- a/docs/framework/wcf/feature-details/how-to-view-certificates-with-the-mmc-snap-in.md +++ b/docs/framework/wcf/feature-details/how-to-view-certificates-with-the-mmc-snap-in.md @@ -2,7 +2,7 @@ title: "How to: View certificates with the MMC snap-in" description: A secure WCF client or service can use a certificate as a credential. Learn about the types of certificate stores you can examine by using the MMC plug-in. ms.date: 02/25/2019 -helpviewer_keywords: +helpviewer_keywords: - "certificates [WCF], viewing with the MMC snap-in" ms.assetid: 2b8782aa-ebb4-4ee7-974b-90299e356dc5 no-loc: [certlm.msc, certmgr.msc] @@ -10,7 +10,7 @@ ms.custom: sfi-image-nochange --- # How to: View certificates with the MMC snap-in -When you create a secure client or service, you can use a [certificate](working-with-certificates.md) as the credential. For example, a common type of credential is the X.509 certificate, which you create with the method. +When you create a secure client or service, you can use a [certificate](working-with-certificates.md) as the credential. For example, a common type of credential is the X.509 certificate, which you create with the method. There are three different types of certificate stores that you can examine with the Microsoft Management Console (MMC) on Windows systems: @@ -23,33 +23,33 @@ There are three different types of certificate stores that you can examine with ## View certificates in the MMC snap-in The following procedure demonstrates how to examine the stores on your local device to find an appropriate certificate: - + 1. Select **Run** from the **Start** menu, and then enter *mmc*. The MMC appears. - + 2. From the **File** menu, select **Add/Remove Snap In**. The **Add or Remove Snap-ins** window appears. - -3. From the **Available snap-ins** list, choose **Certificates**, then select **Add**. + +3. From the **Available snap-ins** list, choose **Certificates**, then select **Add**. ![Add certificate snap-in](./media/mmc-add-certificate-snap-in.png) - + 4. In the **Certificates snap-in** window, select **Computer account**, and then select **Next**. - + Optionally, you can select **My user account** for the current user or **Service account** for a particular service. > [!NOTE] > If you're not an administrator for your device, you can manage certificates only for your user account. - -5. In the **Select Computer** window, leave **Local computer** selected, and then select **Finish**. - -6. In the **Add or Remove Snap-in** window, select **OK**. - + +5. In the **Select Computer** window, leave **Local computer** selected, and then select **Finish**. + +6. In the **Add or Remove Snap-in** window, select **OK**. + ![Add or Remove Snap-ins window with OK button highlighted](./media/mmc-certificate-snap-in-selected.png) -7. Optional: From the **File** menu, select **Save** or **Save As** to save the MMC console file for later use. +7. Optional: From the **File** menu, select **Save** or **Save As** to save the MMC console file for later use. 8. To view your certificates in the MMC snap-in, select **Console Root** in the left pane, then expand **Certificates (Local Computer)**. @@ -64,7 +64,7 @@ You can also view, export, import, and delete certificates by using the Certific 1. Select **Run** from the **Start** menu, and then enter *certlm.msc*. The Certificate Manager tool for the local device appears. - + 2. To view your certificates, under **Certificates - Local Computer** in the left pane, expand the directory for the type of certificate you want to view. ### To view certificates for the current user @@ -72,7 +72,7 @@ You can also view, export, import, and delete certificates by using the Certific 1. Select **Run** from the **Start** menu, and then enter *certmgr.msc*. The Certificate Manager tool for the current user appears. - + 2. To view your certificates, under **Certificates - Current User** in the left pane, expand the directory for the type of certificate you want to view. ## See also diff --git a/docs/framework/wcf/feature-details/http-post-and-http-get-requests-for-aspnet-ajax-endpoints.md b/docs/framework/wcf/feature-details/http-post-and-http-get-requests-for-aspnet-ajax-endpoints.md index 099fc4798ef83..6e3bc81569279 100644 --- a/docs/framework/wcf/feature-details/http-post-and-http-get-requests-for-aspnet-ajax-endpoints.md +++ b/docs/framework/wcf/feature-details/http-post-and-http-get-requests-for-aspnet-ajax-endpoints.md @@ -7,85 +7,85 @@ ms.assetid: b47de82a-4c92-4af6-bceb-a5cb8bb8ede9 --- # How to: Choose between HTTP POST and HTTP GET requests for ASP.NET AJAX Endpoints -Windows Communication Foundation (WCF) allows you to create a service that exposes an ASP.NET AJAX-enabled endpoint that can be called from JavaScript on a client Web site. The basic procedures for building such services is discussed in [How to: Use Configuration to Add an ASP.NET AJAX Endpoint](how-to-use-configuration-to-add-an-aspnet-ajax-endpoint.md) and [How to: Add an ASP.NET AJAX Endpoint Without Using Configuration](how-to-add-an-aspnet-ajax-endpoint-without-using-configuration.md). - - ASP.NET AJAX supports operations that use the HTTP POST and HTTP GET verbs, with HTTP POST being the default. When creating an operation that has no side effects and returns data that rarely or never changes, use HTTP GET instead. Results of GET operations can be cached, which means that multiple calls to the same operation may result in only one request to your service. The caching is not done by WCF but can take place at any level (in a user's browser, on a proxy server, and other levels.) Caching is advantageous if you want to increase service performance, but may not be acceptable if data changes frequently or if the operation performs some action. - - For example, if you are designing service to manage a user's music library, an operation that looks up the artist based on an album's title benefits from using GET, but an operation that adds an album to the user's personal collection must use POST. - - To control the lifetime of the cache, use the type. For example, when designing a service that returns weather forecasts updated hourly, you would use GET but limit the cache duration to an hour or less to prevent the users of the service from accessing stale data. - - When using services from an ASP.NET AJAX page that use the Script Manager control, it makes no difference whether the operation uses GET or POST - the script manager mechanism ensures that the correct request type is issued. - - HTTP GET operations use any input parameters supported by POST operations, including complex data contract types. However, in most cases it is recommended to avoid too many parameters or parameters that are too complex in GET operations because it reduces caching efficiency. - - This topic demonstrates how to select between GET and POST by adding the or attributes to the relevant operations in the service contract. The other steps (to implement, configure and host the service) that are required to get the service running are similar to those used by any ASP.NET AJAX service in WCF. - - An operation marked with the always uses a GET request. An operation marked with the , or not marked with any of the two attributes, uses a POST request. The allows the use of other HTTP verbs, other than GET and POST (such as PUT and DELETE) through the property. However, these verbs are not supported by ASP.NET AJAX. If you intend to use the service from ASP.NET pages using the Script Manager control, do not use the property. - - For a working example of switching to GET, see the [Basic AJAX Service](../samples/basic-ajax-service.md) sample. - - For a sample that uses POST, see the [AJAX Service Using HTTP POST](../samples/ajax-service-using-http-post.md) sample. - +Windows Communication Foundation (WCF) allows you to create a service that exposes an ASP.NET AJAX-enabled endpoint that can be called from JavaScript on a client Web site. The basic procedures for building such services is discussed in [How to: Use Configuration to Add an ASP.NET AJAX Endpoint](how-to-use-configuration-to-add-an-aspnet-ajax-endpoint.md) and [How to: Add an ASP.NET AJAX Endpoint Without Using Configuration](how-to-add-an-aspnet-ajax-endpoint-without-using-configuration.md). + + ASP.NET AJAX supports operations that use the HTTP POST and HTTP GET verbs, with HTTP POST being the default. When creating an operation that has no side effects and returns data that rarely or never changes, use HTTP GET instead. Results of GET operations can be cached, which means that multiple calls to the same operation may result in only one request to your service. The caching is not done by WCF but can take place at any level (in a user's browser, on a proxy server, and other levels.) Caching is advantageous if you want to increase service performance, but may not be acceptable if data changes frequently or if the operation performs some action. + + For example, if you are designing service to manage a user's music library, an operation that looks up the artist based on an album's title benefits from using GET, but an operation that adds an album to the user's personal collection must use POST. + + To control the lifetime of the cache, use the type. For example, when designing a service that returns weather forecasts updated hourly, you would use GET but limit the cache duration to an hour or less to prevent the users of the service from accessing stale data. + + When using services from an ASP.NET AJAX page that use the Script Manager control, it makes no difference whether the operation uses GET or POST - the script manager mechanism ensures that the correct request type is issued. + + HTTP GET operations use any input parameters supported by POST operations, including complex data contract types. However, in most cases it is recommended to avoid too many parameters or parameters that are too complex in GET operations because it reduces caching efficiency. + + This topic demonstrates how to select between GET and POST by adding the or attributes to the relevant operations in the service contract. The other steps (to implement, configure and host the service) that are required to get the service running are similar to those used by any ASP.NET AJAX service in WCF. + + An operation marked with the always uses a GET request. An operation marked with the , or not marked with any of the two attributes, uses a POST request. The allows the use of other HTTP verbs, other than GET and POST (such as PUT and DELETE) through the property. However, these verbs are not supported by ASP.NET AJAX. If you intend to use the service from ASP.NET pages using the Script Manager control, do not use the property. + + For a working example of switching to GET, see the [Basic AJAX Service](../samples/basic-ajax-service.md) sample. + + For a sample that uses POST, see the [AJAX Service Using HTTP POST](../samples/ajax-service-using-http-post.md) sample. + ## To create a WCF service that responds to HTTP GET or HTTP POST requests - + 1. Define a basic WCF service contract with an interface marked with the attribute. Mark each operation with the . Add the attribute to stipulate that an operation should respond to HTTP GET requests. You can also add the attribute to explicitly specify HTTP POST, or not specify an attribute, which defaults to HTTP POST. - + ```csharp - [ServiceContract] - public interface IMusicService - { - //This operation uses a GET method. - [OperationContract] - [WebGet] - string LookUpArtist(string album); - - //This operation will use a POST method. - [OperationContract] - [WebInvoke] - void AddAlbum(string user, string album); - - //This operation will use POST method by default - //since nothing else is explicitly specified. - [OperationContract] - string[] GetAlbums(string user); - - //Other operations omitted… - - } - ``` - + [ServiceContract] + public interface IMusicService + { + //This operation uses a GET method. + [OperationContract] + [WebGet] + string LookUpArtist(string album); + + //This operation will use a POST method. + [OperationContract] + [WebInvoke] + void AddAlbum(string user, string album); + + //This operation will use POST method by default + //since nothing else is explicitly specified. + [OperationContract] + string[] GetAlbums(string user); + + //Other operations omitted… + + } + ``` + 2. Implement the `IMusicService` service contract with a `MusicService`. - + ```csharp - public class MusicService : IMusicService - { - public void AddAlbum(string user, string album) - { - //Add implementation here. - } - - //Other operations omitted… - } - ``` - -3. Create a new file named service with a .svc extension in the application. Edit this file by adding the appropriate [\@ServiceHost](../../configure-apps/file-schema/wcf-directive/servicehost.md) directive information for the service. Specify that the is to be used in the [\@ServiceHost](../../configure-apps/file-schema/wcf-directive/servicehost.md) directive to automatically configure an ASP.NET AJAX endpoint. - + public class MusicService : IMusicService + { + public void AddAlbum(string user, string album) + { + //Add implementation here. + } + + //Other operations omitted… + } + ``` + +3. Create a new file named service with a .svc extension in the application. Edit this file by adding the appropriate [\@ServiceHost](../../configure-apps/file-schema/wcf-directive/servicehost.md) directive information for the service. Specify that the is to be used in the [\@ServiceHost](../../configure-apps/file-schema/wcf-directive/servicehost.md) directive to automatically configure an ASP.NET AJAX endpoint. + ```aspx-csharp <%@ServiceHost language=c# Debug="true" - Service="Microsoft.Ajax.Samples.MusicService" - Factory=System.ServiceModel.Activation.WebScriptServiceHostFactory - %> - ``` - -## To call the service - + Service="Microsoft.Ajax.Samples.MusicService" + Factory=System.ServiceModel.Activation.WebScriptServiceHostFactory + %> + ``` + +## To call the service + 1. You can test your service's GET operations without any client code, by using the browser. For example, if your service is configured at the `http://example.com/service.svc` address, then typing `http://example.com/service.svc/LookUpArtist?album=SomeAlbum` into the browser address bar invokes the service and causes the response to be downloaded or displayed. - + 2. You can use services with GET operations in the same way as any other ASP.NET AJAX services - by entering the service URL into the Scripts collection of the ASP.NET AJAX Script Manager control. For an example, see the [Basic AJAX Service](../samples/basic-ajax-service.md). - + ## See also - [Creating WCF Services for ASP.NET AJAX](creating-wcf-services-for-aspnet-ajax.md) diff --git a/docs/framework/wcf/feature-details/importing-schema-to-generate-classes.md b/docs/framework/wcf/feature-details/importing-schema-to-generate-classes.md index 17252c6b4334a..bf375a043a276 100644 --- a/docs/framework/wcf/feature-details/importing-schema-to-generate-classes.md +++ b/docs/framework/wcf/feature-details/importing-schema-to-generate-classes.md @@ -2,190 +2,190 @@ description: "Learn more about: Importing Schema to Generate Classes" title: "Importing Schema to Generate Classes" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "WCF, schema import and export" - "XsdDataContractImporter class" ms.assetid: b9170583-8c34-43bd-97bb-6c0c8dddeee0 --- # Importing Schema to Generate Classes -To generate classes from schemas that are usable with Windows Communication Foundation (WCF), use the class. This topic describes the process and variations. - +To generate classes from schemas that are usable with Windows Communication Foundation (WCF), use the class. This topic describes the process and variations. + ## The Import Process - The schema import process starts with an and produces a . - - The `XmlSchemaSet` is a part of the .NET Framework’s Schema Object Model (SOM) that represents a set of XML Schema definition language (XSD) schema documents. To create an `XmlSchemaSet` object from a set of XSD documents, deserialize each document into an object (using the ) and add these objects to a new `XmlSchemaSet`. - - The `CodeCompileUnit` is part of the .NET Framework’s Code Document Object Model (CodeDOM) that represents .NET Framework code in an abstract way. To generate the actual code from a `CodeCompileUnit`, use a subclass of the class, such as the or class. - -### To import a schema - -1. Create an instance of the . - -2. Optional. Pass a `CodeCompileUnit` in the constructor. The types generated during schema import are added to this `CodeCompileUnit` instance instead of starting with a blank `CodeCompileUnit`. - -3. Optional. Call one of the methods. The method determines whether the given schema is a valid data contract schema and can be imported. The `CanImport` method has the same overloads as `Import` (the next step). - -4. Call one of the overloaded `Import` methods, for example, the method. - - The simplest overload takes an `XmlSchemaSet` and imports all types, including anonymous types, found in that schema set. Other overloads allow you to specify the XSD type or a list of types to import (in the form of an or a collection of `XmlQualifiedName` objects). In this case, only the specified types are imported. An overload takes an that imports a particular element out of the `XmlSchemaSet`, as well as its associated type (whether it is anonymous or not). This overload returns an `XmlQualifiedName`, which represents the data contract name of the type generated for this element. - - Multiple calls of the `Import` method result in multiple items being added to the same `CodeCompileUnit`. A type is not generated into the `CodeCompileUnit` if it already exists there. Call `Import` multiple times on the same `XsdDataContractImporter` instead of using multiple `XsdDataContractImporter` objects. This is the recommended way to avoid duplicate types being generated. - + The schema import process starts with an and produces a . + + The `XmlSchemaSet` is a part of the .NET Framework’s Schema Object Model (SOM) that represents a set of XML Schema definition language (XSD) schema documents. To create an `XmlSchemaSet` object from a set of XSD documents, deserialize each document into an object (using the ) and add these objects to a new `XmlSchemaSet`. + + The `CodeCompileUnit` is part of the .NET Framework’s Code Document Object Model (CodeDOM) that represents .NET Framework code in an abstract way. To generate the actual code from a `CodeCompileUnit`, use a subclass of the class, such as the or class. + +### To import a schema + +1. Create an instance of the . + +2. Optional. Pass a `CodeCompileUnit` in the constructor. The types generated during schema import are added to this `CodeCompileUnit` instance instead of starting with a blank `CodeCompileUnit`. + +3. Optional. Call one of the methods. The method determines whether the given schema is a valid data contract schema and can be imported. The `CanImport` method has the same overloads as `Import` (the next step). + +4. Call one of the overloaded `Import` methods, for example, the method. + + The simplest overload takes an `XmlSchemaSet` and imports all types, including anonymous types, found in that schema set. Other overloads allow you to specify the XSD type or a list of types to import (in the form of an or a collection of `XmlQualifiedName` objects). In this case, only the specified types are imported. An overload takes an that imports a particular element out of the `XmlSchemaSet`, as well as its associated type (whether it is anonymous or not). This overload returns an `XmlQualifiedName`, which represents the data contract name of the type generated for this element. + + Multiple calls of the `Import` method result in multiple items being added to the same `CodeCompileUnit`. A type is not generated into the `CodeCompileUnit` if it already exists there. Call `Import` multiple times on the same `XsdDataContractImporter` instead of using multiple `XsdDataContractImporter` objects. This is the recommended way to avoid duplicate types being generated. + > [!NOTE] - > If there is a failure during import, the `CodeCompileUnit` will be in an unpredictable state. Using a `CodeCompileUnit` resulting from a failed import could expose you to security vulnerabilities. - -5. Access the `CodeCompileUnit` through the property. - -### Import Options: Customizing the Generated Types - - You can set the property of the to an instance of the class to control various aspects of the import process. A number of options directly influence the types that are generated. - -#### Controlling the Access Level (GenerateInternal or the /internal switch) - - This corresponds to the **/internal** switch on the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). - - Normally, public types are generated from schema, with private fields and matching public data member properties. To generate internal types instead, set the property to `true`. - - The following example shows a schema transformed into an internal class when the property is set to `true.` - + > If there is a failure during import, the `CodeCompileUnit` will be in an unpredictable state. Using a `CodeCompileUnit` resulting from a failed import could expose you to security vulnerabilities. + +5. Access the `CodeCompileUnit` through the property. + +### Import Options: Customizing the Generated Types + + You can set the property of the to an instance of the class to control various aspects of the import process. A number of options directly influence the types that are generated. + +#### Controlling the Access Level (GenerateInternal or the /internal switch) + + This corresponds to the **/internal** switch on the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). + + Normally, public types are generated from schema, with private fields and matching public data member properties. To generate internal types instead, set the property to `true`. + + The following example shows a schema transformed into an internal class when the property is set to `true.` + [!code-csharp[c_SchemaImportExport#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/cs/source.cs#2)] - [!code-vb[c_SchemaImportExport#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_schemaimportexport/vb/source.vb#2)] - -#### Controlling Namespaces (Namespaces or the /namespace switch) - - This corresponds to the **/namespace** switch on the `Svcutil.exe` tool. - - Normally, types generated from schema are generated into .NET Framework namespaces, with each XSD namespace corresponding to a particular .NET Framework namespace according to a mapping described in [Data Contract Schema Reference](data-contract-schema-reference.md). You can customize this mapping by the property to a . If a given XSD namespace is found in the dictionary, the matching .NET Framework namespace is also taken from your dictionary. - - For example, consider the following schema. - - [!code-xml[c_SchemaImportExport#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/common/source.config#10)] - - The following example uses the `Namespaces` property to map the `http://schemas.contoso.com/carSchema` namespace to "Contoso.Cars". - + [!code-vb[c_SchemaImportExport#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_schemaimportexport/vb/source.vb#2)] + +#### Controlling Namespaces (Namespaces or the /namespace switch) + + This corresponds to the **/namespace** switch on the `Svcutil.exe` tool. + + Normally, types generated from schema are generated into .NET Framework namespaces, with each XSD namespace corresponding to a particular .NET Framework namespace according to a mapping described in [Data Contract Schema Reference](data-contract-schema-reference.md). You can customize this mapping by the property to a . If a given XSD namespace is found in the dictionary, the matching .NET Framework namespace is also taken from your dictionary. + + For example, consider the following schema. + + [!code-xml[c_SchemaImportExport#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/common/source.config#10)] + + The following example uses the `Namespaces` property to map the `http://schemas.contoso.com/carSchema` namespace to "Contoso.Cars". + [!code-csharp[c_SchemaImportExport#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/cs/source.cs#8)] - [!code-vb[c_SchemaImportExport#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_schemaimportexport/vb/source.vb#8)] - -#### Adding the SerializableAttribute (GenerateSerializable or the /serializable switch) - - This corresponds to the **/serializable** switch on the `Svcutil.exe` tool. - - Sometimes it is important for the types generated from the schema to be usable with .NET Framework runtime serialization engines. This is useful when using types for .NET Framework remoting. To enable this, you must apply the attribute to the generated types in addition to the regular attribute. The attribute is generated automatically if the `GenerateSerializable` import option is set to `true`. - - The following example shows the `Vehicle` class generated with the `GenerateSerializable` import option set to `true`. - + [!code-vb[c_SchemaImportExport#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_schemaimportexport/vb/source.vb#8)] + +#### Adding the SerializableAttribute (GenerateSerializable or the /serializable switch) + + This corresponds to the **/serializable** switch on the `Svcutil.exe` tool. + + Sometimes it is important for the types generated from the schema to be usable with .NET Framework runtime serialization engines. This is useful when using types for .NET Framework remoting. To enable this, you must apply the attribute to the generated types in addition to the regular attribute. The attribute is generated automatically if the `GenerateSerializable` import option is set to `true`. + + The following example shows the `Vehicle` class generated with the `GenerateSerializable` import option set to `true`. + [!code-csharp[c_SchemaImportExport#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/cs/source.cs#4)] - [!code-vb[c_SchemaImportExport#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_schemaimportexport/vb/source.vb#4)] - -#### Adding Data Binding Support (EnableDataBinding or the /enableDataBinding switch) - - This corresponds to the **/enableDataBinding** switch on the Svcutil.exe tool. - - Sometimes, you may want to bind the types generated from the schema to graphical user interface components so that any update to instances of these types will automatically update the UI. The `XsdDataContractImporter` can generate types that implement the interface in such a way that any property change triggers an event. If you are generating types for use with a client UI programming environment that supports this interface (such as Windows Presentation Foundation (WPF)), set the property to `true` to enable this feature. - - The following example shows the `Vehicle` class generated with the set to `true`. - + [!code-vb[c_SchemaImportExport#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_schemaimportexport/vb/source.vb#4)] + +#### Adding Data Binding Support (EnableDataBinding or the /enableDataBinding switch) + + This corresponds to the **/enableDataBinding** switch on the Svcutil.exe tool. + + Sometimes, you may want to bind the types generated from the schema to graphical user interface components so that any update to instances of these types will automatically update the UI. The `XsdDataContractImporter` can generate types that implement the interface in such a way that any property change triggers an event. If you are generating types for use with a client UI programming environment that supports this interface (such as Windows Presentation Foundation (WPF)), set the property to `true` to enable this feature. + + The following example shows the `Vehicle` class generated with the set to `true`. + [!code-csharp[C_SchemaImportExport#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/cs/source.cs#5)] - [!code-vb[C_SchemaImportExport#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_schemaimportexport/vb/source.vb#5)] - -### Import Options: Choosing Collection Types - - Two special patterns in XML represent collections of items: lists of items and associations between one item and another. The following is an example of a list of strings. - - [!code-xml[C_SchemaImportExport#11](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/common/source.config#11)] - - The following is an example of an association between a string and an integer (`city name` and `population`). - - [!code-xml[C_SchemaImportExport#12](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/common/source.config#12)] - + [!code-vb[C_SchemaImportExport#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_schemaimportexport/vb/source.vb#5)] + +### Import Options: Choosing Collection Types + + Two special patterns in XML represent collections of items: lists of items and associations between one item and another. The following is an example of a list of strings. + + [!code-xml[C_SchemaImportExport#11](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/common/source.config#11)] + + The following is an example of an association between a string and an integer (`city name` and `population`). + + [!code-xml[C_SchemaImportExport#12](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/common/source.config#12)] + > [!NOTE] -> Any association could also be considered a list. For example, you can view the preceding association as a list of complex `city` objects that happen to have two fields (a string field and an integer field). Both patterns have a representation in the XSD Schema. There is no way to differentiate between a list and an association, so such patterns are always treated as lists unless a special annotation specific to WCF is present in the schema. The annotation indicates that a given pattern represents an association. For more information, see [Data Contract Schema Reference](data-contract-schema-reference.md). - - Normally, a list is imported as a collection data contract that derives from a Generic List or as a .NET Framework array, depending on whether or not the schema follows the standard naming pattern for collections. This is described in more detail in [Collection Types in Data Contracts](collection-types-in-data-contracts.md). Associations are normally imported as either a or a collection data contract that derives from the dictionary object. For example, consider the following schema. - - [!code-xml[c_SchemaImportExport#13](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/common/source.config#13)] - - This would be imported as follows (fields are shown instead of properties for readability). - +> Any association could also be considered a list. For example, you can view the preceding association as a list of complex `city` objects that happen to have two fields (a string field and an integer field). Both patterns have a representation in the XSD Schema. There is no way to differentiate between a list and an association, so such patterns are always treated as lists unless a special annotation specific to WCF is present in the schema. The annotation indicates that a given pattern represents an association. For more information, see [Data Contract Schema Reference](data-contract-schema-reference.md). + + Normally, a list is imported as a collection data contract that derives from a Generic List or as a .NET Framework array, depending on whether or not the schema follows the standard naming pattern for collections. This is described in more detail in [Collection Types in Data Contracts](collection-types-in-data-contracts.md). Associations are normally imported as either a or a collection data contract that derives from the dictionary object. For example, consider the following schema. + + [!code-xml[c_SchemaImportExport#13](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/common/source.config#13)] + + This would be imported as follows (fields are shown instead of properties for readability). + [!code-csharp[c_SchemaImportExport#6](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/cs/source.cs#6)] - [!code-vb[c_SchemaImportExport#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_schemaimportexport/vb/source.vb#6)] - - It is possible to customize the collection types that are generated for such schema patterns. For example, you may want to generate collections deriving from the instead of the class in order to bind the type to a list box and have it be automatically updated when the contents of the collection change. To do this, set the property of the class to a list of collection types to be used (hereafter known as the referenced types). When importing any collection, this list of referenced collection types is scanned and the best-matching collection is used if one is found. Associations are matched only against types that implement either the generic or the nongeneric interface, while lists are matched against any supported collection type. - - For example, if the property is set to a , the `people` type in the preceding example is generated as follows. - + [!code-vb[c_SchemaImportExport#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_schemaimportexport/vb/source.vb#6)] + + It is possible to customize the collection types that are generated for such schema patterns. For example, you may want to generate collections deriving from the instead of the class in order to bind the type to a list box and have it be automatically updated when the contents of the collection change. To do this, set the property of the class to a list of collection types to be used (hereafter known as the referenced types). When importing any collection, this list of referenced collection types is scanned and the best-matching collection is used if one is found. Associations are matched only against types that implement either the generic or the nongeneric interface, while lists are matched against any supported collection type. + + For example, if the property is set to a , the `people` type in the preceding example is generated as follows. + [!code-csharp[C_SchemaImportExport#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_schemaimportexport/cs/source.cs#7)] - [!code-vb[C_SchemaImportExport#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_schemaimportexport/vb/source.vb#7)] - - A closed generic is considered the best match. For example, if the types `BindingList(Of Integer)` and are passed to the collection of referenced types, any lists of integers found in schema are imported as a `BindingList(Of Integer)`. Any other lists, for example, a `List(Of String)`, are imported as an `ArrayList`. - - If a type that implements the generic `IDictionary` interface is added to the collection of referenced types, its type parameters must either be fully open or fully closed. - - Duplicates are not allowed. For example, you cannot add both a `List(Of Integer)` and a `Collection(Of Integer)` to the referenced types. That would make it impossible to determine which should be used when a list of integers is found in schema. Duplicates will be detected only if there is a type in schema that exposes the duplicates problem. For example, if the imported schema does not contain lists of integers, it is allowed to have both the `List(Of Integer)` and the `Collection(Of Integer)` in the referenced types collection, but neither will have any effect. - - The referenced collection types mechanism works equally well for collections of complex types (including collections of other collections), and not just for collections of primitives. - - The `ReferencedCollectionTypes` property corresponds to the **/collectionType** switch on the SvcUtil.exe tool. Note that to reference multiple collection types, the **/collectionType** switch must be specified multiple times. If the type is not in the MsCorLib.dll, its assembly must also be referenced using the **/reference** switch. - -#### Import Options: Referencing Existing Types - - Occasionally, types in schema correspond to existing .NET Framework types, and there is no need to generate these types from scratch. (This section applies only to noncollection types. For collection types, see the preceding section.) - - For example, you may have a standard company-wide "Person" data contract type that you always want used when representing a person. Whenever some service makes use of this type, and its schema appears in the service metadata, you may want to reuse the existing `Person` type when importing this schema instead of generating a new one for every service. - - To do this, pass a list of .NET Framework types that you want to reuse into the collection the property returns on the class. If any of these types have a data contract name and namespace that matches the name and namespace of a schema type, a structural comparison is performed. If it is determined that the types have both matching names and matching structures, the existing .NET Framework type is reused instead of generating a new one. If only the name matches but not the structure, an exception is thrown. Note that there is no allowance for versioning when referencing types (for example, adding new optional data members). The structures must match exactly. - - It is legal to add multiple types with the same data contract name and namespace to the referenced types collection, as long as no schema types are imported with that name and namespace. This allows you to easily add all the types in an assembly to the collection without worrying about duplicates for types that do not actually occur in schema. - - The `ReferencedTypes` property corresponds to the **/reference** switch in certain modes of operation of the Svcutil.exe tool. - + [!code-vb[C_SchemaImportExport#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_schemaimportexport/vb/source.vb#7)] + + A closed generic is considered the best match. For example, if the types `BindingList(Of Integer)` and are passed to the collection of referenced types, any lists of integers found in schema are imported as a `BindingList(Of Integer)`. Any other lists, for example, a `List(Of String)`, are imported as an `ArrayList`. + + If a type that implements the generic `IDictionary` interface is added to the collection of referenced types, its type parameters must either be fully open or fully closed. + + Duplicates are not allowed. For example, you cannot add both a `List(Of Integer)` and a `Collection(Of Integer)` to the referenced types. That would make it impossible to determine which should be used when a list of integers is found in schema. Duplicates will be detected only if there is a type in schema that exposes the duplicates problem. For example, if the imported schema does not contain lists of integers, it is allowed to have both the `List(Of Integer)` and the `Collection(Of Integer)` in the referenced types collection, but neither will have any effect. + + The referenced collection types mechanism works equally well for collections of complex types (including collections of other collections), and not just for collections of primitives. + + The `ReferencedCollectionTypes` property corresponds to the **/collectionType** switch on the SvcUtil.exe tool. Note that to reference multiple collection types, the **/collectionType** switch must be specified multiple times. If the type is not in the MsCorLib.dll, its assembly must also be referenced using the **/reference** switch. + +#### Import Options: Referencing Existing Types + + Occasionally, types in schema correspond to existing .NET Framework types, and there is no need to generate these types from scratch. (This section applies only to noncollection types. For collection types, see the preceding section.) + + For example, you may have a standard company-wide "Person" data contract type that you always want used when representing a person. Whenever some service makes use of this type, and its schema appears in the service metadata, you may want to reuse the existing `Person` type when importing this schema instead of generating a new one for every service. + + To do this, pass a list of .NET Framework types that you want to reuse into the collection the property returns on the class. If any of these types have a data contract name and namespace that matches the name and namespace of a schema type, a structural comparison is performed. If it is determined that the types have both matching names and matching structures, the existing .NET Framework type is reused instead of generating a new one. If only the name matches but not the structure, an exception is thrown. Note that there is no allowance for versioning when referencing types (for example, adding new optional data members). The structures must match exactly. + + It is legal to add multiple types with the same data contract name and namespace to the referenced types collection, as long as no schema types are imported with that name and namespace. This allows you to easily add all the types in an assembly to the collection without worrying about duplicates for types that do not actually occur in schema. + + The `ReferencedTypes` property corresponds to the **/reference** switch in certain modes of operation of the Svcutil.exe tool. + > [!NOTE] -> When using the Svcutil.exe or (in Visual Studio) the **Add Service Reference** tools, all of the types in MsCorLib.dll are automatically referenced. - -#### Import Options: Importing Non-DataContract Schema as IXmlSerializable types - - The supports a limited subset of the schema. If unsupported schema constructs are present (for example, XML attributes), the import attempt fails with an exception. However, setting the property to `true` extends the range of schema supported. When set to `true`, the generates types that implement the interface. This enables direct access to the XML representation of these types. - -##### Design Considerations - -- It may be difficult to work with the weakly typed XML representation directly. Consider using an alternative serialization engine, such as the , to work with schema not compatible with data contracts in a strongly typed way. For more information, see [Using the XmlSerializer Class](using-the-xmlserializer-class.md). - -- Some schema constructs cannot be imported by the even when the property is set to `true`. Again, consider using the for such cases. - -- The exact schema constructs that are supported both when is `true` or `false` are described in [Data Contract Schema Reference](data-contract-schema-reference.md). - -- Schema for generated types do not retain fidelity when imported and exported. That is, exporting the schema from the generated types and importing as classes does not return the original schema. - - It is possible to combine the option with the option previously described. For types that have to be generated as implementations, the structural check is skipped when using the feature. - - The option corresponds to the **/importXmlTypes** switch on the Svcutil.exe tool. - -##### Working with Generated IXmlSerializable Types - - The generated `IXmlSerializable` types contain a private field, named "nodesField," that returns an array of objects. When deserializing an instance of such a type, you can access the XML data directly through this field by using the XML Document Object Model. When serializing an instance of this type, you can set this field to the desired XML data and it will be serialized. - - This is accomplished through the `IXmlSerializable` implementation. In the generated `IXmlSerializable` type, the implementation calls the method of the class. The method is a helper method that converts XML provided through an to an array of objects. The implementation does the opposite and converts the array of `XmlNode` objects to a sequence of calls. This is accomplished using the method. - - It is possible to run the schema export process on the generated `IXmlSerializable` classes. As previously stated, you will not get the original schema back. Instead, you will get the "anyType" standard XSD type, which is a wildcard for any XSD type. - - This is accomplished by applying the attribute to the generated `IXmlSerializable` classes and specifying a method that calls the method to generate the "anyType" type. - +> When using the Svcutil.exe or (in Visual Studio) the **Add Service Reference** tools, all of the types in MsCorLib.dll are automatically referenced. + +#### Import Options: Importing Non-DataContract Schema as IXmlSerializable types + + The supports a limited subset of the schema. If unsupported schema constructs are present (for example, XML attributes), the import attempt fails with an exception. However, setting the property to `true` extends the range of schema supported. When set to `true`, the generates types that implement the interface. This enables direct access to the XML representation of these types. + +##### Design Considerations + +- It may be difficult to work with the weakly typed XML representation directly. Consider using an alternative serialization engine, such as the , to work with schema not compatible with data contracts in a strongly typed way. For more information, see [Using the XmlSerializer Class](using-the-xmlserializer-class.md). + +- Some schema constructs cannot be imported by the even when the property is set to `true`. Again, consider using the for such cases. + +- The exact schema constructs that are supported both when is `true` or `false` are described in [Data Contract Schema Reference](data-contract-schema-reference.md). + +- Schema for generated types do not retain fidelity when imported and exported. That is, exporting the schema from the generated types and importing as classes does not return the original schema. + + It is possible to combine the option with the option previously described. For types that have to be generated as implementations, the structural check is skipped when using the feature. + + The option corresponds to the **/importXmlTypes** switch on the Svcutil.exe tool. + +##### Working with Generated IXmlSerializable Types + + The generated `IXmlSerializable` types contain a private field, named "nodesField," that returns an array of objects. When deserializing an instance of such a type, you can access the XML data directly through this field by using the XML Document Object Model. When serializing an instance of this type, you can set this field to the desired XML data and it will be serialized. + + This is accomplished through the `IXmlSerializable` implementation. In the generated `IXmlSerializable` type, the implementation calls the method of the class. The method is a helper method that converts XML provided through an to an array of objects. The implementation does the opposite and converts the array of `XmlNode` objects to a sequence of calls. This is accomplished using the method. + + It is possible to run the schema export process on the generated `IXmlSerializable` classes. As previously stated, you will not get the original schema back. Instead, you will get the "anyType" standard XSD type, which is a wildcard for any XSD type. + + This is accomplished by applying the attribute to the generated `IXmlSerializable` classes and specifying a method that calls the method to generate the "anyType" type. + > [!NOTE] -> The type exists solely to support this particular feature. It is not recommended for use for any other purpose. - -#### Import Options: Advanced Options - - The following are advanced import options: - -- property. Specify the to use to generate the code for the generated classes. The import mechanism attempts to avoid features that the does not support. If the is not set, the full set of .NET Framework features is used with no restrictions. - -- property. An implementation can be specified with this property. The customizes the import process. For more information, see [Data Contract Surrogates](../extending/data-contract-surrogates.md). By default, no surrogate is used. - +> The type exists solely to support this particular feature. It is not recommended for use for any other purpose. + +#### Import Options: Advanced Options + + The following are advanced import options: + +- property. Specify the to use to generate the code for the generated classes. The import mechanism attempts to avoid features that the does not support. If the is not set, the full set of .NET Framework features is used with no restrictions. + +- property. An implementation can be specified with this property. The customizes the import process. For more information, see [Data Contract Surrogates](../extending/data-contract-surrogates.md). By default, no surrogate is used. + ## See also - diff --git a/docs/framework/wcf/feature-details/information-disclosure.md b/docs/framework/wcf/feature-details/information-disclosure.md index d585aa3e1aa56..c08777a3b27a1 100644 --- a/docs/framework/wcf/feature-details/information-disclosure.md +++ b/docs/framework/wcf/feature-details/information-disclosure.md @@ -40,7 +40,7 @@ Mitigations include the following: ## NTLM -By default, in the Windows domain environment, Windows authentication uses the Kerberos protocol to authenticate and authorize users. If the Kerberos protocol cannot be used for some reason, NT LAN Manager (NTLM) is used as a fallback. You can disable this behavior by setting the property to `false`. Issues to be aware of when allowing NTLM include: +By default, in the Windows domain environment, Windows authentication uses the Kerberos protocol to authenticate and authorize users. If the Kerberos protocol cannot be used for some reason, NT LAN Manager (NTLM) is used as a fallback. You can disable this behavior by setting the property to `false`. Issues to be aware of when allowing NTLM include: - NTLM exposes the client user name. If the user name needs to be kept confidential, then set the `AllowNTLM` property on the binding to `false`. diff --git a/docs/framework/wcf/feature-details/integrating-enterprise-services-transactional-components.md b/docs/framework/wcf/feature-details/integrating-enterprise-services-transactional-components.md index ca9c44349b882..3dccb06b1b5e9 100644 --- a/docs/framework/wcf/feature-details/integrating-enterprise-services-transactional-components.md +++ b/docs/framework/wcf/feature-details/integrating-enterprise-services-transactional-components.md @@ -6,90 +6,90 @@ ms.assetid: 05dab277-b8b2-48cf-b40c-826be128b175 --- # Integrating Enterprise Services Transactional Components -Windows Communication Foundation (WCF) provides an automatic mechanism for integrating with Enterprise Services (see [Integrating with COM+ Applications](integrating-with-com-plus-applications.md)). However, you may want the flexibility to develop services that internally use transactional components hosted within Enterprise Services. Because the WCF Transactions feature is built on the infrastructure, the process for integrating Enterprise Services with WCF is identical to that for specifying interoperability between and Enterprise Services, as outlined in [Interoperability with Enterprise Services and COM+ Transactions](/previous-versions/dotnet/netframework-3.0/ms229974(v=vs.85)). - - To provide the desired level of interoperability between the incoming flowed transaction and the COM+ context transaction, the service implementation must create a instance and use the appropriate value from the enumeration. - -## Integrating Enterprise Services with a Service Operation - - The following code demonstrates an operation, with Allowed transaction flow, that creates a with the option. The following conditions apply in this scenario: - -- If the client flows a transaction, the operation, including the call to the Enterprise Services component, is executed within the scope of that transaction. Using ensures that the transaction is synchronized with the context, which means that the ambient transaction for and the is the same. - -- If the client does not flow a transaction, setting to `true` creates a new transaction scope for the operation. Similarly, using ensures that the operation’s transaction is the same as the transaction used inside the component's context. - - Any additional method calls also occur within the scope of the same operation’s transaction. - +Windows Communication Foundation (WCF) provides an automatic mechanism for integrating with Enterprise Services (see [Integrating with COM+ Applications](integrating-with-com-plus-applications.md)). However, you may want the flexibility to develop services that internally use transactional components hosted within Enterprise Services. Because the WCF Transactions feature is built on the infrastructure, the process for integrating Enterprise Services with WCF is identical to that for specifying interoperability between and Enterprise Services, as outlined in [Interoperability with Enterprise Services and COM+ Transactions](/previous-versions/dotnet/netframework-3.0/ms229974(v=vs.85)). + + To provide the desired level of interoperability between the incoming flowed transaction and the COM+ context transaction, the service implementation must create a instance and use the appropriate value from the enumeration. + +## Integrating Enterprise Services with a Service Operation + + The following code demonstrates an operation, with Allowed transaction flow, that creates a with the option. The following conditions apply in this scenario: + +- If the client flows a transaction, the operation, including the call to the Enterprise Services component, is executed within the scope of that transaction. Using ensures that the transaction is synchronized with the context, which means that the ambient transaction for and the is the same. + +- If the client does not flow a transaction, setting to `true` creates a new transaction scope for the operation. Similarly, using ensures that the operation’s transaction is the same as the transaction used inside the component's context. + + Any additional method calls also occur within the scope of the same operation’s transaction. + ```csharp -[ServiceContract()] -public interface ICustomerServiceContract -{ - [OperationContract] - [TransactionFlow(TransactionFlowOption.Allowed)] - void UpdateCustomerNameOperation(int customerID, string newCustomerName); -} - -[ServiceBehavior(TransactionIsolationLevel = System.Transactions.IsolationLevel.Serializable)] -public class CustomerService : ICustomerServiceContract -{ - [OperationBehavior(TransactionScopeRequired = true, TransactionAutoComplete = true)] - public void UpdateCustomerNameOperation(int customerID, string newCustomerName) - { - // Create a transaction scope with full ES interop - using (TransactionScope ts = new TransactionScope( - TransactionScopeOption.Required, - new TransactionOptions(), - EnterpriseServicesInteropOption.Full)) - { - // Create an Enterprise Services component +[ServiceContract()] +public interface ICustomerServiceContract +{ + [OperationContract] + [TransactionFlow(TransactionFlowOption.Allowed)] + void UpdateCustomerNameOperation(int customerID, string newCustomerName); +} + +[ServiceBehavior(TransactionIsolationLevel = System.Transactions.IsolationLevel.Serializable)] +public class CustomerService : ICustomerServiceContract +{ + [OperationBehavior(TransactionScopeRequired = true, TransactionAutoComplete = true)] + public void UpdateCustomerNameOperation(int customerID, string newCustomerName) + { + // Create a transaction scope with full ES interop + using (TransactionScope ts = new TransactionScope( + TransactionScopeOption.Required, + new TransactionOptions(), + EnterpriseServicesInteropOption.Full)) + { + // Create an Enterprise Services component // Call UpdateCustomer method on an Enterprise Services // component - + // Call UpdateOtherCustomerData method on an Enterprise // Services component - ts.Complete(); - } - - // Do UpdateAdditionalData on an non-Enterprise Services - // component - } -} -``` - - If no synchronization is required between an operation’s current transaction and calls to transactional Enterprise Services components, then use the option when instantiating the instance. - -## Integrating Enterprise Services with a Client - - The following code demonstrates client code using a instance with the setting. In this scenario, calls to service operations that support transaction flow occur within the scope of the same transaction as the calls to Enterprise Services components. - + ts.Complete(); + } + + // Do UpdateAdditionalData on an non-Enterprise Services + // component + } +} +``` + + If no synchronization is required between an operation’s current transaction and calls to transactional Enterprise Services components, then use the option when instantiating the instance. + +## Integrating Enterprise Services with a Client + + The following code demonstrates client code using a instance with the setting. In this scenario, calls to service operations that support transaction flow occur within the scope of the same transaction as the calls to Enterprise Services components. + ```csharp -static void Main() -{ - // Create a client - CalculatorClient client = new CalculatorClient(); - - // Create a transaction scope with full ES interop - using (TransactionScope ts = new TransactionScope( - TransactionScopeOption.Required, - new TransactionOptions(), - EnterpriseServicesInteropOption.Full)) - { - // Call Add calculator service operation - - // Create an Enterprise Services component - +static void Main() +{ + // Create a client + CalculatorClient client = new CalculatorClient(); + + // Create a transaction scope with full ES interop + using (TransactionScope ts = new TransactionScope( + TransactionScopeOption.Required, + new TransactionOptions(), + EnterpriseServicesInteropOption.Full)) + { + // Call Add calculator service operation + + // Create an Enterprise Services component + // Call UpdateCustomer method on an Enterprise Services // component - - ts.Complete(); - } - + + ts.Complete(); + } + // Closing the client gracefully closes the connection and - // cleans up resources - client.Close(); -} -``` - + // cleans up resources + client.Close(); +} +``` + ## See also - [Integrating with COM+ Applications](integrating-with-com-plus-applications.md) diff --git a/docs/framework/wcf/feature-details/integrating-with-com-plus-applications-overview.md b/docs/framework/wcf/feature-details/integrating-with-com-plus-applications-overview.md index 804ca57fd60bc..43b4a3ed07432 100644 --- a/docs/framework/wcf/feature-details/integrating-with-com-plus-applications-overview.md +++ b/docs/framework/wcf/feature-details/integrating-with-com-plus-applications-overview.md @@ -81,7 +81,7 @@ Windows Communication Foundation (WCF) provides a rich environment for creating - Web-hosted - The Web service is hosted within a Web server worker process. This mode does not require COM+ to be active when the initial request is received. If the application is not active when this request is received, it is automatically activated prior to processing the request. This mode also provides both Web service and DCOM access to the server application, but causes a process hop for Web service requests. This typically requires the client to enable impersonation. In WCF, this can be done with the property of the class, which is accessed as a property of the generic class, as well as the enumeration value. + The Web service is hosted within a Web server worker process. This mode does not require COM+ to be active when the initial request is received. If the application is not active when this request is received, it is automatically activated prior to processing the request. This mode also provides both Web service and DCOM access to the server application, but causes a process hop for Web service requests. This typically requires the client to enable impersonation. In WCF, this can be done with the property of the class, which is accessed as a property of the generic class, as well as the enumeration value. - Web-hosted in-process diff --git a/docs/framework/wcf/feature-details/interoperability-with-pox-applications.md b/docs/framework/wcf/feature-details/interoperability-with-pox-applications.md index 7b45eba1239df..9daee74e48d6a 100644 --- a/docs/framework/wcf/feature-details/interoperability-with-pox-applications.md +++ b/docs/framework/wcf/feature-details/interoperability-with-pox-applications.md @@ -6,11 +6,11 @@ ms.assetid: 449276b8-4633-46f0-85c9-81f01d127636 --- # Interoperability with POX applications -"Plain Old XML" (POX) applications communicate by exchanging raw HTTP messages that contain only XML application data that is not enclosed within a SOAP envelope. Windows Communication Foundation (WCF) can provide both services and clients that use POX messages. On the service, WCF can be used to implement services that expose endpoints to clients such as Web browsers and scripting languages that send and receive POX messages. On the client, the WCF programming model can be used to implement clients that communicate with POX-based services. - +"Plain Old XML" (POX) applications communicate by exchanging raw HTTP messages that contain only XML application data that is not enclosed within a SOAP envelope. Windows Communication Foundation (WCF) can provide both services and clients that use POX messages. On the service, WCF can be used to implement services that expose endpoints to clients such as Web browsers and scripting languages that send and receive POX messages. On the client, the WCF programming model can be used to implement clients that communicate with POX-based services. + > [!NOTE] > This document was originally written for .NET Framework 3.0. .NET Framework 3.5 has built-in support for working with POX applications. For more information about see [WCF Web HTTP Programming Model](wcf-web-http-programming-model.md). - + ## POX programming with WCF WCF services that communicate over HTTP using POX messages use a [\](../../configure-apps/file-schema/wcf/custombinding.md). @@ -30,7 +30,7 @@ This custom binding contains two elements: - [\](../../configure-apps/file-schema/wcf/textmessageencoding.md) -The standard WCF Text Message Encoder is specially configured to use the value, which allows it to process XML message payloads that do not arrive wrapped in a SOAP envelope. +The standard WCF Text Message Encoder is specially configured to use the value, which allows it to process XML message payloads that do not arrive wrapped in a SOAP envelope. WCF clients that communicate over HTTP using POX messages use a similar binding (shown in the following imperative code). @@ -45,14 +45,14 @@ private static Binding CreatePoxBinding() } ``` -Because POX clients must explicitly specify the URIs to which they send messages, they usually must configure the to a manual addressing mode by setting the property to `true` on the element. This allows messages to be addressed explicitly by application code and it is not necessary to create a new every time an application sends a message to a different HTTP URI. +Because POX clients must explicitly specify the URIs to which they send messages, they usually must configure the to a manual addressing mode by setting the property to `true` on the element. This allows messages to be addressed explicitly by application code and it is not necessary to create a new every time an application sends a message to a different HTTP URI. Because POX messages do not use SOAP headers to convey important protocol information, POX clients and services often must manipulate pieces of the underlying HTTP request used to send or receive a message. HTTP-specific protocol information such as the HTTP headers and status codes are surfaced in the WCF programming model through two classes: - , which contains information about the HTTP request, such as the HTTP method and request headers. - , which contains information about the HTTP response, such as the HTTP status code and status description, as well as any HTTP response headers. - + The following code example shows how to create an HTTP GET request message that is addressed to `http://localhost:8100/customers`. ```csharp @@ -65,6 +65,6 @@ property.SuppressEntityBody = true; request.Properties.Add( HttpRequestMessageProperty.Name, property ); ``` -First, an empty request is created by calling . The parameter is used to indicate that a SOAP envelope is not required and parameter is passed as the Action. The request message is then addressed by setting header to the desired URI. Next, an is created and the is set to the HTTP verb GET method and the is set to `true` to indicate that no data should be sent in the body of the outgoing HTTP request message. Finally, the request property is added to the collection of the request message so it can influence how the HTTP Transport sends the request. The message is then ready to be sent over an appropriate instance of the . +First, an empty request is created by calling . The parameter is used to indicate that a SOAP envelope is not required and parameter is passed as the Action. The request message is then addressed by setting header to the desired URI. Next, an is created and the is set to the HTTP verb GET method and the is set to `true` to indicate that no data should be sent in the body of the outgoing HTTP request message. Finally, the request property is added to the collection of the request message so it can influence how the HTTP Transport sends the request. The message is then ready to be sent over an appropriate instance of the . Similar techniques can be used on the service to extract the from an incoming message and construct a response. diff --git a/docs/framework/wcf/feature-details/interoperable-object-references.md b/docs/framework/wcf/feature-details/interoperable-object-references.md index aaefb07a9dbea..14058d15ec621 100644 --- a/docs/framework/wcf/feature-details/interoperable-object-references.md +++ b/docs/framework/wcf/feature-details/interoperable-object-references.md @@ -6,81 +6,81 @@ ms.assetid: cb8da4c8-08ca-4220-a16b-e04c8f527f1b --- # Interoperable object references -By default, serializes objects by value. You can use the property to instruct the data contract serializer to preserve object references when serializing objects. - -## Generated XML - - As an example, consider the following object: - -```csharp -[DataContract] -public class X -{ - SomeClass someInstance = new SomeClass(); - [DataMember] - public SomeClass A = someInstance; - [DataMember] - public SomeClass B = someInstance; -} - +By default, serializes objects by value. You can use the property to instruct the data contract serializer to preserve object references when serializing objects. + +## Generated XML + + As an example, consider the following object: + +```csharp +[DataContract] +public class X +{ + SomeClass someInstance = new SomeClass(); + [DataMember] + public SomeClass A = someInstance; + [DataMember] + public SomeClass B = someInstance; +} + public class SomeClass -{ -} -``` - - With set to `false` (the default), the following XML is generated: - -```xml - - contents of someInstance - contents of someInstance - -``` - - With set to `true`, the following XML is generated: - -```xml - - contents of someInstance - - -``` - - However, doesn't describe the `id` and `ref` attributes in its schema, even when the `preserveObjectReferences` property is set to `true`. - -## Using IsReference - - To generate object reference information that's valid according to the schema that describes it, apply the attribute to a type, and set the flag to `true`. The following example modifies class `X` in the previous example by adding `IsReference`: - +{ +} +``` + + With set to `false` (the default), the following XML is generated: + +```xml + + contents of someInstance + contents of someInstance + +``` + + With set to `true`, the following XML is generated: + +```xml + + contents of someInstance + + +``` + + However, doesn't describe the `id` and `ref` attributes in its schema, even when the `preserveObjectReferences` property is set to `true`. + +## Using IsReference + + To generate object reference information that's valid according to the schema that describes it, apply the attribute to a type, and set the flag to `true`. The following example modifies class `X` in the previous example by adding `IsReference`: + ```csharp [DataContract(IsReference=true)] public class X -{ +{ SomeClass someInstance = new SomeClass(); [DataMember] public SomeClass A = someInstance; [DataMember] public SomeClass B = someInstance; } - + public class SomeClass { -} +} ```` - The generated XML is as follows: + The generated XML is as follows: ```xml - + - contents of A + contents of A - + -``` - - Using `IsReference` ensures compliance on message round-tripping. Without it, when a type is generated from schema, the XML output for that type isn't necessarily compatible with the schema originally assumed. In other words, although the `id` and `ref` attributes were serialized, the original schema could have barred these attributes (or all attributes) from occurring in the XML. With `IsReference` applied to a data member, the member continues to be recognized as *referenceable* when round-tripped. - +``` + + Using `IsReference` ensures compliance on message round-tripping. Without it, when a type is generated from schema, the XML output for that type isn't necessarily compatible with the schema originally assumed. In other words, although the `id` and `ref` attributes were serialized, the original schema could have barred these attributes (or all attributes) from occurring in the XML. With `IsReference` applied to a data member, the member continues to be recognized as *referenceable* when round-tripped. + ## See also - diff --git a/docs/framework/wcf/feature-details/large-data-and-streaming.md b/docs/framework/wcf/feature-details/large-data-and-streaming.md index b66d4d131cfec..4bd7b69cceb08 100644 --- a/docs/framework/wcf/feature-details/large-data-and-streaming.md +++ b/docs/framework/wcf/feature-details/large-data-and-streaming.md @@ -56,7 +56,7 @@ Windows Communication Foundation (WCF) is an XML-based communications infrastruc For data that does not have these constraints, it is typically better to send sequences of messages within the scope of a session than one large message. For more information, see the "Streaming Data" section later in this topic. - When sending large amounts of data you will need to set the `maxAllowedContentLength` IIS setting (for more information see [Configuring IIS Request Limits](/iis/configuration/system.webServer/security/requestFiltering/requestLimits/)) and the `maxReceivedMessageSize` binding setting (for example [System.ServiceModel.BasicHttpBinding.MaxReceivedMessageSize](xref:System.ServiceModel.HttpBindingBase.MaxReceivedMessageSize%2A) or ). The `maxAllowedContentLength` property defaults to 28.6 MB and the `maxReceivedMessageSize` property defaults to 64KB. + When sending large amounts of data you will need to set the `maxAllowedContentLength` IIS setting (for more information see [Configuring IIS Request Limits](/iis/configuration/system.webServer/security/requestFiltering/requestLimits/)) and the `maxReceivedMessageSize` binding setting (for example [System.ServiceModel.BasicHttpBinding.MaxReceivedMessageSize](xref:System.ServiceModel.HttpBindingBase.MaxReceivedMessageSize%2A) or ). The `maxAllowedContentLength` property defaults to 28.6 MB and the `maxReceivedMessageSize` property defaults to 64KB. ## Encodings @@ -193,7 +193,7 @@ class MyData ### Enabling Asynchronous Streaming - To enable asynchronous streaming, add the endpoint behavior to the service host and set its property to `true`. We have also added the capability of true asynchronous streaming on the send side. This improves scalability of the service in scenarios where it is streaming messages to multiple clients some of which are slow in reading possibly due to network congestion or are not reading at all. In these scenarios we now do not block individual threads on the service per client. This ensures that the service is able to process many more clients thereby improving the scalability of the service. + To enable asynchronous streaming, add the endpoint behavior to the service host and set its property to `true`. We have also added the capability of true asynchronous streaming on the send side. This improves scalability of the service in scenarios where it is streaming messages to multiple clients some of which are slow in reading possibly due to network congestion or are not reading at all. In these scenarios we now do not block individual threads on the service per client. This ensures that the service is able to process many more clients thereby improving the scalability of the service. ### Programming Model for Streamed Transfers diff --git a/docs/framework/wcf/feature-details/limiting-message-distribution.md b/docs/framework/wcf/feature-details/limiting-message-distribution.md index f3a9ae8446e96..24d1a4f5ba30b 100644 --- a/docs/framework/wcf/feature-details/limiting-message-distribution.md +++ b/docs/framework/wcf/feature-details/limiting-message-distribution.md @@ -20,7 +20,7 @@ Hop count may be added to a message by adding `PeerHopCount` as an attribute to `MessagePropagationFilter` can be used for customized control of message flooding, especially when the content of the message or other specific scenarios determine propagation. The filter makes propagation decisions for every message that passes through the node. This is true for messages that originated elsewhere in the mesh that your node has received as well as messages created by your application. The filter has access to both the message and its origination, so decisions about forwarding or dropping the message can be based on the full information available. - is a base abstract class with a single function, . The first argument of the method call passes in a full copy of the message. Any changes made to the message do not affect the actual message. The last argument of the method call identifies the origin of the message (`PeerMessageOrigination.Local` or `PeerMessageOrigination.Remote`). Concrete implementations of this method must return a constant from the enumeration indicating that the message is to be forwarded to the local application (`Local`), forwarded to remote clients (`Remote`), both (`LocalAndRemote`), or neither (`None`). This filter can be applied by accessing the corresponding `PeerNode` object and specifying an instance of the derived propagation filter class in the `PeerNode.MessagePropagationFilter` property. Ensure that the propagation filter is attached before opening the Peer Channel. + is a base abstract class with a single function, . The first argument of the method call passes in a full copy of the message. Any changes made to the message do not affect the actual message. The last argument of the method call identifies the origin of the message (`PeerMessageOrigination.Local` or `PeerMessageOrigination.Remote`). Concrete implementations of this method must return a constant from the enumeration indicating that the message is to be forwarded to the local application (`Local`), forwarded to remote clients (`Remote`), both (`LocalAndRemote`), or neither (`None`). This filter can be applied by accessing the corresponding `PeerNode` object and specifying an instance of the derived propagation filter class in the `PeerNode.MessagePropagationFilter` property. Ensure that the propagation filter is attached before opening the Peer Channel. - For code snippets and related information, see the [Peer Channel and MessagePropagationFilter](/archive/blogs/peerchan/peer-channel-and-messagepropagationfilter) post on the Peer Channel blog. diff --git a/docs/framework/wcf/feature-details/managing-claims-and-authorization-with-the-identity-model.md b/docs/framework/wcf/feature-details/managing-claims-and-authorization-with-the-identity-model.md index d70792be18e3b..2c2029e181060 100644 --- a/docs/framework/wcf/feature-details/managing-claims-and-authorization-with-the-identity-model.md +++ b/docs/framework/wcf/feature-details/managing-claims-and-authorization-with-the-identity-model.md @@ -51,7 +51,7 @@ Authorization is the process of determining which entities have permission to ch A set of claims issued by a particular issuer. Claim type\ - A kind of claim. Claims defined by the Identity Model API are properties of the class. Examples of system-provided claim types are , , , , , , , , , , and . + A kind of claim. Claims defined by the Identity Model API are properties of the class. Examples of system-provided claim types are , , , , , , , , , , and . Evaluation context\ A context in which an authorization policy is evaluated. Contains properties and claim sets. Becomes the basis of an authorization context once evaluation is complete. @@ -69,7 +69,7 @@ Authorization is the process of determining which entities have permission to ch Something in the system that can only be used, accessed, or otherwise manipulated if certain requirements are first met. Right\ - A capability over a resource. Rights defined by the Identity Model API are properties of the class. Examples of system-provided rights are and . + A capability over a resource. Rights defined by the Identity Model API are properties of the class. Examples of system-provided rights are and . Value\ Something over which a right is claimed. @@ -160,7 +160,7 @@ Authorization is the process of determining which entities have permission to ch |Class|Description| |-----------|-----------------| -||A class that provides a method— —to perform claim-based authorization checks for each operation in a service. You must derive from the class and override the method.| +||A class that provides a method— —to perform claim-based authorization checks for each operation in a service. You must derive from the class and override the method.| ||A sealed class that provides various properties related to the behavior of a service as it pertains to authorization.| ||A class that provides security context, including authorization context, for the currently running (or about to be run) operation. An instance of this class is part of the .| @@ -170,9 +170,9 @@ Authorization is the process of determining which entities have permission to ch |Member|Description| |------------|-----------------| -||Derived classes implement this method to perform claim-based access checks prior to running operations in a service. Any and all information in the supplied , or elsewhere, can be examined when making the access check decision. If returns `true`, then access is granted and the operation is allowed to run. If `CheckAccessCore` returns `false`, then access is denied and the operation does not run. For an example, see [How to: Create a Custom Authorization Manager for a Service](../extending/how-to-create-a-custom-authorization-manager-for-a-service.md).| -||Returns the for the service. The is responsible for making authorization decisions.| -||The collection of custom authorization policies specified for the service. These policies are evaluated in addition to those policies associated with credentials in incoming messages.| +||Derived classes implement this method to perform claim-based access checks prior to running operations in a service. Any and all information in the supplied , or elsewhere, can be examined when making the access check decision. If returns `true`, then access is granted and the operation is allowed to run. If `CheckAccessCore` returns `false`, then access is denied and the operation does not run. For an example, see [How to: Create a Custom Authorization Manager for a Service](../extending/how-to-create-a-custom-authorization-manager-for-a-service.md).| +||Returns the for the service. The is responsible for making authorization decisions.| +||The collection of custom authorization policies specified for the service. These policies are evaluated in addition to those policies associated with credentials in incoming messages.| ## See also diff --git a/docs/framework/wcf/feature-details/message-filters.md b/docs/framework/wcf/feature-details/message-filters.md index 19423eb2ab5e6..c4607296352a7 100644 --- a/docs/framework/wcf/feature-details/message-filters.md +++ b/docs/framework/wcf/feature-details/message-filters.md @@ -2,152 +2,152 @@ description: "Learn more about: Message Filters" title: "Message Filters" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "routing [WCF], message filters" ms.assetid: cb33ba49-8b1f-4099-8acb-240404a46d9a --- # Message Filters -To implement content-based routing, the Routing Service uses implementations that inspect specific sections of a message, such as the address, endpoint name, or a specific XPath statement. If none of the message filters provided with [!INCLUDE[netfx_current_short](../../../../includes/netfx-current-short-md.md)] meet your needs, you can create a custom filter by creating a new implementation of the base class. - - When configuring the Routing Service, you must define filter elements ( objects) that describe the type of **MessageFilter** and any supporting data required to create the filter, such as specific string values to search for within the message. Note that creating the filter elements only defines the individual message filters; to use the filters to evaluate and route messages you must also define a filter table (). - - Each entry in the filter table references a filter element and specifies the client endpoint that a message will be routed to if the message matches the filter. The filter table entries also allow you to specify a collection of backup endpoints (), which defines a list of endpoints that the message will be transmitted to in the event of a transmission failure when sending to the primary endpoint. These endpoints will be tried in the order specified until one succeeds. - -## Message Filters - - The message filters used by the Routing Service provide common message selection functionality, such as evaluating the name of the endpoint that a message was sent to, the SOAP action, or the address or address prefix that the message was sent to. Filters can also be joined with an `AND` condition, so that messages will only be routed to an endpoint if the message matches both filters. You can also create custom filters by creating your own implementation of . - - The following table lists the used by the Routing Service, the class that implements the specific message filter, and the required parameters. - -|Filter Type|Description|Filter Data Meaning|Example Filter| -|------------------|-----------------|-------------------------|--------------------| -|Action|Uses the class to match messages containing a specific action.|The action to filter upon.|``| -|EndpointAddress|Uses the class, with == `true` to match messages containing a specific address.|The address to filter upon (in the To header).|``| -|EndpointAddressPrefix|Uses the class, with == `true` to match messages containing a specific address prefix.|The address to filter upon using longest prefix matching.|``| -|And|Uses the class that always evaluates both conditions before returning.|filterData is not used; instead filter1 and filter2 have the names of the corresponding message filters (also in the table), which should be **AND**ed together.|``| -|Custom|A user-defined type that extends the class and has a constructor taking a string.|The customType attribute is the fully qualified type name of the class to create; filterData is the string to pass to the constructor when creating the filter.|``| -|EndpointName|Uses the class to match messages based on the name of the service endpoint they arrived on.|The name of the service endpoint, for example: "serviceEndpoint1". This should be one of the endpoints exposed on the Routing Service.|``| -|MatchAll|Uses the class. This filter matches all arriving messages.|filterData is not used. This filter will always match all messages.|``| -|XPath|Uses the class to match specific XPath queries within the message.|The XPath query to use when matching messages.|``| - - The following example defines filter entries that use the XPath, EndpointName, and PrefixEndpointAddress message filters. This example also demonstrates using a custom filter for the RoundRobinFilter1 and RoundRobinFilter2 entries. - -```xml - +To implement content-based routing, the Routing Service uses implementations that inspect specific sections of a message, such as the address, endpoint name, or a specific XPath statement. If none of the message filters provided with [!INCLUDE[netfx_current_short](../../../../includes/netfx-current-short-md.md)] meet your needs, you can create a custom filter by creating a new implementation of the base class. + + When configuring the Routing Service, you must define filter elements ( objects) that describe the type of **MessageFilter** and any supporting data required to create the filter, such as specific string values to search for within the message. Note that creating the filter elements only defines the individual message filters; to use the filters to evaluate and route messages you must also define a filter table (). + + Each entry in the filter table references a filter element and specifies the client endpoint that a message will be routed to if the message matches the filter. The filter table entries also allow you to specify a collection of backup endpoints (), which defines a list of endpoints that the message will be transmitted to in the event of a transmission failure when sending to the primary endpoint. These endpoints will be tried in the order specified until one succeeds. + +## Message Filters + + The message filters used by the Routing Service provide common message selection functionality, such as evaluating the name of the endpoint that a message was sent to, the SOAP action, or the address or address prefix that the message was sent to. Filters can also be joined with an `AND` condition, so that messages will only be routed to an endpoint if the message matches both filters. You can also create custom filters by creating your own implementation of . + + The following table lists the used by the Routing Service, the class that implements the specific message filter, and the required parameters. + +|Filter Type|Description|Filter Data Meaning|Example Filter| +|------------------|-----------------|-------------------------|--------------------| +|Action|Uses the class to match messages containing a specific action.|The action to filter upon.|``| +|EndpointAddress|Uses the class, with == `true` to match messages containing a specific address.|The address to filter upon (in the To header).|``| +|EndpointAddressPrefix|Uses the class, with == `true` to match messages containing a specific address prefix.|The address to filter upon using longest prefix matching.|``| +|And|Uses the class that always evaluates both conditions before returning.|filterData is not used; instead filter1 and filter2 have the names of the corresponding message filters (also in the table), which should be **AND**ed together.|``| +|Custom|A user-defined type that extends the class and has a constructor taking a string.|The customType attribute is the fully qualified type name of the class to create; filterData is the string to pass to the constructor when creating the filter.|``| +|EndpointName|Uses the class to match messages based on the name of the service endpoint they arrived on.|The name of the service endpoint, for example: "serviceEndpoint1". This should be one of the endpoints exposed on the Routing Service.|``| +|MatchAll|Uses the class. This filter matches all arriving messages.|filterData is not used. This filter will always match all messages.|``| +|XPath|Uses the class to match specific XPath queries within the message.|The XPath query to use when matching messages.|``| + + The following example defines filter entries that use the XPath, EndpointName, and PrefixEndpointAddress message filters. This example also demonstrates using a custom filter for the RoundRobinFilter1 and RoundRobinFilter2 entries. + +```xml + + filterData="/s12:Envelope/s12:Header/custom:RoundingCalculator = 1"/> + filterData="calculatorEndpoint"/> + filterData="http://localhost/routingservice/router/rounding/"/> + RoutingService" filterData="group1"/> - -``` - + RoutingService" filterData="group1"/> + +``` + > [!NOTE] -> Simply defining a filter does not cause messages to be evaluated against the filter. The filter must be added to a filter table, which is then associated with the service endpoint exposed by the Routing Service. - -### Namespace Table - - When using an XPath filter, the filter data that contains the XPath query can become extremely large due to the use of namespaces. To alleviate this problem the Routing Service provides the ability to define your own namespace prefixes by using the namespace table. - - The namespace table is a collection of objects that defines the namespace prefixes for common namespaces that can be used in an XPath. The following are the default namespaces and namespace prefixes that are contained in the namespace table. - -|Prefix|Namespace| -|------------|---------------| -|s11|`http://schemas.xmlsoap.org/soap/envelope`| -|s12|`http://www.w3.org/2003/05/soap-envelope`| -|wsaAugust2004|`http://schemas.xmlsoap.org/ws/2004/08/addressing`| -|wsa10|`http://www.w3.org/2005/08/addressing`| -|sm|`http://schemas.microsoft.com/serviceModel/2004/05/xpathfunctions`| -|tempuri|`http://tempuri.org`| -|ser|`http://schemas.microsoft.com/2003/10/Serialization`| - - When you know that you will be using a specific namespace in your XPath queries, you can add it to the namespace table along with a unique namespace prefix and use the prefix in any XPath query instead of the full namespace. The following example defines a prefix of "custom" for the namespace `"http://my.custom.namespace"`, which is then used in the XPath query contained in filterData. - -```xml - - - - - - -``` - -## Filter Tables - - While each filter element defines a logical comparison that can be applied to a message, the filter table provides the association between the filter element and the destination client endpoint. A filter table is a named collection of objects that define the association between a filter, a primary destination endpoint, and a list of alternative backup endpoints. The filter table entries also allow you to specify an optional priority for each filter condition. The following example defines two filters and then defines a filter table that associates each filter with a destination endpoint. - -```xml - - - - - - - - - - - -
+> Simply defining a filter does not cause messages to be evaluated against the filter. The filter must be added to a filter table, which is then associated with the service endpoint exposed by the Routing Service. + +### Namespace Table + + When using an XPath filter, the filter data that contains the XPath query can become extremely large due to the use of namespaces. To alleviate this problem the Routing Service provides the ability to define your own namespace prefixes by using the namespace table. + + The namespace table is a collection of objects that defines the namespace prefixes for common namespaces that can be used in an XPath. The following are the default namespaces and namespace prefixes that are contained in the namespace table. + +|Prefix|Namespace| +|------------|---------------| +|s11|`http://schemas.xmlsoap.org/soap/envelope`| +|s12|`http://www.w3.org/2003/05/soap-envelope`| +|wsaAugust2004|`http://schemas.xmlsoap.org/ws/2004/08/addressing`| +|wsa10|`http://www.w3.org/2005/08/addressing`| +|sm|`http://schemas.microsoft.com/serviceModel/2004/05/xpathfunctions`| +|tempuri|`http://tempuri.org`| +|ser|`http://schemas.microsoft.com/2003/10/Serialization`| + + When you know that you will be using a specific namespace in your XPath queries, you can add it to the namespace table along with a unique namespace prefix and use the prefix in any XPath query instead of the full namespace. The following example defines a prefix of "custom" for the namespace `"http://my.custom.namespace"`, which is then used in the XPath query contained in filterData. + +```xml + + + + + + +``` + +## Filter Tables + + While each filter element defines a logical comparison that can be applied to a message, the filter table provides the association between the filter element and the destination client endpoint. A filter table is a named collection of objects that define the association between a filter, a primary destination endpoint, and a list of alternative backup endpoints. The filter table entries also allow you to specify an optional priority for each filter condition. The following example defines two filters and then defines a filter table that associates each filter with a destination endpoint. + +```xml + + + + + + + + + + + +
- -``` - -### Filter Evaluation Priority - - By default, all entries in the filter table are evaluated simultaneously, and the message being evaluated is routed to the endpoint(s) associated with each matching filter entry. If multiple filters evaluate to `true`, and the message is one-way or duplex, the message is multicast to the endpoints for all matching filters. Request-reply messages cannot be multicast because only one reply can be returned to the client. - - More complex routing logic can be implemented by specifying priority levels for each filter; the Routing Service evaluates all filters at the highest priority level first. If a message matches a filter of this level, no filters of a lower priority are processed. For example, an incoming one-way message is first evaluated against all filters with a priority of 2. The message does not match any filter at this priority level, so next the message is compared against filters with a priority of 1. Two priority 1 filters match the message, and because it is a one-way message it is routed to both destination endpoints. Because a match was found among the priority 1 filters, no filters of priority 0 are evaluated. - + +``` + +### Filter Evaluation Priority + + By default, all entries in the filter table are evaluated simultaneously, and the message being evaluated is routed to the endpoint(s) associated with each matching filter entry. If multiple filters evaluate to `true`, and the message is one-way or duplex, the message is multicast to the endpoints for all matching filters. Request-reply messages cannot be multicast because only one reply can be returned to the client. + + More complex routing logic can be implemented by specifying priority levels for each filter; the Routing Service evaluates all filters at the highest priority level first. If a message matches a filter of this level, no filters of a lower priority are processed. For example, an incoming one-way message is first evaluated against all filters with a priority of 2. The message does not match any filter at this priority level, so next the message is compared against filters with a priority of 1. Two priority 1 filters match the message, and because it is a one-way message it is routed to both destination endpoints. Because a match was found among the priority 1 filters, no filters of priority 0 are evaluated. + > [!NOTE] -> If no priority is specified, the default priority of 0 is used. - - The following example defines a filter table that specifies priorities of 2, 1, and 0 for the filters referenced in the table. - -```xml - - +> If no priority is specified, the default priority of 0 is used. + + The following example defines a filter table that specifies priorities of 2, 1, and 0 for the filters referenced in the table. + +```xml + + + priority="2"/> + priority="1"/> + priority="1"/> - - -``` - - In the preceding example, if a message matches the XPathFilter, it will be routed to the roundingCalcEndpoint and no further filters in the table will be evaluated because all other filters are of a lower priority. However, if the message does not match the XPathFilter it will then be evaluated against all filters of the next lower priority, EndpointNameFilter and PrefixAddressFilter. - + priority="0"/> + + +``` + + In the preceding example, if a message matches the XPathFilter, it will be routed to the roundingCalcEndpoint and no further filters in the table will be evaluated because all other filters are of a lower priority. However, if the message does not match the XPathFilter it will then be evaluated against all filters of the next lower priority, EndpointNameFilter and PrefixAddressFilter. + > [!NOTE] -> When possible, use exclusive filters instead of specifying a priority because priority evaluation can result in performance degradation. - -### Backup Lists - - Each filter in the filter table can optionally specify a backup list, which is a named collection of endpoints (). This collection contains an ordered list of endpoints that the message will be transmitted to in the event of a when sending to the primary endpoint specified in . The following example defines a backup list named "backupServiceEndpoints" that contains two endpoints. - -```xml - - - - - - - - - - - -``` - +> When possible, use exclusive filters instead of specifying a priority because priority evaluation can result in performance degradation. + +### Backup Lists + + Each filter in the filter table can optionally specify a backup list, which is a named collection of endpoints (). This collection contains an ordered list of endpoints that the message will be transmitted to in the event of a when sending to the primary endpoint specified in . The following example defines a backup list named "backupServiceEndpoints" that contains two endpoints. + +```xml + + + + + + + + + + + +``` + In the preceding example, if a send to the primary endpoint "Destination" fails, the Routing Service will try sending to each endpoint in the sequence they are listed, first sending to backupServiceQueue and subsequently sending to alternateServiceQueue if the send to backupServiceQueue fails. If all backup endpoints fail, a fault is returned. diff --git a/docs/framework/wcf/feature-details/message-security-with-a-windows-client-without-credential-negotiation.md b/docs/framework/wcf/feature-details/message-security-with-a-windows-client-without-credential-negotiation.md index 611ec21a2e284..dee6f1cae5ae9 100644 --- a/docs/framework/wcf/feature-details/message-security-with-a-windows-client-without-credential-negotiation.md +++ b/docs/framework/wcf/feature-details/message-security-with-a-windows-client-without-credential-negotiation.md @@ -103,7 +103,7 @@ The following code and configuration are meant to run independently. Do one of t ### Code -The following code configures the client. The security mode is set to Message, and the client credential type is set to Windows. Note that the and properties are set to `false`. +The following code configures the client. The security mode is set to Message, and the client credential type is set to Windows. Note that the and properties are set to `false`. > [!NOTE] > To use Windows credential type without negotiation, the client must be configured with the service's account SPN prior to commencing the communication with the service. The client uses the SPN to get the Kerberos token to authenticate and secure the communication with the service. The following sample shows how to configure the client with the service's SPN. If you are using the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to generate the client, the service's SPN will be automatically propagated to the client from the service's metadata (WSDL), if the service's metadata contains that information. For more information about how to configure the service to include its SPN in the service's metadata, see the "Service" section later in this topic. diff --git a/docs/framework/wcf/feature-details/messaging-activities.md b/docs/framework/wcf/feature-details/messaging-activities.md index 43cc770adb2f2..0882dfbf3c959 100644 --- a/docs/framework/wcf/feature-details/messaging-activities.md +++ b/docs/framework/wcf/feature-details/messaging-activities.md @@ -36,7 +36,7 @@ The [!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md) A datagram MEP involves a client sending a message and a service receiving the message. If the client is a workflow use a activity to send the message. To receive that message in a workflow, use a activity. The and activities each have a property named `Content`. This property contains the data being sent or received. When implementing the request-response MEP both the client and the service use pairs of activities. The client uses a activity to send the message and a activity to receive the response from the service. These two activities are associated with each other by the property. This property is set to the activity that sent the original message. The service also uses a pair of associated activities: and . These two activities are associated by the property. This property is set to the activity that received the original message. The and activities, like and allow you to send a instance or a message contract type. -Because of the long-running nature of workflows, it is important for the duplex pattern of communication to also support long-running conversations. To support long-running conversations, clients who initiate the conversation must provide the service with an opportunity to call it back at a later time when the data becomes available. For example, a purchase order request is submitted for manager approval, but it might not be processed for a day, a week, or even a year; the workflow that manages the purchase order approval must know to resume after the approval is given. This pattern of duplex communication is supported in workflows using correlation. To implement a duplex pattern, use and activities. On the activity, initialize a correlation using . On the activity set that correlation handle as the property value. For more information, see [Durable Duplex](durable-duplex-correlation.md). +Because of the long-running nature of workflows, it is important for the duplex pattern of communication to also support long-running conversations. To support long-running conversations, clients who initiate the conversation must provide the service with an opportunity to call it back at a later time when the data becomes available. For example, a purchase order request is submitted for manager approval, but it might not be processed for a day, a week, or even a year; the workflow that manages the purchase order approval must know to resume after the approval is given. This pattern of duplex communication is supported in workflows using correlation. To implement a duplex pattern, use and activities. On the activity, initialize a correlation using . On the activity set that correlation handle as the property value. For more information, see [Durable Duplex](durable-duplex-correlation.md). > [!NOTE] > Workflow’s implementation of duplex using a callback correlation ("Durable Duplex") is intended for long-running conversations. This is not the same as WCF duplex with callback contracts where the conversation is short-running (the lifetime of the channel). @@ -50,7 +50,7 @@ The and and activities also have a property named `Content`. This property is of type and represents data the or activity sends. The .NET Framework defines two related types called and both of which are derived from . Set the or activity’s `Content` property to an instance of one of these types to send data from a workflow service. The type to use depends upon the type of data the activity sends. If the activity sends a `Message` object or a message contract type, use . If the activity sends a data contract type use . allows you to send multiple parameters, whereas only allows you to send one object, the message (or the message contract type). -When programming imperatively with the messaging activities, you use the generic and to wrap the objects you assign to the message or parameters properties of the , , , and activities. Use for the and activities and for and activities. `In` arguments are used with the send activities because the data is being passed into the activities. `Out` arguments are used with the receive activities because data is being passed out of the activities, as shown in the following example. +When programming imperatively with the messaging activities, you use the generic and to wrap the objects you assign to the message or parameters properties of the , , , and activities. Use for the and activities and for and activities. `In` arguments are used with the send activities because the data is being passed into the activities. `Out` arguments are used with the receive activities because data is being passed out of the activities, as shown in the following example. ```csharp Receive reserveSeat = new Receive @@ -78,7 +78,7 @@ SendReply reserveSeat = new SendReply }; ``` -When implementing a workflow service that defines a request/response operation that returns void, you must instantiate a activity and set the property to an empty instance of one of the content types ( or ) as shown in the following example. +When implementing a workflow service that defines a request/response operation that returns void, you must instantiate a activity and set the property to an empty instance of one of the content types ( or ) as shown in the following example. ```csharp Receive rcv = new Receive() diff --git a/docs/framework/wcf/feature-details/metadata-architecture-overview.md b/docs/framework/wcf/feature-details/metadata-architecture-overview.md index 789dd9bf59aa2..2beeee839302b 100644 --- a/docs/framework/wcf/feature-details/metadata-architecture-overview.md +++ b/docs/framework/wcf/feature-details/metadata-architecture-overview.md @@ -14,7 +14,7 @@ Windows Communication Foundation (WCF) provides a rich infrastructure for export WCF uses the class to describe endpoints in a service. You can use WCF to generate metadata for service endpoints or import service metadata to generate instances. - WCF represents the metadata for a service as an instance of the type, the structure of which is strongly tied to the metadata serialization format defined in WS-MetadataExchange. The type bundles the actual service metadata, such as Web Services Description Language (WSDL) documents, XML schema documents, or WS-Policy expressions, as a collection of instances. Each instance contains a specific metadata dialect and an identifier. A can contain the following items in its property: + WCF represents the metadata for a service as an instance of the type, the structure of which is strongly tied to the metadata serialization format defined in WS-MetadataExchange. The type bundles the actual service metadata, such as Web Services Description Language (WSDL) documents, XML schema documents, or WS-Policy expressions, as a collection of instances. Each instance contains a specific metadata dialect and an identifier. A can contain the following items in its property: - Raw metadata. @@ -46,7 +46,7 @@ Windows Communication Foundation (WCF) provides a rich infrastructure for export The uses a to export metadata for all service endpoints in your service. For more information about exporting metadata from a service, see [Exporting and Importing Metadata](exporting-and-importing-metadata.md). - The augments your service host by adding a instance as an extension to your service host. The provides the implementation for the metadata publishing protocols. You can also use the to get the service's metadata at runtime by accessing the property. + The augments your service host by adding a instance as an extension to your service host. The provides the implementation for the metadata publishing protocols. You can also use the to get the service's metadata at runtime by accessing the property. > [!CAUTION] > If you add a MEX endpoint in your application configuration file and then attempt to add the to your service host in code you get the following exception: @@ -61,14 +61,14 @@ Windows Communication Foundation (WCF) provides a rich infrastructure for export > When publishing metadata for a service that exposes two different service contracts in which each contain an operation of the same name an exception is thrown. For example, if you have a service that exposes a service contract called ICarService that has an operation Get(Car c) and the same service exposes a service contract called IBookService that has an operation Get(Book b), an exception is thrown or an error message is displayed when generating the service's metadata. To work around this issue do one of the following: > > - Rename one of the operations. -> - Set the to a different name. -> - Set one of the operations' namespaces to a different namespace using the property. +> - Set the to a different name. +> - Set one of the operations' namespaces to a different namespace using the property. ## Retrieving Service Metadata WCF can retrieve service metadata using standardized protocols such as WS-MetadataExchange and HTTP. Both of these protocols are supported by the type. You retrieve service metadata using the type by providing an address and an optional binding. The binding used by a instance can be one of the default bindings from the static class, a user-supplied binding, or a binding loaded from an endpoint configuration for the `IMetadataExchange` contract. The can also resolve HTTP URL references to metadata using the type. - By default, a instance is tied to a single instance. You can change or replace the instance used by a by overriding the virtual method. Similarly, you can change or replace the instance used by a to make HTTP/GET requests by overriding the virtual method. + By default, a instance is tied to a single instance. You can change or replace the instance used by a by overriding the virtual method. Similarly, you can change or replace the instance used by a to make HTTP/GET requests by overriding the virtual method. You can retrieve service metadata using WS-MetadataExchange or HTTP/GET requests by using the Svcutil.exe tool and passing the **/target:metadata** switch and an address. Svcutil.exe downloads the metadata at the specified address and saves the files to disk. Svcutil.exe uses a instance internally and loads an MEX endpoint configuration (from the application configuration file) whose name matches the scheme of the address passed to Svcutil.exe, if one exists. Otherwise, Svcutil.exe defaults to using one of the bindings defined by the static factory type. @@ -76,13 +76,13 @@ Windows Communication Foundation (WCF) provides a rich infrastructure for export In WCF, metadata import is the process of generating an abstract representation of a service or its component parts from its metadata. For example, WCF can import instances, instances or instances from a WSDL document for a service. To import service metadata in WCF, use an implementation of the abstract class. Types that derive from the class implement support for importing metadata formats that take advantage of the WS-Policy import logic in WCF. - A implementation collects the policy expressions attached to the service metadata in a object. The then processes the policies as part of importing the metadata by calling the implementations of the interface in the property. + A implementation collects the policy expressions attached to the service metadata in a object. The then processes the policies as part of importing the metadata by calling the implementations of the interface in the property. - You can add support for importing new policy assertions to a by adding your own implementation of the interface to the collection on a instance. Alternatively, you can register your policy import extension in your client application configuration file. + You can add support for importing new policy assertions to a by adding your own implementation of the interface to the collection on a instance. Alternatively, you can register your policy import extension in your client application configuration file. The type is the implementation of the abstract class included with WCF. The type imports WSDL metadata with attached policies that are bundled in a object. - You can add support for importing WSDL extensions by implementing the interface and then adding your implementation to the property on your instance. The can also load implementations of the interface registered in your client application configuration file. + You can add support for importing WSDL extensions by implementing the interface and then adding your implementation to the property on your instance. The can also load implementations of the interface registered in your client application configuration file. ## Dynamic Bindings diff --git a/docs/framework/wcf/feature-details/middle-tier-client-applications.md b/docs/framework/wcf/feature-details/middle-tier-client-applications.md index 827534debf7e3..25dd97c9b231a 100644 --- a/docs/framework/wcf/feature-details/middle-tier-client-applications.md +++ b/docs/framework/wcf/feature-details/middle-tier-client-applications.md @@ -10,19 +10,19 @@ This topic discusses various issues specific to middle-tier client applications ## Increasing Middle-Tier Client Performance - Compared to previous communications technologies, such as Web services using ASP.NET, the creation of a WCF client instance can be more complex due to the rich feature set of WCF. For example, when a object is opened it can establish a secure session with the service, a procedure that increases the startup time for the client instance. Typically, these additional feature capabilities do not affect client applications greatly since the WCF client makes several calls, and then closes. + Compared to previous communications technologies, such as Web services using ASP.NET, the creation of a WCF client instance can be more complex due to the rich feature set of WCF. For example, when a object is opened it can establish a secure session with the service, a procedure that increases the startup time for the client instance. Typically, these additional feature capabilities do not affect client applications greatly since the WCF client makes several calls, and then closes. Middle-tier client applications, however, can create many WCF client objects quickly and, as a result, experience increased initialization requirements. There are two main approaches to increasing the performance of middle-tier applications when calling services: - Cache the WCF client object and reuse it for subsequent calls where possible. -- Create a object and then use that object to create new WCF client channel objects for each call. +- Create a object and then use that object to create new WCF client channel objects for each call. Issues to consider when using these approaches include: - If the service is maintaining a client-specific state by using a session, then you cannot reuse the middle-tier WCF client with multiple-client tier requests because the service's state is tied to that of the middle-tier client. -- If the service must perform authentication on a per-client basis, you must create a new client for each incoming request on the middle tier instead of reusing the middle-tier WCF client (or WCF client channel object) because the client credentials of the middle tier cannot be modified after the WCF client (or ) has been created. +- If the service must perform authentication on a per-client basis, you must create a new client for each incoming request on the middle tier instead of reusing the middle-tier WCF client (or WCF client channel object) because the client credentials of the middle tier cannot be modified after the WCF client (or ) has been created. - While channels and clients created by the channels are thread-safe, they might not support writing more than one message to the wire concurrently. If you are sending large messages, particularly if streaming, the send operation might block waiting for another send to complete. This causes two sorts of problems: a lack of concurrency and the possibility of deadlock if the flow of control returns to the service reusing the channel (that is, the shared client calls a service whose code path results in a callback to the shared client). This is true regardless of the type of WCF client you reuse. diff --git a/docs/framework/wcf/feature-details/migrating-wse-3-0-web-services-to-wcf.md b/docs/framework/wcf/feature-details/migrating-wse-3-0-web-services-to-wcf.md index 6cbca55e0f97b..16e14b4546722 100644 --- a/docs/framework/wcf/feature-details/migrating-wse-3-0-web-services-to-wcf.md +++ b/docs/framework/wcf/feature-details/migrating-wse-3-0-web-services-to-wcf.md @@ -17,7 +17,7 @@ The benefits of migrating WSE 3.0 Web services to Windows Communication Foundati Although there are many similar aspects between the WCF and ASP.NET or WSE 3.0 programming models, they are different. For details about the WCF programming model, see [Basic Programming Lifecycle](../basic-programming-lifecycle.md). > [!NOTE] -> To migrate a WSE Web service to WCF the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) tool can be used to generate a client. That client however contains interfaces and classes that can be used as a starting point for a WCF service too. The interfaces that are generated have the attribute applied to the members of the contract with the property set to `*`. When a WSE client calls a Web service with this setting, the following exception is thrown: **Web.Services3.ResponseProcessingException: WSE910: An error happened during the processing of a response message, and you can find the error in the inner exception**. To mitigate this, set the property of the attribute to a non-`null` value, such as `http://Microsoft.WCF.Documentation/ResponseToOCAMethod`. +> To migrate a WSE Web service to WCF the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) tool can be used to generate a client. That client however contains interfaces and classes that can be used as a starting point for a WCF service too. The interfaces that are generated have the attribute applied to the members of the contract with the property set to `*`. When a WSE client calls a Web service with this setting, the following exception is thrown: **Web.Services3.ResponseProcessingException: WSE910: An error happened during the processing of a response message, and you can find the error in the inner exception**. To mitigate this, set the property of the attribute to a non-`null` value, such as `http://Microsoft.WCF.Documentation/ResponseToOCAMethod`. ## Security diff --git a/docs/framework/wcf/feature-details/net-tcp-port-sharing.md b/docs/framework/wcf/feature-details/net-tcp-port-sharing.md index e50c8fb5bea0c..429bd3dfce4de 100644 --- a/docs/framework/wcf/feature-details/net-tcp-port-sharing.md +++ b/docs/framework/wcf/feature-details/net-tcp-port-sharing.md @@ -2,53 +2,53 @@ title: "Net.TCP Port Sharing" description: Learn about a TCP-based protocol for high-performance communication and the service that enables ports to be shared across multiple user processes in WCF. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "port activation [WCF]" - "port sharing [WCF]" ms.assetid: f13692ee-a179-4439-ae72-50db9534eded --- # Net.TCP Port Sharing -Windows Communication Foundation (WCF) provides a new TCP-based network protocol (net.tcp://) for high-performance communication. WCF also introduces a new system component, the Net.TCP Port Sharing Service that enables net.tcp ports to be shared across multiple user processes. - -## Background and Motivation - - When the TCP/IP protocol was first introduced, only a small number of application protocols made use of it. TCP/IP used port numbers to differentiate between applications by assigning a unique 16-bit port number to each application protocol. For example, HTTP traffic today is standardized to use TCP port 80, SMTP uses TCP port 25, and FTP uses TCP ports 20 and 21. Other applications using TCP as a transport can choose another available port number, either by convention or through formal standardization. - - Using port numbers to distinguish between applications had security problems. Firewalls are generally configured to block TCP traffic on all ports except for a few well-known entry points, so deploying an application that uses a non-standard port is often complicated or even impossible due to the presence of corporate and personal firewalls. Applications that can communicate over standard, well-known ports that are already permitted, reduce the external attack surface. Many network applications make use of the HTTP protocol because most firewalls are configured by default to allow traffic on TCP port 80. - - The HTTP.SYS model in which traffic for many different HTTP applications is multiplexed onto a single TCP port has become standard on the Windows platform. This provides a common point of control for firewall administrators while allowing application developers to minimize the deployment cost of building new applications that can make use of the network. - - The ability to share ports across multiple HTTP applications has long been a feature of Internet Information Services (IIS). However, it was only with the introduction of HTTP.SYS (the kernel-mode HTTP protocol listener) with IIS 6.0 that this infrastructure was fully generalized. In effect, HTTP.SYS allows arbitrary user processes to share the TCP ports dedicated to HTTP traffic. This capability allows many HTTP applications to coexist on the same physical machine in separate, isolated processes while sharing the network infrastructure required to send and receive traffic over TCP port 80. The Net.TCP Port Sharing Service enables the same type of port sharing for net.tcp applications. - -## Port Sharing Architecture - - The Port Sharing architecture in WCF has three main components: - -- A Worker Process: Any process communicating over net.tcp:// using shared ports. - -- The WCF TCP transport: Implements the net.tcp:// protocol. - -- The Net.TCP Port Sharing Service: Allows many worker processes to share the same TCP port. - - The Net.TCP Port Sharing Service is a user-mode Windows service that accepts net.tcp:// connections on behalf of the worker processes that connect through it. When a socket connection arrives, the port sharing service inspects the incoming message stream to obtain its destination address. Based on this address, the port sharing service can route the data stream to the application that ultimately processes it. - - When a WCF service that uses net.tcp:// port sharing opens, the WCF TCP transport infrastructure does not directly open a TCP socket in the application process. Instead, the transport infrastructure registers the service’s base address Uniform Resource Identifier (URI) with the Net.TCP Port Sharing Service and waits for the port sharing service to listen for messages on its behalf. The port sharing service dispatches messages addressed to the application service as they arrive. - -## Installing Port Sharing - - The Net.TCP Port Sharing Service is available on all operating systems that support WinFX, but the service is not enabled by default. As a security precaution, an administrator must manually enable the Net.TCP Port Sharing Service prior to first use. The Net.TCP Port Sharing Service exposes configuration options that allow you to manipulate several characteristics of the network sockets owned by the port sharing service. For more information, see [How to: Enable the Net.TCP Port Sharing Service](how-to-enable-the-net-tcp-port-sharing-service.md). - -## Using Net.tcp Port Sharing in an Application - - The easiest way to use net.tcp:// port sharing in your WCF application is to expose a service using the and then to enable Net.TCP Port Sharing Service using the property. - - For more information about how to do this, see [How to: Configure a WCF Service to Use Port Sharing](how-to-configure-a-wcf-service-to-use-port-sharing.md). - -## Security Implications of Port Sharing - - Although the Net.TCP Port Sharing Service provides a layer of processing between applications and the network, applications that use port sharing should still be secured as if they were directly listening on the network. Specifically, applications that use port sharing should evaluate the process privileges under which they run. Consider running your application using the built-in Network Service account, which runs with the minimal set of process privileges required for network communication. - +Windows Communication Foundation (WCF) provides a new TCP-based network protocol (net.tcp://) for high-performance communication. WCF also introduces a new system component, the Net.TCP Port Sharing Service that enables net.tcp ports to be shared across multiple user processes. + +## Background and Motivation + + When the TCP/IP protocol was first introduced, only a small number of application protocols made use of it. TCP/IP used port numbers to differentiate between applications by assigning a unique 16-bit port number to each application protocol. For example, HTTP traffic today is standardized to use TCP port 80, SMTP uses TCP port 25, and FTP uses TCP ports 20 and 21. Other applications using TCP as a transport can choose another available port number, either by convention or through formal standardization. + + Using port numbers to distinguish between applications had security problems. Firewalls are generally configured to block TCP traffic on all ports except for a few well-known entry points, so deploying an application that uses a non-standard port is often complicated or even impossible due to the presence of corporate and personal firewalls. Applications that can communicate over standard, well-known ports that are already permitted, reduce the external attack surface. Many network applications make use of the HTTP protocol because most firewalls are configured by default to allow traffic on TCP port 80. + + The HTTP.SYS model in which traffic for many different HTTP applications is multiplexed onto a single TCP port has become standard on the Windows platform. This provides a common point of control for firewall administrators while allowing application developers to minimize the deployment cost of building new applications that can make use of the network. + + The ability to share ports across multiple HTTP applications has long been a feature of Internet Information Services (IIS). However, it was only with the introduction of HTTP.SYS (the kernel-mode HTTP protocol listener) with IIS 6.0 that this infrastructure was fully generalized. In effect, HTTP.SYS allows arbitrary user processes to share the TCP ports dedicated to HTTP traffic. This capability allows many HTTP applications to coexist on the same physical machine in separate, isolated processes while sharing the network infrastructure required to send and receive traffic over TCP port 80. The Net.TCP Port Sharing Service enables the same type of port sharing for net.tcp applications. + +## Port Sharing Architecture + + The Port Sharing architecture in WCF has three main components: + +- A Worker Process: Any process communicating over net.tcp:// using shared ports. + +- The WCF TCP transport: Implements the net.tcp:// protocol. + +- The Net.TCP Port Sharing Service: Allows many worker processes to share the same TCP port. + + The Net.TCP Port Sharing Service is a user-mode Windows service that accepts net.tcp:// connections on behalf of the worker processes that connect through it. When a socket connection arrives, the port sharing service inspects the incoming message stream to obtain its destination address. Based on this address, the port sharing service can route the data stream to the application that ultimately processes it. + + When a WCF service that uses net.tcp:// port sharing opens, the WCF TCP transport infrastructure does not directly open a TCP socket in the application process. Instead, the transport infrastructure registers the service’s base address Uniform Resource Identifier (URI) with the Net.TCP Port Sharing Service and waits for the port sharing service to listen for messages on its behalf. The port sharing service dispatches messages addressed to the application service as they arrive. + +## Installing Port Sharing + + The Net.TCP Port Sharing Service is available on all operating systems that support WinFX, but the service is not enabled by default. As a security precaution, an administrator must manually enable the Net.TCP Port Sharing Service prior to first use. The Net.TCP Port Sharing Service exposes configuration options that allow you to manipulate several characteristics of the network sockets owned by the port sharing service. For more information, see [How to: Enable the Net.TCP Port Sharing Service](how-to-enable-the-net-tcp-port-sharing-service.md). + +## Using Net.tcp Port Sharing in an Application + + The easiest way to use net.tcp:// port sharing in your WCF application is to expose a service using the and then to enable Net.TCP Port Sharing Service using the property. + + For more information about how to do this, see [How to: Configure a WCF Service to Use Port Sharing](how-to-configure-a-wcf-service-to-use-port-sharing.md). + +## Security Implications of Port Sharing + + Although the Net.TCP Port Sharing Service provides a layer of processing between applications and the network, applications that use port sharing should still be secured as if they were directly listening on the network. Specifically, applications that use port sharing should evaluate the process privileges under which they run. Consider running your application using the built-in Network Service account, which runs with the minimal set of process privileges required for network communication. + ## See also - [Configuring the Net.TCP Port Sharing Service](configuring-the-net-tcp-port-sharing-service.md) diff --git a/docs/framework/wcf/feature-details/one-way-services.md b/docs/framework/wcf/feature-details/one-way-services.md index 5573bff805ab4..c327140adf96e 100644 --- a/docs/framework/wcf/feature-details/one-way-services.md +++ b/docs/framework/wcf/feature-details/one-way-services.md @@ -2,7 +2,7 @@ description: "Learn more about: One-Way Services" title: "One-Way Services" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "Windows Communication Foundation [WCF], one-way service contracts" - "WCF [WCF], one-way service contracts" - "service contracts [WCF], defining one-way" @@ -10,47 +10,47 @@ ms.assetid: 19053a36-4492-45a3-bfe6-0365ee0205a3 --- # One-Way Services -The default behavior of a service operation is the request-reply pattern. In a request-reply pattern, the client waits for the reply message, even if the service operation is represented in code as a `void` method. With a one-way operation, only one message is transmitted. The receiver does not send a reply message, nor does the sender expect one. - - Use the one-way design pattern: - -- When the client must call operations and is not affected by the result of the operation at the operation level. - -- When using the or the class. (For more information about this scenario, see [Queues in WCF](queues-in-wcf.md).) - - When an operation is one-way, there is no response message to carry error information back to the client. You can detect error conditions by using features of the underlying binding, such as reliable sessions, or by designing a duplex service contract that uses two one-way operations—a one-way contract from the client to the service to call service operation and another one-way contract between the service and the client so that the service can send back faults to the client using a callback that the client implements. - - To create a one-way service contract, define your service contract, apply the class to each operation, and set the property to `true`, as shown in the following sample code. - +The default behavior of a service operation is the request-reply pattern. In a request-reply pattern, the client waits for the reply message, even if the service operation is represented in code as a `void` method. With a one-way operation, only one message is transmitted. The receiver does not send a reply message, nor does the sender expect one. + + Use the one-way design pattern: + +- When the client must call operations and is not affected by the result of the operation at the operation level. + +- When using the or the class. (For more information about this scenario, see [Queues in WCF](queues-in-wcf.md).) + + When an operation is one-way, there is no response message to carry error information back to the client. You can detect error conditions by using features of the underlying binding, such as reliable sessions, or by designing a duplex service contract that uses two one-way operations—a one-way contract from the client to the service to call service operation and another one-way contract between the service and the client so that the service can send back faults to the client using a callback that the client implements. + + To create a one-way service contract, define your service contract, apply the class to each operation, and set the property to `true`, as shown in the following sample code. + ```csharp -[ServiceContract(Namespace="http://Microsoft.ServiceModel.Samples")] -public interface IOneWayCalculator -{ - [OperationContract(IsOneWay=true)] - void Add(double n1, double n2); - [OperationContract(IsOneWay = true)] - void Subtract(double n1, double n2); - [OperationContract(IsOneWay = true)] - void Multiply(double n1, double n2); - [OperationContract(IsOneWay = true)] - void Divide(double n1, double n2); -} -``` - - For a complete example, see the [One-Way](../samples/one-way.md) sample. - -## Clients Blocking with One-Way Operations - - It is important to realize that while some one-way applications return as soon as the outbound data is written to the network connection, in several scenarios the implementation of a binding or of a service can cause a WCF client to block using one-way operations. In WCF client applications, the WCF client object does not return until the outbound data has been written to the network connection. This is true for all message exchange patterns, including one-way operations; this means that any problem writing the data to the transport prevents the client from returning. Depending upon the problem, the result could be an exception or a delay in sending messages to the service. - - For example, if the transport cannot find the endpoint, a exception is thrown without much delay. However, it is also possible that the service is unable to read the data off the wire for some reason, which prevents the client transport send operation from returning. In these cases, if the period on the client transport binding is exceeded, a is thrown—but not until the timeout period has been exceeded. It is also possible to fire so many messages at a service that the service cannot process them past a certain point. In this case, too, the one-way client blocks until the service can process the messages or until an exception is thrown. - - Another variation is the situation in which the service property is set to and the binding uses sessions. In this case, the dispatcher enforces ordering on the incoming messages (a requirement of sessions), which prevents subsequent messages from being read off the network until the service has processed the preceding message for that session. Again, the client blocks, but whether an exception occurs depends upon whether the service is able to process the waiting data prior to the timeout settings on the client. - - You can mitigate some of this problem by inserting a buffer between the client object and the client transport's send operation. For example, using asynchronous calls or using an in-memory message queue can enable the client object to return quickly. Both approaches may increase functionality, but the size of the thread pool and the message queue still enforce limits. - - It is recommended, instead, that you examine the various controls on the service as well as on the client, and then test your application scenarios to determine the best configuration on either side. For example, if the use of sessions is blocking the processing of messages on your service, you can set the property to so that each message can be processed by a different service instance, and set the to in order to allow more than one thread to dispatch messages at a time. Another approach is to increase the read quotas of the service and client bindings. - +[ServiceContract(Namespace="http://Microsoft.ServiceModel.Samples")] +public interface IOneWayCalculator +{ + [OperationContract(IsOneWay=true)] + void Add(double n1, double n2); + [OperationContract(IsOneWay = true)] + void Subtract(double n1, double n2); + [OperationContract(IsOneWay = true)] + void Multiply(double n1, double n2); + [OperationContract(IsOneWay = true)] + void Divide(double n1, double n2); +} +``` + + For a complete example, see the [One-Way](../samples/one-way.md) sample. + +## Clients Blocking with One-Way Operations + + It is important to realize that while some one-way applications return as soon as the outbound data is written to the network connection, in several scenarios the implementation of a binding or of a service can cause a WCF client to block using one-way operations. In WCF client applications, the WCF client object does not return until the outbound data has been written to the network connection. This is true for all message exchange patterns, including one-way operations; this means that any problem writing the data to the transport prevents the client from returning. Depending upon the problem, the result could be an exception or a delay in sending messages to the service. + + For example, if the transport cannot find the endpoint, a exception is thrown without much delay. However, it is also possible that the service is unable to read the data off the wire for some reason, which prevents the client transport send operation from returning. In these cases, if the period on the client transport binding is exceeded, a is thrown—but not until the timeout period has been exceeded. It is also possible to fire so many messages at a service that the service cannot process them past a certain point. In this case, too, the one-way client blocks until the service can process the messages or until an exception is thrown. + + Another variation is the situation in which the service property is set to and the binding uses sessions. In this case, the dispatcher enforces ordering on the incoming messages (a requirement of sessions), which prevents subsequent messages from being read off the network until the service has processed the preceding message for that session. Again, the client blocks, but whether an exception occurs depends upon whether the service is able to process the waiting data prior to the timeout settings on the client. + + You can mitigate some of this problem by inserting a buffer between the client object and the client transport's send operation. For example, using asynchronous calls or using an in-memory message queue can enable the client object to return quickly. Both approaches may increase functionality, but the size of the thread pool and the message queue still enforce limits. + + It is recommended, instead, that you examine the various controls on the service as well as on the client, and then test your application scenarios to determine the best configuration on either side. For example, if the use of sessions is blocking the processing of messages on your service, you can set the property to so that each message can be processed by a different service instance, and set the to in order to allow more than one thread to dispatch messages at a time. Another approach is to increase the read quotas of the service and client bindings. + ## See also - [One-Way](../samples/one-way.md) diff --git a/docs/framework/wcf/feature-details/ordered-processing-of-messages-in-single-concurrency-mode.md b/docs/framework/wcf/feature-details/ordered-processing-of-messages-in-single-concurrency-mode.md index 74a5a4f0591dd..a192067e0d685 100644 --- a/docs/framework/wcf/feature-details/ordered-processing-of-messages-in-single-concurrency-mode.md +++ b/docs/framework/wcf/feature-details/ordered-processing-of-messages-in-single-concurrency-mode.md @@ -6,22 +6,22 @@ ms.assetid: a90f5662-a796-46cd-ae33-30a4072838af --- # Ordered Processing of Messages in Single Concurrency Mode -WCF makes no guarantees about the order in which messages are processed, unless the underlying channel is sessionful. For instance, a WCF service that uses MsmqInputChannel, which is not a sessionful channel, will fail to process messages in order. There are some circumstances where a developer may want the in order processing behavior but not want to use sessions. This topic describes how to configure this behavior when a service is running in Single Concurrency Mode. - -## In-order Message Processing +WCF makes no guarantees about the order in which messages are processed, unless the underlying channel is sessionful. For instance, a WCF service that uses MsmqInputChannel, which is not a sessionful channel, will fail to process messages in order. There are some circumstances where a developer may want the in order processing behavior but not want to use sessions. This topic describes how to configure this behavior when a service is running in Single Concurrency Mode. + +## In-order Message Processing + + A new attribute called has been added to the . When is set to true and is set to messages sent to the service will be processed in order. The following code snippet illustrates how to set these attributes. - A new attribute called has been added to the . When is set to true and is set to messages sent to the service will be processed in order. The following code snippet illustrates how to set these attributes. - ```csharp -[ServiceBehavior(ConcurrencyMode = ConcurrencyMode.Single, EnsureOrderedDispatch = true )] - class Service : IService - { - // ... - } -``` - - If is set to any other value, an is thrown. - +[ServiceBehavior(ConcurrencyMode = ConcurrencyMode.Single, EnsureOrderedDispatch = true )] + class Service : IService + { + // ... + } +``` + + If is set to any other value, an is thrown. + ## See also - [Sessions, Instancing, and Concurrency](sessions-instancing-and-concurrency.md) diff --git a/docs/framework/wcf/feature-details/out-of-order-message-processing.md b/docs/framework/wcf/feature-details/out-of-order-message-processing.md index 3965dedee24cc..35b10955a0738 100644 --- a/docs/framework/wcf/feature-details/out-of-order-message-processing.md +++ b/docs/framework/wcf/feature-details/out-of-order-message-processing.md @@ -6,31 +6,31 @@ ms.assetid: 33fc62a5-5d59-461c-a37a-0e1b51ac763d --- # Out-of-Order Message Processing -Workflow services may depend on messages being sent in a specific order. A workflow service contains one or more activities and each activity is expecting a specific message. Without particular transport delivery guarantees, messages sent by clients may be delayed and therefore delivered in an order the workflow service may not expect. Implementing a workflow service that does not require messages be sent in a specific order is normally done using a Parallel activity. For a more complicated application protocol, the workflow would become very complex very quickly. The out-of-order message processing feature in Windows Communication Foundation (WCF) allows you to create such a workflow without all of the complexity of nested Parallel activities. Out-of-order message processing is only supported on channels that support such as the WCF MSMQ bindings. - -## Enabling Out-Of-Order Message Processing - - Out-of-order message processing is enabled by setting the property to `true` on the WorkflowService. The following example shows how to set the property in code. - -```csharp -// Code: Opt-in to Buffered Receive processing... -WorkflowService service = new WorkflowService -{ - Name="MyService", - Body = workflow, - AllowBufferedReceive = true -}; -``` - - You can also apply the `AllowBufferedReceive` attribute to a workflow service in XAML as shown in the following example. - -```xaml -// Xaml: Opt-in to Buffered Receive processing... - - - -``` - +Workflow services may depend on messages being sent in a specific order. A workflow service contains one or more activities and each activity is expecting a specific message. Without particular transport delivery guarantees, messages sent by clients may be delayed and therefore delivered in an order the workflow service may not expect. Implementing a workflow service that does not require messages be sent in a specific order is normally done using a Parallel activity. For a more complicated application protocol, the workflow would become very complex very quickly. The out-of-order message processing feature in Windows Communication Foundation (WCF) allows you to create such a workflow without all of the complexity of nested Parallel activities. Out-of-order message processing is only supported on channels that support such as the WCF MSMQ bindings. + +## Enabling Out-Of-Order Message Processing + + Out-of-order message processing is enabled by setting the property to `true` on the WorkflowService. The following example shows how to set the property in code. + +```csharp +// Code: Opt-in to Buffered Receive processing... +WorkflowService service = new WorkflowService +{ + Name="MyService", + Body = workflow, + AllowBufferedReceive = true +}; +``` + + You can also apply the `AllowBufferedReceive` attribute to a workflow service in XAML as shown in the following example. + +```xaml +// Xaml: Opt-in to Buffered Receive processing... + + + +``` + ## See also - diff --git a/docs/framework/wcf/feature-details/partial-trust-best-practices.md b/docs/framework/wcf/feature-details/partial-trust-best-practices.md index 315fb7ab97e8f..7013e188b574d 100644 --- a/docs/framework/wcf/feature-details/partial-trust-best-practices.md +++ b/docs/framework/wcf/feature-details/partial-trust-best-practices.md @@ -37,19 +37,19 @@ All serializable types must be explicitly marked with the `[DataContract]` attri The following best practices apply for types that implement and are serialized using the : -- The static method implementations must be `public`. +- The static method implementations must be `public`. - The instance methods that implement the interface must be `public`. ## Using WCF from Fully Trusted Platform Code that Allows Calls from Partially Trusted Callers -The WCF partial trust security model assumes that any caller of a WCF public method or property is running in the code access security (CAS) context of the hosting application. WCF also assumes that only one application security context exists for each , and that this context is established at creation time by a trusted host (for example, by a call to or by the ASP.NET Application Manager). +The WCF partial trust security model assumes that any caller of a WCF public method or property is running in the code access security (CAS) context of the hosting application. WCF also assumes that only one application security context exists for each , and that this context is established at creation time by a trusted host (for example, by a call to or by the ASP.NET Application Manager). [!INCLUDE [cas-deprecated](../../../../includes/cas-deprecated.md)] This security model applies to user-written applications that can't assert additional CAS permissions, such as user code running in a Medium Trust ASP.NET application. However, fully trusted platform code (for example, a third-party assembly that is installed in the global assembly cache and accepts calls from partially trusted code) must take explicit care when calling into WCF on behalf of a partially trusted application to avoid introducing application-level security vulnerabilities. -Full-trust code should avoid altering the CAS permission set of the current thread (by calling , , or ) prior to calling WCF APIs on behalf of partially trusted code. Asserting, denying, or otherwise creating a thread-specific permission context that is independent of the application-level security context can result in unexpected behavior. Depending on the application, this behavior may result in application-level security vulnerabilities. +Full-trust code should avoid altering the CAS permission set of the current thread (by calling , , or ) prior to calling WCF APIs on behalf of partially trusted code. Asserting, denying, or otherwise creating a thread-specific permission context that is independent of the application-level security context can result in unexpected behavior. Depending on the application, this behavior may result in application-level security vulnerabilities. Code that calls into WCF using a thread-specific permission context must be prepared to handle the following situations that may arise: @@ -63,7 +63,7 @@ Code that calls into WCF using a thread-specific permission context must be prep WCF guarantees that partially trusted code can't obtain full-trust permissions unless such permissions are asserted by a fully trusted component prior to calling into WCF public APIs. However, it doesn't guarantee that the effects of asserting full trust are isolated to a particular thread, operation, or user action. -As a best practice, avoid creating thread-specific permission context by calling , , or . Instead, grant or deny the privilege to the application itself, so that no , , or is required. +As a best practice, avoid creating thread-specific permission context by calling , , or . Instead, grant or deny the privilege to the application itself, so that no , , or is required. ## See also diff --git a/docs/framework/wcf/feature-details/partial-trust-feature-compatibility.md b/docs/framework/wcf/feature-details/partial-trust-feature-compatibility.md index 2ab68d2924738..0f94792b137bc 100644 --- a/docs/framework/wcf/feature-details/partial-trust-feature-compatibility.md +++ b/docs/framework/wcf/feature-details/partial-trust-feature-compatibility.md @@ -80,13 +80,13 @@ WCF supports a subset of features in applications running under either of the fo ### Collection Types - Some collection types implement both and . Examples include types that implement . Such types can implement a `public` implementation of `GetEnumerator()`, and an explicit implementation of `GetEnumerator()`. In this case, invokes the `public` implementation of `GetEnumerator()`, and not the explicit implementation of `GetEnumerator()`. If none of the `GetEnumerator()` implementations are `public` and all are explicit implementations, then invokes `IEnumerable.GetEnumerator()`. + Some collection types implement both and . Examples include types that implement . Such types can implement a `public` implementation of `GetEnumerator()`, and an explicit implementation of `GetEnumerator()`. In this case, invokes the `public` implementation of `GetEnumerator()`, and not the explicit implementation of `GetEnumerator()`. If none of the `GetEnumerator()` implementations are `public` and all are explicit implementations, then invokes `IEnumerable.GetEnumerator()`. For collection types when WCF is running in a partial trust environment, if none of the `GetEnumerator()` implementations are `public`, or none of them are explicit interface implementations, then a security exception is thrown. ### NetDataContractSerializer - Many .NET Framework collection types such as , , and are not supported by the in partial trust. These types have the `[Serializable]` attribute set, and as stated previously in the Serialization section, this attribute is not supported in partial trust. The treats collections in a special way and is thus able to get around this restriction, but the has no such mechanism to circumvent this restriction. + Many .NET Framework collection types such as , , and are not supported by the in partial trust. These types have the `[Serializable]` attribute set, and as stated previously in the Serialization section, this attribute is not supported in partial trust. The treats collections in a special way and is thus able to get around this restriction, but the has no such mechanism to circumvent this restriction. The type is not supported by the in partial trust. diff --git a/docs/framework/wcf/feature-details/preventing-replay-attacks-when-a-wcf-service-is-hosted-in-a-web-farm.md b/docs/framework/wcf/feature-details/preventing-replay-attacks-when-a-wcf-service-is-hosted-in-a-web-farm.md index b15e3e9fcd4e9..65fd106a7a806 100644 --- a/docs/framework/wcf/feature-details/preventing-replay-attacks-when-a-wcf-service-is-hosted-in-a-web-farm.md +++ b/docs/framework/wcf/feature-details/preventing-replay-attacks-when-a-wcf-service-is-hosted-in-a-web-farm.md @@ -6,12 +6,12 @@ ms.assetid: 1c2ed695-7a31-4257-92bd-9e9731b886a5 --- # Preventing Replay Attacks When a WCF Service is Hosted in a Web Farm -When using message security WCF prevents replay attacks by creating a NONCE out of the incoming message and checking the internal `InMemoryNonceCache` to see if the generated NONCE is present. If it is, the message is discarded as a replay. When a WCF service is hosted in a web farm, since the `InMemoryNonceCache` is not shared across the nodes in the web farm, the service is vulnerable to replay attacks. To mitigate this scenario WCF 4.5 provides an extensibility point that allows you to implement your own shared NONCE cache by deriving a class from the abstract class . - -## NonceCache Implementation +When using message security WCF prevents replay attacks by creating a NONCE out of the incoming message and checking the internal `InMemoryNonceCache` to see if the generated NONCE is present. If it is, the message is discarded as a replay. When a WCF service is hosted in a web farm, since the `InMemoryNonceCache` is not shared across the nodes in the web farm, the service is vulnerable to replay attacks. To mitigate this scenario WCF 4.5 provides an extensibility point that allows you to implement your own shared NONCE cache by deriving a class from the abstract class . + +## NonceCache Implementation + + To implement your own shared NONCE cache, derive a class from and override the and methods. will check to see if the specified NONCE exists in the cache. will attempt to add a NONCE to the cache. Once the class is implemented, you hook it up by instantiating an instance and assigning it to for client-side replay detection and for server-side replay detection. There is no out of the box configuration support for this feature. - To implement your own shared NONCE cache, derive a class from and override the and methods. will check to see if the specified NONCE exists in the cache. will attempt to add a NONCE to the cache. Once the class is implemented, you hook it up by instantiating an instance and assigning it to for client-side replay detection and for server-side replay detection. There is no out of the box configuration support for this feature. - ## See also - [Message Security](message-security-in-wcf.md) diff --git a/docs/framework/wcf/feature-details/programming-wcf-security.md b/docs/framework/wcf/feature-details/programming-wcf-security.md index 86a3dc9fba0bd..8ed336fefb036 100644 --- a/docs/framework/wcf/feature-details/programming-wcf-security.md +++ b/docs/framework/wcf/feature-details/programming-wcf-security.md @@ -1,107 +1,107 @@ --- title: "Programming WCF Security" -description: Learn how to create a secure WCF application, including authentication, confidentiality, and integrity. +description: Learn how to create a secure WCF application, including authentication, confidentiality, and integrity. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "message security [WCF], programming overview" ms.assetid: 739ec222-4eda-4cc9-a470-67e64a7a3f10 --- # Programming WCF Security -This topic describes the fundamental programming tasks used to create a secure Windows Communication Foundation (WCF) application. This topic covers only authentication, confidentiality, and integrity, collectively known as *transfer security*. This topic does not cover authorization (the control of access to resources or services); for information on authorization, see [Authorization](authorization-in-wcf.md). - +This topic describes the fundamental programming tasks used to create a secure Windows Communication Foundation (WCF) application. This topic covers only authentication, confidentiality, and integrity, collectively known as *transfer security*. This topic does not cover authorization (the control of access to resources or services); for information on authorization, see [Authorization](authorization-in-wcf.md). + > [!NOTE] -> For a valuable introduction to security concepts, especially in regard to WCF, see the set of patterns and practices tutorials on MSDN at [Scenarios, Patterns, and Implementation Guidance for Web Services Enhancements (WSE) 3.0](/previous-versions/msp-n-p/ff648183(v=pandp.10)). - - Programming WCF security is based on three steps setting the following: the security mode, a client credential type, and the credential values. You can perform these steps either through code or configuration. - -## Setting the Security Mode - - The following explains the general steps for programming with the security mode in WCF: - -1. Select one of the predefined bindings appropriate to your application requirements. For a list of the binding choices, see [System-Provided Bindings](../system-provided-bindings.md). By default, nearly every binding has security enabled. The one exception is the class (using configuration, the [\](../../configure-apps/file-schema/wcf/basichttpbinding.md)). - - The binding you select determines the transport. For example, uses HTTP as the transport; uses TCP. - -2. Select one of the security modes for the binding. Note that the binding you select determines the available mode choices. For example, the does not allow transport security (it is not an option). Similarly, neither the nor the allows message security. - - You have three choices: - - 1. `Transport` - - Transport security depends on the mechanism that the binding you have selected uses. For example, if you are using `WSHttpBinding` then the security mechanism is Secure Sockets Layer (SSL) (also the mechanism for the HTTPS protocol). Generally speaking, the main advantage of transport security is that it delivers good throughput no matter which transport you are using. However, it does have two limitations: The first is that the transport mechanism dictates the credential type used to authenticate a user. This is a drawback only if a service needs to interoperate with other services that demand different types of credentials. The second is that, because the security is not applied at the message level, security is implemented in a hop-by-hop manner rather than end-to-end. This latter limitation is an issue only if the message path between client and service includes intermediaries. For more information about which transport to use, see [Choosing a Transport](choosing-a-transport.md). For more information about using transport security, see [Transport Security Overview](transport-security-overview.md). - - 2. `Message` - - Message security means that every message includes the necessary headers and data to keep the message secure. Because the composition of the headers varies, you can include any number of credentials. This becomes a factor if you are interoperating with other services that demand a specific credential type that a transport mechanism can't supply, or if the message must be used with more than one service, where each service demands a different credential type. - - For more information, see [Message Security](message-security-in-wcf.md). - - 3. `TransportWithMessageCredential` - - This choice uses the transport layer to secure the message transfer, while every message includes the rich credentials other services need. This combines the performance advantage of transport security with the rich credentials advantage of message security. This is available with the following bindings: , , , and . - -3. If you decide to use transport security for HTTP (in other words, HTTPS), you must also configure the host with an SSL certificate and enable SSL on a port. For more information, see [HTTP Transport Security](http-transport-security.md). - -4. If you are using the and do not need to establish a secure session, set the property to `false`. - - A secure session occurs when a client and service create a channel using a symmetric key (both client and server use the same key for the length of a conversation, until the dialog is closed). - -## Setting the Client Credential Type - - Select a client credential type as appropriate. For more information, see [Selecting a Credential Type](selecting-a-credential-type.md). The following client credential types are available: - -- `Windows` - -- `Certificate` - -- `Digest` - -- `Basic` - -- `UserName` - -- `NTLM` - -- `IssuedToken` - - Depending on how you set the mode, you must set the credential type. For example, if you have selected the `wsHttpBinding`, and have set the mode to "Message," then you can also set the `clientCredentialType` attribute of the Message element to one of the following values: `None`, `Windows`, `UserName`, `Certificate`, and `IssuedToken`, as shown in the following configuration example. - -```xml - - - - - - +> For a valuable introduction to security concepts, especially in regard to WCF, see the set of patterns and practices tutorials on MSDN at [Scenarios, Patterns, and Implementation Guidance for Web Services Enhancements (WSE) 3.0](/previous-versions/msp-n-p/ff648183(v=pandp.10)). + + Programming WCF security is based on three steps setting the following: the security mode, a client credential type, and the credential values. You can perform these steps either through code or configuration. + +## Setting the Security Mode + + The following explains the general steps for programming with the security mode in WCF: + +1. Select one of the predefined bindings appropriate to your application requirements. For a list of the binding choices, see [System-Provided Bindings](../system-provided-bindings.md). By default, nearly every binding has security enabled. The one exception is the class (using configuration, the [\](../../configure-apps/file-schema/wcf/basichttpbinding.md)). + + The binding you select determines the transport. For example, uses HTTP as the transport; uses TCP. + +2. Select one of the security modes for the binding. Note that the binding you select determines the available mode choices. For example, the does not allow transport security (it is not an option). Similarly, neither the nor the allows message security. + + You have three choices: + + 1. `Transport` + + Transport security depends on the mechanism that the binding you have selected uses. For example, if you are using `WSHttpBinding` then the security mechanism is Secure Sockets Layer (SSL) (also the mechanism for the HTTPS protocol). Generally speaking, the main advantage of transport security is that it delivers good throughput no matter which transport you are using. However, it does have two limitations: The first is that the transport mechanism dictates the credential type used to authenticate a user. This is a drawback only if a service needs to interoperate with other services that demand different types of credentials. The second is that, because the security is not applied at the message level, security is implemented in a hop-by-hop manner rather than end-to-end. This latter limitation is an issue only if the message path between client and service includes intermediaries. For more information about which transport to use, see [Choosing a Transport](choosing-a-transport.md). For more information about using transport security, see [Transport Security Overview](transport-security-overview.md). + + 2. `Message` + + Message security means that every message includes the necessary headers and data to keep the message secure. Because the composition of the headers varies, you can include any number of credentials. This becomes a factor if you are interoperating with other services that demand a specific credential type that a transport mechanism can't supply, or if the message must be used with more than one service, where each service demands a different credential type. + + For more information, see [Message Security](message-security-in-wcf.md). + + 3. `TransportWithMessageCredential` + + This choice uses the transport layer to secure the message transfer, while every message includes the rich credentials other services need. This combines the performance advantage of transport security with the rich credentials advantage of message security. This is available with the following bindings: , , , and . + +3. If you decide to use transport security for HTTP (in other words, HTTPS), you must also configure the host with an SSL certificate and enable SSL on a port. For more information, see [HTTP Transport Security](http-transport-security.md). + +4. If you are using the and do not need to establish a secure session, set the property to `false`. + + A secure session occurs when a client and service create a channel using a symmetric key (both client and server use the same key for the length of a conversation, until the dialog is closed). + +## Setting the Client Credential Type + + Select a client credential type as appropriate. For more information, see [Selecting a Credential Type](selecting-a-credential-type.md). The following client credential types are available: + +- `Windows` + +- `Certificate` + +- `Digest` + +- `Basic` + +- `UserName` + +- `NTLM` + +- `IssuedToken` + + Depending on how you set the mode, you must set the credential type. For example, if you have selected the `wsHttpBinding`, and have set the mode to "Message," then you can also set the `clientCredentialType` attribute of the Message element to one of the following values: `None`, `Windows`, `UserName`, `Certificate`, and `IssuedToken`, as shown in the following configuration example. + +```xml + + + + + + - - -``` - - Or in code: - + + +``` + + Or in code: + [!code-csharp[c_WsHttpService#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_wshttpservice/cs/source.cs#1)] - [!code-vb[c_WsHttpService#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wshttpservice/vb/source.vb#1)] - -## Setting Service Credential Values + [!code-vb[c_WsHttpService#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_wshttpservice/vb/source.vb#1)] + +## Setting Service Credential Values + + Once you select a client credential type, you must set the actual credentials for the service and client to use. On the service, credentials are set using the class and returned by the property of the class. The binding in use implies the service credential type, the security mode chosen, and the type of the client credential. The following code sets a certificate for a service credential. - Once you select a client credential type, you must set the actual credentials for the service and client to use. On the service, credentials are set using the class and returned by the property of the class. The binding in use implies the service credential type, the security mode chosen, and the type of the client credential. The following code sets a certificate for a service credential. - [!code-csharp[c_tcpService#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_tcpservice/cs/source.cs#3)] - [!code-vb[c_tcpService#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_tcpservice/vb/source.vb#3)] - -## Setting Client Credential Values + [!code-vb[c_tcpService#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_tcpservice/vb/source.vb#3)] + +## Setting Client Credential Values + + On the client, set client credential values using the class and returned by the property of the class. The following code sets a certificate as a credential on a client using the TCP protocol. - On the client, set client credential values using the class and returned by the property of the class. The following code sets a certificate as a credential on a client using the TCP protocol. - [!code-csharp[c_TcpClient#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_tcpclient/cs/source.cs#1)] - [!code-vb[c_TcpClient#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_tcpclient/vb/source.vb#1)] - + [!code-vb[c_TcpClient#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_tcpclient/vb/source.vb#1)] + ## See also - [Basic WCF Programming](../basic-wcf-programming.md) diff --git a/docs/framework/wcf/feature-details/publishing-metadata.md b/docs/framework/wcf/feature-details/publishing-metadata.md index a3756568fea60..8886023b84e8b 100644 --- a/docs/framework/wcf/feature-details/publishing-metadata.md +++ b/docs/framework/wcf/feature-details/publishing-metadata.md @@ -16,7 +16,7 @@ Windows Communication Foundation (WCF) services publish metadata by publishing o The uses a to export metadata for all service endpoints in your service. For more information about exporting metadata from a service, see [Exporting and Importing Metadata](exporting-and-importing-metadata.md). - The adds a instance as an extension to your service host. The provides the implementation for the metadata publishing protocols. You can also use the to get the service's metadata at runtime by accessing the property. + The adds a instance as an extension to your service host. The provides the implementation for the metadata publishing protocols. You can also use the to get the service's metadata at runtime by accessing the property. ### MEX Metadata Endpoints @@ -24,7 +24,7 @@ Windows Communication Foundation (WCF) services publish metadata by publishing o ### HTTP GET Metadata Endpoints - To add a metadata endpoint to your service that responds to HTTP/GET requests, set the property on the to `true`. You can also configure a metadata endpoint that uses HTTPS by setting the property on the to `true`. + To add a metadata endpoint to your service that responds to HTTP/GET requests, set the property on the to `true`. You can also configure a metadata endpoint that uses HTTPS by setting the property on the to `true`. ## In This Section diff --git a/docs/framework/wcf/feature-details/queuing-in-wcf.md b/docs/framework/wcf/feature-details/queuing-in-wcf.md index dd7a68d3eb146..9ac35e4629eb6 100644 --- a/docs/framework/wcf/feature-details/queuing-in-wcf.md +++ b/docs/framework/wcf/feature-details/queuing-in-wcf.md @@ -6,131 +6,131 @@ ms.assetid: e98d76ba-1acf-42cd-b137-0f8214661112 --- # Queuing in WCF -This section describes how to use queued communication in Windows Communication Foundation (WCF). - -## Queues as a WCF transport binding - - In WCF, the contracts specify what is being exchanged. Contracts are business-dependent or application-specific message exchanges. The mechanism used to exchange messages (or the "how") is specified in the bindings. Bindings in WCF encapsulate details of the message exchange. They expose configuration knobs for the user to control various aspects of the transport or the protocol that the bindings represent. Queuing in WCF is treated like any other transport binding, which is a big advantage for many queuing applications. Today, many queuing applications are written differently from other remote procedure call (RPC)-style distributed applications, making it harder to follow and maintain. With WCF, the style of writing a distributed application is much the same, making it easier to follow and maintain. Moreover, by factoring out the mechanism of exchange separately from the business logic, it is easier to configure the transport or make changes to it without affecting application specific code. The following figure illustrates the structure of a WCF service and client using MSMQ as a transport. - - ![Queued Application Diagram](media/distributed-queue-figure.jpg "Distributed-Queue-Figure") - - As you can see from the preceding figure, the client and service must define only the application semantics, that is, the contract and implementation. The service configures a queued binding with preferred settings. The client uses the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to generate a WCF client to the service and to generate a configuration file that describes the bindings to use to send messages to the service. Thus, to send a queued message, the client instantiates a WCF client and invokes an operation on it. This causes the message to be sent to the transmission queue and transferred to the target queue. All the complexities of queued communication are hidden from the application that is sending and receiving messages. - - Caveats about queued binding in WCF include: - -- All service operations must be one-way because the default queued binding in WCF does not support duplex communication using queues. A two-way communication sample ([Two-Way Communication](../samples/two-way-communication.md)) illustrates how to use two one-way contracts to implement duplex communication using queues. - -- To generate a WCF client using metadata exchange requires an additional HTTP endpoint on the service so that it can be queried directly to generate the WCF client and obtain binding information to appropriately configure queued communication. - -- Based on the queued binding, extra configuration outside of WCF is required. For example, the class that is shipped with WCF requires you to configure the bindings as well as minimally configure Message Queuing (MSMQ). - - The following sections describe the specific queued bindings shipped with WCF, which are based on MSMQ. - -### MSMQ - - The queued transport in WCF uses MSMQ for its queued communication. - - MSMQ ships as an optional component with Windows and runs as an NT service. It captures messages for transmission in a transmission queue and for delivery in a target queue. The MSMQ queue managers implement a reliable message-transfer protocol so that messages are not lost in transmission. The protocol can be either native or SOAP-based, such as the SOAP Reliable Message Protocol (SRMP). - - In MSMQ, queues can be transactional or non-transactional. A transactional queue allows messages to be captured and delivered in a transaction and then stored durably in the queue. Messages sent to a transactional queue are transferred exactly once in order. You can use a non-transactional queue to send both volatile and durable messages. A message sent to a non-transactional queue does not carry any reliable transfer assurances; thus, messages can be lost. - - MSMQ queues can also be secured using a Windows identity registered with the Active Directory directory service. When installing MSMQ, you can install Active Directory integration, which requires the computer to be part of a Windows domain network. - - For more information about MSMQ, see [Installing Message Queuing (MSMQ)](../samples/installing-message-queuing-msmq.md). - -### NetMsmqBinding - - The [\](../../configure-apps/file-schema/wcf/netmsmqbinding.md) is the queued binding WCF provides for two WCF endpoints to communicate using MSMQ. The binding, therefore, exposes properties that are specific to MSMQ. However, not all MSMQ features and properties are exposed in the `NetMsmqBinding`. The compact `NetMsmqBinding` is designed with an optimal set of features that most customers should find sufficient. - - The `NetMsmqBinding` manifests the core queuing concepts discussed thus far in the form of properties on the bindings. These properties, in turn, communicate to MSMQ how to transfer and deliver the messages. A discussion of the property categories is in the following sections. For more information, see the conceptual topics that describe specific properties more completely. - -#### ExactlyOnce and Durable Properties - - The `ExactlyOnce` and `Durable` properties affect how messages are transferred between queues: - -- `ExactlyOnce`: When set to `true` (the default), the queued channel ensures that the message, if delivered, is not duplicated. It also ensures that the message is not lost. If the message cannot be delivered, or the message Time-To Live expires before the message can be delivered, the failed message along with the delivery failure reason is recorded in a dead-letter queue. When set to `false`, the queued channel makes an effort to transfer the message. In this case, you can optionally choose a dead-letter queue. - -- `Durable:` When set to `true` (the default), the queued channel ensures that MSMQ stores the message durably on disk. Thus, if the MSMQ service were to stop and restart, the messages on disk is transferred to the target queue or delivered to the service. When set to `false`, the messages are stored in volatile store and are lost on stopping and restarting the MSMQ service. - - For `ExactlyOnce` reliable transfer, MSMQ requires the queue to be transactional. Also, MSMQ requires a transaction to read from a transactional queue. As such, when you use the `NetMsmqBinding`, remember that a transaction is required to send or receive messages when `ExactlyOnce` is set to `true`. Similarly, MSMQ requires the queue to be non-transactional for best-effort assurances, such as when `ExactlyOnce` is `false` and for volatile messaging. Thus, when setting `ExactlyOnce` to `false` or durable to `false`, you cannot send or receive using a transaction. - +This section describes how to use queued communication in Windows Communication Foundation (WCF). + +## Queues as a WCF transport binding + + In WCF, the contracts specify what is being exchanged. Contracts are business-dependent or application-specific message exchanges. The mechanism used to exchange messages (or the "how") is specified in the bindings. Bindings in WCF encapsulate details of the message exchange. They expose configuration knobs for the user to control various aspects of the transport or the protocol that the bindings represent. Queuing in WCF is treated like any other transport binding, which is a big advantage for many queuing applications. Today, many queuing applications are written differently from other remote procedure call (RPC)-style distributed applications, making it harder to follow and maintain. With WCF, the style of writing a distributed application is much the same, making it easier to follow and maintain. Moreover, by factoring out the mechanism of exchange separately from the business logic, it is easier to configure the transport or make changes to it without affecting application specific code. The following figure illustrates the structure of a WCF service and client using MSMQ as a transport. + + ![Queued Application Diagram](media/distributed-queue-figure.jpg "Distributed-Queue-Figure") + + As you can see from the preceding figure, the client and service must define only the application semantics, that is, the contract and implementation. The service configures a queued binding with preferred settings. The client uses the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) to generate a WCF client to the service and to generate a configuration file that describes the bindings to use to send messages to the service. Thus, to send a queued message, the client instantiates a WCF client and invokes an operation on it. This causes the message to be sent to the transmission queue and transferred to the target queue. All the complexities of queued communication are hidden from the application that is sending and receiving messages. + + Caveats about queued binding in WCF include: + +- All service operations must be one-way because the default queued binding in WCF does not support duplex communication using queues. A two-way communication sample ([Two-Way Communication](../samples/two-way-communication.md)) illustrates how to use two one-way contracts to implement duplex communication using queues. + +- To generate a WCF client using metadata exchange requires an additional HTTP endpoint on the service so that it can be queried directly to generate the WCF client and obtain binding information to appropriately configure queued communication. + +- Based on the queued binding, extra configuration outside of WCF is required. For example, the class that is shipped with WCF requires you to configure the bindings as well as minimally configure Message Queuing (MSMQ). + + The following sections describe the specific queued bindings shipped with WCF, which are based on MSMQ. + +### MSMQ + + The queued transport in WCF uses MSMQ for its queued communication. + + MSMQ ships as an optional component with Windows and runs as an NT service. It captures messages for transmission in a transmission queue and for delivery in a target queue. The MSMQ queue managers implement a reliable message-transfer protocol so that messages are not lost in transmission. The protocol can be either native or SOAP-based, such as the SOAP Reliable Message Protocol (SRMP). + + In MSMQ, queues can be transactional or non-transactional. A transactional queue allows messages to be captured and delivered in a transaction and then stored durably in the queue. Messages sent to a transactional queue are transferred exactly once in order. You can use a non-transactional queue to send both volatile and durable messages. A message sent to a non-transactional queue does not carry any reliable transfer assurances; thus, messages can be lost. + + MSMQ queues can also be secured using a Windows identity registered with the Active Directory directory service. When installing MSMQ, you can install Active Directory integration, which requires the computer to be part of a Windows domain network. + + For more information about MSMQ, see [Installing Message Queuing (MSMQ)](../samples/installing-message-queuing-msmq.md). + +### NetMsmqBinding + + The [\](../../configure-apps/file-schema/wcf/netmsmqbinding.md) is the queued binding WCF provides for two WCF endpoints to communicate using MSMQ. The binding, therefore, exposes properties that are specific to MSMQ. However, not all MSMQ features and properties are exposed in the `NetMsmqBinding`. The compact `NetMsmqBinding` is designed with an optimal set of features that most customers should find sufficient. + + The `NetMsmqBinding` manifests the core queuing concepts discussed thus far in the form of properties on the bindings. These properties, in turn, communicate to MSMQ how to transfer and deliver the messages. A discussion of the property categories is in the following sections. For more information, see the conceptual topics that describe specific properties more completely. + +#### ExactlyOnce and Durable Properties + + The `ExactlyOnce` and `Durable` properties affect how messages are transferred between queues: + +- `ExactlyOnce`: When set to `true` (the default), the queued channel ensures that the message, if delivered, is not duplicated. It also ensures that the message is not lost. If the message cannot be delivered, or the message Time-To Live expires before the message can be delivered, the failed message along with the delivery failure reason is recorded in a dead-letter queue. When set to `false`, the queued channel makes an effort to transfer the message. In this case, you can optionally choose a dead-letter queue. + +- `Durable:` When set to `true` (the default), the queued channel ensures that MSMQ stores the message durably on disk. Thus, if the MSMQ service were to stop and restart, the messages on disk is transferred to the target queue or delivered to the service. When set to `false`, the messages are stored in volatile store and are lost on stopping and restarting the MSMQ service. + + For `ExactlyOnce` reliable transfer, MSMQ requires the queue to be transactional. Also, MSMQ requires a transaction to read from a transactional queue. As such, when you use the `NetMsmqBinding`, remember that a transaction is required to send or receive messages when `ExactlyOnce` is set to `true`. Similarly, MSMQ requires the queue to be non-transactional for best-effort assurances, such as when `ExactlyOnce` is `false` and for volatile messaging. Thus, when setting `ExactlyOnce` to `false` or durable to `false`, you cannot send or receive using a transaction. + > [!NOTE] -> Ensure that the correct queue (transactional or non-transactional) is created based on settings in the bindings. If `ExactlyOnce` is `true`, use a transactional queue; otherwise, use a non-transactional queue. - -#### Dead-Letter Queue Properties - - The dead-letter queue is used to store messages that fail delivery. The user can write compensating logic that reads messages out of the dead-letter queue. - - Many queuing systems provide for a system-wide dead-letter queue. MSMQ provides a system-wide non-transactional dead-letter queue for messages that fail delivery to non-transactional queues and a system-wide transactional dead-letter queue for messages that fail delivery to transactional queues. - - If multiple clients sending messages to different target queues share the MSMQ service, all messages sent by the clients go to the same dead-letter queue. This is not always preferable. For better isolation, WCF and MSMQ in Windows Vista provide a custom dead-letter queue (or application-specific dead-letter queue) that the user can specify to store messages that fail delivery. Therefore, different clients do not share the same dead-letter queue. - - The binding has two properties of interest: - -- `DeadLetterQueue`: This property is an enumeration that indicates whether a dead-letter queue is requested. The enumeration also contains the kind of dead-letter queue, if one is requested. The values are `None`, `System`, and `Custom`. For more information about the interpretation of these properties, see [Using Dead-Letter Queues to Handle Message Transfer Failures](using-dead-letter-queues-to-handle-message-transfer-failures.md) - -- `CustomDeadLetterQueue`: This property is the Uniform Resource Identifier (URI) address of the application-specific dead-letter queue. This is required if `DeadLetterQueue`.`Custom` is chosen. - -#### Poison Message Handling properties - - When the service reads messages from the target queue under a transaction, the service may fail to process the message for various reasons. The message is then put back into the queue to be read again. To deal with messages that fail repeatedly, a set of poison-message handling properties can be configured in the binding. There are four properties: `ReceiveRetryCount`, `MaxRetryCycles`, `RetryCycleDelay`, and `ReceiveErrorHandling`. For more information about these properties, see [Poison Message Handling](poison-message-handling.md). - -#### Security Properties - - MSMQ exposes its own security model, such as access control lists (ACLs) on a queue or sending authenticated messages. The `NetMsmqBinding` exposes these security properties as part of its transport security settings. There are two properties in the binding for transport security: `MsmqAuthenticationMode` and `MsmqProtectionLevel`. Settings in these properties depend on how MSMQ is configured. For more information, see [Securing Messages Using Transport Security](securing-messages-using-transport-security.md). - - In addition to transport security, the actual SOAP message itself can be secured using message security. For more information, see [Securing Messages Using Message Security](securing-messages-using-message-security.md). - - `MsmqTransportSecurity` also exposes two properties, `MsmqEncryptionAlgorithm` and `MsmqHashAlgorithm`. These are enumerations of different algorithms to choose for queue-to-queue transfer encryption of messages and hashing of the signatures. - -#### Other Properties - - In addition to the preceding properties, other MSMQ-specific properties exposed in the binding include: - -- `UseSourceJournal`: A property to indicate that source journaling is turned on. Source journaling is an MSMQ feature that keeps track of messages that have been successfully transmitted from the transmission queue. - -- `UseMsmqTracing`: A property to indicate that MSMQ tracing is turned on. MSMQ tracing sends report messages to a report queue each time a message leaves or arrives at a machine hosting an MSMQ queue manager. - -- `QueueTransferProtocol`: An enumeration of the protocol to use for queue-to-queue message transfers. MSMQ implements a native queue-to-queue transfer protocol and a SOAP-based protocol called SOAP Reliable Messaging Protocol (SRMP). SRMP is used when using HTTP transport for queue-to-queue transfers. SRMP secure is used when using HTTPS for queue-to-queue transfers. - -- `UseActiveDirectory`: A Boolean value to indicate whether the Active Directory must be used for queue address resolution. By default, this is off. For more information, see [Service Endpoints and Queue Addressing](service-endpoints-and-queue-addressing.md). - -### MsmqIntegrationBinding - - The `MsmqIntegrationBinding` is used when you want a WCF endpoint to communicate with an existing MSMQ application written in C, C++, COM, or System.Messaging APIs. - - The binding properties are the same as for `NetMsmqBinding`. However, the following differences apply: - -- The operation contract for `MsmqIntegrationBinding` is restricted to taking a single parameter of type where the type parameter is the body type. - -- Much of MSMQ native message properties are exposed in the for use. - -- To help with serialization and deserialization of the message body, serializers such as XML and ActiveX are provided. - -### Sample Code - - For step by step instructions on how to write WCF services that use MSMQ see the following topics: - -- [How to: Exchange Messages with WCF Endpoints and Message Queuing Applications](how-to-exchange-messages-with-wcf-endpoints-and-message-queuing-applications.md) - -- [How to: Exchange Queued Messages with WCF Endpoints](how-to-exchange-queued-messages-with-wcf-endpoints.md) - - For a completed code sample illustrating the use of MSMQ in WCF see the following topics: - -- [Transacted MSMQ Binding](../samples/transacted-msmq-binding.md) - -- [Volatile Queued Communication](../samples/volatile-queued-communication.md) - -- [Dead Letter Queues](../samples/dead-letter-queues.md) - -- [Sessions and Queues](../samples/sessions-and-queues.md) - +> Ensure that the correct queue (transactional or non-transactional) is created based on settings in the bindings. If `ExactlyOnce` is `true`, use a transactional queue; otherwise, use a non-transactional queue. + +#### Dead-Letter Queue Properties + + The dead-letter queue is used to store messages that fail delivery. The user can write compensating logic that reads messages out of the dead-letter queue. + + Many queuing systems provide for a system-wide dead-letter queue. MSMQ provides a system-wide non-transactional dead-letter queue for messages that fail delivery to non-transactional queues and a system-wide transactional dead-letter queue for messages that fail delivery to transactional queues. + + If multiple clients sending messages to different target queues share the MSMQ service, all messages sent by the clients go to the same dead-letter queue. This is not always preferable. For better isolation, WCF and MSMQ in Windows Vista provide a custom dead-letter queue (or application-specific dead-letter queue) that the user can specify to store messages that fail delivery. Therefore, different clients do not share the same dead-letter queue. + + The binding has two properties of interest: + +- `DeadLetterQueue`: This property is an enumeration that indicates whether a dead-letter queue is requested. The enumeration also contains the kind of dead-letter queue, if one is requested. The values are `None`, `System`, and `Custom`. For more information about the interpretation of these properties, see [Using Dead-Letter Queues to Handle Message Transfer Failures](using-dead-letter-queues-to-handle-message-transfer-failures.md) + +- `CustomDeadLetterQueue`: This property is the Uniform Resource Identifier (URI) address of the application-specific dead-letter queue. This is required if `DeadLetterQueue`.`Custom` is chosen. + +#### Poison Message Handling properties + + When the service reads messages from the target queue under a transaction, the service may fail to process the message for various reasons. The message is then put back into the queue to be read again. To deal with messages that fail repeatedly, a set of poison-message handling properties can be configured in the binding. There are four properties: `ReceiveRetryCount`, `MaxRetryCycles`, `RetryCycleDelay`, and `ReceiveErrorHandling`. For more information about these properties, see [Poison Message Handling](poison-message-handling.md). + +#### Security Properties + + MSMQ exposes its own security model, such as access control lists (ACLs) on a queue or sending authenticated messages. The `NetMsmqBinding` exposes these security properties as part of its transport security settings. There are two properties in the binding for transport security: `MsmqAuthenticationMode` and `MsmqProtectionLevel`. Settings in these properties depend on how MSMQ is configured. For more information, see [Securing Messages Using Transport Security](securing-messages-using-transport-security.md). + + In addition to transport security, the actual SOAP message itself can be secured using message security. For more information, see [Securing Messages Using Message Security](securing-messages-using-message-security.md). + + `MsmqTransportSecurity` also exposes two properties, `MsmqEncryptionAlgorithm` and `MsmqHashAlgorithm`. These are enumerations of different algorithms to choose for queue-to-queue transfer encryption of messages and hashing of the signatures. + +#### Other Properties + + In addition to the preceding properties, other MSMQ-specific properties exposed in the binding include: + +- `UseSourceJournal`: A property to indicate that source journaling is turned on. Source journaling is an MSMQ feature that keeps track of messages that have been successfully transmitted from the transmission queue. + +- `UseMsmqTracing`: A property to indicate that MSMQ tracing is turned on. MSMQ tracing sends report messages to a report queue each time a message leaves or arrives at a machine hosting an MSMQ queue manager. + +- `QueueTransferProtocol`: An enumeration of the protocol to use for queue-to-queue message transfers. MSMQ implements a native queue-to-queue transfer protocol and a SOAP-based protocol called SOAP Reliable Messaging Protocol (SRMP). SRMP is used when using HTTP transport for queue-to-queue transfers. SRMP secure is used when using HTTPS for queue-to-queue transfers. + +- `UseActiveDirectory`: A Boolean value to indicate whether the Active Directory must be used for queue address resolution. By default, this is off. For more information, see [Service Endpoints and Queue Addressing](service-endpoints-and-queue-addressing.md). + +### MsmqIntegrationBinding + + The `MsmqIntegrationBinding` is used when you want a WCF endpoint to communicate with an existing MSMQ application written in C, C++, COM, or System.Messaging APIs. + + The binding properties are the same as for `NetMsmqBinding`. However, the following differences apply: + +- The operation contract for `MsmqIntegrationBinding` is restricted to taking a single parameter of type where the type parameter is the body type. + +- Much of MSMQ native message properties are exposed in the for use. + +- To help with serialization and deserialization of the message body, serializers such as XML and ActiveX are provided. + +### Sample Code + + For step by step instructions on how to write WCF services that use MSMQ see the following topics: + +- [How to: Exchange Messages with WCF Endpoints and Message Queuing Applications](how-to-exchange-messages-with-wcf-endpoints-and-message-queuing-applications.md) + +- [How to: Exchange Queued Messages with WCF Endpoints](how-to-exchange-queued-messages-with-wcf-endpoints.md) + + For a completed code sample illustrating the use of MSMQ in WCF see the following topics: + +- [Transacted MSMQ Binding](../samples/transacted-msmq-binding.md) + +- [Volatile Queued Communication](../samples/volatile-queued-communication.md) + +- [Dead Letter Queues](../samples/dead-letter-queues.md) + +- [Sessions and Queues](../samples/sessions-and-queues.md) + - [Two-Way Communication](../samples/two-way-communication.md) - -- [SRMP](../samples/srmp.md) - -- [Message Security over Message Queuing](../samples/message-security-over-message-queuing.md) - + +- [SRMP](../samples/srmp.md) + +- [Message Security over Message Queuing](../samples/message-security-over-message-queuing.md) + ## See also - [Service Endpoints and Queue Addressing](service-endpoints-and-queue-addressing.md) diff --git a/docs/framework/wcf/feature-details/reliable-sessions-overview.md b/docs/framework/wcf/feature-details/reliable-sessions-overview.md index 2d82c3b35b1f0..237d8216a665a 100644 --- a/docs/framework/wcf/feature-details/reliable-sessions-overview.md +++ b/docs/framework/wcf/feature-details/reliable-sessions-overview.md @@ -65,7 +65,7 @@ You can stack a reliable session on different underlying channel types, and the | `IRequestSessionChannel` | Yes | Yes | No | No | | `IDuplexSessionChannel` | No | No | Yes | Yes | -†The supported channel types are the values available for the generic `TChannel` parameter value that is passed into the method. +†The supported channel types are the values available for the generic `TChannel` parameter value that is passed into the method. The following table lists the types of session channels supported on the server as a function of the underlying channel type. @@ -75,7 +75,7 @@ The following table lists the types of session channels supported on the server | `IReplySessionChannel` | Yes | Yes | No | No | | `IDuplexSessionChannel` | No | No | Yes | Yes | -‡The supported channel types are the values available for the generic `TChannel` parameter value that is passed into the method. +‡The supported channel types are the values available for the generic `TChannel` parameter value that is passed into the method. ## Reliable sessions and security diff --git a/docs/framework/wcf/feature-details/request-reply-correlation.md b/docs/framework/wcf/feature-details/request-reply-correlation.md index 58a71ca959a02..508141fef580f 100644 --- a/docs/framework/wcf/feature-details/request-reply-correlation.md +++ b/docs/framework/wcf/feature-details/request-reply-correlation.md @@ -6,95 +6,95 @@ ms.assetid: cf4379bf-2d08-43f3-9584-dfa30ffcb1f6 --- # Request-Reply Correlation -Request-reply correlation is used with a / pair to implement a two-way operation in a workflow service and with a / pair that invokes a two-way operation in another Web service. When invoking a two-way operation in a WCF service, the service can be either a traditional imperative code-based Windows Communication Foundation (WCF) service or it can be a workflow service. To use request-reply correlation a two-way binding must be used, such as . Whether invoking or implementing a two-way operation, the correlation initialization steps are similar and are covered in this section. - -## Using Correlation in a Two-Way Operation with Receive/SendReply - - A / pair is used to implement a two-way operation in a workflow service. The runtime uses request-reply correlation to ensure that the reply is dispatched to the correct caller. When a workflow is hosted using , which is the case for workflow services, then the default correlation initialization is sufficient. In this scenario, a / pair is used by a workflow, and no specific correlation configuration is required. - -```csharp -Receive StartOrder = new Receive -{ - CanCreateInstance = true, - ServiceContractName = OrderContractName, - OperationName = "StartOrder" -}; - -SendReply ReplyToStartOrder = new SendReply -{ - Request = StartOrder, - Content = … // Contains the return value, if any. -}; - -// Construct a workflow using StartOrder and ReplyToStartOrder. -``` - -### Explicitly Initializing Request-Reply Correlation - - If other two-way operations are in parallel, then correlation should be explicitly configured. This can be done by specifying a and , or by placing the / inside of a . In this example, request-reply correlation is configured on a / pair. - -```csharp -Variable RRHandle = new Variable(); - -Receive StartOrder = new Receive -{ - CanCreateInstance = true, - ServiceContractName = OrderContractName, - OperationName = "StartOrder", - CorrelationInitializers = - { - new RequestReplyCorrelationInitializer - { - CorrelationHandle = RRHandle - } - } -}; - -SendReply ReplyToStartOrder = new SendReply -{ - Request = StartOrder, - Content = … // Contains the return value, if any. -}; - -// Construct a workflow using StartOrder and ReplyToStartOrder. -``` - - Instead of explicitly configuring the correlation, a activity can be used. provides an implicit to the messaging activities that it contains. In this example, a / pair is contained inside a . No explicit correlation configuration is required. - -```csharp -Receive StartOrder = new Receive -{ - CanCreateInstance = true, - ServiceContractName = OrderContractName, - OperationName = "StartOrder" -}; - -SendReply ReplyToStartOrder = new SendReply -{ - Request = StartOrder, - Content = … // Contains the return value, if any. -}; - -CorrelationScope s = new CorrelationScope -{ - Body = new Sequence - { +Request-reply correlation is used with a / pair to implement a two-way operation in a workflow service and with a / pair that invokes a two-way operation in another Web service. When invoking a two-way operation in a WCF service, the service can be either a traditional imperative code-based Windows Communication Foundation (WCF) service or it can be a workflow service. To use request-reply correlation a two-way binding must be used, such as . Whether invoking or implementing a two-way operation, the correlation initialization steps are similar and are covered in this section. + +## Using Correlation in a Two-Way Operation with Receive/SendReply + + A / pair is used to implement a two-way operation in a workflow service. The runtime uses request-reply correlation to ensure that the reply is dispatched to the correct caller. When a workflow is hosted using , which is the case for workflow services, then the default correlation initialization is sufficient. In this scenario, a / pair is used by a workflow, and no specific correlation configuration is required. + +```csharp +Receive StartOrder = new Receive +{ + CanCreateInstance = true, + ServiceContractName = OrderContractName, + OperationName = "StartOrder" +}; + +SendReply ReplyToStartOrder = new SendReply +{ + Request = StartOrder, + Content = … // Contains the return value, if any. +}; + +// Construct a workflow using StartOrder and ReplyToStartOrder. +``` + +### Explicitly Initializing Request-Reply Correlation + + If other two-way operations are in parallel, then correlation should be explicitly configured. This can be done by specifying a and , or by placing the / inside of a . In this example, request-reply correlation is configured on a / pair. + +```csharp +Variable RRHandle = new Variable(); + +Receive StartOrder = new Receive +{ + CanCreateInstance = true, + ServiceContractName = OrderContractName, + OperationName = "StartOrder", + CorrelationInitializers = + { + new RequestReplyCorrelationInitializer + { + CorrelationHandle = RRHandle + } + } +}; + +SendReply ReplyToStartOrder = new SendReply +{ + Request = StartOrder, + Content = … // Contains the return value, if any. +}; + +// Construct a workflow using StartOrder and ReplyToStartOrder. +``` + + Instead of explicitly configuring the correlation, a activity can be used. provides an implicit to the messaging activities that it contains. In this example, a / pair is contained inside a . No explicit correlation configuration is required. + +```csharp +Receive StartOrder = new Receive +{ + CanCreateInstance = true, + ServiceContractName = OrderContractName, + OperationName = "StartOrder" +}; + +SendReply ReplyToStartOrder = new SendReply +{ + Request = StartOrder, + Content = … // Contains the return value, if any. +}; + +CorrelationScope s = new CorrelationScope +{ + Body = new Sequence + { Activities = - { - StartOrder, - // Activities that create the reply. - ReplyToStartOrder - } - } -}; - -// Construct a workflow using the CorrelationScope. -``` - - If additional correlations are required then they can be configured using the property of the respective messaging activities using the desired `CorrelationInitializer` types. - -## Using Correlation in a Two-Way Operation with Send/ReceiveReply - - While the activity can only be used in a workflow service hosted by , and the / pair can be used in any workflow that must invoke a method on a Web service. If the workflow is hosted using then the default correlation described in the previous section applies, but if not, then correlation must be configured either explicitly using the desired and , or by using the implicit handle management of the . - + { + StartOrder, + // Activities that create the reply. + ReplyToStartOrder + } + } +}; + +// Construct a workflow using the CorrelationScope. +``` + + If additional correlations are required then they can be configured using the property of the respective messaging activities using the desired `CorrelationInitializer` types. + +## Using Correlation in a Two-Way Operation with Send/ReceiveReply + + While the activity can only be used in a workflow service hosted by , and the / pair can be used in any workflow that must invoke a method on a Web service. If the workflow is hosted using then the default correlation described in the previous section applies, but if not, then correlation must be configured either explicitly using the desired and , or by using the implicit handle management of the . + When using **Add Service Reference** on a service with two-way operations, activities are generated that wrap a / pair activity internally with the Request/Reply correlation explicitly specified. diff --git a/docs/framework/wcf/feature-details/retrieving-metadata.md b/docs/framework/wcf/feature-details/retrieving-metadata.md index 94588310f489e..fda446d3ff0ea 100644 --- a/docs/framework/wcf/feature-details/retrieving-metadata.md +++ b/docs/framework/wcf/feature-details/retrieving-metadata.md @@ -18,7 +18,7 @@ Metadata retrieval is the process of requesting and retrieving metadata from a m Windows Communication Foundation (WCF) can retrieve service metadata using standardized protocols such as WS-MetadataExchange and HTTP/GET requests. Both of these protocols are supported by the type. You retrieve service metadata using the type by providing an address for the metadata endpoint and an optional binding. The binding used by a instance can be one of the default bindings from the static class, a user-supplied binding, or a binding loaded from an endpoint configuration for the `IMetadataExchange` contract. The can also resolve HTTP URL references to metadata using the type. - By default, a instance is tied to a single instance. You can change or replace the instance used by a by overriding the virtual method. Similarly, you can change or replace the instance used by a to make HTTP/GET requests by overriding the virtual method. + By default, a instance is tied to a single instance. You can change or replace the instance used by a by overriding the virtual method. Similarly, you can change or replace the instance used by a to make HTTP/GET requests by overriding the virtual method. ## In This Section diff --git a/docs/framework/wcf/feature-details/routing-introduction.md b/docs/framework/wcf/feature-details/routing-introduction.md index f064464f3d7dc..8953632c5882e 100644 --- a/docs/framework/wcf/feature-details/routing-introduction.md +++ b/docs/framework/wcf/feature-details/routing-introduction.md @@ -17,7 +17,7 @@ When starting, this behavior adds the objects together into filter tables ( objects). Incoming messages are evaluated against the message filters contained in the filter table, and for each **MessageFilter** that matches the message, forwarded to a destination endpoint. The filter table that should be used to route messages is specified by using either the **RoutingBehavior** in configuration or through code by using the **RoutingConfiguration** object. +The routing logic used to perform content-based routing of messages is defined by grouping multiple objects together into filter tables ( objects). Incoming messages are evaluated against the message filters contained in the filter table, and for each **MessageFilter** that matches the message, forwarded to a destination endpoint. The filter table that should be used to route messages is specified by using either the **RoutingBehavior** in configuration or through code by using the **RoutingConfiguration** object. ### Defining Endpoints @@ -105,7 +105,7 @@ The Routing Service provides several **MessageFilter** implementations that insp Multiple message filters are organized together into filter tables, which associate each **MessageFilter** with a destination endpoint. Optionally, the filter table can also be used to specify a list of back-up endpoints that the Routing Service will attempt to send the message to in the event of a transmission failure. -By default all message filters within a filter table are evaluated simultaneously; however, you can specify a that causes the message filters to be evaluated in a specific order. All entries with the highest priority are evaluated first, and message filters of lower priorities are not evaluated if a match is found at a higher priority level. For more information about filter tables, see [Message Filters](message-filters.md). +By default all message filters within a filter table are evaluated simultaneously; however, you can specify a that causes the message filters to be evaluated in a specific order. All entries with the highest priority are evaluated first, and message filters of lower priorities are not evaluated if a match is found at a higher priority level. For more information about filter tables, see [Message Filters](message-filters.md). The following examples use the , which evaluates to `true` for all messages. This **MessageFilter** is added to the "routingTable1" filter table, which associates the **MessageFilter** with the client endpoint named "CalculatorService". The **RoutingBehavior** then specifies that this table should be used to route messages processed by the service endpoint. @@ -148,7 +148,7 @@ rc.FilterTable.Add(new MatchAllMessageFilter(), endpointList); ``` > [!NOTE] -> By default, the Routing Service only evaluates the headers of the message. To allow the filters to access the message body, you must set to `false`. +> By default, the Routing Service only evaluates the headers of the message. To allow the filters to access the message body, you must set to `false`. **Multicast** @@ -222,7 +222,7 @@ The steps taken to create a new **MessageVersion** for the outbound message are - Return the new response message. -By default, the **SoapProcessingBehavior** is automatically added to the client endpoints by the when the service starts; however, you can control whether SOAP processing is added to all client endpoints by using the property. You can also add the behavior directly to a specific endpoint and enable or disable this behavior at the endpoint level if a more granular control of SOAP processing is required. +By default, the **SoapProcessingBehavior** is automatically added to the client endpoints by the when the service starts; however, you can control whether SOAP processing is added to all client endpoints by using the property. You can also add the behavior directly to a specific endpoint and enable or disable this behavior at the endpoint level if a more granular control of SOAP processing is required. > [!NOTE] > If SOAP processing is disabled for an endpoint that requires a different MessageVersion than that of the original request message, you must provide a custom mechanism for performing any SOAP modifications that are required before sending the message to the destination endpoint. @@ -250,7 +250,7 @@ rc.SoapProcessingEnabled = false; When you add additional client endpoints, or need to modify the filters that are used to route messages, you must have a way to update the configuration dynamically at runtime to prevent interrupting the service to the endpoints currently receiving messages through the Routing Service. Modifying a configuration file or the code of the host application is not always sufficient, because either method requires recycling the application, which would lead to the potential loss of any messages currently in transit and the potential for downtime while waiting on the service to restart. -You can only modify the **RoutingConfiguration** programmatically. While you can initially configure the service by using a configuration file, you can only modify the configuration at runtime by constructing a new **RoutingConfiguration** and passing it as a parameter to the method exposed by the service extension. Any messages currently in transit continue to be routed using the previous configuration, while messages received after the call to **ApplyConfiguration** use the new configuration. The following example demonstrates creating an instance of the Routing Service and then subsequently modifying the configuration. +You can only modify the **RoutingConfiguration** programmatically. While you can initially configure the service by using a configuration file, you can only modify the configuration at runtime by constructing a new **RoutingConfiguration** and passing it as a parameter to the method exposed by the service extension. Any messages currently in transit continue to be routed using the previous configuration, while messages received after the call to **ApplyConfiguration** use the new configuration. The following example demonstrates creating an instance of the Routing Service and then subsequently modifying the configuration. ```csharp RoutingConfiguration routingConfig = new RoutingConfiguration(); @@ -405,7 +405,7 @@ Impersonation with the routing service requires either the use of ASP.NET impers To use ASP.NET impersonation with the routing service, enable ASP.NET compatibility mode on the service hosting environment. The routing service has already been marked as allowing ASP.NET compatibility mode and impersonation will automatically be enabled. Impersonation is the only supported use of ASP.NET integration with the routing service. -To use Windows credential impersonation with the routing service you need to configure both the credentials and the service. The client credentials object (, accessible from the ) defines an property that must be set to permit impersonation. Finally, on the service you need to configure the behavior to set `ImpersonateCallerForAllOperations` to `true`. The routing service uses this flag to decide whether to create the clients for forwarding messages with impersonation enabled. +To use Windows credential impersonation with the routing service you need to configure both the credentials and the service. The client credentials object (, accessible from the ) defines an property that must be set to permit impersonation. Finally, on the service you need to configure the behavior to set `ImpersonateCallerForAllOperations` to `true`. The routing service uses this flag to decide whether to create the clients for forwarding messages with impersonation enabled. ## See also diff --git a/docs/framework/wcf/feature-details/routing-service.md b/docs/framework/wcf/feature-details/routing-service.md index 71d14d8a77531..c9c6f89296507 100644 --- a/docs/framework/wcf/feature-details/routing-service.md +++ b/docs/framework/wcf/feature-details/routing-service.md @@ -63,7 +63,7 @@ When providing a service for multiple clients, you may have a service level agre ## Dynamic Configuration -To support mission-critical systems, where messages must be processed without any service interruptions, it is vital that you be able to modify the configuration of components within the system at runtime. To support this need, the Routing Service provides an implementation, the , which allows dynamic updating of the Routing Service configuration at runtime. +To support mission-critical systems, where messages must be processed without any service interruptions, it is vital that you be able to modify the configuration of components within the system at runtime. To support this need, the Routing Service provides an implementation, the , which allows dynamic updating of the Routing Service configuration at runtime. For more information about dynamic configuration of the Routing Service, see [Routing Introduction](routing-introduction.md). diff --git a/docs/framework/wcf/feature-details/saml-tokens-and-claims.md b/docs/framework/wcf/feature-details/saml-tokens-and-claims.md index 20b31bf7eebf7..49e9a005ff400 100644 --- a/docs/framework/wcf/feature-details/saml-tokens-and-claims.md +++ b/docs/framework/wcf/feature-details/saml-tokens-and-claims.md @@ -1,11 +1,11 @@ --- title: "SAML Tokens and Claims" -description: Learn how WFC uses SAML tokens to carry statements that are sets of claims made by one entity about another entity. +description: Learn how WFC uses SAML tokens to carry statements that are sets of claims made by one entity about another entity. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "WCF, federation" - "federation" - "issued tokens" @@ -14,32 +14,32 @@ ms.assetid: 930b6e34-9eab-4e95-826c-4e06659bb977 --- # SAML Tokens and Claims -Security Assertions Markup Language (SAML) *tokens* are XML representations of claims. By default, SAML tokens Windows Communication Foundation (WCF) uses in federated security scenarios are *issued tokens*. - - SAML tokens carry statements that are sets of claims made by one entity about another entity. For example, in federated security scenarios, the statements are made by a security token service about a user in the system. The security token service signs the SAML token to indicate the veracity of the statements contained in the token. In addition, the SAML token is associated with cryptographic key material that the user of the SAML token proves knowledge of. This proof satisfies the relying party that the SAML token was, in fact, issued to that user. For example, in a typical scenario: - -1. A client requests a SAML token from a security token service, authenticating to that security token service by using Windows credentials. - -2. The security token service issues a SAML token to the client. The SAML token is signed with a certificate associated with the security token service and contains a proof key encrypted for the target service. - -3. The client also receives a copy of the *proof key*. The client then presents the SAML token to the application service (the *relying party*) and signs the message with that proof key. - -4. The signature over the SAML token tells the relying party that the security token service issued the token. The message signature created with the proof key tells the relying party that the token was issued to the client. - -## From Claims to SamlAttributes - - In WCF, statements in SAML tokens are modeled as objects, which can be populated directly from objects, provided the object has a property of and the property is of type . For example: - +Security Assertions Markup Language (SAML) *tokens* are XML representations of claims. By default, SAML tokens Windows Communication Foundation (WCF) uses in federated security scenarios are *issued tokens*. + + SAML tokens carry statements that are sets of claims made by one entity about another entity. For example, in federated security scenarios, the statements are made by a security token service about a user in the system. The security token service signs the SAML token to indicate the veracity of the statements contained in the token. In addition, the SAML token is associated with cryptographic key material that the user of the SAML token proves knowledge of. This proof satisfies the relying party that the SAML token was, in fact, issued to that user. For example, in a typical scenario: + +1. A client requests a SAML token from a security token service, authenticating to that security token service by using Windows credentials. + +2. The security token service issues a SAML token to the client. The SAML token is signed with a certificate associated with the security token service and contains a proof key encrypted for the target service. + +3. The client also receives a copy of the *proof key*. The client then presents the SAML token to the application service (the *relying party*) and signs the message with that proof key. + +4. The signature over the SAML token tells the relying party that the security token service issued the token. The message signature created with the proof key tells the relying party that the token was issued to the client. + +## From Claims to SamlAttributes + + In WCF, statements in SAML tokens are modeled as objects, which can be populated directly from objects, provided the object has a property of and the property is of type . For example: + [!code-csharp[c_CreateSTS#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_creatests/cs/source.cs#8)] - [!code-vb[c_CreateSTS#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#8)] - + [!code-vb[c_CreateSTS#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_creatests/vb/source.vb#8)] + > [!NOTE] -> When SAML tokens are serialized in messages, either when they are issued by a security token service or when they are presented by clients to services as part of authentication, the maximum message size quota must be sufficiently large to accommodate the SAML token and the other message parts. In normal cases, the default message size quotas are sufficient. However, in cases where a SAML token is large because it contains hundreds of claims, you may need to increase the quotas to accommodate the serialized token. For more information, see [Security Considerations for Data](security-considerations-for-data.md). - -## From SamlAttributes to Claims +> When SAML tokens are serialized in messages, either when they are issued by a security token service or when they are presented by clients to services as part of authentication, the maximum message size quota must be sufficiently large to accommodate the SAML token and the other message parts. In normal cases, the default message size quotas are sufficient. However, in cases where a SAML token is large because it contains hundreds of claims, you may need to increase the quotas to accommodate the serialized token. For more information, see [Security Considerations for Data](security-considerations-for-data.md). + +## From SamlAttributes to Claims + + When SAML tokens are received in messages, the various statements in the SAML token are turned into objects that are placed into the . The claims from each SAML statement are returned by the property of the and can be examined to determine whether to authenticate and authorize the user. - When SAML tokens are received in messages, the various statements in the SAML token are turned into objects that are placed into the . The claims from each SAML statement are returned by the property of the and can be examined to determine whether to authenticate and authorize the user. - ## See also - diff --git a/docs/framework/wcf/feature-details/secure-conversations-and-secure-sessions.md b/docs/framework/wcf/feature-details/secure-conversations-and-secure-sessions.md index 1da100379b9bc..7babfd12f2f91 100644 --- a/docs/framework/wcf/feature-details/secure-conversations-and-secure-sessions.md +++ b/docs/framework/wcf/feature-details/secure-conversations-and-secure-sessions.md @@ -6,12 +6,12 @@ ms.assetid: 48cb104a-532d-40ae-aa57-769dae103fda --- # Secure Conversations and Secure Sessions -A feature of Windows Communication Foundation (WCF) is the ability to establish secure sessions between two endpoints that authenticate each other and agree upon an encryption and digital signature process. For example, the service endpoint might require a client endpoint to send a security token based upon an X.509 certificate for authentication. Once the client is authenticated, the service endpoint returns a security context token (SCT) back to the client that is then used to secure all subsequent messages within the session. Establishing this secure session enables the set of messages that are exchanged between the two endpoints to be more efficient, because the SCT has a symmetric key. Asymmetric keys, which X.509 certificates are based upon, require significantly more computational power than symmetric keys when generating a digital signature or encrypting a set of data. - - The bootstrap policy (defined in section 6.2.7 of the [WS-SecurityPolicy](https://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ws-securitypolicy-1.2-spec-os.html) standard) contains the message security assertions used to secure the channel and authenticate the client prior to the RST/SCT and RSTR/SCT exchange. Certain WCF standard bindings have a `Security.Message.EstablishSecurityContext` property which controls whether secure conversation is used. When using custom bindings the bootstrap is indicated by nesting security binding elements, either through [\](../../configure-apps/file-schema/wcf/secureconversationbootstrap.md) in the configuration file, or by calling in code. - - For more information about sessions, see [Using Sessions](../using-sessions.md). - +A feature of Windows Communication Foundation (WCF) is the ability to establish secure sessions between two endpoints that authenticate each other and agree upon an encryption and digital signature process. For example, the service endpoint might require a client endpoint to send a security token based upon an X.509 certificate for authentication. Once the client is authenticated, the service endpoint returns a security context token (SCT) back to the client that is then used to secure all subsequent messages within the session. Establishing this secure session enables the set of messages that are exchanged between the two endpoints to be more efficient, because the SCT has a symmetric key. Asymmetric keys, which X.509 certificates are based upon, require significantly more computational power than symmetric keys when generating a digital signature or encrypting a set of data. + + The bootstrap policy (defined in section 6.2.7 of the [WS-SecurityPolicy](https://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ws-securitypolicy-1.2-spec-os.html) standard) contains the message security assertions used to secure the channel and authenticate the client prior to the RST/SCT and RSTR/SCT exchange. Certain WCF standard bindings have a `Security.Message.EstablishSecurityContext` property which controls whether secure conversation is used. When using custom bindings the bootstrap is indicated by nesting security binding elements, either through [\](../../configure-apps/file-schema/wcf/secureconversationbootstrap.md) in the configuration file, or by calling in code. + + For more information about sessions, see [Using Sessions](../using-sessions.md). + ## See also - [Sessions, Instancing, and Concurrency](sessions-instancing-and-concurrency.md) diff --git a/docs/framework/wcf/feature-details/securing-messages-using-message-security.md b/docs/framework/wcf/feature-details/securing-messages-using-message-security.md index 9e2da7bbdef6c..19c0e04c8165c 100644 --- a/docs/framework/wcf/feature-details/securing-messages-using-message-security.md +++ b/docs/framework/wcf/feature-details/securing-messages-using-message-security.md @@ -6,65 +6,65 @@ ms.assetid: a17ebe67-836b-4c52-9a81-2c3d58e225ee --- # Securing Messages Using Message Security -This section discusses WCF message security when using . - +This section discusses WCF message security when using . + > [!NOTE] -> Before reading through this topic, it is recommended that you read [Security Concepts](security-concepts.md). - - The following illustration provides a conceptual model of queued communication using WCF. This illustration and terminology are used to explain - - transport security concepts. - - ![Queued Application Diagram](media/distributed-queue-figure.jpg "Distributed-Queue-Figure") - - When sending queued messages using WCF, the WCF message is attached as a body of the Message Queuing (MSMQ) message. While transport security secures the entire MSMQ message, message (or SOAP) security only secures the body of the MSMQ message. - - The key concept of message security is that the client secures the message for the receiving application (service), unlike transport security where the client secures the message for the Target Queue. As such, MSMQ plays no part when securing the WCF message using message security. - - WCF message security adds security headers to the WCF message that integrate with existing security infrastructures, such as a certificate or the Kerberos protocol. - -## Message Credential Type - - Using message security, the service and client can present credentials to authenticate each another. You can select message security by setting the mode to `Message` or `Both` (that is, use both transport security and message security). - - The service can use the property to inspect the credential used to authenticate the client. This can also be used for further authorization checks that the service chooses to implement. - - This section explains the different credential types and how to use them with queues. - -### Certificate - - The certificate credential type uses an X.509 certificate to identify the service and the client. - - In a typical scenario, the client and the service are issued a valid certificate by a trusted certification authority. Then the connection is established, the client authenticates the validity of the service using the service's certificate to decide whether it can trust the service. Similarly, the service uses the client's certificate to validate the client trust. - - Given the disconnected nature of queues, the client and the service may not be online at the same time. As such, the client and service have to exchange certificates out-of-band. In particular, the client, by virtue of holding the service's certificate (which can be chained to a certification authority) in its trusted store, must trust that it is communicating with the correct service. For authenticating the client, the service uses the X.509 certificate attached with the message to matches it with the certificate in its store to verify the authenticity of the client. Again, the certificate must be chained to a certification authority. - - On a computer running Windows, certificates are held in several kinds of stores. For more information about the different stores, see [Certificate stores](/previous-versions/windows/it-pro/windows-server-2003/cc757138(v=ws.10)). - -### Windows - - Windows message credential type uses the Kerberos protocol. - - The Kerberos protocol is a security mechanism that authenticates users on a domain and allows the authenticated users to establish secure contexts with other entities on a domain. - - The problem with using the Kerberos protocol for queued communication is that the tickets that contain client identity that the Key Distribution Center (KDC) distributes are relatively short-lived. A *lifetime* is associated with the Kerberos ticket that indicates the validity of the ticket. As such, given high latency, you cannot be sure that the token is still valid for the service that authenticates the client. - - Note that when using this credential type, the service must be running under the SERVICE account. - +> Before reading through this topic, it is recommended that you read [Security Concepts](security-concepts.md). + + The following illustration provides a conceptual model of queued communication using WCF. This illustration and terminology are used to explain + + transport security concepts. + + ![Queued Application Diagram](media/distributed-queue-figure.jpg "Distributed-Queue-Figure") + + When sending queued messages using WCF, the WCF message is attached as a body of the Message Queuing (MSMQ) message. While transport security secures the entire MSMQ message, message (or SOAP) security only secures the body of the MSMQ message. + + The key concept of message security is that the client secures the message for the receiving application (service), unlike transport security where the client secures the message for the Target Queue. As such, MSMQ plays no part when securing the WCF message using message security. + + WCF message security adds security headers to the WCF message that integrate with existing security infrastructures, such as a certificate or the Kerberos protocol. + +## Message Credential Type + + Using message security, the service and client can present credentials to authenticate each another. You can select message security by setting the mode to `Message` or `Both` (that is, use both transport security and message security). + + The service can use the property to inspect the credential used to authenticate the client. This can also be used for further authorization checks that the service chooses to implement. + + This section explains the different credential types and how to use them with queues. + +### Certificate + + The certificate credential type uses an X.509 certificate to identify the service and the client. + + In a typical scenario, the client and the service are issued a valid certificate by a trusted certification authority. Then the connection is established, the client authenticates the validity of the service using the service's certificate to decide whether it can trust the service. Similarly, the service uses the client's certificate to validate the client trust. + + Given the disconnected nature of queues, the client and the service may not be online at the same time. As such, the client and service have to exchange certificates out-of-band. In particular, the client, by virtue of holding the service's certificate (which can be chained to a certification authority) in its trusted store, must trust that it is communicating with the correct service. For authenticating the client, the service uses the X.509 certificate attached with the message to matches it with the certificate in its store to verify the authenticity of the client. Again, the certificate must be chained to a certification authority. + + On a computer running Windows, certificates are held in several kinds of stores. For more information about the different stores, see [Certificate stores](/previous-versions/windows/it-pro/windows-server-2003/cc757138(v=ws.10)). + +### Windows + + Windows message credential type uses the Kerberos protocol. + + The Kerberos protocol is a security mechanism that authenticates users on a domain and allows the authenticated users to establish secure contexts with other entities on a domain. + + The problem with using the Kerberos protocol for queued communication is that the tickets that contain client identity that the Key Distribution Center (KDC) distributes are relatively short-lived. A *lifetime* is associated with the Kerberos ticket that indicates the validity of the ticket. As such, given high latency, you cannot be sure that the token is still valid for the service that authenticates the client. + + Note that when using this credential type, the service must be running under the SERVICE account. + The Kerberos protocol is used by default when choosing message credential. - -### Username Password - Using this property, the client can authenticate to the server using a username password in the security header of the message. - -### IssuedToken +### Username Password + + Using this property, the client can authenticate to the server using a username password in the security header of the message. + +### IssuedToken + + The client can use the security token service to issue a token that can then be attached to the message for the service to authenticate the client. + +## Using Transport and Message Security - The client can use the security token service to issue a token that can then be attached to the message for the service to authenticate the client. - -## Using Transport and Message Security + When using both transport security and message security, the certificate used to secure the message both at the transport and the SOAP message level must be the same. - When using both transport security and message security, the certificate used to secure the message both at the transport and the SOAP message level must be the same. - ## See also - [Securing Messages Using Transport Security](securing-messages-using-transport-security.md) diff --git a/docs/framework/wcf/feature-details/securing-messages-using-transport-security.md b/docs/framework/wcf/feature-details/securing-messages-using-transport-security.md index 1a5daeb9b2a6d..ff92789f73e31 100644 --- a/docs/framework/wcf/feature-details/securing-messages-using-transport-security.md +++ b/docs/framework/wcf/feature-details/securing-messages-using-transport-security.md @@ -6,104 +6,104 @@ ms.assetid: 9029771a-097e-448a-a13a-55d2878330b8 --- # Securing Messages Using Transport Security -This section discusses Message Queuing (MSMQ) transport security that you can use to secure messages sent to a queue. - +This section discusses Message Queuing (MSMQ) transport security that you can use to secure messages sent to a queue. + > [!NOTE] -> Before reading through this topic, it is recommended that you read [Security Concepts](security-concepts.md). - - The following illustration provides a conceptual model of queued communication using Windows Communication Foundation (WCF). This illustration and terminology is used to explain transport security concepts. - - ![Queued Application Diagram](media/distributed-queue-figure.jpg "Distributed-Queue-Figure") - - When sending queued messages using WCF with , the WCF message is attached as a body of the MSMQ message. Transport security secures the entire MSMQ message (MSMQ message headers or properties and the message body). Because it is the body of the MSMQ message, using transport security also secures the WCF message. - - The key concept behind transport security is that the client has to meet security requirements to get the message to the target queue. This is unlike Message security, where the message is secured for the application that receives the message. - - Transport security using and impacts how MSMQ messages are secured in-transit between the transmission queue and the target queue where secured implies: - -- Signing the message to ensure it is not tampered with. - -- Encrypting the message to ensure that it cannot be seen or tampered with. This is recommended but optional. - -- The target queue manager that identifies the sender of the message for non-repudiation. - - In MSMQ, independent of authentication, the target queue has an access control list (ACL) to check whether the client has permission to send the message to the target queue. The receiving application is also checked for permission to receive the message from the target queue. - -## WCF MSMQ Transport Security Properties - - MSMQ uses Windows security for authentication. It uses the Windows security identifier (SID) to identify the client and uses Active Directory directory service as the certificate authority when authenticating the client. This requires MSMQ to be installed with Active Directory integration. Because the Windows domain SID is used to identify the client, this security option is only meaningful when both the client and service are part of the same Windows domain. - - MSMQ also provides the ability to attach a certificate with the message that is not registered with Active Directory. In this case, it ensures that the message was signed using the attached certificate. - - WCF provides both these options as part of MSMQ transport security and they are the key pivot for transport security. - - By default, transport security is turned on. - - Given these basics, the following sections detail transport security properties bundled with and . - -#### MSMQ Authentication Mode - - The dictates whether to use the Windows domain security or an external certificate-based security to secure the message. In both authentication modes, the WCF queued transport channel uses the `CertificateValidationMode` specified in the service configuration. The certificate validation mode specifies the mechanism used to check the validity of the certificate. - - When transport security is turned on, the default setting is . - -#### Windows Domain Authentication Mode - - The choice of using Windows security requires Active Directory integration. is the default transport security mode. When this is set, the WCF channel attaches the Windows SID to the MSMQ message and uses its internal certificate obtained from Active Directory. MSMQ uses this internal certificate to secure the message. The receiving queue manager uses Active Directory to search and find a matching certificate to authenticate the client and checks that the SID also matches that of the client. This authentication step is executed if a certificate, either internally generated in the case of `WindowsDomain` authentication mode or externally generated in the case of `Certificate` authentication mode, is attached to the message even if the target queue is not marked as requiring authentication. - +> Before reading through this topic, it is recommended that you read [Security Concepts](security-concepts.md). + + The following illustration provides a conceptual model of queued communication using Windows Communication Foundation (WCF). This illustration and terminology is used to explain transport security concepts. + + ![Queued Application Diagram](media/distributed-queue-figure.jpg "Distributed-Queue-Figure") + + When sending queued messages using WCF with , the WCF message is attached as a body of the MSMQ message. Transport security secures the entire MSMQ message (MSMQ message headers or properties and the message body). Because it is the body of the MSMQ message, using transport security also secures the WCF message. + + The key concept behind transport security is that the client has to meet security requirements to get the message to the target queue. This is unlike Message security, where the message is secured for the application that receives the message. + + Transport security using and impacts how MSMQ messages are secured in-transit between the transmission queue and the target queue where secured implies: + +- Signing the message to ensure it is not tampered with. + +- Encrypting the message to ensure that it cannot be seen or tampered with. This is recommended but optional. + +- The target queue manager that identifies the sender of the message for non-repudiation. + + In MSMQ, independent of authentication, the target queue has an access control list (ACL) to check whether the client has permission to send the message to the target queue. The receiving application is also checked for permission to receive the message from the target queue. + +## WCF MSMQ Transport Security Properties + + MSMQ uses Windows security for authentication. It uses the Windows security identifier (SID) to identify the client and uses Active Directory directory service as the certificate authority when authenticating the client. This requires MSMQ to be installed with Active Directory integration. Because the Windows domain SID is used to identify the client, this security option is only meaningful when both the client and service are part of the same Windows domain. + + MSMQ also provides the ability to attach a certificate with the message that is not registered with Active Directory. In this case, it ensures that the message was signed using the attached certificate. + + WCF provides both these options as part of MSMQ transport security and they are the key pivot for transport security. + + By default, transport security is turned on. + + Given these basics, the following sections detail transport security properties bundled with and . + +#### MSMQ Authentication Mode + + The dictates whether to use the Windows domain security or an external certificate-based security to secure the message. In both authentication modes, the WCF queued transport channel uses the `CertificateValidationMode` specified in the service configuration. The certificate validation mode specifies the mechanism used to check the validity of the certificate. + + When transport security is turned on, the default setting is . + +#### Windows Domain Authentication Mode + + The choice of using Windows security requires Active Directory integration. is the default transport security mode. When this is set, the WCF channel attaches the Windows SID to the MSMQ message and uses its internal certificate obtained from Active Directory. MSMQ uses this internal certificate to secure the message. The receiving queue manager uses Active Directory to search and find a matching certificate to authenticate the client and checks that the SID also matches that of the client. This authentication step is executed if a certificate, either internally generated in the case of `WindowsDomain` authentication mode or externally generated in the case of `Certificate` authentication mode, is attached to the message even if the target queue is not marked as requiring authentication. + > [!NOTE] -> When creating a queue, you can mark the queue as an authenticated queue to indicate that the queue requires authentication of the client sending messages to the queue. This ensures that no unauthenticated messages are accepted in the queue. - - The SID attached with the message is also used to check against the target queue's ACL to ensure that the client has the authority to send messages to the queue. - -#### Certificate Authentication Mode - - The choice of using certificate authentication mode does not require Active Directory integration. In fact, in some cases, such as when MSMQ is installed in workgroup mode (without Active Directory integration) or when using the SOAP Reliable Messaging Protocol (SRMP) transfer protocol to send messages to the queue, only works. - - When sending a WCF message with , the WCF channel does not attach a Windows SID to the MSMQ message. As such, the target queue ACL must allow for `Anonymous` user access to send to the queue. The receiving queue manager checks whether the MSMQ message was signed with the certificate but does not perform any authentication. - - The certificate with its claims and identity information is populated in the by the WCF queued transport channel. The service can use this information to perform its own authentication of the sender. - -### MSMQ Protection Level - - The protection level dictates how to protect the MSMQ message to ensure that it is not tampered with. It is specified in the property. The default value is . - -#### Sign Protection Level - - The MSMQ message is signed using the internally generated certificate when using `WindowsDomain` authentication mode or an externally generated certificate when using `Certificate` authentication mode. - -#### Sign and Encrypt Protection Level - - The MSMQ message is signed using the internally generated certificate when using `WindowsDomain` authentication mode or externally generated certificate when using `Certificate` authentication mode. - - In addition to signing the message, the MSMQ message is encrypted using the public key of the certificate obtained from Active Directory that belongs to the receiving queue manager that hosts the target queue. The sending queue manager ensures that the MSMQ message is encrypted in transit. The receiving queue manager decrypts the MSMQ message using the private key of its internal certificate and stores the message in the queue (if authenticated and authorized) in clear text. - +> When creating a queue, you can mark the queue as an authenticated queue to indicate that the queue requires authentication of the client sending messages to the queue. This ensures that no unauthenticated messages are accepted in the queue. + + The SID attached with the message is also used to check against the target queue's ACL to ensure that the client has the authority to send messages to the queue. + +#### Certificate Authentication Mode + + The choice of using certificate authentication mode does not require Active Directory integration. In fact, in some cases, such as when MSMQ is installed in workgroup mode (without Active Directory integration) or when using the SOAP Reliable Messaging Protocol (SRMP) transfer protocol to send messages to the queue, only works. + + When sending a WCF message with , the WCF channel does not attach a Windows SID to the MSMQ message. As such, the target queue ACL must allow for `Anonymous` user access to send to the queue. The receiving queue manager checks whether the MSMQ message was signed with the certificate but does not perform any authentication. + + The certificate with its claims and identity information is populated in the by the WCF queued transport channel. The service can use this information to perform its own authentication of the sender. + +### MSMQ Protection Level + + The protection level dictates how to protect the MSMQ message to ensure that it is not tampered with. It is specified in the property. The default value is . + +#### Sign Protection Level + + The MSMQ message is signed using the internally generated certificate when using `WindowsDomain` authentication mode or an externally generated certificate when using `Certificate` authentication mode. + +#### Sign and Encrypt Protection Level + + The MSMQ message is signed using the internally generated certificate when using `WindowsDomain` authentication mode or externally generated certificate when using `Certificate` authentication mode. + + In addition to signing the message, the MSMQ message is encrypted using the public key of the certificate obtained from Active Directory that belongs to the receiving queue manager that hosts the target queue. The sending queue manager ensures that the MSMQ message is encrypted in transit. The receiving queue manager decrypts the MSMQ message using the private key of its internal certificate and stores the message in the queue (if authenticated and authorized) in clear text. + > [!NOTE] -> To encrypt the message, Active Directory access is required (`UseActiveDirectory` property of must be set to `true`) and can be used with both and . - -#### None Protection Level +> To encrypt the message, Active Directory access is required (`UseActiveDirectory` property of must be set to `true`) and can be used with both and . + +#### None Protection Level + + This is implied when is set to . This cannot be a valid value for any other authentication modes. - This is implied when is set to . This cannot be a valid value for any other authentication modes. - > [!NOTE] -> If the MSMQ message is signed, MSMQ checks whether the message is signed with the attached certificate (internal or external) independent of the state of the queue, that is, authenticated queue or not. - -### MSMQ Encryption Algorithm - - The encryption algorithm specifies the algorithm to use to encrypt the MSMQ message on the wire. This property is used only if is set to . - - The supported algorithms are `RC4Stream` and `AES` and the default is `RC4Stream`. - - You can use the `AES` algorithm only if the sender has MSMQ 4.0 installed. In addition, the target queue must also be hosted on MSMQ 4.0. - -### MSMQ Hash Algorithm - - The hash algorithm specifies the algorithm used to create a digital signature of the MSMQ message. The receiving queue manager uses this same algorithm to authenticate the MSMQ message. This property is used only if is set to or . - +> If the MSMQ message is signed, MSMQ checks whether the message is signed with the attached certificate (internal or external) independent of the state of the queue, that is, authenticated queue or not. + +### MSMQ Encryption Algorithm + + The encryption algorithm specifies the algorithm to use to encrypt the MSMQ message on the wire. This property is used only if is set to . + + The supported algorithms are `RC4Stream` and `AES` and the default is `RC4Stream`. + + You can use the `AES` algorithm only if the sender has MSMQ 4.0 installed. In addition, the target queue must also be hosted on MSMQ 4.0. + +### MSMQ Hash Algorithm + + The hash algorithm specifies the algorithm used to create a digital signature of the MSMQ message. The receiving queue manager uses this same algorithm to authenticate the MSMQ message. This property is used only if is set to or . + The supported algorithms are `MD5`, `SHA1`, `SHA256`, and `SHA512`. The default is `SHA1`. Due to collision problems with MD5/SHA1, Microsoft recommends SHA256 or better. - + ## See also - [Queues Overview](queues-overview.md) diff --git a/docs/framework/wcf/feature-details/securing-peer-channel-applications.md b/docs/framework/wcf/feature-details/securing-peer-channel-applications.md index b25601ea5c670..3e0cc3aa86e6d 100644 --- a/docs/framework/wcf/feature-details/securing-peer-channel-applications.md +++ b/docs/framework/wcf/feature-details/securing-peer-channel-applications.md @@ -6,44 +6,44 @@ ms.assetid: d4a0311d-3f78-4525-9c4b-5c93c4492f28 --- # Securing Peer Channel Applications -Like other bindings under the WinFX, `NetPeerTcpBinding` has security enabled by default and offers both transport- and message-based security (or both). This topic discusses these two types of security. The type of security is specified by the security mode tag in the binding specification (`Mode`). - -## Transport-Based Security - - Peer Channel supports two types of authentication credentials for securing transport, both of which require setting out the `ClientCredentialSettings.Peer` property on the associated `ChannelFactory`: - -- Password. Clients use knowledge of a secret password to authenticate connections. When this credential type is used, `ClientCredentialSettings.Peer.MeshPassword` must carry a valid password and optionally an `X509Certificate2` instance. - -- Certificate. Specific application authentication is used. When this credential type is used, you must use a concrete implementation of in `ClientCredentialSettings.Peer.PeerAuthentication`. - -## Message-Based Security - - Using message security, an application can sign outgoing messages so that all receiving parties can verify the message is sent by a trusted party and that the message was not tampered with. Currently, Peer Channel supports only X.509 credential message signing. - -## Best Practices - -- This section discusses the best practices for securing Peer Channel applications. - -### Enable Security with Peer Channel Applications - - Due to the distributed nature of the Peer Channel protocols, it is hard to enforce mesh membership, confidentiality, and privacy in an unsecured mesh. It is also important to remember to secure communication between clients and the resolver service. Under Peer Name Resolution Protocol (PNRP), use secure names to avoid spoofing and other common attacks. Secure a custom resolver service by enabling security on the connection clients use to contact the resolver service, including both message- and transport-based security. - -### Use the Strongest Possible Security Model - - For example, if each member of the mesh needs to be individually identified, use certificate-based authentication model. If that is not possible, use password-based authentication following current recommendations to keep them secure. This includes sharing passwords only with trusted parties, transmitting passwords using a secure medium, changing passwords frequently, and ensuring that passwords are strong (at least eight characters long, include at least one letter from both cases, a digit, and a special character). - -### Never Accept Self-Signed Certificates - - Never accept a certificate credential based on subject names. Note that anyone can create a certificate, and anyone can choose a name that you are validating. To avoid the possibility of spoofing, validate certificates based on issuing authority credentials (either a trusted issuer or a root certification authority). - -### Use Message Authentication - - Use message authentication to verify that a message originated from a trusted source and that no one has tampered with the message during transmission. Without message authentication, it is easy for a malicious client to spoof or tamper with messages in the mesh. - -## Peer Channel Code Examples - - [Peer Channel Scenarios](peer-channel-scenarios.md) - +Like other bindings under the WinFX, `NetPeerTcpBinding` has security enabled by default and offers both transport- and message-based security (or both). This topic discusses these two types of security. The type of security is specified by the security mode tag in the binding specification (`Mode`). + +## Transport-Based Security + + Peer Channel supports two types of authentication credentials for securing transport, both of which require setting out the `ClientCredentialSettings.Peer` property on the associated `ChannelFactory`: + +- Password. Clients use knowledge of a secret password to authenticate connections. When this credential type is used, `ClientCredentialSettings.Peer.MeshPassword` must carry a valid password and optionally an `X509Certificate2` instance. + +- Certificate. Specific application authentication is used. When this credential type is used, you must use a concrete implementation of in `ClientCredentialSettings.Peer.PeerAuthentication`. + +## Message-Based Security + + Using message security, an application can sign outgoing messages so that all receiving parties can verify the message is sent by a trusted party and that the message was not tampered with. Currently, Peer Channel supports only X.509 credential message signing. + +## Best Practices + +- This section discusses the best practices for securing Peer Channel applications. + +### Enable Security with Peer Channel Applications + + Due to the distributed nature of the Peer Channel protocols, it is hard to enforce mesh membership, confidentiality, and privacy in an unsecured mesh. It is also important to remember to secure communication between clients and the resolver service. Under Peer Name Resolution Protocol (PNRP), use secure names to avoid spoofing and other common attacks. Secure a custom resolver service by enabling security on the connection clients use to contact the resolver service, including both message- and transport-based security. + +### Use the Strongest Possible Security Model + + For example, if each member of the mesh needs to be individually identified, use certificate-based authentication model. If that is not possible, use password-based authentication following current recommendations to keep them secure. This includes sharing passwords only with trusted parties, transmitting passwords using a secure medium, changing passwords frequently, and ensuring that passwords are strong (at least eight characters long, include at least one letter from both cases, a digit, and a special character). + +### Never Accept Self-Signed Certificates + + Never accept a certificate credential based on subject names. Note that anyone can create a certificate, and anyone can choose a name that you are validating. To avoid the possibility of spoofing, validate certificates based on issuing authority credentials (either a trusted issuer or a root certification authority). + +### Use Message Authentication + + Use message authentication to verify that a message originated from a trusted source and that no one has tampered with the message during transmission. Without message authentication, it is easy for a malicious client to spoof or tamper with messages in the mesh. + +## Peer Channel Code Examples + + [Peer Channel Scenarios](peer-channel-scenarios.md) + ## See also - [Peer Channel Security](peer-channel-security.md) diff --git a/docs/framework/wcf/feature-details/security-considerations-for-data.md b/docs/framework/wcf/feature-details/security-considerations-for-data.md index dc01ed4fa9615..0397131197df5 100644 --- a/docs/framework/wcf/feature-details/security-considerations-for-data.md +++ b/docs/framework/wcf/feature-details/security-considerations-for-data.md @@ -60,7 +60,7 @@ Denial-of-service attacks are usually mitigated using quotas. When a quota is ex The quota exceeded scenario is recoverable; if encountered in a running service, the message currently being processed is discarded and the service keeps running and processes further messages. The out-of-memory and stack overflow scenarios, however, are not recoverable anywhere in the .NET Framework; the service terminates if it encounters such exceptions. -Quotas in WCF do not involve any pre-allocation. For example, if the quota (found on various classes) is set to 128 KB, it does not mean that 128 KB is automatically allocated for each message. The actual amount allocated depends on the actual incoming message size. +Quotas in WCF do not involve any pre-allocation. For example, if the quota (found on various classes) is set to 128 KB, it does not mean that 128 KB is automatically allocated for each message. The actual amount allocated depends on the actual incoming message size. Many quotas are available at the transport layer. These are quotas enforced by the specific transport channel in use (HTTP, TCP, and so on). While this topic discusses some of these quotas, these quotas are described in detail in [Transport Quotas](transport-quotas.md). @@ -70,11 +70,11 @@ A vulnerability exists when data contracts contain hashtables or collections. Th ## Limiting Memory Consumption Without Streaming -The security model around large messages depends on whether streaming is in use. In the basic, non-streamed case, messages are buffered into memory. In this case, use the quota on the or on the system-provided bindings to protect against large messages by limiting the maximum message size to access. Note that a service may be processing multiple messages at the same time, in which case they are all in memory. Use the throttling feature to mitigate this threat. +The security model around large messages depends on whether streaming is in use. In the basic, non-streamed case, messages are buffered into memory. In this case, use the quota on the or on the system-provided bindings to protect against large messages by limiting the maximum message size to access. Note that a service may be processing multiple messages at the same time, in which case they are all in memory. Use the throttling feature to mitigate this threat. Also note that `MaxReceivedMessageSize` does not place an upper bound on per-message memory consumption, but limits it to within a constant factor. For example, if the `MaxReceivedMessageSize` is 1 MB and a 1-MB message is received and then deserialized, additional memory is required to contain the deserialized object graph, resulting in total memory consumption well over 1 MB. For this reason, avoid creating serializable types that could result in significant memory consumption without much incoming data. For example, a data contract "MyContract" with 50 optional data member fields and an additional 100 private fields could be instantiated with the XML construction "\". This XML results in memory being accessed for 150 fields. Note that data members are optional by default. The problem is compounded when such a type is part of an array. -`MaxReceivedMessageSize` alone is not enough to prevent all denial-of-service attacks. For example, the deserializer may be forced to deserialize a deeply-nested object graph (an object that contains another object that contains yet another one, and so on) by an incoming message. Both the and the call methods in a nested way to deserialize such graphs. Deep nesting of method calls may result in an unrecoverable . This threat is mitigated by setting the quota to limit the level of XML nesting, as discussed in the "Using XML Safely" section later in the topic. +`MaxReceivedMessageSize` alone is not enough to prevent all denial-of-service attacks. For example, the deserializer may be forced to deserialize a deeply-nested object graph (an object that contains another object that contains yet another one, and so on) by an incoming message. Both the and the call methods in a nested way to deserialize such graphs. Deep nesting of method calls may result in an unrecoverable . This threat is mitigated by setting the quota to limit the level of XML nesting, as discussed in the "Using XML Safely" section later in the topic. Setting additional quotas to `MaxReceivedMessageSize` is especially important when using binary XML encoding. Using binary encoding is somewhat equivalent to compression: a small group of bytes in the incoming message may represent a lot of data. Thus, even a message fitting into the `MaxReceivedMessageSize` limit may take up much more memory in fully expanded form. To mitigate such XML-specific threats, all of the XML reader quotas must be set correctly, as discussed in the "Using XML Safely" section later in this topic. @@ -88,7 +88,7 @@ To mitigate this threat, specific quota settings exist on various WCF data-proce The `MaxBufferSize` property limits any bulk buffering WCF does. For example, WCF always buffers SOAP headers and SOAP faults, as well as any MIME parts found to be not in the natural reading order in an Message Transmission Optimization Mechanism (MTOM) message. This setting limits the amount of buffering in all these cases. -WCF accomplishes this by passing the `MaxBufferSize` value to the various components that may buffer. For example, some overloads of the class take a `maxSizeOfHeaders` parameter. WCF passes the `MaxBufferSize` value to this parameter to limit the amount of SOAP header buffering. It is important to set this parameter when using the class directly. In general, when using a component in WCF that takes quota parameters, it is important to understand the security implications of these parameters and set them correctly. +WCF accomplishes this by passing the `MaxBufferSize` value to the various components that may buffer. For example, some overloads of the class take a `maxSizeOfHeaders` parameter. WCF passes the `MaxBufferSize` value to this parameter to limit the amount of SOAP header buffering. It is important to set this parameter when using the class directly. In general, when using a component in WCF that takes quota parameters, it is important to understand the security implications of these parameters and set them correctly. The MTOM message encoder also has a `MaxBufferSize` setting. When using standard bindings, this is set automatically to the transport-level `MaxBufferSize` value. However, when using the MTOM message encoder binding element to construct a custom binding, it is important to set the `MaxBufferSize` property to a safe value when streaming is used. @@ -102,11 +102,11 @@ Many possible attacks arise from mixing streaming and non-streaming programming For this reason, avoid mixing stream-based and non-streamed operations in the same contract. If you absolutely must mix the two programming models, use the following precautions: -- Turn off the feature by setting the property of the to `true`. This ensures that only members that are a part of the contract are deserialized. +- Turn off the feature by setting the property of the to `true`. This ensures that only members that are a part of the contract are deserialized. -- Set the property of the to a safe value. This quota is also available on the attribute or through configuration. This quota limits the number of objects that are deserialized in one deserialization episode. Normally, each operation parameter or message body part in a message contract is deserialized in one episode. When deserializing arrays, each array entry is counted as a separate object. +- Set the property of the to a safe value. This quota is also available on the attribute or through configuration. This quota limits the number of objects that are deserialized in one deserialization episode. Normally, each operation parameter or message body part in a message contract is deserialized in one episode. When deserializing arrays, each array entry is counted as a separate object. -- Set all of the XML reader quotas to safe values. Pay attention to , , and and avoid strings in non-streaming operations. +- Set all of the XML reader quotas to safe values. Pay attention to , , and and avoid strings in non-streaming operations. - Review the list of known types, keeping in mind that any one of them can be instantiated at any time (see the "Preventing Unintended Types from Being Loaded" section later in this topic). @@ -116,7 +116,7 @@ For this reason, avoid mixing stream-based and non-streamed operations in the sa - Do not use the , arrays, arrays, or types that implement in the list of known types. -The preceding precautions apply when the non-streamed operation uses the . Never mix streaming and non-streaming programming models on the same service if you are using the , because it does not have the protection of the quota. +The preceding precautions apply when the non-streamed operation uses the . Never mix streaming and non-streaming programming models on the same service if you are using the , because it does not have the protection of the quota. ### Slow Stream Attacks @@ -135,7 +135,7 @@ The XML Infoset forms the basis of all message processing in WCF. When accepting Some of the security features on these readers are always active. For example, the readers never process document type definitions (DTDs), which are a potential source of denial-of-service attacks and should never appear in legitimate SOAP messages. Other security features include reader quotas that must be configured, which are described in the following section. -When working directly with XML readers (such as when writing your own custom encoder or when working directly with the class), always use the WCF secure readers when there is a chance of working with untrusted data. Create the secure readers by calling one of the static factory method overloads of , , or on the class. When creating a reader, pass in secure quota values. Do not call the `Create` method overloads. These do not create a WCF reader. Instead, a reader is created that is not protected by the security features described in this section. +When working directly with XML readers (such as when writing your own custom encoder or when working directly with the class), always use the WCF secure readers when there is a chance of working with untrusted data. Create the secure readers by calling one of the static factory method overloads of , , or on the class. When creating a reader, pass in secure quota values. Do not call the `Create` method overloads. These do not create a WCF reader. Instead, a reader is created that is not protected by the security features described in this section. ### Reader Quotas @@ -143,7 +143,7 @@ The secure XML readers have five configurable quotas. These are normally configu #### MaxBytesPerRead -This quota limits the number of bytes that are read in a single `Read` operation when reading the element start tag and its attributes. (In non-streamed cases, the element name itself is not counted against the quota.) is important for the following reasons: +This quota limits the number of bytes that are read in a single `Read` operation when reading the element start tag and its attributes. (In non-streamed cases, the element name itself is not counted against the quota.) is important for the following reasons: - The element name and its attributes are always buffered in memory when they are being read. Therefore, it is important to set this quota correctly in streaming mode to prevent excessive buffering when streaming is expected. See the `MaxDepth` quota section for information about the actual amount of buffering that takes place. @@ -151,7 +151,7 @@ This quota limits the number of bytes that are read in a single `Read` operation #### MaxDepth -This quota limits the maximum nesting depth of XML elements. For example, the document "\\\\\" has a nesting depth of three. is important for the following reasons: +This quota limits the maximum nesting depth of XML elements. For example, the document "\\\\\" has a nesting depth of three. is important for the following reasons: - `MaxDepth` interacts with `MaxBytesPerRead`: the reader always keeps data in memory for the current element and all of its ancestors, so the maximum memory consumption of the reader is proportional to the product of these two settings. @@ -163,11 +163,11 @@ This quota limits the size of the reader’s *nametable*. The nametable contains #### MaxStringContentLength -This quota limits the maximum string size that the XML reader returns. This quota does not limit memory consumption in the XML reader itself, but in the component that is using the reader. For example, when the uses a reader secured with , it does not deserialize strings larger than this quota. When using the class directly, not all methods respect this quota, but only the methods that are specifically designed to read strings, such as the method. The property on the reader is not affected by this quota, and thus should not be used when the protection this quota provides is necessary. +This quota limits the maximum string size that the XML reader returns. This quota does not limit memory consumption in the XML reader itself, but in the component that is using the reader. For example, when the uses a reader secured with , it does not deserialize strings larger than this quota. When using the class directly, not all methods respect this quota, but only the methods that are specifically designed to read strings, such as the method. The property on the reader is not affected by this quota, and thus should not be used when the protection this quota provides is necessary. #### MaxArrayLength -This quota limits the maximum size of an array of primitives that the XML reader returns, including byte arrays. This quota does not limit memory consumption in the XML reader itself, but in whatever component that is using the reader. For example, when the uses a reader secured with , it does not deserialize byte arrays larger than this quota. It is important to set this quota when attempting to mix streaming and buffered programming models in a single contract. Keep in mind that when using the class directly, only the methods that are specifically designed to read arrays of arbitrary size of certain primitive types, such as , respect this quota. +This quota limits the maximum size of an array of primitives that the XML reader returns, including byte arrays. This quota does not limit memory consumption in the XML reader itself, but in whatever component that is using the reader. For example, when the uses a reader secured with , it does not deserialize byte arrays larger than this quota. It is important to set this quota when attempting to mix streaming and buffered programming models in a single contract. Keep in mind that when using the class directly, only the methods that are specifically designed to read arrays of arbitrary size of certain primitive types, such as , respect this quota. ## Threats Specific to the Binary Encoding @@ -177,15 +177,15 @@ There are two kinds of dictionaries: *static* and *dynamic*. The static dictiona The dynamic dictionaries feature allows messages to define their own strings and associate them with short codes. These string-to-code mappings are kept in memory during the entire communication session, such that subsequent messages do not have to resend the strings and can utilize codes that are already defined. These strings may be of arbitrary length and thus pose a more serious threat than those in the static dictionary. -The first threat that must be mitigated is the possibility of the dynamic dictionary (the string-to-code mapping table) becoming too large. This dictionary may be expanded over the course of several messages, and so the `MaxReceivedMessageSize` quota offers no protection because it applies only to each message separately. Therefore, a separate property exists on the that limits the size of the dictionary. +The first threat that must be mitigated is the possibility of the dynamic dictionary (the string-to-code mapping table) becoming too large. This dictionary may be expanded over the course of several messages, and so the `MaxReceivedMessageSize` quota offers no protection because it applies only to each message separately. Therefore, a separate property exists on the that limits the size of the dictionary. Unlike most other quotas, this quota also applies when writing messages. If it is exceeded when reading a message, the `QuotaExceededException` is thrown as usual. If it is exceeded when writing a message, any strings that cause the quota to be exceeded are written as-is, without using the dynamic dictionaries feature. ### Dictionary Expansion Threats -A significant class of binary-specific attacks arises from dictionary expansion. A small message in binary form may turn into a very large message in fully expanded textual form if it makes extensive use of the string dictionaries feature. The expansion factor for dynamic dictionary strings is limited by the quota, because no dynamic dictionary string exceeds the maximum size of the entire dictionary. +A significant class of binary-specific attacks arises from dictionary expansion. A small message in binary form may turn into a very large message in fully expanded textual form if it makes extensive use of the string dictionaries feature. The expansion factor for dynamic dictionary strings is limited by the quota, because no dynamic dictionary string exceeds the maximum size of the entire dictionary. -The , `MaxStringContentLength`, and `MaxArrayLength` properties only limit memory consumption. They are normally not required to mitigate any threats in the non-streamed usage because memory usage is already limited by `MaxReceivedMessageSize`. However, `MaxReceivedMessageSize` counts pre-expansion bytes. When binary encoding is in use, memory consumption could potentially go beyond `MaxReceivedMessageSize`, limited only by a factor of . For this reason, it is important to always set all of the reader quotas (especially ) when using the binary encoding. +The , `MaxStringContentLength`, and `MaxArrayLength` properties only limit memory consumption. They are normally not required to mitigate any threats in the non-streamed usage because memory usage is already limited by `MaxReceivedMessageSize`. However, `MaxReceivedMessageSize` counts pre-expansion bytes. When binary encoding is in use, memory consumption could potentially go beyond `MaxReceivedMessageSize`, limited only by a factor of . For this reason, it is important to always set all of the reader quotas (especially ) when using the binary encoding. When using binary encoding together with the , the `IExtensibleDataObject` interface can be misused to mount a dictionary expansion attack. This interface essentially provides unlimited storage for arbitrary data that is not a part of the contract. If quotas cannot be set low enough such that `MaxSessionSize` multiplied by `MaxReceivedMessageSize` does not pose a problem, disable the `IExtensibleDataObject` feature when using the binary encoding. Set the `IgnoreExtensionDataObject` property to `true` on the `ServiceBehaviorAttribute` attribute. Alternatively, do not implement the `IExtensibleDataObject` interface. For more information, see [Forward-Compatible Data Contracts](forward-compatible-data-contracts.md). @@ -290,11 +290,11 @@ The is a serializa Because the message itself may indicate any type can be loaded, the mechanism is inherently insecure and should be used only with trusted data. For more information, see the [BinaryFormatter security guide](../../../standard/serialization/binaryformatter-security-guide.md). -Even when used with trusted data, the incoming data may insufficiently specify the type to load, especially if the property is set to . Anyone with access to the application’s directory or to the global assembly cache can substitute a malicious type in place of the one that is supposed to load. Always ensure the security of your application’s directory and of the global assembly cache by correctly setting permissions. +Even when used with trusted data, the incoming data may insufficiently specify the type to load, especially if the property is set to . Anyone with access to the application’s directory or to the global assembly cache can substitute a malicious type in place of the one that is supposed to load. Always ensure the security of your application’s directory and of the global assembly cache by correctly setting permissions. In general, if you allow partially trusted code access to your `NetDataContractSerializer` instance or otherwise control the surrogate selector () or the serialization binder (), the code may exercise a great deal of control over the serialization/deserialization process. For example, it may inject arbitrary types, lead to information disclosure, tamper with the resulting object graph or serialized data, or overflow the resultant serialized stream. -Another security concern with the `NetDataContractSerializer` is a denial of service, not a malicious code execution threat. When using the `NetDataContractSerializer`, always set the quota to a safe value. It is easy to construct a small malicious message that allocates an array of objects whose size is limited only by this quota. +Another security concern with the `NetDataContractSerializer` is a denial of service, not a malicious code execution threat. When using the `NetDataContractSerializer`, always set the quota to a safe value. It is easy to construct a small malicious message that allocates an array of objects whose size is limited only by this quota. ### XmlSerializer-Specific Threats @@ -324,7 +324,7 @@ Note the following concerns regarding threats related to code running with parti - For a deserialized object, if the XML reader (or the data therein) comes from partially-trusted code, treat the resulting deserialized object as untrusted data. -- The fact that the type has no public members does not mean that data within it is secure. For example, if you deserialize from a privileged data source into an object in which some data resides, then hand that object to partially-trusted code, the partially-trusted code can read the data in the `ExtensionDataObject` by serializing the object. Consider setting to `true` when deserializing from a privileged data source into an object that is later passed to partially-trusted code. +- The fact that the type has no public members does not mean that data within it is secure. For example, if you deserialize from a privileged data source into an object in which some data resides, then hand that object to partially-trusted code, the partially-trusted code can read the data in the `ExtensionDataObject` by serializing the object. Consider setting to `true` when deserializing from a privileged data source into an object that is later passed to partially-trusted code. - and support the serialization of private, protected, internal, and public members in full trust. However, in partial trust, only public members can be serialized. A is thrown if an application attempts to serialize a non-public member. @@ -374,15 +374,15 @@ When implementing `WebScriptEnablingBehavior`, the user has the option to expose WCF is a flexible and customizable system. Most of the contents of this topic focus on the most common WCF usage scenarios. However, it is possible to compose components WCF provides in many different ways. It is important to understand the security implications of using each component. In particular: -- When you must use XML readers, use the readers the class provides as opposed to any other readers. Safe readers are created using , , or methods. Do not use the method. Always configure the readers with safe quotas. The serialization engines in WCF are secure only when used with secure XML readers from WCF. +- When you must use XML readers, use the readers the class provides as opposed to any other readers. Safe readers are created using , , or methods. Do not use the method. Always configure the readers with safe quotas. The serialization engines in WCF are secure only when used with secure XML readers from WCF. -- When using the to deserialize potentially untrusted data, always set the property. +- When using the to deserialize potentially untrusted data, always set the property. - When creating a message, set the `maxSizeOfHeaders` parameter if `MaxReceivedMessageSize` does not offer enough protection. - When creating an encoder, always configure the relevant quotas, such as `MaxSessionSize` and `MaxBufferSize`. -- When using an XPath message filter, set the to limit the amount of XML nodes the filter visits. Do not use XPath expressions that could take a long time to compute without visiting many nodes. +- When using an XPath message filter, set the to limit the amount of XML nodes the filter visits. Do not use XPath expressions that could take a long time to compute without visiting many nodes. - In general, when using any component that accepts a quota, understand its security implications and set it to a safe value. diff --git a/docs/framework/wcf/feature-details/security-considerations-for-secure-sessions.md b/docs/framework/wcf/feature-details/security-considerations-for-secure-sessions.md index 6857e3703a77e..927d2d7c53383 100644 --- a/docs/framework/wcf/feature-details/security-considerations-for-secure-sessions.md +++ b/docs/framework/wcf/feature-details/security-considerations-for-secure-sessions.md @@ -6,18 +6,18 @@ ms.assetid: 0d5be591-9a7b-4a6f-a906-95d3abafe8db --- # Security Considerations for Secure Sessions -You should consider the following items that affect security when implementing secure sessions. For more information about security considerations, see [Security Considerations](security-considerations-in-wcf.md) and [Best Practices for Security](best-practices-for-security-in-wcf.md). - -## Secure Sessions and Metadata - - When a secure session is established and the property is set to `false`, Windows Communication Foundation (WCF) sends an `mssp:MustNotSendCancel` assertion as part of the metadata in the Web Services Description Language (WSDL) document for the service endpoint. The `mssp:MustNotSendCancel` assertion informs clients that the service does not respond to requests to cancel the secure session. When the property is set to `true`, then WCF does not emit an `mssp:MustNotSendCancel` assertion in the WSDL document. Clients are expected to send a cancel request to the service when they no longer require the secure session. When a client is generated using the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md), the client code reacts appropriately to the presence or absence of the `mssp:MustNotSendCancel` assertion. - -## Secure Conversations and Custom Tokens - - There are some issues with mixing custom tokens and derived keys due to the way it is defined in the WS-SecureConversation specification. The specification says that `wsse:SecurityTokenReference` is an optional element that references the derived token: "`/wsc:DerivedKeyToken/wsse:SecurityTokenReference` This optional element is used to specify security context token, security token, or shared key/secret used for the derivation. If not specified, it is assumed that the recipient can determine the shared key from the message context. If the context cannot be determined, then a fault such as `wsc:UnknownDerivationSource` should be raised." - - This means that if you want a custom token to be derived, you should wrap its clause type in a `SecurityTokenReference` element. There is an option to turn off derivation but the default is to derive keys. If you fail to wrap the key, serializing the derived key token succeeds, but attempting to deserialize it throws an exception. - +You should consider the following items that affect security when implementing secure sessions. For more information about security considerations, see [Security Considerations](security-considerations-in-wcf.md) and [Best Practices for Security](best-practices-for-security-in-wcf.md). + +## Secure Sessions and Metadata + + When a secure session is established and the property is set to `false`, Windows Communication Foundation (WCF) sends an `mssp:MustNotSendCancel` assertion as part of the metadata in the Web Services Description Language (WSDL) document for the service endpoint. The `mssp:MustNotSendCancel` assertion informs clients that the service does not respond to requests to cancel the secure session. When the property is set to `true`, then WCF does not emit an `mssp:MustNotSendCancel` assertion in the WSDL document. Clients are expected to send a cancel request to the service when they no longer require the secure session. When a client is generated using the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md), the client code reacts appropriately to the presence or absence of the `mssp:MustNotSendCancel` assertion. + +## Secure Conversations and Custom Tokens + + There are some issues with mixing custom tokens and derived keys due to the way it is defined in the WS-SecureConversation specification. The specification says that `wsse:SecurityTokenReference` is an optional element that references the derived token: "`/wsc:DerivedKeyToken/wsse:SecurityTokenReference` This optional element is used to specify security context token, security token, or shared key/secret used for the derivation. If not specified, it is assumed that the recipient can determine the shared key from the message context. If the context cannot be determined, then a fault such as `wsc:UnknownDerivationSource` should be raised." + + This means that if you want a custom token to be derived, you should wrap its clause type in a `SecurityTokenReference` element. There is an option to turn off derivation but the default is to derive keys. If you fail to wrap the key, serializing the derived key token succeeds, but attempting to deserialize it throws an exception. + ## See also - [How to: Disable Secure Sessions on a WSFederationHttpBinding](how-to-disable-secure-sessions-on-a-wsfederationhttpbinding.md) diff --git a/docs/framework/wcf/feature-details/security-considerations-with-metadata.md b/docs/framework/wcf/feature-details/security-considerations-with-metadata.md index 21352ddcba6a7..7420e451193df 100644 --- a/docs/framework/wcf/feature-details/security-considerations-with-metadata.md +++ b/docs/framework/wcf/feature-details/security-considerations-with-metadata.md @@ -26,9 +26,9 @@ When using the metadata features in Windows Communication Foundation (WCF), cons ## Using Safe Techniques for Processing Metadata - Service metadata is frequently retrieved from a service over a network using standardized protocols such as WS-MetadataExchange (MEX). Many metadata formats include referencing mechanisms for pointing to additional metadata. The type automatically processes references for you in Web Services Description Language (WSDL) documents, XML Schema, and MEX documents. The size of the object created from the retrieved metadata is directly proportional to the value for the instance that is used and the `MaxReceivedMessageSize` value for the binding being used by that instance. Set these quotas to appropriate values as dictated by your scenario. + Service metadata is frequently retrieved from a service over a network using standardized protocols such as WS-MetadataExchange (MEX). Many metadata formats include referencing mechanisms for pointing to additional metadata. The type automatically processes references for you in Web Services Description Language (WSDL) documents, XML Schema, and MEX documents. The size of the object created from the retrieved metadata is directly proportional to the value for the instance that is used and the `MaxReceivedMessageSize` value for the binding being used by that instance. Set these quotas to appropriate values as dictated by your scenario. - In WCF, service metadata is processed as XML. When processing XML documents, applications should protect themselves against malicious XML structures. Use the with appropriate quotas when processing XML and also set the property to . + In WCF, service metadata is processed as XML. When processing XML documents, applications should protect themselves against malicious XML structures. Use the with appropriate quotas when processing XML and also set the property to . The metadata system in WCF is extensible and metadata extensions can be registered in your application configuration file (see [Extending the Metadata System](../extending/extending-the-metadata-system.md)). Metadata extensions can run arbitrary code, so you should protect your application configuration file with appropriate access control lists (ACLs) and register only trusted metadata extension implementations. diff --git a/docs/framework/wcf/feature-details/security-negotiation-and-timeouts.md b/docs/framework/wcf/feature-details/security-negotiation-and-timeouts.md index fc82a97989bee..b799c410c0ffc 100644 --- a/docs/framework/wcf/feature-details/security-negotiation-and-timeouts.md +++ b/docs/framework/wcf/feature-details/security-negotiation-and-timeouts.md @@ -6,8 +6,8 @@ ms.assetid: 02a428f1-84e5-4d28-a11f-53ce31d63196 --- # Security Negotiation and Timeouts -When clients and services authenticate, Windows Communication Foundation (WCF) supports a mode where the service credential is negotiated as part of authentication. In such scenarios, a potentially multi-leg exchange occurs between the client and the service to propagate the service credential to the client. The property controls how long the multi-leg exchange can take to complete. However, this timeout only applies if the exchange actually takes more that a single request-response. In cases where the negotiation completes in a single round trip, the timeout does not apply. - +When clients and services authenticate, Windows Communication Foundation (WCF) supports a mode where the service credential is negotiated as part of authentication. In such scenarios, a potentially multi-leg exchange occurs between the client and the service to propagate the service credential to the client. The property controls how long the multi-leg exchange can take to complete. However, this timeout only applies if the exchange actually takes more that a single request-response. In cases where the negotiation completes in a single round trip, the timeout does not apply. + ## See also - diff --git a/docs/framework/wcf/feature-details/security-protocols-version-1-0.md b/docs/framework/wcf/feature-details/security-protocols-version-1-0.md index 1e09370877931..91aa54aee4133 100644 --- a/docs/framework/wcf/feature-details/security-protocols-version-1-0.md +++ b/docs/framework/wcf/feature-details/security-protocols-version-1-0.md @@ -135,7 +135,7 @@ The Web Services Security Protocols provide Web services security mechanisms tha ### 2.1 TimeStamp - Timestamp presence is controlled using the property of the class. WCF always serializes wsse:TimeStamp with wsse:Created and wsse:Expires fields. The wsse:TimeStamp is always signed when signing is used. + Timestamp presence is controlled using the property of the class. WCF always serializes wsse:TimeStamp with wsse:Created and wsse:Expires fields. The wsse:TimeStamp is always signed when signing is used. ### 2.2 Protection Order diff --git a/docs/framework/wcf/feature-details/security-protocols.md b/docs/framework/wcf/feature-details/security-protocols.md index e94f739f0c6b1..aae8a20d9a89d 100644 --- a/docs/framework/wcf/feature-details/security-protocols.md +++ b/docs/framework/wcf/feature-details/security-protocols.md @@ -137,7 +137,7 @@ WCF, version 1, provides 17 authentication modes that can be used as the basis f ### 2.1 TimeStamp - Timestamp presence is controlled using the property of the class. WCF always serializes wsse:TimeStamp with wsse:Created and wsse:Expires fields. The wsse:TimeStamp is always signed when signing is used. + Timestamp presence is controlled using the property of the class. WCF always serializes wsse:TimeStamp with wsse:Created and wsse:Expires fields. The wsse:TimeStamp is always signed when signing is used. ### 2.2 Protection Order diff --git a/docs/framework/wcf/feature-details/securitybindingelement-authentication-modes.md b/docs/framework/wcf/feature-details/securitybindingelement-authentication-modes.md index eef351b18fa14..660adfb515df5 100644 --- a/docs/framework/wcf/feature-details/securitybindingelement-authentication-modes.md +++ b/docs/framework/wcf/feature-details/securitybindingelement-authentication-modes.md @@ -41,7 +41,7 @@ Windows Communication Foundation (WCF) provides several modes by which clients a 1. Determine the return type, which can be one of the following: , , , or . -2. Call the appropriate static method of the class. For example, the following code calls the method. +2. Call the appropriate static method of the class. For example, the following code calls the method. [!code-csharp[c_CustomBindingsAuthMode#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_custombindingsauthmode/cs/source.cs#3)] [!code-vb[c_CustomBindingsAuthMode#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_custombindingsauthmode/vb/source.vb#3)] @@ -52,35 +52,35 @@ Windows Communication Foundation (WCF) provides several modes by which clients a ### AnonymousForCertificate - With this authentication mode, the client is anonymous and the service is authenticated using an X.509 certificate. The security binding element is a returned by the method. Alternatively, set the `authenticationMode` attribute of the `` element to `AnonymousForCertificate`. + With this authentication mode, the client is anonymous and the service is authenticated using an X.509 certificate. The security binding element is a returned by the method. Alternatively, set the `authenticationMode` attribute of the `` element to `AnonymousForCertificate`. ### AnonymousForSslNegotiated - With this authentication mode, the client is anonymous and the service is authenticated using an X.509 certificate that is negotiated at runtime. The security binding element is a returned by the method when a value of `false` is passed for the first parameter. Alternatively, set the `authenticationMode` attribute to `AnonymousForSslNegotiated`. + With this authentication mode, the client is anonymous and the service is authenticated using an X.509 certificate that is negotiated at runtime. The security binding element is a returned by the method when a value of `false` is passed for the first parameter. Alternatively, set the `authenticationMode` attribute to `AnonymousForSslNegotiated`. ### CertificateOverTransport - With this authentication mode, the client authenticates using an X.509 certificate that appears at the SOAP layer as an endorsing supporting token; that is, a token that signs the message signature. The service is authenticated using an X.509 certificate at the transport layer. The security binding element is a returned by the method. Alternatively, set the `authenticationMode` attribute to `CertificateOverTransport`. + With this authentication mode, the client authenticates using an X.509 certificate that appears at the SOAP layer as an endorsing supporting token; that is, a token that signs the message signature. The service is authenticated using an X.509 certificate at the transport layer. The security binding element is a returned by the method. Alternatively, set the `authenticationMode` attribute to `CertificateOverTransport`. ### IssuedToken - With this authentication mode, the client does not authenticate to the service, as such; instead, the client authenticates to a security token service and receives a SAML token, which it then presents to the server to prove its knowledge of a shared key. The service is not authenticated to the client, as such, but the security token service encrypts the shared key as part of the issued token so that only the service can decrypt the key. The security binding element is a returned by the method. Alternatively, set the `authenticationMode` attribute to `IssuedToken`. + With this authentication mode, the client does not authenticate to the service, as such; instead, the client authenticates to a security token service and receives a SAML token, which it then presents to the server to prove its knowledge of a shared key. The service is not authenticated to the client, as such, but the security token service encrypts the shared key as part of the issued token so that only the service can decrypt the key. The security binding element is a returned by the method. Alternatively, set the `authenticationMode` attribute to `IssuedToken`. ### IssuedTokenForCertificate - With this authentication mode, the client does not authenticate to the service, as such; instead, the client authenticates to a security token service and receives a SAML token, which it then presents to the server to prove its knowledge of a shared key. The issued token appears at the SOAP layer as either an endorsing supporting token or a bearer token; that is, a token that signs the message signature. The service authenticates to the client using an X.509 certificate. The security binding element is a returned by the method. Alternatively, set the `authenticationMode` attribute to `IssuedTokenForCertificate`. + With this authentication mode, the client does not authenticate to the service, as such; instead, the client authenticates to a security token service and receives a SAML token, which it then presents to the server to prove its knowledge of a shared key. The issued token appears at the SOAP layer as either an endorsing supporting token or a bearer token; that is, a token that signs the message signature. The service authenticates to the client using an X.509 certificate. The security binding element is a returned by the method. Alternatively, set the `authenticationMode` attribute to `IssuedTokenForCertificate`. ### IssuedTokenForSslNegotiated - With this authentication mode, the client does not authenticate to the service, as such; instead, the client authenticates to a security token service and receives a SAML token, which it then presents to the server to prove its knowledge of a shared key. The issued token appears at the SOAP layer as either an endorsing supporting token or a bearer token; that is, a token that signs the message signature. The service is authenticated using an X.509 certificate. The security binding element is a returned by the method. Alternatively, set the `authenticationMode` attribute to `IssuedTokenForSslNegotiated`. + With this authentication mode, the client does not authenticate to the service, as such; instead, the client authenticates to a security token service and receives a SAML token, which it then presents to the server to prove its knowledge of a shared key. The issued token appears at the SOAP layer as either an endorsing supporting token or a bearer token; that is, a token that signs the message signature. The service is authenticated using an X.509 certificate. The security binding element is a returned by the method. Alternatively, set the `authenticationMode` attribute to `IssuedTokenForSslNegotiated`. ### IssuedTokenOverTransport - With this authentication mode, the client does not authenticate to the service, as such; instead, the client authenticates to a security token service and receives a SAML token, which it then presents to the server to prove its knowledge of a shared key. The issued token appears at the SOAP layer as either an endorsing supporting token or a bearer token; that is, a token that signs the message signature. The service is authenticated using an X.509 certificate at the transport layer. The security binding element is a `TransportSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `IssuedTokenOverTransport`. + With this authentication mode, the client does not authenticate to the service, as such; instead, the client authenticates to a security token service and receives a SAML token, which it then presents to the server to prove its knowledge of a shared key. The issued token appears at the SOAP layer as either an endorsing supporting token or a bearer token; that is, a token that signs the message signature. The service is authenticated using an X.509 certificate at the transport layer. The security binding element is a `TransportSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `IssuedTokenOverTransport`. ### Kerberos - With this authentication mode, the client authenticates to the service using a Kerberos ticket. That same ticket also provides server authentication. The security binding element is a `SymmetricSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `Kerberos`. + With this authentication mode, the client authenticates to the service using a Kerberos ticket. That same ticket also provides server authentication. The security binding element is a `SymmetricSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `Kerberos`. > [!NOTE] > In order to use this authentication mode, the service account must be associated with a service principal name (SPN). To do this, run the service under the NETWORK SERVICE account or the LOCAL SYSTEM account. Alternatively, use the SetSpn.exe tool to create an SPN for the service account. In either case, the client must use the correct SPN in the [\](../../configure-apps/file-schema/wcf/serviceprincipalname.md) element, or by using the constructor. For more information, see [Service Identity and Authentication](service-identity-and-authentication.md). @@ -90,50 +90,50 @@ Windows Communication Foundation (WCF) provides several modes by which clients a ### KerberosOverTransport - With this authentication mode, the client authenticates to the service using a Kerberos ticket. The Kerberos token appears at the SOAP layer as an endorsing supporting token; that is, a token that signs the message signature. The service is authenticated using an X.509 certificate at the transport layer. The security binding element is a `TransportSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `KerberosOverTransport`. + With this authentication mode, the client authenticates to the service using a Kerberos ticket. The Kerberos token appears at the SOAP layer as an endorsing supporting token; that is, a token that signs the message signature. The service is authenticated using an X.509 certificate at the transport layer. The security binding element is a `TransportSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `KerberosOverTransport`. > [!NOTE] > In order to use this authentication mode, the service account must be associated with an SPN. To do this, run the service under the NETWORK SERVICE account or the LOCAL SYSTEM account. Alternatively, use the SetSpn.exe tool to create an SPN for the service account. In either case, the client must use the correct SPN in the [\](../../configure-apps/file-schema/wcf/serviceprincipalname.md) element, or by using the constructor. For more information, see [Service Identity and Authentication](service-identity-and-authentication.md). ### MutualCertificate - With this authentication mode, the client authenticates using an X.509 certificate that appears at the SOAP layer as an endorsing supporting token; that is, a token that signs the message signature. The service is also authenticated using an X.509 certificate. The security binding element is a `SymmetricSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `MutualCertificate`. + With this authentication mode, the client authenticates using an X.509 certificate that appears at the SOAP layer as an endorsing supporting token; that is, a token that signs the message signature. The service is also authenticated using an X.509 certificate. The security binding element is a `SymmetricSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `MutualCertificate`. ### MutualCertificateDuplex - With this authentication mode, the client authenticates using an X.509 certificate that appears at the SOAP layer as an endorsing supporting token; that is, a token that signs the message signature. The service is also authenticated using an X.509 certificate. The binding is a `AsymmetricSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `MutualCertificateDuplex`. + With this authentication mode, the client authenticates using an X.509 certificate that appears at the SOAP layer as an endorsing supporting token; that is, a token that signs the message signature. The service is also authenticated using an X.509 certificate. The binding is a `AsymmetricSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `MutualCertificateDuplex`. ### MutualSslNegotiated - With this authentication mode, the client and the service authenticate using X.509 certificates. The security binding element is a `SymmetricSecurityBindingElement` returned by the method when a value of `true` is passed for the first parameter. Alternatively, set the `authenticationMode` attribute to `MutualSslNegotiated`. + With this authentication mode, the client and the service authenticate using X.509 certificates. The security binding element is a `SymmetricSecurityBindingElement` returned by the method when a value of `true` is passed for the first parameter. Alternatively, set the `authenticationMode` attribute to `MutualSslNegotiated`. ### SecureConversation - The security binding element is a `SymmetricSecurityBindingElement` returned by the method. This method takes a as a parameter, which is used during initialization to establish the secure session. Alternatively, set the `authenticationMode` attribute to `SecureConversation`. + The security binding element is a `SymmetricSecurityBindingElement` returned by the method. This method takes a as a parameter, which is used during initialization to establish the secure session. Alternatively, set the `authenticationMode` attribute to `SecureConversation`. If no bootstrap binding is specified, then the `SspiNegotiated` authentication mode is used for bootstrap. ### SspiNegotiation - With this authentication mode, a negotiation protocol is used to perform client and server authentication. Kerberos is used if possible; otherwise, NT LanMan (NTLM) is used. The security binding element is a `SymmetricSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `SspiNegotiated`. + With this authentication mode, a negotiation protocol is used to perform client and server authentication. Kerberos is used if possible; otherwise, NT LanMan (NTLM) is used. The security binding element is a `SymmetricSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `SspiNegotiated`. ### SspiNegotiatedOverTransport - With this authentication mode, a negotiation protocol is used to perform client and server authentication. Kerberos protocol is used if possible; otherwise, NTLM is used. The resulting token appears at the SOAP layer as an endorsing supporting token; that is, a token that signs the message signature. The service is additionally authenticated at the transport layer by an X.509 certificate. The security binding element is a `TransportSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `SspiNegotiatedOverTransport`. + With this authentication mode, a negotiation protocol is used to perform client and server authentication. Kerberos protocol is used if possible; otherwise, NTLM is used. The resulting token appears at the SOAP layer as an endorsing supporting token; that is, a token that signs the message signature. The service is additionally authenticated at the transport layer by an X.509 certificate. The security binding element is a `TransportSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `SspiNegotiatedOverTransport`. ### UserNameForCertificate - With this authentication mode, the client authenticates to the service using a Username Token that appears at the SOAP layer as a signed supporting token; that is, a token that is signed by the message signature. The service authenticates to the client using an X.509 certificate. The security binding element is a `SymmetricSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `UserNameForCertificate`. + With this authentication mode, the client authenticates to the service using a Username Token that appears at the SOAP layer as a signed supporting token; that is, a token that is signed by the message signature. The service authenticates to the client using an X.509 certificate. The security binding element is a `SymmetricSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `UserNameForCertificate`. For the `UserNameForCertificate` authentication mode, both the client and service must be using WS-Security 1.1. ### UserNameForSslNegotiated - With this authentication mode, the client is authenticates using a Username Token which appears at the SOAP layer as a signed supporting token; that is, a token that is signed by the message signature. The service is authenticated using an X.509 certificate. The security binding element is a `SymmetricSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `UserNameForSslNegotiated`. + With this authentication mode, the client is authenticates using a Username Token which appears at the SOAP layer as a signed supporting token; that is, a token that is signed by the message signature. The service is authenticated using an X.509 certificate. The security binding element is a `SymmetricSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `UserNameForSslNegotiated`. ### UserNameOverTransport - With this authentication mode, the client authenticates using a Username Token that appears at the SOAP layer as a signed supporting token; that is, a token that is signed by the message signature. The service is authenticated using an X.509 certificate at the transport layer. The security binding element is a `TransportSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `UserNameOverTransport`. + With this authentication mode, the client authenticates using a Username Token that appears at the SOAP layer as a signed supporting token; that is, a token that is signed by the message signature. The service is authenticated using an X.509 certificate at the transport layer. The security binding element is a `TransportSecurityBindingElement` returned by the method. Alternatively, set the `authenticationMode` attribute to `UserNameOverTransport`. ## See also diff --git a/docs/framework/wcf/feature-details/selecting-a-credential-type.md b/docs/framework/wcf/feature-details/selecting-a-credential-type.md index 98575bc0be2f8..94564397f16f2 100644 --- a/docs/framework/wcf/feature-details/selecting-a-credential-type.md +++ b/docs/framework/wcf/feature-details/selecting-a-credential-type.md @@ -6,118 +6,118 @@ ms.assetid: bf707063-3f30-4304-ab53-0e63413728a8 --- # Selecting a Credential Type -*Credentials* are the data Windows Communication Foundation (WCF) uses to establish either a claimed identity or capabilities. For example, a passport is a credential a government issues to prove citizenship in a country or region. In WCF, credentials can take many forms, such as user name tokens and X.509 certificates. This topic discusses credentials, how they are used in WCF, and how to select the right credential for your application. - - In many countries and regions, a driver’s license is an example of a credential. A license contains data that represents a person's identity and capabilities. It contains proof of possession in the form of the possessor's picture. The license is issued by a trusted authority, usually a governmental department of licensing. The license is sealed, and can contain a hologram, showing that it has not been tampered with or counterfeited. - - Presenting a credential involves presenting both the data and proof of possession of the data. WCF supports a variety of credential types at both the transport and message security levels. For example, consider two types of credentials supported in WCF: user name and (X.509) certificate credentials. - - For the user name credential, the user name represents the claimed identity and the password provides proof of possession. The trusted authority in this case is the system that validates the user name and password. - - With an X.509 certificate credential, the subject name, subject alternative name or specific fields within the certificate can be used as claims of identity, while other fields, such as the `Valid From` and `Valid To` fields, specify the validity of the certificate. - -## Transport Credential Types - - The following table shows the possible types of client credentials that can be used by a binding in transport security mode. When creating a service, set the `ClientCredentialType` property to one of these values to specify the type of credential that the client must supply to communicate with your service. You can set the types in either code or configuration files. - -|Setting|Description| -|-------------|-----------------| -|None|Specifies that the client does not need to present any credential. This translates to an anonymous client.| -|Basic|Specifies basic authentication for the client. For additional information, see RFC2617—[HTTP Authentication: Basic and Digest Authentication](https://www.rfc-editor.org/rfc/rfc2617).| -|Digest|Specifies digest authentication for the client. For additional information, see RFC2617—[HTTP Authentication: Basic and Digest Authentication](https://www.rfc-editor.org/rfc/rfc2617).| -|Ntlm|Specifies NT LAN Manager (NTLM) authentication. This is used when you cannot use Kerberos authentication for some reason. You can also disable its use as a fallback by setting the property to `false`, which causes WCF to make a best-effort to throw an exception if NTLM is used. Note that setting this property to `false` may not prevent NTLM credentials from being sent over the wire.| -|Windows|Specifies Windows authentication. To specify only the Kerberos protocol on a Windows domain, set the property to `false` (the default is `true`).| -|Certificate|Performs client authentication using an X.509 certificate.| -|Password|User must supply a user name and password. Validate the user name/password pair using Windows authentication or another custom solution.| - -### Message Client Credential Types - - The following table shows the possible credential types that you can use when creating an application that uses message security. You can use these values in either code or configuration files. - -|Setting|Description| -|-------------|-----------------| -|None|Specifies that the client does not need to present a credential. This translates to an anonymous client.| -|Windows|Allows SOAP message exchanges to occur under the security context established with a Windows credential.| -|Username|Allows the service to require that the client be authenticated with a user name credential. Note that WCF does not allow any cryptographic operations with user names, such as generating a signature or encrypting data. WCF ensures that the transport is secured when using user name credentials.| -|Certificate|Allows the service to require that the client be authenticated using an X.509 certificate.| -|Issued Token|A custom token type configured according to a security policy. The default token type is Security Assertions Markup Language (SAML). The token is issued by a secure token service. For more information, see [Federation and Issued Tokens](federation-and-issued-tokens.md).| - -### Negotiation Model of Service Credentials - - *Negotiation* is the process of establishing trust between a client and a service by exchanging credentials. The process is performed iteratively between the client and the service, so as to disclose only the information necessary for the next step in the negotiation process. In practice, the end result is the delivery of a service's credential to the client to be used in subsequent operations. - - With one exception, by default the system-provided bindings in WCF negotiate the service credential automatically when using message-level security. (The exception is the , which does not enable security by default.) To disable this behavior, see the and properties. - +*Credentials* are the data Windows Communication Foundation (WCF) uses to establish either a claimed identity or capabilities. For example, a passport is a credential a government issues to prove citizenship in a country or region. In WCF, credentials can take many forms, such as user name tokens and X.509 certificates. This topic discusses credentials, how they are used in WCF, and how to select the right credential for your application. + + In many countries and regions, a driver’s license is an example of a credential. A license contains data that represents a person's identity and capabilities. It contains proof of possession in the form of the possessor's picture. The license is issued by a trusted authority, usually a governmental department of licensing. The license is sealed, and can contain a hologram, showing that it has not been tampered with or counterfeited. + + Presenting a credential involves presenting both the data and proof of possession of the data. WCF supports a variety of credential types at both the transport and message security levels. For example, consider two types of credentials supported in WCF: user name and (X.509) certificate credentials. + + For the user name credential, the user name represents the claimed identity and the password provides proof of possession. The trusted authority in this case is the system that validates the user name and password. + + With an X.509 certificate credential, the subject name, subject alternative name or specific fields within the certificate can be used as claims of identity, while other fields, such as the `Valid From` and `Valid To` fields, specify the validity of the certificate. + +## Transport Credential Types + + The following table shows the possible types of client credentials that can be used by a binding in transport security mode. When creating a service, set the `ClientCredentialType` property to one of these values to specify the type of credential that the client must supply to communicate with your service. You can set the types in either code or configuration files. + +|Setting|Description| +|-------------|-----------------| +|None|Specifies that the client does not need to present any credential. This translates to an anonymous client.| +|Basic|Specifies basic authentication for the client. For additional information, see RFC2617—[HTTP Authentication: Basic and Digest Authentication](https://www.rfc-editor.org/rfc/rfc2617).| +|Digest|Specifies digest authentication for the client. For additional information, see RFC2617—[HTTP Authentication: Basic and Digest Authentication](https://www.rfc-editor.org/rfc/rfc2617).| +|Ntlm|Specifies NT LAN Manager (NTLM) authentication. This is used when you cannot use Kerberos authentication for some reason. You can also disable its use as a fallback by setting the property to `false`, which causes WCF to make a best-effort to throw an exception if NTLM is used. Note that setting this property to `false` may not prevent NTLM credentials from being sent over the wire.| +|Windows|Specifies Windows authentication. To specify only the Kerberos protocol on a Windows domain, set the property to `false` (the default is `true`).| +|Certificate|Performs client authentication using an X.509 certificate.| +|Password|User must supply a user name and password. Validate the user name/password pair using Windows authentication or another custom solution.| + +### Message Client Credential Types + + The following table shows the possible credential types that you can use when creating an application that uses message security. You can use these values in either code or configuration files. + +|Setting|Description| +|-------------|-----------------| +|None|Specifies that the client does not need to present a credential. This translates to an anonymous client.| +|Windows|Allows SOAP message exchanges to occur under the security context established with a Windows credential.| +|Username|Allows the service to require that the client be authenticated with a user name credential. Note that WCF does not allow any cryptographic operations with user names, such as generating a signature or encrypting data. WCF ensures that the transport is secured when using user name credentials.| +|Certificate|Allows the service to require that the client be authenticated using an X.509 certificate.| +|Issued Token|A custom token type configured according to a security policy. The default token type is Security Assertions Markup Language (SAML). The token is issued by a secure token service. For more information, see [Federation and Issued Tokens](federation-and-issued-tokens.md).| + +### Negotiation Model of Service Credentials + + *Negotiation* is the process of establishing trust between a client and a service by exchanging credentials. The process is performed iteratively between the client and the service, so as to disclose only the information necessary for the next step in the negotiation process. In practice, the end result is the delivery of a service's credential to the client to be used in subsequent operations. + + With one exception, by default the system-provided bindings in WCF negotiate the service credential automatically when using message-level security. (The exception is the , which does not enable security by default.) To disable this behavior, see the and properties. + > [!NOTE] -> When SSL security is used with .NET Framework 3.5 and later, a WCF client uses both the intermediate certificates in its certificate store and the intermediate certificates received during SSL negotiation to perform certificate chain validation on the service's certificate. .NET Framework 3.0 only uses the intermediate certificates installed in the local certificate store. - -#### Out-of-Band Negotiation +> When SSL security is used with .NET Framework 3.5 and later, a WCF client uses both the intermediate certificates in its certificate store and the intermediate certificates received during SSL negotiation to perform certificate chain validation on the service's certificate. .NET Framework 3.0 only uses the intermediate certificates installed in the local certificate store. + +#### Out-of-Band Negotiation + + If automatic negotiation is disabled, the service credential must be provisioned at the client prior to sending any messages to the service. This is also known as an *out-of-band* provisioning. For example, if the specified credential type is a certificate, and automatic negotiation is disabled, the client must contact the service owner to receive and install the certificate on the computer running the client application. This can be done, for example, when you want to strictly control which clients can access a service in a business-to-business scenario. This out-of-band-negotiation can be done in email, and the X.509 certificate is stored in Windows certificate store, using a tool such as the Microsoft Management Console (MMC) Certificates snap-in. - If automatic negotiation is disabled, the service credential must be provisioned at the client prior to sending any messages to the service. This is also known as an *out-of-band* provisioning. For example, if the specified credential type is a certificate, and automatic negotiation is disabled, the client must contact the service owner to receive and install the certificate on the computer running the client application. This can be done, for example, when you want to strictly control which clients can access a service in a business-to-business scenario. This out-of-band-negotiation can be done in email, and the X.509 certificate is stored in Windows certificate store, using a tool such as the Microsoft Management Console (MMC) Certificates snap-in. - > [!NOTE] -> The property is used to provide the service with a certificate that was attained through out-of-band negotiation. This is necessary when using the class because the binding does not allow automated negotiation. The property is also used in an uncorrelated duplex scenario. This is a scenario where a server sends a message to the client without requiring the client to send a request to the server first. Because the server does not have a request from the client, it must use the client's certificate to encrypt the message to the client. - -## Setting Credential Values - - Once you select a security mode, you must specify the actual credentials. For example, if the credential type is set to "certificate," then you must associate a specific credential (such as a specific X.509 certificate) with the service or client. - - Depending on whether you are programming a service or a client, the method for setting the credential value differs slightly. - -### Setting Service Credentials - - If you are using transport mode, and you are using HTTP as the transport, you must use either Internet Information Services (IIS) or configure the port with a certificate. For more information, see [Transport Security Overview](transport-security-overview.md) and [HTTP Transport Security](http-transport-security.md). - - To provision a service with credentials in code, create an instance of the class and specify the appropriate credential using the class, accessed through the property. - -#### Setting a Certificate - - To provision a service with an X.509 certificate to be used to authenticate the service to clients, use the method of the class. - - To provision a service with a client certificate, use the method of the class. - -#### Setting Windows Credentials - - If the client specifies a valid user name and password, that credential is used to authenticate the client. Otherwise, the current logged-on user's credentials are used. - -### Setting Client Credentials - - In WCF, client applications use a WCF client to connect to services. Every client derives from the class, and the property on the client allows the specification of various values of client credentials. - -#### Setting a Certificate - - To provision a service with an X.509 certificate that is used to authenticate the client to a service, use the method of the class. - -## How Client Credentials Are Used to Authenticate a Client to the Service - - Client credential information required to communicate with a service is provided using either the property or the property. The security channel uses this information to authenticate the client to the service. Authentication is accomplished through one of two modes: - -- The client credentials are used once before the first message is sent, using the WCF client instance to establish a security context. All application messages are then secured through the security context. - -- The client credentials are used to authenticate every application message sent to the service. In this case, no context is established between the client and the service. - -### Established Identities Cannot Be Changed - - When the first method is used, the established context is permanently associated with the client identity. That is, once the security context has been established, the identity associated with the client cannot be changed. - +> The property is used to provide the service with a certificate that was attained through out-of-band negotiation. This is necessary when using the class because the binding does not allow automated negotiation. The property is also used in an uncorrelated duplex scenario. This is a scenario where a server sends a message to the client without requiring the client to send a request to the server first. Because the server does not have a request from the client, it must use the client's certificate to encrypt the message to the client. + +## Setting Credential Values + + Once you select a security mode, you must specify the actual credentials. For example, if the credential type is set to "certificate," then you must associate a specific credential (such as a specific X.509 certificate) with the service or client. + + Depending on whether you are programming a service or a client, the method for setting the credential value differs slightly. + +### Setting Service Credentials + + If you are using transport mode, and you are using HTTP as the transport, you must use either Internet Information Services (IIS) or configure the port with a certificate. For more information, see [Transport Security Overview](transport-security-overview.md) and [HTTP Transport Security](http-transport-security.md). + + To provision a service with credentials in code, create an instance of the class and specify the appropriate credential using the class, accessed through the property. + +#### Setting a Certificate + + To provision a service with an X.509 certificate to be used to authenticate the service to clients, use the method of the class. + + To provision a service with a client certificate, use the method of the class. + +#### Setting Windows Credentials + + If the client specifies a valid user name and password, that credential is used to authenticate the client. Otherwise, the current logged-on user's credentials are used. + +### Setting Client Credentials + + In WCF, client applications use a WCF client to connect to services. Every client derives from the class, and the property on the client allows the specification of various values of client credentials. + +#### Setting a Certificate + + To provision a service with an X.509 certificate that is used to authenticate the client to a service, use the method of the class. + +## How Client Credentials Are Used to Authenticate a Client to the Service + + Client credential information required to communicate with a service is provided using either the property or the property. The security channel uses this information to authenticate the client to the service. Authentication is accomplished through one of two modes: + +- The client credentials are used once before the first message is sent, using the WCF client instance to establish a security context. All application messages are then secured through the security context. + +- The client credentials are used to authenticate every application message sent to the service. In this case, no context is established between the client and the service. + +### Established Identities Cannot Be Changed + + When the first method is used, the established context is permanently associated with the client identity. That is, once the security context has been established, the identity associated with the client cannot be changed. + > [!IMPORTANT] -> There is a situation to be aware of when the identity cannot be switched (that is, when establish security context is on, the default behavior). If you create a service that communicates with a second service, the identity used to open the WCF client to the second service cannot be changed. This becomes a problem if multiple clients are allowed to use the first service and the service impersonates the clients when accessing the second service. If the service reuses the same client for all callers, all calls to the second service are done under the identity of the first caller that was used to open the client to the second service. In other words, the service uses the identity of the first client for all its clients to communicate with the second service. This can lead to the elevation of privilege. If this is not the desired behavior of your service, you must track each caller and create a new client to the second service for every distinct caller, and ensure that the service uses only the right client for the right caller to communicate with the second service. - - For more information about credentials and secure sessions, see [Security Considerations for Secure Sessions](security-considerations-for-secure-sessions.md). - +> There is a situation to be aware of when the identity cannot be switched (that is, when establish security context is on, the default behavior). If you create a service that communicates with a second service, the identity used to open the WCF client to the second service cannot be changed. This becomes a problem if multiple clients are allowed to use the first service and the service impersonates the clients when accessing the second service. If the service reuses the same client for all callers, all calls to the second service are done under the identity of the first caller that was used to open the client to the second service. In other words, the service uses the identity of the first client for all its clients to communicate with the second service. This can lead to the elevation of privilege. If this is not the desired behavior of your service, you must track each caller and create a new client to the second service for every distinct caller, and ensure that the service uses only the right client for the right caller to communicate with the second service. + + For more information about credentials and secure sessions, see [Security Considerations for Secure Sessions](security-considerations-for-secure-sessions.md). + ## See also -- -- -- -- -- -- -- -- -- -- -- +- +- +- +- +- +- +- +- +- +- +- - [Security Concepts](security-concepts.md) - [Securing Services and Clients](securing-services-and-clients.md) - [Programming WCF Security](programming-wcf-security.md) diff --git a/docs/framework/wcf/feature-details/serializable-types.md b/docs/framework/wcf/feature-details/serializable-types.md index 1671ad951b6fa..f768ecd0bea78 100644 --- a/docs/framework/wcf/feature-details/serializable-types.md +++ b/docs/framework/wcf/feature-details/serializable-types.md @@ -6,36 +6,36 @@ ms.assetid: f1c8539a-6a79-4413-b294-896f0957b2cd --- # Serializable Types -By default, the serializes all publicly visible types. All public read/write properties and fields of the type are serialized. - - You can change the default behavior by applying the and attributes to the types and members This feature can be useful in situations in which you have types that are not under your control and cannot be modified to add attributes. The recognizes such "unmarked" types. - -## Serialization Defaults - - You can apply the and attributes to explicitly control or customize the serialization of types and members. In addition, you can apply these attributes to private fields. However, even types that are not marked with these attributes are serialized and deserialized. The following rules and exceptions apply: - -- The infers a data contract from types without attributes using the default properties of the newly created types. - -- All public fields, and properties with public `get` and `set` methods are serialized, unless you apply the attribute to that member. - -- The serialization semantics are similar to those of the . - -- In unmarked types, only public types with constructors that do not have parameters are serialized. The exception to this rule is used with the interface. - -- Read-only fields, properties without a `get` or `set` method, and properties with internal or private `set` or `get` methods are not serialized. Such properties are ignored and no exception is thrown, except in the case of get-only collections. - -- attributes (such as `XmlElement`, `XmlAttribute`, `XmlIgnore`, `XmlInclude`, and so on) are ignored. - -- If you do not apply the attribute to a given type, the serializer ignores any member in that type to which the attribute is applied. - -- The property is supported in types not marked with the attribute. This includes support for the attribute on unmarked types. - -- To "opt out" of the serialization process for public members, properties, or fields, apply the attribute to that member. - -## Inheritance - - Unmarked types (types without the attribute) can inherit from types that do have this attribute; however, the reverse is not permitted: types with the attribute cannot inherit from unmarked types. This rule is enforced primarily to ensure backward compatibility with code written in earlier versions of .NET Framework. - +By default, the serializes all publicly visible types. All public read/write properties and fields of the type are serialized. + + You can change the default behavior by applying the and attributes to the types and members This feature can be useful in situations in which you have types that are not under your control and cannot be modified to add attributes. The recognizes such "unmarked" types. + +## Serialization Defaults + + You can apply the and attributes to explicitly control or customize the serialization of types and members. In addition, you can apply these attributes to private fields. However, even types that are not marked with these attributes are serialized and deserialized. The following rules and exceptions apply: + +- The infers a data contract from types without attributes using the default properties of the newly created types. + +- All public fields, and properties with public `get` and `set` methods are serialized, unless you apply the attribute to that member. + +- The serialization semantics are similar to those of the . + +- In unmarked types, only public types with constructors that do not have parameters are serialized. The exception to this rule is used with the interface. + +- Read-only fields, properties without a `get` or `set` method, and properties with internal or private `set` or `get` methods are not serialized. Such properties are ignored and no exception is thrown, except in the case of get-only collections. + +- attributes (such as `XmlElement`, `XmlAttribute`, `XmlIgnore`, `XmlInclude`, and so on) are ignored. + +- If you do not apply the attribute to a given type, the serializer ignores any member in that type to which the attribute is applied. + +- The property is supported in types not marked with the attribute. This includes support for the attribute on unmarked types. + +- To "opt out" of the serialization process for public members, properties, or fields, apply the attribute to that member. + +## Inheritance + + Unmarked types (types without the attribute) can inherit from types that do have this attribute; however, the reverse is not permitted: types with the attribute cannot inherit from unmarked types. This rule is enforced primarily to ensure backward compatibility with code written in earlier versions of .NET Framework. + ## See also - diff --git a/docs/framework/wcf/feature-details/serialization-and-deserialization.md b/docs/framework/wcf/feature-details/serialization-and-deserialization.md index c782c84f01daa..2f40ae8ec37bd 100644 --- a/docs/framework/wcf/feature-details/serialization-and-deserialization.md +++ b/docs/framework/wcf/feature-details/serialization-and-deserialization.md @@ -2,281 +2,281 @@ title: "Serialization and Deserialization" description: Learn about the WCF serialization engine, which translates between .NET Framework objects and XML, in both directions. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 3d71814c-bda7-424b-85b7-15084ff9377a --- # Serialization and Deserialization -Windows Communication Foundation (WCF) includes a new serialization engine, the . The translates between .NET Framework objects and XML, in both directions. This topic explains how the serializer works. - - When serializing .NET Framework objects, the serializer understands a variety of serialization programming models, including the new *data contract* model. For a full list of supported types, see [Types Supported by the Data Contract Serializer](types-supported-by-the-data-contract-serializer.md). For an introduction to data contracts, see [Using Data Contracts](using-data-contracts.md). - - When deserializing XML, the serializer uses the and classes. It also supports the and classes to enable it to produce optimized XML in some cases, such as when using the WCF binary XML format. - +Windows Communication Foundation (WCF) includes a new serialization engine, the . The translates between .NET Framework objects and XML, in both directions. This topic explains how the serializer works. + + When serializing .NET Framework objects, the serializer understands a variety of serialization programming models, including the new *data contract* model. For a full list of supported types, see [Types Supported by the Data Contract Serializer](types-supported-by-the-data-contract-serializer.md). For an introduction to data contracts, see [Using Data Contracts](using-data-contracts.md). + + When deserializing XML, the serializer uses the and classes. It also supports the and classes to enable it to produce optimized XML in some cases, such as when using the WCF binary XML format. + WCF also includes a companion serializer, the . The : * Is ***not*** secure. For more information, see the [BinaryFormatter security guide](../../../standard/serialization/binaryformatter-security-guide.md). * Is similar to the and serializers because it also emits .NET Framework type names as part of the serialized data. * Is used when the same types are shared on the serializing and the deserializing ends. - Both and derive from a common base class, . - + Both and derive from a common base class, . + > [!WARNING] -> The serializes strings containing control characters with a hexadecimal value below 20 as XML entities. This may cause a problem with a non-WCF client when sending such data to a WCF service. - -## Creating a DataContractSerializer Instance - - Constructing an instance of the is an important step. After construction, you cannot change any of the settings. - -### Specifying the Root Type - - The *root type* is the type of which instances are serialized or deserialized. The has many constructor overloads, but, at a minimum, a root type must be supplied using the `type` parameter. - - A serializer created for a certain root type cannot be used to serialize (or deserialize) another type, unless the type is derived from the root type. The following example shows two classes. - +> The serializes strings containing control characters with a hexadecimal value below 20 as XML entities. This may cause a problem with a non-WCF client when sending such data to a WCF service. + +## Creating a DataContractSerializer Instance + + Constructing an instance of the is an important step. After construction, you cannot change any of the settings. + +### Specifying the Root Type + + The *root type* is the type of which instances are serialized or deserialized. The has many constructor overloads, but, at a minimum, a root type must be supplied using the `type` parameter. + + A serializer created for a certain root type cannot be used to serialize (or deserialize) another type, unless the type is derived from the root type. The following example shows two classes. + [!code-csharp[c_StandaloneDataContractSerializer#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#1)] - [!code-vb[c_StandaloneDataContractSerializer#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#1)] - - This code constructs an instance of the `DataContractSerializer` that can be used only to serialize or deserialize instances of the `Person` class. - + [!code-vb[c_StandaloneDataContractSerializer#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#1)] + + This code constructs an instance of the `DataContractSerializer` that can be used only to serialize or deserialize instances of the `Person` class. + [!code-csharp[c_StandaloneDataContractSerializer#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#2)] - [!code-vb[c_StandaloneDataContractSerializer#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#2)] - -### Specifying Known Types - - If polymorphism is involved in the types being serialized that is not already handled using the attribute or some other mechanism, a list of possible known types must be passed to the serializer’s constructor using the `knownTypes` parameter. For more information about known types, see [Data Contract Known Types](data-contract-known-types.md). - - The following example shows a class, `LibraryPatron`, that includes a collection of a specific type, the `LibraryItem`. The second class defines the `LibraryItem` type. The third and four classes (`Book` and `Newspaper`) inherit from the `LibraryItem` class. - - [!code-csharp[c_StandaloneDataContractSerializer#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#3)] - [!code-vb[c_StandaloneDataContractSerializer#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#3)] - - The following code constructs an instance of the serializer using the `knownTypes` parameter. - + [!code-vb[c_StandaloneDataContractSerializer#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#2)] + +### Specifying Known Types + + If polymorphism is involved in the types being serialized that is not already handled using the attribute or some other mechanism, a list of possible known types must be passed to the serializer’s constructor using the `knownTypes` parameter. For more information about known types, see [Data Contract Known Types](data-contract-known-types.md). + + The following example shows a class, `LibraryPatron`, that includes a collection of a specific type, the `LibraryItem`. The second class defines the `LibraryItem` type. The third and four classes (`Book` and `Newspaper`) inherit from the `LibraryItem` class. + + [!code-csharp[c_StandaloneDataContractSerializer#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#3)] + [!code-vb[c_StandaloneDataContractSerializer#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#3)] + + The following code constructs an instance of the serializer using the `knownTypes` parameter. + [!code-csharp[c_StandaloneDataContractSerializer#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#4)] - [!code-vb[c_StandaloneDataContractSerializer#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#4)] - -### Specifying the Default Root Name and Namespace + [!code-vb[c_StandaloneDataContractSerializer#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#4)] + +### Specifying the Default Root Name and Namespace + + Normally, when an object is serialized, the default name and namespace of the outermost XML element are determined according to the data contract name and namespace. The names of all inner elements are determined from data member names, and their namespace is the data contract’s namespace. The following example sets `Name` and `Namespace` values in the constructors of the and classes. - Normally, when an object is serialized, the default name and namespace of the outermost XML element are determined according to the data contract name and namespace. The names of all inner elements are determined from data member names, and their namespace is the data contract’s namespace. The following example sets `Name` and `Namespace` values in the constructors of the and classes. - [!code-csharp[c_StandaloneDataContractSerializer#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#5)] - [!code-vb[c_StandaloneDataContractSerializer#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#5)] - - Serializing an instance of the `Person` class produces XML similar to the following. - -```xml - - - 123 Main Street - - -``` - - However, you can customize the default name and namespace of the root element by passing the values of the `rootName` and `rootNamespace` parameters to the constructor. Note that the `rootNamespace` does not affect the namespace of the contained elements that correspond to data members. It affects only the namespace of the outermost element. - - These values can be passed as strings or instances of the class to allow for their optimization using the binary XML format. - -### Setting the Maximum Objects Quota - - Some `DataContractSerializer` constructor overloads have a `maxItemsInObjectGraph` parameter. This parameter determines the maximum number of objects the serializer serializes or deserializes in a single method call. (The method always reads one root object, but this object may have other objects in its data members. Those objects may have other objects, and so on.) The default is 65536. Note that when serializing or deserializing arrays, every array entry counts as a separate object. Also, note that some objects may have a large memory representation, and so this quota alone may not be sufficient to prevent a denial of service attack. For more information, see [Security Considerations for Data](security-considerations-for-data.md). If you need to increase this quota beyond the default value, it is important to do so both on the sending (serializing) and receiving (deserializing) sides because it applies to both when reading and writing data. - -### Round Trips - - A *round trip* occurs when an object is deserialized and re-serialized in one operation. Thus, it goes from XML to an object instance, and back again into an XML stream. - - Some `DataContractSerializer` constructor overloads have an `ignoreExtensionDataObject` parameter, which is set to `false` by default. In this default mode, data can be sent on a round trip from a newer version of a data contract through an older version and back to the newer version without loss, as long as the data contract implements the interface. For example, suppose version 1 of the `Person` data contract contains the `Name` and `PhoneNumber` data members, and version 2 adds a `Nickname` member. If `IExtensibleDataObject` is implemented, when sending information from version 2 to version 1, the `Nickname` data is stored, and then re-emitted when the data is serialized again; therefore, no data is lost in the round trip. For more information, see [Forward-Compatible Data Contracts](forward-compatible-data-contracts.md) and [Data Contract Versioning](data-contract-versioning.md). - -#### Security and Schema Validity Concerns with Round Trips - - Round trips may have security implications. For example, deserializing and storing large amounts of extraneous data may be a security risk. There may be security concerns about re-emitting this data that there is no way to verify, especially if digital signatures are involved. For example, in the previous scenario, the version 1 endpoint could be signing a `Nickname` value that contains malicious data. Finally, there may be schema validity concerns: an endpoint may want to always emit data that strictly adheres to its stated contract and not any extra values. In the previous example, the version 1 endpoint’s contract says that it emits only `Name` and `PhoneNumber`, and if schema validation is being used, emitting the extra `Nickname` value causes validation to fail. - -#### Enabling and Disabling Round Trips - - To turn off round trips, do not implement the interface. If you have no control over the types, set the `ignoreExtensionDataObject` parameter to `true` to achieve the same effect. - -### Object Graph Preservation - - Normally, the serializer does not care about object identity, as in the following code. - + [!code-vb[c_StandaloneDataContractSerializer#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#5)] + + Serializing an instance of the `Person` class produces XML similar to the following. + +```xml + + + 123 Main Street + + +``` + + However, you can customize the default name and namespace of the root element by passing the values of the `rootName` and `rootNamespace` parameters to the constructor. Note that the `rootNamespace` does not affect the namespace of the contained elements that correspond to data members. It affects only the namespace of the outermost element. + + These values can be passed as strings or instances of the class to allow for their optimization using the binary XML format. + +### Setting the Maximum Objects Quota + + Some `DataContractSerializer` constructor overloads have a `maxItemsInObjectGraph` parameter. This parameter determines the maximum number of objects the serializer serializes or deserializes in a single method call. (The method always reads one root object, but this object may have other objects in its data members. Those objects may have other objects, and so on.) The default is 65536. Note that when serializing or deserializing arrays, every array entry counts as a separate object. Also, note that some objects may have a large memory representation, and so this quota alone may not be sufficient to prevent a denial of service attack. For more information, see [Security Considerations for Data](security-considerations-for-data.md). If you need to increase this quota beyond the default value, it is important to do so both on the sending (serializing) and receiving (deserializing) sides because it applies to both when reading and writing data. + +### Round Trips + + A *round trip* occurs when an object is deserialized and re-serialized in one operation. Thus, it goes from XML to an object instance, and back again into an XML stream. + + Some `DataContractSerializer` constructor overloads have an `ignoreExtensionDataObject` parameter, which is set to `false` by default. In this default mode, data can be sent on a round trip from a newer version of a data contract through an older version and back to the newer version without loss, as long as the data contract implements the interface. For example, suppose version 1 of the `Person` data contract contains the `Name` and `PhoneNumber` data members, and version 2 adds a `Nickname` member. If `IExtensibleDataObject` is implemented, when sending information from version 2 to version 1, the `Nickname` data is stored, and then re-emitted when the data is serialized again; therefore, no data is lost in the round trip. For more information, see [Forward-Compatible Data Contracts](forward-compatible-data-contracts.md) and [Data Contract Versioning](data-contract-versioning.md). + +#### Security and Schema Validity Concerns with Round Trips + + Round trips may have security implications. For example, deserializing and storing large amounts of extraneous data may be a security risk. There may be security concerns about re-emitting this data that there is no way to verify, especially if digital signatures are involved. For example, in the previous scenario, the version 1 endpoint could be signing a `Nickname` value that contains malicious data. Finally, there may be schema validity concerns: an endpoint may want to always emit data that strictly adheres to its stated contract and not any extra values. In the previous example, the version 1 endpoint’s contract says that it emits only `Name` and `PhoneNumber`, and if schema validation is being used, emitting the extra `Nickname` value causes validation to fail. + +#### Enabling and Disabling Round Trips + + To turn off round trips, do not implement the interface. If you have no control over the types, set the `ignoreExtensionDataObject` parameter to `true` to achieve the same effect. + +### Object Graph Preservation + + Normally, the serializer does not care about object identity, as in the following code. + [!code-csharp[c_StandaloneDataContractSerializer#6](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#6)] - [!code-vb[c_StandaloneDataContractSerializer#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#6)] - - The following code creates a purchase order. - + [!code-vb[c_StandaloneDataContractSerializer#6](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#6)] + + The following code creates a purchase order. + [!code-csharp[c_StandaloneDataContractSerializer#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#7)] - [!code-vb[c_StandaloneDataContractSerializer#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#7)] - - Notice that `billTo` and `shipTo` fields are set to the same object instance. However, the generated XML duplicates the information duplicated, and looks similar to the following XML. - -```xml - - 123 Main St. - 123 Main St. - -``` - - However, this approach has the following characteristics, which may be undesirable: - -- Performance. Replicating data is inefficient. - -- Circular references. If objects refer to themselves, even through other objects, serializing by replication results in an infinite loop. (The serializer throws a if this happens.) - -- Semantics. Sometimes it is important to preserve the fact that two references are to the same object, and not to two identical objects. - - For these reasons, some `DataContractSerializer` constructor overloads have a `preserveObjectReferences` parameter (the default is `false`). When this parameter is set to `true`, a special method of encoding object references, which only WCF understands, is used. When set to `true`, the XML code example now resembles the following. - -```xml - - 123 Main St. - - -``` - - The "ser" namespace refers to the standard serialization namespace, `http://schemas.microsoft.com/2003/10/Serialization/`. Each piece of data is serialized only once and given an ID number, and subsequent uses result in a reference to the already serialized data. - + [!code-vb[c_StandaloneDataContractSerializer#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#7)] + + Notice that `billTo` and `shipTo` fields are set to the same object instance. However, the generated XML duplicates the information duplicated, and looks similar to the following XML. + +```xml + + 123 Main St. + 123 Main St. + +``` + + However, this approach has the following characteristics, which may be undesirable: + +- Performance. Replicating data is inefficient. + +- Circular references. If objects refer to themselves, even through other objects, serializing by replication results in an infinite loop. (The serializer throws a if this happens.) + +- Semantics. Sometimes it is important to preserve the fact that two references are to the same object, and not to two identical objects. + + For these reasons, some `DataContractSerializer` constructor overloads have a `preserveObjectReferences` parameter (the default is `false`). When this parameter is set to `true`, a special method of encoding object references, which only WCF understands, is used. When set to `true`, the XML code example now resembles the following. + +```xml + + 123 Main St. + + +``` + + The "ser" namespace refers to the standard serialization namespace, `http://schemas.microsoft.com/2003/10/Serialization/`. Each piece of data is serialized only once and given an ID number, and subsequent uses result in a reference to the already serialized data. + > [!IMPORTANT] -> If both "id" and "ref" attributes are present in the data contract `XMLElement`, then the "ref" attribute is honored and the "id" attribute is ignored. - - It is important to understand the limitations of this mode: - -- The XML the `DataContractSerializer` produces with `preserveObjectReferences` set to `true` is not interoperable with any other technologies, and can be accessed only by another `DataContractSerializer` instance, also with `preserveObjectReferences` set to `true`. - -- There is no metadata (schema) support for this feature. The schema that is produced is valid only for the case when `preserveObjectReferences` is set to `false`. - -- This feature may cause the serialization and deserialization process to run slower. Although data does not have to be replicated, extra object comparisons must be performed in this mode. - +> If both "id" and "ref" attributes are present in the data contract `XMLElement`, then the "ref" attribute is honored and the "id" attribute is ignored. + + It is important to understand the limitations of this mode: + +- The XML the `DataContractSerializer` produces with `preserveObjectReferences` set to `true` is not interoperable with any other technologies, and can be accessed only by another `DataContractSerializer` instance, also with `preserveObjectReferences` set to `true`. + +- There is no metadata (schema) support for this feature. The schema that is produced is valid only for the case when `preserveObjectReferences` is set to `false`. + +- This feature may cause the serialization and deserialization process to run slower. Although data does not have to be replicated, extra object comparisons must be performed in this mode. + > [!CAUTION] -> When the `preserveObjectReferences` mode is enabled, it is especially important to set the `maxItemsInObjectGraph` value to the correct quota. Due to the way arrays are handled in this mode, it is easy for an attacker to construct a small malicious message that results in large memory consumption limited only by the `maxItemsInObjectGraph` quota. - -### Specifying a Data Contract Surrogate - - Some `DataContractSerializer` constructor overloads have a `dataContractSurrogate` parameter, which may be set to `null`. Otherwise, you can use it to specify a *data contract surrogate*, which is a type that implements the interface. You can then use the interface to customize the serialization and deserialization process. For more information, see [Data Contract Surrogates](../extending/data-contract-surrogates.md). - -## Serialization - - The following information applies to any class that inherits from the , including the and classes. - -### Simple Serialization - - The most basic way to serialize an object is to pass it to the method. There are three overloads, one each for writing to a , an , or an . With the overload, the output is XML in the UTF-8 encoding. With the overload, the serializer optimizes its output for binary XML. - - When using the method, the serializer uses the default name and namespace for the wrapper element and writes it out along with the contents (see the previous "Specifying the Default Root Name and Namespace" section). - - The following example demonstrates writing with an . - +> When the `preserveObjectReferences` mode is enabled, it is especially important to set the `maxItemsInObjectGraph` value to the correct quota. Due to the way arrays are handled in this mode, it is easy for an attacker to construct a small malicious message that results in large memory consumption limited only by the `maxItemsInObjectGraph` quota. + +### Specifying a Data Contract Surrogate + + Some `DataContractSerializer` constructor overloads have a `dataContractSurrogate` parameter, which may be set to `null`. Otherwise, you can use it to specify a *data contract surrogate*, which is a type that implements the interface. You can then use the interface to customize the serialization and deserialization process. For more information, see [Data Contract Surrogates](../extending/data-contract-surrogates.md). + +## Serialization + + The following information applies to any class that inherits from the , including the and classes. + +### Simple Serialization + + The most basic way to serialize an object is to pass it to the method. There are three overloads, one each for writing to a , an , or an . With the overload, the output is XML in the UTF-8 encoding. With the overload, the serializer optimizes its output for binary XML. + + When using the method, the serializer uses the default name and namespace for the wrapper element and writes it out along with the contents (see the previous "Specifying the Default Root Name and Namespace" section). + + The following example demonstrates writing with an . + [!code-csharp[c_StandaloneDataContractSerializer#8](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#8)] - [!code-vb[c_StandaloneDataContractSerializer#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#8)] - - This produces XML similar to the following. - -```xml - - Jay Hamlin -
123 Main St.
- -``` - -### Step-By-Step Serialization - - Use the , , and methods to write the end element, write the object contents, and close the wrapper element, respectively. - + [!code-vb[c_StandaloneDataContractSerializer#8](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#8)] + + This produces XML similar to the following. + +```xml + + Jay Hamlin +
123 Main St.
+ +``` + +### Step-By-Step Serialization + + Use the , , and methods to write the end element, write the object contents, and close the wrapper element, respectively. + > [!NOTE] -> There are no overloads of these methods. - - This step-by-step serialization has two common uses. One is to insert contents such as attributes or comments between `WriteStartObject` and `WriteObjectContent`, as shown in the following example. - +> There are no overloads of these methods. + + This step-by-step serialization has two common uses. One is to insert contents such as attributes or comments between `WriteStartObject` and `WriteObjectContent`, as shown in the following example. + [!code-csharp[c_StandaloneDataContractSerializer#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#9)] - [!code-vb[c_StandaloneDataContractSerializer#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#9)] - - This produces XML similar to the following. - -```xml - - Jay Hamlin -
123 Main St.
- -``` - - Another common use is to avoid using and entirely, and to write your own custom wrapper element (or even skip writing a wrapper altogether), as shown in the following code. - + [!code-vb[c_StandaloneDataContractSerializer#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#9)] + + This produces XML similar to the following. + +```xml + + Jay Hamlin +
123 Main St.
+ +``` + + Another common use is to avoid using and entirely, and to write your own custom wrapper element (or even skip writing a wrapper altogether), as shown in the following code. + [!code-csharp[c_StandaloneDataContractSerializer#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#10)] - [!code-vb[c_StandaloneDataContractSerializer#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#10)] - - This produces XML similar to the following. - -```xml - - Jay Hamlin -
123 Main St.
- -``` - + [!code-vb[c_StandaloneDataContractSerializer#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#10)] + + This produces XML similar to the following. + +```xml + + Jay Hamlin +
123 Main St.
+ +``` + > [!NOTE] -> Using step-by-step serialization may result in schema-invalid XML. - -## Deserialization - - The following information applies to any class that inherits from the , including the and classes. - - The most basic way to deserialize an object is to call one of the method overloads. There are three overloads, one each for reading with a , an `XmlReader`, or a `Stream`. Note that the `Stream` overload creates a textual that is not protected by any quotas, and should be used only to read trusted data. - - Also note that the object the `ReadObject` method returns must be cast to the appropriate type. - - The following code constructs an instance of the and an , then deserializes a `Person` instance. - +> Using step-by-step serialization may result in schema-invalid XML. + +## Deserialization + + The following information applies to any class that inherits from the , including the and classes. + + The most basic way to deserialize an object is to call one of the method overloads. There are three overloads, one each for reading with a , an `XmlReader`, or a `Stream`. Note that the `Stream` overload creates a textual that is not protected by any quotas, and should be used only to read trusted data. + + Also note that the object the `ReadObject` method returns must be cast to the appropriate type. + + The following code constructs an instance of the and an , then deserializes a `Person` instance. + [!code-csharp[c_StandaloneDataContractSerializer#11](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#11)] - [!code-vb[c_StandaloneDataContractSerializer#11](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#11)] - - Before calling the method, position the XML reader on the wrapper element or on a non-content node that precedes the wrapper element. You can do this by calling the method of the or its derivation, and testing the , as shown in the following code. - + [!code-vb[c_StandaloneDataContractSerializer#11](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#11)] + + Before calling the method, position the XML reader on the wrapper element or on a non-content node that precedes the wrapper element. You can do this by calling the method of the or its derivation, and testing the , as shown in the following code. + [!code-csharp[c_StandaloneDataContractSerializer#12](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_standalonedatacontractserializer/cs/source.cs#12)] - [!code-vb[c_StandaloneDataContractSerializer#12](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#12)] - - Note that you can read attributes on this wrapper element before handing the reader to `ReadObject`. - - When using one of the simple `ReadObject` overloads, the deserializer looks for the default name and namespace on the wrapper element (see the preceding section, "Specifying the Default Root Name and Namespace") and throws an exception if it finds an unknown element. In the preceding example, the `` wrapper element is expected. The method is called to verify that the reader is positioned on an element that is named as expected. - - There is a way to disable this wrapper element name check; some overloads of the `ReadObject` method take the Boolean parameter `verifyObjectName`, which is set to `true` by default. When set to `false`, the name and namespace of the wrapper element is ignored. This is useful for reading XML that was written using the step-by-step serialization mechanism described previously. - -## Using the NetDataContractSerializer - - The primary difference between the `DataContractSerializer` and the is that the `DataContractSerializer` uses data contract names, whereas the `NetDataContractSerializer` outputs full .NET Framework assembly and type names in the serialized XML. This means that the exact same types must be shared between the serialization and deserialization endpoints. This means that the known types mechanism is not required with the `NetDataContractSerializer` because the exact types to be deserialized are always known. - - However, several problems can occur: - -- Security. Any type found in the XML being deserialized is loaded. This can be exploited to force the loading of malicious types. Using the `NetDataContractSerializer` with untrusted data should be done only if a *Serialization Binder* is used (using the property or constructor parameter). The binder permits only safe types to be loaded. The Binder mechanism is identical to the one that types in the namespace use. - -- Versioning. Using full type and assembly names in the XML severely restricts how types can be versioned. The following cannot be changed: type names, namespaces, assembly names, and assembly versions. Setting the property or constructor parameter to instead of the default value of allows for assembly version changes, but not for generic parameter types. - -- Interoperability. Because .NET Framework type and assembly names are included in the XML, platforms other than the .NET Framework cannot access the resulting data. - -- Performance. Writing out the type and assembly names significantly increases the size of the resulting XML. - - This mechanism is similar to binary or SOAP serialization used by .NET Framework remoting (specifically, the and the ). - - Using the `NetDataContractSerializer` is similar to using the `DataContractSerializer`, with the following differences: - -- The constructors do not require you to specify a root type. You can serialize any type with the same instance of the `NetDataContractSerializer`. - -- The constructors do not accept a list of known types. The known types mechanism is unnecessary if type names are serialized into the XML. - -- The constructors do not accept a data contract surrogate. Instead, they accept an parameter called `surrogateSelector` (which maps to the property). This is a legacy surrogate mechanism. - -- The constructors accept a parameter called `assemblyFormat` of the that maps to the property. As discussed previously, this can be used to enhance the versioning capabilities of the serializer. This is identical to the mechanism in binary or SOAP serialization. - -- The constructors accept a parameter called `context` that maps to the property. You can use this to pass information into types being serialized. This usage is identical to that of the mechanism used in other classes. - -- The and methods are aliases for the and methods. These exist to provide a more consistent programming model with binary or SOAP serialization. - - For more information about these features, see [Binary Serialization](/previous-versions/dotnet/fundamentals/serialization/binary/binary-serialization). - - The XML formats that the `NetDataContractSerializer` and the `DataContractSerializer` use are normally not compatible. That is, attempting to serialize with one of these serializers and deserialize with the other is not a supported scenario. - - Also, note that the `NetDataContractSerializer` does not output the full .NET Framework type and assembly name for each node in the object graph. It outputs that information only where it is ambiguous. That is, it outputs at the root object level and for any polymorphic cases. - + [!code-vb[c_StandaloneDataContractSerializer#12](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_standalonedatacontractserializer/vb/source.vb#12)] + + Note that you can read attributes on this wrapper element before handing the reader to `ReadObject`. + + When using one of the simple `ReadObject` overloads, the deserializer looks for the default name and namespace on the wrapper element (see the preceding section, "Specifying the Default Root Name and Namespace") and throws an exception if it finds an unknown element. In the preceding example, the `` wrapper element is expected. The method is called to verify that the reader is positioned on an element that is named as expected. + + There is a way to disable this wrapper element name check; some overloads of the `ReadObject` method take the Boolean parameter `verifyObjectName`, which is set to `true` by default. When set to `false`, the name and namespace of the wrapper element is ignored. This is useful for reading XML that was written using the step-by-step serialization mechanism described previously. + +## Using the NetDataContractSerializer + + The primary difference between the `DataContractSerializer` and the is that the `DataContractSerializer` uses data contract names, whereas the `NetDataContractSerializer` outputs full .NET Framework assembly and type names in the serialized XML. This means that the exact same types must be shared between the serialization and deserialization endpoints. This means that the known types mechanism is not required with the `NetDataContractSerializer` because the exact types to be deserialized are always known. + + However, several problems can occur: + +- Security. Any type found in the XML being deserialized is loaded. This can be exploited to force the loading of malicious types. Using the `NetDataContractSerializer` with untrusted data should be done only if a *Serialization Binder* is used (using the property or constructor parameter). The binder permits only safe types to be loaded. The Binder mechanism is identical to the one that types in the namespace use. + +- Versioning. Using full type and assembly names in the XML severely restricts how types can be versioned. The following cannot be changed: type names, namespaces, assembly names, and assembly versions. Setting the property or constructor parameter to instead of the default value of allows for assembly version changes, but not for generic parameter types. + +- Interoperability. Because .NET Framework type and assembly names are included in the XML, platforms other than the .NET Framework cannot access the resulting data. + +- Performance. Writing out the type and assembly names significantly increases the size of the resulting XML. + + This mechanism is similar to binary or SOAP serialization used by .NET Framework remoting (specifically, the and the ). + + Using the `NetDataContractSerializer` is similar to using the `DataContractSerializer`, with the following differences: + +- The constructors do not require you to specify a root type. You can serialize any type with the same instance of the `NetDataContractSerializer`. + +- The constructors do not accept a list of known types. The known types mechanism is unnecessary if type names are serialized into the XML. + +- The constructors do not accept a data contract surrogate. Instead, they accept an parameter called `surrogateSelector` (which maps to the property). This is a legacy surrogate mechanism. + +- The constructors accept a parameter called `assemblyFormat` of the that maps to the property. As discussed previously, this can be used to enhance the versioning capabilities of the serializer. This is identical to the mechanism in binary or SOAP serialization. + +- The constructors accept a parameter called `context` that maps to the property. You can use this to pass information into types being serialized. This usage is identical to that of the mechanism used in other classes. + +- The and methods are aliases for the and methods. These exist to provide a more consistent programming model with binary or SOAP serialization. + + For more information about these features, see [Binary Serialization](/previous-versions/dotnet/fundamentals/serialization/binary/binary-serialization). + + The XML formats that the `NetDataContractSerializer` and the `DataContractSerializer` use are normally not compatible. That is, attempting to serialize with one of these serializers and deserialize with the other is not a supported scenario. + + Also, note that the `NetDataContractSerializer` does not output the full .NET Framework type and assembly name for each node in the object graph. It outputs that information only where it is ambiguous. That is, it outputs at the root object level and for any polymorphic cases. + ## See also - diff --git a/docs/framework/wcf/feature-details/service-identity-and-authentication.md b/docs/framework/wcf/feature-details/service-identity-and-authentication.md index dec1f860e365d..ef1eeb2df445f 100644 --- a/docs/framework/wcf/feature-details/service-identity-and-authentication.md +++ b/docs/framework/wcf/feature-details/service-identity-and-authentication.md @@ -27,7 +27,7 @@ A service's *endpoint identity* is a value generated from the service Web Servic Identity processing on the client is analogous to client authentication on the service. A secure service does not execute code until the client's credentials have been authenticated. Likewise, the client does not send messages to the service until the service's credentials have been authenticated based on what is known in advance from the service's metadata. - The property of the class represents the identity of the service called by the client. The service publishes the in its metadata. When the client developer runs the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) against the service endpoint, the generated configuration contains the value of the service's property. The WCF infrastructure (if configured with security) verifies that the service possesses the identity specified. + The property of the class represents the identity of the service called by the client. The service publishes the in its metadata. When the client developer runs the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) against the service endpoint, the generated configuration contains the value of the service's property. The WCF infrastructure (if configured with security) verifies that the service possesses the identity specified. > [!IMPORTANT] > The metadata contains the expected identity of the service, so it is recommended that you expose the service metadata through secure means, for example, by creating an HTTPS endpoint for the service. For more information, see [How to: Secure Metadata Endpoints](how-to-secure-metadata-endpoints.md). @@ -96,7 +96,7 @@ A service's *endpoint identity* is a value generated from the service Web Servic - UPN. The UPN of the service account. The UPN is in the form `username`@`domain`. For example, when the service is running in a user account, it may be `username@contoso.com`. - Specifying the identity programmatically (using the property) is optional. If no identity is specified, and the client credential type is Windows, the default is SPN with the value set to the hostname part of the service endpoint address prefixed with the "host/" literal. If no identity is specified, and the client credential type is a certificate, the default is `Certificate`. This applies to both message- and transport-level security. + Specifying the identity programmatically (using the property) is optional. If no identity is specified, and the client credential type is Windows, the default is SPN with the value set to the hostname part of the service endpoint address prefixed with the "host/" literal. If no identity is specified, and the client credential type is a certificate, the default is `Certificate`. This applies to both message- and transport-level security. ## Identity and Custom Bindings diff --git a/docs/framework/wcf/feature-details/servicemodel-attributes-and-servicedescription-reference.md b/docs/framework/wcf/feature-details/servicemodel-attributes-and-servicedescription-reference.md index 6fa758f3aa2f9..e431cd7dfa7b4 100644 --- a/docs/framework/wcf/feature-details/servicemodel-attributes-and-servicedescription-reference.md +++ b/docs/framework/wcf/feature-details/servicemodel-attributes-and-servicedescription-reference.md @@ -6,110 +6,110 @@ ms.assetid: 4ab86b17-eab9-4846-a881-0099f9a7cc64 --- # ServiceModel Attributes and ServiceDescription Reference -The *description tree* is the hierarchy of types (starting with the class) that together describe every aspect of a service. Windows Communication Foundation (WCF) uses a description tree to build a valid service runtime, to publish Web Services Description Language (WSDL), XML Schema definition language (XSD), and policy assertions (metadata) about the service that clients can use to connect to and use the service, and to generate various code and configuration file representations of the description tree values. - - This topic describes how contract-related properties are obtained from the service contract, and how they are implemented and added to the description tree. In some cases, attribute values are converted into behavior properties and behavior is then inserted into the description tree. For more information about how the description tree values are converted into metadata, see [ServiceDescription and WSDL Reference](servicedescription-and-wsdl-reference.md). - -## Mapping Operations to the Description Tree - - In WCF applications, service contracts are modeled by interfaces (or classes) that use attributes to mark the interface or class and its methods as a grouping of operations. When a class is opened, any service contracts and implementations are reflected over and merged with configuration information into a description tree. - - There are two types of operation models: the *parameter* model and the *message contract* model. The parameter model uses managed methods that do not have a parameter or return value type that is marked by the class. In this model, developers control the serialization of parameters and return values, but WCF generates the values that are used to populate the description tree for the service and its contract. - - Bindings specified in configuration files are loaded directly into the property. - -|ServiceBehaviorAttribute Property|Description Tree Value Affected| -|---------------------------------------|-------------------------------------| -|Name|| -|Namespace|| -|ConfigurationName|| -|IgnoreExtensionDataObject|Sets the property for all operations.| -|MaxItemsInObjectGraph|Sets the property for all operations.| - -|ServiceContractAttribute Property|Description Tree Value Affected| -|---------------------------------------|-------------------------------------| -|CallbackContract|, added to all operations .| -|ConfigurationName|| -|ProtectionLevel| and possibly child protection levels. For more information about the protection-level hierarchy, see [Understanding Protection Level](../understanding-protection-level.md).| -|SessionMode|| - -|ServiceKnownTypesAttribute Value|Description Tree Value Affected| -|--------------------------------------|-------------------------------------| -|MethodName|| - -|OperationContractAttribute Value|Description Tree Value Affected| -|--------------------------------------|-------------------------------------| -|Action| for the output message or input message, depending upon contract/callback contract.| -|AsyncPattern|If true, and | -|IsOneWay|Maps to a single in | -|IsInitiating|| -|IsTerminating|| -|Name|| -|ProtectionLevel| and possibly child protection levels. For more information about the protection-level hierarchy, see [Understanding Protection Level](../understanding-protection-level.md).| -|ReplyAction| for the output message or input message, depending upon contract/callback contract.| - -|FaultContractAttribute Value|Description Tree Value Affected| -|----------------------------------|-------------------------------------| -|Action| depending upon contract/callback contract.| -|DetailType|| -|Name|| -|Namespace|| -|ProtectionLevel|| - -|DataContractFormatAttribute Value|Description Tree Value Affected| -|---------------------------------------|-------------------------------------| -|Use|The value is set on the for the operation.| - -|XmlSerializerFormatAttribute Value|Description Tree Value Affected| -|----------------------------------------|-------------------------------------| -|Style|This property is set on the for the operation.| -|Use|The is set on the for the operation.| - -|TransactionFlowAttribute Value|Description Tree Value Affected| -|------------------------------------|-------------------------------------| -|TransactionFlowOption|The is added as an operation behavior to the property.| - -|MessageContractAttribute Value|Description Tree Value Affected| -|------------------------------------|-------------------------------------| -|ProtectionLevel|| -|WrapperName|| -|WrapperNamespace|| - -|MessageHeaderAttribute Value|Description Tree Value Affected| -|----------------------------------|-------------------------------------| -|Actor| for the corresponding header in | -|MustUnderstand| for the corresponding header in | -|Name| for the corresponding header in | -|Namespace| for the corresponding header in | -|ProtectionLevel| for the corresponding header in | -|Relay| for the corresponding header in | - -|MessageBodyMemberAttribute Value|Description Tree Value Affected| -|--------------------------------------|-------------------------------------| -|Name| for the corresponding part in | -|Namespace| for the corresponding part in | -|Order| for the corresponding part in | -|ProtectionLevel| for the corresponding part in | - -|MessageHeaderArrayAttribute Value|Description Tree Value Affected| -|---------------------------------------|-------------------------------------| -|Actor|| -|MustUnderstand|| -|Name|| -|Namespace|| -|ProtectionLevel|| -|Relay|| - -|MessagePropertyAttribute Value|Description Tree Value Affected| -|------------------------------------|-------------------------------------| -|Name|| - -|MessageParameterAttribute Value|Description Tree Value Affected| -|-------------------------------------|-------------------------------------| -|Name| for the corresponding part in | - - For more information about how the description tree values are converted into metadata, see [ServiceDescription and WSDL Reference](servicedescription-and-wsdl-reference.md). - +The *description tree* is the hierarchy of types (starting with the class) that together describe every aspect of a service. Windows Communication Foundation (WCF) uses a description tree to build a valid service runtime, to publish Web Services Description Language (WSDL), XML Schema definition language (XSD), and policy assertions (metadata) about the service that clients can use to connect to and use the service, and to generate various code and configuration file representations of the description tree values. + + This topic describes how contract-related properties are obtained from the service contract, and how they are implemented and added to the description tree. In some cases, attribute values are converted into behavior properties and behavior is then inserted into the description tree. For more information about how the description tree values are converted into metadata, see [ServiceDescription and WSDL Reference](servicedescription-and-wsdl-reference.md). + +## Mapping Operations to the Description Tree + + In WCF applications, service contracts are modeled by interfaces (or classes) that use attributes to mark the interface or class and its methods as a grouping of operations. When a class is opened, any service contracts and implementations are reflected over and merged with configuration information into a description tree. + + There are two types of operation models: the *parameter* model and the *message contract* model. The parameter model uses managed methods that do not have a parameter or return value type that is marked by the class. In this model, developers control the serialization of parameters and return values, but WCF generates the values that are used to populate the description tree for the service and its contract. + + Bindings specified in configuration files are loaded directly into the property. + +|ServiceBehaviorAttribute Property|Description Tree Value Affected| +|---------------------------------------|-------------------------------------| +|Name|| +|Namespace|| +|ConfigurationName|| +|IgnoreExtensionDataObject|Sets the property for all operations.| +|MaxItemsInObjectGraph|Sets the property for all operations.| + +|ServiceContractAttribute Property|Description Tree Value Affected| +|---------------------------------------|-------------------------------------| +|CallbackContract|, added to all operations .| +|ConfigurationName|| +|ProtectionLevel| and possibly child protection levels. For more information about the protection-level hierarchy, see [Understanding Protection Level](../understanding-protection-level.md).| +|SessionMode|| + +|ServiceKnownTypesAttribute Value|Description Tree Value Affected| +|--------------------------------------|-------------------------------------| +|MethodName|| + +|OperationContractAttribute Value|Description Tree Value Affected| +|--------------------------------------|-------------------------------------| +|Action| for the output message or input message, depending upon contract/callback contract.| +|AsyncPattern|If true, and | +|IsOneWay|Maps to a single in | +|IsInitiating|| +|IsTerminating|| +|Name|| +|ProtectionLevel| and possibly child protection levels. For more information about the protection-level hierarchy, see [Understanding Protection Level](../understanding-protection-level.md).| +|ReplyAction| for the output message or input message, depending upon contract/callback contract.| + +|FaultContractAttribute Value|Description Tree Value Affected| +|----------------------------------|-------------------------------------| +|Action| depending upon contract/callback contract.| +|DetailType|| +|Name|| +|Namespace|| +|ProtectionLevel|| + +|DataContractFormatAttribute Value|Description Tree Value Affected| +|---------------------------------------|-------------------------------------| +|Use|The value is set on the for the operation.| + +|XmlSerializerFormatAttribute Value|Description Tree Value Affected| +|----------------------------------------|-------------------------------------| +|Style|This property is set on the for the operation.| +|Use|The is set on the for the operation.| + +|TransactionFlowAttribute Value|Description Tree Value Affected| +|------------------------------------|-------------------------------------| +|TransactionFlowOption|The is added as an operation behavior to the property.| + +|MessageContractAttribute Value|Description Tree Value Affected| +|------------------------------------|-------------------------------------| +|ProtectionLevel|| +|WrapperName|| +|WrapperNamespace|| + +|MessageHeaderAttribute Value|Description Tree Value Affected| +|----------------------------------|-------------------------------------| +|Actor| for the corresponding header in | +|MustUnderstand| for the corresponding header in | +|Name| for the corresponding header in | +|Namespace| for the corresponding header in | +|ProtectionLevel| for the corresponding header in | +|Relay| for the corresponding header in | + +|MessageBodyMemberAttribute Value|Description Tree Value Affected| +|--------------------------------------|-------------------------------------| +|Name| for the corresponding part in | +|Namespace| for the corresponding part in | +|Order| for the corresponding part in | +|ProtectionLevel| for the corresponding part in | + +|MessageHeaderArrayAttribute Value|Description Tree Value Affected| +|---------------------------------------|-------------------------------------| +|Actor|| +|MustUnderstand|| +|Name|| +|Namespace|| +|ProtectionLevel|| +|Relay|| + +|MessagePropertyAttribute Value|Description Tree Value Affected| +|------------------------------------|-------------------------------------| +|Name|| + +|MessageParameterAttribute Value|Description Tree Value Affected| +|-------------------------------------|-------------------------------------| +|Name| for the corresponding part in | + + For more information about how the description tree values are converted into metadata, see [ServiceDescription and WSDL Reference](servicedescription-and-wsdl-reference.md). + ## See also - [ServiceDescription and WSDL Reference](servicedescription-and-wsdl-reference.md) diff --git a/docs/framework/wcf/feature-details/servicemodel-transaction-attributes.md b/docs/framework/wcf/feature-details/servicemodel-transaction-attributes.md index 89ec4e9659605..48152d361c76f 100644 --- a/docs/framework/wcf/feature-details/servicemodel-transaction-attributes.md +++ b/docs/framework/wcf/feature-details/servicemodel-transaction-attributes.md @@ -26,13 +26,13 @@ This is the only attribute that relates service operations to external interacti The attribute specifies the internal execution behavior of a service contract implementation. Transaction-specific properties of this attribute include: -- specifies whether to complete an uncompleted transaction when the session closes. The default value for this property is `false`. If this property is `true`, and the incoming session was gracefully shut down instead of closing due to network or client faults, any uncompleted transaction is successfully completed. Otherwise, if this property is `false` or if the session was not gracefully closed, any uncompleted transaction is rolled back when the session closes. If this property is `true`, the incoming channel must be session-based. +- specifies whether to complete an uncompleted transaction when the session closes. The default value for this property is `false`. If this property is `true`, and the incoming session was gracefully shut down instead of closing due to network or client faults, any uncompleted transaction is successfully completed. Otherwise, if this property is `false` or if the session was not gracefully closed, any uncompleted transaction is rolled back when the session closes. If this property is `true`, the incoming channel must be session-based. -- specifies whether the underlying service instance is released when a transaction completes. The default value for this property is `true`. The next inbound message causes a new underlying instance to be created, discarding any per-transaction state that the previous instance might have held. Releasing a service instance is an internal action the service takes and has no impact on any existing connections or sessions that clients might have established. This functionality is equivalent to the just-in-time activation feature COM+ provides. If the property is `true`, must be equal to . Otherwise, the service throws an invalid configuration validation exception during startup. +- specifies whether the underlying service instance is released when a transaction completes. The default value for this property is `true`. The next inbound message causes a new underlying instance to be created, discarding any per-transaction state that the previous instance might have held. Releasing a service instance is an internal action the service takes and has no impact on any existing connections or sessions that clients might have established. This functionality is equivalent to the just-in-time activation feature COM+ provides. If the property is `true`, must be equal to . Otherwise, the service throws an invalid configuration validation exception during startup. -- specifies the isolation level to use for transactions within the service; this property takes one of the values. If the local isolation level property is anything other than , the isolation level of an incoming transaction must match the setting of this local property. Otherwise, the incoming transaction is rejected, and a fault is sent back to the client. If is `true`, and no transaction is flowed, this property determines the value to use for the locally created transaction. If is set to , is used. +- specifies the isolation level to use for transactions within the service; this property takes one of the values. If the local isolation level property is anything other than , the isolation level of an incoming transaction must match the setting of this local property. Otherwise, the incoming transaction is rejected, and a fault is sent back to the client. If is `true`, and no transaction is flowed, this property determines the value to use for the locally created transaction. If is set to , is used. -- specifies the time period within which a new transaction created at the service must complete. If this time is reached and the transaction has not been completed, it will abort. The is used as the time-out for any operations that have set to `true` and for which a new transaction was created. The time-out is the maximum allowed duration from the creation of the transaction to the completion of phase 1 in the two-phase commit protocol. The time-out value used is always the lower value between the property and the `transactionTimeout` configuration setting. +- specifies the time period within which a new transaction created at the service must complete. If this time is reached and the transaction has not been completed, it will abort. The is used as the time-out for any operations that have set to `true` and for which a new transaction was created. The time-out is the maximum allowed duration from the creation of the transaction to the completion of phase 1 in the two-phase commit protocol. The time-out value used is always the lower value between the property and the `transactionTimeout` configuration setting. ## OperationBehaviorAttribute @@ -40,7 +40,7 @@ The attribute specifies th This attribute has the following transaction-specific properties: -- specifies whether a method must execute within an active transaction scope. The default is `false`. If the attribute is not set for a method, it also implies that the method will not execute in a transaction. If a transaction scope is not required for an operation, any transaction that is present within the message header is not activated and remains as an element of the of the . If a transaction scope is required for an operation, the source for the transaction is derived from one of the following: +- specifies whether a method must execute within an active transaction scope. The default is `false`. If the attribute is not set for a method, it also implies that the method will not execute in a transaction. If a transaction scope is not required for an operation, any transaction that is present within the message header is not activated and remains as an element of the of the . If a transaction scope is required for an operation, the source for the transaction is derived from one of the following: - If a transaction is flowed from the client, the method is executed under a transaction scope created using that distributed transaction. @@ -50,4 +50,4 @@ This attribute has the following transaction-specific properties: - If none of the above provides an external source for a transaction, a new instance is created immediately prior to calling the method. -- specifies whether the transaction in which the method executes is automatically completed if no unhandled exceptions are thrown. If this property is `true`, the calling infrastructure automatically marks the transaction as "completed" if the user method returns without throwing an exception. If this property is `false`, the transaction is attached to the instance, and is only marked as "completed" if the client calls a subsequent method that is marked with this property equal to `true`, or if a subsequent method explicitly calls . Failure to perform either of these results in the transaction never being "completed," and the contained work is not committed, unless the property is set to `true`. If this property is set to `true`, you must use a channel with a session, and the must be set to . +- specifies whether the transaction in which the method executes is automatically completed if no unhandled exceptions are thrown. If this property is `true`, the calling infrastructure automatically marks the transaction as "completed" if the user method returns without throwing an exception. If this property is `false`, the transaction is attached to the instance, and is only marked as "completed" if the client calls a subsequent method that is marked with this property equal to `true`, or if a subsequent method explicitly calls . Failure to perform either of these results in the transaction never being "completed," and the contained work is not committed, unless the property is set to `true`. If this property is set to `true`, you must use a channel with a session, and the must be set to . diff --git a/docs/framework/wcf/feature-details/servicemodel-transaction-configuration.md b/docs/framework/wcf/feature-details/servicemodel-transaction-configuration.md index ba48dd01490de..0b94569b037a9 100644 --- a/docs/framework/wcf/feature-details/servicemodel-transaction-configuration.md +++ b/docs/framework/wcf/feature-details/servicemodel-transaction-configuration.md @@ -2,65 +2,65 @@ description: "Learn more about: ServiceModel Transaction Configuration" title: "ServiceModel Transaction Configuration" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "transactions [WCF], ServiceModel configuration" ms.assetid: 5636067a-7fbd-4485-aaa2-8141c502acf3 --- # ServiceModel Transaction Configuration -Windows Communication Foundation (WCF) provides three attributes for configuring transactions for a service: `transactionFlow`, `transactionProtocol`, and `transactionTimeout`. - -## Configuring transactionFlow - - Most of the predefined bindings WCF provides contain the `transactionFlow` and `transactionProtocol` attributes, so that you can configure the binding to accept incoming transactions for a specific endpoint using a specific transaction flow protocol. In addition, you can use the `transactionFlow` element and its `transactionProtocol` attribute to build your own custom binding. For more information about setting the configuration elements, see [\](../../configure-apps/file-schema/wcf/bindings.md) and [WCF Configuration Schema](../../configure-apps/file-schema/wcf/index.md). - - The `transactionFlow` attribute specifies whether transaction flow is enabled for service endpoints that use the binding. - -## Configuring transactionProtocol - - The `transactionProtocol` attribute specifies the transaction protocol to use with service endpoints that use the binding. - - The following is an example of a configuration section that configures the specified binding to support transaction flow, as well as a use the WS-AtomicTransaction protocol. - -```xml - - ](../../configure-apps/file-schema/wcf/bindings.md) and [WCF Configuration Schema](../../configure-apps/file-schema/wcf/index.md). + + The `transactionFlow` attribute specifies whether transaction flow is enabled for service endpoints that use the binding. + +## Configuring transactionProtocol + + The `transactionProtocol` attribute specifies the transaction protocol to use with service endpoints that use the binding. + + The following is an example of a configuration section that configures the specified binding to support transaction flow, as well as a use the WS-AtomicTransaction protocol. + +```xml + + - - -``` - -## Configuring transactionTimeout - - You can configure the `transactionTimeout` attribute for your WCF service in the `behavior` element of the configuration file. The following code demonstrates how to do this. - -```xml - - - - - - - -``` - - The `transactionTimeout` attribute specifies the time period within which a new transaction created at the service must complete. It is used as the time-out for any operation that establishes a new transaction, and if is applied, the property is set to `true`. - - The time-out specifies the duration of time from the creation of the transaction to the completion of phase 1 in the two-phase commit protocol. - - If this attribute is set within a `service` configuration section, you should apply at least one method of the corresponding service with , in which the property is set to `true`. - - Note that the time-out value used is the smaller value between this `transactionTimeout` configuration setting and any property. - + maxReceivedMessageSize="1000"> + + +``` + +## Configuring transactionTimeout + + You can configure the `transactionTimeout` attribute for your WCF service in the `behavior` element of the configuration file. The following code demonstrates how to do this. + +```xml + + + + + + + +``` + + The `transactionTimeout` attribute specifies the time period within which a new transaction created at the service must complete. It is used as the time-out for any operation that establishes a new transaction, and if is applied, the property is set to `true`. + + The time-out specifies the duration of time from the creation of the transaction to the completion of phase 1 in the two-phase commit protocol. + + If this attribute is set within a `service` configuration section, you should apply at least one method of the corresponding service with , in which the property is set to `true`. + + Note that the time-out value used is the smaller value between this `transactionTimeout` configuration setting and any property. + ## See also - [\](../../configure-apps/file-schema/wcf/bindings.md) diff --git a/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md b/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md index dbfd8dd8343b1..b0c103a3371a2 100644 --- a/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md +++ b/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md @@ -6,109 +6,109 @@ ms.assetid: 50797a3b-7678-44ed-8138-49ac1602f35b --- # Sessions, Instancing, and Concurrency -A *session* is a correlation of all messages sent between two endpoints. *Instancing* refers to controlling the lifetime of user-defined service objects and their related objects. *Concurrency* is the term given to the control of the number of threads executing in an at the same time. - - This topic describes these settings, how to use them, and the various interactions between them. - -## Sessions - - When a service contract sets the property to , that contract is saying that all calls (that is, the underlying message exchanges that support the calls) must be part of the same conversation. If a contract specifies that it allows sessions but does not require one, clients can connect and either establish a session or not. If the session ends and a message is sent over the same session-based channel an exception is thrown. - - WCF sessions have the following main conceptual features: - -- They are explicitly initiated and terminated by the calling application. - -- Messages delivered during a session are processed in the order in which they are received. - -- Sessions correlate a group of messages into a conversation. The meaning of that correlation is an abstraction. For instance, one session-based channel may correlate messages based on a shared network connection while another session-based channel may correlate messages based on a shared tag in the message body. The features that can be derived from the session depend on the nature of the correlation. - -- There is no general data store associated with a WCF session. - - If you are familiar with the class in ASP.NET applications and the functionality it provides, you might notice the following differences between that kind of session and WCF sessions: - -- ASP.NET sessions are always server-initiated. - -- ASP.NET sessions are implicitly unordered. - -- ASP.NET sessions provide a general data storage mechanism across requests. - - Client applications and service applications interact with sessions in different ways. Client applications initiate sessions and then receive and process the messages sent within the session. Service applications can use sessions as an extensibility point to add additional behavior. This is done by working directly with the or implementing a custom instance context provider. - -## Instancing - - The instancing behavior (set by using the property) controls how the is created in response to incoming messages. By default, each is associated with one user-defined service object, so (in the default case) setting the property also controls the instancing of user-defined service objects. The enumeration defines the instancing modes. - - The following instancing modes are available: - -- : A new (and therefore service object) is created for each client request. - -- : A new (and therefore service object) is created for each new client session and maintained for the lifetime of that session (this requires a binding that supports sessions). - -- : A single (and therefore service object) handles all client requests for the lifetime of the application. - - The following code example shows the default value, being explicitly set on a service class. - -```csharp +A *session* is a correlation of all messages sent between two endpoints. *Instancing* refers to controlling the lifetime of user-defined service objects and their related objects. *Concurrency* is the term given to the control of the number of threads executing in an at the same time. + + This topic describes these settings, how to use them, and the various interactions between them. + +## Sessions + + When a service contract sets the property to , that contract is saying that all calls (that is, the underlying message exchanges that support the calls) must be part of the same conversation. If a contract specifies that it allows sessions but does not require one, clients can connect and either establish a session or not. If the session ends and a message is sent over the same session-based channel an exception is thrown. + + WCF sessions have the following main conceptual features: + +- They are explicitly initiated and terminated by the calling application. + +- Messages delivered during a session are processed in the order in which they are received. + +- Sessions correlate a group of messages into a conversation. The meaning of that correlation is an abstraction. For instance, one session-based channel may correlate messages based on a shared network connection while another session-based channel may correlate messages based on a shared tag in the message body. The features that can be derived from the session depend on the nature of the correlation. + +- There is no general data store associated with a WCF session. + + If you are familiar with the class in ASP.NET applications and the functionality it provides, you might notice the following differences between that kind of session and WCF sessions: + +- ASP.NET sessions are always server-initiated. + +- ASP.NET sessions are implicitly unordered. + +- ASP.NET sessions provide a general data storage mechanism across requests. + + Client applications and service applications interact with sessions in different ways. Client applications initiate sessions and then receive and process the messages sent within the session. Service applications can use sessions as an extensibility point to add additional behavior. This is done by working directly with the or implementing a custom instance context provider. + +## Instancing + + The instancing behavior (set by using the property) controls how the is created in response to incoming messages. By default, each is associated with one user-defined service object, so (in the default case) setting the property also controls the instancing of user-defined service objects. The enumeration defines the instancing modes. + + The following instancing modes are available: + +- : A new (and therefore service object) is created for each client request. + +- : A new (and therefore service object) is created for each new client session and maintained for the lifetime of that session (this requires a binding that supports sessions). + +- : A single (and therefore service object) handles all client requests for the lifetime of the application. + + The following code example shows the default value, being explicitly set on a service class. + +```csharp [ServiceBehavior(InstanceContextMode=InstanceContextMode.PerSession)] public class CalculatorService : ICalculatorInstance { - ... -} -``` - - And while the property controls how often the is released, the and properties control when the service object is released. - -### Well-Known Singleton Services - - One variation on single instance service objects is sometimes useful: you can create a service object yourself and create the service host using that object. To do so, you must also set the property to or an exception is thrown when the service host is opened. - - Use the constructor to create such a service. It provides an alternative to implementing a custom when you wish to provide a specific object instance for use by a singleton service. You can use this overload when your service implementation type is difficult to construct (for example, if it does not implement a parameterless public constructor). - - Note that when an object is provided to this constructor, some features related to the Windows Communication Foundation (WCF) instancing behavior work differently. For example, calling has no effect when a singleton object instance is provided. Similarly, any other instance-release mechanism is ignored. The always behaves as if the property is set to for all operations. - -### Sharing InstanceContext Objects - - You can also control which sessionful channel or call is associated with which object by performing that association yourself. - -## Concurrency - - Concurrency is the control of the number of threads active in an at any one time. This is controlled by using the with the enumeration. - - The following three concurrency modes are available: - -- : Each instance context is allowed to have a maximum of one thread processing messages in the instance context at a time. Other threads wishing to use the same instance context must block until the original thread exits the instance context. - -- : Each service instance can have multiple threads processing messages concurrently. The service implementation must be thread-safe to use this concurrency mode. - -- : Each service instance processes one message at a time, but accepts re-entrant operation calls. The service only accepts these calls when it is calling out through a WCF client object. - + ... +} +``` + + And while the property controls how often the is released, the and properties control when the service object is released. + +### Well-Known Singleton Services + + One variation on single instance service objects is sometimes useful: you can create a service object yourself and create the service host using that object. To do so, you must also set the property to or an exception is thrown when the service host is opened. + + Use the constructor to create such a service. It provides an alternative to implementing a custom when you wish to provide a specific object instance for use by a singleton service. You can use this overload when your service implementation type is difficult to construct (for example, if it does not implement a parameterless public constructor). + + Note that when an object is provided to this constructor, some features related to the Windows Communication Foundation (WCF) instancing behavior work differently. For example, calling has no effect when a singleton object instance is provided. Similarly, any other instance-release mechanism is ignored. The always behaves as if the property is set to for all operations. + +### Sharing InstanceContext Objects + + You can also control which sessionful channel or call is associated with which object by performing that association yourself. + +## Concurrency + + Concurrency is the control of the number of threads active in an at any one time. This is controlled by using the with the enumeration. + + The following three concurrency modes are available: + +- : Each instance context is allowed to have a maximum of one thread processing messages in the instance context at a time. Other threads wishing to use the same instance context must block until the original thread exits the instance context. + +- : Each service instance can have multiple threads processing messages concurrently. The service implementation must be thread-safe to use this concurrency mode. + +- : Each service instance processes one message at a time, but accepts re-entrant operation calls. The service only accepts these calls when it is calling out through a WCF client object. + > [!NOTE] -> Understanding and developing code that safely uses more than one thread can be difficult to write successfully. Before using or values, ensure that your service is properly designed for these modes. For more information, see . - - The use of concurrency is related to the instancing mode. In instancing, concurrency is not relevant, because each message is processed by a new and, therefore, never more than one thread is active in the . - - The following code example demonstrates setting the property to . - +> Understanding and developing code that safely uses more than one thread can be difficult to write successfully. Before using or values, ensure that your service is properly designed for these modes. For more information, see . + + The use of concurrency is related to the instancing mode. In instancing, concurrency is not relevant, because each message is processed by a new and, therefore, never more than one thread is active in the . + + The following code example demonstrates setting the property to . + ```csharp [ServiceBehavior(ConcurrencyMode=ConcurrencyMode.Multiple, InstanceContextMode = InstanceContextMode.Single)] public class CalculatorService : ICalculatorConcurrency { - ... -} -``` - -## Sessions Interact with InstanceContext Settings - - Sessions and interact depending upon the combination of the value of the enumeration in a contract and the property on the service implementation, which controls the association between channels and specific service objects. - - The following table shows the result of an incoming channel either supporting sessions or not supporting sessions given a service's combination of the values of the property and the property. - -|InstanceContextMode value|||| -|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -|PerCall|- Behavior with sessionful channel: A session and for each call.
- Behavior with sessionless channel: An exception is thrown.|- Behavior with sessionful channel: A session and for each call.
- Behavior with sessionless channel: An for each call.|- Behavior with sessionful channel: An exception is thrown.
- Behavior with sessionless channel: An for each call.| -|PerSession|- Behavior with sessionful channel: A session and for each channel.
- Behavior with sessionless channel: An exception is thrown.|- Behavior with sessionful channel: A session and for each channel.
- Behavior with sessionless channel: An for each call.|- Behavior with sessionful channel: An exception is thrown.
- Behavior with sessionless channel: An for each call.| -|Single|- Behavior with sessionful channel: A session and one for all calls.
- Behavior with sessionless channel: An exception is thrown.|- Behavior with sessionful channel: A session and for the created or user-specified singleton.
- Behavior with sessionless channel: An for the created or user-specified singleton.|- Behavior with sessionful channel: An exception is thrown.
- Behavior with sessionless channel: An for each created singleton or for the user-specified singleton.| - + ... +} +``` + +## Sessions Interact with InstanceContext Settings + + Sessions and interact depending upon the combination of the value of the enumeration in a contract and the property on the service implementation, which controls the association between channels and specific service objects. + + The following table shows the result of an incoming channel either supporting sessions or not supporting sessions given a service's combination of the values of the property and the property. + +|InstanceContextMode value|||| +|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| +|PerCall|- Behavior with sessionful channel: A session and for each call.
- Behavior with sessionless channel: An exception is thrown.|- Behavior with sessionful channel: A session and for each call.
- Behavior with sessionless channel: An for each call.|- Behavior with sessionful channel: An exception is thrown.
- Behavior with sessionless channel: An for each call.| +|PerSession|- Behavior with sessionful channel: A session and for each channel.
- Behavior with sessionless channel: An exception is thrown.|- Behavior with sessionful channel: A session and for each channel.
- Behavior with sessionless channel: An for each call.|- Behavior with sessionful channel: An exception is thrown.
- Behavior with sessionless channel: An for each call.| +|Single|- Behavior with sessionful channel: A session and one for all calls.
- Behavior with sessionless channel: An exception is thrown.|- Behavior with sessionful channel: A session and for the created or user-specified singleton.
- Behavior with sessionless channel: An for the created or user-specified singleton.|- Behavior with sessionful channel: An exception is thrown.
- Behavior with sessionless channel: An for each created singleton or for the user-specified singleton.| + ## See also - [Using Sessions](../using-sessions.md) diff --git a/docs/framework/wcf/feature-details/side-by-side-versioning-in-workflowservicehost.md b/docs/framework/wcf/feature-details/side-by-side-versioning-in-workflowservicehost.md index 26b8a084042bf..81b97c2fc3714 100644 --- a/docs/framework/wcf/feature-details/side-by-side-versioning-in-workflowservicehost.md +++ b/docs/framework/wcf/feature-details/side-by-side-versioning-in-workflowservicehost.md @@ -2,162 +2,162 @@ description: "Learn more about: Side by Side Versioning in WorkflowServiceHost" title: "Side by Side Versioning in WorkflowServiceHost" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 60887eed-df40-4412-b812-41e1dd329d15 --- # Side by Side Versioning in WorkflowServiceHost -The side-by-side versioning introduced in .NET Framework 4.5 provides the capability to host multiple versions of a workflow service on a single endpoint. The side-by-side functionality provided allows a workflow service to be configured so that new instances of the workflow service are created using the new workflow definition, while running instances complete using the existing definition. This topic provides an overview of workflow service side-by-side execution using . - -## Hosting Multiple Versions in a Workflow Service +The side-by-side versioning introduced in .NET Framework 4.5 provides the capability to host multiple versions of a workflow service on a single endpoint. The side-by-side functionality provided allows a workflow service to be configured so that new instances of the workflow service are created using the new workflow definition, while running instances complete using the existing definition. This topic provides an overview of workflow service side-by-side execution using . + +## Hosting Multiple Versions in a Workflow Service + + contains two properties that can be configured to allow multiple versions of a workflow to execute side-by-side: and . contains the supported versions of the workflow service, and is used to uniquely identify each workflow service. This is done by associating a with the workflow service. A contains three identifying pieces of information. and contain a name and a and are required, and is optional and can be used to specify an additional string containing information such as assembly name or other desired information. Each workflow service contained in the collection must have a unique . A is unique if any of its three properties are different from another . A `null` is an allowable value for , but only one previous version of a workflow service may have a `null` . - contains two properties that can be configured to allow multiple versions of a workflow to execute side-by-side: and . contains the supported versions of the workflow service, and is used to uniquely identify each workflow service. This is done by associating a with the workflow service. A contains three identifying pieces of information. and contain a name and a and are required, and is optional and can be used to specify an additional string containing information such as assembly name or other desired information. Each workflow service contained in the collection must have a unique . A is unique if any of its three properties are different from another . A `null` is an allowable value for , but only one previous version of a workflow service may have a `null` . - > [!IMPORTANT] -> A should not contain any personally identifiable information (PII). is composed of three parts: a (), a (), and a (). Information about the used to create an instance is emitted to any configured tracking services at several different points of the activity life-cycle by the runtime. WF Tracking does not have any mechanism to hide PII (sensitive user data). Therefore, a instance should not contain any PII data as it will be emitted by the runtime in tracking records and may be visible to anyone with access to view the tracking records. - -### Rules for Hosting Multiple Versions of a Workflow Service - - When a user adds an additional version to the , there are several conditions that must be met in order for a workflow service to be hosted with the same set of endpoints and description. If any of the additional versions fail to meet these conditions, the throws an exception when `Open` is called. Each workflow definition provided to the host as an additional version must meet the following requirements (where the primary version is the workflow service definition that is provided to the host constructor). The additional workflow version must: - -- Have the same the as the primary version of the workflow service. - -- Must not have any or activities in its that are not in the primary version, and they must match the operation contract. - -- Have a unique . One and only one workflow definition may have a `null`. - - Some changes are permitted. The following items may be different between the versions: - -- The may have a different Name and Package than the primary version. - -- The value may be different than the primary version. - -- The may be different than the primary version. - -- The may be different than the primary version. - -### Configuring the DefinitionIdentity - - When a workflow service is created using the workflow designer, the is set using the **Properties** window. Click outside of the service’s root activity in the designer to select the workflow service, and choose **Properties Window** from the **View** menu. Select **WorkflowIdentity** from the drop-down list that appears beside the **DefinitionIdentity** property, and then expand and specify the desired properties. In the following example the is configured with the `MortgageWorkflow` and a of `1.0.0.0`. is optional and in this example is `null`. - - ![Screenshot that shows the DefinitionIdentity property.](./media/side-by-side-versioning-in-workflowservicehost/definitionidentity-property.bmp) - - When a workflow service is self-hosted, the is configured when the workflow service is constructed. In the following example, the is configured with the same values as the previous example, with the `MortgageWorkflow` and a of `1.0.0.0`. - -```csharp -WorkflowService service = new WorkflowService -{ - Name = "MortgageWorkflowService", - Body = new MortgageWorkflow(), - DefinitionIdentity = new WorkflowIdentity - { - Name = "MortgageWorkflow", - Version = new Version(1, 0, 0, 0) - } -}; -``` - -```vb -Dim service As New WorkflowService -With service - .Name = "MortgageWorkflowService" - .Body = New MortgageWorkflow - .DefinitionIdentity = New WorkflowIdentity With _ - { _ - .Name = "MortgageWorkflow", _ - .Version = New Version(1, 0, 0, 0) _ - } -End With -``` - - A is not required, although only one version of the workflow service may have a **null**. - +> A should not contain any personally identifiable information (PII). is composed of three parts: a (), a (), and a (). Information about the used to create an instance is emitted to any configured tracking services at several different points of the activity life-cycle by the runtime. WF Tracking does not have any mechanism to hide PII (sensitive user data). Therefore, a instance should not contain any PII data as it will be emitted by the runtime in tracking records and may be visible to anyone with access to view the tracking records. + +### Rules for Hosting Multiple Versions of a Workflow Service + + When a user adds an additional version to the , there are several conditions that must be met in order for a workflow service to be hosted with the same set of endpoints and description. If any of the additional versions fail to meet these conditions, the throws an exception when `Open` is called. Each workflow definition provided to the host as an additional version must meet the following requirements (where the primary version is the workflow service definition that is provided to the host constructor). The additional workflow version must: + +- Have the same the as the primary version of the workflow service. + +- Must not have any or activities in its that are not in the primary version, and they must match the operation contract. + +- Have a unique . One and only one workflow definition may have a `null`. + + Some changes are permitted. The following items may be different between the versions: + +- The may have a different Name and Package than the primary version. + +- The value may be different than the primary version. + +- The may be different than the primary version. + +- The may be different than the primary version. + +### Configuring the DefinitionIdentity + + When a workflow service is created using the workflow designer, the is set using the **Properties** window. Click outside of the service’s root activity in the designer to select the workflow service, and choose **Properties Window** from the **View** menu. Select **WorkflowIdentity** from the drop-down list that appears beside the **DefinitionIdentity** property, and then expand and specify the desired properties. In the following example the is configured with the `MortgageWorkflow` and a of `1.0.0.0`. is optional and in this example is `null`. + + ![Screenshot that shows the DefinitionIdentity property.](./media/side-by-side-versioning-in-workflowservicehost/definitionidentity-property.bmp) + + When a workflow service is self-hosted, the is configured when the workflow service is constructed. In the following example, the is configured with the same values as the previous example, with the `MortgageWorkflow` and a of `1.0.0.0`. + +```csharp +WorkflowService service = new WorkflowService +{ + Name = "MortgageWorkflowService", + Body = new MortgageWorkflow(), + DefinitionIdentity = new WorkflowIdentity + { + Name = "MortgageWorkflow", + Version = new Version(1, 0, 0, 0) + } +}; +``` + +```vb +Dim service As New WorkflowService +With service + .Name = "MortgageWorkflowService" + .Body = New MortgageWorkflow + .DefinitionIdentity = New WorkflowIdentity With _ + { _ + .Name = "MortgageWorkflow", _ + .Version = New Version(1, 0, 0, 0) _ + } +End With +``` + + A is not required, although only one version of the workflow service may have a **null**. + > [!NOTE] -> This is useful if the service was deployed initially without a configured, and then an updated version is created. - -### Adding a New Version to a Web-hosted Workflow Service - - The first step in configuring a new version of a workflow service in a web-hosted service is to create a new folder in the `App_Code` folder that has the same name as the service file. If the service’s `xamlx` file is named `MortgageWorkflow.xamlx`, then the folder must be named `MortgageWorkflow`. Place a copy of the original service’s `xamlx` file into this folder and rename it to a new name, such as `MortgageWorkflowV1.xamlx`. Make the desired changes to the primary service, update its , and then deploy the service. In the following example the has been updated with a of `MortgageWorkflow` and a of `2.0.0.0`. - - ![Screenshot that shows DefinitionIdentity of WorkflowIdentity.](./media/side-by-side-versioning-in-workflowservicehost/definitionidentity-workflowidentity.bmp) - - When the service restarts, the previous version will automatically be added to the collection because it is located in the designated `App_Code` subfolder. Note that if the primary version of the workflow service has a `null` the previous versions will not be added. One version may have a `null`, but if there are multiple versions the primary version must not be the one with the `null` or else the previous versions will not be added to the collection. - -### Adding a New Version to a Self-hosted Workflow Service - - When adding a new version to a self-hosted workflow service, the is configured with the primary version of the workflow service, and previous versions must be explicitly added to the collection. In the following example, a is configured with a primary workflow service that uses a `MortgageWorkflowV2` workflow definition, and a workflow service configured with a `MortgageWorkflowV1` workflow definition is added to the collection. Each workflow service is configured with a unique that reflects the version of the workflow definition. - -```csharp -// Create the primary version of the workflow service. -WorkflowService serviceV2 = new WorkflowService -{ - Name = "MortgageWorkflowService", - Body = new MortgageWorkflowV2(), - DefinitionIdentity = new WorkflowIdentity - { - Name = "MortgageWorkflow", - Version = new Version(2, 0, 0, 0) - } -}; - -// Configure the WorkflowServiceHost with the current version -// of the workflow service. This code requires Administrator -// privileges to function correctly. If running from Visual -// Studio, Visual Studio must be run with Administrator privileges. +> This is useful if the service was deployed initially without a configured, and then an updated version is created. + +### Adding a New Version to a Web-hosted Workflow Service + + The first step in configuring a new version of a workflow service in a web-hosted service is to create a new folder in the `App_Code` folder that has the same name as the service file. If the service’s `xamlx` file is named `MortgageWorkflow.xamlx`, then the folder must be named `MortgageWorkflow`. Place a copy of the original service’s `xamlx` file into this folder and rename it to a new name, such as `MortgageWorkflowV1.xamlx`. Make the desired changes to the primary service, update its , and then deploy the service. In the following example the has been updated with a of `MortgageWorkflow` and a of `2.0.0.0`. + + ![Screenshot that shows DefinitionIdentity of WorkflowIdentity.](./media/side-by-side-versioning-in-workflowservicehost/definitionidentity-workflowidentity.bmp) + + When the service restarts, the previous version will automatically be added to the collection because it is located in the designated `App_Code` subfolder. Note that if the primary version of the workflow service has a `null` the previous versions will not be added. One version may have a `null`, but if there are multiple versions the primary version must not be the one with the `null` or else the previous versions will not be added to the collection. + +### Adding a New Version to a Self-hosted Workflow Service + + When adding a new version to a self-hosted workflow service, the is configured with the primary version of the workflow service, and previous versions must be explicitly added to the collection. In the following example, a is configured with a primary workflow service that uses a `MortgageWorkflowV2` workflow definition, and a workflow service configured with a `MortgageWorkflowV1` workflow definition is added to the collection. Each workflow service is configured with a unique that reflects the version of the workflow definition. + +```csharp +// Create the primary version of the workflow service. +WorkflowService serviceV2 = new WorkflowService +{ + Name = "MortgageWorkflowService", + Body = new MortgageWorkflowV2(), + DefinitionIdentity = new WorkflowIdentity + { + Name = "MortgageWorkflow", + Version = new Version(2, 0, 0, 0) + } +}; + +// Configure the WorkflowServiceHost with the current version +// of the workflow service. This code requires Administrator +// privileges to function correctly. If running from Visual +// Studio, Visual Studio must be run with Administrator privileges. WorkflowServiceHost host = new WorkflowServiceHost(serviceV2, - new Uri("http://localhost:8080/MortgageWorkflowService")); - -// Create the previous version of the workflow service. -WorkflowService serviceV1 = new WorkflowService -{ - Name = "MortgageWorkflowService", - Body = new MortgageWorkflowV1(), - DefinitionIdentity = new WorkflowIdentity - { - Name = "MortgageWorkflow", - Version = new Version(1, 0, 0, 0) - } -}; - -// Add the previous version of the service to the SupportedVersions collection. -host.SupportedVersions.Add(serviceV1); -``` - -```vb -'Create the primary version of the workflow service -Dim serviceV2 As New WorkflowService -With serviceV2 - .Name = "MortgageWorkflowService" - .Body = New MortgageWorkflowV2 - .DefinitionIdentity = New WorkflowIdentity With _ - { _ - .Name = "MortgageWorkflow", _ - .Version = New Version(2, 0, 0, 0) _ - } -End With - -'Configure the WorkflowServiceHost with the current version -'of the workflow service. This code requires Administrator -'privileges to function correctly. If running from Visual -'Studio, Visual Studio must be run with Administrator privileges. - -Dim host As New WorkflowServiceHost(serviceV2, _ - New Uri("http://localhost:8080/MortgageWorkflowService")) - -'Create the previous version of the workflow service. -Dim serviceV1 As New WorkflowService -With serviceV1 - .Name = "MortgageWorkflowService" - .Body = New MortgageWorkflowV1 - .DefinitionIdentity = New WorkflowIdentity With _ - { _ - .Name = "MortgageWorkflow", _ - .Version = New Version(1, 0, 0, 0) _ - } -End With - -'Add the previous version of the service to the SupportedVersions collection. -host.SupportedVersions.Add(serviceV1) + new Uri("http://localhost:8080/MortgageWorkflowService")); + +// Create the previous version of the workflow service. +WorkflowService serviceV1 = new WorkflowService +{ + Name = "MortgageWorkflowService", + Body = new MortgageWorkflowV1(), + DefinitionIdentity = new WorkflowIdentity + { + Name = "MortgageWorkflow", + Version = new Version(1, 0, 0, 0) + } +}; + +// Add the previous version of the service to the SupportedVersions collection. +host.SupportedVersions.Add(serviceV1); +``` + +```vb +'Create the primary version of the workflow service +Dim serviceV2 As New WorkflowService +With serviceV2 + .Name = "MortgageWorkflowService" + .Body = New MortgageWorkflowV2 + .DefinitionIdentity = New WorkflowIdentity With _ + { _ + .Name = "MortgageWorkflow", _ + .Version = New Version(2, 0, 0, 0) _ + } +End With + +'Configure the WorkflowServiceHost with the current version +'of the workflow service. This code requires Administrator +'privileges to function correctly. If running from Visual +'Studio, Visual Studio must be run with Administrator privileges. + +Dim host As New WorkflowServiceHost(serviceV2, _ + New Uri("http://localhost:8080/MortgageWorkflowService")) + +'Create the previous version of the workflow service. +Dim serviceV1 As New WorkflowService +With serviceV1 + .Name = "MortgageWorkflowService" + .Body = New MortgageWorkflowV1 + .DefinitionIdentity = New WorkflowIdentity With _ + { _ + .Name = "MortgageWorkflow", _ + .Version = New Version(1, 0, 0, 0) _ + } +End With + +'Add the previous version of the service to the SupportedVersions collection. +host.SupportedVersions.Add(serviceV1) ``` diff --git a/docs/framework/wcf/feature-details/specify-the-certificate-authority-chain-verify-signatures-wcf.md b/docs/framework/wcf/feature-details/specify-the-certificate-authority-chain-verify-signatures-wcf.md index ca475f50ec2ab..0cc8129633d4b 100644 --- a/docs/framework/wcf/feature-details/specify-the-certificate-authority-chain-verify-signatures-wcf.md +++ b/docs/framework/wcf/feature-details/specify-the-certificate-authority-chain-verify-signatures-wcf.md @@ -9,26 +9,26 @@ helpviewer_keywords: --- # How to: Specify the Certificate Authority Certificate Chain Used to Verify Signatures (WCF) -When Windows Communication Foundation (WCF) receives a SOAP message signed using an X.509 certificate, by default it verifies that the X.509 certificate was issued by a trusted certification authority. This is done by looking in a certificate store and determining if the certificate for that certification authority has been designated as trusted. In order for WCF to make this determination, the certification authority certificate chain must be installed in the correct certificate store. - -### To install a certification authority certificate chain - -- For each certification authority that a SOAP message recipient intends to trust X.509 certificates issued from, install the certification authority certificate chain into the certificate store that WCF is configured to retrieve X.509 certificates from. - - For instance, if a SOAP message recipient intends to trust X.509 certificates issued by Microsoft, the certification authority certificate chain for Microsoft must be installed in the certificate store that WCF is set up to look for X.509 certificates from. The certificate store in which WCF looks for X.509 certificates can be specified in code or configuration. For example, this can be specified in code using the method or in configuration a few ways, including the [\](../../configure-apps/file-schema/wcf/servicecertificate-of-clientcredentials-element.md). - - Because Windows ships with a set of default certificate chains for trusted certificate authorities, it may not be necessary to install the certificate chain for all certificate authorities. - - 1. Export the certification authority certificate chain. - - Exactly how this is done depends on the certification authority. If the certification authority is running Microsoft Certificate Services, select **Download a CA certificate, certificate chain, or CRL**, and then choose **Download CA certificate**. - - 2. Import the certification authority certificate chain. - - In the Microsoft Management Console (MMC), open the Certificates snap-in. For the certificate store that WCF is configured to retrieve X.509 certificates from, select the **Trusted Root** **Certification Authorities** folder. Under the **Trusted Root Certification Authorities** folder, right-click the **Certificates** folder, point to **All Tasks**, and then click **Import**. Provide the file exported in step a. - - For more information about using the Certificates snap-in with MMC, see [How to: View Certificates with the MMC Snap-in](how-to-view-certificates-with-the-mmc-snap-in.md). - +When Windows Communication Foundation (WCF) receives a SOAP message signed using an X.509 certificate, by default it verifies that the X.509 certificate was issued by a trusted certification authority. This is done by looking in a certificate store and determining if the certificate for that certification authority has been designated as trusted. In order for WCF to make this determination, the certification authority certificate chain must be installed in the correct certificate store. + +### To install a certification authority certificate chain + +- For each certification authority that a SOAP message recipient intends to trust X.509 certificates issued from, install the certification authority certificate chain into the certificate store that WCF is configured to retrieve X.509 certificates from. + + For instance, if a SOAP message recipient intends to trust X.509 certificates issued by Microsoft, the certification authority certificate chain for Microsoft must be installed in the certificate store that WCF is set up to look for X.509 certificates from. The certificate store in which WCF looks for X.509 certificates can be specified in code or configuration. For example, this can be specified in code using the method or in configuration a few ways, including the [\](../../configure-apps/file-schema/wcf/servicecertificate-of-clientcredentials-element.md). + + Because Windows ships with a set of default certificate chains for trusted certificate authorities, it may not be necessary to install the certificate chain for all certificate authorities. + + 1. Export the certification authority certificate chain. + + Exactly how this is done depends on the certification authority. If the certification authority is running Microsoft Certificate Services, select **Download a CA certificate, certificate chain, or CRL**, and then choose **Download CA certificate**. + + 2. Import the certification authority certificate chain. + + In the Microsoft Management Console (MMC), open the Certificates snap-in. For the certificate store that WCF is configured to retrieve X.509 certificates from, select the **Trusted Root** **Certification Authorities** folder. Under the **Trusted Root Certification Authorities** folder, right-click the **Certificates** folder, point to **All Tasks**, and then click **Import**. Provide the file exported in step a. + + For more information about using the Certificates snap-in with MMC, see [How to: View Certificates with the MMC Snap-in](how-to-view-certificates-with-the-mmc-snap-in.md). + ## See also - [Working with Certificates](working-with-certificates.md) diff --git a/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md b/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md index 0adc5a8521540..b29c1170a7e19 100644 --- a/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md +++ b/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md @@ -2,587 +2,587 @@ description: "Learn more about: Specifying Data Transfer in Service Contracts" title: "Specifying Data Transfer in Service Contracts" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "service contracts [WCF], data transfer" ms.assetid: 7c5a26c8-89c9-4bcb-a4bc-7131e6d01f0c --- # Specifying Data Transfer in Service Contracts -The Windows Communication Foundation (WCF) can be thought of as a messaging infrastructure. Service operations can receive messages, process them, and send them messages. Messages are described using operation contracts. For example, consider the following contract. - -```csharp -[ServiceContract] -public interface IAirfareQuoteService -{ - [OperationContract] - float GetAirfare(string fromCity, string toCity); -} -``` - -```vb - -Public Interface IAirfareQuoteService - - - Function GetAirfare(fromCity As String, toCity As String) As Double -End Interface -``` - - Here, the `GetAirfare` operation accepts a message with information about `fromCity` and `toCity`, and then returns a message that contains a number. - - This topic explains the various ways in which an operation contract can describe messages. - -## Describing Messages by Using Parameters - - The simplest way to describe a message is to use a parameter list and the return value. In the preceding example, the `fromCity` and `toCity` string parameters were used to describe the request message, and the float return value was used to describe the reply message. If the return value alone is not enough to describe a reply message, out parameters may be used. For example, the following operation has `fromCity` and `toCity` in its request message, and a number together with a currency in its reply message: - -```csharp -[OperationContract] -float GetAirfare(string fromCity, string toCity, out string currency); -``` - -```vb - - Function GetAirfare(fromCity As String, toCity As String) As Double -``` - - Additionally, you may use reference parameters to make a parameter part of both the request and the reply message. The parameters must be of types that can be serialized (converted to XML). By default, WCF uses a component called the class to perform this conversion. Most primitive types (such as `int`, `string`, `float`, and `DateTime`.) are supported. User-defined types must normally have a data contract. For more information, see [Using Data Contracts](using-data-contracts.md). - +The Windows Communication Foundation (WCF) can be thought of as a messaging infrastructure. Service operations can receive messages, process them, and send them messages. Messages are described using operation contracts. For example, consider the following contract. + +```csharp +[ServiceContract] +public interface IAirfareQuoteService +{ + [OperationContract] + float GetAirfare(string fromCity, string toCity); +} +``` + +```vb + +Public Interface IAirfareQuoteService + + + Function GetAirfare(fromCity As String, toCity As String) As Double +End Interface +``` + + Here, the `GetAirfare` operation accepts a message with information about `fromCity` and `toCity`, and then returns a message that contains a number. + + This topic explains the various ways in which an operation contract can describe messages. + +## Describing Messages by Using Parameters + + The simplest way to describe a message is to use a parameter list and the return value. In the preceding example, the `fromCity` and `toCity` string parameters were used to describe the request message, and the float return value was used to describe the reply message. If the return value alone is not enough to describe a reply message, out parameters may be used. For example, the following operation has `fromCity` and `toCity` in its request message, and a number together with a currency in its reply message: + +```csharp +[OperationContract] +float GetAirfare(string fromCity, string toCity, out string currency); +``` + +```vb + + Function GetAirfare(fromCity As String, toCity As String) As Double +``` + + Additionally, you may use reference parameters to make a parameter part of both the request and the reply message. The parameters must be of types that can be serialized (converted to XML). By default, WCF uses a component called the class to perform this conversion. Most primitive types (such as `int`, `string`, `float`, and `DateTime`.) are supported. User-defined types must normally have a data contract. For more information, see [Using Data Contracts](using-data-contracts.md). + ```csharp -public interface IAirfareQuoteService -{ - [OperationContract] - float GetAirfare(Itinerary itinerary, DateTime date); - - [DataContract] - public class Itinerary - { - [DataMember] - public string fromCity; - [DataMember] - public string toCity; - } -} -``` - -```vb -Public Interface IAirfareQuoteService - - GetAirfare(itinerary as Itinerary, date as DateTime) as Double - - - Class Itinerary - - - Public fromCity As String - - Public toCity As String - End Class -End Interface -``` - - Occasionally, the `DataContractSerializer` is not adequate to serialize your types. WCF supports an alternative serialization engine, the , which you can also use to serialize parameters. The allows you to use more control over the resultant XML using attributes such as the `XmlAttributeAttribute`. To switch to using the for a particular operation or for the entire service, apply the attribute to an operation or a service. For example: - -```csharp -[ServiceContract] -public interface IAirfareQuoteService -{ - [OperationContract] - [XmlSerializerFormat] - float GetAirfare(Itinerary itinerary, DateTime date); -} -public class Itinerary -{ - public string fromCity; - public string toCity; - [XmlAttribute] - public bool isFirstClass; -} -``` - -```vb - -Public Interface IAirfareQuoteService - - - GetAirfare(itinerary as Itinerary, date as DateTime) as Double - -End Interface - -Class Itinerary - - Public fromCity As String - Public toCity As String - - Public isFirstClass As Boolean -End Class -``` - - For more information, see [Using the XmlSerializer Class](using-the-xmlserializer-class.md). Remember that manually switching to the as shown here is not recommended unless you have specific reasons to do so as detailed in that topic. - - To isolate .NET parameter names from contract names, you can use the attribute, and use the `Name` property to set the contract name. For example, the following operation contract is equivalent to the first example in this topic. - -```csharp -[OperationContract] -public float GetAirfare( - [MessageParameter(Name="fromCity")] string originCity, - [MessageParameter(Name="toCity")] string destinationCity); -``` - -```vb - - Function GetAirfare( fromCity As String, toCity As String) As Double -``` - -## Describing Empty Messages - - An empty request message can be described by having no input or reference parameters. For example, in C#: - - `[OperationContract]` - - `public int GetCurrentTemperature();` - - For example, in Visual Basic: - - `` - - `Function GetCurrentTemperature() as Integer` - - An empty reply message can be described by having a `void` return type and no output or reference parameters. For example in: - -```csharp -[OperationContract] -public void SetTemperature(int temperature); -``` - -```vb - -Sub SetTemperature(temperature As Integer) -``` - - This is different from a one-way operation, such as: - -```csharp -[OperationContract(IsOneWay=true)] -public void SetLightbulbStatus(bool isOn); -``` - -```vb - -Sub SetLightbulbStatus(isOne As Boolean) -``` - - The `SetTemperatureStatus` operation returns an empty message. It may return a fault instead if there is a problem processing the input message. The `SetLightbulbStatus` operation returns nothing. There is no way to communicate a fault condition from this operation. - -## Describing Messages by Using Message Contracts - - You may want to use a single type to represent the entire message. While it is possible to use a data contract for this purpose, the recommended way to do this is to use a message contract—this avoids unnecessary levels of wrapping in the resultant XML. Additionally, message contracts allow you to exercise more control over resultant messages. For instance, you can decide which pieces of information should be in the message body and which should be in the message headers. The following example shows the use of message contracts. - -```csharp -[ServiceContract] -public interface IAirfareQuoteService -{ - [OperationContract] - GetAirfareResponse GetAirfare(GetAirfareRequest request); -} - -[MessageContract] -public class GetAirfareRequest -{ - [MessageHeader] public DateTime date; - [MessageBodyMember] public Itinerary itinerary; -} - -[MessageContract] -public class GetAirfareResponse -{ - [MessageBodyMember] public float airfare; - [MessageBodyMember] public string currency; -} - -[DataContract] -public class Itinerary -{ - [DataMember] public string fromCity; - [DataMember] public string toCity; -} -``` - -```vb - -Public Interface IAirfareQuoteService - - Function GetAirfare(request As GetAirfareRequest) As GetAirfareResponse -End Interface - - -Public Class GetAirfareRequest +public interface IAirfareQuoteService +{ + [OperationContract] + float GetAirfare(Itinerary itinerary, DateTime date); + + [DataContract] + public class Itinerary + { + [DataMember] + public string fromCity; + [DataMember] + public string toCity; + } +} +``` + +```vb +Public Interface IAirfareQuoteService + + GetAirfare(itinerary as Itinerary, date as DateTime) as Double + + + Class Itinerary + + + Public fromCity As String + + Public toCity As String + End Class +End Interface +``` + + Occasionally, the `DataContractSerializer` is not adequate to serialize your types. WCF supports an alternative serialization engine, the , which you can also use to serialize parameters. The allows you to use more control over the resultant XML using attributes such as the `XmlAttributeAttribute`. To switch to using the for a particular operation or for the entire service, apply the attribute to an operation or a service. For example: + +```csharp +[ServiceContract] +public interface IAirfareQuoteService +{ + [OperationContract] + [XmlSerializerFormat] + float GetAirfare(Itinerary itinerary, DateTime date); +} +public class Itinerary +{ + public string fromCity; + public string toCity; + [XmlAttribute] + public bool isFirstClass; +} +``` + +```vb + +Public Interface IAirfareQuoteService + + + GetAirfare(itinerary as Itinerary, date as DateTime) as Double + +End Interface + +Class Itinerary + + Public fromCity As String + Public toCity As String + + Public isFirstClass As Boolean +End Class +``` + + For more information, see [Using the XmlSerializer Class](using-the-xmlserializer-class.md). Remember that manually switching to the as shown here is not recommended unless you have specific reasons to do so as detailed in that topic. + + To isolate .NET parameter names from contract names, you can use the attribute, and use the `Name` property to set the contract name. For example, the following operation contract is equivalent to the first example in this topic. + +```csharp +[OperationContract] +public float GetAirfare( + [MessageParameter(Name="fromCity")] string originCity, + [MessageParameter(Name="toCity")] string destinationCity); +``` + +```vb + + Function GetAirfare( fromCity As String, toCity As String) As Double +``` + +## Describing Empty Messages + + An empty request message can be described by having no input or reference parameters. For example, in C#: + + `[OperationContract]` + + `public int GetCurrentTemperature();` + + For example, in Visual Basic: + + `` + + `Function GetCurrentTemperature() as Integer` + + An empty reply message can be described by having a `void` return type and no output or reference parameters. For example in: + +```csharp +[OperationContract] +public void SetTemperature(int temperature); +``` + +```vb + +Sub SetTemperature(temperature As Integer) +``` + + This is different from a one-way operation, such as: + +```csharp +[OperationContract(IsOneWay=true)] +public void SetLightbulbStatus(bool isOn); +``` + +```vb + +Sub SetLightbulbStatus(isOne As Boolean) +``` + + The `SetTemperatureStatus` operation returns an empty message. It may return a fault instead if there is a problem processing the input message. The `SetLightbulbStatus` operation returns nothing. There is no way to communicate a fault condition from this operation. + +## Describing Messages by Using Message Contracts + + You may want to use a single type to represent the entire message. While it is possible to use a data contract for this purpose, the recommended way to do this is to use a message contract—this avoids unnecessary levels of wrapping in the resultant XML. Additionally, message contracts allow you to exercise more control over resultant messages. For instance, you can decide which pieces of information should be in the message body and which should be in the message headers. The following example shows the use of message contracts. + +```csharp +[ServiceContract] +public interface IAirfareQuoteService +{ + [OperationContract] + GetAirfareResponse GetAirfare(GetAirfareRequest request); +} + +[MessageContract] +public class GetAirfareRequest +{ + [MessageHeader] public DateTime date; + [MessageBodyMember] public Itinerary itinerary; +} + +[MessageContract] +public class GetAirfareResponse +{ + [MessageBodyMember] public float airfare; + [MessageBodyMember] public string currency; +} + +[DataContract] +public class Itinerary +{ + [DataMember] public string fromCity; + [DataMember] public string toCity; +} +``` + +```vb + +Public Interface IAirfareQuoteService + + Function GetAirfare(request As GetAirfareRequest) As GetAirfareResponse +End Interface + + +Public Class GetAirfareRequest - Public Property date as DateTime - - Public Property itinerary As Itinerary -End Class - - -Public Class GetAirfareResponse - - Public Property airfare As Double - Public Property currency As String -End Class - - -Public Class Itinerary - Public Property fromCity As String - Public Property toCity As String -End Class -``` - - For more information, see [Using Message Contracts](using-message-contracts.md). - - In the previous example, the class is still used by default. The class can also be used with message contracts. To do this, apply the attribute to either the operation or the contract, and use types compatible with the class in the message headers and body members. - -## Describing Messages by Using Streams - - Another way to describe messages in operations is to use the class or one of its derived classes in an operation contract or as a message contract body member (it must be the only member in this case). For incoming messages, the type must be `Stream`—you cannot use derived classes. - - Instead of invoking the serializer, WCF retrieves data from a stream and puts it directly into an outgoing message, or retrieves data from an incoming message and puts it directly into a stream. The following sample shows the use of streams. - -```csharp -[OperationContract] -public Stream DownloadFile(string fileName); -``` - -```vb - -Function DownloadFile(fileName As String) As String -``` - - You cannot combine `Stream` and non-stream data in a single message body. Use a message contract to put the extra data in message headers. The following example shows the incorrect usage of streams when defining the operation contract. - -```csharp -//Incorrect: -// [OperationContract] -// public void UploadFile (string fileName, Stream fileData); -``` - -```vb -'Incorrect: - ' - Public Sub UploadFile(fileName As String, fileData As StreamingContext) -``` - - The following sample shows the correct usage of streams when defining an operation contract. - -```csharp -[OperationContract] -public void UploadFile (UploadFileMessage message); -//code omitted -[MessageContract] -public class UploadFileMessage -{ - [MessageHeader] public string fileName; - [MessageBodyMember] public Stream fileData; -} -``` - -```vb - -Public Sub UploadFile(fileName As String, fileData As StreamingContext) -'Code Omitted - -Public Class UploadFileMessage - - Public Property fileName As String - - Public Property fileData As Stream -End Class -``` - - For more information, see [Large Data and Streaming](large-data-and-streaming.md). - -## Using the Message Class - - To have complete programmatic control over messages sent or received, you can use the class directly, as shown in the following example code. - -```csharp -[OperationContract] -public void LogMessage(Message m); -``` - -```vb - -Sub LogMessage(m As Message) -``` - - This is an advanced scenario, which is described in detail in [Using the Message Class](using-the-message-class.md). - -## Describing Fault Messages - - In addition to the messages that are described by the return value and output or reference parameters, any operation that is not one-way can return at least two possible messages: its normal response message and a fault message. Consider the following operation contract. - -```csharp -[OperationContract] -float GetAirfare(string fromCity, string toCity, DateTime date); -``` - -```vb - -Function GetAirfare(fromCity As String, toCity As String, date as DateTime) -``` - - This operation may either return a normal message that contains a `float` number, or a fault message that contains a fault code and a description. You can accomplish this by throwing a in your service implementation. - - You can specify additional possible fault messages by using the attribute. The additional faults must be serializable using the , as shown in the following example code. - -```csharp -[OperationContract] -[FaultContract(typeof(ItineraryNotAvailableFault))] -float GetAirfare(string fromCity, string toCity, DateTime date); - -//code omitted - -[DataContract] -public class ItineraryNotAvailableFault -{ - [DataMember] - public bool IsAlternativeDateAvailable; - - [DataMember] - public DateTime alternativeSuggestedDate; -} -``` - -```vb - - -Function GetAirfare(fromCity As String, toCity As String, date as DateTime) As Double - -'Code Omitted - -Public Class - - Public Property IsAlternativeDateAvailable As Boolean - - Public Property alternativeSuggestedDate As DateTime -End Class -``` - - These additional faults can be generated by throwing a of the appropriate data contract type. For more information, see [Handling Exceptions and Faults](../extending/handling-exceptions-and-faults.md). - - You cannot use the class to describe faults. The has no effect on fault contracts. - -## Using Derived Types - - You may want to use a base type in an operation or a message contract, and then use a derived type when actually invoking the operation. In this case, you must use either the attribute or some alternative mechanism to allow the use of derived types. Consider the following operation. - -```csharp -[OperationContract] -public bool IsLibraryItemAvailable(LibraryItem item); -``` - + Public Property date as DateTime + + Public Property itinerary As Itinerary +End Class + + +Public Class GetAirfareResponse + + Public Property airfare As Double + Public Property currency As String +End Class + + +Public Class Itinerary + Public Property fromCity As String + Public Property toCity As String +End Class +``` + + For more information, see [Using Message Contracts](using-message-contracts.md). + + In the previous example, the class is still used by default. The class can also be used with message contracts. To do this, apply the attribute to either the operation or the contract, and use types compatible with the class in the message headers and body members. + +## Describing Messages by Using Streams + + Another way to describe messages in operations is to use the class or one of its derived classes in an operation contract or as a message contract body member (it must be the only member in this case). For incoming messages, the type must be `Stream`—you cannot use derived classes. + + Instead of invoking the serializer, WCF retrieves data from a stream and puts it directly into an outgoing message, or retrieves data from an incoming message and puts it directly into a stream. The following sample shows the use of streams. + +```csharp +[OperationContract] +public Stream DownloadFile(string fileName); +``` + +```vb + +Function DownloadFile(fileName As String) As String +``` + + You cannot combine `Stream` and non-stream data in a single message body. Use a message contract to put the extra data in message headers. The following example shows the incorrect usage of streams when defining the operation contract. + +```csharp +//Incorrect: +// [OperationContract] +// public void UploadFile (string fileName, Stream fileData); +``` + +```vb +'Incorrect: + ' + Public Sub UploadFile(fileName As String, fileData As StreamingContext) +``` + + The following sample shows the correct usage of streams when defining an operation contract. + +```csharp +[OperationContract] +public void UploadFile (UploadFileMessage message); +//code omitted +[MessageContract] +public class UploadFileMessage +{ + [MessageHeader] public string fileName; + [MessageBodyMember] public Stream fileData; +} +``` + +```vb + +Public Sub UploadFile(fileName As String, fileData As StreamingContext) +'Code Omitted + +Public Class UploadFileMessage + + Public Property fileName As String + + Public Property fileData As Stream +End Class +``` + + For more information, see [Large Data and Streaming](large-data-and-streaming.md). + +## Using the Message Class + + To have complete programmatic control over messages sent or received, you can use the class directly, as shown in the following example code. + +```csharp +[OperationContract] +public void LogMessage(Message m); +``` + +```vb + +Sub LogMessage(m As Message) +``` + + This is an advanced scenario, which is described in detail in [Using the Message Class](using-the-message-class.md). + +## Describing Fault Messages + + In addition to the messages that are described by the return value and output or reference parameters, any operation that is not one-way can return at least two possible messages: its normal response message and a fault message. Consider the following operation contract. + +```csharp +[OperationContract] +float GetAirfare(string fromCity, string toCity, DateTime date); +``` + ```vb - - Function IsLibraryItemAvailable(item As LibraryItem) As Boolean -``` - - Assume that two types, `Book` and `Magazine`, derive from `LibraryItem`. To use these types in the `IsLibraryItemAvailable` operation, you can change the operation as follows: - - `[OperationContract]` - - `[ServiceKnownType(typeof(Book))]` - - `[ServiceKnownType(typeof(Magazine))]` - - `public bool IsLibraryItemAvailable(LibraryItem item);` - - Alternatively, you can use the attribute when the default is in use, as shown in the following example code. - -```csharp -[OperationContract] -public bool IsLibraryItemAvailable(LibraryItem item); - + +Function GetAirfare(fromCity As String, toCity As String, date as DateTime) +``` + + This operation may either return a normal message that contains a `float` number, or a fault message that contains a fault code and a description. You can accomplish this by throwing a in your service implementation. + + You can specify additional possible fault messages by using the attribute. The additional faults must be serializable using the , as shown in the following example code. + +```csharp +[OperationContract] +[FaultContract(typeof(ItineraryNotAvailableFault))] +float GetAirfare(string fromCity, string toCity, DateTime date); + +//code omitted + +[DataContract] +public class ItineraryNotAvailableFault +{ + [DataMember] + public bool IsAlternativeDateAvailable; + + [DataMember] + public DateTime alternativeSuggestedDate; +} +``` + +```vb + + +Function GetAirfare(fromCity As String, toCity As String, date as DateTime) As Double + +'Code Omitted + +Public Class + + Public Property IsAlternativeDateAvailable As Boolean + + Public Property alternativeSuggestedDate As DateTime +End Class +``` + + These additional faults can be generated by throwing a of the appropriate data contract type. For more information, see [Handling Exceptions and Faults](../extending/handling-exceptions-and-faults.md). + + You cannot use the class to describe faults. The has no effect on fault contracts. + +## Using Derived Types + + You may want to use a base type in an operation or a message contract, and then use a derived type when actually invoking the operation. In this case, you must use either the attribute or some alternative mechanism to allow the use of derived types. Consider the following operation. + +```csharp +[OperationContract] +public bool IsLibraryItemAvailable(LibraryItem item); +``` + +```vb + + Function IsLibraryItemAvailable(item As LibraryItem) As Boolean +``` + + Assume that two types, `Book` and `Magazine`, derive from `LibraryItem`. To use these types in the `IsLibraryItemAvailable` operation, you can change the operation as follows: + + `[OperationContract]` + + `[ServiceKnownType(typeof(Book))]` + + `[ServiceKnownType(typeof(Magazine))]` + + `public bool IsLibraryItemAvailable(LibraryItem item);` + + Alternatively, you can use the attribute when the default is in use, as shown in the following example code. + +```csharp +[OperationContract] +public bool IsLibraryItemAvailable(LibraryItem item); + // code omitted - -[DataContract] -[KnownType(typeof(Book))] -[KnownType(typeof(Magazine))] -public class LibraryItem -{ - //code omitted -} -``` - -```vb - -Function IsLibraryItemAvailable(item As LibraryItem) As Boolean - -'Code Omitted - - - -Public Class LibraryItem - 'Code Omitted -End Class -``` - - You can use the attribute when using the . - - You can apply the attribute to an operation or to the entire service. It accepts either a type or the name of the method to call to get a list of known types, just like the attribute. For more information, see [Data Contract Known Types](data-contract-known-types.md). - -## Specifying the Use and Style - - When describing services using Web Services Description Language (WSDL), the two commonly used styles are Document and remote procedure call (RPC). In the Document style, the entire message body is described using the schema, and the WSDL describes the various message body parts by referring to elements within that schema. In the RPC style, the WSDL refers to a schema type for each message part rather than an element. In some cases, you have to manually select one of these styles. You can do this by applying the attribute and setting the `Style` property (when the is in use), or by setting `Style` on the attribute (when using the ). - - Additionally, the supports two forms of serialized XML: `Literal` and `Encoded`. `Literal` is the most commonly accepted form, and is the only form the supports. `Encoded` is a legacy form described in section 5 of the SOAP specification, and is not recommended for new services. To switch to `Encoded` mode, set the `Use` property on the attribute to `Encoded`. - - In most cases, you should not change the default settings for the `Style` and `Use` properties. - -## Controlling the Serialization Process - - You can do a number of things to customize the way data is serialized. - -### Changing Server Serialization Settings - - When the default is in use, you can control some aspects of the serialization process on the service by applying the attribute to the service. Specifically, you may use the `MaxItemsInObjectGraph` property to set the quota that limits the maximum number of objects the deserializes. You can use the `IgnoreExtensionDataObject` property to turn off the round-tripping versioning feature. For more information about quotas, see [Security Considerations for Data](security-considerations-for-data.md). For more information about round-tripping, see [Forward-Compatible Data Contracts](forward-compatible-data-contracts.md). - -```csharp -[ServiceBehavior(MaxItemsInObjectGraph=100000)] -public class MyDataService:IDataService -{ - public DataPoint[] GetData() - { - // Implementation omitted - } -} -``` - -```vb - -Public Class MyDataService Implements IDataService - - Function GetData() As DataPoint() - ‘ Implementation omitted - End Function -End Interface -``` - -### Serialization Behaviors - - Two behaviors are available in WCF, the and the that are automatically plugged in depending on which serializer is in use for a particular operation. Because these behaviors are applied automatically, you normally do not have to be aware of them. - - However, the `DataContractSerializerOperationBehavior` has the `MaxItemsInObjectGraph`, `IgnoreExtensionDataObject`, and `DataContractSurrogate` properties that you may use to customize the serialization process. The first two properties have the same meaning as discussed in the previous section. You can use the `DataContractSurrogate` property to enable data contract surrogates, which are a powerful mechanism for customizing and extending the serialization process. For more information, see [Data Contract Surrogates](../extending/data-contract-surrogates.md). - - You can use the `DataContractSerializerOperationBehavior` to customize both client and server serialization. The following example shows how to increase the `MaxItemsInObjectGraph` quota on the client. - -```csharp -ChannelFactory factory = new ChannelFactory(binding, address); -foreach (OperationDescription op in factory.Endpoint.Contract.Operations) -{ - DataContractSerializerOperationBehavior dataContractBehavior = - op.Behaviors.Find() - as DataContractSerializerOperationBehavior; - if (dataContractBehavior != null) - { - dataContractBehavior.MaxItemsInObjectGraph = 100000; - } -} -IDataService client = factory.CreateChannel(); -``` - -```vb -Dim factory As ChannelFactory(Of IDataService) = New ChannelFactory(Of IDataService)(binding, address) -For Each op As OperationDescription In factory.Endpoint.Contract.Operations - Dim dataContractBehavior As DataContractSerializerOperationBehavior = op.Behaviors.Find(Of DataContractSerializerOperationBehavior)() - If dataContractBehavior IsNot Nothing Then - dataContractBehavior.MaxItemsInObjectGraph = 100000 - End If - Next - Dim client As IDataService = factory.CreateChannel -``` - + +[DataContract] +[KnownType(typeof(Book))] +[KnownType(typeof(Magazine))] +public class LibraryItem +{ + //code omitted +} +``` + +```vb + +Function IsLibraryItemAvailable(item As LibraryItem) As Boolean + +'Code Omitted + + + +Public Class LibraryItem + 'Code Omitted +End Class +``` + + You can use the attribute when using the . + + You can apply the attribute to an operation or to the entire service. It accepts either a type or the name of the method to call to get a list of known types, just like the attribute. For more information, see [Data Contract Known Types](data-contract-known-types.md). + +## Specifying the Use and Style + + When describing services using Web Services Description Language (WSDL), the two commonly used styles are Document and remote procedure call (RPC). In the Document style, the entire message body is described using the schema, and the WSDL describes the various message body parts by referring to elements within that schema. In the RPC style, the WSDL refers to a schema type for each message part rather than an element. In some cases, you have to manually select one of these styles. You can do this by applying the attribute and setting the `Style` property (when the is in use), or by setting `Style` on the attribute (when using the ). + + Additionally, the supports two forms of serialized XML: `Literal` and `Encoded`. `Literal` is the most commonly accepted form, and is the only form the supports. `Encoded` is a legacy form described in section 5 of the SOAP specification, and is not recommended for new services. To switch to `Encoded` mode, set the `Use` property on the attribute to `Encoded`. + + In most cases, you should not change the default settings for the `Style` and `Use` properties. + +## Controlling the Serialization Process + + You can do a number of things to customize the way data is serialized. + +### Changing Server Serialization Settings + + When the default is in use, you can control some aspects of the serialization process on the service by applying the attribute to the service. Specifically, you may use the `MaxItemsInObjectGraph` property to set the quota that limits the maximum number of objects the deserializes. You can use the `IgnoreExtensionDataObject` property to turn off the round-tripping versioning feature. For more information about quotas, see [Security Considerations for Data](security-considerations-for-data.md). For more information about round-tripping, see [Forward-Compatible Data Contracts](forward-compatible-data-contracts.md). + +```csharp +[ServiceBehavior(MaxItemsInObjectGraph=100000)] +public class MyDataService:IDataService +{ + public DataPoint[] GetData() + { + // Implementation omitted + } +} +``` + +```vb + +Public Class MyDataService Implements IDataService + + Function GetData() As DataPoint() + ‘ Implementation omitted + End Function +End Interface +``` + +### Serialization Behaviors + + Two behaviors are available in WCF, the and the that are automatically plugged in depending on which serializer is in use for a particular operation. Because these behaviors are applied automatically, you normally do not have to be aware of them. + + However, the `DataContractSerializerOperationBehavior` has the `MaxItemsInObjectGraph`, `IgnoreExtensionDataObject`, and `DataContractSurrogate` properties that you may use to customize the serialization process. The first two properties have the same meaning as discussed in the previous section. You can use the `DataContractSurrogate` property to enable data contract surrogates, which are a powerful mechanism for customizing and extending the serialization process. For more information, see [Data Contract Surrogates](../extending/data-contract-surrogates.md). + + You can use the `DataContractSerializerOperationBehavior` to customize both client and server serialization. The following example shows how to increase the `MaxItemsInObjectGraph` quota on the client. + +```csharp +ChannelFactory factory = new ChannelFactory(binding, address); +foreach (OperationDescription op in factory.Endpoint.Contract.Operations) +{ + DataContractSerializerOperationBehavior dataContractBehavior = + op.Behaviors.Find() + as DataContractSerializerOperationBehavior; + if (dataContractBehavior != null) + { + dataContractBehavior.MaxItemsInObjectGraph = 100000; + } +} +IDataService client = factory.CreateChannel(); +``` + +```vb +Dim factory As ChannelFactory(Of IDataService) = New ChannelFactory(Of IDataService)(binding, address) +For Each op As OperationDescription In factory.Endpoint.Contract.Operations + Dim dataContractBehavior As DataContractSerializerOperationBehavior = op.Behaviors.Find(Of DataContractSerializerOperationBehavior)() + If dataContractBehavior IsNot Nothing Then + dataContractBehavior.MaxItemsInObjectGraph = 100000 + End If + Next + Dim client As IDataService = factory.CreateChannel +``` + The following is the equivalent code on the service, in the self-hosted case: - -```csharp -ServiceHost serviceHost = new ServiceHost(typeof(IDataService)) -foreach (ServiceEndpoint ep in serviceHost.Description.Endpoints) -{ -foreach (OperationDescription op in ep.Contract.Operations) -{ - DataContractSerializerOperationBehavior dataContractBehavior = - op.Behaviors.Find() - as DataContractSerializerOperationBehavior; - if (dataContractBehavior != null) - { - dataContractBehavior.MaxItemsInObjectGraph = 100000; - } -} -} -serviceHost.Open(); -``` - -```vb -Dim serviceHost As ServiceHost = New ServiceHost(GetType(IDataService)) - For Each ep As ServiceEndpoint In serviceHost.Description.Endpoints - For Each op As OperationDescription In ep.Contract.Operations - Dim dataContractBehavior As DataContractSerializerOperationBehavior = op.Behaviors.Find(Of DataContractSerializerOperationBehavior)() - - If dataContractBehavior IsNot Nothing Then - dataContractBehavior.MaxItemsInObjectGraph = 100000 - End If - Next - Next - serviceHost.Open() -``` - - In the Web-hosted case, you must create a new `ServiceHost` derived class and use a service host factory to plug it in. - -### Controlling Serialization Settings in Configuration - - The `MaxItemsInObjectGraph` and `IgnoreExtensionDataObject` can be controlled through configuration by using the `dataContractSerializer` endpoint or service behavior, as shown in the following example. - -```xml - - - - - - - - - - - () + as DataContractSerializerOperationBehavior; + if (dataContractBehavior != null) + { + dataContractBehavior.MaxItemsInObjectGraph = 100000; + } +} +} +serviceHost.Open(); +``` + +```vb +Dim serviceHost As ServiceHost = New ServiceHost(GetType(IDataService)) + For Each ep As ServiceEndpoint In serviceHost.Description.Endpoints + For Each op As OperationDescription In ep.Contract.Operations + Dim dataContractBehavior As DataContractSerializerOperationBehavior = op.Behaviors.Find(Of DataContractSerializerOperationBehavior)() + + If dataContractBehavior IsNot Nothing Then + dataContractBehavior.MaxItemsInObjectGraph = 100000 + End If + Next + Next + serviceHost.Open() +``` + + In the Web-hosted case, you must create a new `ServiceHost` derived class and use a service host factory to plug it in. + +### Controlling Serialization Settings in Configuration + + The `MaxItemsInObjectGraph` and `IgnoreExtensionDataObject` can be controlled through configuration by using the `dataContractSerializer` endpoint or service behavior, as shown in the following example. + +```xml + + + + + + + + + + + - - - -``` - -### Shared Type Serialization, Object Graph Preservation, and Custom Serializers - - The serializes using data contract names and not .NET type names. This is consistent with service-oriented architecture tenets and allows for a great degree of flexibility—the .NET types can change without affecting the wire contract. In rare cases, you may want to serialize actual .NET type names, thereby introducing a tight coupling between the client and the server, similar to the .NET Framework remoting technology. This is not a recommended practice, except in rare cases that usually occur when migrating to WCF from .NET Framework remoting. In this case, you must use the class instead of the class. - - The normally serializes object graphs as object trees. That is, if the same object is referred to more than once, it is serialized more than once. For example, consider a `PurchaseOrder` instance that has two fields of type Address called `billTo` and `shipTo`. If both fields are set to the same Address instance, there are two identical Address instances after serialization and deserialization. This is done because there is no standard interoperable way to represent object graphs in XML (except for the legacy SOAP encoded standard available on the , as described in the previous section on `Style` and `Use`). Serializing object graphs as trees has certain disadvantages, for example, graphs with circular references cannot be serialized. Occasionally, it is necessary to switch to true object graph serialization, even though it is not interoperable. This can be done by using the constructed with the `preserveObjectReferences` parameter set to `true`. - - Occasionally, the built-in serializers are not enough for your scenario. In most cases, you can still use the abstraction from which both the and the derive. - - The previous three cases (.NET type preservation, object graph preservation, and completely custom `XmlObjectSerializer`-based serialization) all require a custom serializer be plugged in. To do this, perform the following steps: - -1. Write your own behavior deriving from the . - -2. Override the two `CreateSerializer` methods to return your own serializer (either the , the with `preserveObjectReferences` set to `true`, or your own custom ). - -3. Before opening the service host or creating a client channel, remove the existing behavior and plug in the custom derived class that you created in the previous steps. - - For more information about advanced serialization concepts, see [Serialization and Deserialization](serialization-and-deserialization.md). - + contract="IDataService" + name="" /> + + + +``` + +### Shared Type Serialization, Object Graph Preservation, and Custom Serializers + + The serializes using data contract names and not .NET type names. This is consistent with service-oriented architecture tenets and allows for a great degree of flexibility—the .NET types can change without affecting the wire contract. In rare cases, you may want to serialize actual .NET type names, thereby introducing a tight coupling between the client and the server, similar to the .NET Framework remoting technology. This is not a recommended practice, except in rare cases that usually occur when migrating to WCF from .NET Framework remoting. In this case, you must use the class instead of the class. + + The normally serializes object graphs as object trees. That is, if the same object is referred to more than once, it is serialized more than once. For example, consider a `PurchaseOrder` instance that has two fields of type Address called `billTo` and `shipTo`. If both fields are set to the same Address instance, there are two identical Address instances after serialization and deserialization. This is done because there is no standard interoperable way to represent object graphs in XML (except for the legacy SOAP encoded standard available on the , as described in the previous section on `Style` and `Use`). Serializing object graphs as trees has certain disadvantages, for example, graphs with circular references cannot be serialized. Occasionally, it is necessary to switch to true object graph serialization, even though it is not interoperable. This can be done by using the constructed with the `preserveObjectReferences` parameter set to `true`. + + Occasionally, the built-in serializers are not enough for your scenario. In most cases, you can still use the abstraction from which both the and the derive. + + The previous three cases (.NET type preservation, object graph preservation, and completely custom `XmlObjectSerializer`-based serialization) all require a custom serializer be plugged in. To do this, perform the following steps: + +1. Write your own behavior deriving from the . + +2. Override the two `CreateSerializer` methods to return your own serializer (either the , the with `preserveObjectReferences` set to `true`, or your own custom ). + +3. Before opening the service host or creating a client channel, remove the existing behavior and plug in the custom derived class that you created in the previous steps. + + For more information about advanced serialization concepts, see [Serialization and Deserialization](serialization-and-deserialization.md). + ## See also - [Using the XmlSerializer Class](using-the-xmlserializer-class.md) diff --git a/docs/framework/wcf/feature-details/stand-alone-json-serialization.md b/docs/framework/wcf/feature-details/stand-alone-json-serialization.md index 3257675572171..118c24b785802 100644 --- a/docs/framework/wcf/feature-details/stand-alone-json-serialization.md +++ b/docs/framework/wcf/feature-details/stand-alone-json-serialization.md @@ -70,7 +70,7 @@ XML types become JSON strings. - There are some special rules that specify how XML is wrapped - for more information, see the Advanced Information section later in this article. -- If you are using ASP.NET AJAX and do not want to use strings in the JavaScript, but want the XML DOM instead, set the property to XML on or the property to XML on the . +- If you are using ASP.NET AJAX and do not want to use strings in the JavaScript, but want the XML DOM instead, set the property to XML on or the property to XML on the . ### Collections, dictionaries, and arrays @@ -94,7 +94,7 @@ All collections, dictionaries, and arrays are represented in JSON as arrays. ### Order of Data Members -Order of data members is not important when using JSON. Specifically, even if is set, JSON data can still be deserialized in any order. +Order of data members is not important when using JSON. Specifically, even if is set, JSON data can still be deserialized in any order. ### JSON Types @@ -252,7 +252,7 @@ If the base `Shape` type also contained a data member called "`radius`", this le #### Polymorphism and Certain Interface Types -It is forbidden to serialize a collection type or a type that implements where a non-collection type that is not (except for ) is expected. For example, a custom interface called `IMyInterface` and a type `MyType` that implement both of type `int` and `IMyInterface`. It is forbidden to return `MyType` from an operation whose return type is `IMyInterface`. This is because `MyType` must be serialized as a JSON array and requires a type hint, and as stated before you cannot include a type hint with arrays, only with complex types. +It is forbidden to serialize a collection type or a type that implements where a non-collection type that is not (except for ) is expected. For example, a custom interface called `IMyInterface` and a type `MyType` that implement both of type `int` and `IMyInterface`. It is forbidden to return `MyType` from an operation whose return type is `IMyInterface`. This is because `MyType` must be serialized as a JSON array and requires a type hint, and as stated before you cannot include a type hint with arrays, only with complex types. #### Known Types and Configuration @@ -260,7 +260,7 @@ All of the Known Type mechanisms used by the : a JSON array with each entry that has a type hint if it is a complex type. For example, a of type `Shape` assigned to looks like the following. +Collections assigned to Object are serialized as if they are collections that implement : a JSON array with each entry that has a type hint if it is a complex type. For example, a of type `Shape` assigned to looks like the following. ```json [{"__type":"Shape:#MyApp.Shapes","x":50,"y":70}, @@ -270,7 +270,7 @@ Collections assigned to Object are serialized as if they are collections that im When deserialized back into : -- `Shape` must be in the Known Types list. Having of type `Shape` in known types has no effect. Note that you do not have to add `Shape` to known types on serialization in this case - this is done automatically. +- `Shape` must be in the Known Types list. Having of type `Shape` in known types has no effect. Note that you do not have to add `Shape` to known types on serialization in this case - this is done automatically. - The collection is deserialized as an of type that contains `Shape` instances. diff --git a/docs/framework/wcf/feature-details/standard-endpoints.md b/docs/framework/wcf/feature-details/standard-endpoints.md index 79d46848d98d3..8528ef3842152 100644 --- a/docs/framework/wcf/feature-details/standard-endpoints.md +++ b/docs/framework/wcf/feature-details/standard-endpoints.md @@ -10,7 +10,7 @@ Endpoints are defined by specifying an address, a binding, and a contract. Other ## Infrastructure Endpoints - A service may expose endpoints with some of the properties not explicitly implemented by the service author. For example, the metadata exchange endpoint exposes the contract but as a service author you do not implement that interface, it is implemented by WCF. Such infrastructure endpoints have default values for one or more endpoint properties, some of which may be unalterable. The property of the metadata exchange endpoint must be , while other properties like binding can be supplied by the developer. Infrastructure endpoints are identified by setting the property to `true`. + A service may expose endpoints with some of the properties not explicitly implemented by the service author. For example, the metadata exchange endpoint exposes the contract but as a service author you do not implement that interface, it is implemented by WCF. Such infrastructure endpoints have default values for one or more endpoint properties, some of which may be unalterable. The property of the metadata exchange endpoint must be , while other properties like binding can be supplied by the developer. Infrastructure endpoints are identified by setting the property to `true`. ## Application Endpoints @@ -40,7 +40,7 @@ public class CustomEndpoint : ServiceEndpoint } ``` - To use a user-defined custom endpoint in a configuration file you must derive a class from , derive a class from , and register the new standard endpoint in the extensions section in app.config or machine.config. The provides configuration support for the standard endpoint, as shown in the following example. + To use a user-defined custom endpoint in a configuration file you must derive a class from , derive a class from , and register the new standard endpoint in the extensions section in app.config or machine.config. The provides configuration support for the standard endpoint, as shown in the following example. ```csharp public class CustomEndpointElement : StandardEndpointElement @@ -101,7 +101,7 @@ public class CustomEndpointElement : StandardEndpointElement } ``` - The provides the backing type for the collection that appears under the `` section in the configuration for the standard endpoint. The following example shows how to implement this class. + The provides the backing type for the collection that appears under the `` section in the configuration for the standard endpoint. The following example shows how to implement this class. ```csharp public class CustomEndpointCollectionElement : StandardEndpointCollectionElement @@ -146,7 +146,7 @@ serviceHost.AddServiceEndpoint(new CustomEndpoint()); ``` - The type of standard endpoint is specified using the kind attribute in the `` element. The endpoint is configured within the `` element. In the example above, a endpoint is added and configured. The `` element contains a `` that sets the property of the . + The type of standard endpoint is specified using the kind attribute in the `` element. The endpoint is configured within the `` element. In the example above, a endpoint is added and configured. The `` element contains a `` that sets the property of the . ## Standard Endpoints Shipped with the .NET Framework diff --git a/docs/framework/wcf/feature-details/startup-time-of-wcf-client-applications-using-the-xmlserializer.md b/docs/framework/wcf/feature-details/startup-time-of-wcf-client-applications-using-the-xmlserializer.md index 262b77657f96a..1c963fb65371c 100644 --- a/docs/framework/wcf/feature-details/startup-time-of-wcf-client-applications-using-the-xmlserializer.md +++ b/docs/framework/wcf/feature-details/startup-time-of-wcf-client-applications-using-the-xmlserializer.md @@ -36,9 +36,9 @@ Services and client applications that use data types that are serializable using 1. Compile the generated serialization code into a separate assembly with the name [*original assembly*].XmlSerializers.dll (for example, MyApp.XmlSerializers.dll). Your application must be able to load the assembly, which must be signed with the same key as the original assembly. If you recompile the original assembly, you must regenerate the serialization assembly. - 2. Compile the generated serialization code into a separate assembly and use the on the service contract that uses the . Set the or properties to point to the compiled serialization assembly. + 2. Compile the generated serialization code into a separate assembly and use the on the service contract that uses the . Set the or properties to point to the compiled serialization assembly. - 3. Compile the generated serialization code into your application assembly and add the to the service contract that uses the . Do not set the or properties. The default serialization assembly is assumed to be the current assembly. + 3. Compile the generated serialization code into your application assembly and add the to the service contract that uses the . Do not set the or properties. The default serialization assembly is assumed to be the current assembly. ### To generate XmlSerializer serialization code in Visual Studio diff --git a/docs/framework/wcf/feature-details/streaming-message-transfer.md b/docs/framework/wcf/feature-details/streaming-message-transfer.md index a22ea5a97806e..8e74ddab99ec0 100644 --- a/docs/framework/wcf/feature-details/streaming-message-transfer.md +++ b/docs/framework/wcf/feature-details/streaming-message-transfer.md @@ -28,7 +28,7 @@ Windows Communication Foundation (WCF) transports support two modes for transfer ## Enabling Asynchronous Streaming - To enable asynchronous streaming, add the endpoint behavior to the service host and set its property to `true`. + To enable asynchronous streaming, add the endpoint behavior to the service host and set its property to `true`. This version of WCF also added the capability of true asynchronous streaming on the send side. This improves scalability of the service in scenarios where it is streaming messages to multiple clients some of which are slow in reading; possibly due to network congestion or are not reading at all. In these scenarios WCF no longer blocks individual threads on the service per client. This ensures that the service is able to process many more clients thereby improving the scalability of the service. diff --git a/docs/framework/wcf/feature-details/syndication-extensibility.md b/docs/framework/wcf/feature-details/syndication-extensibility.md index 1d24d3f9c4207..b5b190541b9cd 100644 --- a/docs/framework/wcf/feature-details/syndication-extensibility.md +++ b/docs/framework/wcf/feature-details/syndication-extensibility.md @@ -6,42 +6,42 @@ ms.assetid: 4d941175-74a2-4b15-81b3-086e8a95d25f --- # Syndication Extensibility -The Syndication API is designed to provide a format-neutral programming model that allows syndicated content to be written to the wire in a variety of formats. The abstract data model consists of the following classes: - -- - -- - -- - -- - -- - - These classes map closely to the constructs defined in the Atom 1.0 specification, although some of the names are different. - - A key feature of syndication protocols is extensibility. Both Atom 1.0 and RSS 2.0, add attributes and elements to syndication feeds that are not defined in the specifications. The Windows Communication Foundation (WCF) syndication programming model provides the following ways of working with custom attributes and extensions, loosely-typed access and deriving a new class. - -## Loosely Typed Access - - Adding extensions by deriving a new class requires writing additional code. Another option is accessing extensions in a loosely-typed way. All of the types defined in the syndication abstract data model contain properties named `AttributeExtensions` and `ElementExtensions` (with one exception, has an `AttributeExtensions` property but no `ElementExtensions` property). These properties are collections of extensions not processed by the `TryParseAttribute` and `TryParseElement` methods respectively. You can access these unprocessed extensions by calling on the `ElementExtensions` property of , , , , and . This set of methods finds all extensions with the specified name and namespace, deserializes them individually into instances of `TExtension` and returns them as a collection of `TExtension` objects. - -## Deriving a New Class - - You can derive a new class from any of the existing abstract data model classes. Do this when implementing an application in which most of the feeds you are working with have a particular extension. In this topic, most of the feeds that the program works with contain a `MyExtension` extension. To provide an improved programming experience, do the following steps: - -- Create a class to hold the extension data. In this case, create a class called MyExtension. - -- Derive a class called MyExtensionItem from to expose a property of type MyExtension for programmability purposes. - -- Override in the MyExtensionItem class to instantiate a new MyExtension instance when a MyExtension is read in. - -- Override in the MyExtensionItem class to write the contents of the MyExtension property to an XML writer. - -- Derive a class called MyExtensionFeed from . - -- Override in the MyExtensionFeed class to instantiate a MyExtensionItem instead of the default . A series of methods are defined in and that can create , , and objects (for example, , , and ). All of which can be overridden to create a custom derived class. - +The Syndication API is designed to provide a format-neutral programming model that allows syndicated content to be written to the wire in a variety of formats. The abstract data model consists of the following classes: + +- + +- + +- + +- + +- + + These classes map closely to the constructs defined in the Atom 1.0 specification, although some of the names are different. + + A key feature of syndication protocols is extensibility. Both Atom 1.0 and RSS 2.0, add attributes and elements to syndication feeds that are not defined in the specifications. The Windows Communication Foundation (WCF) syndication programming model provides the following ways of working with custom attributes and extensions, loosely-typed access and deriving a new class. + +## Loosely Typed Access + + Adding extensions by deriving a new class requires writing additional code. Another option is accessing extensions in a loosely-typed way. All of the types defined in the syndication abstract data model contain properties named `AttributeExtensions` and `ElementExtensions` (with one exception, has an `AttributeExtensions` property but no `ElementExtensions` property). These properties are collections of extensions not processed by the `TryParseAttribute` and `TryParseElement` methods respectively. You can access these unprocessed extensions by calling on the `ElementExtensions` property of , , , , and . This set of methods finds all extensions with the specified name and namespace, deserializes them individually into instances of `TExtension` and returns them as a collection of `TExtension` objects. + +## Deriving a New Class + + You can derive a new class from any of the existing abstract data model classes. Do this when implementing an application in which most of the feeds you are working with have a particular extension. In this topic, most of the feeds that the program works with contain a `MyExtension` extension. To provide an improved programming experience, do the following steps: + +- Create a class to hold the extension data. In this case, create a class called MyExtension. + +- Derive a class called MyExtensionItem from to expose a property of type MyExtension for programmability purposes. + +- Override in the MyExtensionItem class to instantiate a new MyExtension instance when a MyExtension is read in. + +- Override in the MyExtensionItem class to write the contents of the MyExtension property to an XML writer. + +- Derive a class called MyExtensionFeed from . + +- Override in the MyExtensionFeed class to instantiate a MyExtensionItem instead of the default . A series of methods are defined in and that can create , , and objects (for example, , , and ). All of which can be overridden to create a custom derived class. + ## See also - [WCF Syndication Overview](wcf-syndication-overview.md) diff --git a/docs/framework/wcf/feature-details/tampering.md b/docs/framework/wcf/feature-details/tampering.md index 72622c31cc901..3291c18f58905 100644 --- a/docs/framework/wcf/feature-details/tampering.md +++ b/docs/framework/wcf/feature-details/tampering.md @@ -6,16 +6,16 @@ ms.assetid: 3bad93be-60bb-4f89-96ab-a1c3dc7c0fad --- # Tampering -*Tampering* is the act of altering a message, or the delivery of a message, and using the altered message for a purpose other than what it was intended for. - -## Do Not Disable WS-Addressing +*Tampering* is the act of altering a message, or the delivery of a message, and using the altered message for a purpose other than what it was intended for. + +## Do Not Disable WS-Addressing + + The WS-Addressing specification provides address headers on each message, allowing a message recipient to verify the sender of the message. You can disable this feature by setting the property to . + + When the security mode is set to Message, and if WS-Addressing is disabled, an attacker could take a request from a client and send it to another service, and the second service has no way of detecting that the message came from the original client. In effect, the first service can pretend that it is a client when talking to the second service. + + To mitigate this, never set the property to , and avoid the use of , such as the static property, which sets the property to . - The WS-Addressing specification provides address headers on each message, allowing a message recipient to verify the sender of the message. You can disable this feature by setting the property to . - - When the security mode is set to Message, and if WS-Addressing is disabled, an attacker could take a request from a client and send it to another service, and the second service has no way of detecting that the message came from the original client. In effect, the first service can pretend that it is a client when talking to the second service. - - To mitigate this, never set the property to , and avoid the use of , such as the static property, which sets the property to . - ## See also - [Security Considerations](security-considerations-in-wcf.md) diff --git a/docs/framework/wcf/feature-details/transport-security-overview.md b/docs/framework/wcf/feature-details/transport-security-overview.md index 2e51e7d974adc..f9ddfe2a82991 100644 --- a/docs/framework/wcf/feature-details/transport-security-overview.md +++ b/docs/framework/wcf/feature-details/transport-security-overview.md @@ -15,11 +15,11 @@ Transport security mechanisms in Windows Communication Foundation (WCF) depend o > When SSL security is used with .NET Framework 3.5 and later an WCF client uses both the intermediate certificates in its certificate store and the intermediate certificates received during SSL negotiation to perform certificate chain validation on the service's certificate. .NET Framework 3.0 only uses the intermediate certificates installed in the local certificate store. > [!WARNING] -> When transport security is used, the property may be overwritten. To prevent this from happening set the to . is a service behavior that can be set on the service description. +> When transport security is used, the property may be overwritten. To prevent this from happening set the to . is a service behavior that can be set on the service description. ## BasicHttpBinding - By default, the class does not provide security. This binding is designed for interoperability with Web service providers that do not implement security. However, you can switch on security by setting the property to any value except . To enable transport security, set the property to . + By default, the class does not provide security. This binding is designed for interoperability with Web service providers that do not implement security. However, you can switch on security by setting the property to any value except . To enable transport security, set the property to . ### Interoperation with IIS @@ -68,7 +68,7 @@ Transport security mechanisms in Windows Communication Foundation (WCF) depend o The class is designed for interoperation with services that implement WS-* specifications. The transport security for this binding is Secure Sockets Layer (SSL) over HTTP, or HTTPS. To create an WCF application that uses SSL, use IIS to host the application. Alternatively, if you are creating a self-hosted application, use the HttpCfg.exe tool to bind an X.509 certificate to a specific port on a computer. The port number is specified as part of the WCF application as an endpoint address. When using transport mode, the endpoint address must include the HTTPS protocol or an exception will be thrown at runtime. For more information, see [HTTP Transport Security](http-transport-security.md). - For client authentication, set the property of the class to one of the enumeration values. The enumeration values are identical to the client credential types for and are designed to be hosted with IIS services. + For client authentication, set the property of the class to one of the enumeration values. The enumeration values are identical to the client credential types for and are designed to be hosted with IIS services. The following example shows the binding being used with a client credential type of Windows. @@ -83,14 +83,14 @@ Transport security mechanisms in Windows Communication Foundation (WCF) depend o The class uses TCP for message transport. Security for the transport mode is provided by implementing Transport Layer Security (TLS) over TCP. The TLS implementation is provided by the operating system. - You can also specify the client's credential type by setting the property of the class to one of the values, as shown in the following code. + You can also specify the client's credential type by setting the property of the class to one of the values, as shown in the following code. [!code-csharp[c_ProgrammingSecurity#12](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_programmingsecurity/cs/source.cs#12)] [!code-vb[c_ProgrammingSecurity#12](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_programmingsecurity/vb/source.vb#12)] #### Client - On the client, you must specify a certificate using the method of the class. + On the client, you must specify a certificate using the method of the class. > [!NOTE] > If you are using Windows security, a certificate is not required. diff --git a/docs/framework/wcf/feature-details/transport-security-with-basic-authentication.md b/docs/framework/wcf/feature-details/transport-security-with-basic-authentication.md index abe91baa0c908..6712c42e5ca19 100644 --- a/docs/framework/wcf/feature-details/transport-security-with-basic-authentication.md +++ b/docs/framework/wcf/feature-details/transport-security-with-basic-authentication.md @@ -2,7 +2,7 @@ title: "Transport Security with Basic Authentication" description: Review this WCF scenario, which shows basic authentication for a WCF service and client. The service needs a valid certificate that the client trusts. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: b54f491d-196b-4279-876c-76b83ec0442c @@ -13,110 +13,110 @@ ms.custom: # Transport Security with Basic Authentication The following illustration shows a Windows Communication Foundation (WCF) service and client. The server needs a valid X.509 certificate that can be used for Secure Sockets Layer (SSL), and the clients must trust the server’s certificate. Further, the Web service already has an SSL implementation that can be used. For more information about enabling basic authentication on Internet Information Services (IIS), see [Basic Authentication](/iis/configuration/system.webserver/security/authentication/basicauthentication). - - ![Screenshot that shows transport security with basic authentication.](./media/transport-security-with-basic-authentication/transport-security-basic-authentication.gif) - -|Characteristic|Description| -|--------------------|-----------------| -|Security Mode|Transport| -|Interoperability|With existing Web service clients and services| -|Authentication (Server)

Authentication (Client)|Yes (using HTTPS)

Yes (through User name/Password)| -|Integrity|Yes| -|Confidentiality|Yes| -|Transport|HTTPS| -|Binding|| - -## Service - - The following code and configuration are meant to run independently. Do one of the following: - -- Create a stand-alone service using the code with no configuration. - -- Create a service using the supplied configuration, but do not define any endpoints. - -### Code - - The following code shows how to create a service endpoint that uses a Windows domain user name and password for transfer security. Note that the service requires an X.509 certificate to authenticate to the client. For more information, see [Working with Certificates](working-with-certificates.md) and [How to: Configure a Port with an SSL Certificate](how-to-configure-a-port-with-an-ssl-certificate.md). - + + ![Screenshot that shows transport security with basic authentication.](./media/transport-security-with-basic-authentication/transport-security-basic-authentication.gif) + +|Characteristic|Description| +|--------------------|-----------------| +|Security Mode|Transport| +|Interoperability|With existing Web service clients and services| +|Authentication (Server)

Authentication (Client)|Yes (using HTTPS)

Yes (through User name/Password)| +|Integrity|Yes| +|Confidentiality|Yes| +|Transport|HTTPS| +|Binding|| + +## Service + + The following code and configuration are meant to run independently. Do one of the following: + +- Create a stand-alone service using the code with no configuration. + +- Create a service using the supplied configuration, but do not define any endpoints. + +### Code + + The following code shows how to create a service endpoint that uses a Windows domain user name and password for transfer security. Note that the service requires an X.509 certificate to authenticate to the client. For more information, see [Working with Certificates](working-with-certificates.md) and [How to: Configure a Port with an SSL Certificate](how-to-configure-a-port-with-an-ssl-certificate.md). + [!code-csharp[C_SecurityScenarios#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_securityscenarios/cs/source.cs#1)] - [!code-vb[C_SecurityScenarios#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securityscenarios/vb/source.vb#1)] - -## Configuration - - The following configures a service to use basic authentication with transport-level security: - -```xml - - - - - - - - - - - - - - - + + + + + + + + + + + + + + - - - - -``` - -## Client - -### Code - - The following code shows the client code that includes the user name and password. Note that the user must provide a valid Windows user name and password. The code to return the user name and password is not shown here. Use a dialog box or other interface to query the user for the information. - + contract="BasicAuthentication.ICalculator" /> + + + + +``` + +## Client + +### Code + + The following code shows the client code that includes the user name and password. Note that the user must provide a valid Windows user name and password. The code to return the user name and password is not shown here. Use a dialog box or other interface to query the user for the information. + > [!NOTE] -> User name and password can only be set using code. - +> User name and password can only be set using code. + [!code-csharp[C_SecurityScenarios#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_securityscenarios/cs/source.cs#2)] - [!code-vb[C_SecurityScenarios#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securityscenarios/vb/source.vb#2)] - -### Configuration + [!code-vb[C_SecurityScenarios#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securityscenarios/vb/source.vb#2)] + +### Configuration + + The following code shows the client configuration. - The following code shows the client configuration. - > [!NOTE] -> You cannot use configuration to set the user name and password. The configuration shown here must be augmented using code to set the user name and password. - -```xml - - - - - - - - - - - - - +> You cannot use configuration to set the user name and password. The configuration shown here must be augmented using code to set the user name and password. + +```xml + + + + + + + + + + + + + - - - -``` - + contract="ICalculator" + name="WSHttpBinding_ICalculator" /> + + + +``` + ## See also -- +- - - [Working with Certificates](working-with-certificates.md) - [How to: Configure a Port with an SSL Certificate](how-to-configure-a-port-with-an-ssl-certificate.md) diff --git a/docs/framework/wcf/feature-details/troubleshooting-correlation.md b/docs/framework/wcf/feature-details/troubleshooting-correlation.md index 717747c4d3d7c..8a28a860d2409 100644 --- a/docs/framework/wcf/feature-details/troubleshooting-correlation.md +++ b/docs/framework/wcf/feature-details/troubleshooting-correlation.md @@ -20,7 +20,7 @@ host.UnknownMessageReceived += delegate(object sender, UnknownMessageReceivedEve }; ``` - For Web-hosted services, this event can be handled by deriving a class from and overriding . + For Web-hosted services, this event can be handled by deriving a class from and overriding . ```csharp class CustomFactory : WorkflowServiceHostFactory @@ -46,7 +46,7 @@ class CustomFactory : WorkflowServiceHostFactory `<% @ServiceHost Language="C#" Service="OrderServiceWorkflow" Factory="CustomFactory" %>` - When this handler is invoked, the message can be retrieved by using the property of the , and will resemble the following message. + When this handler is invoked, the message can be retrieved by using the property of the , and will resemble the following message. ```xml @@ -66,7 +66,7 @@ class CustomFactory : WorkflowServiceHostFactory ## Use Tracking to Monitor the Progress of the Workflow - Tracking provides a way to monitor the progress of a workflow. By default, tracking records are emitted for workflow life-cycle events, activity life-cycle events, fault propagation, and bookmark resumption. Additionally, custom tracking records can be emitted by custom activities. When troubleshooting correlation, the activity tracking records, the bookmark resumption records, and the fault propagation records are the most useful. The activity tracking records can be used to determine the current progress of the workflow and can help identify which messaging activity is currently waiting for messages. Bookmark resumption records are useful because they indicate that a message was received by the workflow, and fault propagation records provide a record of any faults in the workflow. To enable tracking, specify the desired in the of the . In the following example, the `ConsoleTrackingParticipant` (from the [Custom Tracking](../../windows-workflow-foundation/samples/custom-tracking.md) sample) is configured by using the default tracking profile. + Tracking provides a way to monitor the progress of a workflow. By default, tracking records are emitted for workflow life-cycle events, activity life-cycle events, fault propagation, and bookmark resumption. Additionally, custom tracking records can be emitted by custom activities. When troubleshooting correlation, the activity tracking records, the bookmark resumption records, and the fault propagation records are the most useful. The activity tracking records can be used to determine the current progress of the workflow and can help identify which messaging activity is currently waiting for messages. Bookmark resumption records are useful because they indicate that a message was received by the workflow, and fault propagation records provide a record of any faults in the workflow. To enable tracking, specify the desired in the of the . In the following example, the `ConsoleTrackingParticipant` (from the [Custom Tracking](../../windows-workflow-foundation/samples/custom-tracking.md) sample) is configured by using the default tracking profile. ```csharp host.WorkflowExtensions.Add(new ConsoleTrackingParticipant()); @@ -132,7 +132,7 @@ supports the context protocol and has a valid context initialized. Request-reply correlation is used with a / pair to implement a two-way operation in a workflow service and with a / pair that invokes a two-way operation in another Web service. When invoking a two-way operation in a WCF service, the service can be either a traditional imperative code-based WCF service or it can be a workflow service. To use request-reply correlation a two-way binding must be used, such as , and the operations must be two-way. - If the workflow service has two-way operations in parallel, or overlapping / or / pairs, then the implicit correlation handle management provided by may not be sufficient, especially in high-stress scenarios, and messages may not be correctly routed. To prevent this issue from occurring, we recommend that you always explicitly specify a when using request-reply correlation. When using the **SendAndReceiveReply** and **ReceiveAndSendReply** templates from the Messaging section of the **Toolbox** in the workflow designer, a is explicitly configured by default. When building a workflow by using code, the is specified in the of the first activity in the pair. In the following example, a activity is configured with an explicit specified in the . + If the workflow service has two-way operations in parallel, or overlapping / or / pairs, then the implicit correlation handle management provided by may not be sufficient, especially in high-stress scenarios, and messages may not be correctly routed. To prevent this issue from occurring, we recommend that you always explicitly specify a when using request-reply correlation. When using the **SendAndReceiveReply** and **ReceiveAndSendReply** templates from the Messaging section of the **Toolbox** in the workflow designer, a is explicitly configured by default. When building a workflow by using code, the is specified in the of the first activity in the pair. In the following example, a activity is configured with an explicit specified in the . ```csharp Variable RRHandle = new Variable(); diff --git a/docs/framework/wcf/feature-details/troubleshooting-queued-messaging.md b/docs/framework/wcf/feature-details/troubleshooting-queued-messaging.md index f4720d8be1da9..3dc81a2adee35 100644 --- a/docs/framework/wcf/feature-details/troubleshooting-queued-messaging.md +++ b/docs/framework/wcf/feature-details/troubleshooting-queued-messaging.md @@ -59,13 +59,13 @@ This section contains answers to most common troubleshooting issues. Some issues - Check that the transactional queue requirements are compatible with the assurances specified. Note the following principles: - - You can send durable messages (datagrams and sessions) with "exactly once" assurances ( = `true`) only to a transactional queue. + - You can send durable messages (datagrams and sessions) with "exactly once" assurances ( = `true`) only to a transactional queue. - You can send sessions only with "exactly once" assurances. - A transaction is required to receive messages in a session from a transactional queue. - - You can send or receive volatile or durable messages (datagrams only) with no assurances ( = `false`) only to a non-transactional queue. + - You can send or receive volatile or durable messages (datagrams only) with no assurances ( = `false`) only to a non-transactional queue. - Check the dead-letter queue. If you find the messages there, determine why they were not delivered. @@ -77,9 +77,9 @@ This section contains answers to most common troubleshooting issues. Some issues **Q:** Is it always necessary to define a custom dead-letter queue, or is there a default dead-letter queue? -**A:** If assurances are "exactly once" ( = `true`), and if you do not specify a custom dead-letter queue, the default is a system-wide transactional dead-letter queue. +**A:** If assurances are "exactly once" ( = `true`), and if you do not specify a custom dead-letter queue, the default is a system-wide transactional dead-letter queue. -If assurances are none ( = `false`), then the default is no dead-letter queue functionality. +If assurances are none ( = `false`), then the default is no dead-letter queue functionality. **Q:** My service throws on SvcHost.Open with a message "EndpointListener requirements cannot be met by the ListenerFactory". Why? @@ -138,9 +138,9 @@ The system dead-letter queue, as well as any custom dead-letter queue, is partic **A:** By default, messages are signed using an MSMQ internal certificate that requires the Active Directory directory service. In workgroup mode, because Active Directory is not available, signing the message fails. So the message lands in the dead-letter queue and failure cause, such as "Bad signature", is indicated. -The workaround is to turn off security. This is done by setting = to make it work in workgroup mode. +The workaround is to turn off security. This is done by setting = to make it work in workgroup mode. -Another workaround is to get the from the property and set it to , and set the client certificate. +Another workaround is to get the from the property and set it to , and set the client certificate. Yet another workaround is to install MSMQ with Active Directory integration. @@ -202,4 +202,4 @@ Yet another workaround is to install MSMQ with Active Directory integration. ## Using Custom MSMQ Bindings with ReceiveContext Enabled -When using a custom MSMQ binding with enabled, processing an incoming message uses a thread pool thread because native MSMQ doesn't support I/O completion for asynchronous receives. This is because processing such a message uses internal transactions for and MSMQ doesn't support asynchronous processing. To work around this issue, you can add a to the endpoint to force synchronous processing or set to 1. +When using a custom MSMQ binding with enabled, processing an incoming message uses a thread pool thread because native MSMQ doesn't support I/O completion for asynchronous receives. This is because processing such a message uses internal transactions for and MSMQ doesn't support asynchronous processing. To work around this issue, you can add a to the endpoint to force synchronous processing or set to 1. diff --git a/docs/framework/wcf/feature-details/types-supported-by-the-data-contract-serializer.md b/docs/framework/wcf/feature-details/types-supported-by-the-data-contract-serializer.md index e44dcfb12ae50..3d5bf137c72eb 100644 --- a/docs/framework/wcf/feature-details/types-supported-by-the-data-contract-serializer.md +++ b/docs/framework/wcf/feature-details/types-supported-by-the-data-contract-serializer.md @@ -1,6 +1,6 @@ --- title: "Types Supported by the Data Contract Serializer" -description: See the complete list of types that the WCF data contract serializer supports for serialization and deserialization. +description: See the complete list of types that the WCF data contract serializer supports for serialization and deserialization. ms.date: "03/30/2017" helpviewer_keywords: - "serialization [WCF], supported types" @@ -14,7 +14,7 @@ Windows Communication Foundation (WCF) uses the attribute has been applied. New custom types that represent business objects should normally be created as data contract types. For more information, see [Using Data Contracts](using-data-contracts.md) and [Serializable Types](serializable-types.md). -- Collection types. These are types that represent lists of data. These can be regular arrays of types, or collection types, such as and . The attribute can be used to customize the serialization of these types, but is not required. For more information, see [Collection Types in Data Contracts](collection-types-in-data-contracts.md). +- Collection types. These are types that represent lists of data. These can be regular arrays of types, or collection types, such as and . The attribute can be used to customize the serialization of these types, but is not required. For more information, see [Collection Types in Data Contracts](collection-types-in-data-contracts.md). - Enumeration types. Enumerations, including flag enumerations, are serializable. Optionally, enumeration types can be marked with the attribute, in which case every member that participates in serialization must be marked with the attribute. Members that are not marked are not serialized. For more information, see [Enumeration Types in Data Contracts](enumeration-types-in-data-contracts.md). @@ -33,7 +33,7 @@ Windows Communication Foundation (WCF) uses the in partially-trusted code using the requires the and permissions. +- To serialize or deserialize a type that implements in partially-trusted code using the requires the and permissions. - When running WCF code in [Partial Trust](partial-trust.md) mode, the serialization and deserialization of `readonly` fields (both `public` and `private`) is not supported. This is because the generated IL is unverifiable and therefore requires elevated permissions. @@ -47,7 +47,7 @@ The following is a list of limitations when using certain types in partial trust - Known types must be specified in code or machine-level configuration (`Machine.config`). Known types cannot be specified in application-level configuration for security reasons. -- Types that implement throw an exception in a partially-trusted environment because the method requires the security permission `[SecurityPermission(SecurityAction.LinkDemand, Flags=SecurityPermissionFlag.SerializationFormatter)]`. +- Types that implement throw an exception in a partially-trusted environment because the method requires the security permission `[SecurityPermission(SecurityAction.LinkDemand, Flags=SecurityPermissionFlag.SerializationFormatter)]`. ## Additional Notes on Serialization @@ -63,7 +63,7 @@ The following rules also apply to types supported by the Data Contract Serialize - The does not support the programming model used by the and ASP.NET Web services. In particular, it does not support attributes like and . To enable support for this programming model, WCF must be switched to use the instead of the . -- The type is treated in a special way. It is a singleton type, and upon deserialization the deserializer respects the singleton constraint and points all `DBNull` references to the singleton instance. Because `DBNull` is a serializable type, it demands permission. +- The type is treated in a special way. It is a singleton type, and upon deserialization the deserializer respects the singleton constraint and points all `DBNull` references to the singleton instance. Because `DBNull` is a serializable type, it demands permission. ## See also diff --git a/docs/framework/wcf/feature-details/understanding-generated-client-code.md b/docs/framework/wcf/feature-details/understanding-generated-client-code.md index fb69ae0b8244b..f25c530947335 100644 --- a/docs/framework/wcf/feature-details/understanding-generated-client-code.md +++ b/docs/framework/wcf/feature-details/understanding-generated-client-code.md @@ -2,86 +2,86 @@ description: "Learn more about: Understanding Generated Client Code" title: "Understanding Generated Client Code" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: c3f6e4b0-1131-4c94-aa39-a197c5c2f2ca --- # Understanding Generated Client Code -The [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) generates client code and a client application configuration file for use in building client applications. This topic provides a tour of generated code examples for standard service contract scenarios. For more information about building a client application using the generated code, see [WCF Client Overview](../wcf-client-overview.md). - -## Overview - - If you use Visual Studio to generate Windows Communication Foundation (WCF) client types for your project, you typically do not need to examine the generated client code. If you are not using a development environment that performs the same services for you, you can use a tool such as Svcutil.exe to generate client code and then use that code to develop your client application. - - Because Svcutil.exe has a number of options that modify the generated type information, this topic does not discuss all scenarios. However, the following standard tasks involve locating generated code: - -- Identifying service contract interfaces. - -- Identifying the WCF client class. - -- Identifying data types. - -- Identifying callback contracts for duplex services. - -- Identifying the helper service contract channel interface. - -### Finding Service Contract Interfaces - - To locate the interfaces that model service contracts, search for interfaces that are marked with the attribute. Often this attribute can be difficult to locate with a quick read due to the presence of other attributes and the explicit properties set on the attribute itself. Remember that the service contract interface and the client contract interface are two different types. The following code example shows the original service contract. - - [!code-csharp[C_GeneratedCodeFiles#22](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#22)] - - The following code example shows the same service contract as generated by Svcutil.exe. - - [!code-csharp[C_GeneratedCodeFiles#12](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#12)] - - You can use the generated service contract interface along with the class to create a WCF channel object with which to invoke service operations. For more information, see [How to: Use the ChannelFactory](how-to-use-the-channelfactory.md). - -### Finding WCF Client Classes - - To locate the WCF client class that implements the service contract you want to use, search for an extension of , where the type parameter is the service contract interface that you previously located and that extends that interface. The following code example shows the class of type `ISampleService`. - - [!code-csharp[C_GeneratedCodeFiles#14](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#14)] - - You can use this WCF client class by creating a new instance of it and calling the methods it implements. Those methods invoke the service operation with which it is designed and configured to interact. For more information, see [WCF Client Overview](../wcf-client-overview.md). - +The [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) generates client code and a client application configuration file for use in building client applications. This topic provides a tour of generated code examples for standard service contract scenarios. For more information about building a client application using the generated code, see [WCF Client Overview](../wcf-client-overview.md). + +## Overview + + If you use Visual Studio to generate Windows Communication Foundation (WCF) client types for your project, you typically do not need to examine the generated client code. If you are not using a development environment that performs the same services for you, you can use a tool such as Svcutil.exe to generate client code and then use that code to develop your client application. + + Because Svcutil.exe has a number of options that modify the generated type information, this topic does not discuss all scenarios. However, the following standard tasks involve locating generated code: + +- Identifying service contract interfaces. + +- Identifying the WCF client class. + +- Identifying data types. + +- Identifying callback contracts for duplex services. + +- Identifying the helper service contract channel interface. + +### Finding Service Contract Interfaces + + To locate the interfaces that model service contracts, search for interfaces that are marked with the attribute. Often this attribute can be difficult to locate with a quick read due to the presence of other attributes and the explicit properties set on the attribute itself. Remember that the service contract interface and the client contract interface are two different types. The following code example shows the original service contract. + + [!code-csharp[C_GeneratedCodeFiles#22](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#22)] + + The following code example shows the same service contract as generated by Svcutil.exe. + + [!code-csharp[C_GeneratedCodeFiles#12](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#12)] + + You can use the generated service contract interface along with the class to create a WCF channel object with which to invoke service operations. For more information, see [How to: Use the ChannelFactory](how-to-use-the-channelfactory.md). + +### Finding WCF Client Classes + + To locate the WCF client class that implements the service contract you want to use, search for an extension of , where the type parameter is the service contract interface that you previously located and that extends that interface. The following code example shows the class of type `ISampleService`. + + [!code-csharp[C_GeneratedCodeFiles#14](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#14)] + + You can use this WCF client class by creating a new instance of it and calling the methods it implements. Those methods invoke the service operation with which it is designed and configured to interact. For more information, see [WCF Client Overview](../wcf-client-overview.md). + > [!NOTE] -> When SvcUtil.exe generates a WCF client class, it adds a to the client class that prevents debuggers from stepping through the WCF client class. - -### Finding Data Types - - To locate data types in the generated code, the most basic mechanism is to identify the type name specified in a contract and search the code for that type declaration. For example, the following contract specifies that the `SampleMethod` can return a SOAP fault of type `microsoft.wcf.documentation.SampleFault`. - - [!code-csharp[C_GeneratedCodeFiles#11](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#11)] - - Searching for `SampleFault` locates the following type declaration. - - [!code-csharp[C_GeneratedCodeFiles#30](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#30)] - - In this case the data type is the detail type thrown by a specific exception on the client, a where the detail type parameter is `microsoft.wcf.documentation.SampleFault`. For more information about data types, see [Specifying Data Transfer in Service Contracts](specifying-data-transfer-in-service-contracts.md). For more information about handling exceptions in clients, see [Sending and Receiving Faults](../sending-and-receiving-faults.md). - -### Finding Callback Contracts for Duplex Services - - If you locate a service contract for which the contract interface specifies a value for the property, then that contract specifies a duplex contract. Duplex contracts require the client application to create a callback class that implements the callback contract and pass an instance of that class to the or used to communicate with the service. For more information about duplex clients, see [How to: Access Services with a Duplex Contract](how-to-access-services-with-a-duplex-contract.md). - - The following contract specifies a callback contract of type `SampleDuplexHelloCallback`. - +> When SvcUtil.exe generates a WCF client class, it adds a to the client class that prevents debuggers from stepping through the WCF client class. + +### Finding Data Types + + To locate data types in the generated code, the most basic mechanism is to identify the type name specified in a contract and search the code for that type declaration. For example, the following contract specifies that the `SampleMethod` can return a SOAP fault of type `microsoft.wcf.documentation.SampleFault`. + + [!code-csharp[C_GeneratedCodeFiles#11](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#11)] + + Searching for `SampleFault` locates the following type declaration. + + [!code-csharp[C_GeneratedCodeFiles#30](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#30)] + + In this case the data type is the detail type thrown by a specific exception on the client, a where the detail type parameter is `microsoft.wcf.documentation.SampleFault`. For more information about data types, see [Specifying Data Transfer in Service Contracts](specifying-data-transfer-in-service-contracts.md). For more information about handling exceptions in clients, see [Sending and Receiving Faults](../sending-and-receiving-faults.md). + +### Finding Callback Contracts for Duplex Services + + If you locate a service contract for which the contract interface specifies a value for the property, then that contract specifies a duplex contract. Duplex contracts require the client application to create a callback class that implements the callback contract and pass an instance of that class to the or used to communicate with the service. For more information about duplex clients, see [How to: Access Services with a Duplex Contract](how-to-access-services-with-a-duplex-contract.md). + + The following contract specifies a callback contract of type `SampleDuplexHelloCallback`. + [!code-csharp[C_GeneratedCodeFiles#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/duplexproxycode.cs#2)] - [!code-vb[C_GeneratedCodeFiles#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_generatedcodefiles/vb/duplexproxycode.vb#2)] - - Searching for that callback contract locates the following interface that the client application must implement. - + [!code-vb[C_GeneratedCodeFiles#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_generatedcodefiles/vb/duplexproxycode.vb#2)] + + Searching for that callback contract locates the following interface that the client application must implement. + [!code-csharp[C_GeneratedCodeFiles#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/duplexproxycode.cs#4)] - [!code-vb[C_GeneratedCodeFiles#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_generatedcodefiles/vb/duplexproxycode.vb#4)] - -### Finding Service Contract Channel Interfaces - - When using the class with a service contract interface, you must cast to the interface to explicitly open, close, or abort the channel. To make it easier to work with, the Svcutil.exe tool also generates a helper interface that implements both the service contract interface and to enable you to interact with the client channel infrastructure without having to cast. The following code shows the definition of a helper client channel that implements the preceding service contract. - - [!code-csharp[C_GeneratedCodeFiles#13](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#13)] - + [!code-vb[C_GeneratedCodeFiles#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_generatedcodefiles/vb/duplexproxycode.vb#4)] + +### Finding Service Contract Channel Interfaces + + When using the class with a service contract interface, you must cast to the interface to explicitly open, close, or abort the channel. To make it easier to work with, the Svcutil.exe tool also generates a helper interface that implements both the service contract interface and to enable you to interact with the client channel infrastructure without having to cast. The following code shows the definition of a helper client channel that implements the preceding service contract. + + [!code-csharp[C_GeneratedCodeFiles#13](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#13)] + ## See also - [WCF Client Overview](../wcf-client-overview.md) diff --git a/docs/framework/wcf/feature-details/unsupported-scenarios.md b/docs/framework/wcf/feature-details/unsupported-scenarios.md index 09ba0c980cfb4..94273fa4b9297 100644 --- a/docs/framework/wcf/feature-details/unsupported-scenarios.md +++ b/docs/framework/wcf/feature-details/unsupported-scenarios.md @@ -22,7 +22,7 @@ WCF does not support impersonation and an property of the is set to . +- The property of the is set to . - A state-based security context token (SCT) is created (by default, creation is disabled). @@ -31,18 +31,18 @@ WCF does not support impersonation and an `, then adding a `` element, and setting the `authenticationMode` attribute to SecureConversation and the `requireSecurityContextCancellation` attribute to `true`. > [!NOTE] -> The preceding requirements are specific. For example, the creates a binding element that results in a Windows identity, but does not establish an SCT. Therefore, you can use it with the `Required` option on Windows XP. +> The preceding requirements are specific. For example, the creates a binding element that results in a Windows identity, but does not establish an SCT. Therefore, you can use it with the `Required` option on Windows XP. ### Possible ASP.NET conflict -WCF and ASP.NET can both enable or disable impersonation. When ASP.NET hosts a WCF application, a conflict may exist between the WCF and ASP.NET configuration settings. In case of conflict, the WCF setting takes precedence, unless the property is set to , in which case the ASP.NET impersonation setting takes precedence. +WCF and ASP.NET can both enable or disable impersonation. When ASP.NET hosts a WCF application, a conflict may exist between the WCF and ASP.NET configuration settings. In case of conflict, the WCF setting takes precedence, unless the property is set to , in which case the ASP.NET impersonation setting takes precedence. ### Assembly loads may fail under impersonation If the impersonated context does not have access rights to load an assembly and if it is the first time the common language runtime (CLR) is attempting to load the assembly for that AppDomain, the caches the failure. Subsequent attempts to load that assembly (or assemblies) fail, even after reverting the impersonation, and even if the reverted context has access rights to load the assembly. This is because the CLR does not reattempt the load after the user context is changed. You must restart the application domain to recover from the failure. > [!NOTE] -> The default value for the property of the class is . In most cases, an identification-level impersonation context has no rights to load any additional assemblies. This is the default value, so this is a very common condition to be aware of. Identification-level impersonation also occurs when the impersonating process does not have the `SeImpersonate` privilege. For more information, see [Delegation and Impersonation](delegation-and-impersonation-with-wcf.md). +> The default value for the property of the class is . In most cases, an identification-level impersonation context has no rights to load any additional assemblies. This is the default value, so this is a very common condition to be aware of. Identification-level impersonation also occurs when the impersonating process does not have the `SeImpersonate` privilege. For more information, see [Delegation and Impersonation](delegation-and-impersonation-with-wcf.md). ### Delegation requires credential negotiation diff --git a/docs/framework/wcf/feature-details/uritemplate-and-uritemplatetable.md b/docs/framework/wcf/feature-details/uritemplate-and-uritemplatetable.md index 2a5a147b72e70..0450618d790f4 100644 --- a/docs/framework/wcf/feature-details/uritemplate-and-uritemplatetable.md +++ b/docs/framework/wcf/feature-details/uritemplate-and-uritemplatetable.md @@ -6,165 +6,165 @@ ms.assetid: 5cbbe03f-4a9e-4d44-9e02-c5773239cf52 --- # UriTemplate and UriTemplateTable -Web developers require the ability to describe the shape and layout of the URIs that their services respond to. Windows Communication Foundation (WCF) added two new classes to give developers control over their URIs. and form the basis of the URI-based dispatch engine in WCF. These classes can also be used on their own, allowing developers to take advantage of templates and the URI mapping mechanism without implementing a WCF service. - -## Templates - - A template is a way to describe a set of relative URIs. The set of URI templates in the following table shows how a system that retrieves various types of weather information might be defined. - -|Data|Template| -|----------|--------------| -|National Forecast|weather/national| -|State Forecast|weather/{state}| -|City Forecast|weather/{state}/{city}| -|Activity Forecast|weather/{state}/{city}/{activity}| - - This table describes a set of structurally similar URIs. Each entry is a URI template. The segments in curly braces describe variables. The segments not in curly braces describe literal strings. The WCF template classes allow a developer to take an incoming URI, for example, "/weather/wa/seattle/cycling", and match it to a template that describes it, "/weather/{state}/{city}/{activity}". - -## UriTemplate - - is a class that encapsulates a URI template. The constructor takes a string parameter that defines the template. This string contains the template in the format described in the next section. The class provides methods that allow you match an incoming URI to a template, generate a URI from a template, retrieve a collection of variable names used in the template, determine whether two templates are equivalent, and return the template's string. - - takes a base address and a candidate URI and attempts to match the URI to the template. If the match is successful, a instance is returned. The object contains a base URI, the candidate URI, a name/value collection of the query parameters, an array of the relative path segments, a name/value collection of variables that were matched, the instance used to perform the match, a string that contains any unmatched portion of the candidate URI (used when the template has a wildcard), and an object that is associated with the template. - +Web developers require the ability to describe the shape and layout of the URIs that their services respond to. Windows Communication Foundation (WCF) added two new classes to give developers control over their URIs. and form the basis of the URI-based dispatch engine in WCF. These classes can also be used on their own, allowing developers to take advantage of templates and the URI mapping mechanism without implementing a WCF service. + +## Templates + + A template is a way to describe a set of relative URIs. The set of URI templates in the following table shows how a system that retrieves various types of weather information might be defined. + +|Data|Template| +|----------|--------------| +|National Forecast|weather/national| +|State Forecast|weather/{state}| +|City Forecast|weather/{state}/{city}| +|Activity Forecast|weather/{state}/{city}/{activity}| + + This table describes a set of structurally similar URIs. Each entry is a URI template. The segments in curly braces describe variables. The segments not in curly braces describe literal strings. The WCF template classes allow a developer to take an incoming URI, for example, "/weather/wa/seattle/cycling", and match it to a template that describes it, "/weather/{state}/{city}/{activity}". + +## UriTemplate + + is a class that encapsulates a URI template. The constructor takes a string parameter that defines the template. This string contains the template in the format described in the next section. The class provides methods that allow you match an incoming URI to a template, generate a URI from a template, retrieve a collection of variable names used in the template, determine whether two templates are equivalent, and return the template's string. + + takes a base address and a candidate URI and attempts to match the URI to the template. If the match is successful, a instance is returned. The object contains a base URI, the candidate URI, a name/value collection of the query parameters, an array of the relative path segments, a name/value collection of variables that were matched, the instance used to perform the match, a string that contains any unmatched portion of the candidate URI (used when the template has a wildcard), and an object that is associated with the template. + > [!NOTE] -> The class ignores the scheme and port number when matching a candidate URI to a template. - - There are two methods that allow you to generate a URI from a template, and . takes a base address and a name/value collection of parameters. These parameters are substituted for variables when the template is bound. takes the name/value pairs and substitutes them left to right. - - returns the template string. - - The property contains a collection of the names of the variables used within path segments in the template string. - - takes a as a parameter and returns a Boolean value that specifies whether the two templates are equivalent. For more information, see the Template Equivalence section later in this topic. - - is designed to work with any URI scheme that conforms to the HTTP URI grammar. The following are examples of supported URI schemes. - -- `http://` - -- `https://` - -- `net.tcp://` - -- `net.pipe://` - -- `sb://` - - Schemes like file:// and urn:// do not conform to the HTTP URI grammar and cause unpredictable results when used with URI templates. - -### Template String Syntax - - A template has three parts: a path, an optional query, and an optional fragment. For an example, see the following template: - -`"/weather/{state}/{city}?forecast={length)#frag1` - - The path consists of "/weather/{state}/{city}", the query consists of "?forecast={length}, and the fragment consists of "#frag1". - - Leading and trailing slashes are optional in the path expression. Both the query and fragment expressions can be omitted entirely. A path consists of a series of segments delimited by '/', each segment can have a literal value, a variable name (written in {curly braces}), or a wildcard (written as '\*'). In the previous template the "\weather\ segment is a literal value while "{state}" and "{city}" are variables. Variables take their name from the contents of their curly braces and they can later be replaced with a concrete value to create a *closed URI*. The wildcard is optional, but can only appear at the end of the URI, where it logically matches "the rest of the path". - - The query expression, if present, specifies a series of unordered name/value pairs delimited by '&'. Elements of the query expression can either be literal pairs (x=2) or a variable pair (x={var}). Only the right side of the query can have a variable expression. ({someName} = {someValue} is not allowed. Unpaired values (?x) are not permitted. There is no difference between an empty query expression and a query expression consisting of just a single '?' (both mean "any query"). - - The fragment expression can consist of a literal value, no variables are allowed. - - All template variable names within a template string must be unique. Template variable names are case-insensitive. - - Examples of valid template strings: - -- "" - -- "/shoe" - -- "/shoe/\*" - -- "{shoe}/boat" - -- "{shoe}/{boat}/bed/{quilt}" - -- "shoe/{boat}" - -- "shoe/{boat}/\*" - -- "shoe/boat?x=2" - -- "shoe/{boat}?x={bed}" - -- "shoe/{boat}?x={bed}&y=band" - -- "?x={shoe}" - -- "shoe?x=3&y={var} - - Examples of invalid template strings: - -- "{shoe}/{SHOE}/x=2" – Duplicate variable names. - -- "{shoe}/boat/?bed={shoe}" – Duplicate variable names. - -- "?x=2&x=3" – Name/value pairs within a query string must be unique, even if they are literals. - -- "?x=2&" – Query string is malformed. - -- "?2&x={shoe}" – Query string must be name/value pairs. - -- "?y=2&&X=3" – Query string must be name value pairs, names cannot start with '&'. - -### Compound Path Segments - - Compound path segments allow a single URI path segment to contain multiple variables as well as variables combined with literals. The following are examples of valid compound path segments. - -- /filename.{ext}/ - -- /{filename}.jpg/ - -- /{filename}.{ext}/ - -- /{a}.{b}someLiteral{c}({d})/ - - The following are examples of invalid path segments. - -- /{} - Variables must be named. - -- /{shoe}{boat} - Variables must be separated by a literal. - -### Matching and Compound Path Segments - - Compound path segments allow you to define a UriTemplate that has multiple variables within a single path segment. For example, in the following template string: "Addresses/{state}.{city}" two variables (state and city) are defined within the same segment. This template would match a URL such as `http://example.com/Washington.Redmond` but it will also match an URL like `http://example.com/Washington.Redmond.Microsoft`. In the latter case, the state variable will contain "Washington" and the city variable will contain "Redmond.Microsoft". In this case any text (except ‘/’) will match the {city} variable. If you want a template that will not match the "extra" text, place the variable in a separate template segment, for example: "Addresses/{state}/{city}. - -### Named Wildcard Segments - - A named wildcard segment is any path variable segment whose variable name begins with the wildcard character ‘\*’. The following template string contains a named wildcard segment named "shoe". - -`"literal/{*shoe}"` - - Wildcard segments must follow the following rules: - -- There can be at most one named wildcard segment for each template string. - -- A named wildcard segment must appear at the right-most segment in the path. - -- A named wildcard segment cannot coexist with an anonymous wildcard segment within the same template string. - -- The name of a named wildcard segment must be unique. - -- Named wildcard segments cannot have default values. - -- Named wildcard segments cannot end with "/". - -### Default Variable Values - - Default variable values allow you to specify default values for variables within a template. Default variables can be specified with the curly braces that declare the variable or as a collection passed to the UriTemplate constructor. The following template shows two ways to specify a with variables with default values. - +> The class ignores the scheme and port number when matching a candidate URI to a template. + + There are two methods that allow you to generate a URI from a template, and . takes a base address and a name/value collection of parameters. These parameters are substituted for variables when the template is bound. takes the name/value pairs and substitutes them left to right. + + returns the template string. + + The property contains a collection of the names of the variables used within path segments in the template string. + + takes a as a parameter and returns a Boolean value that specifies whether the two templates are equivalent. For more information, see the Template Equivalence section later in this topic. + + is designed to work with any URI scheme that conforms to the HTTP URI grammar. The following are examples of supported URI schemes. + +- `http://` + +- `https://` + +- `net.tcp://` + +- `net.pipe://` + +- `sb://` + + Schemes like file:// and urn:// do not conform to the HTTP URI grammar and cause unpredictable results when used with URI templates. + +### Template String Syntax + + A template has three parts: a path, an optional query, and an optional fragment. For an example, see the following template: + +`"/weather/{state}/{city}?forecast={length)#frag1` + + The path consists of "/weather/{state}/{city}", the query consists of "?forecast={length}, and the fragment consists of "#frag1". + + Leading and trailing slashes are optional in the path expression. Both the query and fragment expressions can be omitted entirely. A path consists of a series of segments delimited by '/', each segment can have a literal value, a variable name (written in {curly braces}), or a wildcard (written as '\*'). In the previous template the "\weather\ segment is a literal value while "{state}" and "{city}" are variables. Variables take their name from the contents of their curly braces and they can later be replaced with a concrete value to create a *closed URI*. The wildcard is optional, but can only appear at the end of the URI, where it logically matches "the rest of the path". + + The query expression, if present, specifies a series of unordered name/value pairs delimited by '&'. Elements of the query expression can either be literal pairs (x=2) or a variable pair (x={var}). Only the right side of the query can have a variable expression. ({someName} = {someValue} is not allowed. Unpaired values (?x) are not permitted. There is no difference between an empty query expression and a query expression consisting of just a single '?' (both mean "any query"). + + The fragment expression can consist of a literal value, no variables are allowed. + + All template variable names within a template string must be unique. Template variable names are case-insensitive. + + Examples of valid template strings: + +- "" + +- "/shoe" + +- "/shoe/\*" + +- "{shoe}/boat" + +- "{shoe}/{boat}/bed/{quilt}" + +- "shoe/{boat}" + +- "shoe/{boat}/\*" + +- "shoe/boat?x=2" + +- "shoe/{boat}?x={bed}" + +- "shoe/{boat}?x={bed}&y=band" + +- "?x={shoe}" + +- "shoe?x=3&y={var} + + Examples of invalid template strings: + +- "{shoe}/{SHOE}/x=2" – Duplicate variable names. + +- "{shoe}/boat/?bed={shoe}" – Duplicate variable names. + +- "?x=2&x=3" – Name/value pairs within a query string must be unique, even if they are literals. + +- "?x=2&" – Query string is malformed. + +- "?2&x={shoe}" – Query string must be name/value pairs. + +- "?y=2&&X=3" – Query string must be name value pairs, names cannot start with '&'. + +### Compound Path Segments + + Compound path segments allow a single URI path segment to contain multiple variables as well as variables combined with literals. The following are examples of valid compound path segments. + +- /filename.{ext}/ + +- /{filename}.jpg/ + +- /{filename}.{ext}/ + +- /{a}.{b}someLiteral{c}({d})/ + + The following are examples of invalid path segments. + +- /{} - Variables must be named. + +- /{shoe}{boat} - Variables must be separated by a literal. + +### Matching and Compound Path Segments + + Compound path segments allow you to define a UriTemplate that has multiple variables within a single path segment. For example, in the following template string: "Addresses/{state}.{city}" two variables (state and city) are defined within the same segment. This template would match a URL such as `http://example.com/Washington.Redmond` but it will also match an URL like `http://example.com/Washington.Redmond.Microsoft`. In the latter case, the state variable will contain "Washington" and the city variable will contain "Redmond.Microsoft". In this case any text (except ‘/’) will match the {city} variable. If you want a template that will not match the "extra" text, place the variable in a separate template segment, for example: "Addresses/{state}/{city}. + +### Named Wildcard Segments + + A named wildcard segment is any path variable segment whose variable name begins with the wildcard character ‘\*’. The following template string contains a named wildcard segment named "shoe". + +`"literal/{*shoe}"` + + Wildcard segments must follow the following rules: + +- There can be at most one named wildcard segment for each template string. + +- A named wildcard segment must appear at the right-most segment in the path. + +- A named wildcard segment cannot coexist with an anonymous wildcard segment within the same template string. + +- The name of a named wildcard segment must be unique. + +- Named wildcard segments cannot have default values. + +- Named wildcard segments cannot end with "/". + +### Default Variable Values + + Default variable values allow you to specify default values for variables within a template. Default variables can be specified with the curly braces that declare the variable or as a collection passed to the UriTemplate constructor. The following template shows two ways to specify a with variables with default values. + ```csharp -UriTemplate t = new UriTemplate("/test/{a=1}/{b=5}"); -``` - - This template declares a variable named `a` with a default value of `1` and a variable named `b` with a default value of `5`. - +UriTemplate t = new UriTemplate("/test/{a=1}/{b=5}"); +``` + + This template declares a variable named `a` with a default value of `1` and a variable named `b` with a default value of `5`. + > [!NOTE] -> Only path segment variables are allowed to have default values. Query string variables, compound segment variables, and named wildcard variables are not permitted to have default values. - - The following code shows how default variable values are handled when matching a candidate URI. - +> Only path segment variables are allowed to have default values. Query string variables, compound segment variables, and named wildcard variables are not permitted to have default values. + + The following code shows how default variable values are handled when matching a candidate URI. + ```csharp Uri baseAddress = new Uri("http://localhost:8000/"); @@ -182,155 +182,155 @@ foreach (string key in m1.BoundVariables.AllKeys) { Console.WriteLine($"\t{key}={m1.BoundVariables[key]}"); } -// The output of the above code is +// The output of the above code is // Template: /{state=WA}/{city=Redmond}/ // Candidate URI: http://localhost:8000/OR // BoundVariables: // STATE=OR // CITY=Redmond -``` - +``` + > [!NOTE] -> A URI such as `http://localhost:8000///` does not match the template listed in the preceding code, however a URI such as `http://localhost:8000/` does. - - The following code shows how default variable values are handled when creating a URI with a template. - +> A URI such as `http://localhost:8000///` does not match the template listed in the preceding code, however a URI such as `http://localhost:8000/` does. + + The following code shows how default variable values are handled when creating a URI with a template. + ```csharp -Uri baseAddress = new Uri("http://localhost:8000/"); -Dictionary defVals = new Dictionary {{"a","1"}, {"b", "5"}}; -UriTemplate t = new UriTemplate("/test/{a}/{b}", defVals); -NameValueCollection vals = new NameValueCollection(); -vals.Add("a", "10"); - -Uri boundUri = t.BindByName(baseAddress, vals); -Console.WriteLine("BaseAddress: {0}", baseAddress); -Console.WriteLine("Template: {0}", t.ToString()); - -Console.WriteLine("Values: "); -foreach (string key in vals.AllKeys) -{ - Console.WriteLine("\tKey = {0}, Value = {1}", key, vals[key]); -} -Console.WriteLine("Bound URI: {0}", boundUri); - -// The output of the preceding code is -// BaseAddress: http://localhost:8000/ -// Template: /test/{a}/{b} -// Values: -// Key = a, Value = 10 -// Bound URI: http://localhost:8000/test/10/5 -``` - -When a variable is given a default value of `null` there are some additional constraints. A variable can have a default value of `null` if the variable is contained within the right most segment of the template string or if all segments to the right of the segment have default values of `null`. The following are valid template strings with default values of `null`: - +Uri baseAddress = new Uri("http://localhost:8000/"); +Dictionary defVals = new Dictionary {{"a","1"}, {"b", "5"}}; +UriTemplate t = new UriTemplate("/test/{a}/{b}", defVals); +NameValueCollection vals = new NameValueCollection(); +vals.Add("a", "10"); + +Uri boundUri = t.BindByName(baseAddress, vals); +Console.WriteLine("BaseAddress: {0}", baseAddress); +Console.WriteLine("Template: {0}", t.ToString()); + +Console.WriteLine("Values: "); +foreach (string key in vals.AllKeys) +{ + Console.WriteLine("\tKey = {0}, Value = {1}", key, vals[key]); +} +Console.WriteLine("Bound URI: {0}", boundUri); + +// The output of the preceding code is +// BaseAddress: http://localhost:8000/ +// Template: /test/{a}/{b} +// Values: +// Key = a, Value = 10 +// Bound URI: http://localhost:8000/test/10/5 +``` + +When a variable is given a default value of `null` there are some additional constraints. A variable can have a default value of `null` if the variable is contained within the right most segment of the template string or if all segments to the right of the segment have default values of `null`. The following are valid template strings with default values of `null`: + - `UriTemplate t = new UriTemplate("shoe/{boat=null}");` - `UriTemplate t = new UriTemplate("{shoe=null}/{boat=null}");` - + - `UriTemplate t = new UriTemplate("{shoe=1}/{boat=null}");` - The following are invalid template strings with default values of `null`: - + The following are invalid template strings with default values of `null`: + - `UriTemplate t = new UriTemplate("{shoe=null}/boat"); // null default must be in the right most path segment` - + - `UriTemplate t = new UriTemplate("{shoe=null}/{boat=x}/{bed=null}"); // shoe cannot have a null default because boat does not have a default null value` -### Default Values and Matching - - When matching a candidate URI with a template that has default values, the default values are placed in the collection if values are not specified in the candidate URI. - -### Template Equivalence - - Two templates are said to be *structurally equivalent* when all of the templates' literals match and they have variables in the same segments. For example the following templates are structurally equivalent: - -- /a/{var1}/b b/{var2}?x=1&y=2 - -- a/{x}/b%20b/{var1}?y=2&x=1 - -- a/{y}/B%20B/{z}/?y=2&x=1 - - A few things to notice: - -- If a template contains leading slashes, only the first one is ignored. - -- When comparing template strings for structural equivalence, case is ignored for variable names and path segments, query strings are case sensitive. - -- Query strings are unordered. - -## UriTemplateTable - - The class represents an associative table of objects bound to an object of the developer's choosing. A must contain at least one prior to calling . The contents of a can be changed until is called. Validation is performed when is called. The type of validation performed depends upon the value of the `allowMultiple` parameter to . - - When is called passing in `false`, the checks to make sure there are no templates in the table. If it finds any structurally equivalent templates, it throws an exception. This is used in conjunction with when you want to ensure only one template matches an incoming URI. - - When is called passing in `true`, allows multiple, structurally-equivalent templates to be contained within a . - - If a set of objects added to a contain query strings they must not be ambiguous. Identical query strings are allowed. - +### Default Values and Matching + + When matching a candidate URI with a template that has default values, the default values are placed in the collection if values are not specified in the candidate URI. + +### Template Equivalence + + Two templates are said to be *structurally equivalent* when all of the templates' literals match and they have variables in the same segments. For example the following templates are structurally equivalent: + +- /a/{var1}/b b/{var2}?x=1&y=2 + +- a/{x}/b%20b/{var1}?y=2&x=1 + +- a/{y}/B%20B/{z}/?y=2&x=1 + + A few things to notice: + +- If a template contains leading slashes, only the first one is ignored. + +- When comparing template strings for structural equivalence, case is ignored for variable names and path segments, query strings are case sensitive. + +- Query strings are unordered. + +## UriTemplateTable + + The class represents an associative table of objects bound to an object of the developer's choosing. A must contain at least one prior to calling . The contents of a can be changed until is called. Validation is performed when is called. The type of validation performed depends upon the value of the `allowMultiple` parameter to . + + When is called passing in `false`, the checks to make sure there are no templates in the table. If it finds any structurally equivalent templates, it throws an exception. This is used in conjunction with when you want to ensure only one template matches an incoming URI. + + When is called passing in `true`, allows multiple, structurally-equivalent templates to be contained within a . + + If a set of objects added to a contain query strings they must not be ambiguous. Identical query strings are allowed. + > [!NOTE] -> While the allows base addresses that use schemes other than HTTP, the scheme and port number are ignored when matching candidate URIs to templates. - -### Query String Ambiguity - - Templates that share an equivalent path contain ambiguous query strings if there is a URI that matches more than one template. - - The following sets of query strings are unambiguous within themselves: - -- ?x=1 - -- ?x=2 - -- ?x=3 - -- ?x=1&y={var} - -- ?x=2&z={var} - -- ?x=3 - -- ?x=1 - -- ? - -- ? x={var} - -- ? - -- ?m=get&c=rss - -- ?m=put&c=rss - -- ?m=get&c=atom - -- ?m=put&c=atom - - The following sets of query string templates are ambiguous within themselves: - -- ?x=1 - -- ?x={var} - - "x=1" - Matches both templates. - -- ?x=1 - -- ?y=2 - - "x=1&y=2" matches both templates. This is because a query string may contain more query string variables then the template it matches. - -- ?x=1 - -- ?x=1&y={var} - - "x=1&y=3" matches both templates. - -- ?x=3&y=4 - -- ?x=3&z=5 - +> While the allows base addresses that use schemes other than HTTP, the scheme and port number are ignored when matching candidate URIs to templates. + +### Query String Ambiguity + + Templates that share an equivalent path contain ambiguous query strings if there is a URI that matches more than one template. + + The following sets of query strings are unambiguous within themselves: + +- ?x=1 + +- ?x=2 + +- ?x=3 + +- ?x=1&y={var} + +- ?x=2&z={var} + +- ?x=3 + +- ?x=1 + +- ? + +- ? x={var} + +- ? + +- ?m=get&c=rss + +- ?m=put&c=rss + +- ?m=get&c=atom + +- ?m=put&c=atom + + The following sets of query string templates are ambiguous within themselves: + +- ?x=1 + +- ?x={var} + + "x=1" - Matches both templates. + +- ?x=1 + +- ?y=2 + + "x=1&y=2" matches both templates. This is because a query string may contain more query string variables then the template it matches. + +- ?x=1 + +- ?x=1&y={var} + + "x=1&y=3" matches both templates. + +- ?x=3&y=4 + +- ?x=3&z=5 + > [!NOTE] -> The characters á and Á are considered to be different characters when they appear as part of a URI path or path segment literal (but the characters a and A are considered to be the same). The characters á and Á are considered to be the same characters when they appear as part of a {variableName} or a query string (and a and A are also considered to be the same characters). - +> The characters á and Á are considered to be different characters when they appear as part of a URI path or path segment literal (but the characters a and A are considered to be the same). The characters á and Á are considered to be the same characters when they appear as part of a {variableName} or a query string (and a and A are also considered to be the same characters). + ## See also - [WCF Web HTTP Programming Model Overview](wcf-web-http-programming-model-overview.md) diff --git a/docs/framework/wcf/feature-details/using-a-custom-binding-with-the-discovery-client-channel.md b/docs/framework/wcf/feature-details/using-a-custom-binding-with-the-discovery-client-channel.md index 5f34825507efc..18eed462bed34 100644 --- a/docs/framework/wcf/feature-details/using-a-custom-binding-with-the-discovery-client-channel.md +++ b/docs/framework/wcf/feature-details/using-a-custom-binding-with-the-discovery-client-channel.md @@ -6,42 +6,42 @@ ms.topic: how-to --- # Using a Custom Binding with the Discovery Client Channel -When using a custom binding with the , you must define a that creates instances. - -## Creating a DiscoveryEndpointProvider +When using a custom binding with the , you must define a that creates instances. + +## Creating a DiscoveryEndpointProvider + + The is responsible for creating instances on demand. To define a discovery endpoint provider, derive a class from and override the method and return a new discovery endpoint. The following example shows how to create a discovery endpoint provider. - The is responsible for creating instances on demand. To define a discovery endpoint provider, derive a class from and override the method and return a new discovery endpoint. The following example shows how to create a discovery endpoint provider. - ```csharp -// Extend DiscoveryEndpointProvider class to change the default DiscoveryEndpoint +// Extend DiscoveryEndpointProvider class to change the default DiscoveryEndpoint // to the DiscoveryClientBindingElement. The Discovery ClientChannel -// uses this endpoint to send Probe message. -public class UdpDiscoveryEndpointProvider : DiscoveryEndpointProvider -{ - public override DiscoveryEndpoint GetDiscoveryEndpoint() - { - return new UdpDiscoveryEndpoint(DiscoveryVersion.WSDiscoveryApril2005); - } -} -``` - - Once you have defined the discovery endpoint provider you can create a custom binding and add the , which references the discovery endpoint provider as shown in the following example. - +// uses this endpoint to send Probe message. +public class UdpDiscoveryEndpointProvider : DiscoveryEndpointProvider +{ + public override DiscoveryEndpoint GetDiscoveryEndpoint() + { + return new UdpDiscoveryEndpoint(DiscoveryVersion.WSDiscoveryApril2005); + } +} +``` + + Once you have defined the discovery endpoint provider you can create a custom binding and add the , which references the discovery endpoint provider as shown in the following example. + ```csharp -DiscoveryClientBindingElement discoveryBindingElement = new DiscoveryClientBindingElement(); - -// Provide the search criteria and the endpoint over which the probe is sent. -discoveryBindingElement.FindCriteria = new FindCriteria(typeof(ICalculatorService)); -discoveryBindingElement.DiscoveryEndpointProvider = new UdpDiscoveryEndpointProvider(); - -CustomBinding customBinding = new CustomBinding(new NetTcpBinding()); -// Insert DiscoveryClientBindingElement at the top of the BindingElement stack. -// An exception is thrown if this binding element is not at the top. -customBinding.Elements.Insert(0, discoveryBindingElement); -``` - +DiscoveryClientBindingElement discoveryBindingElement = new DiscoveryClientBindingElement(); + +// Provide the search criteria and the endpoint over which the probe is sent. +discoveryBindingElement.FindCriteria = new FindCriteria(typeof(ICalculatorService)); +discoveryBindingElement.DiscoveryEndpointProvider = new UdpDiscoveryEndpointProvider(); + +CustomBinding customBinding = new CustomBinding(new NetTcpBinding()); +// Insert DiscoveryClientBindingElement at the top of the BindingElement stack. +// An exception is thrown if this binding element is not at the top. +customBinding.Elements.Insert(0, discoveryBindingElement); +``` + For more information about using the discovery client channel, see [Using the Discovery Client Channel](using-the-discovery-client-channel.md). - + ## See also - [WCF Discovery Overview](wcf-discovery-overview.md) diff --git a/docs/framework/wcf/feature-details/using-a-data-contract-resolver.md b/docs/framework/wcf/feature-details/using-a-data-contract-resolver.md index ebfb522de9bbb..f4d82069de09a 100644 --- a/docs/framework/wcf/feature-details/using-a-data-contract-resolver.md +++ b/docs/framework/wcf/feature-details/using-a-data-contract-resolver.md @@ -6,84 +6,84 @@ ms.assetid: 2e68a16c-36f0-4df4-b763-32021bff2b89 --- # Using a Data Contract Resolver -A data contract resolver allows you to configure known types dynamically. Known types are required when serializing or deserializing a type not expected by a data contract. For more information about known types, see [Data Contract Known Types](data-contract-known-types.md). Known types are normally specified statically. This means you would have to know all the possible types an operation may receive while implementing the operation. There are scenarios in which this is not true and being able to specify known types dynamically is important. - -## Creating a Data Contract Resolver - - Creating a data contract resolver involves implementing two methods, and . These two methods implement callbacks that are used during serialization and deserialization, respectively. The method is invoked during serialization and takes a data contract type and maps it to an `xsi:type` name and namespace. The method is invoked during deserialization and takes an `xsi:type` name and namespace and resolves it to a data contract type. Both of these methods have a `knownTypeResolver` parameter that can be used to use the default known type resolver in your implementation. - - The following example shows how to implement a to map to and from a data contract type named `Customer` derived from a data contract type `Person`. - -```csharp -public class MyCustomerResolver : DataContractResolver -{ - public override bool TryResolveType(Type dataContractType, Type declaredType, DataContractResolver knownTypeResolver, out XmlDictionaryString typeName, out XmlDictionaryString typeNamespace) - { - if (dataContractType == typeof(Customer)) - { - XmlDictionary dictionary = new XmlDictionary(); - typeName = dictionary.Add("SomeCustomer"); - typeNamespace = dictionary.Add("http://tempuri.com"); - return true; - } - else - { - return knownTypeResolver.TryResolveType(dataContractType, declaredType, null, out typeName, out typeNamespace); - } - } - - public override Type ResolveName(string typeName, string typeNamespace, DataContractResolver knownTypeResolver) - { - if (typeName == "SomeCustomer" && typeNamespace == "http://tempuri.com") - { - return typeof(Customer); - } - else - { - return knownTypeResolver.ResolveName(typeName, typeNamespace, null); - } - } -} -``` - - Once you have defined a you can use it by passing it to the constructor as shown in the following example. - +A data contract resolver allows you to configure known types dynamically. Known types are required when serializing or deserializing a type not expected by a data contract. For more information about known types, see [Data Contract Known Types](data-contract-known-types.md). Known types are normally specified statically. This means you would have to know all the possible types an operation may receive while implementing the operation. There are scenarios in which this is not true and being able to specify known types dynamically is important. + +## Creating a Data Contract Resolver + + Creating a data contract resolver involves implementing two methods, and . These two methods implement callbacks that are used during serialization and deserialization, respectively. The method is invoked during serialization and takes a data contract type and maps it to an `xsi:type` name and namespace. The method is invoked during deserialization and takes an `xsi:type` name and namespace and resolves it to a data contract type. Both of these methods have a `knownTypeResolver` parameter that can be used to use the default known type resolver in your implementation. + + The following example shows how to implement a to map to and from a data contract type named `Customer` derived from a data contract type `Person`. + ```csharp -XmlObjectSerializer serializer = new DataContractSerializer(typeof(Customer), null, Int32.MaxValue, false, false, null, new MyCustomerResolver()); -``` - - You can specify a in a call to the or methods, as shown in the following example. - +public class MyCustomerResolver : DataContractResolver +{ + public override bool TryResolveType(Type dataContractType, Type declaredType, DataContractResolver knownTypeResolver, out XmlDictionaryString typeName, out XmlDictionaryString typeNamespace) + { + if (dataContractType == typeof(Customer)) + { + XmlDictionary dictionary = new XmlDictionary(); + typeName = dictionary.Add("SomeCustomer"); + typeNamespace = dictionary.Add("http://tempuri.com"); + return true; + } + else + { + return knownTypeResolver.TryResolveType(dataContractType, declaredType, null, out typeName, out typeNamespace); + } + } + + public override Type ResolveName(string typeName, string typeNamespace, DataContractResolver knownTypeResolver) + { + if (typeName == "SomeCustomer" && typeNamespace == "http://tempuri.com") + { + return typeof(Customer); + } + else + { + return knownTypeResolver.ResolveName(typeName, typeNamespace, null); + } + } +} +``` + + Once you have defined a you can use it by passing it to the constructor as shown in the following example. + ```csharp -MemoryStream ms = new MemoryStream(); -DataContractSerializer serializer = new DataContractSerializer(typeof(Customer)); -XmlDictionaryWriter writer = XmlDictionaryWriter.CreateDictionaryWriter(XmlWriter.Create(ms)); -serializer.WriteObject(writer, new Customer(), new MyCustomerResolver()); -writer.Flush(); -ms.Position = 0; -Console.WriteLine(((Customer)serializer.ReadObject(XmlDictionaryReader.CreateDictionaryReader(XmlReader.Create(ms)), false, new MyCustomerResolver())); -``` - - Or you can set it on the as shown in the following example. - +XmlObjectSerializer serializer = new DataContractSerializer(typeof(Customer), null, Int32.MaxValue, false, false, null, new MyCustomerResolver()); +``` + + You can specify a in a call to the or methods, as shown in the following example. + ```csharp -ServiceHost host = new ServiceHost(typeof(MyService)); - -ContractDescription cd = host.Description.Endpoints[0].Contract; -OperationDescription myOperationDescription = cd.Operations.Find("Echo"); - -DataContractSerializerOperationBehavior serializerBehavior = myOperationDescription.Behaviors.Find(); -if (serializerBehavior == null) -{ - serializerBehavior = new DataContractSerializerOperationBehavior(myOperationDescription); - myOperationDescription.Behaviors.Add(serializerBehavior); -} - -SerializerBehavior.DataContractResolver = new MyCustomerResolver(); -``` - - You can declaratively specify a data contract resolver by implementing an attribute that can be applied to a service. For more information, see the [KnownAssemblyAttribute](../samples/knownassemblyattribute.md) sample. This sample implements an attribute called "KnownAssembly" that adds a custom data contract resolver to the service’s behavior. - +MemoryStream ms = new MemoryStream(); +DataContractSerializer serializer = new DataContractSerializer(typeof(Customer)); +XmlDictionaryWriter writer = XmlDictionaryWriter.CreateDictionaryWriter(XmlWriter.Create(ms)); +serializer.WriteObject(writer, new Customer(), new MyCustomerResolver()); +writer.Flush(); +ms.Position = 0; +Console.WriteLine(((Customer)serializer.ReadObject(XmlDictionaryReader.CreateDictionaryReader(XmlReader.Create(ms)), false, new MyCustomerResolver())); +``` + + Or you can set it on the as shown in the following example. + +```csharp +ServiceHost host = new ServiceHost(typeof(MyService)); + +ContractDescription cd = host.Description.Endpoints[0].Contract; +OperationDescription myOperationDescription = cd.Operations.Find("Echo"); + +DataContractSerializerOperationBehavior serializerBehavior = myOperationDescription.Behaviors.Find(); +if (serializerBehavior == null) +{ + serializerBehavior = new DataContractSerializerOperationBehavior(myOperationDescription); + myOperationDescription.Behaviors.Add(serializerBehavior); +} + +SerializerBehavior.DataContractResolver = new MyCustomerResolver(); +``` + + You can declaratively specify a data contract resolver by implementing an attribute that can be applied to a service. For more information, see the [KnownAssemblyAttribute](../samples/knownassemblyattribute.md) sample. This sample implements an attribute called "KnownAssembly" that adds a custom data contract resolver to the service’s behavior. + ## See also - [Data Contract Known Types](data-contract-known-types.md) diff --git a/docs/framework/wcf/feature-details/using-contracts-in-workflow.md b/docs/framework/wcf/feature-details/using-contracts-in-workflow.md index 46dd7b5f57195..369dc4e430c1b 100644 --- a/docs/framework/wcf/feature-details/using-contracts-in-workflow.md +++ b/docs/framework/wcf/feature-details/using-contracts-in-workflow.md @@ -6,28 +6,28 @@ ms.assetid: 939c64e9-e7cc-4abc-b41e-27cfce1d7e50 --- # Using Contracts in Workflow -When implementing a service, you define a number of contracts that describe the service and the data that it sends and receives. The data is represented as data contracts and message contracts; both WCF and workflow services use data contract and message contract definitions as part of service descriptions. The service itself exposes metadata (in the form of WSDL) in order to describe the operations of the service. In WCF, service contracts and operation contracts define the service and the operations it supports. However, in a workflow service, these contracts are part of the business process itself; they are exposed in metadata by a process called contract inference. - -## Contract Inference - - When a workflow service is hosted using , the workflow definition is examined and a contract is generated based on the set of messaging activities found in the workflow. In particular the following activities and properties are used to generate the contract: - - Activity - -- - -- - -- - - Activity - -- - - Activity - - The end result of contract inference is a description of the service using the same data structures as WCF service and operation contracts. This information is then used to expose WSDL for the workflow service. - +When implementing a service, you define a number of contracts that describe the service and the data that it sends and receives. The data is represented as data contracts and message contracts; both WCF and workflow services use data contract and message contract definitions as part of service descriptions. The service itself exposes metadata (in the form of WSDL) in order to describe the operations of the service. In WCF, service contracts and operation contracts define the service and the operations it supports. However, in a workflow service, these contracts are part of the business process itself; they are exposed in metadata by a process called contract inference. + +## Contract Inference + + When a workflow service is hosted using , the workflow definition is examined and a contract is generated based on the set of messaging activities found in the workflow. In particular the following activities and properties are used to generate the contract: + + Activity + +- + +- + +- + + Activity + +- + + Activity + + The end result of contract inference is a description of the service using the same data structures as WCF service and operation contracts. This information is then used to expose WSDL for the workflow service. + ## See also - [Workflow Services](workflow-services.md) diff --git a/docs/framework/wcf/feature-details/using-dead-letter-queues-to-handle-message-transfer-failures.md b/docs/framework/wcf/feature-details/using-dead-letter-queues-to-handle-message-transfer-failures.md index dc62972ad2c81..111a1c1f6c113 100644 --- a/docs/framework/wcf/feature-details/using-dead-letter-queues-to-handle-message-transfer-failures.md +++ b/docs/framework/wcf/feature-details/using-dead-letter-queues-to-handle-message-transfer-failures.md @@ -2,72 +2,72 @@ description: "Learn more about: Using Dead-Letter Queues to Handle Message Transfer Failures" title: "Using Dead-Letter Queues to Handle Message Transfer Failures" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 9e891c6a-d960-45ea-904f-1a00e202d61a --- # Using Dead-Letter Queues to Handle Message Transfer Failures -Queued messages can fail delivery. These failed messages are recorded in a dead-letter queue. The failed delivery can be caused by reasons such as network failures, a deleted queue, a full queue, authentication failure, or a failure to deliver on time. - - Queued messages can remain in the queue for a long time if the receiving application does not read them from the queue in a timely fashion. This behavior may not be appropriate for time-sensitive messages. Time-sensitive messages have a Time to Live (TTL) property set in the queued binding, which indicates how long the messages can be in the queue before they must expire. Expired messages are sent to a special queue called the dead-letter queue. Messages can also be put in a dead-letter queue for other reasons, such as exceeding a queue quota or because of authentication failure. - - Generally, applications write compensation logic to read messages from the dead-letter queue and failure reasons. The compensation logic depends on the cause of the failure. For example, in the case of authentication failure, you can correct the certificate attached with the message and resend the message. If delivery failed because the target queue quota was reached, you can reattempt delivery in the hope that the quota problem was resolved. - - Most queuing systems have a system-wide dead-letter queue where all failed messages from that system are stored. Message Queuing (MSMQ) provides two system-wide dead-letter queues: a transactional system-wide dead-letter queue that stores messages that failed delivery to the transactional queue and a non-transactional system-wide dead-letter queue that stores messages that failed delivery to the non-transactional queue. If two clients are sending messages to two different services, and therefore different queues in WCF are sharing the same MSMQ service to send, then it is possible to have a mix of messages in the system dead-letter queue. This is not always optimal. In several cases (security, for example), you may not want one client to read another client's messages from a dead-letter queue. A shared dead-letter queue also requires clients to browse through the queue to find a message that they sent, which can be prohibitively expensive based on the number of messages in the dead-letter queue. Therefore, in WCF`NetMsmqBinding`, `MsmqIntegrationBinding,` and MSMQ on Windows Vista provide a custom dead-letter queue (sometimes referred to as an application-specific dead-letter queue). - - The custom dead-letter queue provides isolation between clients that share the same MSMQ service to send messages. - - On Windows Server 2003 and Windows XP, Windows Communication Foundation (WCF) provides a system-wide dead-letter queue for all queued client applications. On Windows Vista, WCF provides a dead-letter queue for each queued client application. - -## Specifying Use of the Dead-Letter Queue - - A dead-letter queue is in the queue manager of the sending application. It stores messages that have expired or that have failed transfer or delivery. - - The binding has the following dead-letter queue properties: - -- - -- - -## Reading Messages from the Dead-Letter Queue - - An application that reads messages out of a dead-letter queue is similar to a WCF service that reads from an application queue, except for the following minor differences: - -- To read messages from a system transactional dead-letter queue, the Uniform Resource Identifier (URI) must be of the form: net.msmq://localhost/system$;DeadXact. - -- To read messages from a system non-transactional dead-letter queue, the URI must be of the form: net.msmq://localhost/system$;DeadLetter. - -- To read messages from a custom dead-letter queue, the URI must be of the form:net.msmq://localhost/private/\<*custom-dlq-name*> where *custom-dlq-name* is the name of the custom dead-letter queue. - - For more information about how to address queues, see [Service Endpoints and Queue Addressing](service-endpoints-and-queue-addressing.md). - - The WCF stack on the receiver matches addresses that the service is listening on with the address on the message. If the addresses match, the message is dispatched; if not, the message is not dispatched. This can cause problems when reading from the dead-letter queue, because messages in the dead-letter queue are typically addressed to the service and not the dead-letter queue service. Therefore, the service reading from the dead-letter queue must install an address filter `ServiceBehavior` that instructs the stack to match all messages in the queue independently of the addressee. Specifically, you must add a `ServiceBehavior` with the parameter to the service reading messages from the dead-letter queue. - -## Poison Message Handling from the Dead-Letter Queue - - Poison message handling is available on dead-letter queues, with some conditions. Because you cannot create sub-queues from system queues, when reading from the system dead-letter queue, the `ReceiveErrorHandling` cannot be set to `Move`. Note that if you are reading from a custom dead-letter queue, you can have sub-queues and, therefore, `Move` is a valid disposition for the poison message. - - When `ReceiveErrorHandling` is set to `Reject`, when reading from the custom dead letter queue, the poison message is put in the system dead-letter queue. If reading from the system dead-letter queue, the message is dropped (purged). A reject from a system dead-letter queue in MSMQ drops (purges) the message. - -## Example - - The following example shows how to create a dead-letter queue and how to use it to process expired messages. The example is based on the example in [How to: Exchange Queued Messages with WCF Endpoints](how-to-exchange-queued-messages-with-wcf-endpoints.md). The following example shows how to write the client code to the order processing service that uses a dead-letter queue for each application. The example also shows how to process messages from the dead-letter queue. - - The following is code for a client that specifies a dead-letter queue for each application. - +Queued messages can fail delivery. These failed messages are recorded in a dead-letter queue. The failed delivery can be caused by reasons such as network failures, a deleted queue, a full queue, authentication failure, or a failure to deliver on time. + + Queued messages can remain in the queue for a long time if the receiving application does not read them from the queue in a timely fashion. This behavior may not be appropriate for time-sensitive messages. Time-sensitive messages have a Time to Live (TTL) property set in the queued binding, which indicates how long the messages can be in the queue before they must expire. Expired messages are sent to a special queue called the dead-letter queue. Messages can also be put in a dead-letter queue for other reasons, such as exceeding a queue quota or because of authentication failure. + + Generally, applications write compensation logic to read messages from the dead-letter queue and failure reasons. The compensation logic depends on the cause of the failure. For example, in the case of authentication failure, you can correct the certificate attached with the message and resend the message. If delivery failed because the target queue quota was reached, you can reattempt delivery in the hope that the quota problem was resolved. + + Most queuing systems have a system-wide dead-letter queue where all failed messages from that system are stored. Message Queuing (MSMQ) provides two system-wide dead-letter queues: a transactional system-wide dead-letter queue that stores messages that failed delivery to the transactional queue and a non-transactional system-wide dead-letter queue that stores messages that failed delivery to the non-transactional queue. If two clients are sending messages to two different services, and therefore different queues in WCF are sharing the same MSMQ service to send, then it is possible to have a mix of messages in the system dead-letter queue. This is not always optimal. In several cases (security, for example), you may not want one client to read another client's messages from a dead-letter queue. A shared dead-letter queue also requires clients to browse through the queue to find a message that they sent, which can be prohibitively expensive based on the number of messages in the dead-letter queue. Therefore, in WCF`NetMsmqBinding`, `MsmqIntegrationBinding,` and MSMQ on Windows Vista provide a custom dead-letter queue (sometimes referred to as an application-specific dead-letter queue). + + The custom dead-letter queue provides isolation between clients that share the same MSMQ service to send messages. + + On Windows Server 2003 and Windows XP, Windows Communication Foundation (WCF) provides a system-wide dead-letter queue for all queued client applications. On Windows Vista, WCF provides a dead-letter queue for each queued client application. + +## Specifying Use of the Dead-Letter Queue + + A dead-letter queue is in the queue manager of the sending application. It stores messages that have expired or that have failed transfer or delivery. + + The binding has the following dead-letter queue properties: + +- + +- + +## Reading Messages from the Dead-Letter Queue + + An application that reads messages out of a dead-letter queue is similar to a WCF service that reads from an application queue, except for the following minor differences: + +- To read messages from a system transactional dead-letter queue, the Uniform Resource Identifier (URI) must be of the form: net.msmq://localhost/system$;DeadXact. + +- To read messages from a system non-transactional dead-letter queue, the URI must be of the form: net.msmq://localhost/system$;DeadLetter. + +- To read messages from a custom dead-letter queue, the URI must be of the form:net.msmq://localhost/private/\<*custom-dlq-name*> where *custom-dlq-name* is the name of the custom dead-letter queue. + + For more information about how to address queues, see [Service Endpoints and Queue Addressing](service-endpoints-and-queue-addressing.md). + + The WCF stack on the receiver matches addresses that the service is listening on with the address on the message. If the addresses match, the message is dispatched; if not, the message is not dispatched. This can cause problems when reading from the dead-letter queue, because messages in the dead-letter queue are typically addressed to the service and not the dead-letter queue service. Therefore, the service reading from the dead-letter queue must install an address filter `ServiceBehavior` that instructs the stack to match all messages in the queue independently of the addressee. Specifically, you must add a `ServiceBehavior` with the parameter to the service reading messages from the dead-letter queue. + +## Poison Message Handling from the Dead-Letter Queue + + Poison message handling is available on dead-letter queues, with some conditions. Because you cannot create sub-queues from system queues, when reading from the system dead-letter queue, the `ReceiveErrorHandling` cannot be set to `Move`. Note that if you are reading from a custom dead-letter queue, you can have sub-queues and, therefore, `Move` is a valid disposition for the poison message. + + When `ReceiveErrorHandling` is set to `Reject`, when reading from the custom dead letter queue, the poison message is put in the system dead-letter queue. If reading from the system dead-letter queue, the message is dropped (purged). A reject from a system dead-letter queue in MSMQ drops (purges) the message. + +## Example + + The following example shows how to create a dead-letter queue and how to use it to process expired messages. The example is based on the example in [How to: Exchange Queued Messages with WCF Endpoints](how-to-exchange-queued-messages-with-wcf-endpoints.md). The following example shows how to write the client code to the order processing service that uses a dead-letter queue for each application. The example also shows how to process messages from the dead-letter queue. + + The following is code for a client that specifies a dead-letter queue for each application. + [!code-csharp[S_DeadLetter#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_deadletter/cs/client.cs#1)] - [!code-vb[S_DeadLetter#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_deadletter/vb/client.vb#1)] - - The following is code for the client configuration file. + [!code-vb[S_DeadLetter#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_deadletter/vb/client.vb#1)] + + The following is code for the client configuration file. + + The following is code for a service processing messages from a dead-letter queue. - The following is code for a service processing messages from a dead-letter queue. - [!code-csharp[S_DeadLetter#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/s_deadletter/cs/dlservice.cs#3)] - [!code-vb[S_DeadLetter#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_deadletter/vb/dlservice.vb#3)] - - The following is code for the dead-letter queue service configuration file. + [!code-vb[S_DeadLetter#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_deadletter/vb/dlservice.vb#3)] + + The following is code for the dead-letter queue service configuration file. ## See also diff --git a/docs/framework/wcf/feature-details/using-message-contracts.md b/docs/framework/wcf/feature-details/using-message-contracts.md index 8541134b86c31..887f6eab3c221 100644 --- a/docs/framework/wcf/feature-details/using-message-contracts.md +++ b/docs/framework/wcf/feature-details/using-message-contracts.md @@ -10,455 +10,455 @@ helpviewer_keywords: --- # Using Message Contracts -Typically when building Windows Communication Foundation (WCF) applications, developers pay close attention to the data structures and serialization issues and do not need to concern themselves with the structure of the messages in which the data is carried. For these applications, creating data contracts for the parameters or return values is straightforward. (For more information, see [Specifying Data Transfer in Service Contracts](specifying-data-transfer-in-service-contracts.md).) - - However, sometimes complete control over the structure of a SOAP message is just as important as control over its contents. This is especially true when interoperability is important or to specifically control security issues at the level of the message or message part. In these cases, you can create a *message contract* that enables you to specify the structure of the precise SOAP message required. - - This topic discusses how to use the various message contract attributes to create a specific message contract for your operation. - -## Using Message Contracts in Operations - - WCF supports operations modeled on either the *remote procedure call (RPC) style* or the *messaging style*. In an RPC-style operation, you can use any serializable type, and you have access to the features that are available to local calls, such as multiple parameters and `ref` and `out` parameters. In this style, the form of serialization chosen controls the structure of the data in the underlying messages, and the WCF runtime creates the messages to support the operation. This enables developers who are not familiar with SOAP and SOAP messages to quickly and easily create and use service applications. - - The following code example shows a service operation modeled on the RPC style. - -```csharp -[OperationContract] -public BankingTransactionResponse PostBankingTransaction(BankingTransaction bt); -``` - - Normally, a data contract is sufficient to define the schema for the messages. For instance, in the preceding example, it is sufficient for most applications if `BankingTransaction` and `BankingTransactionResponse` have data contracts to define the contents of the underlying SOAP messages. For more information about data contracts, see [Using Data Contracts](using-data-contracts.md). - - However, occasionally it is necessary to precisely control how the structure of the SOAP message transmitted over the wire. The most common scenario for this is inserting custom SOAP headers. Another common scenario is to define security properties for the message's headers and body, that is, to decide whether these elements are digitally signed and encrypted. Finally, some third-party SOAP stacks require messages be in a specific format. Messaging-style operations provide this control. - - A messaging-style operation has at most one parameter and one return value where both types are message types; that is, they serialize directly into a specified SOAP message structure. This may be any type marked with the or the type. The following code example shows an operation similar to the preceding RCP-style, but which uses the messaging style. - - For example, if `BankingTransaction` and `BankingTransactionResponse` are both types that are message contracts, then the code in the following operations is valid. - -```csharp -[OperationContract] -BankingTransactionResponse Process(BankingTransaction bt); -[OperationContract] -void Store(BankingTransaction bt); -[OperationContract] -BankingTransactionResponse GetResponse(); -``` - - However, the following code is invalid. - -```csharp -[OperationContract] -bool Validate(BankingTransaction bt); -// Invalid, the return type is not a message contract. -[OperationContract] -void Reconcile(BankingTransaction bt1, BankingTransaction bt2); -// Invalid, there is more than one parameter. -``` - - An exception is thrown for any operation that involves a message contract type and that does not follow one of the valid patterns. Of course, operations that do not involve message contract types are not subject to these restrictions. - - If a type has both a message contract and a data contract, only its message contract is considered when the type is used in an operation. - -## Defining Message Contracts - - To define a message contract for a type (that is, to define the mapping between the type and a SOAP envelope), apply the to the type. Then apply the to those members of the type you want to make into SOAP headers, and apply the to those members you want to make into parts of the SOAP body of the message. - - The following code provides an example of using a message contract. - -```csharp -[MessageContract] -public class BankingTransaction -{ - [MessageHeader] public Operation operation; - [MessageHeader] public DateTime transactionDate; - [MessageBodyMember] private Account sourceAccount; - [MessageBodyMember] private Account targetAccount; - [MessageBodyMember] public int amount; -} -``` - - When using this type as an operation parameter, the following SOAP envelope is generated: - -```xml - - - Deposit - 2012-02-16T16:10:00 - - - - 0 - - - - - -``` - - Notice that `operation` and `transactionDate` appear as SOAP headers and the SOAP body consists of a wrapper element `BankingTransaction` containing `sourceAccount`, `targetAccount`, and `amount`. - - You can apply the and to all fields, properties, and events, regardless of whether they are public, private, protected, or internal. - - The allows you to specify the WrapperName and WrapperNamespace attributes which control the name of the wrapper element in the body of the SOAP message. By default the name of the message contract type is used for the wrapper and the namespace in which the message contract is defined `http://tempuri.org/` is used as the default namespace. - +Typically when building Windows Communication Foundation (WCF) applications, developers pay close attention to the data structures and serialization issues and do not need to concern themselves with the structure of the messages in which the data is carried. For these applications, creating data contracts for the parameters or return values is straightforward. (For more information, see [Specifying Data Transfer in Service Contracts](specifying-data-transfer-in-service-contracts.md).) + + However, sometimes complete control over the structure of a SOAP message is just as important as control over its contents. This is especially true when interoperability is important or to specifically control security issues at the level of the message or message part. In these cases, you can create a *message contract* that enables you to specify the structure of the precise SOAP message required. + + This topic discusses how to use the various message contract attributes to create a specific message contract for your operation. + +## Using Message Contracts in Operations + + WCF supports operations modeled on either the *remote procedure call (RPC) style* or the *messaging style*. In an RPC-style operation, you can use any serializable type, and you have access to the features that are available to local calls, such as multiple parameters and `ref` and `out` parameters. In this style, the form of serialization chosen controls the structure of the data in the underlying messages, and the WCF runtime creates the messages to support the operation. This enables developers who are not familiar with SOAP and SOAP messages to quickly and easily create and use service applications. + + The following code example shows a service operation modeled on the RPC style. + +```csharp +[OperationContract] +public BankingTransactionResponse PostBankingTransaction(BankingTransaction bt); +``` + + Normally, a data contract is sufficient to define the schema for the messages. For instance, in the preceding example, it is sufficient for most applications if `BankingTransaction` and `BankingTransactionResponse` have data contracts to define the contents of the underlying SOAP messages. For more information about data contracts, see [Using Data Contracts](using-data-contracts.md). + + However, occasionally it is necessary to precisely control how the structure of the SOAP message transmitted over the wire. The most common scenario for this is inserting custom SOAP headers. Another common scenario is to define security properties for the message's headers and body, that is, to decide whether these elements are digitally signed and encrypted. Finally, some third-party SOAP stacks require messages be in a specific format. Messaging-style operations provide this control. + + A messaging-style operation has at most one parameter and one return value where both types are message types; that is, they serialize directly into a specified SOAP message structure. This may be any type marked with the or the type. The following code example shows an operation similar to the preceding RCP-style, but which uses the messaging style. + + For example, if `BankingTransaction` and `BankingTransactionResponse` are both types that are message contracts, then the code in the following operations is valid. + +```csharp +[OperationContract] +BankingTransactionResponse Process(BankingTransaction bt); +[OperationContract] +void Store(BankingTransaction bt); +[OperationContract] +BankingTransactionResponse GetResponse(); +``` + + However, the following code is invalid. + +```csharp +[OperationContract] +bool Validate(BankingTransaction bt); +// Invalid, the return type is not a message contract. +[OperationContract] +void Reconcile(BankingTransaction bt1, BankingTransaction bt2); +// Invalid, there is more than one parameter. +``` + + An exception is thrown for any operation that involves a message contract type and that does not follow one of the valid patterns. Of course, operations that do not involve message contract types are not subject to these restrictions. + + If a type has both a message contract and a data contract, only its message contract is considered when the type is used in an operation. + +## Defining Message Contracts + + To define a message contract for a type (that is, to define the mapping between the type and a SOAP envelope), apply the to the type. Then apply the to those members of the type you want to make into SOAP headers, and apply the to those members you want to make into parts of the SOAP body of the message. + + The following code provides an example of using a message contract. + +```csharp +[MessageContract] +public class BankingTransaction +{ + [MessageHeader] public Operation operation; + [MessageHeader] public DateTime transactionDate; + [MessageBodyMember] private Account sourceAccount; + [MessageBodyMember] private Account targetAccount; + [MessageBodyMember] public int amount; +} +``` + + When using this type as an operation parameter, the following SOAP envelope is generated: + +```xml + + + Deposit + 2012-02-16T16:10:00 + + + + 0 + + + + + +``` + + Notice that `operation` and `transactionDate` appear as SOAP headers and the SOAP body consists of a wrapper element `BankingTransaction` containing `sourceAccount`, `targetAccount`, and `amount`. + + You can apply the and to all fields, properties, and events, regardless of whether they are public, private, protected, or internal. + + The allows you to specify the WrapperName and WrapperNamespace attributes which control the name of the wrapper element in the body of the SOAP message. By default the name of the message contract type is used for the wrapper and the namespace in which the message contract is defined `http://tempuri.org/` is used as the default namespace. + > [!NOTE] -> attributes are ignored in message contracts. If a is required, place it on the operation that is using the message contract in question. - -## Controlling Header and Body Part Names and Namespaces - - In the SOAP representation of a message contract, each header and body part maps to an XML element that has a name and a namespace. - - By default, the namespace is the same as the namespace of the service contract that the message is participating in, and the name is determined by the member name to which the or the attributes are applied. - - You can change these defaults by manipulating the and (on the parent class of the and attributes). - - Consider the class in the following code example. - -```csharp -[MessageContract] -public class BankingTransaction -{ - [MessageHeader] public Operation operation; - [MessageHeader(Namespace="http://schemas.contoso.com/auditing/2005")] public bool IsAudited; - [MessageBodyMember(Name="transactionData")] public BankingTransactionData theData; -} -``` - - In this example, the `IsAudited` header is in the namespace specified in the code, and the body part that represents the `theData` member is represented by an XML element with the name `transactionData`. The following shows the XML generated for this message contract. - -```xml - - - false - Deposit - - - - - - - -``` - -## Controlling Whether the SOAP Body Parts Are Wrapped - - By default, the SOAP body parts are serialized inside a wrapped element. For example, the following code shows the `HelloGreetingMessage` wrapper element generated from the name of the type in the message contract for the `HelloGreetingMessage` message. - +> attributes are ignored in message contracts. If a is required, place it on the operation that is using the message contract in question. + +## Controlling Header and Body Part Names and Namespaces + + In the SOAP representation of a message contract, each header and body part maps to an XML element that has a name and a namespace. + + By default, the namespace is the same as the namespace of the service contract that the message is participating in, and the name is determined by the member name to which the or the attributes are applied. + + You can change these defaults by manipulating the and (on the parent class of the and attributes). + + Consider the class in the following code example. + +```csharp +[MessageContract] +public class BankingTransaction +{ + [MessageHeader] public Operation operation; + [MessageHeader(Namespace="http://schemas.contoso.com/auditing/2005")] public bool IsAudited; + [MessageBodyMember(Name="transactionData")] public BankingTransactionData theData; +} +``` + + In this example, the `IsAudited` header is in the namespace specified in the code, and the body part that represents the `theData` member is represented by an XML element with the name `transactionData`. The following shows the XML generated for this message contract. + +```xml + + + false + Deposit + + + + + + + +``` + +## Controlling Whether the SOAP Body Parts Are Wrapped + + By default, the SOAP body parts are serialized inside a wrapped element. For example, the following code shows the `HelloGreetingMessage` wrapper element generated from the name of the type in the message contract for the `HelloGreetingMessage` message. + [!code-csharp[MessageHeaderAttribute#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/messageheaderattribute/cs/services.cs#3)] -[!code-vb[MessageHeaderAttribute#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/messageheaderattribute/vb/services.vb#3)] - - To suppress the wrapper element, set the property to `false`. To control the name and the namespace of the wrapper element, use the and properties. - +[!code-vb[MessageHeaderAttribute#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/messageheaderattribute/vb/services.vb#3)] + + To suppress the wrapper element, set the property to `false`. To control the name and the namespace of the wrapper element, use the and properties. + > [!NOTE] -> Having more than one message body part in messages that are not wrapped is not compliant with WS-I Basic Profile 1.1 and is not recommended when designing new message contracts. However, it may be necessary to have more than one unwrapped message body part in certain specific interoperability scenarios. If you are going to transmit more than one piece of data in a message body, it is recommended to use the default (wrapped) mode. Having more than one message header in unwrapped messages is completely acceptable. - -## Using Custom Types Inside Message Contracts - - Each individual message header and message body part is serialized (turned into XML) using the chosen serialization engine for the service contract where the message is used. The default serialization engine, the `XmlFormatter`, can handle any type that has a data contract, either explicitly (by having the ) or implicitly (by being a primitive type, having the , and so on). For more information, see [Using Data Contracts](using-data-contracts.md). - - In the preceding example, the `Operation` and `BankingTransactionData` types must have a data contract, and `transactionDate` is serializable because is a primitive (and so has an implicit data contract). - - However, it is possible to switch to a different serialization engine, the `XmlSerializer`. If you make such a switch, you should ensure that all of the types used for message headers and body parts are serializable using the `XmlSerializer`. - -## Using Arrays Inside Message Contracts - - You can use arrays of repeating elements in message contracts in two ways. - - The first is to use a or a directly on the array. In this case, the entire array is serialized as one element (that is, one header or one body part) with multiple child elements. Consider the class in the following example. - -```csharp -[MessageContract] -public class BankingDepositLog -{ - [MessageHeader] public int numRecords; - [MessageHeader] public DepositRecord[] records; - [MessageHeader] public int branchID; -} -``` - - This results in SOAP headers is similar to the following. - -```xml - -3 - - Record1 - Record2 - Record3 - -20643 - -``` - - An alternative to this is to use the . In this case, each array element is serialized independently and so that each array element has one header, similar to the following. - -```xml -3 -Record1 -Record2 -Record3 -20643 -``` - - The default name for array entries is the name of the member to which the attributes is applied. - - The attribute inherits from the . It has the same set of features as the non-array attributes, for example, it is possible to set the order, name, and namespace for an array of headers in the same way you set it for a single header. When you use the `Order` property on an array, it applies to the entire array. - - You can apply the only to arrays, not collections. - -## Using Byte Arrays in Message Contracts - - Byte arrays, when used with the non-array attributes ( and ), are not treated as arrays but as a special primitive type represented as Base64-encoded data in the resulting XML. - - When you use byte arrays with the array attribute , the results depend on the serializer in use. With the default serializer, the array is represented as an individual entry for each byte. However, when the `XmlSerializer` is selected, (using the on the service contract), byte arrays are treated as Base64 data regardless of whether the array or non-array attributes are used. - -## Signing and Encrypting Parts of the Message - - A message contract can indicate whether the headers and/or body of the message should be digitally signed and encrypted. - - This is done by setting the property on the and attributes. The property is an enumeration of the type and can be set to (no encryption or signature), (digital signature only), or (both encryption and a digital signature). The default is . - - For these security features to work, you must properly configure the binding and behaviors. If you use these security features without the proper configuration (for example, attempting to sign a message without supplying your credentials), an exception is thrown at validation time. - - For message headers, the protection level is determined individually for each header. - - For message body parts, the protection level can be thought of as the "minimum protection level." The body has only one protection level, regardless of the number of body parts. The protection level of the body is determined by the highest property setting of all the body parts. However, you should set the protection level of each body part to the actual minimum protection level required. - - Consider the class in the following code example. - -```csharp -[MessageContract] -public class PatientRecord -{ - [MessageHeader(ProtectionLevel=None)] public int recordID; - [MessageHeader(ProtectionLevel=Sign)] public string patientName; - [MessageHeader(ProtectionLevel=EncryptAndSign)] public string SSN; - [MessageBodyMember(ProtectionLevel=None)] public string comments; - [MessageBodyMember(ProtectionLevel=Sign)] public string diagnosis; - [MessageBodyMember(ProtectionLevel=EncryptAndSign)] public string medicalHistory; -} -``` - - In this example, the `recordID` header is not protected, `patientName` is `signed`, and `SSN` is encrypted and signed. At least one body part, `medicalHistory`, has applied, and thus the entire message body is encrypted and signed, even though the comments and diagnosis body parts specify lower protection levels. - -## SOAP Action - - SOAP and related Web services standards define a property called `Action` that can be present for every SOAP message sent. The operation's and properties control the value of this property. - -## SOAP Header Attributes - - The SOAP standard defines the following attributes that may exist on a header: - -- `Actor/Role` (`Actor` in SOAP 1.1, `Role` in SOAP 1.2) - -- `MustUnderstand` - -- `Relay` - - The `Actor` or `Role` attribute specifies the Uniform Resource Identifier (URI) of the node for which a given header is intended. The `MustUnderstand` attribute specifies whether the node processing the header must understand it. The `Relay` attribute specifies whether the header is to be relayed to downstream nodes. WCF does not perform any processing of these attributes on incoming messages, except for the `MustUnderstand` attribute, as specified in the "Message Contract Versioning" section later in this topic. However, it allows you to read and write these attributes as necessary, as in the following description. - - When sending a message, these attributes are not emitted by default. You can change this in two ways. First, you may statically set the attributes to any desired values by changing the , , and properties, as shown in the following code example. (Note that there is no `Role` property; setting the property emits the `Role` attribute if you are using SOAP 1.2). - -```csharp -[MessageContract] -public class BankingTransaction -{ - [MessageHeader(Actor="http://auditingservice.contoso.com", MustUnderstand=true)] public bool IsAudited; - [MessageHeader] public Operation operation; - [MessageBodyMember] public BankingTransactionData theData; -} -``` - - The second way to control these attributes is dynamically, through code. You can achieve this by wrapping the desired header type in the type (be sure not to confuse this type with the non-generic version) and by using the type together with the . Then, you can use properties on the to set the SOAP attributes, as shown in the following code example. - -```csharp -[MessageContract] -public class BankingTransaction -{ - [MessageHeader] public MessageHeader IsAudited; - [MessageHeader] public Operation operation; - [MessageBodyMember] public BankingTransactionData theData; -} -// application code: -BankingTransaction bt = new BankingTransaction(); -bt.IsAudited = new MessageHeader(); -bt.IsAudited.Content = false; // Set IsAudited header value to "false" -bt.IsAudited.Actor="http://auditingservice.contoso.com"; -bt.IsAudited.MustUnderstand=true; -``` - - If you use both the dynamic and the static control mechanisms, the static settings are used as a default but can later be overridden by using the dynamic mechanism, as shown in the following code. - -```csharp -[MessageHeader(MustUnderstand=true)] public MessageHeader documentApprover; -// later on in the code: -BankingTransaction bt = new BankingTransaction(); -bt.documentApprover = new MessageHeader(); -bt.documentApprover.MustUnderstand = false; // override the static default of 'true' -``` - - Creating repeated headers with dynamic attribute control is allowed, as shown in the following code. - -```csharp -[MessageHeaderArray] public MessageHeader documentApprovers[]; -``` - - On the receiving side, reading these SOAP attributes can only be done if the class is used for the header in the type. Examine the `Actor`, `Relay`, or `MustUnderstand` properties of a header of the type to discover the attribute settings on the received message. - - When a message is received and then sent back, the SOAP attribute settings only go round-trip for headers of the type. - -## Order of SOAP Body Parts - - In some circumstances, you may need to control the order of the body parts. The order of the body elements is alphabetical by default, but can be controlled by the property. This property has the same semantics as the property, except for the behavior in inheritance scenarios (in message contracts, base type body members are not sorted before the derived type body members). For more information, see [Data Member Order](data-member-order.md). - - In the following example, `amount` would normally come first because it is first alphabetically. However, the property puts it into the third position. - -```csharp -[MessageContract] -public class BankingTransaction -{ - [MessageHeader] public Operation operation; - [MessageBodyMember(Order=1)] public Account sourceAccount; - [MessageBodyMember(Order=2)] public Account targetAccount; - [MessageBodyMember(Order=3)] public int amount; -} -``` - -## Message Contract Versioning - - Occasionally, you may need to change message contracts. For example, a new version of your application may add an extra header to a message. Then, when sending from the new version to the old, the system must deal with an extra header, as well as a missing header when going in the other direction. - - The following rules apply for versioning headers: - -- WCF does not object to the missing headers—the corresponding members are left at their default values. - -- WCF also ignores unexpected extra headers. The one exception to this rule is if the extra header has a `MustUnderstand` attribute set to `true` in the incoming SOAP message—in this case, an exception is thrown because a header that must be understood cannot be processed. - - Message bodies have similar versioning rules—both missing and additional message body parts are ignored. - -## Inheritance Considerations - - A message contract type can inherit from another type, as long as the base type also has a message contract. - - When creating or accessing a message using a message contract type that inherits from other message contract types, the following rules apply: - -- All of the message headers in the inheritance hierarchy are collected together to form the full set of headers for the message. - -- All of the message body parts in the inheritance hierarchy are collected together to form the full message body. The body parts are ordered according to the usual ordering rules (by property and then alphabetical), with no relevance to their place in the inheritance hierarchy. Using message contract inheritance where message body parts occur at multiple levels of the inheritance tree is strongly discouraged. If a base class and a derived class define a header or a body part with the same name, the member from the base-most class is used to store the value of that header or body part. - - Consider the classes in the following code example. - -```csharp -[MessageContract] -public class PersonRecord -{ - [MessageHeader(Name="ID")] public int personID; - [MessageBodyMember] public string patientName; -} - -[MessageContract] -public class PatientRecord : PersonRecord -{ - [MessageHeader(Name="ID")] public int patientID; - [MessageBodyMember] public string diagnosis; -} -``` - - The `PatientRecord` class describes a message with one header called `ID`. The header corresponds to the `personID` and not the `patientID` member, because the base-most member is chosen. Thus, the `patientID` field is useless in this case. The body of the message contains the `diagnosis` element followed by the `patientName` element, because that is the alphabetical order. Notice that the example shows a pattern that is strongly discouraged: both the base and the derived message contracts have message body parts. - -## WSDL Considerations - - When generating a Web Services Description Language (WSDL) contract from a service that uses message contracts, it is important to remember that not all message contract features are reflected in the resulting WSDL. Consider the following points: - -- WSDL cannot express the concept of an array of headers. When creating messages with an array of headers using the , the resulting WSDL reflects only one header instead of the array. - -- The resulting WSDL document may not reflect some protection-level information. - -- The message type generated in the WSDL has the same name as the class name of the message contract type. - -- When using the same message contract in multiple operations, multiple message types are generated in the WSDL document. The names are made unique by adding the numbers "2", "3", and so on, for subsequent uses. When importing back the WSDL, multiple message contract types are created and are identical except for their names. - -## SOAP Encoding Considerations - - WCF allows you to use the legacy SOAP encoding style of XML, however, its use is not recommended. When using this style (by setting the `Use` property to `Encoded` on the applied to the service contract), the following additional considerations apply: - -- The message headers are not supported; this means that the attribute and the array attribute are incompatible with SOAP encoding. - -- If the message contract is not wrapped, that is, if the property is set to `false`, the message contract can have only one body part. - -- The name of the wrapper element for the request message contract must match the operation name. Use the `WrapperName` property of the message contract for this. - -- The name of the wrapper element for the response message contract must be the same as the name of the operation suffixed by 'Response'. Use the property of the message contract for this. - -- SOAP encoding preserves object references. For example, consider the following code. - - ```csharp - [MessageContract(WrapperName="updateChangeRecord")] - public class ChangeRecordRequest - { - [MessageBodyMember] Person changedBy; - [MessageBodyMember] Person changedFrom; - [MessageBodyMember] Person changedTo; - } - - [MessageContract(WrapperName="updateChangeRecordResponse")] - public class ChangeRecordResponse - { - [MessageBodyMember] Person changedBy; - [MessageBodyMember] Person changedFrom; - [MessageBodyMember] Person changedTo; - } - - // application code: - ChangeRecordRequest cr = new ChangeRecordRequest(); - Person p = new Person("John Doe"); - cr.changedBy=p; - cr.changedFrom=p; - cr.changedTo=p; - ``` - - After serializing the message using SOAP encoding, `changedFrom` and `changedTo` do not contain their own copies of `p`, but instead point to the copy inside the `changedBy` element. - -## Performance Considerations - - Every message header and message body part is serialized independently of the others. Therefore, the same namespaces can be declared again for each header and body part. To improve performance, especially in terms of the size of the message on the wire, consolidate multiple headers and body parts into a single header or body part. For example, instead of the following code: - -```csharp -[MessageContract] -public class BankingTransaction -{ - [MessageHeader] public Operation operation; - [MessageBodyMember] public Account sourceAccount; - [MessageBodyMember] public Account targetAccount; - [MessageBodyMember] public int amount; -} -``` - - Use this code. - -```csharp -[MessageContract] -public class BankingTransaction -{ - [MessageHeader] public Operation operation; - [MessageBodyMember] public OperationDetails details; -} - -[DataContract] -public class OperationDetails -{ - [DataMember] public Account sourceAccount; - [DataMember] public Account targetAccount; - [DataMember] public int amount; -} -``` - -### Event-based Asynchronous and Message Contracts - - The design guidelines for the event-based asynchronous model state that if more than one value is returned, one value is returned as the `Result` property and the others are returned as properties on the object. One result of this is that if a client imports metadata using the event-based asynchronous command options and the operation returns more than one value, the default object returns one value as the `Result` property and the remainder are properties of the object. - - If you want to receive the message object as the `Result` property and have the returned values as properties on that object, use the `/messageContract` command option. This generates a signature that returns the response message as the `Result` property on the object. All internal return values are then properties of the response message object. - +> Having more than one message body part in messages that are not wrapped is not compliant with WS-I Basic Profile 1.1 and is not recommended when designing new message contracts. However, it may be necessary to have more than one unwrapped message body part in certain specific interoperability scenarios. If you are going to transmit more than one piece of data in a message body, it is recommended to use the default (wrapped) mode. Having more than one message header in unwrapped messages is completely acceptable. + +## Using Custom Types Inside Message Contracts + + Each individual message header and message body part is serialized (turned into XML) using the chosen serialization engine for the service contract where the message is used. The default serialization engine, the `XmlFormatter`, can handle any type that has a data contract, either explicitly (by having the ) or implicitly (by being a primitive type, having the , and so on). For more information, see [Using Data Contracts](using-data-contracts.md). + + In the preceding example, the `Operation` and `BankingTransactionData` types must have a data contract, and `transactionDate` is serializable because is a primitive (and so has an implicit data contract). + + However, it is possible to switch to a different serialization engine, the `XmlSerializer`. If you make such a switch, you should ensure that all of the types used for message headers and body parts are serializable using the `XmlSerializer`. + +## Using Arrays Inside Message Contracts + + You can use arrays of repeating elements in message contracts in two ways. + + The first is to use a or a directly on the array. In this case, the entire array is serialized as one element (that is, one header or one body part) with multiple child elements. Consider the class in the following example. + +```csharp +[MessageContract] +public class BankingDepositLog +{ + [MessageHeader] public int numRecords; + [MessageHeader] public DepositRecord[] records; + [MessageHeader] public int branchID; +} +``` + + This results in SOAP headers is similar to the following. + +```xml + +3 + + Record1 + Record2 + Record3 + +20643 + +``` + + An alternative to this is to use the . In this case, each array element is serialized independently and so that each array element has one header, similar to the following. + +```xml +3 +Record1 +Record2 +Record3 +20643 +``` + + The default name for array entries is the name of the member to which the attributes is applied. + + The attribute inherits from the . It has the same set of features as the non-array attributes, for example, it is possible to set the order, name, and namespace for an array of headers in the same way you set it for a single header. When you use the `Order` property on an array, it applies to the entire array. + + You can apply the only to arrays, not collections. + +## Using Byte Arrays in Message Contracts + + Byte arrays, when used with the non-array attributes ( and ), are not treated as arrays but as a special primitive type represented as Base64-encoded data in the resulting XML. + + When you use byte arrays with the array attribute , the results depend on the serializer in use. With the default serializer, the array is represented as an individual entry for each byte. However, when the `XmlSerializer` is selected, (using the on the service contract), byte arrays are treated as Base64 data regardless of whether the array or non-array attributes are used. + +## Signing and Encrypting Parts of the Message + + A message contract can indicate whether the headers and/or body of the message should be digitally signed and encrypted. + + This is done by setting the property on the and attributes. The property is an enumeration of the type and can be set to (no encryption or signature), (digital signature only), or (both encryption and a digital signature). The default is . + + For these security features to work, you must properly configure the binding and behaviors. If you use these security features without the proper configuration (for example, attempting to sign a message without supplying your credentials), an exception is thrown at validation time. + + For message headers, the protection level is determined individually for each header. + + For message body parts, the protection level can be thought of as the "minimum protection level." The body has only one protection level, regardless of the number of body parts. The protection level of the body is determined by the highest property setting of all the body parts. However, you should set the protection level of each body part to the actual minimum protection level required. + + Consider the class in the following code example. + +```csharp +[MessageContract] +public class PatientRecord +{ + [MessageHeader(ProtectionLevel=None)] public int recordID; + [MessageHeader(ProtectionLevel=Sign)] public string patientName; + [MessageHeader(ProtectionLevel=EncryptAndSign)] public string SSN; + [MessageBodyMember(ProtectionLevel=None)] public string comments; + [MessageBodyMember(ProtectionLevel=Sign)] public string diagnosis; + [MessageBodyMember(ProtectionLevel=EncryptAndSign)] public string medicalHistory; +} +``` + + In this example, the `recordID` header is not protected, `patientName` is `signed`, and `SSN` is encrypted and signed. At least one body part, `medicalHistory`, has applied, and thus the entire message body is encrypted and signed, even though the comments and diagnosis body parts specify lower protection levels. + +## SOAP Action + + SOAP and related Web services standards define a property called `Action` that can be present for every SOAP message sent. The operation's and properties control the value of this property. + +## SOAP Header Attributes + + The SOAP standard defines the following attributes that may exist on a header: + +- `Actor/Role` (`Actor` in SOAP 1.1, `Role` in SOAP 1.2) + +- `MustUnderstand` + +- `Relay` + + The `Actor` or `Role` attribute specifies the Uniform Resource Identifier (URI) of the node for which a given header is intended. The `MustUnderstand` attribute specifies whether the node processing the header must understand it. The `Relay` attribute specifies whether the header is to be relayed to downstream nodes. WCF does not perform any processing of these attributes on incoming messages, except for the `MustUnderstand` attribute, as specified in the "Message Contract Versioning" section later in this topic. However, it allows you to read and write these attributes as necessary, as in the following description. + + When sending a message, these attributes are not emitted by default. You can change this in two ways. First, you may statically set the attributes to any desired values by changing the , , and properties, as shown in the following code example. (Note that there is no `Role` property; setting the property emits the `Role` attribute if you are using SOAP 1.2). + +```csharp +[MessageContract] +public class BankingTransaction +{ + [MessageHeader(Actor="http://auditingservice.contoso.com", MustUnderstand=true)] public bool IsAudited; + [MessageHeader] public Operation operation; + [MessageBodyMember] public BankingTransactionData theData; +} +``` + + The second way to control these attributes is dynamically, through code. You can achieve this by wrapping the desired header type in the type (be sure not to confuse this type with the non-generic version) and by using the type together with the . Then, you can use properties on the to set the SOAP attributes, as shown in the following code example. + +```csharp +[MessageContract] +public class BankingTransaction +{ + [MessageHeader] public MessageHeader IsAudited; + [MessageHeader] public Operation operation; + [MessageBodyMember] public BankingTransactionData theData; +} +// application code: +BankingTransaction bt = new BankingTransaction(); +bt.IsAudited = new MessageHeader(); +bt.IsAudited.Content = false; // Set IsAudited header value to "false" +bt.IsAudited.Actor="http://auditingservice.contoso.com"; +bt.IsAudited.MustUnderstand=true; +``` + + If you use both the dynamic and the static control mechanisms, the static settings are used as a default but can later be overridden by using the dynamic mechanism, as shown in the following code. + +```csharp +[MessageHeader(MustUnderstand=true)] public MessageHeader documentApprover; +// later on in the code: +BankingTransaction bt = new BankingTransaction(); +bt.documentApprover = new MessageHeader(); +bt.documentApprover.MustUnderstand = false; // override the static default of 'true' +``` + + Creating repeated headers with dynamic attribute control is allowed, as shown in the following code. + +```csharp +[MessageHeaderArray] public MessageHeader documentApprovers[]; +``` + + On the receiving side, reading these SOAP attributes can only be done if the class is used for the header in the type. Examine the `Actor`, `Relay`, or `MustUnderstand` properties of a header of the type to discover the attribute settings on the received message. + + When a message is received and then sent back, the SOAP attribute settings only go round-trip for headers of the type. + +## Order of SOAP Body Parts + + In some circumstances, you may need to control the order of the body parts. The order of the body elements is alphabetical by default, but can be controlled by the property. This property has the same semantics as the property, except for the behavior in inheritance scenarios (in message contracts, base type body members are not sorted before the derived type body members). For more information, see [Data Member Order](data-member-order.md). + + In the following example, `amount` would normally come first because it is first alphabetically. However, the property puts it into the third position. + +```csharp +[MessageContract] +public class BankingTransaction +{ + [MessageHeader] public Operation operation; + [MessageBodyMember(Order=1)] public Account sourceAccount; + [MessageBodyMember(Order=2)] public Account targetAccount; + [MessageBodyMember(Order=3)] public int amount; +} +``` + +## Message Contract Versioning + + Occasionally, you may need to change message contracts. For example, a new version of your application may add an extra header to a message. Then, when sending from the new version to the old, the system must deal with an extra header, as well as a missing header when going in the other direction. + + The following rules apply for versioning headers: + +- WCF does not object to the missing headers—the corresponding members are left at their default values. + +- WCF also ignores unexpected extra headers. The one exception to this rule is if the extra header has a `MustUnderstand` attribute set to `true` in the incoming SOAP message—in this case, an exception is thrown because a header that must be understood cannot be processed. + + Message bodies have similar versioning rules—both missing and additional message body parts are ignored. + +## Inheritance Considerations + + A message contract type can inherit from another type, as long as the base type also has a message contract. + + When creating or accessing a message using a message contract type that inherits from other message contract types, the following rules apply: + +- All of the message headers in the inheritance hierarchy are collected together to form the full set of headers for the message. + +- All of the message body parts in the inheritance hierarchy are collected together to form the full message body. The body parts are ordered according to the usual ordering rules (by property and then alphabetical), with no relevance to their place in the inheritance hierarchy. Using message contract inheritance where message body parts occur at multiple levels of the inheritance tree is strongly discouraged. If a base class and a derived class define a header or a body part with the same name, the member from the base-most class is used to store the value of that header or body part. + + Consider the classes in the following code example. + +```csharp +[MessageContract] +public class PersonRecord +{ + [MessageHeader(Name="ID")] public int personID; + [MessageBodyMember] public string patientName; +} + +[MessageContract] +public class PatientRecord : PersonRecord +{ + [MessageHeader(Name="ID")] public int patientID; + [MessageBodyMember] public string diagnosis; +} +``` + + The `PatientRecord` class describes a message with one header called `ID`. The header corresponds to the `personID` and not the `patientID` member, because the base-most member is chosen. Thus, the `patientID` field is useless in this case. The body of the message contains the `diagnosis` element followed by the `patientName` element, because that is the alphabetical order. Notice that the example shows a pattern that is strongly discouraged: both the base and the derived message contracts have message body parts. + +## WSDL Considerations + + When generating a Web Services Description Language (WSDL) contract from a service that uses message contracts, it is important to remember that not all message contract features are reflected in the resulting WSDL. Consider the following points: + +- WSDL cannot express the concept of an array of headers. When creating messages with an array of headers using the , the resulting WSDL reflects only one header instead of the array. + +- The resulting WSDL document may not reflect some protection-level information. + +- The message type generated in the WSDL has the same name as the class name of the message contract type. + +- When using the same message contract in multiple operations, multiple message types are generated in the WSDL document. The names are made unique by adding the numbers "2", "3", and so on, for subsequent uses. When importing back the WSDL, multiple message contract types are created and are identical except for their names. + +## SOAP Encoding Considerations + + WCF allows you to use the legacy SOAP encoding style of XML, however, its use is not recommended. When using this style (by setting the `Use` property to `Encoded` on the applied to the service contract), the following additional considerations apply: + +- The message headers are not supported; this means that the attribute and the array attribute are incompatible with SOAP encoding. + +- If the message contract is not wrapped, that is, if the property is set to `false`, the message contract can have only one body part. + +- The name of the wrapper element for the request message contract must match the operation name. Use the `WrapperName` property of the message contract for this. + +- The name of the wrapper element for the response message contract must be the same as the name of the operation suffixed by 'Response'. Use the property of the message contract for this. + +- SOAP encoding preserves object references. For example, consider the following code. + + ```csharp + [MessageContract(WrapperName="updateChangeRecord")] + public class ChangeRecordRequest + { + [MessageBodyMember] Person changedBy; + [MessageBodyMember] Person changedFrom; + [MessageBodyMember] Person changedTo; + } + + [MessageContract(WrapperName="updateChangeRecordResponse")] + public class ChangeRecordResponse + { + [MessageBodyMember] Person changedBy; + [MessageBodyMember] Person changedFrom; + [MessageBodyMember] Person changedTo; + } + + // application code: + ChangeRecordRequest cr = new ChangeRecordRequest(); + Person p = new Person("John Doe"); + cr.changedBy=p; + cr.changedFrom=p; + cr.changedTo=p; + ``` + + After serializing the message using SOAP encoding, `changedFrom` and `changedTo` do not contain their own copies of `p`, but instead point to the copy inside the `changedBy` element. + +## Performance Considerations + + Every message header and message body part is serialized independently of the others. Therefore, the same namespaces can be declared again for each header and body part. To improve performance, especially in terms of the size of the message on the wire, consolidate multiple headers and body parts into a single header or body part. For example, instead of the following code: + +```csharp +[MessageContract] +public class BankingTransaction +{ + [MessageHeader] public Operation operation; + [MessageBodyMember] public Account sourceAccount; + [MessageBodyMember] public Account targetAccount; + [MessageBodyMember] public int amount; +} +``` + + Use this code. + +```csharp +[MessageContract] +public class BankingTransaction +{ + [MessageHeader] public Operation operation; + [MessageBodyMember] public OperationDetails details; +} + +[DataContract] +public class OperationDetails +{ + [DataMember] public Account sourceAccount; + [DataMember] public Account targetAccount; + [DataMember] public int amount; +} +``` + +### Event-based Asynchronous and Message Contracts + + The design guidelines for the event-based asynchronous model state that if more than one value is returned, one value is returned as the `Result` property and the others are returned as properties on the object. One result of this is that if a client imports metadata using the event-based asynchronous command options and the operation returns more than one value, the default object returns one value as the `Result` property and the remainder are properties of the object. + + If you want to receive the message object as the `Result` property and have the returned values as properties on that object, use the `/messageContract` command option. This generates a signature that returns the response message as the `Result` property on the object. All internal return values are then properties of the response message object. + ## See also - [Using Data Contracts](using-data-contracts.md) diff --git a/docs/framework/wcf/feature-details/using-servicethrottlingbehavior-to-control-wcf-service-performance.md b/docs/framework/wcf/feature-details/using-servicethrottlingbehavior-to-control-wcf-service-performance.md index 2cfa790a87ee6..4cb1054a1c20c 100644 --- a/docs/framework/wcf/feature-details/using-servicethrottlingbehavior-to-control-wcf-service-performance.md +++ b/docs/framework/wcf/feature-details/using-servicethrottlingbehavior-to-control-wcf-service-performance.md @@ -12,19 +12,19 @@ The class expos ## Controlling Service Instances and Concurrent Calls - Use the property to specify the maximum number of messages actively processing across a class, and the property to specify the maximum number of objects in the service. + Use the property to specify the maximum number of messages actively processing across a class, and the property to specify the maximum number of objects in the service. Because determining the settings for these properties usually takes place after real-world experience running the application against loads, the settings for the properties is typically specified in an application configuration file using the [\](../../configure-apps/file-schema/wcf/servicethrottling.md) element. - The following code example shows the use of the class from an application configuration file that sets the , , and properties to 1 as a trivial example. Real-world experience determines the optimal settings for any particular application. + The following code example shows the use of the class from an application configuration file that sets the , , and properties to 1 as a trivial example. Real-world experience determines the optimal settings for any particular application. [!code-xml[ServiceThrottlingBehavior#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/servicethrottlingbehavior/cs/hostapplication.exe.config#3)] - The exact runtime behavior depends upon the values of the and properties, which control how many messages can execute inside an operation at once and the lifetimes of the service relative to incoming channel sessions, respectively. + The exact runtime behavior depends upon the values of the and properties, which control how many messages can execute inside an operation at once and the lifetimes of the service relative to incoming channel sessions, respectively. - For details, see , and . + For details, see , and . ## See also - -- +- diff --git a/docs/framework/wcf/feature-details/using-the-discovery-client-channel.md b/docs/framework/wcf/feature-details/using-the-discovery-client-channel.md index 8efeb4b3c7934..a61de4811b259 100644 --- a/docs/framework/wcf/feature-details/using-the-discovery-client-channel.md +++ b/docs/framework/wcf/feature-details/using-the-discovery-client-channel.md @@ -6,56 +6,56 @@ ms.assetid: 1494242a-1d64-4035-8ecd-eb4f06c8d2ba --- # Using the Discovery Client Channel -When writing a WCF client application you need to know the endpoint address of the service you are calling. In many situations the endpoint address of a service is not known in advance or the address of the service changes over time. The Discovery Client Channel allows you to write a WCF client application, describe the service you want to call, and the client channel automatically sends a probe request. When a service responds, the discovery client channel retrieves the endpoint address for the service from the probe response and uses it to call the service. - -## Using the Discovery Client Channel +When writing a WCF client application you need to know the endpoint address of the service you are calling. In many situations the endpoint address of a service is not known in advance or the address of the service changes over time. The Discovery Client Channel allows you to write a WCF client application, describe the service you want to call, and the client channel automatically sends a probe request. When a service responds, the discovery client channel retrieves the endpoint address for the service from the probe response and uses it to call the service. + +## Using the Discovery Client Channel + + To use the Discovery Client Channel, add an instance of the to your client channel stack. Alternatively you can use the and a is automatically added to your binding if not already present. - To use the Discovery Client Channel, add an instance of the to your client channel stack. Alternatively you can use the and a is automatically added to your binding if not already present. - > [!CAUTION] -> It is recommended that the is the top-most element on your client channel stack. Any binding element that is added on top of the must make sure that the or channel it creates does not use the endpoint address or `Via` address (passed to the `CreateChannel` method) because they may not contain the correct address. - - The class contains two public properties: - -1. , which is used to describe the service you want to call. - -2. which specifies the discovery endpoint to send discovery messages to. - - The property allows you to specify the service contract you are searching for, any required scope URIs, and the maximum number of time to attempt to open the channel. The contract type is specified by calling the constructor . Scope URIs can be added to the property. The property allows you to specify the maximum number of results to which the client tries to connect to. When a probe response is received the client attempts to open the channel using the endpoint address from the probe response. If an exception occurs the client moves on to the next probe response, waiting for more responses to be received if necessary. It continues to do this until the channel is successfully opened or the maximum number of results is reached. For more information about these settings, see . - - The property allows you to specify the discovery endpoint to use. Normally this is a , but it can be any valid endpoint. - - When you are creating the binding to use to communicate with the service, you must be careful to use the exact same binding as the service. The only difference is the client binding has a on the top of the stack. If service is using one of the system-provided bindings, create a new and pass in the system-provided binding to the constructor. Then you can add the by calling `Insert` on the property. - - Once you have added the to your binding and configured it, you can create an instance of the WCF client class, open it, and call its methods. The following example uses the Discovery Client Channel to discover a WCF service that implements the `ICalculator` class (used in the Getting Started WCF tutorial) and calls its `Add` method. - +> It is recommended that the is the top-most element on your client channel stack. Any binding element that is added on top of the must make sure that the or channel it creates does not use the endpoint address or `Via` address (passed to the `CreateChannel` method) because they may not contain the correct address. + + The class contains two public properties: + +1. , which is used to describe the service you want to call. + +2. which specifies the discovery endpoint to send discovery messages to. + + The property allows you to specify the service contract you are searching for, any required scope URIs, and the maximum number of time to attempt to open the channel. The contract type is specified by calling the constructor . Scope URIs can be added to the property. The property allows you to specify the maximum number of results to which the client tries to connect to. When a probe response is received the client attempts to open the channel using the endpoint address from the probe response. If an exception occurs the client moves on to the next probe response, waiting for more responses to be received if necessary. It continues to do this until the channel is successfully opened or the maximum number of results is reached. For more information about these settings, see . + + The property allows you to specify the discovery endpoint to use. Normally this is a , but it can be any valid endpoint. + + When you are creating the binding to use to communicate with the service, you must be careful to use the exact same binding as the service. The only difference is the client binding has a on the top of the stack. If service is using one of the system-provided bindings, create a new and pass in the system-provided binding to the constructor. Then you can add the by calling `Insert` on the property. + + Once you have added the to your binding and configured it, you can create an instance of the WCF client class, open it, and call its methods. The following example uses the Discovery Client Channel to discover a WCF service that implements the `ICalculator` class (used in the Getting Started WCF tutorial) and calls its `Add` method. + ```csharp -// Create the DiscoveryClientBindingElement -DiscoveryClientBindingElement bindingElement = new DiscoveryClientBindingElement(); -// Search for a service that implements the ICalculator interface, attempting to open -// the channel a maximum of 2 times -bindingElement.FindCriteria = new FindCriteria(typeof(ICalculator)) { MaxResults = 2 }; -// Use the UdpDiscoveryEndpoint -bindingElement.DiscoveryEndpoint = new UdpDiscoveryEndpoint(); - +// Create the DiscoveryClientBindingElement +DiscoveryClientBindingElement bindingElement = new DiscoveryClientBindingElement(); +// Search for a service that implements the ICalculator interface, attempting to open +// the channel a maximum of 2 times +bindingElement.FindCriteria = new FindCriteria(typeof(ICalculator)) { MaxResults = 2 }; +// Use the UdpDiscoveryEndpoint +bindingElement.DiscoveryEndpoint = new UdpDiscoveryEndpoint(); + // The service uses the BasicHttpBinding, so use that and insert the DiscoveryClientBindingElement at the -// top of the stack -CustomBinding binding = new CustomBinding(new BasicHttpBinding()); -binding.Elements.Insert(0,bindingElement); - -try -{ - // Create the WCF client and call a method - CalculatorClient client = new CalculatorClient(binding, new EndpointAddress("http://schemas.microsoft.com/dynamic")); - client.Open(); - client.Add(1, 1); -} -catch (EndpointNotFoundException ex) -{ - Console.WriteLine("An exception occurred: " + ex.Message); -} -``` - -## Security and the Discovery Client Channel +// top of the stack +CustomBinding binding = new CustomBinding(new BasicHttpBinding()); +binding.Elements.Insert(0,bindingElement); + +try +{ + // Create the WCF client and call a method + CalculatorClient client = new CalculatorClient(binding, new EndpointAddress("http://schemas.microsoft.com/dynamic")); + client.Open(); + client.Add(1, 1); +} +catch (EndpointNotFoundException ex) +{ + Console.WriteLine("An exception occurred: " + ex.Message); +} +``` + +## Security and the Discovery Client Channel When using the discovery client channel, two endpoints are being specified. One is used for discovery messages, usually , and the other is the application endpoint. When implementing a secure service, care must be taken to secure both endpoints. For more information about security, see [Securing Services and Clients](securing-services-and-clients.md). diff --git a/docs/framework/wcf/feature-details/using-the-message-class.md b/docs/framework/wcf/feature-details/using-the-message-class.md index 284ed3ebada16..f28e512bbec8d 100644 --- a/docs/framework/wcf/feature-details/using-the-message-class.md +++ b/docs/framework/wcf/feature-details/using-the-message-class.md @@ -42,7 +42,7 @@ The class is fundamental to Windows The class provides static `CreateMessage` factory methods that you can use to create basic messages. - All `CreateMessage` overloads take a version parameter of type that indicates the SOAP and WS-Addressing versions to use for the message. If you want to use the same protocol versions as the incoming message, you can use the property on the instance obtained from the property. Most `CreateMessage` overloads also have a string parameter that indicates the SOAP action to use for the message. Version can be set to `None` to disable SOAP envelope generation; the message consists of only the body. + All `CreateMessage` overloads take a version parameter of type that indicates the SOAP and WS-Addressing versions to use for the message. If you want to use the same protocol versions as the incoming message, you can use the property on the instance obtained from the property. Most `CreateMessage` overloads also have a string parameter that indicates the SOAP action to use for the message. Version can be set to `None` to disable SOAP envelope generation; the message consists of only the body. ## Creating Messages from Objects @@ -91,7 +91,7 @@ The class is fundamental to Windows ## Writing Messages - The method writes out the body contents of a given `Message` instance to a given XML writer. The method does the same, except that it encloses the body contents in the appropriate wrapper element (for example, ``). Finally, writes out the entire message, including the wrapping SOAP envelope and the headers. If SOAP is turned off ( is ), all three methods do the same thing: they write out the message body contents. + The method writes out the body contents of a given `Message` instance to a given XML writer. The method does the same, except that it encloses the body contents in the appropriate wrapper element (for example, ``). Finally, writes out the entire message, including the wrapping SOAP envelope and the headers. If SOAP is turned off ( is ), all three methods do the same thing: they write out the message body contents. For example, the following code writes out the body of an incoming message to a file. @@ -100,21 +100,21 @@ The class is fundamental to Windows Two additional helper methods write out certain SOAP start element tags. These methods do not access the message body and so they do not change the message state. These include: -- writes the start body element, for example, ``. +- writes the start body element, for example, ``. -- writes the start envelope element, for example, ``. +- writes the start envelope element, for example, ``. To write the corresponding end element tags, call `WriteEndElement` on the corresponding XML writer. These methods are rarely called directly. ## Reading Messages - The primary way to read a message body is to call . You get back an that you can use to read the message body. Note that the transitions to the Read state as soon as is called, and not when you use the returned XML reader. + The primary way to read a message body is to call . You get back an that you can use to read the message body. Note that the transitions to the Read state as soon as is called, and not when you use the returned XML reader. - The method also enables you to access the message body as a typed object. Internally, this method uses `GetReaderAtBodyContents`, and so it also transitions the message state to the state (see the property). + The method also enables you to access the message body as a typed object. Internally, this method uses `GetReaderAtBodyContents`, and so it also transitions the message state to the state (see the property). - It is good practice to check the property, in which case the message body is empty and throws an . Also, if it is a received message (for example, the reply), you may also want to check , which indicates whether the message contains a fault. + It is good practice to check the property, in which case the message body is empty and throws an . Also, if it is a received message (for example, the reply), you may also want to check , which indicates whether the message contains a fault. - The most basic overload of deserializes the message body into an instance of a type (indicated by the generic parameter) using a configured with the default settings and with the quota disabled. If you want to use a different serialization engine, or configure the `DataContractSerializer` in a non-default way, use the overload that takes an . + The most basic overload of deserializes the message body into an instance of a type (indicated by the generic parameter) using a configured with the default settings and with the quota disabled. If you want to use a different serialization engine, or configure the `DataContractSerializer` in a non-default way, use the overload that takes an . For example, the following code extracts data from a message body that contains a serialized `Person` object and prints out the person’s name. @@ -125,32 +125,32 @@ The class is fundamental to Windows Sometimes it is necessary to access the message body more than once, for example, to forward the same message to multiple destinations as part of a publisher-subscriber system. In this case, it is necessary to buffer the entire message (including the body) in memory. You can do this by calling . This method takes an integer parameter that represents the maximum buffer size, and creates a buffer not larger than this size. It is important to set this to a safe value if the message is coming from an untrusted source. - The buffer is returned as a instance. You can access data in the buffer in several ways. The primary way is to call to create `Message` instances from the buffer. + The buffer is returned as a instance. You can access data in the buffer in several ways. The primary way is to call to create `Message` instances from the buffer. - Another way to access the data in the buffer is to implement the interface that the class implements to access the underlying XML directly. Some overloads allow you to create navigators protected by a node quota, limiting the number of XML nodes that can be visited. This helps prevent denial of service attacks based on lengthy processing time. This quote is disabled by default. Some `CreateNavigator` overloads allow you to specify how white space should be handled in the XML using the enumeration, with the default being `XmlSpace.None`. + Another way to access the data in the buffer is to implement the interface that the class implements to access the underlying XML directly. Some overloads allow you to create navigators protected by a node quota, limiting the number of XML nodes that can be visited. This helps prevent denial of service attacks based on lengthy processing time. This quote is disabled by default. Some `CreateNavigator` overloads allow you to specify how white space should be handled in the XML using the enumeration, with the default being `XmlSpace.None`. - A final way to access the contents of a message buffer is to write out its contents to a stream using . + A final way to access the contents of a message buffer is to write out its contents to a stream using . The following example demonstrates the process of working with a `MessageBuffer`: an incoming message is forwarded to multiple recipients, and then logged to a file. Without buffering, this is not possible, because the message body can then be accessed only once. [!code-csharp[C_UsingTheMessageClass#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_usingthemessageclass/cs/source.cs#7)] [!code-vb[C_UsingTheMessageClass#7](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_usingthemessageclass/vb/source.vb#7)] - The `MessageBuffer` class has other members worth noting. The method can be called to free resources when the buffer contents are no longer required. The property returns the size of the allocated buffer. The property returns the MIME content type of the message. + The `MessageBuffer` class has other members worth noting. The method can be called to free resources when the buffer contents are no longer required. The property returns the size of the allocated buffer. The property returns the MIME content type of the message. ## Accessing the Message Body for Debugging - For debugging purposes, you can call the method to get a representation of the message as a string. This representation generally matches the way a message would look on the wire if it were encoded with the text encoder, except that the XML would be better formatted for human readability. The one exception to this is the message body. The body can be read only once, and `ToString` does not change the message state. Therefore, the `ToString` method might not be able to access the body and might substitute a placeholder (for example, "…" or three dots) instead of the message body. Therefore, do not use `ToString` to log messages if the body content of the messages is important. + For debugging purposes, you can call the method to get a representation of the message as a string. This representation generally matches the way a message would look on the wire if it were encoded with the text encoder, except that the XML would be better formatted for human readability. The one exception to this is the message body. The body can be read only once, and `ToString` does not change the message state. Therefore, the `ToString` method might not be able to access the body and might substitute a placeholder (for example, "…" or three dots) instead of the message body. Therefore, do not use `ToString` to log messages if the body content of the messages is important. ## Accessing Other Message Parts Various properties are provided to access information about the message other than its body contents. However, these cannot be called once the message has been closed: -- The property represents the message headers. See the section on "Working with Headers" later in this topic. +- The property represents the message headers. See the section on "Working with Headers" later in this topic. -- The property represents the message properties, which are pieces of named data attached to the message that do not generally get emitted when the message is sent. See the section on "Working with Properties" later in this topic. +- The property represents the message properties, which are pieces of named data attached to the message that do not generally get emitted when the message is sent. See the section on "Working with Properties" later in this topic. -- The property indicates the SOAP and WS-Addressing version associated with the message, or `None` if SOAP is disabled. +- The property indicates the SOAP and WS-Addressing version associated with the message, or `None` if SOAP is disabled. - The property returns `true` if the message is a SOAP fault message. @@ -167,19 +167,19 @@ The class is fundamental to Windows #### Adding, Removing, Finding Headers - You can add a new header at the end of all existing headers using the method. You can use the method to insert a header at a particular index. Existing headers are shifted for the inserted item. Headers are ordered according to their index, and the first available index is 0. You can use the various method overloads to add headers from a different `Message` or `MessageHeaders` instance. Some overloads copy one individual header, while others copy all of them. The method removes all headers. The method removes a header at a particular index (shifting all headers after it). The method removes all headers with a particular name and namespace. + You can add a new header at the end of all existing headers using the method. You can use the method to insert a header at a particular index. Existing headers are shifted for the inserted item. Headers are ordered according to their index, and the first available index is 0. You can use the various method overloads to add headers from a different `Message` or `MessageHeaders` instance. Some overloads copy one individual header, while others copy all of them. The method removes all headers. The method removes a header at a particular index (shifting all headers after it). The method removes all headers with a particular name and namespace. - Retrieve a particular header using the method. This method takes the name and namespace of the header to find, and returns its index. If the header occurs more than once, an exception is thrown. If the header is not found, it returns -1. + Retrieve a particular header using the method. This method takes the name and namespace of the header to find, and returns its index. If the header occurs more than once, an exception is thrown. If the header is not found, it returns -1. In the SOAP header model, headers can have an `Actor` value that specifies the intended recipient of the header. The most basic `FindHeader` overload searches only headers intended for the ultimate receiver of the message. However, another overload enables you to specify which `Actor` values are included in the search. For more information, see the SOAP specification. A method is provided to copy headers from a collection to an array of objects. - To access the XML data in a header, you can call and return an XML reader for the specific header index. If you want to deserialize the header contents into an object, use or one of the other overloads. The most basic overloads deserialize headers using the configured in the default way. If you want to use a different serializer or a different configuration of the `DataContractSerializer`, use one of the overloads that take an `XmlObjectSerializer`. There are also overloads that take the header name, namespace, and optionally a list of `Actor` values instead of an index; this is a combination of `FindHeader` and `GetHeader`. + To access the XML data in a header, you can call and return an XML reader for the specific header index. If you want to deserialize the header contents into an object, use or one of the other overloads. The most basic overloads deserialize headers using the configured in the default way. If you want to use a different serializer or a different configuration of the `DataContractSerializer`, use one of the overloads that take an `XmlObjectSerializer`. There are also overloads that take the header name, namespace, and optionally a list of `Actor` values instead of an index; this is a combination of `FindHeader` and `GetHeader`. ## Working with Properties - A `Message` instance can contain an arbitrary number of named objects of arbitrary types. This collection is accessed through the `Properties` property of type `MessageProperties`. The collection implements the interface and acts as a mapping from to . Normally, property values do not map directly to any part of the message on the wire, but rather provide various message processing hints to the various channels in the WCF channel stack or to the service framework. For an example, see [Data Transfer Architectural Overview](data-transfer-architectural-overview.md). + A `Message` instance can contain an arbitrary number of named objects of arbitrary types. This collection is accessed through the `Properties` property of type `MessageProperties`. The collection implements the interface and acts as a mapping from to . Normally, property values do not map directly to any part of the message on the wire, but rather provide various message processing hints to the various channels in the WCF channel stack or to the service framework. For an example, see [Data Transfer Architectural Overview](data-transfer-architectural-overview.md). ## Inheriting from the Message Class @@ -187,14 +187,14 @@ The class is fundamental to Windows ### Defining the Message Body Contents - Three primary techniques exist for accessing data within a message body: writing, reading, and copying it to a buffer. These operations ultimately result in the , , and methods being called, respectively, on your derived class of `Message`. The base `Message` class guarantees that only one of these methods is called for each `Message` instance, and that it is not called more than once. The base class also ensures that the methods are not called on a closed message. There is no need to track the message state in your implementation. + Three primary techniques exist for accessing data within a message body: writing, reading, and copying it to a buffer. These operations ultimately result in the , , and methods being called, respectively, on your derived class of `Message`. The base `Message` class guarantees that only one of these methods is called for each `Message` instance, and that it is not called more than once. The base class also ensures that the methods are not called on a closed message. There is no need to track the message state in your implementation. - is an abstract method and must be implemented. The most basic way to define the body contents of your message is to write using this method. For example, the following message contains 100,000 random numbers from 1 to 20. + is an abstract method and must be implemented. The most basic way to define the body contents of your message is to write using this method. For example, the following message contains 100,000 random numbers from 1 to 20. [!code-csharp[C_UsingTheMessageClass#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_usingthemessageclass/cs/source.cs#9)] [!code-vb[C_UsingTheMessageClass#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_usingthemessageclass/vb/source.vb#9)] - The and methods have default implementations that work for most cases. The default implementations call , buffer the results, and work with the resulting buffer. However, in some cases this may not be enough. In the preceding example, reading the message results in 100,000 XML elements being buffered, which might not be desirable. You might want to override to return a custom derived class that serves up random numbers. You can then override to use the reader that the method returns, as shown in the following example. + The and methods have default implementations that work for most cases. The default implementations call , buffer the results, and work with the resulting buffer. However, in some cases this may not be enough. In the preceding example, reading the message results in 100,000 XML elements being buffered, which might not be desirable. You might want to override to return a custom derived class that serves up random numbers. You can then override to use the reader that the method returns, as shown in the following example. [!code-csharp[C_UsingTheMessageClass#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_usingthemessageclass/cs/source.cs#10)] [!code-vb[C_UsingTheMessageClass#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_usingthemessageclass/vb/source.vb#10)] @@ -207,17 +207,17 @@ The class is fundamental to Windows ### Other Members that Can Be Overridden - You can override the , , and methods to specify how the SOAP envelope, SOAP headers, and SOAP body element start tags are written out. These normally correspond to ``, ``, and ``. These methods should normally not write anything out if the property returns . + You can override the , , and methods to specify how the SOAP envelope, SOAP headers, and SOAP body element start tags are written out. These normally correspond to ``, ``, and ``. These methods should normally not write anything out if the property returns . > [!NOTE] > The default implementation of `OnGetReaderAtBodyContents` calls `OnWriteStartEnvelope` and `OnWriteStartBody` before calling `OnWriteBodyContents` and buffering the results. Headers are not written out. - Override the method to change the way the entire message is constructed from its various pieces. The `OnWriteMessage` method is called from and from the default implementation. Note that overriding is not a best practice. It is better to override the appropriate `On` methods (for example, , , and . + Override the method to change the way the entire message is constructed from its various pieces. The `OnWriteMessage` method is called from and from the default implementation. Note that overriding is not a best practice. It is better to override the appropriate `On` methods (for example, , , and . - Override to override how your message body is represented during debugging. The default is to represent it as three dots ("…"). Note that this method can be called multiple times when the message state is anything other than Closed. An implementation of this method should never cause any action that must be performed only once (such as reading from a forward-only stream). + Override to override how your message body is represented during debugging. The default is to represent it as three dots ("…"). Note that this method can be called multiple times when the message state is anything other than Closed. An implementation of this method should never cause any action that must be performed only once (such as reading from a forward-only stream). - Override the method to allow access to attributes on the SOAP body element. This method can be called any number of times, but the `Message` base type guarantees that it is only called when the message is in the Created state. It is not required to check the state in an implementation. The default implementation always returns `null`, which indicates that there are no attributes on the body element. + Override the method to allow access to attributes on the SOAP body element. This method can be called any number of times, but the `Message` base type guarantees that it is only called when the message is in the Created state. It is not required to check the state in an implementation. The default implementation always returns `null`, which indicates that there are no attributes on the body element. - If your `Message` object must do any special cleanup when the message body is no longer required, you can override . The default implementation does nothing. + If your `Message` object must do any special cleanup when the message body is no longer required, you can override . The default implementation does nothing. The `IsEmpty` and `IsFault` properties can be overridden. By default, both return `false`. diff --git a/docs/framework/wcf/feature-details/using-the-xmlserializer-class.md b/docs/framework/wcf/feature-details/using-the-xmlserializer-class.md index a5862275f0d6e..cdc40ba2c3447 100644 --- a/docs/framework/wcf/feature-details/using-the-xmlserializer-class.md +++ b/docs/framework/wcf/feature-details/using-the-xmlserializer-class.md @@ -106,13 +106,13 @@ There are three varieties of types that implement `IXmlSerializable`: types that - Element types are used when an `IXmlSerializable` type must control its own root element name. To mark a type as an element type, either set the property on the attribute to `true` or return `null` from the schema provider method. Having a schema provider method is optional for element types – you may specify `null` instead of the method name in the `XmlSchemaProviderAttribute`. However, if `IsAny` is `true` and a schema provider method is specified, the method must return `null`. -- Legacy types are `IXmlSerializable` types that are not marked with the `XmlSchemaProviderAttribute` attribute. Instead, they rely on the method for schema generation. This pattern is used for the `DataSet` type and its typed dataset derives a class in earlier versions of the .NET Framework, but is now obsolete and is supported only for legacy reasons. Do not rely on this pattern and always apply the `XmlSchemaProviderAttribute` to your `IXmlSerializable` types. +- Legacy types are `IXmlSerializable` types that are not marked with the `XmlSchemaProviderAttribute` attribute. Instead, they rely on the method for schema generation. This pattern is used for the `DataSet` type and its typed dataset derives a class in earlier versions of the .NET Framework, but is now obsolete and is supported only for legacy reasons. Do not rely on this pattern and always apply the `XmlSchemaProviderAttribute` to your `IXmlSerializable` types. ### IXmlSerializable Content Types -When serializing a data member of a type that implements `IXmlSerializable` and is a content type as defined previously, the serializer writes the wrapper element for the data member and passes control to the method. The implementation can write any XML, which includes adding attributes to the wrapper element. After `WriteXml` is done, the serializer closes the element. +When serializing a data member of a type that implements `IXmlSerializable` and is a content type as defined previously, the serializer writes the wrapper element for the data member and passes control to the method. The implementation can write any XML, which includes adding attributes to the wrapper element. After `WriteXml` is done, the serializer closes the element. -When deserializing a data member of a type that implements `IXmlSerializable` and is a content type as defined previously, the deserializer positions the XML reader on the wrapper element for the data member and passes control to the method. The method must read the entire element, including the start and end tags. Make sure your `ReadXml` code handles the case where the element is empty. Additionally, your `ReadXml` implementation should not rely on the wrapper element being named a particular way. The name is chosen by the serializer can vary. +When deserializing a data member of a type that implements `IXmlSerializable` and is a content type as defined previously, the deserializer positions the XML reader on the wrapper element for the data member and passes control to the method. The method must read the entire element, including the start and end tags. Make sure your `ReadXml` code handles the case where the element is empty. Additionally, your `ReadXml` implementation should not rely on the wrapper element being named a particular way. The name is chosen by the serializer can vary. It is permitted to assign `IXmlSerializable` content types polymorphically, for example, to data members of type . It is also permitted for the type instances to be null. Finally, it is possible to use `IXmlSerializable` types with object graph preservation enabled and with the . All these features require the WCF serializer to attach certain attributes into the wrapper element ("nil" and "type" in the XML Schema Instance namespace and "Id", "Ref", "Type" and "Assembly" in a WCF-specific namespace). @@ -124,11 +124,11 @@ Before passing control to your `ReadXml` code, the deserializer examines the XML When exporting schema and an `IXmlSerializable` content type, the schema provider method is called. An is passed to the schema provider method. The method can add any valid schema to the schema set. The schema set contains the schema that is already known at the time when schema export occurs. When the schema provider method must add an item to the schema set, it must determine whether an with the appropriate namespace already exists in the set. If it does, the schema provider method must add the new item to the existing `XmlSchema`. Otherwise, it must create a new `XmlSchema` instance. This is important if arrays of `IXmlSerializable` types are being used. For example, if you have an `IXmlSerializable` type that gets exported as type "A" in namespace "B", it is possible that by the time the schema provider method is called the schema set already contains the schema for "B" to hold the "ArrayOfA" type. -In addition to adding types to the , the schema provider method for content types must return a non-null value. It can return an that specifies the name of the schema type to use for the given `IXmlSerializable` type. This qualified name also serves as the data contract name and namespace for the type. It is permitted to return a type that does not exist in the schema set immediately when the schema provider method returns. However, it is expected that by the time all related types are exported (the method is called for all relevant types on the and the property is accessed), the type exists in the schema set. Accessing the `Schemas` property before all relevant `Export` calls have been made can result in an . For more information about the export process, see [Exporting Schemas from Classes](exporting-schemas-from-classes.md). +In addition to adding types to the , the schema provider method for content types must return a non-null value. It can return an that specifies the name of the schema type to use for the given `IXmlSerializable` type. This qualified name also serves as the data contract name and namespace for the type. It is permitted to return a type that does not exist in the schema set immediately when the schema provider method returns. However, it is expected that by the time all related types are exported (the method is called for all relevant types on the and the property is accessed), the type exists in the schema set. Accessing the `Schemas` property before all relevant `Export` calls have been made can result in an . For more information about the export process, see [Exporting Schemas from Classes](exporting-schemas-from-classes.md). The schema provider method can also return the to use. The type may or may not be anonymous. If it is anonymous, the schema for the `IXmlSerializable` type is exported as an anonymous type every time the `IXmlSerializable` type is used as a data member. The `IXmlSerializable` type still has a data contract name and namespace. (This is determined as described in [Data Contract Names](data-contract-names.md) except that the attribute cannot be used to customize the name.) If it is not anonymous, it must be one of the types in the `XmlSchemaSet`. This case is equivalent to returning the `XmlQualifiedName` of the type. -Additionally, a global element declaration is exported for the type. If the type does not have the attribute applied to it, the element has the same name and namespace as the data contract, and its "nillable" property is `true`. The only exception to this is the schema namespace (`http://www.w3.org/2001/XMLSchema`) – if the type’s data contract is in this namespace, the corresponding global element is in the blank namespace because it is forbidden to add new elements to the schema namespace. If the type has the `XmlRootAttribute` attribute applied to it, the global element declaration is exported using the following: , and properties. The defaults with `XmlRootAttribute` applied are the data contract name, a blank namespace and "nillable" being `true`. +Additionally, a global element declaration is exported for the type. If the type does not have the attribute applied to it, the element has the same name and namespace as the data contract, and its "nillable" property is `true`. The only exception to this is the schema namespace (`http://www.w3.org/2001/XMLSchema`) – if the type’s data contract is in this namespace, the corresponding global element is in the blank namespace because it is forbidden to add new elements to the schema namespace. If the type has the `XmlRootAttribute` attribute applied to it, the global element declaration is exported using the following: , and properties. The defaults with `XmlRootAttribute` applied are the data contract name, a blank namespace and "nillable" being `true`. The same global element declaration rules apply to legacy dataset types. Note that the `XmlRootAttribute` cannot override global element declarations added through custom code, either added to the `XmlSchemaSet` using the schema provider method or through `GetSchema` for legacy dataset types. @@ -144,9 +144,9 @@ Serializing and deserializing an element type is very similar to serializing and - When serializing an element type regularly (for example, as a data member in a data contract), the serializer outputs a wrapper element before calling `WriteXml`, as with content types. However, when serializing an element type at the top level, the serializer does not normally output a wrapper element at all around the element that `WriteXml` writes, unless a root name and namespace are explicitly specified when constructing the serializer in the `DataContractSerializer` or `NetDataContractSerializer` constructors. For more information, see [Serialization and Deserialization](serialization-and-deserialization.md). -- When serializing an element type at the top level without specifying the root name and namespace at construction time, and essentially do nothing and calls `WriteXml`. In this mode, the object being serialized cannot be `null` and cannot be polymorphically assigned. Also, object graph preservation cannot enabled and the `NetDataContractSerializer` cannot be used. +- When serializing an element type at the top level without specifying the root name and namespace at construction time, and essentially do nothing and calls `WriteXml`. In this mode, the object being serialized cannot be `null` and cannot be polymorphically assigned. Also, object graph preservation cannot enabled and the `NetDataContractSerializer` cannot be used. -- When deserializing an element type at the top level without specifying the root name and namespace at construction time, returns `true` if it can find the start of any element. with the `verifyObjectName` parameter set to `true` behaves in the same way as `IsStartObject` before actually reading the object. `ReadObject` then passes control to `ReadXml` method. +- When deserializing an element type at the top level without specifying the root name and namespace at construction time, returns `true` if it can find the start of any element. with the `verifyObjectName` parameter set to `true` behaves in the same way as `IsStartObject` before actually reading the object. `ReadObject` then passes control to `ReadXml` method. The schema exported for element types is the same as for the `XmlElement` type as described in an earlier section, except that the schema provider method can add any additional schema to the as with content types. Using the `XmlRootAttribute` attribute with element types is not allowed, and global element declarations are never emitted for these types. diff --git a/docs/framework/wcf/feature-details/wcf-and-internationalized-domain-names.md b/docs/framework/wcf/feature-details/wcf-and-internationalized-domain-names.md index 08d7d5f0a1e40..695e1515619b2 100644 --- a/docs/framework/wcf/feature-details/wcf-and-internationalized-domain-names.md +++ b/docs/framework/wcf/feature-details/wcf-and-internationalized-domain-names.md @@ -6,38 +6,38 @@ ms.assetid: c8a3e10a-8bc2-4a78-8d86-a562ba6e65fa --- # WCF and Internationalized Domain Names -Support has been added to allow for WCF services with Internationalized Domain Names (IDN). An internationalized domain name is a domain name that contains non-ASCII characters. This support includes both the ability to host a WCF service with an IDN name and a WCF client to talk to a web service with an IDN name. - -## System.Uri and IDN - - has two properties and . These properties contain Unicode or Punycode values depending upon the IDN configuration settings. - - IDN is enabled in an application’s configuration file using the following XML - -```xml - - - - - -``` - - The \ element contains the enabled attribute which can be set to one of the following values: - -1. "None" - -2. "AllExceptIntranet" - -3. "All" - - When the IDN setting is set to "None", no conversions are performed by Uri.Host or Uri.DnsSafeHost. When the IDN setting is set to "All", uri.Host remains Unicode and uri.DnsSafeHost is converted to Punycode. When the IDN setting is set to "AllExceptIntranet", uri.DnsSafeHost is converted to Punycode for internet addresses, and remains Unicode for intranet addresses. This setting is important for correct DNS name resolution. Note this setting is not required to be configured for Windows 8 and newer versions. - +Support has been added to allow for WCF services with Internationalized Domain Names (IDN). An internationalized domain name is a domain name that contains non-ASCII characters. This support includes both the ability to host a WCF service with an IDN name and a WCF client to talk to a web service with an IDN name. + +## System.Uri and IDN + + has two properties and . These properties contain Unicode or Punycode values depending upon the IDN configuration settings. + + IDN is enabled in an application’s configuration file using the following XML + +```xml + + + + + +``` + + The \ element contains the enabled attribute which can be set to one of the following values: + +1. "None" + +2. "AllExceptIntranet" + +3. "All" + + When the IDN setting is set to "None", no conversions are performed by Uri.Host or Uri.DnsSafeHost. When the IDN setting is set to "All", uri.Host remains Unicode and uri.DnsSafeHost is converted to Punycode. When the IDN setting is set to "AllExceptIntranet", uri.DnsSafeHost is converted to Punycode for internet addresses, and remains Unicode for intranet addresses. This setting is important for correct DNS name resolution. Note this setting is not required to be configured for Windows 8 and newer versions. + > [!WARNING] -> You should never hard-code an address using Punycode. WCF will convert it for you based on the configuration settings you apply. - +> You should never hard-code an address using Punycode. WCF will convert it for you based on the configuration settings you apply. + > [!WARNING] -> When adding Unicode characters to applicationHost.exe.config, save the file using the UTF-8 encoding. - +> When adding Unicode characters to applicationHost.exe.config, save the file using the UTF-8 encoding. + ## See also - diff --git a/docs/framework/wcf/feature-details/wcf-and-websockets.md b/docs/framework/wcf/feature-details/wcf-and-websockets.md index fc04f18f7cde5..9b8086ce5ee25 100644 --- a/docs/framework/wcf/feature-details/wcf-and-websockets.md +++ b/docs/framework/wcf/feature-details/wcf-and-websockets.md @@ -6,16 +6,16 @@ ms.assetid: 1e53b49e-022c-49c7-8984-4b21b53c05b3 --- # WCF and WebSockets -The .NET Framework 4.5 introduces support for WebSockets in Windows Communication Foundation. WebSockets is an efficient, standards-based technology that enables bidirectional communication over the standard HTTP ports 80 and 443. The use of the standard HTTP ports allow WebSockets to communicate across the web through intermediaries. Two new standard bindings have been added to support communication over a WebSocket transport. and . WebSockets-specific settings can be configured on the by accessing the property. - -## In This Section +The .NET Framework 4.5 introduces support for WebSockets in Windows Communication Foundation. WebSockets is an efficient, standards-based technology that enables bidirectional communication over the standard HTTP ports 80 and 443. The use of the standard HTTP ports allow WebSockets to communicate across the web through intermediaries. Two new standard bindings have been added to support communication over a WebSocket transport. and . WebSockets-specific settings can be configured on the by accessing the property. + +## In This Section + + [Using the NetHttpBinding](using-the-nethttpbinding.md) + Discusses the and how to configure it. + + [How to: Create a WCF Service that Communicates over WebSockets](how-to-create-a-wcf-service-that-communicates-over-websockets.md) + Describes how to create a WCF service that communicates over Websockets. + +## Reference - [Using the NetHttpBinding](using-the-nethttpbinding.md) - Discusses the and how to configure it. - - [How to: Create a WCF Service that Communicates over WebSockets](how-to-create-a-wcf-service-that-communicates-over-websockets.md) - Describes how to create a WCF service that communicates over Websockets. - -## Reference - ## Related Sections diff --git a/docs/framework/wcf/feature-details/wcf-discovery-object-model.md b/docs/framework/wcf/feature-details/wcf-discovery-object-model.md index 449af14566a41..d81906ef7251c 100644 --- a/docs/framework/wcf/feature-details/wcf-discovery-object-model.md +++ b/docs/framework/wcf/feature-details/wcf-discovery-object-model.md @@ -14,7 +14,7 @@ WCF Discovery consists of a set of types that provide a unified programming mode A client that wants to listen for service announcement messages hosts an announcement service and adds one or more announcement endpoints. The announcement service receives announcement messages and raises announcement events. - A client uses the class to search for available services. The client application instantiates the class, passing in a discovery endpoint that specifies where to send discovery messages. The client calls the method, which sends a `Probe` request. Services listening for discovery messages receive this `Probe` request. If the service matches the criteria specified in the `Probe`, it sends a `ProbeMatch` message back to the client. + A client uses the class to search for available services. The client application instantiates the class, passing in a discovery endpoint that specifies where to send discovery messages. The client calls the method, which sends a `Probe` request. Services listening for discovery messages receive this `Probe` request. If the service matches the criteria specified in the `Probe`, it sends a `ProbeMatch` message back to the client. ## Object Model @@ -74,7 +74,7 @@ WCF Discovery consists of a set of types that provide a unified programming mode ## AnnouncementService - is a system-provided implementation of an announcement service that receives and processes announcement messages. When a Hello or Bye message is received, the instance calls the appropriate virtual method or , which raises announcement events. + is a system-provided implementation of an announcement service that receives and processes announcement messages. When a Hello or Bye message is received, the instance calls the appropriate virtual method or , which raises announcement events. ## DiscoveryClient @@ -96,7 +96,7 @@ WCF Discovery consists of a set of types that provide a unified programming mode ## DiscoveryService - The abstract class provides a framework for receiving and processing `Probe` and `Resolve` messages. When a `Probe` message is received, creates an instance of based on the incoming message and invokes the virtual method. When a `Resolve` message is received, invokes the virtual method. You can inherit from this class to provide a custom Discovery Service implementation. + The abstract class provides a framework for receiving and processing `Probe` and `Resolve` messages. When a `Probe` message is received, creates an instance of based on the incoming message and invokes the virtual method. When a `Resolve` message is received, invokes the virtual method. You can inherit from this class to provide a custom Discovery Service implementation. ## DiscoveryProxy @@ -116,7 +116,7 @@ WCF Discovery consists of a set of types that provide a unified programming mode ## FindCriteria - The class is a version-independent class used to specify the criteria used when finding a service. It fully supports the WS-Discovery-defined criteria for matching services. It also has extensions that developers can use to specify custom values that can be used during the matching process. The developer can provide the termination criteria for the `Find` operation by specifying the , which specifies the total number of services the developer is looking for or that specifies the , which is the value that specifies how long the client waits for responses. + The class is a version-independent class used to specify the criteria used when finding a service. It fully supports the WS-Discovery-defined criteria for matching services. It also has extensions that developers can use to specify custom values that can be used during the matching process. The developer can provide the termination criteria for the `Find` operation by specifying the , which specifies the total number of services the developer is looking for or that specifies the , which is the value that specifies how long the client waits for responses. ## FindRequestContext @@ -124,15 +124,15 @@ WCF Discovery consists of a set of types that provide a unified programming mode ## FindResponse - The class is returned to the caller of with the responses of the `Find` operation. It is also present in . It contains a collection of , which is the collection of discovered endpoints and a dictionary of and . + The class is returned to the caller of with the responses of the `Find` operation. It is also present in . It contains a collection of , which is the collection of discovered endpoints and a dictionary of and . ## ResolveCriteria - The class is a version-independent class used to specify the criteria used when resolving an already known service. It contains the endpoint address of the known service. The developer can provide the termination criteria for the resolve operation by specifying the , which specifies how long the client waits for responses. + The class is a version-independent class used to specify the criteria used when resolving an already known service. It contains the endpoint address of the known service. The developer can provide the termination criteria for the resolve operation by specifying the , which specifies how long the client waits for responses. ## ResolveResponse - The is returned to the caller of the method with the response of the `Resolve` operation. It is also present in . It contains an instance of , which is the discovered endpoints and an instance of . + The is returned to the caller of the method with the response of the `Resolve` operation. It is also present in . It contains an instance of , which is the discovered endpoints and an instance of . ## ServiceDiscoveryBehavior diff --git a/docs/framework/wcf/feature-details/wcf-discovery-overview.md b/docs/framework/wcf/feature-details/wcf-discovery-overview.md index e0711b37f2c85..87c5416b9fb4c 100644 --- a/docs/framework/wcf/feature-details/wcf-discovery-overview.md +++ b/docs/framework/wcf/feature-details/wcf-discovery-overview.md @@ -6,29 +6,29 @@ ms.assetid: 84fad0e4-23b1-45b5-a2d4-c9cdf90bbb22 --- # WCF Discovery Overview -The Discovery APIs provide a unified programming model for the dynamic publication and discovery of Web services using the WS-Discovery protocol. These APIs allow services to publish themselves and clients to find published services. Once a service is made discoverable, the service has the ability to send announcement messages as well as listen for and respond to discovery requests. Discoverable services can send Hello messages to announce their arrival on a network and Bye messages to announce their departure from a network. To find a service, clients send a `Probe` request that contains specific criteria such as service contract type, keywords, and scope on the network. Services receive the `Probe` request and determine whether they match the criteria. If a service matches, it responds by sending a `ProbeMatch` message back to the client with the information necessary to contact the service. Clients can also send `Resolve` requests that allow them to find services that may have changed their endpoint address. Matching services respond to `Resolve` requests by sending a `ResolveMatch` message back to the client. - -## Ad-Hoc and Managed Modes - - The Discovery API supports two different modes: Managed and Ad-Hoc. In Managed mode there is a centralized server called a discovery proxy that maintains information about available services. The discovery proxy can be populated with information about services in a variety of ways. For example, services can send announcement messages during start up to the discovery proxy or the proxy may read data from a database or a configuration file to determine what services are available. How the discovery proxy is populated is completely up to the developer. Clients use the discovery proxy to retrieve information about available services. When a client searches for a service it sends a `Probe` message to the discovery proxy and the proxy determines whether any of the services it knows about match the service the client is searching for. If there are matches the discovery proxy sends a `ProbeMatch` response back to the client. The client can then contact the service directly using the service information returned from the proxy. The key principle behind Managed mode is that the discovery requests are sent in a unicast manner to one authority, the discovery proxy. The .NET Framework contains key components that allow you to build your own proxy. Clients and services can locate the proxy by multiple methods: - -- The proxy can respond to ad-hoc messages. - -- The proxy can send an announcement message during start up. - -- Clients and services can be written to look for a specific well-known endpoint. - - In Ad-Hoc mode, there is no centralized server. All discovery messages such as service announcements and client requests are sent in a multicast fashion. By default the .NET Framework contains support for Ad-Hoc discovery over the UDP protocol. For example, if a service is configured to send out a Hello announcement on start up, it sends it out over a well-known, multicast address using the UDP protocol. Clients have to actively listen for these announcements and process them accordingly. When a client sends a `Probe` message for a service it is sent over the network using a multicast protocol. Each service that receives the request determines whether it matches the criteria in the `Probe` message and responds directly to the client with a `ProbeMatch` message if the service matches the criteria specified in the `Probe` message. - -## Benefits of Using WCF Discovery - - Because WCF Discovery is implemented using the WS-Discovery protocol it is interoperable with other clients, services, and proxies that implement WS-Discovery as well. WCF Discovery is built upon the existing WCF APIs, which makes it easy to add Discovery functionality to your existing services and clients. Service discoverability can be easily added through the application configuration settings. In addition, WCF Discovery also supports using the discovery protocol over other transports such as peer net, naming overlay, and HTTP. WCF Discovery provides support for a Managed mode of operation where a discovery proxy is used. This can reduce network traffic as messages are sent directly to the discovery proxy instead of sending multicast messages to the entire network. WCF Discovery also allows for more flexibility when working with Web services. For example, you can change the address of a service without having to reconfigure the client or the service. When a client must access the service it can issue a `Probe` message through a `Find` request and expect the service to respond with its current address. WCF Discovery allows a client to search for a service based on different criteria including contract types, binding elements, namespace, scope, and keywords or version numbers. WCF Discovery enables runtime and design time discovery. Adding discovery to your application can be used to enable other scenarios such as fault tolerance and auto configuration. - -## Service Publication - - To make a service discoverable, a must be added to the service host and a discovery endpoint must be added to specify where to listen for discovery messages. The following code example shows how a self-hosted service can be modified to make it discoverable. - -```csharp +The Discovery APIs provide a unified programming model for the dynamic publication and discovery of Web services using the WS-Discovery protocol. These APIs allow services to publish themselves and clients to find published services. Once a service is made discoverable, the service has the ability to send announcement messages as well as listen for and respond to discovery requests. Discoverable services can send Hello messages to announce their arrival on a network and Bye messages to announce their departure from a network. To find a service, clients send a `Probe` request that contains specific criteria such as service contract type, keywords, and scope on the network. Services receive the `Probe` request and determine whether they match the criteria. If a service matches, it responds by sending a `ProbeMatch` message back to the client with the information necessary to contact the service. Clients can also send `Resolve` requests that allow them to find services that may have changed their endpoint address. Matching services respond to `Resolve` requests by sending a `ResolveMatch` message back to the client. + +## Ad-Hoc and Managed Modes + + The Discovery API supports two different modes: Managed and Ad-Hoc. In Managed mode there is a centralized server called a discovery proxy that maintains information about available services. The discovery proxy can be populated with information about services in a variety of ways. For example, services can send announcement messages during start up to the discovery proxy or the proxy may read data from a database or a configuration file to determine what services are available. How the discovery proxy is populated is completely up to the developer. Clients use the discovery proxy to retrieve information about available services. When a client searches for a service it sends a `Probe` message to the discovery proxy and the proxy determines whether any of the services it knows about match the service the client is searching for. If there are matches the discovery proxy sends a `ProbeMatch` response back to the client. The client can then contact the service directly using the service information returned from the proxy. The key principle behind Managed mode is that the discovery requests are sent in a unicast manner to one authority, the discovery proxy. The .NET Framework contains key components that allow you to build your own proxy. Clients and services can locate the proxy by multiple methods: + +- The proxy can respond to ad-hoc messages. + +- The proxy can send an announcement message during start up. + +- Clients and services can be written to look for a specific well-known endpoint. + + In Ad-Hoc mode, there is no centralized server. All discovery messages such as service announcements and client requests are sent in a multicast fashion. By default the .NET Framework contains support for Ad-Hoc discovery over the UDP protocol. For example, if a service is configured to send out a Hello announcement on start up, it sends it out over a well-known, multicast address using the UDP protocol. Clients have to actively listen for these announcements and process them accordingly. When a client sends a `Probe` message for a service it is sent over the network using a multicast protocol. Each service that receives the request determines whether it matches the criteria in the `Probe` message and responds directly to the client with a `ProbeMatch` message if the service matches the criteria specified in the `Probe` message. + +## Benefits of Using WCF Discovery + + Because WCF Discovery is implemented using the WS-Discovery protocol it is interoperable with other clients, services, and proxies that implement WS-Discovery as well. WCF Discovery is built upon the existing WCF APIs, which makes it easy to add Discovery functionality to your existing services and clients. Service discoverability can be easily added through the application configuration settings. In addition, WCF Discovery also supports using the discovery protocol over other transports such as peer net, naming overlay, and HTTP. WCF Discovery provides support for a Managed mode of operation where a discovery proxy is used. This can reduce network traffic as messages are sent directly to the discovery proxy instead of sending multicast messages to the entire network. WCF Discovery also allows for more flexibility when working with Web services. For example, you can change the address of a service without having to reconfigure the client or the service. When a client must access the service it can issue a `Probe` message through a `Find` request and expect the service to respond with its current address. WCF Discovery allows a client to search for a service based on different criteria including contract types, binding elements, namespace, scope, and keywords or version numbers. WCF Discovery enables runtime and design time discovery. Adding discovery to your application can be used to enable other scenarios such as fault tolerance and auto configuration. + +## Service Publication + + To make a service discoverable, a must be added to the service host and a discovery endpoint must be added to specify where to listen for discovery messages. The following code example shows how a self-hosted service can be modified to make it discoverable. + +```csharp Uri baseAddress = new Uri($"http://{System.Net.Dns.GetHostName()}:8000/discovery/scenarios/calculatorservice/{Guid.NewGuid().ToString()}/"); // Create a ServiceHost for the CalculatorService type. @@ -52,15 +52,15 @@ using (ServiceHost serviceHost = new ServiceHost(typeof(CalculatorService), base Console.WriteLine("Press to terminate service."); Console.ReadLine(); } -``` - - A instance must be added to a service description for the service to be discoverable. A instance must be added to the service host to tell the service where to listen for discovery requests. In this example, a (which is derived from ) is added to specify that the service should listen for discovery requests over the UDP multicast transport. The is used for Ad-Hoc discovery because all messages are sent in a multicast fashion. - -## Announcement - - By default, service publication does not send out announcement messages. The service must be configured to send out announcement messages. This provides additional flexibility for service writers because they can announce the service separately from listening for discovery messages. Service announcement can also be used as a mechanism for registering services with a discovery proxy or other service registries. The following code shows how to configure a service to send announcement messages over a UDP binding. - -```csharp +``` + + A instance must be added to a service description for the service to be discoverable. A instance must be added to the service host to tell the service where to listen for discovery requests. In this example, a (which is derived from ) is added to specify that the service should listen for discovery requests over the UDP multicast transport. The is used for Ad-Hoc discovery because all messages are sent in a multicast fashion. + +## Announcement + + By default, service publication does not send out announcement messages. The service must be configured to send out announcement messages. This provides additional flexibility for service writers because they can announce the service separately from listening for discovery messages. Service announcement can also be used as a mechanism for registering services with a discovery proxy or other service registries. The following code shows how to configure a service to send announcement messages over a UDP binding. + +```csharp Uri baseAddress = new Uri($"http://{System.Net.Dns.GetHostName()}:8000/discovery/scenarios/calculatorservice/{Guid.NewGuid().ToString()}/"); // Create a ServiceHost for the CalculatorService type. @@ -89,76 +89,76 @@ using (ServiceHost serviceHost = new ServiceHost(typeof(CalculatorService), base Console.WriteLine("Press to terminate service."); Console.ReadLine(); } -``` - -## Service Discovery +``` + +## Service Discovery - A client application can use the class to find services. The developer creates an instance of the class that passes in a discovery endpoint that specifies where to send `Probe` or `Resolve` messages. The client then calls that specifies search criteria within a instance. If matching services are found, returns a collection of . The following code shows how to call the `Find` method and then connect to a discovered service. - -```csharp + A client application can use the class to find services. The developer creates an instance of the class that passes in a discovery endpoint that specifies where to send `Probe` or `Resolve` messages. The client then calls that specifies search criteria within a instance. If matching services are found, returns a collection of . The following code shows how to call the `Find` method and then connect to a discovered service. + +```csharp class Client { static EndpointAddress serviceAddress; - + static void Main() - { + { if (FindService()) { InvokeService(); } - } - - // ** DISCOVERY ** // - static bool FindService() - { - Console.WriteLine("\nFinding Calculator Service .."); + } + + // ** DISCOVERY ** // + static bool FindService() + { + Console.WriteLine("\nFinding Calculator Service .."); DiscoveryClient discoveryClient = - new DiscoveryClient(new UdpDiscoveryEndpoint()); - + new DiscoveryClient(new UdpDiscoveryEndpoint()); + Collection calculatorServices = - (Collection)discoveryClient.Find(new FindCriteria(typeof(ICalculator))).Endpoints; - - discoveryClient.Close(); - - if (calculatorServices.Count == 0) - { - Console.WriteLine("\nNo services are found."); - return false; - } - else - { - serviceAddress = calculatorServices[0].Address; - return true; - } - } - - static void InvokeService() - { - Console.WriteLine("\nInvoking Calculator Service at {0}\n", serviceAddress); - - // Create a client - CalculatorClient client = new CalculatorClient(); - client.Endpoint.Address = serviceAddress; - client.Add(10,3); + (Collection)discoveryClient.Find(new FindCriteria(typeof(ICalculator))).Endpoints; + + discoveryClient.Close(); + + if (calculatorServices.Count == 0) + { + Console.WriteLine("\nNo services are found."); + return false; + } + else + { + serviceAddress = calculatorServices[0].Address; + return true; + } + } + + static void InvokeService() + { + Console.WriteLine("\nInvoking Calculator Service at {0}\n", serviceAddress); + + // Create a client + CalculatorClient client = new CalculatorClient(); + client.Endpoint.Address = serviceAddress; + client.Add(10,3); } -} -``` - -## Discovery and Message Level Security - - When using message level security it is necessary to specify an on the service discovery endpoint and a matching on the client discovery endpoint. For more information about message level security, see [Message Security](message-security-in-wcf.md). - -## Discovery and Web Hosted Services - - In order for WCF services to be discoverable they must be running. WCF services hosted under IIS or WAS do not run until IIS/WAS receives a message bound for the service, so they cannot be discoverable by default. There are two options for making Web-Hosted services discoverable: - -1. Use the Windows Server AppFabric Auto-Start feature - -2. Use a discovery proxy to communicate on behalf of the service - - Windows Server AppFabric has an Auto-Start feature that will allow a service to be started before receiving any messages. With this Auto-Start set, an IIS/WAS hosted service can be configured to be discoverable. For more information about the Auto-Start feature see, [Windows Server AppFabric Auto-Start Feature](/previous-versions/appfabric/ee677260(v=azure.10)). Along with turning on the Auto-Start feature, you must configure the service for discovery. For more information, see [How to: Programmatically Add Discoverability to a WCF Service and Client](how-to-programmatically-add-discoverability-to-a-wcf-service-and-client.md)[Configuring Discovery in a Configuration File](configuring-discovery-in-a-configuration-file.md). - - A discovery proxy can be used to communicate on behalf of the WCF service when the service is not running. The proxy can listen for probe or resolve messages and respond to the client. The client can then send messages directly to the service. When the client sends a message to the service it will be instantiated to respond to the message. For more information about implementing a discovery proxy see, [Implementing a Discovery Proxy](implementing-a-discovery-proxy.md). - +} +``` + +## Discovery and Message Level Security + + When using message level security it is necessary to specify an on the service discovery endpoint and a matching on the client discovery endpoint. For more information about message level security, see [Message Security](message-security-in-wcf.md). + +## Discovery and Web Hosted Services + + In order for WCF services to be discoverable they must be running. WCF services hosted under IIS or WAS do not run until IIS/WAS receives a message bound for the service, so they cannot be discoverable by default. There are two options for making Web-Hosted services discoverable: + +1. Use the Windows Server AppFabric Auto-Start feature + +2. Use a discovery proxy to communicate on behalf of the service + + Windows Server AppFabric has an Auto-Start feature that will allow a service to be started before receiving any messages. With this Auto-Start set, an IIS/WAS hosted service can be configured to be discoverable. For more information about the Auto-Start feature see, [Windows Server AppFabric Auto-Start Feature](/previous-versions/appfabric/ee677260(v=azure.10)). Along with turning on the Auto-Start feature, you must configure the service for discovery. For more information, see [How to: Programmatically Add Discoverability to a WCF Service and Client](how-to-programmatically-add-discoverability-to-a-wcf-service-and-client.md)[Configuring Discovery in a Configuration File](configuring-discovery-in-a-configuration-file.md). + + A discovery proxy can be used to communicate on behalf of the WCF service when the service is not running. The proxy can listen for probe or resolve messages and respond to the client. The client can then send messages directly to the service. When the client sends a message to the service it will be instantiated to respond to the message. For more information about implementing a discovery proxy see, [Implementing a Discovery Proxy](implementing-a-discovery-proxy.md). + > [!NOTE] > For WCF Discovery to work correctly, all NICs (Network Interface Controller) should only have 1 IP address. diff --git a/docs/framework/wcf/feature-details/wcf-services-and-aspnet.md b/docs/framework/wcf/feature-details/wcf-services-and-aspnet.md index 00ea0f46123b3..593be349ccc3a 100644 --- a/docs/framework/wcf/feature-details/wcf-services-and-aspnet.md +++ b/docs/framework/wcf/feature-details/wcf-services-and-aspnet.md @@ -24,7 +24,7 @@ The results of the side-by-side model are as follows: - Within an AppDomain, features implemented by the HTTP runtime apply to ASP.NET content but not to WCF. Many HTTP-specific features of the ASP.NET application platform do not apply to WCF Services hosted inside of an AppDomain that contains ASP.NET content. Examples of these features include the following: - - HttpContext: is always `null` when accessed from within a WCF service. Use instead. + - HttpContext: is always `null` when accessed from within a WCF service. Use instead. - File-based authorization: The WCF security model does not allow for the access control list (ACL) applied to the .svc file of the service when deciding if a service request is authorized. @@ -54,7 +54,7 @@ Although the WCF model is designed to behave consistently across hosting environ Unlike the default side-by-side configuration, where the WCF hosting infrastructure intercepts WCF messages and routes them out of the HTTP pipeline, WCF services running in ASP.NET Compatibility Mode participate fully in the ASP.NET HTTP request lifecycle. In compatibility mode, WCF services use the HTTP pipeline through an implementation, similar to the way requests for ASPX pages and ASMX Web services are handled. As a result, WCF behaves identically to ASMX with respect to the following ASP.NET features: -- : WCF services running in ASP.NET Compatibility Mode can access and its associated state. +- : WCF services running in ASP.NET Compatibility Mode can access and its associated state. - File-based authorization: WCF services running in ASP.NET compatibility mode can be secure by attaching file system access control lists (ACLs) to the service’s .svc file. diff --git a/docs/framework/wcf/feature-details/wcf-web-http-error-handling.md b/docs/framework/wcf/feature-details/wcf-web-http-error-handling.md index 780148ca4455a..4b3a91acf4ac3 100644 --- a/docs/framework/wcf/feature-details/wcf-web-http-error-handling.md +++ b/docs/framework/wcf/feature-details/wcf-web-http-error-handling.md @@ -6,49 +6,49 @@ ms.assetid: 02891563-0fce-4c32-84dc-d794b1a5c040 --- # WCF Web HTTP Error Handling -Windows Communication Foundation (WCF) Web HTTP error handling enables you to return errors from WCF Web HTTP services that specify an HTTP status code and return error details using the same format as the operation (for example, XML or JSON). - -## WCF Web HTTP Error Handling +Windows Communication Foundation (WCF) Web HTTP error handling enables you to return errors from WCF Web HTTP services that specify an HTTP status code and return error details using the same format as the operation (for example, XML or JSON). + +## WCF Web HTTP Error Handling + + The class defines a constructor that allows you to specify an HTTP status code. This status code is then returned to the client. A generic version of the class, enables you to return a user-defined type that contains information about the error that occurred. This custom object is serialized using the format specified by the operation and returned to the client. The following example shows how to return an HTTP status code. - The class defines a constructor that allows you to specify an HTTP status code. This status code is then returned to the client. A generic version of the class, enables you to return a user-defined type that contains information about the error that occurred. This custom object is serialized using the format specified by the operation and returned to the client. The following example shows how to return an HTTP status code. - ```csharp public string Operation1() { - // Operation logic + // Operation logic // ... throw new WebFaultException(HttpStatusCode.Forbidden); -} -``` - - The following example shows how to return an HTTP status code and extra information in a user-defined type. `MyErrorDetail` is a user-defined type that contains extra information about the error that occurred. - +} +``` + + The following example shows how to return an HTTP status code and extra information in a user-defined type. `MyErrorDetail` is a user-defined type that contains extra information about the error that occurred. + ```csharp public string Operation2() { - // Operation logic + // Operation logic // ... MyErrorDetail detail = new MyErrorDetail() - { - Message = "Error Message", - ErrorCode = 123, - } - throw new WebFaultException(detail, HttpStatusCode.Forbidden); -} -``` - - The preceding code returns an HTTP response with the forbidden status code and a body that contains an instance of the `MyErrorDetails` object. The format of the `MyErrorDetails` object is determined by: - -- The value of the `ResponseFormat` parameter of the or attribute specified on the service operation. - -- The value of . - -- The value of the property by accessing the . - - For more information about how these values affect the formatting of the operation, see [WCF Web HTTP Formatting](wcf-web-http-formatting.md). - - is a and therefore can be used as the fault exception programming model for services that expose SOAP endpoints as well as web HTTP endpoints. - + { + Message = "Error Message", + ErrorCode = 123, + } + throw new WebFaultException(detail, HttpStatusCode.Forbidden); +} +``` + + The preceding code returns an HTTP response with the forbidden status code and a body that contains an instance of the `MyErrorDetails` object. The format of the `MyErrorDetails` object is determined by: + +- The value of the `ResponseFormat` parameter of the or attribute specified on the service operation. + +- The value of . + +- The value of the property by accessing the . + + For more information about how these values affect the formatting of the operation, see [WCF Web HTTP Formatting](wcf-web-http-formatting.md). + + is a and therefore can be used as the fault exception programming model for services that expose SOAP endpoints as well as web HTTP endpoints. + ## See also - [WCF Web HTTP Programming Model](wcf-web-http-programming-model.md) diff --git a/docs/framework/wcf/feature-details/wcf-web-http-formatting.md b/docs/framework/wcf/feature-details/wcf-web-http-formatting.md index 70558534159b2..d8b111fe53beb 100644 --- a/docs/framework/wcf/feature-details/wcf-web-http-formatting.md +++ b/docs/framework/wcf/feature-details/wcf-web-http-formatting.md @@ -6,161 +6,161 @@ ms.assetid: e2414896-5463-41cd-b0a6-026a713eac2c --- # WCF Web HTTP formatting -The WCF Web HTTP programming model allows you to dynamically determine the best format for a service operation to return its response in. Two methods for determining an appropriate format are supported: automatic and explicit. - -## Automatic formatting - - When enabled, automatic formatting chooses the best format in which to return the response. It determines the best format by checking the following, in order: - -1. The media types in the request message’s Accept header. - -2. The content-type of the request message. - -3. The default format setting in the operation. - -4. The default format setting in the WebHttpBehavior. - - If the request message contains an Accept header the Windows Communication Foundation (WCF) infrastructure searches for a type that it supports. If the `Accept` header specifies priorities for its media types, they are honored. If no suitable format is found in the `Accept` header, the content-type of the request message is used. If no suitable content-type is specified, the default format setting for the operation is used. The default format is set with the `ResponseFormat` parameter of the and attributes. If no default format is specified on the operation, the value of the property is used. Automatic formatting relies on the property. When this property is set to `true`, the WCF infrastructure determines the best format to use. Automatic format selection is disabled by default for backwards compatibility. Automatic format selection can be enabled programmatically or through configuration. The following example shows how to enable automatic format selection in code. - +The WCF Web HTTP programming model allows you to dynamically determine the best format for a service operation to return its response in. Two methods for determining an appropriate format are supported: automatic and explicit. + +## Automatic formatting + + When enabled, automatic formatting chooses the best format in which to return the response. It determines the best format by checking the following, in order: + +1. The media types in the request message’s Accept header. + +2. The content-type of the request message. + +3. The default format setting in the operation. + +4. The default format setting in the WebHttpBehavior. + + If the request message contains an Accept header the Windows Communication Foundation (WCF) infrastructure searches for a type that it supports. If the `Accept` header specifies priorities for its media types, they are honored. If no suitable format is found in the `Accept` header, the content-type of the request message is used. If no suitable content-type is specified, the default format setting for the operation is used. The default format is set with the `ResponseFormat` parameter of the and attributes. If no default format is specified on the operation, the value of the property is used. Automatic formatting relies on the property. When this property is set to `true`, the WCF infrastructure determines the best format to use. Automatic format selection is disabled by default for backwards compatibility. Automatic format selection can be enabled programmatically or through configuration. The following example shows how to enable automatic format selection in code. + ```csharp // This code assumes the service name is MyService and the service contract is IMyContract -Uri baseAddress = new Uri("http://localhost:8000"); - -WebServiceHost host = new WebServiceHost(typeof(MyService), baseAddress) -try -{ - ServiceEndpoint sep = host.AddServiceEndpoint(typeof(IMyContract), new WebHttpBinding(), ""); - // Check it see if the WebHttpBehavior already exists - WebHttpBehavior whb = sep.Behaviors.Find(); - - if (whb != null) - { - whb.AutomaticFormatSelectionEnabled = true; - } - else - { - WebHttpBehavior webBehavior = new WebHttpBehavior(); - webBehavior.AutomaticFormatSelectionEnabled = true; - sep.Behaviors.Add(webBehavior); - } - // Open host to start listening for messages +Uri baseAddress = new Uri("http://localhost:8000"); + +WebServiceHost host = new WebServiceHost(typeof(MyService), baseAddress) +try +{ + ServiceEndpoint sep = host.AddServiceEndpoint(typeof(IMyContract), new WebHttpBinding(), ""); + // Check it see if the WebHttpBehavior already exists + WebHttpBehavior whb = sep.Behaviors.Find(); + + if (whb != null) + { + whb.AutomaticFormatSelectionEnabled = true; + } + else + { + WebHttpBehavior webBehavior = new WebHttpBehavior(); + webBehavior.AutomaticFormatSelectionEnabled = true; + sep.Behaviors.Add(webBehavior); + } + // Open host to start listening for messages host.Open(); - - // ... -} - catch(CommunicationException ex) - { - Console.WriteLine("An exception occurred: " + ex.Message()); - } -``` - - Automatic formatting can also be enabled through configuration. You can set the property directly on the or using the . The following example shows how to enable the automatic format selection on the . - -```xml - - - - - - - - - - - - - - - -``` - - The following example shows how to enable automatic format selection using . - -```xml - - - - - - - - -``` - -## Explicit formatting - - As the name implies, in explicit formatting the developer determines the best format to use within the operation code. If the best format is XML or JSON the developer sets to either or . If the property is not explicitly set, then the operation’s default format is used. - - The following example checks the format query string parameter for a format to use. If it has been specified, it sets the operation’s format using . - + + // ... +} + catch(CommunicationException ex) + { + Console.WriteLine("An exception occurred: " + ex.Message()); + } +``` + + Automatic formatting can also be enabled through configuration. You can set the property directly on the or using the . The following example shows how to enable the automatic format selection on the . + +```xml + + + + + + + + + + + + + + + +``` + + The following example shows how to enable automatic format selection using . + +```xml + + + + + + + + +``` + +## Explicit formatting + + As the name implies, in explicit formatting the developer determines the best format to use within the operation code. If the best format is XML or JSON the developer sets to either or . If the property is not explicitly set, then the operation’s default format is used. + + The following example checks the format query string parameter for a format to use. If it has been specified, it sets the operation’s format using . + ```csharp -public class Service : IService -{ - [WebGet] - public string EchoWithGet(string s) - { +public class Service : IService +{ + [WebGet] + public string EchoWithGet(string s) + { // if a format query string parameter has been specified, set the response format to that. If no such // query string parameter exists the Accept header will be used - string formatQueryStringValue = WebOperationContext.Current.IncomingRequest.UriTemplateMatch.QueryParameters["format"]; - if (!string.IsNullOrEmpty(formatQueryStringValue)) - { - if (formatQueryStringValue.Equals("xml", System.StringComparison.OrdinalIgnoreCase)) + string formatQueryStringValue = WebOperationContext.Current.IncomingRequest.UriTemplateMatch.QueryParameters["format"]; + if (!string.IsNullOrEmpty(formatQueryStringValue)) + { + if (formatQueryStringValue.Equals("xml", System.StringComparison.OrdinalIgnoreCase)) { WebOperationContext.Current.OutgoingResponse.Format = WebMessageFormat.Xml; } - else if (formatQueryStringValue.Equals("json", System.StringComparison.OrdinalIgnoreCase)) - { - WebOperationContext.Current.OutgoingResponse.Format = WebMessageFormat.Json; - } - else - { + else if (formatQueryStringValue.Equals("json", System.StringComparison.OrdinalIgnoreCase)) + { + WebOperationContext.Current.OutgoingResponse.Format = WebMessageFormat.Json; + } + else + { throw new WebFaultException($"Unsupported format '{formatQueryStringValue}'", HttpStatusCode.BadRequest); - } - } - return "You said " + s; - } -``` - - If you need to support formats other than XML or JSON, define your operation to have a return type of . Within the operation code, determine the appropriate format to use and then create a object using one of the following methods: - -- `WebOperationContext.CreateAtom10Response` - -- `WebOperationContext.CreateJsonResponse` - -- `WebOperationContext.CreateStreamResponse` - -- `WebOperationContext.CreateTextResponse` - -- `WebOperationContext.CreateXmlResponse` - - Each of these methods takes content and creates a message with the appropriate format. The `WebOperationContext.Current.IncomingRequest.GetAcceptHeaderElements` method can be used to get a list of formats preferred by the client in order of decreasing preference. The following example shows how to use `WebOperationContext.Current.IncomingRequest.GetAcceptHeaderElements` to determine the format to use and then uses the appropriate create response method to create the response message. - + } + } + return "You said " + s; + } +``` + + If you need to support formats other than XML or JSON, define your operation to have a return type of . Within the operation code, determine the appropriate format to use and then create a object using one of the following methods: + +- `WebOperationContext.CreateAtom10Response` + +- `WebOperationContext.CreateJsonResponse` + +- `WebOperationContext.CreateStreamResponse` + +- `WebOperationContext.CreateTextResponse` + +- `WebOperationContext.CreateXmlResponse` + + Each of these methods takes content and creates a message with the appropriate format. The `WebOperationContext.Current.IncomingRequest.GetAcceptHeaderElements` method can be used to get a list of formats preferred by the client in order of decreasing preference. The following example shows how to use `WebOperationContext.Current.IncomingRequest.GetAcceptHeaderElements` to determine the format to use and then uses the appropriate create response method to create the response message. + ```csharp -public class Service : IService -{ - public Message EchoListWithGet(string list) - { - List returnList = new List(list.Split(new char[] { ',' }, StringSplitOptions.RemoveEmptyEntries)); - IList acceptHeaderElements = WebOperationContext.Current.IncomingRequest.GetAcceptHeaderElements(); - for (int x = 0; x < acceptHeaderElements.Count; x++) - { - string normalizedMediaType = acceptHeaderElements[x].MediaType.ToLowerInvariant(); - switch (normalizedMediaType) - { - case "image/jpeg": return CreateJpegResponse(returnList); - case "application/xhtml+xml": return CreateXhtmlResponse(returnList); - case "application/atom+xml": return CreateAtom10Response(returnList); - case "application/xml": return CreateXmlResponse(returnList); - case "application/json": return CreateJsonResponse(returnList); - } - } - - // Default response format is XML - return CreateXmlResponse(returnList); - } -} -``` - +public class Service : IService +{ + public Message EchoListWithGet(string list) + { + List returnList = new List(list.Split(new char[] { ',' }, StringSplitOptions.RemoveEmptyEntries)); + IList acceptHeaderElements = WebOperationContext.Current.IncomingRequest.GetAcceptHeaderElements(); + for (int x = 0; x < acceptHeaderElements.Count; x++) + { + string normalizedMediaType = acceptHeaderElements[x].MediaType.ToLowerInvariant(); + switch (normalizedMediaType) + { + case "image/jpeg": return CreateJpegResponse(returnList); + case "application/xhtml+xml": return CreateXhtmlResponse(returnList); + case "application/atom+xml": return CreateAtom10Response(returnList); + case "application/xml": return CreateXmlResponse(returnList); + case "application/json": return CreateJsonResponse(returnList); + } + } + + // Default response format is XML + return CreateXmlResponse(returnList); + } +} +``` + ## See also - diff --git a/docs/framework/wcf/feature-details/wcf-web-http-programming-model-overview.md b/docs/framework/wcf/feature-details/wcf-web-http-programming-model-overview.md index 4a247e5800117..1d0ba5b4541e6 100644 --- a/docs/framework/wcf/feature-details/wcf-web-http-programming-model-overview.md +++ b/docs/framework/wcf/feature-details/wcf-web-http-programming-model-overview.md @@ -141,7 +141,7 @@ Because the WCF WEB HTTP programming model does not support the WS-* protocols, ## Troubleshooting the WCF WEB HTTP Programming Model - When calling WCF WEB HTTP services using a to create a channel, the uses the set in the configuration file even if a different is passed to the . + When calling WCF WEB HTTP services using a to create a channel, the uses the set in the configuration file even if a different is passed to the . ## See also diff --git a/docs/framework/wcf/feature-details/wcf-web-http-service-help-page.md b/docs/framework/wcf/feature-details/wcf-web-http-service-help-page.md index 0727ed6fe7377..8828c5a0c015d 100644 --- a/docs/framework/wcf/feature-details/wcf-web-http-service-help-page.md +++ b/docs/framework/wcf/feature-details/wcf-web-http-service-help-page.md @@ -6,236 +6,236 @@ ms.assetid: 63c7c695-44b6-4f31-bb9c-00f2763f525e --- # WCF Web HTTP Service Help Page -[!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md)] provides an automatic help page for WCF WEB HTTP services. This help page lists a description of each operation, request and response formats, and schemas. This functionality is turned off by default. When a user browses to a WCF WEB HTTP service and appends "/Help" on to the end of the URL, for example `http://localhost:8000/Customers/Help`, a help page like the following is displayed. - - ![A browser with the WCF REST Help page open.](./media/wcf-web-http-service-help-page/windows-communication-foundation-rest-help-page.gif) - - The user can then click any method listed in the help page and detailed page for that operation is displayed showing more information about the method, including message formats and example responses. The following image is an example of a help page for a method. - - ![A browser with the WCF REST Help page details for the GetCustomers method open.](./media/wcf-web-http-service-help-page/windows-communication-foundation-rest-help-page-detail.gif) - -## Using the WCF Web HTTP Help Page - - The WCF WEB HTTP Help page displays a short description for each operation provided that you specify one using the . This attribute takes a string that contains a short description of the operation it is applied to. For example, the following code shows how to use the to provide a short description. - +[!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md)] provides an automatic help page for WCF WEB HTTP services. This help page lists a description of each operation, request and response formats, and schemas. This functionality is turned off by default. When a user browses to a WCF WEB HTTP service and appends "/Help" on to the end of the URL, for example `http://localhost:8000/Customers/Help`, a help page like the following is displayed. + + ![A browser with the WCF REST Help page open.](./media/wcf-web-http-service-help-page/windows-communication-foundation-rest-help-page.gif) + + The user can then click any method listed in the help page and detailed page for that operation is displayed showing more information about the method, including message formats and example responses. The following image is an example of a help page for a method. + + ![A browser with the WCF REST Help page details for the GetCustomers method open.](./media/wcf-web-http-service-help-page/windows-communication-foundation-rest-help-page-detail.gif) + +## Using the WCF Web HTTP Help Page + + The WCF WEB HTTP Help page displays a short description for each operation provided that you specify one using the . This attribute takes a string that contains a short description of the operation it is applied to. For example, the following code shows how to use the to provide a short description. + ```csharp -[OperationContract] -[WebGet(UriTemplate="/template1", BodyStyle = WebMessageBodyStyle.Bare)] -[Description("Description for GET /template1")] -SyndicationFeedFormatter GetTemplate1(); -``` - - To turn on the WCF WEB HTTP Help page, you must add an endpoint behavior to your service's endpoints. This can be done in configuration or code. To enable the WCF WEB HTTP Help age in configuration, add an endpoint behavior with a `` element, set `helpEnabled` to `true`, and add an endpoint and configure it to use the endpoint behavior. The following configuration code shows how to do this. - -```xml - - - - - - - - - - - - -``` - - To enable the WCF Web HTTP Help page in code, add a service endpoint and add a to the endpoint setting to `true`. The following code shows how to do this. - +[OperationContract] +[WebGet(UriTemplate="/template1", BodyStyle = WebMessageBodyStyle.Bare)] +[Description("Description for GET /template1")] +SyndicationFeedFormatter GetTemplate1(); +``` + + To turn on the WCF WEB HTTP Help page, you must add an endpoint behavior to your service's endpoints. This can be done in configuration or code. To enable the WCF WEB HTTP Help age in configuration, add an endpoint behavior with a `` element, set `helpEnabled` to `true`, and add an endpoint and configure it to use the endpoint behavior. The following configuration code shows how to do this. + +```xml + + + + + + + + + + + + +``` + + To enable the WCF Web HTTP Help page in code, add a service endpoint and add a to the endpoint setting to `true`. The following code shows how to do this. + ```csharp -using (WebServiceHost host = new WebServiceHost(typeof(Service), new Uri("http://localhost:8000/Customers"))) -{ +using (WebServiceHost host = new WebServiceHost(typeof(Service), new Uri("http://localhost:8000/Customers"))) +{ host.AddServiceEndpoint(typeof(ICustomerCollection), new WebHttpBinding(), ""); - host.Description.Endpoints[0].Behaviors.Add(new WebHttpBehavior { EnableHelp = true }); - // ... -} -``` - - The help page is XHTML based with mark-up that identifies the different parts of the page. This enables clients to programmatically access the page using or other XLinq APIs. - -## Schemas Used in the WCF Web HTTP Service Help Page - - The following schemas are used in the WCF Web HTTP service help page. - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - true - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - + host.Description.Endpoints[0].Behaviors.Add(new WebHttpBehavior { EnableHelp = true }); + // ... +} +``` + + The help page is XHTML based with mark-up that identifies the different parts of the page. This enables clients to programmatically access the page using or other XLinq APIs. + +## Schemas Used in the WCF Web HTTP Service Help Page + + The following schemas are used in the WCF Web HTTP service help page. + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + true + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + For more information about the data contract serialization schema, see [Data Contract Schema Reference](data-contract-schema-reference.md). diff --git a/docs/framework/wcf/feature-details/workflow-service-host-extensibility.md b/docs/framework/wcf/feature-details/workflow-service-host-extensibility.md index 055499710f860..afc86d5a24186 100644 --- a/docs/framework/wcf/feature-details/workflow-service-host-extensibility.md +++ b/docs/framework/wcf/feature-details/workflow-service-host-extensibility.md @@ -10,11 +10,11 @@ ms.assetid: c0e8f7bb-cb13-49ec-852f-b85d7c23972f ## Workflow Service Host Extensions - The contains a property of type that provides methods to add extensions to the . Use the method to add an extension for each workflow service instance. The delegate specified is called to create a new extension when a workflow service instance is created or loaded from a persistence store. Use the method to add an extension for each workflow service host, one instance of the extension is shared for all workflow service instances. + The contains a property of type that provides methods to add extensions to the . Use the method to add an extension for each workflow service instance. The delegate specified is called to create a new extension when a workflow service instance is created or loaded from a persistence store. Use the method to add an extension for each workflow service host, one instance of the extension is shared for all workflow service instances. ## React to Unhandled Exceptions - The enables you to specify the action to take if an unhandled exception occurs within a workflow service. The property specifies one of the values: + The enables you to specify the action to take if an unhandled exception occurs within a workflow service. The property specifies one of the values: - – Aborts the workflow service instance. @@ -46,7 +46,7 @@ host.Description.Behaviors.Add(new WorkflowUnhandledExceptionBehavior { Action = ## Hosting Non-Service Workflows - can be used to host non-service workflows, or workflows that either do not begin with a activity or workflows that do not use the messaging activities. Workflow services normally begin with a activity. When the receives a message for a workflow service, if it is not already running (or persisted) a new workflow service instance is created. If a workflow does not begin with a Receive activity, it cannot be started by sending a message because there is no activity to receive the message. To host a non-service workflow, derive a class from and override , , and . Override if you want to provide a preferred instance ID. Override to create a custom workflow creation context or populate an instance of the existing . Override to manually extract the bookmark from the incoming message. If you override this method, you must invoke in its body so as to respond to the message sent to the WorkflowHostingEndpoint. If you do not do so, a limit may be eventually exceeded. In two-way contracts, you may be able to detect your failure to invoke because of the client’s failure to receive a response. In one-way contracts, you may not recognize the mistake of failing to call until it’s too late, after the throttle limit is exceeded. To create a new instance of a non-service workflow, declare a service contract that defines an operation that creates a new instance. The creation operation should take an IDictionary\ to pass any required workflow parameters. This contract is implicitly implemented by the -derived class. When hosting the workflow, add an instance of the -derived class to the host by calling and call . To create an instance of the workflow, create a of your service contract type and call . You can then call the create operation defined in your service contract. + can be used to host non-service workflows, or workflows that either do not begin with a activity or workflows that do not use the messaging activities. Workflow services normally begin with a activity. When the receives a message for a workflow service, if it is not already running (or persisted) a new workflow service instance is created. If a workflow does not begin with a Receive activity, it cannot be started by sending a message because there is no activity to receive the message. To host a non-service workflow, derive a class from and override , , and . Override if you want to provide a preferred instance ID. Override to create a custom workflow creation context or populate an instance of the existing . Override to manually extract the bookmark from the incoming message. If you override this method, you must invoke in its body so as to respond to the message sent to the WorkflowHostingEndpoint. If you do not do so, a limit may be eventually exceeded. In two-way contracts, you may be able to detect your failure to invoke because of the client’s failure to receive a response. In one-way contracts, you may not recognize the mistake of failing to call until it’s too late, after the throttle limit is exceeded. To create a new instance of a non-service workflow, declare a service contract that defines an operation that creates a new instance. The creation operation should take an IDictionary\ to pass any required workflow parameters. This contract is implicitly implemented by the -derived class. When hosting the workflow, add an instance of the -derived class to the host by calling and call . To create an instance of the workflow, create a of your service contract type and call . You can then call the create operation defined in your service contract. ## See also diff --git a/docs/framework/wcf/feature-details/workflow-service-host-internals.md b/docs/framework/wcf/feature-details/workflow-service-host-internals.md index d167e982c401b..0da6a6d2ed274 100644 --- a/docs/framework/wcf/feature-details/workflow-service-host-internals.md +++ b/docs/framework/wcf/feature-details/workflow-service-host-internals.md @@ -6,47 +6,47 @@ ms.assetid: af44596f-bf6a-4149-9f04-08d8e8f45250 --- # Workflow Service Host Internals - provides a host for workflow services. It is responsible for listening for incoming messages and routing them to the appropriate workflow service instance, it controls unloading and persisting of idle workflows, and more. This topic describes how WorkflowServiceHost processes incoming messages. - -## WorkflowServiceHost Overview + provides a host for workflow services. It is responsible for listening for incoming messages and routing them to the appropriate workflow service instance, it controls unloading and persisting of idle workflows, and more. This topic describes how WorkflowServiceHost processes incoming messages. + +## WorkflowServiceHost Overview The class is used to host workflow services. It listens for incoming messages and routes them to the appropriate service instance, creating new instances or loading existing instances from durable storage as needed. The following diagram illustrates on a high level how works: - - ![Diagram that shows an overview of the Workflow Service Host.](./media/workflow-service-host-internals/workflow-service-host-high-level-overview.gif) - - This diagram shows that loads workflow service definitions from .xamlx files and loads configuration information from a configuration file. It also loads tracking configuration from the tracking profile. exposes a workflow control endpoint which allows you to send control operations to workflow instances. For more information see [Workflow Control Endpoint sample](workflow-control-endpoint.md). - - also exposes application endpoints that listen for incoming application messages. When an incoming message arrives it is sent to the appropriate workflow service instance (if it is currently loaded). If needed a new workflow instance is created. Or if an existing instance has been persisted it is loaded from the persistence store. - -## WorkflowServiceHost Details - - The following diagram shows how handles messages in a bit more detail: - - ![Diagram that shows the Workflow Service Host message flow.](./media/workflow-service-host-internals/workflow-service-host-message-flow.gif) - - This diagram shows three different endpoints, an application endpoint, a workflow control endpoint, and a workflow hosting endpoint. The application endpoint receives messages that are bound for a specific workflow instance. The workflow control endpoint listens for control operations. The workflow hosting endpoint listens for messages that cause to load and execute non-service workflows. As shown in the diagram all messages are processed through the WCF runtime. Workflow service instance throttling is achieved by using the property. This property will limit the number of concurrent workflow service instances. When this throttle is exceeded any additional requests for new workflow service instances or requests to activate persisted workflow instances will be queued. The queued requests are processed in FIFO order regardless of whether they are requests for a new instance or a running, persisted instance. Host policy information is loaded that determines how unhandled exceptions are dealt with, and how idle workflow services are unloaded and persisted. For more information about these topics see [How to: Configure Workflow Unhandled Exception Behavior with WorkflowServiceHost](config-workflow-unhandled-exception-workflowservicehost.md) and [How to: Configure Idle Behavior with WorkflowServiceHost](how-to-configure-idle-behavior-with-workflowservicehost.md). Workflow instances are persisted according to host policies and are reloaded when needed. For more information about workflow persistence see: [How to: Configure Persistence with WorkflowServiceHost](how-to-configure-persistence-with-workflowservicehost.md), [Creating a Long-running Workflow Service](creating-a-long-running-workflow-service.md), and [Workflow Persistence](../../windows-workflow-foundation/workflow-persistence.md). - - The following illustration shows the flow when WorkflowServiceHost.Open is called: - - ![Diagram that shows the flow when WorkflowServiceHost.Open is called.](./media/workflow-service-host-internals/workflow-service-host-open.gif) - - The workflow is loaded from XAML and the activity tree is created. walks the activity tree and creates the service description. Configuration is applied to the host. Finally the host begins to listen for incoming messages. - - The following illustration shows what the does when it receives a message bound for a Receive activity that has CanCreateInstance set to `true`: - - ![Decision tree used by the WFS Host when it receives a message and CanCreateInstance is true.](./media/workflow-service-host-internals/workflow-service-host-receive-message-cancreateinstance.gif) - - The message arrives and is processed by the WCF channel stack. Throttles are checked and correlation queries are executed. If the message is bound for an existing instance the message is delivered. If a new instance needs to be created, the Receive activity’s CanCreateInstance property is checked. If it is set to true, a new instance is created and the message is delivered. - - The following illustration shows what the does when it receives a message bound for a Receive activity that has CanCreateInstance set to false. - - ![Decision tree used by the WFS Host when it receives a message and CanCreateInstance is false.](./media/workflow-service-host-internals/workflow-service-host-receive-message.gif) - - The message arrives and is processed by the WCF channel stack. Throttles are checked and correlation queries are executed. The message is bound for an existing instance (because CanCreateInstance is false) so the instance is loaded from persistence store, the bookmark is resumed and the workflow executes. - + + ![Diagram that shows an overview of the Workflow Service Host.](./media/workflow-service-host-internals/workflow-service-host-high-level-overview.gif) + + This diagram shows that loads workflow service definitions from .xamlx files and loads configuration information from a configuration file. It also loads tracking configuration from the tracking profile. exposes a workflow control endpoint which allows you to send control operations to workflow instances. For more information see [Workflow Control Endpoint sample](workflow-control-endpoint.md). + + also exposes application endpoints that listen for incoming application messages. When an incoming message arrives it is sent to the appropriate workflow service instance (if it is currently loaded). If needed a new workflow instance is created. Or if an existing instance has been persisted it is loaded from the persistence store. + +## WorkflowServiceHost Details + + The following diagram shows how handles messages in a bit more detail: + + ![Diagram that shows the Workflow Service Host message flow.](./media/workflow-service-host-internals/workflow-service-host-message-flow.gif) + + This diagram shows three different endpoints, an application endpoint, a workflow control endpoint, and a workflow hosting endpoint. The application endpoint receives messages that are bound for a specific workflow instance. The workflow control endpoint listens for control operations. The workflow hosting endpoint listens for messages that cause to load and execute non-service workflows. As shown in the diagram all messages are processed through the WCF runtime. Workflow service instance throttling is achieved by using the property. This property will limit the number of concurrent workflow service instances. When this throttle is exceeded any additional requests for new workflow service instances or requests to activate persisted workflow instances will be queued. The queued requests are processed in FIFO order regardless of whether they are requests for a new instance or a running, persisted instance. Host policy information is loaded that determines how unhandled exceptions are dealt with, and how idle workflow services are unloaded and persisted. For more information about these topics see [How to: Configure Workflow Unhandled Exception Behavior with WorkflowServiceHost](config-workflow-unhandled-exception-workflowservicehost.md) and [How to: Configure Idle Behavior with WorkflowServiceHost](how-to-configure-idle-behavior-with-workflowservicehost.md). Workflow instances are persisted according to host policies and are reloaded when needed. For more information about workflow persistence see: [How to: Configure Persistence with WorkflowServiceHost](how-to-configure-persistence-with-workflowservicehost.md), [Creating a Long-running Workflow Service](creating-a-long-running-workflow-service.md), and [Workflow Persistence](../../windows-workflow-foundation/workflow-persistence.md). + + The following illustration shows the flow when WorkflowServiceHost.Open is called: + + ![Diagram that shows the flow when WorkflowServiceHost.Open is called.](./media/workflow-service-host-internals/workflow-service-host-open.gif) + + The workflow is loaded from XAML and the activity tree is created. walks the activity tree and creates the service description. Configuration is applied to the host. Finally the host begins to listen for incoming messages. + + The following illustration shows what the does when it receives a message bound for a Receive activity that has CanCreateInstance set to `true`: + + ![Decision tree used by the WFS Host when it receives a message and CanCreateInstance is true.](./media/workflow-service-host-internals/workflow-service-host-receive-message-cancreateinstance.gif) + + The message arrives and is processed by the WCF channel stack. Throttles are checked and correlation queries are executed. If the message is bound for an existing instance the message is delivered. If a new instance needs to be created, the Receive activity’s CanCreateInstance property is checked. If it is set to true, a new instance is created and the message is delivered. + + The following illustration shows what the does when it receives a message bound for a Receive activity that has CanCreateInstance set to false. + + ![Decision tree used by the WFS Host when it receives a message and CanCreateInstance is false.](./media/workflow-service-host-internals/workflow-service-host-receive-message.gif) + + The message arrives and is processed by the WCF channel stack. Throttles are checked and correlation queries are executed. The message is bound for an existing instance (because CanCreateInstance is false) so the instance is loaded from persistence store, the bookmark is resumed and the workflow executes. + > [!WARNING] -> Workflow Service Host will fail to open if SQL Server is configured to listen on NamedPipe protocol only. - +> Workflow Service Host will fail to open if SQL Server is configured to listen on NamedPipe protocol only. + ## See also - [Workflow Services](workflow-services.md) diff --git a/docs/framework/wcf/feature-details/workflow-services-overview.md b/docs/framework/wcf/feature-details/workflow-services-overview.md index 0959ea0944cb1..b09008f9dd265 100644 --- a/docs/framework/wcf/feature-details/workflow-services-overview.md +++ b/docs/framework/wcf/feature-details/workflow-services-overview.md @@ -18,15 +18,15 @@ When implementing a WCF service, you define a number of contracts that describe Activity -- +- -- +- -- +- Activity -- +- Activity @@ -51,7 +51,7 @@ Like WCF services, workflow services must be hosted. WCF services use the class and pass it an instance of the that contains the workflow definition within the property. A workflow definition that contains messaging activities is exposed as a workflow service. +Workflow services hosted in a managed .NET Framework application or a managed Windows service create an instance of the class and pass it an instance of the that contains the workflow definition within the property. A workflow definition that contains messaging activities is exposed as a workflow service. To host a workflow service in IIS or WAS, place the .xamlx file that contains the workflow service definition into a virtual directory. A default endpoint (using ) is created automatically For more information, see [Simplified Configuration](../simplified-configuration.md). You can also place a Web.config file in the virtual directory to specify your own endpoints. If your workflow definition is in an assembly you can place a .svc file in the virtual directory and the workflow assembly in the App_Code directory. The .svc file must specify the service host factory and the class that implements the workflow service. The following example shows how to specify the service host factory and specify the class that implements the workflow service. diff --git a/docs/framework/wcf/feature-details/working-with-certificates.md b/docs/framework/wcf/feature-details/working-with-certificates.md index ce41e278e5f9f..f33e936dab98a 100644 --- a/docs/framework/wcf/feature-details/working-with-certificates.md +++ b/docs/framework/wcf/feature-details/working-with-certificates.md @@ -69,10 +69,10 @@ When creating a new service, you may be using a certificate that is not issued b |Class|Property| |-----------|--------------| -||| -||| -||| -||| +||| +||| +||| +||| You can also set the property using configuration. The following elements are used to specify the validation mode: @@ -86,7 +86,7 @@ You can also set the property using configuration. The following elements are us The `CertificateValidationMode` property also enables you to customize how certificates are authenticated. By default, the level is set to `ChainTrust`. To use the value, you must also set the `CustomCertificateValidatorType` attribute to an assembly and type used to validate the certificate. To create a custom validator, you must inherit from the abstract class. -When creating a custom authenticator, the most important method to override is the method. For an example of custom authentication, see the [X.509 Certificate Validator](../samples/x-509-certificate-validator.md) sample. For more information, see [Custom Credential and Credential Validation](../extending/custom-credential-and-credential-validation.md). +When creating a custom authenticator, the most important method to override is the method. For an example of custom authentication, see the [X.509 Certificate Validator](../samples/x-509-certificate-validator.md) sample. For more information, see [Custom Credential and Credential Validation](../extending/custom-credential-and-credential-validation.md). ## Use the PowerShell New-SelfSignedCertificate cmdlet to build a certificate chain @@ -136,11 +136,11 @@ In WCF, you must often specify a certificate or set of certificates a service or | Class | Method | |-------|--------| -||| -||| -||| +||| +||| +||| || | -|| | +|| | The `SetCertificate` method works by designating a store location and store, a "find" type (`x509FindType` parameter) that specifies a field of the certificate, and a value to find in the field. For example, the following code creates a instance and sets the service certificate used to authenticate the service to clients with the `SetCertificate` method. diff --git a/docs/framework/wcf/feature-details/xml-and-ado-net-types-in-data-contracts.md b/docs/framework/wcf/feature-details/xml-and-ado-net-types-in-data-contracts.md index f52f1b2171572..2503de2b6e847 100644 --- a/docs/framework/wcf/feature-details/xml-and-ado-net-types-in-data-contracts.md +++ b/docs/framework/wcf/feature-details/xml-and-ado-net-types-in-data-contracts.md @@ -2,214 +2,214 @@ description: "Learn more about: XML and ADO.NET Types in Data Contracts" title: "XML and ADO.NET Types in Data Contracts" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: c2ce8461-3c15-4c41-8c81-1cb78f5b59a6 --- # XML and ADO.NET Types in Data Contracts -The Windows Communication Foundation (WCF) data contract model supports certain types that represent XML directly. When these types are serialized to XML, the serializer writes out the XML contents of these types without any further processing. Supported types are , arrays of (but not the `XmlNode` type itself), as well as types that implement . The and type, as well as typed datasets, are commonly used in database programming. These types implement the `IXmlSerializable` interface and are therefore serializable in the data contract model. Some special considerations for these types are listed at the end of this topic. - -## XML Types - -### Xml Element +The Windows Communication Foundation (WCF) data contract model supports certain types that represent XML directly. When these types are serialized to XML, the serializer writes out the XML contents of these types without any further processing. Supported types are , arrays of (but not the `XmlNode` type itself), as well as types that implement . The and type, as well as typed datasets, are commonly used in database programming. These types implement the `IXmlSerializable` interface and are therefore serializable in the data contract model. Some special considerations for these types are listed at the end of this topic. + +## XML Types + +### Xml Element + + The `XmlElement` type is serialized using its XML contents. For example, using the following type. - The `XmlElement` type is serialized using its XML contents. For example, using the following type. - [!code-csharp[DataContractAttribute#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/datacontractattribute/cs/overview.cs#4)] - [!code-vb[DataContractAttribute#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/datacontractattribute/vb/overview.vb#4)] - - This is serialized to XML as follows: - -```xml - - - - myContents - - - -``` - - Notice that a wrapper data member element `` is still present. There is no way of removing this element in the data contract model. The serializers that handle this model (the and ) may emit special attributes into this wrapper element. These attributes include the standard XML Schema Instance "nil" attribute (allowing the `XmlElement` to be `null`) and the "type" attribute (allowing `XmlElement` to be used polymorphically). Also, the following XML attributes are specific to WCF: "Id", "Ref", "Type" and "Assembly". These attributes may be emitted to support using the `XmlElement` with the object graph preservation mode enabled, or with the . (For more information about the object graph preservation mode, see [Serialization and Deserialization](serialization-and-deserialization.md).) - - Arrays or collections of `XmlElement` are allowed and are handled as any other array or collection. That is, there is a wrapper element for the entire collection, and a separate wrapper element (similar to `` in the preceding example) for each `XmlElement` in the array. - - On deserialization, an `XmlElement` is created by the deserializer from the incoming XML. A valid parent is provided by the deserializer. - - Make sure that the XML fragment that is deserialized to an `XmlElement` defines all prefixes that it uses and does not rely on any prefix definitions from ancestor elements. This is a concern only when using the `DataContractSerializer` to access XML from a different (non-`DataContractSerializer`) source. - - When used with the `DataContractSerializer`, the `XmlElement` may be assigned polymorphically, but only to a data member of type . Even though it implements , an `XmlElement` cannot be used as a collection type and cannot be assigned to an data member. As with all polymorphic assignments, the `DataContractSerializer` emits the data contract name in the resulting XML. In this case, it is "XmlElement" in the `http://schemas.datacontract.org/2004/07/System.Xml` namespace. - - With the `NetDataContractSerializer`, any valid polymorphic assignment of `XmlElement` (to `Object` or `IEnumerable`) is supported. - - Do not attempt to use either of the serializers with types derived from `XmlElement`, whether they are assigned polymorphically or not. - -### Array of XmlNode - - Using arrays of is very similar to using `XmlElement`. Using arrays of `XmlNode` gives you more flexibility than using `XmlElement`. You can write multiple elements inside the data member wrapping element. You can also inject content other than elements inside of the data member wrapping element, such as XML comments. Finally, you can put attributes into the wrapping data member element. All this can be achieved by populating the array of `XmlNode` with specific derived classes of `XmlNode` such as , `XmlElement` or . For example, using the following type. - + [!code-vb[DataContractAttribute#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/datacontractattribute/vb/overview.vb#4)] + + This is serialized to XML as follows: + +```xml + + + + myContents + + + +``` + + Notice that a wrapper data member element `` is still present. There is no way of removing this element in the data contract model. The serializers that handle this model (the and ) may emit special attributes into this wrapper element. These attributes include the standard XML Schema Instance "nil" attribute (allowing the `XmlElement` to be `null`) and the "type" attribute (allowing `XmlElement` to be used polymorphically). Also, the following XML attributes are specific to WCF: "Id", "Ref", "Type" and "Assembly". These attributes may be emitted to support using the `XmlElement` with the object graph preservation mode enabled, or with the . (For more information about the object graph preservation mode, see [Serialization and Deserialization](serialization-and-deserialization.md).) + + Arrays or collections of `XmlElement` are allowed and are handled as any other array or collection. That is, there is a wrapper element for the entire collection, and a separate wrapper element (similar to `` in the preceding example) for each `XmlElement` in the array. + + On deserialization, an `XmlElement` is created by the deserializer from the incoming XML. A valid parent is provided by the deserializer. + + Make sure that the XML fragment that is deserialized to an `XmlElement` defines all prefixes that it uses and does not rely on any prefix definitions from ancestor elements. This is a concern only when using the `DataContractSerializer` to access XML from a different (non-`DataContractSerializer`) source. + + When used with the `DataContractSerializer`, the `XmlElement` may be assigned polymorphically, but only to a data member of type . Even though it implements , an `XmlElement` cannot be used as a collection type and cannot be assigned to an data member. As with all polymorphic assignments, the `DataContractSerializer` emits the data contract name in the resulting XML. In this case, it is "XmlElement" in the `http://schemas.datacontract.org/2004/07/System.Xml` namespace. + + With the `NetDataContractSerializer`, any valid polymorphic assignment of `XmlElement` (to `Object` or `IEnumerable`) is supported. + + Do not attempt to use either of the serializers with types derived from `XmlElement`, whether they are assigned polymorphically or not. + +### Array of XmlNode + + Using arrays of is very similar to using `XmlElement`. Using arrays of `XmlNode` gives you more flexibility than using `XmlElement`. You can write multiple elements inside the data member wrapping element. You can also inject content other than elements inside of the data member wrapping element, such as XML comments. Finally, you can put attributes into the wrapping data member element. All this can be achieved by populating the array of `XmlNode` with specific derived classes of `XmlNode` such as , `XmlElement` or . For example, using the following type. + [!code-csharp[DataContractAttribute#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/datacontractattribute/cs/overview.cs#5)] - [!code-vb[DataContractAttribute#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/datacontractattribute/vb/overview.vb#5)] - - When serialized, the resulting XML is similar to the following code. - -```xml - - - - - myContents - - - myContents - - - -``` - - Note that the data member wrapper element `` contains an attribute, a comment, and two elements. These are the four `XmlNode` instances that were serialized. - - An array of `XmlNode` that results in invalid XML cannot be serialized. For example, an array of two `XmlNode` instances where the first one is an `XmlElement` and the second one is an is invalid, because this sequence does not correspond to any valid XML instance (there is no place to attach the attribute to). - - On deserialization of an array of `XmlNode`, nodes are created and populated with information from the incoming XML. A valid parent is provided by the deserializer. All nodes are deserialized, including any attributes on the wrapper data member element, but excluding the attributes placed there by the WCF serializers (such as the attributes used to indicate polymorphic assignment). The caveat about defining all namespace prefixes in the XML fragment applies to the deserialization of arrays of `XmlNode` just like it does to deserializing `XmlElement`. - - When using the serializers with object graph preservation turned on, object equality is only preserved on the level of `XmlNode` arrays, not individual `XmlNode` instances. - - Do not attempt to serialize an array of `XmlNode` where one or more of the nodes is set to `null`. It is permitted for the entire array member to be `null`, but not for any individual `XmlNode` contained in the array. If the entire array member is null, the wrapper data member element contains a special attribute that indicates that it is null. On deserialization, the entire array member also becomes null. - - Only regular arrays of `XmlNode` are treated specially by the serializer. Data members declared as other collection types that contain `XmlNode`, or data members declared as arrays of types derived from `XmlNode`, are not treated specially. Thus, they are normally not serializable unless they also meet one of the other criteria for serializing. - - Arrays or collections of arrays of `XmlNode` are allowed. There is a wrapper element for the entire collection, and a separate wrapper element (similar to `` in the preceding example) for each array of `XmlNode` in the outer array or collection. - - Populating a data member of type of `Object` or `Array` of `IEnumerable` with `XmlNode` instances does not result in the data member being treated as an `Array` of `XmlNode` instances. Each array member is serialized separately. - - When used with the `DataContractSerializer`, arrays of `XmlNode` can be assigned polymorphically, but only to a data member of type `Object`. Even though it implements `IEnumerable`, an array of `XmlNode` cannot be used as a collection type and be assigned to an `IEnumerable` data member. As with all polymorphic assignments, the `DataContractSerializer` emits the data contract name in the resulting XML – in this case, it is "ArrayOfXmlNode" in the `http://schemas.datacontract.org/2004/07/System.Xml` namespace. When used with the `NetDataContractSerializer`, any valid assignment of an `XmlNode` array is supported. - -### Schema Considerations - - For details about the schema mapping of XML types, see [Data Contract Schema Reference](data-contract-schema-reference.md). This section provides a summary of the important points. - - A data member of type `XmlElement` is mapped to an element defined using the following anonymous type. - -```xml - - - - - -``` - - A data member of type Array of `XmlNode` is mapped to an element defined using the following anonymous type. - -```xml - - - - - - -``` - -## Types Implementing the IXmlSerializable Interface - - Types that implement the `IXmlSerializable` interface are fully supported by the `DataContractSerializer`. The attribute should always be applied to these types to control their schema. - - There are three varieties of types that implement `IXmlSerializable`: types that represent arbitrary content, types that represent a single element, and legacy types. - -- Content types use a schema provider method specified by the `XmlSchemaProviderAttribute` attribute. The method does not return `null`, and the property on the attribute is left at its default value of `false`. This is the most common usage of `IXmlSerializable` types. - -- Element types are used when an `IXmlSerializable` type must control its own root element name. To mark a type as an element type, either set the property on the attribute to `true` or return null from the schema provider method. Having a schema provider method is optional for element types – you may specify null instead of the method name in the `XmlSchemaProviderAttribute`. However, if `IsAny` is `true` and a schema provider method is specified, the method must return null. - -- Legacy types are `IXmlSerializable` types that are not marked with the `XmlSchemaProviderAttribute` attribute. Instead, they rely on the method for schema generation. This pattern is used for the `DataSet` type and its typed dataset derives a class in earlier versions of the .NET Framework, but is now obsolete and is supported only for legacy reasons. Do not rely on this pattern and always apply the `XmlSchemaProviderAttribute` to your `IXmlSerializable` types. - -### IXmlSerializable Content Types - - When serializing a data member of a type that implements `IXmlSerializable` and is a content type as defined previously, the serializer writes the wrapper element for the data member and pass control to the method. The implementation can write any XML, including adding attributes to the wrapper element. After `WriteXml` is done, the serializer closes the element. - - When deserializing a data member of a type that implements `IXmlSerializable` and is a content type as defined previously, the deserializer positions the XML reader on the wrapper element for the data member and pass control to the method. The method must read the entire element, including the start and end tags. Make sure your `ReadXml` code handles the case where the element is empty. Additionally, your `ReadXml` implementation should not rely on the wrapper element being named a particular way. The name is chosen by the serializer can vary. - - It is permitted to assign `IXmlSerializable` content types polymorphically, for example, to data members of type . It is also permitted for the type instances to be null. Finally, it is possible to use `IXmlSerializable` types with object graph preservation enabled and with the . All these features require the WCF serializer to attach certain attributes into the wrapper element ("nil" and "type" in the XML Schema Instance namespace and "Id", "Ref", "Type" and "Assembly" in a WCF-specific namespace). - -#### Attributes to Ignore when Implementing ReadXml - - Before passing control to your `ReadXml` code, the deserializer examines the XML element, detects these special XML attributes, and acts on them. For example, if "nil" is `true`, a null value is deserialized and `ReadXml` is not called. If polymorphism is detected, the contents of the element are deserialized as if it was a different type. The polymorphically assigned type’s implementation of `ReadXml` is called. In any case, a `ReadXml` implementation should ignore these special attributes because they are handled by the deserializer. - -### Schema Considerations for IXmlSerializable Content Types - - When exporting schema an `IXmlSerializable` content type, the schema provider method is called. An is passed to the schema provider method. The method can add any valid schema to the schema set. The schema set contains the schema that is already known at the time when schema export occurs. When the schema provider method must add an item to the schema set, it must determine if an with the appropriate namespace already exists in the set. If it does, the schema provider method must add the new item to the existing `XmlSchema`. Otherwise, it must create a new `XmlSchema` instance. This is important if arrays of `IXmlSerializable` types are being used. For example, if you have an `IXmlSerializable` type that gets exported as type "A" in namespace "B", it is possible that by the time the schema provider method is called the schema set already contains the schema for "B" to hold the "ArrayOfA" type. - - In addition to adding types to the , the schema provider method for content types must return a non-null value. It can return an that specifies the name of the schema type to use for the given `IXmlSerializable` type. This qualified name also serves as the data contract name and namespace for the type. It is permitted to return a type that does not exist in the schema set immediately when the schema provider method returns. However, it is expected that by the time all related types are exported (the method is called for all relevant types on the and the property is accessed), the type exists in the schema set. Accessing the `Schemas` property before all relevant `Export` calls have been made can result in an . For more information about the export process, see [Exporting Schemas from Classes](exporting-schemas-from-classes.md). - - The schema provider method can also return the to use. The type may or may not be anonymous. If it is anonymous, the schema for the `IXmlSerializable` type is exported as an anonymous type every time the `IXmlSerializable` type is used as a data member. The `IXmlSerializable` type still has a data contract name and namespace. (This is determined as described in [Data Contract Names](data-contract-names.md) except that the attribute cannot be used to customize the name.) If it is not anonymous, it must be one of the types in the `XmlSchemaSet`. This case is equivalent to returning the `XmlQualifiedName` of the type. - - Additionally, a global element declaration is exported for the type. If the type does not have the attribute applied to it, the element has the same name and namespace as the data contract, and its "nillable" property is `true`. The only exception to this is the schema namespace (`http://www.w3.org/2001/XMLSchema`); if the type's data contract is in this namespace, the corresponding global element is in the blank namespace because it's forbidden to add new elements to the schema namespace. If the type has the `XmlRootAttribute` attribute applied to it, the global element declaration is exported using the following properties: , , and . The defaults with `XmlRootAttribute` applied are the data contract name, a blank namespace, and "nillable" being true. - - The same global element declaration rules apply to legacy dataset types. Note that the `XmlRootAttribute` cannot override global element declarations added through custom code, either added to the `XmlSchemaSet` using the schema provider method or through `GetSchema` for legacy dataset types. - -### IXmlSerializable Element Types - - `IXmlSerializable` element types have either the `IsAny` property set to `true` or have their schema provider method return `null`. - - Serializing and deserializing an element type is very similar to serializing and deserializing a content type. However, there are some important differences: - -- The `WriteXml` implementation is expected to write exactly one element (which could of course contain multiple child elements). It should not be writing attributes outside of this single element, multiple sibling elements or mixed content. The element may be empty. - -- The `ReadXml` implementation should not read the wrapper element. It is expected to read the one element that `WriteXml` produces. - -- When serializing an element type regularly (for example, as a data member in a data contract), the serializer outputs a wrapper element before calling `WriteXml`, as with content types. However, when serializing an element type at the top level, the serializer does not normally output a wrapper element at all around the element that `WriteXml` writes, unless a root name and namespace were explicitly specified when constructing the serializer in the `DataContractSerializer` or `NetDataContractSerializer` constructors. For more information, see [Serialization and Deserialization](serialization-and-deserialization.md). - -- When serializing an element type at the top level without specifying the root name and namespace at construction time, and essentially does nothing and calls `WriteXml`. In this mode, the object being serialized cannot be null and cannot be polymorphically assigned. Also, object graph preservation cannot enabled and the `NetDataContractSerializer` cannot be used. - -- When deserializing an element type at the top level without specifying the root name and namespace at construction time, returns `true` if it can find the start of any element. with the `verifyObjectName` parameter set to `true` behaves in the same way as `IsStartObject` before actually reading the object. `ReadObject` then passes control to `ReadXml` method. - - The schema exported for element types is the same as for the `XmlElement` type as described in an earlier section, except that the schema provider method can add any additional schema to the as with content types. Using the `XmlRootAttribute` attribute with element types is not allowed, and global element declarations are never emitted for these types. - -### Differences from the XmlSerializer - - The `IXmlSerializable` interface and the `XmlSchemaProviderAttribute` and `XmlRootAttribute` attributes are also understood by the . However, there are some differences in how these are treated in the data contract model. The important differences are summarized in the following: - -- The schema provider method must be public to be usable in the `XmlSerializer`, but does not have to be public to be usable in the data contract model. - -- The schema provider method is called when `IsAny` is true in the data contract model but not with the `XmlSerializer`. - -- When the `XmlRootAttribute` attribute is not present for content or legacy dataset types, the `XmlSerializer` exports a global element declaration in the blank namespace. In the data contract model, the namespace used is normally the data contract namespace as described earlier. - - Be aware of these differences when creating types that are used with both serialization technologies. - -### Importing IXmlSerializable Schema - - When importing a schema generated from `IXmlSerializable` types, there are a few possibilities: - -- The generated schema may be a valid data contract schema as described in [Data Contract Schema Reference](data-contract-schema-reference.md). In this case, schema can be imported as usual and regular data contract types are generated. - -- The generated schema may not be a valid data contract schema. For example, your schema provider method may generate schema that involves XML attributes which are not supported in the data contract model. In this case, you can import the schema as `IXmlSerializable` types. This import mode is not on by default but can easily be enabled – for example, with the `/importXmlTypes` command-line switch to the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). This is described in detail in the [Importing Schema to Generate Classes](importing-schema-to-generate-classes.md). Note that you must work directly with the XML for your type instances. You may also consider using a different serialization technology that supports a wider range of schema – see the topic on using the `XmlSerializer`. - -- You may want to reuse your existing `IXmlSerializable` types in the proxy instead of generating new ones. In this case, the referenced types feature described in the Importing Schema to Generate Types topic can be used to indicate the type to reuse. This corresponds to using the `/reference` switch on svcutil.exe, which specifies the assembly that contains the types to reuse. - -## Representing Arbitrary XML in Data Contracts - - The `XmlElement`, Array of `XmlNode` and `IXmlSerializable` types allow you to inject arbitrary XML into the data contract model. The `DataContractSerializer` and `NetDataContractSerializer` pass this XML content on to the XML writer in use, without interfering in the process. However, the XML writers may enforce certain restrictions on the XML that they write. Specifically, here are some important examples: - -- The XML writers do not typically allow an XML document declaration (for example, \) in the middle of writing another document. You cannot take a full XML document and serialize it as an `Array` of `XmlNode` data member. To do this, you have to either strip out the document declaration or use your own encoding scheme to represent it. - -- All of the XML writers supplied with WCF reject XML processing instructions (\) and document type definitions (\), because they are not allowed in SOAP messages. Again, you can use your own encoding mechanism to get around this restriction. If you must include these in your resultant XML, you can write a custom encoder that uses XML writers that support them. - -- When implementing `WriteXml`, avoid calling method on the XML writer. WCF uses a variety of XML encodings (including binary), it is very difficult or impossible to use `WriteRaw` such that the result is usable in any encoding. - -- When implementing `WriteXml`, avoid using the and methods that are unsupported on the XML writers supplied with WCF. - -## Using DataSet, Typed DataSet and DataTable - - Using these types is fully supported in the data contract model. When using these types, consider the following points: - -- The schema for these types (especially and its typed derived classes) may not be interoperable with some non-WCF platforms, or may result in poor usability when used with these platforms. Additionally, using the `DataSet` type may have performance implications. Finally, it may make it more difficult for you to version your application in the future. Consider using explicitly defined data contract types instead of `DataSet` types in your contracts. - -- When importing `DataSet` or `DataTable` schema, it is important to reference these types. With the Svcutil.exe command-line tool, this can be accomplished by passing the System.Data.dll assembly name to the `/reference` switch. If importing typed dataset schema, you must reference the typed dataset’s type. With Svcutil.exe, pass the location of the typed dataset’s assembly to the `/reference` switch. For more information about referencing types, see the [Importing Schema to Generate Classes](importing-schema-to-generate-classes.md). - - Support for typed DataSets in the data contract model is limited. Typed DataSets can be serialized and deserialized and can export their schema. However, the Data Contract schema import is unable to generate new typed DataSet types from the schema, as it can only reuse existing ones. You can point to an existing typed DataSet by using the `/r` switch on Svcutil.exe. If you attempt to use a Svcutil.exe without the `/r` switch on a service that uses a typed dataset, an alternative serializer (XmlSerializer) is automatically selected. If you must use the DataContractSerializer and must generate DataSets from schema, you can use the following procedure: generate the typed DataSet types (by using the Xsd.exe tool with the `/d` switch on the service), compile the types, and then point to them using the `/r` switch on Svcutil.exe. - + [!code-vb[DataContractAttribute#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/datacontractattribute/vb/overview.vb#5)] + + When serialized, the resulting XML is similar to the following code. + +```xml + + + + + myContents + + + myContents + + + +``` + + Note that the data member wrapper element `` contains an attribute, a comment, and two elements. These are the four `XmlNode` instances that were serialized. + + An array of `XmlNode` that results in invalid XML cannot be serialized. For example, an array of two `XmlNode` instances where the first one is an `XmlElement` and the second one is an is invalid, because this sequence does not correspond to any valid XML instance (there is no place to attach the attribute to). + + On deserialization of an array of `XmlNode`, nodes are created and populated with information from the incoming XML. A valid parent is provided by the deserializer. All nodes are deserialized, including any attributes on the wrapper data member element, but excluding the attributes placed there by the WCF serializers (such as the attributes used to indicate polymorphic assignment). The caveat about defining all namespace prefixes in the XML fragment applies to the deserialization of arrays of `XmlNode` just like it does to deserializing `XmlElement`. + + When using the serializers with object graph preservation turned on, object equality is only preserved on the level of `XmlNode` arrays, not individual `XmlNode` instances. + + Do not attempt to serialize an array of `XmlNode` where one or more of the nodes is set to `null`. It is permitted for the entire array member to be `null`, but not for any individual `XmlNode` contained in the array. If the entire array member is null, the wrapper data member element contains a special attribute that indicates that it is null. On deserialization, the entire array member also becomes null. + + Only regular arrays of `XmlNode` are treated specially by the serializer. Data members declared as other collection types that contain `XmlNode`, or data members declared as arrays of types derived from `XmlNode`, are not treated specially. Thus, they are normally not serializable unless they also meet one of the other criteria for serializing. + + Arrays or collections of arrays of `XmlNode` are allowed. There is a wrapper element for the entire collection, and a separate wrapper element (similar to `` in the preceding example) for each array of `XmlNode` in the outer array or collection. + + Populating a data member of type of `Object` or `Array` of `IEnumerable` with `XmlNode` instances does not result in the data member being treated as an `Array` of `XmlNode` instances. Each array member is serialized separately. + + When used with the `DataContractSerializer`, arrays of `XmlNode` can be assigned polymorphically, but only to a data member of type `Object`. Even though it implements `IEnumerable`, an array of `XmlNode` cannot be used as a collection type and be assigned to an `IEnumerable` data member. As with all polymorphic assignments, the `DataContractSerializer` emits the data contract name in the resulting XML – in this case, it is "ArrayOfXmlNode" in the `http://schemas.datacontract.org/2004/07/System.Xml` namespace. When used with the `NetDataContractSerializer`, any valid assignment of an `XmlNode` array is supported. + +### Schema Considerations + + For details about the schema mapping of XML types, see [Data Contract Schema Reference](data-contract-schema-reference.md). This section provides a summary of the important points. + + A data member of type `XmlElement` is mapped to an element defined using the following anonymous type. + +```xml + + + + + +``` + + A data member of type Array of `XmlNode` is mapped to an element defined using the following anonymous type. + +```xml + + + + + + +``` + +## Types Implementing the IXmlSerializable Interface + + Types that implement the `IXmlSerializable` interface are fully supported by the `DataContractSerializer`. The attribute should always be applied to these types to control their schema. + + There are three varieties of types that implement `IXmlSerializable`: types that represent arbitrary content, types that represent a single element, and legacy types. + +- Content types use a schema provider method specified by the `XmlSchemaProviderAttribute` attribute. The method does not return `null`, and the property on the attribute is left at its default value of `false`. This is the most common usage of `IXmlSerializable` types. + +- Element types are used when an `IXmlSerializable` type must control its own root element name. To mark a type as an element type, either set the property on the attribute to `true` or return null from the schema provider method. Having a schema provider method is optional for element types – you may specify null instead of the method name in the `XmlSchemaProviderAttribute`. However, if `IsAny` is `true` and a schema provider method is specified, the method must return null. + +- Legacy types are `IXmlSerializable` types that are not marked with the `XmlSchemaProviderAttribute` attribute. Instead, they rely on the method for schema generation. This pattern is used for the `DataSet` type and its typed dataset derives a class in earlier versions of the .NET Framework, but is now obsolete and is supported only for legacy reasons. Do not rely on this pattern and always apply the `XmlSchemaProviderAttribute` to your `IXmlSerializable` types. + +### IXmlSerializable Content Types + + When serializing a data member of a type that implements `IXmlSerializable` and is a content type as defined previously, the serializer writes the wrapper element for the data member and pass control to the method. The implementation can write any XML, including adding attributes to the wrapper element. After `WriteXml` is done, the serializer closes the element. + + When deserializing a data member of a type that implements `IXmlSerializable` and is a content type as defined previously, the deserializer positions the XML reader on the wrapper element for the data member and pass control to the method. The method must read the entire element, including the start and end tags. Make sure your `ReadXml` code handles the case where the element is empty. Additionally, your `ReadXml` implementation should not rely on the wrapper element being named a particular way. The name is chosen by the serializer can vary. + + It is permitted to assign `IXmlSerializable` content types polymorphically, for example, to data members of type . It is also permitted for the type instances to be null. Finally, it is possible to use `IXmlSerializable` types with object graph preservation enabled and with the . All these features require the WCF serializer to attach certain attributes into the wrapper element ("nil" and "type" in the XML Schema Instance namespace and "Id", "Ref", "Type" and "Assembly" in a WCF-specific namespace). + +#### Attributes to Ignore when Implementing ReadXml + + Before passing control to your `ReadXml` code, the deserializer examines the XML element, detects these special XML attributes, and acts on them. For example, if "nil" is `true`, a null value is deserialized and `ReadXml` is not called. If polymorphism is detected, the contents of the element are deserialized as if it was a different type. The polymorphically assigned type’s implementation of `ReadXml` is called. In any case, a `ReadXml` implementation should ignore these special attributes because they are handled by the deserializer. + +### Schema Considerations for IXmlSerializable Content Types + + When exporting schema an `IXmlSerializable` content type, the schema provider method is called. An is passed to the schema provider method. The method can add any valid schema to the schema set. The schema set contains the schema that is already known at the time when schema export occurs. When the schema provider method must add an item to the schema set, it must determine if an with the appropriate namespace already exists in the set. If it does, the schema provider method must add the new item to the existing `XmlSchema`. Otherwise, it must create a new `XmlSchema` instance. This is important if arrays of `IXmlSerializable` types are being used. For example, if you have an `IXmlSerializable` type that gets exported as type "A" in namespace "B", it is possible that by the time the schema provider method is called the schema set already contains the schema for "B" to hold the "ArrayOfA" type. + + In addition to adding types to the , the schema provider method for content types must return a non-null value. It can return an that specifies the name of the schema type to use for the given `IXmlSerializable` type. This qualified name also serves as the data contract name and namespace for the type. It is permitted to return a type that does not exist in the schema set immediately when the schema provider method returns. However, it is expected that by the time all related types are exported (the method is called for all relevant types on the and the property is accessed), the type exists in the schema set. Accessing the `Schemas` property before all relevant `Export` calls have been made can result in an . For more information about the export process, see [Exporting Schemas from Classes](exporting-schemas-from-classes.md). + + The schema provider method can also return the to use. The type may or may not be anonymous. If it is anonymous, the schema for the `IXmlSerializable` type is exported as an anonymous type every time the `IXmlSerializable` type is used as a data member. The `IXmlSerializable` type still has a data contract name and namespace. (This is determined as described in [Data Contract Names](data-contract-names.md) except that the attribute cannot be used to customize the name.) If it is not anonymous, it must be one of the types in the `XmlSchemaSet`. This case is equivalent to returning the `XmlQualifiedName` of the type. + + Additionally, a global element declaration is exported for the type. If the type does not have the attribute applied to it, the element has the same name and namespace as the data contract, and its "nillable" property is `true`. The only exception to this is the schema namespace (`http://www.w3.org/2001/XMLSchema`); if the type's data contract is in this namespace, the corresponding global element is in the blank namespace because it's forbidden to add new elements to the schema namespace. If the type has the `XmlRootAttribute` attribute applied to it, the global element declaration is exported using the following properties: , , and . The defaults with `XmlRootAttribute` applied are the data contract name, a blank namespace, and "nillable" being true. + + The same global element declaration rules apply to legacy dataset types. Note that the `XmlRootAttribute` cannot override global element declarations added through custom code, either added to the `XmlSchemaSet` using the schema provider method or through `GetSchema` for legacy dataset types. + +### IXmlSerializable Element Types + + `IXmlSerializable` element types have either the `IsAny` property set to `true` or have their schema provider method return `null`. + + Serializing and deserializing an element type is very similar to serializing and deserializing a content type. However, there are some important differences: + +- The `WriteXml` implementation is expected to write exactly one element (which could of course contain multiple child elements). It should not be writing attributes outside of this single element, multiple sibling elements or mixed content. The element may be empty. + +- The `ReadXml` implementation should not read the wrapper element. It is expected to read the one element that `WriteXml` produces. + +- When serializing an element type regularly (for example, as a data member in a data contract), the serializer outputs a wrapper element before calling `WriteXml`, as with content types. However, when serializing an element type at the top level, the serializer does not normally output a wrapper element at all around the element that `WriteXml` writes, unless a root name and namespace were explicitly specified when constructing the serializer in the `DataContractSerializer` or `NetDataContractSerializer` constructors. For more information, see [Serialization and Deserialization](serialization-and-deserialization.md). + +- When serializing an element type at the top level without specifying the root name and namespace at construction time, and essentially does nothing and calls `WriteXml`. In this mode, the object being serialized cannot be null and cannot be polymorphically assigned. Also, object graph preservation cannot enabled and the `NetDataContractSerializer` cannot be used. + +- When deserializing an element type at the top level without specifying the root name and namespace at construction time, returns `true` if it can find the start of any element. with the `verifyObjectName` parameter set to `true` behaves in the same way as `IsStartObject` before actually reading the object. `ReadObject` then passes control to `ReadXml` method. + + The schema exported for element types is the same as for the `XmlElement` type as described in an earlier section, except that the schema provider method can add any additional schema to the as with content types. Using the `XmlRootAttribute` attribute with element types is not allowed, and global element declarations are never emitted for these types. + +### Differences from the XmlSerializer + + The `IXmlSerializable` interface and the `XmlSchemaProviderAttribute` and `XmlRootAttribute` attributes are also understood by the . However, there are some differences in how these are treated in the data contract model. The important differences are summarized in the following: + +- The schema provider method must be public to be usable in the `XmlSerializer`, but does not have to be public to be usable in the data contract model. + +- The schema provider method is called when `IsAny` is true in the data contract model but not with the `XmlSerializer`. + +- When the `XmlRootAttribute` attribute is not present for content or legacy dataset types, the `XmlSerializer` exports a global element declaration in the blank namespace. In the data contract model, the namespace used is normally the data contract namespace as described earlier. + + Be aware of these differences when creating types that are used with both serialization technologies. + +### Importing IXmlSerializable Schema + + When importing a schema generated from `IXmlSerializable` types, there are a few possibilities: + +- The generated schema may be a valid data contract schema as described in [Data Contract Schema Reference](data-contract-schema-reference.md). In this case, schema can be imported as usual and regular data contract types are generated. + +- The generated schema may not be a valid data contract schema. For example, your schema provider method may generate schema that involves XML attributes which are not supported in the data contract model. In this case, you can import the schema as `IXmlSerializable` types. This import mode is not on by default but can easily be enabled – for example, with the `/importXmlTypes` command-line switch to the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). This is described in detail in the [Importing Schema to Generate Classes](importing-schema-to-generate-classes.md). Note that you must work directly with the XML for your type instances. You may also consider using a different serialization technology that supports a wider range of schema – see the topic on using the `XmlSerializer`. + +- You may want to reuse your existing `IXmlSerializable` types in the proxy instead of generating new ones. In this case, the referenced types feature described in the Importing Schema to Generate Types topic can be used to indicate the type to reuse. This corresponds to using the `/reference` switch on svcutil.exe, which specifies the assembly that contains the types to reuse. + +## Representing Arbitrary XML in Data Contracts + + The `XmlElement`, Array of `XmlNode` and `IXmlSerializable` types allow you to inject arbitrary XML into the data contract model. The `DataContractSerializer` and `NetDataContractSerializer` pass this XML content on to the XML writer in use, without interfering in the process. However, the XML writers may enforce certain restrictions on the XML that they write. Specifically, here are some important examples: + +- The XML writers do not typically allow an XML document declaration (for example, \) in the middle of writing another document. You cannot take a full XML document and serialize it as an `Array` of `XmlNode` data member. To do this, you have to either strip out the document declaration or use your own encoding scheme to represent it. + +- All of the XML writers supplied with WCF reject XML processing instructions (\) and document type definitions (\), because they are not allowed in SOAP messages. Again, you can use your own encoding mechanism to get around this restriction. If you must include these in your resultant XML, you can write a custom encoder that uses XML writers that support them. + +- When implementing `WriteXml`, avoid calling method on the XML writer. WCF uses a variety of XML encodings (including binary), it is very difficult or impossible to use `WriteRaw` such that the result is usable in any encoding. + +- When implementing `WriteXml`, avoid using the and methods that are unsupported on the XML writers supplied with WCF. + +## Using DataSet, Typed DataSet and DataTable + + Using these types is fully supported in the data contract model. When using these types, consider the following points: + +- The schema for these types (especially and its typed derived classes) may not be interoperable with some non-WCF platforms, or may result in poor usability when used with these platforms. Additionally, using the `DataSet` type may have performance implications. Finally, it may make it more difficult for you to version your application in the future. Consider using explicitly defined data contract types instead of `DataSet` types in your contracts. + +- When importing `DataSet` or `DataTable` schema, it is important to reference these types. With the Svcutil.exe command-line tool, this can be accomplished by passing the System.Data.dll assembly name to the `/reference` switch. If importing typed dataset schema, you must reference the typed dataset’s type. With Svcutil.exe, pass the location of the typed dataset’s assembly to the `/reference` switch. For more information about referencing types, see the [Importing Schema to Generate Classes](importing-schema-to-generate-classes.md). + + Support for typed DataSets in the data contract model is limited. Typed DataSets can be serialized and deserialized and can export their schema. However, the Data Contract schema import is unable to generate new typed DataSet types from the schema, as it can only reuse existing ones. You can point to an existing typed DataSet by using the `/r` switch on Svcutil.exe. If you attempt to use a Svcutil.exe without the `/r` switch on a service that uses a typed dataset, an alternative serializer (XmlSerializer) is automatically selected. If you must use the DataContractSerializer and must generate DataSets from schema, you can use the following procedure: generate the typed DataSet types (by using the Xsd.exe tool with the `/d` switch on the service), compile the types, and then point to them using the `/r` switch on Svcutil.exe. + ## See also - diff --git a/docs/framework/wcf/how-to-declare-faults-in-service-contracts.md b/docs/framework/wcf/how-to-declare-faults-in-service-contracts.md index 44cf6d87339a1..1a0dc99e7da00 100644 --- a/docs/framework/wcf/how-to-declare-faults-in-service-contracts.md +++ b/docs/framework/wcf/how-to-declare-faults-in-service-contracts.md @@ -30,7 +30,7 @@ In managed code, exceptions are thrown when error conditions occur. In Windows C ### Throw the specified SOAP fault in the operation -1. When a -specified error condition occurs in an operation, throw a new where the specified SOAP fault is the type parameter. The following example shows how to throw the `GreetingFault` in the `SampleMethod` shown in the preceding procedure and in the following Code section. +1. When a -specified error condition occurs in an operation, throw a new where the specified SOAP fault is the type parameter. The following example shows how to throw the `GreetingFault` in the `SampleMethod` shown in the preceding procedure and in the following Code section. [!code-csharp[FaultContractAttribute#5](~/samples/snippets/csharp/VS_Snippets_CFX/faultcontractattribute/cs/services.cs#5)] [!code-vb[FaultContractAttribute#5](~/samples/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/services.vb#5)] @@ -45,4 +45,4 @@ The following code example shows an implementation of a single operation that sp ## See also - -- +- diff --git a/docs/framework/wcf/how-to-examine-the-security-context.md b/docs/framework/wcf/how-to-examine-the-security-context.md index 2cf4108042052..4ae43ea33aa03 100644 --- a/docs/framework/wcf/how-to-examine-the-security-context.md +++ b/docs/framework/wcf/how-to-examine-the-security-context.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Examine the Security Context" title: "How to: Examine the Security Context" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "ServiceSecurityContext class" - "WCF, security" - "Claimset class" @@ -13,45 +13,45 @@ ms.assetid: 389b5a57-4175-4bc0-ada0-fc750d51149f --- # How to: Examine the Security Context -When programming Windows Communication Foundation (WCF) services, the service security context enables you to determine details about the client credentials and claims used to authenticate with the service. This is done by using the properties of the class. - - For example, you can retrieve the identity of the current client by using the or the property. To determine whether the client is anonymous, use the property. - - You can also determine what claims are being made on behalf of the client by iterating through the collection of claims in the property. - -### To get the current security context - -- Access the static property to get the current security context. Examine any of the properties of the current context from the reference. - -### To determine the identity of the caller - -1. Print the value of the and properties. - -### To parse the claims of a caller - -1. Return the current class. Use the property to return the current service security context, then return the `AuthorizationContext` using the property. - -2. Parse the collection of objects returned by the property of the class. - -## Example - - The following example prints the values of the and properties of the current security context and the property, the resource value of the claim, and the property of every claim in the current security context. - +When programming Windows Communication Foundation (WCF) services, the service security context enables you to determine details about the client credentials and claims used to authenticate with the service. This is done by using the properties of the class. + + For example, you can retrieve the identity of the current client by using the or the property. To determine whether the client is anonymous, use the property. + + You can also determine what claims are being made on behalf of the client by iterating through the collection of claims in the property. + +### To get the current security context + +- Access the static property to get the current security context. Examine any of the properties of the current context from the reference. + +### To determine the identity of the caller + +1. Print the value of the and properties. + +### To parse the claims of a caller + +1. Return the current class. Use the property to return the current service security context, then return the `AuthorizationContext` using the property. + +2. Parse the collection of objects returned by the property of the class. + +## Example + + The following example prints the values of the and properties of the current security context and the property, the resource value of the claim, and the property of every claim in the current security context. + [!code-csharp[c_PrincipalPermissionAttribute#4](../../../samples/snippets/csharp/VS_Snippets_CFX/c_principalpermissionattribute/cs/source.cs#4)] - [!code-vb[c_PrincipalPermissionAttribute#4](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_principalpermissionattribute/vb/source.vb#4)] - -## Compiling the Code - - The code uses the following namespaces: - -- - -- - -- - -- - + [!code-vb[c_PrincipalPermissionAttribute#4](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_principalpermissionattribute/vb/source.vb#4)] + +## Compiling the Code + + The code uses the following namespaces: + +- + +- + +- + +- + ## See also - [Securing Services](securing-services.md) diff --git a/docs/framework/wcf/how-to-host-a-wcf-service-in-a-managed-application.md b/docs/framework/wcf/how-to-host-a-wcf-service-in-a-managed-application.md index 1831fe6f8ebb1..141de4faa7557 100644 --- a/docs/framework/wcf/how-to-host-a-wcf-service-in-a-managed-application.md +++ b/docs/framework/wcf/how-to-host-a-wcf-service-in-a-managed-application.md @@ -11,7 +11,7 @@ ms.assetid: 5eb29db0-b6dc-4e77-8c68-0a62f79d743b To host a service inside a managed application, embed the code for the service inside the managed application code, define an endpoint for the service either imperatively in code, declaratively through configuration, or using default endpoints, and then create an instance of . -To start receiving messages, call on . This creates and opens the listener for the service. Hosting a service in this way is often referred to as "self-hosting" because the managed application is doing the hosting work itself. To close the service, call on . +To start receiving messages, call on . This creates and opens the listener for the service. Hosting a service in this way is often referred to as "self-hosting" because the managed application is doing the hosting work itself. To close the service, call on . A service can also be hosted in a managed Windows service, in Internet Information Services (IIS), or in Windows Process Activation Service (WAS). For more information about hosting options for a service, see [Hosting Services](hosting-services.md). @@ -52,7 +52,7 @@ The following procedure demonstrates how to implement a self-hosted service in a [!code-csharp[CFX_SelfHost4#3](../../../samples/snippets/csharp/VS_Snippets_CFX/cfx_selfhost4/cs/program.cs#3)] [!code-vb[CFX_SelfHost4#3](../../../samples/snippets/visualbasic/VS_Snippets_CFX/cfx_selfhost4/vb/module1.vb#3)] -6. Create an instance of the class, passing a that represents the service type and the base address Uniform Resource Identifier (URI) to the . Enable metadata publishing, and then call the method on the to initialize the service and prepare it to receive messages. +6. Create an instance of the class, passing a that represents the service type and the base address Uniform Resource Identifier (URI) to the . Enable metadata publishing, and then call the method on the to initialize the service and prepare it to receive messages. [!code-csharp[CFX_SelfHost4#4](../../../samples/snippets/csharp/VS_Snippets_CFX/cfx_selfhost4/cs/program.cs#4)] [!code-vb[CFX_SelfHost4#4](../../../samples/snippets/visualbasic/VS_Snippets_CFX/cfx_selfhost4/vb/module1.vb#4)] @@ -84,7 +84,7 @@ The following procedure demonstrates how to implement a self-hosted service in a ## Example -The following example creates a object to host a service of type `HelloWorldService`, and then calls the method on . A base address is provided in code, metadata publishing is enabled, and default endpoints are used. +The following example creates a object to host a service of type `HelloWorldService`, and then calls the method on . A base address is provided in code, metadata publishing is enabled, and default endpoints are used. [!code-csharp[CFX_SelfHost4#5](../../../samples/snippets/csharp/VS_Snippets_CFX/cfx_selfhost4/cs/program.cs#5)] [!code-vb[CFX_SelfHost4#5](../../../samples/snippets/visualbasic/VS_Snippets_CFX/cfx_selfhost4/vb/module1.vb#5)] @@ -92,7 +92,7 @@ The following example creates a object to ## See also - -- +- - - [How to: Host a WCF Service in IIS](./feature-details/how-to-host-a-wcf-service-in-iis.md) - [Self-Host](./samples/self-host.md) diff --git a/docs/framework/wcf/how-to-host-and-run-a-basic-wcf-service.md b/docs/framework/wcf/how-to-host-and-run-a-basic-wcf-service.md index daa1ef467a85d..39de5b9da3e5e 100644 --- a/docs/framework/wcf/how-to-host-and-run-a-basic-wcf-service.md +++ b/docs/framework/wcf/how-to-host-and-run-a-basic-wcf-service.md @@ -209,7 +209,7 @@ The steps in the code you added to host the service are described as follows: > [!IMPORTANT] > For .NET Framework Version 4 and later, adding a service endpoint is optional. For these versions, if you don't add your code or configuration, WCF adds one default endpoint for each combination of base address and contract implemented by the service. For more information about default endpoints, see [Specifying an endpoint address](specifying-an-endpoint-address.md). For more information about default endpoints, bindings, and behaviors, see [Simplified configuration](simplified-configuration.md) and [Simplified configuration for WCF services](samples/simplified-configuration-for-wcf-services.md). -- **Step 4**: Enable metadata exchange. Clients use metadata exchange to generate proxies for calling the service operations. To enable metadata exchange, create a instance, set its property to `true`, and add the `ServiceMetadataBehavior` object to the collection of the instance. +- **Step 4**: Enable metadata exchange. Clients use metadata exchange to generate proxies for calling the service operations. To enable metadata exchange, create a instance, set its property to `true`, and add the `ServiceMetadataBehavior` object to the collection of the instance. - **Step 5**: Open to listen for incoming messages. The application waits for you to press Enter. After the application instantiates , it executes a try/catch block. For more information about safely catching exceptions thrown by , see [Use Close and Abort to release WCF client resources](samples/use-close-abort-release-wcf-client-resources.md). diff --git a/docs/framework/wcf/how-to-impersonate-a-client-on-a-service.md b/docs/framework/wcf/how-to-impersonate-a-client-on-a-service.md index 9ac7ec5b3724e..e273467fd84d7 100644 --- a/docs/framework/wcf/how-to-impersonate-a-client-on-a-service.md +++ b/docs/framework/wcf/how-to-impersonate-a-client-on-a-service.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Impersonate a Client on a Service" title: "How to: Impersonate a Client on a Service" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "WCF, impersonation" - "impersonation" - "WCF, security" @@ -13,34 +13,34 @@ ms.assetid: 431db851-a75b-4009-9fe2-247243d810d3 --- # How to: Impersonate a Client on a Service -Impersonating a client on a Windows Communication Foundation (WCF) service enables the service to perform actions on behalf of the client. For actions subject to access control list (ACL) checks, such as access to directories and files on a machine or access to a SQL Server database, the ACL check is against the client user account. This topic shows the basic steps required to enable a client in a Windows domain to set a client impersonation level. For a working example of this, see [Impersonating the Client](./samples/impersonating-the-client.md). For more information about client impersonation, see [Delegation and Impersonation](./feature-details/delegation-and-impersonation-with-wcf.md). - +Impersonating a client on a Windows Communication Foundation (WCF) service enables the service to perform actions on behalf of the client. For actions subject to access control list (ACL) checks, such as access to directories and files on a machine or access to a SQL Server database, the ACL check is against the client user account. This topic shows the basic steps required to enable a client in a Windows domain to set a client impersonation level. For a working example of this, see [Impersonating the Client](./samples/impersonating-the-client.md). For more information about client impersonation, see [Delegation and Impersonation](./feature-details/delegation-and-impersonation-with-wcf.md). + > [!NOTE] -> When the client and service are running on the same computer and the client is running under a system account (that is, `Local System` or `Network Service`), the client cannot be impersonated when a secure session is established with stateful Security Context tokens. A WinForms or console application typically is run under the currently logged in account, so that account can be impersonated by default. However, when the client is an ASP.NET page and that page is hosted in IIS 6.0 or IIS 7.0, then the client does run under the `Network Service` account by default. All of the system-provided bindings that support secure sessions use a stateless Security Context token by default. However, if the client is an ASP.NET page and secure sessions with stateful Security Context tokens are used, the client cannot be impersonated. For more information about using stateful Security Context tokens in a secure session, see [How to: Create a Security Context Token for a Secure Session](./feature-details/how-to-create-a-security-context-token-for-a-secure-session.md). - -### To enable impersonation of a client from a cached Windows token on a service - -1. Create the service. For a tutorial of this basic procedure, see [Getting Started Tutorial](getting-started-tutorial.md). - -2. Use a binding that uses Windows authentication and creates a session, such as or . - -3. When creating the implementation of the service's interface, apply the class to the method that requires client impersonation. Set the property to . - +> When the client and service are running on the same computer and the client is running under a system account (that is, `Local System` or `Network Service`), the client cannot be impersonated when a secure session is established with stateful Security Context tokens. A WinForms or console application typically is run under the currently logged in account, so that account can be impersonated by default. However, when the client is an ASP.NET page and that page is hosted in IIS 6.0 or IIS 7.0, then the client does run under the `Network Service` account by default. All of the system-provided bindings that support secure sessions use a stateless Security Context token by default. However, if the client is an ASP.NET page and secure sessions with stateful Security Context tokens are used, the client cannot be impersonated. For more information about using stateful Security Context tokens in a secure session, see [How to: Create a Security Context Token for a Secure Session](./feature-details/how-to-create-a-security-context-token-for-a-secure-session.md). + +### To enable impersonation of a client from a cached Windows token on a service + +1. Create the service. For a tutorial of this basic procedure, see [Getting Started Tutorial](getting-started-tutorial.md). + +2. Use a binding that uses Windows authentication and creates a session, such as or . + +3. When creating the implementation of the service's interface, apply the class to the method that requires client impersonation. Set the property to . + [!code-csharp[c_SimpleImpersonation#2](../../../samples/snippets/csharp/VS_Snippets_CFX/c_simpleimpersonation/cs/source.cs#2)] - [!code-vb[c_SimpleImpersonation#2](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_simpleimpersonation/vb/source.vb#2)] - -### To set the allowed impersonation level on the client - -1. Create service client code by using the [ServiceModel Metadata Utility Tool (Svcutil.exe)](servicemodel-metadata-utility-tool-svcutil-exe.md). For more information, see [Accessing Services Using a WCF Client](accessing-services-using-a-wcf-client.md). - -2. After creating the WCF client, set the property of the class to one of the enumeration values. - + [!code-vb[c_SimpleImpersonation#2](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_simpleimpersonation/vb/source.vb#2)] + +### To set the allowed impersonation level on the client + +1. Create service client code by using the [ServiceModel Metadata Utility Tool (Svcutil.exe)](servicemodel-metadata-utility-tool-svcutil-exe.md). For more information, see [Accessing Services Using a WCF Client](accessing-services-using-a-wcf-client.md). + +2. After creating the WCF client, set the property of the class to one of the enumeration values. + > [!NOTE] - > To use , negotiated Kerberos authentication (sometimes called *multi-leg* or *multi-step* Kerberos) must be used. For a description of how to implement this, see [Best Practices for Security](./feature-details/best-practices-for-security-in-wcf.md). - + > To use , negotiated Kerberos authentication (sometimes called *multi-leg* or *multi-step* Kerberos) must be used. For a description of how to implement this, see [Best Practices for Security](./feature-details/best-practices-for-security-in-wcf.md). + [!code-csharp[c_SimpleImpersonation#1](../../../samples/snippets/csharp/VS_Snippets_CFX/c_simpleimpersonation/cs/source.cs#1)] - [!code-vb[c_SimpleImpersonation#1](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_simpleimpersonation/vb/source.vb#1)] - + [!code-vb[c_SimpleImpersonation#1](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_simpleimpersonation/vb/source.vb#1)] + ## See also - diff --git a/docs/framework/wcf/how-to-implement-an-asynchronous-service-operation.md b/docs/framework/wcf/how-to-implement-an-asynchronous-service-operation.md index 59a7d60683182..a88b1ed1078a8 100644 --- a/docs/framework/wcf/how-to-implement-an-asynchronous-service-operation.md +++ b/docs/framework/wcf/how-to-implement-an-asynchronous-service-operation.md @@ -2,46 +2,46 @@ title: "How to: Implement an Asynchronous Service Operation" description: Learn about the structure of an asynchronous service operation in WFC. A service operation can be implemented asynchronously or synchronously. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 4e5d2ea5-d8f8-4712-bd18-ea3c5461702c --- # How to: Implement an Asynchronous Service Operation -In Windows Communication Foundation (WCF) applications, a service operation can be implemented asynchronously or synchronously without dictating to the client how to call it. For example, asynchronous service operations can be called synchronously, and synchronous service operations can be called asynchronously. For an example that shows how to call an operation asynchronously in a client application, see [How to: Call Service Operations Asynchronously](./feature-details/how-to-call-wcf-service-operations-asynchronously.md). For more information about synchronous and asynchronous operations, see [Designing Service Contracts](designing-service-contracts.md) and [Synchronous and Asynchronous Operations](synchronous-and-asynchronous-operations.md). This topic describes the basic structure of an asynchronous service operation, the code is not complete. For a complete example of both the service and client sides, see [Asynchronous](/previous-versions/dotnet/netframework-4.0/ms751505(v=vs.100)). - -### Implement a service operation asynchronously - -1. In your service contract, declare an asynchronous method pair according to the .NET asynchronous design guidelines. The `Begin` method takes a parameter, a callback object, and a state object, and returns a and a matching `End` method that takes a and returns the return value. For more information about asynchronous calls, see [Asynchronous Programming Design Patterns](../../standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md). - -2. Mark the `Begin` method of the asynchronous method pair with the attribute and set the property to `true`. For example, the following code performs steps 1 and 2. - +In Windows Communication Foundation (WCF) applications, a service operation can be implemented asynchronously or synchronously without dictating to the client how to call it. For example, asynchronous service operations can be called synchronously, and synchronous service operations can be called asynchronously. For an example that shows how to call an operation asynchronously in a client application, see [How to: Call Service Operations Asynchronously](./feature-details/how-to-call-wcf-service-operations-asynchronously.md). For more information about synchronous and asynchronous operations, see [Designing Service Contracts](designing-service-contracts.md) and [Synchronous and Asynchronous Operations](synchronous-and-asynchronous-operations.md). This topic describes the basic structure of an asynchronous service operation, the code is not complete. For a complete example of both the service and client sides, see [Asynchronous](/previous-versions/dotnet/netframework-4.0/ms751505(v=vs.100)). + +### Implement a service operation asynchronously + +1. In your service contract, declare an asynchronous method pair according to the .NET asynchronous design guidelines. The `Begin` method takes a parameter, a callback object, and a state object, and returns a and a matching `End` method that takes a and returns the return value. For more information about asynchronous calls, see [Asynchronous Programming Design Patterns](../../standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md). + +2. Mark the `Begin` method of the asynchronous method pair with the attribute and set the property to `true`. For example, the following code performs steps 1 and 2. + [!code-csharp[C_SyncAsyncClient#6](../../../samples/snippets/csharp/VS_Snippets_CFX/c_syncasyncclient/cs/services.cs#6)] - [!code-vb[C_SyncAsyncClient#6](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_syncasyncclient/vb/services.vb#6)] - -3. Implement the `Begin/End` method pair in your service class according to the asynchronous design guidelines. For example, the following code example shows an implementation in which a string is written to the console in both the `Begin` and `End` portions of the asynchronous service operation, and the return value of the `End` operation is returned to the client. For the complete code example, see the Example section. - + [!code-vb[C_SyncAsyncClient#6](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_syncasyncclient/vb/services.vb#6)] + +3. Implement the `Begin/End` method pair in your service class according to the asynchronous design guidelines. For example, the following code example shows an implementation in which a string is written to the console in both the `Begin` and `End` portions of the asynchronous service operation, and the return value of the `End` operation is returned to the client. For the complete code example, see the Example section. + [!code-csharp[C_SyncAsyncClient#3](../../../samples/snippets/csharp/VS_Snippets_CFX/c_syncasyncclient/cs/services.cs#3)] - [!code-vb[C_SyncAsyncClient#3](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_syncasyncclient/vb/services.vb#3)] - -## Example - - The following code examples show: - -1. A service contract interface with: - - 1. A synchronous `SampleMethod` operation. - - 2. An asynchronous `BeginSampleMethod` operation. - - 3. An asynchronous `BeginServiceAsyncMethod`/`EndServiceAsyncMethod` operation pair. - -2. A service implementation using a object. - + [!code-vb[C_SyncAsyncClient#3](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_syncasyncclient/vb/services.vb#3)] + +## Example + + The following code examples show: + +1. A service contract interface with: + + 1. A synchronous `SampleMethod` operation. + + 2. An asynchronous `BeginSampleMethod` operation. + + 3. An asynchronous `BeginServiceAsyncMethod`/`EndServiceAsyncMethod` operation pair. + +2. A service implementation using a object. + [!code-csharp[C_SyncAsyncClient#1](../../../samples/snippets/csharp/VS_Snippets_CFX/c_syncasyncclient/cs/services.cs#1)] - [!code-vb[C_SyncAsyncClient#1](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_syncasyncclient/vb/services.vb#1)] - + [!code-vb[C_SyncAsyncClient#1](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_syncasyncclient/vb/services.vb#1)] + ## See also - [Designing Service Contracts](designing-service-contracts.md) diff --git a/docs/framework/wcf/how-to-restrict-access-with-the-principalpermissionattribute-class.md b/docs/framework/wcf/how-to-restrict-access-with-the-principalpermissionattribute-class.md index eebbcdb684af7..69ea1151ff36f 100644 --- a/docs/framework/wcf/how-to-restrict-access-with-the-principalpermissionattribute-class.md +++ b/docs/framework/wcf/how-to-restrict-access-with-the-principalpermissionattribute-class.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Restrict Access with the PrincipalPermissionAttribute Class" title: "How to: Restrict Access with the PrincipalPermissionAttribute Class" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "PrincipalPermissionAttribute class" - "WCF, authorization" - "WCF, security" @@ -13,79 +13,79 @@ ms.assetid: 5162f5c4-8781-4cc4-9425-bb7620eaeaf4 --- # How to: Restrict Access with the PrincipalPermissionAttribute Class -Controlling the access to resources on a Windows-domain computer is a basic security task. For example, only certain users should be able to view sensitive data, such as payroll information. This topic explains how to restrict access to a method by demanding that the user belong to a predefined group. For a working sample, see [Authorizing Access to Service Operations](./samples/authorizing-access-to-service-operations.md). - - The task consists of two separate procedures. The first creates the group and populates it with users. The second applies the class to specify the group. - -### To create a Windows group - -1. Open the **Computer Management** console. - -2. In the left panel, click **Local Users and Groups**. - -3. Right-click **Groups**, and click **New Group**. - -4. In the **Group Name** box, type a name for the new group. - -5. In the **Description** box, type a description of the new group. - -6. Click the **Add** button to add new members to the group. - -7. If you have added yourself to the group and want to test the following code, you must log off the computer and log back on to be included in the group. - -### To demand user membership - -1. Open the Windows Communication Foundation (WCF) code file that contains the implemented service contract code. For more information about implementing a contract, see [Implementing Service Contracts](implementing-service-contracts.md). - -2. Apply the attribute to each method that must be restricted to a specific group. Set the property to and the property to the name of the group. For example: - +Controlling the access to resources on a Windows-domain computer is a basic security task. For example, only certain users should be able to view sensitive data, such as payroll information. This topic explains how to restrict access to a method by demanding that the user belong to a predefined group. For a working sample, see [Authorizing Access to Service Operations](./samples/authorizing-access-to-service-operations.md). + + The task consists of two separate procedures. The first creates the group and populates it with users. The second applies the class to specify the group. + +### To create a Windows group + +1. Open the **Computer Management** console. + +2. In the left panel, click **Local Users and Groups**. + +3. Right-click **Groups**, and click **New Group**. + +4. In the **Group Name** box, type a name for the new group. + +5. In the **Description** box, type a description of the new group. + +6. Click the **Add** button to add new members to the group. + +7. If you have added yourself to the group and want to test the following code, you must log off the computer and log back on to be included in the group. + +### To demand user membership + +1. Open the Windows Communication Foundation (WCF) code file that contains the implemented service contract code. For more information about implementing a contract, see [Implementing Service Contracts](implementing-service-contracts.md). + +2. Apply the attribute to each method that must be restricted to a specific group. Set the property to and the property to the name of the group. For example: + [!code-csharp[c_PrincipalPermissionAttribute#1](../../../samples/snippets/csharp/VS_Snippets_CFX/c_principalpermissionattribute/cs/source.cs#1)] - [!code-vb[c_PrincipalPermissionAttribute#1](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_principalpermissionattribute/vb/source.vb#1)] - + [!code-vb[c_PrincipalPermissionAttribute#1](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_principalpermissionattribute/vb/source.vb#1)] + > [!NOTE] - > If you apply the attribute to a contract a will be thrown. You can only apply the attribute at the method level. - -## Using a Certificate to Control Access to a Method - - You can also use the `PrincipalPermissionAttribute` class to control access to a method if the client credential type is a certificate. To do this, you must have the certificate's subject and thumbprint. - - To examine a certificate for its properties, see [How to: View Certificates with the MMC Snap-in](./feature-details/how-to-view-certificates-with-the-mmc-snap-in.md). To find the thumbprint value, see [How to: Retrieve the Thumbprint of a Certificate](./feature-details/how-to-retrieve-the-thumbprint-of-a-certificate.md). - -#### To control access using a certificate - -1. Apply the class to the method you want to restrict access to. - -2. Set the action of the attribute to . - -3. Set the `Name` property to a string that consists of the subject name and the certificate's thumbprint. Separate the two values with a semicolon and a space, as shown in the following example: - + > If you apply the attribute to a contract a will be thrown. You can only apply the attribute at the method level. + +## Using a Certificate to Control Access to a Method + + You can also use the `PrincipalPermissionAttribute` class to control access to a method if the client credential type is a certificate. To do this, you must have the certificate's subject and thumbprint. + + To examine a certificate for its properties, see [How to: View Certificates with the MMC Snap-in](./feature-details/how-to-view-certificates-with-the-mmc-snap-in.md). To find the thumbprint value, see [How to: Retrieve the Thumbprint of a Certificate](./feature-details/how-to-retrieve-the-thumbprint-of-a-certificate.md). + +#### To control access using a certificate + +1. Apply the class to the method you want to restrict access to. + +2. Set the action of the attribute to . + +3. Set the `Name` property to a string that consists of the subject name and the certificate's thumbprint. Separate the two values with a semicolon and a space, as shown in the following example: + [!code-csharp[c_PrincipalPermissionAttribute#2](../../../samples/snippets/csharp/VS_Snippets_CFX/c_principalpermissionattribute/cs/source.cs#2)] - [!code-vb[c_PrincipalPermissionAttribute#2](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_principalpermissionattribute/vb/source.vb#2)] - -4. Set the property to as shown in the following configuration example: - - ```xml - - - - - - - - ``` - - Setting this value to `UseAspNetRoles` indicates that the `Name` property of the `PrincipalPermissionAttribute` will be used to perform a string comparison. When a certificate is used as a client credential, by default WCF concatenates the certificate common name and the thumbprint with a semicolon to create a unique value for the client's primary identity. With `UseAspNetRoles` set as the `PrincipalPermissionMode` on the service, this primary identity value is compared with the `Name` property value to determine the access rights of the user. - - Alternatively, when creating a self-hosted service, set the property in code as shown in the following code: - + [!code-vb[c_PrincipalPermissionAttribute#2](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_principalpermissionattribute/vb/source.vb#2)] + +4. Set the property to as shown in the following configuration example: + + ```xml + + + + + + + + ``` + + Setting this value to `UseAspNetRoles` indicates that the `Name` property of the `PrincipalPermissionAttribute` will be used to perform a string comparison. When a certificate is used as a client credential, by default WCF concatenates the certificate common name and the thumbprint with a semicolon to create a unique value for the client's primary identity. With `UseAspNetRoles` set as the `PrincipalPermissionMode` on the service, this primary identity value is compared with the `Name` property value to determine the access rights of the user. + + Alternatively, when creating a self-hosted service, set the property in code as shown in the following code: + [!code-csharp[c_PrincipalPermissionAttribute#3](../../../samples/snippets/csharp/VS_Snippets_CFX/c_principalpermissionattribute/cs/source.cs#3)] - [!code-vb[c_PrincipalPermissionAttribute#3](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_principalpermissionattribute/vb/source.vb#3)] - + [!code-vb[c_PrincipalPermissionAttribute#3](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_principalpermissionattribute/vb/source.vb#3)] + ## See also - - -- +- - [Authorizing Access to Service Operations](./samples/authorizing-access-to-service-operations.md) - [Security Overview](./feature-details/security-overview.md) - [Implementing Service Contracts](implementing-service-contracts.md) diff --git a/docs/framework/wcf/how-to-secure-a-service-with-windows-credentials.md b/docs/framework/wcf/how-to-secure-a-service-with-windows-credentials.md index 55ce4ff640666..80afede94a185 100644 --- a/docs/framework/wcf/how-to-secure-a-service-with-windows-credentials.md +++ b/docs/framework/wcf/how-to-secure-a-service-with-windows-credentials.md @@ -31,9 +31,9 @@ The first procedure walks through creating and configuring a class. -3. Set the property of the class to . +3. Set the property of the class to . -4. Set the property of the class to . +4. Set the property of the class to . 5. The code for this procedure is as follows: @@ -58,7 +58,7 @@ This is the second procedure, which shows how to use the binding in a self-hoste 6. Add an endpoint to the service using the `contractType`, binding, and an endpoint name (secureCalculator). A client must concatenate the base address and the endpoint name when initiating a call to the service. -7. Call the method to start the service. The code for this procedure is shown here: +7. Call the method to start the service. The code for this procedure is shown here: [!code-csharp[c_SecureWindowsService#2](../../../samples/snippets/csharp/VS_Snippets_CFX/c_securewindowsservice/cs/secureservice.cs#2)] [!code-vb[c_SecureWindowsService#2](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_securewindowsservice/vb/secureservice.vb#2)] @@ -73,7 +73,7 @@ This example uses only code to create the client. As an alternative, you can use #### To use a binding in a client with code -1. Use the SvcUtil.exe tool to generate the proxy code from the service's metadata. For more information, see [How to: Create a Client](how-to-create-a-wcf-client.md). The generated proxy code inherits from the class, which ensures that every client has the necessary constructors, methods, and properties to communicate with a WCF service. In this example, the generated code includes the `CalculatorClient` class, which implements the `ICalculator` interface, enabling compatibility with the service code. +1. Use the SvcUtil.exe tool to generate the proxy code from the service's metadata. For more information, see [How to: Create a Client](how-to-create-a-wcf-client.md). The generated proxy code inherits from the class, which ensures that every client has the necessary constructors, methods, and properties to communicate with a WCF service. In this example, the generated code includes the `CalculatorClient` class, which implements the `ICalculator` interface, enabling compatibility with the service code. 2. This procedure's code is inserted at the beginning of the `Main` method of the client program. @@ -83,7 +83,7 @@ This example uses only code to create the client. As an alternative, you can use 5. Create an instance of the generated client class with the `serviceAddress` and the `clientBinding` variables. -6. Call the method, as shown in the following code. +6. Call the method, as shown in the following code. 7. Call the service and display the results. @@ -137,7 +137,7 @@ This procedure shows how to generate two files: a proxy that communicates with t 4. Create an instance of the generated client class passing the name of the binding in the configuration file as an input parameter. -5. Call the method, as shown in the following code. +5. Call the method, as shown in the following code. 6. Call the service and display the results. diff --git a/docs/framework/wcf/how-to-set-the-security-mode.md b/docs/framework/wcf/how-to-set-the-security-mode.md index 6f828338b8a61..a66e9c8108032 100644 --- a/docs/framework/wcf/how-to-set-the-security-mode.md +++ b/docs/framework/wcf/how-to-set-the-security-mode.md @@ -45,7 +45,7 @@ For more information, see WCF security, see [Security Overview](./feature-detail ## Setting the ClientCredentialType Property -Setting the mode to one of the three values determines how you set the `ClientCredentialType` property. For example, using the class, setting the mode to `Transport` means you must set the property of the class to an appropriate value. +Setting the mode to one of the three values determines how you set the `ClientCredentialType` property. For example, using the class, setting the mode to `Transport` means you must set the property of the class to an appropriate value. ### To set the ClientCredentialType property for Transport mode diff --git a/docs/framework/wcf/how-to-specify-client-credential-values.md b/docs/framework/wcf/how-to-specify-client-credential-values.md index 1b91b267cf8bd..d30f6836dfc56 100644 --- a/docs/framework/wcf/how-to-specify-client-credential-values.md +++ b/docs/framework/wcf/how-to-specify-client-credential-values.md @@ -44,7 +44,7 @@ This example sets the security mode to Transport mode and sets the client creden 2. Create an instance of the WCF client using the generated code. -3. On the client class, set the property of the class to an appropriate value. This example sets the property to an X.509 certificate using the method of the class. +3. On the client class, set the property of the class to an appropriate value. This example sets the property to an X.509 certificate using the method of the class. [!code-csharp[c_TcpService#4](../../../samples/snippets/csharp/VS_Snippets_CFX/c_tcpservice/cs/source.cs#4)] [!code-vb[c_TcpService#4](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_tcpservice/vb/source.vb#4)] @@ -91,9 +91,9 @@ This example sets the security mode to Transport mode and sets the client creden ## See also - -- +- - -- +- - - [Programming WCF Security](./feature-details/programming-wcf-security.md) - [Selecting a Credential Type](./feature-details/selecting-a-credential-type.md) diff --git a/docs/framework/wcf/how-to-specify-the-client-credential-type.md b/docs/framework/wcf/how-to-specify-the-client-credential-type.md index bb3f94b5d05f1..3ede00573cc26 100644 --- a/docs/framework/wcf/how-to-specify-the-client-credential-type.md +++ b/docs/framework/wcf/how-to-specify-the-client-credential-type.md @@ -2,57 +2,57 @@ description: "Learn more about: How to: Specify the Client Credential Type" title: "How to: Specify the Client Credential Type" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "security credentials, adding to SOAP messages" - "WCF, security" ms.assetid: 10f51bee-5f92-4c1a-9126-fa5418535d8f --- # How to: Specify the Client Credential Type -After setting a security mode (either transport or message), you have the option of setting the client credential type. This property specifies what type of credential the client must provide to the service for authentication. For more information about setting the security mode (a necessary step before setting the client credential type), see [How to: Set the Security Mode](how-to-set-the-security-mode.md). - -### To set the client credential type in code - -1. Create an instance of the binding that the service will use. This example uses the binding. - -2. Set the property to an appropriate value. This example uses the Message mode. - -3. Set the property to an appropriate value. This example sets it to use Windows authentication (). - +After setting a security mode (either transport or message), you have the option of setting the client credential type. This property specifies what type of credential the client must provide to the service for authentication. For more information about setting the security mode (a necessary step before setting the client credential type), see [How to: Set the Security Mode](how-to-set-the-security-mode.md). + +### To set the client credential type in code + +1. Create an instance of the binding that the service will use. This example uses the binding. + +2. Set the property to an appropriate value. This example uses the Message mode. + +3. Set the property to an appropriate value. This example sets it to use Windows authentication (). + [!code-csharp[c_ProgrammingSecurity#14](../../../samples/snippets/csharp/VS_Snippets_CFX/c_programmingsecurity/cs/source.cs#14)] - [!code-vb[c_ProgrammingSecurity#14](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_programmingsecurity/vb/source.vb#14)] - -### To set the client credential type in configuration - -1. Add a [\](../configure-apps/file-schema/wcf/system-servicemodel.md) element to the configuration file. - -2. As a child element, add a [\](../configure-apps/file-schema/wcf/bindings.md) element. - -3. Add an appropriate binding. This example uses the [\](../configure-apps/file-schema/wcf/wshttpbinding.md) element. - -4. Add a [\](../configure-apps/file-schema/wcf/bindings.md) element and set the `name` attribute to an appropriate value. This example uses the name "SecureBinding". - -5. Add a `` binding. Set the `mode` attribute to an appropriate value. This example sets it to `"Message"`. - -6. Add either a `` or `` element, as determined by the security mode. Set the `clientCredentialType` attribute to an appropriate value. This example uses `"Windows"`. - - ```xml - - - - - - - - - - - - ``` - + [!code-vb[c_ProgrammingSecurity#14](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_programmingsecurity/vb/source.vb#14)] + +### To set the client credential type in configuration + +1. Add a [\](../configure-apps/file-schema/wcf/system-servicemodel.md) element to the configuration file. + +2. As a child element, add a [\](../configure-apps/file-schema/wcf/bindings.md) element. + +3. Add an appropriate binding. This example uses the [\](../configure-apps/file-schema/wcf/wshttpbinding.md) element. + +4. Add a [\](../configure-apps/file-schema/wcf/bindings.md) element and set the `name` attribute to an appropriate value. This example uses the name "SecureBinding". + +5. Add a `` binding. Set the `mode` attribute to an appropriate value. This example sets it to `"Message"`. + +6. Add either a `` or `` element, as determined by the security mode. Set the `clientCredentialType` attribute to an appropriate value. This example uses `"Windows"`. + + ```xml + + + + + + + + + + + + ``` + ## See also - [Securing Services](securing-services.md) diff --git a/docs/framework/wcf/load-balancing.md b/docs/framework/wcf/load-balancing.md index f5bcc07727b30..115c45e0fdc31 100644 --- a/docs/framework/wcf/load-balancing.md +++ b/docs/framework/wcf/load-balancing.md @@ -2,96 +2,96 @@ description: "Learn more about: Load Balancing" title: "Load Balancing" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "load balancing [WCF]" ms.assetid: 148e0168-c08d-4886-8769-776d0953b80f --- # Load Balancing -One way to increase the capacity of Windows Communication Foundation (WCF) applications is to scale them out by deploying them into a load-balanced server farm. WCF applications can be load balanced using standard load balancing techniques, including software load balancers such as Windows Network Load Balancing as well as hardware-based load balancing appliances. - - The following sections discuss considerations for load balancing WCF applications built using various system-provided bindings. - -## Load Balancing with the Basic HTTP Binding - - From the perspective of load balancing, WCF applications that communicate using the are no different than other common types of HTTP network traffic (static HTML content, ASP.NET pages, or ASMX Web Services). WCF channels that use this binding are inherently stateless, and terminate their connections when the channel closes. As such, the works well with existing HTTP load balancing techniques. - - By default, the sends a connection HTTP header in messages with a `Keep-Alive` value, which enables clients to establish persistent connections to the services that support them. This configuration offers enhanced throughput because previously established connections can be reused to send subsequent messages to the same server. However, connection reuse may cause clients to become strongly associated to a specific server within the load-balanced farm, which reduces the effectiveness of round-robin load balancing. If this behavior is undesirable, HTTP `Keep-Alive` can be disabled on the server using the property with a or user-defined . The following example shows how to do this using configuration. - -```xml - - - - - +One way to increase the capacity of Windows Communication Foundation (WCF) applications is to scale them out by deploying them into a load-balanced server farm. WCF applications can be load balanced using standard load balancing techniques, including software load balancers such as Windows Network Load Balancing as well as hardware-based load balancing appliances. + + The following sections discuss considerations for load balancing WCF applications built using various system-provided bindings. + +## Load Balancing with the Basic HTTP Binding + + From the perspective of load balancing, WCF applications that communicate using the are no different than other common types of HTTP network traffic (static HTML content, ASP.NET pages, or ASMX Web Services). WCF channels that use this binding are inherently stateless, and terminate their connections when the channel closes. As such, the works well with existing HTTP load balancing techniques. + + By default, the sends a connection HTTP header in messages with a `Keep-Alive` value, which enables clients to establish persistent connections to the services that support them. This configuration offers enhanced throughput because previously established connections can be reused to send subsequent messages to the same server. However, connection reuse may cause clients to become strongly associated to a specific server within the load-balanced farm, which reduces the effectiveness of round-robin load balancing. If this behavior is undesirable, HTTP `Keep-Alive` can be disabled on the server using the property with a or user-defined . The following example shows how to do this using configuration. + +```xml + + + + + - - - - - - - + + + + + + + - - - - - - - - - - - - - -``` - - Using the simplified configuration introduced in .NET Framework 4, the same behavior can be accomplished using the following simplified configuration. - -```xml - - - - - - - - - - - - - - - - -``` - - For more information about default endpoints, bindings, and behaviors, see [Simplified Configuration](simplified-configuration.md) and [Simplified Configuration for WCF Services](./samples/simplified-configuration-for-wcf-services.md). - -## Load Balancing with the WSHttp Binding and the WSDualHttp Binding - - Both the and the can be load balanced using HTTP load balancing techniques provided several modifications are made to the default binding configuration. - -- Turn off Security Context Establishment or use stateful security sessions. Security Context Establishment can be turned off by setting the property on the to `false`. If you are using or security sessions are required, it is possible to use stateful security sessions as described in [Secure Sessions](./feature-details/secure-sessions.md). Stateful security sessions enable the service to remain stateless, as all of the state for the security session is transmitted with each request as a part of the protection security token. To enable a stateful security session, you must use a or user-defined , as the necessary configuration settings are not exposed on the system-provided and . + contract="Microsoft.ServiceModel.Samples.ICalculator" /> + + + + + + + + + + + + + +``` + + Using the simplified configuration introduced in .NET Framework 4, the same behavior can be accomplished using the following simplified configuration. + +```xml + + + + + + + + + + + + + + + + +``` + + For more information about default endpoints, bindings, and behaviors, see [Simplified Configuration](simplified-configuration.md) and [Simplified Configuration for WCF Services](./samples/simplified-configuration-for-wcf-services.md). + +## Load Balancing with the WSHttp Binding and the WSDualHttp Binding + + Both the and the can be load balanced using HTTP load balancing techniques provided several modifications are made to the default binding configuration. + +- Turn off Security Context Establishment or use stateful security sessions. Security Context Establishment can be turned off by setting the property on the to `false`. If you are using or security sessions are required, it is possible to use stateful security sessions as described in [Secure Sessions](./feature-details/secure-sessions.md). Stateful security sessions enable the service to remain stateless, as all of the state for the security session is transmitted with each request as a part of the protection security token. To enable a stateful security session, you must use a or user-defined , as the necessary configuration settings are not exposed on the system-provided and . - If you turn off Security Context Establishment, you also need to turn off Service Credential Negotiation. To turn it off, set the property on the to `false`. To disable Service Credential Negotiation, you may need to explicitly specify the endpoint identity on the client. - -- Do not use reliable sessions. This feature is off by default. - -## Load Balancing the Net.TCP Binding - - The can be load balanced using IP-layer load balancing techniques. However, the pools TCP connections by default to reduce connection latency. This is an optimization that interferes with the basic mechanism of load balancing. The primary configuration value for optimizing the is the lease timeout, which is part of the Connection Pool Settings. Connection pooling causes client connections to become associated to specific servers within the farm. As the lifetime of those connections increase (a factor controlled by the lease timeout setting), the load distribution across various servers in the farm becomes unbalanced. As a result the average call time increases. So when using the in load-balanced scenarios, consider reducing the default lease timeout used by the binding. A 30-second lease timeout is a reasonable starting point for load-balanced scenarios, although the optimal value is application-dependent. For more information about the channel lease timeout and other transport quotas, see [Transport Quotas](./feature-details/transport-quotas.md). - - For best performance in load-balanced scenarios, consider using (either or ). - + +- Do not use reliable sessions. This feature is off by default. + +## Load Balancing the Net.TCP Binding + + The can be load balanced using IP-layer load balancing techniques. However, the pools TCP connections by default to reduce connection latency. This is an optimization that interferes with the basic mechanism of load balancing. The primary configuration value for optimizing the is the lease timeout, which is part of the Connection Pool Settings. Connection pooling causes client connections to become associated to specific servers within the farm. As the lifetime of those connections increase (a factor controlled by the lease timeout setting), the load distribution across various servers in the farm becomes unbalanced. As a result the average call time increases. So when using the in load-balanced scenarios, consider reducing the default lease timeout used by the binding. A 30-second lease timeout is a reasonable starting point for load-balanced scenarios, although the optimal value is application-dependent. For more information about the channel lease timeout and other transport quotas, see [Transport Quotas](./feature-details/transport-quotas.md). + + For best performance in load-balanced scenarios, consider using (either or ). + ## See also - [Internet Information Services Hosting Best Practices](./feature-details/internet-information-services-hosting-best-practices.md) diff --git a/docs/framework/wcf/privacy-information.md b/docs/framework/wcf/privacy-information.md index 4c18a7afd56de..5e02fc3313070 100644 --- a/docs/framework/wcf/privacy-information.md +++ b/docs/framework/wcf/privacy-information.md @@ -103,11 +103,11 @@ Microsoft is committed to protecting end user privacy. When you build an applica The diagnostics feature of the WCF infrastructure logs messages that pass through the transport and service model layers, and the activities and events associated with these messages. This feature is turned off by default. It is enabled using the application’s configuration file and the tracing behavior may be modified using the WCF WMI provider at runtime. When enabled, the tracing infrastructure emits a diagnostic trace that contains messages, activities, and processing events to configured listeners. The format and location of the output are determined by the administrator’s listener configuration choices, but is typically an XML formatted file. The administrator is responsible for setting the access control list (ACL) on the trace files. In particular, when hosted by Windows Activation System (WAS), the administrator should make sure the files are not served from the public virtual root directory if that is not desired. - There are two types of tracing: Message logging and Service Model diagnostic tracing, described in the following section. Each type is configured through its own trace source: and . Both of these logging trace sources capture data that is local to the application. + There are two types of tracing: Message logging and Service Model diagnostic tracing, described in the following section. Each type is configured through its own trace source: and . Both of these logging trace sources capture data that is local to the application. ### Message logging - The message logging trace source () allows an administrator to log the messages that flow through the system. Through configuration, the user may decide to log entire messages or message headers only, whether to log at the transport and/or service model layers, and whether to include malformed messages. Also, the user may configure filtering to restrict which messages are logged. + The message logging trace source () allows an administrator to log the messages that flow through the system. Through configuration, the user may decide to log entire messages or message headers only, whether to log at the transport and/or service model layers, and whether to include malformed messages. Also, the user may configure filtering to restrict which messages are logged. By default, message logging is disabled. The local machine administrator can prevent the application-level administrator from turning message logging on. @@ -280,7 +280,7 @@ Microsoft is committed to protecting end user privacy. When you build an applica ### Service model tracing - The Service Model trace source () enables tracing of activities and events related to message processing. This feature uses the .NET Framework diagnostic functionality from . As with the property, the location and its ACL are user-configurable using .NET Framework application configuration files. As with message logging, the file location is always configured when the administrator enables tracing; thus, the administrator controls the ACL. + The Service Model trace source () enables tracing of activities and events related to message processing. This feature uses the .NET Framework diagnostic functionality from . As with the property, the location and its ACL are user-configurable using .NET Framework application configuration files. As with message logging, the file location is always configured when the administrator enables tracing; thus, the administrator controls the ACL. Traces contain message headers when a message is in scope. The same rules for hiding potentially personal information in message headers in the previous section apply: the personal information previously identified is removed by default from the headers in traces. Both the machine administrator and the application deployer must modify the configuration in order to log potentially personal information. However, personal information contained in application-specific headers is logged in traces. The application deployer is responsible for setting the ACLs on the configuration and trace files. They can also turn off tracing to hide this information or filter out this information from the trace files after it's logged. @@ -296,7 +296,7 @@ Microsoft is committed to protecting end user privacy. When you build an applica WCF configuration uses the .NET Framework configuration mechanism. The configuration files are stored on the machine. The application developer and the administrator create the configuration files and ACL for each of the application's requirements. A configuration file can contain endpoint addresses and links to certificates in the certificate store. The certificates can be used to provide application data to configure various properties of the features used by the application. - WCF also uses the .NET Framework process dump functionality by calling the method. + WCF also uses the .NET Framework process dump functionality by calling the method. ### IT pro tools diff --git a/docs/framework/wcf/samples/authorization-policy.md b/docs/framework/wcf/samples/authorization-policy.md index 7700db5de19d8..000cc244669b4 100644 --- a/docs/framework/wcf/samples/authorization-policy.md +++ b/docs/framework/wcf/samples/authorization-policy.md @@ -232,7 +232,7 @@ catch (Exception e) client2.Close(); ``` -This sample uses a custom to validate user names and passwords. The sample implements `MyCustomUserNamePasswordValidator`, derived from . See the documentation about for more information. For the purposes of demonstrating the integration with the , this custom validator sample implements the method to accept user name/password pairs where the user name matches the password as shown in the following code. +This sample uses a custom to validate user names and passwords. The sample implements `MyCustomUserNamePasswordValidator`, derived from . See the documentation about for more information. For the purposes of demonstrating the integration with the , this custom validator sample implements the method to accept user name/password pairs where the user name matches the password as shown in the following code. ```csharp public class MyCustomUserNamePasswordValidator : UserNamePasswordValidator @@ -280,7 +280,7 @@ Or you can do the same thing in configuration: Windows Communication Foundation (WCF) provides a rich claims-based model for performing access checks. The object is used to perform the access check and determine whether the claims associated with the client satisfy the requirements necessary to access the service method. -For the purposes of demonstration, this sample shows an implementation of that implements the method to allow a user's access to methods based on claims of type `http://example.com/claims/allowedoperation` whose value is the Action URI of the operation that is allowed to be called. +For the purposes of demonstration, this sample shows an implementation of that implements the method to allow a user's access to methods based on claims of type `http://example.com/claims/allowedoperation` whose value is the Action URI of the operation that is allowed to be called. ```csharp public class MyServiceAuthorizationManager : ServiceAuthorizationManager diff --git a/docs/framework/wcf/samples/basic-http-service.md b/docs/framework/wcf/samples/basic-http-service.md index 357a6e34d6378..4fc3982c95fd1 100644 --- a/docs/framework/wcf/samples/basic-http-service.md +++ b/docs/framework/wcf/samples/basic-http-service.md @@ -12,11 +12,11 @@ The [BasicHttpService sample](https://github.com/dotnet/samples/tree/main/framew The WCF service exposes 2 operations, `EchoWithGet` and `EchoWithPost`, which returns the string that was passed as input. -The `EchoWithGet` operation is annotated with , which indicates that the operation processes HTTP `GET` requests. Because the does not explicitly specify a , the operation expects the input string to be passed in using a query string parameter with name `s`. Note that the format of the URI that the service expects can be customized using the property. +The `EchoWithGet` operation is annotated with , which indicates that the operation processes HTTP `GET` requests. Because the does not explicitly specify a , the operation expects the input string to be passed in using a query string parameter with name `s`. Note that the format of the URI that the service expects can be customized using the property. -The `EchoWithPost` operation is annotated with , which indicates it is not a `GET` operation (it has side effects). Because the does not explicitly specify a `Method`, the operation processes HTTP `POST` requests that have the string in the request body (in the XML format, for instance). Note that the HTTP method and the format of the URI for the request can be customized using the and properties respectively. +The `EchoWithPost` operation is annotated with , which indicates it is not a `GET` operation (it has side effects). Because the does not explicitly specify a `Method`, the operation processes HTTP `POST` requests that have the string in the request body (in the XML format, for instance). Note that the HTTP method and the format of the URI for the request can be customized using the and properties respectively. -The App.config file configures the WCF service with a default that has the property set to `true`. As a result, the WCF infrastructure creates an automatic HTML based help page at `http://localhost:8000/Customers/help` that provides information about how to construct HTTP requests to the service and how to consume the service's HTTP response. +The App.config file configures the WCF service with a default that has the property set to `true`. As a result, the WCF infrastructure creates an automatic HTML based help page at `http://localhost:8000/Customers/help` that provides information about how to construct HTTP requests to the service and how to consume the service's HTTP response. Program.cs demonstrates how a WCF channel factory can be used to make calls to the service and process responses. Note that this is just one way to access a WCF service. It is also possible to access the service using other .NET Framework classes like and . diff --git a/docs/framework/wcf/samples/channel-factory.md b/docs/framework/wcf/samples/channel-factory.md index 7408967d38478..b574d760022c3 100644 --- a/docs/framework/wcf/samples/channel-factory.md +++ b/docs/framework/wcf/samples/channel-factory.md @@ -11,7 +11,7 @@ The [ChannelFactory sample](https://github.com/dotnet/samples/tree/main/framewor > [!NOTE] > The setup procedure and build instructions for this sample are located at the end of this topic. -This sample uses the class to create a channel to a service endpoint. Typically, to create a channel to a service endpoint you generate a client type with the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) and create an instance of the generated type. You can also create a channel by using the class, as demonstrated in this sample. The service created by the following sample code is identical to the service in the [Getting Started](getting-started-sample.md). +This sample uses the class to create a channel to a service endpoint. Typically, to create a channel to a service endpoint you generate a client type with the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md) and create an instance of the generated type. You can also create a channel by using the class, as demonstrated in this sample. The service created by the following sample code is identical to the service in the [Getting Started](getting-started-sample.md). ```csharp EndpointAddress address = new EndpointAddress("http://localhost/servicemodelsamples/service.svc"); diff --git a/docs/framework/wcf/samples/configuration-channel-factory.md b/docs/framework/wcf/samples/configuration-channel-factory.md index 21fb9c94c0035..60b3e33ea7323 100644 --- a/docs/framework/wcf/samples/configuration-channel-factory.md +++ b/docs/framework/wcf/samples/configuration-channel-factory.md @@ -6,17 +6,17 @@ ms.assetid: 3b749493-bd8a-4ccb-893e-5948901a1486 --- # Configuration Channel Factory -The [ConfigurationChannelFactory sample](https://github.com/dotnet/samples/tree/main/framework/wcf) covers the usage of the . The allows central management of WCF client configuration. This can also be useful in scenarios in which configuration is selected or changed after the application domain load time. +The [ConfigurationChannelFactory sample](https://github.com/dotnet/samples/tree/main/framework/wcf) covers the usage of the . The allows central management of WCF client configuration. This can also be useful in scenarios in which configuration is selected or changed after the application domain load time. ## Demonstrates - + ## Discussion -This sample shows how to use to add a particular configuration file to a client application, without having to use the default application configuration file. +This sample shows how to use to add a particular configuration file to a client application, without having to use the default application configuration file. -The sample consists of two projects. The first project is a simple service that runs to reply to messages coming from the clients. The second project is a client application that builds two objects using a for the Test.config configuration file and uses them to communicate with the service. Both clients communicate with the service using the configuration specified in Test.config. +The sample consists of two projects. The first project is a simple service that runs to reply to messages coming from the clients. The second project is a client application that builds two objects using a for the Test.config configuration file and uses them to communicate with the service. Both clients communicate with the service using the configuration specified in Test.config. The following code adds a custom configuration file to a client application. diff --git a/docs/framework/wcf/samples/configuration-sample.md b/docs/framework/wcf/samples/configuration-sample.md index 3531e46e3cfa6..313bf4ad60ed3 100644 --- a/docs/framework/wcf/samples/configuration-sample.md +++ b/docs/framework/wcf/samples/configuration-sample.md @@ -50,7 +50,7 @@ To take advantage of announcements, you will need to add an announcement endpoin Adding an announcement endpoint to the discovery service behavior creates a default announcement client for the service. This guarantees that the service will send an online and offline announcement when the service is opened and closed respectively. -This configuration file goes beyond just those simple steps by modifying additional behaviors. It is possible to control discovery-related information by using specific endpoints. That is, a user can control whether an endpoint can be discovered and the user can also mark that endpoint with and custom XML metadata. To do this, the user must add a `behaviorConfiguration` property to the application endpoint. In this case, the following property is added to the application endpoint. +This configuration file goes beyond just those simple steps by modifying additional behaviors. It is possible to control discovery-related information by using specific endpoints. That is, a user can control whether an endpoint can be discovered and the user can also mark that endpoint with and custom XML metadata. To do this, the user must add a `behaviorConfiguration` property to the application endpoint. In this case, the following property is added to the application endpoint. `behaviorConfiguration="endpointBehaviorConfiguration"` diff --git a/docs/framework/wcf/samples/custom-channel-dispatcher.md b/docs/framework/wcf/samples/custom-channel-dispatcher.md index 7d2f48b07d3c0..7a4aec8708ad1 100644 --- a/docs/framework/wcf/samples/custom-channel-dispatcher.md +++ b/docs/framework/wcf/samples/custom-channel-dispatcher.md @@ -10,9 +10,9 @@ The [CustomChannelDispatcher sample](https://github.com/dotnet/samples/tree/main ## Custom ServiceHostBase -This sample implements the base type instead of to demonstrate how to replace the Windows Communication Foundation (WCF) stack implementation with a custom message handling layer on top of the channel stack. You override the virtual method to build channel listeners and the channel dispatcher. +This sample implements the base type instead of to demonstrate how to replace the Windows Communication Foundation (WCF) stack implementation with a custom message handling layer on top of the channel stack. You override the virtual method to build channel listeners and the channel dispatcher. -To implement a Web-hosted service, get the service extension from the collection and add it to the so that the transport layer knows how to configure the channel listener based on the hosting environment settings, that is, the Internet Information Services (IIS)/Windows Process Activation Service (WAS) settings. +To implement a Web-hosted service, get the service extension from the collection and add it to the so that the transport layer knows how to configure the channel listener based on the hosting environment settings, that is, the Internet Information Services (IIS)/Windows Process Activation Service (WAS) settings. ## Custom Channel Dispatcher diff --git a/docs/framework/wcf/samples/custom-find-criteria.md b/docs/framework/wcf/samples/custom-find-criteria.md index fe68740ab9eb8..3bba26444f84a 100644 --- a/docs/framework/wcf/samples/custom-find-criteria.md +++ b/docs/framework/wcf/samples/custom-find-criteria.md @@ -38,11 +38,11 @@ Open the service project. Three files are used to implement the Custom Discovery 1. **AsyncResult.cs**: This is the implementation of the `AsyncResult` that is required by Discovery methods. -2. **CustomDiscoveryService.cs**: This file implements the custom discovery service. The implementation extends the class and overrides the necessary methods. Note the implementation of the method. The method checks to see whether the custom scope match by rule was specified by the client. This is the same custom URI that the client specified previously. If the custom rule is specified, the code path that implements the "OR" match logic is followed. +2. **CustomDiscoveryService.cs**: This file implements the custom discovery service. The implementation extends the class and overrides the necessary methods. Note the implementation of the method. The method checks to see whether the custom scope match by rule was specified by the client. This is the same custom URI that the client specified previously. If the custom rule is specified, the code path that implements the "OR" match logic is followed. This custom logic goes through all of the scopes on each of the endpoints that the service has. If any of the endpoint's scopes match any of the scopes provided by the client, the discovery service adds that endpoint to the response that is sent back to the client. -3. **CustomDiscoveryExtension.cs**: The last step in implementing the discovery service is to connect this implementation of the custom discover service to the service host. The helper class used here is the `CustomDiscoveryExtension` class. This class extends the class. The user must override the method. In this case, the method returns an instance of the custom discovery service that was created before. `PublishedEndpoints` is a that contains all of the application endpoints that are added to the . The custom discovery service uses this to populate its internal list. A user can to add other endpoint metadata as well. +3. **CustomDiscoveryExtension.cs**: The last step in implementing the discovery service is to connect this implementation of the custom discover service to the service host. The helper class used here is the `CustomDiscoveryExtension` class. This class extends the class. The user must override the method. In this case, the method returns an instance of the custom discovery service that was created before. `PublishedEndpoints` is a that contains all of the application endpoints that are added to the . The custom discovery service uses this to populate its internal list. A user can to add other endpoint metadata as well. Lastly, open Program.cs. Note that both the and `CustomDiscoveryExtension` are added to the host. Once this is done and the host has an endpoint over which to receive discovery messages, the application can use the custom discovery service. diff --git a/docs/framework/wcf/samples/custom-lifetime.md b/docs/framework/wcf/samples/custom-lifetime.md index f83e34822dce2..834efaafb0e2f 100644 --- a/docs/framework/wcf/samples/custom-lifetime.md +++ b/docs/framework/wcf/samples/custom-lifetime.md @@ -49,21 +49,21 @@ using (new OperationContextScope((IClientChannel)proxy2)) } ``` -Unlike other instancing modes, the shared instancing mode has a unique way of releasing the service instances. By default, when all the channels are closed for an , the WCF service runtime checks to see if the service is configured to or , and if so releases the instance and claims the resources. If a custom is being used, WCF invokes the method of the provider implementation before releasing the instance. If returns `true` the instance is released, otherwise the implementation is responsible for notifying the `Dispatcher` of the idle state by using a callback method. This is done by calling the method of the provider. +Unlike other instancing modes, the shared instancing mode has a unique way of releasing the service instances. By default, when all the channels are closed for an , the WCF service runtime checks to see if the service is configured to or , and if so releases the instance and claims the resources. If a custom is being used, WCF invokes the method of the provider implementation before releasing the instance. If returns `true` the instance is released, otherwise the implementation is responsible for notifying the `Dispatcher` of the idle state by using a callback method. This is done by calling the method of the provider. This sample demonstrates how you can delay releasing the with an idle timeout of 20 seconds. ## Extending the InstanceContext -In WCF, is the link between the service instance and the `Dispatcher`. WCF allows you to extend this runtime component by adding new state or behavior by using its extensible object pattern. The extensible object pattern is used in WCF to either extend existing runtime classes with new functionality or to add new state features to an object. There are three interfaces in the extensible object pattern: , , and . +In WCF, is the link between the service instance and the `Dispatcher`. WCF allows you to extend this runtime component by adding new state or behavior by using its extensible object pattern. The extensible object pattern is used in WCF to either extend existing runtime classes with new functionality or to add new state features to an object. There are three interfaces in the extensible object pattern: , , and . -The interface is implemented by objects to allow extensions that customize their functionality. +The interface is implemented by objects to allow extensions that customize their functionality. -The interface is implemented by objects that can be extensions of classes of type `T`. +The interface is implemented by objects that can be extensions of classes of type `T`. -And finally, the interface is a collection of implementations that allows for retrieving an implementation of by their type. +And finally, the interface is a collection of implementations that allows for retrieving an implementation of by their type. -Therefore, in order to extend the , you must implement the interface. In this sample project, the `CustomLeaseExtension` class contains this implementation. +Therefore, in order to extend the , you must implement the interface. In this sample project, the `CustomLeaseExtension` class contains this implementation. ```csharp class CustomLeaseExtension : IExtension @@ -71,7 +71,7 @@ class CustomLeaseExtension : IExtension } ``` -The interface has two methods and . As their names imply, these two methods are called when the runtime attaches and detaches the extension to an instance of the class. In this sample, the `Attach` method is used to keep track of the object that belongs to the current instance of the extension. +The interface has two methods and . As their names imply, these two methods are called when the runtime attaches and detaches the extension to an instance of the class. In this sample, the `Attach` method is used to keep track of the object that belongs to the current instance of the extension. ```csharp InstanceContext owner; @@ -96,7 +96,7 @@ class CustomLeaseExtension : IExtension, ICustomLease } ``` -When WCF invokes the method in the implementation, this call is routed to the method of the `CustomLeaseExtension`. Then, the `CustomLeaseExtension` checks its private state to see whether the is idle. If it is idle, it returns `true`. Otherwise, it starts a timer for a specified amount of extended lifetime. +When WCF invokes the method in the implementation, this call is routed to the method of the `CustomLeaseExtension`. Then, the `CustomLeaseExtension` checks its private state to see whether the is idle. If it is idle, it returns `true`. Otherwise, it starts a timer for a specified amount of extended lifetime. ```csharp public bool IsIdle @@ -137,12 +137,12 @@ void idleTimer_Elapsed(object sender, ElapsedEventArgs args) There's no way to renew the running timer when a new message arrives for the instance being moved to the idle state. -The sample implements to intercept the calls to the method and route them to the `CustomLeaseExtension`. The implementation is contained in `CustomLifetimeLease` class. The method is invoked when WCF is about to release the service instance. However, there is only one instance of a particular `ISharedSessionInstance` implementation in the ServiceBehavior's collection. This means there's no way of knowing if the is closed at the time WCF checks the method. Therefore, this sample uses thread locking to serialize requests to the method. +The sample implements to intercept the calls to the method and route them to the `CustomLeaseExtension`. The implementation is contained in `CustomLifetimeLease` class. The method is invoked when WCF is about to release the service instance. However, there is only one instance of a particular `ISharedSessionInstance` implementation in the ServiceBehavior's collection. This means there's no way of knowing if the is closed at the time WCF checks the method. Therefore, this sample uses thread locking to serialize requests to the method. > [!IMPORTANT] > Using thread locking is not a recommended approach because serialization can severely affect the performance of your application. -A private member field is used in the `CustomLifetimeLease` class to track the idle state and is returned by the method. Each time the method is called, the `isIdle` field is returned and reset to `false`. It is essential to set this value to `false` in order to make sure the Dispatcher calls the method. +A private member field is used in the `CustomLifetimeLease` class to track the idle state and is returned by the method. Each time the method is called, the `isIdle` field is returned and reset to `false`. It is essential to set this value to `false` in order to make sure the Dispatcher calls the method. ```csharp public bool IsIdle(InstanceContext instanceContext) @@ -160,7 +160,7 @@ public bool IsIdle(InstanceContext instanceContext) } ``` -If the method returns `false`, the Dispatcher registers a callback function by using the method. This method receives a reference to the being released. Therefore, the sample code can query the `ICustomLease` type extension and check the `ICustomLease.IsIdle` property in the extended state. +If the method returns `false`, the Dispatcher registers a callback function by using the method. This method receives a reference to the being released. Therefore, the sample code can query the `ICustomLease` type extension and check the `ICustomLease.IsIdle` property in the extended state. ```csharp public void NotifyIdle(InstanceContextIdleCallback callback, @@ -180,9 +180,9 @@ public void NotifyIdle(InstanceContextIdleCallback callback, } ``` -Before the `ICustomLease.IsIdle` property is checked, the Callback property needs to be set as this is essential for `CustomLeaseExtension` to notify the Dispatcher when it becomes idle. If `ICustomLease.IsIdle` returns `true`, the `isIdle` private member is simply set in `CustomLifetimeLease` to `true` and calls the callback method. Because the code holds a lock, other threads can't change the value of this private member. And the next time Dispatcher calls the , it returns `true` and lets Dispatcher release the instance. +Before the `ICustomLease.IsIdle` property is checked, the Callback property needs to be set as this is essential for `CustomLeaseExtension` to notify the Dispatcher when it becomes idle. If `ICustomLease.IsIdle` returns `true`, the `isIdle` private member is simply set in `CustomLifetimeLease` to `true` and calls the callback method. Because the code holds a lock, other threads can't change the value of this private member. And the next time Dispatcher calls the , it returns `true` and lets Dispatcher release the instance. -Now that the groundwork for the custom extension is completed, it has to be hooked up to the service model. To hook up the `CustomLeaseExtension` implementation to the , WCF provides the interface to perform the bootstrapping of . In the sample, the `CustomLeaseInitializer` class implements this interface and adds an instance of `CustomLeaseExtension` to the collection from the only method initialization. This method is called by Dispatcher while initializing the . +Now that the groundwork for the custom extension is completed, it has to be hooked up to the service model. To hook up the `CustomLeaseExtension` implementation to the , WCF provides the interface to perform the bootstrapping of . In the sample, the `CustomLeaseInitializer` class implements this interface and adds an instance of `CustomLeaseExtension` to the collection from the only method initialization. This method is called by Dispatcher while initializing the . ```csharp public void InitializeInstanceContext(InstanceContext instanceContext, diff --git a/docs/framework/wcf/samples/custom-message-encoder-compression-encoder.md b/docs/framework/wcf/samples/custom-message-encoder-compression-encoder.md index d8db1a2a7cb2e..bb0b3018ca11b 100644 --- a/docs/framework/wcf/samples/custom-message-encoder-compression-encoder.md +++ b/docs/framework/wcf/samples/custom-message-encoder-compression-encoder.md @@ -43,7 +43,7 @@ As indicated previously, there are several layers that are implemented in a cust 4. The message encoder factory returns a message encoder for reading in the message and writing out the response. -5. The encoder layer is implemented as a class factory. Only the encoder class factory must be publicly exposed for the custom encoder. The factory object is returned by the binding element when the or object is created. Message encoders can operate in a buffered or streaming mode. This sample demonstrates both buffered mode and streaming mode. +5. The encoder layer is implemented as a class factory. Only the encoder class factory must be publicly exposed for the custom encoder. The factory object is returned by the binding element when the or object is created. Message encoders can operate in a buffered or streaming mode. This sample demonstrates both buffered mode and streaming mode. For each mode there is an accompanying `ReadMessage` and `WriteMessage` method on the abstract `MessageEncoder` class. A majority of the encoding work takes place in these methods. The sample wraps the existing text and binary message encoders. This allows the sample to delegate the reading and writing of the wire representation of messages to the inner encoder and allows the compression encoder to compress or decompress the results. Because there is no pipeline for message encoding, this is the only model for using multiple encoders in WCF. Once the message has been decompressed, the resulting message is passed up the stack for the channel stack to handle. During compression, the resulting compressed message is written directly to the stream provided. @@ -51,7 +51,7 @@ This sample uses helper methods (`CompressBuffer` and `DecompressBuffer`) to per The buffered `ReadMessage` and `WriteMessage` classes make use of the `BufferManager` class. The encoder is accessible only through the encoder factory. The abstract `MessageEncoderFactory` class provides a property named `Encoder` for accessing the current encoder and a method named `CreateSessionEncoder` for creating an encoder that supports sessions. Such an encoder can be used in the scenario where the channel supports sessions, is ordered and is reliable. This scenario allows for optimization in each session of the data written to the wire. If this is not desired, the base method should not be overloaded. The `Encoder` property provides a mechanism for accessing the session-less encoder and the default implementation of the `CreateSessionEncoder` method returns the value of the property. Because the sample wraps an existing encoder to provide compression, the `MessageEncoderFactory` implementation accepts a `MessageEncoderFactory` that represents the inner encoder factory. -Now that the encoder and encoder factory are defined, they can be used with a WCF client and service. However, these encoders must be added to the channel stack. You can derive classes from the and classes and override the `OnInitialize` methods to add this encoder factory manually. You can also expose the encoder factory through a custom binding element. +Now that the encoder and encoder factory are defined, they can be used with a WCF client and service. However, these encoders must be added to the channel stack. You can derive classes from the and classes and override the `OnInitialize` methods to add this encoder factory manually. You can also expose the encoder factory through a custom binding element. To create a new custom binding element, derive a class from the class. There are, however, several types of binding elements. To ensure that the custom binding element is recognized as a message encoding binding element, you also must implement the . The exposes a method for creating a new message encoder factory (`CreateMessageEncoderFactory`), which is implemented to return an instance of the matching message encoder factory. Additionally, the has a property to indicate the addressing version. Because this sample wraps the existing encoders, the sample implementation also wraps the existing encoder binding elements and takes an inner encoder binding element as a parameter to the constructor and exposes it through a property. The following sample code shows the implementation of the `GZipMessageEncodingBindingElement` class. @@ -210,7 +210,7 @@ binding.Namespace = "http://tempuri.org/bindings"; While this may be sufficient for the majority of user scenarios, supporting a file configuration is critical if a service is to be Web-hosted. To support the Web-hosted scenario, you must develop a custom configuration handler to allow a custom binding element to be configurable in a file. -You can build a configuration handler for the binding element on top of the configuration system. The configuration handler for the binding element must derive from the class. The informs the configuration system of the type of binding element to create for this section. All aspects of the `BindingElement` that can be set should be exposed as properties in the derived class. The assists in mapping the configuration element attributes to the properties and setting default values if attributes are missing. After the values from configuration are loaded and applied to the properties, the method is called, which converts the properties into a concrete instance of a binding element. The method is used to convert the properties on the derived class into the values to be set on the newly created binding element. +You can build a configuration handler for the binding element on top of the configuration system. The configuration handler for the binding element must derive from the class. The informs the configuration system of the type of binding element to create for this section. All aspects of the `BindingElement` that can be set should be exposed as properties in the derived class. The assists in mapping the configuration element attributes to the properties and setting default values if attributes are missing. After the values from configuration are loaded and applied to the properties, the method is called, which converts the properties into a concrete instance of a binding element. The method is used to convert the properties on the derived class into the values to be set on the newly created binding element. The following sample code shows the implementation of the `GZipMessageEncodingElement`. diff --git a/docs/framework/wcf/samples/custom-message-encoder-custom-text-encoder.md b/docs/framework/wcf/samples/custom-message-encoder-custom-text-encoder.md index fa26f45068443..cae7a7248088e 100644 --- a/docs/framework/wcf/samples/custom-message-encoder-custom-text-encoder.md +++ b/docs/framework/wcf/samples/custom-message-encoder-custom-text-encoder.md @@ -181,7 +181,7 @@ public class CustomTextMessageEncoderFactory : MessageEncoderFactory The binding elements allow the configuration of the WCF runtime stack. To use the custom message encoder in a WCF application, a binding element is required that creates the message encoder factory with the appropriate settings at the appropriate level in the runtime stack. -The `CustomTextMessageBindingElement` derives from the base class and inherits from the class. This allows other WCF components to recognize this binding element as being a message encoding binding element. The implementation of returns an instance of the matching message encoder factory with appropriate settings. +The `CustomTextMessageBindingElement` derives from the base class and inherits from the class. This allows other WCF components to recognize this binding element as being a message encoding binding element. The implementation of returns an instance of the matching message encoder factory with appropriate settings. The `CustomTextMessageBindingElement` exposes settings for `MessageVersion`, `ContentType`, and `Encoding` through properties. The encoder supports both Soap11Addressing and Soap12Addressing1 versions. The default is Soap11Addressing1. The default value of the `ContentType` is "text/xml". The `Encoding` property allows you to set the value of the desired character encoding. The sample client and service uses the ISO-8859-1 (Latin1) character encoding, which is not supported by the of WCF. @@ -206,7 +206,7 @@ For this sample, the client configuration is hand configured. You cannot use Svc The previous section shows how to use the custom text message encoder programmatically. The `CustomTextMessageEncodingBindingSection` implements a configuration handler that allows you to specify the use of a custom text message encoder within a configuration file. The `CustomTextMessageEncodingBindingSection` class derives from the class. The `BindingElementType` property informs the configuration system of the type of binding element to create for this section. -All of the settings defined by `CustomTextMessageBindingElement` are exposed as the properties in the `CustomTextMessageEncodingBindingSection`. The assists in mapping the configuration element attributes to the properties and setting default values if the attribute is not set. After the values from configuration are loaded and applied to the properties of the type, the method is called, which converts the properties into a concrete instance of a binding element. +All of the settings defined by `CustomTextMessageBindingElement` are exposed as the properties in the `CustomTextMessageEncodingBindingSection`. The assists in mapping the configuration element attributes to the properties and setting default values if the attribute is not set. After the values from configuration are loaded and applied to the properties of the type, the method is called, which converts the properties into a concrete instance of a binding element. This configuration handler maps to the following representation in the App.config or Web.config for the service or client. diff --git a/docs/framework/wcf/samples/custom-message-filter.md b/docs/framework/wcf/samples/custom-message-filter.md index 58d56415c85c4..13ad14aad9f89 100644 --- a/docs/framework/wcf/samples/custom-message-filter.md +++ b/docs/framework/wcf/samples/custom-message-filter.md @@ -13,11 +13,11 @@ The [MessageFilter sample](https://github.com/dotnet/samples/tree/main/framework When the first message on a channel arrives at the server, the server must determine which (if any) of the endpoints associated with that URI should receive the message. This process is controlled by the objects attached to the . -Each endpoint of a service has a single . The has both an and a . The union of these two filters is the message filter used for that endpoint. +Each endpoint of a service has a single . The has both an and a . The union of these two filters is the message filter used for that endpoint. -By default, the for an endpoint matches any message that is addressed to an address that matches the service endpoint's . By default, the for an endpoint inspects the action of the incoming message and matches any message with an action that corresponds to one of the actions of the service endpoint contract's operations (only `IsInitiating`=`true` actions are considered). As a result, by default, the filter for an endpoint only matches if both the message's To header is the of the endpoint and the message's action matches one of the endpoint operation's actions. +By default, the for an endpoint matches any message that is addressed to an address that matches the service endpoint's . By default, the for an endpoint inspects the action of the incoming message and matches any message with an action that corresponds to one of the actions of the service endpoint contract's operations (only `IsInitiating`=`true` actions are considered). As a result, by default, the filter for an endpoint only matches if both the message's To header is the of the endpoint and the message's action matches one of the endpoint operation's actions. -These filters can be changed using a behavior. In the sample, the service creates an that replaces the and on the : +These filters can be changed using a behavior. In the sample, the service creates an that replaces the and on the : ```csharp class FilteringEndpointBehavior : IEndpointBehavior @@ -86,7 +86,7 @@ Finally, the service's endpoint references one of the `behaviorConfigurations`: behaviorConfiguration="endpoint2" /> ``` -The implementation of the client application is straightforward; it creates two channels to the service's URI (by passing in that value as the second (`via`) parameter to and sends a single message on each channel, but it uses different endpoint addresses for each. As a result, the outbound messages from the client have different To designations, and the server responds accordingly, as demonstrated by the client's output: +The implementation of the client application is straightforward; it creates two channels to the service's URI (by passing in that value as the second (`via`) parameter to and sends a single message on each channel, but it uses different endpoint addresses for each. As a result, the outbound messages from the client have different To designations, and the server responds accordingly, as demonstrated by the client's output: ```console Sending message to urn:e... diff --git a/docs/framework/wcf/samples/datacontractresolver.md b/docs/framework/wcf/samples/datacontractresolver.md index 79bd45656fb21..cda7d2e10d5b8 100644 --- a/docs/framework/wcf/samples/datacontractresolver.md +++ b/docs/framework/wcf/samples/datacontractresolver.md @@ -94,7 +94,7 @@ public void deserialize(Type type) } ``` -Since the custom is passed in to the constructor, the is called during serialization to map a CLR type to an equivalent `xsi:type`. Similarly the is called during deserialization to map the `xsi:type` to an equivalent CLR type. In this sample, the is defined as shown in the following example. +Since the custom is passed in to the constructor, the is called during serialization to map a CLR type to an equivalent `xsi:type`. Similarly the is called during deserialization to map the `xsi:type` to an equivalent CLR type. In this sample, the is defined as shown in the following example. The following code example is a class deriving from . diff --git a/docs/framework/wcf/samples/datacontractserializer-sample.md b/docs/framework/wcf/samples/datacontractserializer-sample.md index 1df2fae6bc089..1bf3bb75b6efb 100644 --- a/docs/framework/wcf/samples/datacontractserializer-sample.md +++ b/docs/framework/wcf/samples/datacontractserializer-sample.md @@ -95,7 +95,7 @@ Record record2 = (Record)serializer.ReadObject(stream1); Console.WriteLine("Deserialized record: {0}", record2.ToString()); ``` -By default, the `DataContractSerializer` encodes objects into a stream using a textual representation of XML. However, you can influence the encoding of the XML by passing in a different writer. The sample creates a binary writer by calling . It then passes the writer and the record object to the serializer when it calls . Finally, the sample flushes the writer and reports on the length of the streams. +By default, the `DataContractSerializer` encodes objects into a stream using a textual representation of XML. However, you can influence the encoding of the XML by passing in a different writer. The sample creates a binary writer by calling . It then passes the writer and the record object to the serializer when it calls . Finally, the sample flushes the writer and reports on the length of the streams. ```csharp MemoryStream stream2 = new MemoryStream(); diff --git a/docs/framework/wcf/samples/dead-letter-queues.md b/docs/framework/wcf/samples/dead-letter-queues.md index a6edb877808d1..aa3177470fca0 100644 --- a/docs/framework/wcf/samples/dead-letter-queues.md +++ b/docs/framework/wcf/samples/dead-letter-queues.md @@ -20,15 +20,15 @@ Because queued communication can involve a certain amount of dormancy, you may w The dead-letter queue in the `NetMsmqBinding` binding is expressed in the following properties: -- property to express the kind of dead-letter queue required by the client. This enumeration has the following values: +- property to express the kind of dead-letter queue required by the client. This enumeration has the following values: - `None`: No dead-letter queue is required by the client. - `System`: The system dead-letter queue is used to store dead messages. The system dead-letter queue is shared by all applications running on the computer. -- `Custom`: A custom dead-letter queue specified using the property is used to store dead messages. This feature is only available on Windows Vista. This is used when the application must use its own dead letter queue instead of sharing it with other applications running on the same computer. +- `Custom`: A custom dead-letter queue specified using the property is used to store dead messages. This feature is only available on Windows Vista. This is used when the application must use its own dead letter queue instead of sharing it with other applications running on the same computer. -- property to express the specific queue to use as a dead-letter queue. This is available only in Windows Vista. +- property to express the specific queue to use as a dead-letter queue. This is available only in Windows Vista. In this sample, the client sends a batch of messages to the service from within the scope of a transaction and specifies an arbitrarily low value for "time-to-live" for these messages (about 2 seconds). The client also specifies a custom dead-letter queue to use to enqueue the messages that have expired. @@ -147,7 +147,7 @@ The dead-letter message service reads messages from the dead-letter queue. The d > [!NOTE] > The dead-letter queue is a client queue and is local to the client queue manager. -The dead-letter message service implementation checks for the reason a message failed delivery and takes corrective measures. The reason for a message failure is captured in two enumerations, and . You can retrieve the from the as shown in the following sample code: +The dead-letter message service implementation checks for the reason a message failed delivery and takes corrective measures. The reason for a message failure is captured in two enumerations, and . You can retrieve the from the as shown in the following sample code: ```csharp public void SubmitPurchaseOrder(PurchaseOrder po) diff --git a/docs/framework/wcf/samples/default-service-behavior.md b/docs/framework/wcf/samples/default-service-behavior.md index 91716f0c2d1f3..e7bd5ab5d5cd2 100644 --- a/docs/framework/wcf/samples/default-service-behavior.md +++ b/docs/framework/wcf/samples/default-service-behavior.md @@ -45,21 +45,21 @@ Service behaviors are specified with the |Automatically shuts down a session at the client's request.| -||Specifies the concurrency mode for each service instance.| -||Specifies the instance context mode.| +||Automatically shuts down a session at the client's request.| +||Specifies the concurrency mode for each service instance.| +||Specifies the instance context mode.| ||Determines whether to use the provided synchronization context, if one is set. Use this when you want to control whether to use a `WindowsFormsSynchronizationContext` in Windows Forms applications.| -||Determines whether general unhandled execution exceptions are to be converted into a `Fault` and sent as a fault message.| -||Specifies the isolation level for transactions.| +||Determines whether general unhandled execution exceptions are to be converted into a `Fault` and sent as a fault message.| +||Specifies the isolation level for transactions.| ||Determines whether unexpected message headers cause an error condition.| Operation behaviors are specified by using the attribute. The following table describes some of these behaviors. |Operation Behavior|Description| |------------------------|-----------------| -||Determines whether service operation completion commits the current transaction.| -||Determines whether the service operation enlists in a client-flowed transaction.| -||Determines whether the service operation impersonates the caller's identity.| +||Determines whether service operation completion commits the current transaction.| +||Determines whether the service operation enlists in a client-flowed transaction.| +||Determines whether the service operation impersonates the caller's identity.| ||Determines whether service instances are recycled at the start or end of the service operation call.| When you run the sample, the operation requests and responses are displayed in the client console window. The delay between the calls is the result of the calls to `System.Threading.Thread.Sleep()` made in the service operations. The rest of the behavior samples explain these behaviors in more detail. Press ENTER in the client window to shut down the client. diff --git a/docs/framework/wcf/samples/discovery-with-scopes-sample.md b/docs/framework/wcf/samples/discovery-with-scopes-sample.md index 48e3a56ba21ee..62a762b35a9fe 100644 --- a/docs/framework/wcf/samples/discovery-with-scopes-sample.md +++ b/docs/framework/wcf/samples/discovery-with-scopes-sample.md @@ -14,7 +14,7 @@ This project shows two service endpoints being added to a and pass in a with two restrictions. A scope is added to the criteria and the property is set to 1. The scope limits the results to only the services that publish the same scope. Setting to 1 limits the responses the waits for to, at most, 1 endpoint. The call is a synchronous operation that blocks the thread until a timeout is reached or one endpoint is found. +The `FindCalculatorServiceAddress()` method shows how to use a and pass in a with two restrictions. A scope is added to the criteria and the property is set to 1. The scope limits the results to only the services that publish the same scope. Setting to 1 limits the responses the waits for to, at most, 1 endpoint. The call is a synchronous operation that blocks the thread until a timeout is reached or one endpoint is found. ### To use this sample diff --git a/docs/framework/wcf/samples/dispatch-by-body-element.md b/docs/framework/wcf/samples/dispatch-by-body-element.md index 763bc2c20fb17..a0d59c120d2e4 100644 --- a/docs/framework/wcf/samples/dispatch-by-body-element.md +++ b/docs/framework/wcf/samples/dispatch-by-body-element.md @@ -30,9 +30,9 @@ class DispatchByBodyElementOperationSelector : IDispatchOperationSelector } ``` - implementations are very straightforward to build as there is only one method on the interface: . The job of this method is to inspect an incoming message and to return a string that equals the name of a method on the service contract for the current endpoint. + implementations are very straightforward to build as there is only one method on the interface: . The job of this method is to inspect an incoming message and to return a string that equals the name of a method on the service contract for the current endpoint. -In this sample, the operation selector acquires an for the incoming message's body using . This method already positions the reader on the first child of the message's body so that it is sufficient to get the current element's name and namespace URI and combine them into an `XmlQualifiedName` that is then used for looking up the corresponding operation from the dictionary held by the operation selector. +In this sample, the operation selector acquires an for the incoming message's body using . This method already positions the reader on the first child of the message's body so that it is sufficient to get the current element's name and namespace URI and combine them into an `XmlQualifiedName` that is then used for looking up the corresponding operation from the dictionary held by the operation selector. ```csharp public string SelectOperation(ref System.ServiceModel.Channels.Message message) @@ -52,7 +52,7 @@ public string SelectOperation(ref System.ServiceModel.Channels.Message message) } ``` -Accessing the message body with or any of the other methods that provide access to the message's body content causes the message to be marked as "read", which means that the message is invalid for any further processing. Therefore, the operation selector creates a copy of the incoming message with the method shown in the following code. Because the reader's position has not been changed during the inspection, it can be referenced by the newly created message to which the message properties and the message headers are also copied, which results in an exact clone of the original message: +Accessing the message body with or any of the other methods that provide access to the message's body content causes the message to be marked as "read", which means that the message is invalid for any further processing. Therefore, the operation selector creates a copy of the incoming message with the method shown in the following code. Because the reader's position has not been changed during the inspection, it can be referenced by the newly created message to which the message properties and the message headers are also copied, which results in an exact clone of the original message: ```csharp private Message CreateMessageCopy(Message message, @@ -73,7 +73,7 @@ Like most service model extensions, dispatch operation selectors are added to th Because operation selectors have contract scope, the appropriate behavior to implement here is the . Because the interface is implemented on a derived class as shown in the following code, the behavior can be declaratively added to any service contract. Whenever a is opened and the dispatch runtime is built, all behaviors found either as attributes on contracts, operations, and service implementations or as element in the service configuration are automatically added and subsequently asked to contribute extensions or modify the default configuration. -For brevity, the following code excerpt only shows the implementation of the method , which effects the configuration changes for the dispatcher in this sample. The other methods are not shown because they return to the caller without doing any work. +For brevity, the following code excerpt only shows the implementation of the method , which effects the configuration changes for the dispatcher in this sample. The other methods are not shown because they return to the caller without doing any work. ```csharp [AttributeUsage(AttributeTargets.Class|AttributeTargets.Interface)] @@ -84,7 +84,7 @@ class DispatchByBodyElementBehaviorAttribute : Attribute, IContractBehavior // public void Validate(...) ``` -First, the implementation sets up the lookup dictionary for the operation selector by iterating over the elements in the service endpoint's . Then, each operation description is inspected for the presence of the `DispatchBodyElementAttribute` behavior, an implementation of that is also defined in this sample. While this class is also a behavior, it is passive and does not actively contribute any configuration changes to the dispatch runtime. All of its methods return to the caller without taking any actions. The operation behavior only exists so that the metadata required for the new dispatch mechanism, namely the qualified name of the body element on whose occurrence an operation is selected, can be associated with the respective operations. +First, the implementation sets up the lookup dictionary for the operation selector by iterating over the elements in the service endpoint's . Then, each operation description is inspected for the presence of the `DispatchBodyElementAttribute` behavior, an implementation of that is also defined in this sample. While this class is also a behavior, it is passive and does not actively contribute any configuration changes to the dispatch runtime. All of its methods return to the caller without taking any actions. The operation behavior only exists so that the metadata required for the new dispatch mechanism, namely the qualified name of the body element on whose occurrence an operation is selected, can be associated with the respective operations. If such a behavior is found, a value pair created from the XML qualified name (`QName` property) and the operation name (`Name` property) is added to the dictionary. diff --git a/docs/framework/wcf/samples/durable-issued-token-provider.md b/docs/framework/wcf/samples/durable-issued-token-provider.md index 02da4ec05748d..84731bf31f073 100644 --- a/docs/framework/wcf/samples/durable-issued-token-provider.md +++ b/docs/framework/wcf/samples/durable-issued-token-provider.md @@ -116,7 +116,7 @@ The following steps show how to develop a custom token provider that caches issu The sample implements a custom token provider that returns a security token retrieved from a cache. - To perform this task, the custom token provider derives the class and overrides the method. This method tries to get a token from the cache, or if a token cannot be found in the cache, retrieves a token from the underlying provider and then caches that token. In both cases the method returns a `SecurityToken`. + To perform this task, the custom token provider derives the class and overrides the method. This method tries to get a token from the cache, or if a token cannot be found in the cache, retrieves a token from the underlying provider and then caches that token. In both cases the method returns a `SecurityToken`. ```csharp protected override SecurityToken GetTokenCore(TimeSpan timeout) diff --git a/docs/framework/wcf/samples/extending-control-over-error-handling-and-reporting.md b/docs/framework/wcf/samples/extending-control-over-error-handling-and-reporting.md index 2ec8af20fd138..255c0eeb4d6b1 100644 --- a/docs/framework/wcf/samples/extending-control-over-error-handling-and-reporting.md +++ b/docs/framework/wcf/samples/extending-control-over-error-handling-and-reporting.md @@ -11,11 +11,11 @@ The [ErrorHandling sample](https://github.com/dotnet/samples/tree/main/framework > [!NOTE] > The setup procedure and build instructions for this sample are located at the end of this topic. -Services can intercept errors, perform processing, and affect how errors are reported using the interface. The interface has two methods that can be implemented: and . The method allows you to add, modify, or suppress a fault message that is generated in response to an exception. The method allows error processing to take place in the event of an error and controls whether additional error handling can run. +Services can intercept errors, perform processing, and affect how errors are reported using the interface. The interface has two methods that can be implemented: and . The method allows you to add, modify, or suppress a fault message that is generated in response to an exception. The method allows error processing to take place in the event of an error and controls whether additional error handling can run. In this sample, the `CalculatorErrorHandler` type implements the interface. In the - method, the `CalculatorErrorHandler` writes a log of the error to an Error.txt text file in c:\logs. Note that the sample logs the fault and does not suppress it, allowing it to be reported back to the client. + method, the `CalculatorErrorHandler` writes a log of the error to an Error.txt text file in c:\logs. Note that the sample logs the fault and does not suppress it, allowing it to be reported back to the client. ```csharp public class CalculatorErrorHandler : IErrorHandler @@ -45,7 +45,7 @@ public class CalculatorErrorHandler : IErrorHandler } ``` -The `ErrorBehaviorAttribute` exists as a mechanism to register an error handler with a service. This attribute takes a single type parameter. That type should implement the interface and should have a public, empty constructor. The attribute then instantiates an instance of that error handler type and installs it into the service. It does this by implementing the interface and then using the method to add instances of the error handler to the service. +The `ErrorBehaviorAttribute` exists as a mechanism to register an error handler with a service. This attribute takes a single type parameter. That type should implement the interface and should have a public, empty constructor. The attribute then instantiates an instance of that error handler type and installs it into the service. It does this by implementing the interface and then using the method to add instances of the error handler to the service. ```csharp // This attribute can be used to install a custom error handler for a service. diff --git a/docs/framework/wcf/samples/fault-contract.md b/docs/framework/wcf/samples/fault-contract.md index 542f6f1fc917c..08f7156d92338 100644 --- a/docs/framework/wcf/samples/fault-contract.md +++ b/docs/framework/wcf/samples/fault-contract.md @@ -54,7 +54,7 @@ public class MathFault } ``` -The `Divide` method throws a exception when a divide by zero exception occurs as shown in the following sample code. This exception results in a fault being sent to the client. +The `Divide` method throws a exception when a divide by zero exception occurs as shown in the following sample code. This exception results in a fault being sent to the client. ```csharp public int Divide(int n1, int n2) @@ -96,7 +96,7 @@ catch (FaultException e) By default, the details of unexpected exceptions are not sent to the client to prevent details of the service implementation from escaping the secure boundary of the service. `FaultContract` provides a way to describe faults in a contract and mark certain types of exceptions as appropriate for transmission to the client. `FaultException` provides the runtime mechanism for sending faults to consumers. -However, it is useful to see the internal details of a service failure when debugging. To turn off the secure behavior previously described, you can indicate that the details of every unhandled exception on the server should be included in the fault that is sent to the client. This is accomplished by setting to `true`. You can either set it in code, or in configuration as shown in the following sample. +However, it is useful to see the internal details of a service failure when debugging. To turn off the secure behavior previously described, you can indicate that the details of every unhandled exception on the server should be included in the fault that is sent to the client. This is accomplished by setting to `true`. You can either set it in code, or in configuration as shown in the following sample. ```xml diff --git a/docs/framework/wcf/samples/httpcookiesession.md b/docs/framework/wcf/samples/httpcookiesession.md index 56de5fd52e121..40108825a21e0 100644 --- a/docs/framework/wcf/samples/httpcookiesession.md +++ b/docs/framework/wcf/samples/httpcookiesession.md @@ -55,13 +55,13 @@ The sample provides a service channel in the `HttpCookieReplySessionChannelListe Dictionary channelMapping; ``` -The `HttpCookieReplySessionChannel` class implements . Higher levels of the channel stack call the method to read requests for this session. Each session channel has a private message queue that is populated by the service channel. +The `HttpCookieReplySessionChannel` class implements . Higher levels of the channel stack call the method to read requests for this session. Each session channel has a private message queue that is populated by the service channel. ```csharp InputQueue requestQueue; ``` -In the case when someone calls the method and there are no messages in the message queue, the channel waits for a specified amount of time before shutting itself down. This cleans up the session channels created for non-WCF clients. +In the case when someone calls the method and there are no messages in the message queue, the channel waits for a specified amount of time before shutting itself down. This cleans up the session channels created for non-WCF clients. We use the `channelMapping` to track the `ReplySessionChannels`, and we do not close our underlying `innerChannel` until all the accepted channels have been closed. This way `HttpCookieReplySessionChannel` can exist beyond the lifetime of `HttpCookieReplySessionChannelListener`. We also do not have to worry about the listener getting garbage collected underneath us because the accepted channels keep a reference to their listener through the `OnClosed` callback. diff --git a/docs/framework/wcf/samples/instancing-initialization.md b/docs/framework/wcf/samples/instancing-initialization.md index 33a51672b9e5c..3f5900b0ff52f 100644 --- a/docs/framework/wcf/samples/instancing-initialization.md +++ b/docs/framework/wcf/samples/instancing-initialization.md @@ -15,19 +15,19 @@ The [Initialization sample](https://github.com/dotnet/samples/tree/main/framewor The first step in creating a Windows Communication Foundation (WCF) extension is to decide the extensibility point to use. In WCF, the term *EndpointDispatcher* refers to a runtime component responsible for converting incoming messages into method invocations on the user's service and for converting return values from that method to an outgoing message. A WCF service creates an EndpointDispatcher for each endpoint. -The EndpointDispatcher offers endpoint scope (for all messages received or sent by the service) extensibility using the class. This class allows you to customize various properties that control the behavior of the EndpointDispatcher. This sample focuses on the property that points to the object that provides the instances of the service class. +The EndpointDispatcher offers endpoint scope (for all messages received or sent by the service) extensibility using the class. This class allows you to customize various properties that control the behavior of the EndpointDispatcher. This sample focuses on the property that points to the object that provides the instances of the service class. ## IInstanceProvider In WCF, the EndpointDispatcher creates instances of a service class by using an instance provider that implements the interface. This interface has only two methods: -- : When a message arrives, the Dispatcher calls the method to create an instance of the service class to process the message. The frequency of the calls to this method is determined by the property. For example if the property is set to , a new instance of service class is created to process each message that arrives, so is called whenever a message arrives. +- : When a message arrives, the Dispatcher calls the method to create an instance of the service class to process the message. The frequency of the calls to this method is determined by the property. For example if the property is set to , a new instance of service class is created to process each message that arrives, so is called whenever a message arrives. -- : When the service instance finishes processing the message, the EndpointDispatcher calls the method. As in the method, the frequency of the calls to this method is determined by the property. +- : When the service instance finishes processing the message, the EndpointDispatcher calls the method. As in the method, the frequency of the calls to this method is determined by the property. ## The Object Pool -The `ObjectPoolInstanceProvider` class contains the implementation for the object pool. This class implements the interface to interact with the service model layer. When the EndpointDispatcher calls the method, instead of creating a new instance, the custom implementation looks for an existing object in an in-memory pool. If one is available, it is returned. Otherwise, `ObjectPoolInstanceProvider` checks whether the `ActiveObjectsCount` property (number of objects returned from the pool) has reached the maximum pool size. If not, a new instance is created and returned to the caller and `ActiveObjectsCount` is subsequently incremented. Otherwise an object creation request is queued for a configured period of time. The implementation for `GetObjectFromThePool` is shown in the following sample code. +The `ObjectPoolInstanceProvider` class contains the implementation for the object pool. This class implements the interface to interact with the service model layer. When the EndpointDispatcher calls the method, instead of creating a new instance, the custom implementation looks for an existing object in an in-memory pool. If one is available, it is returned. Otherwise, `ObjectPoolInstanceProvider` checks whether the `ActiveObjectsCount` property (number of objects returned from the pool) has reached the maximum pool size. If not, a new instance is created and returned to the caller and `ActiveObjectsCount` is subsequently incremented. Otherwise an object creation request is queued for a configured period of time. The implementation for `GetObjectFromThePool` is shown in the following sample code. ```csharp private object GetObjectFromThePool() @@ -153,13 +153,13 @@ For the purpose of an object pooling extension, either an endpoint behavior or a This sample uses a custom attribute. When the is constructed, it examines the attributes used in the service's type definition and adds the available behaviors to the service description's behaviors collection. -The interface has three methods: `,` `,` and . These methods are called by WCF when the is being initialized. is called first; it allows the service to be inspected for inconsistencies. is called next; this method is only required in very advanced scenarios. is called last and is responsible for configuring the runtime. The following parameters are passed into : +The interface has three methods: `,` `,` and . These methods are called by WCF when the is being initialized. is called first; it allows the service to be inspected for inconsistencies. is called next; this method is only required in very advanced scenarios. is called last and is responsible for configuring the runtime. The following parameters are passed into : - `Description`: This parameter provides the service description for the entire service. This can be used to inspect description data about the service's endpoints, contracts, bindings, and other data associated with the service. - `ServiceHostBase`: This parameter provides the that is currently being initialized. -In the custom implementation, a new instance of `ObjectPoolInstanceProvider` is instantiated and assigned to the property in each that is attached to the . +In the custom implementation, a new instance of `ObjectPoolInstanceProvider` is instantiated and assigned to the property in each that is attached to the . ```csharp public void ApplyDispatchBehavior(ServiceDescription description, ServiceHostBase serviceHostBase) diff --git a/docs/framework/wcf/samples/loosely-typed-extensions-sample.md b/docs/framework/wcf/samples/loosely-typed-extensions-sample.md index 7093bddce078e..264740057b505 100644 --- a/docs/framework/wcf/samples/loosely-typed-extensions-sample.md +++ b/docs/framework/wcf/samples/loosely-typed-extensions-sample.md @@ -65,7 +65,7 @@ This document contains the following pieces of extension data: ## Writing Extension Data -Attribute extensions are created by adding entries to the collection as shown in the following sample code. +Attribute extensions are created by adding entries to the collection as shown in the following sample code. ```csharp //Attribute extensions are stored in a dictionary indexed by @@ -73,7 +73,7 @@ Attribute extensions are created by adding entries to the collection. These extensions can by basic values such as strings, XML serializations of .NET Framework objects, or XML nodes coded by hand. +Element extensions are created by adding entries to the collection. These extensions can by basic values such as strings, XML serializations of .NET Framework objects, or XML nodes coded by hand. The following sample code creates an extension element named `simpleString`. @@ -103,7 +103,7 @@ feed.ElementExtensions.Add(new XElement("xElementExtension", ## Reading Extension Data -The values for attribute extensions can be obtained by looking up the attribute in the collection by its as shown in the following sample code. +The values for attribute extensions can be obtained by looking up the attribute in the collection by its as shown in the following sample code. ```csharp Console.WriteLine( feed.AttributeExtensions[ new XmlQualifiedName( "myAttribute", "" )]); diff --git a/docs/framework/wcf/samples/message-correlation.md b/docs/framework/wcf/samples/message-correlation.md index 16a78de326f1a..ba8abc5623c34 100644 --- a/docs/framework/wcf/samples/message-correlation.md +++ b/docs/framework/wcf/samples/message-correlation.md @@ -12,7 +12,7 @@ The service processes the message received from the sender and sends a response The `IOrderProcessor` service contract defines a one-way service operation that is suitable for use with queuing. An MSMQ message does not have an Action header, so it is not possible to map different MSMQ messages to operation contracts automatically. Therefore, there can be only one operation contract in this case. If you want to define more operation contracts in the service, the application must provide information as to which header in the MSMQ message (for example, the label, or correlationID) can be used to decide which operation contract to dispatch. -The MSMQ message also does not contain information as to which headers are mapped to the different parameters of the operation contract. Therefore, there can be only one parameter in the operation contract. The parameter is of type , which contains the underlying MSMQ message. The type "T" in the `MsmqMessage` class represents the data that is serialized into the MSMQ message body. In this sample, the `PurchaseOrder` type is serialized into the MSMQ message body. +The MSMQ message also does not contain information as to which headers are mapped to the different parameters of the operation contract. Therefore, there can be only one parameter in the operation contract. The parameter is of type , which contains the underlying MSMQ message. The type "T" in the `MsmqMessage` class represents the data that is serialized into the MSMQ message body. In this sample, the `PurchaseOrder` type is serialized into the MSMQ message body. ```csharp [ServiceContract(Namespace = "http://Microsoft.ServiceModel.Samples")] diff --git a/docs/framework/wcf/samples/message-inspectors.md b/docs/framework/wcf/samples/message-inspectors.md index 9b0b0476e2c21..e1f6884d1711f 100644 --- a/docs/framework/wcf/samples/message-inspectors.md +++ b/docs/framework/wcf/samples/message-inspectors.md @@ -36,9 +36,9 @@ public class SchemaValidationMessageInspector : IClientMessageInspector, IDispat } ``` -Any service (dispatcher) message inspector must implement the two methods and . +Any service (dispatcher) message inspector must implement the two methods and . - is invoked by the dispatcher when a message has been received, processed by the channel stack and assigned to a service, but before it is deserialized and dispatched to an operation. If the incoming message was encrypted, the message is already decrypted when it reaches the message inspector. The method gets the `request` message passed as a reference parameter, which allows the message to be inspected, manipulated or replaced as required. The return value can be any object and is used as a correlation state object that is passed to when the service returns a reply to the current message. In this sample, delegates the inspection (validation) of the message to the private, local method `ValidateMessageBody` and returns no correlation state object. This method ensures that no invalid messages pass into the service. + is invoked by the dispatcher when a message has been received, processed by the channel stack and assigned to a service, but before it is deserialized and dispatched to an operation. If the incoming message was encrypted, the message is already decrypted when it reaches the message inspector. The method gets the `request` message passed as a reference parameter, which allows the message to be inspected, manipulated or replaced as required. The return value can be any object and is used as a correlation state object that is passed to when the service returns a reply to the current message. In this sample, delegates the inspection (validation) of the message to the private, local method `ValidateMessageBody` and returns no correlation state object. This method ensures that no invalid messages pass into the service. ```csharp object IDispatchMessageInspector.AfterReceiveRequest(ref System.ServiceModel.Channels.Message request, System.ServiceModel.IClientChannel channel, System.ServiceModel.InstanceContext instanceContext) @@ -53,9 +53,9 @@ object IDispatchMessageInspector.AfterReceiveRequest(ref System.ServiceModel.Cha } ``` - is invoked whenever a reply is ready to be sent back to a client, or in the case of one-way messages, when the incoming message has been processed. This allows extensions to count on being called symmetrically, regardless of MEP. As with , the message is passed as a reference parameter and can be inspected, modified or replaced. The validation of the message that is performed in this sample is again delegated to the `ValidMessageBody` method, but the handling of validation errors is slightly different in this case. + is invoked whenever a reply is ready to be sent back to a client, or in the case of one-way messages, when the incoming message has been processed. This allows extensions to count on being called symmetrically, regardless of MEP. As with , the message is passed as a reference parameter and can be inspected, modified or replaced. The validation of the message that is performed in this sample is again delegated to the `ValidMessageBody` method, but the handling of validation errors is slightly different in this case. -If a validation error occurs on the service, the `ValidateMessageBody` method throws -derived exceptions. In , these exceptions can be put into the service model infrastructure where they are automatically transformed into SOAP faults and relayed to the client. In , exceptions must not be put into the infrastructure, because the transformation of fault exceptions thrown by the service occurs before the message inspector is called. Therefore the following implementation catches the known `ReplyValidationFault` exception and replaces the reply message with an explicit fault message. This method ensures that no invalid messages are returned by the service implementation. +If a validation error occurs on the service, the `ValidateMessageBody` method throws -derived exceptions. In , these exceptions can be put into the service model infrastructure where they are automatically transformed into SOAP faults and relayed to the client. In , exceptions must not be put into the infrastructure, because the transformation of fault exceptions thrown by the service occurs before the message inspector is called. Therefore the following implementation catches the known `ReplyValidationFault` exception and replaces the reply message with an explicit fault message. This method ensures that no invalid messages are returned by the service implementation. ```csharp void IDispatchMessageInspector.BeforeSendReply(ref System.ServiceModel.Channels.Message reply, object correlationState) @@ -77,13 +77,13 @@ void IDispatchMessageInspector.BeforeSendReply(ref System.ServiceModel.Channels. } ``` -The client message inspector is very similar. The two methods that must be implemented from are and . +The client message inspector is very similar. The two methods that must be implemented from are and . - is invoked when the message has been composed either by the client application or by the operation formatter. As with the dispatcher message inspectors, the message can just be inspected or entirely replaced. In this sample, the inspector delegates to the same local `ValidateMessageBody` helper method that is also used for the dispatch message inspectors. + is invoked when the message has been composed either by the client application or by the operation formatter. As with the dispatcher message inspectors, the message can just be inspected or entirely replaced. In this sample, the inspector delegates to the same local `ValidateMessageBody` helper method that is also used for the dispatch message inspectors. The behavioral difference between the client and service validation (as specified in the constructor) is that the client validation throws local exceptions that are put into the user code because they occur locally and not because of a service failure. Generally, the rule is that service dispatcher inspectors throw faults and that client inspectors throw exceptions. -This implementation ensures that no invalid messages are sent to the service. +This implementation ensures that no invalid messages are sent to the service. ```csharp object IClientMessageInspector.BeforeSendRequest(ref System.ServiceModel.Channels.Message request, System.ServiceModel.IClientChannel channel) @@ -202,7 +202,7 @@ As previously discussed, the exceptions thrown by the handler differ between the Message inspectors are extensions to the client runtime or the dispatch runtime. Such extensions are configured using *behaviors*. A behavior is a class that changes the behavior of the service model runtime by changing the default configuration or adding extensions (such as message inspectors) to it. -The following `SchemaValidationBehavior` class is the behavior used to add this sample's message inspector to the client or dispatch runtime. The implementation is rather basic in both cases. In and , the message inspector is created and added to the collection of the respective runtime. +The following `SchemaValidationBehavior` class is the behavior used to add this sample's message inspector to the client or dispatch runtime. The implementation is rather basic in both cases. In and , the message inspector is created and added to the collection of the respective runtime. ```csharp public class SchemaValidationBehavior : IEndpointBehavior @@ -367,7 +367,7 @@ public bool ValidateRequest ## Adding Message Inspectors Imperatively -Except through attributes (which is not supported in this sample for the reason cited previously) and configuration, behaviors can quite easily be added to a client and service runtime using imperative code. In this sample, this is done in the client application to test the client message inspector. The `GenericClient` class is derived from , which exposes the endpoint configuration to the user code. Before the client is implicitly opened the endpoint configuration can be changed, for instance by adding behaviors as shown in the following code. Adding the behavior on the service is largely equivalent to the client technique shown here and must be performed before the service host is opened. +Except through attributes (which is not supported in this sample for the reason cited previously) and configuration, behaviors can quite easily be added to a client and service runtime using imperative code. In this sample, this is done in the client application to test the client message inspector. The `GenericClient` class is derived from , which exposes the endpoint configuration to the user code. Before the client is implicitly opened the endpoint configuration can be changed, for instance by adding behaviors as shown in the following code. Adding the behavior on the service is largely equivalent to the client technique shown here and must be performed before the service host is opened. ```csharp try diff --git a/docs/framework/wcf/samples/message-queuing-to-wcf.md b/docs/framework/wcf/samples/message-queuing-to-wcf.md index 42ee958e1379b..41c5f88278257 100644 --- a/docs/framework/wcf/samples/message-queuing-to-wcf.md +++ b/docs/framework/wcf/samples/message-queuing-to-wcf.md @@ -10,7 +10,7 @@ The [MsmqToWcf sample](https://github.com/dotnet/samples/tree/main/framework/wcf The service contract is `IOrderProcessor`, which defines a one-way service that is suitable for use with queues. An MSMQ message does not have an Action header, so it is not possible to map different MSMQ messages to operation contracts automatically. Therefore, there can be only one operation contract. If you want to define more than one operation contract for the service, the application must provide information as to which header in the MSMQ message (for example, the label or correlationID) can be used to decide which operation contract to dispatch. -The MSMQ message does not contain information as to which headers are mapped to the different parameters of the operation contract. The parameter is of type (`MsmqMessage`), which contains the underlying MSMQ message. The type "T" in the (`MsmqMessage`) class represents the data that is serialized into the MSMQ message body. In this sample, the `PurchaseOrder` type is serialized into the MSMQ message body. +The MSMQ message does not contain information as to which headers are mapped to the different parameters of the operation contract. The parameter is of type (`MsmqMessage`), which contains the underlying MSMQ message. The type "T" in the (`MsmqMessage`) class represents the data that is serialized into the MSMQ message body. In this sample, the `PurchaseOrder` type is serialized into the MSMQ message body. The following sample code shows the service contract of the order processing service. @@ -64,7 +64,7 @@ The MSMQ queue name is specified in an appSettings section of the configuration ``` -The client application is an MSMQ application that uses the method to send a durable and transactional message to the queue, as shown in the following sample code. +The client application is an MSMQ application that uses the method to send a durable and transactional message to the queue, as shown in the following sample code. ```csharp //Connect to the queue. diff --git a/docs/framework/wcf/samples/message-security-anonymous.md b/docs/framework/wcf/samples/message-security-anonymous.md index 1a53854818f9b..74e65e8b75528 100644 --- a/docs/framework/wcf/samples/message-security-anonymous.md +++ b/docs/framework/wcf/samples/message-security-anonymous.md @@ -102,7 +102,7 @@ The client endpoint configuration consists of an absolute address for the servic ``` -The sample sets the to for authenticating the service's certificate. This is done in the client's App.config file in the `behaviors` section. This means that if the certificate is in the user's Trusted People store, then it is trusted without performing a validation of the certificate's issuer chain. This setting is used here for convenience so that the sample can be run without requiring certificates issued by a certification authority (CA). This setting is less secure than the default, ChainTrust. The security implications of this setting should be carefully considered before using `PeerOrChainTrust` in production code. +The sample sets the to for authenticating the service's certificate. This is done in the client's App.config file in the `behaviors` section. This means that if the certificate is in the user's Trusted People store, then it is trusted without performing a validation of the certificate's issuer chain. This setting is used here for convenience so that the sample can be run without requiring certificates issued by a certification authority (CA). This setting is less secure than the default, ChainTrust. The security implications of this setting should be carefully considered before using `PeerOrChainTrust` in production code. The client implementation adds a call to the `IsCallerAnonymous` method and otherwise does not differ from the [WSHttpBinding](wshttpbinding.md) sample. diff --git a/docs/framework/wcf/samples/message-security-windows.md b/docs/framework/wcf/samples/message-security-windows.md index e88f91954022a..c700f8f9f8578 100644 --- a/docs/framework/wcf/samples/message-security-windows.md +++ b/docs/framework/wcf/samples/message-security-windows.md @@ -56,7 +56,7 @@ The client endpoint configuration consists of an absolute address for the servic ``` -The service source code has been modified to demonstrate how the can be used to access the identity of the caller. +The service source code has been modified to demonstrate how the can be used to access the identity of the caller. ```csharp public string GetCallerIdentity() diff --git a/docs/framework/wcf/samples/metadata-publishing-behavior.md b/docs/framework/wcf/samples/metadata-publishing-behavior.md index 5d40196258ed8..cced26265a72f 100644 --- a/docs/framework/wcf/samples/metadata-publishing-behavior.md +++ b/docs/framework/wcf/samples/metadata-publishing-behavior.md @@ -51,7 +51,7 @@ The following shows the MEX endpoint. contract="IMetadataExchange" /> ``` -This sample sets the property to `true`, which also exposes the service's metadata using HTTP GET. To enable an HTTP GET metadata endpoint, the service must have an HTTP base address. The query string `?wsdl` is used on the base address of the service to access the metadata. For example, to see the WSDL for the service in a Web browser you would use the address `http://localhost/servicemodelsamples/service.svc?wsdl`. Alternatively, you can use this behavior to expose metadata over HTTPS by setting to `true`. This requires an HTTPS base address. +This sample sets the property to `true`, which also exposes the service's metadata using HTTP GET. To enable an HTTP GET metadata endpoint, the service must have an HTTP base address. The query string `?wsdl` is used on the base address of the service to access the metadata. For example, to see the WSDL for the service in a Web browser you would use the address `http://localhost/servicemodelsamples/service.svc?wsdl`. Alternatively, you can use this behavior to expose metadata over HTTPS by setting to `true`. This requires an HTTPS base address. To access the service's MEX endpoint use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../servicemodel-metadata-utility-tool-svcutil-exe.md). diff --git a/docs/framework/wcf/samples/net-tcp-port-sharing-sample.md b/docs/framework/wcf/samples/net-tcp-port-sharing-sample.md index e5e8d3b59d920..c95060555b7fc 100644 --- a/docs/framework/wcf/samples/net-tcp-port-sharing-sample.md +++ b/docs/framework/wcf/samples/net-tcp-port-sharing-sample.md @@ -20,7 +20,7 @@ The NetTcp Port Sharing Service is not enabled by default. Before running this s Unhandled Exception: System.ServiceModel.CommunicationException: The TransportManager failed to listen on the supplied URI using the NetTcpPortSharing service: failed to start the service because it is disabled. An administrator can enable it by running 'sc.exe config NetTcpPortSharing start= demand'.. ---> System.InvalidOperationException: Cannot start service NetTcpPortSharing on computer '.'. ---> System.ComponentModel.Win32Exception: The service cannot be started, either because it is disabled or because it has no enabled devices associated with it ``` -Port sharing is enabled on the server by setting the property of the binding or the binding element. The client does not have to know how port sharing has been configured to use it on the server. +Port sharing is enabled on the server by setting the property of the binding or the binding element. The client does not have to know how port sharing has been configured to use it on the server. ## Enabling Port Sharing diff --git a/docs/framework/wcf/samples/one-way.md b/docs/framework/wcf/samples/one-way.md index a810b20e628b6..beba235b45068 100644 --- a/docs/framework/wcf/samples/one-way.md +++ b/docs/framework/wcf/samples/one-way.md @@ -80,7 +80,7 @@ Processing Divide(22,7) - result: 3.14285714285714 ``` > [!NOTE] -> HTTP is, by definition, a request/response protocol; when a request is made, a response is returned. This is true even for a one-way service operation that is exposed over HTTP. When the operation is called, the service returns an HTTP status code of 202 before the service operation has executed. This status code means that the request has been accepted for processing, but the processing has not yet been completed. The client that called the operation blocks until it receives the 202 response from the service. This can cause some unexpected behavior when multiple one-way messages are sent using a binding that is configured to use sessions. The `wsHttpBinding` binding used in this sample is configured to use sessions by default to establish a security context. By default, messages in a session are guaranteed to arrive in the order in which they are sent. Because of this, when the second message in a session is sent, it is not processed until the first message has been processed. The result of this is that the client does not receive the 202 response for a message until the processing of the previous message has been completed. The client therefore appears to block on each subsequent operation call. To avoid this behavior, this sample configures the runtime to dispatch messages concurrently to distinct instances for processing. The sample sets to `PerCall` so that each message can be processed by a different instance. is set to `Multiple` to allow more than one thread to dispatch messages at a time. +> HTTP is, by definition, a request/response protocol; when a request is made, a response is returned. This is true even for a one-way service operation that is exposed over HTTP. When the operation is called, the service returns an HTTP status code of 202 before the service operation has executed. This status code means that the request has been accepted for processing, but the processing has not yet been completed. The client that called the operation blocks until it receives the 202 response from the service. This can cause some unexpected behavior when multiple one-way messages are sent using a binding that is configured to use sessions. The `wsHttpBinding` binding used in this sample is configured to use sessions by default to establish a security context. By default, messages in a session are guaranteed to arrive in the order in which they are sent. Because of this, when the second message in a session is sent, it is not processed until the first message has been processed. The result of this is that the client does not receive the 202 response for a message until the processing of the previous message has been completed. The client therefore appears to block on each subsequent operation call. To avoid this behavior, this sample configures the runtime to dispatch messages concurrently to distinct instances for processing. The sample sets to `PerCall` so that each message can be processed by a different instance. is set to `Multiple` to allow more than one thread to dispatch messages at a time. ### To set up, build, and run the sample diff --git a/docs/framework/wcf/samples/operation-formatter-and-operation-selector.md b/docs/framework/wcf/samples/operation-formatter-and-operation-selector.md index e3e85c04d8252..b8c991dab28f1 100644 --- a/docs/framework/wcf/samples/operation-formatter-and-operation-selector.md +++ b/docs/framework/wcf/samples/operation-formatter-and-operation-selector.md @@ -35,7 +35,7 @@ Request: - The sample uses the class to convert parameter data in the request message to and from strings. If a is not available for a specific type, the sample formatter throws an exception. -- In the `IClientMessageFormatter.SerializeRequest` method on the client, the formatter creates a URI with the appropriate To address and appends the operation name as a suffix. This name is used to dispatch to the appropriate operation on the server. It then takes the array of parameter objects and serializes the parameter data to the URI query string using parameter names and the values converted by the class. The and properties are then set to this URI. is accessed through the property. +- In the `IClientMessageFormatter.SerializeRequest` method on the client, the formatter creates a URI with the appropriate To address and appends the operation name as a suffix. This name is used to dispatch to the appropriate operation on the server. It then takes the array of parameter objects and serializes the parameter data to the URI query string using parameter names and the values converted by the class. The and properties are then set to this URI. is accessed through the property. - In the `IDispatchMessageFormatter.DeserializeRequest` method on the server, the formatter retrieves the `Via` URI in the incoming request message properties. It parses the name-value pairs in the URI query string into parameter names and values and uses the parameter names and values to populate the array of parameters passed into the method. Note that operation dispatch has already occurred, so the operation name suffix is ignored in this method. @@ -57,7 +57,7 @@ The `UriPathSuffixOperationSelector` component can be set up programmatically or On the server: -The is set to the implementation. +The is set to the implementation. By default, WCF uses an exact-match address filter. The URI on the incoming message contains an operation name suffix followed by a query string that contains parameter data, so the endpoint behavior also changes the address filter to be a prefix match filter. It uses the WCF for this purpose. @@ -65,7 +65,7 @@ By default, WCF uses an exact-match address filter. The URI on the incoming mess Operation behaviors that specify formatters are unique. One such behavior is always implemented by default for every operation to create the necessary operation formatter. However, these behaviors look like just another operation behavior; they are not identifiable by any other attribute. To install a replacement behavior, the implementation must look for specific formatter behaviors that are installed by the WCF type loader by default and either replace it or add a compatible behavior to run after the default behavior. -These operation formatters behaviors can be set up programmatically prior to calling or by specifying an operation behavior that is executed after the default one. However, it cannot easily be set up by an endpoint behavior (and therefore by configuration) because the behavior model does not allow a behavior to replace other behaviors or otherwise modify the description tree. +These operation formatters behaviors can be set up programmatically prior to calling or by specifying an operation behavior that is executed after the default one. However, it cannot easily be set up by an endpoint behavior (and therefore by configuration) because the behavior model does not allow a behavior to replace other behaviors or otherwise modify the description tree. On the client: @@ -96,7 +96,7 @@ On the server: - The interface must be implemented so that it can read HTTP GET requests and delegate to the original formatter for writing responses. This is done by calling the same `EnableHttpGetRequestsBehavior.ReplaceFormatterBehavior` helper method as the client (see the previous code sample). -- This must be done before is called. In this sample, we show how the formatter is manually modified before calling . Another way to achieve the same thing is to derive a class from that makes the calls to `EnableHttpGetRequestsBehavior.ReplaceFormatterBehavior` before opening (please see hosting documentation and samples for examples). +- This must be done before is called. In this sample, we show how the formatter is manually modified before calling . Another way to achieve the same thing is to derive a class from that makes the calls to `EnableHttpGetRequestsBehavior.ReplaceFormatterBehavior` before opening (please see hosting documentation and samples for examples). ### User experience @@ -137,7 +137,7 @@ On the server: ``` -- Add operation formatters before calling . +- Add operation formatters before calling . On the client: @@ -158,7 +158,7 @@ On the client: - The App.config for the client must specify the same custom `EnableHttpGetRequestsBehavior` as the server. -- Add operation formatters before calling . +- Add operation formatters before calling . When you run the sample, the operation requests and responses are displayed in the client console window. All four operations (Add, Subtract, Multiply, and Divide) must succeed. diff --git a/docs/framework/wcf/samples/operationcontextscope.md b/docs/framework/wcf/samples/operationcontextscope.md index 8ebe846f2a2ec..5c726f58a0caf 100644 --- a/docs/framework/wcf/samples/operationcontextscope.md +++ b/docs/framework/wcf/samples/operationcontextscope.md @@ -11,11 +11,11 @@ The [OperationContextScope sample](https://github.com/dotnet/samples/tree/main/f > [!NOTE] > The setup procedure and build instructions for this sample are located at the end of this topic. -The sample demonstrates how a client can send additional information as a using . An object is created by scoping it to a channel. Headers that must be translated to the remote service can be added to the collection. Headers added to this collection can be retrieved on the service by accessing . Its calls are made on multiple channels and then the headers added to the client only apply to the channel that was used to create the . +The sample demonstrates how a client can send additional information as a using . An object is created by scoping it to a channel. Headers that must be translated to the remote service can be added to the collection. Headers added to this collection can be retrieved on the service by accessing . Its calls are made on multiple channels and then the headers added to the client only apply to the channel that was used to create the . ## MessageHeaderReader -This is the sample service that receives a message from the client and tries to look up the header in the collection. The client passes the GUID that it sent in the header and the service retrieves the custom header and, if present, compares it with the GUID passed as the argument by the client. +This is the sample service that receives a message from the client and tries to look up the header in the collection. The client passes the GUID that it sent in the header and the service retrieves the custom header and, if present, compares it with the GUID passed as the argument by the client. ```csharp public bool RetrieveHeader(string guid) @@ -61,7 +61,7 @@ MessageHeaderReaderClient client1 = new MessageHeaderReaderClient(); MessageHeaderReaderClient client2 = new MessageHeaderReaderClient(); ``` -Client then creates an OperationContextScope and scopes it to `client1`. It adds a to and invokes one call on both clients. It ensures that the header is sent only on `client1` and not on `client2` by checking the return value from the `RetrieveHeader` call. +Client then creates an OperationContextScope and scopes it to `client1`. It adds a to and invokes one call on both clients. It ensures that the header is sent only on `client1` and not on `client2` by checking the return value from the `RetrieveHeader` call. ```csharp using (new OperationContextScope(client1.InnerChannel)) diff --git a/docs/framework/wcf/samples/poison-message-handling-in-msmq-4-0.md b/docs/framework/wcf/samples/poison-message-handling-in-msmq-4-0.md index ae72592f66a0f..cf9e91879a316 100644 --- a/docs/framework/wcf/samples/poison-message-handling-in-msmq-4-0.md +++ b/docs/framework/wcf/samples/poison-message-handling-in-msmq-4-0.md @@ -20,7 +20,7 @@ This sample illustrates the limited poison facilities provided on Windows Server In Windows Vista, MSMQ provides a poison subqueue facility that can be used to store poison messages. This sample demonstrates the best practice of dealing with poison messages using Windows Vista. -The poison message detection in Windows Vista is sophisticated. There are 3 properties that help with detection. The is number of times a given message is re-read from the queue and dispatched to the application for processing. A message is re-read from the queue when it is put back into the queue because the message cannot be dispatched to the application or the application rolls back the transaction in the service operation. is the number of times the message is moved to the retry queue. When is reached, the message is moved to the retry queue. The property is the time delay after which the message is moved from the retry queue back to the main queue. The is reset to 0. The message is tried again. If all attempts to read the message have failed, then the message is marked as poisoned. +The poison message detection in Windows Vista is sophisticated. There are 3 properties that help with detection. The is number of times a given message is re-read from the queue and dispatched to the application for processing. A message is re-read from the queue when it is put back into the queue because the message cannot be dispatched to the application or the application rolls back the transaction in the service operation. is the number of times the message is moved to the retry queue. When is reached, the message is moved to the retry queue. The property is the time delay after which the message is moved from the retry queue back to the main queue. The is reset to 0. The message is tried again. If all attempts to read the message have failed, then the message is marked as poisoned. Once the message is marked as poisoned, the message is dealt with according to the settings in the enumeration. To reiterate the possible values: diff --git a/docs/framework/wcf/samples/pooling.md b/docs/framework/wcf/samples/pooling.md index 513f1a99a5d57..3f2e5ee644375 100644 --- a/docs/framework/wcf/samples/pooling.md +++ b/docs/framework/wcf/samples/pooling.md @@ -15,17 +15,17 @@ The first step in creating a WCF extension is to decide the extensibility point In WCF the term *dispatcher* refers to a runtime component responsible for converting incoming messages into method invocations on the user's service and for converting return values from that method to an outgoing message. A WCF service creates a dispatcher for each endpoint. A WCF client must use a dispatcher if the contract associated with that client is a duplex contract. -The channel and endpoint dispatchers offer channel-and contract-wide extensibility by exposing various properties that control the behavior of the dispatcher. The property also enables you to inspect, modify, or customize the dispatching process. This sample focuses on the property that points to the object that provides the instances of the service class. +The channel and endpoint dispatchers offer channel-and contract-wide extensibility by exposing various properties that control the behavior of the dispatcher. The property also enables you to inspect, modify, or customize the dispatching process. This sample focuses on the property that points to the object that provides the instances of the service class. ## The IInstanceProvider -In WCF, the dispatcher creates instances of the service class using a , which implements the interface. This interface has three methods: +In WCF, the dispatcher creates instances of the service class using a , which implements the interface. This interface has three methods: -- : When a message arrives the Dispatcher calls the method to create an instance of the service class to process the message. The frequency of the calls to this method is determined by the property. For example, if the property is set to a new instance of service class is created to process each message that arrives, so is called whenever a message arrives. +- : When a message arrives the Dispatcher calls the method to create an instance of the service class to process the message. The frequency of the calls to this method is determined by the property. For example, if the property is set to a new instance of service class is created to process each message that arrives, so is called whenever a message arrives. - : This is identical to the previous method, except this is invoked when there is no Message argument. -- : When a service instance's lifetime has elapsed, the Dispatcher calls the method. Just like for the method, the frequency of the calls to this method is determined by the property. +- : When a service instance's lifetime has elapsed, the Dispatcher calls the method. Just like for the method, the frequency of the calls to this method is determined by the property. ## The Object Pool @@ -100,13 +100,13 @@ For the purpose of an object pooling extension a service behavior must be create This sample uses a custom attribute. When the is constructed it examines the attributes used in the service's type definition and adds the available behaviors to the service description's behaviors collection. -The interface has three methods in it -- , , and . The method is used to ensure that the behavior can be applied to the service. In this sample, the implementation ensures that the service is not configured with . The method is used to configure the service's bindings. It is not required in this scenario. The is used to configure the service's dispatchers. This method is called by WCF when the is being initialized. The following parameters are passed into this method: +The interface has three methods in it -- , , and . The method is used to ensure that the behavior can be applied to the service. In this sample, the implementation ensures that the service is not configured with . The method is used to configure the service's bindings. It is not required in this scenario. The is used to configure the service's dispatchers. This method is called by WCF when the is being initialized. The following parameters are passed into this method: - `Description`: This argument provides the service description for the entire service. This can be used to inspect description data about the service's endpoints, contracts, bindings, and other data. - `ServiceHostBase`: This argument provides the that is currently being initialized. -In the custom implementation a new instance of `ObjectPoolingInstanceProvider` is instantiated and assigned to the property in each in the ServiceHostBase. +In the custom implementation a new instance of `ObjectPoolingInstanceProvider` is instantiated and assigned to the property in each in the ServiceHostBase. ```csharp void IServiceBehavior.ApplyDispatchBehavior(ServiceDescription description, ServiceHostBase serviceHostBase) @@ -172,7 +172,7 @@ InvalidOperationException(ResourceHelper.GetString("ExNullThrottle")); } ``` -In addition to an implementation the class has several members to customize the object pool using the attribute arguments. These members include , , and , to match the object pooling feature set provided by .NET Enterprise Services. +In addition to an implementation the class has several members to customize the object pool using the attribute arguments. These members include , , and , to match the object pooling feature set provided by .NET Enterprise Services. The object pooling behavior can now be added to a WCF service by annotating the service implementation with the newly created custom `ObjectPooling` attribute. diff --git a/docs/framework/wcf/samples/saml-token-provider.md b/docs/framework/wcf/samples/saml-token-provider.md index 65e49f651ed5d..7cd4bcfc34b97 100644 --- a/docs/framework/wcf/samples/saml-token-provider.md +++ b/docs/framework/wcf/samples/saml-token-provider.md @@ -113,7 +113,7 @@ The following steps show how to develop a custom SAML token provider and integra The sample implements a custom SAML token provider that returns a security token based on a SAML assertion that is provided at construction time. - To perform this task, the custom token provider is derived from the class and overrides the method. This method creates and returns a new `SecurityToken`. + To perform this task, the custom token provider is derived from the class and overrides the method. This method creates and returns a new `SecurityToken`. ```csharp protected override SecurityToken GetTokenCore(TimeSpan timeout) diff --git a/docs/framework/wcf/samples/service-description.md b/docs/framework/wcf/samples/service-description.md index 316602b3ff23b..508636787b133 100644 --- a/docs/framework/wcf/samples/service-description.md +++ b/docs/framework/wcf/samples/service-description.md @@ -32,7 +32,7 @@ public interface IServiceDescriptionCalculator } ``` -The implementation code for `GetServiceDescriptionInfo` uses the to list the service endpoints. Because service endpoints can have relative addresses, it first lists the base addresses for the service. To get all of this information, the code obtains its operation context using . The and its object are retrieved from the operation context. To list the base endpoints for the service, the code iterates through the service host's collection. To list the service endpoints for the service, the code iterates through the service description's endpoints collection. +The implementation code for `GetServiceDescriptionInfo` uses the to list the service endpoints. Because service endpoints can have relative addresses, it first lists the base addresses for the service. To get all of this information, the code obtains its operation context using . The and its object are retrieved from the operation context. To list the base endpoints for the service, the code iterates through the service host's collection. To list the service endpoints for the service, the code iterates through the service description's endpoints collection. ```csharp public string GetServiceDescriptionInfo() diff --git a/docs/framework/wcf/samples/services.md b/docs/framework/wcf/samples/services.md index 111c5e8b75518..c2cffc9494be0 100644 --- a/docs/framework/wcf/samples/services.md +++ b/docs/framework/wcf/samples/services.md @@ -32,7 +32,7 @@ Demonstrates how to use standard endpoints in service configuration files. Demonstrates Extended Protection, a security initiative for protecting against man-in-the-middle (MITM) attacks. - [Configuration Channel Factory](configuration-channel-factory.md)\ -Demonstrates the usage of the . +Demonstrates the usage of the . - [Addressing](addressing.md)\ Demonstrates various aspects and features of endpoint addresses. diff --git a/docs/framework/wcf/samples/sessions-and-queues.md b/docs/framework/wcf/samples/sessions-and-queues.md index 79d5cd6f9ef1e..f3f9b777ad23d 100644 --- a/docs/framework/wcf/samples/sessions-and-queues.md +++ b/docs/framework/wcf/samples/sessions-and-queues.md @@ -70,7 +70,7 @@ public class OrderTakerService : IOrderTaker } ``` -The service is self hosted. When using the MSMQ transport, the queue used must be created in advance. This can be done manually or through code. In this sample, the service contains code to check for the existence of the queue and creates it, if necessary. The queue name is read from the configuration file using the class. +The service is self hosted. When using the MSMQ transport, the queue used must be created in advance. This can be done manually or through code. In this sample, the service contains code to check for the existence of the queue and creates it, if necessary. The queue name is read from the configuration file using the class. ```csharp // Host the service within this EXE console application. @@ -125,7 +125,7 @@ The MSMQ queue name is specified in an appSettings section of the configuration ``` -The client creates a transaction scope. All messages in the session are sent to the queue within the transaction scope, causing it to be treated as an atomic unit where all messages succeed or fail. The transaction is committed by calling . +The client creates a transaction scope. All messages in the session are sent to the queue within the transaction scope, causing it to be treated as an atomic unit where all messages succeed or fail. The transaction is committed by calling . ```csharp //Create a transaction scope. @@ -200,7 +200,7 @@ Purchase Order: 7c86fef0-2306-4c51-80e6-bcabcc1a6e5e 3. To run the sample in a single- or cross-machine configuration, follow the instructions in [Running the Windows Communication Foundation Samples](running-the-samples.md). -By default with the , transport security is enabled. There are two relevant properties for MSMQ transport security namely, and `.` By default, the authentication mode is set to `Windows` and the protection level is set to `Sign`. For MSMQ to provide the authentication and signing feature, it must be part of a domain and the active directory integration option for MSMQ must be installed. If you run this sample on a computer that does not satisfy these criteria, you receive an error. +By default with the , transport security is enabled. There are two relevant properties for MSMQ transport security namely, and `.` By default, the authentication mode is set to `Windows` and the protection level is set to `Sign`. For MSMQ to provide the authentication and signing feature, it must be part of a domain and the active directory integration option for MSMQ must be installed. If you run this sample on a computer that does not satisfy these criteria, you receive an error. ### Run the sample on a computer joined to a workgroup @@ -254,4 +254,4 @@ By default with the , transport securit 2. Ensure that you change the configuration on both the server and the client before you run the sample. > [!NOTE] - > Setting security mode to `None` is equivalent to setting , , and `Message` security to `None`. + > Setting security mode to `None` is equivalent to setting , , and `Message` security to `None`. diff --git a/docs/framework/wcf/samples/setting-the-use-and-style-properties.md b/docs/framework/wcf/samples/setting-the-use-and-style-properties.md index db951bc99213c..2dc14f0a300e3 100644 --- a/docs/framework/wcf/samples/setting-the-use-and-style-properties.md +++ b/docs/framework/wcf/samples/setting-the-use-and-style-properties.md @@ -11,7 +11,7 @@ The [UseAndStyle sample](https://github.com/dotnet/samples/tree/main/framework/w > [!NOTE] > The setup procedure and build instructions for this sample are located at the end of this topic. -The style property determines how the WSDL metadata for the service is formatted. Possible values are , and . RPC means that the WSDL representation of messages exchanged for an operation contains parameters as if it were a remote procedure call. The following is an example. +The style property determines how the WSDL metadata for the service is formatted. Possible values are , and . RPC means that the WSDL representation of messages exchanged for an operation contains parameters as if it were a remote procedure call. The following is an example. ```xml @@ -69,7 +69,7 @@ public interface IUseAndStyleCalculator } ``` -To see the difference between the different and settings, modify them in the service, regenerate the client, run the sample, and examine the c:\logs\message.logs file with the Service Trace Viewer tool. Also observe the impact on the metadata by viewing `http://localhost/ServiceModelSamples/service.svc?wsdl`. The metadata for services is typically broken up into multiple pages. The main wsdl page contains the WSDL bindings, but view `http://localhost/ServiceModelSamples/service.svc?wsdl=wsdl0` to observe the message definitions. +To see the difference between the different and settings, modify them in the service, regenerate the client, run the sample, and examine the c:\logs\message.logs file with the Service Trace Viewer tool. Also observe the impact on the metadata by viewing `http://localhost/ServiceModelSamples/service.svc?wsdl`. The metadata for services is typically broken up into multiple pages. The main wsdl page contains the WSDL bindings, but view `http://localhost/ServiceModelSamples/service.svc?wsdl=wsdl0` to observe the message definitions. ## To set up, build, and run the sample diff --git a/docs/framework/wcf/samples/strongly-typed-extensions-sample.md b/docs/framework/wcf/samples/strongly-typed-extensions-sample.md index f5b17c6ca9177..51d62c4b1b39c 100644 --- a/docs/framework/wcf/samples/strongly-typed-extensions-sample.md +++ b/docs/framework/wcf/samples/strongly-typed-extensions-sample.md @@ -8,7 +8,7 @@ ms.assetid: 02220f11-1a83-441c-9e5a-85f9a9367572 The [StronglyTypedExtensions sample](https://github.com/dotnet/samples/tree/main/framework/wcf) uses the class for the purposes of the example. However, the patterns demonstrated in this sample can be used with all of the Syndication classes that support extension data. -The Syndication object model (, , and related classes) supports loosely-typed access to extension data by using the and properties. This sample shows how to provide strongly typed access to extension data by implementing custom derived classes of and that make available certain application-specific extensions as strongly typed properties. +The Syndication object model (, , and related classes) supports loosely-typed access to extension data by using the and properties. This sample shows how to provide strongly typed access to extension data by implementing custom derived classes of and that make available certain application-specific extensions as strongly typed properties. As an example, this sample shows how to implement an extension element defined in the proposed Atom Threading Extensions RFC. This is for demonstration purposes only and this sample is not intended to be a full implementation of the proposed specification. @@ -84,9 +84,9 @@ public class InReplyToElement : IXmlSerializable } ``` -The `InReplyToElement` class implements properties for the required attribute (`HRef`, `MediaType`, and `Source`) as well as collections to hold and . +The `InReplyToElement` class implements properties for the required attribute (`HRef`, `MediaType`, and `Source`) as well as collections to hold and . -The `InReplyToElement` class implements the interface, which allows direct control over how object instances are read from and written to XML. The `ReadXml` method first reads the values for the `Ref`, `HRef`, `Source`, and `MediaType` properties from the passed to it. Any unknown attributes are stored in the collection. When all the attributes have been read, is called to advance the reader to the next element. Because the element modeled by this class has no required children, the child elements get buffered into `XElement` instances and stored in the collection, as shown in the following code. +The `InReplyToElement` class implements the interface, which allows direct control over how object instances are read from and written to XML. The `ReadXml` method first reads the values for the `Ref`, `HRef`, `Source`, and `MediaType` properties from the passed to it. Any unknown attributes are stored in the collection. When all the attributes have been read, is called to advance the reader to the next element. Because the element modeled by this class has no required children, the child elements get buffered into `XElement` instances and stored in the collection, as shown in the following code. ```csharp public void ReadXml(System.Xml.XmlReader reader) @@ -142,7 +142,7 @@ public void ReadXml(System.Xml.XmlReader reader) } ``` -In `WriteXml`, the `InReplyToElement` method first writes out the values of the `Ref`, `HRef`, `Source`, and `MediaType` properties as XML attributes (`WriteXml` is not responsible for writing the actual outer element itself, as that done by the caller of `WriteXml`). It also writes the contents of the and to the writer, as shown in the following code. +In `WriteXml`, the `InReplyToElement` method first writes out the values of the `Ref`, `HRef`, `Source`, and `MediaType` properties as XML attributes (`WriteXml` is not responsible for writing the actual outer element itself, as that done by the caller of `WriteXml`). It also writes the contents of the and to the writer, as shown in the following code. ```csharp public void WriteXml(System.Xml.XmlWriter writer) diff --git a/docs/framework/wcf/samples/token-authenticator.md b/docs/framework/wcf/samples/token-authenticator.md index 489cca8e35235..1eff32d6a7cc6 100644 --- a/docs/framework/wcf/samples/token-authenticator.md +++ b/docs/framework/wcf/samples/token-authenticator.md @@ -277,7 +277,7 @@ Use the following steps to create a custom token authenticator: serviceHost.Description.Behaviors.Add(serviceCredential); ``` -To display the caller's information, you can use the as shown in the following code. The contains claims information about the current caller. +To display the caller's information, you can use the as shown in the following code. The contains claims information about the current caller. ```csharp static void DisplayIdentityInformation() diff --git a/docs/framework/wcf/samples/token-provider.md b/docs/framework/wcf/samples/token-provider.md index 1a3237968e195..674e7d98f5c04 100644 --- a/docs/framework/wcf/samples/token-provider.md +++ b/docs/framework/wcf/samples/token-provider.md @@ -199,7 +199,7 @@ The following steps show how to develop a custom token provider and integrate it } ``` -On the service, to display the caller's information, use the as shown in the following code example. The contains claims information about the current caller. +On the service, to display the caller's information, use the as shown in the following code example. The contains claims information about the current caller. ```csharp static void DisplayIdentityInformation() diff --git a/docs/framework/wcf/samples/transacted-msmq-binding.md b/docs/framework/wcf/samples/transacted-msmq-binding.md index b805a8a4532dd..e98b69780a1e0 100644 --- a/docs/framework/wcf/samples/transacted-msmq-binding.md +++ b/docs/framework/wcf/samples/transacted-msmq-binding.md @@ -88,7 +88,7 @@ The MSMQ queue name is specified in an appSettings section of the configuration > [!NOTE] > The queue name uses a dot (.) for the local computer and backslash separators in its path when creating the queue using . The Windows Communication Foundation (WCF) endpoint uses the queue address with net.msmq scheme, uses "localhost" to denote the local computer, and uses forward slashes in its path. -The client creates a transaction scope. Communication with the queue takes place within the scope of the transaction, causing it to be treated as an atomic unit where all messages are sent to the queue or none of the messages are sent to the queue. The transaction is committed by calling on the transaction scope. +The client creates a transaction scope. Communication with the queue takes place within the scope of the transaction, causing it to be treated as an atomic unit where all messages are sent to the queue or none of the messages are sent to the queue. The transaction is committed by calling on the transaction scope. ```csharp // Create a client. @@ -173,7 +173,7 @@ Processing Purchase Order: 7b31ce51-ae7c-4def-9b8b-617e4288eafd 4. To run the sample in a single- or cross-computer configuration, follow the instructions in [Running the Windows Communication Foundation Samples](running-the-samples.md). -By default with the , transport security is enabled. There are two relevant properties for MSMQ transport security, and . By default, the authentication mode is set to `Windows` and the protection level is set to `Sign`. For MSMQ to provide the authentication and signing feature, it must be part of a domain and the Active Directory integration option for MSMQ must be installed. If you run this sample on a computer that does not satisfy these criteria, you receive an error. +By default with the , transport security is enabled. There are two relevant properties for MSMQ transport security, and . By default, the authentication mode is set to `Windows` and the protection level is set to `Sign`. For MSMQ to provide the authentication and signing feature, it must be part of a domain and the Active Directory integration option for MSMQ must be installed. If you run this sample on a computer that does not satisfy these criteria, you receive an error. ### To run the sample on a computer joined to a workgroup or without Active Directory integration @@ -224,4 +224,4 @@ By default with the , transport securit 2. Ensure that you change the configuration on both the server and the client before you run the sample. > [!NOTE] - > Setting `security mode` to `None` is equivalent to setting , , and `Message` security to `None`. + > Setting `security mode` to `None` is equivalent to setting , , and `Message` security to `None`. diff --git a/docs/framework/wcf/samples/transport-udp.md b/docs/framework/wcf/samples/transport-udp.md index b26ef58f84f70..b417c32453a9f 100644 --- a/docs/framework/wcf/samples/transport-udp.md +++ b/docs/framework/wcf/samples/transport-udp.md @@ -53,17 +53,17 @@ WCF has a common state machine that is used for managing the lifecycle of object - Created: This is the state of a when it is first instantiated. No input/output (I/O) occurs in this state. -- Opening: Objects transition to this state when is called. At this point properties are made immutable, and input/output can begin. This transition is valid only from the Created state. +- Opening: Objects transition to this state when is called. At this point properties are made immutable, and input/output can begin. This transition is valid only from the Created state. - Opened: Objects transition to this state when the open process completes. This transition is valid only from the Opening state. At this point, the object is fully usable for transfer. -- Closing: Objects transition to this state when is called for a graceful shutdown. This transition is valid only from the Opened state. +- Closing: Objects transition to this state when is called for a graceful shutdown. This transition is valid only from the Opened state. - Closed: In the Closed state objects are no longer usable. In general, most configuration is still accessible for inspection, but no communication can occur. This state is equivalent to being disposed. - Faulted: In the Faulted state, objects are accessible to inspection but no longer usable. When a non-recoverable error occurs, the object transitions into this state. The only valid transition from this state is into the `Closed` state. -There are events that fire for each state transition. The method can be called at any time, and causes the object to transition immediately from its current state into the Closed state. Calling terminates any unfinished work. +There are events that fire for each state transition. The method can be called at any time, and causes the object to transition immediately from its current state into the Closed state. Calling terminates any unfinished work. @@ -83,7 +83,7 @@ In this sample, the factory implementation is contained in UdpChannelFactory.cs ### The UDP Channel Factory -The `UdpChannelFactory` derives from . The sample overrides to provide access to the message version of the message encoder. The sample also overrides so that we can tear down our instance of when the state machine transitions. +The `UdpChannelFactory` derives from . The sample overrides to provide access to the message version of the message encoder. The sample also overrides so that we can tear down our instance of when the state machine transitions. #### The UDP Output Channel diff --git a/docs/framework/wcf/samples/two-way-communication.md b/docs/framework/wcf/samples/two-way-communication.md index 75a53bdb74cf6..21ae0f6de064d 100644 --- a/docs/framework/wcf/samples/two-way-communication.md +++ b/docs/framework/wcf/samples/two-way-communication.md @@ -223,7 +223,7 @@ Status of order 124a1f69-3699-4b16-9bcc-43147a8756fc:Pending > [!NOTE] > If you use Svcutil.exe to regenerate the configuration for this sample, be sure to modify the endpoint names in the client configuration to match the client code. -By default with the , transport security is enabled. There are two relevant properties for MSMQ transport security, and `.` By default, the authentication mode is set to `Windows` and the protection level is set to `Sign`. For MSMQ to provide the authentication and signing feature, it must be part of a domain and the active directory integration option for MSMQ must be installed. If you run this sample on a computer that does not satisfy these criteria you receive an error. +By default with the , transport security is enabled. There are two relevant properties for MSMQ transport security, and `.` By default, the authentication mode is set to `Windows` and the protection level is set to `Sign`. For MSMQ to provide the authentication and signing feature, it must be part of a domain and the active directory integration option for MSMQ must be installed. If you run this sample on a computer that does not satisfy these criteria you receive an error. ### To run the sample on a computer joined to a workgroup or without active directory integration @@ -316,4 +316,4 @@ By default with the , transport securit 4. Ensure that you change the configuration on both the server and the client before you run the sample. > [!NOTE] - > Setting `security mode` to `None` is equivalent to setting , or `Message` security to `None`. + > Setting `security mode` to `None` is equivalent to setting , or `Message` security to `None`. diff --git a/docs/framework/wcf/samples/uritemplate-sample.md b/docs/framework/wcf/samples/uritemplate-sample.md index d54dee005bb2d..5a01f3591fd26 100644 --- a/docs/framework/wcf/samples/uritemplate-sample.md +++ b/docs/framework/wcf/samples/uritemplate-sample.md @@ -10,9 +10,9 @@ The class provides methods for working with sets of UR - Syntax for creating templates. -- Instantiating URIs from a `UriTemplate` using and . +- Instantiating URIs from a `UriTemplate` using and . -- , which is the inverse operation of `BindByName` and `BindByPosition`. +- , which is the inverse operation of `BindByName` and `BindByPosition`. ### To set up, build, and run the sample diff --git a/docs/framework/wcf/samples/uritemplate-table-dispatcher-sample.md b/docs/framework/wcf/samples/uritemplate-table-dispatcher-sample.md index de1f118fffa03..9468cabf7f183 100644 --- a/docs/framework/wcf/samples/uritemplate-table-dispatcher-sample.md +++ b/docs/framework/wcf/samples/uritemplate-table-dispatcher-sample.md @@ -12,7 +12,7 @@ This sample demonstrates the following key concepts for the `UriTemplateTable` c - Associating delegates with `UriTemplates` in a `UriTemplateTable`. -- Using to obtain the correct handler delegate for a particular URI. +- Using to obtain the correct handler delegate for a particular URI. - Invoking the handler delegate to process the request. diff --git a/docs/framework/wcf/samples/uritemplate-table-sample.md b/docs/framework/wcf/samples/uritemplate-table-sample.md index bbdc6110103c3..c2134aaf24e92 100644 --- a/docs/framework/wcf/samples/uritemplate-table-sample.md +++ b/docs/framework/wcf/samples/uritemplate-table-sample.md @@ -14,7 +14,7 @@ The [UriTemplateTable sample](https://github.com/dotnet/samples/tree/main/framew - Populating a `UriTemplateTable` with a set of key/value pairs. -- Matching a candidate URI against the table using . +- Matching a candidate URI against the table using . ### To set up, build, and run the sample diff --git a/docs/framework/wcf/samples/volatile-queued-communication.md b/docs/framework/wcf/samples/volatile-queued-communication.md index fd6144405960d..de04e7cfcc9f2 100644 --- a/docs/framework/wcf/samples/volatile-queued-communication.md +++ b/docs/framework/wcf/samples/volatile-queued-communication.md @@ -159,7 +159,7 @@ Stock Tick zzz9:43.3 3. To run the sample in a single- or cross-machine configuration, follow the instructions in [Running the Windows Communication Foundation Samples](running-the-samples.md). -By default with the , transport security is enabled. There are two pertinent properties for MSMQ transport security, and `.` By default, the authentication mode is set to `Windows` and the protection level is set to `Sign`. For MSMQ to provide the authentication and signing feature, it must be part of a domain and the active directory integration option for MSMQ must be installed. If you run this sample on a computer that does not satisfy these criteria you receive an error. +By default with the , transport security is enabled. There are two pertinent properties for MSMQ transport security, and `.` By default, the authentication mode is set to `Windows` and the protection level is set to `Sign`. For MSMQ to provide the authentication and signing feature, it must be part of a domain and the active directory integration option for MSMQ must be installed. If you run this sample on a computer that does not satisfy these criteria you receive an error. ### To run the sample on a computer joined to a workgroup or without active directory integration @@ -213,4 +213,4 @@ By default with the , transport securit 2. Ensure that you change the configuration on both the server and the client before you run the sample. > [!NOTE] - > Setting `security mode` to `None` is equivalent to setting , , and `Message` security to `None`. + > Setting `security mode` to `None` is equivalent to setting , , and `Message` security to `None`. diff --git a/docs/framework/wcf/samples/weakly-typed-json-serialization-sample.md b/docs/framework/wcf/samples/weakly-typed-json-serialization-sample.md index 0056c916679f0..5baba67ce7c02 100644 --- a/docs/framework/wcf/samples/weakly-typed-json-serialization-sample.md +++ b/docs/framework/wcf/samples/weakly-typed-json-serialization-sample.md @@ -105,7 +105,7 @@ XmlDictionaryReader reader = channel.GetMemberProfile().GetReaderAtBodyContents( JsonObject json = new JsonObject(reader); ``` -The `JsonObject` constructor takes a , which is obtained through the method. The reader contains an XML representation of the JSON message received by the client. For more information, see the topic [Mapping Between JSON and XML](../feature-details/mapping-between-json-and-xml.md). +The `JsonObject` constructor takes a , which is obtained through the method. The reader contains an XML representation of the JSON message received by the client. For more information, see the topic [Mapping Between JSON and XML](../feature-details/mapping-between-json-and-xml.md). The program produces the following output: diff --git a/docs/framework/wcf/samples/ws-transaction-flow.md b/docs/framework/wcf/samples/ws-transaction-flow.md index b344848762fa0..c278e895437e3 100644 --- a/docs/framework/wcf/samples/ws-transaction-flow.md +++ b/docs/framework/wcf/samples/ws-transaction-flow.md @@ -62,10 +62,10 @@ To enable transaction flow, bindings with the [\](../../configu > [!NOTE] > The system-provided netTcpBinding allows specification of the transactionProtocol whereas the system-provided wsHttpBinding uses only the more interoperable WSAtomicTransactionOctober2004 protocol. The OleTransactions protocol is only available for use by Windows Communication Foundation (WCF) clients. -For the class that implements the `ICalculator` interface, all of the methods are attributed with property set to `true`. This setting declares that all actions taken within the method occur within the scope of a transaction. In this case, the actions taken include recording to the log database. If the operation request includes a flowed transaction then the actions occur within the scope of the incoming transaction or a new transaction scope is automatically generated. +For the class that implements the `ICalculator` interface, all of the methods are attributed with property set to `true`. This setting declares that all actions taken within the method occur within the scope of a transaction. In this case, the actions taken include recording to the log database. If the operation request includes a flowed transaction then the actions occur within the scope of the incoming transaction or a new transaction scope is automatically generated. > [!NOTE] -> The property defines behavior local to the service method implementations and does not define the client's ability to or requirement for flowing a transaction. +> The property defines behavior local to the service method implementations and does not define the client's ability to or requirement for flowing a transaction. ```csharp // Service class that implements the service contract. diff --git a/docs/framework/wcf/samples/wsstreamedhttpbinding.md b/docs/framework/wcf/samples/wsstreamedhttpbinding.md index a686290ff4ab3..5827d22bb39ae 100644 --- a/docs/framework/wcf/samples/wsstreamedhttpbinding.md +++ b/docs/framework/wcf/samples/wsstreamedhttpbinding.md @@ -39,7 +39,7 @@ The steps to create and configure a new standard binding are as follows. 2. Add configuration support - To expose the transport through configuration the sample implements two more classes—`WSStreamedHttpBindingConfigurationElement` and `WSStreamedHttpBindingSection`. The class `WSStreamedHttpBindingSection` is a that exposes `WSStreamedHttpBinding` to the WCF configuration system. The bulk of the implementation is delegated to `WSStreamedHttpBindingConfigurationElement`, which derives from . The class `WSStreamedHttpBindingConfigurationElement` has properties that correspond to the properties of `WSStreamedHttpBinding`, and functions to map each configuration element to a binding. + To expose the transport through configuration the sample implements two more classes—`WSStreamedHttpBindingConfigurationElement` and `WSStreamedHttpBindingSection`. The class `WSStreamedHttpBindingSection` is a that exposes `WSStreamedHttpBinding` to the WCF configuration system. The bulk of the implementation is delegated to `WSStreamedHttpBindingConfigurationElement`, which derives from . The class `WSStreamedHttpBindingConfigurationElement` has properties that correspond to the properties of `WSStreamedHttpBinding`, and functions to map each configuration element to a binding. Register the handler with the configuration system, by adding the following section to the service's configuration file. diff --git a/docs/framework/wcf/samples/xmlreader-sample.md b/docs/framework/wcf/samples/xmlreader-sample.md index c50b758297a21..f4c68b6cd9bd8 100644 --- a/docs/framework/wcf/samples/xmlreader-sample.md +++ b/docs/framework/wcf/samples/xmlreader-sample.md @@ -49,7 +49,7 @@ using (new OperationContextScope(client.InnerChannel)) } ``` -In the service, the implementation of the service operation `Sum` accesses the message body using an object to iterate through the values to sum. The method is called to access the message body, as shown in the following sample code. +In the service, the implementation of the service operation `Sum` accesses the message body using an object to iterate through the values to sum. The method is called to access the message body, as shown in the following sample code. ```csharp public int Sum(Message message) diff --git a/docs/framework/wcf/samples/xmlserializer-faults.md b/docs/framework/wcf/samples/xmlserializer-faults.md index 2ab4789cc89d7..453b7ce500537 100644 --- a/docs/framework/wcf/samples/xmlserializer-faults.md +++ b/docs/framework/wcf/samples/xmlserializer-faults.md @@ -11,7 +11,7 @@ The [XmlSerializerFaults sample](https://github.com/dotnet/samples/tree/main/fra > [!NOTE] > The setup procedure and build instructions for this sample are located at the end of this topic. -The calculator contract has been modified to include a as shown in the following sample code. Also, the is used to enable serialization using the . The property is set to `true` on this attribute, which instructs the serializer to use the for reading and writing faults. +The calculator contract has been modified to include a as shown in the following sample code. Also, the is used to enable serialization using the . The property is set to `true` on this attribute, which instructs the serializer to use the for reading and writing faults. ```csharp [XmlSerializerFormat(SupportFaults=true)] @@ -46,4 +46,4 @@ When generating code for the client proxy, you must apply the **/UseSerializerFo ## See also - -- +- diff --git a/docs/framework/wcf/securing-clients.md b/docs/framework/wcf/securing-clients.md index eef97d3f9f08d..d31da1519e515 100644 --- a/docs/framework/wcf/securing-clients.md +++ b/docs/framework/wcf/securing-clients.md @@ -8,111 +8,111 @@ ms.custom: sfi-ropc-nochange --- # Securing Clients -In Windows Communication Foundation (WCF), the service dictates the security requirements for clients. That is, the service specifies what security mode to use, and whether or not the client must provide a credential. The process of securing a client, therefore, is simple: use the metadata obtained from the service (if it is published) and build a client. The metadata specifies how to configure the client. If the service requires that the client supply a credential, then you must obtain a credential that fits the requirement. This topic discusses the process in further detail. For more information about creating a secure service, see [Securing Services](securing-services.md). - -## The Service Specifies Security +In Windows Communication Foundation (WCF), the service dictates the security requirements for clients. That is, the service specifies what security mode to use, and whether or not the client must provide a credential. The process of securing a client, therefore, is simple: use the metadata obtained from the service (if it is published) and build a client. The metadata specifies how to configure the client. If the service requires that the client supply a credential, then you must obtain a credential that fits the requirement. This topic discusses the process in further detail. For more information about creating a secure service, see [Securing Services](securing-services.md). - By default, WCF bindings have security features enabled. (The exception is the .) Therefore, if the service was created using WCF, there is a greater chance that it will implement security to ensure authentication, confidentiality, and integrity. In that case, the metadata the service provides will indicate what it requires to establish a secure communication channel. If the service metadata does not include any security requirements, there is no way to impose a security scheme, such as Secure Sockets Layer (SSL) over HTTP, on a service. If, however, the service requires the client to supply a credential, then the client developer, deployer, or administrator must supply the actual credential that the client will use to authenticate itself to the service. - -## Obtaining Metadata +## The Service Specifies Security + + By default, WCF bindings have security features enabled. (The exception is the .) Therefore, if the service was created using WCF, there is a greater chance that it will implement security to ensure authentication, confidentiality, and integrity. In that case, the metadata the service provides will indicate what it requires to establish a secure communication channel. If the service metadata does not include any security requirements, there is no way to impose a security scheme, such as Secure Sockets Layer (SSL) over HTTP, on a service. If, however, the service requires the client to supply a credential, then the client developer, deployer, or administrator must supply the actual credential that the client will use to authenticate itself to the service. + +## Obtaining Metadata + + When creating a client, the first step is to obtain the metadata for the service that the client will communicate with. This can be done in two ways. First, if the service publishes a metadata exchange (MEX) endpoint or makes its metadata available over HTTP or HTTPS, you can download the metadata using the [ServiceModel Metadata Utility Tool (Svcutil.exe)](servicemodel-metadata-utility-tool-svcutil-exe.md), which generates both code files for a client as well as a configuration file. (For more information about using the tool, see [Accessing Services Using a WCF Client](accessing-services-using-a-wcf-client.md).) If the service does not publish a MEX endpoint and also does not make its metadata available over HTTP or HTTPS, you must contact the service creator for documentation that describes the security requirements and the metadata. - When creating a client, the first step is to obtain the metadata for the service that the client will communicate with. This can be done in two ways. First, if the service publishes a metadata exchange (MEX) endpoint or makes its metadata available over HTTP or HTTPS, you can download the metadata using the [ServiceModel Metadata Utility Tool (Svcutil.exe)](servicemodel-metadata-utility-tool-svcutil-exe.md), which generates both code files for a client as well as a configuration file. (For more information about using the tool, see [Accessing Services Using a WCF Client](accessing-services-using-a-wcf-client.md).) If the service does not publish a MEX endpoint and also does not make its metadata available over HTTP or HTTPS, you must contact the service creator for documentation that describes the security requirements and the metadata. - > [!IMPORTANT] -> It is recommended that the metadata come from a trusted source and that it not be tampered with. Metadata retrieved using the HTTP protocol is sent in clear text and can be tampered with. If the service uses the and properties, use the URL the service creator supplied to download the data using the HTTPS protocol. - -## Validating Security - - Metadata sources can be divided into two broad categories: trust sources and untrusted sources. If you trust a source and have downloaded the client code and other metadata from that source's secure MEX endpoint, then you can build the client, supply it with the right credentials, and run it with no other concerns. - - However, if you elect to download a client and metadata from a source that you know little about, be sure to validate the security measures the code uses. For example, you must not simply create a client that sends your personal or financial information to a service unless the service demands confidentiality and integrity (at the very least). You should trust the owner of the service to the extent that you are willing to disclose such information, because such information will be visible to them. - - As a rule, therefore, when using code and metadata from an untrusted source, check the code and metadata to ensure that it meets the security level that you require. - -## Setting a Client Credential - - Setting a client credential on a client consists of two steps: - -1. Determine the *client credential type* the service requires. This is accomplished by one of two methods. First, if you have documentation from the service creator, it should specify the client credential type (if any) the service requires. Second, if you have only a configuration file generated by the Svcutil.exe tool, you can examine the individual bindings to determine what credential type is required. - -2. Specify an actual client credential. The actual client credential is called a *client credential value* to distinguish it from the type. For example, if the client credential type specifies a certificate, you must supply an X.509 certificate that is issued by a certification authority the service trusts. - -### Determining the Client Credential Type - - If you have the configuration file the Svcutil.exe tool generated, examine the [\](../configure-apps/file-schema/wcf/bindings.md) section to determine what client credential type is required. Within the section are binding elements that specify the security requirements. Specifically, examine the \ Element of each binding. That element includes the `mode` attribute, which you can set to one of three possible values (`Message`, `Transport`, or `TransportWithMessageCredential`). The value of the attribute determines the mode, and the mode determines which of the child elements is significant. - - The `` element can contain either a `` or `` element, or both. The significant element is the one that matches the security mode. For example, the following code specifies that the security mode is `"Message"`, and the client credential type for the `` element is `"Certificate"`. In this case, the `` element can be ignored. However, the `` element specifies that an X.509 certificate must be supplied. - -```xml - - - +> It is recommended that the metadata come from a trusted source and that it not be tampered with. Metadata retrieved using the HTTP protocol is sent in clear text and can be tampered with. If the service uses the and properties, use the URL the service creator supplied to download the data using the HTTPS protocol. + +## Validating Security + + Metadata sources can be divided into two broad categories: trust sources and untrusted sources. If you trust a source and have downloaded the client code and other metadata from that source's secure MEX endpoint, then you can build the client, supply it with the right credentials, and run it with no other concerns. + + However, if you elect to download a client and metadata from a source that you know little about, be sure to validate the security measures the code uses. For example, you must not simply create a client that sends your personal or financial information to a service unless the service demands confidentiality and integrity (at the very least). You should trust the owner of the service to the extent that you are willing to disclose such information, because such information will be visible to them. + + As a rule, therefore, when using code and metadata from an untrusted source, check the code and metadata to ensure that it meets the security level that you require. + +## Setting a Client Credential + + Setting a client credential on a client consists of two steps: + +1. Determine the *client credential type* the service requires. This is accomplished by one of two methods. First, if you have documentation from the service creator, it should specify the client credential type (if any) the service requires. Second, if you have only a configuration file generated by the Svcutil.exe tool, you can examine the individual bindings to determine what credential type is required. + +2. Specify an actual client credential. The actual client credential is called a *client credential value* to distinguish it from the type. For example, if the client credential type specifies a certificate, you must supply an X.509 certificate that is issued by a certification authority the service trusts. + +### Determining the Client Credential Type + + If you have the configuration file the Svcutil.exe tool generated, examine the [\](../configure-apps/file-schema/wcf/bindings.md) section to determine what client credential type is required. Within the section are binding elements that specify the security requirements. Specifically, examine the \ Element of each binding. That element includes the `mode` attribute, which you can set to one of three possible values (`Message`, `Transport`, or `TransportWithMessageCredential`). The value of the attribute determines the mode, and the mode determines which of the child elements is significant. + + The `` element can contain either a `` or `` element, or both. The significant element is the one that matches the security mode. For example, the following code specifies that the security mode is `"Message"`, and the client credential type for the `` element is `"Certificate"`. In this case, the `` element can be ignored. However, the `` element specifies that an X.509 certificate must be supplied. + +```xml + + + + realm="" /> - - - -``` - - Note that if the `clientCredentialType` attribute is set to `"Windows"`, as shown in the following example, you do not need to supply an actual credential value. This is because the Windows integrated security provides the actual credential (a Kerberos token) of the person who is running the client. - -```xml - + establishSecurityContext="true" /> + + + +``` + + Note that if the `clientCredentialType` attribute is set to `"Windows"`, as shown in the following example, you do not need to supply an actual credential value. This is because the Windows integrated security provides the actual credential (a Kerberos token) of the person who is running the client. + +```xml + - -``` - -### Setting the Client Credential Value - - If it is determined that the client must supply a credential, use the appropriate method to configure the client. For example, to set a client certificate, use the method. - - A common form of credential is the X.509 certificate. You can supply the credential in two ways: - -- By programming it in your client code (using the `SetCertificate` method). - - By adding a [\](../configure-apps/file-schema/wcf/behaviors.md) section of the configuration file for the client and using the `clientCredentials` element (shown below). - -#### Setting a \ Value in Code - - To set a [\](../configure-apps/file-schema/wcf/clientcredentials.md) value in code, you must access the property of the class. The property returns a object that allows access to various credential types, as shown in the following table. - -|ClientCredential Property|Description|Notes| -|-------------------------------|-----------------|-----------| -||Returns an |Represents an X.509 certificate provided by the client to authenticate itself to the service.| -||Returns an |Represents an HTTP digest credential. The credential is a hash of the user name and password.| -||Returns an |Represents a custom security token issued by a Security Token Service, commonly used in federation scenarios.| -||Returns a |Represents a Peer credential for participation in a Peer mesh on a Windows domain.| -||Returns an |Represents an X.509 certificate provided by the service in an out-of-band negotiation.| -||Returns a |Represents a user name and password pair.| -||Returns a |Represents a Windows client credential (a Kerberos credential). The properties of the class are read-only.| - -#### Setting a \ Value in Configuration - - Credential values are specified by using an endpoint behavior as child elements of the [\](../configure-apps/file-schema/wcf/clientcredentials.md) element. The element used depends on the client credential type. For example, the following example shows the configuration to set an X.509 certificate using the <[\](../configure-apps/file-schema/wcf/clientcertificate-of-clientcredentials-element.md). - -```xml - - - + realm="" /> + +``` + +### Setting the Client Credential Value + + If it is determined that the client must supply a credential, use the appropriate method to configure the client. For example, to set a client certificate, use the method. + + A common form of credential is the X.509 certificate. You can supply the credential in two ways: + +- By programming it in your client code (using the `SetCertificate` method). + + By adding a [\](../configure-apps/file-schema/wcf/behaviors.md) section of the configuration file for the client and using the `clientCredentials` element (shown below). + +#### Setting a \ Value in Code + + To set a [\](../configure-apps/file-schema/wcf/clientcredentials.md) value in code, you must access the property of the class. The property returns a object that allows access to various credential types, as shown in the following table. + +|ClientCredential Property|Description|Notes| +|-------------------------------|-----------------|-----------| +||Returns an |Represents an X.509 certificate provided by the client to authenticate itself to the service.| +||Returns an |Represents an HTTP digest credential. The credential is a hash of the user name and password.| +||Returns an |Represents a custom security token issued by a Security Token Service, commonly used in federation scenarios.| +||Returns a |Represents a Peer credential for participation in a Peer mesh on a Windows domain.| +||Returns an |Represents an X.509 certificate provided by the service in an out-of-band negotiation.| +||Returns a |Represents a user name and password pair.| +||Returns a |Represents a Windows client credential (a Kerberos credential). The properties of the class are read-only.| + +#### Setting a \ Value in Configuration + + Credential values are specified by using an endpoint behavior as child elements of the [\](../configure-apps/file-schema/wcf/clientcredentials.md) element. The element used depends on the client credential type. For example, the following example shows the configuration to set an X.509 certificate using the <[\](../configure-apps/file-schema/wcf/clientcertificate-of-clientcredentials-element.md). + +```xml + + + - - + + - + storeLocation="Current" X509FindType="FindBySubjectName" /> + - - -``` - - To set the client credential in configuration, add an [\](../configure-apps/file-schema/wcf/endpointbehaviors.md) element to the configuration file. Additionally, the added behavior element must be linked to the service's endpoint using the `behaviorConfiguration` attribute of the [\ of \](../configure-apps/file-schema/wcf/endpoint-of-client.md) element as shown in the following example. The value of the `behaviorConfiguration` attribute must match the value of the behavior `name` attribute. + + +``` + + To set the client credential in configuration, add an [\](../configure-apps/file-schema/wcf/endpointbehaviors.md) element to the configuration file. Additionally, the added behavior element must be linked to the service's endpoint using the `behaviorConfiguration` attribute of the [\ of \](../configure-apps/file-schema/wcf/endpoint-of-client.md) element as shown in the following example. The value of the `behaviorConfiguration` attribute must match the value of the behavior `name` attribute. ```xml @@ -127,35 +127,35 @@ In Windows Communication Foundation (WCF), the service dictates the security req ``` - + > [!NOTE] -> Some of the client credential values cannot be set using application configuration files, for example, user name and password, or Windows user and password values. Such credential values can be specified only in code. - - For more information about setting the client credential, see [How to: Specify Client Credential Values](how-to-specify-client-credential-values.md). - +> Some of the client credential values cannot be set using application configuration files, for example, user name and password, or Windows user and password values. Such credential values can be specified only in code. + + For more information about setting the client credential, see [How to: Specify Client Credential Values](how-to-specify-client-credential-values.md). + > [!NOTE] -> `ClientCredentialType` is ignored when `SecurityMode` is set to `"TransportWithMessageCredential"`, as shown in the following sample configuration. - -```xml - - - +> `ClientCredentialType` is ignored when `SecurityMode` is set to `"TransportWithMessageCredential"`, as shown in the following sample configuration. + +```xml + + + - - - - -``` - + negotiateServiceCredential="false" /> + + + + +``` + ## See also -- -- +- +- - -- -- +- +- - [\](../configure-apps/file-schema/wcf/bindings.md) - [Configuration Editor Tool (SvcConfigEditor.exe)](configuration-editor-tool-svcconfigeditor-exe.md) - [Securing Services](securing-services.md) diff --git a/docs/framework/wcf/securing-services.md b/docs/framework/wcf/securing-services.md index 3776315eb0245..9218b99b96b87 100644 --- a/docs/framework/wcf/securing-services.md +++ b/docs/framework/wcf/securing-services.md @@ -100,7 +100,7 @@ Security of a Windows Communication Foundation (WCF) service consists of two pri ## Identity - In WCF, the term *identity* has different meanings to the server and the client. In brief, when running a service, an identity is assigned to the security context after authentication. To view the actual identity, check the and properties of the class. For more information, see [How to: Examine the Security Context](how-to-examine-the-security-context.md). + In WCF, the term *identity* has different meanings to the server and the client. In brief, when running a service, an identity is assigned to the security context after authentication. To view the actual identity, check the and properties of the class. For more information, see [How to: Examine the Security Context](how-to-examine-the-security-context.md). In contrast, on the client, identity is used to validate the service. At design time, a client developer can set the [\](../configure-apps/file-schema/wcf/identity.md) element to a value obtained from the service. At runtime, the client checks the value of the element against the actual identity of the service. If the check fails, the client terminates the communication. The value can be a user principal name (UPN) if the service runs under a particular user's identity or a service principal name (SPN) if the service runs under a machine account. For more information, see [Service Identity and Authentication](./feature-details/service-identity-and-authentication.md). The credential could also be a certificate, or a field found on a certificate that identifies the certificate. diff --git a/docs/framework/wcf/sending-and-receiving-faults.md b/docs/framework/wcf/sending-and-receiving-faults.md index 93f213f0b2fa6..edad7feb96115 100644 --- a/docs/framework/wcf/sending-and-receiving-faults.md +++ b/docs/framework/wcf/sending-and-receiving-faults.md @@ -19,29 +19,29 @@ Declared SOAP faults are those in which an operation has a where the type parameter is a new object of the type specified in the for that operation. The following code example shows the use of to specify that the `SampleMethod` operation can return a SOAP fault with the detail type of `GreetingFault`. +To send a declared SOAP fault, detect the error condition for which the SOAP fault is appropriate and throw a new where the type parameter is a new object of the type specified in the for that operation. The following code example shows the use of to specify that the `SampleMethod` operation can return a SOAP fault with the detail type of `GreetingFault`. [!code-csharp[FaultContractAttribute#4](../../../samples/snippets/csharp/VS_Snippets_CFX/faultcontractattribute/cs/services.cs#4)] [!code-vb[FaultContractAttribute#4](../../../samples/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/services.vb#4)] -To convey the `GreetingFault` error information to the client, catch the appropriate error condition and throw a new of type `GreetingFault` with a new `GreetingFault` object as the argument, as in the following code example. If the client is an WCF client application, it experiences this as a managed exception where the type is of type `GreetingFault`. +To convey the `GreetingFault` error information to the client, catch the appropriate error condition and throw a new of type `GreetingFault` with a new `GreetingFault` object as the argument, as in the following code example. If the client is an WCF client application, it experiences this as a managed exception where the type is of type `GreetingFault`. [!code-csharp[FaultContractAttribute#5](../../../samples/snippets/csharp/VS_Snippets_CFX/faultcontractattribute/cs/services.cs#5)] [!code-vb[FaultContractAttribute#5](../../../samples/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/services.vb#5)] ### Sending Undeclared Faults -Sending undeclared faults can be very useful to quickly diagnose and debug problems in WCF applications, but its usefulness as a debugging tool is limited. More generally, when debugging it is recommended that you use the property. When you set this value to true, clients experience such faults as exceptions of type . +Sending undeclared faults can be very useful to quickly diagnose and debug problems in WCF applications, but its usefulness as a debugging tool is limited. More generally, when debugging it is recommended that you use the property. When you set this value to true, clients experience such faults as exceptions of type . > [!IMPORTANT] -> Because managed exceptions can expose internal application information, setting or to `true` can permit WCF clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information. +> Because managed exceptions can expose internal application information, setting or to `true` can permit WCF clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information. > -> Therefore, setting or to `true` is only recommended as a way of temporarily debugging a service application. In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the of type . Clients must expect the possibility of an unknown SOAP fault (returned to WCF clients as objects) to obtain the debugging information properly. +> Therefore, setting or to `true` is only recommended as a way of temporarily debugging a service application. In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the of type . Clients must expect the possibility of an unknown SOAP fault (returned to WCF clients as objects) to obtain the debugging information properly. -To send an undeclared SOAP fault, throw a object (that is, not the generic type ) and pass the string to the constructor. This is exposed to the WCF client applications as a thrown exception where the string is available by calling the method. +To send an undeclared SOAP fault, throw a object (that is, not the generic type ) and pass the string to the constructor. This is exposed to the WCF client applications as a thrown exception where the string is available by calling the method. > [!NOTE] -> If you declare a SOAP fault of type string, and then throw this in your service as a where the type parameter is a the string value is assigned to the property, and is not available from . +> If you declare a SOAP fault of type string, and then throw this in your service as a where the type parameter is a the string value is assigned to the property, and is not available from . ## Handling Faults @@ -55,23 +55,23 @@ In WCF clients, SOAP faults that occur during communication that are of interest objects are thrown when there is some recoverable communication error condition on either the service or the client. -The class has two important derived types, and the generic type. +The class has two important derived types, and the generic type. - exceptions are thrown when a listener receives a fault that is not expected or specified in the operation contract; usually this occurs when the application is being debugged and the service has the property set to `true`. + exceptions are thrown when a listener receives a fault that is not expected or specified in the operation contract; usually this occurs when the application is being debugged and the service has the property set to `true`. - exceptions are thrown on the client when a fault that is specified in the operation contract is received in response to a two-way operation (that is, a method with an attribute with set to `false`). + exceptions are thrown on the client when a fault that is specified in the operation contract is received in response to a two-way operation (that is, a method with an attribute with set to `false`). > [!NOTE] -> When an WCF service has the or property set to `true` the client experiences this as an undeclared of type . Clients can either catch this specific fault or handle the fault in a catch block for . +> When an WCF service has the or property set to `true` the client experiences this as an undeclared of type . Clients can either catch this specific fault or handle the fault in a catch block for . -Typically, only , , and exceptions are of interest to clients and services. +Typically, only , , and exceptions are of interest to clients and services. > [!NOTE] > Other exceptions, of course, do occur. Unexpected exceptions include catastrophic failures like ; typically applications should not catch such methods. ### Catch Fault Exceptions in the Correct Order -Because derives from , and derives from , it is important to catch these exceptions in the proper order. If, for example, you have a try/catch block in which you first catch , all specified and unspecified SOAP faults are handled there; any subsequent catch blocks to handle a custom exception are never invoked. +Because derives from , and derives from , it is important to catch these exceptions in the proper order. If, for example, you have a try/catch block in which you first catch , all specified and unspecified SOAP faults are handled there; any subsequent catch blocks to handle a custom exception are never invoked. Remember that one operation can return any number of specified faults. Each fault is a unique type and must be handled separately. @@ -85,9 +85,9 @@ Typically, client object channels are closed in one of the following ways: - When the WCF client object is recycled. -- When the client application calls . +- When the client application calls . -- When the client application calls . +- When the client application calls . - When the client application calls an operation that is a terminating operation for a session. @@ -110,7 +110,7 @@ The following code example shows how to handle SOAP fault exceptions in a basic ## See also - -- +- - - [Expected Exceptions](./samples/expected-exceptions.md) - [Use Close and Abort to release WCF client resources](./samples/use-close-abort-release-wcf-client-resources.md) diff --git a/docs/framework/wcf/service-versioning.md b/docs/framework/wcf/service-versioning.md index 27a477dc5cb77..ac2d2813a6920 100644 --- a/docs/framework/wcf/service-versioning.md +++ b/docs/framework/wcf/service-versioning.md @@ -6,204 +6,204 @@ ms.assetid: 37575ead-d820-4a67-8059-da11a2ab48e2 --- # Service Versioning -After initial deployment, and potentially several times during their lifetime, services (and the endpoints they expose) may need to be changed for a variety of reasons, such as changing business needs, information technology requirements, or to address other issues. Each change introduces a new version of the service. This topic explains how to consider versioning in Windows Communication Foundation (WCF). - -## Four Categories of Service Changes - - The changes to services that may be required can be classified into four categories: - -- Contract changes: For example, an operation might be added, or a data element in a message might be added or changed. - -- Address changes: For example, a service moves to a different location where endpoints have new addresses. - -- Binding changes: For example, a security mechanism changes or its settings change. - -- Implementation changes: For example, when an internal method implementation changes. - - Some of these changes are called "breaking" and others are "nonbreaking." A change is *nonbreaking* if all messages that would have been processed successfully in the previous version are processed successfully in the new version. Any change that does not meet that criterion is a *breaking* change. - -## Service Orientation and Versioning - - One of the tenets of service orientation is that services and clients are autonomous (or independent). Among other things, this implies that service developers cannot assume that they control or even know about all service clients. This eliminates the option of rebuilding and redeploying all clients when a service changes versions. This topic assumes the service adheres to this tenet and therefore must be changed or "versioned" independent of its clients. - - In cases where a breaking change is unexpected and cannot be avoided, an application may choose to ignore this tenet and require that clients be rebuilt and redeployed with a new version of the service. - -## Contract Versioning - - Contracts used by a client do not need to be the same as the contract used by the service; they need only to be compatible. - - For service contracts, compatibility means new operations exposed by the service can be added but existing operations cannot be removed or changed semantically. - - For data contracts, compatibility means new schema type definitions can be added but existing schema type definitions cannot be changed in breaking ways. Breaking changes might include removing data members or changing their data type incompatibly. This feature allows the service some latitude in changing the version of its contracts without breaking clients. The next two sections explain nonbreaking and breaking changes that can be made to WCF data and service contracts. - -## Data Contract Versioning - - This section deals with data versioning when using the and classes. - -### Strict Versioning - - In many scenarios when changing versions is an issue, the service developer does not have control over the clients and therefore cannot make assumptions about how they would react to changes in the message XML or schema. In these cases, you must guarantee that the new messages will validate against the old schema, for two reasons: - -- The old clients were developed with the assumption that the schema will not change. They may fail to process messages that they were never designed for. - -- The old clients may perform actual schema validation against the old schema before even attempting to process the messages. - - The recommended approach in such scenarios is to treat existing data contracts as immutable and create new ones with unique XML qualified names. The service developer would then either add new methods to an existing service contract or create a new service contract with methods that use the new data contract. - - It will often be the case that a service developer needs to write some business logic that should run within all versions of a data contract plus version-specific business code for each version of the data contract. The appendix at the end of this topic explains how interfaces can be used to satisfy this need. - -### Lax Versioning - - In many other scenarios, the service developer can make the assumption that adding a new, optional member to the data contract will not break existing clients. This requires the service developer to investigate whether existing clients are not performing schema validation and that they ignore unknown data members. In these scenarios, it is possible to take advantage of data contract features for adding new members in a nonbreaking way. The service developer can make this assumption with confidence if the data contract features for versioning were already used for the first version of the service. - - WCF, ASP.NET Web Services, and many other Web service stacks support *lax versioning*: that is, they do not throw exceptions for new unknown data members in received data. - - It is easy to mistakenly believe that adding a new member will not break existing clients. If you are unsure that all clients can handle lax versioning, the recommendation is to use the strict versioning guidelines and treat data contracts as immutable. - - For detailed guidelines for both lax and strict versioning of data contracts, see [Best Practices: Data Contract Versioning](best-practices-data-contract-versioning.md). - -### Distinguishing Between Data Contract and .NET Types - - A .NET class or structure can be projected as a data contract by applying the attribute to the class. The .NET type and its data contract projections are two distinct matters. It is possible to have multiple .NET types with the same data contract projection. This distinction is especially useful in allowing you to change the .NET type while maintaining the projected data contract, thereby maintaining compatibility with existing clients even in the strict sense of the word. There are two things you should always do to maintain this distinction between .NET type and data contract: - -- Specify a and . You should always specify the name and namespace of your data contract to prevent your .NET type's name and namespace from being exposed in the contract. This way, if you decide later to change the .NET namespace or type name, your data contract remains the same. - -- Specify . You should always specify the name of your data members to prevent your .NET member name from being exposed in the contract. This way, if you decide later to change the .NET name of the member, your data contract remains the same. - -### Changing or Removing Members - - Changing the name or data type of a member, or removing data members is a breaking change even if lax versioning is allowed. If this is necessary, create a new data contract. - - If service compatibility is of high importance, you might consider ignoring unused data members in your code and leave them in place. If you are splitting up a data member into multiple members, you might consider leaving the existing member in place as a property that can perform the required splitting and re-aggregation for down-level clients (clients that are not upgraded to the latest version). - - Similarly, changes to the data contract's name or namespace are breaking changes. - -### Round-Trips of Unknown Data - - In some scenarios, there is a need to "round-trip" unknown data that comes from members added in a new version. For example, a "versionNew" service sends data with some newly added members to a "versionOld" client. The client ignores the newly added members when processing the message, but it resends that same data, including the newly added members, back to the versionNew service. The typical scenario for this is data updates where data is retrieved from the service, changed, and returned. - - To enable round-tripping for a particular type, the type must implement the interface. The interface contains one property, that returns the type. The property is used to store any data from future versions of the data contract that is unknown to the current version. This data is opaque to the client, but when the instance is serialized, the content of the property is written with the rest of the data contract members' data. - - It is recommended that all your types implement this interface to accommodate new and unknown future members. - -### Data Contract Libraries - - There may be libraries of data contracts where a contract is published to a central repository, and service and type implementers implement and expose data contracts from that repository. In that case, when you publish a data contract to the repository, you have no control over who creates types that implement it. Thus, you cannot modify the contract once it is published, rendering it effectively immutable. - -### When Using the XmlSerializer - - The same versioning principles apply when using the class. When strict versioning is required, treat data contracts as immutable and create new data contracts with unique, qualified names for the new versions. When you are sure that lax versioning can be used, you can add new serializable members in new versions but not change or remove existing members. - +After initial deployment, and potentially several times during their lifetime, services (and the endpoints they expose) may need to be changed for a variety of reasons, such as changing business needs, information technology requirements, or to address other issues. Each change introduces a new version of the service. This topic explains how to consider versioning in Windows Communication Foundation (WCF). + +## Four Categories of Service Changes + + The changes to services that may be required can be classified into four categories: + +- Contract changes: For example, an operation might be added, or a data element in a message might be added or changed. + +- Address changes: For example, a service moves to a different location where endpoints have new addresses. + +- Binding changes: For example, a security mechanism changes or its settings change. + +- Implementation changes: For example, when an internal method implementation changes. + + Some of these changes are called "breaking" and others are "nonbreaking." A change is *nonbreaking* if all messages that would have been processed successfully in the previous version are processed successfully in the new version. Any change that does not meet that criterion is a *breaking* change. + +## Service Orientation and Versioning + + One of the tenets of service orientation is that services and clients are autonomous (or independent). Among other things, this implies that service developers cannot assume that they control or even know about all service clients. This eliminates the option of rebuilding and redeploying all clients when a service changes versions. This topic assumes the service adheres to this tenet and therefore must be changed or "versioned" independent of its clients. + + In cases where a breaking change is unexpected and cannot be avoided, an application may choose to ignore this tenet and require that clients be rebuilt and redeployed with a new version of the service. + +## Contract Versioning + + Contracts used by a client do not need to be the same as the contract used by the service; they need only to be compatible. + + For service contracts, compatibility means new operations exposed by the service can be added but existing operations cannot be removed or changed semantically. + + For data contracts, compatibility means new schema type definitions can be added but existing schema type definitions cannot be changed in breaking ways. Breaking changes might include removing data members or changing their data type incompatibly. This feature allows the service some latitude in changing the version of its contracts without breaking clients. The next two sections explain nonbreaking and breaking changes that can be made to WCF data and service contracts. + +## Data Contract Versioning + + This section deals with data versioning when using the and classes. + +### Strict Versioning + + In many scenarios when changing versions is an issue, the service developer does not have control over the clients and therefore cannot make assumptions about how they would react to changes in the message XML or schema. In these cases, you must guarantee that the new messages will validate against the old schema, for two reasons: + +- The old clients were developed with the assumption that the schema will not change. They may fail to process messages that they were never designed for. + +- The old clients may perform actual schema validation against the old schema before even attempting to process the messages. + + The recommended approach in such scenarios is to treat existing data contracts as immutable and create new ones with unique XML qualified names. The service developer would then either add new methods to an existing service contract or create a new service contract with methods that use the new data contract. + + It will often be the case that a service developer needs to write some business logic that should run within all versions of a data contract plus version-specific business code for each version of the data contract. The appendix at the end of this topic explains how interfaces can be used to satisfy this need. + +### Lax Versioning + + In many other scenarios, the service developer can make the assumption that adding a new, optional member to the data contract will not break existing clients. This requires the service developer to investigate whether existing clients are not performing schema validation and that they ignore unknown data members. In these scenarios, it is possible to take advantage of data contract features for adding new members in a nonbreaking way. The service developer can make this assumption with confidence if the data contract features for versioning were already used for the first version of the service. + + WCF, ASP.NET Web Services, and many other Web service stacks support *lax versioning*: that is, they do not throw exceptions for new unknown data members in received data. + + It is easy to mistakenly believe that adding a new member will not break existing clients. If you are unsure that all clients can handle lax versioning, the recommendation is to use the strict versioning guidelines and treat data contracts as immutable. + + For detailed guidelines for both lax and strict versioning of data contracts, see [Best Practices: Data Contract Versioning](best-practices-data-contract-versioning.md). + +### Distinguishing Between Data Contract and .NET Types + + A .NET class or structure can be projected as a data contract by applying the attribute to the class. The .NET type and its data contract projections are two distinct matters. It is possible to have multiple .NET types with the same data contract projection. This distinction is especially useful in allowing you to change the .NET type while maintaining the projected data contract, thereby maintaining compatibility with existing clients even in the strict sense of the word. There are two things you should always do to maintain this distinction between .NET type and data contract: + +- Specify a and . You should always specify the name and namespace of your data contract to prevent your .NET type's name and namespace from being exposed in the contract. This way, if you decide later to change the .NET namespace or type name, your data contract remains the same. + +- Specify . You should always specify the name of your data members to prevent your .NET member name from being exposed in the contract. This way, if you decide later to change the .NET name of the member, your data contract remains the same. + +### Changing or Removing Members + + Changing the name or data type of a member, or removing data members is a breaking change even if lax versioning is allowed. If this is necessary, create a new data contract. + + If service compatibility is of high importance, you might consider ignoring unused data members in your code and leave them in place. If you are splitting up a data member into multiple members, you might consider leaving the existing member in place as a property that can perform the required splitting and re-aggregation for down-level clients (clients that are not upgraded to the latest version). + + Similarly, changes to the data contract's name or namespace are breaking changes. + +### Round-Trips of Unknown Data + + In some scenarios, there is a need to "round-trip" unknown data that comes from members added in a new version. For example, a "versionNew" service sends data with some newly added members to a "versionOld" client. The client ignores the newly added members when processing the message, but it resends that same data, including the newly added members, back to the versionNew service. The typical scenario for this is data updates where data is retrieved from the service, changed, and returned. + + To enable round-tripping for a particular type, the type must implement the interface. The interface contains one property, that returns the type. The property is used to store any data from future versions of the data contract that is unknown to the current version. This data is opaque to the client, but when the instance is serialized, the content of the property is written with the rest of the data contract members' data. + + It is recommended that all your types implement this interface to accommodate new and unknown future members. + +### Data Contract Libraries + + There may be libraries of data contracts where a contract is published to a central repository, and service and type implementers implement and expose data contracts from that repository. In that case, when you publish a data contract to the repository, you have no control over who creates types that implement it. Thus, you cannot modify the contract once it is published, rendering it effectively immutable. + +### When Using the XmlSerializer + + The same versioning principles apply when using the class. When strict versioning is required, treat data contracts as immutable and create new data contracts with unique, qualified names for the new versions. When you are sure that lax versioning can be used, you can add new serializable members in new versions but not change or remove existing members. + > [!NOTE] -> The uses the and attributes to support round-tripping of unknown data. - -## Message Contract Versioning - - The guidelines for message contract versioning are very similar to versioning data contracts. If strict versioning is required, you should not change your message body but instead create a new message contract with a unique qualified name. If you know that you can use lax versioning, you can add new message body parts but not change or remove existing ones. This guidance applies both to bare and wrapped message contracts. - - Message headers can always be added, even if strict versioning is in use. The MustUnderstand flag may affect versioning. In general, the versioning model for headers in WCF is as described in the SOAP specification. - -## Service Contract Versioning - - Similar to data contract versioning, service contract versioning also involves adding, changing, and removing operations. - -### Specifying Name, Namespace, and Action - - By default, the name of a service contract is the name of the interface. Its default namespace is `http://tempuri.org`, and each operation's action is `http://tempuri.org/contractname/methodname`. It is recommended that you explicitly specify a name and namespace for the service contract, and an action for each operation to avoid using `http://tempuri.org` and to prevent interface and method names from being exposed in the service's contract. - -### Adding Parameters and Operations - - Adding service operations exposed by the service is a nonbreaking change because existing clients need not be concerned about those new operations. - +> The uses the and attributes to support round-tripping of unknown data. + +## Message Contract Versioning + + The guidelines for message contract versioning are very similar to versioning data contracts. If strict versioning is required, you should not change your message body but instead create a new message contract with a unique qualified name. If you know that you can use lax versioning, you can add new message body parts but not change or remove existing ones. This guidance applies both to bare and wrapped message contracts. + + Message headers can always be added, even if strict versioning is in use. The MustUnderstand flag may affect versioning. In general, the versioning model for headers in WCF is as described in the SOAP specification. + +## Service Contract Versioning + + Similar to data contract versioning, service contract versioning also involves adding, changing, and removing operations. + +### Specifying Name, Namespace, and Action + + By default, the name of a service contract is the name of the interface. Its default namespace is `http://tempuri.org`, and each operation's action is `http://tempuri.org/contractname/methodname`. It is recommended that you explicitly specify a name and namespace for the service contract, and an action for each operation to avoid using `http://tempuri.org` and to prevent interface and method names from being exposed in the service's contract. + +### Adding Parameters and Operations + + Adding service operations exposed by the service is a nonbreaking change because existing clients need not be concerned about those new operations. + > [!NOTE] -> Adding operations to a duplex callback contract is a breaking change. - -### Changing Operation Parameter or Return Types - - Changing parameter or return types generally is a breaking change unless the new type implements the same data contract implemented by the old type. To make such a change, add a new operation to the service contract or define a new service contract. - -### Removing Operations - - Removing operations is also a breaking change. To make such a change, define a new service contract and expose it on a new endpoint. - -### Fault Contracts - - The attribute enables a service contract developer to specify information about faults that can be returned from the contract's operations. - - The list of faults described in a service's contract is not considered exhaustive. At any time, an operation may return faults that are not described in its contract. Therefore changing the set of faults described in the contract is not considered breaking. For example, adding a new fault to the contract using the or removing an existing fault from the contract. - -### Service Contract Libraries - - Organizations may have libraries of contracts where a contract is published to a central repository and service implementers implement contracts from that repository. In this case, when you publish a service contract to the repository you have no control over who creates services that implement it. Therefore, you cannot modify the service contract once published, rendering it effectively immutable. WCF supports contract inheritance, which can be used to create a new contract that extends existing contracts. To use this feature, define a new service contract interface that inherits from the old service contract interface, then add methods to the new interface. You then change the service that implements the old contract to implement the new contract and change the "versionOld" endpoint definition to use the new contract. To "versionOld" clients, the endpoint will continue to appear as exposing the "versionOld" contract; to "versionNew" clients, the endpoint will appear to expose the "versionNew" contract. - -## Address and Binding Versioning - - Changes to endpoint address and binding are breaking changes unless clients are capable of dynamically discovering the new endpoint address or binding. One mechanism for implementing this capability is by using a Universal Discovery Description and Integration (UDDI) registry and the UDDI Invocation Pattern where a client attempts to communicate with an endpoint and, upon failure, queries a well-known UDDI registry for the current endpoint metadata. The client then uses the address and binding from this metadata to communicate with the endpoint. If this communication succeeds, the client caches the address and binding information for future use. - -## Routing Service and Versioning - - If the changes made to a service are breaking changes and you need to have two or more different versions of a service running simultaneously you can use the WCF Routing Service to route messages to the appropriate service instance. The WCF Routing Service uses content-based routing, in other words, it uses information within the message to determine where to route the message. For more information about the WCF Routing Service see [Routing Service](./feature-details/routing-service.md). For an example of how to use the WCF Routing Service for service versioning see [How To: Service Versioning](./feature-details/how-to-service-versioning.md). - -## Appendix - - The general data contract versioning guidance when strict versioning is needed is to treat data contracts as immutable and create new ones when changes are required. A new class needs to be created for each new data contract, so a mechanism is needed to avoid having to take existing code that was written in terms of the old data contract class and rewrite it in terms of the new data contract class. - - One such mechanism is to use interfaces to define the members of each data contract and write internal implementation code in terms of the interfaces rather than the data contract classes that implement the interfaces. The following code for version 1 of a service shows an `IPurchaseOrderV1` interface and a `PurchaseOrderV1`: - -```csharp -public interface IPurchaseOrderV1 -{ - string OrderId { get; set; } - string CustomerId { get; set; } -} - -[DataContract( -Name = "PurchaseOrder", -Namespace = "http://examples.microsoft.com/WCF/2005/10/PurchaseOrder")] -public class PurchaseOrderV1 : IPurchaseOrderV1 -{ - [DataMember(...)] - public string OrderId {...} - [DataMember(...)] - public string CustomerId {...} -} -``` - - While the service contract's operations would be written in terms of `PurchaseOrderV1`, the actual business logic would be in terms of `IPurchaseOrderV1`. Then, in version 2, there would be a new `IPurchaseOrderV2` interface and a new `PurchaseOrderV2` class as shown in the following code: - +> Adding operations to a duplex callback contract is a breaking change. + +### Changing Operation Parameter or Return Types + + Changing parameter or return types generally is a breaking change unless the new type implements the same data contract implemented by the old type. To make such a change, add a new operation to the service contract or define a new service contract. + +### Removing Operations + + Removing operations is also a breaking change. To make such a change, define a new service contract and expose it on a new endpoint. + +### Fault Contracts + + The attribute enables a service contract developer to specify information about faults that can be returned from the contract's operations. + + The list of faults described in a service's contract is not considered exhaustive. At any time, an operation may return faults that are not described in its contract. Therefore changing the set of faults described in the contract is not considered breaking. For example, adding a new fault to the contract using the or removing an existing fault from the contract. + +### Service Contract Libraries + + Organizations may have libraries of contracts where a contract is published to a central repository and service implementers implement contracts from that repository. In this case, when you publish a service contract to the repository you have no control over who creates services that implement it. Therefore, you cannot modify the service contract once published, rendering it effectively immutable. WCF supports contract inheritance, which can be used to create a new contract that extends existing contracts. To use this feature, define a new service contract interface that inherits from the old service contract interface, then add methods to the new interface. You then change the service that implements the old contract to implement the new contract and change the "versionOld" endpoint definition to use the new contract. To "versionOld" clients, the endpoint will continue to appear as exposing the "versionOld" contract; to "versionNew" clients, the endpoint will appear to expose the "versionNew" contract. + +## Address and Binding Versioning + + Changes to endpoint address and binding are breaking changes unless clients are capable of dynamically discovering the new endpoint address or binding. One mechanism for implementing this capability is by using a Universal Discovery Description and Integration (UDDI) registry and the UDDI Invocation Pattern where a client attempts to communicate with an endpoint and, upon failure, queries a well-known UDDI registry for the current endpoint metadata. The client then uses the address and binding from this metadata to communicate with the endpoint. If this communication succeeds, the client caches the address and binding information for future use. + +## Routing Service and Versioning + + If the changes made to a service are breaking changes and you need to have two or more different versions of a service running simultaneously you can use the WCF Routing Service to route messages to the appropriate service instance. The WCF Routing Service uses content-based routing, in other words, it uses information within the message to determine where to route the message. For more information about the WCF Routing Service see [Routing Service](./feature-details/routing-service.md). For an example of how to use the WCF Routing Service for service versioning see [How To: Service Versioning](./feature-details/how-to-service-versioning.md). + +## Appendix + + The general data contract versioning guidance when strict versioning is needed is to treat data contracts as immutable and create new ones when changes are required. A new class needs to be created for each new data contract, so a mechanism is needed to avoid having to take existing code that was written in terms of the old data contract class and rewrite it in terms of the new data contract class. + + One such mechanism is to use interfaces to define the members of each data contract and write internal implementation code in terms of the interfaces rather than the data contract classes that implement the interfaces. The following code for version 1 of a service shows an `IPurchaseOrderV1` interface and a `PurchaseOrderV1`: + ```csharp -public interface IPurchaseOrderV2 -{ - DateTime OrderDate { get; set; } +public interface IPurchaseOrderV1 +{ + string OrderId { get; set; } + string CustomerId { get; set; } } [DataContract( -Name = "PurchaseOrder", -Namespace = "http://examples.microsoft.com/WCF/2006/02/PurchaseOrder")] -public class PurchaseOrderV2 : IPurchaseOrderV1, IPurchaseOrderV2 -{ - [DataMember(...)] - public string OrderId {...} - [DataMember(...)] - public string CustomerId {...} - [DataMember(...)] - public DateTime OrderDate { ... } -} -``` - - The service contract would be updated to include new operations that are written in terms of `PurchaseOrderV2`. Existing business logic written in terms of `IPurchaseOrderV1` would continue to work for `PurchaseOrderV2` and new business logic that needs the `OrderDate` property would be written in terms of `IPurchaseOrderV2`. - +Name = "PurchaseOrder", +Namespace = "http://examples.microsoft.com/WCF/2005/10/PurchaseOrder")] +public class PurchaseOrderV1 : IPurchaseOrderV1 +{ + [DataMember(...)] + public string OrderId {...} + [DataMember(...)] + public string CustomerId {...} +} +``` + + While the service contract's operations would be written in terms of `PurchaseOrderV1`, the actual business logic would be in terms of `IPurchaseOrderV1`. Then, in version 2, there would be a new `IPurchaseOrderV2` interface and a new `PurchaseOrderV2` class as shown in the following code: + +```csharp +public interface IPurchaseOrderV2 +{ + DateTime OrderDate { get; set; } +} + +[DataContract( +Name = "PurchaseOrder", +Namespace = "http://examples.microsoft.com/WCF/2006/02/PurchaseOrder")] +public class PurchaseOrderV2 : IPurchaseOrderV1, IPurchaseOrderV2 +{ + [DataMember(...)] + public string OrderId {...} + [DataMember(...)] + public string CustomerId {...} + [DataMember(...)] + public DateTime OrderDate { ... } +} +``` + + The service contract would be updated to include new operations that are written in terms of `PurchaseOrderV2`. Existing business logic written in terms of `IPurchaseOrderV1` would continue to work for `PurchaseOrderV2` and new business logic that needs the `OrderDate` property would be written in terms of `IPurchaseOrderV2`. + ## See also - - -- -- -- +- +- +- - - - -- +- - - [Data Contract Equivalence](./feature-details/data-contract-equivalence.md) - [Version-Tolerant Serialization Callbacks](./feature-details/version-tolerant-serialization-callbacks.md) diff --git a/docs/framework/wcf/services-and-transactions.md b/docs/framework/wcf/services-and-transactions.md index 472c80261474c..e3b99f69e78dd 100644 --- a/docs/framework/wcf/services-and-transactions.md +++ b/docs/framework/wcf/services-and-transactions.md @@ -2,88 +2,88 @@ description: "Learn more about: Services and Transactions" title: "Services and Transactions" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "service contracts [WCF], designing services and transactions" ms.assetid: 864813ff-2709-4376-912d-f5c8d318c460 --- # Services and Transactions -Windows Communication Foundation (WCF) applications can initiate a transaction from within a client and coordinate the transaction within the service operation. Clients can initiate a transaction and invoke several service operations and ensure that the service operations are either committed or rolled back as a single unit. - - You can enable the transaction behavior in the service contract by specifying a and setting its and properties for service operations that require client transactions. The parameter specifies whether the transaction in which the method executes is automatically completed if no unhandled exceptions are thrown. For more information about these attributes, see [ServiceModel Transaction Attributes](./feature-details/servicemodel-transaction-attributes.md). - - The work that is performed in the service operations and managed by a resource manager, such as logging database updates, is part of the client’s transaction. - - The following sample demonstrates usage of the and attributes to control service-side transaction behavior. - +Windows Communication Foundation (WCF) applications can initiate a transaction from within a client and coordinate the transaction within the service operation. Clients can initiate a transaction and invoke several service operations and ensure that the service operations are either committed or rolled back as a single unit. + + You can enable the transaction behavior in the service contract by specifying a and setting its and properties for service operations that require client transactions. The parameter specifies whether the transaction in which the method executes is automatically completed if no unhandled exceptions are thrown. For more information about these attributes, see [ServiceModel Transaction Attributes](./feature-details/servicemodel-transaction-attributes.md). + + The work that is performed in the service operations and managed by a resource manager, such as logging database updates, is part of the client’s transaction. + + The following sample demonstrates usage of the and attributes to control service-side transaction behavior. + ```csharp -[ServiceBehavior(TransactionIsolationLevel = System.Transactions.IsolationLevel.Serializable)] -public class CalculatorService: ICalculatorLog -{ - [OperationBehavior(TransactionScopeRequired = true, - TransactionAutoComplete = true)] - public double Add(double n1, double n2) - { +[ServiceBehavior(TransactionIsolationLevel = System.Transactions.IsolationLevel.Serializable)] +public class CalculatorService: ICalculatorLog +{ + [OperationBehavior(TransactionScopeRequired = true, + TransactionAutoComplete = true)] + public double Add(double n1, double n2) + { recordToLog($"Added {n1} to {n2}"); - return n1 + n2; - } - + return n1 + n2; + } + [OperationBehavior(TransactionScopeRequired = true, - TransactionAutoComplete = true)] - public double Subtract(double n1, double n2) - { + TransactionAutoComplete = true)] + public double Subtract(double n1, double n2) + { recordToLog($"Subtracted {n1} from {n2}"); - return n1 - n2; - } - + return n1 - n2; + } + [OperationBehavior(TransactionScopeRequired = true, - TransactionAutoComplete = true)] - public double Multiply(double n1, double n2) - { + TransactionAutoComplete = true)] + public double Multiply(double n1, double n2) + { recordToLog($"Multiplied {n1} by {n2}"); - return n1 * n2; - } - + return n1 * n2; + } + [OperationBehavior(TransactionScopeRequired = true, - TransactionAutoComplete = true)] - public double Divide(double n1, double n2) - { + TransactionAutoComplete = true)] + public double Divide(double n1, double n2) + { recordToLog($"Divided {n1} by {n2}", n1, n2); - return n1 / n2; - } - -} -``` - - You can enable transactions and transaction flow by configuring the client and service bindings to use the WS-AtomicTransaction protocol, and setting the [\](../configure-apps/file-schema/wcf/transactionflow.md) element to `true`, as shown in the following sample configuration. - -```xml - + return n1 / n2; + } + +} +``` + + You can enable transactions and transaction flow by configuring the client and service bindings to use the WS-AtomicTransaction protocol, and setting the [\](../configure-apps/file-schema/wcf/transactionflow.md) element to `true`, as shown in the following sample configuration. + +```xml + - - - - - - - -``` - - Clients can begin a transaction by creating a and invoking service operations within the scope of the transaction. - + contract="Microsoft.ServiceModel.Samples.ICalculatorLog" /> + + + + + + + +``` + + Clients can begin a transaction by creating a and invoking service operations within the scope of the transaction. + ```csharp -using (TransactionScope ts = new TransactionScope(TransactionScopeOption.RequiresNew)) -{ - //Do work here - ts.Complete(); -} -``` - +using (TransactionScope ts = new TransactionScope(TransactionScopeOption.RequiresNew)) +{ + //Do work here + ts.Complete(); +} +``` + ## See also - [Transactional Support in System.ServiceModel](./feature-details/transactional-support-in-system-servicemodel.md) diff --git a/docs/framework/wcf/specifying-an-endpoint-address.md b/docs/framework/wcf/specifying-an-endpoint-address.md index 64faf43d1dc44..2a59b1954f572 100644 --- a/docs/framework/wcf/specifying-an-endpoint-address.md +++ b/docs/framework/wcf/specifying-an-endpoint-address.md @@ -11,7 +11,7 @@ ms.assetid: ac24f5ad-9558-4298-b168-c473c68e819b --- # Specifying an Endpoint Address -All communication with a Windows Communication Foundation (WCF) service occurs through its endpoints. Each contains an , a , and a . The contract specifies which operations are available. The binding specifies how to communicate with the service, and the address specifies where to find the service. Every endpoint must have a unique address. The endpoint address is represented by the class, which contains a Uniform Resource Identifier (URI) that represents the address of the service, an , which represents the security identity of the service, and a collection of optional . The optional headers provide more detailed addressing information to identify or interact with the endpoint. For example, headers can indicate how to process an incoming message, where the endpoint should send a reply message, or which instance of a service to use to process an incoming message from a particular user when multiple instances are available. +All communication with a Windows Communication Foundation (WCF) service occurs through its endpoints. Each contains an , a , and a . The contract specifies which operations are available. The binding specifies how to communicate with the service, and the address specifies where to find the service. Every endpoint must have a unique address. The endpoint address is represented by the class, which contains a Uniform Resource Identifier (URI) that represents the address of the service, an , which represents the security identity of the service, and a collection of optional . The optional headers provide more detailed addressing information to identify or interact with the endpoint. For example, headers can indicate how to process an incoming message, where the endpoint should send a reply message, or which instance of a service to use to process an incoming message from a particular user when multiple instances are available. ## Definition of an Endpoint Address @@ -41,7 +41,7 @@ To define an endpoint in a configuration file, use the [\](../configur [!code-xml[S_UEHelloWorld#5](./snippets/specifying-an-endpoint-address/serviceapp2.config#5)] -When the method is called (that is, when the hosting application attempts to start the service), the system looks for a [\](../configure-apps/file-schema/wcf/service.md) element with a name attribute that specifies "UE.Samples.HelloService". If the [\](../configure-apps/file-schema/wcf/service.md) element is found, the system loads the specified class and creates endpoints using the endpoint definitions provided in the configuration file. This mechanism allows you to load and start a service with two lines of code while keeping binding and addressing information out of your code. The advantage of this approach is that these changes can be made without having to recompile or redeploy the application. +When the method is called (that is, when the hosting application attempts to start the service), the system looks for a [\](../configure-apps/file-schema/wcf/service.md) element with a name attribute that specifies "UE.Samples.HelloService". If the [\](../configure-apps/file-schema/wcf/service.md) element is found, the system loads the specified class and creates endpoints using the endpoint definitions provided in the configuration file. This mechanism allows you to load and start a service with two lines of code while keeping binding and addressing information out of your code. The advantage of this approach is that these changes can be made without having to recompile or redeploy the application. The optional headers are declared in a [\](../configure-apps/file-schema/wcf/headers-element.md). The following is an example of the elements used to specify endpoints for a service in a configuration file that distinguishes between two headers: "Gold" clients from `http://tempuri1.org/` and "Standard" clients from `http://tempuri2.org/`. The client calling this service must have the appropriate [\](../configure-apps/file-schema/wcf/headers-element.md) in its configuration file. @@ -69,17 +69,17 @@ The following example demonstrates how to add a relative address ("MyService") t [!code-csharp[S_UEHelloWorld#3](../../../samples/snippets/csharp/VS_Snippets_CFX/s_uehelloworld/cs/snippet.cs#3)] > [!NOTE] -> Properties of the in the service application must not be modified subsequent to the method on . Some members, such as the property and the `AddServiceEndpoint` methods on and , throw an exception if modified after that point. Others permit you to modify them, but the result is undefined. +> Properties of the in the service application must not be modified subsequent to the method on . Some members, such as the property and the `AddServiceEndpoint` methods on and , throw an exception if modified after that point. Others permit you to modify them, but the result is undefined. > -> Similarly, on the client the values must not be modified after the call to on the . The property throws an exception if modified after that point. The other client description values can be modified without error, but the result is undefined. +> Similarly, on the client the values must not be modified after the call to on the . The property throws an exception if modified after that point. The other client description values can be modified without error, but the result is undefined. > -> Whether for the service or client, it is recommended that you modify the description prior to calling . +> Whether for the service or client, it is recommended that you modify the description prior to calling . ## Using Default Endpoints -If no endpoints are specified in code or in configuration then the runtime provides default endpoints by adding one default endpoint on each base address for each service contract implemented by the service. The base address can be specified in code or in configuration, and the default endpoints are added when is called on the . +If no endpoints are specified in code or in configuration then the runtime provides default endpoints by adding one default endpoint on each base address for each service contract implemented by the service. The base address can be specified in code or in configuration, and the default endpoints are added when is called on the . -If endpoints are explicitly provided, the default endpoints can still be added by calling on the before calling . For more information about default endpoints, bindings, and behaviors, see [Simplified Configuration](simplified-configuration.md) and [Simplified Configuration for WCF Services](./samples/simplified-configuration-for-wcf-services.md). +If endpoints are explicitly provided, the default endpoints can still be added by calling on the before calling . For more information about default endpoints, bindings, and behaviors, see [Simplified Configuration](simplified-configuration.md) and [Simplified Configuration for WCF Services](./samples/simplified-configuration-for-wcf-services.md). ## See also diff --git a/docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md b/docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md index e5e321599e369..9d4f2d1a825e3 100644 --- a/docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md +++ b/docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md @@ -42,12 +42,12 @@ For more information, see [Sending and Receiving Faults](sending-and-receiving-f ## Undeclared SOAP Faults and Debugging -Declared SOAP faults are extremely useful for building robust, interoperable, distributed applications. However, in some cases it is useful for a service (or duplex client) to send an undeclared SOAP fault, one that is not mentioned in the Web Services Description Language (WSDL) for that operation. For example, when developing a service, unexpected situations can occur in which it is useful for debugging purposes to send information back to the client. In addition, you can set the property or the property to `true` to permit WCF clients to obtain information about internal service operation exceptions. Both sending individual faults and setting the debugging behavior properties are described in [Sending and Receiving Faults](sending-and-receiving-faults.md). +Declared SOAP faults are extremely useful for building robust, interoperable, distributed applications. However, in some cases it is useful for a service (or duplex client) to send an undeclared SOAP fault, one that is not mentioned in the Web Services Description Language (WSDL) for that operation. For example, when developing a service, unexpected situations can occur in which it is useful for debugging purposes to send information back to the client. In addition, you can set the property or the property to `true` to permit WCF clients to obtain information about internal service operation exceptions. Both sending individual faults and setting the debugging behavior properties are described in [Sending and Receiving Faults](sending-and-receiving-faults.md). > [!IMPORTANT] -> Because managed exceptions can expose internal application information, setting or to `true` can permit WCF clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information. +> Because managed exceptions can expose internal application information, setting or to `true` can permit WCF clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information. > -> Therefore, setting or to `true` is recommended only as a way to temporarily debug a service application. In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the of type . Clients must expect the possibility of an unknown SOAP fault (returned to WCF clients as objects) to obtain the debugging information properly. +> Therefore, setting or to `true` is recommended only as a way to temporarily debug a service application. In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the of type . Clients must expect the possibility of an unknown SOAP fault (returned to WCF clients as objects) to obtain the debugging information properly. ## Customizing Error Handling with IErrorHandler @@ -66,9 +66,9 @@ When deserializing a fault contract, WCF first attempts to match the fault contr - - - -- -- -- -- +- +- +- +- - - [Defining and Specifying Faults](defining-and-specifying-faults.md) diff --git a/docs/framework/wcf/specifying-client-run-time-behavior.md b/docs/framework/wcf/specifying-client-run-time-behavior.md index 118ab500770cf..b180df940e6f0 100644 --- a/docs/framework/wcf/specifying-client-run-time-behavior.md +++ b/docs/framework/wcf/specifying-client-run-time-behavior.md @@ -17,20 +17,20 @@ Windows Communication Foundation (WCF) clients, like Windows Communication Found You can configure or extend the execution behavior of a callback contract implementation in a client application by using the class. This attribute performs a similar function for the callback class as the class, with the exception of instancing behavior and transaction settings. - The class must be applied to the class that implements the callback contract. If applied to a nonduplex contract implementation, an exception is thrown at runtime. The following code example shows a class on a callback object that uses the object to determine the thread to marshal to, the property to enforce message validation, and the property to return exceptions as objects to the service for debugging purposes. + The class must be applied to the class that implements the callback contract. If applied to a nonduplex contract implementation, an exception is thrown at runtime. The following code example shows a class on a callback object that uses the object to determine the thread to marshal to, the property to enforce message validation, and the property to return exceptions as objects to the service for debugging purposes. [!code-csharp[CallbackBehaviorAttribute#3](../../../samples/snippets/csharp/VS_Snippets_CFX/callbackbehaviorattribute/cs/client.cs#3)] [!code-vb[CallbackBehaviorAttribute#3](../../../samples/snippets/visualbasic/VS_Snippets_CFX/callbackbehaviorattribute/vb/client.vb#3)] ## Using CallbackDebugBehavior to Enable the Flow of Managed Exception Information - You can enable the flow of managed exception information in a client callback object back to the service for debugging purposes by setting the property to `true` either programmatically or from an application configuration file. + You can enable the flow of managed exception information in a client callback object back to the service for debugging purposes by setting the property to `true` either programmatically or from an application configuration file. - Returning managed exception information to services can be a security risk because exception details expose information about the internal client implementation that unauthorized services could use. In addition, although the properties can also be set programmatically, it can be easy to forget to disable when deploying. + Returning managed exception information to services can be a security risk because exception details expose information about the internal client implementation that unauthorized services could use. In addition, although the properties can also be set programmatically, it can be easy to forget to disable when deploying. Because of the security issues involved, it is strongly recommended that: -- You use an application configuration file to set the value of the property to `true`. +- You use an application configuration file to set the value of the property to `true`. - You do so only in controlled debugging scenarios. diff --git a/docs/framework/wcf/specifying-service-run-time-behavior.md b/docs/framework/wcf/specifying-service-run-time-behavior.md index 275e40b6adbfb..de05fa6c4161f 100644 --- a/docs/framework/wcf/specifying-service-run-time-behavior.md +++ b/docs/framework/wcf/specifying-service-run-time-behavior.md @@ -43,7 +43,7 @@ Once you have designed a service contract ([Designing Service Contracts](designi - Impersonation -- To use these attributes, mark the service or operation implementation with the attribute appropriate to that scope and set the properties. For example, the following code example shows an operation implementation that uses the property to require that callers of this operation support impersonation. +- To use these attributes, mark the service or operation implementation with the attribute appropriate to that scope and set the properties. For example, the following code example shows an operation implementation that uses the property to require that callers of this operation support impersonation. [!code-csharp[OperationBehaviorAttribute_Impersonation#1](../../../samples/snippets/csharp/VS_Snippets_CFX/operationbehaviorattribute_impersonation/cs/services.cs#1)] [!code-vb[OperationBehaviorAttribute_Impersonation#1](../../../samples/snippets/visualbasic/VS_Snippets_CFX/operationbehaviorattribute_impersonation/vb/services.vb#1)] @@ -54,17 +54,17 @@ Once you have designed a service contract ([Designing Service Contracts](designi You can use the and attributes to control certain lifetimes, both of the and of the service objects that implement the operations. - For example, the property controls how often the is released, and the and properties control when the service object is released. + For example, the property controls how often the is released, and the and properties control when the service object is released. - However, you can also create a service object yourself and create the service host using that object. To do so, you must also set the property to or an exception is thrown when the service host is opened. + However, you can also create a service object yourself and create the service host using that object. To do so, you must also set the property to or an exception is thrown when the service host is opened. Use the constructor to create such a service. It provides an alternative to implementing a custom when you wish to provide a specific object instance for use by a singleton service. You can use this overload when your service implementation type is difficult to construct (for example, if it does not implement a parameterless public constructor). - Note that when an object is provided to this constructor, some features related to the Windows Communication Foundation (WCF) instancing behavior work differently. For example, calling has no effect when a well-known object instance is provided. Similarly, any other instance release mechanism is ignored. The class always behaves as if the property is set to for all operations. + Note that when an object is provided to this constructor, some features related to the Windows Communication Foundation (WCF) instancing behavior work differently. For example, calling has no effect when a well-known object instance is provided. Similarly, any other instance release mechanism is ignored. The class always behaves as if the property is set to for all operations. ## Other Service, Endpoint, Contract, and Operation Behaviors - Service behaviors, such as the attribute, operate across an entire service. For example, if you set the property to you must handle thread synchronization issues inside each operation in that service yourself. Endpoint behaviors operate across an endpoint; many of the system-provided endpoint behaviors are for client functionality. Contract behaviors operate at the contract level, and operation behaviors modify operation delivery. + Service behaviors, such as the attribute, operate across an entire service. For example, if you set the property to you must handle thread synchronization issues inside each operation in that service yourself. Endpoint behaviors operate across an endpoint; many of the system-provided endpoint behaviors are for client functionality. Contract behaviors operate at the contract level, and operation behaviors modify operation delivery. Many of these behaviors are implemented on attributes, and you make use of them as you do the and attributes—by applying them to the appropriate service class or operation implementation. Other behaviors, such as the or objects, are typically applied using an application configuration file, although they can also be used programmatically. diff --git a/docs/framework/wcf/synchronous-and-asynchronous-operations.md b/docs/framework/wcf/synchronous-and-asynchronous-operations.md index 0cced251d2984..10f2bcba12cba 100644 --- a/docs/framework/wcf/synchronous-and-asynchronous-operations.md +++ b/docs/framework/wcf/synchronous-and-asynchronous-operations.md @@ -112,7 +112,7 @@ public class AsyncExample #### IAsyncResult Asynchronous Pattern - A service operation can be implemented in an asynchronous fashion using the .NET Framework asynchronous programming pattern and marking the `` method with the property set to `true`. In this case, the asynchronous operation is exposed in metadata in the same form as a synchronous operation: It is exposed as a single operation with a request message and a correlated response message. Client programming models then have a choice. They can represent this pattern as a synchronous operation or as an asynchronous one, so long as when the service is invoked a request-response message exchange takes place. + A service operation can be implemented in an asynchronous fashion using the .NET Framework asynchronous programming pattern and marking the `` method with the property set to `true`. In this case, the asynchronous operation is exposed in metadata in the same form as a synchronous operation: It is exposed as a single operation with a request message and a correlated response message. Client programming models then have a choice. They can represent this pattern as a synchronous operation or as an asynchronous one, so long as when the service is invoked a request-response message exchange takes place. In general, with the asynchronous nature of the systems, you should not take a dependency on the threads. The most reliable way of passing data to various stages of operation dispatch processing is to use extensions. @@ -177,13 +177,13 @@ svcutil http://localhost:8000/servicemodelsamples/service/mex /async /tcv:Versio When this is done, Svcutil.exe generates a WCF client class with the event infrastructure that enables the calling application to implement and assign an event handler to receive the response and take the appropriate action. For a complete example, see [How to: Call Service Operations Asynchronously](./feature-details/how-to-call-wcf-service-operations-asynchronously.md). - The event-based asynchronous model, however, is only available in .NET Framework 3.5. In addition, it is not supported even in .NET Framework 3.5 when a WCF client channel is created by using a . With WCF client channel objects, you must use objects to invoke your operations asynchronously. To use this approach, specify the **/async** command option with the [ServiceModel Metadata Utility Tool (Svcutil.exe)](servicemodel-metadata-utility-tool-svcutil-exe.md), as in the following example. + The event-based asynchronous model, however, is only available in .NET Framework 3.5. In addition, it is not supported even in .NET Framework 3.5 when a WCF client channel is created by using a . With WCF client channel objects, you must use objects to invoke your operations asynchronously. To use this approach, specify the **/async** command option with the [ServiceModel Metadata Utility Tool (Svcutil.exe)](servicemodel-metadata-utility-tool-svcutil-exe.md), as in the following example. ```console svcutil http://localhost:8000/servicemodelsamples/service/mex /async ``` - This generates a service contract in which each operation is modeled as a `` method with the property set to `true` and a corresponding `` method. For a complete example using a , see [How to: Call Operations Asynchronously Using a Channel Factory](./feature-details/how-to-call-operations-asynchronously-using-a-channel-factory.md). + This generates a service contract in which each operation is modeled as a `` method with the property set to `true` and a corresponding `` method. For a complete example using a , see [How to: Call Operations Asynchronously Using a Channel Factory](./feature-details/how-to-call-operations-asynchronously-using-a-channel-factory.md). In either case, applications can invoke an operation asynchronously even if the service is implemented synchronously, in the same way that an application can use the same pattern to invoke asynchronously a local synchronous method. How the operation is implemented is not significant to the client; when the response message arrives, its content is dispatched to the client's asynchronous `` method and the client retrieves the information. @@ -200,4 +200,4 @@ svcutil http://localhost:8000/servicemodelsamples/service/mex /async ## See also - -- +- diff --git a/docs/framework/wcf/using-sessions.md b/docs/framework/wcf/using-sessions.md index bf11f4de07c12..5340f59e48f3e 100644 --- a/docs/framework/wcf/using-sessions.md +++ b/docs/framework/wcf/using-sessions.md @@ -47,7 +47,7 @@ In Windows Communication Foundation (WCF) applications, a *session* correlates a ## Default Execution Behavior Using Sessions - A binding that attempts to initiate a session is called a *session-based* binding. Service contracts specify that they require, permit, or refuse session-based bindings by setting the property on the service contract interface (or class) to one of the enumeration values. By default, the value of this property is , which means that if a client uses a session-based binding with a WCF service implementation, the service establishes and uses the session provided. + A binding that attempts to initiate a session is called a *session-based* binding. Service contracts specify that they require, permit, or refuse session-based bindings by setting the property on the service contract interface (or class) to one of the enumeration values. By default, the value of this property is , which means that if a client uses a session-based binding with a WCF service implementation, the service establishes and uses the session provided. When a WCF service accepts a client session, the following features are enabled by default: @@ -69,11 +69,11 @@ In Windows Communication Foundation (WCF) applications, a *session* correlates a - The binding provides MSMQ datagram sessions. For more information, see [Queues in WCF](./feature-details/queues-in-wcf.md). - Setting the property does not specify the type of session the contract requires, only that it requires one. + Setting the property does not specify the type of session the contract requires, only that it requires one. ## Creating a Contract That Requires a Session - Creating a contract that requires a session states that the group of operations that the service contract declares must all be executed within the same session and that messages must be delivered in order. To assert the level of session support that a service contract requires, set the property on your service contract interface or class to the value of the enumeration to specify whether the contract: + Creating a contract that requires a session states that the group of operations that the service contract declares must all be executed within the same session and that messages must be delivered in order. To assert the level of session support that a service contract requires, set the property on your service contract interface or class to the value of the enumeration to specify whether the contract: - Requires a session. @@ -81,7 +81,7 @@ In Windows Communication Foundation (WCF) applications, a *session* correlates a - Prohibits a session. - Setting the property does not, however, specify the type of session-based behavior the contract requires. It instructs WCF to confirm at runtime that the configured binding (which creates the communication channel) for the service does, does not, or can establish a session when implementing a service. Again, the binding can satisfy that requirement with any type of session-based behavior it chooses—security, transport, reliable, or some combination. The exact behavior depends on the value selected. If the configured binding of the service does not conform to the value of , an exception is thrown. Bindings and the channels they create that support sessions are said to be session-based. + Setting the property does not, however, specify the type of session-based behavior the contract requires. It instructs WCF to confirm at runtime that the configured binding (which creates the communication channel) for the service does, does not, or can establish a session when implementing a service. Again, the binding can satisfy that requirement with any type of session-based behavior it chooses—security, transport, reliable, or some combination. The exact behavior depends on the value selected. If the configured binding of the service does not conform to the value of , an exception is thrown. Bindings and the channels they create that support sessions are said to be session-based. The following service contract specifies that all operations in the `ICalculatorSession` must be exchanged within a session. None of the operations returns a value to the caller except the `Equals` method. However, the `Equals` method takes no parameters and, therefore, can only return a non-zero value inside a session in which data has already been passed to the other operations. This contract requires a session to function properly. Without a session associated with a specific client, the service instance has no way of knowing what previous data this client has sent. @@ -116,17 +116,17 @@ In Windows Communication Foundation (WCF) applications, a *session* correlates a Services do not start sessions with clients. In WCF client applications, a direct relationship exists between the lifetime of the session-based channel and the lifetime of the session itself. As such, clients create new sessions by creating new session-based channels and tear down existing sessions by closing session-based channels gracefully. A client starts a session with a service endpoint by calling one of the following: -- on the channel returned by a call to . +- on the channel returned by a call to . -- on the WCF client object generated by the [ServiceModel Metadata Utility Tool (Svcutil.exe)](servicemodel-metadata-utility-tool-svcutil-exe.md). +- on the WCF client object generated by the [ServiceModel Metadata Utility Tool (Svcutil.exe)](servicemodel-metadata-utility-tool-svcutil-exe.md). - An initiating operation on either type of WCF client object (by default, all operations are initiating). When the first operation is called, the WCF client object automatically opens the channel and initiates a session. Typically a client ends a session with a service endpoint by calling one of the following: -- on the channel returned by a call to . +- on the channel returned by a call to . -- on the WCF client object generated by Svcutil.exe. +- on the WCF client object generated by Svcutil.exe. - A terminating operation on either type of WCF client object (by default, no operations are terminating; the contract must explicitly specify a terminating operation). When the first operation is called, the WCF client object automatically opens the channel and initiates a session. @@ -136,7 +136,7 @@ In Windows Communication Foundation (WCF) applications, a *session* correlates a ## Sessions Interact with InstanceContext Settings - There is an interaction between the enumeration in a contract and the property, which controls the association between channels and specific service objects. For more information, see [Sessions, Instancing, and Concurrency](./feature-details/sessions-instancing-and-concurrency.md). + There is an interaction between the enumeration in a contract and the property, which controls the association between channels and specific service objects. For more information, see [Sessions, Instancing, and Concurrency](./feature-details/sessions-instancing-and-concurrency.md). ### Sharing InstanceContext Objects diff --git a/docs/framework/wcf/wcf-client-overview.md b/docs/framework/wcf/wcf-client-overview.md index b4004d9be7148..05ef930471d3f 100644 --- a/docs/framework/wcf/wcf-client-overview.md +++ b/docs/framework/wcf/wcf-client-overview.md @@ -57,14 +57,14 @@ svcutil /language:vb /out:ClientCode.vb /config:app.config http://computerName/M #### Creating a New WCF Object - To illustrate the use of a class, assume the following simple service contract has been generated from a service application. + To illustrate the use of a class, assume the following simple service contract has been generated from a service application. > [!NOTE] > If you are using Visual Studio to create your WCF client, objects are loaded automatically into the object browser when you add a service reference to your project. [!code-csharp[C_GeneratedCodeFiles#12](../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#12)] - If you are not using Visual Studio, examine the generated contract code to find the type that extends and the service contract interface `ISampleService`. In this case, that type looks like the following code: + If you are not using Visual Studio, examine the generated contract code to find the type that extends and the service contract interface `ISampleService`. In this case, that type looks like the following code: [!code-csharp[C_GeneratedCodeFiles#14](../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#14)] @@ -80,7 +80,7 @@ svcutil /language:vb /out:ClientCode.vb /config:app.config http://computerName/M [!code-xml[C_GeneratedCodeFiles#19](../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/common/client.exe.config#19)] - This configuration file specifies a target endpoint in the `` element. For more information about using multiple target endpoints, see the or the constructors. + This configuration file specifies a target endpoint in the `` element. For more information about using multiple target endpoints, see the or the constructors. ## Calling Operations @@ -135,7 +135,7 @@ End Interface ## Handling Errors - Exceptions can occur in a client application when opening the underlying client channel (whether explicitly or automatically by calling an operation), using the client or channel object to call operations, or when closing the underlying client channel. It is recommended at a minimum that applications expect to handle possible and exceptions in addition to any objects thrown as a result of SOAP faults returned by operations. SOAP faults specified in the operation contract are raised to client applications as a where the type parameter is the detail type of the SOAP fault. For more information about handling error conditions in a client application, see [Sending and Receiving Faults](sending-and-receiving-faults.md). For a complete sample the shows how to handle errors in a client, see [Expected Exceptions](./samples/expected-exceptions.md). + Exceptions can occur in a client application when opening the underlying client channel (whether explicitly or automatically by calling an operation), using the client or channel object to call operations, or when closing the underlying client channel. It is recommended at a minimum that applications expect to handle possible and exceptions in addition to any objects thrown as a result of SOAP faults returned by operations. SOAP faults specified in the operation contract are raised to client applications as a where the type parameter is the detail type of the SOAP fault. For more information about handling error conditions in a client application, see [Sending and Receiving Faults](sending-and-receiving-faults.md). For a complete sample the shows how to handle errors in a client, see [Expected Exceptions](./samples/expected-exceptions.md). ## Configuring and Securing Clients @@ -176,9 +176,9 @@ End Interface ## Calling Services Using WCF Client Channels - WCF client types extend , which itself derives from interface to expose the underlying channel system. You can invoke services by using the target service contract with the class. For details, see [WCF Client Architecture](./feature-details/client-architecture.md). + WCF client types extend , which itself derives from interface to expose the underlying channel system. You can invoke services by using the target service contract with the class. For details, see [WCF Client Architecture](./feature-details/client-architecture.md). ## See also -- -- +- +- diff --git a/docs/framework/wcf/wcf-error-handling.md b/docs/framework/wcf/wcf-error-handling.md index 21bd808dcdfec..b8b2f84b5136a 100644 --- a/docs/framework/wcf/wcf-error-handling.md +++ b/docs/framework/wcf/wcf-error-handling.md @@ -6,44 +6,44 @@ ms.assetid: 1e4b1e0f-9598-449d-9d73-90bda62305b8 --- # WCF Error Handling -The errors encountered by a WCF application belong to one of three groups: - -1. Communication Errors - -2. Proxy/Channel Errors - -3. Application Errors - - Communication errors occur when a network is unavailable, a client uses an incorrect address, or the service host is not listening for incoming messages. Errors of this type are returned to the client as or -derived classes. - - Proxy/Channel errors are errors that occur within the channel or proxy itself. Errors of this type include: attempting to use a proxy or channel that has been closed, a contract mismatch exists between the client and service, or the client’s credentials are rejected by the service. There are many different types of errors in this category, too many to list here. Errors of this type are returned to the client as-is (no transformation is performed on the exception objects). - - Application errors occur during the execution of a service operation. Errors of this kind are sent to the client as or . - - Error handling in WCF is performed by one or more of the following: - -- Directly handling the exception thrown. This is only done for communication and proxy/channel errors. - -- Using fault contracts - -- Implementing the interface - -- Handling events - -## Fault Contracts - - Fault contracts allow you to define the errors that can occur during service operation in a platform independent way. By default all exceptions thrown from within a service operation will be returned to the client as a object. The object will contain very little information. You can control the information sent to the client by defining a fault contract and returning the error as a . For more information, see [Specifying and Handling Faults in Contracts and Services](specifying-and-handling-faults-in-contracts-and-services.md). - -## IErrorHandler - - The interface allows you more control over how your WCF application responds to errors. It gives you full control over the fault message that is returned to the client and allows you to perform custom error processing such as logging. For more information about and [Extending Control Over Error Handling and Reporting](./samples/extending-control-over-error-handling-and-reporting.md) - -## ServiceHost Events - - The class hosts services and defines several events that may be needed for handling errors. For example: - +The errors encountered by a WCF application belong to one of three groups: + +1. Communication Errors + +2. Proxy/Channel Errors + +3. Application Errors + + Communication errors occur when a network is unavailable, a client uses an incorrect address, or the service host is not listening for incoming messages. Errors of this type are returned to the client as or -derived classes. + + Proxy/Channel errors are errors that occur within the channel or proxy itself. Errors of this type include: attempting to use a proxy or channel that has been closed, a contract mismatch exists between the client and service, or the client’s credentials are rejected by the service. There are many different types of errors in this category, too many to list here. Errors of this type are returned to the client as-is (no transformation is performed on the exception objects). + + Application errors occur during the execution of a service operation. Errors of this kind are sent to the client as or . + + Error handling in WCF is performed by one or more of the following: + +- Directly handling the exception thrown. This is only done for communication and proxy/channel errors. + +- Using fault contracts + +- Implementing the interface + +- Handling events + +## Fault Contracts + + Fault contracts allow you to define the errors that can occur during service operation in a platform independent way. By default all exceptions thrown from within a service operation will be returned to the client as a object. The object will contain very little information. You can control the information sent to the client by defining a fault contract and returning the error as a . For more information, see [Specifying and Handling Faults in Contracts and Services](specifying-and-handling-faults-in-contracts-and-services.md). + +## IErrorHandler + + The interface allows you more control over how your WCF application responds to errors. It gives you full control over the fault message that is returned to the client and allows you to perform custom error processing such as logging. For more information about and [Extending Control Over Error Handling and Reporting](./samples/extending-control-over-error-handling-and-reporting.md) + +## ServiceHost Events + + The class hosts services and defines several events that may be needed for handling errors. For example: + 1. - + 2. - + For more information, see diff --git a/docs/framework/wcf/wcf-simplification-features.md b/docs/framework/wcf/wcf-simplification-features.md index 7a5506a0dbc73..1dedfcda4422b 100644 --- a/docs/framework/wcf/wcf-simplification-features.md +++ b/docs/framework/wcf/wcf-simplification-features.md @@ -84,7 +84,7 @@ WCF provides ASP.NET compatibility mode to grant developers full access to the f ## Streaming Improvements -- New support for asynchronous streaming has been added to WCF. To enable asynchronous streaming, add the endpoint behavior to the service host and set its property to `true`. This can benefit scalability when a service is sending streamed messages to multiple clients which are reading slowly. WCF does not block one thread per client anymore and will free up the thread to service another client. +- New support for asynchronous streaming has been added to WCF. To enable asynchronous streaming, add the endpoint behavior to the service host and set its property to `true`. This can benefit scalability when a service is sending streamed messages to multiple clients which are reading slowly. WCF does not block one thread per client anymore and will free up the thread to service another client. - Removed limitations around buffering of messages when a service is IIS hosted. In previous versions of WCF when receiving a message for an IIS-hosted service that used streaming message transfer, ASP.NET would buffer the entire message before sending it to WCF. This would cause large memory consumption. This buffering has been removed in .NET Framework 4.5 and now IIS-hosted WCF services can start processing the incoming stream before the entire message has been received, thereby enabling true streaming. This allows WCF to respond immediately to messages and allows improved performance. In addition, you no longer have to specify a value for `maxRequestLength`, the ASP.NET size limit on incoming requests. If this property is set, it is ignored. For more information about `maxRequestLength` see [\ configuration element](/previous-versions/dotnet/netframework-1.1/e1f13641(v=vs.71)). You will still need to configure the maxAllowedContentLength, For more information, see [IIS Request Limits](/previous-versions/iis/settings-schema/ms689462(v=vs.90)). @@ -94,10 +94,10 @@ The following table describes the settings that have changed and where to find a |Property|On|New Default|More Information| |--------------|--------|-----------------|----------------------| -|channelInitializationTimeout||30 seconds|This property determines how long a TCP connection can take to authenticate itself using the .NET Framing protocol. A client needs to send some initial data before the server has enough information to perform authentication. This timeout is intentionally made smaller than the ReceiveTimeout (10 min) so that malicious unauthenticated clients do not keep the connections tied up to the server for long. The default value is 30 seconds. For more information about | -|listenBacklog||16 * number of processors|This socket-level property describes the number of "pending accept" requests to be queued. If the listen backlog queue fills up, new socket requests will be rejected. For more information about | -|maxPendingAccepts|ConnectionOrientedTransportBindingElement

SMSvcHost.exe|2 * number of processors for transport

4 \* number of processors for SMSvcHost.exe|This property limits the number of channels that the server can have waiting on a listener. When MaxPendingAccepts is too low, there will be a small interval of time in which all of the waiting channels have started servicing connections, but no new channels have begun listening. A connection can arrive during this interval and will fail because nothing is waiting for it on the server. This property can be configured by setting the property to a larger number. For more information, see and [Configuring the Net.TCP Port Sharing Service](./feature-details/configuring-the-net-tcp-port-sharing-service.md)| -|maxPendingConnections|ConnectionOrientedTransportBindingElement|12 * number of processors|This property controls how many connections a transport has accepted but have not been picked up by the ServiceModel Dispatcher. To set this value, use `MaxConnections` on the binding or `maxOutboundConnectionsPerEndpoint` on the binding element. For more information about | +|channelInitializationTimeout||30 seconds|This property determines how long a TCP connection can take to authenticate itself using the .NET Framing protocol. A client needs to send some initial data before the server has enough information to perform authentication. This timeout is intentionally made smaller than the ReceiveTimeout (10 min) so that malicious unauthenticated clients do not keep the connections tied up to the server for long. The default value is 30 seconds. For more information about | +|listenBacklog||16 * number of processors|This socket-level property describes the number of "pending accept" requests to be queued. If the listen backlog queue fills up, new socket requests will be rejected. For more information about | +|maxPendingAccepts|ConnectionOrientedTransportBindingElement

SMSvcHost.exe|2 * number of processors for transport

4 \* number of processors for SMSvcHost.exe|This property limits the number of channels that the server can have waiting on a listener. When MaxPendingAccepts is too low, there will be a small interval of time in which all of the waiting channels have started servicing connections, but no new channels have begun listening. A connection can arrive during this interval and will fail because nothing is waiting for it on the server. This property can be configured by setting the property to a larger number. For more information, see and [Configuring the Net.TCP Port Sharing Service](./feature-details/configuring-the-net-tcp-port-sharing-service.md)| +|maxPendingConnections|ConnectionOrientedTransportBindingElement|12 * number of processors|This property controls how many connections a transport has accepted but have not been picked up by the ServiceModel Dispatcher. To set this value, use `MaxConnections` on the binding or `maxOutboundConnectionsPerEndpoint` on the binding element. For more information about | |receiveTimeout|SMSvcHost.exe|30 seconds|This property specifies the timeout for reading the TCP framing data and performing connection dispatching from the underlying connections. This exists to put a cap on the amount of time SMSvcHost.exe service is kept engaged to read the preamble data from an incoming connection. For more information, see [Configuring the Net.TCP Port Sharing Service](./feature-details/configuring-the-net-tcp-port-sharing-service.md).| > [!NOTE] @@ -109,11 +109,11 @@ The following table describes the settings that have changed and where to find a |Quota Name|Default Value|Description| |----------------|-------------------|-----------------| -||Int32.MaxValue|Gets and sets the maximum allowed array length. This quota limits the maximum size of an array of primitives that the XML reader returns, including byte arrays. This quota does not limit memory consumption in the XML reader itself, but in whatever component that is using the reader. For example, when the uses a reader secured with , it does not deserialize byte arrays larger than this quota.| -||Int32.MaxValue|Gets and sets the maximum allowed bytes returned for each read. This quota limits the number of bytes that are read in a single Read operation when reading the element start tag and its attributes. (In non-streamed cases, the element name itself is not counted against the quota). Having too many XML attributes may use up disproportionate processing time because attribute names have to be checked for uniqueness. mitigates this threat.| -||128 nodes deep|This quota limits the maximum nesting depth of XML elements. interacts with : the reader always keeps data in memory for the current element and all of its ancestors, so the maximum memory consumption of the reader is proportional to the product of these two settings. When deserializing a deeply-nested object graph, the deserializer is forced to access the entire stack and throw an unrecoverable . A direct correlation exists between XML nesting and object nesting for both the and the . is used to mitigate this threat.| -||Int32.MaxValue|This quota limits the maximum number of characters allowed in a nametable. The nametable contains certain strings (such as namespaces and prefixes) that are encountered when processing an XML document. As these strings are buffered in memory, this quota is used to prevent excessive buffering when streaming is expected.| -||Int32.MaxValue|This quota limits the maximum string size that the XML reader returns. This quota does not limit memory consumption in the XML reader itself, but in the component that is using the reader. For example, when the uses a reader secured with , it does not deserialize strings larger than this quota.| +||Int32.MaxValue|Gets and sets the maximum allowed array length. This quota limits the maximum size of an array of primitives that the XML reader returns, including byte arrays. This quota does not limit memory consumption in the XML reader itself, but in whatever component that is using the reader. For example, when the uses a reader secured with , it does not deserialize byte arrays larger than this quota.| +||Int32.MaxValue|Gets and sets the maximum allowed bytes returned for each read. This quota limits the number of bytes that are read in a single Read operation when reading the element start tag and its attributes. (In non-streamed cases, the element name itself is not counted against the quota). Having too many XML attributes may use up disproportionate processing time because attribute names have to be checked for uniqueness. mitigates this threat.| +||128 nodes deep|This quota limits the maximum nesting depth of XML elements. interacts with : the reader always keeps data in memory for the current element and all of its ancestors, so the maximum memory consumption of the reader is proportional to the product of these two settings. When deserializing a deeply-nested object graph, the deserializer is forced to access the entire stack and throw an unrecoverable . A direct correlation exists between XML nesting and object nesting for both the and the . is used to mitigate this threat.| +||Int32.MaxValue|This quota limits the maximum number of characters allowed in a nametable. The nametable contains certain strings (such as namespaces and prefixes) that are encountered when processing an XML document. As these strings are buffered in memory, this quota is used to prevent excessive buffering when streaming is expected.| +||Int32.MaxValue|This quota limits the maximum string size that the XML reader returns. This quota does not limit memory consumption in the XML reader itself, but in the component that is using the reader. For example, when the uses a reader secured with , it does not deserialize strings larger than this quota.| > [!IMPORTANT] > Refer to "Using XML Safely" under [Security Considerations for Data](./feature-details/security-considerations-for-data.md) for more information about securing your data. diff --git a/docs/framework/wcf/wcf-troubleshooting-quickstart.md b/docs/framework/wcf/wcf-troubleshooting-quickstart.md index a9d0bd068da28..934c810dfcd5f 100644 --- a/docs/framework/wcf/wcf-troubleshooting-quickstart.md +++ b/docs/framework/wcf/wcf-troubleshooting-quickstart.md @@ -2,118 +2,118 @@ description: "Learn more about: WCF Troubleshooting Quickstart" title: "WCF Troubleshooting Quickstart" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "WCF [WCF], troubleshooting" - "Windows Communication Foundation [WCF], troubleshooting" ms.assetid: a9ea7a53-f31a-46eb-806e-898e465a4992 --- # WCF Troubleshooting Quickstart -This topic lists a number of known issues customers have run into while developing WCF clients and services. If the issue you are running into is not in this list, we recommend you configure tracing for your service. This will generate a trace file that you can view with the trace file viewer and get detailed information about exceptions that may be occurring within the service. For more information on configuring tracing, see: [Configuring Tracing](./diagnostics/tracing/configuring-tracing.md). For more information on the trace file viewer, see: [Service Trace Viewer Tool (SvcTraceViewer.exe)](service-trace-viewer-tool-svctraceviewer-exe.md). - -1. [After installing Windows 7 and IIS, when I attempt to browse to a WCF service I get the following error message: HTTP Error 404.3 – Not Found](#bkmk_0) - - HTTP Error 404.3 – Not FoundThe page you are requesting cannot be served because of the extension configuration. If the page is a script, add a handler. If the file should be downloaded, add a MIME map. Detailed Error InformationModule StaticFileModule. - -2. [Sometimes I receive a MessageSecurityException on the second request if my client is idle for a while after the first request. What is happening?](#BKMK_q1) - -3. [My service starts to reject new clients after about 10 clients are interacting with it. What is happening?](#BKMK_q2) - -4. [Can I load my service configuration from somewhere other than the WCF application’s configuration file?](#BKMK_q3) - -5. [My service and client work great, but I can’t get them to work when the client is on another computer? What’s happening?](#BKMK_q4) - -6. [When I throw a FaultException\ where the type is an exception, I always receive a general FaultException type on the client and not the generic type. What’s happening?](#BKMK_q5) - -7. [It seems like one-way and request-reply operations return at roughly the same speed when the reply contains no data. What's happening?](#BKMK_q6) - -8. [I’m using an X.509 certificate with my service and I get a System.Security.Cryptography.CryptographicException. What’s happening?](#BKMK_q77) - -9. [I changed the first parameter of an operation from uppercase to lowercase; now my client throws an exception. What's happening?](#BKMK_q88) - -10. [I’m using one of my tracing tools and I get an EndpointNotFoundException. What’s happening?](#BKMK_q99) - -11. [When calling a WCF Web HTTP application from a WCF SOAP application the service returns the following error: 405 Method Not Allowed](#BK_MK99) - - [What is the base address? How does it relate to an endpoint address?](#BKMK_q10) - +This topic lists a number of known issues customers have run into while developing WCF clients and services. If the issue you are running into is not in this list, we recommend you configure tracing for your service. This will generate a trace file that you can view with the trace file viewer and get detailed information about exceptions that may be occurring within the service. For more information on configuring tracing, see: [Configuring Tracing](./diagnostics/tracing/configuring-tracing.md). For more information on the trace file viewer, see: [Service Trace Viewer Tool (SvcTraceViewer.exe)](service-trace-viewer-tool-svctraceviewer-exe.md). + +1. [After installing Windows 7 and IIS, when I attempt to browse to a WCF service I get the following error message: HTTP Error 404.3 – Not Found](#bkmk_0) + + HTTP Error 404.3 – Not FoundThe page you are requesting cannot be served because of the extension configuration. If the page is a script, add a handler. If the file should be downloaded, add a MIME map. Detailed Error InformationModule StaticFileModule. + +2. [Sometimes I receive a MessageSecurityException on the second request if my client is idle for a while after the first request. What is happening?](#BKMK_q1) + +3. [My service starts to reject new clients after about 10 clients are interacting with it. What is happening?](#BKMK_q2) + +4. [Can I load my service configuration from somewhere other than the WCF application’s configuration file?](#BKMK_q3) + +5. [My service and client work great, but I can’t get them to work when the client is on another computer? What’s happening?](#BKMK_q4) + +6. [When I throw a FaultException\ where the type is an exception, I always receive a general FaultException type on the client and not the generic type. What’s happening?](#BKMK_q5) + +7. [It seems like one-way and request-reply operations return at roughly the same speed when the reply contains no data. What's happening?](#BKMK_q6) + +8. [I’m using an X.509 certificate with my service and I get a System.Security.Cryptography.CryptographicException. What’s happening?](#BKMK_q77) + +9. [I changed the first parameter of an operation from uppercase to lowercase; now my client throws an exception. What's happening?](#BKMK_q88) + +10. [I’m using one of my tracing tools and I get an EndpointNotFoundException. What’s happening?](#BKMK_q99) + +11. [When calling a WCF Web HTTP application from a WCF SOAP application the service returns the following error: 405 Method Not Allowed](#BK_MK99) + + [What is the base address? How does it relate to an endpoint address?](#BKMK_q10) + -## After installing Windows 7 and IIS, when I attempt to browse to a WCF service I get the following error message: HTTP Error 404.3 – Not Found +## After installing Windows 7 and IIS, when I attempt to browse to a WCF service I get the following error message: HTTP Error 404.3 – Not Found + + The full error message is: + + HTTP Error 404.3 – Not FoundThe page you are requesting cannot be served because of the extension configuration. If the page is a script, add a handler. If the file should be downloaded, add a MIME map. Detailed Error InformationModule StaticFileModule. + + This error message occurs when "Windows Communication Foundation HTTP Activation" is not explicitly set in the Control Panel. To set this go to the Control Panel, click Programs in the lower left-hand corner of the window. Click Turn Windows features on or off. Expand Microsoft .NET Framework 3.5.1 and select Windows Communication Foundation HTTP Activation. - The full error message is: - - HTTP Error 404.3 – Not FoundThe page you are requesting cannot be served because of the extension configuration. If the page is a script, add a handler. If the file should be downloaded, add a MIME map. Detailed Error InformationModule StaticFileModule. - - This error message occurs when "Windows Communication Foundation HTTP Activation" is not explicitly set in the Control Panel. To set this go to the Control Panel, click Programs in the lower left-hand corner of the window. Click Turn Windows features on or off. Expand Microsoft .NET Framework 3.5.1 and select Windows Communication Foundation HTTP Activation. - -## Sometimes I receive a MessageSecurityException on the second request if my client is idle for a while after the first request. What is happening? +## Sometimes I receive a MessageSecurityException on the second request if my client is idle for a while after the first request. What is happening? + + The second request can fail primarily for two reasons: (1) the session has timed out or (2) the Web server that is hosting the service is recycled. In the first case, the session is valid until the service times out. When the service does not receive a request from the client within the period of time specified in the service's binding (), the service terminates the security session. Subsequent client messages result in the . The client must re-establish a secure session with the service to send future messages or use a stateful security context token. Stateful security context tokens also allow a secure session to survive a Web server being recycled. For more information about using stateful secure context tokens in a secure session, see [How to: Create a Security Context Token for a Secure Session](./feature-details/how-to-create-a-security-context-token-for-a-secure-session.md). Alternatively, you can disable secure sessions. When you use the [\](../configure-apps/file-schema/wcf/wshttpbinding.md) binding, you can set the `establishSecurityContext` property to `false` to disable secure sessions. To disable secure sessions for other bindings, you must create a custom binding. For details about creating a custom binding, see [How to: Create a Custom Binding Using the SecurityBindingElement](./feature-details/how-to-create-a-custom-binding-using-the-securitybindingelement.md). Before you apply any of these options, you must understand your application's security requirements. - The second request can fail primarily for two reasons: (1) the session has timed out or (2) the Web server that is hosting the service is recycled. In the first case, the session is valid until the service times out. When the service does not receive a request from the client within the period of time specified in the service's binding (), the service terminates the security session. Subsequent client messages result in the . The client must re-establish a secure session with the service to send future messages or use a stateful security context token. Stateful security context tokens also allow a secure session to survive a Web server being recycled. For more information about using stateful secure context tokens in a secure session, see [How to: Create a Security Context Token for a Secure Session](./feature-details/how-to-create-a-security-context-token-for-a-secure-session.md). Alternatively, you can disable secure sessions. When you use the [\](../configure-apps/file-schema/wcf/wshttpbinding.md) binding, you can set the `establishSecurityContext` property to `false` to disable secure sessions. To disable secure sessions for other bindings, you must create a custom binding. For details about creating a custom binding, see [How to: Create a Custom Binding Using the SecurityBindingElement](./feature-details/how-to-create-a-custom-binding-using-the-securitybindingelement.md). Before you apply any of these options, you must understand your application's security requirements. - -## My service starts to reject new clients after about 10 clients are interacting with it. What is happening? +## My service starts to reject new clients after about 10 clients are interacting with it. What is happening? + + By default, services can have only 10 concurrent sessions. Therefore, if the service bindings use sessions, the service accepts new client connections until it reaches that number, after which it refuses new client connections until one of the current sessions ends. You can support more clients in a number of ways. If your service does not require sessions, do not use a sessionful binding. (For more information, see [Using Sessions](using-sessions.md).) Another option is to increase the session limit by changing the value of the property to the number appropriate to your circumstance. - By default, services can have only 10 concurrent sessions. Therefore, if the service bindings use sessions, the service accepts new client connections until it reaches that number, after which it refuses new client connections until one of the current sessions ends. You can support more clients in a number of ways. If your service does not require sessions, do not use a sessionful binding. (For more information, see [Using Sessions](using-sessions.md).) Another option is to increase the session limit by changing the value of the property to the number appropriate to your circumstance. - -## Can I load my service configuration from somewhere other than the WCF application’s configuration file? +## Can I load my service configuration from somewhere other than the WCF application’s configuration file? + + Yes, however, you have to create a custom class that overrides the method. Inside that method, you can call the base to load configuration first (if you want to load the standard configuration information as well) but you can also entirely replace the configuration loading system. If you want to load configuration from a configuration file that is different from the application configuration file, you must parse the configuration file yourself and load the configuration. + + The following code example shows how to override the method and directly configure an endpoint. - Yes, however, you have to create a custom class that overrides the method. Inside that method, you can call the base to load configuration first (if you want to load the standard configuration information as well) but you can also entirely replace the configuration loading system. If you want to load configuration from a configuration file that is different from the application configuration file, you must parse the configuration file yourself and load the configuration. - - The following code example shows how to override the method and directly configure an endpoint. - ```csharp -public class MyServiceHost : ServiceHost -{ +public class MyServiceHost : ServiceHost +{ public MyServiceHost(Type serviceType, params Uri[] baseAddresses) - : base(serviceType, baseAddresses) + : base(serviceType, baseAddresses) { Console.WriteLine("MyServiceHost Constructor"); - } - - protected override void ApplyConfiguration() - { - string straddress = GetAddress(); - Uri address = new Uri(straddress); - Binding binding = GetBinding(); - base.AddServiceEndpoint(typeof(IData), binding, address); - } - - string GetAddress() + } + + protected override void ApplyConfiguration() + { + string straddress = GetAddress(); + Uri address = new Uri(straddress); + Binding binding = GetBinding(); + base.AddServiceEndpoint(typeof(IData), binding, address); + } + + string GetAddress() { return "http://MyMachine:7777/MyEndpointAddress/"; - } - - Binding GetBinding() - { - WSHttpBinding binding = new WSHttpBinding(); - binding.Security.Mode = SecurityMode.None; - return binding; - } -} -``` - + } + + Binding GetBinding() + { + WSHttpBinding binding = new WSHttpBinding(); + binding.Security.Mode = SecurityMode.None; + return binding; + } +} +``` + -## My service and client work great, but I can’t get them to work when the client is on another computer? What’s happening? - - Depending upon the exception, there may be several issues: - -- You might need to change the client endpoint addresses to the host name and not "localhost". - -- You might need to open the port to the application. For details, see [Firewall Instructions](./samples/firewall-instructions.md) from the SDK samples. - -- For other possible issues, see the samples topic [Running the Windows Communication Foundation Samples](./samples/running-the-samples.md). - -- If your client is using Windows credentials and the exception is a , configure Kerberos as follows. - - 1. Add the identity credentials to the endpoint element in the client’s App.config file: - +## My service and client work great, but I can’t get them to work when the client is on another computer? What’s happening? + + Depending upon the exception, there may be several issues: + +- You might need to change the client endpoint addresses to the host name and not "localhost". + +- You might need to open the port to the application. For details, see [Firewall Instructions](./samples/firewall-instructions.md) from the SDK samples. + +- For other possible issues, see the samples topic [Running the Windows Communication Foundation Samples](./samples/running-the-samples.md). + +- If your client is using Windows credentials and the exception is a , configure Kerberos as follows. + + 1. Add the identity credentials to the endpoint element in the client’s App.config file: + ```xml - - - - - ``` - - 2. Run the self-hosted service under the System or NetworkService account. You can run this command to create a command window under the System account: - + name="WSHttpBinding_IServiceExample"> + + + + + ``` + + 2. Run the self-hosted service under the System or NetworkService account. You can run this command to create a command window under the System account: + ```console - at 12:36 /interactive "cmd.exe" - ``` - - 3. Host the service under Internet Information Services (IIS), which, by default, uses the service principal name (SPN) account. - - 4. Register a new SPN with the domain using SetSPN. You need to be a domain administrator in order to do this. - - For more information about the Kerberos protocol, see [Security Concepts Used in WCF](./feature-details/security-concepts-used-in-wcf.md) and: - -- [Debugging Windows Authentication Errors](./feature-details/debugging-windows-authentication-errors.md) - -- [Registering Kerberos Service Principal Names by Using Http.sys](/previous-versions/sql/sql-server-2008-r2/ms178119(v=sql.105)) - -- [Kerberos Explained](/previous-versions/windows/it-pro/windows-2000-server/bb742516(v=technet.10)) - + at 12:36 /interactive "cmd.exe" + ``` + + 3. Host the service under Internet Information Services (IIS), which, by default, uses the service principal name (SPN) account. + + 4. Register a new SPN with the domain using SetSPN. You need to be a domain administrator in order to do this. + + For more information about the Kerberos protocol, see [Security Concepts Used in WCF](./feature-details/security-concepts-used-in-wcf.md) and: + +- [Debugging Windows Authentication Errors](./feature-details/debugging-windows-authentication-errors.md) + +- [Registering Kerberos Service Principal Names by Using Http.sys](/previous-versions/sql/sql-server-2008-r2/ms178119(v=sql.105)) + +- [Kerberos Explained](/previous-versions/windows/it-pro/windows-2000-server/bb742516(v=technet.10)) + -## When I throw a FaultException\ where the type is an exception, I always receive a general FaultException type on the client and not the generic type. What’s happening? - - It is highly recommended that you create your own custom error data type and declare that as the detail type in your fault contract. The reason is that using system-provided exception types: - -- Creates a type dependency that removes one of the biggest strengths of service-oriented applications. - -- Cannot depend upon exceptions serializing in a standard way. Some—like —may not be serializable at all. - -- Exposes internal implementation details to clients. For more information, see [Specifying and Handling Faults in Contracts and Services](specifying-and-handling-faults-in-contracts-and-services.md). - - If you are debugging an application, however, you can serialize exception information and return it to the client by using the class. - +## When I throw a FaultException\ where the type is an exception, I always receive a general FaultException type on the client and not the generic type. What’s happening? + + It is highly recommended that you create your own custom error data type and declare that as the detail type in your fault contract. The reason is that using system-provided exception types: + +- Creates a type dependency that removes one of the biggest strengths of service-oriented applications. + +- Cannot depend upon exceptions serializing in a standard way. Some—like —may not be serializable at all. + +- Exposes internal implementation details to clients. For more information, see [Specifying and Handling Faults in Contracts and Services](specifying-and-handling-faults-in-contracts-and-services.md). + + If you are debugging an application, however, you can serialize exception information and return it to the client by using the class. + -## It seems like one-way and request-reply operations return at roughly the same speed when the reply contains no data. What's happening? +## It seems like one-way and request-reply operations return at roughly the same speed when the reply contains no data. What's happening? + + Specifying that an operation is one way means only that the operation contract accepts an input message and does not return an output message. In WCF, all client invocations return when the outbound data has been written to the wire or an exception is thrown. One-way operations work the same way, and they can throw if the service cannot be located or block if the service is not prepared to accept the data from the network. Typically in WCF, this results in one-way calls returning to the client more quickly than request-reply; but any condition that slows the sending of the outbound data over the network slows one-way operations as well as request-reply operations. For more information, see [One-Way Services](./feature-details/one-way-services.md) and [Accessing Services Using a WCF Client](./feature-details/accessing-services-using-a-client.md). - Specifying that an operation is one way means only that the operation contract accepts an input message and does not return an output message. In WCF, all client invocations return when the outbound data has been written to the wire or an exception is thrown. One-way operations work the same way, and they can throw if the service cannot be located or block if the service is not prepared to accept the data from the network. Typically in WCF, this results in one-way calls returning to the client more quickly than request-reply; but any condition that slows the sending of the outbound data over the network slows one-way operations as well as request-reply operations. For more information, see [One-Way Services](./feature-details/one-way-services.md) and [Accessing Services Using a WCF Client](./feature-details/accessing-services-using-a-client.md). - -## I’m using an X.509 certificate with my service and I get a System.Security.Cryptography.CryptographicException. What’s happening? +## I’m using an X.509 certificate with my service and I get a System.Security.Cryptography.CryptographicException. What’s happening? + + This commonly occurs after changing the user account under which the IIS worker process runs. For example, in Windows XP, if you change the default user account that the Aspnet_wp.exe runs under from ASPNET to a custom user account, you may see this error. If using a private key, the process that uses it will need to have permissions to access the file storing that key. + + If this is the case, you must give read access privileges to the process's account for the file containing the private key. For example, if the IIS worker process is running under the Bob account, then you will need to give Bob read access to the file containing the private key. + + For more information about how to give the correct user account access to the file that contains the private key for a specific X.509 certificate, see [How to: Make X.509 Certificates Accessible to WCF](./feature-details/how-to-make-x-509-certificates-accessible-to-wcf.md). - This commonly occurs after changing the user account under which the IIS worker process runs. For example, in Windows XP, if you change the default user account that the Aspnet_wp.exe runs under from ASPNET to a custom user account, you may see this error. If using a private key, the process that uses it will need to have permissions to access the file storing that key. - - If this is the case, you must give read access privileges to the process's account for the file containing the private key. For example, if the IIS worker process is running under the Bob account, then you will need to give Bob read access to the file containing the private key. - - For more information about how to give the correct user account access to the file that contains the private key for a specific X.509 certificate, see [How to: Make X.509 Certificates Accessible to WCF](./feature-details/how-to-make-x-509-certificates-accessible-to-wcf.md). - -## I changed the first parameter of an operation from uppercase to lowercase; now my client throws an exception. What's happening? +## I changed the first parameter of an operation from uppercase to lowercase; now my client throws an exception. What's happening? + + The values of the parameter names in the operation signature are part of the contract and are case-sensitive. Use the attribute when you need to distinguish between the local parameter name and the metadata that describes the operation for client applications. - The values of the parameter names in the operation signature are part of the contract and are case-sensitive. Use the attribute when you need to distinguish between the local parameter name and the metadata that describes the operation for client applications. - -## I’m using one of my tracing tools and I get an EndpointNotFoundException. What’s happening? +## I’m using one of my tracing tools and I get an EndpointNotFoundException. What’s happening? + + If you are using a tracing tool that is not the system-provided WCF tracing mechanism and you receive an that indicates that there was an address filter mismatch, you need to use the class to direct the messages to the tracing utility and have the utility redirect those messages to the service address. The class alters the `Via` addressing header to specify the next network address separately from the ultimate receiver, indicated by the `To` addressing header. When doing this, however, do not change the endpoint address, which is used to establish the `To` value. + + The following code example shows an example client configuration file. - If you are using a tracing tool that is not the system-provided WCF tracing mechanism and you receive an that indicates that there was an address filter mismatch, you need to use the class to direct the messages to the tracing utility and have the utility redirect those messages to the service address. The class alters the `Via` addressing header to specify the next network address separately from the ultimate receiver, indicated by the `To` addressing header. When doing this, however, do not change the endpoint address, which is used to establish the `To` value. - - The following code example shows an example client configuration file. - ```xml - - - - - - - - -``` - + name="WSHttpBinding_IMyContract"> + + + + + + + + +``` + -## What is the base address? How does it relate to an endpoint address? - - A base address is the root address for a class. By default, if you add a class into your service configuration, the Web Services Description Language (WSDL) for all endpoints the host publishes are retrieved from the HTTP base address, plus any relative address provided to the metadata behavior, plus "?wsdl". If you are familiar with ASP.NET and IIS, the base address is equivalent to the virtual directory. - -## Sharing a port between a service endpoint and a mex endpoint using the NetTcpBinding - - If you specify the base address for a service as net.tcp://MyServer:8080/MyService and add the following endpoints: - -```xml - - - - - - -``` - - And if you modify one of the NetTcpBinding settings as shown in the following configuration snippet: - -```xml - - - - - - - - - - - -``` - - You will see an error like the following: Unhandled Exception: System.ServiceModel.AddressAlreadyInUseException: There is already a listener on IP endpoint 0.0.0.0:9000 You can work around this error by specifying a fully qualified URL with a different port for the MEX endpoint as shown in the following configuration snippet: - +## What is the base address? How does it relate to an endpoint address? + + A base address is the root address for a class. By default, if you add a class into your service configuration, the Web Services Description Language (WSDL) for all endpoints the host publishes are retrieved from the HTTP base address, plus any relative address provided to the metadata behavior, plus "?wsdl". If you are familiar with ASP.NET and IIS, the base address is equivalent to the virtual directory. + +## Sharing a port between a service endpoint and a mex endpoint using the NetTcpBinding + + If you specify the base address for a service as net.tcp://MyServer:8080/MyService and add the following endpoints: + +```xml + + + + + + +``` + + And if you modify one of the NetTcpBinding settings as shown in the following configuration snippet: + +```xml + + + + + + + + + + + +``` + + You will see an error like the following: Unhandled Exception: System.ServiceModel.AddressAlreadyInUseException: There is already a listener on IP endpoint 0.0.0.0:9000 You can work around this error by specifying a fully qualified URL with a different port for the MEX endpoint as shown in the following configuration snippet: + ```xml - - - - - - -``` - + + + + + + +``` + -## When calling a WCF Web HTTP application from a WCF SOAP application the service returns the following error: 405 Method Not Allowed +## When calling a WCF Web HTTP application from a WCF SOAP application the service returns the following error: 405 Method Not Allowed + + Calling a WCF Web HTTP application (a service that uses the and ) from a WCF service may generate the following exception: ``Unhandled Exception: System.ServiceModel.FaultException`1[System.ServiceModel.ExceptionDetail]: The remote server returned an unexpected response: (405) Method Not Allowed.`` This exception occurs because WCF overwrites the outgoing with the incoming . To solve this problem, create an within the WCF Web HTTP service operation. For example: - Calling a WCF Web HTTP application (a service that uses the and ) from a WCF service may generate the following exception: ``Unhandled Exception: System.ServiceModel.FaultException`1[System.ServiceModel.ExceptionDetail]: The remote server returned an unexpected response: (405) Method Not Allowed.`` This exception occurs because WCF overwrites the outgoing with the incoming . To solve this problem, create an within the WCF Web HTTP service operation. For example: - ```csharp -public string Echo(string input) -{ - using (new OperationContextScope(this.InnerChannel)) - { - return base.Channel.Echo(input); - } -} -``` - +public string Echo(string input) +{ + using (new OperationContextScope(this.InnerChannel)) + { + return base.Channel.Echo(input); + } +} +``` + ## See also - [Debugging Windows Authentication Errors](./feature-details/debugging-windows-authentication-errors.md) diff --git a/docs/framework/wcf/whats-new.md b/docs/framework/wcf/whats-new.md index 4c43d318305ae..c5b3b5ec2f92d 100644 --- a/docs/framework/wcf/whats-new.md +++ b/docs/framework/wcf/whats-new.md @@ -78,10 +78,10 @@ The following table describes the settings that have changed and where to find a |Property|On|New Default|For more information see| |--------------|--------|-----------------|------------------------------| -|channelInitializationTimeout||30 seconds|| -|listenBacklog||12 * number of processors|| -|maxPendingAccepts|ConnectionOrientedTransportBindingElement

SMSvcHost.exe|2 * number of processors for transport

4 \* number of processors for SMSvcHost.exe| [Configuring the Net.TCP Port Sharing Service](./feature-details/configuring-the-net-tcp-port-sharing-service.md)| -|maxPendingConnections|ConnectionOrientedTransportBindingElement|12 * number of processors|| +|channelInitializationTimeout||30 seconds|| +|listenBacklog||12 * number of processors|| +|maxPendingAccepts|ConnectionOrientedTransportBindingElement

SMSvcHost.exe|2 * number of processors for transport

4 \* number of processors for SMSvcHost.exe| [Configuring the Net.TCP Port Sharing Service](./feature-details/configuring-the-net-tcp-port-sharing-service.md)| +|maxPendingConnections|ConnectionOrientedTransportBindingElement|12 * number of processors|| |receiveTimeout|SMSvcHost.exe|30 seconds|[Configuring the Net.TCP Port Sharing Service](./feature-details/configuring-the-net-tcp-port-sharing-service.md)| ## Configuring WCF Services in Code @@ -90,7 +90,7 @@ Windows Communication Foundation (WCF) allows developers to configure services u ## ChannelFactory Caching -WCF client applications use the class to create a communication channel with a WCF service. Creating instances incurs some overhead because it involves the following operations: +WCF client applications use the class to create a communication channel with a WCF service. Creating instances incurs some overhead because it involves the following operations: 1. Constructing the tree @@ -104,7 +104,7 @@ To help minimize this overhead, WCF can cache channel factories when you are usi ## Compression and the Binary Encoder -Beginning with WCF 4.5 the WCF binary encoder adds support for compression. The type of compression is configured with the property. Both the client and the service must configure the property. Compression will work for HTTP, HTTPS, and TCP protocols. If a client specifies to use compression but the service does not support it a protocol exception is thrown indicating a protocol mismatch. For more information, see [Choosing a Message Encoder](./feature-details/choosing-a-message-encoder.md). +Beginning with WCF 4.5 the WCF binary encoder adds support for compression. The type of compression is configured with the property. Both the client and the service must configure the property. Compression will work for HTTP, HTTPS, and TCP protocols. If a client specifies to use compression but the service does not support it a protocol exception is thrown indicating a protocol mismatch. For more information, see [Choosing a Message Encoder](./feature-details/choosing-a-message-encoder.md). ## UDP @@ -146,7 +146,7 @@ In Visual Studio 2010, WebServiceHost automatically created a default endpoint w ## IHttpCookieContainerManager -This interface, exposed by , makes working with cookies on the client side much easier. When AllowCookies is set to true on the binding, you can access cookies by using the following code: +This interface, exposed by , makes working with cookies on the client side much easier. When AllowCookies is set to true on the binding, you can access cookies by using the following code: ```csharp IHttpCookieContainerManager cookieManager = factory.GetProperty(); diff --git a/docs/framework/whats-new/index.md b/docs/framework/whats-new/index.md index 18f48599c919f..998005bb459d2 100644 --- a/docs/framework/whats-new/index.md +++ b/docs/framework/whats-new/index.md @@ -367,7 +367,7 @@ End Function **Support for ephemeral keys** -PFX import can optionally load private keys directly from memory, bypassing the hard drive. When the new flag is specified in an constructor or one of the overloads of the method, the private keys will be loaded as ephemeral keys. This prevents the keys from being visible on the disk. However: +PFX import can optionally load private keys directly from memory, bypassing the hard drive. When the new flag is specified in an constructor or one of the overloads of the method, the private keys will be loaded as ephemeral keys. This prevents the keys from being visible on the disk. However: - Since the keys are not persisted to disk, certificates loaded with this flag are not good candidates to add to an X509Store. @@ -383,11 +383,11 @@ For more information and code examples, see "Programmatic creation of PKCS#10 ce **New SignerInfo members** -Starting with .NET Framework 4.7.2, the class exposes more information about the signature. You can retrieve the value of the property to determine the signature algorithm used by the signer. can be called to get a copy of the cryptographic signature for this signer. +Starting with .NET Framework 4.7.2, the class exposes more information about the signature. You can retrieve the value of the property to determine the signature algorithm used by the signer. can be called to get a copy of the cryptographic signature for this signer. **Leaving a wrapped stream open after CryptoStream is disposed** -Starting with .NET Framework 4.7.2, the class has an additional constructor that allows to not close the wrapped stream. To leave the wrapped stream open after the instance is disposed, call the new constructor as follows: +Starting with .NET Framework 4.7.2, the class has an additional constructor that allows to not close the wrapped stream. To leave the wrapped stream open after the instance is disposed, call the new constructor as follows: ```csharp var cStream = new CryptoStream(stream, transform, mode, leaveOpen: true); @@ -409,24 +409,24 @@ Support for decompression by using Windows APIs is enabled by default for applic **Additional collection APIs** -.NET Framework 4.7.2 adds a number of new APIs to the and types. These include: +.NET Framework 4.7.2 adds a number of new APIs to the and types. These include: - `TryGetValue` methods, which extend the try pattern used in other collection types to these two types. The methods are: - - [public bool HashSet\.TryGetValue(T equalValue, out T actualValue)](xref:System.Collections.Generic.SortedSet%601.TryGetValue%2A) - - [public bool SortedSet\.TryGetValue(T equalValue, out T actualValue)](xref:System.Collections.Generic.SortedSet%601.TryGetValue%2A) + - [public bool HashSet\.TryGetValue(T equalValue, out T actualValue)](xref:System.Collections.Generic.SortedSet`1.TryGetValue%2A) + - [public bool SortedSet\.TryGetValue(T equalValue, out T actualValue)](xref:System.Collections.Generic.SortedSet`1.TryGetValue%2A) -- `Enumerable.To*` extension methods, which convert a collection to a : +- `Enumerable.To*` extension methods, which convert a collection to a : - [public static HashSet\ ToHashSet\(this IEnumerable\ source)](xref:System.Linq.Enumerable.ToHashSet%2A) - [public static HashSet\ ToHashSet\(this IEnumerable\ source, IEqualityComparer\ comparer)](xref:System.Linq.Enumerable.ToHashSet%2A) -- New constructors that let you set the collection's capacity, which yields a performance benefit when you know the size of the in advance: +- New constructors that let you set the collection's capacity, which yields a performance benefit when you know the size of the in advance: - - [public HashSet(int capacity)](xref:System.Collections.Generic.HashSet%601.%23ctor(System.Int32)) - - [public HashSet(int capacity, IEqualityComparer\ comparer)](xref:System.Collections.Generic.HashSet%601.%23ctor(System.Int32,System.Collections.Generic.IEqualityComparer%7B%600%7D)) + - [public HashSet(int capacity)](xref:System.Collections.Generic.HashSet`1.%23ctor(System.Int32)) + - [public HashSet(int capacity, IEqualityComparer\ comparer)](xref:System.Collections.Generic.HashSet`1.%23ctor(System.Int32,System.Collections.Generic.IEqualityComparer%7B`0%7D)) -The class includes new overloads of the and methods to retrieve a value from the dictionary or to add it if it is not found, and to add a value to the dictionary or to update it if it already exists. +The class includes new overloads of the and methods to retrieve a value from the dictionary or to add it if it is not found, and to add a value to the dictionary or to update it if it already exists. ```csharp public TValue AddOrUpdate(TKey key, Func addValueFactory, Func updateValueFactory, TArg factoryArgument) @@ -562,7 +562,7 @@ Starting with .NET Framework 4.7.2, a diagnostic assistant can locate the  ``` -A diagnostic assistant that edits the original markup in *MyRD.xaml* can use the new feature to locate the dictionary. The feature is implemented by a new static method, . The diagnostic assistant calls the new method using an absolute Uri that identifies the original markup, as illustrated by the following code: +A diagnostic assistant that edits the original markup in *MyRD.xaml* can use the new feature to locate the dictionary. The feature is implemented by a new static method, . The diagnostic assistant calls the new method using an absolute Uri that identifies the original markup, as illustrated by the following code: ```csharp IEnumerable dictionaries = ResourceDictionaryDiagnostics.GetResourceDictionariesForSource(new Uri("pack://application:,,,/MyApp;component/MyRD.xaml")); @@ -665,15 +665,15 @@ In addition, a major focus in .NET Framework 4.7.1 is improved accessibility, wh Configuration builders allow developers to inject and build configuration settings for applications dynamically at runtime. Custom configuration builders can be used to modify existing data in a configuration section or to build a configuration section entirely from scratch. Without configuration builders, .config files are static, and their settings are defined some time before an application is launched. -To create a custom configuration builder, you derive your builder from the abstract class and override its and . You also define your builders in your .config file. For more information, see the "Configuration Builders" section in the [.NET Framework 4.7.1 ASP.NET and Configuration Features](https://devblogs.microsoft.com/dotnet/net-framework-4-7-1-asp-net-and-configuration-features/) blog post. +To create a custom configuration builder, you derive your builder from the abstract class and override its and . You also define your builders in your .config file. For more information, see the "Configuration Builders" section in the [.NET Framework 4.7.1 ASP.NET and Configuration Features](https://devblogs.microsoft.com/dotnet/net-framework-4-7-1-asp-net-and-configuration-features/) blog post. **Runtime feature detection** -The class provides a mechanism for determine whether a predefined feature is supported on a given .NET implementation at compile time or runtime. At compile time, a compiler can check whether a specified field exists to determine whether the feature is supported; if so, it can emit code that takes advantage of that feature. At runtime, an application can call the method before emitting code at runtime. For more information, see [Add helper method to describe features supported by the runtime](https://github.com/dotnet/corefx/issues/17116). +The class provides a mechanism for determine whether a predefined feature is supported on a given .NET implementation at compile time or runtime. At compile time, a compiler can check whether a specified field exists to determine whether the feature is supported; if so, it can emit code that takes advantage of that feature. At runtime, an application can call the method before emitting code at runtime. For more information, see [Add helper method to describe features supported by the runtime](https://github.com/dotnet/corefx/issues/17116). **Value tuple types are serializable** -Starting with .NET Framework 4.7.1, and its associated generic types are marked as [Serializable](xref:System.SerializableAttribute), which allows binary serialization. This should make migrating Tuple types, such as and , to value tuple types easier. For more information, see "Compiler -- ValueTuple is Serializable" in the [.NET Framework 4.7.1 Runtime and Compiler Features](https://devblogs.microsoft.com/dotnet/net-framework-4-7-1-runtime-and-compiler-features/) blog post. +Starting with .NET Framework 4.7.1, and its associated generic types are marked as [Serializable](xref:System.SerializableAttribute), which allows binary serialization. This should make migrating Tuple types, such as and , to value tuple types easier. For more information, see "Compiler -- ValueTuple is Serializable" in the [.NET Framework 4.7.1 Runtime and Compiler Features](https://devblogs.microsoft.com/dotnet/net-framework-4-7-1-runtime-and-compiler-features/) blog post. **Support for read-only references** @@ -705,7 +705,7 @@ ASP.NET processes requests in a predefined pipeline that includes 23 events. ASP **ASP.NET HttpCookie parsing** -.NET Framework 4.7.1 includes a new method, , that provides a standardized way to create an object from a string and accurately assign cookie values such as expiration date and path. For more information, see "ASP.NET HttpCookie parsing" in the [.NET Framework 4.7.1 ASP.NET and Configuration Features](https://devblogs.microsoft.com/dotnet/net-framework-4-7-1-asp-net-and-configuration-features/) blog post. +.NET Framework 4.7.1 includes a new method, , that provides a standardized way to create an object from a string and accurately assign cookie values such as expiration date and path. For more information, see "ASP.NET HttpCookie parsing" in the [.NET Framework 4.7.1 ASP.NET and Configuration Features](https://devblogs.microsoft.com/dotnet/net-framework-4-7-1-asp-net-and-configuration-features/) blog post. **SHA-2 hash options for ASP.NET forms authentication credentials** @@ -736,7 +736,7 @@ For a list of new APIs added to .NET Framework 4.7, see [.NET Framework 4.7 API In .NET Framework 4.7, `ImportParameters(ECParameters)` methods were added to the and classes to allow for an object to represent an already-established key. An `ExportParameters(Boolean)` method was also added for exporting the key using explicit curve parameters. -.NET Framework 4.7 also adds support for additional curves (including the Brainpool curve suite), and has added predefined definitions for ease-of-creation through the new and factory methods. +.NET Framework 4.7 also adds support for additional curves (including the Brainpool curve suite), and has added predefined definitions for ease-of-creation through the new and factory methods. You can see an [example of .NET Framework 4.7 cryptography improvements](https://gist.github.com/richlander/5a182899895a87a296c21ada97f7a54e) on GitHub. @@ -766,9 +766,9 @@ Starting with .NET Framework 4.7, ASP.NET adds a new set of APIs that allow deve - **Object Cache Store**. By using the new cache providers configuration section, developers can plug in new implementations of an object cache for an ASP.NET application by using the new `ICacheStoreProvider` interface. -- **Memory monitoring**. The default memory monitor in ASP.NET notifies applications when they are running close to the configured private bytes limit for the process, or when the machine is low on total available physical RAM. When these limits are near, notifications are fired. For some applications, notifications are fired too close to the configured limits to allow for useful reactions. Developers can now write their own memory monitors to replace the default by using the property. +- **Memory monitoring**. The default memory monitor in ASP.NET notifies applications when they are running close to the configured private bytes limit for the process, or when the machine is low on total available physical RAM. When these limits are near, notifications are fired. For some applications, notifications are fired too close to the configured limits to allow for useful reactions. Developers can now write their own memory monitors to replace the default by using the property. -- **Memory Limit Reactions**. By default, ASP.NET attempts to trim the object cache and periodically call when the private byte process limit is near. For some applications, the frequency of calls to or the amount of cache that is trimmed are inefficient. Developers can now replace or supplement the default behavior by subscribing `IObserver` implementations to the application's memory monitor. +- **Memory Limit Reactions**. By default, ASP.NET attempts to trim the object cache and periodically call when the private byte process limit is near. For some applications, the frequency of calls to or the amount of cache that is trimmed are inefficient. Developers can now replace or supplement the default behavior by subscribing `IObserver` implementations to the application's memory monitor. @@ -857,15 +857,15 @@ In .NET Framework 4.6.2, ASP.NET includes the following enhancements: **Improved support for localized error messages in data annotation validators** -Data annotation validators enable you to perform validation by adding one or more attributes to a class property. The attribute's element defines the text of the error message if validation fails. Starting with .NET Framework 4.6.2, ASP.NET makes it easy to localize error messages. Error messages will be localized if: +Data annotation validators enable you to perform validation by adding one or more attributes to a class property. The attribute's element defines the text of the error message if validation fails. Starting with .NET Framework 4.6.2, ASP.NET makes it easy to localize error messages. Error messages will be localized if: -1. The is provided in the validation attribute. +1. The is provided in the validation attribute. 2. The resource file is stored in the App_LocalResources folder. 3. The name of the localized resources file has the form `DataAnnotation.Localization.{`*name*`}.resx`, where *name* is a culture name in the format *languageCode*`-`*country/regionCode* or *languageCode*. -4. The key name of the resource is the string assigned to the attribute, and its value is the localized error message. +4. The key name of the resource is the string assigned to the attribute, and its value is the localized error message. For example, the following data annotation attribute defines the default culture's error message for an invalid rating. @@ -912,7 +912,7 @@ Public Interface ISessionStateModule : Inherits IHttpModule End Interface ``` - In addition, the class includes two new methods, and , that can be used to support asynchronous operations. + In addition, the class includes two new methods, and , that can be used to support asynchronous operations. **Async support for output-cache providers** @@ -924,17 +924,17 @@ End Interface - The class, which provides helper methods for configuring the output cache. -- 18 new methods in the class. These include , , , , , , , , , , , , , , and . +- 18 new methods in the class. These include , , , , , , , , , , , , , , and . -- 2 new methods in the class: and . +- 2 new methods in the class: and . -- 2 new methods in the class: and . +- 2 new methods in the class: and . -- 2 new methods in the class: and . +- 2 new methods in the class: and . -- In the class, the method. +- In the class, the method. -- In the , the method. +- In the , the method. @@ -942,7 +942,7 @@ End Interface Characters in .NET Framework 4.6.2 are classified based on the [Unicode Standard, Version 8.0.0](https://www.unicode.org/versions/Unicode8.0.0/). In .NET Framework 4.6 and .NET Framework 4.6.1, characters were classified based on Unicode 6.3 character categories. -Support for Unicode 8.0 is limited to the classification of characters by the class and to types and methods that rely on it. These include the class, the overloaded method, and the [character classes](../../standard/base-types/character-classes-in-regular-expressions.md) recognized by the .NET Framework regular expression engine. Character and string comparison and sorting is unaffected by this change and continues to rely on the underlying operating system or, on Windows 7 systems, on character data provided by .NET Framework. +Support for Unicode 8.0 is limited to the classification of characters by the class and to types and methods that rely on it. These include the class, the overloaded method, and the [character classes](../../standard/base-types/character-classes-in-regular-expressions.md) recognized by the .NET Framework regular expression engine. Character and string comparison and sorting is unaffected by this change and continues to rely on the underlying operating system or, on Windows 7 systems, on character data provided by .NET Framework. For changes in character categories from Unicode 6.0 to Unicode 7.0, see [The Unicode Standard, Version 7.0.0](https://www.unicode.org/versions/Unicode7.0.0/) at The Unicode Consortium website. For changes from Unicode 7.0 to Unicode 8.0, see [The Unicode Standard, Version 8.0.0](https://www.unicode.org/versions/Unicode8.0.0/) at The Unicode Consortium website. @@ -956,7 +956,7 @@ For changes in character categories from Unicode 6.0 to Unicode 7.0, see [The Un In addition to supporting the larger key sizes of FIPS 186-3, .NET Framework 4.6.2 allows computing signatures with the SHA-2 family of hash algorithms (SHA256, SHA384, and SHA512). FIPS 186-3 support is provided by the new class. -In keeping with recent changes to the class in .NET Framework 4.6 and the class in .NET Framework 4.6.1, the abstract base class in .NET Framework 4.6.2 has additional methods to allow callers to use this functionality without casting. You can call the extension method to sign data, as the following example shows. +In keeping with recent changes to the class in .NET Framework 4.6 and the class in .NET Framework 4.6.1, the abstract base class in .NET Framework 4.6.2 has additional methods to allow callers to use this functionality without casting. You can call the extension method to sign data, as the following example shows. ```csharp public static byte[] SignDataDsaSha384(byte[] data, X509Certificate2 cert) @@ -976,7 +976,7 @@ Public Shared Function SignDataDsaSha384(data As Byte(), cert As X509Certificate End Function ``` -And you can call the extension method to verify signed data, as the following example shows. +And you can call the extension method to verify signed data, as the following example shows. ```csharp public static bool VerifyDataDsaSha384(byte[] data, byte[] signature, X509Certificate2 cert) @@ -1106,9 +1106,9 @@ The connection pool blocking period is always disabled. SQLClient introduces two enhancements for Always Encrypted: -- To improve performance of parameterized queries against encrypted database columns, encryption metadata for query parameters is now cached. With the property set to `true` (which is the default value), if the same query is called multiple times, the client retrieves parameter metadata from the server only once. +- To improve performance of parameterized queries against encrypted database columns, encryption metadata for query parameters is now cached. With the property set to `true` (which is the default value), if the same query is called multiple times, the client retrieves parameter metadata from the server only once. -- Column encryption key entries in the key cache are now evicted after a configurable time interval, set using the property. +- Column encryption key entries in the key cache are now evicted after a configurable time interval, set using the property. @@ -1177,9 +1177,9 @@ To enable this change, add the following app setting to your client application' When using NetTcp with transport security and a credential type of certificate, SSL 3.0 is no longer a default protocol used for negotiating a secure connection. In most cases, there should be no impact to existing apps, because TLS 1.0 is included in the protocol list for NetTcp. All existing clients should be able to negotiate a connection using at least TLS 1.0. If Ssl3 is required, use one of the following configuration mechanisms to add it to the list of negotiated protocols. -- The property +- The property -- The property +- The property - The [\](../configure-apps/file-schema/wcf/transport-of-nettcpbinding.md) section of the [\](../configure-apps/file-schema/wcf/nettcpbinding.md) section @@ -1195,7 +1195,7 @@ In .NET Framework 4.6.2, Windows Presentation Foundation has been enhanced in th An application that uses a object to group data can now explicitly declare how to sort the groups. Explicit sorting addresses the problem of non-intuitive ordering that occurs when an app dynamically adds or removes groups, or when it changes the value of item properties involved in grouping. It can also improve the performance of the group creation process by moving comparisons of the grouping properties from the sort of the full collection to the sort of the groups. -To support group sorting, the new and properties describe how to sort the collection of groups produced by the object. This is analogous to the way the identically named properties describe how to sort the data items. +To support group sorting, the new and properties describe how to sort the collection of groups produced by the object. This is analogous to the way the identically named properties describe how to sort the data items. Two new static properties of the class, and , can be used for the most common cases. @@ -1260,9 +1260,9 @@ If this scenario is not enabled, running the application continues to generate a **Workflow Improvements when using Dynamic Update with Visual Studio Workflow Designer** -The Workflow Designer, FlowChart Activity Designer, and other Workflow Activity Designers now successfully load and display workflows that have been saved after calling the method. In versions of the .NET Framework before .NET Framework 4.6.2, loading a XAML file in Visual Studio for a workflow that has been saved after calling can result in the following issues: +The Workflow Designer, FlowChart Activity Designer, and other Workflow Activity Designers now successfully load and display workflows that have been saved after calling the method. In versions of the .NET Framework before .NET Framework 4.6.2, loading a XAML file in Visual Studio for a workflow that has been saved after calling can result in the following issues: -- The Workflow Designer can't load the XAML file correctly (when the is at the end of the line). +- The Workflow Designer can't load the XAML file correctly (when the is at the end of the line). - Flowchart Activity Designer or other Workflow Activity Designers may display all objects in their default locations as opposed to attached property values. @@ -1346,9 +1346,9 @@ ADO.NET now supports storing Always Encrypted column master keys natively in Har Customers need to install the HSM vendor-provided CSP provider or CNG key store providers on the app servers or client computers in order to access Always Encrypted data protected with column master keys stored in an HSM. -**Improved connection behavior for AlwaysOn** +**Improved connection behavior for AlwaysOn** -SqlClient now automatically provides faster connections to an AlwaysOn Availability Group (AG). It transparently detects whether your application is connecting to an AlwaysOn availability group (AG) on a different subnet and quickly discovers the current active server and provides a connection to the server. Prior to this release, an application had to set the connection string to include `"MultisubnetFailover=true"` to indicate that it was connecting to an AlwaysOn Availability Group. Without setting the connection keyword to `true`, an application might experience a timeout while connecting to an AlwaysOn Availability Group. With this release, an application does *not* need to set to `true` anymore. For more information about SqlClient support for Always On Availability Groups, see [SqlClient Support for High Availability, Disaster Recovery](../data/adonet/sql/sqlclient-support-for-high-availability-disaster-recovery.md). +SqlClient now automatically provides faster connections to an AlwaysOn Availability Group (AG). It transparently detects whether your application is connecting to an AlwaysOn availability group (AG) on a different subnet and quickly discovers the current active server and provides a connection to the server. Prior to this release, an application had to set the connection string to include `"MultisubnetFailover=true"` to indicate that it was connecting to an AlwaysOn Availability Group. Without setting the connection keyword to `true`, an application might experience a timeout while connecting to an AlwaysOn Availability Group. With this release, an application does *not* need to set to `true` anymore. For more information about SqlClient support for Always On Availability Groups, see [SqlClient Support for High Availability, Disaster Recovery](../data/adonet/sql/sqlclient-support-for-high-availability-disaster-recovery.md). @@ -1403,17 +1403,17 @@ WPF includes a [NuGet package](https://www.nuget.org/packages/Microsoft.Wpf.Inte ### Windows Workflow Foundation: Transactions -The method can now use a distributed transaction manager other than MSDTC to promote the transaction. You do this by specifying a GUID transaction promoter identifier to the new overload . If this operation is successful, there are limitations placed on the capabilities of the transaction. Once a non-MSDTC transaction promoter is enlisted, the following methods throw a because these methods require promotion to MSDTC: +The method can now use a distributed transaction manager other than MSDTC to promote the transaction. You do this by specifying a GUID transaction promoter identifier to the new overload . If this operation is successful, there are limitations placed on the capabilities of the transaction. Once a non-MSDTC transaction promoter is enlisted, the following methods throw a because these methods require promotion to MSDTC: -- +- -- +- -- +- -- +- -Once a non-MSDTC transaction promoter is enlisted, it must be used for future durable enlistments by using protocols that it defines. The of the transaction promoter can be obtained by using the property. When the transaction promotes, the transaction promoter provides a array that represents the promoted token. An application can obtain the promoted token for a non-MSDTC promoted transaction with the method. +Once a non-MSDTC transaction promoter is enlisted, it must be used for future durable enlistments by using protocols that it defines. The of the transaction promoter can be obtained by using the property. When the transaction promotes, the transaction promoter provides a array that represents the promoted token. An application can obtain the promoted token for a non-MSDTC promoted transaction with the method. Users of the new overload must follow a specific call sequence in order for the promotion operation to complete successfully. These rules are documented in the method's documentation. @@ -1457,7 +1457,7 @@ With Ngen PDBs, NGen can create a PDB that contains the IL-to-native mapping wit - **Task-based API for Asynchronous Response Flushing** - ASP.NET now provides a simple task-based API for asynchronous response flushing, , that allows responses to be flushed asynchronously by using your language's `async/await` support. + ASP.NET now provides a simple task-based API for asynchronous response flushing, , that allows responses to be flushed asynchronously by using your language's `async/await` support. - **Model binding supports task-returning methods** @@ -1524,15 +1524,15 @@ With Ngen PDBs, NGen can create a PDB that contains the IL-to-native mapping wit - **IReadOnlyCollection\ implementations** - Additional collections implement such as and . + Additional collections implement such as and . - **CultureInfo.CurrentCulture and CultureInfo.CurrentUICulture** - The and properties are now read-write rather than read-only. If you assign a new object to these properties, the current thread culture defined by the `Thread.CurrentThread.CurrentCulture` property and the current UI thread culture defined by the `Thread.CurrentThread.CurrentUICulture` properties also change. + The and properties are now read-write rather than read-only. If you assign a new object to these properties, the current thread culture defined by the `Thread.CurrentThread.CurrentCulture` property and the current UI thread culture defined by the `Thread.CurrentThread.CurrentUICulture` properties also change. - **Enhancements to garbage collection (GC)** - The class now includes and methods that allow you to disallow garbage collection during the execution of a critical path. + The class now includes and methods that allow you to disallow garbage collection during the execution of a critical path. A new overload of the method allows you to control whether both the small object heap and the large object heap are swept and compacted or swept only. @@ -1566,13 +1566,13 @@ With Ngen PDBs, NGen can create a PDB that contains the IL-to-native mapping wit The following new methods have been added to the structure to support converting date and time values to or from Unix time: - - + - - - + - - - + - - - + - - **Compatibility switches** @@ -1636,13 +1636,13 @@ With Ngen PDBs, NGen can create a PDB that contains the IL-to-native mapping wit - **Changes to the task-based asynchronous pattern (TAP)** - For apps that target .NET Framework 4.6, and objects inherit the culture and UI culture of the calling thread. The behavior of apps that target previous versions of .NET Framework, or that do not target a specific version of .NET Framework, is unaffected. For more information, see the "Culture and task-based asynchronous operations" section of the class topic. + For apps that target .NET Framework 4.6, and objects inherit the culture and UI culture of the calling thread. The behavior of apps that target previous versions of .NET Framework, or that do not target a specific version of .NET Framework, is unaffected. For more information, see the "Culture and task-based asynchronous operations" section of the class topic. - The class allows you to represent ambient data that is local to a given asynchronous control flow, such as an `async` method. It can be used to persist data across threads. You can also define a callback method that is notified whenever the ambient data changes either because the property was explicitly changed, or because the thread encountered a context transition. + The class allows you to represent ambient data that is local to a given asynchronous control flow, such as an `async` method. It can be used to persist data across threads. You can also define a callback method that is notified whenever the ambient data changes either because the property was explicitly changed, or because the thread encountered a context transition. - Three convenience methods, , , and , have been added to the task-based asynchronous pattern (TAP) to return completed tasks in a particular state. + Three convenience methods, , , and , have been added to the task-based asynchronous pattern (TAP) to return completed tasks in a particular state. - The class now supports asynchronous communication with its new . method. + The class now supports asynchronous communication with its new . method. - **EventSource now supports writing to the Event log** @@ -1662,7 +1662,7 @@ With Ngen PDBs, NGen can create a PDB that contains the IL-to-native mapping wit Causes Start and Stop events to tag events between them with an ID that represents all currently active activities. - To support these features, the overloaded method has been added to the class. + To support these features, the overloaded method has been added to the class. - **Windows Presentation Foundation (WPF)** @@ -1696,7 +1696,7 @@ With Ngen PDBs, NGen can create a PDB that contains the IL-to-native mapping wit - **SSL support** - WCF now supports SSL version TLS 1.1 and TLS 1.2, in addition to SSL 3.0 and TLS 1.0, when using NetTcp with transport security and client authentication. It is now possible to select which protocol to use, or to disable old lesser secure protocols. This can be done either by setting the property or by adding the following to a configuration file. + WCF now supports SSL version TLS 1.1 and TLS 1.2, in addition to SSL 3.0 and TLS 1.0, when using NetTcp with transport security and client authentication. It is now possible to select which protocol to use, or to disable old lesser secure protocols. This can be done either by setting the property or by adding the following to a configuration file. ```xml @@ -1717,7 +1717,7 @@ With Ngen PDBs, NGen can create a PDB that contains the IL-to-native mapping wit - **Using a connection group name prefix** - Users can specify a string that WCF will use as a prefix for the connection group name. Two messages with different prefixes are sent using different underlying HTTP connections. You set the prefix by adding a key/value pair to the message's property. The key is "HttpTransportConnectionGroupNamePrefix"; the value is the desired prefix. + Users can specify a string that WCF will use as a prefix for the connection group name. Two messages with different prefixes are sent using different underlying HTTP connections. You set the prefix by adding a key/value pair to the message's property. The key is "HttpTransportConnectionGroupNamePrefix"; the value is the desired prefix. - **Using different channel factories** @@ -1767,19 +1767,19 @@ With Ngen PDBs, NGen can create a PDB that contains the IL-to-native mapping wit - The enumeration value. - - The property. + - The property. - By default, the property is `false` unless the `HWRPortReuseOnSocketBind` value of the `HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319` registry key is set to 0x1. To enable local port reuse on HTTP connections, set the property to `true`. This causes all outgoing TCP socket connections from and to use a new Windows 10 socket option, [SO_REUSE_UNICASTPORT](/windows/desktop/WinSock/sol-socket-socket-options), that enables local port reuse. + By default, the property is `false` unless the `HWRPortReuseOnSocketBind` value of the `HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319` registry key is set to 0x1. To enable local port reuse on HTTP connections, set the property to `true`. This causes all outgoing TCP socket connections from and to use a new Windows 10 socket option, [SO_REUSE_UNICASTPORT](/windows/desktop/WinSock/sol-socket-socket-options), that enables local port reuse. - Developers writing a sockets-only application can specify the option when calling a method such as so that outbound sockets reuse local ports during binding. + Developers writing a sockets-only application can specify the option when calling a method such as so that outbound sockets reuse local ports during binding. - **Support for international domain names and PunyCode** - A new property, , has been added to the class to better support international domain names and PunyCode. + A new property, , has been added to the class to better support international domain names and PunyCode. - **Resizing in Windows Forms controls.** - This feature has been expanded in .NET Framework 4.6 to include the , , , and types and the rectangle specified by the property used when drawing a . + This feature has been expanded in .NET Framework 4.6 to include the , , , and types and the rectangle specified by the property used when drawing a . This is an opt-in feature. To enable it, set the `EnableWindowsFormsHighDpiAutoResizing` element to `true` in the application configuration (app.config) file: @@ -1791,7 +1791,7 @@ With Ngen PDBs, NGen can create a PDB that contains the IL-to-native mapping wit - **Support for code page encodings** - .NET Core primarily supports the Unicode encodings and by default provides limited support for code page encodings. You can add support for code page encodings available in .NET Framework but unsupported in .NET Core by registering code page encodings with the method. For more information, see . + .NET Core primarily supports the Unicode encodings and by default provides limited support for code page encodings. You can add support for code page encodings available in .NET Framework but unsupported in .NET Core by registering code page encodings with the method. For more information, see . - **.NET Native** @@ -1809,11 +1809,11 @@ Universal Windows Platform (UWP) apps that are written in C# or Visual Basic can ## What's new in .NET Framework 4.5.2 -- **New APIs for ASP.NET apps.** The new and methods let you inspect and modify response headers and status code as the response is being flushed to the client app. Consider using these methods instead of the and events; they are more efficient and reliable. +- **New APIs for ASP.NET apps.** The new and methods let you inspect and modify response headers and status code as the response is being flushed to the client app. Consider using these methods instead of the and events; they are more efficient and reliable. - The method lets you schedule small background work items. ASP.NET tracks these items and prevents IIS from abruptly terminating the worker process until all background work items have completed. This method can't be called outside an ASP.NET managed app domain. + The method lets you schedule small background work items. ASP.NET tracks these items and prevents IIS from abruptly terminating the worker process until all background work items have completed. This method can't be called outside an ASP.NET managed app domain. - The new and properties return Boolean values that indicate whether the response headers have been written. You can use these properties to make sure that calls to APIs such as (which throw exceptions if the headers have been written) will succeed. + The new and properties return Boolean values that indicate whether the response headers have been written. You can use these properties to make sure that calls to APIs such as (which throw exceptions if the headers have been written) will succeed. - **Resizing in Windows Forms controls.** This feature has been expanded. You can now use the system DPI setting to resize components of the following additional controls (for example, the drop-down arrow in combo boxes): @@ -1832,7 +1832,7 @@ Universal Windows Platform (UWP) apps that are written in C# or Visual Basic can ``` -- **New workflow feature.** A resource manager that's using the method (and therefore implementing the interface) can use the new method to request the following: +- **New workflow feature.** A resource manager that's using the method (and therefore implementing the interface) can use the new method to request the following: - Promote the transaction to a Microsoft Distributed Transaction Coordinator (MSDTC) transaction. @@ -1864,7 +1864,7 @@ Universal Windows Platform (UWP) apps that are written in C# or Visual Basic can - **Promoting a transaction and converting it to a durable enlistment** - is a new API added to .NET Framework 4.5.2 and 4.6: + is a new API added to .NET Framework 4.5.2 and 4.6: ```csharp [System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.LinkDemand, Name = "FullTrust")] @@ -1882,7 +1882,7 @@ Universal Windows Platform (UWP) apps that are written in C# or Visual Basic can enlistmentOptions As EnlistmentOptions) As Enlistment ``` - The method may be used by an enlistment that was previously created by in response to the method. It asks `System.Transactions` to promote the transaction to an MSDTC transaction and to "convert" the promotable enlistment to a durable enlistment. After this method completes successfully, the interface will no longer be referenced by `System.Transactions`, and any future notifications will arrive on the provided interface. The enlistment in question must act as a durable enlistment, supporting transaction logging and recovery. Refer to for details. In addition, the enlistment must support . This method can *only* be called while processing an call. If that is not the case, a exception is thrown. + The method may be used by an enlistment that was previously created by in response to the method. It asks `System.Transactions` to promote the transaction to an MSDTC transaction and to "convert" the promotable enlistment to a durable enlistment. After this method completes successfully, the interface will no longer be referenced by `System.Transactions`, and any future notifications will arrive on the provided interface. The enlistment in question must act as a durable enlistment, supporting transaction logging and recovery. Refer to for details. In addition, the enlistment must support . This method can *only* be called while processing an call. If that is not the case, a exception is thrown. @@ -1910,9 +1910,9 @@ New features and enhancements in the base classes in .NET Framework 4.5.1 includ - Automatic binding redirection for assemblies. Starting with Visual Studio 2013, when you compile an app that targets .NET Framework 4.5.1, binding redirects may be added to the app configuration file if your app or its components reference multiple versions of the same assembly. You can also enable this feature for projects that target older versions of .NET Framework. For more information, see [How to: Enable and Disable Automatic Binding Redirection](../configure-apps/how-to-enable-and-disable-automatic-binding-redirection.md). -- Ability to collect diagnostics information to help developers improve the performance of server and cloud applications. For more information, see the and methods in the class. +- Ability to collect diagnostics information to help developers improve the performance of server and cloud applications. For more information, see the and methods in the class. -- Ability to explicitly compact the large object heap (LOH) during garbage collection. For more information, see the property. +- Ability to explicitly compact the large object heap (LOH) during garbage collection. For more information, see the property. - Additional performance improvements such as ASP.NET app suspension, multi-core JIT improvements, and faster app startup after a .NET Framework update. For details, see the [.NET Framework 4.5.1 announcement](https://devblogs.microsoft.com/dotnet/announcing-the-net-framework-4-5-1-preview/) and the [ASP.NET app suspend](https://devblogs.microsoft.com/dotnet/asp-net-app-suspend-responsive-shared-net-web-hosting/) blog post. @@ -1960,7 +1960,7 @@ For new features in ASP.NET 4.5.1, see [ASP.NET and Web Tools for Visual Studio - Background just-in-time (JIT) compilation, which is optionally available on multi-core processors to improve application performance. See . -- Ability to limit how long the regular expression engine will attempt to resolve a regular expression before it times out. See the property. +- Ability to limit how long the regular expression engine will attempt to resolve a regular expression before it times out. See the property. - Ability to define the default culture for an application domain. See the class. diff --git a/docs/framework/whats-new/obsolete-members.md b/docs/framework/whats-new/obsolete-members.md index 262833542dd19..aaf009023317b 100644 --- a/docs/framework/whats-new/obsolete-members.md +++ b/docs/framework/whats-new/obsolete-members.md @@ -20,166 +20,166 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||The registry key only works on Win9x, which is no longer supported by the CLR. On NT-based operating systems, use the registry key or the registry proxy instead.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use Evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> ||| has been deprecated. Investigate the use of instead.| -> ||| has been deprecated. Investigate the use of instead.| -> ||| has been deprecated. Investigate the use of instead.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||The registry key only works on Win9x, which is no longer supported by the CLR. On NT-based operating systems, use the registry key or the registry proxy instead.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use Evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> ||| has been deprecated. Investigate the use of instead.| +> ||| has been deprecated. Investigate the use of instead.| +> ||| has been deprecated. Investigate the use of instead.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| > |||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| > |||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| > |||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| > |||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| > |||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| > |||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| > |||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> ||| has been deprecated because it doesn't provide a stable ID when managed threads are running on fibers (also known as lightweight threads). To get a stable identifier for a managed thread, use the property.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> ||| policy levels are obsolete and will be removed in a future release of the .NET Framework.| -> ||| has been deprecated. Investigate the use of instead.| -> ||| has been deprecated. Investigate the use of instead.| -> ||| has been deprecated. Investigate the use of instead.| -> ||| has been deprecated. Investigate the use of instead.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> ||| has been deprecated because it doesn't provide a stable ID when managed threads are running on fibers (also known as lightweight threads). To get a stable identifier for a managed thread, use the property.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> ||| policy levels are obsolete and will be removed in a future release of the .NET Framework.| +> ||| has been deprecated. Investigate the use of instead.| +> ||| has been deprecated. Investigate the use of instead.| +> ||| has been deprecated. Investigate the use of instead.| +> ||| has been deprecated. Investigate the use of instead.| > |||The `provider` argument isn't used. Use .| > |||The `provider` argument isn't used. Use .| -> |||This method has been deprecated. Use instead.| -> |||This method has been deprecated. Use instead.| +> |||This method has been deprecated. Use instead.| +> |||This method has been deprecated. Use instead.| > |||Use instead.| > |||Use instead.| > |||Use instead.| > |||Use instead.| -> |||Use the property.| -> |||Use `KeyComparer` properties.| +> |||Use the property.| +> |||Use `KeyComparer` properties.| > |||Use instead.| -> |||The class has been deprecated.| +> |||The class has been deprecated.| > |||The class has been deprecated.| > |||The class has been deprecated.| -> |||The class has been deprecated.| +> |||The class has been deprecated.| > |||The class has been deprecated.| -> |||The class has been deprecated.| -> |||The class has been deprecated.| -> |||Don't create instances of the class. Call the static methods directly on this type instead.| +> |||The class has been deprecated.| +> |||The class has been deprecated.| +> |||Don't create instances of the class. Call the static methods directly on this type instead.| > |||First deprecated in the .NET Framework 4.5.

This constructor has been deprecated. Use a constructor that doesn't require a parameter.| -> |||The recommended alternative is , which takes the importer interface pointer as an instead of an , and thus works on both 32-bit and 64-bit architectures.| +> |||The recommended alternative is , which takes the importer interface pointer as an instead of an , and thus works on both 32-bit and 64-bit architectures.| > |||This value has been deprecated. Use other values in .| > |||This value has been deprecated. Use other values in .| > |||This constructor has been deprecated. Use instead.| > |||This constructor has been deprecated. Use instead, and optionally make a new with `ownsHandle`= `false` if needed.| > |||This constructor has been deprecated. Use instead, and optionally make a new with `ownsHandle`= `false` if needed.| > |||This constructor has been deprecated. Use instead, and optionally make a new with `ownsHandle`= `false` if needed.| -> |||This property has been deprecated. Use the property instead.| -> |||Use or instead.| -> ||| will be removed eventually. Use `new ManualResetEvent(false)` instead.| -> |||First deprecated in the .NET Framework 4.5.

Don't call or override this method.| -> ||| has been deprecated because it isn't CLS Compliant. To get the current size, use .| -> ||| has been deprecated because it isn't CLS Compliant. To get the maximum size, use .| -> ||| has been deprecated because it isn't CLS Compliant. To get the current size, use .| -> ||| has been deprecated because it isn't CLS Compliant. To get the maximum size, use .| -> |||This property has been deprecated. Use the property instead.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||This method has been deprecated. Use instead.| -> |||This method has been deprecated. Use instead.| +> |||This property has been deprecated. Use the property instead.| +> |||Use or instead.| +> ||| will be removed eventually. Use `new ManualResetEvent(false)` instead.| +> |||First deprecated in the .NET Framework 4.5.

Don't call or override this method.| +> ||| has been deprecated because it isn't CLS Compliant. To get the current size, use .| +> ||| has been deprecated because it isn't CLS Compliant. To get the maximum size, use .| +> ||| has been deprecated because it isn't CLS Compliant. To get the current size, use .| +> ||| has been deprecated because it isn't CLS Compliant. To get the maximum size, use .| +> |||This property has been deprecated. Use the property instead.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||This method has been deprecated. Use instead.| +> |||This method has been deprecated. Use instead.| > |||This constructor has been deprecated. Use instead.| > |||This constructor has been deprecated. Use instead.| -> |||This property has been deprecated. Use instead.| +> |||This property has been deprecated. Use instead.| > |||This property has been deprecated.| -> |||An alternate API is available: Emit the custom attribute instead.| +> |||An alternate API is available: Emit the custom attribute instead.| > |||This API has been deprecated.| -> |||An alternate API is available: Emit the custom attribute instead.| +> |||An alternate API is available: Emit the custom attribute instead.| > |||This API has been deprecated.| > |||This API has been deprecated.| -> |||An alternate API is available: Emit the custom attribute instead.| +> |||An alternate API is available: Emit the custom attribute instead.| > |||Call instead.| -> |||The method has been deprecated and will be removed in a future release.| -> |||The method has been deprecated. Use the hosting API to perform this operation.| +> |||The method has been deprecated and will be removed in a future release.| +> |||The method has been deprecated. Use the hosting API to perform this operation.| > |||Use instead.| > |||Use instead.| > |||Use instead.| > |||Use instead.| -> |||The method has been deprecated and will be removed in a future release.| -> |||This API didn't perform any operation and will be removed in future versions of the CLR.| -> |||Use of this member generates a compiler error.

Don't create instances of the class. Call the static methods directly on this type instead.| -> |||Use instead.| -> |||Use of this member generates a compiler error.

Don't create instances of the class. Call the static methods directly on this type instead.| +> |||The method has been deprecated and will be removed in a future release.| +> |||This API didn't perform any operation and will be removed in future versions of the CLR.| +> |||Use of this member generates a compiler error.

Don't create instances of the class. Call the static methods directly on this type instead.| +> |||Use instead.| +> |||Use of this member generates a compiler error.

Don't create instances of the class. Call the static methods directly on this type instead.| > |||Use instead.| -> |||Use of this method isn't recommended. The existed for internal diagnostic purposes only.| -> ||| is obsolete and will be removed in a future release of the .NET Framework.| -> ||| is obsolete and will be removed in a future release of the .NET Framework.| +> |||Use of this method isn't recommended. The existed for internal diagnostic purposes only.| +> ||| is obsolete and will be removed in a future release of the .NET Framework.| +> ||| is obsolete and will be removed in a future release of the .NET Framework.| > |||AppDomain policy levels are obsolete and will be removed in a future release of the .NET Framework.| > |||AppDomain policy levels are obsolete and will be removed in a future release of the .NET Framework.| -> |||This method is obsolete and should no longer be used.| -> ||| is obsolete and will be removed in a future release of the .NET Framework.| -> ||| is only used for .NET Framework 2.0 transparency compatibility.| +> |||This method is obsolete and should no longer be used.| +> ||| is obsolete and will be removed in a future release of the .NET Framework.| +> ||| is only used for .NET Framework 2.0 transparency compatibility.| > |||Because execution permission checks can no longer be turned off, the property no longer has any effect.| -> ||| is obsolete and will be removed in a future release of the .NET Framework. Use either the property or the property instead.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework.| +> ||| is obsolete and will be removed in a future release of the .NET Framework. Use either the property or the property instead.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework.| > |||This method is obsolete and will be removed in a future release of the .NET Framework.| > |||This method is obsolete and will be removed in a future release of the .NET Framework.| > |||This method is obsolete and will be removed in a future release of the .NET Framework.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework.| -> |||Because security can no longer be turned off, the property no longer has any effect.| -> ||| replaces for deriving key material from a password and is preferred in new applications.| -> |||This method has been deprecated. Use the property instead.| -> |||This method has been deprecated. Use the property instead.| -> |||Use the property instead.| -> |||This permission is no longer used by the CLR.| -> |||This API has been deprecated.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework.| +> |||Because security can no longer be turned off, the property no longer has any effect.| +> ||| replaces for deriving key material from a password and is preferred in new applications.| +> |||This method has been deprecated. Use the property instead.| +> |||This method has been deprecated. Use the property instead.| +> |||Use the property instead.| +> |||This permission is no longer used by the CLR.| +> |||This API has been deprecated.| > |||This permission has been deprecated. The enumeration member doesn't include . Use to get full access.| > |||This permission is no longer used by the CLR.| > |||This API has been deprecated.| -> |||Use the property instead.| +> |||Use the property instead.| > ||| is obsolete and will be removed in a future release of the .NET Framework.| > |||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| > |||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| > |||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -> |||This method is obsolete. Use instead.| -> |||This method is obsolete. Use instead.| -> |||Evidence should not be treated as an . Use the and methods rather than using .| -> |||Evidence should not be treated as an . Use and to iterate over the evidence to collect a count.| +> |||This method is obsolete. Use instead.| +> |||This method is obsolete. Use instead.| +> |||Evidence should not be treated as an . Use the and methods rather than using .| +> |||Evidence should not be treated as an . Use and to iterate over the evidence to collect a count.| > |||This constructor is obsolete. Use the constructor instead.| -> ||| is obsolete. Use and instead.| +> ||| is obsolete. Use and instead.| > |||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they're trusted.| > |||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they're trusted.| -> |||AppDomain policy levels are obsolete and will be removed in a future release of the .NET Framework.| -> |||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they're trusted.| +> |||AppDomain policy levels are obsolete and will be removed in a future release of the .NET Framework.| +> |||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they're trusted.| > |||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they're trusted.| > |||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they're trusted.| -> |||This property isn't 64-bit compatible. Use instead.| +> |||This property isn't 64-bit compatible. Use instead.| > |||This constructor isn't 64-bit compatible. Use the constructor that takes an for the event handle.| > |||This method isn't safe. Use instead.| > |||This method isn't safe. Use instead.| -> |||The property has been deprecated. Use , or instead.| -> ||| is no longer supported. Use the class.| -> ||| has been deprecated. Use other classes in , such as , , , and to synchronize threads or protect resources.| -> ||| is no longer supported. Use the class.| -> ||| has been deprecated. Use other classes in , such as , , , and , to synchronize threads or protect resources.| +> |||The property has been deprecated. Use , or instead.| +> ||| is no longer supported. Use the class.| +> ||| has been deprecated. Use other classes in , such as , , , and to synchronize threads or protect resources.| +> ||| is no longer supported. Use the class.| +> ||| has been deprecated. Use other classes in , such as , , , and , to synchronize threads or protect resources.| > ||| has been deprecated. Use instead.| -> |||Use the property instead.| +> |||Use the property instead.| ## PresentationCore.dll @@ -187,40 +187,40 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> ||| is an obsolete property and may be removed in a future release. The value of this property isn't defined.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> ||| is an obsolete property and may be removed in a future release. The value of this property isn't defined.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| > |||Use the PixelsPerDip override.| > |||Use the PixelsPerDip override.| > |||Use the PixelsPerDip override.| > |||Use the PixelsPerDip override.| > |||Use the PixelsPerDip override.| -> |||This property is deprecated. Use the static method instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||This property is deprecated. Use the static method instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +> |||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| ## PresentationFramework.dll @@ -228,10 +228,10 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||Replaced by .| -> |||Replaced by .| -> |||Replaced by .| -> |||Replaced by .| +> |||Replaced by .| +> |||Replaced by .| +> |||Replaced by .| +> |||Replaced by .| ## System.Activities.dll @@ -250,13 +250,13 @@ This article doesn't list the members of obsolete types. For a list of obsolete > |----------|------------|-------------| > |||This method doesn't support dragging multiple items.| > |||First deprecated in the .NET Framework 4.5.

This method doesn't support dragging multiple items. Use instead.| -> |||This method doesn't support dragging multiple items.| -> |||First deprecated in the .NET Framework 4.5.

This method doesn't support dragging multiple items. Use instead.| -> |||First deprecated in the .NET Framework 4.5.

This method doesn't support dragging multiple items. Use instead.| -> |||This method doesn't support dragging multiple items.| -> |||First deprecated in the .NET Framework 4.5.

Don't use this property. Use instead.| -> |||First deprecated in the .NET Framework 4.5.

Don't use this property. Use instead.| -> |||First deprecated in the .NET Framework 4.5.

Don't use this property. Use instead.| +> |||This method doesn't support dragging multiple items.| +> |||First deprecated in the .NET Framework 4.5.

This method doesn't support dragging multiple items. Use instead.| +> |||First deprecated in the .NET Framework 4.5.

This method doesn't support dragging multiple items. Use instead.| +> |||This method doesn't support dragging multiple items.| +> |||First deprecated in the .NET Framework 4.5.

Don't use this property. Use instead.| +> |||First deprecated in the .NET Framework 4.5.

Don't use this property. Use instead.| +> |||First deprecated in the .NET Framework 4.5.

Don't use this property. Use instead.| ## System.Core.dll @@ -265,42 +265,42 @@ This article doesn't list the members of obsolete types. For a list of obsolete > |Type|Member|Message| > |----------|------------|-------------| > |||First deprecated in the .NET Framework 4.5.

Incorrect value; use instead.| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -> |||Use a different constructor that doesn't take an argument. Then override the and properties to provide the values that would be specified to this constructor.| -> |||Don't use this constructor. It will be removed in future releases.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +> |||Use a different constructor that doesn't take an argument. Then override the and properties to provide the values that would be specified to this constructor.| +> |||Don't use this constructor. It will be removed in future releases.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| > |||Use of this member generates a compiler error.

Don't use this method.| > |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| ## System.Data.dll @@ -308,22 +308,22 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> ||| has been deprecated.| -> ||| has been deprecated. Use the constructor.| +> ||| has been deprecated.| +> ||| has been deprecated. Use the constructor.| > |||Use of this member generates a compiler error.

This constructor has been deprecated. Pass the constructor a value of .| > |||Use of this member generates a compiler error.

This constructor has been deprecated. Pass the constructor a value of .| > ||| has been deprecated. Use .| > |||Use of this member generates a compiler error.

has been deprecated. Pass the constructor a value of .| > |||Use of this member generates a compiler error.

has been deprecated. Pass the constructor a value of .| -> ||| has been deprecated. Use the method.| +> ||| has been deprecated. Use the method.| > |||Use of this member generates a compiler error.

has been deprecated. Pass the a value of .| > |||Use of this member generates a compiler error.

has been deprecated. Pass the a value of .| -> |||The property has been deprecated. Use the method.| -> |||The property has been deprecated. Use the method.| +> |||The property has been deprecated. Use the method.| +> |||The property has been deprecated. Use the method.| > |||Use of this constructor generates a compiler error.

has been deprecated. Pass the constructor a value of .| > |||Use of this constructor generates a compiler error.

has been deprecated. Pass the constructor a value of .| > ||| has been deprecated. will ignore the 'connection reset' keyword and always reset the connection.| -> ||| has been deprecated. Use .| +> ||| has been deprecated. Use .| ## System.Data.Entity.dll @@ -331,9 +331,9 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||This property is going away, Use the property instead.| -> |||First deprecated in the .NET Framework 4.5.

Use instead.| -> |||Use instead.| +> |||This property is going away, Use the property instead.| +> |||First deprecated in the .NET Framework 4.5.

Use instead.| +> |||Use instead.| > |||Use instead.| ## System.Data.OracleClient.dll @@ -342,9 +342,9 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> ||| has been deprecated. Use the classes to explicitly set the precision of a decimal.| -> ||| has been deprecated. Use the classes to explicitly set the scale of a decimal.| -> ||| has been deprecated. Use .| +> ||| has been deprecated. Use the classes to explicitly set the precision of a decimal.| +> ||| has been deprecated. Use the classes to explicitly set the scale of a decimal.| +> ||| has been deprecated. Use .| ## System.Design.dll @@ -352,53 +352,53 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||This method has been deprecated. Use instead.| -> |||This method has been deprecated. Use instead.| -> |||The method has been replaced by .| -> |||This method has been deprecated. Use or instead.| -> |||Use of this property generates a compiler error.

Error: This property can no longer be referenced, and is included to support existing compiled applications. The design\-time element view architecture is no longer used.| -> |||The recommended alternative is to use [`ControlDesigner.SetViewFlags(ViewFlags.DesignTimeHtmlRequiresLoadComplete, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||The recommended alternative is .| +> |||This method has been deprecated. Use instead.| +> |||This method has been deprecated. Use instead.| +> |||The method has been replaced by .| +> |||This method has been deprecated. Use or instead.| +> |||Use of this property generates a compiler error.

Error: This property can no longer be referenced, and is included to support existing compiled applications. The design\-time element view architecture is no longer used.| +> |||The recommended alternative is to use [`ControlDesigner.SetViewFlags(ViewFlags.DesignTimeHtmlRequiresLoadComplete, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||The recommended alternative is .| > |||The recommended alternative is to use [`ControlDesigner.Tag.SetDirty`](xref:System.Web.UI.Design.IControlDesignerTag.SetDirty%2A) and [`ControlDesigner.Tag.IsDirty`](xref:System.Web.UI.Design.IControlDesignerTag.IsDirty%2A).| -> |||The recommended alternative is [`ControlDesigner.DataBindings.Contains`](xref:System.Web.UI.DataBindingCollection.Contains%2A). The class allows more control of the data bindings associated with the control.| -> |||The recommended alternative is to handle the `ControlDesigner.DataBindings.Changed` event. The collection returned by the [`ControlDesigner.DataBindings`](xref:System.Web.UI.Design.HtmlControlDesigner.DataBindings%2A) property allows more control of the data bindings associated with the control.| -> |||The recommended alternative is , which is called when any property of the control is changed.| -> |||Use of this method isn't recommended because resizing is handled by the method.| +> |||The recommended alternative is [`ControlDesigner.DataBindings.Contains`](xref:System.Web.UI.DataBindingCollection.Contains%2A). The class allows more control of the data bindings associated with the control.| +> |||The recommended alternative is to handle the `ControlDesigner.DataBindings.Changed` event. The collection returned by the [`ControlDesigner.DataBindings`](xref:System.Web.UI.Design.HtmlControlDesigner.DataBindings%2A) property allows more control of the data bindings associated with the control.| +> |||The recommended alternative is , which is called when any property of the control is changed.| +> |||Use of this method isn't recommended because resizing is handled by the method.| > |||The recommended alternative is to inherit from instead and to use an . Regions allow for better control of the content in the designer.| -> |||The recommended alternative is .| -> |||Use of this property generates a compiler error.

Error: This property can no longer be referenced, and is included to support existing compiled applications. The design\-time element may not always provide access to the element in the markup. There are alternate methods on for handling client script and controls.| -> |||The recommended alternative is .| -> |||The recommended alternative is .| -> |||The recommended alternative is to handle the [HtmlControlDesigner.DataBindings.Changed](xref:System.Web.UI.DataBindingCollection.Changed) event. The collection returned by the property allows more control of the data bindings associated with the control.| +> |||The recommended alternative is .| +> |||Use of this property generates a compiler error.

Error: This property can no longer be referenced, and is included to support existing compiled applications. The design\-time element may not always provide access to the element in the markup. There are alternate methods on for handling client script and controls.| +> |||The recommended alternative is .| +> |||The recommended alternative is .| +> |||The recommended alternative is to handle the [HtmlControlDesigner.DataBindings.Changed](xref:System.Web.UI.DataBindingCollection.Changed) event. The collection returned by the property allows more control of the data bindings associated with the control.| > |||Use of this property isn't recommended because code serialization isn't supported.| -> |||Use of this property isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||The recommended alternative is .| -> |||The recommended alternative is .| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because the **AutoFormat** dialog is launched by the designer host. The list of available AutoFormats is exposed by the property.| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| -> |||The recommended alternative is .| -> |||This method has been deprecated. Use instead.| +> |||Use of this property isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||The recommended alternative is .| +> |||The recommended alternative is .| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because the **AutoFormat** dialog is launched by the designer host. The list of available AutoFormats is exposed by the property.| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||Use of this method isn't recommended because template editing is handled in . To support template editing, expose template data in the property and call [`ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`](xref:System.Web.UI.Design.ControlDesigner.SetViewFlags%2A).| +> |||The recommended alternative is .| +> |||This method has been deprecated. Use instead.| ## System.dll @@ -406,35 +406,35 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||Callers should not use the interface and should instead use the methods directly on the class.| -> |||Callers should not use the interface and should instead use the methods directly on the class.| -> |||Callers should not use the interface and should instead use the methods directly on the class.| -> |||Callers should not use the interface and should instead use the methods directly on the class.| +> |||Callers should not use the interface and should instead use the methods directly on the class.| +> |||Callers should not use the interface and should instead use the methods directly on the class.| +> |||Callers should not use the interface and should instead use the methods directly on the class.| +> |||Callers should not use the interface and should instead use the methods directly on the class.| > |||This event has been deprecated.| -> |||The method has been deprecated. It isn't used by the system.| -> |||The method has been deprecated. It isn't used by the system.| -> |||The method has been deprecated. It isn't used by the system.| -> |||The method has been deprecated. Use the method or the static method to escape a Uri component or a string.| -> |||The method has been deprecated. It isn't used by the system.| -> |||The method has been deprecated. It isn't used by the system.| -> |||The method has been deprecated. It isn't used by the system.| -> |||The method has been deprecated. Use .| -> |||The method has been deprecated. It isn't used by the system.| -> |||The method has been deprecated. Use the method or the static method to escape a Uri component or a string.| +> |||The method has been deprecated. It isn't used by the system.| +> |||The method has been deprecated. It isn't used by the system.| +> |||The method has been deprecated. It isn't used by the system.| +> |||The method has been deprecated. Use the method or the static method to escape a Uri component or a string.| +> |||The method has been deprecated. It isn't used by the system.| +> |||The method has been deprecated. It isn't used by the system.| +> |||The method has been deprecated. It isn't used by the system.| +> |||The method has been deprecated. Use .| +> |||The method has been deprecated. It isn't used by the system.| +> |||The method has been deprecated. Use the method or the static method to escape a Uri component or a string.| > |||The constructor has been deprecated. Use . The `dontEscape` parameter is deprecated and is always `false`.| > |||The constructor has been deprecated. Use . The `dontEscape` parameter is deprecated and is always `false`.| -> |||Callers should not use the interface and should instead use the methods directly on the class. Those inheriting from must still implement this interface, and should exclude this warning or also obsolete this method.| -> |||Callers should not use the interface and should instead use the methods directly on the class. Those inheriting from must still implement this interface, and should exclude this warning or also obsolete this method.| -> |||Callers should not use the interface and should instead use the methods directly on the class. Those inheriting from must still implement this interface, and should exclude this warning or also obsolete this method.| -> |||CAS policy is obsolete and will be removed in a future release of the .NET Framework. For more information, see [Security Changes in the .NET Framework 4](/previous-versions/dotnet/netframework-4.0/ee191568(v=vs.100)).| -> |||CAS policy is obsolete and will be removed in a future release of the .NET Framework. For more information, see [Security Changes in the .NET Framework 4](/previous-versions/dotnet/netframework-4.0/ee191568(v=vs.100)).| +> |||Callers should not use the interface and should instead use the methods directly on the class. Those inheriting from must still implement this interface, and should exclude this warning or also obsolete this method.| +> |||Callers should not use the interface and should instead use the methods directly on the class. Those inheriting from must still implement this interface, and should exclude this warning or also obsolete this method.| +> |||Callers should not use the interface and should instead use the methods directly on the class. Those inheriting from must still implement this interface, and should exclude this warning or also obsolete this method.| +> |||CAS policy is obsolete and will be removed in a future release of the .NET Framework. For more information, see [Security Changes in the .NET Framework 4](/previous-versions/dotnet/netframework-4.0/ee191568(v=vs.100)).| +> |||CAS policy is obsolete and will be removed in a future release of the .NET Framework. For more information, see [Security Changes in the .NET Framework 4](/previous-versions/dotnet/netframework-4.0/ee191568(v=vs.100)).| > |||Use instead.| > |||Use instead.| > |||Use instead.| > |||Use instead.| > |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| -> |||This method has been deprecated. Use instead.| -> |||This property has been deprecated. Use a type description provider to supply type information for COM types instead.| +> |||This method has been deprecated. Use instead.| +> |||This property has been deprecated. Use a type description provider to supply type information for COM types instead.| > |||This constructor is obsolete. Use instead.| > |||This value has been deprecated. Use instead.| > |||This value has been deprecated. It is no longer supported.| @@ -450,68 +450,68 @@ This article doesn't list the members of obsolete types. For a list of obsolete > |||This class is obsolete. To create a new exception, create a .| > |||This class is obsolete. To create a new exception, create a .| > |||This class is obsolete. To create a new exception, create a .| -> |||This class is obsolete. Use instead.| -> |||This class is obsolete. Use instead| -> |||This method is obsolete. It has been replaced by .| -> |||This method is obsolete. It has been replaced by .| +> |||This class is obsolete. Use instead.| +> |||This class is obsolete. Use instead| +> |||This method is obsolete. It has been replaced by .| +> |||This method is obsolete. It has been replaced by .| > |||This method has been deprecated. Use instead.| -> |||This property has been deprecated. Use instead.| +> |||This property has been deprecated. Use instead.| > |||This member has been deprecated. Use instead.| > |||This member has been deprecated. Use instead.| > |||This member has been deprecated. Use instead.| -> |||This constructor has been deprecated. Use to get an instance of this collection instead.| -> |||This constructor has been deprecated. Use to get an instance of this collection instead.| +> |||This constructor has been deprecated. Use to get an instance of this collection instead.| +> |||This constructor has been deprecated. Use to get an instance of this collection instead.| > |||This field has been deprecated and isn't used. Use machine.config or an application configuration file to set the size of the file mapping.| > |||This method has been deprecated. Use instead.| > |||This method has been deprecated. Use instead.| -> |||This class has been deprecated. Use the performance counters through the class instead.| -> |||This class has been deprecated. Use the performance counters through the class instead.| -> |||This class has been deprecated. Use the performance counters through the class instead.| +> |||This class has been deprecated. Use the performance counters through the class instead.| +> |||This class has been deprecated. Use the performance counters through the class instead.| +> |||This class has been deprecated. Use the performance counters through the class instead.| > |||This member has been deprecated. Use instead.| > |||This member has been deprecated. Use instead.| -> |||This property has been deprecated. Use instead.| -> |||This property has been deprecated. Use instead.| -> |||This property has been deprecated. Use instead.| -> |||This property has been deprecated. Use instead.| -> |||This property has been deprecated. Use instead.| -> |||This property has been deprecated. Use instead.| -> |||This property has been deprecated. Use instead.| -> |||This property has been deprecated. Use instead.| -> |||This property has been deprecated. Use instead.| -> ||| is obsoleted for this type, Use instead.| +> |||This property has been deprecated. Use instead.| +> |||This property has been deprecated. Use instead.| +> |||This property has been deprecated. Use instead.| +> |||This property has been deprecated. Use instead.| +> |||This property has been deprecated. Use instead.| +> |||This property has been deprecated. Use instead.| +> |||This property has been deprecated. Use instead.| +> |||This property has been deprecated. Use instead.| +> |||This property has been deprecated. Use instead.| +> ||| is obsoleted for this type, Use instead.| > ||| is obsoleted for this type, Use instead.| -> ||| is obsoleted for this type, Use instead.| -> ||| is obsoleted for this type, Use instead.| +> ||| is obsoleted for this type, Use instead.| +> ||| is obsoleted for this type, Use instead.| > ||| is obsoleted for this type, Use instead.| > ||| is obsoleted for this type, Use instead.| -> ||| is obsoleted for this type, Use instead.| -> ||| is obsoleted for this type, Use instead.| -> |||Serialization is obsoleted for this type.| -> |||Serialization is obsoleted for this type.| +> ||| is obsoleted for this type, Use instead.| +> ||| is obsoleted for this type, Use instead.| +> |||Serialization is obsoleted for this type.| +> |||Serialization is obsoleted for this type.| > |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| > |||Serialization is obsoleted for this type.| > |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| > |||Serialization is obsoleted for this type.| -> |||This property has been deprecated. It is address family dependent. Use the method to perform comparisons instead.| -> ||| is obsoleted for this type. Use instead.| -> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| -> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| +> |||This property has been deprecated. It is address family dependent. Use the method to perform comparisons instead.| +> ||| is obsoleted for this type. Use instead.| +> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| +> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| > ||`System.Net.WebClient.OnWriteStreamClosed`|First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| > |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| -> |||This method has been deprecated. Use the proxy selected for you by default.| -> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| -> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| -> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| -> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| -> ||| is obsoleted for this type. Use instead, which can accept multiple addresses.| +> |||This method has been deprecated. Use the proxy selected for you by default.| +> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| +> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| +> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| +> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| +> ||| is obsoleted for this type. Use instead, which can accept multiple addresses.| > |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| > |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| -> ||| is obsoleted for this type. Use instead.| -> ||| is obsoleted for this type. Use instead.| +> ||| is obsoleted for this type. Use instead.| +> ||| is obsoleted for this type. Use instead.| > |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| > |||This method has been deprecated. Use instead.| -> |||First deprecated in the .NET Framework 4.5.

This member is for internal use only and will be removed in a future version of the .NET Framework. Don't call it.| -> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

Use to add claims to a .| +> |||First deprecated in the .NET Framework 4.5.

This member is for internal use only and will be removed in a future version of the .NET Framework. Don't call it.| +> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

Use to add claims to a .| ## System.Drawing.dll @@ -519,7 +519,7 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||Don't use the method; use the property instead.| +> |||Don't use the method; use the property instead.| > |||First deprecated in the .NET Framework 4.5.

This constructor has been deprecated. Use .| ## System.Messaging.dll @@ -528,8 +528,8 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||This method returns a that implements the family of methods incorrectly. Use instead.| -> |||This method returns a that implements the family of methods incorrectly. Use instead.| +> |||This method returns a that implements the family of methods incorrectly. Use instead.| +> |||This method returns a that implements the family of methods incorrectly. Use instead.| ## System.ServiceModel.dll @@ -537,12 +537,12 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||First deprecated in the .NET Framework 4.5.

This property is obsolete. To enable Http , use the property instead.| -> |||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| -> |||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| -> |||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| -> |||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| -> |||This property is deprecated and is maintained for backward compatibility only. The local machine policy will be used to determine if NTLM should be used.| +> |||First deprecated in the .NET Framework 4.5.

This property is obsolete. To enable Http , use the property instead.| +> |||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| +> |||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| +> |||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| +> |||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| +> |||This property is deprecated and is maintained for backward compatibility only. The local machine policy will be used to determine if NTLM should be used.| ## System.ServiceModel.Discovery.dll @@ -550,8 +550,8 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||First deprecated in the .NET Framework 4.5.

The property is obsolete. Consider using for setting the transport properties.| -> |||First deprecated in the .NET Framework 4.5.

The property is obsolete. Consider using for setting the transport properties.| +> |||First deprecated in the .NET Framework 4.5.

The property is obsolete. Consider using for setting the transport properties.| +> |||First deprecated in the .NET Framework 4.5.

The property is obsolete. Consider using for setting the transport properties.| ## System.Web.DataVisualization.dll @@ -559,7 +559,7 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> ||| has been deprecated. Investigate instead.| +> ||| has been deprecated. Investigate instead.| ## System.Web.dll @@ -567,35 +567,35 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||The recommended alternative is in System.Web.dll.| -> |||The recommended alternative is in System.Web.dll.| -> |||First deprecated in the .NET Framework 4.5.

This method produces non\-standards\-compliant output and has interoperability issues. The preferred alternative is .| -> |||First deprecated in the .NET Framework 4.5.

This method produces non\-standards\-compliant output and has interoperability issues. The preferred alternative is .| +> |||The recommended alternative is in System.Web.dll.| +> |||The recommended alternative is in System.Web.dll.| +> |||First deprecated in the .NET Framework 4.5.

This method produces non\-standards\-compliant output and has interoperability issues. The preferred alternative is .| +> |||First deprecated in the .NET Framework 4.5.

This method produces non\-standards\-compliant output and has interoperability issues. The preferred alternative is .| > |||This field is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](https://account.microsoft.com/account/Account?destrt=home-index).| > |||This property is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](https://account.microsoft.com/account/Account?destrt=home-index).| -> |||The recommended alternative is the property. A version value greater than or equal to 1 implies JavaScript support.| -> |||System.Web.Mobile.dll is obsolete.| -> |||This method is obsolete. Override the method to use the event.| -> |||First deprecated in the .NET Framework 4.5.

The recommended alternative is to use the APIs, such as .| -> |||First deprecated in the .NET Framework 4.5.

The recommended alternative is to use the APIs, such as .| -> |||First deprecated in the .NET Framework 4.5.

This method is obsolete and is only provided for compatibility with existing code. It is recommended that new code use the and methods instead.| -> |||First deprecated in the .NET Framework 4.5.

This method is obsolete and is only provided for compatibility with existing code. It is recommended that new code use the and methods instead.| -> |||The recommended alternative is .| -> |||The recommended alternative is .| -> |||The recommended alternative is .| +> |||The recommended alternative is the property. A version value greater than or equal to 1 implies JavaScript support.| +> |||System.Web.Mobile.dll is obsolete.| +> |||This method is obsolete. Override the method to use the event.| +> |||First deprecated in the .NET Framework 4.5.

The recommended alternative is to use the APIs, such as .| +> |||First deprecated in the .NET Framework 4.5.

The recommended alternative is to use the APIs, such as .| +> |||First deprecated in the .NET Framework 4.5.

This method is obsolete and is only provided for compatibility with existing code. It is recommended that new code use the and methods instead.| +> |||First deprecated in the .NET Framework 4.5.

This method is obsolete and is only provided for compatibility with existing code. It is recommended that new code use the and methods instead.| +> |||The recommended alternative is .| +> |||The recommended alternative is .| +> |||The recommended alternative is .| > |||The recommended alternative is .| -> |||The recommended alternative is .| -> |||The recommended alternative is .| -> |||The recommended alternative is .| -> |||The recommended alternative is .| -> |||The recommended alternative is .| -> |||The recommended alternative is .| -> |||The recommended alternative is .| -> |||The recommended alternative is .| -> |||The recommended alternative is and .| -> |||Use of this property isn't recommended because it is no longer useful.| -> |||First deprecated in the .NET Framework 4.5.

This method is kept for backward compatibility. This API is no longer used.| -> |||The recommended alternative is the property. Create a and call to create an .| +> |||The recommended alternative is .| +> |||The recommended alternative is .| +> |||The recommended alternative is .| +> |||The recommended alternative is .| +> |||The recommended alternative is .| +> |||The recommended alternative is .| +> |||The recommended alternative is .| +> |||The recommended alternative is .| +> |||The recommended alternative is and .| +> |||Use of this property isn't recommended because it is no longer useful.| +> |||First deprecated in the .NET Framework 4.5.

This method is kept for backward compatibility. This API is no longer used.| +> |||The recommended alternative is the property. Create a and call to create an .| ## System.Web.DynamicData.dll @@ -603,7 +603,7 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||Use the `EnablePersistedSelection` property on a databound control such as or .| +> |||Use the `EnablePersistedSelection` property on a databound control such as or .| ## System.Web.Extensions.dll @@ -611,14 +611,14 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||Use .| -> |||This property is obsolete. Set the [`System.Web.UI.ScriptReference.Path`](xref:System.Web.UI.ScriptReferenceBase.Path%2A) property on each individual instead.| -> |||This property is obsolete. Instead of using , set the [`System.Web.UI.ScriptReference.Path`](xref:System.Web.UI.ScriptReferenceBase.Path%2A) property on each individual .| -> |||Use .| -> |||Use .| +> |||Use .| +> |||This property is obsolete. Set the [`System.Web.UI.ScriptReference.Path`](xref:System.Web.UI.ScriptReferenceBase.Path%2A) property on each individual instead.| +> |||This property is obsolete. Instead of using , set the [`System.Web.UI.ScriptReference.Path`](xref:System.Web.UI.ScriptReferenceBase.Path%2A) property on each individual .| +> |||Use .| +> |||Use .| > ||| is no longer required in script references.| -> |||This property is obsolete. Use instead.| -> |||This property is obsolete. Use instead.| +> |||This property is obsolete. Use instead.| +> |||This property is obsolete. Use instead.| ## System.Web.Services.dll @@ -626,8 +626,8 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||This method will be removed from a future version. The method call is no longer required for resource discovery.| -> |||This property will be removed from a future version. The presence of a particular header in a SOAP message is no longer enforced.| +> |||This method will be removed from a future version. The method call is no longer required for resource discovery.| +> |||This property will be removed from a future version. The presence of a particular header in a SOAP message is no longer enforced.| ## System.Windows.Forms.dll @@ -636,16 +636,16 @@ This article doesn't list the members of obsolete types. For a list of obsolete > |Type|Member|Message| > |----------|------------|-------------| > |||This enumeration value has been deprecated. There is no replacement.| -> |||This method has been deprecated. There is no replacement.| -> |||This property has been deprecated. Use instead.| +> |||This method has been deprecated. There is no replacement.| +> |||This property has been deprecated. Use instead.| > |||This method has been deprecated. Use the method instead.| > |||This method has been deprecated. Use the method instead.| -> |||This method has been deprecated. Use the method instead.| -> |||This property has been deprecated. Use the property instead.| -> |||This method has been deprecated. Use the property instead.| -> |||This property has been deprecated. Use instead.| -> |||This method has been deprecated. There is no replacement.| -> |||This property has been deprecated. Use the property instead.| +> |||This method has been deprecated. Use the method instead.| +> |||This property has been deprecated. Use the property instead.| +> |||This method has been deprecated. Use the property instead.| +> |||This property has been deprecated. Use instead.| +> |||This method has been deprecated. There is no replacement.| +> |||This property has been deprecated. Use the property instead.| ## System.Xaml.dll @@ -653,7 +653,7 @@ This article doesn't list the members of obsolete types. For a list of obsolete > > |Type|Member|Message| > |----------|------------|-------------| -> |||This isn't used by the XAML parser. See .| +> |||This isn't used by the XAML parser. See .| > |||The `expressionType` argument isn't used by the XAML parser. To specify the expected return type, use . To specify custom handling for expression types, use .| ## System.Xml.dll @@ -666,18 +666,18 @@ This article doesn't list the members of obsolete types. For a list of obsolete > |||XDR validation through is obsoleted.| > |||Use .| > |||Use .| -> |||Use the property instead.| +> |||Use the property instead.| > |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and isn't intended to be used directly from your code.| -> |||Use the property instead.| +> |||Use the property instead.| > |||Use for schema compilation and validation.| > |||Use for schema compilation and validation.| -> |||This property has been deprecated. Use property, which returns a strongly typed attribute type.| -> |||This property has been deprecated. Use the property, which returns a strongly typed element type.| -> |||This property has been deprecated. Use the property, which returns a strongly typed base schema type.| -> |||This class should never get constructed as it contains only static methods.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an constructor overload that doesn't take an parameter.| -> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||This property has been deprecated. Use property, which returns a strongly typed attribute type.| +> |||This property has been deprecated. Use the property, which returns a strongly typed element type.| +> |||This property has been deprecated. Use the property, which returns a strongly typed base schema type.| +> |||This class should never get constructed as it contains only static methods.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an constructor overload that doesn't take an parameter.| +> |||This method is obsolete and will be removed in a future release of the .NET Framework. Use an overload of that doesn't take an parameter.| ## IEHost.dll and IEExec.exe @@ -689,7 +689,7 @@ The IEHost.dll and IEExec.exe assemblies have been removed from .NET Framework. > > |Type|Member|Message| > |----------|------------|-------------| -> |||The recommended alternative is . takes the importer interface pointer as an instead of an , and thus works on both 32-bit and 64-bit architectures.| +> |||The recommended alternative is . takes the importer interface pointer as an instead of an , and thus works on both 32-bit and 64-bit architectures.| ## Microsoft.Build.Conversion.v4.0.dll @@ -708,8 +708,8 @@ The IEHost.dll and IEExec.exe assemblies have been removed from .NET Framework. > > |Type|Member|Message| > |----------|------------|-------------| -> |||Avoid setting . If you were simply passing in the .NET Framework location as the , no other action is necessary. Otherwise, define Toolsets instead in the registry or config file, or by adding elements to the Engine's , to use a custom .| -> |||If you were simply passing in the .NET Framework location as the , just change to the parameterless constructor. Otherwise, you can define custom toolsets in the registry or configuration file, or add elements to the Engine's . Then use either the or constructor instead.| +> |||Avoid setting . If you were simply passing in the .NET Framework location as the , no other action is necessary. Otherwise, define Toolsets instead in the registry or config file, or by adding elements to the Engine's , to use a custom .| +> |||If you were simply passing in the .NET Framework location as the , just change to the parameterless constructor. Otherwise, you can define custom toolsets in the registry or configuration file, or add elements to the Engine's . Then use either the or constructor instead.| ## Microsoft.Build.Framework.dll @@ -717,7 +717,7 @@ The IEHost.dll and IEExec.exe assemblies have been removed from .NET Framework. > > |Type|Member|Message| > |----------|------------|-------------| -> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

Use the property instead.| +> |||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

Use the property instead.| ## Microsoft.Build.Utilities.v4.0.dll @@ -725,7 +725,7 @@ The IEHost.dll and IEExec.exe assemblies have been removed from .NET Framework. > > |Type|Member|Message| > |----------|------------|-------------| -> |||Use the property.| +> |||Use the property.| ## Microsoft.Data.Entity.Build.Tasks.dll @@ -741,18 +741,18 @@ The IEHost.dll and IEExec.exe assemblies have been removed from .NET Framework. > > |Type|Member|Message| > |----------|------------|-------------| -> |||This member has been deprecated. Use to write types, or coerce `FileNumber` and `RecordNumber` to for writing non-object types.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||Use of this member generates a compiler error.

Don't use this method.| -> |||The `DynData` registry key works only on Win9x, which isn't supported by this version of .NET Framework. Use the `PerformanceData` registry key instead. This property will be removed from a future version of .NET Framework.| +> |||This member has been deprecated. Use to write types, or coerce `FileNumber` and `RecordNumber` to for writing non-object types.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||Use of this member generates a compiler error.

Don't use this method.| +> |||The `DynData` registry key works only on Win9x, which isn't supported by this version of .NET Framework. Use the `PerformanceData` registry key instead. This property will be removed from a future version of .NET Framework.| ## See also diff --git a/docs/framework/whats-new/obsolete-types.md b/docs/framework/whats-new/obsolete-types.md index 6fb7134257c71..8cb1b6511a3f0 100644 --- a/docs/framework/whats-new/obsolete-types.md +++ b/docs/framework/whats-new/obsolete-types.md @@ -165,14 +165,14 @@ The following tables list the types that have been declared obsolete in system a ||Use of this type is not recommended because DataBindings editing is launched via a instead of the property grid.| ||The recommended alternative is and .| ||The recommended alternative is and .| -||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| +||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| ||The recommended alternative is . The contains additional functionality and allows for more extensibility. To get the , use the `RootDesigner.ReferenceManager` property from your .| -||The recommended alternative is . The contains additional functionality and allows for more extensibility. To get the , use the property from your .| -||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| +||The recommended alternative is . The contains additional functionality and allows for more extensibility. To get the , use the property from your .| +||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| ||The recommended alternative is because it uses an for editing the content. Designer regions allow for better control of the content being edited.| -||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| -||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| -||Use of this type is not recommended because the AutoFormat dialog is launched by the designer host. The list of available AutoFormats is exposed on the in the property.| +||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| +||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| +||Use of this type is not recommended because the AutoFormat dialog is launched by the designer host. The list of available AutoFormats is exposed on the in the property.| ||The recommended alternative is because it uses an for editing the content. Designer regions allow for better control of the content being edited.| [Back to top](#introduction) @@ -183,12 +183,12 @@ The following tables list the types that have been declared obsolete in system a |Type|Message| |----------|-------------| -||This interface has been deprecated. Add a to handle type instead.| +||This interface has been deprecated. Add a to handle type instead.| ||Use instead to work with the new settings model.| ||This attribute has been deprecated. Use instead.| ||This class has been deprecated.| ||This class has been deprecated. Use the performance counters through the class instead.| -||This class has been deprecated. Please use instead to access and set the global default proxy. Use 'null' instead of .| +||This class has been deprecated. Please use instead to access and set the global default proxy. Use 'null' instead of .| ||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| [Back to top](#introduction) @@ -256,7 +256,7 @@ The following tables list the types that have been declared obsolete in system a ||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](https://account.microsoft.com/account/Account?destrt=home-index)| ||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](https://account.microsoft.com/account/Account?destrt=home-index)| ||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](https://account.microsoft.com/account/Account?destrt=home-index)| -||The recommended alternative is and .| +||The recommended alternative is and .| [Back to top](#introduction) @@ -558,7 +558,7 @@ The following tables list the types that have been declared obsolete in system a |----------|-------------| ||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| ||Use for schema compilation and validation.| -||Use an created by the method using the appropriate instead.| +||Use an created by the method using the appropriate instead.| ||Use of this type generates a compiler error. This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| ||This class has been deprecated. Please use instead.| diff --git a/docs/framework/whats-new/whats-new-in-accessibility.md b/docs/framework/whats-new/whats-new-in-accessibility.md index 6d6a051f61cca..fc2ceaceef36b 100644 --- a/docs/framework/whats-new/whats-new-in-accessibility.md +++ b/docs/framework/whats-new/whats-new-in-accessibility.md @@ -506,9 +506,9 @@ To support live regions, the following APIs have been added to WPF: - The property, which identifies the **AutomationProperties.LiveSetting** attached property. -- The method, which can be overridden to provide a `LiveSetting` value. +- The method, which can be overridden to provide a `LiveSetting` value. -- The and methods, which get and set a `LiveSetting` value. +- The and methods, which get and set a `LiveSetting` value. - The enumeration, which defines the following possible `LiveSetting` values: @@ -538,7 +538,7 @@ peer.RaiseAutomationEvent(AutomationEvents.LiveRegionChanged) **High contrast** -Starting with .NET Framework 4.7.1, improvements in high contrast have been made to various WPF controls. They are now visible when the theme is set. These include: +Starting with .NET Framework 4.7.1, improvements in high contrast have been made to various WPF controls. They are now visible when the theme is set. These include: - control @@ -742,7 +742,7 @@ Accessibility changes in the Workflow Designer include the following: - Breakpoints set in the workflow designer. - - The , , and activities. + - The , , and activities. - The contents of the activity. - The Target Type for the activity. diff --git a/docs/framework/windows-services/how-to-add-installers-to-your-service-application.md b/docs/framework/windows-services/how-to-add-installers-to-your-service-application.md index a425566e11095..505495805b48b 100644 --- a/docs/framework/windows-services/how-to-add-installers-to-your-service-application.md +++ b/docs/framework/windows-services/how-to-add-installers-to-your-service-application.md @@ -2,7 +2,7 @@ title: "How to: Add Installers to Your Service Application" description: See how to add installers to your service application. Visual Studio ships installation components that can install resources associated with your service apps. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "Windows Service applications, deploying" - "installation components, adding to services" - "installers, adding to services" @@ -16,47 +16,47 @@ ms.assetid: 8b698e9a-b88e-4f44-ae45-e0c5ea0ae5a8 [!INCLUDE [windows-service-disambiguation](../../core/extensions/includes/windows-service-disambiguation.md)] -Visual Studio ships installation components that can install resources associated with your service applications. Installation components register an individual service on the system to which it is being installed and let the Services Control Manager know that the service exists. When you work with a service application, you can select a link in the Properties window to automatically add the appropriate installers to your project. - +Visual Studio ships installation components that can install resources associated with your service applications. Installation components register an individual service on the system to which it is being installed and let the Services Control Manager know that the service exists. When you work with a service application, you can select a link in the Properties window to automatically add the appropriate installers to your project. + > [!NOTE] -> Property values for your service are copied from the service class to the installer class. If you update the property values on the service class, they are not automatically updated in the installer. - - When you add an installer to your project, a new class (which, by default, is named `ProjectInstaller`) is created in the project, and instances of the appropriate installation components are created within it. This class acts as a central point for all of the installation components your project needs. For example, if you add a second service to your application and click the Add Installer link, a second installer class is not created; instead, the necessary additional installation component for the second service is added to the existing class. - - You do not need to do any special coding within the installers to make your services install correctly. However, you may occasionally need to modify the contents of the installers if you need to add special functionality to the installation process. - +> Property values for your service are copied from the service class to the installer class. If you update the property values on the service class, they are not automatically updated in the installer. + + When you add an installer to your project, a new class (which, by default, is named `ProjectInstaller`) is created in the project, and instances of the appropriate installation components are created within it. This class acts as a central point for all of the installation components your project needs. For example, if you add a second service to your application and click the Add Installer link, a second installer class is not created; instead, the necessary additional installation component for the second service is added to the existing class. + + You do not need to do any special coding within the installers to make your services install correctly. However, you may occasionally need to modify the contents of the installers if you need to add special functionality to the installation process. + > [!NOTE] -> The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose **Import and Export Settings** on the **Tools** menu. For more information, see [Personalize the Visual Studio IDE](/visualstudio/ide/personalizing-the-visual-studio-ide). - -### To add installers to your service application - -1. In **Solution Explorer**, access **Design** view for the service for which you want to add an installation component. - -2. Click the background of the designer to select the service itself, rather than any of its contents. - -3. With the designer in focus, right-click, and then click **Add Installer**. - - A new class, `ProjectInstaller`, and two installation components, and , are added to your project, and property values for the service are copied to the components. - -4. Click the component and verify that the value of the property is set to the same value as the property on the service itself. - -5. To determine how your service will be started, click the component and set the property to the appropriate value. - - |Value|Result| - |-----------|------------| - ||The service must be manually started after installation. For more information, see [How to: Start Services](how-to-start-services.md).| - ||The service will start by itself whenever the computer reboots.| - ||The service cannot be started.| - -6. To determine the security context in which your service will run, click the component and set the appropriate property values. For more information, see [How to: Specify the Security Context for Services](how-to-specify-the-security-context-for-services.md). - -7. Override any methods for which you need to perform custom processing. - -8. Perform steps 1 through 7 for each additional service in your project. - +> The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose **Import and Export Settings** on the **Tools** menu. For more information, see [Personalize the Visual Studio IDE](/visualstudio/ide/personalizing-the-visual-studio-ide). + +### To add installers to your service application + +1. In **Solution Explorer**, access **Design** view for the service for which you want to add an installation component. + +2. Click the background of the designer to select the service itself, rather than any of its contents. + +3. With the designer in focus, right-click, and then click **Add Installer**. + + A new class, `ProjectInstaller`, and two installation components, and , are added to your project, and property values for the service are copied to the components. + +4. Click the component and verify that the value of the property is set to the same value as the property on the service itself. + +5. To determine how your service will be started, click the component and set the property to the appropriate value. + + |Value|Result| + |-----------|------------| + ||The service must be manually started after installation. For more information, see [How to: Start Services](how-to-start-services.md).| + ||The service will start by itself whenever the computer reboots.| + ||The service cannot be started.| + +6. To determine the security context in which your service will run, click the component and set the appropriate property values. For more information, see [How to: Specify the Security Context for Services](how-to-specify-the-security-context-for-services.md). + +7. Override any methods for which you need to perform custom processing. + +8. Perform steps 1 through 7 for each additional service in your project. + > [!NOTE] - > For each additional service in your project, you must add an additional component to the project's `ProjectInstaller` class. The component added in step three works with all of the individual service installers in the project. - + > For each additional service in your project, you must add an additional component to the project's `ProjectInstaller` class. The component added in step three works with all of the individual service installers in the project. + ## See also - [Introduction to Windows Service Applications](introduction-to-windows-service-applications.md) diff --git a/docs/framework/windows-services/how-to-continue-a-windows-service-visual-basic.md b/docs/framework/windows-services/how-to-continue-a-windows-service-visual-basic.md index 58d167796e60d..95f8310deee48 100644 --- a/docs/framework/windows-services/how-to-continue-a-windows-service-visual-basic.md +++ b/docs/framework/windows-services/how-to-continue-a-windows-service-visual-basic.md @@ -2,11 +2,11 @@ title: "How to: Continue a Windows Service (Visual Basic)" description: Read how to use the ServiceController component to continue a Windows service (such as the IIS Admin service) on a local computer with Visual Basic. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "vb" -f1_keywords: +f1_keywords: - "ServiceController.Continue" -helpviewer_keywords: +helpviewer_keywords: - "Windows Service applications, pausing" - "pausing Windows Service applications" ms.assetid: e5d13760-4c83-4b0d-abef-39852677cd7a @@ -15,41 +15,41 @@ ms.assetid: e5d13760-4c83-4b0d-abef-39852677cd7a [!INCLUDE [windows-service-disambiguation](../../core/extensions/includes/windows-service-disambiguation.md)] -This example uses the component to continue the IIS Admin service on the local computer. - -## Example - - [!code-vb[VbRadconService#11](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#11)] -[!code-vb[VbRadconService#13](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#13)] - - This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Windows Operating System > Windows Services**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). - -## Compiling the Code - - This example requires: - -- A project reference to System.serviceprocess.dll. - -- Access to the members of the namespace. Add an `Imports` statement if you are not fully qualifying member names in your code. For more information, see [Imports Statement (.NET Namespace and Type)](../../visual-basic/language-reference/statements/imports-statement-net-namespace-and-type.md). - -## Robust Programming - - The property of the class is the local computer by default. To reference Windows services on another computer, change the property to the name of that computer. - - You cannot call the method on a service until the service controller status is . - - The following conditions may cause an exception: - -- The service cannot be resumed. () - -- An error occurred when accessing a system API. () - -## .NET Framework Security - - Control of services on the computer may be restricted by using the enumeration to set permissions in the class. - - Access to service information may be restricted by using the enumeration to set permissions in the class. - +This example uses the component to continue the IIS Admin service on the local computer. + +## Example + + [!code-vb[VbRadconService#11](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#11)] +[!code-vb[VbRadconService#13](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#13)] + + This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Windows Operating System > Windows Services**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). + +## Compiling the Code + + This example requires: + +- A project reference to System.serviceprocess.dll. + +- Access to the members of the namespace. Add an `Imports` statement if you are not fully qualifying member names in your code. For more information, see [Imports Statement (.NET Namespace and Type)](../../visual-basic/language-reference/statements/imports-statement-net-namespace-and-type.md). + +## Robust Programming + + The property of the class is the local computer by default. To reference Windows services on another computer, change the property to the name of that computer. + + You cannot call the method on a service until the service controller status is . + + The following conditions may cause an exception: + +- The service cannot be resumed. () + +- An error occurred when accessing a system API. () + +## .NET Framework Security + + Control of services on the computer may be restricted by using the enumeration to set permissions in the class. + + Access to service information may be restricted by using the enumeration to set permissions in the class. + ## See also - diff --git a/docs/framework/windows-services/how-to-create-windows-services.md b/docs/framework/windows-services/how-to-create-windows-services.md index 0fa33e06d5234..743737b82cc45 100644 --- a/docs/framework/windows-services/how-to-create-windows-services.md +++ b/docs/framework/windows-services/how-to-create-windows-services.md @@ -2,7 +2,7 @@ title: "How to: Create Windows Services" description: Use the Windows Service project template to create a service. Set the ServiceName property, create installers, and override the OnStart and OnStop methods. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "Windows Service applications, creating" - "templates, Windows Service" ms.assetid: 0f5e2cbb-d95d-477c-b2b5-4b990e6b86ff @@ -11,59 +11,59 @@ ms.assetid: 0f5e2cbb-d95d-477c-b2b5-4b990e6b86ff [!INCLUDE [windows-service-disambiguation](../../core/extensions/includes/windows-service-disambiguation.md)] -When you create a service, you can use a Visual Studio project template called **Windows Service**. This template automatically does much of the work for you by referencing the appropriate classes and namespaces, setting up the inheritance from the base class for services, and overriding several of the methods you're likely to want to override. - +When you create a service, you can use a Visual Studio project template called **Windows Service**. This template automatically does much of the work for you by referencing the appropriate classes and namespaces, setting up the inheritance from the base class for services, and overriding several of the methods you're likely to want to override. + > [!WARNING] -> The Windows Services project template is not available in the Express edition of Visual Studio. - - At a minimum, to create a functional service you must: - -- Set the property. - -- Create the necessary installers for your service application. - -- Override and specify code for the and methods to customize the ways in which your service behaves. - -### To create a Windows Service application - -1. Create a **Windows Service** project. - +> The Windows Services project template is not available in the Express edition of Visual Studio. + + At a minimum, to create a functional service you must: + +- Set the property. + +- Create the necessary installers for your service application. + +- Override and specify code for the and methods to customize the ways in which your service behaves. + +### To create a Windows Service application + +1. Create a **Windows Service** project. + > [!NOTE] - > For instructions on writing a service without using the template, see [How to: Write Services Programmatically](how-to-write-services-programmatically.md). - -2. In the **Properties** window, set the property for your service. - - ![Set the ServiceName property.](./media/windowsservice-servicename.PNG "WindowsService_ServiceName") - + > For instructions on writing a service without using the template, see [How to: Write Services Programmatically](how-to-write-services-programmatically.md). + +2. In the **Properties** window, set the property for your service. + + ![Set the ServiceName property.](./media/windowsservice-servicename.PNG "WindowsService_ServiceName") + > [!NOTE] - > The value of the property must always match the name recorded in the installer classes. If you change this property, you must update the property of installer classes as well. - -3. Set any of the following properties to determine how your service will function. - - |Property|Setting| - |--------------|-------------| - ||`True` to indicate that the service will accept requests to stop running; `false` to prevent the service from being stopped.| - ||`True` to indicate that the service wants to receive notification when the computer on which it lives shuts down, enabling it to call the procedure.| - ||`True` to indicate that the service will accept requests to pause or to resume running; `false` to prevent the service from being paused and resumed.| - ||`True` to indicate that the service can handle notification of changes to the computer's power status; `false` to prevent the service from being notified of these changes.| - ||`True` to write informational entries to the Application event log when your service performs an action; `false` to disable this functionality. For more information, see [How to: Log Information About Services](how-to-log-information-about-services.md). **Note:** By default, is set to `true`.| - + > The value of the property must always match the name recorded in the installer classes. If you change this property, you must update the property of installer classes as well. + +3. Set any of the following properties to determine how your service will function. + + |Property|Setting| + |--------------|-------------| + ||`True` to indicate that the service will accept requests to stop running; `false` to prevent the service from being stopped.| + ||`True` to indicate that the service wants to receive notification when the computer on which it lives shuts down, enabling it to call the procedure.| + ||`True` to indicate that the service will accept requests to pause or to resume running; `false` to prevent the service from being paused and resumed.| + ||`True` to indicate that the service can handle notification of changes to the computer's power status; `false` to prevent the service from being notified of these changes.| + ||`True` to write informational entries to the Application event log when your service performs an action; `false` to disable this functionality. For more information, see [How to: Log Information About Services](how-to-log-information-about-services.md). **Note:** By default, is set to `true`.| + > [!NOTE] - > When or are set to `false`, the **Service Control Manager** will disable the corresponding menu options to stop, pause, or continue the service. - -4. Access the Code Editor and fill in the processing you want for the and procedures. - -5. Override any other methods for which you want to define functionality. - -6. Add the necessary installers for your service application. For more information, see [How to: Add Installers to Your Service Application](how-to-add-installers-to-your-service-application.md). - -7. Build your project by selecting **Build Solution** from the **Build** menu. - + > When or are set to `false`, the **Service Control Manager** will disable the corresponding menu options to stop, pause, or continue the service. + +4. Access the Code Editor and fill in the processing you want for the and procedures. + +5. Override any other methods for which you want to define functionality. + +6. Add the necessary installers for your service application. For more information, see [How to: Add Installers to Your Service Application](how-to-add-installers-to-your-service-application.md). + +7. Build your project by selecting **Build Solution** from the **Build** menu. + > [!NOTE] - > Do not press F5 to run your project — you cannot run a service project in this way. - -8. Install the service. For more information, see [How to: Install and Uninstall Services](how-to-install-and-uninstall-services.md). - + > Do not press F5 to run your project — you cannot run a service project in this way. + +8. Install the service. For more information, see [How to: Install and Uninstall Services](how-to-install-and-uninstall-services.md). + ## See also - [Introduction to Windows Service Applications](introduction-to-windows-service-applications.md) diff --git a/docs/framework/windows-services/how-to-debug-windows-service-applications.md b/docs/framework/windows-services/how-to-debug-windows-service-applications.md index bbe2a8a976643..ec9b026dce80f 100644 --- a/docs/framework/windows-services/how-to-debug-windows-service-applications.md +++ b/docs/framework/windows-services/how-to-debug-windows-service-applications.md @@ -2,7 +2,7 @@ title: "How to: Debug Windows Service Applications" description: Understand how to debug Windows service applications, which aren't as straightforward to debug as other Visual Studio application types. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "debugging Windows Service applications" - "debugging [Visual Studio], Windows services" - "Windows services, debugging" @@ -14,103 +14,103 @@ ms.assetid: 63ab0800-0f05-4f1e-88e6-94c73fd920a2 [!INCLUDE [windows-service-disambiguation](../../core/extensions/includes/windows-service-disambiguation.md)] -A service must be run from within the context of the Services Control Manager rather than from within Visual Studio. For this reason, debugging a service is not as straightforward as debugging other Visual Studio application types. To debug a service, you must start the service and then attach a debugger to the process in which it is running. You can then debug your application by using all of the standard debugging functionality of Visual Studio. - +A service must be run from within the context of the Services Control Manager rather than from within Visual Studio. For this reason, debugging a service is not as straightforward as debugging other Visual Studio application types. To debug a service, you must start the service and then attach a debugger to the process in which it is running. You can then debug your application by using all of the standard debugging functionality of Visual Studio. + > [!CAUTION] -> You should not attach to a process unless you know what the process is and understand the consequences of attaching to and possibly killing that process. For example, if you attach to the WinLogon process and then stop debugging, the system will halt because it can't operate without WinLogon. - - You can attach the debugger only to a running service. The attachment process interrupts the current functioning of your service; it doesn't actually stop or pause the service's processing. That is, if your service is running when you begin debugging, it is still technically in the Started state as you debug it, but its processing has been suspended. - - After attaching to the process, you can set breakpoints and use these to debug your code. Once you exit the dialog box you use to attach to the process, you are effectively in debug mode. You can use the Services Control Manager to start, stop, pause and continue your service, thus hitting the breakpoints you've set. You can later remove this dummy service after debugging is successful. - - This article covers debugging a service that's running on the local computer, but you can also debug Windows Services that are running on a remote computer. See [Remote Debugging](/visualstudio/debugger/debug-installed-app-package). - +> You should not attach to a process unless you know what the process is and understand the consequences of attaching to and possibly killing that process. For example, if you attach to the WinLogon process and then stop debugging, the system will halt because it can't operate without WinLogon. + + You can attach the debugger only to a running service. The attachment process interrupts the current functioning of your service; it doesn't actually stop or pause the service's processing. That is, if your service is running when you begin debugging, it is still technically in the Started state as you debug it, but its processing has been suspended. + + After attaching to the process, you can set breakpoints and use these to debug your code. Once you exit the dialog box you use to attach to the process, you are effectively in debug mode. You can use the Services Control Manager to start, stop, pause and continue your service, thus hitting the breakpoints you've set. You can later remove this dummy service after debugging is successful. + + This article covers debugging a service that's running on the local computer, but you can also debug Windows Services that are running on a remote computer. See [Remote Debugging](/visualstudio/debugger/debug-installed-app-package). + > [!NOTE] -> Debugging the method can be difficult because the Services Control Manager imposes a 30-second limit on all attempts to start a service. For more information, see [Troubleshooting: Debugging Windows Services](troubleshooting-debugging-windows-services.md). - +> Debugging the method can be difficult because the Services Control Manager imposes a 30-second limit on all attempts to start a service. For more information, see [Troubleshooting: Debugging Windows Services](troubleshooting-debugging-windows-services.md). + > [!WARNING] -> To get meaningful information for debugging, the Visual Studio debugger needs to find symbol files for the binaries that are being debugged. If you are debugging a service that you built in Visual Studio, the symbol files (.pdb files) are in the same folder as the executable or library, and the debugger loads them automatically. If you are debugging a service that you didn't build, you should first find symbols for the service and make sure they can be found by the debugger. See [Specify Symbol (.pdb) and Source Files in the Visual Studio Debugger](/visualstudio/debugger/specify-symbol-dot-pdb-and-source-files-in-the-visual-studio-debugger). If you're debugging a system process or want to have symbols for system calls in your services, you should add the Microsoft Symbol Servers. See [Debugging Symbols](/windows/desktop/DxTechArts/debugging-with-symbols). - -### To debug a service - -1. Build your service in the Debug configuration. - -2. Install your service. For more information, see [How to: Install and Uninstall Services](how-to-install-and-uninstall-services.md). - -3. Start your service, either from **Services Control Manager**, **Server Explorer**, or from code. For more information, see [How to: Start Services](how-to-start-services.md). - -4. Start Visual Studio with administrative credentials so you can attach to system processes. - -5. (Optional) On the Visual Studio menu bar, choose **Tools**, **Options**. In the **Options** dialog box, choose **Debugging**, **Symbols**, select the **Microsoft Symbol Servers** check box, and then choose the **OK** button. - -6. On the menu bar, choose **Attach to Process** from the **Debug** or **Tools** menu. (Keyboard: Ctrl+Alt+P) - - The **Processes** dialog box appears. - -7. Select the **Show processes from all users** check box. - -8. In the **Available Processes** section, choose the process for your service, and then choose **Attach**. - +> To get meaningful information for debugging, the Visual Studio debugger needs to find symbol files for the binaries that are being debugged. If you are debugging a service that you built in Visual Studio, the symbol files (.pdb files) are in the same folder as the executable or library, and the debugger loads them automatically. If you are debugging a service that you didn't build, you should first find symbols for the service and make sure they can be found by the debugger. See [Specify Symbol (.pdb) and Source Files in the Visual Studio Debugger](/visualstudio/debugger/specify-symbol-dot-pdb-and-source-files-in-the-visual-studio-debugger). If you're debugging a system process or want to have symbols for system calls in your services, you should add the Microsoft Symbol Servers. See [Debugging Symbols](/windows/desktop/DxTechArts/debugging-with-symbols). + +### To debug a service + +1. Build your service in the Debug configuration. + +2. Install your service. For more information, see [How to: Install and Uninstall Services](how-to-install-and-uninstall-services.md). + +3. Start your service, either from **Services Control Manager**, **Server Explorer**, or from code. For more information, see [How to: Start Services](how-to-start-services.md). + +4. Start Visual Studio with administrative credentials so you can attach to system processes. + +5. (Optional) On the Visual Studio menu bar, choose **Tools**, **Options**. In the **Options** dialog box, choose **Debugging**, **Symbols**, select the **Microsoft Symbol Servers** check box, and then choose the **OK** button. + +6. On the menu bar, choose **Attach to Process** from the **Debug** or **Tools** menu. (Keyboard: Ctrl+Alt+P) + + The **Processes** dialog box appears. + +7. Select the **Show processes from all users** check box. + +8. In the **Available Processes** section, choose the process for your service, and then choose **Attach**. + > [!TIP] - > The process will have the same name as the executable file for your service. - - The **Attach to Process** dialog box appears. - -9. Choose the appropriate options, and then choose **OK** to close the dialog box. - + > The process will have the same name as the executable file for your service. + + The **Attach to Process** dialog box appears. + +9. Choose the appropriate options, and then choose **OK** to close the dialog box. + > [!NOTE] - > You are now in debug mode. - -10. Set any breakpoints you want to use in your code. - -11. Access the Services Control Manager and manipulate your service, sending stop, pause, and continue commands to hit your breakpoints. For more information about running the Services Control Manager, see [How to: Start Services](how-to-start-services.md). Also, see [Troubleshooting: Debugging Windows Services](troubleshooting-debugging-windows-services.md). - -## Debugging Tips for Windows Services - - Attaching to the service's process allows you to debug most, but not all, the code for that service. For example, because the service has already been started, you cannot debug the code in the service's method or the code in the `Main` method that is used to load the service this way. One way to work around this limitation is to create a temporary second service in your service application that exists only to aid in debugging. You can install both services, and then start this dummy service to load the service process. Once the temporary service has started the process, you can use the **Debug** menu in Visual Studio to attach to the service process. - - Try adding calls to the method to delay action until you're able to attach to the process. - - Try changing the program to a regular console application. To do this, rewrite the `Main` method as follows so it can run both as a Windows Service and as a console application, depending on how it's started. - -#### How to: Run a Windows Service as a console application - -1. Add a method to your service that runs the and methods: - - ```csharp - internal void TestStartupAndStop(string[] args) - { - this.OnStart(args); - Console.ReadLine(); - this.OnStop(); - } - ``` - -2. Rewrite the `Main` method as follows: - - ```csharp - static void Main(string[] args) - { - if (Environment.UserInteractive) - { - MyNewService service1 = new MyNewService(args); - service1.TestStartupAndStop(args); - } - else - { - // Put the body of your old Main method here. - } + > You are now in debug mode. + +10. Set any breakpoints you want to use in your code. + +11. Access the Services Control Manager and manipulate your service, sending stop, pause, and continue commands to hit your breakpoints. For more information about running the Services Control Manager, see [How to: Start Services](how-to-start-services.md). Also, see [Troubleshooting: Debugging Windows Services](troubleshooting-debugging-windows-services.md). + +## Debugging Tips for Windows Services + + Attaching to the service's process allows you to debug most, but not all, the code for that service. For example, because the service has already been started, you cannot debug the code in the service's method or the code in the `Main` method that is used to load the service this way. One way to work around this limitation is to create a temporary second service in your service application that exists only to aid in debugging. You can install both services, and then start this dummy service to load the service process. Once the temporary service has started the process, you can use the **Debug** menu in Visual Studio to attach to the service process. + + Try adding calls to the method to delay action until you're able to attach to the process. + + Try changing the program to a regular console application. To do this, rewrite the `Main` method as follows so it can run both as a Windows Service and as a console application, depending on how it's started. + +#### How to: Run a Windows Service as a console application + +1. Add a method to your service that runs the and methods: + + ```csharp + internal void TestStartupAndStop(string[] args) + { + this.OnStart(args); + Console.ReadLine(); + this.OnStop(); } - ``` - -3. In the **Application** tab of the project's properties, set the **Output type** to **Console Application**. - -4. Choose **Start Debugging** (F5). - -5. To run the program as a Windows Service again, install it and start it as usual for a Windows Service. It's not necessary to reverse these changes. - - In some cases, such as when you want to debug an issue that occurs only on system startup, you have to use the Windows debugger. [Download the Windows Driver Kit (WDK)](/windows-hardware/drivers/download-the-wdk) and see [How to debug Windows Services](https://support.microsoft.com/kb/824344). - + ``` + +2. Rewrite the `Main` method as follows: + + ```csharp + static void Main(string[] args) + { + if (Environment.UserInteractive) + { + MyNewService service1 = new MyNewService(args); + service1.TestStartupAndStop(args); + } + else + { + // Put the body of your old Main method here. + } + } + ``` + +3. In the **Application** tab of the project's properties, set the **Output type** to **Console Application**. + +4. Choose **Start Debugging** (F5). + +5. To run the program as a Windows Service again, install it and start it as usual for a Windows Service. It's not necessary to reverse these changes. + + In some cases, such as when you want to debug an issue that occurs only on system startup, you have to use the Windows debugger. [Download the Windows Driver Kit (WDK)](/windows-hardware/drivers/download-the-wdk) and see [How to debug Windows Services](https://support.microsoft.com/kb/824344). + ## See also - [Introduction to Windows Service Applications](introduction-to-windows-service-applications.md) diff --git a/docs/framework/windows-services/how-to-log-information-about-services.md b/docs/framework/windows-services/how-to-log-information-about-services.md index f35ed14261204..6104e05c74bad 100644 --- a/docs/framework/windows-services/how-to-log-information-about-services.md +++ b/docs/framework/windows-services/how-to-log-information-about-services.md @@ -18,43 +18,43 @@ ms.assetid: c0d8140f-c055-4d8e-a2e0-37358a550116 [!INCLUDE [windows-service-disambiguation](../../core/extensions/includes/windows-service-disambiguation.md)] -By default, all Windows Service projects have the ability to interact with the Application event log and write information and exceptions to it. You use the property to indicate whether you want this functionality in your application. By default, logging is turned on for any service you create with the Windows Service project template. You can use a static form of the class to write service information to a log without having to create an instance of an component or manually register a source. +By default, all Windows Service projects have the ability to interact with the Application event log and write information and exceptions to it. You use the property to indicate whether you want this functionality in your application. By default, logging is turned on for any service you create with the Windows Service project template. You can use a static form of the class to write service information to a log without having to create an instance of an component or manually register a source. The installer for your service automatically registers each service in your project as a valid source of events with the Application log on the computer where the service is installed, when logging is turned on. The service logs information each time the service is started, stopped, paused, resumed, installed, or uninstalled. It also logs any failures that occur. You do not need to write any code to write entries to the log when using the default behavior; the service handles this for you automatically. - If you want to write to an event log other than the Application log, you must set the property to `false`, create your own custom event log within your services code, and register your service as a valid source of entries for that log. You must then write code to record entries to the log whenever an action you're interested in occurs. + If you want to write to an event log other than the Application log, you must set the property to `false`, create your own custom event log within your services code, and register your service as a valid source of entries for that log. You must then write code to record entries to the log whenever an action you're interested in occurs. > [!NOTE] -> If you use a custom event log and configure your service application to write to it, you must not attempt to access the event log before setting the service's property in your code. The event log needs this property's value to register your service as a valid source of events. +> If you use a custom event log and configure your service application to write to it, you must not attempt to access the event log before setting the service's property in your code. The event log needs this property's value to register your service as a valid source of events. ## To enable default event logging for your service -- Set the property for your component to `true`. +- Set the property for your component to `true`. > [!NOTE] - > By default, this property is set to `true`. You do not need to set this explicitly unless you are building more complex processing, such as evaluating a condition and then setting the property based on the result of that condition. + > By default, this property is set to `true`. You do not need to set this explicitly unless you are building more complex processing, such as evaluating a condition and then setting the property based on the result of that condition. ## To disable event logging for your service -- Set the property for your component to `false`. +- Set the property for your component to `false`. [!code-csharp[VbRadconService#17](./snippets/MyNewService/csharp/MyNewService.cs#17)] [!code-vb[VbRadconService#17](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#17)] ## To set up logging to a custom log -1. Set the property to `false`. +1. Set the property to `false`. > [!NOTE] - > You must set to false in order to use a custom log. + > You must set to false in order to use a custom log. 2. Set up an instance of an component in your Windows Service application. -3. Create a custom log by calling the method and specifying the source string and the name of the log file you want to create. +3. Create a custom log by calling the method and specifying the source string and the name of the log file you want to create. -4. Set the property on the component instance to the source string you created in step 3. +4. Set the property on the component instance to the source string you created in step 3. -5. Write your entries by accessing the method on the component instance. +5. Write your entries by accessing the method on the component instance. The following code shows how to set up logging to a custom log. diff --git a/docs/framework/windows-services/how-to-pause-a-windows-service-visual-basic.md b/docs/framework/windows-services/how-to-pause-a-windows-service-visual-basic.md index e58bfed500383..0c86bdf3ccbc9 100644 --- a/docs/framework/windows-services/how-to-pause-a-windows-service-visual-basic.md +++ b/docs/framework/windows-services/how-to-pause-a-windows-service-visual-basic.md @@ -2,11 +2,11 @@ title: "How to: Pause a Windows Service (Visual Basic)" description: Read how to use the ServiceController component to pause a Windows service (such as the IIS Admin service) on a local computer with Visual Basic. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "vb" -f1_keywords: +f1_keywords: - "ServiceController.Pause" -helpviewer_keywords: +helpviewer_keywords: - "Windows Service applications, pausing" - "pausing Windows Service applications" ms.assetid: eddb9409-942b-46b6-a2ce-fbd4c65f2790 @@ -15,42 +15,42 @@ ms.assetid: eddb9409-942b-46b6-a2ce-fbd4c65f2790 [!INCLUDE [windows-service-disambiguation](../../core/extensions/includes/windows-service-disambiguation.md)] -This example uses the component to pause the IIS Admin service on the local computer. - -## Example - - [!code-vb[VbRadconService#11](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#11)] -[!code-vb[VbRadconService#12](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#12)] - - This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Windows Operating System > Windows Services**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). - -## Compiling the Code - - This example requires: - -- A project reference to System.serviceprocess.dll. - -- Access to the members of the namespace. Add an `Imports` statement if you are not fully qualifying member names in your code. For more information, see [Imports Statement (.NET Namespace and Type)](../../visual-basic/language-reference/statements/imports-statement-net-namespace-and-type.md). - -## Robust Programming - - The property of the class is the local computer by default. To reference Windows services on another computer, change the property to the name of that computer. - - The following conditions may cause an exception: - -- The service cannot be paused. () - -- An error occurred when accessing a system API. () - -## .NET Framework Security - - Control of services on the computer may be restricted by using the to set permissions in the . - - Access to service information may be restricted by using the to set permissions in the . - +This example uses the component to pause the IIS Admin service on the local computer. + +## Example + + [!code-vb[VbRadconService#11](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#11)] +[!code-vb[VbRadconService#12](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#12)] + + This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Windows Operating System > Windows Services**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). + +## Compiling the Code + + This example requires: + +- A project reference to System.serviceprocess.dll. + +- Access to the members of the namespace. Add an `Imports` statement if you are not fully qualifying member names in your code. For more information, see [Imports Statement (.NET Namespace and Type)](../../visual-basic/language-reference/statements/imports-statement-net-namespace-and-type.md). + +## Robust Programming + + The property of the class is the local computer by default. To reference Windows services on another computer, change the property to the name of that computer. + + The following conditions may cause an exception: + +- The service cannot be paused. () + +- An error occurred when accessing a system API. () + +## .NET Framework Security + + Control of services on the computer may be restricted by using the to set permissions in the . + + Access to service information may be restricted by using the to set permissions in the . + ## See also - - -- +- - [How to: Continue a Windows Service (Visual Basic)](how-to-continue-a-windows-service-visual-basic.md) diff --git a/docs/framework/windows-services/how-to-specify-the-security-context-for-services.md b/docs/framework/windows-services/how-to-specify-the-security-context-for-services.md index 76860b5728a3d..55381c0417d12 100644 --- a/docs/framework/windows-services/how-to-specify-the-security-context-for-services.md +++ b/docs/framework/windows-services/how-to-specify-the-security-context-for-services.md @@ -2,7 +2,7 @@ title: "How to: Specify the Security Context for Services" description: Specify the security context for services. Services run in the default system account context have other system resource access rights than the logged-in user. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "Windows Service applications, security" - "security [Visual Studio], contexts" - "contexts, Visual Studio security" @@ -16,31 +16,31 @@ ms.assetid: 02187c7b-dbf2-45f2-96c2-e11010225a22 [!INCLUDE [windows-service-disambiguation](../../core/extensions/includes/windows-service-disambiguation.md)] -By default, services run in a different security context than that of the logged-in user. Services run in the context of the default system account, called `LocalSystem`, which gives them different access privileges to system resources than the user. You can change this behavior to specify a different user account under which your service should run. - - You set the security context by manipulating the property for the process within which the service runs. This property allows you to set the service to one of four account types: - -- `User`, which causes the system to prompt for a valid user name and password when the service is installed and runs in the context of an account specified by a single user on the network; - -- `LocalService`, which runs in the context of an account that acts as a non-privileged user on the local computer, and presents anonymous credentials to any remote server; - -- `LocalSystem`, which runs in the context of an account that provides extensive local privileges, and presents the computer's credentials to any remote server; - -- `NetworkService`, which runs in the context of an account that acts as a non-privileged user on the local computer, and presents the computer's credentials to any remote server. - - For more information, see the enumeration. - -### To specify the security context for a service - -1. After creating your service, add the necessary installers for it. For more information, see [How to: Add Installers to Your Service Application](how-to-add-installers-to-your-service-application.md). - -2. In the designer, access the `ProjectInstaller` class and click the service process installer for the service you are working with. - +By default, services run in a different security context than that of the logged-in user. Services run in the context of the default system account, called `LocalSystem`, which gives them different access privileges to system resources than the user. You can change this behavior to specify a different user account under which your service should run. + + You set the security context by manipulating the property for the process within which the service runs. This property allows you to set the service to one of four account types: + +- `User`, which causes the system to prompt for a valid user name and password when the service is installed and runs in the context of an account specified by a single user on the network; + +- `LocalService`, which runs in the context of an account that acts as a non-privileged user on the local computer, and presents anonymous credentials to any remote server; + +- `LocalSystem`, which runs in the context of an account that provides extensive local privileges, and presents the computer's credentials to any remote server; + +- `NetworkService`, which runs in the context of an account that acts as a non-privileged user on the local computer, and presents the computer's credentials to any remote server. + + For more information, see the enumeration. + +### To specify the security context for a service + +1. After creating your service, add the necessary installers for it. For more information, see [How to: Add Installers to Your Service Application](how-to-add-installers-to-your-service-application.md). + +2. In the designer, access the `ProjectInstaller` class and click the service process installer for the service you are working with. + > [!NOTE] - > For every service application, there are at least two installation components in the `ProjectInstaller` class — one that installs the processes for all services in the project, and one installer for each service the application contains. In this instance, you want to select . - -3. In the **Properties** window, set the to the appropriate value. - + > For every service application, there are at least two installation components in the `ProjectInstaller` class — one that installs the processes for all services in the project, and one installer for each service the application contains. In this instance, you want to select . + +3. In the **Properties** window, set the to the appropriate value. + ## See also - [Introduction to Windows Service Applications](introduction-to-windows-service-applications.md) diff --git a/docs/framework/windows-services/how-to-start-services.md b/docs/framework/windows-services/how-to-start-services.md index f4d9493307e54..e970fa82c1da3 100644 --- a/docs/framework/windows-services/how-to-start-services.md +++ b/docs/framework/windows-services/how-to-start-services.md @@ -11,7 +11,7 @@ ms.assetid: 9ea77955-2d96-4c3d-913c-14db7604cdad [!INCLUDE [windows-service-disambiguation](../../core/extensions/includes/windows-service-disambiguation.md)] -After a service is installed, it must be started. Starting calls the method on the service class. Usually, the method defines the useful work the service will perform. After a service starts, it remains active until it is manually paused or stopped. +After a service is installed, it must be started. Starting calls the method on the service class. Usually, the method defines the useful work the service will perform. After a service starts, it remains active until it is manually paused or stopped. Services can be set up to start automatically or manually. A service that starts automatically will be started when the computer on which it is installed is rebooted or first turned on. A user must start a service that starts manually. @@ -61,7 +61,7 @@ You set the property on 1. Create an instance of the class, and configure it to interact with the service you want to administer. -2. Call the method to start the service. +2. Call the method to start the service. ## See also diff --git a/docs/framework/windows-services/how-to-write-services-programmatically.md b/docs/framework/windows-services/how-to-write-services-programmatically.md index 15249fa86743c..46754460a9d23 100644 --- a/docs/framework/windows-services/how-to-write-services-programmatically.md +++ b/docs/framework/windows-services/how-to-write-services-programmatically.md @@ -18,9 +18,9 @@ If you choose not to use the Windows Service project template, you can write you - You must set up your service class to inherit from the class. -- You must create a `Main` method for your service project that defines the services to run and calls the method on them. +- You must create a `Main` method for your service project that defines the services to run and calls the method on them. -- You must override the and procedures and fill in any code you want them to run. +- You must override the and procedures and fill in any code you want them to run. ### To write a service programmatically @@ -49,7 +49,7 @@ If you choose not to use the Windows Service project template, you can write you [!code-csharp[VbRadconService#9](./snippets/MyNewService/csharp/MyNewService.cs#9)] [!code-vb[VbRadconService#9](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#9)] -5. Override the method, and define any processing you want to occur when your service is started. +5. Override the method, and define any processing you want to occur when your service is started. [!code-csharp[VbRadconService#10](./snippets/MyNewService/csharp/MyNewService.cs#10)] [!code-vb[VbRadconService#10](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#10)] diff --git a/docs/framework/windows-services/introduction-to-windows-service-applications.md b/docs/framework/windows-services/introduction-to-windows-service-applications.md index bae2833e98451..24eae56e6a79e 100644 --- a/docs/framework/windows-services/introduction-to-windows-service-applications.md +++ b/docs/framework/windows-services/introduction-to-windows-service-applications.md @@ -2,9 +2,9 @@ title: "Introduction to Windows Service Applications" description: Read an introduction to Windows service applications. Services let you create long-running executable applications that run in their own Windows sessions. ms.date: "03/30/2017" -f1_keywords: +f1_keywords: - "ServiceController" -helpviewer_keywords: +helpviewer_keywords: - "Windows Service applications, deploying" - "OnStop method" - "OnPause method" @@ -27,60 +27,60 @@ ms.assetid: 1b1b5e67-3ff3-40c0-8154-322cfd6ef0ae [!INCLUDE [windows-service-disambiguation](../../core/extensions/includes/windows-service-disambiguation.md)] -Microsoft Windows services, formerly known as NT services, enable you to create long-running executable applications that run in their own Windows sessions. These services can be automatically started when the computer boots, can be paused and restarted, and do not show any user interface. These features make services ideal for use on a server or whenever you need long-running functionality that does not interfere with other users who are working on the same computer. You can also run services in the security context of a specific user account that is different from the logged-on user or the default computer account. For more information about services and Windows sessions, see the Windows SDK documentation. - - You can easily create services by creating an application that is installed as a service. For example, suppose you want to monitor performance counter data and react to threshold values. You could write a Windows Service application that listens to the performance counter data, deploy the application, and begin collecting and analyzing data. - - You create your service as a Microsoft Visual Studio project, defining code within it that controls what commands can be sent to the service and what actions should be taken when those commands are received. Commands that can be sent to a service include starting, pausing, resuming, and stopping the service; you can also execute custom commands. - - After you create and build the application, you can install it by running the command-line utility InstallUtil.exe and passing the path to the service's executable file. You can then use the **Services Control Manager** to start, stop, pause, resume, and configure your service. You can also accomplish many of these same tasks in the **Services** node in **Server Explorer** or by using the class. - -## Service Applications vs. Other Visual Studio Applications - - Service applications function differently from many other project types in several ways: - -- The compiled executable file that a service application project creates must be installed on the server before the project can function in a meaningful way. You cannot debug or run a service application by pressing F5 or F11; you cannot immediately run a service or step into its code. Instead, you must install and start your service, and then attach a debugger to the service's process. For more information, see [How to: Debug Windows Service Applications](how-to-debug-windows-service-applications.md). - -- Unlike some types of projects, you must create installation components for service applications. The installation components install and register the service on the server and create an entry for your service with the Windows **Services Control Manager**. For more information, see [How to: Add Installers to Your Service Application](how-to-add-installers-to-your-service-application.md). - -- The `Main` method for your service application must issue the Run command for the services your project contains. The `Run` method loads the services into the **Services Control Manager** on the appropriate server. If you use the **Windows Services** project template, this method is written for you automatically. Note that loading a service is not the same thing as starting the service. See "Service Lifetime" below for more information. - -- Windows Service applications run in a different window station than the interactive station of the logged-on user. A window station is a secure object that contains a Clipboard, a set of global atoms, and a group of desktop objects. Because the station of the Windows service is not an interactive station, dialog boxes raised from within a Windows service application will not be seen and may cause your program to stop responding. Similarly, error messages should be logged in the Windows event log rather than raised in the user interface. - - The Windows service classes supported by the .NET Framework do not support interaction with interactive stations, that is, the logged-on user. The .NET Framework also does not include classes that represent stations and desktops. If your Windows service must interact with other stations, you will need to access the unmanaged Windows API. For more information, see the Windows SDK documentation. - - The interaction of the Windows service with the user or other stations must be carefully designed to include scenarios such as there being no logged on user, or the user having an unexpected set of desktop objects. In some cases, it may be more appropriate to write a Windows application that runs under the control of the user. - -- Windows service applications run in their own security context and are started before the user logs into the Windows computer on which they are installed. You should plan carefully what user account to run the service within; a service running under the system account has more permissions and privileges than a user account. - -## Service Lifetime - - A service goes through several internal states in its lifetime. First, the service is installed onto the system on which it will run. This process executes the installers for the service project and loads the service into the **Services Control Manager** for that computer. The **Services Control Manager** is the central utility provided by Windows to administer services. - - After the service has been loaded, it must be started. Starting the service allows it to begin functioning. You can start a service from the **Services Control Manager**, from **Server Explorer**, or from code by calling the method. The method passes processing to the application's method and processes any code you have defined there. - - A running service can exist in this state indefinitely until it is either stopped or paused or until the computer shuts down. A service can exist in one of three basic states: , , or . The service can also report the state of a pending command: , , , or . These statuses indicate that a command has been issued, such as a command to pause a running service, but has not been carried out yet. You can query the to determine what state a service is in, or use the to carry out an action when any of these states occurs. - - You can pause, stop, or resume a service from the **Services Control Manager**, from **Server Explorer**, or by calling methods in code. Each of these actions can call an associated procedure in the service (, , or ), in which you can define additional processing to be performed when the service changes state. - -## Types of Services - - There are two types of services you can create in Visual Studio using the .NET Framework. Services that are the only service in a process are assigned the type . Services that share a process with another service are assigned the type . You can retrieve the service type by querying the property. - - You might occasionally see other service types if you query existing services that were not created in Visual Studio. For more information on these, see the . - -## Services and the ServiceController Component - - The component is used to connect to an installed service and manipulate its state; using a component, you can start and stop a service, pause and continue its functioning, and send custom commands to a service. However, you do not need to use a component when you create a service application. In fact, in most cases your component should exist in a separate application from the Windows service application that defines your service. - - For more information, see . - -## Requirements - -- Services must be created in a **Windows Service** application project or another .NET Framework–enabled project that creates an .exe file when built and inherits from the class. - -- Projects containing Windows services must have installation components for the project and its services. This can be easily accomplished from the **Properties** window. For more information, see [How to: Add Installers to Your Service Application](how-to-add-installers-to-your-service-application.md). - +Microsoft Windows services, formerly known as NT services, enable you to create long-running executable applications that run in their own Windows sessions. These services can be automatically started when the computer boots, can be paused and restarted, and do not show any user interface. These features make services ideal for use on a server or whenever you need long-running functionality that does not interfere with other users who are working on the same computer. You can also run services in the security context of a specific user account that is different from the logged-on user or the default computer account. For more information about services and Windows sessions, see the Windows SDK documentation. + + You can easily create services by creating an application that is installed as a service. For example, suppose you want to monitor performance counter data and react to threshold values. You could write a Windows Service application that listens to the performance counter data, deploy the application, and begin collecting and analyzing data. + + You create your service as a Microsoft Visual Studio project, defining code within it that controls what commands can be sent to the service and what actions should be taken when those commands are received. Commands that can be sent to a service include starting, pausing, resuming, and stopping the service; you can also execute custom commands. + + After you create and build the application, you can install it by running the command-line utility InstallUtil.exe and passing the path to the service's executable file. You can then use the **Services Control Manager** to start, stop, pause, resume, and configure your service. You can also accomplish many of these same tasks in the **Services** node in **Server Explorer** or by using the class. + +## Service Applications vs. Other Visual Studio Applications + + Service applications function differently from many other project types in several ways: + +- The compiled executable file that a service application project creates must be installed on the server before the project can function in a meaningful way. You cannot debug or run a service application by pressing F5 or F11; you cannot immediately run a service or step into its code. Instead, you must install and start your service, and then attach a debugger to the service's process. For more information, see [How to: Debug Windows Service Applications](how-to-debug-windows-service-applications.md). + +- Unlike some types of projects, you must create installation components for service applications. The installation components install and register the service on the server and create an entry for your service with the Windows **Services Control Manager**. For more information, see [How to: Add Installers to Your Service Application](how-to-add-installers-to-your-service-application.md). + +- The `Main` method for your service application must issue the Run command for the services your project contains. The `Run` method loads the services into the **Services Control Manager** on the appropriate server. If you use the **Windows Services** project template, this method is written for you automatically. Note that loading a service is not the same thing as starting the service. See "Service Lifetime" below for more information. + +- Windows Service applications run in a different window station than the interactive station of the logged-on user. A window station is a secure object that contains a Clipboard, a set of global atoms, and a group of desktop objects. Because the station of the Windows service is not an interactive station, dialog boxes raised from within a Windows service application will not be seen and may cause your program to stop responding. Similarly, error messages should be logged in the Windows event log rather than raised in the user interface. + + The Windows service classes supported by the .NET Framework do not support interaction with interactive stations, that is, the logged-on user. The .NET Framework also does not include classes that represent stations and desktops. If your Windows service must interact with other stations, you will need to access the unmanaged Windows API. For more information, see the Windows SDK documentation. + + The interaction of the Windows service with the user or other stations must be carefully designed to include scenarios such as there being no logged on user, or the user having an unexpected set of desktop objects. In some cases, it may be more appropriate to write a Windows application that runs under the control of the user. + +- Windows service applications run in their own security context and are started before the user logs into the Windows computer on which they are installed. You should plan carefully what user account to run the service within; a service running under the system account has more permissions and privileges than a user account. + +## Service Lifetime + + A service goes through several internal states in its lifetime. First, the service is installed onto the system on which it will run. This process executes the installers for the service project and loads the service into the **Services Control Manager** for that computer. The **Services Control Manager** is the central utility provided by Windows to administer services. + + After the service has been loaded, it must be started. Starting the service allows it to begin functioning. You can start a service from the **Services Control Manager**, from **Server Explorer**, or from code by calling the method. The method passes processing to the application's method and processes any code you have defined there. + + A running service can exist in this state indefinitely until it is either stopped or paused or until the computer shuts down. A service can exist in one of three basic states: , , or . The service can also report the state of a pending command: , , , or . These statuses indicate that a command has been issued, such as a command to pause a running service, but has not been carried out yet. You can query the to determine what state a service is in, or use the to carry out an action when any of these states occurs. + + You can pause, stop, or resume a service from the **Services Control Manager**, from **Server Explorer**, or by calling methods in code. Each of these actions can call an associated procedure in the service (, , or ), in which you can define additional processing to be performed when the service changes state. + +## Types of Services + + There are two types of services you can create in Visual Studio using the .NET Framework. Services that are the only service in a process are assigned the type . Services that share a process with another service are assigned the type . You can retrieve the service type by querying the property. + + You might occasionally see other service types if you query existing services that were not created in Visual Studio. For more information on these, see the . + +## Services and the ServiceController Component + + The component is used to connect to an installed service and manipulate its state; using a component, you can start and stop a service, pause and continue its functioning, and send custom commands to a service. However, you do not need to use a component when you create a service application. In fact, in most cases your component should exist in a separate application from the Windows service application that defines your service. + + For more information, see . + +## Requirements + +- Services must be created in a **Windows Service** application project or another .NET Framework–enabled project that creates an .exe file when built and inherits from the class. + +- Projects containing Windows services must have installation components for the project and its services. This can be easily accomplished from the **Properties** window. For more information, see [How to: Add Installers to Your Service Application](how-to-add-installers-to-your-service-application.md). + ## See also - [Windows Service Applications](index.md) diff --git a/docs/framework/windows-services/service-application-programming-architecture.md b/docs/framework/windows-services/service-application-programming-architecture.md index 738b7b5d85d29..998ad9fd8137a 100644 --- a/docs/framework/windows-services/service-application-programming-architecture.md +++ b/docs/framework/windows-services/service-application-programming-architecture.md @@ -36,20 +36,20 @@ Windows Service applications are based on a class that inherits from the |Indicate what actions should be taken when your service starts running. You must write code in this procedure for your service to perform useful work.| -||Indicate what should happen when your service is paused.| -||Indicate what should happen when your service stops running.| -||Indicate what should happen when your service resumes normal functioning after being paused.| -||Indicate what should happen just prior to your system shutting down, if your service is running at that time.| -||Indicate what should happen when your service receives a custom command. For more information on custom commands, see MSDN online.| -||Indicate how the service should respond when a power management event is received, such as a low battery or suspended operation.| +||Indicate what actions should be taken when your service starts running. You must write code in this procedure for your service to perform useful work.| +||Indicate what should happen when your service is paused.| +||Indicate what should happen when your service stops running.| +||Indicate what should happen when your service resumes normal functioning after being paused.| +||Indicate what should happen just prior to your system shutting down, if your service is running at that time.| +||Indicate what should happen when your service receives a custom command. For more information on custom commands, see MSDN online.| +||Indicate how the service should respond when a power management event is received, such as a low battery or suspended operation.| > [!NOTE] -> These methods represent states that the service moves through in its lifetime; the service transitions from one state to the next. For example, you will never get the service to respond to an command before has been called. +> These methods represent states that the service moves through in its lifetime; the service transitions from one state to the next. For example, you will never get the service to respond to an command before has been called. There are several other properties and methods that are of interest. These include: -- The method on the class. This is the main entry point for the service. When you create a service using the Windows Service template, code is inserted in your application's `Main` method to run the service. This code looks like this: +- The method on the class. This is the main entry point for the service. When you create a service using the Windows Service template, code is inserted in your application's `Main` method to run the service. This code looks like this: [!code-csharp[VbRadconService#6](./snippets/MyNewService/csharp/MyNewService.cs#6)] [!code-vb[VbRadconService#6](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#6)] @@ -57,10 +57,10 @@ Windows Service applications are based on a class that inherits from the [!NOTE] > These examples use an array of type , into which each service your application contains can be added, and then all of the services can be run together. If you are only creating a single service, however, you might choose not to use the array and simply declare a new object inheriting from and then run it. For an example, see [How to: Write Services Programmatically](how-to-write-services-programmatically.md). -- A series of properties on the class. These determine what methods can be called on your service. For example, when the property is set to `true`, the method on your service can be called. When the property is set to `true`, the and methods can be called. When you set one of these properties to `true`, you should then override and define processing for the associated methods. +- A series of properties on the class. These determine what methods can be called on your service. For example, when the property is set to `true`, the method on your service can be called. When the property is set to `true`, the and methods can be called. When you set one of these properties to `true`, you should then override and define processing for the associated methods. > [!NOTE] - > Your service must override at least and to be useful. + > Your service must override at least and to be useful. You can also use a component called the to communicate with and control the behavior of an existing service. diff --git a/docs/framework/windows-services/troubleshooting-debugging-windows-services.md b/docs/framework/windows-services/troubleshooting-debugging-windows-services.md index b05369535dc09..17726f166f12b 100644 --- a/docs/framework/windows-services/troubleshooting-debugging-windows-services.md +++ b/docs/framework/windows-services/troubleshooting-debugging-windows-services.md @@ -2,7 +2,7 @@ title: "Troubleshooting: Debugging Windows Services" description: Get started with debugging Windows services. When you debug a Windows service application, your service and the Windows Service Manager interact. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "debugging Windows Service applications" - "debugging [Visual Studio], Windows services" - "troubleshooting service applications" @@ -17,10 +17,10 @@ ms.assetid: cf859d4c-f04c-4cb7-81e3-bc7de8bea190 [!INCLUDE [windows-service-disambiguation](../../core/extensions/includes/windows-service-disambiguation.md)] -When you debug a Windows service application, your service and the **Windows Service Manager** interact. The **Service Manager** starts your service by calling the method, and then waits 30 seconds for the method to return. If the method does not return in this time, the manager shows an error that the service cannot be started. - - When you debug the method as described in [How to: Debug Windows Service Applications](how-to-debug-windows-service-applications.md), you must be aware of this 30-second period. If you place a breakpoint in the method and do not step through it in 30 seconds, the manager will not start the service. - +When you debug a Windows service application, your service and the **Windows Service Manager** interact. The **Service Manager** starts your service by calling the method, and then waits 30 seconds for the method to return. If the method does not return in this time, the manager shows an error that the service cannot be started. + + When you debug the method as described in [How to: Debug Windows Service Applications](how-to-debug-windows-service-applications.md), you must be aware of this 30-second period. If you place a breakpoint in the method and do not step through it in 30 seconds, the manager will not start the service. + ## See also - [How to: Debug Windows Service Applications](how-to-debug-windows-service-applications.md) diff --git a/docs/framework/windows-services/troubleshooting-service-application-wont-install.md b/docs/framework/windows-services/troubleshooting-service-application-wont-install.md index 3dc30ed1e51e0..eaa932c25bd78 100644 --- a/docs/framework/windows-services/troubleshooting-service-application-wont-install.md +++ b/docs/framework/windows-services/troubleshooting-service-application-wont-install.md @@ -2,7 +2,7 @@ title: "Troubleshooting: Service Application Won't Install" description: Do troubleshooting if your service application won't install. Make sure the ServiceName property for the service class is set correctly. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "troubleshooting service applications" - "services, troubleshooting" - "services, debugging" @@ -15,13 +15,13 @@ ms.assetid: 45c48e2e-b97d-44bc-8896-14f328e0ce33 [!INCLUDE [windows-service-disambiguation](../../core/extensions/includes/windows-service-disambiguation.md)] -If your service application will not install correctly, check to make sure that the property for the service class is set to the same value as is shown in the installer for that service. The value must be the same in both instances in order for your service to install correctly. - +If your service application will not install correctly, check to make sure that the property for the service class is set to the same value as is shown in the installer for that service. The value must be the same in both instances in order for your service to install correctly. + > [!NOTE] -> You can also look at the installation logs to get feedback on the installation process. - - You should also check to determine whether you have another service with the same name already installed. Service names must be unique for installation to succeed. - +> You can also look at the installation logs to get feedback on the installation process. + + You should also check to determine whether you have another service with the same name already installed. Service names must be unique for installation to succeed. + ## See also - [Introduction to Windows Service Applications](introduction-to-windows-service-applications.md) diff --git a/docs/framework/windows-services/walkthrough-creating-a-windows-service-application-in-the-component-designer.md b/docs/framework/windows-services/walkthrough-creating-a-windows-service-application-in-the-component-designer.md index 3df9d1ff241c9..e9aec4fc28bc3 100644 --- a/docs/framework/windows-services/walkthrough-creating-a-windows-service-application-in-the-component-designer.md +++ b/docs/framework/windows-services/walkthrough-creating-a-windows-service-application-in-the-component-designer.md @@ -81,19 +81,19 @@ In this section, you add a custom event log to the Windows service. The method. Visual Studio automatically created an empty method definition when you created the project. Add code that writes an entry to the event log when the service starts: +In the code editor for **MyNewService.cs** or **MyNewService.vb**, locate the method. Visual Studio automatically created an empty method definition when you created the project. Add code that writes an entry to the event log when the service starts: [!code-csharp[VbRadconService#3](./snippets/MyNewService/csharp/MyNewService.cs#3)] [!code-vb[VbRadconService#3](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#3)] #### Polling -Because a service application is designed to be long-running, it usually polls or monitors the system, which you set up in the method. The `OnStart` method must return to the operating system after the service's operation has begun so that the system isn't blocked. +Because a service application is designed to be long-running, it usually polls or monitors the system, which you set up in the method. The `OnStart` method must return to the operating system after the service's operation has begun so that the system isn't blocked. To set up a simple polling mechanism, use the component. The timer raises an event at regular intervals, at which time your service can do its monitoring. You use the component as follows: - Set the properties of the component in the `MyNewService.OnStart` method. -- Start the timer by calling the method. +- Start the timer by calling the method. ##### Set up the polling mechanism @@ -159,16 +159,16 @@ Instead of running all your work on the main thread, you can run tasks by using ### Define what occurs when the service is stopped -Insert a line of code in the method that adds an entry to the event log when the service is stopped: +Insert a line of code in the method that adds an entry to the event log when the service is stopped: [!code-csharp[VbRadconService#2](./snippets/MyNewService/csharp/MyNewService.cs#4)] [!code-vb[VbRadconService#4](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#4)] ### Define other actions for the service -You can override the , , and methods to define additional processing for your component. +You can override the , , and methods to define additional processing for your component. -The following code shows how you can override the method in the `MyNewService` class: +The following code shows how you can override the method in the `MyNewService` class: [!code-csharp[VbRadconService#5](./snippets/MyNewService/csharp/MyNewService.cs#5)] [!code-vb[VbRadconService#5](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#5)] @@ -253,7 +253,7 @@ You can implement the `SERVICE_START_PENDING` and `SERVICE_STOP_PENDING` status Declare Auto Function SetServiceStatus Lib "advapi32.dll" (ByVal handle As IntPtr, ByRef serviceStatus As ServiceStatus) As Boolean ``` -4. To implement the `SERVICE_START_PENDING` status, add the following code to the beginning of the method: +4. To implement the `SERVICE_START_PENDING` status, add the following code to the beginning of the method: ```csharp // Update the service state to Start Pending. @@ -287,7 +287,7 @@ You can implement the `SERVICE_START_PENDING` and `SERVICE_STOP_PENDING` status SetServiceStatus(Me.ServiceHandle, serviceStatus) ``` -6. (Optional) If is a long-running method, repeat this procedure in the `OnStop` method. Implement the `SERVICE_STOP_PENDING` status and return the `SERVICE_STOPPED` status before the `OnStop` method exits. +6. (Optional) If is a long-running method, repeat this procedure in the `OnStop` method. Implement the `SERVICE_STOP_PENDING` status and return the `SERVICE_STOPPED` status before the `OnStop` method exits. For example: diff --git a/docs/framework/windows-workflow-foundation/activity-authoring-options-in-wf.md b/docs/framework/windows-workflow-foundation/activity-authoring-options-in-wf.md index c56eb9e38e7b1..af7b791b4007d 100644 --- a/docs/framework/windows-workflow-foundation/activity-authoring-options-in-wf.md +++ b/docs/framework/windows-workflow-foundation/activity-authoring-options-in-wf.md @@ -15,7 +15,7 @@ ms.topic: "reference" |Base activity class|Features available| |-------------------------|------------------------| ||Composes groups of system-provided and custom activities into a composite activity.| -||Implements imperative functionality by providing an method that can be overridden. Also provides access to tracking, variables, and arguments..| +||Implements imperative functionality by providing an method that can be overridden. Also provides access to tracking, variables, and arguments..| ||Provides all of the features of , plus aborting activity execution, canceling child activity execution, using bookmarks, and scheduling activities, activity actions, and functions.| ||Provides a DOM-like approach to constructing activities that interfaces with the WF designer and the runtime machinery through , allowing new activities to be created without defining new types.| @@ -25,16 +25,16 @@ ms.topic: "reference" ## Authoring Activities using CodeActivity or AsyncCodeActivity - Activities that derive from or can implement imperative functionality by overriding the method with custom imperative code. The custom code is executed when the activity is executed by the runtime. While activities created in this way have access to custom functionality, they do not have access to all of the features of the runtime, such as full access to the execution environment, the ability to schedule child activities, bookmark creation, or support for a Cancel or Abort method. When a executes, it has access to a reduced version of the execution environment (through the or class). Activities created using have access to argument and variable resolution, extensions, and tracking. Asynchronous activity scheduling can be done using . + Activities that derive from or can implement imperative functionality by overriding the method with custom imperative code. The custom code is executed when the activity is executed by the runtime. While activities created in this way have access to custom functionality, they do not have access to all of the features of the runtime, such as full access to the execution environment, the ability to schedule child activities, bookmark creation, or support for a Cancel or Abort method. When a executes, it has access to a reduced version of the execution environment (through the or class). Activities created using have access to argument and variable resolution, extensions, and tracking. Asynchronous activity scheduling can be done using . ## Authoring Activities using NativeActivity - Activities that derive from , like those that derive from , create imperative functionality by overriding , but also have access to all of the functionality of the workflow runtime through the that gets passed into the method. This context has support for scheduling and canceling child activities, executing and objects, flowing transactions into a workflow, invoking asynchronous processes, canceling and aborting execution, access to execution properties and extensions, and bookmarks (handles for resuming paused workflows). + Activities that derive from , like those that derive from , create imperative functionality by overriding , but also have access to all of the functionality of the workflow runtime through the that gets passed into the method. This context has support for scheduling and canceling child activities, executing and objects, flowing transactions into a workflow, invoking asynchronous processes, canceling and aborting execution, access to execution properties and extensions, and bookmarks (handles for resuming paused workflows). ## Authoring Activities using DynamicActivity - Unlike the other three types of activity, new functionality is not created by deriving new types from (the class is sealed), but instead, by assembling functionality into the and properties using an activity document object model (DOM). + Unlike the other three types of activity, new functionality is not created by deriving new types from (the class is sealed), but instead, by assembling functionality into the and properties using an activity document object model (DOM). ## Authoring Activities that Return a Result - Many activities must return a result after their execution. Although it is possible to always define a custom on an activity for this purpose, it is suggested to instead use , or derive from or . Each of these base classes has an named Result that your activity can use for its return value. Activities that return a result should only be used if only one result needs to be returned from an activity; if multiple results need to be returned, separate members should be used instead. + Many activities must return a result after their execution. Although it is possible to always define a custom on an activity for this purpose, it is suggested to instead use , or derive from or . Each of these base classes has an named Result that your activity can use for its return value. Activities that return a result should only be used if only one result needs to be returned from an activity; if multiple results need to be returned, separate members should be used instead. diff --git a/docs/framework/windows-workflow-foundation/activity-definition-scoping-and-visibility.md b/docs/framework/windows-workflow-foundation/activity-definition-scoping-and-visibility.md index 6e3ce4c7c71ed..04f107bb6eaec 100644 --- a/docs/framework/windows-workflow-foundation/activity-definition-scoping-and-visibility.md +++ b/docs/framework/windows-workflow-foundation/activity-definition-scoping-and-visibility.md @@ -6,69 +6,69 @@ ms.assetid: ccdffa07-9503-4eea-a61b-17f1564368b7 --- # Activity Definition Scoping and Visibility -Activity definition scoping and visibility, just like scoping and visibility of an object, is the ability of other objects or activities to access members of the activity. Activity definition is performed by the following implementations: - -1. Determining the members (, , and objects, and child activities) an activity exposes to its users. - -2. Implementing the execution logic of the activity - - The implementation may involve members that are not exposed to consumers of the activity, but are rather details of the implementation. Similar to type definition, the activity model allows an author to qualify the visibility of an activity member regarding the definition of the activity being defined. This visibility governs aspects of member usage, such as data scoping. - -## Scope - - In addition to data scoping, activity model visibility can restrict access to other aspects of the activity, such as validation, debugging, tracking, or tracing. Execution properties use visibility and scoping for constraining execution characteristics to a particular scope of definition. Secondary roots use visibility and scoping to constrain the state captured by a to the scope of definition in which the compensable activities are used. - -## Definition and usage - - A workflow is written by authoring new activities by inheriting from base activity classes, and by using activities from the [Built-In Activity Library](net-framework-4-5-built-in-activity-library.md). In order to use an activity, the activity author must configure the visibility of each component of its definition. - -### Activity Members - - The activity model defines the arguments, variables, delegates, and child activities that the activity makes available to consumers. Each of these members can be declared as `public` or `private`. Public members are configured by the consumer of the activity, whereas `private` members use an implementation fixed by the author of the activity. The visibility rules for data scoping are as follows: - -1. Public members and the public members of public child activities can reference public variables. - -2. Private members and the public members of public child activities can reference arguments and private variables. - - A member that can be set by the consumer of an activity should never be made private. - -### Authoring Models - - Custom activities are defined by using , , , or . Activities that derive from these classes can expose different member types with different visibilities. - -#### NativeActivity - - Activities that derive from have behavior that is written in imperative code, and can optionally be defined by using existing activities. Deriving activities from grants access to all of the features exposed by the runtime. Any member of such an activity can be defined by using either public or private visibility, except arguments, which can only be declared as `public`. - - Members of classes derived from are declared to the runtime using the struct passed to the method. - -#### Activity - - Activities created by using have behavior that is designed strictly through composing other activities. The class has one implementation child activity, obtained by the runtime using . An activity deriving from can define public arguments, public variables, imported ActivityDelegates, and imported Activities. - - Imported ActivityDelegates and Activities are declared as public children of the activity, but cannot be directly scheduled by the activity. This information is used during validation to avoid running parent-facing validations at locations where the activity will never execute. Also, imported children, just like public children, can be referenced and scheduled by the activity’s implementation. This means that an activity which imports an activity called Activity1 can contain a in its implementation which schedules Activity1. - -#### CodeActivity/ AsyncCodeActivity - - This base class is used for authoring behavior in imperative code. Activities that derive from this class only have access to the arguments they expose. This means that the only members that these activities can expose are public arguments. No other members or visibilities apply to these activities. - -#### Summary of visibilities - - The following table summarizes the information earlier in this section. - -|Member Type|NativeActivity|Activity|CodeActivity/ AsyncCodeActivity| -|-----------------|--------------------|--------------|--------------------------------------| -|Arguments|Public/ Private|Public|not applicable| -|Variables|Public/ Private|Public|not applicable| -|Child Activities|Public/ Private|Public, one fixed private child defined in Implementation.|not applicable| -|ActivityDelegates|Public/ Private|Public|not applicable| - - In general, a member that cannot be set by the consumer of an activity should not be made public. - -### Execution Properties - - In some scenarios, it is useful to scope a particular execution property to the public children of an activity. The collection provides this capability with the method. This method has a Boolean parameter indicating whether a particular property is scoped to all children, or just those that are public. If this parameter is set to `true`, the property will only be visible to public members and the public members of their public children. - -### Secondary Roots +Activity definition scoping and visibility, just like scoping and visibility of an object, is the ability of other objects or activities to access members of the activity. Activity definition is performed by the following implementations: + +1. Determining the members (, , and objects, and child activities) an activity exposes to its users. + +2. Implementing the execution logic of the activity + + The implementation may involve members that are not exposed to consumers of the activity, but are rather details of the implementation. Similar to type definition, the activity model allows an author to qualify the visibility of an activity member regarding the definition of the activity being defined. This visibility governs aspects of member usage, such as data scoping. + +## Scope + + In addition to data scoping, activity model visibility can restrict access to other aspects of the activity, such as validation, debugging, tracking, or tracing. Execution properties use visibility and scoping for constraining execution characteristics to a particular scope of definition. Secondary roots use visibility and scoping to constrain the state captured by a to the scope of definition in which the compensable activities are used. + +## Definition and usage + + A workflow is written by authoring new activities by inheriting from base activity classes, and by using activities from the [Built-In Activity Library](net-framework-4-5-built-in-activity-library.md). In order to use an activity, the activity author must configure the visibility of each component of its definition. + +### Activity Members + + The activity model defines the arguments, variables, delegates, and child activities that the activity makes available to consumers. Each of these members can be declared as `public` or `private`. Public members are configured by the consumer of the activity, whereas `private` members use an implementation fixed by the author of the activity. The visibility rules for data scoping are as follows: + +1. Public members and the public members of public child activities can reference public variables. + +2. Private members and the public members of public child activities can reference arguments and private variables. + + A member that can be set by the consumer of an activity should never be made private. + +### Authoring Models + + Custom activities are defined by using , , , or . Activities that derive from these classes can expose different member types with different visibilities. + +#### NativeActivity + + Activities that derive from have behavior that is written in imperative code, and can optionally be defined by using existing activities. Deriving activities from grants access to all of the features exposed by the runtime. Any member of such an activity can be defined by using either public or private visibility, except arguments, which can only be declared as `public`. + + Members of classes derived from are declared to the runtime using the struct passed to the method. + +#### Activity + + Activities created by using have behavior that is designed strictly through composing other activities. The class has one implementation child activity, obtained by the runtime using . An activity deriving from can define public arguments, public variables, imported ActivityDelegates, and imported Activities. + + Imported ActivityDelegates and Activities are declared as public children of the activity, but cannot be directly scheduled by the activity. This information is used during validation to avoid running parent-facing validations at locations where the activity will never execute. Also, imported children, just like public children, can be referenced and scheduled by the activity’s implementation. This means that an activity which imports an activity called Activity1 can contain a in its implementation which schedules Activity1. + +#### CodeActivity/ AsyncCodeActivity + + This base class is used for authoring behavior in imperative code. Activities that derive from this class only have access to the arguments they expose. This means that the only members that these activities can expose are public arguments. No other members or visibilities apply to these activities. + +#### Summary of visibilities + + The following table summarizes the information earlier in this section. + +|Member Type|NativeActivity|Activity|CodeActivity/ AsyncCodeActivity| +|-----------------|--------------------|--------------|--------------------------------------| +|Arguments|Public/ Private|Public|not applicable| +|Variables|Public/ Private|Public|not applicable| +|Child Activities|Public/ Private|Public, one fixed private child defined in Implementation.|not applicable| +|ActivityDelegates|Public/ Private|Public|not applicable| + + In general, a member that cannot be set by the consumer of an activity should not be made public. + +### Execution Properties + + In some scenarios, it is useful to scope a particular execution property to the public children of an activity. The collection provides this capability with the method. This method has a Boolean parameter indicating whether a particular property is scoped to all children, or just those that are public. If this parameter is set to `true`, the property will only be visible to public members and the public members of their public children. + +### Secondary Roots A secondary root is the runtime’s internal mechanism for managing state for compensation activities. When a has finished running, its state is not cleaned up immediately. Instead, the state is maintained by the runtime in a secondary root until the compensation episode has completed. The location environments captured with the secondary root correspond to the scope of definition in which the Compensable activity is used. diff --git a/docs/framework/windows-workflow-foundation/activity-tree-inspection.md b/docs/framework/windows-workflow-foundation/activity-tree-inspection.md index 86bd1d4018524..9add30f54fc98 100644 --- a/docs/framework/windows-workflow-foundation/activity-tree-inspection.md +++ b/docs/framework/windows-workflow-foundation/activity-tree-inspection.md @@ -6,43 +6,43 @@ ms.assetid: 100d00e4-8c1d-4233-8fbb-dd443a01155d --- # Activity Tree Inspection -Activity tree inspection is used by workflow application authors to inspect the workflows hosted by the application. By using , workflows can be searched for specific child activities, individual activities and their properties can be enumerated, and runtime metadata of the activities can be cached at a specific time. This topic provides an overview of and how to use it to inspect an activity tree. - -## Using WorkflowInspectionServices - - The method is used to enumerate all of the activities in the specified activity tree. returns an enumerable that touches all activities within the tree including children, delegate handlers, variable defaults, and argument expressions. In the following example, a workflow definition is created by using a , , , , and expressions. After the workflow definition is created, it is invoked and then the `InspectActivity` method is called. - - [!code-csharp[CFX_WorkflowApplicationExample#45](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#45)] - - To enumerate the activities, the is called on the root activity, and again recursively on each returned activity. In the following example, the of each activity and expression in the activity tree is written to the console. - - [!code-csharp[CFX_WorkflowApplicationExample#46](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#46)] - - This sample code provides the following output. - - **List Item 1** +Activity tree inspection is used by workflow application authors to inspect the workflows hosted by the application. By using , workflows can be searched for specific child activities, individual activities and their properties can be enumerated, and runtime metadata of the activities can be cached at a specific time. This topic provides an overview of and how to use it to inspect an activity tree. + +## Using WorkflowInspectionServices + + The method is used to enumerate all of the activities in the specified activity tree. returns an enumerable that touches all activities within the tree including children, delegate handlers, variable defaults, and argument expressions. In the following example, a workflow definition is created by using a , , , , and expressions. After the workflow definition is created, it is invoked and then the `InspectActivity` method is called. + + [!code-csharp[CFX_WorkflowApplicationExample#45](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#45)] + + To enumerate the activities, the is called on the root activity, and again recursively on each returned activity. In the following example, the of each activity and expression in the activity tree is written to the console. + + [!code-csharp[CFX_WorkflowApplicationExample#46](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#46)] + + This sample code provides the following output. + + **List Item 1** **List Item 2** **List Item 3** **List Item 4** **List Item 5** **Items added to collection.** **Sequence** - **Literal>** - **While** - **AddToCollection\** - **VariableValue>** - **LambdaValue\** - **LocationReferenceValue>** - **LambdaValue\** - **LocationReferenceValue>** - **ForEach\** - **VariableValue>** - **WriteLine** - **DelegateArgumentValue\** - **Sequence** - **WriteLine** - **Literal\** To retrieve a specific activity instead of enumerating all of the activities, is used. Both and perform metadata caching if `WorkflowInspectionServices.CacheMetadata` has not been previously called. If has been called then is based on the existing metadata. Therefore, if tree changes have been made since the last call to , might give unexpected results. If changes have been made to the workflow after calling , metadata can be re-cached by calling the method. Caching metadata is discussed in the next section. - -### Caching Metadata - - Caching the metadata for an activity builds and validates a description of the activity’s arguments, variables, child activities, and activity delegates. Metadata, by default, is cached by the runtime when an activity is prepared for execution. If a workflow host author wants to cache the metadata for an activity or activity tree before this, for example to take all of the cost upfront, then can be used to cache the metadata at the desired time. + **Literal>** + **While** + **AddToCollection\** + **VariableValue>** + **LambdaValue\** + **LocationReferenceValue>** + **LambdaValue\** + **LocationReferenceValue>** + **ForEach\** + **VariableValue>** + **WriteLine** + **DelegateArgumentValue\** + **Sequence** + **WriteLine** + **Literal\** To retrieve a specific activity instead of enumerating all of the activities, is used. Both and perform metadata caching if `WorkflowInspectionServices.CacheMetadata` has not been previously called. If has been called then is based on the existing metadata. Therefore, if tree changes have been made since the last call to , might give unexpected results. If changes have been made to the workflow after calling , metadata can be re-cached by calling the method. Caching metadata is discussed in the next section. + +### Caching Metadata + + Caching the metadata for an activity builds and validates a description of the activity’s arguments, variables, child activities, and activity delegates. Metadata, by default, is cached by the runtime when an activity is prepared for execution. If a workflow host author wants to cache the metadata for an activity or activity tree before this, for example to take all of the cost upfront, then can be used to cache the metadata at the desired time. diff --git a/docs/framework/windows-workflow-foundation/architecture.md b/docs/framework/windows-workflow-foundation/architecture.md index addd09e4bb9be..eb62294d811a9 100644 --- a/docs/framework/windows-workflow-foundation/architecture.md +++ b/docs/framework/windows-workflow-foundation/architecture.md @@ -6,46 +6,46 @@ ms.assetid: 1d4c6495-d64a-46d0-896a-3a01fac90aa9 --- # Windows Workflow Architecture -Windows Workflow Foundation (WF) raises the abstraction level for developing interactive long-running applications. Units of work are encapsulated as activities. Activities run in an environment that provides facilities for flow control, exception handling, fault propagation, persistence of state data, loading and unloading of in-progress workflows from memory, tracking, and transaction flow. - -## Activity Architecture - - Activities are developed as CLR types that derive from either , , , or , or their variants that return a value, , , , or . Developing activities that derive from allows the user to assemble pre-existing activities to quickly create units of work that execute in the workflow environment. , on the other hand, enables execution logic to be authored in managed code using primarily for access to activity arguments. is similar to except that it can be used to implement asynchronous tasks. Developing activities that derive from allows users to access the runtime through the for functionality like scheduling children, creating bookmarks, invoking asynchronous work, registering transactions, and more. - - Authoring activities that derive from is declarative and these activities can be authored in XAML. In the following example, an activity called `Prompt` is created using other activities for the execution body. - -```xml - - - - - - - - - - -``` - -## Activity Context - - The is the activity author's interface to the workflow runtime and provides access to the runtime's wealth of features. In the following example, an activity is defined that uses the execution context to create a bookmark (the mechanism that allows an activity to register a continuation point in its execution that can be resumed by a host passing data into the activity). - - [!code-csharp[CFX_WorkflowApplicationExample#15](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#15)] - -## Activity Life Cycle +Windows Workflow Foundation (WF) raises the abstraction level for developing interactive long-running applications. Units of work are encapsulated as activities. Activities run in an environment that provides facilities for flow control, exception handling, fault propagation, persistence of state data, loading and unloading of in-progress workflows from memory, tracking, and transaction flow. + +## Activity Architecture + + Activities are developed as CLR types that derive from either , , , or , or their variants that return a value, , , , or . Developing activities that derive from allows the user to assemble pre-existing activities to quickly create units of work that execute in the workflow environment. , on the other hand, enables execution logic to be authored in managed code using primarily for access to activity arguments. is similar to except that it can be used to implement asynchronous tasks. Developing activities that derive from allows users to access the runtime through the for functionality like scheduling children, creating bookmarks, invoking asynchronous work, registering transactions, and more. + + Authoring activities that derive from is declarative and these activities can be authored in XAML. In the following example, an activity called `Prompt` is created using other activities for the execution body. + +```xml + + + + + + + + + + +``` + +## Activity Context + + The is the activity author's interface to the workflow runtime and provides access to the runtime's wealth of features. In the following example, an activity is defined that uses the execution context to create a bookmark (the mechanism that allows an activity to register a continuation point in its execution that can be resumed by a host passing data into the activity). + + [!code-csharp[CFX_WorkflowApplicationExample#15](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#15)] + +## Activity Life Cycle An instance of an activity starts out in the state. Unless exceptions are encountered, it remains in this state until all child activities are finished executing and any other pending work ( objects, for instance) is completed, at which point it transitions to the state. The parent of an activity instance can request a child to cancel; if the child is able to be canceled it completes in the state. If an exception is thrown during execution, the runtime puts the activity into the state and propagates the exception up the parent chain of activities. The following are the three completion states of an activity: - -- **Closed:** The activity has completed its work and exited. - -- **Canceled:** The activity has gracefully abandoned its work and exited. Work is not explicitly rolled back when this state is entered. - -- **Faulted:** The activity has encountered an error and has exited without completing its work. - + +- **Closed:** The activity has completed its work and exited. + +- **Canceled:** The activity has gracefully abandoned its work and exited. Work is not explicitly rolled back when this state is entered. + +- **Faulted:** The activity has encountered an error and has exited without completing its work. + Activities remain in the state when they are persisted or unloaded. diff --git a/docs/framework/windows-workflow-foundation/authoring-workflows-activities-and-expressions-using-imperative-code.md b/docs/framework/windows-workflow-foundation/authoring-workflows-activities-and-expressions-using-imperative-code.md index 2f99bb7fb4824..18d6a3a2ed33e 100644 --- a/docs/framework/windows-workflow-foundation/authoring-workflows-activities-and-expressions-using-imperative-code.md +++ b/docs/framework/windows-workflow-foundation/authoring-workflows-activities-and-expressions-using-imperative-code.md @@ -17,7 +17,7 @@ A workflow definition is a tree of configured activity objects. This tree of act > [!NOTE] > The examples in this topic use to run the sample workflows. For more information about invoking workflows, passing arguments, and the different hosting choices that are available, see [Using WorkflowInvoker and WorkflowApplication](using-workflowinvoker-and-workflowapplication.md). - In this example, a workflow that consists of a single activity is created. The activity’s argument is set, and the workflow is invoked. If an activity contains child activities, the method of construction is similar. The following example uses a activity that contains two activities. + In this example, a workflow that consists of a single activity is created. The activity’s argument is set, and the workflow is invoked. If an activity contains child activities, the method of construction is similar. The following example uses a activity that contains two activities. [!code-csharp[CFX_WorkflowApplicationExample#48](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#48)] @@ -35,11 +35,11 @@ A workflow definition is a tree of configured activity objects. This tree of act [!code-csharp[CFX_WorkflowApplicationExample#50](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#50)] - When this workflow definition code is executed, the call to `Random.Next` is made and the result is stored in the workflow definition as a literal value. Many instances of this workflow can be invoked, and all would display the same number. To have the random number generation occur during workflow execution, an expression must be used that is evaluated each time the workflow runs. In the following example, a Visual Basic expression is used with a . + When this workflow definition code is executed, the call to `Random.Next` is made and the result is stored in the workflow definition as a literal value. Many instances of this workflow can be invoked, and all would display the same number. To have the random number generation occur during workflow execution, an expression must be used that is evaluated each time the workflow runs. In the following example, a Visual Basic expression is used with a . [!code-csharp[CFX_WorkflowApplicationExample#51](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#51)] - The expression in the previous example could also be implemented using a and a C# expression. + The expression in the previous example could also be implemented using a and a C# expression. ```csharp new Assign @@ -51,10 +51,10 @@ new Assign C# expressions must be compiled before the workflow containing them is invoked. If the C# expressions are not compiled, a is thrown when the workflow is invoked with a message similar to the following: ``Expression Activity type 'CSharpValue`1' requires compilation in order to run. Please ensure that the workflow has been compiled.`` In most scenarios involving workflows created in Visual Studio the C# expressions are compiled automatically, but in some scenarios, such as code workflows, the C# expressions must be manually compiled. For an example of how to compile C# expressions, see the [Using C# expressions in code workflows](csharp-expressions.md#CodeWorkflows) section of the [C# Expressions](csharp-expressions.md) topic. - A represents an expression in Visual Basic syntax that can be used as an r-value in an expression, and a represents an expression in C# syntax that can be used as an r-value in an expression. These expressions are evaluated each time the containing activity is executed. The result of the expression is assigned to the workflow variable `n`, and these results are used by the next activity in the workflow. To access the value of the workflow variable `n` at runtime, the is required. This can be accessed by using the following lambda expression. + A represents an expression in Visual Basic syntax that can be used as an r-value in an expression, and a represents an expression in C# syntax that can be used as an r-value in an expression. These expressions are evaluated each time the containing activity is executed. The result of the expression is assigned to the workflow variable `n`, and these results are used by the next activity in the workflow. To access the value of the workflow variable `n` at runtime, the is required. This can be accessed by using the following lambda expression. > [!NOTE] -> Note that both of these code are examples are using C# as the programming language, but one uses a and one uses a . and can be used in both Visual Basic and C# projects. By default, expressions created in the workflow designer match the language of the hosting project. When creating workflows in code, the desired language is at the discretion of the workflow author. +> Note that both of these code are examples are using C# as the programming language, but one uses a and one uses a . and can be used in both Visual Basic and C# projects. By default, expressions created in the workflow designer match the language of the hosting project. When creating workflows in code, the desired language is at the discretion of the workflow author. In these examples the result of the expression is assigned to the workflow variable `n`, and these results are used by the next activity in the workflow. To access the value of the workflow variable `n` at runtime, the is required. This can be accessed by using the following lambda expression. @@ -62,19 +62,19 @@ new Assign For more information about lambda expressions, see [Lambda Expressions (C# reference)](../../csharp/language-reference/operators/lambda-expressions.md) or [Lambda Expressions (Visual Basic)](../../visual-basic/programming-guide/language-features/procedures/lambda-expressions.md). - Lambda expressions are not serializable to XAML format. If an attempt to serialize a workflow with lambda expressions is made, a is thrown with the following message: "This workflow contains lambda expressions specified in code. These expressions are not XAML serializable. In order to make your workflow XAML-serializable, either use VisualBasicValue/VisualBasicReference or ExpressionServices.Convert(lambda). This will convert your lambda expressions into expression activities." To make this expression compatible with XAML, use and , as shown in the following example. + Lambda expressions are not serializable to XAML format. If an attempt to serialize a workflow with lambda expressions is made, a is thrown with the following message: "This workflow contains lambda expressions specified in code. These expressions are not XAML serializable. In order to make your workflow XAML-serializable, either use VisualBasicValue/VisualBasicReference or ExpressionServices.Convert(lambda). This will convert your lambda expressions into expression activities." To make this expression compatible with XAML, use and , as shown in the following example. [!code-csharp[CFX_WorkflowApplicationExample#53](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#53)] - A could also be used. Note that no lambda expression is required when using a Visual Basic expression. + A could also be used. Note that no lambda expression is required when using a Visual Basic expression. [!code-csharp[CFX_WorkflowApplicationExample#54](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#54)] - At runtime, Visual Basic expressions are compiled into LINQ expressions. Both of the previous examples are serializable to XAML, but if the serialized XAML is intended to be viewed and edited in the workflow designer, use for your expressions. Serialized workflows that use `ExpressionServices.Convert` can be opened in the designer, but the value of the expression will be blank. For more information about serializing workflows to XAML, see [Serializing Workflows and Activities to and from XAML](serializing-workflows-and-activities-to-and-from-xaml.md). + At runtime, Visual Basic expressions are compiled into LINQ expressions. Both of the previous examples are serializable to XAML, but if the serialized XAML is intended to be viewed and edited in the workflow designer, use for your expressions. Serialized workflows that use `ExpressionServices.Convert` can be opened in the designer, but the value of the expression will be blank. For more information about serializing workflows to XAML, see [Serializing Workflows and Activities to and from XAML](serializing-workflows-and-activities-to-and-from-xaml.md). #### Literal Expressions and Reference Types - Literal expressions are represented in workflows by the activity. The following activities are functionally equivalent. + Literal expressions are represented in workflows by the activity. The following activities are functionally equivalent. ```csharp new WriteLine @@ -87,7 +87,7 @@ new WriteLine } ``` - It is invalid to initialize a literal expression with any reference type except . In the following example, an activity's property is initialized with a literal expression using a `List`. + It is invalid to initialize a literal expression with any reference type except . In the following example, an activity's property is initialized with a literal expression using a `List`. ```csharp new Assign @@ -111,11 +111,11 @@ new Assign #### Invoking Methods on Objects using Expressions and the InvokeMethod Activity - The activity can be used to invoke static and instance methods of classes in the .NET Framework. In a previous example in this topic, a random number was generated using the class. + The activity can be used to invoke static and instance methods of classes in the .NET Framework. In a previous example in this topic, a random number was generated using the class. [!code-csharp[CFX_WorkflowApplicationExample#51](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#51)] - The activity could also have been used to call the method of the class. + The activity could also have been used to call the method of the class. ```csharp new InvokeMethod @@ -131,11 +131,11 @@ new InvokeMethod } ``` - Since is not a static method, an instance of the class is supplied for the property. In this example a new instance is created using a Visual Basic expression, but it could also have been created previously and stored in a workflow variable. In this example, it would be simpler to use the activity instead of the activity. If the method call ultimately invoked by either the or activities is long running, has an advantage since it has a property. When this property is set to `true`, the invoked method will run asynchronously with regard to the workflow. If other activities are in parallel, they will not be blocked while the method is asynchronously executing. Also, if the method to be invoked has no return value, then is the appropriate way to invoke the method. + Since is not a static method, an instance of the class is supplied for the property. In this example a new instance is created using a Visual Basic expression, but it could also have been created previously and stored in a workflow variable. In this example, it would be simpler to use the activity instead of the activity. If the method call ultimately invoked by either the or activities is long running, has an advantage since it has a property. When this property is set to `true`, the invoked method will run asynchronously with regard to the workflow. If other activities are in parallel, they will not be blocked while the method is asynchronously executing. Also, if the method to be invoked has no return value, then is the appropriate way to invoke the method. ## Arguments and Dynamic Activities - A workflow definition is created in code by assembling activities into an activity tree and configuring any properties and arguments. Existing arguments can be bound, but new arguments cannot be added to activities. This includes workflow arguments passed to the root activity. In imperative code, workflow arguments are specified as properties on a new CLR type, and in XAML they are declared by using `x:Class` and `x:Member`. Because there is no new CLR type created when a workflow definition is created as a tree of in-memory objects, arguments cannot be added. However, arguments can be added to a . In this example, a is created that takes two integer arguments, adds them together, and returns the result. A is created for each argument, and the result of the operation is assigned to the argument of the . + A workflow definition is created in code by assembling activities into an activity tree and configuring any properties and arguments. Existing arguments can be bound, but new arguments cannot be added to activities. This includes workflow arguments passed to the root activity. In imperative code, workflow arguments are specified as properties on a new CLR type, and in XAML they are declared by using `x:Class` and `x:Member`. Because there is no new CLR type created when a workflow definition is created as a tree of in-memory objects, arguments cannot be added. However, arguments can be added to a . In this example, a is created that takes two integer arguments, adds them together, and returns the result. A is created for each argument, and the result of the operation is assigned to the argument of the . [!code-csharp[CFX_WorkflowApplicationExample#55](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#55)] @@ -147,7 +147,7 @@ new InvokeMethod Activities that derive from can define their logic using imperative code and they can also contain child activities that define the logic. They also have full access to the features of the runtime such as creating bookmarks. For examples of creating a -based activity, see [NativeActivity Base Class](nativeactivity-base-class.md), [How to: Create an Activity](how-to-create-an-activity.md), and the [Custom Composite using Native Activity](./samples/custom-composite-using-native-activity.md) sample. - Activities that derive from define their logic solely through the use of child activities. These activities are typically created by using the workflow designer, but can also be defined by using code. In the following example, a `Square` activity is defined that derives from `Activity`. The `Square` activity has a single named `Value`, and defines its logic by specifying a activity using the property. The activity contains a activity and an activity. Together, these three activities implement the logic of the `Square` activity. + Activities that derive from define their logic solely through the use of child activities. These activities are typically created by using the workflow designer, but can also be defined by using code. In the following example, a `Square` activity is defined that derives from `Activity`. The `Square` activity has a single named `Value`, and defines its logic by specifying a activity using the property. The activity contains a activity and an activity. Together, these three activities implement the logic of the `Square` activity. ```csharp class Square : Activity diff --git a/docs/framework/windows-workflow-foundation/binding-a-custom-activity-property-to-a-designer-control.md b/docs/framework/windows-workflow-foundation/binding-a-custom-activity-property-to-a-designer-control.md index c1d58fc5dd958..479c3ec6c0d98 100644 --- a/docs/framework/windows-workflow-foundation/binding-a-custom-activity-property-to-a-designer-control.md +++ b/docs/framework/windows-workflow-foundation/binding-a-custom-activity-property-to-a-designer-control.md @@ -15,7 +15,7 @@ Binding a text box designer control to an activity argument is fairly straightfo 2. Create a new class called ComboBoxItemConverter. Add a reference to System.Windows.Data, and have the class derive from . Have Visual Studio implement the interface to generate stubs for `Convert` and `ConvertBack`. -3. Add the following code to the `Convert` method. This code converts the activity's of type to the value to be placed in the designer. +3. Add the following code to the `Convert` method. This code converts the activity's of type to the value to be placed in the designer. ```csharp ModelItem modelItem = value as ModelItem; @@ -42,7 +42,7 @@ Binding a text box designer control to an activity argument is fairly straightfo return null; ``` - The expression in the above code snippet can also be created using instead of . + The expression in the above code snippet can also be created using instead of . ```csharp ModelItem modelItem = value as ModelItem; @@ -69,7 +69,7 @@ Binding a text box designer control to an activity argument is fairly straightfo return null; ``` -4. Add the following code to the `ConvertBack` method. This code converts the incoming combo box item back to an . +4. Add the following code to the `ConvertBack` method. This code converts the incoming combo box item back to an . ```csharp // Convert combo box value to InArgument @@ -79,7 +79,7 @@ Binding a text box designer control to an activity argument is fairly straightfo return inArgument; ``` - The expression in the above code snippet can also be created using instead of . + The expression in the above code snippet can also be created using instead of . ```csharp // Convert combo box value to InArgument diff --git a/docs/framework/windows-workflow-foundation/bookmarks.md b/docs/framework/windows-workflow-foundation/bookmarks.md index 46783668ddf69..aeafdc7694d8c 100644 --- a/docs/framework/windows-workflow-foundation/bookmarks.md +++ b/docs/framework/windows-workflow-foundation/bookmarks.md @@ -6,112 +6,112 @@ ms.assetid: 9b51a346-09ae-455c-a70a-e2264ddeb9e2 --- # Bookmarks -Bookmarks are the mechanism that enables an activity to passively wait for input without holding onto a workflow thread. When an activity signals that it is waiting for stimulus, it can create a bookmark. This indicates to the runtime that the activity’s execution should not be considered complete even when the currently executing method (which created the ) returns. - -## Bookmark Basics - - A represents a point at which execution can be resumed (and through which input can be delivered) within a workflow instance. Typically, a is given a name and external (host or extension) code is responsible for resuming the bookmark with relevant data. When a is resumed, the workflow runtime schedules the delegate that was associated with that at the time of its creation. - -## Bookmark Options - - The class specifies the type of being created. The possible non mutually-exclusive values are , , and . Use , the default, when creating a that is expected to be resumed exactly once. Use when creating a that can be resumed multiple times. Use when creating a that might never be resumed. Unlike bookmarks created using the default , bookmarks do not prevent an activity from completing. - -## Bookmark Resumption - - Bookmarks can be resumed by code outside of a workflow using one of the overloads. In this example, a `ReadLine` activity is created. When executed, the `ReadLine` activity creates a , registers a callback, and then waits for the to be resumed. When it is resumed, the `ReadLine` activity assigns the data that was passed with the to its argument. - -```csharp -public sealed class ReadLine : NativeActivity -{ - [RequiredArgument] - public InArgument BookmarkName { get; set; } - - protected override void Execute(NativeActivityContext context) - { - // Create a Bookmark and wait for it to be resumed. +Bookmarks are the mechanism that enables an activity to passively wait for input without holding onto a workflow thread. When an activity signals that it is waiting for stimulus, it can create a bookmark. This indicates to the runtime that the activity’s execution should not be considered complete even when the currently executing method (which created the ) returns. + +## Bookmark Basics + + A represents a point at which execution can be resumed (and through which input can be delivered) within a workflow instance. Typically, a is given a name and external (host or extension) code is responsible for resuming the bookmark with relevant data. When a is resumed, the workflow runtime schedules the delegate that was associated with that at the time of its creation. + +## Bookmark Options + + The class specifies the type of being created. The possible non mutually-exclusive values are , , and . Use , the default, when creating a that is expected to be resumed exactly once. Use when creating a that can be resumed multiple times. Use when creating a that might never be resumed. Unlike bookmarks created using the default , bookmarks do not prevent an activity from completing. + +## Bookmark Resumption + + Bookmarks can be resumed by code outside of a workflow using one of the overloads. In this example, a `ReadLine` activity is created. When executed, the `ReadLine` activity creates a , registers a callback, and then waits for the to be resumed. When it is resumed, the `ReadLine` activity assigns the data that was passed with the to its argument. + +```csharp +public sealed class ReadLine : NativeActivity +{ + [RequiredArgument] + public InArgument BookmarkName { get; set; } + + protected override void Execute(NativeActivityContext context) + { + // Create a Bookmark and wait for it to be resumed. context.CreateBookmark(BookmarkName.Get(context), - new BookmarkCallback(OnResumeBookmark)); - } - + new BookmarkCallback(OnResumeBookmark)); + } + // NativeActivity derived activities that do asynchronous operations by calling // one of the CreateBookmark overloads defined on System.Activities.NativeActivityContext - // must override the CanInduceIdle property and return true. - protected override bool CanInduceIdle - { - get { return true; } - } - - public void OnResumeBookmark(NativeActivityContext context, Bookmark bookmark, object obj) - { - // When the Bookmark is resumed, assign its value to - // the Result argument. - Result.Set(context, (string)obj); - } -} -``` - - In this example, a workflow is created that uses the `ReadLine` activity to gather the user’s name and display it to the console window. The host application performs the actual work of gathering the input and passes it to the workflow by resuming the . - -```csharp -Variable name = new Variable -{ - Name = "name" -}; - -Activity wf = new Sequence -{ - Variables = - { - name - }, - Activities = - { - new WriteLine() - { - Text = "What is your name?" - }, - new ReadLine() - { - BookmarkName = "UserName", - Result = name - }, - new WriteLine() - { - Text = new InArgument((env) => "Hello, " + name.Get(env)) - } - } -}; - -AutoResetEvent syncEvent = new AutoResetEvent(false); - -// Create the WorkflowApplication using the desired -// workflow definition. -WorkflowApplication wfApp = new WorkflowApplication(wf); - -// Handle the desired lifecycle events. -wfApp.Completed = delegate(WorkflowApplicationCompletedEventArgs e) -{ - // Signal the host that the workflow is complete. - syncEvent.Set(); -}; - -// Start the workflow. -wfApp.Run(); - -// Collect the user's name and resume the bookmark. -// Bookmark resumption only occurs when the workflow -// is idle. If a call to ResumeBookmark is made and the workflow -// is not idle, ResumeBookmark blocks until the workflow becomes -// idle before resuming the bookmark. -wfApp.ResumeBookmark("UserName", Console.ReadLine()); - -// Wait for Completed to arrive and signal that -// the workflow is complete. -syncEvent.WaitOne(); -``` - - When the `ReadLine` activity is executed, it creates a named `UserName` and then waits for the bookmark to be resumed. The host collects the desired data and then resumes the . The workflow resumes, displays the name, and then completes. Note that no synchronization code is required with regard to resuming the bookmark. A can only be resumed when the workflow is idle, and if the workflow is not idle, the call to blocks until the workflow becomes idle. - -## Bookmark Resumption Result - - returns a enumeration value to indicate the results of the bookmark resumption request. The possible return values are , , and . Hosts and extensions can use this value to determine how to proceed. + // must override the CanInduceIdle property and return true. + protected override bool CanInduceIdle + { + get { return true; } + } + + public void OnResumeBookmark(NativeActivityContext context, Bookmark bookmark, object obj) + { + // When the Bookmark is resumed, assign its value to + // the Result argument. + Result.Set(context, (string)obj); + } +} +``` + + In this example, a workflow is created that uses the `ReadLine` activity to gather the user’s name and display it to the console window. The host application performs the actual work of gathering the input and passes it to the workflow by resuming the . + +```csharp +Variable name = new Variable +{ + Name = "name" +}; + +Activity wf = new Sequence +{ + Variables = + { + name + }, + Activities = + { + new WriteLine() + { + Text = "What is your name?" + }, + new ReadLine() + { + BookmarkName = "UserName", + Result = name + }, + new WriteLine() + { + Text = new InArgument((env) => "Hello, " + name.Get(env)) + } + } +}; + +AutoResetEvent syncEvent = new AutoResetEvent(false); + +// Create the WorkflowApplication using the desired +// workflow definition. +WorkflowApplication wfApp = new WorkflowApplication(wf); + +// Handle the desired lifecycle events. +wfApp.Completed = delegate(WorkflowApplicationCompletedEventArgs e) +{ + // Signal the host that the workflow is complete. + syncEvent.Set(); +}; + +// Start the workflow. +wfApp.Run(); + +// Collect the user's name and resume the bookmark. +// Bookmark resumption only occurs when the workflow +// is idle. If a call to ResumeBookmark is made and the workflow +// is not idle, ResumeBookmark blocks until the workflow becomes +// idle before resuming the bookmark. +wfApp.ResumeBookmark("UserName", Console.ReadLine()); + +// Wait for Completed to arrive and signal that +// the workflow is complete. +syncEvent.WaitOne(); +``` + + When the `ReadLine` activity is executed, it creates a named `UserName` and then waits for the bookmark to be resumed. The host collects the desired data and then resumes the . The workflow resumes, displays the name, and then completes. Note that no synchronization code is required with regard to resuming the bookmark. A can only be resumed when the workflow is idle, and if the workflow is not idle, the call to blocks until the workflow becomes idle. + +## Bookmark Resumption Result + + returns a enumeration value to indicate the results of the bookmark resumption request. The possible return values are , , and . Hosts and extensions can use this value to determine how to proceed. diff --git a/docs/framework/windows-workflow-foundation/collection-activities-in-wf.md b/docs/framework/windows-workflow-foundation/collection-activities-in-wf.md index 770f0a3b50eaa..1da568ef92041 100644 --- a/docs/framework/windows-workflow-foundation/collection-activities-in-wf.md +++ b/docs/framework/windows-workflow-foundation/collection-activities-in-wf.md @@ -6,422 +6,422 @@ ms.assetid: 2680c3e2-9902-4968-b98d-cab776103dbe --- # Collection Activities in WF -Collection activities are used to work with collection objects in a workflow. [!INCLUDE[netfx_current_long](../../../includes/netfx-current-long-md.md)] has system-provided activities for adding and removing items from a collection, testing for the existence of an item in a collection, and clearing a collection. `ExistsInCollection` and `RemoveFromCollection` have an of type , which indicates the result. - +Collection activities are used to work with collection objects in a workflow. [!INCLUDE[netfx_current_long](../../../includes/netfx-current-long-md.md)] has system-provided activities for adding and removing items from a collection, testing for the existence of an item in a collection, and clearing a collection. `ExistsInCollection` and `RemoveFromCollection` have an of type , which indicates the result. + > [!IMPORTANT] -> If a collection activity is executed before setting the underlying collection object, an is thrown and the activity faults. - -## Collection activities - +> If a collection activity is executed before setting the underlying collection object, an is thrown and the activity faults. + +## Collection activities + | Activity type | Description | | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | -| | Adds an item to a specified collection. | -| | Clears all items from a specified collection. | -| | Returns `true` if an item exists in a collection. | -| | Removes an item from a specified collection and returns `true` if the item was successfully removed. | - -## Using collection activities +| | Adds an item to a specified collection. | +| | Clears all items from a specified collection. | +| | Returns `true` if an item exists in a collection. | +| | Removes an item from a specified collection and returns `true` if the item was successfully removed. | + +## Using collection activities + + The following code example demonstrates how to interact with a collection declared as a workflow variable. The collection used is a of objects named `fruitList`. + +```csharp +Variable> fruitList = new Variable> +{ + Default = new VisualBasicValue>("New List(Of String) From {\"Apple\", \"Orange\"}"), + Name = "FruitList" +}; + +Variable result = new Variable +{ + Name = "Result" +}; + +Activity wf = new Sequence +{ + Variables = { fruitList, result }, - The following code example demonstrates how to interact with a collection declared as a workflow variable. The collection used is a of objects named `fruitList`. - -```csharp -Variable> fruitList = new Variable> -{ - Default = new VisualBasicValue>("New List(Of String) From {\"Apple\", \"Orange\"}"), - Name = "FruitList" -}; - -Variable result = new Variable -{ - Name = "Result" -}; - -Activity wf = new Sequence -{ - Variables = { fruitList, result }, - Activities = - { - new If - { - Condition = new ExistsInCollection - { - Collection = fruitList, - Item = "Pear" - }, - Then = new AddToCollection - { - Collection = fruitList, - Item = "Pear" - }, - Else = new RemoveFromCollection - { - Collection = fruitList, - Item = "Apple" - } - }, - - new RemoveFromCollection - { - Collection = fruitList, - Item = "Apple", - Result = result - }, - new If - { - Condition = result, - Then = new ClearCollection - { - Collection = fruitList, - } - } - } -}; -``` - -```xaml - - - __ReferenceID0 - __ReferenceID1 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - - The above code samples can also be created using instead of - + { + new If + { + Condition = new ExistsInCollection + { + Collection = fruitList, + Item = "Pear" + }, + Then = new AddToCollection + { + Collection = fruitList, + Item = "Pear" + }, + Else = new RemoveFromCollection + { + Collection = fruitList, + Item = "Apple" + } + }, + + new RemoveFromCollection + { + Collection = fruitList, + Item = "Apple", + Result = result + }, + new If + { + Condition = result, + Then = new ClearCollection + { + Collection = fruitList, + } + } + } +}; +``` + +```xaml + + + __ReferenceID0 + __ReferenceID1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + + The above code samples can also be created using instead of + ```csharp -Variable> fruitList = new Variable> -{ - Default = new CSharpValue>("new List From {\"Apple\", \"Orange\"};"), - Name = "FruitList" -}; - -Variable result = new Variable -{ - Name = "Result" -}; - -Activity wf = new Sequence -{ - Variables = { fruitList, result }, - +Variable> fruitList = new Variable> +{ + Default = new CSharpValue>("new List From {\"Apple\", \"Orange\"};"), + Name = "FruitList" +}; + +Variable result = new Variable +{ + Name = "Result" +}; + +Activity wf = new Sequence +{ + Variables = { fruitList, result }, + Activities = - { - new If - { - Condition = new ExistsInCollection - { - Collection = fruitList, - Item = "Pear" - }, - Then = new AddToCollection - { - Collection = fruitList, - Item = "Pear" - }, - Else = new RemoveFromCollection - { - Collection = fruitList, - Item = "Apple" - } - }, - - new RemoveFromCollection - { - Collection = fruitList, - Item = "Apple", - Result = result - }, - new If - { - Condition = result, - Then = new ClearCollection - { - Collection = fruitList, - } - } - } -}; -``` - -```xml - - - __ReferenceID0 - __ReferenceID1 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - + { + new If + { + Condition = new ExistsInCollection + { + Collection = fruitList, + Item = "Pear" + }, + Then = new AddToCollection + { + Collection = fruitList, + Item = "Pear" + }, + Else = new RemoveFromCollection + { + Collection = fruitList, + Item = "Apple" + } + }, + + new RemoveFromCollection + { + Collection = fruitList, + Item = "Apple", + Result = result + }, + new If + { + Condition = result, + Then = new ClearCollection + { + Collection = fruitList, + } + } + } +}; +``` + +```xml + + + __ReferenceID0 + __ReferenceID1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + ## See also - [Authoring Workflows, Activities, and Expressions Using Imperative Code](authoring-workflows-activities-and-expressions-using-imperative-code.md) diff --git a/docs/framework/windows-workflow-foundation/compensation.md b/docs/framework/windows-workflow-foundation/compensation.md index 1630224874f8a..e9a1793f06b4c 100644 --- a/docs/framework/windows-workflow-foundation/compensation.md +++ b/docs/framework/windows-workflow-foundation/compensation.md @@ -17,7 +17,7 @@ Compensation in Windows Workflow Foundation (WF) is the mechanism by which previ ## Using CompensableActivity - is the core compensation activity in WF. Any activities that perform work that may need to be compensated are placed into the of a . In this example, the reservation step of purchasing a flight is placed into the of a and the cancellation of the reservation is placed into the . Immediately following the in the workflow are two activities that wait for manager approval and then complete the purchasing step of the flight. If an error condition causes the workflow to be canceled after the has successfully completed, then the activities in the handler are scheduled and the flight is canceled. + is the core compensation activity in WF. Any activities that perform work that may need to be compensated are placed into the of a . In this example, the reservation step of purchasing a flight is placed into the of a and the cancellation of the reservation is placed into the . Immediately following the in the workflow are two activities that wait for manager approval and then complete the purchasing step of the flight. If an error condition causes the workflow to be canceled after the has successfully completed, then the activities in the handler are scheduled and the flight is canceled. [!code-csharp[CFX_CompensationExample#1](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_CompensationExample/cs/Program.cs#1)] @@ -99,12 +99,12 @@ Compensation in Windows Workflow Foundation (WF) is the mechanism by which previ ### Cancellation and CompensableActivity - If the activities in the of a have not completed and the activity is canceled, the activities in the are executed. + If the activities in the of a have not completed and the activity is canceled, the activities in the are executed. > [!NOTE] -> The is only invoked if the activities in the of the have not completed and the activity is canceled. The is only executed if the activities in the of the have successfully completed and compensation is subsequently invoked on the activity. +> The is only invoked if the activities in the of the have not completed and the activity is canceled. The is only executed if the activities in the of the have successfully completed and compensation is subsequently invoked on the activity. - The gives workflow authors the opportunity to provide any appropriate cancellation logic. In the following example, an exception is thrown during the execution of the , and then the is invoked. + The gives workflow authors the opportunity to provide any appropriate cancellation logic. In the following example, an exception is thrown during the execution of the , and then the is invoked. ```csharp Activity wf = new Sequence() @@ -160,7 +160,7 @@ Activity wf = new Sequence() ``` - When the workflow is invoked, the simulated error condition exception is handled by the host application in , the workflow is canceled, and the cancellation logic of the is invoked. In this example, the compensation logic and the cancellation logic have different goals. If the completed successfully, then this means the credit card was charged and the flight booked, so the compensation should undo both steps. (In this example, canceling the flight automatically cancels the credit card charges.) However, if the is canceled, this means the did not complete and so the logic of the needs to be able to determine how to best handle the cancellation. In this example, the cancels the credit card charge, but since `ReserveFlight` was the last activity in the , it does not attempt to cancel the flight. Since `ReserveFlight` was the last activity in the , if it had successfully completed then the would have completed and no cancellation would be possible. + When the workflow is invoked, the simulated error condition exception is handled by the host application in , the workflow is canceled, and the cancellation logic of the is invoked. In this example, the compensation logic and the cancellation logic have different goals. If the completed successfully, then this means the credit card was charged and the flight booked, so the compensation should undo both steps. (In this example, canceling the flight automatically cancels the credit card charges.) However, if the is canceled, this means the did not complete and so the logic of the needs to be able to determine how to best handle the cancellation. In this example, the cancels the credit card charge, but since `ReserveFlight` was the last activity in the , it does not attempt to cancel the flight. Since `ReserveFlight` was the last activity in the , if it had successfully completed then the would have completed and no cancellation would be possible. **ChargeCreditCard: Charge credit card for flight.** **SimulatedErrorCondition: Throwing an ApplicationException.** @@ -171,7 +171,7 @@ Activity wf = new Sequence() ### Explicit Compensation Using the Compensate Activity - In the previous section, implicit compensation was covered. Implicit compensation can be appropriate for simple scenarios, but if more explicit control is required over the scheduling of compensation handling then the activity can be used. To initiate the compensation process with the activity, the of the for which compensation is desired is used. The activity can be used to initiate compensation on any completed that has not been confirmed or compensated. For example, a activity could be used in the section of a activity, or any time after the has completed. In this example, the activity is used in the section of a activity to reverse the action of the . + In the previous section, implicit compensation was covered. Implicit compensation can be appropriate for simple scenarios, but if more explicit control is required over the scheduling of compensation handling then the activity can be used. To initiate the compensation process with the activity, the of the for which compensation is desired is used. The activity can be used to initiate compensation on any completed that has not been confirmed or compensated. For example, a activity could be used in the section of a activity, or any time after the has completed. In this example, the activity is used in the section of a activity to reverse the action of the . [!code-csharp[CFX_CompensationExample#3](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_CompensationExample/cs/Program.cs#3)] @@ -253,7 +253,7 @@ Activity wf = new Sequence() ### Confirming Compensation - By default, compensable activities can be compensated any time after they have completed. In some scenarios this may not be appropriate. In the previous example the compensation to reserving the ticket was to cancel the reservation. However, after the flight has been completed this compensation step is no longer valid. Confirming the compensable activity invokes the activity specified by the . One possible use for this is to allow any resources that are necessary to perform the compensation to be released. After a compensable activity is confirmed it is not possible for it to be compensated, and if this is attempted an exception is thrown. When a workflow completes successfully, all non-confirmed and non-compensated compensable activities that completed successfully are confirmed in reverse order of completion. In this example the flight is reserved, purchased, and completed, and then the compensable activity is confirmed. To confirm a , use the activity and specify the of the to confirm. + By default, compensable activities can be compensated any time after they have completed. In some scenarios this may not be appropriate. In the previous example the compensation to reserving the ticket was to cancel the reservation. However, after the flight has been completed this compensation step is no longer valid. Confirming the compensable activity invokes the activity specified by the . One possible use for this is to allow any resources that are necessary to perform the compensation to be released. After a compensable activity is confirmed it is not possible for it to be compensated, and if this is attempted an exception is thrown. When a workflow completes successfully, all non-confirmed and non-compensated compensable activities that completed successfully are confirmed in reverse order of completion. In this example the flight is reserved, purchased, and completed, and then the compensable activity is confirmed. To confirm a , use the activity and specify the of the to confirm. [!code-csharp[CFX_CompensationExample#4](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_CompensationExample/cs/Program.cs#4)] @@ -326,7 +326,7 @@ When the workflow is invoked, the following output is displayed to the console. ## Nesting Compensation Activities -A can be placed into the section of another . A may not be placed into a handler of another . It is the responsibility of a parent to ensure that when it is canceled, confirmed, or compensated, all child compensable activities that have completed successfully and have not already been confirmed or compensated must be confirmed or compensated before the parent completes cancellation, confirmation, or compensation. If this is not modeled explicitly the parent will implicitly compensate child compensable activities if the parent received the cancel or compensate signal. If the parent received the confirm signal the parent will implicitly confirm child compensable activities. If the logic to handle cancellation, confirmation, or compensation is explicitly modeled in the handler of the parent , any child not explicitly handled will be implicitly confirmed. +A can be placed into the section of another . A may not be placed into a handler of another . It is the responsibility of a parent to ensure that when it is canceled, confirmed, or compensated, all child compensable activities that have completed successfully and have not already been confirmed or compensated must be confirmed or compensated before the parent completes cancellation, confirmation, or compensation. If this is not modeled explicitly the parent will implicitly compensate child compensable activities if the parent received the cancel or compensate signal. If the parent received the confirm signal the parent will implicitly confirm child compensable activities. If the logic to handle cancellation, confirmation, or compensation is explicitly modeled in the handler of the parent , any child not explicitly handled will be implicitly confirmed. ## See also diff --git a/docs/framework/windows-workflow-foundation/configuring-tracking-for-a-workflow.md b/docs/framework/windows-workflow-foundation/configuring-tracking-for-a-workflow.md index 1455a4452df10..028e2211f0355 100644 --- a/docs/framework/windows-workflow-foundation/configuring-tracking-for-a-workflow.md +++ b/docs/framework/windows-workflow-foundation/configuring-tracking-for-a-workflow.md @@ -47,7 +47,7 @@ instance.Extensions.Add(trackingParticipant); ### Configuring Workflow Service Tracking -A workflow can be exposed as a WCF service when hosted in the service host. is a specialized .NET ServiceHost implementation for a workflow-based service. This section explains how to configure tracking for a .NET Framework 4.6.1 workflow service running in . It is configured through a Web.config file (for a Web-hosted service) or an App.config file (for a service hosted in a stand-alone application, such as a console application) by specifying a service behavior or through code by adding a tracking-specific behavior to the collection for the service host. +A workflow can be exposed as a WCF service when hosted in the service host. is a specialized .NET ServiceHost implementation for a workflow-based service. This section explains how to configure tracking for a .NET Framework 4.6.1 workflow service running in . It is configured through a Web.config file (for a Web-hosted service) or an App.config file (for a service hosted in a stand-alone application, such as a console application) by specifying a service behavior or through code by adding a tracking-specific behavior to the collection for the service host. For a workflow service hosted in , you can add the using the <`behavior`> element in a configuration file, as shown in the following example. diff --git a/docs/framework/windows-workflow-foundation/consuming-odata-feeds-from-a-workflow.md b/docs/framework/windows-workflow-foundation/consuming-odata-feeds-from-a-workflow.md index 4666f4d6a5d2b..9fb24972359d2 100644 --- a/docs/framework/windows-workflow-foundation/consuming-odata-feeds-from-a-workflow.md +++ b/docs/framework/windows-workflow-foundation/consuming-odata-feeds-from-a-workflow.md @@ -14,7 +14,7 @@ The examples in this topic use the sample Northwind data service located at and . These classes enable you to query a data service and then work with the returned entity data as CLR objects. This section covers two approaches to creating activities that use the client libraries. +WCF Data Services includes client libraries that enable you to more easily consume an OData feed from .NET Framework and client applications. These libraries simplify sending and receiving HTTP messages. They also translate the message payload into CLR objects that represent entity data. The client libraries feature the two core classes and . These classes enable you to query a data service and then work with the returned entity data as CLR objects. This section covers two approaches to creating activities that use the client libraries. ### Adding a service reference to the WCF Data service @@ -36,13 +36,13 @@ To address possible latency issues that may occur when accessing resources over ### Using client library asynchronous methods -The class provides and methods for querying an OData service asynchronously. These methods can be called from the and overrides of an derived class. When the override returns, the workflow can go idle (but not persist), and when the asynchronous work is completed, is invoked by the runtime. +The class provides and methods for querying an OData service asynchronously. These methods can be called from the and overrides of an derived class. When the override returns, the workflow can go idle (but not persist), and when the asynchronous work is completed, is invoked by the runtime. -In the following example, an `OrdersByCustomer` activity is defined that has two input arguments. The `CustomerId` argument represents the customer who identifies which orders to return, and the `ServiceUri` argument represents the URI of the OData service to be queried. Because the activity derives from `AsyncCodeActivity>` there is also a output argument that is used to return the results of the query. The override creates a LINQ query that selects all orders of the specified customer. This query is specified as the of the passed , and then the query's method is called. Note that the callback and state that are passed into the query's are the ones that are passed in to the activity's method. When the query has finished executing, the activity's method is invoked. The query is retrieved from the , and then the query's method is called. This method returns an of the specified entity type; in this case `Order`. Since `IEnumerable` is the generic type of the , this is set as the of the activity. +In the following example, an `OrdersByCustomer` activity is defined that has two input arguments. The `CustomerId` argument represents the customer who identifies which orders to return, and the `ServiceUri` argument represents the URI of the OData service to be queried. Because the activity derives from `AsyncCodeActivity>` there is also a output argument that is used to return the results of the query. The override creates a LINQ query that selects all orders of the specified customer. This query is specified as the of the passed , and then the query's method is called. Note that the callback and state that are passed into the query's are the ones that are passed in to the activity's method. When the query has finished executing, the activity's method is invoked. The query is retrieved from the , and then the query's method is called. This method returns an of the specified entity type; in this case `Order`. Since `IEnumerable` is the generic type of the , this is set as the of the activity. [!code-csharp[CFX_WCFDataServicesActivityExample#100](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_WCFDataServicesActivityExample/cs/Program.cs#100)] -In the following example, the `OrdersByCustomer` activity retrieves a list of orders for the specified customer, and then a activity enumerates the returned orders and writes the date of each order to the console. +In the following example, the `OrdersByCustomer` activity retrieves a list of orders for the specified customer, and then a activity enumerates the returned orders and writes the date of each order to the console. [!code-csharp[CFX_WCFDataServicesActivityExample#10](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_WCFDataServicesActivityExample/cs/Program.cs#10)] @@ -63,27 +63,27 @@ Calling WCF Data Service... > > Unhandled Exception: System.InvalidOperationException: An error occurred while processing this request. ---> System.Net.WebException: Unable to connect to the remote server ---> System.Net.Sockets.SocketException: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond. -If any additional processing of the data returned by the query is required, it can be done in the activity's override. Both and are invoked by using the workflow thread, and any code in these overrides does not run asynchronously. If the additional processing is extensive or long-running, or the query results are paged, you should consider the approach discussed in the next section, which uses a delegate to execute the query and perform additional processing asynchronously. +If any additional processing of the data returned by the query is required, it can be done in the activity's override. Both and are invoked by using the workflow thread, and any code in these overrides does not run asynchronously. If the additional processing is extensive or long-running, or the query results are paged, you should consider the approach discussed in the next section, which uses a delegate to execute the query and perform additional processing asynchronously. ### Using a delegate -In addition to invoking the asynchronous method of a .NET Framework class, an -based activity can also define the asynchronous logic in one of its methods. This method is specified by using a delegate in the activity's override. When the method returns, the runtime invokes the activity's override. When calling an OData service from a workflow, this method can be used to query the service and provide any additional processing. +In addition to invoking the asynchronous method of a .NET Framework class, an -based activity can also define the asynchronous logic in one of its methods. This method is specified by using a delegate in the activity's override. When the method returns, the runtime invokes the activity's override. When calling an OData service from a workflow, this method can be used to query the service and provide any additional processing. In the following example, a `ListCustomers` activity is defined. This activity queries the sample Northwind data service and returns a `List` that contains all of the customers in the Northwind database. The asynchronous work is performed by the `GetCustomers` method. This method queries the service for all customers, and then copies them into a `List`. It then checks to see if the results are paged. If so, it queries the service for the next page of results, adds them to the list, and continues until all of the customer data has been retrieved. > [!NOTE] > For more information about paging in WCF Data Services, see [How to: Load Paged Results (WCF Data Services)](/previous-versions/dotnet/framework/data/wcf/how-to-load-paged-results-wcf-data-services). -Once all customers are added, the list is returned. The `GetCustomers` method is specified in the activity's override. Since the method has a return value, a `Func>` is created to specify the method. +Once all customers are added, the list is returned. The `GetCustomers` method is specified in the activity's override. Since the method has a return value, a `Func>` is created to specify the method. > [!NOTE] -> If the method that performs the asynchronous work does not have a return value, an is used instead of a . For examples of creating an asynchronous example using both approaches, see [Creating Asynchronous Activities](creating-asynchronous-activities-in-wf.md). +> If the method that performs the asynchronous work does not have a return value, an is used instead of a . For examples of creating an asynchronous example using both approaches, see [Creating Asynchronous Activities](creating-asynchronous-activities-in-wf.md). -This is assigned to the , and then `BeginInvoke` is called. Since the method to be invoked does not have access to the activity's environment of arguments, the value of the `ServiceUri` argument is passed as the first parameter, together with the callback and state that were passed into . When `GetCustomers` returns, the runtime invokes . The code in retrieves the delegate from the , calls `EndInvoke`, and returns the result, which is the list of customers returned from the `GetCustomers` method. +This is assigned to the , and then `BeginInvoke` is called. Since the method to be invoked does not have access to the activity's environment of arguments, the value of the `ServiceUri` argument is passed as the first parameter, together with the callback and state that were passed into . When `GetCustomers` returns, the runtime invokes . The code in retrieves the delegate from the , calls `EndInvoke`, and returns the result, which is the list of customers returned from the `GetCustomers` method. [!code-csharp[CFX_WCFDataServicesActivityExample#200](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_WCFDataServicesActivityExample/cs/Program.cs#200)] -In the following example, the `ListCustomers` activity retrieves a list of customers, and then a activity enumerates them and writes the company name and contact name of each customer to the console. +In the following example, the `ListCustomers` activity retrieves a list of customers, and then a activity enumerates them and writes the company name and contact name of each customer to the console. [!code-csharp[CFX_WCFDataServicesActivityExample#20](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_WCFDataServicesActivityExample/cs/Program.cs#20)] @@ -113,11 +113,11 @@ Raw data returned: Maria Anders ``` -In a workflow, the code from this example could be incorporated into the override of a -based custom activity, but the same functionality can also be accomplished by using the activity. The activity enables workflow authors to invoke static and instance methods of a class, and also has an option to invoke the specified method asynchronously. In the following example, an activity is configured to call the method of the class and return a list of customers. +In a workflow, the code from this example could be incorporated into the override of a -based custom activity, but the same functionality can also be accomplished by using the activity. The activity enables workflow authors to invoke static and instance methods of a class, and also has an option to invoke the specified method asynchronously. In the following example, an activity is configured to call the method of the class and return a list of customers. [!code-csharp[CFX_WCFDataServicesActivityExample#3](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_WCFDataServicesActivityExample/cs/Program.cs#3)] - can call both static and instance methods of a class. Since is an instance method of the class, a new instance of the class is specified for the . `DownloadString` is specified as the , the URI that contains the query is specified in the collection, and the return value is assigned to the value. The value is set to `true`, which means that the method invocation will run asynchronously with regard to the workflow. In the following example, a workflow is constructed that uses the activity to query the sample Northwind data service for a list of orders for a specific customer, and then the returned data is written to the console. + can call both static and instance methods of a class. Since is an instance method of the class, a new instance of the class is specified for the . `DownloadString` is specified as the , the URI that contains the query is specified in the collection, and the return value is assigned to the value. The value is set to `true`, which means that the method invocation will run asynchronously with regard to the workflow. In the following example, a workflow is constructed that uses the activity to query the sample Northwind data service for a list of orders for a specific customer, and then the returned data is written to the console. [!code-csharp[CFX_WCFDataServicesActivityExample#1](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_WCFDataServicesActivityExample/cs/Program.cs#1)] diff --git a/docs/framework/windows-workflow-foundation/contract-first-workflow-service-development.md b/docs/framework/windows-workflow-foundation/contract-first-workflow-service-development.md index d2ddcfbc26179..3070702dca161 100644 --- a/docs/framework/windows-workflow-foundation/contract-first-workflow-service-development.md +++ b/docs/framework/windows-workflow-foundation/contract-first-workflow-service-development.md @@ -120,12 +120,12 @@ Insert subsection body here. Two public static methods are added to the and activities to support the generation of pre-configured message activities when using contract-first workflow services. -- +- -- +- -The activity generated by these methods should pass contract validation, and therefore these methods are used internally as part of the validation logic for and . The , , , , , and are all pre-configured to match the imported contract. In the content properties page for the activities in the workflow designer, the **Message** or **Parameters** sections are also pre-configured to match the contract. +The activity generated by these methods should pass contract validation, and therefore these methods are used internally as part of the validation logic for and . The , , , , , and are all pre-configured to match the imported contract. In the content properties page for the activities in the workflow designer, the **Message** or **Parameters** sections are also pre-configured to match the contract. -WCF fault contracts are also handled by returning a separate set of configured activities for each of the faults that show up in the . +WCF fault contracts are also handled by returning a separate set of configured activities for each of the faults that show up in the . For other parts of that are unsupported by WF services today (e.g. WebGet/WebInvoke behaviors, or custom operation behaviors), the API will ignore those values as part of the generation and configuration. No exceptions will be thrown. diff --git a/docs/framework/windows-workflow-foundation/control-flow-activities-in-wf.md b/docs/framework/windows-workflow-foundation/control-flow-activities-in-wf.md index 76aa7971f9849..c92d43dd2694a 100644 --- a/docs/framework/windows-workflow-foundation/control-flow-activities-in-wf.md +++ b/docs/framework/windows-workflow-foundation/control-flow-activities-in-wf.md @@ -6,21 +6,21 @@ ms.topic: "reference" --- # Control Flow Activities in WF -The [!INCLUDE[netfx_current_long](../../../includes/netfx-current-long-md.md)] provides several activities for controlling flow of execution within a workflow. Some of these activities (such as `Switch` and `If`) implement flow control structures similar to those in programming environments such as Visual C#, while others (such as `Pick`) model new programming structures. - - Note that while activities such as the `Parallel` and `ParallelForEach` activities schedule multiple child activities for execution simultaneously, only a single thread is used for a workflow. Each child activity of these activities executes sequentially and successive activities do not execute until previous activities either complete or go idle. As a result, these activities are most useful for applications in which several potentially blocking activities must execute in an interleaved fashion. If none of the child activities of these activities go idle, a `Parallel` activity executes just like a `Sequence` activity, and a `ParallelForEach` activity executes just like a `ForEach` activity. If, however, asynchronous activities (such as activities that derive from ) or messaging activities are used, control will pass to the next branch while the child activity waits for its message to be received or its asynchronous work to be completed. - -## Flow control activities - -|Activity|Description| -|--------------|-----------------| -||Executes the contained activities once and continues to do so while a condition is `true`.| -||Executes an embedded statement in sequence for each element in a collection. is similar to the keyword `foreach`, but is implemented as an activity rather than a language statement.| -||Executes contained activities if a condition is `true`, and can execute activities contained in the property if the condition is `false`.| -||Executes contained activities in parallel.| -||Executes an embedded statement in parallel for each element in a collection.| -||Provides event-based control flow modeling.| -||Represents a potential path of execution in a activity.| -||Executes contained activities in sequence.| -||Selects one choice from a number of activities to execute, based on the value of a given expression.| +The [!INCLUDE[netfx_current_long](../../../includes/netfx-current-long-md.md)] provides several activities for controlling flow of execution within a workflow. Some of these activities (such as `Switch` and `If`) implement flow control structures similar to those in programming environments such as Visual C#, while others (such as `Pick`) model new programming structures. + + Note that while activities such as the `Parallel` and `ParallelForEach` activities schedule multiple child activities for execution simultaneously, only a single thread is used for a workflow. Each child activity of these activities executes sequentially and successive activities do not execute until previous activities either complete or go idle. As a result, these activities are most useful for applications in which several potentially blocking activities must execute in an interleaved fashion. If none of the child activities of these activities go idle, a `Parallel` activity executes just like a `Sequence` activity, and a `ParallelForEach` activity executes just like a `ForEach` activity. If, however, asynchronous activities (such as activities that derive from ) or messaging activities are used, control will pass to the next branch while the child activity waits for its message to be received or its asynchronous work to be completed. + +## Flow control activities + +|Activity|Description| +|--------------|-----------------| +||Executes the contained activities once and continues to do so while a condition is `true`.| +||Executes an embedded statement in sequence for each element in a collection. is similar to the keyword `foreach`, but is implemented as an activity rather than a language statement.| +||Executes contained activities if a condition is `true`, and can execute activities contained in the property if the condition is `false`.| +||Executes contained activities in parallel.| +||Executes an embedded statement in parallel for each element in a collection.| +||Provides event-based control flow modeling.| +||Represents a potential path of execution in a activity.| +||Executes contained activities in sequence.| +||Selects one choice from a number of activities to execute, based on the value of a given expression.| ||Executes contained activities while a condition is `true`.| diff --git a/docs/framework/windows-workflow-foundation/creating-an-activity-at-runtime-with-dynamicactivity.md b/docs/framework/windows-workflow-foundation/creating-an-activity-at-runtime-with-dynamicactivity.md index e779f2192a7c3..40fedd428fe0e 100644 --- a/docs/framework/windows-workflow-foundation/creating-an-activity-at-runtime-with-dynamicactivity.md +++ b/docs/framework/windows-workflow-foundation/creating-an-activity-at-runtime-with-dynamicactivity.md @@ -14,7 +14,7 @@ ms.assetid: 1af85cc6-912d-449e-90c5-c5db3eca5ace Top-level properties can be set using workflow objects. In imperative code, these arguments are created using CLR properties on a new type. In XAML, they are declared using `x:Class` and `x:Member` tags. - Activities constructed using interface with the designer using . Activities created in the designer can be loaded dynamically using , as demonstrated in the following procedure. + Activities constructed using interface with the designer using . Activities created in the designer can be loaded dynamically using , as demonstrated in the following procedure. #### To create an activity at runtime using imperative code @@ -30,7 +30,7 @@ ms.assetid: 1af85cc6-912d-449e-90c5-c5db3eca5ace using System.Collections.Generic; ``` -5. Replace the contents of the `Main` method with the following code, which creates a activity that contains a single activity and assigns it to the property of a new dynamic activity. +5. Replace the contents of the `Main` method with the following code, which creates a activity that contains a single activity and assigns it to the property of a new dynamic activity. ```csharp //Define the input argument for the activity diff --git a/docs/framework/windows-workflow-foundation/creating-asynchronous-activities-in-wf.md b/docs/framework/windows-workflow-foundation/creating-asynchronous-activities-in-wf.md index 0b9575428cc93..8280fd4e307c3 100644 --- a/docs/framework/windows-workflow-foundation/creating-asynchronous-activities-in-wf.md +++ b/docs/framework/windows-workflow-foundation/creating-asynchronous-activities-in-wf.md @@ -6,49 +6,49 @@ ms.topic: "how-to" --- # Creating Asynchronous Activities in WF - provides activity authors a base class to use that enables derived activities to implement asynchronous execution logic. This is useful for custom activities that must perform asynchronous work without holding the workflow scheduler thread and blocking any activities that may be able to run in parallel. This topic provides an overview of how to create custom asynchronous activities using . - -## Using AsyncCodeActivity - - provides custom activity authors with different base classes for different activity authoring requirements. Each one carries a particular semantic and provides a workflow author (and the activity runtime) a corresponding contract. An based activity is an activity that performs work asynchronously relative to the scheduler thread and whose execution logic is expressed in managed code. As a result of going asynchronous, an may induce an idle point during execution. Due to the volatile nature of asynchronous work, an always creates a no persist block for the duration of the activity's execution. This prevents the workflow runtime from persisting the workflow instance in the middle of the asynchronous work, and also prevents the workflow instance from unloading while the asynchronous code is executing. - -### AsyncCodeActivity Methods - - Activities that derive from can create asynchronous execution logic by overriding the and methods with custom code. When called by the runtime, these methods are passed an . allows the activity author to provide shared state across / in the context's property. In the following example, a `GenerateRandom` activity generates a random number asynchronously. - - [!code-csharp[CFX_ActivityExample#8](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#8)] - - The previous example activity derives from , and has an elevated `OutArgument` named `Result`. The value returned by the `GetRandom` method is extracted and returned by the override, and this value is set as the `Result` value. Asynchronous activities that do not return a result should derive from . In the following example, a `DisplayRandom` activity is defined which derives from . This activity is like the `GetRandom` activity but instead of returning a result it displays a message to the console. - - [!code-csharp[CFX_ActivityExample#11](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#11)] - - Note that because there is no return value, `DisplayRandom` uses an instead of a to invoke its delegate, and the delegate returns no value. - - also provides a override. While and are required overrides, is optional, and can be overridden so the activity can clean up its outstanding asynchronous state when it is being canceled or aborted. If clean up is possible and `AsyncCodeActivity.ExecutingActivityInstance.IsCancellationRequested` is `true`, the activity should call . Any exceptions thrown from this method are fatal to the workflow instance. - - [!code-csharp[CFX_ActivityExample#10](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#10)] - -### Invoking Asynchronous Methods on a Class - - Many of the classes in the .NET Framework provide asynchronous functionality, and this functionality can be asynchronously invoked by using an based activity. In the following example, an activity is created that asynchronously creates a file by using the class. - - [!code-csharp[CFX_ActivityExample#12](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#12)] - -### Sharing State Between the BeginExecute and EndExecute Methods - - In the previous example, the object that was created in was accessed in the . This is possible because the `file` variable was passed in the property in . This is the correct method for sharing state between and . It is incorrect to use a member variable in the derived class (`FileWriter` in this case) to share state between and because the activity object may be referenced by multiple activity instances. Attempting to use a member variable to share state can result in values from one overwriting or consuming values from another . - -### Accessing Argument Values - - The environment of an consists of the arguments defined on the activity. These arguments can be accessed from the / overrides using the parameter. The arguments cannot be accessed in the delegate, but the argument values or any other desired data can be passed in to the delegate using its parameters. In the following example, a random number-generating activity is defined that obtains the inclusive upper bound from its `Max` argument. The value of the argument is passed in to the asynchronous code when the delegate is invoked. - - [!code-csharp[CFX_ActivityExample#9](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#9)] - -### Scheduling Actions or Child Activities Using AsyncCodeActivity - - derived custom activities provide a method for performing work asynchronously with regard to the workflow thread, but do not provide the ability to schedule child activities or actions. However, asynchronous behavior can be incorporated with scheduling of child activities through composition. An asynchronous activity can be created, and then composed with an or derived activity to provide asynchronous behavior and scheduling of child activities or actions. For example, an activity could be created that derives from , and has as its implementation a containing the asynchronous activity as well the other activities that implement the logic of the activity. For more examples of composing activities using and , see [How to: Create an Activity](how-to-create-an-activity.md) and [Activity Authoring Options](activity-authoring-options-in-wf.md). - + provides activity authors a base class to use that enables derived activities to implement asynchronous execution logic. This is useful for custom activities that must perform asynchronous work without holding the workflow scheduler thread and blocking any activities that may be able to run in parallel. This topic provides an overview of how to create custom asynchronous activities using . + +## Using AsyncCodeActivity + + provides custom activity authors with different base classes for different activity authoring requirements. Each one carries a particular semantic and provides a workflow author (and the activity runtime) a corresponding contract. An based activity is an activity that performs work asynchronously relative to the scheduler thread and whose execution logic is expressed in managed code. As a result of going asynchronous, an may induce an idle point during execution. Due to the volatile nature of asynchronous work, an always creates a no persist block for the duration of the activity's execution. This prevents the workflow runtime from persisting the workflow instance in the middle of the asynchronous work, and also prevents the workflow instance from unloading while the asynchronous code is executing. + +### AsyncCodeActivity Methods + + Activities that derive from can create asynchronous execution logic by overriding the and methods with custom code. When called by the runtime, these methods are passed an . allows the activity author to provide shared state across / in the context's property. In the following example, a `GenerateRandom` activity generates a random number asynchronously. + + [!code-csharp[CFX_ActivityExample#8](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#8)] + + The previous example activity derives from , and has an elevated `OutArgument` named `Result`. The value returned by the `GetRandom` method is extracted and returned by the override, and this value is set as the `Result` value. Asynchronous activities that do not return a result should derive from . In the following example, a `DisplayRandom` activity is defined which derives from . This activity is like the `GetRandom` activity but instead of returning a result it displays a message to the console. + + [!code-csharp[CFX_ActivityExample#11](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#11)] + + Note that because there is no return value, `DisplayRandom` uses an instead of a to invoke its delegate, and the delegate returns no value. + + also provides a override. While and are required overrides, is optional, and can be overridden so the activity can clean up its outstanding asynchronous state when it is being canceled or aborted. If clean up is possible and `AsyncCodeActivity.ExecutingActivityInstance.IsCancellationRequested` is `true`, the activity should call . Any exceptions thrown from this method are fatal to the workflow instance. + + [!code-csharp[CFX_ActivityExample#10](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#10)] + +### Invoking Asynchronous Methods on a Class + + Many of the classes in the .NET Framework provide asynchronous functionality, and this functionality can be asynchronously invoked by using an based activity. In the following example, an activity is created that asynchronously creates a file by using the class. + + [!code-csharp[CFX_ActivityExample#12](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#12)] + +### Sharing State Between the BeginExecute and EndExecute Methods + + In the previous example, the object that was created in was accessed in the . This is possible because the `file` variable was passed in the property in . This is the correct method for sharing state between and . It is incorrect to use a member variable in the derived class (`FileWriter` in this case) to share state between and because the activity object may be referenced by multiple activity instances. Attempting to use a member variable to share state can result in values from one overwriting or consuming values from another . + +### Accessing Argument Values + + The environment of an consists of the arguments defined on the activity. These arguments can be accessed from the / overrides using the parameter. The arguments cannot be accessed in the delegate, but the argument values or any other desired data can be passed in to the delegate using its parameters. In the following example, a random number-generating activity is defined that obtains the inclusive upper bound from its `Max` argument. The value of the argument is passed in to the asynchronous code when the delegate is invoked. + + [!code-csharp[CFX_ActivityExample#9](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#9)] + +### Scheduling Actions or Child Activities Using AsyncCodeActivity + + derived custom activities provide a method for performing work asynchronously with regard to the workflow thread, but do not provide the ability to schedule child activities or actions. However, asynchronous behavior can be incorporated with scheduling of child activities through composition. An asynchronous activity can be created, and then composed with an or derived activity to provide asynchronous behavior and scheduling of child activities or actions. For example, an activity could be created that derives from , and has as its implementation a containing the asynchronous activity as well the other activities that implement the logic of the activity. For more examples of composing activities using and , see [How to: Create an Activity](how-to-create-an-activity.md) and [Activity Authoring Options](activity-authoring-options-in-wf.md). + ## See also - -- +- diff --git a/docs/framework/windows-workflow-foundation/creating-custom-flow-control-activities.md b/docs/framework/windows-workflow-foundation/creating-custom-flow-control-activities.md index 85569cafddc96..3d455fbbf9735 100644 --- a/docs/framework/windows-workflow-foundation/creating-custom-flow-control-activities.md +++ b/docs/framework/windows-workflow-foundation/creating-custom-flow-control-activities.md @@ -6,28 +6,28 @@ ms.assetid: 27f409f6-2d1d-4cfb-9765-93eb2ad667d5 --- # Creating custom flow control activities -The .NET Framework contains a variety of flow-control activities that function similarly to abstract programming structures (such as ) or to standard programming statements (such as ). This topic discusses the architecture of one of the sample projects, [Non-Generic ForEach](./samples/non-generic-foreach.md). - -## Creating the custom class - - Since the Non-Generic ForEach class will need to schedule child activities, it will need to derive from , since activities that derive from do not have this functionality. - -```csharp -public sealed class ForEach : NativeActivity +The .NET Framework contains a variety of flow-control activities that function similarly to abstract programming structures (such as ) or to standard programming statements (such as ). This topic discusses the architecture of one of the sample projects, [Non-Generic ForEach](./samples/non-generic-foreach.md). + +## Creating the custom class + + Since the Non-Generic ForEach class will need to schedule child activities, it will need to derive from , since activities that derive from do not have this functionality. + +```csharp +public sealed class ForEach : NativeActivity { } -``` - - The custom class requires several members to store data being used by the activity, and to provide functionality to execute the activity’s child activities. These members include: - -- `valueEnumerator`: The non-public of type used to iterate over the collection of items. This member is of type because it is used internally in the activity, rather than an argument or public property, which would be used if this object were to have an origin outside the activity. - -- `OnChildComplete`: The public property that executes when each child completes execution. This member is defined as a CLR property, since its value will not change for different instances of the activity. - -- `Values`: The collection of inputs used for the iterations of the child activity. This member is of type , since the origin of the data is outside the activity, but the contents of the collection is not expected to change during the execution of the activity. If the activity needed the functionality to change the contents of this collection while the activity was executing (to add or remove activities, for instance), this member would have been defined as an , which then would have been evaluated every time it was accessed, so that changes would be available to the activity. - -- `Body`: This member defines the activity to be executed for each item in the `Values` collection. This member is defined as an so that it is evaluated every time it is accessed. - -- `Execute`: This method uses the `InternalExecute`, `OnForEachComplete`, and `GetStateAndExecute` non-public members to schedule the execution and assign the completion handler of the child activity defined in the Body member. - +``` + + The custom class requires several members to store data being used by the activity, and to provide functionality to execute the activity’s child activities. These members include: + +- `valueEnumerator`: The non-public of type used to iterate over the collection of items. This member is of type because it is used internally in the activity, rather than an argument or public property, which would be used if this object were to have an origin outside the activity. + +- `OnChildComplete`: The public property that executes when each child completes execution. This member is defined as a CLR property, since its value will not change for different instances of the activity. + +- `Values`: The collection of inputs used for the iterations of the child activity. This member is of type , since the origin of the data is outside the activity, but the contents of the collection is not expected to change during the execution of the activity. If the activity needed the functionality to change the contents of this collection while the activity was executing (to add or remove activities, for instance), this member would have been defined as an , which then would have been evaluated every time it was accessed, so that changes would be available to the activity. + +- `Body`: This member defines the activity to be executed for each item in the `Values` collection. This member is defined as an so that it is evaluated every time it is accessed. + +- `Execute`: This method uses the `InternalExecute`, `OnForEachComplete`, and `GetStateAndExecute` non-public members to schedule the execution and assign the completion handler of the child activity defined in the Body member. + - `CacheMetadata`: This member provides the runtime with the information it needs to execute the activity. By default, an activity’s `CacheMetadata` method will inform the runtime of all public members of the activity, but since this activity uses private members for some functionality, it needs to inform the runtime of their existence so that the runtime can be aware of them. In this case, the `CacheMetadata` function is overridden so that the private `valueEnumerator` member can be accessed. This member also creates an argument for the values for the activity so that they can be passed in to the activity during execution. diff --git a/docs/framework/windows-workflow-foundation/csharp-expressions.md b/docs/framework/windows-workflow-foundation/csharp-expressions.md index 25e2a2cd03ecd..548178a8c2cfa 100644 --- a/docs/framework/windows-workflow-foundation/csharp-expressions.md +++ b/docs/framework/windows-workflow-foundation/csharp-expressions.md @@ -39,7 +39,7 @@ Visual Basic expressions in existing .NET Framework 4 C# workflow projects that ### Using C# expressions in code workflows -C# expressions are supported in .NET Framework 4.6.1 code based workflows, but before the workflow can be invoked the C# expressions must be compiled using . Workflow authors can use `CSharpValue` to represent the r-value of an expression, and `CSharpReference` to represent the l-value of an expression. In the following example, a workflow is created with an `Assign` activity and a `WriteLine` activity contained in a `Sequence` activity. A `CSharpReference` is specified for the `To` argument of the `Assign`, and represents the l-value of the expression. A `CSharpValue` is specified for the `Value` argument of the `Assign`, and for the `Text` argument of the `WriteLine`, and represents the r-value for those two expressions. +C# expressions are supported in .NET Framework 4.6.1 code based workflows, but before the workflow can be invoked the C# expressions must be compiled using . Workflow authors can use `CSharpValue` to represent the r-value of an expression, and `CSharpReference` to represent the l-value of an expression. In the following example, a workflow is created with an `Assign` activity and a `WriteLine` activity contained in a `Sequence` activity. A `CSharpReference` is specified for the `To` argument of the `Assign`, and represents the l-value of the expression. A `CSharpValue` is specified for the `Value` argument of the `Assign`, and for the `Text` argument of the `WriteLine`, and represents the r-value for those two expressions. ```csharp Variable n = new Variable @@ -199,7 +199,7 @@ C# expressions are supported in compiled XAML workflows that are compiled to a t #### Loose Xaml -C# expressions are supported in loose XAML workflows. The workflow host program that loads and invokes the loose XAML workflow must target .NET Framework 4.6.1, and must be set to `true` (the default is `false`). To set to `true`, create an instance with its property set to `true`, and pass it as a parameter to . If `CompileExpressions` Is not set to `true`, a will be thrown with a message similar to the following: `Expression Activity type 'CSharpValue`1' requires compilation in order to run. Please ensure that the workflow has been compiled.` +C# expressions are supported in loose XAML workflows. The workflow host program that loads and invokes the loose XAML workflow must target .NET Framework 4.6.1, and must be set to `true` (the default is `false`). To set to `true`, create an instance with its property set to `true`, and pass it as a parameter to . If `CompileExpressions` Is not set to `true`, a will be thrown with a message similar to the following: `Expression Activity type 'CSharpValue`1' requires compilation in order to run. Please ensure that the workflow has been compiled.` ```csharp ActivityXamlServicesSettings settings = new ActivityXamlServicesSettings diff --git a/docs/framework/windows-workflow-foundation/custom-tracking-records.md b/docs/framework/windows-workflow-foundation/custom-tracking-records.md index c70f602a8d1c7..59ab7f8790a6e 100644 --- a/docs/framework/windows-workflow-foundation/custom-tracking-records.md +++ b/docs/framework/windows-workflow-foundation/custom-tracking-records.md @@ -23,7 +23,7 @@ protected override void Execute(CodeActivityContext context) } ``` -A is emitted in a code activity by invoking the method on the `ActivityContext`. +A is emitted in a code activity by invoking the method on the `ActivityContext`. ## See also diff --git a/docs/framework/windows-workflow-foundation/declarative-constraints.md b/docs/framework/windows-workflow-foundation/declarative-constraints.md index 1044f9312ac9e..9649771953cf7 100644 --- a/docs/framework/windows-workflow-foundation/declarative-constraints.md +++ b/docs/framework/windows-workflow-foundation/declarative-constraints.md @@ -6,173 +6,173 @@ ms.assetid: 67001ed1-7f4d-4ada-ae57-a31176901a53 --- # Declarative Constraints -Declarative constraints provide a powerful method of validation for an activity and its relationships with other activities. Constraints are configured for an activity during the authoring process, but additional constraints can also be specified by the workflow host. This topic provides an overview of using declarative constraints to provide activity validation. - -## Using Declarative Constraints - - A constraint is an activity that contains validation logic. This constraint activity can be authored in code or in XAML. After a constraint activity is created, activity authors add this constraint to the property of the activity to validate, or they use the constraint to provide additional validation by using the property of a instance. The validation logic can consist of simple validations such as validating an activity’s metadata, but it can also perform validation that takes into account the relationship of the current activity to its parent, children, and sibling activities. Constraints are authored by using the activity, and several additional validation activities are provided to assist with the creation of validation errors and warnings and to provide information about related activities in the workflow. - -### AssertValidation and AddValidationError - - The activity evaluates the expression referenced by its property, and if the expression evaluates to `false`, a validation error or warning is added to the . The property describes the validation error and the property indicates whether the validation failure is an error or a warning. The default value for is `false`. - - In the following example, a constraint is declared that returns a validation warning if the of the activity being validated is two characters or less in length. The generic type parameter used for specifies the type of activity that is validated by the constraint. This constraint uses as the generic type and can be used to validate all types of activities. - -```csharp -public static Constraint ActivityDisplayNameIsNotSetWarning() -{ - DelegateInArgument element = new DelegateInArgument(); - - return new Constraint - { - Body = new ActivityAction - { - Argument1 = element, - Handler = new AssertValidation - { - IsWarning = true, - Assertion = new InArgument(env => (element.Get(env).DisplayName.Length > 2)), - Message = new InArgument("It is a best practice to have a DisplayName of more than 2 characters."), - } - } - }; -} -``` - - To specify this constraint for an activity, it is added to the of the activity, as shown in the following example code. - -```csharp -public sealed class SampleActivity : CodeActivity -{ - public SampleActivity() - { - base.Constraints.Add(ActivityDisplayNameIsNotSetWarning()); - } - - // Activity implementation omitted. -} -``` - - The host could also specify this constraint for activities in a workflow by using , which is covered in the next section. - +Declarative constraints provide a powerful method of validation for an activity and its relationships with other activities. Constraints are configured for an activity during the authoring process, but additional constraints can also be specified by the workflow host. This topic provides an overview of using declarative constraints to provide activity validation. + +## Using Declarative Constraints + + A constraint is an activity that contains validation logic. This constraint activity can be authored in code or in XAML. After a constraint activity is created, activity authors add this constraint to the property of the activity to validate, or they use the constraint to provide additional validation by using the property of a instance. The validation logic can consist of simple validations such as validating an activity’s metadata, but it can also perform validation that takes into account the relationship of the current activity to its parent, children, and sibling activities. Constraints are authored by using the activity, and several additional validation activities are provided to assist with the creation of validation errors and warnings and to provide information about related activities in the workflow. + +### AssertValidation and AddValidationError + + The activity evaluates the expression referenced by its property, and if the expression evaluates to `false`, a validation error or warning is added to the . The property describes the validation error and the property indicates whether the validation failure is an error or a warning. The default value for is `false`. + + In the following example, a constraint is declared that returns a validation warning if the of the activity being validated is two characters or less in length. The generic type parameter used for specifies the type of activity that is validated by the constraint. This constraint uses as the generic type and can be used to validate all types of activities. + +```csharp +public static Constraint ActivityDisplayNameIsNotSetWarning() +{ + DelegateInArgument element = new DelegateInArgument(); + + return new Constraint + { + Body = new ActivityAction + { + Argument1 = element, + Handler = new AssertValidation + { + IsWarning = true, + Assertion = new InArgument(env => (element.Get(env).DisplayName.Length > 2)), + Message = new InArgument("It is a best practice to have a DisplayName of more than 2 characters."), + } + } + }; +} +``` + + To specify this constraint for an activity, it is added to the of the activity, as shown in the following example code. + +```csharp +public sealed class SampleActivity : CodeActivity +{ + public SampleActivity() + { + base.Constraints.Add(ActivityDisplayNameIsNotSetWarning()); + } + + // Activity implementation omitted. +} +``` + + The host could also specify this constraint for activities in a workflow by using , which is covered in the next section. + The activity is used to generate a validation error or warning without requiring the evaluation of an expression. Its properties are similar to and it can be used in conjunction with flow control activities of a constraint such as the activity. - + ### Workflow Relationship Activities -Several validation activities are available that provide information about the other activities in the workflow in relation to the activity being validated. returns a collection of activities that contains all of the activities between the current activity and the root activity. provides a collection of activities that contains the child activities in a recursive pattern, and gets all the activities in the workflow. - -In the following example, a `CreateState` activity is defined. The `CreateState` activity must be contained within a `CreateCountry` activity, and the `GetParent` method returns a constraint that enforces this requirement. `GetParent` uses the activity in conjunction with a activity to inspect the parent activities of the `CreateState` activity to determine if the requirement is met. - -```csharp -public sealed class CreateState : CodeActivity -{ - public CreateState() - { - base.Constraints.Add(CheckParent()); +Several validation activities are available that provide information about the other activities in the workflow in relation to the activity being validated. returns a collection of activities that contains all of the activities between the current activity and the root activity. provides a collection of activities that contains the child activities in a recursive pattern, and gets all the activities in the workflow. + +In the following example, a `CreateState` activity is defined. The `CreateState` activity must be contained within a `CreateCountry` activity, and the `GetParent` method returns a constraint that enforces this requirement. `GetParent` uses the activity in conjunction with a activity to inspect the parent activities of the `CreateState` activity to determine if the requirement is met. + +```csharp +public sealed class CreateState : CodeActivity +{ + public CreateState() + { + base.Constraints.Add(CheckParent()); this.Cities = new List(); - } - - public List Cities { get; set; } - + } + + public List Cities { get; set; } + public string Name { get; set; } - - static Constraint CheckParent() - { - DelegateInArgument element = new DelegateInArgument(); + + static Constraint CheckParent() + { + DelegateInArgument element = new DelegateInArgument(); DelegateInArgument context = new DelegateInArgument(); - Variable result = new Variable(); - DelegateInArgument parent = new DelegateInArgument(); - - return new Constraint + Variable result = new Variable(); + DelegateInArgument parent = new DelegateInArgument(); + + return new Constraint { - Body = new ActivityAction + Body = new ActivityAction { - Argument1 = element, - Argument2 = context, - Handler = new Sequence - { - Variables = - { + Argument1 = element, + Argument2 = context, + Handler = new Sequence + { + Variables = + { result - }, - Activities = - { - new ForEach + }, + Activities = + { + new ForEach { - Values = new GetParentChain - { + Values = new GetParentChain + { ValidationContext = context - }, - Body = new ActivityAction + }, + Body = new ActivityAction { Argument = parent, - Handler = new If() + Handler = new If() { Condition = new InArgument((env) => object.Equals(parent.Get(env).GetType(),typeof(CreateCountry))), - Then = new Assign - { - Value = true, - To = result - } - } + Then = new Assign + { + Value = true, + To = result + } + } } - }, - new AssertValidation - { - Assertion = new InArgument(result), + }, + new AssertValidation + { + Assertion = new InArgument(result), Message = new InArgument ("CreateState has to be inside a CreateCountry activity"), - } - } - } - } - }; - } - - protected override void Execute(CodeActivityContext context) - { - // not needed for the sample - } -} + } + } + } + } + }; + } + + protected override void Execute(CodeActivityContext context) + { + // not needed for the sample + } +} ``` - -## Additional Constraints - - Workflow host authors can specify additional validation constraints for activities in a workflow by creating constraints and adding them to the dictionary of a instance. Each item in contains the type of activity for which the constraints apply and a list of the additional constraints for that type of activity. When validation is invoked for the workflow, each activity of the specified type, including derived classes, evaluates the constraints. In this example, the `ActivityDisplayNameIsNotSetWarning` constraint from the previous section is applied to all activities in a workflow. - -```csharp -Activity wf = new Sequence -{ - // Workflow Details Omitted. -}; - -ValidationSettings settings = new ValidationSettings() -{ - - AdditionalConstraints = - { + +## Additional Constraints + + Workflow host authors can specify additional validation constraints for activities in a workflow by creating constraints and adding them to the dictionary of a instance. Each item in contains the type of activity for which the constraints apply and a list of the additional constraints for that type of activity. When validation is invoked for the workflow, each activity of the specified type, including derived classes, evaluates the constraints. In this example, the `ActivityDisplayNameIsNotSetWarning` constraint from the previous section is applied to all activities in a workflow. + +```csharp +Activity wf = new Sequence +{ + // Workflow Details Omitted. +}; + +ValidationSettings settings = new ValidationSettings() +{ + + AdditionalConstraints = + { {typeof(Activity), new List {ActivityDisplayNameIsNotSetWarning()}}, - } -}; - -// Validate the workflow. -ValidationResults results = ActivityValidationServices.Validate(wf, settings); - -// Evaluate the results. -if (results.Errors.Count == 0 && results.Warnings.Count == 0) -{ - Console.WriteLine("No warnings or errors"); -} -else -{ - foreach (ValidationError error in results.Errors) - { - Console.WriteLine("Error in " + error.Source.DisplayName + ": " + error.Message); - } - foreach (ValidationError warning in results.Warnings) - { - Console.WriteLine("Warning in " + warning.Source.DisplayName + ": " + warning.Message); - } -} -``` - - If the property of is `true`, then only the specified additional constraints are evaluated when validation is invoked by calling . This can be useful for inspecting workflows for specific validation configurations. Note however that when the workflow is invoked, the validation logic configured in the workflow is evaluated and must pass for the workflow to successfully begin. For more information about invoking validation, see [Invoking Activity Validation](invoking-activity-validation.md). + } +}; + +// Validate the workflow. +ValidationResults results = ActivityValidationServices.Validate(wf, settings); + +// Evaluate the results. +if (results.Errors.Count == 0 && results.Warnings.Count == 0) +{ + Console.WriteLine("No warnings or errors"); +} +else +{ + foreach (ValidationError error in results.Errors) + { + Console.WriteLine("Error in " + error.Source.DisplayName + ": " + error.Message); + } + foreach (ValidationError warning in results.Warnings) + { + Console.WriteLine("Warning in " + warning.Source.DisplayName + ": " + warning.Message); + } +} +``` + + If the property of is `true`, then only the specified additional constraints are evaluated when validation is invoked by calling . This can be useful for inspecting workflows for specific validation configurations. Note however that when the workflow is invoked, the validation logic configured in the workflow is evaluated and must pass for the workflow to successfully begin. For more information about invoking validation, see [Invoking Activity Validation](invoking-activity-validation.md). diff --git a/docs/framework/windows-workflow-foundation/dynamic-update.md b/docs/framework/windows-workflow-foundation/dynamic-update.md index eab2e5304bdb3..9e7260e67ac54 100644 --- a/docs/framework/windows-workflow-foundation/dynamic-update.md +++ b/docs/framework/windows-workflow-foundation/dynamic-update.md @@ -23,9 +23,9 @@ This article provides an overview of the dynamic update process of adding a new ## Prepare the workflow definition for dynamic update -The first step in the dynamic update process is to prepare the desired workflow definition for update. This is done by calling the method and passing in the workflow definition to modify. This method validates and then walks the workflow tree to identify all of the objects such as public activities and variables that need to be tagged so they can be compared later with the modified workflow definition. When this is complete, the workflow tree is cloned and attached to the original workflow definition. When the update map is created, the updated version of the workflow definition is compared with the original workflow definition and the update map is generated based on the differences. +The first step in the dynamic update process is to prepare the desired workflow definition for update. This is done by calling the method and passing in the workflow definition to modify. This method validates and then walks the workflow tree to identify all of the objects such as public activities and variables that need to be tagged so they can be compared later with the modified workflow definition. When this is complete, the workflow tree is cloned and attached to the original workflow definition. When the update map is created, the updated version of the workflow definition is compared with the original workflow definition and the update map is generated based on the differences. -To prepare a Xaml workflow for dynamic update it may be loaded into an , and then the is passed into . +To prepare a Xaml workflow for dynamic update it may be loaded into an , and then the is passed into . > [!NOTE] > For more information about working with serialized workflows and , see [Serializing Workflows and Activities to and from XAML](serializing-workflows-and-activities-to-and-from-xaml.md). @@ -71,7 +71,7 @@ s.Activities.Insert(2, va); ## Create the update map -Once the workflow definition that was prepared for update has been modified, the update map can be created. To create a dynamic update map, the method is invoked. This returns a that contains the information the runtime needs to modify a persisted workflow instance so that it may be loaded and resumed with the new workflow definition. In the following example, a dynamic map is created for the modified `MortgageWorkflow` definition from the previous example. +Once the workflow definition that was prepared for update has been modified, the update map can be created. To create a dynamic update map, the method is invoked. This returns a that contains the information the runtime needs to modify a persisted workflow instance so that it may be loaded and resumed with the new workflow definition. In the following example, a dynamic map is created for the modified `MortgageWorkflow` definition from the previous example. ```csharp // Create the update map. @@ -89,7 +89,7 @@ using (FileStream fs = System.IO.File.Open(@"C:\WorkflowDefinitions\MortgageWork } ``` -When returns, the cloned workflow definition and other dynamic update information that was added in the call to is removed, and the modified workflow definition is ready to be saved so that it can be used later when resuming updated workflow instances. In the following example, the modified workflow definition is saved to `MortgageWorkflow_v1.1.xaml`. +When returns, the cloned workflow definition and other dynamic update information that was added in the call to is removed, and the modified workflow definition is ready to be saved so that it can be used later when resuming updated workflow instances. In the following example, the modified workflow definition is saved to `MortgageWorkflow_v1.1.xaml`. ```csharp // Save the modified workflow definition. @@ -101,7 +101,7 @@ sw.Close(); ## Apply the update map to the desired persisted workflow instances -Applying the update map can be done at any time after creating it. It can be done right away using the instance that was returned by , or it can be done later using a saved copy of the update map. To update a workflow instance, load it into a using . Next, create a using the updated workflow definition, and the desired . This may be different than the one that was used to persist the original workflow, and typically is in order to reflect that the persisted instance has been modified. Once the is created, it is loaded using the overload of that takes a , and then unloaded with a call to . This applies the dynamic update and persists the updated workflow instance. +Applying the update map can be done at any time after creating it. It can be done right away using the instance that was returned by , or it can be done later using a saved copy of the update map. To update a workflow instance, load it into a using . Next, create a using the updated workflow definition, and the desired . This may be different than the one that was used to persist the original workflow, and typically is in order to reflect that the persisted instance has been modified. Once the is created, it is loaded using the overload of that takes a , and then unloaded with a call to . This applies the dynamic update and persists the updated workflow instance. ```csharp // Load the serialized update map. diff --git a/docs/framework/windows-workflow-foundation/exceptions.md b/docs/framework/windows-workflow-foundation/exceptions.md index 4c9d35cb1e084..36ed9b6afac79 100644 --- a/docs/framework/windows-workflow-foundation/exceptions.md +++ b/docs/framework/windows-workflow-foundation/exceptions.md @@ -6,7 +6,7 @@ ms.topic: "reference" --- # Windows Workflow Foundation Exceptions -Workflows can use the activity to handle exceptions that are raised during the execution of a workflow. These exceptions can be handled or they can be re-thrown using the activity. Activities in the section are executed when either the section or the section completes. Workflows hosted by a instance can also use the event handler to handle exceptions that are not handled by a activity. +Workflows can use the activity to handle exceptions that are raised during the execution of a workflow. These exceptions can be handled or they can be re-thrown using the activity. Activities in the section are executed when either the section or the section completes. Workflows hosted by a instance can also use the event handler to handle exceptions that are not handled by a activity. ## Causes of Exceptions @@ -36,11 +36,11 @@ Workflows can use the activity to h ### Handling Exceptions with the TryCatch Activity - Handling exceptions inside a workflow is performed with the activity. The activity has a collection of activities that are each associated with a specific type. If the exception thrown by an activity that is contained in the section of a activity matches the exception of a activity in the collection, then the exception is handled. If the exception is explicitly re-thrown or a new exception is thrown then this exception passes up to the parent activity. The following code example shows a activity that handles an that is thrown in the section by a activity. The exception's message is written to the console by the activity, and then a message is written to the console in the section. + Handling exceptions inside a workflow is performed with the activity. The activity has a collection of activities that are each associated with a specific type. If the exception thrown by an activity that is contained in the section of a activity matches the exception of a activity in the collection, then the exception is handled. If the exception is explicitly re-thrown or a new exception is thrown then this exception passes up to the parent activity. The following code example shows a activity that handles an that is thrown in the section by a activity. The exception's message is written to the console by the activity, and then a message is written to the console in the section. [!code-csharp[CFX_WorkflowApplicationExample#33](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#33)] - The activities in the section are executed when either the section or the section successfully completes. The section successfully completes if no exceptions are thrown from it, and the section successfully completes if no exceptions are thrown or rethrown from it. If an exception is thrown in the section of a and is either not handled by a in the section, or is rethrown from the , the activities in the will not be executed unless the one of the following occurs. + The activities in the section are executed when either the section or the section successfully completes. The section successfully completes if no exceptions are thrown from it, and the section successfully completes if no exceptions are thrown or rethrown from it. If an exception is thrown in the section of a and is either not handled by a in the section, or is rethrown from the , the activities in the will not be executed unless the one of the following occurs. - The exception is caught by a higher level activity in the workflow, regardless of whether it is rethrown from that higher level . diff --git a/docs/framework/windows-workflow-foundation/exposing-data-with-cachemetadata.md b/docs/framework/windows-workflow-foundation/exposing-data-with-cachemetadata.md index 2b5cc072ed064..be8efabb7a289 100644 --- a/docs/framework/windows-workflow-foundation/exposing-data-with-cachemetadata.md +++ b/docs/framework/windows-workflow-foundation/exposing-data-with-cachemetadata.md @@ -7,17 +7,17 @@ ms.assetid: 34832f23-e93b-40e6-a80b-606a855a00d9 # Exposing data with CacheMetadata -Before executing an activity, the workflow runtime obtains all of the information about the activity that it needs in order to maintain its execution. The workflow runtime gets this information during the execution of the method. The default implementation of this method provides the runtime with all of the public arguments, variables, and child activities exposed by the activity at the time it is executed; if the activity needs to give more information to the runtime than this (such as private members, or activities to be scheduled by the activity), this method can be overridden to provide it. +Before executing an activity, the workflow runtime obtains all of the information about the activity that it needs in order to maintain its execution. The workflow runtime gets this information during the execution of the method. The default implementation of this method provides the runtime with all of the public arguments, variables, and child activities exposed by the activity at the time it is executed; if the activity needs to give more information to the runtime than this (such as private members, or activities to be scheduled by the activity), this method can be overridden to provide it. ## Default CacheMetadata behavior -The default implementation of for activities that derive from processes the following method types in the following ways: +The default implementation of for activities that derive from processes the following method types in the following ways: -- , , or (generic arguments): These arguments are exposed to the runtime as arguments with a name and type equal to the exposed property name and type, the appropriate argument direction, and some validation data. +- , , or (generic arguments): These arguments are exposed to the runtime as arguments with a name and type equal to the exposed property name and type, the appropriate argument direction, and some validation data. - or any subclass thereof: These members are exposed to the runtime as public variables. -- or any subclass thereof: These members are exposed to the runtime as public child activities. The default behavior can be implemented explicitly by calling , passing in the child activity. +- or any subclass thereof: These members are exposed to the runtime as public child activities. The default behavior can be implemented explicitly by calling , passing in the child activity. - or any subclass thereof: These members are exposed to the runtime as public delegates. @@ -27,7 +27,7 @@ The default implementation of of type : All elements in the collection are exposed to the runtime as public delegates. -The for activities that derive from , , and also function as above, except for the following differences: +The for activities that derive from , , and also function as above, except for the following differences: - Classes that derive from cannot schedule child activities or delegates, so such members are exposed as imported children and delegates; the @@ -35,7 +35,7 @@ The for activities that deriv ## Overriding CacheMetadata to provide information to the runtime -The following code snippet demonstrates how to add information about members to an activity’s metadata during the execution of the method. Note that the base of the method is called to cache all public data about the activity. +The following code snippet demonstrates how to add information about members to an activity’s metadata during the execution of the method. Note that the base of the method is called to cache all public data about the activity. ```csharp protected override void CacheMetadata(NativeActivityMetadata metadata) @@ -53,9 +53,9 @@ protected override void CacheMetadata(NativeActivityMetadata metadata) ## Using CacheMetadata to expose implementation children -In order to pass data to child activities that are to be scheduled by an activity using variables, it is necessary to add the variables as implementation variables; public variables cannot have their values set this way. The reason for this is that activities are intended to be executed more as implementations of functions (which have parameters), rather than encapsulated classes (which have properties). However, there are situations in which the arguments must be explicitly set, such as when using , since the scheduled activity doesn't have access to the parent activity's arguments in the way a child activity would. +In order to pass data to child activities that are to be scheduled by an activity using variables, it is necessary to add the variables as implementation variables; public variables cannot have their values set this way. The reason for this is that activities are intended to be executed more as implementations of functions (which have parameters), rather than encapsulated classes (which have properties). However, there are situations in which the arguments must be explicitly set, such as when using , since the scheduled activity doesn't have access to the parent activity's arguments in the way a child activity would. -The following code snippet demonstrates how to pass an argument from a native activity into a scheduled activity using . +The following code snippet demonstrates how to pass an argument from a native activity into a scheduled activity using . ```csharp public sealed class ChildActivity : NativeActivity diff --git a/docs/framework/windows-workflow-foundation/expressions.md b/docs/framework/windows-workflow-foundation/expressions.md index ec57698d495a0..ecc0734c53f1f 100644 --- a/docs/framework/windows-workflow-foundation/expressions.md +++ b/docs/framework/windows-workflow-foundation/expressions.md @@ -6,11 +6,11 @@ ms.assetid: c42341a9-43a1-462c-bffb-c5de004aa428 --- # Expressions (WF) -A Windows Workflow Foundation (WF) expression is any activity that returns a result. All expression activities derive indirectly from , which contains an property named as the activity’s return value. WF ships with a wide range of expression activities from simple ones like and , which provide access to single workflow variable through operator activities, to complex activities such as and that offer access to the full breadth of Visual Basic language to produce the result. Additional expression activities can be created by deriving from or . +A Windows Workflow Foundation (WF) expression is any activity that returns a result. All expression activities derive indirectly from , which contains an property named as the activity’s return value. WF ships with a wide range of expression activities from simple ones like and , which provide access to single workflow variable through operator activities, to complex activities such as and that offer access to the full breadth of Visual Basic language to produce the result. Additional expression activities can be created by deriving from or . ## Using Expressions - Workflow designer uses and for all expressions in Visual Basic projects, and and for expressions in C# workflow projects. + Workflow designer uses and for all expressions in Visual Basic projects, and and for expressions in C# workflow projects. > [!NOTE] > Support for C# expressions in workflow projects was introduced in .NET Framework 4.5. For more information, see [C# Expressions](csharp-expressions.md). diff --git a/docs/framework/windows-workflow-foundation/feature-specifics.md b/docs/framework/windows-workflow-foundation/feature-specifics.md index d28fadccfb207..d162d89972b7e 100644 --- a/docs/framework/windows-workflow-foundation/feature-specifics.md +++ b/docs/framework/windows-workflow-foundation/feature-specifics.md @@ -63,7 +63,7 @@ A correlation is one of two things: - An example of correlation used to group messages together is a Request-Reply correlation that groups messages together. - - On a activity, click on the property and add a using the CorrelationHandle created in the first step above. + - On a activity, click on the property and add a using the CorrelationHandle created in the first step above. - Create a activity by right-clicking on the and clicking "Create SendReply". Paste it into your workflow after the activity. @@ -87,13 +87,13 @@ The WCF configuration schema is complex and provides users with many hard to fin - Standard endpoints define reusable preconfigured endpoints, which have fixed values for one or more of the endpoint properties (address, binding and contract), and allow defining custom properties. -- Finally, the allows you to do central management of WCF client configuration, useful in scenarios in which configuration is selected or changed after the application domain load time. +- Finally, the allows you to do central management of WCF client configuration, useful in scenarios in which configuration is selected or changed after the application domain load time. ### Getting Started - [A Developer's Guide to WCF 4.0](/previous-versions/dotnet/articles/ee354381(v=msdn.10)) -- [Configuration Channel Factory](xref:System.ServiceModel.Configuration.ConfigurationChannelFactory%601) +- [Configuration Channel Factory](xref:System.ServiceModel.Configuration.ConfigurationChannelFactory`1) - [Standard Endpoint Element](xref:System.ServiceModel.Configuration.StandardEndpointElement) @@ -155,7 +155,7 @@ Flowchart is a well-known paradigm to visually represent domain problems. It is - - - + - - Samples: @@ -175,11 +175,11 @@ A flowchart activity can be used to implement a guessing game. The guessing game - -- +- - -- +- - @@ -207,7 +207,7 @@ Procedural activities provide a mechanism to model sequential control flow using - : An intranet document management system has a document approval workflow. Documents need to be approved by people in several departments before they can be published to the intranet. There isn't an established order for the approvals; they can occur at any time while the document is in the "approval pending" phase. When a user submits a document for review, it must be approved by their direct manager, the intranet administrator, and the internal communications manager. -- : A WF application manages corporate buys within a large company. The corporate rules dictate that before planning any purchase operation, the valuations of three different vendors is required. An employee from the buying department selects three vendors from the company's vendor list. After these vendors have been selected and notified, the company will wait for their economic proposals. The proposals can come in any order. To implement this scenario in WF, we use a that will iterate through our collection of vendors and ask for their economic proposals. After all offers are gathered, the best one is selected and displayed. +- : A WF application manages corporate buys within a large company. The corporate rules dictate that before planning any purchase operation, the valuations of three different vendors is required. An employee from the buying department selects three vendors from the company's vendor list. After these vendors have been selected and notified, the company will wait for their economic proposals. The proposals can come in any order. To implement this scenario in WF, we use a that will iterate through our collection of vendors and ask for their economic proposals. After all offers are gathered, the best one is selected and displayed. ## InvokeMethod @@ -243,7 +243,7 @@ A set of activities needs to be executed, and specific logic needs to be execute ## Pick activity -The Activity provides event-based control flow modeling in WF. contains many branches where each branch waits for a particular event to occur before running. In this setup, a behaves similar to a to which the Activity will execute only one of the set of events it is listening. Each branch is event driven and the event that occurs runs the corresponding branch first. All other branches cancel and stop listening for events. +The Activity provides event-based control flow modeling in WF. contains many branches where each branch waits for a particular event to occur before running. In this setup, a behaves similar to a to which the Activity will execute only one of the set of events it is listening. Each branch is event driven and the event that occurs runs the corresponding branch first. All other branches cancel and stop listening for events. ### Getting Started @@ -255,7 +255,7 @@ The Activity provides event-based contr ### Pick Scenario -A user needs to be prompted for input. Under normal circumstances, the developer would use a method call like to prompt for a user's input. The problem with this setup is that the program waits until the user enters something. In this scenario, a time-out is needed to unblock a blocking activity. A common scenario is one that requires a task to be completed within a given time duration. Timing out a blocking activity is a scenario where Pick adds a lot of value. +A user needs to be prompted for input. Under normal circumstances, the developer would use a method call like to prompt for a user's input. The problem with this setup is that the program waits until the user enters something. In this scenario, a time-out is needed to unblock a blocking activity. A common scenario is one that requires a task to be completed within a given time duration. Timing out a blocking activity is a scenario where Pick adds a lot of value. ## WCF Routing Service @@ -275,7 +275,7 @@ The routing service in .NET 4 is designed to make these problems easier to solve 3. Error handling (the router catches communication exceptions and fails over to backup endpoints) -4. Dynamic (in memory) update of and Routing Configuration. +4. Dynamic (in memory) update of and Routing Configuration. ### Getting Started diff --git a/docs/framework/windows-workflow-foundation/flowchart-activities-in-wf.md b/docs/framework/windows-workflow-foundation/flowchart-activities-in-wf.md index f70c8bd0fd787..d9627d7f62c26 100644 --- a/docs/framework/windows-workflow-foundation/flowchart-activities-in-wf.md +++ b/docs/framework/windows-workflow-foundation/flowchart-activities-in-wf.md @@ -6,14 +6,14 @@ ms.assetid: e80d9734-b43a-4d21-a250-74400330a4c0 --- # Flowchart Activities in WF -[!INCLUDE[netfx_current_long](../../../includes/netfx-current-long-md.md)] provides several system-provided activities for controlling execution and branching within a Flowchart. - -| Activity type | Description | -|-|-| -||Executes contained activities using the familiar Flowchart paradigm.| -||A specialized that provides the ability to model a conditional node with two outcomes.| -||A specialized that allows modeling a switch construct, with one expression of a type defined in the activity’s type specifier and a single outcome for each match.| - +[!INCLUDE[netfx_current_long](../../../includes/netfx-current-long-md.md)] provides several system-provided activities for controlling execution and branching within a Flowchart. + +| Activity type | Description | +|-|-| +||Executes contained activities using the familiar Flowchart paradigm.| +||A specialized that provides the ability to model a conditional node with two outcomes.| +||A specialized that allows modeling a switch construct, with one expression of a type defined in the activity’s type specifier and a single outcome for each match.| + ## See also - [Getting Started Tutorial](getting-started-tutorial.md) diff --git a/docs/framework/windows-workflow-foundation/flowchart-workflows.md b/docs/framework/windows-workflow-foundation/flowchart-workflows.md index 53628f336436a..4b0574fbda709 100644 --- a/docs/framework/windows-workflow-foundation/flowchart-workflows.md +++ b/docs/framework/windows-workflow-foundation/flowchart-workflows.md @@ -10,7 +10,7 @@ A flowchart is a well-known paradigm for designing programs. The Flowchart activ ## Flowchart workflow structure - A Flowchart activity is an activity that contains a collection of activities to be executed. Flowcharts also contain flow control elements such as and that direct execution between contained activities based on the values of variables. + A Flowchart activity is an activity that contains a collection of activities to be executed. Flowcharts also contain flow control elements such as and that direct execution between contained activities based on the values of variables. ## Types of flow nodes @@ -20,7 +20,7 @@ A flowchart is a well-known paradigm for designing programs. The Flowchart activ - `FlowDecision` - Branches execution based on a Boolean condition, similar to . -- `FlowSwitch` – Branches execution based on an exclusive switch, similar to . +- `FlowSwitch` – Branches execution based on an exclusive switch, similar to . Each link has an `Action` property that defines a that can be used to execute child activities, and one or more `Next` properties that define which element or elements to execute when the current element finishes execution. @@ -50,7 +50,7 @@ To model a basic sequence in which two activities execute in turn, the `FlowStep ### Creating a conditional flowchart with a FlowDecision node -To model a conditional flow node in a flowchart workflow (that is, to create a link that functions as a traditional flowchart's decision symbol), a node is used. The property of the node is set to an expression that defines the condition, and the and properties are set to instances to be executed if the expression evaluates to `true` or `false`. The following example shows how to define a workflow that uses a node. +To model a conditional flow node in a flowchart workflow (that is, to create a link that functions as a traditional flowchart's decision symbol), a node is used. The property of the node is set to an expression that defines the condition, and the and properties are set to instances to be executed if the expression evaluates to `true` or `false`. The following example shows how to define a workflow that uses a node. ```xml @@ -77,7 +77,7 @@ To model a conditional flow node in a flowchart workflow (that is, to create a l ### Creating an exclusive switch with a FlowSwitch node -To model a flowchart in which one exclusive path is selected based on a matching value, the node is used. The property is set to a with a type parameter of that defines the value to match choices against. The property defines a dictionary of keys and objects to match against the conditional expression, and a set of objects that define how execution should flow if the given case matches the conditional expression. The also defines a property that defines how execution should flow if no cases match the condition expression. The following example demonstrates how to define a workflow that uses a element. +To model a flowchart in which one exclusive path is selected based on a matching value, the node is used. The property is set to a with a type parameter of that defines the value to match choices against. The property defines a dictionary of keys and objects to match against the conditional expression, and a set of objects that define how execution should flow if the given case matches the conditional expression. The also defines a property that defines how execution should flow if no cases match the condition expression. The following example demonstrates how to define a workflow that uses a element. ```xml diff --git a/docs/framework/windows-workflow-foundation/getting-started-tutorial.md b/docs/framework/windows-workflow-foundation/getting-started-tutorial.md index e63eeecf3022e..57b091045040f 100644 --- a/docs/framework/windows-workflow-foundation/getting-started-tutorial.md +++ b/docs/framework/windows-workflow-foundation/getting-started-tutorial.md @@ -2,38 +2,38 @@ title: "Getting Started Tutorial2" description: This article begins a sequence of tutorials that introduce you to programming Windows Workflow Foundation applications. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "WF [WF], getting started" - "Windows Workflow Foundation [WF], getting started" ms.assetid: c2d3585f-6b1a-4d4f-9865-bd7cd31c5d42 --- # Getting Started Tutorial -This section contains a set of walkthrough topics that introduce you to programming Windows Workflow Foundation (WF) applications. By following the procedures in these topics, you will build an application that is a number guessing game. The first topic in the tutorial leads you through the steps to create the custom activities required for the workflow. In the second topic, these activities are assembled along with built-in workflow activities into a flowchart workflow. In the third topic, the host application is configured to run the workflow, and in the final topic persistence is introduced. Each step in this process depends on the previous steps, so we recommend that you complete them in order. - -## In This Section - - [How to: Create an Activity](how-to-create-an-activity.md) - Describes how to create a custom activity that derives from , and how to compose this activity along with a built-in activity into a composite activity using the activity designer. - - [How to: Create a Workflow](how-to-create-a-workflow.md) - Describes how to create flowchart, sequential, and state machine workflows by using built-in activities and the custom activities from the preceding tutorial. - - [How to: Run a Workflow](how-to-run-a-workflow.md) - Describes how to invoke a workflow from a host environment, pass data into and out of a workflow, and how to resume bookmarks. - - [How to: Create and Run a Long Running Workflow](how-to-create-and-run-a-long-running-workflow.md) - Describes how to add persistence to a workflow application. - - [How to: Create a Custom Tracking Participant](how-to-create-a-custom-tracking-participant.md) - Describes how to create a custom tracking participant and tracking profile. - - [How to: Host Multiple Versions of a Workflow Side-by-Side](how-to-host-multiple-versions-of-a-workflow-side-by-side.md) - Describes how to use `WorkflowIdentity` to host multiple versions of a workflow side-by-side. - - [How to: Update the Definition of a Running Workflow Instance](how-to-update-the-definition-of-a-running-workflow-instance.md) - Describes how to use dynamic update to modify running workflow instances. - +This section contains a set of walkthrough topics that introduce you to programming Windows Workflow Foundation (WF) applications. By following the procedures in these topics, you will build an application that is a number guessing game. The first topic in the tutorial leads you through the steps to create the custom activities required for the workflow. In the second topic, these activities are assembled along with built-in workflow activities into a flowchart workflow. In the third topic, the host application is configured to run the workflow, and in the final topic persistence is introduced. Each step in this process depends on the previous steps, so we recommend that you complete them in order. + +## In This Section + + [How to: Create an Activity](how-to-create-an-activity.md) + Describes how to create a custom activity that derives from , and how to compose this activity along with a built-in activity into a composite activity using the activity designer. + + [How to: Create a Workflow](how-to-create-a-workflow.md) + Describes how to create flowchart, sequential, and state machine workflows by using built-in activities and the custom activities from the preceding tutorial. + + [How to: Run a Workflow](how-to-run-a-workflow.md) + Describes how to invoke a workflow from a host environment, pass data into and out of a workflow, and how to resume bookmarks. + + [How to: Create and Run a Long Running Workflow](how-to-create-and-run-a-long-running-workflow.md) + Describes how to add persistence to a workflow application. + + [How to: Create a Custom Tracking Participant](how-to-create-a-custom-tracking-participant.md) + Describes how to create a custom tracking participant and tracking profile. + + [How to: Host Multiple Versions of a Workflow Side-by-Side](how-to-host-multiple-versions-of-a-workflow-side-by-side.md) + Describes how to use `WorkflowIdentity` to host multiple versions of a workflow side-by-side. + + [How to: Update the Definition of a Running Workflow Instance](how-to-update-the-definition-of-a-running-workflow-instance.md) + Describes how to use dynamic update to modify running workflow instances. + ## See also - [Windows Workflow Foundation Programming](programming.md) diff --git a/docs/framework/windows-workflow-foundation/how-to-create-a-custom-activity-designer.md b/docs/framework/windows-workflow-foundation/how-to-create-a-custom-activity-designer.md index 5dcdec8e5a2bc..30639e0f7795a 100644 --- a/docs/framework/windows-workflow-foundation/how-to-create-a-custom-activity-designer.md +++ b/docs/framework/windows-workflow-foundation/how-to-create-a-custom-activity-designer.md @@ -100,7 +100,7 @@ This topic outlines two procedures. ``` -13. To associate an activity designer with an activity type, you must register that activity designer with the metadata store. To do this, add the `RegisterMetadata` method to the `RehostingWFDesigner` class. Within the scope of the `RegisterMetadata` method, create an object and call the method to add the attributes to it. Call the method to add the to the metadata store. The following code contains the rehosting logic for the designer. It registers the metadata, puts the `SimpleNativeActivity` into the toolbox, and creates the workflow. Put this code into the *RehostingWFDesigner.xaml.cs* file. +13. To associate an activity designer with an activity type, you must register that activity designer with the metadata store. To do this, add the `RegisterMetadata` method to the `RehostingWFDesigner` class. Within the scope of the `RegisterMetadata` method, create an object and call the method to add the attributes to it. Call the method to add the to the metadata store. The following code contains the rehosting logic for the designer. It registers the metadata, puts the `SimpleNativeActivity` into the toolbox, and creates the workflow. Put this code into the *RehostingWFDesigner.xaml.cs* file. ```csharp using System; diff --git a/docs/framework/windows-workflow-foundation/how-to-create-a-custom-activity-template.md b/docs/framework/windows-workflow-foundation/how-to-create-a-custom-activity-template.md index d0bbadff8caf1..f1d55b7055b74 100644 --- a/docs/framework/windows-workflow-foundation/how-to-create-a-custom-activity-template.md +++ b/docs/framework/windows-workflow-foundation/how-to-create-a-custom-activity-template.md @@ -10,7 +10,7 @@ Custom activity templates are used to customize the configuration of activities, The first procedure in this topic describes how to create a custom activity template for a **Delay** activity and the second procedure describes briefly how to make it available in a Workflow Designer to verify that the custom template works. - Custom activity templates must implement the . The interface has a single method with which you can create and configure the activity instances used in the template. + Custom activity templates must implement the . The interface has a single method with which you can create and configure the activity instances used in the template. ## To create a template for the Delay activity diff --git a/docs/framework/windows-workflow-foundation/how-to-create-a-custom-instance-store.md b/docs/framework/windows-workflow-foundation/how-to-create-a-custom-instance-store.md index 873cf2fb4d90e..fbd8d7ac801d0 100644 --- a/docs/framework/windows-workflow-foundation/how-to-create-a-custom-instance-store.md +++ b/docs/framework/windows-workflow-foundation/how-to-create-a-custom-instance-store.md @@ -11,13 +11,13 @@ ms.assetid: 593c4e9d-8a49-4e12-8257-cee5e6b4c075 ## Implementing the BeginTryCommand method -The is sent to the instance store by the persistence engine. The type of the `command` parameter indicates which command is being executed; this parameter can be of the following types: +The is sent to the instance store by the persistence engine. The type of the `command` parameter indicates which command is being executed; this parameter can be of the following types: -- : The persistence engine sends this command to the instance store when a workflow is to be persisted to the storage medium. The workflow persistence data is provided to the method in the member of the `command` parameter. +- : The persistence engine sends this command to the instance store when a workflow is to be persisted to the storage medium. The workflow persistence data is provided to the method in the member of the `command` parameter. -- : The persistence engine sends this command to the instance store when a workflow is to be loaded from the storage medium. The instance ID of the workflow to be loaded is provided to the method in the `instanceId` parameter of the property of the `context` parameter. +- : The persistence engine sends this command to the instance store when a workflow is to be loaded from the storage medium. The instance ID of the workflow to be loaded is provided to the method in the `instanceId` parameter of the property of the `context` parameter. -- : The persistence engine sends this command to the instance store when a must be registered as a lock owner. The instance ID of the current workflow should be provided to the instance store using method of the `context` parameter. +- : The persistence engine sends this command to the instance store when a must be registered as a lock owner. The instance ID of the current workflow should be provided to the instance store using method of the `context` parameter. The following code snippet demonstrates how to implement the CreateWorkflowOwner command to assign an explicit lock owner. @@ -83,7 +83,7 @@ The is } ``` -- : The persistence engine sends this command to the instance store when a workflow instance is to be loaded using the workflow’s instance key. The ID of the instance key can be determined by using the parameter of the command. +- : The persistence engine sends this command to the instance store when a workflow instance is to be loaded using the workflow’s instance key. The ID of the instance key can be determined by using the parameter of the command. - : The persistence engine sends this command to the instance store to retrieve activation parameters for persisted workflows in order to create a workflow host that can then load workflows. This command is sent by the engine in response to the instance store raising the to the host when it locates an instance that can be activated. The instance store should be polled to determine if there are workflows that can be activated. @@ -127,7 +127,7 @@ The is } ``` - In the above code snippet, the instance store queries the events available and examines each one to determine if it is a event. If one is found, is called to signal the host to send a command to the instance store. The following code snippet demonstrates an implementation of a handler for this command. + In the above code snippet, the instance store queries the events available and examines each one to determine if it is a event. If one is found, is called to signal the host to send a command to the instance store. The following code snippet demonstrates an implementation of a handler for this command. ```csharp If (command is TryLoadRunnableWorkflowCommand) @@ -222,7 +222,7 @@ The is ## Using a custom instance store -To implement a custom instance store, assign an instance of the instance store to the , and implement the method. See the [How to: Create and Run a Long Running Workflow](how-to-create-and-run-a-long-running-workflow.md) tutorial for specifics. +To implement a custom instance store, assign an instance of the instance store to the , and implement the method. See the [How to: Create and Run a Long Running Workflow](how-to-create-and-run-a-long-running-workflow.md) tutorial for specifics. ## A sample instance store diff --git a/docs/framework/windows-workflow-foundation/how-to-create-a-custom-persistence-participant.md b/docs/framework/windows-workflow-foundation/how-to-create-a-custom-persistence-participant.md index f653e928fc6b2..79bd4e767fe90 100644 --- a/docs/framework/windows-workflow-foundation/how-to-create-a-custom-persistence-participant.md +++ b/docs/framework/windows-workflow-foundation/how-to-create-a-custom-persistence-participant.md @@ -6,49 +6,49 @@ ms.assetid: 1d9cc47a-8966-4286-94d5-4221403d9c06 --- # How to: Create a Custom Persistence Participant -The following procedure has steps to create a persistence participant. See the [Participating in Persistence](/previous-versions/dotnet/netframework-4.0/dd699769(v=vs.100)) sample and [Store Extensibility](store-extensibility.md) topic for sample implementations of persistence participants. - -1. Create a class deriving from the or the class. The PersistenceIOParticipant class offers the same extensibility points as the PersistenceParticipant class in addition to being able to participate in I/O operations. Follow one or more of the following steps. - -2. Implement the method. The **CollectValues** method has two dictionary parameters, one for storing read/write values and the other one for storing write-only values (used later in queries). In this method, you should populate these dictionaries with data that is specific to a persistence participant. Each dictionary contains the name of the value as the key and the value itself as an object. - +The following procedure has steps to create a persistence participant. See the [Participating in Persistence](/previous-versions/dotnet/netframework-4.0/dd699769(v=vs.100)) sample and [Store Extensibility](store-extensibility.md) topic for sample implementations of persistence participants. + +1. Create a class deriving from the or the class. The PersistenceIOParticipant class offers the same extensibility points as the PersistenceParticipant class in addition to being able to participate in I/O operations. Follow one or more of the following steps. + +2. Implement the method. The **CollectValues** method has two dictionary parameters, one for storing read/write values and the other one for storing write-only values (used later in queries). In this method, you should populate these dictionaries with data that is specific to a persistence participant. Each dictionary contains the name of the value as the key and the value itself as an object. + The values in the readWriteValues dictionary are packaged as **InstanceValue** objects. The values in the write-only dictionary are packaged as **InstanceValue** objects with InstanceValueOptions.Optional and InstanceValueOption.WriteOnly set. Each **InstanceValue** provided by the **CollectValues** implementations across all persistence participants must have a unique name. - - ```csharp + + ```csharp protected virtual void CollectValues(out IDictionary readWriteValues, out IDictionary writeOnlyValues) { } - ``` - -3. Implement the method. The **MapValues** method takes two parameters that are similar to the parameters that the **CollectValues** method receives. All the values collected in the **CollectValues** stage are passed through these dictionary parameters. The new values added by the **MapValues** stage are added to the write-only values. The write-only dictionary is used to provide data to an external source not directly associated with the instance values. Each value provided by implementations of the **MapValues** method across all persistence participants must have a unique name. - - ```csharp + ``` + +3. Implement the method. The **MapValues** method takes two parameters that are similar to the parameters that the **CollectValues** method receives. All the values collected in the **CollectValues** stage are passed through these dictionary parameters. The new values added by the **MapValues** stage are added to the write-only values. The write-only dictionary is used to provide data to an external source not directly associated with the instance values. Each value provided by implementations of the **MapValues** method across all persistence participants must have a unique name. + + ```csharp protected virtual IDictionary MapValues(IDictionary readWriteValues,IDictionary writeOnlyValues) { } - ``` - - The method provides functionality that does not, in that it allows for a dependency on another value provided by another persistence participant that hasn’t been processed by yet. - -4. Implement the **PublishValues** method. The **PublishValues** method receives a dictionary containing all the values loaded from the persistence store. - - ```csharp + ``` + + The method provides functionality that does not, in that it allows for a dependency on another value provided by another persistence participant that hasn’t been processed by yet. + +4. Implement the **PublishValues** method. The **PublishValues** method receives a dictionary containing all the values loaded from the persistence store. + + ```csharp protected virtual void PublishValues(IDictionary readWriteValues) { } - ``` - -5. Implement the **BeginOnSave** method if the participant is a persistence I/O participant. This method is called during a Save operation. In this method, you should perform I/O adjunct to the persisting (saving) workflow instances. If the host is using a transaction for the corresponding persistence command, the same transaction is provided in Transaction.Current. Additionally, PersistenceIOParticipants may advertise a transactional consistency requirement, in which case the host creates a transaction for the persistence episode if one would not otherwise be used. - - ```csharp + ``` + +5. Implement the **BeginOnSave** method if the participant is a persistence I/O participant. This method is called during a Save operation. In this method, you should perform I/O adjunct to the persisting (saving) workflow instances. If the host is using a transaction for the corresponding persistence command, the same transaction is provided in Transaction.Current. Additionally, PersistenceIOParticipants may advertise a transactional consistency requirement, in which case the host creates a transaction for the persistence episode if one would not otherwise be used. + + ```csharp protected virtual IAsyncResult BeginOnSave(IDictionary readWriteValues, IDictionary writeOnlyValues, TimeSpan timeout, AsyncCallback callback, Object state) { } - ``` - -6. Implement the **BeginOnLoad** method if the participant is a persistence I/O participant. This method is called during a Load operation. In this method, you should perform I/O adjunct to the loading of workflow instances. If the host is using a transaction for the corresponding persistence command, the same transaction is provided in Transaction.Current. Additionally, Persistence I/O participants may advertise a transactional consistency requirement, in which case the host creates a transaction for the persistence episode if one would not otherwise be used. - - ```csharp + ``` + +6. Implement the **BeginOnLoad** method if the participant is a persistence I/O participant. This method is called during a Load operation. In this method, you should perform I/O adjunct to the loading of workflow instances. If the host is using a transaction for the corresponding persistence command, the same transaction is provided in Transaction.Current. Additionally, Persistence I/O participants may advertise a transactional consistency requirement, in which case the host creates a transaction for the persistence episode if one would not otherwise be used. + + ```csharp protected virtual IAsyncResult BeginOnLoad(IDictionary readWriteValues, TimeSpan timeout, AsyncCallback callback, Object state) { } diff --git a/docs/framework/windows-workflow-foundation/how-to-create-a-sequential-workflow.md b/docs/framework/windows-workflow-foundation/how-to-create-a-sequential-workflow.md index ff84408554858..49a22e9a4a186 100644 --- a/docs/framework/windows-workflow-foundation/how-to-create-a-sequential-workflow.md +++ b/docs/framework/windows-workflow-foundation/how-to-create-a-sequential-workflow.md @@ -82,7 +82,7 @@ Workflows can be constructed from built-in activities as well as from custom act Guess != Target ``` - A activity executes its child activities and then evaluates its . If the evaluates to `True`, then the activities in the execute again. In this example, the user’s guess is evaluated and the continues until the guess is correct. + A activity executes its child activities and then evaluates its . If the evaluates to `True`, then the activities in the execute again. In this example, the user’s guess is evaluated and the continues until the guess is correct. 4. Drag a **Prompt** activity from the **NumberGuessWorkflowActivities** section of the **Toolbox** and drop it in the **DoWhile** activity from the previous step. diff --git a/docs/framework/windows-workflow-foundation/how-to-create-a-state-machine-workflow.md b/docs/framework/windows-workflow-foundation/how-to-create-a-state-machine-workflow.md index f722c51f96412..d5474673e9589 100644 --- a/docs/framework/windows-workflow-foundation/how-to-create-a-state-machine-workflow.md +++ b/docs/framework/windows-workflow-foundation/how-to-create-a-state-machine-workflow.md @@ -2,183 +2,183 @@ title: "How to: Create a State Machine Workflow" description: This article creates a workflow that uses both built-in activities, such as the StateMachine activity, and custom activities. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 3ec60e8f-fad4-493e-a426-e7962d7aee8c --- # How to: Create a State Machine Workflow -Workflows can be constructed from built-in activities as well as from custom activities. This topic steps through creating a workflow that uses both built-in activities such as the activity, and the custom activities from the previous [How to: Create an Activity](how-to-create-an-activity.md) topic. The workflow models a number guessing game. - +Workflows can be constructed from built-in activities as well as from custom activities. This topic steps through creating a workflow that uses both built-in activities such as the activity, and the custom activities from the previous [How to: Create an Activity](how-to-create-an-activity.md) topic. The workflow models a number guessing game. + > [!NOTE] -> Each topic in the Getting Started tutorial depends on the previous topics. To complete this topic, you must first complete [How to: Create an Activity](how-to-create-an-activity.md). - -### To create the workflow - -1. Right-click **NumberGuessWorkflowActivities** in **Solution Explorer** and select **Add**, **New Item**. - -2. In the **Installed**, **Common Items** node, select **Workflow**. Select **Activity** from the **Workflow** list. - -3. Type `StateMachineNumberGuessWorkflow` into the **Name** box and click **Add**. - -4. Drag a **StateMachine** activity from the **State Machine** section of the **Toolbox** and drop it onto the **Drop activity here** label on the workflow design surface. - -### To create the workflow variables and arguments - -1. Double-click **StateMachineNumberGuessWorkflow.xaml** in **Solution Explorer** to display the workflow in the designer, if it is not already displayed. - -2. Click **Arguments** in the lower-left side of the workflow designer to display the **Arguments** pane. - -3. Click **Create Argument**. - -4. Type `MaxNumber` into the **Name** box, select **In** from the **Direction** drop-down list, select **Int32** from the **Argument type** drop-down list, and then press ENTER to save the argument. - -5. Click **Create Argument**. - -6. Type `Turns` into the **Name** box that is below the newly added `MaxNumber` argument, select **Out** from the **Direction** drop-down list, select **Int32** from the **Argument type** drop-down list, and then press ENTER. - -7. Click **Arguments** in the lower-left side of the activity designer to close the **Arguments** pane. - -8. Click **Variables** in the lower-left side of the workflow designer to display the **Variables** pane. - -9. Click **Create Variable**. - +> Each topic in the Getting Started tutorial depends on the previous topics. To complete this topic, you must first complete [How to: Create an Activity](how-to-create-an-activity.md). + +### To create the workflow + +1. Right-click **NumberGuessWorkflowActivities** in **Solution Explorer** and select **Add**, **New Item**. + +2. In the **Installed**, **Common Items** node, select **Workflow**. Select **Activity** from the **Workflow** list. + +3. Type `StateMachineNumberGuessWorkflow` into the **Name** box and click **Add**. + +4. Drag a **StateMachine** activity from the **State Machine** section of the **Toolbox** and drop it onto the **Drop activity here** label on the workflow design surface. + +### To create the workflow variables and arguments + +1. Double-click **StateMachineNumberGuessWorkflow.xaml** in **Solution Explorer** to display the workflow in the designer, if it is not already displayed. + +2. Click **Arguments** in the lower-left side of the workflow designer to display the **Arguments** pane. + +3. Click **Create Argument**. + +4. Type `MaxNumber` into the **Name** box, select **In** from the **Direction** drop-down list, select **Int32** from the **Argument type** drop-down list, and then press ENTER to save the argument. + +5. Click **Create Argument**. + +6. Type `Turns` into the **Name** box that is below the newly added `MaxNumber` argument, select **Out** from the **Direction** drop-down list, select **Int32** from the **Argument type** drop-down list, and then press ENTER. + +7. Click **Arguments** in the lower-left side of the activity designer to close the **Arguments** pane. + +8. Click **Variables** in the lower-left side of the workflow designer to display the **Variables** pane. + +9. Click **Create Variable**. + > [!TIP] - > If no **Create Variable** box is displayed, click the activity on the workflow designer surface to select it. - -10. Type `Guess` into the **Name** box, select **Int32** from the **Variable type** drop-down list, and then press ENTER to save the variable. - -11. Click **Create Variable**. - -12. Type `Target` into the **Name** box, select **Int32** from the **Variable type** drop-down list, and then press ENTER to save the variable. - -13. Click **Variables** in the lower-left side of the activity designer to close the **Variables** pane. - -### To add the workflow activities - -1. Click **State1** to select it. In the **Properties Window**, change the **DisplayName** to `Initialize Target`. - + > If no **Create Variable** box is displayed, click the activity on the workflow designer surface to select it. + +10. Type `Guess` into the **Name** box, select **Int32** from the **Variable type** drop-down list, and then press ENTER to save the variable. + +11. Click **Create Variable**. + +12. Type `Target` into the **Name** box, select **Int32** from the **Variable type** drop-down list, and then press ENTER to save the variable. + +13. Click **Variables** in the lower-left side of the activity designer to close the **Variables** pane. + +### To add the workflow activities + +1. Click **State1** to select it. In the **Properties Window**, change the **DisplayName** to `Initialize Target`. + > [!TIP] - > If the **Properties Window** is not displayed, select **Properties Window** from the **View** menu. - -2. Double-click the newly renamed **Initialize Target** state in the workflow designer to expand it. - -3. Drag an **Assign** activity from the **Primitives** section of the **Toolbox** and drop it onto the **Entry** section of the state. Type `Target` into the **To** box and the following expression into the **Enter a C# expression** or **Enter a VB expression** box. - - ```vb - New System.Random().Next(1, MaxNumber + 1) - ``` - - ```csharp - new System.Random().Next(1, MaxNumber + 1) - ``` - + > If the **Properties Window** is not displayed, select **Properties Window** from the **View** menu. + +2. Double-click the newly renamed **Initialize Target** state in the workflow designer to expand it. + +3. Drag an **Assign** activity from the **Primitives** section of the **Toolbox** and drop it onto the **Entry** section of the state. Type `Target` into the **To** box and the following expression into the **Enter a C# expression** or **Enter a VB expression** box. + + ```vb + New System.Random().Next(1, MaxNumber + 1) + ``` + + ```csharp + new System.Random().Next(1, MaxNumber + 1) + ``` + > [!TIP] - > If the **Toolbox** window is not displayed, select **Toolbox** from the **View** menu. - -4. Return to the overall state machine view in the workflow designer by clicking **StateMachine** in the breadcrumb display at the top of the workflow designer. - -5. Drag a **State** activity from the **State Machine** section of the **Toolbox** onto the workflow designer and hover it over the **Initialize Target** state. Note that four triangles will appear around the **Initialize Target** state when the new state is over it. Drop the new state on the triangle that is immediately below the **Initialize Target** state. This places the new state onto the workflow and creates a transition from the **Initialize Target** state to the new state. - -6. Click **State1** to select it, change the **DisplayName** to `Enter Guess`, and then double-click the state in the workflow designer to expand it. - -7. Drag a **WriteLine** activity from the **Primitives** section of the **Toolbox** and drop it onto the **Entry** section of the state. - -8. Type the following expression into the **Text** property box of the **WriteLine**. - - ```vb - "Please enter a number between 1 and " & MaxNumber - ``` - - ```csharp - "Please enter a number between 1 and " + MaxNumber - ``` - -9. Drag an **Assign** activity from the **Primitives** section of the **Toolbox** and drop onto the **Exit** section of the state. - -10. Type `Turns` into the **To** box and `Turns + 1` into the **Enter a C# expression** or **Enter a VB expression** box. - -11. Return to the overall state machine view in the workflow designer by clicking **StateMachine** in the breadcrumb display at the top of the workflow designer. - -12. Drag a **FinalState** activity from the **State Machine** section of the **Toolbox**, hover it over the **Enter Guess** state, and drop it onto the triangle that appears to the right of the **Enter Guess** state so that a transition is created between **Enter Guess** and **FinalState**. - -13. The default name of the transition is **T2**. Click the transition in the workflow designer to select it, and set its **DisplayName** to **Guess Correct**. Then click and select the **FinalState**, and drag it to the right so that there is room for the full transition name to be displayed without overlaying either of the two states. This will make it easier to complete the remaining steps in the tutorial. - -14. Double-click the newly renamed **Guess Correct** transition in the workflow designer to expand it. - -15. Drag a **ReadInt** activity from the **NumberGuessWorkflowActivities** section of the **Toolbox** and drop it in the **Trigger** section of the transition. - -16. In the **Properties Window** for the **ReadInt** activity, type `"EnterGuess"` including the quotes into the **BookmarkName** property value box, and type `Guess` into the **Result** property value box - -17. Type the following expression into the **Guess Correct** transition’s **Condition** property value box. - - ```vb - Guess = Target - ``` - - ```csharp - Guess == Target - ``` - -18. Return to the overall state machine view in the workflow designer by clicking **StateMachine** in the breadcrumb display at the top of the workflow designer. - + > If the **Toolbox** window is not displayed, select **Toolbox** from the **View** menu. + +4. Return to the overall state machine view in the workflow designer by clicking **StateMachine** in the breadcrumb display at the top of the workflow designer. + +5. Drag a **State** activity from the **State Machine** section of the **Toolbox** onto the workflow designer and hover it over the **Initialize Target** state. Note that four triangles will appear around the **Initialize Target** state when the new state is over it. Drop the new state on the triangle that is immediately below the **Initialize Target** state. This places the new state onto the workflow and creates a transition from the **Initialize Target** state to the new state. + +6. Click **State1** to select it, change the **DisplayName** to `Enter Guess`, and then double-click the state in the workflow designer to expand it. + +7. Drag a **WriteLine** activity from the **Primitives** section of the **Toolbox** and drop it onto the **Entry** section of the state. + +8. Type the following expression into the **Text** property box of the **WriteLine**. + + ```vb + "Please enter a number between 1 and " & MaxNumber + ``` + + ```csharp + "Please enter a number between 1 and " + MaxNumber + ``` + +9. Drag an **Assign** activity from the **Primitives** section of the **Toolbox** and drop onto the **Exit** section of the state. + +10. Type `Turns` into the **To** box and `Turns + 1` into the **Enter a C# expression** or **Enter a VB expression** box. + +11. Return to the overall state machine view in the workflow designer by clicking **StateMachine** in the breadcrumb display at the top of the workflow designer. + +12. Drag a **FinalState** activity from the **State Machine** section of the **Toolbox**, hover it over the **Enter Guess** state, and drop it onto the triangle that appears to the right of the **Enter Guess** state so that a transition is created between **Enter Guess** and **FinalState**. + +13. The default name of the transition is **T2**. Click the transition in the workflow designer to select it, and set its **DisplayName** to **Guess Correct**. Then click and select the **FinalState**, and drag it to the right so that there is room for the full transition name to be displayed without overlaying either of the two states. This will make it easier to complete the remaining steps in the tutorial. + +14. Double-click the newly renamed **Guess Correct** transition in the workflow designer to expand it. + +15. Drag a **ReadInt** activity from the **NumberGuessWorkflowActivities** section of the **Toolbox** and drop it in the **Trigger** section of the transition. + +16. In the **Properties Window** for the **ReadInt** activity, type `"EnterGuess"` including the quotes into the **BookmarkName** property value box, and type `Guess` into the **Result** property value box + +17. Type the following expression into the **Guess Correct** transition’s **Condition** property value box. + + ```vb + Guess = Target + ``` + + ```csharp + Guess == Target + ``` + +18. Return to the overall state machine view in the workflow designer by clicking **StateMachine** in the breadcrumb display at the top of the workflow designer. + > [!NOTE] - > A transition occurs when the trigger event is received and the , if present, evaluates to `True`. For this transition, if the user’s `Guess` matches the randomly generated `Target`, then control passes to the **FinalState** and the workflow completes. - -19. Depending on whether the guess is correct, the workflow should transition either to the **FinalState** or back to the **Enter Guess** state for another try. Both transitions share the same trigger of waiting for the user’s guess to be received via the **ReadInt** activity. This is called a shared transition. To create a shared transition, click the circle that indicates the start of the **Guess Correct** transition and drag it to the desired state. In this case the transition is a self-transition, so drag the start point of the **Guess Correct** transition and drop it back onto the bottom of the **Enter Guess** state. After creating the transition, select it in the workflow designer and set its **DisplayName** property to **Guess Incorrect**. - + > A transition occurs when the trigger event is received and the , if present, evaluates to `True`. For this transition, if the user’s `Guess` matches the randomly generated `Target`, then control passes to the **FinalState** and the workflow completes. + +19. Depending on whether the guess is correct, the workflow should transition either to the **FinalState** or back to the **Enter Guess** state for another try. Both transitions share the same trigger of waiting for the user’s guess to be received via the **ReadInt** activity. This is called a shared transition. To create a shared transition, click the circle that indicates the start of the **Guess Correct** transition and drag it to the desired state. In this case the transition is a self-transition, so drag the start point of the **Guess Correct** transition and drop it back onto the bottom of the **Enter Guess** state. After creating the transition, select it in the workflow designer and set its **DisplayName** property to **Guess Incorrect**. + > [!NOTE] - > Shared transitions can also be created from within the transition designer by clicking **Add shared trigger transition** at the bottom of the transition designer, and then selecting the desired target state from the **Available states to connect** drop-down. + > Shared transitions can also be created from within the transition designer by clicking **Add shared trigger transition** at the bottom of the transition designer, and then selecting the desired target state from the **Available states to connect** drop-down. > [!NOTE] - > Note that if the of a transition evaluates to `false` (or all of the conditions of a shared trigger transition evaluate to `false`), the transition will not occur and all triggers for all the transitions from the state will be rescheduled. In this tutorial, this situation cannot happen because of the way the conditions are configured (we have specific actions for whether the guess is correct or incorrect). - -20. Double-click the **Guess Incorrect** transition in the workflow designer to expand it. Note that the **Trigger** is already set to the same **ReadInt** activity that was used by the **Guess Correct** transition. - -21. Type the following expression into the **Condition** property value box. - - ```vb - Guess <> Target - ``` - - ```csharp - Guess != Target - ``` - -22. Drag an **If** activity from the **Control Flow** section of the **Toolbox** and drop it in the **Action** section of the transition. - -23. Type the following expression into the **If** activity’s **Condition** property value box. - + > Note that if the of a transition evaluates to `false` (or all of the conditions of a shared trigger transition evaluate to `false`), the transition will not occur and all triggers for all the transitions from the state will be rescheduled. In this tutorial, this situation cannot happen because of the way the conditions are configured (we have specific actions for whether the guess is correct or incorrect). + +20. Double-click the **Guess Incorrect** transition in the workflow designer to expand it. Note that the **Trigger** is already set to the same **ReadInt** activity that was used by the **Guess Correct** transition. + +21. Type the following expression into the **Condition** property value box. + + ```vb + Guess <> Target + ``` + + ```csharp + Guess != Target + ``` + +22. Drag an **If** activity from the **Control Flow** section of the **Toolbox** and drop it in the **Action** section of the transition. + +23. Type the following expression into the **If** activity’s **Condition** property value box. + ```text Guess < Target - ``` - -24. Drag two **WriteLine** activities from the **Primitives** section of the **Toolbox** and drop them so that one is in the **Then** section of the **If** activity, and one is in the **Else** section. - -25. Click the **WriteLine** activity in the **Then** section to select it, and type the following expression into the **Text** property value box. - + ``` + +24. Drag two **WriteLine** activities from the **Primitives** section of the **Toolbox** and drop them so that one is in the **Then** section of the **If** activity, and one is in the **Else** section. + +25. Click the **WriteLine** activity in the **Then** section to select it, and type the following expression into the **Text** property value box. + ```text - "Your guess is too low." - ``` - -26. Click the **WriteLine** activity in the **Else** section to select it, and type the following expression into the **Text** property value box. - + "Your guess is too low." + ``` + +26. Click the **WriteLine** activity in the **Else** section to select it, and type the following expression into the **Text** property value box. + ```text - "Your guess is too high." - ``` - -27. Return to the overall state machine view in the workflow designer by clicking **StateMachine** in the breadcrumb display at the top of the workflow designer. - - The following example illustrates the completed workflow. - - ![Illustration that shows the completed state machine workflow.](./media/how-to-create-a-state-machine-workflow/complete-state-machine-workflow.jpg) - -### To build the workflow - -1. Press CTRL+SHIFT+B to build the solution. - - For instructions on how to run the workflow, please see the next topic, [How to: Run a Workflow](how-to-run-a-workflow.md). If you have already completed the [How to: Run a Workflow](how-to-run-a-workflow.md) step with a different style of workflow and wish to run it using the state machine workflow from this step, skip ahead to the [To build and run the application](how-to-run-a-workflow.md#BKMK_ToRunTheApplication) section of [How to: Run a Workflow](how-to-run-a-workflow.md). - + "Your guess is too high." + ``` + +27. Return to the overall state machine view in the workflow designer by clicking **StateMachine** in the breadcrumb display at the top of the workflow designer. + + The following example illustrates the completed workflow. + + ![Illustration that shows the completed state machine workflow.](./media/how-to-create-a-state-machine-workflow/complete-state-machine-workflow.jpg) + +### To build the workflow + +1. Press CTRL+SHIFT+B to build the solution. + + For instructions on how to run the workflow, please see the next topic, [How to: Run a Workflow](how-to-run-a-workflow.md). If you have already completed the [How to: Run a Workflow](how-to-run-a-workflow.md) step with a different style of workflow and wish to run it using the state machine workflow from this step, skip ahead to the [To build and run the application](how-to-run-a-workflow.md#BKMK_ToRunTheApplication) section of [How to: Run a Workflow](how-to-run-a-workflow.md). + ## See also - diff --git a/docs/framework/windows-workflow-foundation/how-to-create-an-activity.md b/docs/framework/windows-workflow-foundation/how-to-create-an-activity.md index 37373d3296321..e778ef94115ae 100644 --- a/docs/framework/windows-workflow-foundation/how-to-create-an-activity.md +++ b/docs/framework/windows-workflow-foundation/how-to-create-an-activity.md @@ -38,7 +38,7 @@ Activities are the core unit of behavior in WF. The execution logic of an activi [!code-vb[CFX_WF_GettingStarted#1](~/samples/snippets/visualbasic/VS_Snippets_CFX/cfx_wf_gettingstarted/vb/readint.vb#1)] > [!NOTE] - > The `ReadInt` activity derives from instead of , which is the default for the code activity template. can be used if the activity provides a single result, which is exposed through the argument, but does not support the use of bookmarks, so is used. + > The `ReadInt` activity derives from instead of , which is the default for the code activity template. can be used if the activity provides a single result, which is exposed through the argument, but does not support the use of bookmarks, so is used. ## Create the Prompt activity @@ -97,7 +97,7 @@ For instructions on how to create a workflow by using these activities, see the ## See also - -- +- - [Designing and Implementing Custom Activities](designing-and-implementing-custom-activities.md) - [Getting Started Tutorial](getting-started-tutorial.md) - [How to: Create a Workflow](how-to-create-a-workflow.md) diff --git a/docs/framework/windows-workflow-foundation/how-to-deserialize-instance-data-properties.md b/docs/framework/windows-workflow-foundation/how-to-deserialize-instance-data-properties.md index c97133dbb1063..32150ec8e67e6 100644 --- a/docs/framework/windows-workflow-foundation/how-to-deserialize-instance-data-properties.md +++ b/docs/framework/windows-workflow-foundation/how-to-deserialize-instance-data-properties.md @@ -16,7 +16,7 @@ Primitive data properties refer to properties whose .NET types are considered to *Read/write* properties refer to properties that are returned back to the Workflow Runtime when an instance is loaded. *WriteOnly* properties are written to the database and then never read again. -This example provides code that enables a user to deserialize primitive data properties. Given a byte array read from either the ReadWritePrimitiveDataProperties or WriteOnlyPrimitiveDataProperties column, this code will convert the binary large object (BLOB) into a of type `` where each key-value pair represents a property name and its corresponding value. +This example provides code that enables a user to deserialize primitive data properties. Given a byte array read from either the ReadWritePrimitiveDataProperties or WriteOnlyPrimitiveDataProperties column, this code will convert the binary large object (BLOB) into a of type `` where each key-value pair represents a property name and its corresponding value. [!INCLUDE [managed-identities](../../includes/managed-identities.md)] diff --git a/docs/framework/windows-workflow-foundation/how-to-display-validation-errors-in-a-rehosted-designer.md b/docs/framework/windows-workflow-foundation/how-to-display-validation-errors-in-a-rehosted-designer.md index 99a4d6af4ec1b..f66e649c0d1f8 100644 --- a/docs/framework/windows-workflow-foundation/how-to-display-validation-errors-in-a-rehosted-designer.md +++ b/docs/framework/windows-workflow-foundation/how-to-display-validation-errors-in-a-rehosted-designer.md @@ -6,36 +6,36 @@ ms.assetid: 5aa8fb53-8f75-433b-bc06-7c7d33583d5d --- # How to: Display Validation Errors in a Rehosted Designer -This topic describes how to retrieve and publish validation errors in a rehosted Windows Workflow Designer. This provides us with a procedure to confirm that a workflow in a rehosted designer is valid. - - This task has two parts. The first is to provide an implementation . There is one critical method to implement on this interface, which will pass you a list of objects containing information about the errors to the debug log. After implementing the interface, you retrieve the error information by publishing an instance of that implementation to the editing context. - -### Implement the IValidationErrorService Interface - -1. Here is a code sample for a simple implementation that will write out the validation errors to the debug log. - - ```csharp - using System.Activities.Presentation.Validation; - using System.Collections.Generic; - using System.Diagnostics; - using System.Linq; - - namespace VariableFinderShell - { - class DebugValidationErrorService : IValidationErrorService - { - public void ShowValidationErrors(IList errors) - { - errors.ToList().ForEach(vei => Debug.WriteLine($"Error: {vei.Message}")); - } - } - } - ``` - -### Publishing to the Editing Context - -1. Here is the code that will publish this to the editing context. - - ```csharp - wd.Context.Services.Publish(new DebugValidationErrorService()); +This topic describes how to retrieve and publish validation errors in a rehosted Windows Workflow Designer. This provides us with a procedure to confirm that a workflow in a rehosted designer is valid. + + This task has two parts. The first is to provide an implementation . There is one critical method to implement on this interface, which will pass you a list of objects containing information about the errors to the debug log. After implementing the interface, you retrieve the error information by publishing an instance of that implementation to the editing context. + +### Implement the IValidationErrorService Interface + +1. Here is a code sample for a simple implementation that will write out the validation errors to the debug log. + + ```csharp + using System.Activities.Presentation.Validation; + using System.Collections.Generic; + using System.Diagnostics; + using System.Linq; + + namespace VariableFinderShell + { + class DebugValidationErrorService : IValidationErrorService + { + public void ShowValidationErrors(IList errors) + { + errors.ToList().ForEach(vei => Debug.WriteLine($"Error: {vei.Message}")); + } + } + } + ``` + +### Publishing to the Editing Context + +1. Here is the code that will publish this to the editing context. + + ```csharp + wd.Context.Services.Publish(new DebugValidationErrorService()); ``` diff --git a/docs/framework/windows-workflow-foundation/how-to-enable-persistence-for-workflows-and-workflow-services.md b/docs/framework/windows-workflow-foundation/how-to-enable-persistence-for-workflows-and-workflow-services.md index 82ce134065fbb..4fc3efa731ad1 100644 --- a/docs/framework/windows-workflow-foundation/how-to-enable-persistence-for-workflows-and-workflow-services.md +++ b/docs/framework/windows-workflow-foundation/how-to-enable-persistence-for-workflows-and-workflow-services.md @@ -9,7 +9,7 @@ This article describes how to enable persistence for workflows and workflow serv ## Enable persistence for workflows -You can associate an instance store with a **WorkflowApplication** by using the property of the class. The method saves or persists a workflow into the instance store associated with the application. The method persists a workflow into the instance store and then unloads the instance from the memory. The **Load** method loads a workflow into memory using the workflow data stored in the instance persistence store. +You can associate an instance store with a **WorkflowApplication** by using the property of the class. The method saves or persists a workflow into the instance store associated with the application. The method persists a workflow into the instance store and then unloads the instance from the memory. The **Load** method loads a workflow into memory using the workflow data stored in the instance persistence store. The **Persist** method performs the following steps: diff --git a/docs/framework/windows-workflow-foundation/how-to-enable-sql-persistence-for-workflows-and-workflow-services.md b/docs/framework/windows-workflow-foundation/how-to-enable-sql-persistence-for-workflows-and-workflow-services.md index 4bd152e7d7032..7ae0b95a95423 100644 --- a/docs/framework/windows-workflow-foundation/how-to-enable-sql-persistence-for-workflows-and-workflow-services.md +++ b/docs/framework/windows-workflow-foundation/how-to-enable-sql-persistence-for-workflows-and-workflow-services.md @@ -37,7 +37,7 @@ You can enable persistence for self-hosted workflows that use and assign it to the of the as shown in the following code example. +3. Construct a and assign it to the of the as shown in the following code example. ```csharp SqlWorkflowInstanceStore store = @@ -52,7 +52,7 @@ You can enable persistence for self-hosted workflows that use [!NOTE] > Depending on your edition of SQL Server, the connection string server name may be different. -4. Invoke the method on the object to persist a workflow, or method to persist and unload a workflow. You can also handle the event raised by the object and return appropriate ( or ) member of . +4. Invoke the method on the object to persist a workflow, or method to persist and unload a workflow. You can also handle the event raised by the object and return appropriate ( or ) member of . ```csharp wfApp.PersistableIdle = delegate(WorkflowApplicationIdleEventArgs e) @@ -66,7 +66,7 @@ You can enable persistence for self-hosted workflows that use programmatically by using the class or the class. +You can enable persistence for self-hosted workflow services that use programmatically by using the class or the class. ### Use the SqlWorkflowInstanceStoreBehavior class @@ -107,7 +107,7 @@ The following procedure contains steps to use the property of the `WorkflowServiceHost` without using the `SqlWorkflowInstanceStoreBehavior` class as shown in the following code example. +When the `SqlWorkflowInstanceStoreBehavior` is applied, the `DurableInstancingOptions.InstanceStore` on the `WorkflowServiceHost` is set to the `SqlWorkflowInstanceStore` object created using the configuration values. You can do the same programmatically to set the property of the `WorkflowServiceHost` without using the `SqlWorkflowInstanceStoreBehavior` class as shown in the following code example. ```csharp workflowServiceHost.DurableInstancingOptions.InstanceStore = sqlInstanceStoreObject; diff --git a/docs/framework/windows-workflow-foundation/how-to-run-a-workflow.md b/docs/framework/windows-workflow-foundation/how-to-run-a-workflow.md index fb31a92a3a555..39417c1c0995d 100644 --- a/docs/framework/windows-workflow-foundation/how-to-run-a-workflow.md +++ b/docs/framework/windows-workflow-foundation/how-to-run-a-workflow.md @@ -75,7 +75,7 @@ This topic is a continuation of the Windows Workflow Foundation Getting Started [!code-csharp[CFX_WF_GettingStarted#4](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_wf_gettingstarted/cs/extrasnippets.cs#4)] [!code-vb[CFX_WF_GettingStarted#4](~/samples/snippets/visualbasic/VS_Snippets_CFX/cfx_wf_gettingstarted/vb/extrasnippets.vb#4)] - This code creates a , subscribes to three workflow life-cycle events, starts the workflow with a call to , and then waits for the workflow to complete. When the workflow completes, the is set and the host application completes. + This code creates a , subscribes to three workflow life-cycle events, starts the workflow with a call to , and then waits for the workflow to complete. When the workflow completes, the is set and the host application completes. ### To set input arguments of a workflow @@ -108,7 +108,7 @@ This topic is a continuation of the Windows Workflow Foundation Getting Started [!code-csharp[CFX_WF_GettingStarted#8](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_wf_gettingstarted/cs/program.cs#8)] [!code-vb[CFX_WF_GettingStarted#8](~/samples/snippets/visualbasic/VS_Snippets_CFX/cfx_wf_gettingstarted/vb/module1.vb#8)] -2. Add the following handler just below the existing three workflow life-cycle handlers in `Main`. +2. Add the following handler just below the existing three workflow life-cycle handlers in `Main`. [!code-csharp[CFX_WF_GettingStarted#9](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_wf_gettingstarted/cs/program.cs#9)] [!code-vb[CFX_WF_GettingStarted#9](~/samples/snippets/visualbasic/VS_Snippets_CFX/cfx_wf_gettingstarted/vb/module1.vb#9)] @@ -116,7 +116,7 @@ This topic is a continuation of the Windows Workflow Foundation Getting Started Each time the workflow becomes idle waiting for the next guess, this handler is called and the `idleAction` is set. The code in the following step uses `idleEvent` and `syncEvent` to determine whether the workflow is waiting for the next guess or is complete. > [!NOTE] - > In this example, the host application uses auto-reset events in the and handlers to synchronize the host application with the progress of the workflow. It is not necessary to block and wait for the workflow to become idle before resuming a bookmark, but in this example the synchronization events are required so the host knows whether the workflow is complete or whether it is waiting on more user input by using the . For more information, see [Bookmarks](bookmarks.md). + > In this example, the host application uses auto-reset events in the and handlers to synchronize the host application with the progress of the workflow. It is not necessary to block and wait for the workflow to become idle before resuming a bookmark, but in this example the synchronization events are required so the host knows whether the workflow is complete or whether it is waiting on more user input by using the . For more information, see [Bookmarks](bookmarks.md). 3. Remove the call to `WaitOne`, and replace it with code to gather input from the user and resume the . diff --git a/docs/framework/windows-workflow-foundation/imperative-code-based-validation.md b/docs/framework/windows-workflow-foundation/imperative-code-based-validation.md index 3c9a0ada21a40..244dc421339c7 100644 --- a/docs/framework/windows-workflow-foundation/imperative-code-based-validation.md +++ b/docs/framework/windows-workflow-foundation/imperative-code-based-validation.md @@ -10,10 +10,10 @@ Imperative code-based validation provides a simple way for an activity to provid ## Using Code-Based Validation -Code-based validation is supported by activities that derive from , , and . Validation code can be placed in the override, and validation errors or warnings can be added to the metadata argument. In the following example, if the `Cost` is greater than the `Price`, a validation error is added to the metadata. +Code-based validation is supported by activities that derive from , , and . Validation code can be placed in the override, and validation errors or warnings can be added to the metadata argument. In the following example, if the `Cost` is greater than the `Price`, a validation error is added to the metadata. > [!NOTE] -> Note that `Cost` and `Price` are not arguments to the activity, but are properties that are set at design time. That is why their values can be validated in the override. The value of the data flowing through an argument cannot be validated at design time because the data does not flow until runtime, but activity arguments can be validated to ensure that they are bound by using the `RequiredArgument` attribute and overload groups. This example code sees the `RequiredArgument` attribute for the `Description` argument, and if it is not bound then a validation error is generated. Required arguments are covered in [Required Arguments and Overload Groups](required-arguments-and-overload-groups.md). +> Note that `Cost` and `Price` are not arguments to the activity, but are properties that are set at design time. That is why their values can be validated in the override. The value of the data flowing through an argument cannot be validated at design time because the data does not flow until runtime, but activity arguments can be validated to ensure that they are bound by using the `RequiredArgument` attribute and overload groups. This example code sees the `RequiredArgument` attribute for the `Description` argument, and if it is not bound then a validation error is generated. Required arguments are covered in [Required Arguments and Overload Groups](required-arguments-and-overload-groups.md). ```csharp public sealed class CreateProduct : CodeActivity @@ -44,10 +44,10 @@ public sealed class CreateProduct : CodeActivity } ``` - By default, a validation error is added to the metadata when is called. To add a validation warning, use the overload that takes a , and specify that the represents a warning by setting the property. + By default, a validation error is added to the metadata when is called. To add a validation warning, use the overload that takes a , and specify that the represents a warning by setting the property. Validation occurs when a workflow is modified in the workflow designer and any validation errors or warnings are displayed in the workflow designer. Validation also occurs at runtime when a workflow is invoked and if any validation errors occur, an is thrown by the default validation logic. For more information about invoking validation and accessing any validation warnings or errors, see [Invoking Activity Validation](invoking-activity-validation.md). - Any exceptions that are thrown from are not treated as validation errors. These exceptions will escape from the call to and must be handled by the caller. + Any exceptions that are thrown from are not treated as validation errors. These exceptions will escape from the call to and must be handled by the caller. Code-based validation is useful for validating the activity that contains the code, but it does not have visibility into the other activities in the workflow. Declarative constraints validation provides the ability to validate the relationships between an activity and other activities in the workflow, and is covered in the [Declarative Constraints](declarative-constraints.md) topic. diff --git a/docs/framework/windows-workflow-foundation/instance-locked-exception-action.md b/docs/framework/windows-workflow-foundation/instance-locked-exception-action.md index fc5e985b8893c..d740130fb312a 100644 --- a/docs/framework/windows-workflow-foundation/instance-locked-exception-action.md +++ b/docs/framework/windows-workflow-foundation/instance-locked-exception-action.md @@ -6,18 +6,18 @@ ms.topic: "reference" --- # Instance Locked Exception Action -The property of the SQL Workflow Instance Store lets you specify what action the SQL persistence provider should take when it receives an . The persistence provider receives this exception when it tries to lock a workflow service instance that is currently locked by another service host. The values for this property are , , and . The default value is . The following list describes the three options: - -- . The service host does not attempt to lock the workflow service instance and passes the to the caller. If your workflow stays in memory for a period exceeding 60 seconds, use as the retry. The default value is . - -- . The service host reattempts to lock the workflow service instance with a linear interval between retry attempts and passes the to the caller at the end of the sequence. If you workflow stays in memory approximately between 5-60 seconds, and messages arrive in batches where it is more likely for messages being sent to the same instance on the same host to process all messages before unloading the workflow, use to achieve the best latency without wasting resources. - -- . The service host reattempts to lock the workflow service instance with an exponential backoff interval between retry attempts, and passes the exception to the caller at the end of the sequence. If your workflow stays in memory for a very short time (less than 5 seconds), or a Web farm is large and the chance of another message being delivered to the same host is not very high, use to achieve the best latency. - - The Instance Locked Exception Action feature supports the following scenarios. In all scenarios, if the instanceLockedExceptionAction property of the SqlWorkflowInstanceStore is set to or , the host transparently retries to acquire the lock on instances periodically. - -1. **Enabling graceful shutdown and overlapped recycling of application domains.** Suppose an **AppDomain** with a service host running workflow service instances is being recycled and a new **AppDomain** is brought up to handle new requests in parallel while the old **AppDomain** is brought down gracefully. The shutdown waits until workflow service instances are idle, and then persists and unloads the instances. Any attempts by hosts in the new **AppDomain** to lock an instance will cause an . - -2. **Horizontally scaling durable workflows across a homogeneous farm of servers.** Suppose a node of a server farm on which a workflow instance is running crashes and the workflow host cannot remove locks on the instance it is running. When a service host running on another node of the farm receives a message for that workflow instance, it tries to acquire locks on these instances it will receive the . The locks will expire after some time because the host that was supposed to renew the lock no longer exists. - +The property of the SQL Workflow Instance Store lets you specify what action the SQL persistence provider should take when it receives an . The persistence provider receives this exception when it tries to lock a workflow service instance that is currently locked by another service host. The values for this property are , , and . The default value is . The following list describes the three options: + +- . The service host does not attempt to lock the workflow service instance and passes the to the caller. If your workflow stays in memory for a period exceeding 60 seconds, use as the retry. The default value is . + +- . The service host reattempts to lock the workflow service instance with a linear interval between retry attempts and passes the to the caller at the end of the sequence. If you workflow stays in memory approximately between 5-60 seconds, and messages arrive in batches where it is more likely for messages being sent to the same instance on the same host to process all messages before unloading the workflow, use to achieve the best latency without wasting resources. + +- . The service host reattempts to lock the workflow service instance with an exponential backoff interval between retry attempts, and passes the exception to the caller at the end of the sequence. If your workflow stays in memory for a very short time (less than 5 seconds), or a Web farm is large and the chance of another message being delivered to the same host is not very high, use to achieve the best latency. + + The Instance Locked Exception Action feature supports the following scenarios. In all scenarios, if the instanceLockedExceptionAction property of the SqlWorkflowInstanceStore is set to or , the host transparently retries to acquire the lock on instances periodically. + +1. **Enabling graceful shutdown and overlapped recycling of application domains.** Suppose an **AppDomain** with a service host running workflow service instances is being recycled and a new **AppDomain** is brought up to handle new requests in parallel while the old **AppDomain** is brought down gracefully. The shutdown waits until workflow service instances are idle, and then persists and unloads the instances. Any attempts by hosts in the new **AppDomain** to lock an instance will cause an . + +2. **Horizontally scaling durable workflows across a homogeneous farm of servers.** Suppose a node of a server farm on which a workflow instance is running crashes and the workflow host cannot remove locks on the instance it is running. When a service host running on another node of the farm receives a message for that workflow instance, it tries to acquire locks on these instances it will receive the . The locks will expire after some time because the host that was supposed to renew the lock no longer exists. + **Horizontally scaling durable workflows across a homogeneous farm of servers.** Suppose you want to horizontally scale a durable workflow using multiple hosts behind a NLB (Network Load Balancer), the workflow host running on one node of the farm loads a workflow instance and is processing a message, and the next message to the instance is routed to the host that is running on another node because the NLB does not have routing algorithm to deliver messages to the host that is already running the instance. Upon receiving the message, the second host attempts to load the workflow instance and receives the because the first host has a lock on the instance. The first host unlocks the instance when it is finished with processing the first message and the second host acquires the lock when it retries the next time, loads the instance, and processes the second message. diff --git a/docs/framework/windows-workflow-foundation/instance-stores.md b/docs/framework/windows-workflow-foundation/instance-stores.md index c9d65d1ed6f56..086303b5a6de7 100644 --- a/docs/framework/windows-workflow-foundation/instance-stores.md +++ b/docs/framework/windows-workflow-foundation/instance-stores.md @@ -6,22 +6,22 @@ ms.assetid: f2629668-0923-4987-b943-67477131c1e0 --- # Instance Stores -An instance store is a logical container of instances. It is the place where the instance data and metadata is stored. An instance store does not imply dedicated physical storage. An instance store could contain durable information in a SQL Server database or non-durable state information in a memory. The [!INCLUDE[netfx_current_long](../../../includes/netfx-current-long-md.md)] ships with the SQL Workflow Instance Store, which is a concrete implementation of an instance store that allows workflows to persist instance data and metadata into a SQL Server 2005 or SQL Server 2008 database. In addition Windows Server App Fabric also provides a concrete implementation of an instance store. For more information, see [Windows Server App Fabric Instance Store, Query, and Control Providers](/previous-versions/appfabric/ff383417(v=azure.10)). - - The persistence API is the interface between a host and an instance store that allows the host to send command requests (for example, and ) to the instance store. The concrete implementation of this API is called a persistence provider. The persistence provider receives requests from a host and modifies the instance store. - - Hosts and instance stores are pluggable so that a host can be used with many instance stores, and an instance store can be used with many hosts. An instance store is typically optimized for the usage patterns of a particular host, although the instance store and host may evolve on independent life cycles. For example, the **WorkflowServiceHost** and the **SqlWorkflowInstanceStore** are designed to work well together. You can create your own instance store to persist data and metadata of workflow service instances and use that instance store with the **WorkflowServiceHost**. For example, you can create an OracleWorkflowInstanceStore that lets workflows persist information into an Oracle database instead of saving them into a SQL Server database. - - It is common for hosts to be extended with additional functionality that modifies the persisted objects. For example, an instance persistence system may have a workflow host, an extension that supports the "Suspend" operation, and an SQL instance store. The workflow host might send a standard command such as Save or Load to save or load a workflow from an instance store or to save a workflow into an instance store. The suspend extension might add additional semantics to the commands for saving and loading workflow instances so that a suspended workflow instance cannot be loaded. The persistence provider for the SQL instance store understands the commands for saving and loading workflow instances, and implements the commands by calling appropriate stored procedures that change the tables of persistent objects in an SQL Server database. - - A host acts as an instance owner within an instance store. A host may act as more than one instance owner with more than one instance store at the same time. The host provides GUIDs for instance keys associated with the instances. An instance key is a unique alias that identifies an instance. The persistence system creates, updates, and deletes instance owner information as it executes commands requested by hosts. - - The following list contains the important steps involved in the host’s interaction with the instance store: - -1. Obtain an **InstanceStore** from a persistence provider. - -2. Obtain the handle to an instance by calling the method on the **InstanceStore**. - -3. Invoke commands against the instance handle by calling the method on the **InstanceStore**. - +An instance store is a logical container of instances. It is the place where the instance data and metadata is stored. An instance store does not imply dedicated physical storage. An instance store could contain durable information in a SQL Server database or non-durable state information in a memory. The [!INCLUDE[netfx_current_long](../../../includes/netfx-current-long-md.md)] ships with the SQL Workflow Instance Store, which is a concrete implementation of an instance store that allows workflows to persist instance data and metadata into a SQL Server 2005 or SQL Server 2008 database. In addition Windows Server App Fabric also provides a concrete implementation of an instance store. For more information, see [Windows Server App Fabric Instance Store, Query, and Control Providers](/previous-versions/appfabric/ff383417(v=azure.10)). + + The persistence API is the interface between a host and an instance store that allows the host to send command requests (for example, and ) to the instance store. The concrete implementation of this API is called a persistence provider. The persistence provider receives requests from a host and modifies the instance store. + + Hosts and instance stores are pluggable so that a host can be used with many instance stores, and an instance store can be used with many hosts. An instance store is typically optimized for the usage patterns of a particular host, although the instance store and host may evolve on independent life cycles. For example, the **WorkflowServiceHost** and the **SqlWorkflowInstanceStore** are designed to work well together. You can create your own instance store to persist data and metadata of workflow service instances and use that instance store with the **WorkflowServiceHost**. For example, you can create an OracleWorkflowInstanceStore that lets workflows persist information into an Oracle database instead of saving them into a SQL Server database. + + It is common for hosts to be extended with additional functionality that modifies the persisted objects. For example, an instance persistence system may have a workflow host, an extension that supports the "Suspend" operation, and an SQL instance store. The workflow host might send a standard command such as Save or Load to save or load a workflow from an instance store or to save a workflow into an instance store. The suspend extension might add additional semantics to the commands for saving and loading workflow instances so that a suspended workflow instance cannot be loaded. The persistence provider for the SQL instance store understands the commands for saving and loading workflow instances, and implements the commands by calling appropriate stored procedures that change the tables of persistent objects in an SQL Server database. + + A host acts as an instance owner within an instance store. A host may act as more than one instance owner with more than one instance store at the same time. The host provides GUIDs for instance keys associated with the instances. An instance key is a unique alias that identifies an instance. The persistence system creates, updates, and deletes instance owner information as it executes commands requested by hosts. + + The following list contains the important steps involved in the host’s interaction with the instance store: + +1. Obtain an **InstanceStore** from a persistence provider. + +2. Obtain the handle to an instance by calling the method on the **InstanceStore**. + +3. Invoke commands against the instance handle by calling the method on the **InstanceStore**. + 4. Examine the returned by **InstanceStore.Execute** to determine the results of the commands. diff --git a/docs/framework/windows-workflow-foundation/invoking-activity-validation.md b/docs/framework/windows-workflow-foundation/invoking-activity-validation.md index 3397329666b9c..270625b3e45a7 100644 --- a/docs/framework/windows-workflow-foundation/invoking-activity-validation.md +++ b/docs/framework/windows-workflow-foundation/invoking-activity-validation.md @@ -10,7 +10,7 @@ Activity validation provides a method to identify and report errors in any activ ## Using ActivityValidationServices - has two overloads that are used to invoke an activity's validation logic. The first overload takes the root activity to be validated and returns a collection of validation errors and warnings. In the following example, a custom `Add` activity is used that has two required arguments. + has two overloads that are used to invoke an activity's validation logic. The first overload takes the root activity to be validated and returns a collection of validation errors and warnings. In the following example, a custom `Add` activity is used that has two required arguments. ```csharp public sealed class Add : CodeActivity @@ -49,7 +49,7 @@ Activity wf = new Sequence }; ``` - This workflow can be validated by calling . returns a collection of any validation errors or warnings contained by the activity and any children, as shown in the following example. + This workflow can be validated by calling . returns a collection of any validation errors or warnings contained by the activity and any children, as shown in the following example. ```csharp ValidationResults results = ActivityValidationServices.Validate(wf); @@ -71,7 +71,7 @@ else } ``` - When is called on this sample workflow, two validation errors are returned. + When is called on this sample workflow, two validation errors are returned. **Error: Value for a required activity argument 'Operand2' was not supplied.** **Error: Value for a required activity argument 'Operand1' was not supplied.** If this workflow was invoked, an would be thrown, as shown in the following example. @@ -90,7 +90,7 @@ catch (Exception ex) **System.Activities.InvalidWorkflowException:** **The following errors were encountered while processing the workflow tree:** **'Add': Value for a required activity argument 'Operand2' was not supplied.** -**'Add': Value for a required activity argument 'Operand1' was not supplied.** For this example workflow to be valid, the two required arguments of the `Add` activity must be bound. In the following example, the two required arguments are bound to workflow variables along with the result value. In this example the argument is bound along with the two required arguments. The argument is not required to be bound and does not cause a validation error if it is not. It is the responsibility of the workflow author to bind if its value is used elsewhere in the workflow. +**'Add': Value for a required activity argument 'Operand1' was not supplied.** For this example workflow to be valid, the two required arguments of the `Add` activity must be bound. In the following example, the two required arguments are bound to workflow variables along with the result value. In this example the argument is bound along with the two required arguments. The argument is not required to be bound and does not cause a validation error if it is not. It is the responsibility of the workflow author to bind if its value is used elsewhere in the workflow. ```csharp new Add @@ -156,7 +156,7 @@ catch (Exception ex) ### Invoking Imperative Code-Based Validation -Imperative code-based validation provides a simple way for an activity to provide validation about itself, and is available for activities that derive from , , and . Validation code that determines any validation errors or warnings is added to the activity. When validation is invoked on the activity, these warnings or errors are contained in the collection returned by the call to . In the following example, a `CreateProduct` activity is defined. If the `Cost` is greater than the `Price`, a validation error is added to the metadata in the override. +Imperative code-based validation provides a simple way for an activity to provide validation about itself, and is available for activities that derive from , , and . Validation code that determines any validation errors or warnings is added to the activity. When validation is invoked on the activity, these warnings or errors are contained in the collection returned by the call to . In the following example, a `CreateProduct` activity is defined. If the `Cost` is greater than the `Price`, a validation error is added to the metadata in the override. ```csharp public sealed class CreateProduct : CodeActivity @@ -229,13 +229,13 @@ else **Error: The Cost must be less than or equal to the Price.** **Error: Value for a required activity argument 'Description' was not supplied.** > [!NOTE] -> Custom activity authors can provide validation logic in an activity's override. Any exceptions that are thrown from are not treated as validation errors. These exceptions will escape from the call to and must be handled by the caller. +> Custom activity authors can provide validation logic in an activity's override. Any exceptions that are thrown from are not treated as validation errors. These exceptions will escape from the call to and must be handled by the caller. ## Using ValidationSettings - By default, all activities in the activity tree are evaluated when validation is invoked by . allows the validation to be customized in several different ways by configuring its three properties. specifies whether the validator should walk the entire activity tree or only apply validation logic to the supplied activity. The default for this value is `false`. specifies additional constraint mapping from a type to a list of constraints. For the base type of each activity in the activity tree being validated there is a lookup into . If a matching constraint list is found, all constraints in the list are evaluated for the activity. specifies whether the validator should evaluate all constraints or only those specified in . The default value is `false`. and are useful for workflow host authors to add additional validation for workflows, such as policy constraints for tools such as FxCop. For more information about constraints, see [Declarative Constraints](declarative-constraints.md). + By default, all activities in the activity tree are evaluated when validation is invoked by . allows the validation to be customized in several different ways by configuring its three properties. specifies whether the validator should walk the entire activity tree or only apply validation logic to the supplied activity. The default for this value is `false`. specifies additional constraint mapping from a type to a list of constraints. For the base type of each activity in the activity tree being validated there is a lookup into . If a matching constraint list is found, all constraints in the list are evaluated for the activity. specifies whether the validator should evaluate all constraints or only those specified in . The default value is `false`. and are useful for workflow host authors to add additional validation for workflows, such as policy constraints for tools such as FxCop. For more information about constraints, see [Declarative Constraints](declarative-constraints.md). - To use , configure the desired properties, and then pass it in the call to . In this example, a workflow that consists of a with a custom `Add` activity is validated. The `Add` activity has two required arguments. + To use , configure the desired properties, and then pass it in the call to . In this example, a workflow that consists of a with a custom `Add` activity is validated. The `Add` activity has two required arguments. ```csharp public sealed class Add : CodeActivity @@ -274,7 +274,7 @@ Activity wf = new Sequence }; ``` - For the following example, validation is performed with set to `true`, so only the root activity is validated. + For the following example, validation is performed with set to `true`, so only the root activity is validated. ```csharp ValidationSettings settings = new ValidationSettings diff --git a/docs/framework/windows-workflow-foundation/modeling-cancellation-behavior-in-workflows.md b/docs/framework/windows-workflow-foundation/modeling-cancellation-behavior-in-workflows.md index c90e462817828..ae8891a10613c 100644 --- a/docs/framework/windows-workflow-foundation/modeling-cancellation-behavior-in-workflows.md +++ b/docs/framework/windows-workflow-foundation/modeling-cancellation-behavior-in-workflows.md @@ -6,107 +6,107 @@ ms.assetid: d48f6cf3-cdde-4dd3-8265-a665acf32a03 --- # Modeling Cancellation Behavior in Workflows -Activities can be canceled inside a workflow, for example by a activity canceling incomplete branches when its evaluates to `true`, or from outside the workflow, if the host calls . To provide cancellation handling, workflow authors can use the activity, the activity, or create custom activities that provide cancellation logic. This topic provides an overview of cancellation in workflows. - -## Cancellation, Compensation, and Transactions +Activities can be canceled inside a workflow, for example by a activity canceling incomplete branches when its evaluates to `true`, or from outside the workflow, if the host calls . To provide cancellation handling, workflow authors can use the activity, the activity, or create custom activities that provide cancellation logic. This topic provides an overview of cancellation in workflows. + +## Cancellation, Compensation, and Transactions + + Transactions give your application the ability to abort (roll back) all changes executed within the transaction if any errors occur during any part of the transaction process. However, not all work that may need to be canceled or undone is appropriate for transactions, such as long-running work or work that does not involve transactional resources. Compensation provides a model for undoing previously completed non-transactional work if there is a subsequent failure in the workflow. Cancellation provides a model for workflow and activity authors to handle non-transactional work that was not completed. If an activity has not completed its execution and it is canceled, its cancellation logic will be invoked if it is available. - Transactions give your application the ability to abort (roll back) all changes executed within the transaction if any errors occur during any part of the transaction process. However, not all work that may need to be canceled or undone is appropriate for transactions, such as long-running work or work that does not involve transactional resources. Compensation provides a model for undoing previously completed non-transactional work if there is a subsequent failure in the workflow. Cancellation provides a model for workflow and activity authors to handle non-transactional work that was not completed. If an activity has not completed its execution and it is canceled, its cancellation logic will be invoked if it is available. - > [!NOTE] -> For more information about transactions and compensation, see [Transactions](workflow-transactions.md) and [Compensation](compensation.md). - -## Using CancellationScope - - The activity has two sections that can contain child activities: and . The is where the activities that make up the logic of the activity are placed, and the is where the activities that provide cancellation logic for the activity are placed. An activity can be canceled only if it has not completed. In the case of the activity, completion refers to the completion of the activities in the . If a cancellation request is scheduled and the activities in the have not completed, then the will be marked as and the activities will be executed. - -### Canceling a Workflow from the Host - - A host can cancel a workflow by calling the method of the instance that is hosting the workflow. In the following example a workflow is created that has a . The workflow is invoked, and then the host makes a call to . The main execution of the workflow is stopped, the of the is invoked, and then the workflow completes with a status of . - - [!code-csharp[CFX_WorkflowApplicationExample#35](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#35)] - - When this workflow is invoked, the following output is displayed to the console. - - **Starting the workflow.** +> For more information about transactions and compensation, see [Transactions](workflow-transactions.md) and [Compensation](compensation.md). + +## Using CancellationScope + + The activity has two sections that can contain child activities: and . The is where the activities that make up the logic of the activity are placed, and the is where the activities that provide cancellation logic for the activity are placed. An activity can be canceled only if it has not completed. In the case of the activity, completion refers to the completion of the activities in the . If a cancellation request is scheduled and the activities in the have not completed, then the will be marked as and the activities will be executed. + +### Canceling a Workflow from the Host + + A host can cancel a workflow by calling the method of the instance that is hosting the workflow. In the following example a workflow is created that has a . The workflow is invoked, and then the host makes a call to . The main execution of the workflow is stopped, the of the is invoked, and then the workflow completes with a status of . + + [!code-csharp[CFX_WorkflowApplicationExample#35](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#35)] + + When this workflow is invoked, the following output is displayed to the console. + + **Starting the workflow.** **CancellationHandler invoked.** **Workflow b30ebb30-df46-4d90-a211-e31c38d8db3c Canceled.** > [!NOTE] -> When a activity is canceled and the invoked, it is the responsibility of the workflow author to determine the progress that the canceled activity made before it was canceled in order to provide the appropriate cancellation logic. The does not provide any information about the progress of the canceled activity. - - A workflow can also be canceled from the host if an unhandled exception bubbles up past the root of the workflow and the handler returns . In this example the workflow starts and then throws an . This exception is unhandled by the workflow and so the handler is invoked. The handler instructs the runtime to cancel the workflow, and the of the currently executing activity is invoked. - - [!code-csharp[CFX_WorkflowApplicationExample#36](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#36)] - - When this workflow is invoked, the following output is displayed to the console. - - **Starting the workflow.** +> When a activity is canceled and the invoked, it is the responsibility of the workflow author to determine the progress that the canceled activity made before it was canceled in order to provide the appropriate cancellation logic. The does not provide any information about the progress of the canceled activity. + + A workflow can also be canceled from the host if an unhandled exception bubbles up past the root of the workflow and the handler returns . In this example the workflow starts and then throws an . This exception is unhandled by the workflow and so the handler is invoked. The handler instructs the runtime to cancel the workflow, and the of the currently executing activity is invoked. + + [!code-csharp[CFX_WorkflowApplicationExample#36](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#36)] + + When this workflow is invoked, the following output is displayed to the console. + + **Starting the workflow.** **OnUnhandledException in Workflow 6bb2d5d6-f49a-4c6d-a988-478afb86dbe9** **An ApplicationException was thrown.** **CancellationHandler invoked.** **Workflow 6bb2d5d6-f49a-4c6d-a988-478afb86dbe9 Canceled.** -### Canceling an Activity from Inside a Workflow +### Canceling an Activity from Inside a Workflow - An activity can also be canceled by its parent. For example, if a activity has multiple executing branches and its evaluates to `true` then its incomplete branches will be canceled. In this example a activity is created that has two branches. Its is set to `true` so the completes as soon as any one of its branches is completed. In this example branch 2 completes, and so branch 1 is canceled. - - [!code-csharp[CFX_WorkflowApplicationExample#37](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#37)] - - When this workflow is invoked, the following output is displayed to the console. - - **Branch 1 starting.** + An activity can also be canceled by its parent. For example, if a activity has multiple executing branches and its evaluates to `true` then its incomplete branches will be canceled. In this example a activity is created that has two branches. Its is set to `true` so the completes as soon as any one of its branches is completed. In this example branch 2 completes, and so branch 1 is canceled. + + [!code-csharp[CFX_WorkflowApplicationExample#37](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#37)] + + When this workflow is invoked, the following output is displayed to the console. + + **Branch 1 starting.** **Branch 2 complete.** **Branch 1 canceled.** -**Workflow e0685e24-18ef-4a47-acf3-5c638732f3be Completed.** Activities are also canceled if an exception bubbles up past the root of the activity but is handled at a higher level in the workflow. In this example, the main logic of the workflow consists of a activity. The is specified as the of a activity which is contained by a activity. An exception is thrown from the body of the , is handled by the parent activity, and the is canceled. - - [!code-csharp[CFX_WorkflowApplicationExample#39](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#39)] - - When this workflow is invoked, the following output is displayed to the console. - - **Sequence starting.** +**Workflow e0685e24-18ef-4a47-acf3-5c638732f3be Completed.** Activities are also canceled if an exception bubbles up past the root of the activity but is handled at a higher level in the workflow. In this example, the main logic of the workflow consists of a activity. The is specified as the of a activity which is contained by a activity. An exception is thrown from the body of the , is handled by the parent activity, and the is canceled. + + [!code-csharp[CFX_WorkflowApplicationExample#39](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#39)] + + When this workflow is invoked, the following output is displayed to the console. + + **Sequence starting.** **Sequence canceled.** **Exception caught.** **Workflow e3c18939-121e-4c43-af1c-ba1ce977ce55 Completed.** -### Throwing Exceptions from a CancellationHandler - - Any exceptions thrown from the of a are fatal to the workflow. If there is a possibility of exceptions escaping from a , use a in the to catch and handle these exceptions. - -### Cancellation using CompensableActivity - - Like the activity, the has a . If a is canceled, any activities in its are invoked. This can be useful for undoing partially completed compensable work. For information about how to use for compensation and cancellation, see [Compensation](compensation.md). - -## Cancellation using Custom Activities - - Custom activity authors can implement cancellation logic into their custom activities in several different ways. Custom activities that derive from can implement cancellation logic by placing a or other custom activity that contains cancellation logic in the body of the activity. and derived activities can override their respective method and provide cancellation logic there. derived activities do not provide any provision for cancellation because all their work is performed in a single burst of execution when the runtime calls the method. If the execute method has not yet been called and a based activity is canceled, the activity closes with a status of and the method is not called. - -### Cancellation using NativeActivity - - derived activities can override the method to provide custom cancellation logic. If this method is not overridden, then the default workflow cancellation logic is applied. Default cancellation is the process that occurs for a that does not override the method or whose method calls the base method. When an activity is canceled, the runtime flags the activity for cancellation and automatically handles certain cleanup. If the activity only has outstanding bookmarks, the bookmarks will be removed and the activity will be marked as . Any outstanding child activities of the canceled activity will in turn be canceled. Any attempt to schedule additional child activities will result in the attempt being ignored and the activity will be marked as . If any outstanding child activity completes in the or state, then the activity will be marked as . Note that a cancellation request can be ignored. If an activity does not have any outstanding bookmarks or executing child activities and does not schedule any additional work items after being flagged for cancellation, it will complete successfully. This default cancellation suffices for many scenarios, but if additional cancellation logic is needed, then the built-in cancellation activities or custom activities can be used. - - In the following example, the override of a based custom `ParallelForEach` activity is defined. When the activity is canceled, this override handles the cancellation logic for the activity. This example is part of the [Non-Generic ParallelForEach](./samples/non-generic-parallelforeach.md) sample. - -```csharp -protected override void Cancel(NativeActivityContext context) -{ - // If we do not have a completion condition then we can just - // use default logic. - if (this.CompletionCondition == null) - { - base.Cancel(context); - } - else - { - context.CancelChildren(); - } -} -``` - - derived activities can determine if cancellation has been requested by inspecting the property, and mark themselves as canceled by calling the method. Calling does not immediately complete the activity. As usual, the runtime will complete the activity when it has no more outstanding work, but if is called the final state will be instead of . - -### Cancellation using AsyncCodeActivity - - based activities can also provide custom cancellation logic by overriding the method. If this method is not overridden, then no cancellation handling is performed if the activity is canceled. In the following example, the override of an based custom `ExecutePowerShell` activity is defined. When the activity is canceled, it performs the desired cancellation behavior. - - [!code-csharp[CFX_WorkflowApplicationExample#1020](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#1020)] - - derived activities can determine if cancellation has been requested by inspecting the property, and mark themselves as canceled by calling the method. +### Throwing Exceptions from a CancellationHandler + + Any exceptions thrown from the of a are fatal to the workflow. If there is a possibility of exceptions escaping from a , use a in the to catch and handle these exceptions. + +### Cancellation using CompensableActivity + + Like the activity, the has a . If a is canceled, any activities in its are invoked. This can be useful for undoing partially completed compensable work. For information about how to use for compensation and cancellation, see [Compensation](compensation.md). + +## Cancellation using Custom Activities + + Custom activity authors can implement cancellation logic into their custom activities in several different ways. Custom activities that derive from can implement cancellation logic by placing a or other custom activity that contains cancellation logic in the body of the activity. and derived activities can override their respective method and provide cancellation logic there. derived activities do not provide any provision for cancellation because all their work is performed in a single burst of execution when the runtime calls the method. If the execute method has not yet been called and a based activity is canceled, the activity closes with a status of and the method is not called. + +### Cancellation using NativeActivity + + derived activities can override the method to provide custom cancellation logic. If this method is not overridden, then the default workflow cancellation logic is applied. Default cancellation is the process that occurs for a that does not override the method or whose method calls the base method. When an activity is canceled, the runtime flags the activity for cancellation and automatically handles certain cleanup. If the activity only has outstanding bookmarks, the bookmarks will be removed and the activity will be marked as . Any outstanding child activities of the canceled activity will in turn be canceled. Any attempt to schedule additional child activities will result in the attempt being ignored and the activity will be marked as . If any outstanding child activity completes in the or state, then the activity will be marked as . Note that a cancellation request can be ignored. If an activity does not have any outstanding bookmarks or executing child activities and does not schedule any additional work items after being flagged for cancellation, it will complete successfully. This default cancellation suffices for many scenarios, but if additional cancellation logic is needed, then the built-in cancellation activities or custom activities can be used. + + In the following example, the override of a based custom `ParallelForEach` activity is defined. When the activity is canceled, this override handles the cancellation logic for the activity. This example is part of the [Non-Generic ParallelForEach](./samples/non-generic-parallelforeach.md) sample. + +```csharp +protected override void Cancel(NativeActivityContext context) +{ + // If we do not have a completion condition then we can just + // use default logic. + if (this.CompletionCondition == null) + { + base.Cancel(context); + } + else + { + context.CancelChildren(); + } +} +``` + + derived activities can determine if cancellation has been requested by inspecting the property, and mark themselves as canceled by calling the method. Calling does not immediately complete the activity. As usual, the runtime will complete the activity when it has no more outstanding work, but if is called the final state will be instead of . + +### Cancellation using AsyncCodeActivity + + based activities can also provide custom cancellation logic by overriding the method. If this method is not overridden, then no cancellation handling is performed if the activity is canceled. In the following example, the override of an based custom `ExecutePowerShell` activity is defined. When the activity is canceled, it performs the desired cancellation behavior. + + [!code-csharp[CFX_WorkflowApplicationExample#1020](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#1020)] + + derived activities can determine if cancellation has been requested by inspecting the property, and mark themselves as canceled by calling the method. diff --git a/docs/framework/windows-workflow-foundation/nativeactivity-base-class.md b/docs/framework/windows-workflow-foundation/nativeactivity-base-class.md index 23f9b17c73b7d..d49a55e1da071 100644 --- a/docs/framework/windows-workflow-foundation/nativeactivity-base-class.md +++ b/docs/framework/windows-workflow-foundation/nativeactivity-base-class.md @@ -6,27 +6,27 @@ ms.assetid: 254a4c50-425b-426d-a32f-0f7234925bac --- # NativeActivity Base Class - is an abstract class with a protected constructor. Like , is used for writing imperative behavior by implementing an method. Unlike , has access to all of the exposed features of the workflow runtime through the object passed to the method. + is an abstract class with a protected constructor. Like , is used for writing imperative behavior by implementing an method. Unlike , has access to all of the exposed features of the workflow runtime through the object passed to the method. ## Using NativeActivityContext - Features of the workflow runtime can be accessed from within the method by using members of the `context` parameter, of type . The features available through include the following: + Features of the workflow runtime can be accessed from within the method by using members of the `context` parameter, of type . The features available through include the following: - Getting and setting of arguments and variables. -- Scheduling child activities with +- Scheduling child activities with -- Aborting activity execution using . +- Aborting activity execution using . -- Canceling child execution using and . +- Canceling child execution using and . -- Access to activity bookmarks using such methods as , , and . +- Access to activity bookmarks using such methods as , , and . -- Custom tracking features using . +- Custom tracking features using . -- Access to the activity’s execution properties and value properties using and . +- Access to the activity’s execution properties and value properties using and . -- Scheduling activity actions and functions using and . +- Scheduling activity actions and functions using and . ### To create a custom activity that inherits from NativeActivity @@ -51,7 +51,7 @@ ms.assetid: 254a4c50-425b-426d-a32f-0f7234925bac class HelloActivity : NativeActivity ``` -7. Add functionality to the class by adding an method. +7. Add functionality to the class by adding an method. ```csharp protected override void Execute(NativeActivityContext context) @@ -60,9 +60,9 @@ ms.assetid: 254a4c50-425b-426d-a32f-0f7234925bac } ``` -8. Override the method and call the appropriate Add method to let the workflow runtime know about the custom activity’s variables, arguments, children, and delegates. For more information see the class. +8. Override the method and call the appropriate Add method to let the workflow runtime know about the custom activity’s variables, arguments, children, and delegates. For more information see the class. -9. Use the object to schedule a bookmark. See for details on how to create, schedule, and resume a bookmark. +9. Use the object to schedule a bookmark. See for details on how to create, schedule, and resume a bookmark. ```csharp protected override void Execute(NativeActivityContext context) diff --git a/docs/framework/windows-workflow-foundation/net-framework-3-0-wf-in-net-framework-4-interop.md b/docs/framework/windows-workflow-foundation/net-framework-3-0-wf-in-net-framework-4-interop.md index 174b6ce1e77c9..eeb7b7b57a6ea 100644 --- a/docs/framework/windows-workflow-foundation/net-framework-3-0-wf-in-net-framework-4-interop.md +++ b/docs/framework/windows-workflow-foundation/net-framework-3-0-wf-in-net-framework-4-interop.md @@ -25,9 +25,9 @@ The activity is a .NET Framework 4.6 ## Configuring a WF 3 Activity Within an Interop Activity - To configure and pass data into and out of a WF 3 activity, across the interoperation boundary, the WF 3 activity’s properties and metadata properties are exposed by the activity. The WF 3 activity’s metadata properties (such as ) are exposed through the collection. This is a collection of name-value pairs used to define the values for the WF 3 activity’s metadata properties. A metadata property is a property backed by dependency property for which the flag is set. + To configure and pass data into and out of a WF 3 activity, across the interoperation boundary, the WF 3 activity’s properties and metadata properties are exposed by the activity. The WF 3 activity’s metadata properties (such as ) are exposed through the collection. This is a collection of name-value pairs used to define the values for the WF 3 activity’s metadata properties. A metadata property is a property backed by dependency property for which the flag is set. - The WF 3 activity’s properties are exposed through the collection. This is a set of name-value pairs, where each value is a object, used to define the arguments for the WF 3 activity’s properties. Because the direction of a WF 3 activity property cannot be inferred, every property is surfaced as an / pair. Depending on the activity’s usage of the property, you may want to provide an entry, an entry, or both. The expected name of the entry in the collection is the name of the property as defined on the WF 3 activity. The expected name of the entry in the collection is a concatenation of the name of the property and the string "Out". + The WF 3 activity’s properties are exposed through the collection. This is a set of name-value pairs, where each value is a object, used to define the arguments for the WF 3 activity’s properties. Because the direction of a WF 3 activity property cannot be inferred, every property is surfaced as an / pair. Depending on the activity’s usage of the property, you may want to provide an entry, an entry, or both. The expected name of the entry in the collection is the name of the property as defined on the WF 3 activity. The expected name of the entry in the collection is a concatenation of the name of the property and the string "Out". ## Limitations of Using a WF 3 Activity Within an Interop Activity diff --git a/docs/framework/windows-workflow-foundation/overview.md b/docs/framework/windows-workflow-foundation/overview.md index cfb92a488281f..be768edd063c9 100644 --- a/docs/framework/windows-workflow-foundation/overview.md +++ b/docs/framework/windows-workflow-foundation/overview.md @@ -31,13 +31,13 @@ Workflow components in the host process ![Diagram that shows how workflow components interact.](./media/overview/workflow-component-interatction.gif) - In the preceding diagram, the method of the class is used to invoke several workflow instances. is used for lightweight workflows that do not need management from the host; workflows that need management from the host (such as resumption) must be executed using instead. It isn’t required to wait for one workflow instance to complete before invoking another; the runtime engine supports running multiple workflow instances simultaneously. The workflows invoked are as follows: + In the preceding diagram, the method of the class is used to invoke several workflow instances. is used for lightweight workflows that do not need management from the host; workflows that need management from the host (such as resumption) must be executed using instead. It isn’t required to wait for one workflow instance to complete before invoking another; the runtime engine supports running multiple workflow instances simultaneously. The workflows invoked are as follows: - A activity that contains a child activity. A of the parent activity is bound to an of the child activity. For more information about on variables, arguments, and binding, see [Variables and Arguments](variables-and-arguments.md). -- A custom activity called `ReadLine`. An of the `ReadLine` activity is returned to the calling method. +- A custom activity called `ReadLine`. An of the `ReadLine` activity is returned to the calling method. -- A custom activity that derives from the abstract class. The can access runtime features (such as tracking and properties) using the that is available as a parameter of the method. For more information about these runtime features, see [Workflow Tracking and Tracing](workflow-tracking-and-tracing.md) and [Workflow Execution Properties](workflow-execution-properties.md). +- A custom activity that derives from the abstract class. The can access runtime features (such as tracking and properties) using the that is available as a parameter of the method. For more information about these runtime features, see [Workflow Tracking and Tracing](workflow-tracking-and-tracing.md) and [Workflow Execution Properties](workflow-execution-properties.md). ## See also diff --git a/docs/framework/windows-workflow-foundation/pausing-and-resuming-a-workflow.md b/docs/framework/windows-workflow-foundation/pausing-and-resuming-a-workflow.md index 00c8a47c89fc7..9d90109c17b16 100644 --- a/docs/framework/windows-workflow-foundation/pausing-and-resuming-a-workflow.md +++ b/docs/framework/windows-workflow-foundation/pausing-and-resuming-a-workflow.md @@ -11,7 +11,7 @@ Workflows pause and resume in response to bookmarks and blocking activities such ## Pause a workflow -To pause a workflow, use . This method requests that the workflow persist and unload, and will throw a if the workflow does not unload in 30 seconds. +To pause a workflow, use . This method requests that the workflow persist and unload, and will throw a if the workflow does not unload in 30 seconds. ```csharp try @@ -27,7 +27,7 @@ catch (TimeoutException e) ## Resume a workflow -To resume a previously paused and unloaded workflow, use . This method loads a workflow from a persistence store into memory. +To resume a previously paused and unloaded workflow, use . This method loads a workflow from a persistence store into memory. ```csharp WorkflowApplication application = new WorkflowApplication(activity); diff --git a/docs/framework/windows-workflow-foundation/performance.md b/docs/framework/windows-workflow-foundation/performance.md index 68f3f4c2dc4eb..f6ff8df4506b0 100644 --- a/docs/framework/windows-workflow-foundation/performance.md +++ b/docs/framework/windows-workflow-foundation/performance.md @@ -48,7 +48,7 @@ ms.assetid: 67d2b3e8-3777-49f8-9084-abbb33b5a766 ### Asynchronous Programming - Applications usually have better performance and scalability with asynchronous programming for long running blocking operations such as I/O or distributed computing operations. WF4 provides asynchronous support through base activity types , . The runtime natively understands asynchronous activities and therefore can automatically put the instance in a no-persist zone while the asynchronous work is outstanding. Custom activities can derive from these types to perform asynchronous work without holding the workflow scheduler thread and blocking any activities that may be able to run in parallel. + Applications usually have better performance and scalability with asynchronous programming for long running blocking operations such as I/O or distributed computing operations. WF4 provides asynchronous support through base activity types , . The runtime natively understands asynchronous activities and therefore can automatically put the instance in a no-persist zone while the asynchronous work is outstanding. Custom activities can derive from these types to perform asynchronous work without holding the workflow scheduler thread and blocking any activities that may be able to run in parallel. ### Messaging @@ -116,7 +116,7 @@ ms.assetid: 67d2b3e8-3777-49f8-9084-abbb33b5a766 ### Replicator compared to ParallelForEach - in WF3 has sequential and parallel execution modes. In sequential mode, the activity’s performance is similar to the . The is most useful for parallel execution. The WF4 analog for this is the activity. + in WF3 has sequential and parallel execution modes. In sequential mode, the activity’s performance is similar to the . The is most useful for parallel execution. The WF4 analog for this is the activity. The following diagram shows the workflows used for this test. The WF3 workflow is on the left and the WF4 workflow is on the right. @@ -410,7 +410,7 @@ public class Workflow1 : Activity When the transport between client and middle tier is HTTP, persistence in WF4 shows an improvement of 2.6 times. The TCP transport increases that factor to 3.0 times. In all cases, CPU utilization on the middle tier is 98% or higher. The reason that WF4 throughput is greater is due to the faster workflow runtime. The size of the serialized instance is low for both cases and is not a major contributing element in this situation. - Both the WF3 and WF4 workflows in this test use an activity to explicitly indicate when persistence should occur. This has the benefit of persisting the workflow without unloading it. In WF3, it is also possible to persist using the feature, but this unloads the workflow instance from memory. If a developer using WF3 wants to make sure a workflow persists at certain points, they either have to alter the workflow definition or pay the cost for unloading and re-loading the workflow instance. A new feature in WF4 makes it possible to persist without unloading: . This feature allows the workflow instance to be persisted on idle but stay in memory until the threshold is met or execution is resumed. + Both the WF3 and WF4 workflows in this test use an activity to explicitly indicate when persistence should occur. This has the benefit of persisting the workflow without unloading it. In WF3, it is also possible to persist using the feature, but this unloads the workflow instance from memory. If a developer using WF3 wants to make sure a workflow persists at certain points, they either have to alter the workflow definition or pay the cost for unloading and re-loading the workflow instance. A new feature in WF4 makes it possible to persist without unloading: . This feature allows the workflow instance to be persisted on idle but stay in memory until the threshold is met or execution is resumed. Note that the WF4 SQL persistence provider performs more work in the database tier. The SQL database can become a bottleneck so it is important to monitor the CPU and disk usage there. Be sure to include the following performance counters from the SQL database when performance testing workflow applications: diff --git a/docs/framework/windows-workflow-foundation/persistence-best-practices.md b/docs/framework/windows-workflow-foundation/persistence-best-practices.md index 079721f1feb46..da16e551666bf 100644 --- a/docs/framework/windows-workflow-foundation/persistence-best-practices.md +++ b/docs/framework/windows-workflow-foundation/persistence-best-practices.md @@ -6,83 +6,83 @@ ms.assetid: 6974c5a4-1af8-4732-ab53-7d694608a3a0 --- # Persistence Best Practices -This document covers best practices for workflow design and configuration related to workflow persistence. - -## Design and Implementation of Durable Workflows - - In general, workflows perform work in short periods that are interleaved with times during which the workflow is idle because it is waiting for an event. This event can be such things as a message or an expiring timer. To be able to unload the workflow instance when it becomes idle, the service host must persist the workflow instance. This is possible only if the workflow instance is not in a no-persist zone (for example, waiting for a transaction to complete, or waiting for an asynchronous callback). To allow an idle workflow instance to unload, the workflow author should use transaction scopes and asynchronous activities for short-lived actions only. In particular, the author should keep delay activities within these no-persist zones as short as possible. - - A workflow can only be persisted if all of the data types used by the workflow are serializable. In addition, custom types used in persisted workflows must be serializable with in order to be persisted by . - - A workflow instance cannot be recovered in case of a host or computer failure if it has not been persisted. In general, we recommend that you persist a workflow instance early in the workflow’s life cycle. - - If your workflow is busy for a long time, we recommend that you persist the workflow instance regularly throughout its busy period. You can do this by adding activities throughout the sequence of activities that keep the workflow instance busy. In this manner, application domain recycling, host failures, or computer failures do not cause the system to be rolled back to the start of the busy period. Be aware that adding activities to your workflow could lead to a degradation of performance. - - Windows Server App Fabric greatly simplifies the configuration and use of persistence. For more information, see [Windows Server App Fabric Persistence](/previous-versions/appfabric/ee677272(v=azure.10)) - -## Configuration of Scalability Parameters - - Scalability and performance requirements determine the settings of the following parameters: - -- - -- - -- - - These parameters should be set as follows, according to the current scenario. - -### Scenario: A Small Number of Workflow Instances That Require Optimal Response Time - - In this scenario, all workflow instances should remain loaded when they become idle. Set to a large value. The use of this setting prevents a workflow instance from moving between computers. Use this setting only if one or more of the following are true: - -- A workflow instance receives a single message throughout its lifetime. - -- All workflow instances run on a single computer - -- All messages that are received by a workflow instance are received by the same computer. - - Use activities or set to 0 to enable recovery of your workflow instance after service host or computer failures. - -### Scenario: Workflow Instances Are Idle for Long Periods of Time - - In this scenario, set to 0 to release resources as soon as possible. - -### Scenario: Workflow Instances Receive Multiple Messages in a Short Period of Time - - In this scenario, set to 60 seconds if these messages are received by the same computer. This prevents a rapid sequence of unloading and loading of a workflow instance. This also does not keep the instance in memory for too long. - - Set to 0, and set to BasicRetry or AggressiveRetry if these messages may be received by different computers. This allows the workflow instance to be loaded by another computer. - -### Scenario: Workflow Uses Delay Activities with Short Durations - - In this scenario, the regularly polls the persistence database for instances that should be loaded because of an expired activity. If the finds a timer that will expire in the next polling interval, the SQL Workflow Instance Store shortens the polling interval. The next poll will then occur right after the timer has expired. This way, the SQL Workflow Instance Store achieves a high accuracy of timers that run longer than the polling interval, which is set by . To enable timely processing of shorter delays, the workflow instance must remain in memory for at least one polling interval. - - Set to 0 to write the expiration time to the persistence database. - - Set to longer than or equal to to keep the instance in memory for at least one polling interval. - - We do not recommend reducing the because this leads to an increased load on the persistence database. Each service host that uses the polls the database one time per detection period. Setting to too small a time interval may cause your system's performance to decrease if the number of service hosts is large. - -## Configuring the SQL Workflow Instance Store - - The SQL Workflow Instance Store has the following configuration parameters: - - - This parameter instructs the to compress the workflow instance state. Compression reduces the amount of data that is stored in the persistence database and reduces network traffic in case the persistence database resides on a dedicated database server. If compression is used, it requires computational resources to compress and extract the instance state. In most cases, compression yields increased performance. - - - This parameter instructs the to either keep or delete completed instances. Keeping completed instances increases the persistence database storage requirements and leads to larger tables, which increases table lookup times. Unless completed instances are required for debugging or auditing, it is best to instruct the to delete completed instances. Deleted instances should be kept only if the user establishes a process for eventually removing them. Note that correlation keys cannot be reused as long as the completed workflow instance resides in the instance store. - - - This parameter defines the maximum interval with which the polls the persistence database for instances that should be loaded when a activity expires. If the finds a timer that will expire in the next polling interval, it shortens the polling interval so that the next poll will occur right after the timer has expired. This way, the SQL Workflow Instance Store achieves a high accuracy of timers that run longer than . - - We do not recommend reducing the , because this leads to an increased load on the persistence database. Each service host that uses the polls the database one time per detection period. Setting to too small an interval may cause your system's performance to decrease if the number of service hosts is large. - - - This parameter defines the interval with which the host renews its lock in the persistence database. Shortening this interval will enable a quicker recovery of the workflow instances in case a host or computer fails. On the other hand, a short lock renewal period increases the load on the persistence database. Each service host that uses the will update its locks in the database one time per renewal period. If a computer runs many service hosts, make sure that the load caused by lock renewal does not decrease your system's performance. If it does, consider increasing the . - - - If enabled, the retries to load a locked instance for the next 30 seconds. Set to BasicRetry or AggressiveRetry if the workflow receives multiple messages in a short time, and these messages are received by different computers. - - Because the load retry mechanism does not introduce any performance overhead as long as load retries are not tried, should always be enabled. +This document covers best practices for workflow design and configuration related to workflow persistence. + +## Design and Implementation of Durable Workflows + + In general, workflows perform work in short periods that are interleaved with times during which the workflow is idle because it is waiting for an event. This event can be such things as a message or an expiring timer. To be able to unload the workflow instance when it becomes idle, the service host must persist the workflow instance. This is possible only if the workflow instance is not in a no-persist zone (for example, waiting for a transaction to complete, or waiting for an asynchronous callback). To allow an idle workflow instance to unload, the workflow author should use transaction scopes and asynchronous activities for short-lived actions only. In particular, the author should keep delay activities within these no-persist zones as short as possible. + + A workflow can only be persisted if all of the data types used by the workflow are serializable. In addition, custom types used in persisted workflows must be serializable with in order to be persisted by . + + A workflow instance cannot be recovered in case of a host or computer failure if it has not been persisted. In general, we recommend that you persist a workflow instance early in the workflow’s life cycle. + + If your workflow is busy for a long time, we recommend that you persist the workflow instance regularly throughout its busy period. You can do this by adding activities throughout the sequence of activities that keep the workflow instance busy. In this manner, application domain recycling, host failures, or computer failures do not cause the system to be rolled back to the start of the busy period. Be aware that adding activities to your workflow could lead to a degradation of performance. + + Windows Server App Fabric greatly simplifies the configuration and use of persistence. For more information, see [Windows Server App Fabric Persistence](/previous-versions/appfabric/ee677272(v=azure.10)) + +## Configuration of Scalability Parameters + + Scalability and performance requirements determine the settings of the following parameters: + +- + +- + +- + + These parameters should be set as follows, according to the current scenario. + +### Scenario: A Small Number of Workflow Instances That Require Optimal Response Time + + In this scenario, all workflow instances should remain loaded when they become idle. Set to a large value. The use of this setting prevents a workflow instance from moving between computers. Use this setting only if one or more of the following are true: + +- A workflow instance receives a single message throughout its lifetime. + +- All workflow instances run on a single computer + +- All messages that are received by a workflow instance are received by the same computer. + + Use activities or set to 0 to enable recovery of your workflow instance after service host or computer failures. + +### Scenario: Workflow Instances Are Idle for Long Periods of Time + + In this scenario, set to 0 to release resources as soon as possible. + +### Scenario: Workflow Instances Receive Multiple Messages in a Short Period of Time + + In this scenario, set to 60 seconds if these messages are received by the same computer. This prevents a rapid sequence of unloading and loading of a workflow instance. This also does not keep the instance in memory for too long. + + Set to 0, and set to BasicRetry or AggressiveRetry if these messages may be received by different computers. This allows the workflow instance to be loaded by another computer. + +### Scenario: Workflow Uses Delay Activities with Short Durations + + In this scenario, the regularly polls the persistence database for instances that should be loaded because of an expired activity. If the finds a timer that will expire in the next polling interval, the SQL Workflow Instance Store shortens the polling interval. The next poll will then occur right after the timer has expired. This way, the SQL Workflow Instance Store achieves a high accuracy of timers that run longer than the polling interval, which is set by . To enable timely processing of shorter delays, the workflow instance must remain in memory for at least one polling interval. + + Set to 0 to write the expiration time to the persistence database. + + Set to longer than or equal to to keep the instance in memory for at least one polling interval. + + We do not recommend reducing the because this leads to an increased load on the persistence database. Each service host that uses the polls the database one time per detection period. Setting to too small a time interval may cause your system's performance to decrease if the number of service hosts is large. + +## Configuring the SQL Workflow Instance Store + + The SQL Workflow Instance Store has the following configuration parameters: + + + This parameter instructs the to compress the workflow instance state. Compression reduces the amount of data that is stored in the persistence database and reduces network traffic in case the persistence database resides on a dedicated database server. If compression is used, it requires computational resources to compress and extract the instance state. In most cases, compression yields increased performance. + + + This parameter instructs the to either keep or delete completed instances. Keeping completed instances increases the persistence database storage requirements and leads to larger tables, which increases table lookup times. Unless completed instances are required for debugging or auditing, it is best to instruct the to delete completed instances. Deleted instances should be kept only if the user establishes a process for eventually removing them. Note that correlation keys cannot be reused as long as the completed workflow instance resides in the instance store. + + + This parameter defines the maximum interval with which the polls the persistence database for instances that should be loaded when a activity expires. If the finds a timer that will expire in the next polling interval, it shortens the polling interval so that the next poll will occur right after the timer has expired. This way, the SQL Workflow Instance Store achieves a high accuracy of timers that run longer than . + + We do not recommend reducing the , because this leads to an increased load on the persistence database. Each service host that uses the polls the database one time per detection period. Setting to too small an interval may cause your system's performance to decrease if the number of service hosts is large. + + + This parameter defines the interval with which the host renews its lock in the persistence database. Shortening this interval will enable a quicker recovery of the workflow instances in case a host or computer fails. On the other hand, a short lock renewal period increases the load on the persistence database. Each service host that uses the will update its locks in the database one time per renewal period. If a computer runs many service hosts, make sure that the load caused by lock renewal does not decrease your system's performance. If it does, consider increasing the . + + + If enabled, the retries to load a locked instance for the next 30 seconds. Set to BasicRetry or AggressiveRetry if the workflow receives multiple messages in a short time, and these messages are received by different computers. + + Because the load retry mechanism does not introduce any performance overhead as long as load retries are not tried, should always be enabled. diff --git a/docs/framework/windows-workflow-foundation/persistence-participants.md b/docs/framework/windows-workflow-foundation/persistence-participants.md index d7e11c0f3ecd2..f7fd6ba508be1 100644 --- a/docs/framework/windows-workflow-foundation/persistence-participants.md +++ b/docs/framework/windows-workflow-foundation/persistence-participants.md @@ -6,56 +6,56 @@ ms.assetid: f84d2d5d-1c1b-4f19-be45-65b552d3e9e3 --- # Persistence Participants -A persistence participant can participate in a persistence operation (Save or Load) triggered by an application host. The [!INCLUDE[netfx_current_long](../../../includes/netfx-current-long-md.md)] ships with two abstract classes, **PersistenceParticipant** and **PersistenceIOParticipant**, which you can use to create a persistence participant. A persistence participant derives from one of these classes, implements the methods of interest, and then adds an instance of the class to the collection on the . The application host may look for such workflow extensions when persisting a workflow instance and invoke appropriate methods on the persistence participants at appropriate times. - - The following list describes the tasks performed by the persistence subsystem in different stages of the Persist (Save) operation. The persistence participants are used in the third and fourth stages. If the participant is an I/O participant (a persistence participant that also participates in I/O operations), the participant is also used in the sixth stage. - -1. Gathers built-in values, including workflow state, bookmarks, mapped variables, and timestamp. - -2. Gathers all persistence participants that were added to the extension collection associated with the workflow instance. - -3. Invokes the method implemented by all persistence participants. - -4. Invokes the method implemented by all persistence participants. - -5. Persist or save the workflow into the persistence store. - -6. Invokes the method on all of the persistence I/O participants. If the participant is not an I/O participant, this task is skipped. If the persistence episode is transactional, the transaction is provided in Transaction.Current property. - -7. Waits for all persistence participants to complete. If all the participants succeed in persisting instance data, commits the transaction. - - A persistence participant derives from the **PersistenceParticipant** class and may implement the **CollectValues** and **MapValues** methods. A persistence I/O participant derives from the **PersistenceIOParticipant** class and may implement the **BeginOnSave** method in addition to implementing the **CollectValues** and **MapValues** methods. - - Each stage is completed before the next stage begins. For example, values are collected from **all** persistence participants in the first stage. Then all the values collected in the first stage are provided to all persistence participants in the second stage for mapping. Then all the values collected and mapped in the first and second stages are provided to the persistence provider in the third stage, and so on. - - The following list describes the tasks performed by the persistence subsystem in different stages of the Load operation. The persistence participants are used in the fourth stage. The persistence I/O participants (persistence participants that also participate in I/O operations) are also used in the third stage. - -1. Gathers all persistence participants that were added to the extension collection associated with the workflow instance. - -2. Loads the workflow from the persistence store. - -3. Invokes the on all persistence I/O participants and waits for all the persistence participants to complete. If the persistence episode is transactional, the transaction is provided in Transaction.Current. - -4. Loads the workflow instance in memory based on the data retrieved from the persistence store. - -5. Invokes on each persistence participant. - - A persistence participant derives from the **PersistenceParticipant** class and may implement the **PublishValues** method. A persistence I/O participant derives from the **PersistenceIOParticipant** class and may implement the **BeginOnLoad** method in addition to implementing the **PublishValues** method. - - When loading a workflow instance the persistence provider creates a lock on that instance. This prevents the instance from being loaded by more than one host in a multi-node scenario. If you attempt to load a workflow instance that has been locked you will see an exception like the following: The exception " System.ServiceModel.Persistence.InstanceLockException: The requested operation could not complete because the lock for instance '00000000-0000-0000-0000-000000000000' could not be acquired". This error is caused when one of the following occurs: - -- In a multi-node scenario the instance is loaded by another host. There are a few different ways to resolve these types of conflicts: forward the processing to the node which owns the lock and retry, or force the load which will cause the other host to be unable to save their work. - -- In a single-node scenario and the host crashed. When the host starts up again (a process recycle or creating a new persistence provider factory) the new host attempts to load an instance which is still locked by the old host because the lock hasn't expired yet. - -- In a single-node scenario and the instance in question was aborted at some point and a new persistence provider instance is created which has a different host ID. - - The lock timeout value has a default value of 5 minutes, you can specify a different timeout value when calling . - -## In This Section - -- [How to: Create a Custom Persistence Participant](how-to-create-a-custom-persistence-participant.md) - +A persistence participant can participate in a persistence operation (Save or Load) triggered by an application host. The [!INCLUDE[netfx_current_long](../../../includes/netfx-current-long-md.md)] ships with two abstract classes, **PersistenceParticipant** and **PersistenceIOParticipant**, which you can use to create a persistence participant. A persistence participant derives from one of these classes, implements the methods of interest, and then adds an instance of the class to the collection on the . The application host may look for such workflow extensions when persisting a workflow instance and invoke appropriate methods on the persistence participants at appropriate times. + + The following list describes the tasks performed by the persistence subsystem in different stages of the Persist (Save) operation. The persistence participants are used in the third and fourth stages. If the participant is an I/O participant (a persistence participant that also participates in I/O operations), the participant is also used in the sixth stage. + +1. Gathers built-in values, including workflow state, bookmarks, mapped variables, and timestamp. + +2. Gathers all persistence participants that were added to the extension collection associated with the workflow instance. + +3. Invokes the method implemented by all persistence participants. + +4. Invokes the method implemented by all persistence participants. + +5. Persist or save the workflow into the persistence store. + +6. Invokes the method on all of the persistence I/O participants. If the participant is not an I/O participant, this task is skipped. If the persistence episode is transactional, the transaction is provided in Transaction.Current property. + +7. Waits for all persistence participants to complete. If all the participants succeed in persisting instance data, commits the transaction. + + A persistence participant derives from the **PersistenceParticipant** class and may implement the **CollectValues** and **MapValues** methods. A persistence I/O participant derives from the **PersistenceIOParticipant** class and may implement the **BeginOnSave** method in addition to implementing the **CollectValues** and **MapValues** methods. + + Each stage is completed before the next stage begins. For example, values are collected from **all** persistence participants in the first stage. Then all the values collected in the first stage are provided to all persistence participants in the second stage for mapping. Then all the values collected and mapped in the first and second stages are provided to the persistence provider in the third stage, and so on. + + The following list describes the tasks performed by the persistence subsystem in different stages of the Load operation. The persistence participants are used in the fourth stage. The persistence I/O participants (persistence participants that also participate in I/O operations) are also used in the third stage. + +1. Gathers all persistence participants that were added to the extension collection associated with the workflow instance. + +2. Loads the workflow from the persistence store. + +3. Invokes the on all persistence I/O participants and waits for all the persistence participants to complete. If the persistence episode is transactional, the transaction is provided in Transaction.Current. + +4. Loads the workflow instance in memory based on the data retrieved from the persistence store. + +5. Invokes on each persistence participant. + + A persistence participant derives from the **PersistenceParticipant** class and may implement the **PublishValues** method. A persistence I/O participant derives from the **PersistenceIOParticipant** class and may implement the **BeginOnLoad** method in addition to implementing the **PublishValues** method. + + When loading a workflow instance the persistence provider creates a lock on that instance. This prevents the instance from being loaded by more than one host in a multi-node scenario. If you attempt to load a workflow instance that has been locked you will see an exception like the following: The exception " System.ServiceModel.Persistence.InstanceLockException: The requested operation could not complete because the lock for instance '00000000-0000-0000-0000-000000000000' could not be acquired". This error is caused when one of the following occurs: + +- In a multi-node scenario the instance is loaded by another host. There are a few different ways to resolve these types of conflicts: forward the processing to the node which owns the lock and retry, or force the load which will cause the other host to be unable to save their work. + +- In a single-node scenario and the host crashed. When the host starts up again (a process recycle or creating a new persistence provider factory) the new host attempts to load an instance which is still locked by the old host because the lock hasn't expired yet. + +- In a single-node scenario and the instance in question was aborted at some point and a new persistence provider instance is created which has a different host ID. + + The lock timeout value has a default value of 5 minutes, you can specify a different timeout value when calling . + +## In This Section + +- [How to: Create a Custom Persistence Participant](how-to-create-a-custom-persistence-participant.md) + ## See also - [Store Extensibility](store-extensibility.md) diff --git a/docs/framework/windows-workflow-foundation/pick-activity.md b/docs/framework/windows-workflow-foundation/pick-activity.md index ff476dd74682d..3fcaeb8241453 100644 --- a/docs/framework/windows-workflow-foundation/pick-activity.md +++ b/docs/framework/windows-workflow-foundation/pick-activity.md @@ -6,7 +6,7 @@ ms.assetid: b3e49b7f-0285-4720-8c09-11ae18f0d53e --- # Pick Activity -The activity simplifies the modeling of a set of event triggers followed by their corresponding handlers. A activity contains a collection of activities, where each is a pairing between a activity and an activity. At execution time, the triggers for all branches are executed in parallel. When one trigger completes, then its corresponding action is executed, and all other triggers are canceled. The behavior of the .NET Framework 4.6.1 activity is similar to the .NET Framework 3.5 activity. +The activity simplifies the modeling of a set of event triggers followed by their corresponding handlers. A activity contains a collection of activities, where each is a pairing between a activity and an activity. At execution time, the triggers for all branches are executed in parallel. When one trigger completes, then its corresponding action is executed, and all other triggers are canceled. The behavior of the .NET Framework 4.6.1 activity is similar to the .NET Framework 3.5 activity. The following screenshot from the [Using the Pick Activity](./samples/using-the-pick-activity.md) SDK sample shows a Pick activity with two branches. One branch has a trigger called **Read input**, a custom activity that reads input from the command line. The second branch has a activity trigger. If the **Read input** activity receives data before the activity finishes, Delay will be canceled and a greeting will be written to the console. Otherwise, if the **Read input** activity does not receive data in the allotted time, then it will be canceled and a timeout message will be written to the console. This is a common pattern used to add a timeout to any action. @@ -22,7 +22,7 @@ The activity simplifies the modeling of ## Using the Pick Activity in code - The activity is used by populating its collection with activities. The activities each have a property of type . When the specified activity completes execution, the executes. + The activity is used by populating its collection with activities. The activities each have a property of type . When the specified activity completes execution, the executes. The following code example demonstrates how to use a activity to implement a timeout for an activity that reads a line from the console. diff --git a/docs/framework/windows-workflow-foundation/procedural-workflows.md b/docs/framework/windows-workflow-foundation/procedural-workflows.md index b468061be3de2..54b56e7368c87 100644 --- a/docs/framework/windows-workflow-foundation/procedural-workflows.md +++ b/docs/framework/windows-workflow-foundation/procedural-workflows.md @@ -6,33 +6,33 @@ ms.assetid: 52401de9-9115-472d-8fd9-047af6a072b9 --- # Procedural Workflows -Procedural workflows use flow-control methods similar to those found in procedural languages. These constructs include `While` and `If`. These workflows can be freely composed using other flow control activities such as and . - -## Controlling Execution Flow - - The workflow activity library has activities for modeling most flow-control methods used in procedural languages. These include: - -- - -- - -- - -- - -- - -- - -- - -- - - To use flow control activities, drag and drop them from the **Activity** toolbox into a composite activity inside the designer window. - +Procedural workflows use flow-control methods similar to those found in procedural languages. These constructs include `While` and `If`. These workflows can be freely composed using other flow control activities such as and . + +## Controlling Execution Flow + + The workflow activity library has activities for modeling most flow-control methods used in procedural languages. These include: + +- + +- + +- + +- + +- + +- + +- + +- + + To use flow control activities, drag and drop them from the **Activity** toolbox into a composite activity inside the designer window. + > [!NOTE] -> If using the hosting features of Windows Server AppFabric to host workflows on a Web farm, AppFabric will move instances between different AppFabric servers. This requires that the resources are able to be shared between all nodes. None of the default NET 4 workflow activities contain any operations that access local resources. Since AppFabric does not offer any mechanism to mark a workflow as immovable, a developer must not create custom activities that fail when a workflow is moved. - +> If using the hosting features of Windows Server AppFabric to host workflows on a Web farm, AppFabric will move instances between different AppFabric servers. This requires that the resources are able to be shared between all nodes. None of the default NET 4 workflow activities contain any operations that access local resources. Since AppFabric does not offer any mechanism to mark a workflow as immovable, a developer must not create custom activities that fail when a workflow is moved. + ## See also - [Flowchart Workflows](flowchart-workflows.md) diff --git a/docs/framework/windows-workflow-foundation/properties-vs-arguments.md b/docs/framework/windows-workflow-foundation/properties-vs-arguments.md index 8f1d3ac2b262c..f75cb4f2de40d 100644 --- a/docs/framework/windows-workflow-foundation/properties-vs-arguments.md +++ b/docs/framework/windows-workflow-foundation/properties-vs-arguments.md @@ -6,16 +6,16 @@ ms.assetid: 14651389-4a49-4cbb-9ddf-c83fdc155df1 --- # Properties vs. Arguments -There are several options available for passing data into an activity. In addition to using , activities can also be developed that receive data using either standard CLR Properties or public properties. This topic discusses how to select the appropriate method type. - -## Using CLR Properties +There are several options available for passing data into an activity. In addition to using , activities can also be developed that receive data using either standard CLR Properties or public properties. This topic discusses how to select the appropriate method type. - When passing data into an activity, CLR properties (that is, public methods that use Get and Set routines to expose data) are the option that has the most restrictions. The value of a parameter passed into a CLR property must be known when the solution is compiled; this value will be the same for every instance of the workflow. In this way, a value passed into a CLR property is similar to a constant defined in code; this value can’t change for the life of the activity, and can’t be changed for different instances of the activity. is an example of a CLR property exposed by an activity; the method name that the activity calls can’t be changed based on runtime conditions, and will be the same for every instance of the activity. - -## Using Arguments +## Using CLR Properties - Arguments should be used when data is only evaluated once during the lifetime of the activity; that is, its value will not change during the lifetime of the activity, but the value can be different for different instances of the activity. is an example of a value that gets evaluated once; therefore it is defined as an argument. is another example of a method that should be defined as an argument, since it is only evaluated once during the activity’s execution, but it can be different for different instances of the activity. - -## Using ActivityAction + When passing data into an activity, CLR properties (that is, public methods that use Get and Set routines to expose data) are the option that has the most restrictions. The value of a parameter passed into a CLR property must be known when the solution is compiled; this value will be the same for every instance of the workflow. In this way, a value passed into a CLR property is similar to a constant defined in code; this value can’t change for the life of the activity, and can’t be changed for different instances of the activity. is an example of a CLR property exposed by an activity; the method name that the activity calls can’t be changed based on runtime conditions, and will be the same for every instance of the activity. - When data needs to be evaluated multiple times during the lifetime of an activity’s execution, an should be used. For example, the property is evaluated for each iteration of the loop. If an were used for this purpose, the loop would never exit, since the argument would not be reevaluated for each iteration, and would always return the same result. +## Using Arguments + + Arguments should be used when data is only evaluated once during the lifetime of the activity; that is, its value will not change during the lifetime of the activity, but the value can be different for different instances of the activity. is an example of a value that gets evaluated once; therefore it is defined as an argument. is another example of a method that should be defined as an argument, since it is only evaluated once during the activity’s execution, but it can be different for different instances of the activity. + +## Using ActivityAction + + When data needs to be evaluated multiple times during the lifetime of an activity’s execution, an should be used. For example, the property is evaluated for each iteration of the loop. If an were used for this purpose, the loop would never exit, since the argument would not be reevaluated for each iteration, and would always return the same result. diff --git a/docs/framework/windows-workflow-foundation/required-arguments-and-overload-groups.md b/docs/framework/windows-workflow-foundation/required-arguments-and-overload-groups.md index c17445aed2c4b..5e13e7f04269c 100644 --- a/docs/framework/windows-workflow-foundation/required-arguments-and-overload-groups.md +++ b/docs/framework/windows-workflow-foundation/required-arguments-and-overload-groups.md @@ -28,7 +28,7 @@ public sealed class Add : CodeActivity } ``` - In XAML, required arguments are also indicated by using . In this example the `Add` activity is defined by using three arguments and uses an activity to perform the add operation. + In XAML, required arguments are also indicated by using . In this example the `Add` activity is defined by using three arguments and uses an activity to perform the add operation. ```xaml diff --git a/docs/framework/windows-workflow-foundation/samples/accessing-operationcontext.md b/docs/framework/windows-workflow-foundation/samples/accessing-operationcontext.md index 25137ea5ab892..17a0a177c5849 100644 --- a/docs/framework/windows-workflow-foundation/samples/accessing-operationcontext.md +++ b/docs/framework/windows-workflow-foundation/samples/accessing-operationcontext.md @@ -6,7 +6,7 @@ ms.assetid: 4e92efe8-7e79-41f3-b50e-bdc38b9f41f8 --- # Accessing OperationContext -The [AccessingOperationContext sample](https://github.com/dotnet/samples/tree/main/framework/windows-workflow-foundation/scenario/Services/AccessingOperationContext/CS) demonstrates how the messaging activities ( and ) can be used with a custom scope activity to access and attach or retrieve a custom message header within an outgoing or incoming message. +The [AccessingOperationContext sample](https://github.com/dotnet/samples/tree/main/framework/windows-workflow-foundation/scenario/Services/AccessingOperationContext/CS) demonstrates how the messaging activities ( and ) can be used with a custom scope activity to access and attach or retrieve a custom message header within an outgoing or incoming message. ## Demonstrates @@ -14,7 +14,7 @@ The [AccessingOperationContext sample](https://github.com/dotnet/samples/tree/ma ## Discussion - This sample shows how to use extensibility points () ) in the messaging activities to access . The callbacks are registered within the workflow runtime as an implementation of that is picked up by the messaging activities upon execution. Any messaging activity in the same scope as that implementation is affected. In particular, this sample uses a custom scope activity to enforce the callback behavior. The is used in the client workflow to include the workflow's as an outgoing . This header is then picked up in the service using the and the value of the header is printed out to the console. + This sample shows how to use extensibility points () ) in the messaging activities to access . The callbacks are registered within the workflow runtime as an implementation of that is picked up by the messaging activities upon execution. Any messaging activity in the same scope as that implementation is affected. In particular, this sample uses a custom scope activity to enforce the callback behavior. The is used in the client workflow to include the workflow's as an outgoing . This header is then picked up in the service using the and the value of the header is printed out to the console. ## Set up, build, and run the sample diff --git a/docs/framework/windows-workflow-foundation/samples/activity-library.md b/docs/framework/windows-workflow-foundation/samples/activity-library.md index bf69dde5bd2ce..d0f953033f292 100644 --- a/docs/framework/windows-workflow-foundation/samples/activity-library.md +++ b/docs/framework/windows-workflow-foundation/samples/activity-library.md @@ -6,27 +6,27 @@ ms.assetid: 5323e9d4-71d6-47eb-bfa6-31feac62044d --- # Activity Library -This section contains samples that demonstrate advanced custom activities in Windows Workflow Foundation (WF). - +This section contains samples that demonstrate advanced custom activities in Windows Workflow Foundation (WF). + ## In This Section - [SendMail Custom Activity](sendmail-custom-activity.md) - Demonstrates how to create a custom activity that derives from to send mail using SMTP for use within a workflow application. - - [Throttled Parallel ForEach](throttled-parallel-foreach.md) - Demonstrates how the `ThrottleParallelForEach` activity is similar to the activity with the one exception that it allows setting a concurrency factor to restrict the number of simultaneous branches to execute. - - [Database Access Activities](database-access-activities.md) - Demonstrates how to create activities that allow accessing databases to retrieve or modify information and use [ADO.NET](../../data/adonet/index.md) to access the database. - - [Externalized Policy Activity in .NET Framework 4.5](externalized-policy-activity-in-net-framework-4-5.md) + [SendMail Custom Activity](sendmail-custom-activity.md) + Demonstrates how to create a custom activity that derives from to send mail using SMTP for use within a workflow application. + + [Throttled Parallel ForEach](throttled-parallel-foreach.md) + Demonstrates how the `ThrottleParallelForEach` activity is similar to the activity with the one exception that it allows setting a concurrency factor to restrict the number of simultaneous branches to execute. + + [Database Access Activities](database-access-activities.md) + Demonstrates how to create activities that allow accessing databases to retrieve or modify information and use [ADO.NET](../../data/adonet/index.md) to access the database. + + [Externalized Policy Activity in .NET Framework 4.5](externalized-policy-activity-in-net-framework-4-5.md) Demonstrates how the ExternalizedPolicy4 activity allows executing existing Windows Workflow Foundation in .NET Framework 3.5 (WF 3.5) objects in Windows Workflow Foundation in [!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md)] (WF 4.5) directly by using the rules engine that is shipped in WF 3.5. - - [Non-Generic ForEach](non-generic-foreach.md) - Demonstrates how to create a non-generic version of the activity. - - [Non-Generic ParallelForEach](non-generic-parallelforeach.md) - Demonstrates how to create a non-generic version of the activity. - - [Get WorkflowInstanceId](get-workflowinstanceid.md) + + [Non-Generic ForEach](non-generic-foreach.md) + Demonstrates how to create a non-generic version of the activity. + + [Non-Generic ParallelForEach](non-generic-parallelforeach.md) + Demonstrates how to create a non-generic version of the activity. + + [Get WorkflowInstanceId](get-workflowinstanceid.md) Demonstrates how to use the custom activity, `GetWorkflowInstanceId`, to return the workflow instance ID. diff --git a/docs/framework/windows-workflow-foundation/samples/corporate-purchase-process.md b/docs/framework/windows-workflow-foundation/samples/corporate-purchase-process.md index 2bff734a067d9..bc5288effd40e 100644 --- a/docs/framework/windows-workflow-foundation/samples/corporate-purchase-process.md +++ b/docs/framework/windows-workflow-foundation/samples/corporate-purchase-process.md @@ -6,7 +6,7 @@ ms.assetid: a5e57336-4290-41ea-936d-435593d97055 --- # Corporate Purchase Process -The [PurchaseProcess sample](https://github.com/dotnet/samples/tree/main/framework/windows-workflow-foundation/application/PurchaseProcess) shows how to create a very basic Request for Proposals (RFP) based purchase process with automatic best proposal selection. It combines , , and and a custom activity to create a workflow that represents the process. +The [PurchaseProcess sample](https://github.com/dotnet/samples/tree/main/framework/windows-workflow-foundation/application/PurchaseProcess) shows how to create a very basic Request for Proposals (RFP) based purchase process with automatic best proposal selection. It combines , , and and a custom activity to create a workflow that represents the process. This sample contains an ASP.NET client application that allows interacting with the process as different participants (as the original requester or a particular vendor). @@ -54,7 +54,7 @@ The [PurchaseProcess sample](https://github.com/dotnet/samples/tree/main/framewo ## Process Definition - The core logic of the sample uses a activity that waits for the offers from each vendor (using a custom activity that creates a bookmark), and registers the vendor proposal as an RFP (using an activity). + The core logic of the sample uses a activity that waits for the offers from each vendor (using a custom activity that creates a bookmark), and registers the vendor proposal as an RFP (using an activity). The sample then iterates through all of the received proposals stored in the `RfpRepository`, calculating the adjusted value (using an activity and activities), and if the adjusted value is better than the previous best offer, assigns the new value as the best offer (using and activities). @@ -78,7 +78,7 @@ The [PurchaseProcess sample](https://github.com/dotnet/samples/tree/main/framewo |IPurchaseProcessHost.cs|Interface for the host of the workflow.| |PurchaseProcessHost.cs|Implementation of a host for the workflow. The host abstracts the details of the workflow runtime and is used in all the client applications to load, run, and interact with `PurchaseProcess` workflow instances.| |PurchaseProcessWorkflow.cs|An activity that contains the definition of the Purchase Process workflow (derives from ).

Activities that derive from compose functionality by assembling existing custom activities and activities from the [!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md)] activity library. Assembling these activities is the most basic way to create custom functionality.| -|WaitForVendorProposal.cs|This custom activity derives from and creates a named bookmark that must be resumed later by a vendor when submitting the proposal.

Activities that derive from , like those that derive from , create imperative functionality by overriding , but also have access to all of the functionality of the workflow runtime through the that gets passed into the `Execute` method. This context has support for scheduling and canceling child activities, setting up no-persist zones (execution blocks during which the runtime does not persist the workflow's data, such as within atomic transactions), and objects (handles for resuming paused workflows).| +|WaitForVendorProposal.cs|This custom activity derives from and creates a named bookmark that must be resumed later by a vendor when submitting the proposal.

Activities that derive from , like those that derive from , create imperative functionality by overriding , but also have access to all of the functionality of the workflow runtime through the that gets passed into the `Execute` method. This context has support for scheduling and canceling child activities, setting up no-persist zones (execution blocks during which the runtime does not persist the workflow's data, such as within atomic transactions), and objects (handles for resuming paused workflows).| |TrackingParticipant.cs|A that receives all tracking events and saves them to a text file.

Tracking participants are added to workflow instance as Extensions.| |XmlWorkflowInstanceStore.cs|A custom that saves workflow applications to XML files.| |XmlPersistenceParticipant.cs|A custom that saves an instance of request for proposal to an XML file.| @@ -121,13 +121,13 @@ The [PurchaseProcess sample](https://github.com/dotnet/samples/tree/main/framewo ### Persistence Files - The following table shows the files generated by the persistence provider (`XmlPersistenceProvider`) are located in the path of the current system's temporary folder (using ). The tracing file is created in the current execution path. + The following table shows the files generated by the persistence provider (`XmlPersistenceProvider`) are located in the path of the current system's temporary folder (using ). The tracing file is created in the current execution path. |File Name|Description|Path| |-|-|-| -|rfps.xml|The XML file with all the active and finished Requests for Proposals.|| -|[instanceid]|This file contains all the information about a workflow instance.

This file is generated by the schematized persistence implementation (PersistenceParticipant in XmlPersistenceProvider).|| -|[instanceId].tracking|A text file with all the events that occurred within a concrete instance.

This file is generated by TrackingParticipant.|| +|rfps.xml|The XML file with all the active and finished Requests for Proposals.|| +|[instanceid]|This file contains all the information about a workflow instance.

This file is generated by the schematized persistence implementation (PersistenceParticipant in XmlPersistenceProvider).|| +|[instanceId].tracking|A text file with all the events that occurred within a concrete instance.

This file is generated by TrackingParticipant.|| |PurchaseProcess.Tracing.TraceLog.txt|The tracing file generated by the workflow based on the configuration parameters in the App.config or Web.config files.|Current execution path| ## To use this sample diff --git a/docs/framework/windows-workflow-foundation/samples/creating-and-running-a-workflow-instance.md b/docs/framework/windows-workflow-foundation/samples/creating-and-running-a-workflow-instance.md index 93e674bd06808..268d6bf3133bf 100644 --- a/docs/framework/windows-workflow-foundation/samples/creating-and-running-a-workflow-instance.md +++ b/docs/framework/windows-workflow-foundation/samples/creating-and-running-a-workflow-instance.md @@ -14,7 +14,7 @@ The [CreatingWorkflowInstances sample](https://github.com/dotnet/samples/tree/ma ## Discussion -The first part of the sample uses . This is the most basic way to execute a workflow. Workflows executed with are executed synchronously. +The first part of the sample uses . This is the most basic way to execute a workflow. Workflows executed with are executed synchronously. The second part of the sample uses the class. enables you to have more control over each instance, including the ability to interact with the running workflow and to run the workflow asynchronously. diff --git a/docs/framework/windows-workflow-foundation/samples/custom-composite-using-native-activity.md b/docs/framework/windows-workflow-foundation/samples/custom-composite-using-native-activity.md index d55b095cfe203..2cd8a4c383696 100644 --- a/docs/framework/windows-workflow-foundation/samples/custom-composite-using-native-activity.md +++ b/docs/framework/windows-workflow-foundation/samples/custom-composite-using-native-activity.md @@ -12,17 +12,17 @@ The [CustomCompositeNativeActivity sample](https://github.com/dotnet/samples/tre Starting with `MySequence`, the first thing to notice is that it derives from . is the object that exposes the full breadth of the workflow runtime through the passed to the `Execute` method. - `MySequence` exposes a public collection of objects that gets populated by the workflow author. Before the workflow is executed, the workflow runtime calls the method on each activity in a workflow. During this process, the runtime establishes parent-child relationships for data scoping and lifetime management. The default implementation of the method uses the instance class for the `MySequence` activity to add any public property of type or \<> as children of the `MySequence` activity. + `MySequence` exposes a public collection of objects that gets populated by the workflow author. Before the workflow is executed, the workflow runtime calls the method on each activity in a workflow. During this process, the runtime establishes parent-child relationships for data scoping and lifetime management. The default implementation of the method uses the instance class for the `MySequence` activity to add any public property of type or \<> as children of the `MySequence` activity. - Whenever an activity exposes a public collection of child activities, it is likely those child activities share state. It is a best practice for the parent activity, in this case `MySequence`, to also expose a collection of variables through which the child activities can accomplish this. Like child activities, the method adds public properties of type or \<> as variables associated with the `MySequence` activity. + Whenever an activity exposes a public collection of child activities, it is likely those child activities share state. It is a best practice for the parent activity, in this case `MySequence`, to also expose a collection of variables through which the child activities can accomplish this. Like child activities, the method adds public properties of type or \<> as variables associated with the `MySequence` activity. - Besides the public variables, which are manipulated by the children of `MySequence`, `MySequence` must also keep track of where it is in the execution of its children. It uses a private variable, `currentIndex`, to accomplish this. This variable is registered as part of the `MySequence` environment by adding a call to the method within the `MySequence` activity's method. The objects added to the `MySequence` `Activities` collection cannot access variables added this way. + Besides the public variables, which are manipulated by the children of `MySequence`, `MySequence` must also keep track of where it is in the execution of its children. It uses a private variable, `currentIndex`, to accomplish this. This variable is registered as part of the `MySequence` environment by adding a call to the method within the `MySequence` activity's method. The objects added to the `MySequence` `Activities` collection cannot access variables added this way. - When `MySequence` is executed by the runtime, the runtime calls its method, passing in an . The is the activity's proxy back into the runtime for dereferencing arguments and variables as well as scheduling other objects, or `ActivityDelegates`. `MySequence` uses an `InternalExecute` method to encapsulate the logic of scheduling the first child and all subsequent children in a single method. It starts by dereferencing the `currentIndex`. If it is equal to the count in the `Activities` collection, then the sequence is finished, the activity returns without scheduling any work and the runtime moves it into the state. If the `currentIndex` is less than the count of activities, the next child is obtained from the `Activities` collection and `MySequence` calls , passing in the child to be scheduled and a that points at the `InternalExecute` method. Finally, the `currentIndex` is incremented and control is yielded back to the runtime. As long as an instance of `MySequence` has a child object scheduled, the runtime considers it to be in the Executing state. + When `MySequence` is executed by the runtime, the runtime calls its method, passing in an . The is the activity's proxy back into the runtime for dereferencing arguments and variables as well as scheduling other objects, or `ActivityDelegates`. `MySequence` uses an `InternalExecute` method to encapsulate the logic of scheduling the first child and all subsequent children in a single method. It starts by dereferencing the `currentIndex`. If it is equal to the count in the `Activities` collection, then the sequence is finished, the activity returns without scheduling any work and the runtime moves it into the state. If the `currentIndex` is less than the count of activities, the next child is obtained from the `Activities` collection and `MySequence` calls , passing in the child to be scheduled and a that points at the `InternalExecute` method. Finally, the `currentIndex` is incremented and control is yielded back to the runtime. As long as an instance of `MySequence` has a child object scheduled, the runtime considers it to be in the Executing state. When the child activity completes, the is executed. The loop continues from the top. Like `Execute`, a takes an , giving the implementer access to the runtime. - `MyWhile` differs from `MySequence` in that it schedules a single object repeatedly, and in that it uses a named `Condition` to determine whether this scheduling should occur. Like `MySequence`, `MyWhile` uses an `InternalExecute` method to centralize its scheduling logic. It schedules the `Condition` with a \ named `OnEvaluationCompleted`. When the execution of `Condition` is completed, its result becomes available through this in a strongly typed parameter named `result`. If `true`, `MyWhile` calls , passing in the `Body` object and `InternalExecute` as the . When the execution of `Body` completes, `Condition` gets scheduled again in `InternalExecute`, starting the loop over again. When the `Condition` returns `false`, an instance of `MyWhile` gives control back to the runtime without scheduling the `Body` and the runtime moves it to the state. + `MyWhile` differs from `MySequence` in that it schedules a single object repeatedly, and in that it uses a named `Condition` to determine whether this scheduling should occur. Like `MySequence`, `MyWhile` uses an `InternalExecute` method to centralize its scheduling logic. It schedules the `Condition` with a \ named `OnEvaluationCompleted`. When the execution of `Condition` is completed, its result becomes available through this in a strongly typed parameter named `result`. If `true`, `MyWhile` calls , passing in the `Body` object and `InternalExecute` as the . When the execution of `Body` completes, `Condition` gets scheduled again in `InternalExecute`, starting the loop over again. When the `Condition` returns `false`, an instance of `MyWhile` gives control back to the runtime without scheduling the `Body` and the runtime moves it to the state. #### To set up, build, and run the sample diff --git a/docs/framework/windows-workflow-foundation/samples/custom-tracking.md b/docs/framework/windows-workflow-foundation/samples/custom-tracking.md index 685b1e0c97580..f9baed04c48d4 100644 --- a/docs/framework/windows-workflow-foundation/samples/custom-tracking.md +++ b/docs/framework/windows-workflow-foundation/samples/custom-tracking.md @@ -33,7 +33,7 @@ The [CustomTracking sample](https://github.com/dotnet/samples/tree/main/framewor The tracking participant API allows extension of the tracking runtime with a user provided tracking participant that can include custom logic to handle objects emitted by the workflow runtime. - To write a tracking participant the user must implement . Specifically, the method has to be implemented by the custom participant. This method is called when a is emitted by the workflow runtime. + To write a tracking participant the user must implement . Specifically, the method has to be implemented by the custom participant. This method is called when a is emitted by the workflow runtime. ```csharp public abstract class TrackingParticipant @@ -45,7 +45,7 @@ public abstract class TrackingParticipant } ``` - The complete tracking participant is implemented in the ConsoleTrackingParticipant.cs file. The following code example is the method for the custom tracking participant. + The complete tracking participant is implemented in the ConsoleTrackingParticipant.cs file. The following code example is the method for the custom tracking participant. ```csharp protected override void Track(TrackingRecord record, TimeSpan timeout) diff --git a/docs/framework/windows-workflow-foundation/samples/database-access-activities.md b/docs/framework/windows-workflow-foundation/samples/database-access-activities.md index fe6cb7bf24f09..c08c54ec0ca5d 100644 --- a/docs/framework/windows-workflow-foundation/samples/database-access-activities.md +++ b/docs/framework/windows-workflow-foundation/samples/database-access-activities.md @@ -75,7 +75,7 @@ Public class DbUpdate: AsyncCodeActivity Executes a query that retrieves a single value from the database. -This class performs its work asynchronously (it derives from and uses its asynchronous capabilities). +This class performs its work asynchronously (it derives from and uses its asynchronous capabilities). The connection information can be configured by setting a provider invariant name (`ProviderName`) and the connection string (`ConnectionString`) or just using a connection string configuration name (`ConfigFileSectionName`) from the application configuration file. @@ -83,7 +83,7 @@ The connection information can be configured by setting a provider invariant nam The query to be executed is configured in its `Sql` property and the parameters are passed through the `Parameters` collection. -After `DbQueryScalar` is executed, the scalar is returned in the `Result out` argument (of type `TResult`, that is defined in the base class ). +After `DbQueryScalar` is executed, the scalar is returned in the `Result out` argument (of type `TResult`, that is defined in the base class ). ```csharp public class DbQueryScalar : AsyncCodeActivity @@ -131,7 +131,7 @@ public class DbQueryScalar : AsyncCodeActivity ## DbQuery -Executes a query that retrieves a list of objects. After the query is executed, a mapping function is executed (it can be <`DbDataReader`, `TResult`> or an <`DbDataReader`, `TResult`>). This mapping function gets a record in a `DbDataReader` and maps it to the object to be returned. +Executes a query that retrieves a list of objects. After the query is executed, a mapping function is executed (it can be <`DbDataReader`, `TResult`> or an <`DbDataReader`, `TResult`>). This mapping function gets a record in a `DbDataReader` and maps it to the object to be returned. The connection information can be configured by setting a provider invariant name (`ProviderName`) and the connection string (`ConnectionString`) or just using a connection string configuration name (`ConfigFileSectionName`) from the application configuration file. @@ -139,7 +139,7 @@ The connection information can be configured by setting a provider invariant nam The query to be executed is configured in its `Sql` property and the parameters are passed through the `Parameters` collection. -The results of the SQL query are retrieved using a `DbDataReader`. The activity iterates through the `DbDataReader` and maps the rows in the `DbDataReader` to an instance of `TResult`. The user of `DbQuery` has to provide the mapping code and this can be done in two ways: using a <`DbDataReader`, `TResult`> or an <`DbDataReader`, `TResult`>. In the first case, the map is done in a single pulse of execution. Therefore, it is faster, but this cannot be serialized to XAML. In the last case, the map is performed in multiple pulses. Therefore, it might be slower but can be serialized to XAML and authored declaratively (any existing activity can participate in the mapping). +The results of the SQL query are retrieved using a `DbDataReader`. The activity iterates through the `DbDataReader` and maps the rows in the `DbDataReader` to an instance of `TResult`. The user of `DbQuery` has to provide the mapping code and this can be done in two ways: using a <`DbDataReader`, `TResult`> or an <`DbDataReader`, `TResult`>. In the first case, the map is done in a single pulse of execution. Therefore, it is faster, but this cannot be serialized to XAML. In the last case, the map is performed in multiple pulses. Therefore, it might be slower but can be serialized to XAML and authored declaratively (any existing activity can participate in the mapping). ```csharp public class DbQuery : AsyncCodeActivity> where TResult : class @@ -189,8 +189,8 @@ public class DbQuery : AsyncCodeActivity> where TResult | ConfigName | Name of the configuration file section where the connection information is stored. When this argument is set `ProviderName` and `ConnectionString` are not required. | | Sql | The SQL command to be executed. | | Parameters | Collection of the parameters of the SQL query. | -| Mapper | Mapping function (<`DbDataReader`, `TResult`>) that takes a record in the `DataReader` obtained as result of executing the query and returns an instance of an object of type `TResult` to be added to the `Result` collection.

In this case, mapping is done in a single pulse of execution, but it cannot be authored declaratively using the designer. | -| MapperFunc | Mapping function (<`DbDataReader`, `TResult`>) that takes a record in the `DataReader` obtained as result of executing the query and returns an instance of an object of type `TResult` to be added to the `Result` collection.

In this case, the mapping is done in multiple pulses of execution. This function can be serialized to XAML and authored declaratively (any existing activity can participate in the mapping). | +| Mapper | Mapping function (<`DbDataReader`, `TResult`>) that takes a record in the `DataReader` obtained as result of executing the query and returns an instance of an object of type `TResult` to be added to the `Result` collection.

In this case, mapping is done in a single pulse of execution, but it cannot be authored declaratively using the designer. | +| MapperFunc | Mapping function (<`DbDataReader`, `TResult`>) that takes a record in the `DataReader` obtained as result of executing the query and returns an instance of an object of type `TResult` to be added to the `Result` collection.

In this case, the mapping is done in multiple pulses of execution. This function can be serialized to XAML and authored declaratively (any existing activity can participate in the mapping). | | Result | List of objects obtained as result of executing the query and executing the mapping function for each record in the `DataReader`. | [!INCLUDE [managed-identities](../../../includes/managed-identities.md)] @@ -205,7 +205,7 @@ The connection information can be configured by setting a provider invariant nam The query to be executed is configured in its `Sql` property and the parameters are passed through the `Parameters` collection. -After the `DbQueryDataSet` is executed the `DataSet` is returned in the `Result out` argument (of type `TResult`, that is defined in the base class ). +After the `DbQueryDataSet` is executed the `DataSet` is returned in the `Result out` argument (of type `TResult`, that is defined in the base class ). ```csharp public class DbQueryDataSet : AsyncCodeActivity diff --git a/docs/framework/windows-workflow-foundation/samples/designer-rehosting.md b/docs/framework/windows-workflow-foundation/samples/designer-rehosting.md index 777c15050c6c2..0ee1709c1c594 100644 --- a/docs/framework/windows-workflow-foundation/samples/designer-rehosting.md +++ b/docs/framework/windows-workflow-foundation/samples/designer-rehosting.md @@ -37,7 +37,7 @@ Designer rehosting is a common scenario that refers to hosting the workflow desi ``` - Next the sample creates the designer, and associates its primary and with the appropriate container in the user interface. There are a few additional lines of code in the following example that merit some explanation. The call is required to associate the default activity designers for the activities shipped with .NET Framework. is called to pass in the WF item to be edited. Finally, the (primary canvas) and (property grid) are placed onto the user interface surface. + Next the sample creates the designer, and associates its primary and with the appropriate container in the user interface. There are a few additional lines of code in the following example that merit some explanation. The call is required to associate the default activity designers for the activities shipped with .NET Framework. is called to pass in the WF item to be edited. Finally, the (primary canvas) and (property grid) are placed onto the user interface surface. ```csharp protected override void OnInitialized(EventArgs e) diff --git a/docs/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch.md b/docs/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch.md index 222cb7292e582..6bb9de9c47975 100644 --- a/docs/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch.md +++ b/docs/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch.md @@ -17,7 +17,7 @@ The following table details the variables for the `CreateFlowchartWithFaults` ac |promoCode|The promotion code. Type: String

The possible values with description in parentheses:

- Single (Single)
- MNK (Married with no kids.)
- MWK (Married with kids.)| |numKids|The number of children. Type: int| -The `CreateFlowchartWithFaults` activity uses a activity that switches on the `promoCode` argument and calculates the discount using the following formula. +The `CreateFlowchartWithFaults` activity uses a activity that switches on the `promoCode` argument and calculates the discount using the following formula. |Value of `promoCode`|Discount (%)| |--------------------------|--------------------| diff --git a/docs/framework/windows-workflow-foundation/samples/get-workflowinstanceid.md b/docs/framework/windows-workflow-foundation/samples/get-workflowinstanceid.md index d7e3efccb652c..cd08da50e7977 100644 --- a/docs/framework/windows-workflow-foundation/samples/get-workflowinstanceid.md +++ b/docs/framework/windows-workflow-foundation/samples/get-workflowinstanceid.md @@ -16,7 +16,7 @@ The [GetWorkflowInstanceId sample](https://github.com/dotnet/samples/tree/main/f Getting the instance ID of a running workflow requires writing code. If you want to write a fully-declarative workflow, then you need an activity that can return the workflow instance ID so that the activity can be referenced in the workflow to provide a fully-declarative workflow authoring experience. Many scenarios require access to the instance ID: a few examples are for logging or auditing purposes or for doing application-level correlation by providing the instance ID back to a client for future association (for example, by using this activity inside a SendReply activity). - `GetWorkflowInstanceId` is implemented as a because it must return a value of type , and it must have access to the for getting the workflow's instance ID. Its implementation is fairly basic. + `GetWorkflowInstanceId` is implemented as a because it must return a value of type , and it must have access to the for getting the workflow's instance ID. Its implementation is fairly basic. ```csharp public sealed class GetWorkflowInstanceId : CodeActivity diff --git a/docs/framework/windows-workflow-foundation/samples/hiring-process.md b/docs/framework/windows-workflow-foundation/samples/hiring-process.md index 817c7298722de..004944594490a 100644 --- a/docs/framework/windows-workflow-foundation/samples/hiring-process.md +++ b/docs/framework/windows-workflow-foundation/samples/hiring-process.md @@ -104,12 +104,12 @@ The [HiringProcess sample](https://github.com/dotnet/samples/tree/main/framework |Workflow services|The Flowchart with the process definition is hosted in a service (in this example, the service is hosted in a console application).|HiringRequestService| |Messaging activities|The flowchart uses messaging activities in two ways:

- To get information from the user (to receive the decisions and related information in each approval step).
- To interact with other existing services (InboxService and OrgDataService, used through service references).|HiringRequestService| |Content-based correlation|Approval messages correlate on the ID property of the hiring request:

- When a process is started, the correlation handle is initialized with the ID of the request.
- Incoming approval messages correlate on their ID (the first parameter of each approval message is the ID of the request).|HiringRequestService / ResumeRequestService| -|Custom activities (declarative and code based)|There are several custom activities in this sample:

- `SaveActionTracking`: This activity emits a custom (using ). This activity has been authored using imperative code extending .
- `GetEmployeesByPositionTypes`: This activity receives a list of position type IDs and returns a list of people that have that position in Contoso. This activity has been authored declaratively (using the activity designer).
- `SaveHiringRequestInfo`: This activity saves the information of a `HiringRequest` (using `HiringRequestRepository.Save`). This activity has been authored using imperative code extending .|HiringRequestService| +|Custom activities (declarative and code based)|There are several custom activities in this sample:

- `SaveActionTracking`: This activity emits a custom (using ). This activity has been authored using imperative code extending .
- `GetEmployeesByPositionTypes`: This activity receives a list of position type IDs and returns a list of people that have that position in Contoso. This activity has been authored declaratively (using the activity designer).
- `SaveHiringRequestInfo`: This activity saves the information of a `HiringRequest` (using `HiringRequestRepository.Save`). This activity has been authored using imperative code extending .|HiringRequestService| |System-provided SQL Server Persistence|The instance that hosts the Flowchart process definition is configured to use the system-provided SQL Server persistence.|HiringRequestService / ResumeRequestService| |Custom Tracking|The sample includes a custom tracking participant that saves the history of a `HiringRequestProcess` (this records what action has been done, by whom, and when). The source code is in the Tracking folder of HiringRequestService.|HiringRequestService| |ETW Tracking|System-provided ETW Tracking is configured in the App.config file in the HiringRequestService service.|HiringRequestService| |Composition of Activities|The process definition uses the free composition of . The Flowchart contains several Sequence and Parallel activities that at the same time contain other activities (and so on).|HiringRequestService| -|Parallel Activities|- is used to register in the Inbox of the CEO and HR Managers in parallel (Waiting for two HR Managers' Approval step).
- is used to do some clean-up tasks in the Completed and Rejected steps|HiringRequestService| +|Parallel Activities|- is used to register in the Inbox of the CEO and HR Managers in parallel (Waiting for two HR Managers' Approval step).
- is used to do some clean-up tasks in the Completed and Rejected steps|HiringRequestService| |Model Cancellation|The Flowchart uses to create cancellation behavior (in this case it does some clean-up.)|HiringRequestService| |Customer Persistence Participant|`HiringRequestPersistenceParticipant` saves data from a workflow variable to a table stored in the Contoso HR database.|HiringRequestService| |Workflow Services|`ResumeRequestService` is implemented using workflow services. Workflow definition and service information are contained in ResumeRequestService.xamlx. The service is configured to use persistence and tracking.|ResumeRequestService| diff --git a/docs/framework/windows-workflow-foundation/samples/load-from-xaml.md b/docs/framework/windows-workflow-foundation/samples/load-from-xaml.md index 137fc87a60dda..4a31d9dba6094 100644 --- a/docs/framework/windows-workflow-foundation/samples/load-from-xaml.md +++ b/docs/framework/windows-workflow-foundation/samples/load-from-xaml.md @@ -6,7 +6,7 @@ ms.assetid: 1f103ef6-7bed-4f16-ae52-9e665c5a43d7 --- # Load From XAML -The [LoadFromXAML sample](https://github.com/dotnet/samples/tree/main/framework/windows-workflow-foundation/basic/Built-InActivities/LoadFromXAML/CS) demonstrates how to dynamically load a XAML workflow without having to run the XamlBuildTask tool. Instead, the sample calls the method. The sample is a Windows Presentation Foundation (WPF) client application that loads XAML workflows using the class and executes them. After they have been loaded using the class, a is returned that can be executed. +The [LoadFromXAML sample](https://github.com/dotnet/samples/tree/main/framework/windows-workflow-foundation/basic/Built-InActivities/LoadFromXAML/CS) demonstrates how to dynamically load a XAML workflow without having to run the XamlBuildTask tool. Instead, the sample calls the method. The sample is a Windows Presentation Foundation (WPF) client application that loads XAML workflows using the class and executes them. After they have been loaded using the class, a is returned that can be executed. ## To use this sample diff --git a/docs/framework/windows-workflow-foundation/samples/non-generic-foreach.md b/docs/framework/windows-workflow-foundation/samples/non-generic-foreach.md index d6b52dfbfaefb..a1a3bf8172cc4 100644 --- a/docs/framework/windows-workflow-foundation/samples/non-generic-foreach.md +++ b/docs/framework/windows-workflow-foundation/samples/non-generic-foreach.md @@ -6,15 +6,15 @@ ms.assetid: 576cd07a-d58d-4536-b514-77bad60bff38 --- # Non-Generic ForEach -[!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md)] ships in its toolbox a set of Control Flow activities, including , which allows iterating through collections. +[!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md)] ships in its toolbox a set of Control Flow activities, including , which allows iterating through collections. - requires its property to be of type . This precludes users from iterating over data structures that implement interface (for example, ). The non-generic version of overcomes this requirement, at the expense of more runtime complexity for ensuring the compatibility of the types of the values in the collection. + requires its property to be of type . This precludes users from iterating over data structures that implement interface (for example, ). The non-generic version of overcomes this requirement, at the expense of more runtime complexity for ensuring the compatibility of the types of the values in the collection. - The [NonGenericForEach sample](https://github.com/dotnet/samples/tree/main/framework/windows-workflow-foundation/scenario/ActivityLibrary/NonGenericForEach/CS) shows how to implement a non-generic activity and its designer. This activity can be used to iterate through . + The [NonGenericForEach sample](https://github.com/dotnet/samples/tree/main/framework/windows-workflow-foundation/scenario/ActivityLibrary/NonGenericForEach/CS) shows how to implement a non-generic activity and its designer. This activity can be used to iterate through . ## ForEach Activity - The C#/Visual Basic `foreach` statement enumerates the elements of a collection, executing an embedded statement for each element of the collection. The WF equivalent activities of `foreach` are and . The activity contains a list of values and a body. At runtime, the list is iterated and the body is executed for each value in the list. + The C#/Visual Basic `foreach` statement enumerates the elements of a collection, executing an embedded statement for each element of the collection. The WF equivalent activities of `foreach` are and . The activity contains a list of values and a body. At runtime, the list is iterated and the body is executed for each value in the list. For most cases, the generic version of the activity should be the preferred solution, because it covers most of the scenarios in which it would be used, and provides type checking at compile time. The non-generic version can be used for iterating through types that implement the non-generic interface. @@ -72,7 +72,7 @@ Activity sampleUsage = ## ForEach Designer - The activity designer for the sample is similar in appearance to the designer provided for the built-in activity. The designer appears in the toolbox in the **Samples**, **Non-Generic Activities** category. The designer is named **ForEachWithBodyFactory** in the toolbox, because the activity exposes an in the toolbox, which creates the activity with a properly configured . + The activity designer for the sample is similar in appearance to the designer provided for the built-in activity. The designer appears in the toolbox in the **Samples**, **Non-Generic Activities** category. The designer is named **ForEachWithBodyFactory** in the toolbox, because the activity exposes an in the toolbox, which creates the activity with a properly configured . ```csharp public sealed class ForEachWithBodyFactory : IActivityTemplateFactory diff --git a/docs/framework/windows-workflow-foundation/samples/non-generic-parallelforeach.md b/docs/framework/windows-workflow-foundation/samples/non-generic-parallelforeach.md index 7490620dcd0de..58b576cf9a201 100644 --- a/docs/framework/windows-workflow-foundation/samples/non-generic-parallelforeach.md +++ b/docs/framework/windows-workflow-foundation/samples/non-generic-parallelforeach.md @@ -6,17 +6,17 @@ ms.assetid: de17e7a2-257b-48b3-91a1-860e2e9bf6e6 --- # Non-generic ParallelForEach -[!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md)] ships in its toolbox a set of Control Flow activities, including , which allows iterating through collections. +[!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md)] ships in its toolbox a set of Control Flow activities, including , which allows iterating through collections. - requires its property to be of type . This precludes users from iterating over data structures that implement interface (for example, ). The non-generic version of overcomes this requirement, at the expense of more runtime complexity for ensuring the compatibility of the types of the values in the collection. + requires its property to be of type . This precludes users from iterating over data structures that implement interface (for example, ). The non-generic version of overcomes this requirement, at the expense of more runtime complexity for ensuring the compatibility of the types of the values in the collection. -The [NonGenericParallelForEach sample](https://github.com/dotnet/samples/tree/main/framework/windows-workflow-foundation/scenario/ActivityLibrary/NonGenericParallelForEach/CS) shows how to implement a non-generic activity and its designer. This activity can be used to iterate through . +The [NonGenericParallelForEach sample](https://github.com/dotnet/samples/tree/main/framework/windows-workflow-foundation/scenario/ActivityLibrary/NonGenericParallelForEach/CS) shows how to implement a non-generic activity and its designer. This activity can be used to iterate through . ## ParallelForEach activity -The C#/Visual Basic `foreach` statement enumerates the elements of a collection, executing an embedded statement for each element of the collection. The WF equivalent activities are and . The activity contains a list of values and a body. At runtime, the list is iterated and the body is executed for each value in the list. +The C#/Visual Basic `foreach` statement enumerates the elements of a collection, executing an embedded statement for each element of the collection. The WF equivalent activities are and . The activity contains a list of values and a body. At runtime, the list is iterated and the body is executed for each value in the list. - has a , so that the activity could complete early if the evaluation of the returns `true`. The is evaluated after each iteration is completed. + has a , so that the activity could complete early if the evaluation of the returns `true`. The is evaluated after each iteration is completed. For most cases, the generic version of the activity should be the preferred solution, because it covers most of the scenarios in which it is used and provides type checking at compile time. The non-generic version can be used for iterating through types that implement the non-generic interface. @@ -48,7 +48,7 @@ Values (optional)\ The collection of elements that are iterated over. Ensuring that all elements of the collection are of compatible types is done at runtime. CompletionCondition (optional)\ -The property is evaluated after any iteration completes. If it evaluates to `true`, then the scheduled pending iterations are canceled. If this property is not set, all activities in the Branches collection execute until completion. +The property is evaluated after any iteration completes. If it evaluates to `true`, then the scheduled pending iterations are canceled. If this property is not set, all activities in the Branches collection execute until completion. ## Example of using ParallelForEach @@ -76,7 +76,7 @@ Activity sampleUsage = ## ParallelForEach designer -The activity designer for the sample is similar in appearance to the designer provided for the built-in activity. The designer appears in the toolbox in the **Samples**, **Non-Generic Activities** category. The designer is named **ParallelForEachWithBodyFactory** in the toolbox, because the activity exposes an in the toolbox that creates the activity with a properly configured . +The activity designer for the sample is similar in appearance to the designer provided for the built-in activity. The designer appears in the toolbox in the **Samples**, **Non-Generic Activities** category. The designer is named **ParallelForEachWithBodyFactory** in the toolbox, because the activity exposes an in the toolbox that creates the activity with a properly configured . ```csharp public sealed class ParallelForEachWithBodyFactory : IActivityTemplateFactory diff --git a/docs/framework/windows-workflow-foundation/samples/property-grid-extensibility.md b/docs/framework/windows-workflow-foundation/samples/property-grid-extensibility.md index 6012ef0ce547c..e53be3a53d8b5 100644 --- a/docs/framework/windows-workflow-foundation/samples/property-grid-extensibility.md +++ b/docs/framework/windows-workflow-foundation/samples/property-grid-extensibility.md @@ -22,7 +22,7 @@ The inline editor sample demonstrates the following: - Creates a type that derives from . -- In the constructor, the value is set with a Windows Presentation Foundation (WPF) data template. This can be bound to a XAML template, but in this sample, code is used to initialize data binding. +- In the constructor, the value is set with a Windows Presentation Foundation (WPF) data template. This can be bound to a XAML template, but in this sample, code is used to initialize data binding. - The data template has a data context of the of the item rendered in the property grid. Note in the following code (from CustomInlineEditor.cs) that this context then binds to the `Value` property. @@ -55,7 +55,7 @@ The dialog editor sample demonstrates the following: 1. Creates a type that derives from . -2. Sets the value in the constructor with a WPF data template. This can be created in XAML, but in this sample, this is created in code. +2. Sets the value in the constructor with a WPF data template. This can be created in XAML, but in this sample, this is created in code. 3. The data template has a data context of the of the item rendered in the property grid. In the following code, this then binds to the `Value` property. It is critical to also include an to provide the button that raises the dialog in FilePickerEditor.cs. @@ -80,7 +80,7 @@ The dialog editor sample demonstrates the following: this.InlineEditorTemplate.VisualTree = stack; ``` -4. Overrides the method in the designer type to handle the display of the dialog. In this sample, a basic is shown. +4. Overrides the method in the designer type to handle the display of the dialog. In this sample, a basic is shown. ```csharp public override void ShowDialog(PropertyValue propertyValue, IInputElement commandSource) diff --git a/docs/framework/windows-workflow-foundation/samples/sendmail-custom-activity.md b/docs/framework/windows-workflow-foundation/samples/sendmail-custom-activity.md index d57aa948bf2dc..80088a9389e20 100644 --- a/docs/framework/windows-workflow-foundation/samples/sendmail-custom-activity.md +++ b/docs/framework/windows-workflow-foundation/samples/sendmail-custom-activity.md @@ -15,16 +15,16 @@ The [SendMail sample](https://github.com/dotnet/samples/tree/main/framework/wind |Host|String|Address of the SMTP server host.| |Port|String|Port of the SMTP service in the host.| |EnableSsl|bool|Specifies whether the uses Secure Sockets Layer (SSL) to encrypt the connection.| -|UserName|String|Username to set up the credentials to authenticate the sender property.| -|Password|String|Password to set up the credentials to authenticate the sender property.| -|Subject|\|Subject of the message.| -|Body|\|Body of the message.| -|Attachments|\|Attachment collection used to store data attached to this email message.| +|UserName|String|Username to set up the credentials to authenticate the sender property.| +|Password|String|Password to set up the credentials to authenticate the sender property.| +|Subject|\|Subject of the message.| +|Body|\|Body of the message.| +|Attachments|\|Attachment collection used to store data attached to this email message.| |From||From address for this email message.| -|To|\<>|Address collection that contains the recipients of this email message.| -|CC|\<>|Address collection that contains the carbon copy (CC) recipients for this email message.| -|BCC|\<>|Address collection that contains the blind carbon copy (BCC) recipients for this email message.| -|Tokens|>|Tokens to replace in the body. This feature allows users to specify some values in the body than can be replaced later by the tokens provided using this property.| +|To|\<>|Address collection that contains the recipients of this email message.| +|CC|\<>|Address collection that contains the carbon copy (CC) recipients for this email message.| +|BCC|\<>|Address collection that contains the blind carbon copy (BCC) recipients for this email message.| +|Tokens|>|Tokens to replace in the body. This feature allows users to specify some values in the body than can be replaced later by the tokens provided using this property.| |BodyTemplateFilePath|String|Path of a template for the body. The `SendMail` activity copies the contents of this file to its body property.

The template can contain tokens that are replaced by the contents of the tokens property.| |TestMailTo||When this property is set, all emails are sent to the address specified in it.

This property is intended to be used when testing workflows. For example, when you want to make sure that all emails are sent without sending them to the actual recipients.| |TestDropPath|String|When this property is set, all emails are also saved in the specified file.

This property is intended to be used when you are testing or debugging workflows, to make sure that the format and contents of the outgoing emails is appropriate.| diff --git a/docs/framework/windows-workflow-foundation/samples/throttled-parallel-foreach.md b/docs/framework/windows-workflow-foundation/samples/throttled-parallel-foreach.md index df0ed0e3c57a9..af5f4d3d43f2e 100644 --- a/docs/framework/windows-workflow-foundation/samples/throttled-parallel-foreach.md +++ b/docs/framework/windows-workflow-foundation/samples/throttled-parallel-foreach.md @@ -6,7 +6,7 @@ ms.assetid: f2855b5f-e9a7-433d-96a4-40fc31025215 --- # Throttled Parallel ForEach -The `ThrottleParallelForEach` activity is similar to the activity with the one exception that it allows setting a concurrency factor to restrict the number of simultaneous branches to execute. The `ThrottleParallelForEach` activity derives from , because it needs to schedule other activities (the child activities) and this is only accessible through the class. +The `ThrottleParallelForEach` activity is similar to the activity with the one exception that it allows setting a concurrency factor to restrict the number of simultaneous branches to execute. The `ThrottleParallelForEach` activity derives from , because it needs to schedule other activities (the child activities) and this is only accessible through the class. ## Projects diff --git a/docs/framework/windows-workflow-foundation/samples/using-editing-scope.md b/docs/framework/windows-workflow-foundation/samples/using-editing-scope.md index ac2a02133e6fa..f3bbec1806eaa 100644 --- a/docs/framework/windows-workflow-foundation/samples/using-editing-scope.md +++ b/docs/framework/windows-workflow-foundation/samples/using-editing-scope.md @@ -16,9 +16,9 @@ The [UsingEditingScope sample](https://github.com/dotnet/samples/tree/main/frame This sample demonstrates how to batch a set of changes to the tree within a single unit of work. Note that when binding to values directly from a WPF designer, changes are applied automatically. This sample demonstrates what must be done when multiple changes to be batched are being made through imperative code, rather than a single change. - In this sample, three activities are added. When editing begins, is called on an instance of . Changes made to the tree within this editing scope are batched. The command returns an , which can be used to control this instance. Either or can be called to either commit or revert the editing scope. + In this sample, three activities are added. When editing begins, is called on an instance of . Changes made to the tree within this editing scope are batched. The command returns an , which can be used to control this instance. Either or can be called to either commit or revert the editing scope. - You can also nest objects, which allows for multiple sets of changes to be tracked as part of a larger editing scope and can be controlled individually. A scenario that may use this feature would be when changes from multiple dialogs must be committed or reverted separately, with all changes being treated as a single atomic operation. In this sample, the editing scopes are stacked using an of type . The is used so that the depth of the nesting can be observed on the designer surface. + You can also nest objects, which allows for multiple sets of changes to be tracked as part of a larger editing scope and can be controlled individually. A scenario that may use this feature would be when changes from multiple dialogs must be committed or reverted separately, with all changes being treated as a single atomic operation. In this sample, the editing scopes are stacked using an of type . The is used so that the depth of the nesting can be observed on the designer surface. ## To set up, build, and run the sample @@ -26,8 +26,8 @@ The [UsingEditingScope sample](https://github.com/dotnet/samples/tree/main/frame 2. Click **Open Editing Scope**. - 1. This command calls that creates an editing scope and pushes it onto the editing stack. + 1. This command calls that creates an editing scope and pushes it onto the editing stack. - 2. Three activities are then added to the selected . Note that if the editing scope had not been opened with , three new activities would appear on the designer canvas. Because this operation is still pending within the , the designer is not yet updated. + 2. Three activities are then added to the selected . Note that if the editing scope had not been opened with , three new activities would appear on the designer canvas. Because this operation is still pending within the , the designer is not yet updated. 3. Press **Close Editing Scope** to commit the editing scope. Three activities appear in the designer. diff --git a/docs/framework/windows-workflow-foundation/samples/wpf-and-wf-integration-in-xaml.md b/docs/framework/windows-workflow-foundation/samples/wpf-and-wf-integration-in-xaml.md index 440e459c7fd0d..8359c37df371e 100644 --- a/docs/framework/windows-workflow-foundation/samples/wpf-and-wf-integration-in-xaml.md +++ b/docs/framework/windows-workflow-foundation/samples/wpf-and-wf-integration-in-xaml.md @@ -10,11 +10,11 @@ The [WPFWFIntegration sample](https://github.com/dotnet/samples/tree/main/framew ## Sample details - The ShowWindow.xaml file deserializes into a activity with two string variables that are manipulated by the sequence's activities: `ShowWindow` and `WriteLine`. The activity outputs to the console window the expression that it assigns to the property. The `ShowWindow` activity displays a WPF window as part of its execution logic. The of the window includes the variables declared in the sequence. The controls of the window declared in the `ShowWindow` activity use data binding to manipulate those variables. Finally, the window contains a button control. The `Click` event for the button is handled by a named `MarkupExtension` that contains a `CloseWindow` activity. `MarkUpExtension` invokes the contained activity that provides, as context, any objects identified by an `x:Name`, as well as the of the containing window. Thus, the `CloseWindow.InArgument` can be bound using an expression that references the window's name. + The ShowWindow.xaml file deserializes into a activity with two string variables that are manipulated by the sequence's activities: `ShowWindow` and `WriteLine`. The activity outputs to the console window the expression that it assigns to the property. The `ShowWindow` activity displays a WPF window as part of its execution logic. The of the window includes the variables declared in the sequence. The controls of the window declared in the `ShowWindow` activity use data binding to manipulate those variables. Finally, the window contains a button control. The `Click` event for the button is handled by a named `MarkupExtension` that contains a `CloseWindow` activity. `MarkUpExtension` invokes the contained activity that provides, as context, any objects identified by an `x:Name`, as well as the of the containing window. Thus, the `CloseWindow.InArgument` can be bound using an expression that references the window's name. - The `ShowWindow` activity derives from the class to display a WPF window and completes when the window is closed. The `Window` property is of type `Func` that allows the window to be created on demand for each execution of the activity. The `Window` property uses a to enable this deferred evaluation model. The `FuncFactoryDeferringLoader` allows a `XamlReader` to be captured during serialization and then read during activity execution. + The `ShowWindow` activity derives from the class to display a WPF window and completes when the window is closed. The `Window` property is of type `Func` that allows the window to be created on demand for each execution of the activity. The `Window` property uses a to enable this deferred evaluation model. The `FuncFactoryDeferringLoader` allows a `XamlReader` to be captured during serialization and then read during activity execution. - A well-written activity never blocks the scheduler thread. However, the `ShowWindow` activity cannot complete until the window it is displaying is closed. The `ShowWindow` activity achieves this behavior by deriving from , calling the method in the method, and showing the window modally. The delegate is invoked through the WPF . The `ShowWindow` activity assigns the property to the `Window.DataContext` property to provide any data bound controls access to the in-scope variables. + A well-written activity never blocks the scheduler thread. However, the `ShowWindow` activity cannot complete until the window it is displaying is closed. The `ShowWindow` activity achieves this behavior by deriving from , calling the method in the method, and showing the window modally. The delegate is invoked through the WPF . The `ShowWindow` activity assigns the property to the `Window.DataContext` property to provide any data bound controls access to the in-scope variables. The last point of interest in this sample is a called `DelegateActivityExtension`. The `ProvideValue` method of this markup extension returns a delegate that invokes an embedded activity. This activity runs in an environment that includes the WPF data context and any `x:Name` values in scope. In the `GenericInvoke` method, this environment is provided to the activity through a extension. This extension is added to a that is then used to invoke the embedded activity whenever the markup extension's delegate is invoked. diff --git a/docs/framework/windows-workflow-foundation/serializing-workflows-and-activities-to-and-from-xaml.md b/docs/framework/windows-workflow-foundation/serializing-workflows-and-activities-to-and-from-xaml.md index 6304f268130d7..951e03152642f 100644 --- a/docs/framework/windows-workflow-foundation/serializing-workflows-and-activities-to-and-from-xaml.md +++ b/docs/framework/windows-workflow-foundation/serializing-workflows-and-activities-to-and-from-xaml.md @@ -10,11 +10,11 @@ In addition to being compiled into types that are contained in assemblies, workf ## Work with XAML Workflow definitions -To create a workflow definition for serialization, the class is used. Creating an is very similar to creating a . Any desired arguments are specified, and the activities that constitute the behavior are configured. In the following example, an `Add` activity is created that takes two input arguments, adds them together, and returns the result. Because this activity returns a result, the generic class is used. +To create a workflow definition for serialization, the class is used. Creating an is very similar to creating a . Any desired arguments are specified, and the activities that constitute the behavior are configured. In the following example, an `Add` activity is created that takes two input arguments, adds them together, and returns the result. Because this activity returns a result, the generic class is used. [!code-csharp[CFX_WorkflowApplicationExample#41](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#41)] -Each of the instances represents one of the input arguments to the workflow, and the contains the activities that make up the logic of the workflow. Note that the r-value expressions in this example are Visual Basic expressions. Lambda expressions are not serializable to XAML unless is used. If the serialized workflows are intended to be opened or edited in the workflow designer, then Visual Basic expressions should be used. For more information, see [Authoring Workflows, Activities, and Expressions Using Imperative Code](authoring-workflows-activities-and-expressions-using-imperative-code.md). +Each of the instances represents one of the input arguments to the workflow, and the contains the activities that make up the logic of the workflow. Note that the r-value expressions in this example are Visual Basic expressions. Lambda expressions are not serializable to XAML unless is used. If the serialized workflows are intended to be opened or edited in the workflow designer, then Visual Basic expressions should be used. For more information, see [Authoring Workflows, Activities, and Expressions Using Imperative Code](authoring-workflows-activities-and-expressions-using-imperative-code.md). To serialize the workflow definition represented by the instance to XAML, use to create a , and then use to serialize the workflow definition by using the . has methods to map instances to and from XAML and to load XAML workflows and return a that can be invoked. In the following example, the instance from the previous example is serialized to a string and saved to a file. @@ -61,7 +61,7 @@ The following example represents the serialized workflow. ``` -To load a serialized workflow, use the method. This takes the serialized workflow definition and returns a that represents the workflow definition. Note that the XAML is not deserialized until is called on the body of the during the validation process. If validation is not explicitly called, then it is performed when the workflow is invoked. If the XAML workflow definition is invalid, then an exception is thrown. Any exceptions thrown from escape from the call to and must be handled by the caller. In the following example, the serialized workflow from the previous example is loaded and invoked by using . +To load a serialized workflow, use the method. This takes the serialized workflow definition and returns a that represents the workflow definition. Note that the XAML is not deserialized until is called on the body of the during the validation process. If validation is not explicitly called, then it is performed when the workflow is invoked. If the XAML workflow definition is invalid, then an exception is thrown. Any exceptions thrown from escape from the call to and must be handled by the caller. In the following example, the serialized workflow from the previous example is loaded and invoked by using . [!code-csharp[CFX_WorkflowApplicationExample#43](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#43)] @@ -71,9 +71,9 @@ When this workflow is invoked, the following output is displayed to the console. **40** > [!NOTE] -> For more information about invoking workflows with input and output arguments, see [Using WorkflowInvoker and WorkflowApplication](using-workflowinvoker-and-workflowapplication.md) and . +> For more information about invoking workflows with input and output arguments, see [Using WorkflowInvoker and WorkflowApplication](using-workflowinvoker-and-workflowapplication.md) and . -If the serialized workflow contains C# expressions, then an instance with its property set to `true` must be passed as a parameter to , otherwise a will be thrown with a message similar to the following: **Expression Activity type 'CSharpValue`1' requires compilation in order to run. Please ensure that the workflow has been compiled.** +If the serialized workflow contains C# expressions, then an instance with its property set to `true` must be passed as a parameter to , otherwise a will be thrown with a message similar to the following: **Expression Activity type 'CSharpValue`1' requires compilation in order to run. Please ensure that the workflow has been compiled.** ```csharp ActivityXamlServicesSettings settings = new ActivityXamlServicesSettings @@ -86,6 +86,6 @@ DynamicActivity wf = ActivityXamlServices.Load(new StringReader(serializedA For more information, see [C# Expressions](csharp-expressions.md). -A serialized workflow definition can also be loaded into an instance by using the method. After a serialized workflow is loaded into an instance, it can be inspected and modified. This is useful for custom workflow designer authors and provides a mechanism for saving and reloading workflow definitions during the design process. In the following example, the serialized workflow definition from the previous example is loaded and its properties are inspected. +A serialized workflow definition can also be loaded into an instance by using the method. After a serialized workflow is loaded into an instance, it can be inspected and modified. This is useful for custom workflow designer authors and provides a mechanism for saving and reloading workflow definitions during the design process. In the following example, the serialized workflow definition from the previous example is loaded and its properties are inspected. [!code-csharp[CFX_WorkflowApplicationExample#44](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#44)] diff --git a/docs/framework/windows-workflow-foundation/state-machine-workflows.md b/docs/framework/windows-workflow-foundation/state-machine-workflows.md index c68af29224387..5c1fed0f1ec12 100644 --- a/docs/framework/windows-workflow-foundation/state-machine-workflows.md +++ b/docs/framework/windows-workflow-foundation/state-machine-workflows.md @@ -6,101 +6,101 @@ ms.assetid: 344caacd-bf3b-4716-bd5a-eca74fc5a61d --- # State Machine Workflows -A state machine is a well-known paradigm for developing programs. The activity, along with , , and other activities can be used to build state machine workflow programs. This topic provides an overview of creating state machine workflows. - -## State Machine Workflow Overview - - State machine workflows provide a modeling style with which you can model your workflow in an event-driven manner. A activity contains the states and transitions that make up the logic of the state machine, and can be used anywhere an activity can be used. There are several classes in the state machine runtime: - -- - -- - -- - - To create a state machine workflow, states are added to a activity, and transitions are used to control the flow between states. The following screenshot, from the [Getting Started Tutorial](getting-started-tutorial.md) step [How to: Create a State Machine Workflow](how-to-create-a-state-machine-workflow.md), shows a state machine workflow with three states and three transitions. **Initialize Target** is the initial state and represents the first state in the workflow. This is designated by the line leading to it from the **Start** node. The final state in the workflow is named **FinalState**, and represents the point at which the workflow is completed. - - ![Illustration that shows the completed state machine workflow.](./media/state-machine-workflows/complete-state-machine-workflow.jpg) - - A state machine workflow must have one and only one initial state, and at least one final state. Each state that is not a final state must have at least one transition. The following sections cover creating and configuring states and transitions. - -## Creating and Configuring States - - A represents a state in which a state machine can be in. To add a to a workflow, drag the **State** activity designer from the **State Machine** section of the **Toolbox** and drop it onto a activity on the Windows Workflow Designer surface. - - ![Screenshot of the State Machine section of the Toolbox.](./media/state-machine-workflows/state-machine-section-toolbox.jpg) - - To configure a state as the **Initial State**, right-click the state and select **Set as Initial State**. Additionally, if there is no current initial state, the initial state can be designated by dragging a line from the **Start** node at the top of the workflow to the desired state. When a activity is dropped onto the workflow designer, it is pre-configured with an initial state named **State1**. A state machine workflow must have one and only one initial state. - - A state that represents a terminating state in a state machine is called a final state. A final state is a state that has its property set to `true`, has no activity, and no transitions originating from it. To add a final state to a workflow, drag a **FinalState** activity designer from the **State Machine** section of the **Toolbox** and drop it onto a activity on the Windows Workflow Designer surface. A state machine workflow must have at least one final state. - -### Configuring Entry and Exit Actions - - A state can have an and an action. (A state configured as a final state may have only an entry action). When a workflow instance enters a state, any activities in the entry action execute. When the entry action is complete, the triggers for the state's transitions are scheduled. When a transition to another state is confirmed, the activities in the exit action are executed, even if the state transitions back to the same state. After the exit action completes, the activities in the transition's action execute, and then the new state is transitioned to, and its entry actions are scheduled. - +A state machine is a well-known paradigm for developing programs. The activity, along with , , and other activities can be used to build state machine workflow programs. This topic provides an overview of creating state machine workflows. + +## State Machine Workflow Overview + + State machine workflows provide a modeling style with which you can model your workflow in an event-driven manner. A activity contains the states and transitions that make up the logic of the state machine, and can be used anywhere an activity can be used. There are several classes in the state machine runtime: + +- + +- + +- + + To create a state machine workflow, states are added to a activity, and transitions are used to control the flow between states. The following screenshot, from the [Getting Started Tutorial](getting-started-tutorial.md) step [How to: Create a State Machine Workflow](how-to-create-a-state-machine-workflow.md), shows a state machine workflow with three states and three transitions. **Initialize Target** is the initial state and represents the first state in the workflow. This is designated by the line leading to it from the **Start** node. The final state in the workflow is named **FinalState**, and represents the point at which the workflow is completed. + + ![Illustration that shows the completed state machine workflow.](./media/state-machine-workflows/complete-state-machine-workflow.jpg) + + A state machine workflow must have one and only one initial state, and at least one final state. Each state that is not a final state must have at least one transition. The following sections cover creating and configuring states and transitions. + +## Creating and Configuring States + + A represents a state in which a state machine can be in. To add a to a workflow, drag the **State** activity designer from the **State Machine** section of the **Toolbox** and drop it onto a activity on the Windows Workflow Designer surface. + + ![Screenshot of the State Machine section of the Toolbox.](./media/state-machine-workflows/state-machine-section-toolbox.jpg) + + To configure a state as the **Initial State**, right-click the state and select **Set as Initial State**. Additionally, if there is no current initial state, the initial state can be designated by dragging a line from the **Start** node at the top of the workflow to the desired state. When a activity is dropped onto the workflow designer, it is pre-configured with an initial state named **State1**. A state machine workflow must have one and only one initial state. + + A state that represents a terminating state in a state machine is called a final state. A final state is a state that has its property set to `true`, has no activity, and no transitions originating from it. To add a final state to a workflow, drag a **FinalState** activity designer from the **State Machine** section of the **Toolbox** and drop it onto a activity on the Windows Workflow Designer surface. A state machine workflow must have at least one final state. + +### Configuring Entry and Exit Actions + + A state can have an and an action. (A state configured as a final state may have only an entry action). When a workflow instance enters a state, any activities in the entry action execute. When the entry action is complete, the triggers for the state's transitions are scheduled. When a transition to another state is confirmed, the activities in the exit action are executed, even if the state transitions back to the same state. After the exit action completes, the activities in the transition's action execute, and then the new state is transitioned to, and its entry actions are scheduled. + > [!NOTE] -> When debugging a state machine workflow, breakpoints can be placed on the root state machine activity and states within the state machine workflow. Breakpoints may not be placed directly on the transitions, but they may be placed on any activities contained within the states and transitions. - -## Creating and Configuring Transitions - - All states must have at least one transition, except for a final state, which may not have any transitions. Transitions may be added after a state is added to a state machine workflow, or they can be created as the state is dropped. - - To add a and create a transition in one step, drag a **State** activity from the **State Machine** section of the **Toolbox** and hover it over another state in the workflow designer. When the dragged is over another , four triangles will appear around the other . If the is dropped onto one of the four triangles, it is added to the state machine and a transition is created from the source to the dropped destination . For more information, see [Transition Activity Designer](/visualstudio/workflow-designer/transition-activity-designer). - - To create a transition after a state is added, there are two options. The first option is to drag the state from the workflow designer surface and hover it over an existing state and drop it on one of the drop points. This is similar to the method described in the previous section. You can also hover the mouse over the desired source state, and drag a line to the desired destination state. - +> When debugging a state machine workflow, breakpoints can be placed on the root state machine activity and states within the state machine workflow. Breakpoints may not be placed directly on the transitions, but they may be placed on any activities contained within the states and transitions. + +## Creating and Configuring Transitions + + All states must have at least one transition, except for a final state, which may not have any transitions. Transitions may be added after a state is added to a state machine workflow, or they can be created as the state is dropped. + + To add a and create a transition in one step, drag a **State** activity from the **State Machine** section of the **Toolbox** and hover it over another state in the workflow designer. When the dragged is over another , four triangles will appear around the other . If the is dropped onto one of the four triangles, it is added to the state machine and a transition is created from the source to the dropped destination . For more information, see [Transition Activity Designer](/visualstudio/workflow-designer/transition-activity-designer). + + To create a transition after a state is added, there are two options. The first option is to drag the state from the workflow designer surface and hover it over an existing state and drop it on one of the drop points. This is similar to the method described in the previous section. You can also hover the mouse over the desired source state, and drag a line to the desired destination state. + > [!NOTE] -> A single state in a state machine can have up to 76 transitions created using the workflow designer. The limit on transitions for a state for workflows created outside the designer is limited only by system resources. - - A transition may have a , a , and an . A transition's is scheduled when the transition's source state's action is complete. Typically the is an activity that waits for some type of event to occur, but it can be any activity, or no activity at all. Once the activity is complete, the , if present, is evaluated. If there is no activity, then the is immediately evaluated. If the condition evaluates to `false`, the transition is canceled, and the activity for all transitions from the state are rescheduled. If there are other transitions that share the same source state as the current transition, those actions are canceled and rescheduled as well. If the evaluates to `true`, or there is no condition, then the action of the source state is executed, and then the of the transition is executed. When the completes, control passes to the **Target** state - - Transitions that share a common trigger are known as shared trigger transitions. Each transition in a group of shared trigger transitions has the same trigger, but a unique and Action. To add additional actions to a transition and create a shared transition, click the circle that indicates the start of the desired transition and drag it to the desired state. The new transition will share a same trigger as the initial transition, but it will have a unique condition and action. Shared transitions can also be created from within the transition designer by clicking **Add shared trigger transition** at the bottom of the transition designer, and then selecting the desired target state from the **Available states to connect** drop-down. - +> A single state in a state machine can have up to 76 transitions created using the workflow designer. The limit on transitions for a state for workflows created outside the designer is limited only by system resources. + + A transition may have a , a , and an . A transition's is scheduled when the transition's source state's action is complete. Typically the is an activity that waits for some type of event to occur, but it can be any activity, or no activity at all. Once the activity is complete, the , if present, is evaluated. If there is no activity, then the is immediately evaluated. If the condition evaluates to `false`, the transition is canceled, and the activity for all transitions from the state are rescheduled. If there are other transitions that share the same source state as the current transition, those actions are canceled and rescheduled as well. If the evaluates to `true`, or there is no condition, then the action of the source state is executed, and then the of the transition is executed. When the completes, control passes to the **Target** state + + Transitions that share a common trigger are known as shared trigger transitions. Each transition in a group of shared trigger transitions has the same trigger, but a unique and Action. To add additional actions to a transition and create a shared transition, click the circle that indicates the start of the desired transition and drag it to the desired state. The new transition will share a same trigger as the initial transition, but it will have a unique condition and action. Shared transitions can also be created from within the transition designer by clicking **Add shared trigger transition** at the bottom of the transition designer, and then selecting the desired target state from the **Available states to connect** drop-down. + > [!NOTE] -> Note that if the of a transition evaluates to `False` (or all of the conditions of a shared trigger transition evaluate to `False`), the transition will not occur and all triggers for all the transitions from the state will be rescheduled. - - For more information on creating state machine workflows, see [How to: Create a State Machine Workflow](how-to-create-a-state-machine-workflow.md), [StateMachine Activity Designer](/visualstudio/workflow-designer/statemachine-activity-designer), [State Activity Designer](/visualstudio/workflow-designer/state-activity-designer), [FinalState Activity Designer](/visualstudio/workflow-designer/finalstate-activity-designer), and [Transition Activity Designer](/visualstudio/workflow-designer/transition-activity-designer). - -## State Machine Terminology - - This section defines the state machine vocabulary used throughout this topic. - - State - The basic unit that composes a state machine. A state machine can be in one state at any particular time. - - Entry Action - An activity executed when entering the state - - Exit Action - An activity executed when exiting the state - - Transition - A directed relationship between two states that represents the complete response of a state machine to an occurrence of an event of a particular type. - - Shared Transition - A transition that shares a source state and trigger with one or more transitions, but has a unique condition and action. - - Trigger - A triggering activity that causes a transition to occur. - - Condition - A constraint that must evaluate to `true` after the trigger occurs in order for the transition to complete. - - Transition Action - An activity that is executed when performing a certain transition. - - Conditional Transition - A transition with an explicit condition. - - Self-transition - A transition that transits from a state to itself. - - Initial State - A state that represents the starting point of the state machine. - - Final State - A state that represents the completion of the state machine. - +> Note that if the of a transition evaluates to `False` (or all of the conditions of a shared trigger transition evaluate to `False`), the transition will not occur and all triggers for all the transitions from the state will be rescheduled. + + For more information on creating state machine workflows, see [How to: Create a State Machine Workflow](how-to-create-a-state-machine-workflow.md), [StateMachine Activity Designer](/visualstudio/workflow-designer/statemachine-activity-designer), [State Activity Designer](/visualstudio/workflow-designer/state-activity-designer), [FinalState Activity Designer](/visualstudio/workflow-designer/finalstate-activity-designer), and [Transition Activity Designer](/visualstudio/workflow-designer/transition-activity-designer). + +## State Machine Terminology + + This section defines the state machine vocabulary used throughout this topic. + + State + The basic unit that composes a state machine. A state machine can be in one state at any particular time. + + Entry Action + An activity executed when entering the state + + Exit Action + An activity executed when exiting the state + + Transition + A directed relationship between two states that represents the complete response of a state machine to an occurrence of an event of a particular type. + + Shared Transition + A transition that shares a source state and trigger with one or more transitions, but has a unique condition and action. + + Trigger + A triggering activity that causes a transition to occur. + + Condition + A constraint that must evaluate to `true` after the trigger occurs in order for the transition to complete. + + Transition Action + An activity that is executed when performing a certain transition. + + Conditional Transition + A transition with an explicit condition. + + Self-transition + A transition that transits from a state to itself. + + Initial State + A state that represents the starting point of the state machine. + + Final State + A state that represents the completion of the state machine. + ## See also - [How to: Create a State Machine Workflow](how-to-create-a-state-machine-workflow.md) diff --git a/docs/framework/windows-workflow-foundation/store-extensibility.md b/docs/framework/windows-workflow-foundation/store-extensibility.md index 47641f95e6bff..219982e51dce6 100644 --- a/docs/framework/windows-workflow-foundation/store-extensibility.md +++ b/docs/framework/windows-workflow-foundation/store-extensibility.md @@ -9,7 +9,7 @@ ms.custom: sfi-ropc-nochange allows users to promote custom, application-specific properties that can be used to query for instances in the persistence database. The act of promoting a property causes the value to be available within a special view in the database. These promoted properties (properties that can be used in user queries) can be of simple types, such as `Int64`, `Guid`, `String`, and `DateTime`, or of a serialized binary type (`byte[]`). -The class has the method that you can use to promote a property as a property that can be used in queries. The following example is an end-to-end example of store extensibility. +The class has the method that you can use to promote a property as a property that can be used in queries. The following example is an end-to-end example of store extensibility. 1. In this example scenario, a document processing (DP) application has workflows, each of which uses custom activities for document processing. These workflows have a set of state variables that need to be made visible to the end user. To achieve this, the DP application provides an instance extension of type , which is used by activities to supply the state variables. diff --git a/docs/framework/windows-workflow-foundation/tracking-participants.md b/docs/framework/windows-workflow-foundation/tracking-participants.md index 838d13c27199e..7a33c5e0df6b0 100644 --- a/docs/framework/windows-workflow-foundation/tracking-participants.md +++ b/docs/framework/windows-workflow-foundation/tracking-participants.md @@ -6,7 +6,7 @@ ms.assetid: f13e360c-eeb7-4a49-98a0-8f6a52d64f68 --- # Tracking Participants -Tracking participants are extensibility points that allow a workflow developer to access objects and process them. [!INCLUDE[netfx_current_long](../../../includes/netfx-current-long-md.md)] includes a standard tracking participant that writes tracking records as Event Tracing for Windows (ETW) events. If that does not meet your requirements, you can also write a custom tracking participant. +Tracking participants are extensibility points that allow a workflow developer to access objects and process them. [!INCLUDE[netfx_current_long](../../../includes/netfx-current-long-md.md)] includes a standard tracking participant that writes tracking records as Event Tracing for Windows (ETW) events. If that does not meet your requirements, you can also write a custom tracking participant. ## Tracking Participants @@ -93,7 +93,7 @@ Tracking participants are extensibility points that allow a workflow developer t The tracking participant API allows extension of the tracking runtime with a user-provided tracking participant that can include custom logic to handle tracking records emitted by the workflow runtime. To write a custom tracking participant, the developer must implement the `Track` method on the class. This method is called when a tracking record is emitted by the workflow runtime. - Tracking participants derive from the class. The system-provided emits an Event Tracking for Windows (ETW) event for each tracking record that is received. To create a custom tracking participant, a class is created that derives from . To provide basic tracking functionality, override . is called when a tracking record is sent by the runtime and can be processed in the desired manner. In the following example, a custom tracking participant class is defined that emits all tracking records to the console window. You can also implement a object that processes the tracking records asynchronously using its `BeginTrack` and `EndTrack` methods + Tracking participants derive from the class. The system-provided emits an Event Tracking for Windows (ETW) event for each tracking record that is received. To create a custom tracking participant, a class is created that derives from . To provide basic tracking functionality, override . is called when a tracking record is sent by the runtime and can be processed in the desired manner. In the following example, a custom tracking participant class is defined that emits all tracking records to the console window. You can also implement a object that processes the tracking records asynchronously using its `BeginTrack` and `EndTrack` methods ```csharp class ConsoleTrackingParticipant : TrackingParticipant diff --git a/docs/framework/windows-workflow-foundation/tracking-records.md b/docs/framework/windows-workflow-foundation/tracking-records.md index 6b0c87ae48c83..5c42d0d5c83eb 100644 --- a/docs/framework/windows-workflow-foundation/tracking-records.md +++ b/docs/framework/windows-workflow-foundation/tracking-records.md @@ -6,57 +6,57 @@ ms.assetid: 51adbda3-bd8b-4892-a8ea-d343186472d2 --- # Tracking Records -The workflow runtime is instrumented to emit tracking records to follow the execution of a workflow instance. - -## Tracking Records - - The following table details the tracking records that the workflow runtime emits. - -|Tracking record|Description| -|---------------------|-----------------| -|Workflow life cycle records|Emitted during various stages of the life cycle of the workflow instance. For example, a record is emitted when the workflow starts or completes.| -|Activity life cycle records|Details activity execution. These records indicate the state of a workflow activity such as when an activity is scheduled, when the activity completes, or when a fault occurs.| -|Bookmark resumption records|Emitted whenever a bookmark within a workflow instance is resumed.| -|Custom tracking records|A workflow author can create custom tracking records and emit them within a custom activity.| - - All tracking-related records emitted from the WF runtime derive from the base class , which contains the common set of data. Tracking records show the life cycle for a simple workflow. Each tracking record contains details about the associated tracking event, such as the , , and additional information specific to the type of tracking record. - - The following types of objects are emitted by the workflow runtime: - -- **WorkflowInstanceRecord** - This describes the life cycle of the workflow instance. For example, a record is emitted when the workflow starts or completes, and contains the state of the workflow instance. The details of this record can be found at . - -- **WorkflowInstanceAbortedRecord** - This is emitted when a workflow instance aborts. The record contains the reason for the workflow instance being aborted. The details of this record can be found at . - -- **WorkflowInstanceUnhandledExceptionRecord** - This is emitted if an exception occurs in the workflow instance and is not handled by any activity. The record contains the exception details. The details of this record can be found at . - -- **WorkflowInstanceSuspendedRecord** - This is emitted whenever a workflow instance is suspended. The record contains the reason for the workflow instance being suspended. The details of this record can be found at . - -- **WorkflowInstanceTerminatedRecord** - This is emitted whenever a workflow instance is terminated. The record contains the reason for the workflow instance being terminated. The details of this record can be found at . - -- **ActivityStateRecord** - This is emitted when an activity within a workflow executes. These records indicate the state of the activity within the workflow instance. The details of this record can be found at . - -- **ActivityScheduledRecord** - This is emitted when an activity schedules a child activity. This record contains details for both the parent activity (scheduling activity) and the scheduled child activity. The details of this record can be found at . - -- **FaultPropagationRecord** - This is emitted for each handler that looks at the record until it is handled. It is used to denote the path a fault took within the workflow instance. The details of this record can be found at . - -- **CancelRequestedRecord** - This is emitted whenever an activity tries to cancel a child activity. This record contains details for both the parent activity and the child activity that is being canceled. The details of this record can be found at . - -- **BookmarkResumptionRecord** - This tracks any bookmark that is successfully resumed. The details of this record can be found at . - -- **CustomTrackingRecord** - This is created and emitted by a workflow author within a custom workflow activity. Custom tracking records can be populated with data to be emitted along with the records. The details of this record can be found at . - - For example, there could be a simple activity that contains a operation with tracking records emitted in the following order: - -1. indicates that the workflow is starting. - -2. indicates that an activity has been scheduled. In this case it is a activity. - -3. represents the activity. - -4. There are two records that represent the two activities completing. - -5. indicates that the workflow is completing. - +The workflow runtime is instrumented to emit tracking records to follow the execution of a workflow instance. + +## Tracking Records + + The following table details the tracking records that the workflow runtime emits. + +|Tracking record|Description| +|---------------------|-----------------| +|Workflow life cycle records|Emitted during various stages of the life cycle of the workflow instance. For example, a record is emitted when the workflow starts or completes.| +|Activity life cycle records|Details activity execution. These records indicate the state of a workflow activity such as when an activity is scheduled, when the activity completes, or when a fault occurs.| +|Bookmark resumption records|Emitted whenever a bookmark within a workflow instance is resumed.| +|Custom tracking records|A workflow author can create custom tracking records and emit them within a custom activity.| + + All tracking-related records emitted from the WF runtime derive from the base class , which contains the common set of data. Tracking records show the life cycle for a simple workflow. Each tracking record contains details about the associated tracking event, such as the , , and additional information specific to the type of tracking record. + + The following types of objects are emitted by the workflow runtime: + +- **WorkflowInstanceRecord** - This describes the life cycle of the workflow instance. For example, a record is emitted when the workflow starts or completes, and contains the state of the workflow instance. The details of this record can be found at . + +- **WorkflowInstanceAbortedRecord** - This is emitted when a workflow instance aborts. The record contains the reason for the workflow instance being aborted. The details of this record can be found at . + +- **WorkflowInstanceUnhandledExceptionRecord** - This is emitted if an exception occurs in the workflow instance and is not handled by any activity. The record contains the exception details. The details of this record can be found at . + +- **WorkflowInstanceSuspendedRecord** - This is emitted whenever a workflow instance is suspended. The record contains the reason for the workflow instance being suspended. The details of this record can be found at . + +- **WorkflowInstanceTerminatedRecord** - This is emitted whenever a workflow instance is terminated. The record contains the reason for the workflow instance being terminated. The details of this record can be found at . + +- **ActivityStateRecord** - This is emitted when an activity within a workflow executes. These records indicate the state of the activity within the workflow instance. The details of this record can be found at . + +- **ActivityScheduledRecord** - This is emitted when an activity schedules a child activity. This record contains details for both the parent activity (scheduling activity) and the scheduled child activity. The details of this record can be found at . + +- **FaultPropagationRecord** - This is emitted for each handler that looks at the record until it is handled. It is used to denote the path a fault took within the workflow instance. The details of this record can be found at . + +- **CancelRequestedRecord** - This is emitted whenever an activity tries to cancel a child activity. This record contains details for both the parent activity and the child activity that is being canceled. The details of this record can be found at . + +- **BookmarkResumptionRecord** - This tracks any bookmark that is successfully resumed. The details of this record can be found at . + +- **CustomTrackingRecord** - This is created and emitted by a workflow author within a custom workflow activity. Custom tracking records can be populated with data to be emitted along with the records. The details of this record can be found at . + + For example, there could be a simple activity that contains a operation with tracking records emitted in the following order: + +1. indicates that the workflow is starting. + +2. indicates that an activity has been scheduled. In this case it is a activity. + +3. represents the activity. + +4. There are two records that represent the two activities completing. + +5. indicates that the workflow is completing. + ## See also - [Windows Server App Fabric Monitoring](/previous-versions/appfabric/ee677251(v=azure.10)) diff --git a/docs/framework/windows-workflow-foundation/using-a-custom-activity.md b/docs/framework/windows-workflow-foundation/using-a-custom-activity.md index d66c44359c7fc..c0b3aa56904f2 100644 --- a/docs/framework/windows-workflow-foundation/using-a-custom-activity.md +++ b/docs/framework/windows-workflow-foundation/using-a-custom-activity.md @@ -19,4 +19,4 @@ Activities that derive from or its subclasses 3. To use the custom activity in the designer, locate the custom activity in the toolbox, and drag the activity onto the designer surface. -4. To use the custom activity in code, add a `using` directive that refers to the custom activity project, and pass a new instance of the activity to . +4. To use the custom activity in code, add a `using` directive that refers to the custom activity project, and pass a new instance of the activity to . diff --git a/docs/framework/windows-workflow-foundation/using-a-custom-expression-editor.md b/docs/framework/windows-workflow-foundation/using-a-custom-expression-editor.md index f4a089f72589a..28300e20223a8 100644 --- a/docs/framework/windows-workflow-foundation/using-a-custom-expression-editor.md +++ b/docs/framework/windows-workflow-foundation/using-a-custom-expression-editor.md @@ -6,277 +6,277 @@ ms.topic: "how-to" --- # Using a Custom Expression Editor -A custom expression editor can be implemented to provide a richer or simpler expression editing experience. There are several scenarios in which you might want to use a custom expression editor: - -- To provide support for IntelliSense and other rich editing features in a rehosted workflow designer. This functionality must be provided because the default Visual Studio expression editor cannot be used in rehosted applications. - -- To simplify the expression editing experience for the business analyst users, so that they are not, for example, required to learn Visual Basic or deal with Visual Basic expressions. - - Three basic steps are needed to implement a custom expression editor: - -1. Implement the interface. This interface manages the creation and destruction of expression editors. - -2. Implement the interface. This interface implements the UI for expression editing UI. - -3. Publish the in your rehosted workflow application. - -## Implementing a Custom Expression Editor in a Class Library - - Here is a sample of code for a (proof of concept) `MyEditorService` class that implements the interface is contained in a MyExpressionEditorService library project. - -```csharp -using System; -using System.Collections.Generic; -using System.Activities.Presentation.View; -using System.Activities.Presentation.Hosting; -using System.Activities.Presentation.Model; - -namespace MyExpressionEditorService -{ - public class MyEditorService : IExpressionEditorService - { - public void CloseExpressionEditors() - { - - } - public IExpressionEditorInstance CreateExpressionEditor(AssemblyContextControlItem assemblies, ImportedNamespaceContextItem importedNamespaces, List variables, string text) - { - MyExpressionEditorInstance instance = new MyExpressionEditorInstance(); - return instance; - } - public IExpressionEditorInstance CreateExpressionEditor(AssemblyContextControlItem assemblies, ImportedNamespaceContextItem importedNamespaces, List variables, string text, System.Windows.Size initialSize) - { - MyExpressionEditorInstance instance = new MyExpressionEditorInstance(); - return instance; - } - public IExpressionEditorInstance CreateExpressionEditor(AssemblyContextControlItem assemblies, ImportedNamespaceContextItem importedNamespaces, List variables, string text, Type expressionType) - { - MyExpressionEditorInstance instance = new MyExpressionEditorInstance(); - return instance; - } - public IExpressionEditorInstance CreateExpressionEditor(AssemblyContextControlItem assemblies, ImportedNamespaceContextItem importedNamespaces, List variables, string text, Type expressionType, System.Windows.Size initialSize) - { - MyExpressionEditorInstance instance = new MyExpressionEditorInstance(); - return instance; - } - public void UpdateContext(AssemblyContextControlItem assemblies, ImportedNamespaceContextItem importedNamespaces) - { - - } - - } -} -``` - - Here is the code for a `MyExpressionEditorInstance` class that implements the interface in a MyExpressionEditorService library project. - -```csharp -using System; -using System.Activities.Presentation.View; -using System.Windows; -using System.Reflection; -using System.Windows.Controls; - -namespace MyExpressionEditorService -{ - public class MyExpressionEditorInstance : IExpressionEditorInstance - { - private TextBox textBox = new TextBox(); - - public bool AcceptsReturn { get; set; } - public bool AcceptsTab { get; set; } - public bool HasAggregateFocus { - get - { - return true; - } - } - - public System.Windows.Controls.ScrollBarVisibility HorizontalScrollBarVisibility { get; set; } - public System.Windows.Controls.Control HostControl { - get - { - return textBox; - } - } - public int MaxLines { get; set; } - public int MinLines { get; set; } - public string Text { get; set; } - public System.Windows.Controls.ScrollBarVisibility VerticalScrollBarVisibility { get; set; } - - public event EventHandler Closing; - public event EventHandler GotAggregateFocus; - public event EventHandler LostAggregateFocus; - public event EventHandler TextChanged; - - public bool CanCompleteWord() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool CanCopy() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool CanCut() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool CanDecreaseFilterLevel() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool CanGlobalIntellisense() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool CanIncreaseFilterLevel() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool CanParameterInfo() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool CanPaste() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool CanQuickInfo() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool CanRedo() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool CanUndo() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - - public void ClearSelection() - { - MessageBox.Show(MethodBase.GetCurrentMethod().Name); - } - public void Close() - { - MessageBox.Show(MethodBase.GetCurrentMethod().Name); - } - public bool CompleteWord() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool Copy() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool Cut() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool DecreaseFilterLevel() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public void Focus() - { - MessageBox.Show(MethodBase.GetCurrentMethod().Name); - } - public string GetCommittedText() - { - return "CommittedText"; - } - public bool GlobalIntellisense() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool IncreaseFilterLevel() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool ParameterInfo() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool Paste() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool QuickInfo() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool Redo() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - public bool Undo() - { - return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); - } - } -} -``` - -### Publishing a Custom Expression Editor in a WPF Project - - Here is the code that shows how to rehost the designer in a WPF application and how to create and publish the `MyEditorService` service. Before using this code, add a reference to the MyExpressionEditorService library project from the project that contains the avalon2 application. - -```csharp -using System.Windows; -using System.Windows.Controls; -using System.Activities.Presentation; -using System.Activities.Statements; -using System.Activities.Core.Presentation; -using System.Activities.Presentation.View; -using MyExpressionEditorService; - -namespace WpfApplication1 -{ - /// - /// Interaction logic for MainWindow.xaml - /// - public partial class MainWindow : Window - { - - private MyEditorService expressionEditorService; - public MainWindow() - { - InitializeComponent(); - new DesignerMetadata().Register(); - createDesigner(); - } - - public void createDesigner() - { - WorkflowDesigner designer = new WorkflowDesigner(); - Sequence root = new Sequence() - { - Activities = { - new Assign(), - new WriteLine()} - }; - - designer.Load(root); - - Grid.SetColumn(designer.View, 0); - +A custom expression editor can be implemented to provide a richer or simpler expression editing experience. There are several scenarios in which you might want to use a custom expression editor: + +- To provide support for IntelliSense and other rich editing features in a rehosted workflow designer. This functionality must be provided because the default Visual Studio expression editor cannot be used in rehosted applications. + +- To simplify the expression editing experience for the business analyst users, so that they are not, for example, required to learn Visual Basic or deal with Visual Basic expressions. + + Three basic steps are needed to implement a custom expression editor: + +1. Implement the interface. This interface manages the creation and destruction of expression editors. + +2. Implement the interface. This interface implements the UI for expression editing UI. + +3. Publish the in your rehosted workflow application. + +## Implementing a Custom Expression Editor in a Class Library + + Here is a sample of code for a (proof of concept) `MyEditorService` class that implements the interface is contained in a MyExpressionEditorService library project. + +```csharp +using System; +using System.Collections.Generic; +using System.Activities.Presentation.View; +using System.Activities.Presentation.Hosting; +using System.Activities.Presentation.Model; + +namespace MyExpressionEditorService +{ + public class MyEditorService : IExpressionEditorService + { + public void CloseExpressionEditors() + { + + } + public IExpressionEditorInstance CreateExpressionEditor(AssemblyContextControlItem assemblies, ImportedNamespaceContextItem importedNamespaces, List variables, string text) + { + MyExpressionEditorInstance instance = new MyExpressionEditorInstance(); + return instance; + } + public IExpressionEditorInstance CreateExpressionEditor(AssemblyContextControlItem assemblies, ImportedNamespaceContextItem importedNamespaces, List variables, string text, System.Windows.Size initialSize) + { + MyExpressionEditorInstance instance = new MyExpressionEditorInstance(); + return instance; + } + public IExpressionEditorInstance CreateExpressionEditor(AssemblyContextControlItem assemblies, ImportedNamespaceContextItem importedNamespaces, List variables, string text, Type expressionType) + { + MyExpressionEditorInstance instance = new MyExpressionEditorInstance(); + return instance; + } + public IExpressionEditorInstance CreateExpressionEditor(AssemblyContextControlItem assemblies, ImportedNamespaceContextItem importedNamespaces, List variables, string text, Type expressionType, System.Windows.Size initialSize) + { + MyExpressionEditorInstance instance = new MyExpressionEditorInstance(); + return instance; + } + public void UpdateContext(AssemblyContextControlItem assemblies, ImportedNamespaceContextItem importedNamespaces) + { + + } + + } +} +``` + + Here is the code for a `MyExpressionEditorInstance` class that implements the interface in a MyExpressionEditorService library project. + +```csharp +using System; +using System.Activities.Presentation.View; +using System.Windows; +using System.Reflection; +using System.Windows.Controls; + +namespace MyExpressionEditorService +{ + public class MyExpressionEditorInstance : IExpressionEditorInstance + { + private TextBox textBox = new TextBox(); + + public bool AcceptsReturn { get; set; } + public bool AcceptsTab { get; set; } + public bool HasAggregateFocus { + get + { + return true; + } + } + + public System.Windows.Controls.ScrollBarVisibility HorizontalScrollBarVisibility { get; set; } + public System.Windows.Controls.Control HostControl { + get + { + return textBox; + } + } + public int MaxLines { get; set; } + public int MinLines { get; set; } + public string Text { get; set; } + public System.Windows.Controls.ScrollBarVisibility VerticalScrollBarVisibility { get; set; } + + public event EventHandler Closing; + public event EventHandler GotAggregateFocus; + public event EventHandler LostAggregateFocus; + public event EventHandler TextChanged; + + public bool CanCompleteWord() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool CanCopy() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool CanCut() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool CanDecreaseFilterLevel() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool CanGlobalIntellisense() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool CanIncreaseFilterLevel() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool CanParameterInfo() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool CanPaste() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool CanQuickInfo() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool CanRedo() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool CanUndo() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + + public void ClearSelection() + { + MessageBox.Show(MethodBase.GetCurrentMethod().Name); + } + public void Close() + { + MessageBox.Show(MethodBase.GetCurrentMethod().Name); + } + public bool CompleteWord() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool Copy() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool Cut() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool DecreaseFilterLevel() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public void Focus() + { + MessageBox.Show(MethodBase.GetCurrentMethod().Name); + } + public string GetCommittedText() + { + return "CommittedText"; + } + public bool GlobalIntellisense() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool IncreaseFilterLevel() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool ParameterInfo() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool Paste() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool QuickInfo() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool Redo() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + public bool Undo() + { + return (MessageBox.Show(MethodBase.GetCurrentMethod().Name, "TestEditorInstance", MessageBoxButton.YesNo) == MessageBoxResult.Yes); + } + } +} +``` + +### Publishing a Custom Expression Editor in a WPF Project + + Here is the code that shows how to rehost the designer in a WPF application and how to create and publish the `MyEditorService` service. Before using this code, add a reference to the MyExpressionEditorService library project from the project that contains the avalon2 application. + +```csharp +using System.Windows; +using System.Windows.Controls; +using System.Activities.Presentation; +using System.Activities.Statements; +using System.Activities.Core.Presentation; +using System.Activities.Presentation.View; +using MyExpressionEditorService; + +namespace WpfApplication1 +{ + /// + /// Interaction logic for MainWindow.xaml + /// + public partial class MainWindow : Window + { + + private MyEditorService expressionEditorService; + public MainWindow() + { + InitializeComponent(); + new DesignerMetadata().Register(); + createDesigner(); + } + + public void createDesigner() + { + WorkflowDesigner designer = new WorkflowDesigner(); + Sequence root = new Sequence() + { + Activities = { + new Assign(), + new WriteLine()} + }; + + designer.Load(root); + + Grid.SetColumn(designer.View, 0); + // Create ExpressionEditorService - this.expressionEditorService = new MyEditorService(); - - // Publish the instance of MyEditorService. - designer.Context.Services.Publish(this.expressionEditorService); - - MyGrid.Children.Add(designer.View); - } - } -} -``` - -### Notes - - If you are using an **ExpressionTextBox** control in a custom activity designer, it is not necessary to create and destroy expression editors using the and methods of the interface. The class manages this for you. - + this.expressionEditorService = new MyEditorService(); + + // Publish the instance of MyEditorService. + designer.Context.Services.Publish(this.expressionEditorService); + + MyGrid.Children.Add(designer.View); + } + } +} +``` + +### Notes + + If you are using an **ExpressionTextBox** control in a custom activity designer, it is not necessary to create and destroy expression editors using the and methods of the interface. The class manages this for you. + ## See also - diff --git a/docs/framework/windows-workflow-foundation/using-activity-delegates.md b/docs/framework/windows-workflow-foundation/using-activity-delegates.md index 9bcdc9ee76ce0..d620d55e0d7a0 100644 --- a/docs/framework/windows-workflow-foundation/using-activity-delegates.md +++ b/docs/framework/windows-workflow-foundation/using-activity-delegates.md @@ -6,13 +6,13 @@ ms.assetid: e33cf876-8979-440b-9b23-4a12d1139960 --- # Using Activity Delegates -Activity delegates enable activity authors to expose callbacks with specific signatures, for which users of the activity can provide activity-based handlers. Two types of activity delegates are available: is used to define activity delegates that do not have a return value, and is used to define activity delegates that do have a return value. +Activity delegates enable activity authors to expose callbacks with specific signatures, for which users of the activity can provide activity-based handlers. Two types of activity delegates are available: is used to define activity delegates that do not have a return value, and is used to define activity delegates that do have a return value. -Activity delegates are useful in scenarios where a child activity must be constrained to having a certain signature. For example, a activity can contain any type of child activity with no constraints, but the body of a activity is an , and the child activity that is ultimately executed by must have an that is the same type of the members of the collection that the enumerates. +Activity delegates are useful in scenarios where a child activity must be constrained to having a certain signature. For example, a activity can contain any type of child activity with no constraints, but the body of a activity is an , and the child activity that is ultimately executed by must have an that is the same type of the members of the collection that the enumerates. ## Using ActivityAction -Several .NET Framework 4.6.1 activities use activity actions, such as the activity and the activity. In each case, the activity action represents a location where the workflow author specifies an activity to provide the desired behavior when composing a workflow using one of these activities. In the following example, a activity is used to display text to the console window. The body of the is specified by using an that matches the type of the which is string. The activity specified in the has its argument bound to the string values in the collection that the activity iterates. +Several .NET Framework 4.6.1 activities use activity actions, such as the activity and the activity. In each case, the activity action represents a location where the workflow author specifies an activity to provide the desired behavior when composing a workflow using one of these activities. In the following example, a activity is used to display text to the console window. The body of the is specified by using an that matches the type of the which is string. The activity specified in the has its argument bound to the string values in the collection that the activity iterates. [!code-csharp[CFX_ActivityExample#6](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#6)] @@ -28,11 +28,11 @@ The examples in this topic use object initialization syntax. Object initializati For more information about object initializers, see [How to: Initialize Objects without Calling a Constructor (C# Programming Guide)](../../csharp/programming-guide/classes-and-structs/how-to-initialize-objects-by-using-an-object-initializer.md) and [How to: Declare an Object by Using an Object Initializer (Visual Basic)](../../visual-basic/programming-guide/language-features/objects-and-classes/how-to-declare-an-object-by-using-an-object-initializer.md). -In the following example, a activity is used in a workflow. An is thrown by the workflow, and is handled by a activity. The handler for the activity's activity action is a activity, and the exception detail is flowed through to it using the `ex` . +In the following example, a activity is used in a workflow. An is thrown by the workflow, and is handled by a activity. The handler for the activity's activity action is a activity, and the exception detail is flowed through to it using the `ex` . [!code-csharp[CFX_WorkflowApplicationExample#33](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#33)] -When creating a custom activity that defines an , use an to model the invocation of that . In this example, a custom `WriteLineWithNotification` activity is defined. This activity is composed of a that contains a activity followed by an that invokes an that takes one string argument. +When creating a custom activity that defines an , use an to model the invocation of that . In this example, a custom `WriteLineWithNotification` activity is defined. This activity is composed of a that contains a activity followed by an that invokes an that takes one string argument. [!code-csharp[CFX_ActivityExample#1](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#1)] @@ -40,11 +40,11 @@ When a workflow is created by using the `WriteLineWithNotification` activity, th [!code-csharp[CFX_ActivityExample#2](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#2)] -There are multiple generic versions of and provided for passing one or more arguments. +There are multiple generic versions of and provided for passing one or more arguments. ## Using ActivityFunc - is useful when there is no result value from the activity, and is used when a result value is returned. When creating a custom activity that defines an , use an to model the invocation of that . In the following example, a `WriteFillerText` activity is defined. To supply the filler text, an is specified that takes an integer argument and has a string result. Once the filler text is retrieved, it is displayed to the console using a activity. + is useful when there is no result value from the activity, and is used when a result value is returned. When creating a custom activity that defines an , use an to model the invocation of that . In the following example, a `WriteFillerText` activity is defined. To supply the filler text, an is specified that takes an integer argument and has a string result. Once the filler text is retrieved, it is displayed to the console using a activity. [!code-csharp[CFX_ActivityExample#3](~/samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#3)] diff --git a/docs/framework/windows-workflow-foundation/using-the-modelitem-editing-context.md b/docs/framework/windows-workflow-foundation/using-the-modelitem-editing-context.md index ade9f4c65cd55..9d1403043bd78 100644 --- a/docs/framework/windows-workflow-foundation/using-the-modelitem-editing-context.md +++ b/docs/framework/windows-workflow-foundation/using-the-modelitem-editing-context.md @@ -6,146 +6,146 @@ ms.assetid: 7f9f1ea5-0147-4079-8eca-be94f00d3aa1 --- # Using the ModelItem Editing Context -The editing context is the object that the host application uses to communicate with the designer. exposes two methods, and , which can be used - -## The Items collection - - The collection is used to access data that is shared between the host and the designer, or data that is available to all designers. This collection has the following capabilities, accessed via the class: - -1. - -2. - -3. - -4. - -## The Services collection - - The collection is used to access services that the designer uses to interact with the host, or services that all designers use. This collection has the following methods of note: - -1. - -2. - -3. - -4. - -## Assigning a designer an activity - - To specify which designer an activity uses, the Designer attribute is used. - -```csharp -[Designer(typeof(MyClassDesigner))] -public sealed class MyClass : CodeActivity +The editing context is the object that the host application uses to communicate with the designer. exposes two methods, and , which can be used + +## The Items collection + + The collection is used to access data that is shared between the host and the designer, or data that is available to all designers. This collection has the following capabilities, accessed via the class: + +1. + +2. + +3. + +4. + +## The Services collection + + The collection is used to access services that the designer uses to interact with the host, or services that all designers use. This collection has the following methods of note: + +1. + +2. + +3. + +4. + +## Assigning a designer an activity + + To specify which designer an activity uses, the Designer attribute is used. + +```csharp +[Designer(typeof(MyClassDesigner))] +public sealed class MyClass : CodeActivity { } -``` - -## Creating a service - - To create a service that serves as a conduit of information between the designer and the host, an interface and an implementation must be created. The interface is used by the method to define the members of the service, and the implementation contains the logic for the service. In the following code example, a service interface and implementation are created. - -```csharp -public interface IMyService - { - IEnumerable GetValues(string DisplayName); - } - - public class MyServiceImpl : IMyService - { - public IEnumerable GetValues(string DisplayName) - { +``` + +## Creating a service + + To create a service that serves as a conduit of information between the designer and the host, an interface and an implementation must be created. The interface is used by the method to define the members of the service, and the implementation contains the logic for the service. In the following code example, a service interface and implementation are created. + +```csharp +public interface IMyService + { + IEnumerable GetValues(string DisplayName); + } + + public class MyServiceImpl : IMyService + { + public IEnumerable GetValues(string DisplayName) + { return new string[] { DisplayName + " One", - DisplayName + " Two", - "Three " + DisplayName - } ; - } - } -``` - -## Publishing a service - - For a designer to consume a service, it must first be published by the host using the method. - -```csharp -this.Context.Services.Publish(new MyServiceImpl); -``` - -## Subscribing to a service - - The designer obtains access to the service using the method in the method. The following code snippet demonstrates how to subscribe to a service. - -```csharp -protected override void OnModelItemChanged(object newItem) -{ - if (!subscribed) - { - this.Context.Services.Subscribe( - servInstance => - { - listBox1.ItemsSource = servInstance.GetValues(this.ModelItem.Properties["DisplayName"].ComputedValue.ToString()); - } - ); + DisplayName + " Two", + "Three " + DisplayName + } ; + } + } +``` + +## Publishing a service + + For a designer to consume a service, it must first be published by the host using the method. + +```csharp +this.Context.Services.Publish(new MyServiceImpl); +``` + +## Subscribing to a service + + The designer obtains access to the service using the method in the method. The following code snippet demonstrates how to subscribe to a service. + +```csharp +protected override void OnModelItemChanged(object newItem) +{ + if (!subscribed) + { + this.Context.Services.Subscribe( + servInstance => + { + listBox1.ItemsSource = servInstance.GetValues(this.ModelItem.Properties["DisplayName"].ComputedValue.ToString()); + } + ); subscribed = true; - } -} -``` - -## Sharing data using the Items collection - - Using the Items collection is similar to using the Services collection, except that is used instead of Publish. This collection is more appropriate for sharing simple data between the designers and the host, rather than complex functionality. - -## EditingContext host items and services - - The .NET Framework provides a number of built-in items and services accessed through the editing context. - - Items: - -- : Manages the list of referenced local assemblies that will be used inside the workflow for controls (such as the expression editor). - -- : Indicates whether the designer is in a read-only state. - -- : Defines the collection of objects that are currently selected. - -- : - -- : Provides information on the file that the current editing session is based on. - - Services: - -- : Allows properties to be added to the current instance, using . - -- : Allows access to the properties of the designer canvas. - -- : Allows the contents of the toolbox to be updated. - -- : Used to integrate designer commands (such as Context Menu) with custom-provided service implementations. - -- : Provides functionality for the designer debugger. - -- : Provides access to the Expression Editor dialog. - -- : Provides the designer with integrated help functionality. - -- : Provides access to validation errors using . - -- : Provides an internal service to store and retrieve data. This service is used internally by the .NET Framework, and is not intended for external use. - -- : Provides access to the XAML load error collection using . - -- : Used by the designer to interact with the model of the workflow being edited. - -- : Provides access to the root of the model item tree using . - -- : Provides undo and redo functionality. - -- : Maps visual elements to underlying model items. - -- : Stores view states for model items. - -- : Used to customize the virtual container UI behavior. - + } +} +``` + +## Sharing data using the Items collection + + Using the Items collection is similar to using the Services collection, except that is used instead of Publish. This collection is more appropriate for sharing simple data between the designers and the host, rather than complex functionality. + +## EditingContext host items and services + + The .NET Framework provides a number of built-in items and services accessed through the editing context. + + Items: + +- : Manages the list of referenced local assemblies that will be used inside the workflow for controls (such as the expression editor). + +- : Indicates whether the designer is in a read-only state. + +- : Defines the collection of objects that are currently selected. + +- : + +- : Provides information on the file that the current editing session is based on. + + Services: + +- : Allows properties to be added to the current instance, using . + +- : Allows access to the properties of the designer canvas. + +- : Allows the contents of the toolbox to be updated. + +- : Used to integrate designer commands (such as Context Menu) with custom-provided service implementations. + +- : Provides functionality for the designer debugger. + +- : Provides access to the Expression Editor dialog. + +- : Provides the designer with integrated help functionality. + +- : Provides access to validation errors using . + +- : Provides an internal service to store and retrieve data. This service is used internally by the .NET Framework, and is not intended for external use. + +- : Provides access to the XAML load error collection using . + +- : Used by the designer to interact with the model of the workflow being edited. + +- : Provides access to the root of the model item tree using . + +- : Provides undo and redo functionality. + +- : Maps visual elements to underlying model items. + +- : Stores view states for model items. + +- : Used to customize the virtual container UI behavior. + - : Used to register and unregister delegates for event notifications. Also allows a window owner to be set. diff --git a/docs/framework/windows-workflow-foundation/using-workflowidentity-and-versioning.md b/docs/framework/windows-workflow-foundation/using-workflowidentity-and-versioning.md index 2aceff7648514..95454d7649c20 100644 --- a/docs/framework/windows-workflow-foundation/using-workflowidentity-and-versioning.md +++ b/docs/framework/windows-workflow-foundation/using-workflowidentity-and-versioning.md @@ -20,7 +20,7 @@ ms.assetid: b8451735-8046-478f-912b-40870a6c0c3a ## Using WorkflowIdentity -To use , create an instance, configure it, and associate it with a instance. A instance contains three identifying pieces of information. and contain a name and a and are required, and is optional and can be used to specify an additional string containing information such as assembly name or other desired information. A is unique if any of its three properties are different from another . +To use , create an instance, configure it, and associate it with a instance. A instance contains three identifying pieces of information. and contain a name and a and are required, and is optional and can be used to specify an additional string containing information such as assembly name or other desired information. A is unique if any of its three properties are different from another . > [!IMPORTANT] > A should not contain any personally identifiable information (PII). Information about the used to create an instance is emitted to any configured tracking services at several different points of the activity life-cycle by the runtime. WF Tracking does not have any mechanism to hide PII (sensitive user data). Therefore, a instance should not contain any PII data as it will be emitted by the runtime in tracking records and may be visible to anyone with access to view the tracking records. @@ -81,7 +81,7 @@ The WorkflowIdentity ('MortgageWorkflow v1; Version=1.0.0.0') of the loaded inst can be used to facilitate the execution of multiple versions of a workflow side-by-side. One common scenario is changing business requirements on a long-running workflow. Many instances of a workflow could be running when an updated version is deployed. The host application can be configured to use the updated workflow definition when starting new instances, and it is the responsibility of the host application to provide the correct workflow definition when resuming instances. can be used to identify and supply the matching workflow definition when resuming workflow instances. -To retrieve the of a persisted workflow instance, the method is used. The method takes the of the persisted workflow instance and the that contains the persisted instance and returns a . A contains information about a persisted workflow instance, including its associated . This associated can be used by the host to supply the correct workflow definition when loading and resuming the workflow instance. +To retrieve the of a persisted workflow instance, the method is used. The method takes the of the persisted workflow instance and the that contains the persisted instance and returns a . A contains information about a persisted workflow instance, including its associated . This associated can be used by the host to supply the correct workflow definition when loading and resuming the workflow instance. > [!NOTE] > A null is valid, and can be used by the host to map instances that were persisted with no associated to the proper workflow definition. This scenario can occur when a workflow application was not initially written with workflow versioning, or when an application is upgraded from .NET Framework 4. For more information, see [Upgrading .NET Framework 4 Persistence Databases to Support Workflow Versioning](using-workflowidentity-and-versioning.md#UpdatingWF4PersistenceDatabases). @@ -114,10 +114,10 @@ ConfigureWorkflowApplication(wfApp); wfApp.Run(); ``` -In the following example, information about the persisted workflow instance from the previous example is retrieved by calling , and the persisted information is used to retrieve the matching workflow definition. This information is used to configure the , and then the workflow is loaded. Note that because the overload that takes the is used, the that was configured on the is used by the and therefore its property does not need to be configured. +In the following example, information about the persisted workflow instance from the previous example is retrieved by calling , and the persisted information is used to retrieve the matching workflow definition. This information is used to configure the , and then the workflow is loaded. Note that because the overload that takes the is used, the that was configured on the is used by the and therefore its property does not need to be configured. > [!NOTE] -> If the property is set, it must be set with the same instance used by the or else an will be thrown with the following message: `The instance is configured with a different InstanceStore than this WorkflowApplication.`. +> If the property is set, it must be set with the same instance used by the or else an will be thrown with the following message: `The instance is configured with a different InstanceStore than this WorkflowApplication.`. ```csharp // Get the WorkflowApplicationInstance of the desired workflow from the specified diff --git a/docs/framework/windows-workflow-foundation/using-workflowinvoker-and-workflowapplication.md b/docs/framework/windows-workflow-foundation/using-workflowinvoker-and-workflowapplication.md index 267403b1d715b..cf8e547c05f7c 100644 --- a/docs/framework/windows-workflow-foundation/using-workflowinvoker-and-workflowapplication.md +++ b/docs/framework/windows-workflow-foundation/using-workflowinvoker-and-workflowapplication.md @@ -6,101 +6,101 @@ ms.assetid: cd0e583c-a3f9-4fa2-b247-c7b3368c48a7 --- # Using WorkflowInvoker and WorkflowApplication -Windows Workflow Foundation (WF) provides several methods of hosting workflows. provides a simple way for invoking a workflow as if it were a method call and can be used only for workflows that do not use persistence. provides a richer model for executing workflows that includes notification of lifecycle events, execution control, bookmark resumption, and persistence. provides support for messaging activities and is primarily used with workflow services. This topic introduces you to workflow hosting with and . For more information about hosting workflows with , see [Workflow Services](../wcf/feature-details/workflow-services.md) and [Hosting Workflow Services Overview](../wcf/feature-details/hosting-workflow-services-overview.md). - -## Using WorkflowInvoker - - provides a model for executing a workflow as if it were a method call. To invoke a workflow using , call the method and pass in the workflow definition of the workflow to invoke. In this example, a activity is invoked using . - - [!code-csharp[CFX_WorkflowInvokerExample#1](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#1)] - - When a workflow is invoked using , the workflow executes on the calling thread and the method blocks until the workflow is complete, including any idle time. To configure a time-out interval in which the workflow must complete, use one of the overloads that takes a parameter. In this example, a workflow is invoked twice with two different time-out intervals. The first workflow completes, but the second does not. - - [!code-csharp[CFX_WorkflowInvokerExample#50](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#50)] - +Windows Workflow Foundation (WF) provides several methods of hosting workflows. provides a simple way for invoking a workflow as if it were a method call and can be used only for workflows that do not use persistence. provides a richer model for executing workflows that includes notification of lifecycle events, execution control, bookmark resumption, and persistence. provides support for messaging activities and is primarily used with workflow services. This topic introduces you to workflow hosting with and . For more information about hosting workflows with , see [Workflow Services](../wcf/feature-details/workflow-services.md) and [Hosting Workflow Services Overview](../wcf/feature-details/hosting-workflow-services-overview.md). + +## Using WorkflowInvoker + + provides a model for executing a workflow as if it were a method call. To invoke a workflow using , call the method and pass in the workflow definition of the workflow to invoke. In this example, a activity is invoked using . + + [!code-csharp[CFX_WorkflowInvokerExample#1](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#1)] + + When a workflow is invoked using , the workflow executes on the calling thread and the method blocks until the workflow is complete, including any idle time. To configure a time-out interval in which the workflow must complete, use one of the overloads that takes a parameter. In this example, a workflow is invoked twice with two different time-out intervals. The first workflow completes, but the second does not. + + [!code-csharp[CFX_WorkflowInvokerExample#50](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#50)] + > [!NOTE] -> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. - - also provides asynchronous versions of the invoke method. For more information, see and . - -### Setting Input Arguments of a Workflow - - Data can be passed into a workflow using a dictionary of input parameters, keyed by argument name, that map to the input arguments of the workflow. In this example, a is invoked and the value for its argument is specified using the dictionary of input parameters. - - [!code-csharp[CFX_WorkflowInvokerExample#3](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#3)] - -### Retrieving Output Arguments of a Workflow - - The output parameters of a workflow can be obtained using the outputs dictionary that is returned from the call to . The following example invokes a workflow consisting of a single `Divide` activity that has two input arguments and two output arguments. When the workflow is invoked, the `arguments` dictionary is passed which contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, each output argument is returned in the `outputs` dictionary, also keyed by argument name. - - [!code-csharp[CFX_WorkflowInvokerExample#120](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#120)] - - [!code-csharp[CFX_WorkflowInvokerExample#20](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#20)] - - If the workflow derives from , such as `CodeActivity` or `Activity`, and there are output arguments in addition to the well-defined output argument, a non-generic overload of `Invoke` must be used in order to retrieve the additional arguments. To do this, the workflow definition passed into `Invoke` must be of type . In this example the `Divide` activity derives from `CodeActivity`, but is declared as so that a non-generic overload of `Invoke` is used which returns a dictionary of arguments instead of a single return value. - - [!code-csharp[CFX_WorkflowInvokerExample#121](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#121)] - - [!code-csharp[CFX_WorkflowInvokerExample#21](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#21)] - -## Using WorkflowApplication - - provides a rich set of features for workflow instance management. acts as a thread safe proxy to the actual , which encapsulates the runtime, and provides methods for creating and loading workflow instances, pausing and resuming, terminating, and notification of lifecycle events. To run a workflow using you create the , subscribe to any desired lifecycle events, start the workflow, and then wait for it to finish. In this example, a workflow definition that consists of a activity is created and a is created using the specified workflow definition. is handled so the host is notified when the workflow completes, the workflow is started with a call to , and then the host waits for the workflow to complete. When the workflow completes, the is set and the host application can resume execution, as shown in the following example. - - [!code-csharp[CFX_WorkflowApplicationExample#31](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#31)] - -### WorkflowApplication Lifecycle Events - - In addition to , host authors can be notified when a workflow is unloaded (), aborted (), becomes idle ( and ), or an unhandled exception occurs (). Workflow application developers can handle these notifications and take appropriate action, as shown in the following example. - - [!code-csharp[CFX_WorkflowApplicationExample#32](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#32)] - -### Setting Input Arguments of a Workflow - - Data can be passed into a workflow as it is started using a dictionary of parameters, similar to the way data is passed in when using . Each item in the dictionary maps to an input argument of the specified workflow. In this example, a workflow that consists of a activity is invoked and its argument is specified using the dictionary of input parameters. - - [!code-csharp[CFX_WorkflowApplicationExample#30](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#30)] - -### Retrieving Output Arguments of a Workflow - - When a workflow completes, any output arguments can be retrieved in the handler by accessing the dictionary. The following example hosts a workflow using . A instance is constructed using a workflow definition consisting of a single `DiceRoll` activity. The `DiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes, the outputs are retrieved in the handler. - - [!code-csharp[CFX_WorkflowApplicationExample#130](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#130)] - - [!code-csharp[CFX_WorkflowApplicationExample#21](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#21)] - +> The is only thrown if the time-out interval elapses and the workflow becomes idle during execution. A workflow that takes longer than the specified time-out interval to complete completes successfully if the workflow does not become idle. + + also provides asynchronous versions of the invoke method. For more information, see and . + +### Setting Input Arguments of a Workflow + + Data can be passed into a workflow using a dictionary of input parameters, keyed by argument name, that map to the input arguments of the workflow. In this example, a is invoked and the value for its argument is specified using the dictionary of input parameters. + + [!code-csharp[CFX_WorkflowInvokerExample#3](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#3)] + +### Retrieving Output Arguments of a Workflow + + The output parameters of a workflow can be obtained using the outputs dictionary that is returned from the call to . The following example invokes a workflow consisting of a single `Divide` activity that has two input arguments and two output arguments. When the workflow is invoked, the `arguments` dictionary is passed which contains the values for each input argument, keyed by argument name. When the call to `Invoke` returns, each output argument is returned in the `outputs` dictionary, also keyed by argument name. + + [!code-csharp[CFX_WorkflowInvokerExample#120](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#120)] + + [!code-csharp[CFX_WorkflowInvokerExample#20](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#20)] + + If the workflow derives from , such as `CodeActivity` or `Activity`, and there are output arguments in addition to the well-defined output argument, a non-generic overload of `Invoke` must be used in order to retrieve the additional arguments. To do this, the workflow definition passed into `Invoke` must be of type . In this example the `Divide` activity derives from `CodeActivity`, but is declared as so that a non-generic overload of `Invoke` is used which returns a dictionary of arguments instead of a single return value. + + [!code-csharp[CFX_WorkflowInvokerExample#121](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#121)] + + [!code-csharp[CFX_WorkflowInvokerExample#21](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowinvokerexample/cs/program.cs#21)] + +## Using WorkflowApplication + + provides a rich set of features for workflow instance management. acts as a thread safe proxy to the actual , which encapsulates the runtime, and provides methods for creating and loading workflow instances, pausing and resuming, terminating, and notification of lifecycle events. To run a workflow using you create the , subscribe to any desired lifecycle events, start the workflow, and then wait for it to finish. In this example, a workflow definition that consists of a activity is created and a is created using the specified workflow definition. is handled so the host is notified when the workflow completes, the workflow is started with a call to , and then the host waits for the workflow to complete. When the workflow completes, the is set and the host application can resume execution, as shown in the following example. + + [!code-csharp[CFX_WorkflowApplicationExample#31](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#31)] + +### WorkflowApplication Lifecycle Events + + In addition to , host authors can be notified when a workflow is unloaded (), aborted (), becomes idle ( and ), or an unhandled exception occurs (). Workflow application developers can handle these notifications and take appropriate action, as shown in the following example. + + [!code-csharp[CFX_WorkflowApplicationExample#32](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#32)] + +### Setting Input Arguments of a Workflow + + Data can be passed into a workflow as it is started using a dictionary of parameters, similar to the way data is passed in when using . Each item in the dictionary maps to an input argument of the specified workflow. In this example, a workflow that consists of a activity is invoked and its argument is specified using the dictionary of input parameters. + + [!code-csharp[CFX_WorkflowApplicationExample#30](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#30)] + +### Retrieving Output Arguments of a Workflow + + When a workflow completes, any output arguments can be retrieved in the handler by accessing the dictionary. The following example hosts a workflow using . A instance is constructed using a workflow definition consisting of a single `DiceRoll` activity. The `DiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes, the outputs are retrieved in the handler. + + [!code-csharp[CFX_WorkflowApplicationExample#130](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#130)] + + [!code-csharp[CFX_WorkflowApplicationExample#21](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#21)] + > [!NOTE] -> and take a dictionary of input arguments and return a dictionary of `out` arguments. These dictionary parameters, properties, and return values are of type `IDictionary`. The actual instance of the dictionary class that is passed in can be any class that implements `IDictionary`. In these examples, `Dictionary` is used. For more information about dictionaries, see and . - -### Passing Data into a Running Workflow Using Bookmarks - - Bookmarks are the mechanism by which an activity can passively wait to be resumed and are a mechanism for passing data into a running workflow instance. If an activity is waiting for data, it can create a and register a callback method to be called when the is resumed, as shown in the following example. - - [!code-csharp[CFX_WorkflowApplicationExample#15](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#15)] - - When executed, the `ReadLine` activity creates a , registers a callback, and then waits for the to be resumed. When it is resumed, the `ReadLine` activity assigns the data that was passed with the to its argument. In this example, a workflow is created that uses the `ReadLine` activity to gather the user’s name and display it to the console window. - - [!code-csharp[CFX_WorkflowApplicationExample#22](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#22)] - - When the `ReadLine` activity is executed, it creates a named `UserName` and then waits for the bookmark to be resumed. The host collects the desired data and then resumes the . The workflow resumes, displays the name, and then completes. - - The host application can inspect the workflow to determine if there are any active bookmarks. It can do this by calling the method of a instance, or by inspecting the in the handler. - - The following code example is like the previous example except that the active bookmarks are enumerated before the bookmark is resumed. The workflow is started, and once the is created and the workflow goes idle, is called. When the workflow is completed, the following output is displayed to the console. - - **What is your name?** +> and take a dictionary of input arguments and return a dictionary of `out` arguments. These dictionary parameters, properties, and return values are of type `IDictionary`. The actual instance of the dictionary class that is passed in can be any class that implements `IDictionary`. In these examples, `Dictionary` is used. For more information about dictionaries, see and . + +### Passing Data into a Running Workflow Using Bookmarks + + Bookmarks are the mechanism by which an activity can passively wait to be resumed and are a mechanism for passing data into a running workflow instance. If an activity is waiting for data, it can create a and register a callback method to be called when the is resumed, as shown in the following example. + + [!code-csharp[CFX_WorkflowApplicationExample#15](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#15)] + + When executed, the `ReadLine` activity creates a , registers a callback, and then waits for the to be resumed. When it is resumed, the `ReadLine` activity assigns the data that was passed with the to its argument. In this example, a workflow is created that uses the `ReadLine` activity to gather the user’s name and display it to the console window. + + [!code-csharp[CFX_WorkflowApplicationExample#22](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#22)] + + When the `ReadLine` activity is executed, it creates a named `UserName` and then waits for the bookmark to be resumed. The host collects the desired data and then resumes the . The workflow resumes, displays the name, and then completes. + + The host application can inspect the workflow to determine if there are any active bookmarks. It can do this by calling the method of a instance, or by inspecting the in the handler. + + The following code example is like the previous example except that the active bookmarks are enumerated before the bookmark is resumed. The workflow is started, and once the is created and the workflow goes idle, is called. When the workflow is completed, the following output is displayed to the console. + + **What is your name?** **BookmarkName: UserName - OwnerDisplayName: ReadLine** **Steve** **Hello, Steve** -[!code-csharp[CFX_WorkflowApplicationExample#14](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#14)] - - The following code example inspects the passed into the handler of a instance. In this example the workflow going idle has one with a name of `EnterGuess`, owned by an activity named `ReadInt`. This code example is based off of [How to: Run a Workflow](how-to-run-a-workflow.md), which is part of the [Getting Started Tutorial](getting-started-tutorial.md). If the handler in that step is modified to contain the code from this example, the following output is displayed. - +[!code-csharp[CFX_WorkflowApplicationExample#14](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#14)] + + The following code example inspects the passed into the handler of a instance. In this example the workflow going idle has one with a name of `EnterGuess`, owned by an activity named `ReadInt`. This code example is based off of [How to: Run a Workflow](how-to-run-a-workflow.md), which is part of the [Getting Started Tutorial](getting-started-tutorial.md). If the handler in that step is modified to contain the code from this example, the following output is displayed. + **BookmarkName: EnterGuess - OwnerDisplayName: ReadInt** - [!code-csharp[CFX_WorkflowApplicationExample#2](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#2)] - -## Summary + [!code-csharp[CFX_WorkflowApplicationExample#2](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#2)] + +## Summary provides a lightweight way to invoke workflows, and although it provides methods for passing data in at the start of a workflow and extracting data from a completed workflow, it does not provide for more complex scenarios which is where can be used. diff --git a/docs/framework/windows-workflow-foundation/variables-and-arguments.md b/docs/framework/windows-workflow-foundation/variables-and-arguments.md index 2396c62cd64a1..94ee305db9343 100644 --- a/docs/framework/windows-workflow-foundation/variables-and-arguments.md +++ b/docs/framework/windows-workflow-foundation/variables-and-arguments.md @@ -10,7 +10,7 @@ In Windows Workflow Foundation (WF), variables represent the storage of data and ## Variables - Variables are storage locations for data. Variables are declared as part of the definition of a workflow. Variables take on values at runtime and these values are stored as part of the state of a workflow instance. A variable definition specifies the type of the variable and optionally, the name. The following code shows how to declare a variable, assign a value to it using an activity, and then display its value to the console using a activity. + Variables are storage locations for data. Variables are declared as part of the definition of a workflow. Variables take on values at runtime and these values are stored as part of the state of a workflow instance. A variable definition specifies the type of the variable and optionally, the name. The following code shows how to declare a variable, assign a value to it using an activity, and then display its value to the console using a activity. ```csharp // Define a variable named "str" of type string. @@ -62,17 +62,17 @@ Variable var = new Variable The workflow runtime makes the following guarantees about the timing of data movement into and out of activities: -1. When an activity starts executing, the values of all of its input and input/output arguments are calculated. For example, regardless of when is called, the value returned is the one calculated by the runtime prior to its invocation of `Execute`. +1. When an activity starts executing, the values of all of its input and input/output arguments are calculated. For example, regardless of when is called, the value returned is the one calculated by the runtime prior to its invocation of `Execute`. -2. When is called, the runtime sets the value immediately. +2. When is called, the runtime sets the value immediately. -3. Arguments can optionally have their specified. is a zero-based value that specifies the order in which the argument is evaluated. By default, the evaluation order of the argument is unspecified and is equal to the value. Set to a value greater or equal to zero to specify an evaluation order for this argument. Windows Workflow Foundation evaluates arguments with a specified evaluation order in ascending order. Note that arguments with an unspecified evaluation order are evaluated before those with a specified evaluation order. +3. Arguments can optionally have their specified. is a zero-based value that specifies the order in which the argument is evaluated. By default, the evaluation order of the argument is unspecified and is equal to the value. Set to a value greater or equal to zero to specify an evaluation order for this argument. Windows Workflow Foundation evaluates arguments with a specified evaluation order in ascending order. Note that arguments with an unspecified evaluation order are evaluated before those with a specified evaluation order. - An activity author can use a strongly typed mechanism for exposing its arguments. This is accomplished by declaring properties of type , , and . This allows an activity author to establish a specific contract about the data going into and out of an activity. + An activity author can use a strongly typed mechanism for exposing its arguments. This is accomplished by declaring properties of type , , and . This allows an activity author to establish a specific contract about the data going into and out of an activity. ### Defining the Arguments on an Activity - Arguments can be defined on an activity by specifying properties of type , , and . The following code shows how to define the arguments for a `Prompt` activity that takes in a string to display to the user and returns a string that contains the user's response. + Arguments can be defined on an activity by specifying properties of type , , and . The following code shows how to define the arguments for a `Prompt` activity that takes in a string to display to the user and returns a string that contains the user's response. ```csharp public class Prompt : Activity @@ -84,11 +84,11 @@ public class Prompt : Activity ``` > [!NOTE] -> Activities that return a single value can derive from , , or . These activities have a well-defined named that contains the return value of the activity. +> Activities that return a single value can derive from , , or . These activities have a well-defined named that contains the return value of the activity. ### Using Variables and Arguments in Workflows - The following example shows how variables and arguments are used in a workflow. The workflow is a sequence that declares three variables: `var1`, `var2`, and `var3`. The first activity in the workflow is an `Assign` activity that assigns the value of variable `var1` to the variable `var2`. This is followed by a `WriteLine` activity that prints the value of the `var2` variable. Next is another `Assign` activity that assigns the value of variable `var2` to the variable `var3`. Finally there is another `WriteLine` activity that prints the value of the `var3` variable. The first `Assign` activity uses `InArgument` and `OutArgument` objects that explicitly represent the bindings for the activity's arguments. `InArgument` is used for because the value is flowing into the activity through its argument, and `OutArgument` is used for because the value is flowing out of the argument into the variable. The second `Assign` activity accomplishes the same thing with more compact but equivalent syntax that uses implicit casts. The `WriteLine` activities also use the compact syntax. + The following example shows how variables and arguments are used in a workflow. The workflow is a sequence that declares three variables: `var1`, `var2`, and `var3`. The first activity in the workflow is an `Assign` activity that assigns the value of variable `var1` to the variable `var2`. This is followed by a `WriteLine` activity that prints the value of the `var2` variable. Next is another `Assign` activity that assigns the value of variable `var2` to the variable `var3`. Finally there is another `WriteLine` activity that prints the value of the `var3` variable. The first `Assign` activity uses `InArgument` and `OutArgument` objects that explicitly represent the bindings for the activity's arguments. `InArgument` is used for because the value is flowing into the activity through its argument, and `OutArgument` is used for because the value is flowing out of the argument into the variable. The second `Assign` activity accomplishes the same thing with more compact but equivalent syntax that uses implicit casts. The `WriteLine` activities also use the compact syntax. ```csharp // Declare three variables; the first one is given an initial value. @@ -125,7 +125,7 @@ WorkflowInvoker.Invoke(wf); ### Using Variables and Arguments in Code-Based Activities - The previous examples show how to use arguments and variables in workflows and declarative activities. Arguments and variables are also used in code-based activities. Conceptually the usage is very similar. Variables represent data storage within the activity, and arguments represent the flow of data into or out of the activity, and are bound by the workflow author to other variables or arguments in the workflow that represent where the data flows to or from. To get or set the value of a variable or argument in an activity, an activity context must be used that represents the current execution environment of the activity. This is passed into the method of the activity by the workflow runtime. In this example, a custom `Add` activity is defined that has two arguments. To access the value of the arguments, the method is used and the context that was passed in by the workflow runtime is used. + The previous examples show how to use arguments and variables in workflows and declarative activities. Arguments and variables are also used in code-based activities. Conceptually the usage is very similar. Variables represent data storage within the activity, and arguments represent the flow of data into or out of the activity, and are bound by the workflow author to other variables or arguments in the workflow that represent where the data flows to or from. To get or set the value of a variable or argument in an activity, an activity context must be used that represents the current execution environment of the activity. This is passed into the method of the activity by the workflow runtime. In this example, a custom `Add` activity is defined that has two arguments. To access the value of the arguments, the method is used and the context that was passed in by the workflow runtime is used. ```csharp public sealed class Add : CodeActivity diff --git a/docs/framework/windows-workflow-foundation/wf-features-in-the-rehosted-workflow-designer.md b/docs/framework/windows-workflow-foundation/wf-features-in-the-rehosted-workflow-designer.md index 6aa9dc329faee..5bcede0261421 100644 --- a/docs/framework/windows-workflow-foundation/wf-features-in-the-rehosted-workflow-designer.md +++ b/docs/framework/windows-workflow-foundation/wf-features-in-the-rehosted-workflow-designer.md @@ -77,7 +77,7 @@ Windows Workflow Foundation (WF) in .NET Framework 4.5 introduced many new featu ### More control of visibility of shell bar and header items - In a rehosted designer, some of the standard UI controls may not have meaning for a given workflow, and may be turned off. In .NET Framework 4, this customization is only supported by the shell bar at the bottom of the designer. In .NET Framework 4.5, the visibility of shell header items at the top of the designer can be adjusted by setting with the appropriate value. + In a rehosted designer, some of the standard UI controls may not have meaning for a given workflow, and may be turned off. In .NET Framework 4, this customization is only supported by the shell bar at the bottom of the designer. In .NET Framework 4.5, the visibility of shell header items at the top of the designer can be adjusted by setting with the appropriate value. ### Auto-connect and auto-insert in Flowchart and State Machine workflows @@ -128,7 +128,7 @@ Windows Workflow Foundation (WF) in .NET Framework 4.5 introduced many new featu ### Opt-in for Workflow 4.5 features in rehosted designer - To preserve backward compatibility, some new features included in .NET Framework 4.5 are not enabled by default in the rehosted designer. This is to ensure that existing applications that use the rehosted designer are not broken by updating to the latest version. To enable new features in the rehosted designer, either set to ".Net Framework 4.5", or set individual members of to enable individual features. + To preserve backward compatibility, some new features included in .NET Framework 4.5 are not enabled by default in the rehosted designer. This is to ensure that existing applications that use the rehosted designer are not broken by updating to the latest version. To enable new features in the rehosted designer, either set to ".Net Framework 4.5", or set individual members of to enable individual features. ## New Workflow Development Models diff --git a/docs/framework/windows-workflow-foundation/whats-new-in-wf-in-dotnet.md b/docs/framework/windows-workflow-foundation/whats-new-in-wf-in-dotnet.md index bcdbe07d07780..ff9af15929639 100644 --- a/docs/framework/windows-workflow-foundation/whats-new-in-wf-in-dotnet.md +++ b/docs/framework/windows-workflow-foundation/whats-new-in-wf-in-dotnet.md @@ -21,7 +21,7 @@ Windows Workflow Foundation (WF) in .NET Framework 4.5 introduces many new featu .NET Framework 4.5 introduced several new versioning features based around the new class. provides workflow application authors a mechanism for mapping a persisted workflow instance with its definition. -- Developers using hosting can use to enable hosting multiple versions of a workflow side-by-side. Persisted workflow instances can be loaded using the new class, and then the can be used by the host to provide the correct version of the workflow definition when instantiating the . For more information, see [Using WorkflowIdentity and Versioning](using-workflowidentity-and-versioning.md) and [How to: Host Multiple Versions of a Workflow Side-by-Side](how-to-host-multiple-versions-of-a-workflow-side-by-side.md). +- Developers using hosting can use to enable hosting multiple versions of a workflow side-by-side. Persisted workflow instances can be loaded using the new class, and then the can be used by the host to provide the correct version of the workflow definition when instantiating the . For more information, see [Using WorkflowIdentity and Versioning](using-workflowidentity-and-versioning.md) and [How to: Host Multiple Versions of a Workflow Side-by-Side](how-to-host-multiple-versions-of-a-workflow-side-by-side.md). - is now a multi-version host. When a new version of a workflow service is deployed, new instances are created using the new service, but existing instances complete using the previous version. For more information, see [Side by Side Versioning in WorkflowServiceHost](../wcf/feature-details/side-by-side-versioning-in-workflowservicehost.md). @@ -41,7 +41,7 @@ The built-in activity library contains new activities and new features for exist Flowcharts are updated for .NET Framework 4.5 and have the following new capabilities: -- The `DisplayName` property of a or activity is editable. This will let the activity designer show more information about the activity's purpose. +- The `DisplayName` property of a or activity is editable. This will let the activity designer show more information about the activity's purpose. - Flowcharts have a new property called ; the default for this property is `False`. If this property is set to `True`, then unconnected flowchart nodes will produce validation errors. @@ -68,11 +68,11 @@ Workflows in .NET Framework 4 required a fully trusted application domain. In .N If exceptions are not to be serialized, ensure that exceptions are used within a . -4. Activity authors should override to avoid having the workflow runtime automatically execute reflection against the type. Arguments and child activities must be non-null, and must be called explicitly. For more information on overriding , see [Exposing data with CacheMetadata](exposing-data-with-cachemetadata.md). Also, instances of arguments that are of a type that is `internal` or **private** must be explicitly created in to avoid being created by reflection. +4. Activity authors should override to avoid having the workflow runtime automatically execute reflection against the type. Arguments and child activities must be non-null, and must be called explicitly. For more information on overriding , see [Exposing data with CacheMetadata](exposing-data-with-cachemetadata.md). Also, instances of arguments that are of a type that is `internal` or **private** must be explicitly created in to avoid being created by reflection. 5. Types will not use or for serialization; types that are to be serialized must support . -6. Expressions that use require , and thus will not work under partial trust. Workflows that use should replace those expressions with activities that derive from . . +6. Expressions that use require , and thus will not work under partial trust. Workflows that use should replace those expressions with activities that derive from . . 7. Expressions cannot be compiled using or the Visual Basic hosted compiler in partial trust, but previously compiled expressions can be run. @@ -162,7 +162,7 @@ For more information about C# expressions, see [C# Expressions](csharp-expressio ### More control of visibility of shell bar and header items -In a rehosted designer, some of the standard UI controls may not have meaning for a given workflow, and may be turned off. In .NET Framework 4, this customization is only supported by the shell bar at the bottom of the designer. In .NET Framework 4.5, the visibility of shell header items at the top of the designer can be adjusted by setting with the appropriate value. +In a rehosted designer, some of the standard UI controls may not have meaning for a given workflow, and may be turned off. In .NET Framework 4, this customization is only supported by the shell bar at the bottom of the designer. In .NET Framework 4.5, the visibility of shell header items at the top of the designer can be adjusted by setting with the appropriate value. ### Auto-connect and auto-insert in Flowchart and State Machine workflows @@ -208,7 +208,7 @@ In .NET Framework 4.5, we provide a way for developers to create their own expre ### Opt-in for Workflow 4.5 features in rehosted designer -To preserve backward compatibility, some new features included in .NET Framework 4.5 are not enabled by default in the rehosted designer. This is to ensure that existing applications that use the rehosted designer are not broken by updating to the latest version. To enable new features in the rehosted designer, either set to ".NET Framework 4.5", or set individual members of to enable individual features. +To preserve backward compatibility, some new features included in .NET Framework 4.5 are not enabled by default in the rehosted designer. This is to ensure that existing applications that use the rehosted designer are not broken by updating to the latest version. To enable new features in the rehosted designer, either set to ".NET Framework 4.5", or set individual members of to enable individual features. ## New Workflow Development Models diff --git a/docs/framework/windows-workflow-foundation/whats-new.md b/docs/framework/windows-workflow-foundation/whats-new.md index 715bd2c5fac0f..be9f04ab10b41 100644 --- a/docs/framework/windows-workflow-foundation/whats-new.md +++ b/docs/framework/windows-workflow-foundation/whats-new.md @@ -17,15 +17,15 @@ Windows Workflow Foundation (WF) in .NET Framework 4 changes several development ## Rich Composite Activity Options - is a powerful new control flow activity that allows authors to model arbitrary loops and conditional branching. provides an event-driven programming model that was previously only able to be implemented with . Procedural workflows benefit from new flow-control activities that model traditional flow-control structures, such as and . + is a powerful new control flow activity that allows authors to model arbitrary loops and conditional branching. provides an event-driven programming model that was previously only able to be implemented with . Procedural workflows benefit from new flow-control activities that model traditional flow-control structures, such as and . ## Expanded Built-In Activity Library New features of the activity library include: -- New flow control activities, such as , , , , , and . +- New flow control activities, such as , , , , , and . -- Activities for manipulating member data, such as and collection activities such as . +- Activities for manipulating member data, such as and collection activities such as . - Activities for controlling transactions, such as and . diff --git a/docs/framework/windows-workflow-foundation/workflow-activity-authoring-using-the-codeactivity-class.md b/docs/framework/windows-workflow-foundation/workflow-activity-authoring-using-the-codeactivity-class.md index b063a826d6647..c936265e2e779 100644 --- a/docs/framework/windows-workflow-foundation/workflow-activity-authoring-using-the-codeactivity-class.md +++ b/docs/framework/windows-workflow-foundation/workflow-activity-authoring-using-the-codeactivity-class.md @@ -6,17 +6,17 @@ ms.assetid: cfe315c1-f86d-43ec-b9ce-2f8c469b1106 --- # Workflow Activity Authoring Using the CodeActivity Class -Activities created by inheriting from can implement basic imperative behavior by overriding the method. +Activities created by inheriting from can implement basic imperative behavior by overriding the method. ## Using CodeActivityContext - Features of the workflow runtime can be accessed from within the method by using members of the `context` parameter, of type . The features available through include the following: + Features of the workflow runtime can be accessed from within the method by using members of the `context` parameter, of type . The features available through include the following: - Getting and setting the values of variables and arguments. -- Custom tracking features using . +- Custom tracking features using . -- Access to the activity’s execution properties using . +- Access to the activity’s execution properties using . #### To create a custom activity that inherits from CodeActivity @@ -41,7 +41,7 @@ Activities created by inheriting from can class HelloActivity : CodeActivity ``` -7. Add functionality to the class by adding an method. +7. Add functionality to the class by adding an method. ```csharp protected override void Execute(CodeActivityContext context) diff --git a/docs/framework/windows-workflow-foundation/workflow-execution-properties.md b/docs/framework/windows-workflow-foundation/workflow-execution-properties.md index 42571cb66c407..46c1b78f28829 100644 --- a/docs/framework/windows-workflow-foundation/workflow-execution-properties.md +++ b/docs/framework/windows-workflow-foundation/workflow-execution-properties.md @@ -6,158 +6,158 @@ ms.assetid: a50e088e-3a45-4267-bd51-1a3e6c2d246d --- # Workflow Execution Properties -Through thread local storage (TLS), the CLR maintains an execution context for each thread. This execution context governs well-known thread properties such as the thread identity, the ambient transaction, and the current permission set in addition to user-defined thread properties like named slots. - - Unlike programs directly targeting the CLR, workflow programs are hierarchically scoped trees of activities that execute in a thread-agnostic environment. This implies that the standard TLS mechanisms cannot directly be used to determine what context is in scope for a given work item. For example, two parallel branches of execution might use different transactions, yet the scheduler might interleave their execution on the same CLR thread. - - Workflow execution properties provide a mechanism to add context specific properties to an activity’s environment. This allows an activity to declare which properties are in scope for its sub-tree and also provides hooks for setting up and tearing down TLS to properly interoperate with CLR objects. - -## Creating and Using Workflow Execution Properties - - Workflow execution properties usually implement the interface, though properties focused on messaging may implement and instead. To create a workflow execution property, create a class that implements the interface and implement the members and . These members provide the execution property with an opportunity to properly set up and tear down the thread local storage during each pulse of work of the activity that contains the property, including any child activities. In this example, a `ConsoleColorProperty` is created that sets the `Console.ForegroundColor`. - -```csharp -class ConsoleColorProperty : IExecutionProperty -{ - public const string Name = "ConsoleColorProperty"; - - ConsoleColor original; - ConsoleColor color; - - public ConsoleColorProperty(ConsoleColor color) - { - this.color = color; - } - - void IExecutionProperty.SetupWorkflowThread() - { - original = Console.ForegroundColor; - Console.ForegroundColor = color; - } - - void IExecutionProperty.CleanupWorkflowThread() - { - Console.ForegroundColor = original; - } -} -``` - - Activity authors can use this property by registering it in the activity’s execute override. In this example, a `ConsoleColorScope` activity is defined that registers the `ConsoleColorProperty` by adding it to the collection of the current . - -```csharp -public sealed class ConsoleColorScope : NativeActivity -{ - public ConsoleColorScope() - : base() - { - } - - public ConsoleColor Color { get; set; } - public Activity Body { get; set; } - - protected override void Execute(NativeActivityContext context) - { - context.Properties.Add(ConsoleColorProperty.Name, new ConsoleColorProperty(this.Color)); - - if (this.Body != null) - { - context.ScheduleActivity(this.Body); - } - } -} -``` - - When the activity’s body starts a pulse of work, the method of the property is called, and when the pulse of work is complete, the is called. In this example, a workflow is created that uses a activity with three branches. The first two branches use the `ConsoleColorScope` activity and the third branch does not. All three branches contain two activities and a activity. When the activity executes, the activities that are contained in the branches execute in an interleaved manner, but as each child activity executes the correct console color is applied by the `ConsoleColorProperty`. - -```csharp -Activity wf = new Parallel -{ +Through thread local storage (TLS), the CLR maintains an execution context for each thread. This execution context governs well-known thread properties such as the thread identity, the ambient transaction, and the current permission set in addition to user-defined thread properties like named slots. + + Unlike programs directly targeting the CLR, workflow programs are hierarchically scoped trees of activities that execute in a thread-agnostic environment. This implies that the standard TLS mechanisms cannot directly be used to determine what context is in scope for a given work item. For example, two parallel branches of execution might use different transactions, yet the scheduler might interleave their execution on the same CLR thread. + + Workflow execution properties provide a mechanism to add context specific properties to an activity’s environment. This allows an activity to declare which properties are in scope for its sub-tree and also provides hooks for setting up and tearing down TLS to properly interoperate with CLR objects. + +## Creating and Using Workflow Execution Properties + + Workflow execution properties usually implement the interface, though properties focused on messaging may implement and instead. To create a workflow execution property, create a class that implements the interface and implement the members and . These members provide the execution property with an opportunity to properly set up and tear down the thread local storage during each pulse of work of the activity that contains the property, including any child activities. In this example, a `ConsoleColorProperty` is created that sets the `Console.ForegroundColor`. + +```csharp +class ConsoleColorProperty : IExecutionProperty +{ + public const string Name = "ConsoleColorProperty"; + + ConsoleColor original; + ConsoleColor color; + + public ConsoleColorProperty(ConsoleColor color) + { + this.color = color; + } + + void IExecutionProperty.SetupWorkflowThread() + { + original = Console.ForegroundColor; + Console.ForegroundColor = color; + } + + void IExecutionProperty.CleanupWorkflowThread() + { + Console.ForegroundColor = original; + } +} +``` + + Activity authors can use this property by registering it in the activity’s execute override. In this example, a `ConsoleColorScope` activity is defined that registers the `ConsoleColorProperty` by adding it to the collection of the current . + +```csharp +public sealed class ConsoleColorScope : NativeActivity +{ + public ConsoleColorScope() + : base() + { + } + + public ConsoleColor Color { get; set; } + public Activity Body { get; set; } + + protected override void Execute(NativeActivityContext context) + { + context.Properties.Add(ConsoleColorProperty.Name, new ConsoleColorProperty(this.Color)); + + if (this.Body != null) + { + context.ScheduleActivity(this.Body); + } + } +} +``` + + When the activity’s body starts a pulse of work, the method of the property is called, and when the pulse of work is complete, the is called. In this example, a workflow is created that uses a activity with three branches. The first two branches use the `ConsoleColorScope` activity and the third branch does not. All three branches contain two activities and a activity. When the activity executes, the activities that are contained in the branches execute in an interleaved manner, but as each child activity executes the correct console color is applied by the `ConsoleColorProperty`. + +```csharp +Activity wf = new Parallel +{ Branches = - { - new ConsoleColorScope - { - Color = ConsoleColor.Blue, - Body = new Sequence - { + { + new ConsoleColorScope + { + Color = ConsoleColor.Blue, + Body = new Sequence + { Activities = - { - new WriteLine - { - Text = "Start blue text." - }, - new Delay - { - Duration = TimeSpan.FromSeconds(1) - }, - new WriteLine - { - Text = "End blue text." - } - } - } - }, - new ConsoleColorScope - { - Color = ConsoleColor.Red, - Body = new Sequence - { + { + new WriteLine + { + Text = "Start blue text." + }, + new Delay + { + Duration = TimeSpan.FromSeconds(1) + }, + new WriteLine + { + Text = "End blue text." + } + } + } + }, + new ConsoleColorScope + { + Color = ConsoleColor.Red, + Body = new Sequence + { Activities = - { - new WriteLine - { - Text = "Start red text." - }, - new Delay - { - Duration = TimeSpan.FromSeconds(1) - }, - new WriteLine - { - Text = "End red text." - } - } - } - }, - new Sequence - { + { + new WriteLine + { + Text = "Start red text." + }, + new Delay + { + Duration = TimeSpan.FromSeconds(1) + }, + new WriteLine + { + Text = "End red text." + } + } + } + }, + new Sequence + { Activities = - { - new WriteLine - { - Text = "Start default text." - }, - new Delay - { - Duration = TimeSpan.FromSeconds(1) - }, - new WriteLine - { - Text = "End default text." - } - } - } - } -}; - -WorkflowInvoker.Invoke(wf); -``` - - When the workflow is invoked, the following output is written to the console window. - -```console -Start blue text. -Start red text. -Start default text. -End blue text. -End red text. -End default text. -``` - + { + new WriteLine + { + Text = "Start default text." + }, + new Delay + { + Duration = TimeSpan.FromSeconds(1) + }, + new WriteLine + { + Text = "End default text." + } + } + } + } +}; + +WorkflowInvoker.Invoke(wf); +``` + + When the workflow is invoked, the following output is written to the console window. + +```console +Start blue text. +Start red text. +Start default text. +End blue text. +End red text. +End default text. +``` + > [!NOTE] -> Although it is not shown in the previous output, each line of text in the console window is displayed in the indicated color. - - Workflow execution properties can be used by custom activity authors, and they also provide the mechanism for handle management for activities such as the and activities. - +> Although it is not shown in the previous output, each line of text in the console window is displayed in the indicated color. + + Workflow execution properties can be used by custom activity authors, and they also provide the mechanism for handle management for activities such as the and activities. + ## See also - diff --git a/docs/framework/windows-workflow-foundation/workflow-transactions.md b/docs/framework/windows-workflow-foundation/workflow-transactions.md index 3922e6cf4b3b4..e0ef78da88f36 100644 --- a/docs/framework/windows-workflow-foundation/workflow-transactions.md +++ b/docs/framework/windows-workflow-foundation/workflow-transactions.md @@ -6,9 +6,9 @@ ms.assetid: 6081fb02-c0f2-483d-97b8-f3b7dc03011d --- # Workflow Transactions -WF provides support for participating in transactions by using the activity to scope a transacted unit of work. While the must be explicitly completed the activity implicitly calls complete on the transaction upon successful completion. Any activities that are contained in the of the activity participate in the transaction. WF can to flow transactions into a workflow through the use of the activity. Like the activity, any activity contained in the participates in the transaction. WF ensures that activities dependent on works with both and . If the system-provided activities do not address all requirements, custom activities can be built using the to enable advanced flow and transaction control scenarios. +WF provides support for participating in transactions by using the activity to scope a transacted unit of work. While the must be explicitly completed the activity implicitly calls complete on the transaction upon successful completion. Any activities that are contained in the of the activity participate in the transaction. WF can to flow transactions into a workflow through the use of the activity. Like the activity, any activity contained in the participates in the transaction. WF ensures that activities dependent on works with both and . If the system-provided activities do not address all requirements, custom activities can be built using the to enable advanced flow and transaction control scenarios. -In the following example, a workflow is constructed consisting of a activity that contains child activities including a activity. The activities of the execute under the transaction initialized by the activity. +In the following example, a workflow is constructed consisting of a activity that contains child activities including a activity. The activities of the execute under the transaction initialized by the activity. ```csharp static Activity ScenarioOne() @@ -48,4 +48,4 @@ For more information, see about using - -- +- diff --git a/docs/fsharp/language-reference/assertions.md b/docs/fsharp/language-reference/assertions.md index e7b78369a9fa6..84c98418812be 100644 --- a/docs/fsharp/language-reference/assertions.md +++ b/docs/fsharp/language-reference/assertions.md @@ -17,7 +17,7 @@ assert condition The `assert` expression has type `bool -> unit`. -The `assert` function resolves to . This means its behavior is identical to having called directly. +The `assert` function resolves to . This means its behavior is identical to having called directly. Assertion checking is enabled only when you compile in Debug mode; that is, if the constant `DEBUG` is defined. In the project system, by default, the `DEBUG` constant is defined in the Debug configuration but not in the Release configuration. diff --git a/docs/fsharp/language-reference/async-expressions.md b/docs/fsharp/language-reference/async-expressions.md index efddc31571a6e..08b827feefce1 100644 --- a/docs/fsharp/language-reference/async-expressions.md +++ b/docs/fsharp/language-reference/async-expressions.md @@ -36,8 +36,8 @@ let! (result2 : byte[]) = stream.AsyncRead(bufferSize) `let!` can only be used to await F# async computations [`Async`](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-control-fsharpasync.html) directly. You can await other kinds of asynchronous operations indirectly: -* .NET tasks, and the non-generic , by combining with `Async.AwaitTask` -* .NET value tasks, and the non-generic , by combining with `.AsTask()` and `Async.AwaitTask` +* .NET tasks, and the non-generic , by combining with `Async.AwaitTask` +* .NET value tasks, and the non-generic , by combining with `.AsTask()` and `Async.AwaitTask` * Any object following the "GetAwaiter" pattern specified in [F# RFC FS-1097](https://github.com/fsharp/fslang-design/blob/main/FSharp-6.0/FS-1097-task-builder.md), by combining with `task { return! expr } |> Async.AwaitTask`. ## Control Flow diff --git a/docs/fsharp/language-reference/byrefs.md b/docs/fsharp/language-reference/byrefs.md index fd1dfb27e125c..15e43b277b2af 100644 --- a/docs/fsharp/language-reference/byrefs.md +++ b/docs/fsharp/language-reference/byrefs.md @@ -8,7 +8,7 @@ ms.date: 09/27/2021 F# has two major feature areas that deal in the space of low-level programming: * The `byref`/`inref`/`outref` types, which are managed pointers. They have restrictions on usage so that you cannot compile a program that is invalid at run time. -* A `byref`-like struct, which is a [struct](structs.md) that has similar semantics and the same compile-time restrictions as `byref<'T>`. One example is . +* A `byref`-like struct, which is a [struct](structs.md) that has similar semantics and the same compile-time restrictions as `byref<'T>`. One example is . ## Syntax diff --git a/docs/fsharp/language-reference/computation-expressions.md b/docs/fsharp/language-reference/computation-expressions.md index f3224cae1fcd4..2a075faffc9c3 100644 --- a/docs/fsharp/language-reference/computation-expressions.md +++ b/docs/fsharp/language-reference/computation-expressions.md @@ -124,7 +124,7 @@ For the [async workflow](async-expressions.md), this type is `Async`. For ### `yield` -The `yield` keyword is for returning a value from the computation expression so that it can be consumed as an : +The `yield` keyword is for returning a value from the computation expression so that it can be consumed as an : ```fsharp let squares = @@ -440,7 +440,7 @@ comp |> step |> step comp |> step |> step |> step |> step ``` -A computation expression has an underlying type, which the expression returns. The underlying type may represent a computed result or a delayed computation that can be performed, or it may provide a way to iterate through some type of collection. In the previous example, the underlying type was `Eventually<_>`. For a sequence expression, the underlying type is . For a query expression, the underlying type is . For an async expression, the underlying type is [`Async`](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-control-fsharpasync-1.html). The `Async` object represents the work to be performed to compute the result. For example, you call [`Async.RunSynchronously`](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-control-fsharpasync.html#RunSynchronously) to execute a computation and return the result. +A computation expression has an underlying type, which the expression returns. The underlying type may represent a computed result or a delayed computation that can be performed, or it may provide a way to iterate through some type of collection. In the previous example, the underlying type was `Eventually<_>`. For a sequence expression, the underlying type is . For a query expression, the underlying type is . For an async expression, the underlying type is [`Async`](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-control-fsharpasync-1.html). The `Async` object represents the work to be performed to compute the result. For example, you call [`Async.RunSynchronously`](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-control-fsharpasync.html#RunSynchronously) to execute a computation and return the result. ## Custom Operations diff --git a/docs/fsharp/language-reference/functions/external-functions.md b/docs/fsharp/language-reference/functions/external-functions.md index 99f08fca914cc..03171796df739 100644 --- a/docs/fsharp/language-reference/functions/external-functions.md +++ b/docs/fsharp/language-reference/functions/external-functions.md @@ -65,7 +65,7 @@ Alternately, you might want to manage the marshalling of data types manually and extern int GetBinaryTypeW(nativeint lpApplicationName, uint* lpBinaryType); ``` -You could use to convert a .NET string to native format and receive a pointer (`nativeint`) to it that could be supplied to `lpApplicationName`. +You could use to convert a .NET string to native format and receive a pointer (`nativeint`) to it that could be supplied to `lpApplicationName`. To obtain a pointer to an integer, use the pointer of `&&` operator or the [`fixed`](../fixed.md) keyword. diff --git a/docs/fsharp/language-reference/interpolated-strings.md b/docs/fsharp/language-reference/interpolated-strings.md index 4080184b60fa8..8fe4fb967906a 100644 --- a/docs/fsharp/language-reference/interpolated-strings.md +++ b/docs/fsharp/language-reference/interpolated-strings.md @@ -108,7 +108,7 @@ let data = [0..4] let output = $"The data is %A{data}" // "The data is [0; 1; 2; 3; 4]" ``` -.NET-style specifiers are those usable with , placed after a `:` within the braces. For example: +.NET-style specifiers are those usable with , placed after a `:` within the braces. For example: ```fsharp let pi = $"{System.Math.PI:N4}" // "3.1416" diff --git a/docs/fsharp/language-reference/nullable-value-types.md b/docs/fsharp/language-reference/nullable-value-types.md index 3390b1339339d..edd0abd18f8cd 100644 --- a/docs/fsharp/language-reference/nullable-value-types.md +++ b/docs/fsharp/language-reference/nullable-value-types.md @@ -6,7 +6,7 @@ ms.date: 11/19/2020 # Nullable value types -A _nullable value type_ `Nullable<'T>` represents any [struct](structs.md) type that could also be `null`. This is helpful when interacting with libraries and components that may choose to represent these kinds of types, like integers, with a `null` value for efficiency reasons. The underlying type that backs this construct is . +A _nullable value type_ `Nullable<'T>` represents any [struct](structs.md) type that could also be `null`. This is helpful when interacting with libraries and components that may choose to represent these kinds of types, like integers, with a `null` value for efficiency reasons. The underlying type that backs this construct is . ## Syntax diff --git a/docs/fsharp/language-reference/query-expressions.md b/docs/fsharp/language-reference/query-expressions.md index 72b16c4f9b709..1c0c0fb1b15c7 100644 --- a/docs/fsharp/language-reference/query-expressions.md +++ b/docs/fsharp/language-reference/query-expressions.md @@ -20,7 +20,7 @@ Query expressions are a type of computation expression similar to sequence expre :::code language="fsharp" source="~/samples/snippets/fsharp/query-expressions/snippet1.fs"::: -In the previous code example, the query expression is in curly braces. The meaning of the code in the expression is, return every customer in the Customers table in the database in the query results. Query expressions return a type that implements and , and so they can be iterated using the [Seq module](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-collections-seqmodule.html) as the example shows. +In the previous code example, the query expression is in curly braces. The meaning of the code in the expression is, return every customer in the Customers table in the database in the query results. Query expressions return a type that implements and , and so they can be iterated using the [Seq module](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-collections-seqmodule.html) as the example shows. Every computation expression type is built from a builder class. The builder class for the query computation expression is `QueryBuilder`. For more information, see [Computation Expressions](computation-expressions.md) and [QueryBuilder Class](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-linq-querybuilder.html). diff --git a/docs/fsharp/language-reference/sequences.md b/docs/fsharp/language-reference/sequences.md index 7c09fd0c66bf4..5189ba6b2e5f3 100644 --- a/docs/fsharp/language-reference/sequences.md +++ b/docs/fsharp/language-reference/sequences.md @@ -5,7 +5,7 @@ ms.date: 10/29/2021 --- # Sequences -A *sequence* is a logical series of elements all of one type. Sequences are particularly useful when you have a large, ordered collection of data but do not necessarily expect to use all of the elements. Individual sequence elements are computed only as required, so a sequence can provide better performance than a list in situations in which not all the elements are used. Sequences are represented by the `seq<'T>` type, which is an alias for . Therefore, any .NET type that implements interface can be used as a sequence. The [Seq module](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-collections-seqmodule.html) provides support for manipulations involving sequences. +A *sequence* is a logical series of elements all of one type. Sequences are particularly useful when you have a large, ordered collection of data but do not necessarily expect to use all of the elements. Individual sequence elements are computed only as required, so a sequence can provide better performance than a list in situations in which not all the elements are used. Sequences are represented by the `seq<'T>` type, which is an alias for . Therefore, any .NET type that implements interface can be used as a sequence. The [Seq module](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-collections-seqmodule.html) provides support for manipulations involving sequences. ## Sequence Expressions @@ -127,7 +127,7 @@ The sequence seq1 contains numbers from 0 to 20. The sequence fib contains Fibonacci numbers. -0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 2584 4181 +0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 2584 4181 ``` The following code is an example that uses many of the sequence module functions described here to generate and compute the values of infinite sequences. The code might take a few minutes to run. diff --git a/docs/fsharp/language-reference/slices.md b/docs/fsharp/language-reference/slices.md index d4f46b29cc889..2423e93c40c6a 100644 --- a/docs/fsharp/language-reference/slices.md +++ b/docs/fsharp/language-reference/slices.md @@ -90,7 +90,7 @@ printfn $"{twoByTwo}" The F# core library defines slices for a limited set of types. If you wish to define slices for more data types, you can do so either in the type definition itself or in a type extension. -For example, here's how you might define slices for the class to allow for convenient data manipulation: +For example, here's how you might define slices for the class to allow for convenient data manipulation: ```fsharp open System @@ -105,7 +105,7 @@ let arr = ArraySegment [| 1 .. 10 |] let slice = arr[2..5] //[ 3; 4; 5] ``` -Another example using the and types: +Another example using the and types: ```fsharp open System diff --git a/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md b/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md index 1561f5867cf35..dcb51a4f11bc8 100644 --- a/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md +++ b/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md @@ -30,11 +30,11 @@ The unchecked behavior does not throw exceptions when overflow or underflow occu The following table summarizes the binary arithmetic operators that are available for **Checked Arithmetic** with unboxed integral types. Checked operators ensure that calculations are verified for overflow or underflow, providing safer arithmetic for critical applications. -| Binary Operator | Notes | -|------------------|----------------------------------------------------------------------------------------| -| `+` (addition, plus) | Throws an if the result exceeds the maximum value or goes below the minimum value supported by the type. Both **Overflow** and **Underflow** are possible. | -| `-` (subtraction, minus) | Throws an if the result exceeds the maximum value or goes below the minimum value supported by the type. Both **Overflow** and **Underflow** are possible. | -| `*` (multiplication, times) | Throws an if the product exceeds the maximum value or goes below the minimum value supported by the type. Both **Overflow** and **Underflow** are possible. | +| Binary Operator | Notes | +|------------------|----------------------------------------------------------------------------------------| +| `+` (addition, plus) | Throws an if the result exceeds the maximum value or goes below the minimum value supported by the type. Both **Overflow** and **Underflow** are possible. | +| `-` (subtraction, minus) | Throws an if the result exceeds the maximum value or goes below the minimum value supported by the type. Both **Overflow** and **Underflow** are possible. | +| `*` (multiplication, times) | Throws an if the product exceeds the maximum value or goes below the minimum value supported by the type. Both **Overflow** and **Underflow** are possible. | The checked operators are useful for ensuring that arithmetic overflows are caught and handled explicitly. @@ -76,9 +76,9 @@ Floating-point numbers should never be directly compared for equality, because t ## Overloaded and Generic Operators -All of the operators discussed in this topic are defined in the **Microsoft.FSharp.Core.Operators** namespace. Some of the operators are defined by using statically resolved type parameters. This means that there are individual definitions for each specific type that works with that operator. All of the unary and binary arithmetic and bitwise operators are in this category. The comparison operators are generic and therefore work with any type, not just primitive arithmetic types. Discriminated union and record types have their own custom implementations that are generated by the F# compiler. Class types use the method . +All of the operators discussed in this topic are defined in the **Microsoft.FSharp.Core.Operators** namespace. Some of the operators are defined by using statically resolved type parameters. This means that there are individual definitions for each specific type that works with that operator. All of the unary and binary arithmetic and bitwise operators are in this category. The comparison operators are generic and therefore work with any type, not just primitive arithmetic types. Discriminated union and record types have their own custom implementations that are generated by the F# compiler. Class types use the method . -The generic operators are customizable. To customize the comparison functions, override to provide your own custom equality comparison, and then implement . The interface has a single method, the method. +The generic operators are customizable. To customize the comparison functions, override to provide your own custom equality comparison, and then implement . The interface has a single method, the method. ## Operators and Type Inference diff --git a/docs/fsharp/language-reference/task-expressions.md b/docs/fsharp/language-reference/task-expressions.md index 5b3115e4ee61e..c37c8aa51c2d0 100644 --- a/docs/fsharp/language-reference/task-expressions.md +++ b/docs/fsharp/language-reference/task-expressions.md @@ -32,8 +32,8 @@ let! (result2 : int) = stream.ReadAsync(buffer, offset, count, cancellationToke F# `task { }` expressions can await the following kinds of asynchronous operations: -* .NET tasks, and the non-generic . -* .NET value tasks, and the non-generic . +* .NET tasks, and the non-generic . +* .NET value tasks, and the non-generic . * F# async computations [`Async`](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-control-fsharpasync.html). * Any object following the "GetAwaiter" pattern specified in [F# RFC FS-1097](https://github.com/fsharp/fslang-design/blob/main/FSharp-6.0/FS-1097-task-builder.md). @@ -64,7 +64,7 @@ task { use httpClient = new Net.Http.HttpClient() // use! Task use! exampleDomain = httpClient.GetAsync "https://example.com/data.enc" - + // use IDisposable use aes = Aes.Create() aes.KeySize <- 256 @@ -137,7 +137,7 @@ If you intend to correctly make your code cancelable, carefully check that you p ## Background tasks -By default, .NET tasks are scheduled using if present. This allows tasks to serve as cooperative, interleaved agents executing on a user interface thread without blocking the UI. If not present, task continuations are scheduled to the .NET thread pool. +By default, .NET tasks are scheduled using if present. This allows tasks to serve as cooperative, interleaved agents executing on a user interface thread without blocking the UI. If not present, task continuations are scheduled to the .NET thread pool. In practice, it's often desirable that library code that generates tasks ignores the synchronization context and instead always switches to the .NET thread pool, if necessary. You can achieve this using `backgroundTask { }`: @@ -210,6 +210,6 @@ Tasks are implemented using Resumable Code, a new feature in F# 6. Tasks are com - [Resumable State Machines - F# Compiler Community Session](https://www.youtube.com/watch?v=GYi3ZMF8Pm0) - [Resumable Code - RFC FS-1087](https://github.com/fsharp/fslang-design/blob/main/FSharp-6.0/FS-1087-resumable-code.md) - -- +- - -- +- diff --git a/docs/fsharp/language-reference/type-extensions.md b/docs/fsharp/language-reference/type-extensions.md index 8e1df6915ea1f..9de7edfa7d5f2 100644 --- a/docs/fsharp/language-reference/type-extensions.md +++ b/docs/fsharp/language-reference/type-extensions.md @@ -47,7 +47,7 @@ namespace Example type Variant = | Num of int | Str of string - + module Variant = let print v = match v with @@ -87,7 +87,7 @@ type IEnumerable<'T> with } ``` -You can now access `RepeatElements` as if it's a member of as long as the `Extensions` module is opened in the scope that you are working in. +You can now access `RepeatElements` as if it's a member of as long as the `Extensions` module is opened in the scope that you are working in. Optional extensions do not appear on the extended type when examined by reflection. Optional extensions must be in modules, and they're only in scope when the module that contains the extension is open or is otherwise in scope. @@ -137,7 +137,7 @@ type IEnumerableExtensions = static member inline Sum(xs: IEnumerable<'T>) = Seq.sum xs ``` -When used, this code will make it appear as if `Sum` is defined on , so long as `Extensions` has been opened or is in scope. +When used, this code will make it appear as if `Sum` is defined on , so long as `Extensions` has been opened or is in scope. For the extension to be available to VB.NET code, an extra `ExtensionAttribute` is required at the assembly level: diff --git a/docs/fsharp/tutorials/async.md b/docs/fsharp/tutorials/async.md index 6a46f8fa56ce9..c5ee29258daf4 100644 --- a/docs/fsharp/tutorials/async.md +++ b/docs/fsharp/tutorials/async.md @@ -67,7 +67,7 @@ let main argv = 0 ``` -In the example, the `printTotalFileBytesUsingAsync` function is of type `string -> Async`. Calling the function does not actually execute the asynchronous computation. Instead, it returns an `Async` that acts as a *specification* of the work that is to execute asynchronously. It calls `Async.AwaitTask` in its body, which converts the result of to an appropriate type. +In the example, the `printTotalFileBytesUsingAsync` function is of type `string -> Async`. Calling the function does not actually execute the asynchronous computation. Instead, it returns an `Async` that acts as a *specification* of the work that is to execute asynchronously. It calls `Async.AwaitTask` in its body, which converts the result of to an appropriate type. Another important line is the call to `Async.RunSynchronously`. This is one of the Async module starting functions that you'll need to call if you want to actually execute an F# asynchronous computation. @@ -178,7 +178,7 @@ What to watch out for: ### Async.StartAsTask -Executes a computation in the thread pool. Returns a that will be completed on the corresponding state once the computation terminates (produces the result, throws exception, or gets canceled). If no cancellation token is provided, then the default cancellation token is used. +Executes a computation in the thread pool. Returns a that will be completed on the corresponding state once the computation terminates (produces the result, throws exception, or gets canceled). If no cancellation token is provided, then the default cancellation token is used. Signature: @@ -188,7 +188,7 @@ computation: Async<'T> * ?taskCreationOptions: TaskCreationOptions * ?cancellati When to use: -- When you need to call into a .NET API that yields a to represent the result of an asynchronous computation. +- When you need to call into a .NET API that yields a to represent the result of an asynchronous computation. What to watch out for: @@ -235,7 +235,7 @@ What to watch out for: ### Async.AwaitTask -Returns an asynchronous computation that waits for the given to complete and returns its result as an `Async<'T>` +Returns an asynchronous computation that waits for the given to complete and returns its result as an `Async<'T>` Signature: @@ -245,7 +245,7 @@ task: Task<'T> -> Async<'T> When to use: -- When you are consuming a .NET API that returns a within an F# asynchronous computation. +- When you are consuming a .NET API that returns a within an F# asynchronous computation. What to watch out for: @@ -330,7 +330,7 @@ What to watch out for: ### Interoperate with .NET -If using `async { }` programming, you may need to interoperate with a .NET library or C# codebase that uses [async/await](../../csharp/language-reference/keywords/async.md)-style asynchronous programming. Because C# and the majority of .NET libraries use the and types as their core abstractions this may change how you write your F# asynchronous code. +If using `async { }` programming, you may need to interoperate with a .NET library or C# codebase that uses [async/await](../../csharp/language-reference/keywords/async.md)-style asynchronous programming. Because C# and the majority of .NET libraries use the and types as their core abstractions this may change how you write your F# asynchronous code. One option is to switch to writing .NET tasks directly using `task { }`. Alternatively, you can use the `Async.AwaitTask` function to await a .NET asynchronous computation: diff --git a/docs/fsharp/whats-new/fsharp-45.md b/docs/fsharp/whats-new/fsharp-45.md index e2ff653a142a3..a81226aa1d5d2 100644 --- a/docs/fsharp/whats-new/fsharp-45.md +++ b/docs/fsharp/whats-new/fsharp-45.md @@ -14,7 +14,7 @@ F# 4.5 is available in all .NET Core distributions and Visual Studio tooling. [G ## Span and byref-like structs -The type introduced in .NET Core allows you to represent buffers in memory in a strongly typed manner, which is now allowed in F# starting with F# 4.5. The following example shows how you can re-use a function operating on a with different buffer representations: +The type introduced in .NET Core allows you to represent buffers in memory in a strongly typed manner, which is now allowed in F# starting with F# 4.5. The following example shows how you can re-use a function operating on a with different buffer representations: ```fsharp let safeSum (bytes: Span) = diff --git a/docs/fundamentals/code-analysis/includes/fix-binaryformatter-serializationbinder.md b/docs/fundamentals/code-analysis/includes/fix-binaryformatter-serializationbinder.md index b080d36c47574..ac47f1359f6e2 100644 --- a/docs/fundamentals/code-analysis/includes/fix-binaryformatter-serializationbinder.md +++ b/docs/fundamentals/code-analysis/includes/fix-binaryformatter-serializationbinder.md @@ -1,3 +1,3 @@ - Use a secure serializer instead, and **don't allow an attacker to specify an arbitrary type to deserialize**. For more information see the [Preferred alternatives](../../../standard/serialization/binaryformatter-security-guide.md#preferred-alternatives). - Make the serialized data tamper-proof. After serialization, cryptographically sign the serialized data. Before deserialization, validate the cryptographic signature. Protect the cryptographic key from being disclosed and design for key rotations. -- This option makes code vulnerable to denial of service attacks and possible remote code execution attacks in the future. For more information, see the [BinaryFormatter security guide](../../../standard/serialization/binaryformatter-security-guide.md). Restrict deserialized types. Implement a custom . Before deserializing, set the `Binder` property to an instance of your custom in all code paths. In the overridden method, if the type is unexpected, throw an exception to stop deserialization. +- This option makes code vulnerable to denial of service attacks and possible remote code execution attacks in the future. For more information, see the [BinaryFormatter security guide](../../../standard/serialization/binaryformatter-security-guide.md). Restrict deserialized types. Implement a custom . Before deserializing, set the `Binder` property to an instance of your custom in all code paths. In the overridden method, if the type is unexpected, throw an exception to stop deserialization. diff --git a/docs/fundamentals/code-analysis/overview.md b/docs/fundamentals/code-analysis/overview.md index ce7317402e62d..5867a1ac35513 100644 --- a/docs/fundamentals/code-analysis/overview.md +++ b/docs/fundamentals/code-analysis/overview.md @@ -40,7 +40,7 @@ The following rules are enabled, by default, as errors or warnings in .NET 10. A | [CA1857](quality-rules/ca1857.md) | Performance | Warning | .NET 8 | A constant is expected for the parameter | | [CA2013](quality-rules/ca2013.md) | Reliability | Warning | .NET 5 | Do not use `ReferenceEquals` with value types | | [CA2014](quality-rules/ca2014.md) | Reliability | Warning | .NET 5 | Do not use `stackalloc` in loops | -| [CA2015](quality-rules/ca2015.md) | Reliability | Warning | .NET 5 | Do not define finalizers for types derived from | +| [CA2015](quality-rules/ca2015.md) | Reliability | Warning | .NET 5 | Do not define finalizers for types derived from | | [CA2017](quality-rules/ca2017.md) | Reliability | Warning | .NET 6 | Parameter count mismatch | | [CA2018](quality-rules/ca2018.md) | Reliability | Warning | .NET 6 | The `count` argument to `Buffer.BlockCopy` should specify the number of bytes to copy | | [CA2021](quality-rules/ca2021.md) | Reliability | Warning | .NET 8 | Do not call `Enumerable.Cast` or `Enumerable.OfType` with incompatible types | @@ -75,7 +75,7 @@ The following rules are enabled, by default, as errors or warnings in .NET 9. Ad | [CA1857](quality-rules/ca1857.md) | Performance | Warning | .NET 8 | A constant is expected for the parameter | | [CA2013](quality-rules/ca2013.md) | Reliability | Warning | .NET 5 | Do not use `ReferenceEquals` with value types | | [CA2014](quality-rules/ca2014.md) | Reliability | Warning | .NET 5 | Do not use `stackalloc` in loops | -| [CA2015](quality-rules/ca2015.md) | Reliability | Warning | .NET 5 | Do not define finalizers for types derived from | +| [CA2015](quality-rules/ca2015.md) | Reliability | Warning | .NET 5 | Do not define finalizers for types derived from | | [CA2017](quality-rules/ca2017.md) | Reliability | Warning | .NET 6 | Parameter count mismatch | | [CA2018](quality-rules/ca2018.md) | Reliability | Warning | .NET 6 | The `count` argument to `Buffer.BlockCopy` should specify the number of bytes to copy | | [CA2021](quality-rules/ca2021.md) | Reliability | Warning | .NET 8 | Do not call `Enumerable.Cast` or `Enumerable.OfType` with incompatible types | @@ -109,7 +109,7 @@ The following rules are enabled, by default, as errors or warnings in .NET 8. Ad | [CA1857](quality-rules/ca1857.md) | Performance | Warning | .NET 8 | A constant is expected for the parameter | | [CA2013](quality-rules/ca2013.md) | Reliability | Warning | .NET 5 | Do not use `ReferenceEquals` with value types | | [CA2014](quality-rules/ca2014.md) | Reliability | Warning | .NET 5 | Do not use `stackalloc` in loops | -| [CA2015](quality-rules/ca2015.md) | Reliability | Warning | .NET 5 | Do not define finalizers for types derived from | +| [CA2015](quality-rules/ca2015.md) | Reliability | Warning | .NET 5 | Do not define finalizers for types derived from | | [CA2017](quality-rules/ca2017.md) | Reliability | Warning | .NET 6 | Parameter count mismatch | | [CA2018](quality-rules/ca2018.md) | Reliability | Warning | .NET 6 | The `count` argument to `Buffer.BlockCopy` should specify the number of bytes to copy | | [CA2021](quality-rules/ca2021.md) | Reliability | Warning | .NET 8 | Do not call `Enumerable.Cast` or `Enumerable.OfType` with incompatible types | diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1001.md b/docs/fundamentals/code-analysis/quality-rules/ca1001.md index 22bcf7dd4621b..d76871d40505c 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1001.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1001.md @@ -38,7 +38,7 @@ This rule respects types implementing interface. In the method, call the method of the field's type. +To fix a violation of this rule, implement the interface. In the method, call the method of the field's type. ## When to suppress warnings diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1002.md b/docs/fundamentals/code-analysis/quality-rules/ca1002.md index a6bc97a3d413c..fdbfe3911dcdd 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1002.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1002.md @@ -25,27 +25,27 @@ dev_langs: ## Cause -A type contains an externally visible member that is a type, returns a type, or whose signature includes a parameter. +A type contains an externally visible member that is a type, returns a type, or whose signature includes a parameter. By default, this rule only looks at externally visible types, but this is [configurable](#configure-code-to-analyze). ## Rule description - is a generic collection that's designed for performance and not inheritance. does not contain virtual members that make it easier to change the behavior of an inherited class. The following generic collections are designed for inheritance and should be exposed instead of . + is a generic collection that's designed for performance and not inheritance. does not contain virtual members that make it easier to change the behavior of an inherited class. The following generic collections are designed for inheritance and should be exposed instead of . -- +- -- +- -- +- -- +- -- +- ## How to fix violations -To fix a violation of this rule, change the type to one of the generic collections that's designed for inheritance. +To fix a violation of this rule, change the type to one of the generic collections that's designed for inheritance. ## Example diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1003.md b/docs/fundamentals/code-analysis/quality-rules/ca1003.md index a69694a871ffb..d897e0c042560 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1003.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1003.md @@ -32,13 +32,13 @@ By default, this rule only looks at externally visible types, but this is [confi ## Rule description -Before .NET Framework 2.0, in order to pass custom information to the event handler, a new delegate had to be declared that specified a class that was derived from the class. In .NET Framework 2.0 and later versions, the generic delegate allows any class that's derived from to be used together with the event handler. +Before .NET Framework 2.0, in order to pass custom information to the event handler, a new delegate had to be declared that specified a class that was derived from the class. In .NET Framework 2.0 and later versions, the generic delegate allows any class that's derived from to be used together with the event handler. ## How to fix violations -To fix a violation of this rule, remove the delegate and replace its use by using the delegate. +To fix a violation of this rule, remove the delegate and replace its use by using the delegate. -If the delegate is autogenerated by the Visual Basic compiler, change the syntax of the event declaration to use the delegate. +If the delegate is autogenerated by the Visual Basic compiler, change the syntax of the event declaration to use the delegate. ## When to suppress warnings @@ -62,7 +62,7 @@ The following example shows a delegate that violates the rule. In the Visual Bas :::code language="csharp" source="snippets/csharp/all-rules/ca1003.cs" id="snippet1"::: -The following code snippet removes the delegate declaration from the previous example, which satisfies the rule. It replaces its use in the `ClassThatRaisesEvent` and `ClassThatHandlesEvent` methods by using the delegate. +The following code snippet removes the delegate declaration from the previous example, which satisfies the rule. It replaces its use in the `ClassThatRaisesEvent` and `ClassThatHandlesEvent` methods by using the delegate. :::code language="csharp" source="snippets/csharp/all-rules/ca1003.cs" id="snippet2"::: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1010.md b/docs/fundamentals/code-analysis/quality-rules/ca1010.md index 37db75defa653..98c2ebc9c1315 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1010.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1010.md @@ -25,7 +25,7 @@ ms.author: gewarren ## Cause -A type implements the interface but does not implement the interface, and the containing assembly targets .NET. This rule ignores types that implement . +A type implements the interface but does not implement the interface, and the containing assembly targets .NET. This rule ignores types that implement . By default, this rule only looks at externally visible types, but this is [configurable](#configure-code-to-analyze). You can also configure additional interfaces to require that a generic interface be implemented. @@ -33,17 +33,17 @@ By default, this rule only looks at externally visible types, but this is [confi To broaden the usability of a collection, implement one of the generic collection interfaces. Then the collection can be used to populate generic collection types such as the following: -- -- -- +- +- +- ## How to fix violations To fix a violation of this rule, implement one of the following generic collection interfaces: -- -- -- +- +- +- ## When to suppress warnings @@ -92,8 +92,8 @@ Examples: | Option value | Summary | | --- | --- | -|``dotnet_code_quality.CA1010.additional_required_generic_interfaces = ISomething->System.Collections.Generic.IEnumerable`1`` | All types that implement `ISomething` regardless of its namespace are expected to also implement . | -|``dotnet_code_quality.CA1010.additional_required_generic_interfaces = T:System.Collections.IDictionary->T:System.Collections.Generic.IDictionary`2`` | All types that implement are expected to also implement . | +|``dotnet_code_quality.CA1010.additional_required_generic_interfaces = ISomething->System.Collections.Generic.IEnumerable`1`` | All types that implement `ISomething` regardless of its namespace are expected to also implement . | +|``dotnet_code_quality.CA1010.additional_required_generic_interfaces = T:System.Collections.IDictionary->T:System.Collections.Generic.IDictionary`2`` | All types that implement are expected to also implement . | ## Example @@ -108,7 +108,7 @@ To fix a violation of this rule, do one of the following: ### Fix by interface implementation -The following example fixes the violation by implementing these generic interfaces: , , and . +The following example fixes the violation by implementing these generic interfaces: , , and . :::code language="csharp" source="snippets/csharp/all-rules/ca1010.cs" id="snippet3"::: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1021.md b/docs/fundamentals/code-analysis/quality-rules/ca1021.md index 67568ab7532df..c7d14609c4aed 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1021.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1021.md @@ -117,7 +117,7 @@ Passing by return value: ## Try pattern methods -Methods that implement the **Try\** pattern, such as , do not raise this violation. The following example shows a structure (value type) that implements the method. +Methods that implement the **Try\** pattern, such as , do not raise this violation. The following example shows a structure (value type) that implements the method. :::code language="csharp" source="snippets/csharp/all-rules/ca1021.cs" id="snippet5"::: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1033.md b/docs/fundamentals/code-analysis/quality-rules/ca1033.md index e35e5c764d794..ff130a652a19a 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1033.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1033.md @@ -29,7 +29,7 @@ An unsealed externally visible type provides an explicit method implementation o Consider a base type that explicitly implements a public interface method. A type that derives from the base type can access the inherited interface method only through a reference to the current instance (`this` in C#) that is cast to the interface. If the derived type reimplements (explicitly) the inherited interface method, the base implementation can no longer be accessed. The call through the current instance reference will invoke the derived implementation; this causes recursion and an eventual stack overflow. -This rule does not report a violation for an explicit implementation of when an externally visible `Close()` or `System.IDisposable.Dispose(Boolean)` method is provided. +This rule does not report a violation for an explicit implementation of when an externally visible `Close()` or `System.IDisposable.Dispose(Boolean)` method is provided. ## How to fix violations diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1036.md b/docs/fundamentals/code-analysis/quality-rules/ca1036.md index b52ec1a109352..d3cd4407c09b8 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1036.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1036.md @@ -26,17 +26,17 @@ dev_langs: ## Cause -A type implements the interface and does not override or does not overload the language-specific operator for equality, inequality, less-than, or greater-than. The rule does not report a violation if the type inherits only an implementation of the interface. +A type implements the interface and does not override or does not overload the language-specific operator for equality, inequality, less-than, or greater-than. The rule does not report a violation if the type inherits only an implementation of the interface. By default, this rule only looks at externally visible types, but this is [configurable](#configure-code-to-analyze). ## Rule description -Types that define a custom sort order implement the interface. The method returns an integer value that indicates the correct sort order for two instances of the type. This rule identifies types that set a sort order. Setting a sort order implies that the ordinary meaning of equality, inequality, less-than, and greater-than don't apply. When you provide an implementation of , you must usually also override so that it returns values that are consistent with . If you override and are coding in a language that supports operator overloads, you should also provide operators that are consistent with . +Types that define a custom sort order implement the interface. The method returns an integer value that indicates the correct sort order for two instances of the type. This rule identifies types that set a sort order. Setting a sort order implies that the ordinary meaning of equality, inequality, less-than, and greater-than don't apply. When you provide an implementation of , you must usually also override so that it returns values that are consistent with . If you override and are coding in a language that supports operator overloads, you should also provide operators that are consistent with . ## How to fix violations -To fix a violation of this rule, override . If your programming language supports operator overloading, supply the following operators: +To fix a violation of this rule, override . If your programming language supports operator overloading, supply the following operators: - `op_Equality` - `op_Inequality` @@ -73,7 +73,7 @@ End Operator ## When to suppress warnings -It's safe to suppress a warning from rule CA1036 when the violation is caused by missing operators and your programming language does not support operator overloading. If you determine that implementing the operators does not make sense in your app context, it's also safe to suppress a warning from this rule when it fires on equality operators other than `op_Equality`. However, you should always override `op_Equality` and the `==` operator if you override . +It's safe to suppress a warning from rule CA1036 when the violation is caused by missing operators and your programming language does not support operator overloading. If you determine that implementing the operators does not make sense in your app context, it's also safe to suppress a warning from this rule when it fires on equality operators other than `op_Equality`. However, you should always override `op_Equality` and the `==` operator if you override . ## Suppress a warning @@ -106,7 +106,7 @@ You can configure this option for just this rule, for all rules it applies to, o ## Examples -The following code contains a type that correctly implements . Code comments identify the methods that satisfy various rules that are related to and the interface. +The following code contains a type that correctly implements . Code comments identify the methods that satisfy various rules that are related to and the interface. :::code language="csharp" source="snippets/csharp/all-rules/ca1036.cs" id="snippet1"::: :::code language="vb" source="snippets/vb/all-rules/ca1036.vb" id="snippet1"::: @@ -119,5 +119,5 @@ The following application code tests the behavior of the -- +- - [Equality operators](../../../standard/design-guidelines/equality-operators.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1041.md b/docs/fundamentals/code-analysis/quality-rules/ca1041.md index d2aab33bcfa8b..0aaab1d1497e5 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1041.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1041.md @@ -26,13 +26,13 @@ dev_langs: ## Cause -A type or member is marked by using a attribute that does not have its property specified. +A type or member is marked by using a attribute that does not have its property specified. By default, this rule only looks at externally visible types and members, but this is [configurable](#configure-code-to-analyze). ## Rule description - is used to mark deprecated library types and members. Library consumers should avoid the use of any type or member that is marked obsolete. This is because it might not be supported and will eventually be removed from later versions of the library. When a type or member marked by using is compiled, the property of the attribute is displayed. This gives the user information about the obsolete type or member. This information generally includes how long the obsolete type or member will be supported by the library designers and the preferred replacement to use. + is used to mark deprecated library types and members. Library consumers should avoid the use of any type or member that is marked obsolete. This is because it might not be supported and will eventually be removed from later versions of the library. When a type or member marked by using is compiled, the property of the attribute is displayed. This gives the user information about the obsolete type or member. This information generally includes how long the obsolete type or member will be supported by the library designers and the preferred replacement to use. ## How to fix violations @@ -40,7 +40,7 @@ To fix a violation of this rule, add the `message` parameter to the property provides critical information about the obsolete type or member. +Do not suppress a warning from this rule because the property provides critical information about the obsolete type or member. ## Configure code to analyze diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1046.md b/docs/fundamentals/code-analysis/quality-rules/ca1046.md index 39b83a8af11a5..b497359bb0e15 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1046.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1046.md @@ -89,5 +89,5 @@ c and a are == ? Yes ## See also -- +- - [Equality Operators](../../../standard/design-guidelines/equality-operators.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1047.md b/docs/fundamentals/code-analysis/quality-rules/ca1047.md index 193ac0cd55ab8..f16bfd6785f8d 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1047.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1047.md @@ -26,7 +26,7 @@ dev_langs: ## Cause -A public type is `sealed` (`NotInheritable` in Visual basic) and declares a protected member or a protected nested type. This rule does not report violations for methods, which must follow this pattern. +A public type is `sealed` (`NotInheritable` in Visual basic) and declares a protected member or a protected nested type. This rule does not report violations for methods, which must follow this pattern. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1063.md b/docs/fundamentals/code-analysis/quality-rules/ca1063.md index e6bc8ee1a4e1f..543bf596326cf 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1063.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1063.md @@ -61,7 +61,7 @@ Examine your code and determine which of the following resolutions will fix this - Make sure that Dispose(bool) is declared as protected, virtual, and unsealed. -- Modify Dispose() so that it calls Dispose(true), then calls on the current object instance (`this`, or `Me` in Visual Basic), and then returns. +- Modify Dispose() so that it calls Dispose(true), then calls on the current object instance (`this`, or `Me` in Visual Basic), and then returns. - Modify your finalizer so that it calls Dispose(false) and then returns. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1065.md b/docs/fundamentals/code-analysis/quality-rules/ca1065.md index 0326481ea57a6..e747e37487e88 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1065.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1065.md @@ -67,8 +67,8 @@ The following exceptions can be thrown from an event accessor: The following **Equals** methods should not throw exceptions: -- -- +- +- An `Equals` method should return `true` or `false` instead of throwing an exception. For example, if `Equals` is passed two mismatched types, it should just return `false` instead of throwing an . @@ -76,8 +76,8 @@ An `Equals` method should return `true` or `false` instead of throwing an except The following `GetHashCode` methods should usually not throw exceptions: -- -- +- +- `GetHashCode` should always return a value. Otherwise, you can lose items in the hash table. @@ -85,7 +85,7 @@ The versions of `GetHashCode` that take an argument can throw an to help display information about objects in string format. Therefore, `ToString` should not change the state of an object, and it shouldn't throw exceptions. +The debugger uses to help display information about objects in string format. Therefore, `ToString` should not change the state of an object, and it shouldn't throw exceptions. ### Static constructors @@ -97,7 +97,7 @@ Throwing an exception from a finalizer causes the CLR to fail fast, which tears ### Dispose methods -A method should not throw an exception. `Dispose` is often called as part of the cleanup logic in a `finally` clause. Therefore, explicitly throwing an exception from `Dispose` forces the user to add exception handling inside the `finally` clause. +A method should not throw an exception. `Dispose` is often called as part of the cleanup logic in a `finally` clause. Therefore, explicitly throwing an exception from `Dispose` forces the user to add exception handling inside the `finally` clause. The `Dispose(false)` code path should never throw exceptions, because `Dispose` is almost always called from a finalizer. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1066.md b/docs/fundamentals/code-analysis/quality-rules/ca1066.md index d49a162a6d5a5..40eb44d5440c3 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1066.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1066.md @@ -21,17 +21,17 @@ ms.author: mavasani ## Cause -A value type (struct) overrides method, but does not implement . +A value type (struct) overrides method, but does not implement . ## Rule description -A value type overriding method indicates that it supports comparing two instances of the type for value equality. Consider implementing the interface to support strongly typed tests for equality. This ensures that callers performing equality checks invoke the strongly typed method and avoid boxing the argument, improving performance. For more information, see [Notes to implementers](/dotnet/api/system.iequatable-1#notes-to-implementers). +A value type overriding method indicates that it supports comparing two instances of the type for value equality. Consider implementing the interface to support strongly typed tests for equality. This ensures that callers performing equality checks invoke the strongly typed method and avoid boxing the argument, improving performance. For more information, see [Notes to implementers](/dotnet/api/system.iequatable-1#notes-to-implementers). -Your implementation should return results that are consistent with . +Your implementation should return results that are consistent with . ## How to fix violations -To fix a violation, implement and update override to invoke this implemented method. For example, the following two code snippets show a violation of the rule and how to fix it: +To fix a violation, implement and update override to invoke this implemented method. For example, the following two code snippets show a violation of the rule and how to fix it: ```csharp public struct S diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1067.md b/docs/fundamentals/code-analysis/quality-rules/ca1067.md index 0f99a1ee3c08d..560c104fe7770 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1067.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1067.md @@ -21,17 +21,17 @@ ms.author: mavasani ## Cause -A type implements , but does not override method. +A type implements , but does not override method. ## Rule description -A type implementing interface indicates that it supports comparing two instances of the type for equality. You should also override the base class implementations of and methods so that their behavior is consistent with that of the implementation. For more information, see [Notes to implementers](/dotnet/api/system.iequatable-1#notes-to-implementers). +A type implementing interface indicates that it supports comparing two instances of the type for equality. You should also override the base class implementations of and methods so that their behavior is consistent with that of the implementation. For more information, see [Notes to implementers](/dotnet/api/system.iequatable-1#notes-to-implementers). -Your implementation should return results that are consistent with implementation. +Your implementation should return results that are consistent with implementation. ## How to fix violations -To fix a violation, override and implement it by invoking the implementation. For example, the following two code snippets show a violation of the rule and how to fix it: +To fix a violation, override and implement it by invoking the implementation. For example, the following two code snippets show a violation of the rule and how to fix it: ```csharp using System; diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1303.md b/docs/fundamentals/code-analysis/quality-rules/ca1303.md index 585b3a9c75e80..bd2100f562402 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1303.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1303.md @@ -33,7 +33,7 @@ This warning is raised when a literal string is passed as a value to a parameter - The attribute of the parameter or property is set to `true`. -- The literal string is passed to the `string value` or `string format` parameter of a or method overload. +- The literal string is passed to the `string value` or `string format` parameter of a or method overload. - Rule CA1303 is [configured to use the naming heuristic](#use-naming-heuristic), and a parameter or property name contains the phrase `Text`, `Message`, or `Caption`. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1304.md b/docs/fundamentals/code-analysis/quality-rules/ca1304.md index bae1debd968b8..03af9cd4658b9 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1304.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1304.md @@ -25,9 +25,9 @@ ms.author: gewarren A method or constructor calls a member that has an overload that accepts a parameter, and the method or constructor does not call the overload that takes the parameter. This rule ignores calls to the following methods: -- -- -- +- +- +- You can also [configure](#configure-code-to-analyze) more symbols to be excluded by this rule. @@ -88,7 +88,7 @@ You can configure these options for just this rule, for all rules they apply to, ## Example showing how to fix violations -In the following example, `BadMethod` causes two violations of this rule. `GoodMethod` corrects the first violation by passing the invariant culture to , and corrects the second violation by passing the current culture to because `string3` is displayed to the user. +In the following example, `BadMethod` causes two violations of this rule. `GoodMethod` corrects the first violation by passing the invariant culture to , and corrects the second violation by passing the current culture to because `string3` is displayed to the user. :::code language="csharp" source="snippets/csharp/all-rules/ca1304.cs" id="snippet1"::: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1305.md b/docs/fundamentals/code-analysis/quality-rules/ca1305.md index 8bb10f9253c7b..afcd5b66baed8 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1305.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1305.md @@ -29,12 +29,12 @@ A call is made to a method that has an overload that accepts a parameter. The rule also ignores the following methods: -- -- -- -- -- -- +- +- +- +- +- +- ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1309.md b/docs/fundamentals/code-analysis/quality-rules/ca1309.md index 950aedf94d68c..d2a0830ce5c35 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1309.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1309.md @@ -27,7 +27,7 @@ A string comparison operation that is nonlinguistic does not set the and methods, now provide an overload that accepts a enumeration value as a parameter. +Many string operations, most importantly the and methods, now provide an overload that accepts a enumeration value as a parameter. When you specify either **StringComparison.Ordinal** or **StringComparison.OrdinalIgnoreCase**, the string comparison is non-linguistic. That is, the features that are specific to the natural language are ignored when comparison decisions are made. Ignoring natural language features means the decisions are based on simple byte comparisons and not on casing or equivalence tables that are parameterized by culture. As a result, by explicitly setting the parameter to either the **StringComparison.Ordinal** or **StringComparison.OrdinalIgnoreCase**, your code often gains speed, increases correctness, and becomes more reliable. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1416.md b/docs/fundamentals/code-analysis/quality-rules/ca1416.md index 0cc07f62d8cde..4ebb01ad5a658 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1416.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1416.md @@ -113,7 +113,7 @@ The analyzer does not check target framework moniker (TFM) target platforms from ## How to fix violations -The recommended way to deal with violations is to make sure you only call platform-specific APIs when running on an appropriate platform. You can achieve this by excluding the code at build time using `#if` and multi-targeting, or by conditionally calling the code at runtime. The analyzer recognizes the platform guards in the class and . +The recommended way to deal with violations is to make sure you only call platform-specific APIs when running on an appropriate platform. You can achieve this by excluding the code at build time using `#if` and multi-targeting, or by conditionally calling the code at runtime. The analyzer recognizes the platform guards in the class and . - Suppress violations by surrounding the call site with the standard platform guard methods or custom guard APIs annotated with or . @@ -203,7 +203,7 @@ The recommended way to deal with violations is to make sure you only call platfo } ``` -- The analyzer also respects as a means for preventing the code from being reached on unsupported platforms. Using `Debug.Assert` allows the check to be trimmed out of release builds, if desired. +- The analyzer also respects as a means for preventing the code from being reached on unsupported platforms. Using `Debug.Assert` allows the check to be trimmed out of release builds, if desired. ```csharp // An API supported only on Linux. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1510.md b/docs/fundamentals/code-analysis/quality-rules/ca1510.md index 126defcc61d68..e5804b91ab99a 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1510.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1510.md @@ -23,7 +23,7 @@ Code checks whether an argument is `null` and then conditionally throws an are simpler and more efficient than `if` blocks that construct a new exception instance. +Argument checks have a substantial impact on code size and often dominate the code for small functions and property setters. These checks prevent inlining and cause substantial instruction-cache pollution. Throw-helper methods such as are simpler and more efficient than `if` blocks that construct a new exception instance. ## Example @@ -48,7 +48,7 @@ void M(string arg) ## How to fix violations -Replace the `if` block that throws the exception with a call to . Or, in Visual Studio, use the lightbulb menu to fix your code automatically. +Replace the `if` block that throws the exception with a call to . Or, in Visual Studio, use the lightbulb menu to fix your code automatically. ## When to suppress warnings diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1512.md b/docs/fundamentals/code-analysis/quality-rules/ca1512.md index 16334716bdbac..230fa5100244f 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1512.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1512.md @@ -23,7 +23,7 @@ Code checks whether an argument is less than or greater than a given value and t ## Rule description -Argument checks have a substantial impact on code size and often dominate the code for small functions and property setters. These checks prevent inlining and cause substantial instruction-cache pollution. Throw-helper methods such as are simpler and more efficient than `if` blocks that construct a new exception instance. +Argument checks have a substantial impact on code size and often dominate the code for small functions and property setters. These checks prevent inlining and cause substantial instruction-cache pollution. Throw-helper methods such as are simpler and more efficient than `if` blocks that construct a new exception instance. ## Example @@ -74,15 +74,15 @@ void M(int arg) Replace the `if` block that throws the exception with a call to one of the following throw-helper methods: -- -- -- -- -- -- -- -- -- +- +- +- +- +- +- +- +- +- Or, in Visual Studio, use the lightbulb menu to fix your code automatically. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1513.md b/docs/fundamentals/code-analysis/quality-rules/ca1513.md index 70069fb706c23..dd38de07b181c 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1513.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1513.md @@ -23,7 +23,7 @@ Code checks if an object is disposed and then conditionally throws an are simpler and more efficient than `if` blocks that construct a new exception instance. +Object checks have a substantial impact on code size and often dominate the code for small functions and property setters. These checks prevent inlining and cause substantial instruction-cache pollution. Throw-helper methods such as are simpler and more efficient than `if` blocks that construct a new exception instance. ## Example @@ -56,7 +56,7 @@ class C ## How to fix violations -Replace the `if` block that throws the exception with a call to . Or, in Visual Studio, use the lightbulb menu to fix your code automatically. +Replace the `if` block that throws the exception with a call to . Or, in Visual Studio, use the lightbulb menu to fix your code automatically. ## When to suppress warnings diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1514.md b/docs/fundamentals/code-analysis/quality-rules/ca1514.md index 2419a6cd323a7..4a0219527ce1c 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1514.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1514.md @@ -26,7 +26,7 @@ dev_langs: ## Cause -A redundant length argument is passed to , , , or when slicing to the end of a string or buffer. +A redundant length argument is passed to , , , or when slicing to the end of a string or buffer. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1700.md b/docs/fundamentals/code-analysis/quality-rules/ca1700.md index 741cd745f9469..d2a4910ef9003 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1700.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1700.md @@ -33,7 +33,7 @@ This rule assumes that an enumeration member that has a name that contains "rese Instead of using a reserved member, add a new member to the enumeration in the future version. In most cases the addition of the new member is not a breaking change, as long as the addition does not cause the values of the original members to change. -In a limited number of cases the addition of a member is a breaking change even when the original members retain their original values. Primarily, the new member cannot be returned from existing code paths without breaking callers that use a `switch` (`Select` in Visual Basic) statement on the return value that encompasses the whole member list and that throw an exception in the default case. A secondary concern is that client code might not handle the change in behavior from reflection methods such as . Accordingly, if the new member has to be returned from existing methods or a known application incompatibility occurs because of poor reflection usage, the only nonbreaking solution is to: +In a limited number of cases the addition of a member is a breaking change even when the original members retain their original values. Primarily, the new member cannot be returned from existing code paths without breaking callers that use a `switch` (`Select` in Visual Basic) statement on the return value that encompasses the whole member list and that throw an exception in the default case. A secondary concern is that client code might not handle the change in behavior from reflection methods such as . Accordingly, if the new member has to be returned from existing methods or a known application incompatibility occurs because of poor reflection usage, the only nonbreaking solution is to: 1. Add a new enumeration that contains the original and new members. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1710.md b/docs/fundamentals/code-analysis/quality-rules/ca1710.md index 176c113aececf..79d4f87cc3967 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1710.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1710.md @@ -43,11 +43,11 @@ The following table lists the base types and interfaces that have associated suf | | `Collection` | | | `Dictionary` | | | `Collection` | -| | `Dictionary` | +| | `Dictionary` | | | `Collection` or `Queue` | | | `Collection` or `Stack` | -| | `Collection` | -| | `Dictionary` | +| | `Collection` | +| | `Dictionary` | | | `DataSet` | | | `Collection` or `DataTable` | | | `Stream` | @@ -59,7 +59,7 @@ Types that implement and are a generalized Types that implement and are a collection of specific items have names that end with the word `Collection`. For example, a collection of objects would have the name `QueueCollection`. The `Collection` suffix signifies that the members of the collection can be enumerated by using the `foreach` (`For Each` in Visual Basic) statement. -Types that implement or have names that end with the word `Dictionary` even if the type also implements or . The `Collection` and `Dictionary` suffix naming conventions enable users to distinguish between the following two enumeration patterns. +Types that implement or have names that end with the word `Dictionary` even if the type also implements or . The `Collection` and `Dictionary` suffix naming conventions enable users to distinguish between the following two enumeration patterns. Types with the `Collection` suffix follow this enumeration pattern. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1711.md b/docs/fundamentals/code-analysis/quality-rules/ca1711.md index 2daaa8a3ff1cf..9727ae718cd49 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1711.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1711.md @@ -38,8 +38,8 @@ The following table lists the reserved suffixes and the base types and interface | Suffix | Base type/Interface | |----------------|-------------------------------------------------------------| | `Attribute` | | -| `Collection` |











| -| `Dictionary` |

| +| `Collection` |











| +| `Dictionary` |

| | `EventArgs` | | | `EventHandler` | An event-handler delegate | | `Exception` | | diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1801.md b/docs/fundamentals/code-analysis/quality-rules/ca1801.md index f8dfce500fa43..11931b0540164 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1801.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1801.md @@ -34,7 +34,7 @@ This rule does not examine the following kinds of methods: - Serialization constructors (see [guidelines](/previous-versions/dotnet/fundamentals/serialization/serialization-guidelines#runtime-serialization)). -- Serialization methods. +- Serialization methods. - Methods declared with the `abstract` (`MustOverride` in Visual Basic) modifier. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1806.md b/docs/fundamentals/code-analysis/quality-rules/ca1806.md index f14da0302e6f7..cba12cb0895c7 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1806.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1806.md @@ -38,7 +38,7 @@ There are several possible reasons for this warning: Unnecessary object creation and the associated garbage collection of the unused object degrade performance. -Strings are immutable and methods such as return a new instance of a string instead of modifying the instance of the string in the calling method. +Strings are immutable and methods such as return a new instance of a string instead of modifying the instance of the string in the calling method. Ignoring `HRESULT` or an error code can lead to low-resource conditions or unexpected behavior in error conditions. @@ -108,12 +108,12 @@ dotnet_code_quality.CA1806.additional_use_results_methods = M:MyNamespace.MyType ## Example 1 -The following example shows a class that ignores the result of calling . +The following example shows a class that ignores the result of calling . :::code language="csharp" source="snippets/csharp/all-rules/ca1806.cs" id="snippet1"::: :::code language="vb" source="snippets/vb/all-rules/ca1806-do-not-ignore-method-results_1.vb" id="snippet1"::: -The following example fixes the violation by assigning the result of back to the variable it was called on. +The following example fixes the violation by assigning the result of back to the variable it was called on. :::code language="csharp" source="snippets/csharp/all-rules/ca1806.cs" id="snippet2"::: :::code language="vb" source="snippets/vb/all-rules/ca1806-do-not-ignore-method-results_1.vb" id="snippet2"::: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1812.md b/docs/fundamentals/code-analysis/quality-rules/ca1812.md index 71809158b87ac..09e06cd7b9cb4 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1812.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1812.md @@ -48,7 +48,7 @@ To fix a violation of this rule, remove the type or add code that uses it. If th It is safe to suppress a warning from this rule. We recommend that you suppress this warning in the following situations: -- The class is created through late-bound reflection methods such as . +- The class is created through late-bound reflection methods such as . - The class is registered in an inversion of control (IoC) container as part of the [dependency injection](../../../core/extensions/dependency-injection/overview.md) pattern. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1813.md b/docs/fundamentals/code-analysis/quality-rules/ca1813.md index c631fc401fae5..b55e6e5f17f63 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1813.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1813.md @@ -30,7 +30,7 @@ A public type inherits from , is ## Rule description -.NET provides methods for retrieving custom attributes. By default, these methods search the attribute inheritance hierarchy. For example, searches for the specified attribute type or any attribute type that extends the specified attribute type. Sealing the attribute eliminates the search through the inheritance hierarchy, and can improve performance. +.NET provides methods for retrieving custom attributes. By default, these methods search the attribute inheritance hierarchy. For example, searches for the specified attribute type or any attribute type that extends the specified attribute type. Sealing the attribute eliminates the search through the inheritance hierarchy, and can improve performance. ## How to fix violations diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1815.md b/docs/fundamentals/code-analysis/quality-rules/ca1815.md index 14313d64f5577..49136c4dbd3b0 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1815.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1815.md @@ -23,17 +23,17 @@ ms.author: gewarren ## Cause -A value type does not override or does not implement the equality operator (==). This rule does not check enumerations. +A value type does not override or does not implement the equality operator (==). This rule does not check enumerations. By default, this rule only looks at externally visible types, but this is [configurable](#configure-code-to-analyze). ## Rule description -For [non-blittable](../../../framework/interop/blittable-and-non-blittable-types.md) value types, the inherited implementation of uses the library to compare the contents of all fields. Reflection is computationally expensive, and comparing every field for equality might be unnecessary. If you expect users to compare or sort instances, or use them as hash table keys, your value type should implement . If your programming language supports operator overloading, you should also provide an implementation of the equality and inequality operators. +For [non-blittable](../../../framework/interop/blittable-and-non-blittable-types.md) value types, the inherited implementation of uses the library to compare the contents of all fields. Reflection is computationally expensive, and comparing every field for equality might be unnecessary. If you expect users to compare or sort instances, or use them as hash table keys, your value type should implement . If your programming language supports operator overloading, you should also provide an implementation of the equality and inequality operators. ## How to fix violations -To fix a violation of this rule, provide an implementation of . If you can, implement the equality operator. +To fix a violation of this rule, provide an implementation of . If you can, implement the equality operator. ## When to suppress warnings @@ -74,7 +74,7 @@ The following code shows a structure (value type) that violates this rule: :::code language="csharp" source="snippets/csharp/all-rules/ca1815.cs" id="snippet1"::: -The following code fixes the previous violation by overriding and implementing the equality operators (`==` and `!=`): +The following code fixes the previous violation by overriding and implementing the equality operators (`==` and `!=`): :::code language="csharp" source="snippets/csharp/all-rules/ca1815.cs" id="snippet2"::: @@ -85,4 +85,4 @@ The following code fixes the previous violation by overriding +- diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1816.md b/docs/fundamentals/code-analysis/quality-rules/ca1816.md index 491a29bb253b4..cefe568cc5b55 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1816.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1816.md @@ -28,33 +28,33 @@ dev_langs: Violations of this rule can be caused by: -- In an unsealed class, a method that's an implementation of and doesn't call . +- In an unsealed class, a method that's an implementation of and doesn't call . -- A method that's not an implementation of and calls . +- A method that's not an implementation of and calls . -- A method that calls and passes something other than [this (C#)](../../../csharp/language-reference/keywords/this.md) or [Me (Visual Basic)](../../../visual-basic/programming-guide/program-structure/me-my-mybase-and-myclass.md#me). +- A method that calls and passes something other than [this (C#)](../../../csharp/language-reference/keywords/this.md) or [Me (Visual Basic)](../../../visual-basic/programming-guide/program-structure/me-my-mybase-and-myclass.md#me). ## Rule description -The method lets users release resources at any time before the object becomes available for garbage collection. If the method is called, it frees resources of the object. This makes finalization unnecessary. should call so the garbage collector doesn't call the finalizer of the object. +The method lets users release resources at any time before the object becomes available for garbage collection. If the method is called, it frees resources of the object. This makes finalization unnecessary. should call so the garbage collector doesn't call the finalizer of the object. -To prevent derived types with finalizers from having to reimplement and to call it, unsealed types without finalizers should still call . +To prevent derived types with finalizers from having to reimplement and to call it, unsealed types without finalizers should still call . ## How to fix violations To fix a violation of this rule: -- If the method is an implementation of , add a call to . +- If the method is an implementation of , add a call to . -- If the method is not an implementation of , either remove the call to or move it to the type's implementation. +- If the method is not an implementation of , either remove the call to or move it to the type's implementation. -- Change all calls to to pass [this (C#)](../../../csharp/language-reference/keywords/this.md) or [Me (Visual Basic)](../../../visual-basic/programming-guide/program-structure/me-my-mybase-and-myclass.md#me). +- Change all calls to to pass [this (C#)](../../../csharp/language-reference/keywords/this.md) or [Me (Visual Basic)](../../../visual-basic/programming-guide/program-structure/me-my-mybase-and-myclass.md#me). - If the type is not meant to be overridden, mark it as `sealed`. ## When to suppress warnings -Only suppress a warning from this rule if you're deliberately using to control the lifetime of other objects. Don't suppress a warning from this rule if an implementation of doesn't call . In this situation, failing to suppress finalization degrades performance and provides no benefits. +Only suppress a warning from this rule if you're deliberately using to control the lifetime of other objects. Don't suppress a warning from this rule if an implementation of doesn't call . In this situation, failing to suppress finalization degrades performance and provides no benefits. ## Suppress a warning @@ -77,7 +77,7 @@ For more information, see [How to suppress code analysis warnings](../suppress-w ## Example that violates CA1816 -This code shows a method that calls , but doesn't pass [this (C#)](../../../csharp/language-reference/keywords/this.md) or [Me (Visual Basic)](../../../visual-basic/programming-guide/program-structure/me-my-mybase-and-myclass.md#me). As a result, this code violates rule CA1816. +This code shows a method that calls , but doesn't pass [this (C#)](../../../csharp/language-reference/keywords/this.md) or [Me (Visual Basic)](../../../visual-basic/programming-guide/program-structure/me-my-mybase-and-myclass.md#me). As a result, this code violates rule CA1816. :::code language="vb" source="snippets/vb/all-rules/ca1816-call-gc-suppressfinalize-correctly_1.vb" id="snippet1"::: @@ -85,7 +85,7 @@ This code shows a method that calls by passing [this (C#)](../../../csharp/language-reference/keywords/this.md) or [Me (Visual Basic)](../../../visual-basic/programming-guide/program-structure/me-my-mybase-and-myclass.md#me). +This example shows a method that correctly calls by passing [this (C#)](../../../csharp/language-reference/keywords/this.md) or [Me (Visual Basic)](../../../visual-basic/programming-guide/program-structure/me-my-mybase-and-myclass.md#me). :::code language="vb" source="snippets/vb/all-rules/ca1816-call-gc-suppressfinalize-correctly_1.vb" id="snippet2"::: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1819.md b/docs/fundamentals/code-analysis/quality-rules/ca1819.md index 3bb5e0c0c91d4..ca29fdc96d5d2 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1819.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1819.md @@ -95,7 +95,7 @@ The following example fixes the violation by changing the property to a method: ### Change the property to return a collection -The following example fixes the violation by changing the property to return a : +The following example fixes the violation by changing the property to return a : :::code language="csharp" source="snippets/csharp/all-rules/ca1819.cs" id="snippet3"::: @@ -109,7 +109,7 @@ You might want to allow the consumer of the class to modify a property. The foll :::code language="vb" source="snippets/vb/all-rules/ca1819-properties-should-not-return-arrays_1.vb" id="snippet4"::: -The following example fixes the violation by changing the property to return a : +The following example fixes the violation by changing the property to return a : :::code language="vb" source="snippets/vb/all-rules/ca1819-properties-should-not-return-arrays_1.vb" id="snippet5"::: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1820.md b/docs/fundamentals/code-analysis/quality-rules/ca1820.md index 4ae0a9a52023b..673e450048edb 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1820.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1820.md @@ -23,17 +23,17 @@ ms.author: gewarren ## Cause -A string is compared to the empty string by using . +A string is compared to the empty string by using . ## Rule description -Comparing strings using the property or the method is faster than using . This is because executes significantly more CIL instructions than either or the number of instructions executed to retrieve the property value and compare it to zero. +Comparing strings using the property or the method is faster than using . This is because executes significantly more CIL instructions than either or the number of instructions executed to retrieve the property value and compare it to zero. -For null strings, and `.Length == 0` behave differently. If you try to get the value of the property on a null string, the common language runtime throws a . If you perform a comparison between a null string and the empty string, the common language runtime does not throw an exception and returns `false`. Testing for null does not significantly affect the relative performance of these two approaches. When targeting .NET Framework 2.0 or later, use the method. Otherwise, use the == 0 comparison whenever possible. +For null strings, and `.Length == 0` behave differently. If you try to get the value of the property on a null string, the common language runtime throws a . If you perform a comparison between a null string and the empty string, the common language runtime does not throw an exception and returns `false`. Testing for null does not significantly affect the relative performance of these two approaches. When targeting .NET Framework 2.0 or later, use the method. Otherwise, use the == 0 comparison whenever possible. ## How to fix violations -To fix a violation of this rule, change the comparison to use the method. +To fix a violation of this rule, change the comparison to use the method. ## When to suppress warnings diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1825.md b/docs/fundamentals/code-analysis/quality-rules/ca1825.md index 3596a541522e6..18994cd655e72 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1825.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1825.md @@ -29,11 +29,11 @@ An empty with no elements is allocated. ## Rule description -Initializing a zero-length array leads to an unnecessary memory allocation. Instead, use the statically allocated empty array instance by calling the method. The memory allocation is shared across all invocations of this method. +Initializing a zero-length array leads to an unnecessary memory allocation. Instead, use the statically allocated empty array instance by calling the method. The memory allocation is shared across all invocations of this method. ## How to fix violations -To fix a violation, replace the zero-length array allocation with a call to . For example, the following two code snippets show a violation of the rule and how to fix it: +To fix a violation, replace the zero-length array allocation with a call to . For example, the following two code snippets show a violation of the rule and how to fix it: ```csharp class C diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1826.md b/docs/fundamentals/code-analysis/quality-rules/ca1826.md index 7119a6b79650d..82fe6033aff55 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1826.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1826.md @@ -29,15 +29,15 @@ The LINQ method was used on a type that supports a This rule flags the LINQ method calls on collections of types that have equivalent but more efficient properties to fetch the same data. -This rule analyzes collection types that implement but not . +This rule analyzes collection types that implement but not . This rule flags calls to the following methods on these collection types: -- -- -- -- -- +- +- +- +- +- The analyzed collection types and methods may be extended in the future to cover more cases. @@ -112,7 +112,7 @@ Use the following option to configure which parts of your codebase to run this r ### Exclude FirstOrDefault and LastOrDefault methods -You can configure this rule to exclude the and methods from analysis. You might consider excluding these methods if readability is a concern, since the code you'd write to replace them is not easily readable. To exclude these methods, add the following key-value pair to an *.editorconfig* file in your project: +You can configure this rule to exclude the and methods from analysis. You might consider excluding these methods if readability is a concern, since the code you'd write to replace them is not easily readable. To exclude these methods, add the following key-value pair to an *.editorconfig* file in your project: ```ini dotnet_code_quality.CA1826.exclude_ordefault_methods = true diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1827.md b/docs/fundamentals/code-analysis/quality-rules/ca1827.md index 49b53b3199707..13dfecad774a8 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1827.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1827.md @@ -34,7 +34,7 @@ This rule flags [Count()](xref:System.Linq.Enumerable.Count%2A) and [LongCount() ## How to fix violations -To fix a violation, replace the or method call with the method. For example, the following two code snippets show a violation of the rule and how to fix it: +To fix a violation, replace the or method call with the method. For example, the following two code snippets show a violation of the rule and how to fix it: ```csharp using System.Collections.Generic; diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1828.md b/docs/fundamentals/code-analysis/quality-rules/ca1828.md index bd183e97af4ca..56faeb0bf3155 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1828.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1828.md @@ -23,15 +23,15 @@ ms.author: mavasani ## Cause -The or method was used where the method would be more efficient. +The or method was used where the method would be more efficient. ## Rule description -This rule flags the and LINQ method calls used to check if the collection has at least one element. These method calls require enumerating the entire collection to compute the count. The same check is faster with the method as it avoids enumerating the collection. +This rule flags the and LINQ method calls used to check if the collection has at least one element. These method calls require enumerating the entire collection to compute the count. The same check is faster with the method as it avoids enumerating the collection. ## How to fix violations -To fix a violation, replace the or method call with the method. For example, the following two code snippets show a violation of the rule and how to fix it: +To fix a violation, replace the or method call with the method. For example, the following two code snippets show a violation of the rule and how to fix it: ```csharp using System.Linq; diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1829.md b/docs/fundamentals/code-analysis/quality-rules/ca1829.md index 9b466d4cf130e..54300e416eae4 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1829.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1829.md @@ -23,28 +23,28 @@ ms.author: mavasani ## Cause -The LINQ method was used on a type that supports an equivalent, more efficient `Length` or `Count` property. +The LINQ method was used on a type that supports an equivalent, more efficient `Length` or `Count` property. ## Rule description -This rule flags the LINQ method calls on collections of types that have equivalent, but more efficient `Length` or `Count` property to fetch the same data. `Length` or `Count` property does not enumerate the collection, hence is more efficient. +This rule flags the LINQ method calls on collections of types that have equivalent, but more efficient `Length` or `Count` property to fetch the same data. `Length` or `Count` property does not enumerate the collection, hence is more efficient. -This rule flags calls on the following collection types with `Length` property: +This rule flags calls on the following collection types with `Length` property: - -- +- -This rule flags calls on the following collection types with the `Count` property: +This rule flags calls on the following collection types with the `Count` property: - -- -- +- +- The analyzed collection types may be extended in the future to cover more cases. ## How to fix violations -To fix a violation, replace the method call with use of the `Length` or `Count` property access. For example, the following two code snippets show a violation of the rule and how to fix it: +To fix a violation, replace the method call with use of the `Length` or `Count` property access. For example, the following two code snippets show a violation of the rule and how to fix it: ```csharp using System.Collections.Generic; diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1830.md b/docs/fundamentals/code-analysis/quality-rules/ca1830.md index a38ab3cfa3329..ac00ffdb80e1b 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1830.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1830.md @@ -27,7 +27,7 @@ An `Append` or `Insert` method was called with ## Rule description - and provide overloads for multiple types beyond . When possible, prefer the strongly-typed overloads over using ToString() and the string-based overload. + and provide overloads for multiple types beyond . When possible, prefer the strongly-typed overloads over using ToString() and the string-based overload. ## How to fix violations diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1831.md b/docs/fundamentals/code-analysis/quality-rules/ca1831.md index 9bf0dc55b20e9..6e79d0ec6c127 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1831.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1831.md @@ -26,7 +26,7 @@ A range-indexer is used on a string and the value is implicitly assigned to `Rea ## Rule description -This rule fires when you use a range-indexer on a string and assign it to a span type. The range indexer on a is a non-copying operation, but for the range indexer on a string, the method will be used instead of . This produces a copy of the requested portion of the string. This copy is usually unnecessary when it's implicitly used as a or value. If a copy isn't intended, use the method to avoid the unnecessary copy. If the copy is intended, either assign it to a local variable first or add an explicit cast. The analyzer only reports when an implicit cast is used on the result of the range indexer operation. +This rule fires when you use a range-indexer on a string and assign it to a span type. The range indexer on a is a non-copying operation, but for the range indexer on a string, the method will be used instead of . This produces a copy of the requested portion of the string. This copy is usually unnecessary when it's implicitly used as a or value. If a copy isn't intended, use the method to avoid the unnecessary copy. If the copy is intended, either assign it to a local variable first or add an explicit cast. The analyzer only reports when an implicit cast is used on the result of the range indexer operation. ### Detects @@ -42,7 +42,7 @@ Explicit conversion: ## How to fix violations -To fix a violation of this rule, use instead of the -based indexer on the string to avoid creating unnecessary data copies. +To fix a violation of this rule, use instead of the -based indexer on the string to avoid creating unnecessary data copies. ```csharp public void TestMethod(string str) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1832.md b/docs/fundamentals/code-analysis/quality-rules/ca1832.md index b349629c9e15e..7b0ae93e60b2e 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1832.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1832.md @@ -22,11 +22,11 @@ author: buyaa-n ## Cause -When using a range-indexer on an array and implicitly assigning the value to or . +When using a range-indexer on an array and implicitly assigning the value to or . ## Rule description -The range indexer on a is a non-copying operation. But for the range indexer on an array, the method will be used instead of , which produces a copy of the requested portion of the array. This copy is usually unnecessary when it's implicitly used as a or value. If a copy isn't intended, use the or method to avoid the unnecessary copy. If the copy is intended, either assign it to a local variable first or add an explicit cast. +The range indexer on a is a non-copying operation. But for the range indexer on an array, the method will be used instead of , which produces a copy of the requested portion of the array. This copy is usually unnecessary when it's implicitly used as a or value. If a copy isn't intended, use the or method to avoid the unnecessary copy. If the copy is intended, either assign it to a local variable first or add an explicit cast. The analyzer only reports when an implicit cast is used on the result of the range indexer operation. @@ -46,7 +46,7 @@ Explicit conversions: ## How to fix violations -To fix a violation of this rule, use the or extension method to avoid creating unnecessary data copies. +To fix a violation of this rule, use the or extension method to avoid creating unnecessary data copies. ```csharp class C diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1833.md b/docs/fundamentals/code-analysis/quality-rules/ca1833.md index 5b415258b52a2..84797eb75a9b3 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1833.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1833.md @@ -22,11 +22,11 @@ author: buyaa-n ## Cause -When using a range-indexer on an array and implicitly assigning the value to or . +When using a range-indexer on an array and implicitly assigning the value to or . ## Rule description -The range indexer on a is a non-copying operation. But for the range indexer on an array, the method will be used instead of , which produces a copy of the requested portion of the array. This copy is usually unnecessary when it's implicitly used as a or value. If a copy isn't intended, use the or method to avoid the unnecessary copy. If the copy is intended, either assign it to a local variable first or add an explicit cast. The analyzer only reports when an implicit cast is used on the result of the range indexer operation. +The range indexer on a is a non-copying operation. But for the range indexer on an array, the method will be used instead of , which produces a copy of the requested portion of the array. This copy is usually unnecessary when it's implicitly used as a or value. If a copy isn't intended, use the or method to avoid the unnecessary copy. If the copy is intended, either assign it to a local variable first or add an explicit cast. The analyzer only reports when an implicit cast is used on the result of the range indexer operation. ### Detects @@ -44,7 +44,7 @@ Explicit conversions: ## How to fix violations -To fix a violation of this rule, use the or extension method to avoid creating unnecessary data copies. +To fix a violation of this rule, use the or extension method to avoid creating unnecessary data copies. ```csharp class C diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1834.md b/docs/fundamentals/code-analysis/quality-rules/ca1834.md index 503cb317c2873..369be7650f4d9 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1834.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1834.md @@ -22,7 +22,7 @@ author: pgovind ## Cause -This rule fires when a unit length string is passed to the method. +This rule fires when a unit length string is passed to the method. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1836.md b/docs/fundamentals/code-analysis/quality-rules/ca1836.md index e7ba6bf926ab5..e17acef93c46d 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1836.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1836.md @@ -23,17 +23,17 @@ ms.author: dacantu ## Cause -The `Count` or `Length` property or the extension method was used to determine whether or not the object contains any items by comparing the value to `0` or `1`, and the object has a more efficient `IsEmpty` property that could be used instead. +The `Count` or `Length` property or the extension method was used to determine whether or not the object contains any items by comparing the value to `0` or `1`, and the object has a more efficient `IsEmpty` property that could be used instead. ## Rule description -This rule flags the calls to the `Count` and `Length` properties or and LINQ methods when they are used to determine if the object contains any items and the object has a more efficient `IsEmpty` property. +This rule flags the calls to the `Count` and `Length` properties or and LINQ methods when they are used to determine if the object contains any items and the object has a more efficient `IsEmpty` property. The analysis of this rule originally overlapped with similar rules CA1827, CA1828, and CA1829; the analyzers of such rules were merged along with the one for CA1836 to report the best diagnosis in case of overlap. ## How to fix violations -To fix a violation, replace the or method call or the `Length` or `Count` property access when it's used in an operation that determines if the object is empty with use of the `IsEmpty` property access. For example, the following two code snippets show a violation of the rule and how to fix it: +To fix a violation, replace the or method call or the `Length` or `Count` property access when it's used in an operation that determines if the object is empty with use of the `IsEmpty` property access. For example, the following two code snippets show a violation of the rule and how to fix it: ```csharp using System.Collections.Concurrent; diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1838.md b/docs/fundamentals/code-analysis/quality-rules/ca1838.md index f7aa0814ce755..c74df24ed7996 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1838.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1838.md @@ -96,7 +96,7 @@ public void Bar() } ``` -When the P/Invoke is frequently called for larger buffers, can be used to avoid the repeated allocations and memory pressure that comes with them: +When the P/Invoke is frequently called for larger buffers, can be used to avoid the repeated allocations and memory pressure that comes with them: ```csharp [DllImport("MyLibrary", CharSet = CharSet.Unicode)] @@ -169,7 +169,7 @@ For more information, see [How to suppress code analysis warnings](../suppress-w - [Default marshalling for strings](../../../framework/interop/default-marshalling-for-strings.md) - [Native interoperability best practices](../../../standard/native-interop/best-practices.md) -- +- - [stackalloc](../../../csharp/language-reference/operators/stackalloc.md) - [Charsets](../../../standard/native-interop/charset.md) - [Performance rules](performance-warnings.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1841.md b/docs/fundamentals/code-analysis/quality-rules/ca1841.md index 7ff16b044d690..ba1e4d5971fbc 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1841.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1841.md @@ -25,14 +25,14 @@ dev_langs: ## Cause -This rule locates calls to a `Contains` method on the `Keys` or `Values` collection of an that could be replaced with a call to a `ContainsKey` or `ContainsValue` method on the dictionary itself. +This rule locates calls to a `Contains` method on the `Keys` or `Values` collection of an that could be replaced with a call to a `ContainsKey` or `ContainsValue` method on the dictionary itself. ## Rule description Calling `Contains` on the `Keys` or `Values` collection can often be more expensive than calling `ContainsKey` or `ContainsValue` on the dictionary itself: - Many dictionary implementations lazily instantiate the key and value collections, which means that accessing the `Keys` or `Values` collection may result in extra allocations. -- You may end up calling an extension method on if the keys or values collection uses explicit interface implementation to hide methods on . This can lead to reduced performance, especially when accessing the key collection. Most dictionary implementations are able to provide a fast O(1) containment check for keys, while the `Contains` extension method on usually does a slow O(n) containment check. +- You may end up calling an extension method on if the keys or values collection uses explicit interface implementation to hide methods on . This can lead to reduced performance, especially when accessing the key collection. Most dictionary implementations are able to provide a fast O(1) containment check for keys, while the `Contains` extension method on usually does a slow O(n) containment check. ## How to fix violations diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1842.md b/docs/fundamentals/code-analysis/quality-rules/ca1842.md index e481bd5ab5ee2..127f328940449 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1842.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1842.md @@ -22,7 +22,7 @@ author: Youssef1313 ## Cause - is called with a single task. + is called with a single task. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1843.md b/docs/fundamentals/code-analysis/quality-rules/ca1843.md index 6066779beba44..849b59b2fb65c 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1843.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1843.md @@ -22,7 +22,7 @@ author: Youssef1313 ## Cause - is called with a single task. + is called with a single task. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1844.md b/docs/fundamentals/code-analysis/quality-rules/ca1844.md index 87a1939d0e95a..9b3e9e38365d9 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1844.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1844.md @@ -33,7 +33,7 @@ The memory-based `ReadAsync` and `WriteAsync` methods were added to improve perf - They return `ValueTask` and `ValueTask` instead of `Task` and `Task`, respectively. - They allow any type of buffer to be passed in without having to perform an extra copy to an array. -In order to realize these performance benefits, types that derive from must provide their own memory-based implementation. Otherwise, the default implementation will be forced to copy the memory into an array in order to call the array-based implementation, resulting in reduced performance. When the caller passes in a or instance that's not backed by an array, performance is affected more. +In order to realize these performance benefits, types that derive from must provide their own memory-based implementation. Otherwise, the default implementation will be forced to copy the memory into an array in order to call the array-based implementation, resulting in reduced performance. When the caller passes in a or instance that's not backed by an array, performance is affected more. ## How to fix violations diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1845.md b/docs/fundamentals/code-analysis/quality-rules/ca1845.md index 29f6872c1dedf..1dddf2244f977 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1845.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1845.md @@ -24,7 +24,7 @@ dev_langs: ## Cause -This rule locates string-concatenation expressions that contain calls and suggests replacing with and using the span-based overload of . +This rule locates string-concatenation expressions that contain calls and suggests replacing with and using the span-based overload of . ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1846.md b/docs/fundamentals/code-analysis/quality-rules/ca1846.md index 98f3183d9f773..d42affe346676 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1846.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1846.md @@ -25,17 +25,17 @@ dev_langs: ## Cause -The result of a call to one of the overloads is passed to a method with an available overload that accepts `ReadOnlySpan`. +The result of a call to one of the overloads is passed to a method with an available overload that accepts `ReadOnlySpan`. ## Rule description -`Substring` allocates a new `string` object on the heap and performs a full copy of the extracted text. String manipulation is a performance bottleneck for many programs. Allocating many small, short-lived strings on a hot path can create enough collection pressure to impact performance. The O(n) copies created by `Substring` become relevant when the substrings get large. The and types were created to solve these performance problems. +`Substring` allocates a new `string` object on the heap and performs a full copy of the extracted text. String manipulation is a performance bottleneck for many programs. Allocating many small, short-lived strings on a hot path can create enough collection pressure to impact performance. The O(n) copies created by `Substring` become relevant when the substrings get large. The and types were created to solve these performance problems. Many APIs that accept strings also have overloads that accept a `ReadOnlySpan` argument. When such overloads are available, you can improve performance by calling `AsSpan` instead of `Substring`. ## How to fix violations -To fix a violation of this rule, replace the call to `string.Substring` with a call to one of the extension methods. +To fix a violation of this rule, replace the call to `string.Substring` with a call to one of the extension methods. ```csharp using System; diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1848.md b/docs/fundamentals/code-analysis/quality-rules/ca1848.md index 8da42e23d6e0b..e9ac0b2ec59aa 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1848.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1848.md @@ -22,7 +22,7 @@ author: Youssef1313 ## Cause -Use of [logger extension methods](xref:Microsoft.Extensions.Logging.LoggerExtensions), such as and . +Use of [logger extension methods](xref:Microsoft.Extensions.Logging.LoggerExtensions), such as and . ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1851.md b/docs/fundamentals/code-analysis/quality-rules/ca1851.md index d279a64911b71..49661e3c952fe 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1851.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1851.md @@ -28,7 +28,7 @@ Detected multiple enumerations of an `IEnumerable` collection. ## Rule description -A collection of type [IEnumerable](xref:System.Collections.IEnumerable) or [IEnumerable\](xref:System.Collections.Generic.IEnumerable%601) has the ability to defer enumeration when it's generated. Many LINQ methods, such as [Select](xref:System.Linq.Enumerable.Select%2A), use [deferred execution](../../../standard/linq/deferred-execution-lazy-evaluation.md). Enumeration starts when the collection is passed into a LINQ enumeration method, like [ElementAt](xref:System.Linq.Enumerable.ElementAt%2A), or used in a [for each statement](../../../csharp/language-reference/statements/iteration-statements.md#the-foreach-statement). The enumeration result is not calculated once and cached, like [Lazy](xref:System.Lazy%601). +A collection of type [IEnumerable](xref:System.Collections.IEnumerable) or [IEnumerable\](xref:System.Collections.Generic.IEnumerable`1) has the ability to defer enumeration when it's generated. Many LINQ methods, such as [Select](xref:System.Linq.Enumerable.Select%2A), use [deferred execution](../../../standard/linq/deferred-execution-lazy-evaluation.md). Enumeration starts when the collection is passed into a LINQ enumeration method, like [ElementAt](xref:System.Linq.Enumerable.ElementAt%2A), or used in a [for each statement](../../../csharp/language-reference/statements/iteration-statements.md#the-foreach-statement). The enumeration result is not calculated once and cached, like [Lazy](xref:System.Lazy`1). If the enumeration operation itself is expensive, for example, a query into a database, multiple enumerations would hurt the performance of the program. @@ -78,7 +78,7 @@ Public Sub MyMethod(input As IEnumerable(Of Integer)) End Sub ``` -If the underlying type of the `IEnumerable` collection uses an iterator-based implementation (for example, if it's generated by LINQ methods like or by using the [yield](../../../csharp/language-reference/statements/yield.md) keyword), you can fix the violation by materializing the collection. However, this allocates extra memory. +If the underlying type of the `IEnumerable` collection uses an iterator-based implementation (for example, if it's generated by LINQ methods like or by using the [yield](../../../csharp/language-reference/statements/yield.md) keyword), you can fix the violation by materializing the collection. However, this allocates extra memory. For example: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1853.md b/docs/fundamentals/code-analysis/quality-rules/ca1853.md index d4e07ad3bc2f8..b972d1ded1d45 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1853.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1853.md @@ -25,15 +25,15 @@ dev_langs: ## Cause -A call to is guarded with a call to . +A call to is guarded with a call to . ## Rule description -There's no need to guard `Dictionary.Remove(key)` with `Dictionary.ContainsKey(key)`. already checks whether the key exists and doesn't throw if it doesn't exist. +There's no need to guard `Dictionary.Remove(key)` with `Dictionary.ContainsKey(key)`. already checks whether the key exists and doesn't throw if it doesn't exist. ## How to fix violations -Remove the guarding code that calls . +Remove the guarding code that calls . ## Example diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1855.md b/docs/fundamentals/code-analysis/quality-rules/ca1855.md index e5247042d8ec9..7ef4f9908e0cc 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1855.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1855.md @@ -23,15 +23,15 @@ dev_langs: ## Cause - is called to fill the elements of a span with a default value. + is called to fill the elements of a span with a default value. ## Rule description -It's more efficient to call than to call to fill the elements of the span with a default value. +It's more efficient to call than to call to fill the elements of the span with a default value. ## How to fix violations -Replace the call to with a call to . +Replace the call to with a call to . ## Example diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1858.md b/docs/fundamentals/code-analysis/quality-rules/ca1858.md index 6eef9d9bf0f2b..6a20349a14b1f 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1858.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1858.md @@ -24,17 +24,17 @@ dev_langs: ## Cause - is called and its result is compared against zero. + is called and its result is compared against zero. ## Rule description -It's more efficient and clearer to call than to call and compare the result with zero to determine whether a string starts with a given prefix. +It's more efficient and clearer to call than to call and compare the result with zero to determine whether a string starts with a given prefix. `IndexOf` searches the entire string, while `StartsWith` only compares at the beginning of the string. ## How to fix violations -Replace the call to with a call to . +Replace the call to with a call to . ## Example diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1860.md b/docs/fundamentals/code-analysis/quality-rules/ca1860.md index 1906a51397d81..4bd1a1d04c9bf 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1860.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1860.md @@ -24,11 +24,11 @@ dev_langs: ## Cause - is called on a type that has a `Length`, `Count`, or `IsEmpty` *property*. + is called on a type that has a `Length`, `Count`, or `IsEmpty` *property*. ## Rule description -To determine whether a collection type has any elements, it's more efficient and clearer to use the `Length`, `Count`, or `IsEmpty` (if possible) properties than to call the method. +To determine whether a collection type has any elements, it's more efficient and clearer to use the `Length`, `Count`, or `IsEmpty` (if possible) properties than to call the method. `Any()`, which is an extension method, uses language integrated query (LINQ). It's more efficient to rely on the collection's own properties, and it also clarifies intent. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1862.md b/docs/fundamentals/code-analysis/quality-rules/ca1862.md index cf870390482c5..01fdd66cdbeb5 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1862.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1862.md @@ -37,14 +37,14 @@ Remove the call to , - - -- -- +- +- - - - - - -- +- - > [!NOTE] diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1864.md b/docs/fundamentals/code-analysis/quality-rules/ca1864.md index 0863d139cef63..8ca2f92c2bb7c 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1864.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1864.md @@ -24,15 +24,15 @@ dev_langs: ## Cause - is guarded by a call. + is guarded by a call. ## Rule description -Both and perform a lookup, which is redundant. also throws an exception if the key is already present in the dictionary. It's more efficient to call , which returns a Boolean value that indicates if the value was added or not. `TryAdd` doesn't overwrite the key's value if the key is already present. +Both and perform a lookup, which is redundant. also throws an exception if the key is already present in the dictionary. It's more efficient to call , which returns a Boolean value that indicates if the value was added or not. `TryAdd` doesn't overwrite the key's value if the key is already present. ## How to fix violations -Replace a call to that's followed by a call to with a single call to . +Replace a call to that's followed by a call to with a single call to . ## Example @@ -73,7 +73,7 @@ End Sub ## When to suppress warnings -It's safe to suppress this warning if performance isn't a concern and if you handle the exception that might be thrown by . +It's safe to suppress this warning if performance isn't a concern and if you handle the exception that might be thrown by . ## Suppress a warning diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1868.md b/docs/fundamentals/code-analysis/quality-rules/ca1868.md index 9745360e6f0ab..81cb4d82cac2c 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1868.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1868.md @@ -25,17 +25,17 @@ dev_langs: ## Cause -An or call is guarded by a call to . Or, an or call is guarded by a call to . +An or call is guarded by a call to . Or, an or call is guarded by a call to . ## Rule description -Both and perform a lookup, which makes it redundant to call beforehand. It's more efficient to call or directly, which returns a Boolean value indicating whether the item was added or removed. +Both and perform a lookup, which makes it redundant to call beforehand. It's more efficient to call or directly, which returns a Boolean value indicating whether the item was added or removed. -This logic also applies to and , except that they either return a new set if the item is added or removed, or the original set if it wasn't. +This logic also applies to and , except that they either return a new set if the item is added or removed, or the original set if it wasn't. ## How to fix violations -Replace the call to (or ) that's followed by a call to or (or or ) with a single call to the latter method. +Replace the call to (or ) that's followed by a call to or (or or ) with a single call to the latter method. ## Example diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1869.md b/docs/fundamentals/code-analysis/quality-rules/ca1869.md index f18522c8d2abd..23d63e3021f84 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1869.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1869.md @@ -23,7 +23,7 @@ ms.author: dacantu ## Cause -A local instance of is used once as the `options` argument of a or call. +A local instance of is used once as the `options` argument of a or call. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1870.md b/docs/fundamentals/code-analysis/quality-rules/ca1870.md index 4cd47c3db6344..f2032e6a1e00a 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1870.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1870.md @@ -31,11 +31,11 @@ The rule doesn't flag calls that use up to five values, as those already use an ## Rule description -Using a cached instance is more efficient than passing values to `IndexOfAny` or `ContainsAny` directly. +Using a cached instance is more efficient than passing values to `IndexOfAny` or `ContainsAny` directly. ## How to fix violations -Create and cache a instance in a `static readonly` field, then pass that instance to the `IndexOfAny` or `ContainsAny` call instead. +Create and cache a instance in a `static readonly` field, then pass that instance to the `IndexOfAny` or `ContainsAny` call instead. A *code fix* that automatically performs this transformation is available. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1872.md b/docs/fundamentals/code-analysis/quality-rules/ca1872.md index 5d3b6ca2bf000..1d8e42c9146ae 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1872.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1872.md @@ -26,16 +26,16 @@ dev_langs: ## Cause -A call to followed by a call to to remove dashes is used to encode bytes to a hexadecimal string representation. -This rule also fires if is used in the call chain. +A call to followed by a call to to remove dashes is used to encode bytes to a hexadecimal string representation. +This rule also fires if is used in the call chain. ## Rule description -Use or when encoding bytes to a hexadecimal string representation. These methods are more efficient and allocation-friendly than using in combination with to remove dashes and . +Use or when encoding bytes to a hexadecimal string representation. These methods are more efficient and allocation-friendly than using in combination with to remove dashes and . ## How to fix violations -To fix a violation of this rule, replace the call chain with either or . +To fix a violation of this rule, replace the call chain with either or . ## Example @@ -119,7 +119,7 @@ End Class ## When to suppress warnings -It is safe to suppress a warning from this rule; however, we recommend that you use either or . +It is safe to suppress a warning from this rule; however, we recommend that you use either or . ## Suppress a warning diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1873.md b/docs/fundamentals/code-analysis/quality-rules/ca1873.md index 9979975fe6c62..d61585ae1f9c7 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1873.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1873.md @@ -30,13 +30,13 @@ In many situations, logging is disabled or set to a log level that results in an ## Rule description -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 *source-generated logging* with the attribute. +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 *source-generated logging* with the attribute. ## How to fix violations To fix a violation of this rule, use one of the following approaches: -- Guard the logging call with a check to . +- Guard the logging call with a check to . - Use source-generated logging with the attribute. - Ensure expensive operations aren't performed in logging arguments unless necessary. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1874.md b/docs/fundamentals/code-analysis/quality-rules/ca1874.md index 263a0c1c01ffc..25fa93ccd0712 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1874.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1874.md @@ -26,7 +26,7 @@ ai-usage: ai-generated ## Cause -The property of the result from is used to check if a pattern matches. +The property of the result from is used to check if a pattern matches. ## Rule description @@ -118,5 +118,5 @@ For more information, see [How to suppress code analysis warnings](../suppress-w ## See also - [Performance rules](performance-warnings.md) -- -- +- +- diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1875.md b/docs/fundamentals/code-analysis/quality-rules/ca1875.md index 6d3aa8f30b30e..bded7cce78dd8 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1875.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1875.md @@ -118,5 +118,5 @@ For more information, see [How to suppress code analysis warnings](../suppress-w ## See also - [Performance rules](performance-warnings.md) -- -- +- +- diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1877.md b/docs/fundamentals/code-analysis/quality-rules/ca1877.md index c0e3fb7961a73..8ec9aa0c3f20e 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1877.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1877.md @@ -26,7 +26,7 @@ ai-usage: ai-generated ## Cause -Multiple consecutive or operations are used to build a path. +Multiple consecutive or operations are used to build a path. ## Rule description @@ -76,5 +76,5 @@ For more information, see [How to suppress code analysis warnings](../suppress-w ## See also - [Performance rules](performance-warnings.md) -- -- +- +- diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2000.md b/docs/fundamentals/code-analysis/quality-rules/ca2000.md index bb8e1b3d15745..6433dd05ff1d9 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2000.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2000.md @@ -49,7 +49,7 @@ Passing an object of one of these types to a constructor and then assigning it t ## How to fix violations -To fix a violation of this rule, call on the object before all references to it are out of scope. +To fix a violation of this rule, call on the object before all references to it are out of scope. You can use the [`using` statement](../../../csharp/language-reference/statements/using.md) ([`Using`](../../../visual-basic/language-reference/statements/using-statement.md) in Visual Basic) to wrap objects that implement . Objects that are wrapped in this manner are automatically disposed at the end of the `using` block. However, the following situations should not or cannot be handled with a `using` statement: @@ -70,7 +70,7 @@ You can use the [`using` statement](../../../csharp/language-reference/statement Do not suppress a warning from this rule unless: -- You've called a method on your object that calls `Dispose`, such as . +- You've called a method on your object that calls `Dispose`, such as . - The method that raised the warning returns an object that wraps your object. - The allocating method does not have dispose ownership; that is, the responsibility to dispose the object is transferred to another object or wrapper that's created in the method and returned to the caller. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2007.md b/docs/fundamentals/code-analysis/quality-rules/ca2007.md index 27013958a29e2..429ee62e6cc79 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2007.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2007.md @@ -32,9 +32,9 @@ When an asynchronous method awaits a directly ## How to fix violations -To fix violations, call on the awaited . You can pass either `true` or `false` for the `continueOnCapturedContext` parameter. +To fix violations, call on the awaited . You can pass either `true` or `false` for the `continueOnCapturedContext` parameter. -- Calling `ConfigureAwait(true)` on the task has the same behavior as not explicitly calling . By explicitly calling this method, you're letting readers know you intentionally want to perform the continuation on the original synchronization context. +- Calling `ConfigureAwait(true)` on the task has the same behavior as not explicitly calling . By explicitly calling this method, you're letting readers know you intentionally want to perform the continuation on the original synchronization context. - Call `ConfigureAwait(false)` on the task to schedule continuations to the thread pool, thereby avoiding a deadlock on the UI thread. Passing `false` is a good option for app-independent libraries. @@ -50,7 +50,7 @@ public async Task Execute() } ``` -To fix the violation, call on the awaited : +To fix the violation, call on the awaited : ```csharp public async Task Execute() diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2008.md b/docs/fundamentals/code-analysis/quality-rules/ca2008.md index b07105f4c08d8..1d8dbe470edfb 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2008.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2008.md @@ -30,10 +30,10 @@ A task creation or continuation operation uses a method overload that does not s The following .NET task creation and continuation methods have overloads that allow specifying or omitting a instance: -- methods -- methods +- methods +- methods -Always specify an explicit argument to avoid the default value, whose behavior is defined by the caller and may vary at runtime. returns the scheduler associated with whatever is currently running on that thread. If there is no such task, it returns , which represents the thread pool. Using could lead to deadlocks or UI responsiveness issues in some situations, when it was intended to create the task on the thread pool, but instead it waits to get back onto the UI thread. +Always specify an explicit argument to avoid the default value, whose behavior is defined by the caller and may vary at runtime. returns the scheduler associated with whatever is currently running on that thread. If there is no such task, it returns , which represents the thread pool. Using could lead to deadlocks or UI responsiveness issues in some situations, when it was intended to create the task on the thread pool, but instead it waits to get back onto the UI thread. For further information and detailed examples, see [New TaskCreationOptions and TaskContinuationOptions in .NET Framework 4.5](https://devblogs.microsoft.com/pfxteam/new-taskcreationoptions-and-taskcontinuationoptions-in-net-4-5/). @@ -42,7 +42,7 @@ For further information and detailed examples, see [New TaskCreationOptions and ## How to fix violations -To fix violations, call the method overload that takes a and explicitly pass in or to make the intent clear. +To fix violations, call the method overload that takes a and explicitly pass in or to make the intent clear. ## Example diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2009.md b/docs/fundamentals/code-analysis/quality-rules/ca2009.md index 971c2175bc11a..0b068bde443b4 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2009.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2009.md @@ -28,21 +28,21 @@ ms.author: mavasani namespace contains types that define immutable collections. This rule analyzes the following immutable collection types: -- -- -- -- -- -- - -These types define extension methods that create a new immutable collection from an existing collection. - -- defines . -- defines . -- defines . -- defines . -- defines . -- defines . +- +- +- +- +- +- + +These types define extension methods that create a new immutable collection from an existing collection. + +- defines . +- defines . +- defines . +- defines . +- defines . +- defines . These extension methods are designed to convert a mutable collection to an immutable collection. However, the caller might accidentally pass in an immutable collection as input to these methods. This can represent a performance and/or a functional issue. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2013.md b/docs/fundamentals/code-analysis/quality-rules/ca2013.md index 97e0bb810326a..a07858ef9427d 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2013.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2013.md @@ -22,11 +22,11 @@ author: buyaa-n ## Cause -Using method to test one or more value types for equality. +Using method to test one or more value types for equality. ## Rule description -When comparing values using , if objA and objB are value types, they are boxed before they are passed to the method. This means that even if both objA and objB represent the same instance of a value type, the method nevertheless returns false, as the following example shows. +When comparing values using , if objA and objB are value types, they are boxed before they are passed to the method. This means that even if both objA and objB represent the same instance of a value type, the method nevertheless returns false, as the following example shows. ## How to fix violations diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2015.md b/docs/fundamentals/code-analysis/quality-rules/ca2015.md index a667f67ee0556..38dd512cda6b2 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2015.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2015.md @@ -22,14 +22,14 @@ author: buyaa-n ## Cause -Defining finalizers for types derived from +Defining finalizers for types derived from ## Rule description -Adding a finalizer to a type derived from is likely an indication of a bug, as it suggests a native resource that could have been handed out in a is getting cleaned up and potentially while it is still in use by the . +Adding a finalizer to a type derived from is likely an indication of a bug, as it suggests a native resource that could have been handed out in a is getting cleaned up and potentially while it is still in use by the . > [!NOTE] -> The class is intended for advanced scenarios. Most developers do not need to use it. +> The class is intended for advanced scenarios. Most developers do not need to use it. ## How to fix violations diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2021.md b/docs/fundamentals/code-analysis/quality-rules/ca2021.md index 997c50cd98e17..ef16602485037 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2021.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2021.md @@ -22,20 +22,20 @@ dev_langs: ## Cause -A call to or specifies a type parameter that's incompatible with the type of the input collection. +A call to or specifies a type parameter that's incompatible with the type of the input collection. ## Rule description - and require compatible types to produce the expected result: + and require compatible types to produce the expected result: -- The generic cast used by the sequence returned by throws an at runtime on elements of incompatible types. -- The generic type check used by won't succeed with elements of incompatible types, resulting in an empty sequence. +- The generic cast used by the sequence returned by throws an at runtime on elements of incompatible types. +- The generic type check used by won't succeed with elements of incompatible types, resulting in an empty sequence. Widening and user-defined conversions aren't supported with generic types. ## How to fix violations -Use a compatible type for the type parameter of and . +Use a compatible type for the type parameter of and . ## Example diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2026.md b/docs/fundamentals/code-analysis/quality-rules/ca2026.md index 99e2c74659bab..5f7f6ccc6afeb 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2026.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2026.md @@ -29,7 +29,7 @@ Code uses `JsonDocument.Parse().RootElement` to parse JSON into a 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. + 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 @@ -73,5 +73,5 @@ For more information, see [How to suppress code analysis warnings](../suppress-w ## See also - [Reliability rules](reliability-warnings.md) -- -- +- +- diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2100.md b/docs/fundamentals/code-analysis/quality-rules/ca2100.md index c7c8ff0104cf5..e8e12b270c288 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2100.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2100.md @@ -25,7 +25,7 @@ dev_langs: ## Cause -A method sets the property by using a string that's built from a string argument to the method. +A method sets the property by using a string that's built from a string argument to the method. By default, this rule analyzes the entire codebase, but this is [configurable](#configure-code-to-analyze). @@ -37,7 +37,7 @@ This rule assumes that any string whose value can't be determined at compile tim - Use a parameterized command string. - Validate the user input for both type and content before you build the command string. -The following .NET types implement the property or provide constructors that set the property by using a string argument: +The following .NET types implement the property or provide constructors that set the property by using a string argument: - and - and diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2109.md b/docs/fundamentals/code-analysis/quality-rules/ca2109.md index 315fac2566a44..2a07662179b2a 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2109.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2109.md @@ -83,5 +83,5 @@ The following code shows an event-handling method that can be misused by malicio ## See also -- +- - diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2213.md b/docs/fundamentals/code-analysis/quality-rules/ca2213.md index 5dfb2d38e7346..c451746639674 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2213.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2213.md @@ -23,7 +23,7 @@ ms.author: gewarren ## Cause -A type that implements declares fields that are of types that also implement . The method of the field is not called by the method of the declaring type. +A type that implements declares fields that are of types that also implement . The method of the field is not called by the method of the declaring type. ## Rule description @@ -45,14 +45,14 @@ Passing an object of one of these types to a constructor and then assigning it t ## How to fix violations -To fix a violation of this rule, call on fields that are of types that implement . +To fix a violation of this rule, call on fields that are of types that implement . ## When to suppress warnings It's safe to suppress a warning from this rule if: - The flagged type is not responsible for releasing the resource held by the field (that is, the type does not have *dispose ownership*) -- The call to occurs at a deeper calling level than the rule checks +- The call to occurs at a deeper calling level than the rule checks - the dispose ownership of the field(s) is not held by the containing type. ## Suppress a warning @@ -93,7 +93,7 @@ The following snippet shows a type `TypeA` that implements on the field. +The following snippet shows a type `TypeB` that violates rule CA2213 by declaring a field `aFieldOfADisposableType` as a disposable type (`TypeA`) and not calling on the field. :::code language="csharp" source="snippets/csharp/all-rules/ca2213.cs" id="snippet2"::: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2215.md b/docs/fundamentals/code-analysis/quality-rules/ca2215.md index ea993cecaa0b4..198800cea8d13 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2215.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2215.md @@ -27,19 +27,19 @@ dev_langs: ## Cause -A type that implements inherits from a type that also implements . The method of the inheriting type does not call the method of the parent type. +A type that implements inherits from a type that also implements . The method of the inheriting type does not call the method of the parent type. ## Rule description -If a type inherits from a disposable type, it must call the method of the base type from within its own method. Calling the base type `Dispose` method ensures that any resources created by the base type are released. +If a type inherits from a disposable type, it must call the method of the base type from within its own method. Calling the base type `Dispose` method ensures that any resources created by the base type are released. ## How to fix violations -To fix a violation of this rule, call `base`. in your method. +To fix a violation of this rule, call `base`. in your method. ## When to suppress warnings -It is safe to suppress a warning from this rule if the call to `base`. occurs at a deeper calling level than the rule checks. +It is safe to suppress a warning from this rule if the call to `base`. occurs at a deeper calling level than the rule checks. ## Suppress a warning @@ -62,7 +62,7 @@ For more information, see [How to suppress code analysis warnings](../suppress-w ## Example -The following example shows two types, `TypeA` that implements , and `TypeB` that inherits from type `TypeA` and correctly calls its method. +The following example shows two types, `TypeA` that implements , and `TypeB` that inherits from type `TypeA` and correctly calls its method. :::code language="vb" source="snippets/vb/all-rules/ca2215.vb"::: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2216.md b/docs/fundamentals/code-analysis/quality-rules/ca2216.md index 566444f6473c7..6a468dc5f7538 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2216.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2216.md @@ -23,7 +23,7 @@ ms.author: gewarren ## Cause -A type that implements , and has fields that suggest the use of unmanaged resources, does not implement a finalizer as described by . +A type that implements , and has fields that suggest the use of unmanaged resources, does not implement a finalizer as described by . ## Rule description @@ -37,7 +37,7 @@ A violation of this rule is reported if the disposable type contains fields of t ## How to fix violations -To fix a violation of this rule, implement a finalizer that calls your method. +To fix a violation of this rule, implement a finalizer that calls your method. ## When to suppress warnings @@ -78,5 +78,5 @@ The following example shows a type that violates this rule. - - - -- +- - [Dispose Pattern](../../../standard/design-guidelines/dispose-pattern.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2218.md b/docs/fundamentals/code-analysis/quality-rules/ca2218.md index b26c448bab77d..3a740e9ca55f0 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2218.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2218.md @@ -23,28 +23,28 @@ dev_langs: ## Cause -A public type overrides but does not override . +A public type overrides but does not override . ## Rule description - returns a value, based on the current instance, that's suited for hashing algorithms and data structures such as hash tables. Two objects that are the same type and are equal must return the same hash code to ensure that instances of the following types work correctly: + returns a value, based on the current instance, that's suited for hashing algorithms and data structures such as hash tables. Two objects that are the same type and are equal must return the same hash code to ensure that instances of the following types work correctly: - - -- -- -- +- +- +- - - - -- Types that implement +- Types that implement > [!NOTE] > This rule only applies to Visual Basic code. The C# compiler generates a separate warning, [CS0659](../../../csharp/language-reference/compiler-messages/overloaded-operator-errors.md#equality-operators). ## How to fix violations -To fix a violation of this rule, provide an implementation of . For a pair of objects of the same type, ensure that the implementation returns the same value if your implementation of returns `true` for the pair. +To fix a violation of this rule, provide an implementation of . For a pair of objects of the same type, ensure that the implementation returns the same value if your implementation of returns `true` for the pair. ## When to suppress warnings @@ -71,7 +71,7 @@ The following example fixes the violation by overriding -- +- +- - - [Equality Operators](../../../standard/design-guidelines/equality-operators.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2224.md b/docs/fundamentals/code-analysis/quality-rules/ca2224.md index 3a0b0cab954e7..2d702f02ba270 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2224.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2224.md @@ -22,22 +22,22 @@ helpviewer_keywords: ## Cause -A public type implements the equality operator but doesn't override the method. +A public type implements the equality operator but doesn't override the method. ## Rule description -The equality operator is intended to be a syntactically convenient way to access the functionality of the method. If you implement the equality operator, its logic must be identical to that of . +The equality operator is intended to be a syntactically convenient way to access the functionality of the method. If you implement the equality operator, its logic must be identical to that of . > [!NOTE] > This rule only applies to Visual Basic code. The C# compiler generates a separate warning, [CS0660](../../../csharp/language-reference/compiler-messages/overloaded-operator-errors.md#equality-operators). ## How to fix violations -To fix a violation of this rule, you should either remove the implementation of the equality operator, or override and have the two methods return the same values. If the equality operator doesn't introduce inconsistent behavior, you can fix the violation by providing an implementation of that calls the method in the base class. +To fix a violation of this rule, you should either remove the implementation of the equality operator, or override and have the two methods return the same values. If the equality operator doesn't introduce inconsistent behavior, you can fix the violation by providing an implementation of that calls the method in the base class. ## When to suppress warnings -It's safe to suppress a warning from this rule if the equality operator returns the same value as the inherited implementation of . The examples in this article include a type that could safely suppress a warning from this rule. +It's safe to suppress a warning from this rule if the equality operator returns the same value as the inherited implementation of . The examples in this article include a type that could safely suppress a warning from this rule. ## Suppress a warning @@ -64,7 +64,7 @@ The following example shows a class (reference type) that violates this rule. :::code language="vb" source="snippets/vb/all-rules/ca2224.vb" id="1"::: -The following example fixes the violation by overriding . +The following example fixes the violation by overriding . :::code language="vb" source="snippets/vb/all-rules/ca2224.vb" id="2"::: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2227.md b/docs/fundamentals/code-analysis/quality-rules/ca2227.md index 6429b6c81edc4..6f7ea9e7d1cf4 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2227.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2227.md @@ -30,7 +30,7 @@ An externally visible, writable property is of a type that implements and methods of the class for an example of this pattern. +A writable collection property allows a user to replace the collection with a completely different collection. A read-only or [init-only](../../../csharp/language-reference/keywords/init.md) property stops the collection from being replaced, but still allows the individual members to be set. If replacing the collection is a goal, the preferred design pattern is to include a method to remove all the elements from the collection, and a method to repopulate the collection. See the and methods of the class for an example of this pattern. Both binary and XML serialization support read-only properties that are collections. The class has specific requirements for types that implement and in order to be serializable. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2229.md b/docs/fundamentals/code-analysis/quality-rules/ca2229.md index 563149ab9afbb..11259d54b3156 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2229.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2229.md @@ -36,7 +36,7 @@ The type implements the interface. The serialization constructor is required to deserialize, or recreate, objects that have been serialized using the method. +This rule is relevant for types that support custom serialization. A type supports custom serialization if it implements the interface. The serialization constructor is required to deserialize, or recreate, objects that have been serialized using the method. ## How to fix violations diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2231.md b/docs/fundamentals/code-analysis/quality-rules/ca2231.md index 6d02532b84b2e..f444ddf04d3c5 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2231.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2231.md @@ -27,13 +27,13 @@ dev_langs: ## Cause -A value type overrides but does not implement the equality operator. +A value type overrides but does not implement the equality operator. By default, this rule only looks at externally visible types, but this is [configurable](#configure-code-to-analyze). ## Rule description -In most programming languages, there is no default implementation of the equality operator (==) for value types. If your programming language supports operator overloads, you should consider implementing the equality operator. Its behavior should be identical to that of . +In most programming languages, there is no default implementation of the equality operator (==) for value types. If your programming language supports operator overloads, you should consider implementing the equality operator. Its behavior should be identical to that of . You cannot use the default equality operator in an overloaded implementation of the equality operator. Doing so will cause a stack overflow. To implement the equality operator, use the Object.Equals method in your implementation. For example: @@ -102,4 +102,4 @@ The following example defines a type that violates this rule: ## See also -- +- diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2241.md b/docs/fundamentals/code-analysis/quality-rules/ca2241.md index 9bea5fad38088..b88e51f52a3ae 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2241.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2241.md @@ -27,13 +27,13 @@ dev_langs: ## Cause -The `format` string argument passed to a method such as , , or does not contain a format item that corresponds to each object argument, or vice versa. +The `format` string argument passed to a method such as , , or does not contain a format item that corresponds to each object argument, or vice versa. By default, this rule only analyzes calls to the three methods mentioned previously, but this is [configurable](#configure-code-to-analyze). ## Rule description -The arguments to methods such as , , and consist of a format string followed by several instances. The format string consists of text and embedded format items of the form `{index[,alignment][:formatString]}`. 'index' is a zero-based integer that indicates which of the objects to format. If an object does not have a corresponding index in the format string, the object is ignored. If the object specified by 'index' does not exist, a is thrown at runtime. +The arguments to methods such as , , and consist of a format string followed by several instances. The format string consists of text and embedded format items of the form `{index[,alignment][:formatString]}`. 'index' is a zero-based integer that indicates which of the objects to format. If an object does not have a corresponding index in the format string, the object is ignored. If the object specified by 'index' does not exist, a is thrown at runtime. ## How to fix violations diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2242.md b/docs/fundamentals/code-analysis/quality-rules/ca2242.md index 12f55afd40ca4..27c11d2acdec0 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2242.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2242.md @@ -33,7 +33,7 @@ An expression tests a value against , use or to test the value. +To fix a violation of this rule and accurately determine whether a value represents , use or to test the value. ## When to suppress warnings @@ -41,7 +41,7 @@ Do not suppress a warning from this rule. ## Example -The following example shows two expressions that incorrectly test a value against and an expression that correctly uses to test the value. +The following example shows two expressions that incorrectly test a value against and an expression that correctly uses to test the value. :::code language="vb" source="snippets/vb/all-rules/ca2242-test-for-nan-correctly_1.vb"::: diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2247.md b/docs/fundamentals/code-analysis/quality-rules/ca2247.md index 952394c6741a2..cdf1be4628874 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2247.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2247.md @@ -24,7 +24,7 @@ ms.author: stoub ## Cause Constructing a `System.Threading.Tasks.TaskCompletionSource` with a enum value rather than a enum value. -Using method to test one or more value types for equality. +Using method to test one or more value types for equality. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2249.md b/docs/fundamentals/code-analysis/quality-rules/ca2249.md index b2d55dbd71dfe..185493bce8f06 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2249.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2249.md @@ -20,13 +20,13 @@ author: pgovind ## Cause -This rule locates calls to where the result is used to check for the presence or absence of a substring, and suggests using instead, to improve readability. +This rule locates calls to where the result is used to check for the presence or absence of a substring, and suggests using instead, to improve readability. ## Rule description -When is used to check if the result is equal to `-1` or greater or equal than `0`, the call can be safely substituted with without an impact on performance. +When is used to check if the result is equal to `-1` or greater or equal than `0`, the call can be safely substituted with without an impact on performance. -Depending on the overload being used, the suggested fix could get a `comparisonType` argument added: +Depending on the overload being used, the suggested fix could get a `comparisonType` argument added: | Overload | Suggested fix | | -------------------------------------------------------- | ---------------------------------------------------------- | diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2251.md b/docs/fundamentals/code-analysis/quality-rules/ca2251.md index c272a4c84fea4..a08380c26e73a 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2251.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2251.md @@ -22,15 +22,15 @@ author: NewellClark ## Cause -The result of a call to is compared to zero. +The result of a call to is compared to zero. ## Rule description - is designed to produce a total-order comparison that can be used for sorting. If you only care whether the strings are equal, it is both clearer and likely faster to use an equivalent overload of . + is designed to produce a total-order comparison that can be used for sorting. If you only care whether the strings are equal, it is both clearer and likely faster to use an equivalent overload of . ## How to fix violations -To fix violations of this rule, replace the expression comparing the result of with a call to . +To fix violations of this rule, replace the expression comparing the result of with a call to . ## Example diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2253.md b/docs/fundamentals/code-analysis/quality-rules/ca2253.md index 66a422b4d226a..5310d88bbd311 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2253.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2253.md @@ -34,7 +34,7 @@ Named placeholders in the logging message template should not be composed of onl Rename the numeric placeholder. -For usage examples, see the method. +For usage examples, see the method. ## Example diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2254.md b/docs/fundamentals/code-analysis/quality-rules/ca2254.md index 10a6711e629ea..c3cac7f302bb4 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2254.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2254.md @@ -64,7 +64,7 @@ Update the message template to be a constant expression. If you're using values logger.LogWarning("Person {FirstName} {LastName} encountered an issue", firstName, lastName); ``` -For usage examples, see the method. +For usage examples, see the method. ## When to suppress errors diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2261.md b/docs/fundamentals/code-analysis/quality-rules/ca2261.md index ff1008587949f..27bc802b5948a 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2261.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2261.md @@ -19,15 +19,15 @@ helpviewer_keywords: ## Cause -A value of is passed to . +A value of is passed to . ## Rule description -The option isn't supported by the generic , since that might lead to returning an invalid `TResult`. This rule flags the use of with to surface the error at build time rather than runtime. +The option isn't supported by the generic , since that might lead to returning an invalid `TResult`. This rule flags the use of with to surface the error at build time rather than runtime. ## How to fix violations -Cast the to a non-generic before calling . +Cast the to a non-generic before calling . ## Example diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2264.md b/docs/fundamentals/code-analysis/quality-rules/ca2264.md index 8f33281532fd4..b3c2b3e71b065 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2264.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2264.md @@ -26,7 +26,7 @@ A value that's known to never be null is passed to `ArgumentNullException.ThrowI ## Rule description -`ArgumentNullException.ThrowIfNull` throws when the passed argument is `null`. Certain constructs like non-nullable structs (except for ), type parameters known to be non-nullable structs, 'nameof()' expressions, and 'new' expressions are known to never be null, so `ArgumentNullException.ThrowIfNull` will never throw. Thus, calling `ArgumentNullException.ThrowIfNull` is unnecessary. +`ArgumentNullException.ThrowIfNull` throws when the passed argument is `null`. Certain constructs like non-nullable structs (except for ), type parameters known to be non-nullable structs, 'nameof()' expressions, and 'new' expressions are known to never be null, so `ArgumentNullException.ThrowIfNull` will never throw. Thus, calling `ArgumentNullException.ThrowIfNull` is unnecessary. In the case of a struct, since `ArgumentNullException.ThrowIfNull` accepts an `object?`, the struct is boxed, which causes an additional performance penalty. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2350.md b/docs/fundamentals/code-analysis/quality-rules/ca2350.md index d7d24642b3fd5..7e5898bcdd0e2 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2350.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2350.md @@ -21,7 +21,7 @@ f1_keywords: ## Cause -The method was called or referenced. +The method was called or referenced. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2351.md b/docs/fundamentals/code-analysis/quality-rules/ca2351.md index 6239089f4a132..5763b5169d3a9 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2351.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2351.md @@ -21,7 +21,7 @@ f1_keywords: ## Cause -The method was called or referenced, and not within autogenerated code. +The method was called or referenced, and not within autogenerated code. This rule classifies autogenerated code b: @@ -29,7 +29,7 @@ This rule classifies autogenerated code b: - The `ReadXmlSerializable` method has a . - The `ReadXmlSerializable` method is within a type that has a . -[CA2361](ca2361.md) is a similar rule, for when appears within autogenerated code. +[CA2361](ca2361.md) is a similar rule, for when appears within autogenerated code. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2355.md b/docs/fundamentals/code-analysis/quality-rules/ca2355.md index 9a7ab2db9afb2..ef8b4ce256663 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2355.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2355.md @@ -30,9 +30,9 @@ The casted or specified type is evaluated when: - Initializing a object - Initializing a object - Initializing an object -- Invoking -- Invoking -- Invoking +- Invoking +- Invoking +- Invoking - Invoking Newtonsoft Json.NET JsonSerializer.Deserialize - Invoking Newtonsoft Json.NET JsonConvert.DeserializeObject diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2361.md b/docs/fundamentals/code-analysis/quality-rules/ca2361.md index faa323b0d1697..679578ae573bc 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2361.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2361.md @@ -21,7 +21,7 @@ f1_keywords: ## Cause -The method was called or referenced, and is within autogenerated code. +The method was called or referenced, and is within autogenerated code. This rule classifies autogenerated code b: @@ -29,7 +29,7 @@ This rule classifies autogenerated code b: - The `ReadXmlSerializable` method has a . - The `ReadXmlSerializable` method is within a type that has a . -[CA2351](ca2351.md) is a similar rule, for when appears within non-autogenerated code. +[CA2351](ca2351.md) is a similar rule, for when appears within non-autogenerated code. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca3012.md b/docs/fundamentals/code-analysis/quality-rules/ca3012.md index 5e1f706562968..6c7c3aa08af94 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca3012.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca3012.md @@ -44,7 +44,7 @@ Some mitigations against regex injections include: - Always use a [match timeout](../../../standard/base-types/best-practices-regex.md#use-time-out-values) when using regular expressions. - Avoid using regular expressions based on user input. -- Escape special characters from user input by calling or another method. +- Escape special characters from user input by calling or another method. - Allow only non-special characters from user input. ## When to suppress warnings diff --git a/docs/fundamentals/code-analysis/quality-rules/ca3075.md b/docs/fundamentals/code-analysis/quality-rules/ca3075.md index bbc0b891a0575..708694a68caf3 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca3075.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca3075.md @@ -25,13 +25,13 @@ A *Document Type Definition (DTD)* is one of two ways an XML parser can determin - DtdProcessing is enabled on the instance, which resolves external XML entities using . -- The property in the XML is set. +- The property in the XML is set. - property is set to Parse. - Untrusted input is processed using instead of . -- The method is invoked with an insecure instance or no instance at all. +- The method is invoked with an insecure instance or no instance at all. - is created with insecure default settings or values. @@ -45,11 +45,11 @@ In each of these cases, the outcome is the same: the contents from either the fi - Do not allow the to open any external resources by setting the property to **null**. -- Ensure that the property is assigned from a trusted source. +- Ensure that the property is assigned from a trusted source. ### .NET Framework 3.5 and earlier -- Disable DTD processing if you are dealing with untrusted sources by setting the property to **true**. +- Disable DTD processing if you are dealing with untrusted sources by setting the property to **true**. - XmlTextReader class has a full trust inheritance demand. @@ -380,4 +380,4 @@ namespace TestNamespace ``` > [!NOTE] -> Although is the recommended way to create an instance, there are behavior differences from . An from normalizes `\r\n` to `\n` in XML values, while preserves the `\r\n` sequence. +> Although is the recommended way to create an instance, there are behavior differences from . An from normalizes `\r\n` to `\n` in XML values, while preserves the `\r\n` sequence. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca3076.md b/docs/fundamentals/code-analysis/quality-rules/ca3076.md index 7c15b51c2cba1..08c6a07bb5fff 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca3076.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca3076.md @@ -23,7 +23,7 @@ If you execute Extensible Stylesheets Language Transformations (XSLT) in .NET ap *XSLT* is a World Wide Web Consortium (W3C) standard for transforming XML data. XSLT is typically used to write style sheets to transform XML data to other formats such as HTML, fixed-length text, comma-separated text, or a different XML format. Although prohibited by default, you might choose to enable it for your project. -To ensure you're not exposing an attack surface, this rule triggers whenever the XslCompiledTransform. receives insecure combination instances of and , which allows malicious script processing. +To ensure you're not exposing an attack surface, this rule triggers whenever the XslCompiledTransform. receives insecure combination instances of and , which allows malicious script processing. ## How to fix violations @@ -150,7 +150,7 @@ namespace TestNamespace ``` > [!NOTE] -> Starting in .NET 10, the property is marked as obsolete and generates warning `SYSLIB0062`. On .NET (Core), it's no longer necessary to explicitly set this property to `false` since script execution isn't supported. +> Starting in .NET 10, the property is marked as obsolete and generates warning `SYSLIB0062`. On .NET (Core), it's no longer necessary to explicitly set this property to `false` since script execution isn't supported. ## See also diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5360.md b/docs/fundamentals/code-analysis/quality-rules/ca5360.md index 0757d8e7fe1d5..73ede96e7469f 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5360.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5360.md @@ -22,34 +22,34 @@ f1_keywords: Calling one of the following dangerous methods in deserialization: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- All methods meets one of the following requirements could be the callback of deserialization: - Marked with . - Marked with . -- Implementing . -- Implementing . +- Implementing . +- Implementing . - Is a destructor. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5361.md b/docs/fundamentals/code-analysis/quality-rules/ca5361.md index 47294aa07fc66..5dce953e777a5 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5361.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5361.md @@ -23,7 +23,7 @@ f1_keywords: ## Cause -A method call sets `Switch.System.Net.DontEnableSchUseStrongCrypto` to `true`. +A method call sets `Switch.System.Net.DontEnableSchUseStrongCrypto` to `true`. By default, this rule analyzes the entire codebase, but this is [configurable](#configure-code-to-analyze). @@ -33,7 +33,7 @@ Setting `Switch.System.Net.DontEnableSchUseStrongCrypto` to `true` weakens the c ## How to fix violations -- If your application targets .NET Framework v4.6 or later, you can either remove the method call, or set the switch's value to `false`. +- If your application targets .NET Framework v4.6 or later, you can either remove the method call, or set the switch's value to `false`. - If your application targets .NET Framework earlier than v4.6 and runs on .NET Framework v4.6 or later, set the switch's value to `false`. - Otherwise, refer to [Transport Layer Security (TLS) best practices with .NET Framework](../../../framework/network-programming/tls.md) for mitigations. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5366.md b/docs/fundamentals/code-analysis/quality-rules/ca5366.md index e761b80f36b84..2b5ff0b47c5a5 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5366.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5366.md @@ -21,9 +21,9 @@ f1_keywords: A Document Type Definition (DTD) defines the structure and the legal elements and attributes of an XML document. Referring to a DTD from an external resource could cause potential Denial of Service (DoS) attacks. Most readers cannot disable DTD processing and restrict external references loading except for . Using these other readers to load XML by one of the following methods triggers this rule: -- -- -- +- +- +- ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5368.md b/docs/fundamentals/code-analysis/quality-rules/ca5368.md index 233cae77c368b..965deb8838eda 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5368.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5368.md @@ -20,7 +20,7 @@ f1_keywords: ## Cause -The property is not assigned in or the `Page_Init` method. +The property is not assigned in or the `Page_Init` method. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5369.md b/docs/fundamentals/code-analysis/quality-rules/ca5369.md index 578004f79a9e7..908104f312bad 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5369.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5369.md @@ -21,15 +21,15 @@ f1_keywords: ## Cause -Deserializing untrusted XML input with instantiated without an `XmlReader` object can potentially lead to denial of service, information disclosure, and server-side request forgery attacks. These attacks are enabled by untrusted DTD and XML schema processing, which allows for the inclusion of XML bombs and malicious external entities in the XML. Only with `XmlReader` is it possible to disable DTD. Inline XML schema processing as `XmlReader` has the `ProhibitDtd` and `ProcessInlineSchema` property set to `false` by default in .NET Framework version 4.0 and later. The other options such as `Stream`, `TextReader`, and `XmlSerializationReader` cannot disable DTD processing. +Deserializing untrusted XML input with instantiated without an `XmlReader` object can potentially lead to denial of service, information disclosure, and server-side request forgery attacks. These attacks are enabled by untrusted DTD and XML schema processing, which allows for the inclusion of XML bombs and malicious external entities in the XML. Only with `XmlReader` is it possible to disable DTD. Inline XML schema processing as `XmlReader` has the `ProhibitDtd` and `ProcessInlineSchema` property set to `false` by default in .NET Framework version 4.0 and later. The other options such as `Stream`, `TextReader`, and `XmlSerializationReader` cannot disable DTD processing. ## Rule description -Processing untrusted DTD and XML schemas may enable loading dangerous external references, which should be restricted by using an `XmlReader` with a secure resolver or with DTD and XML inline schema processing disabled. This rule detects code that uses the method and does not take `XmlReader` as a constructor parameter. +Processing untrusted DTD and XML schemas may enable loading dangerous external references, which should be restricted by using an `XmlReader` with a secure resolver or with DTD and XML inline schema processing disabled. This rule detects code that uses the method and does not take `XmlReader` as a constructor parameter. ## How to fix violations -Do not use overloads other than , , , or . +Do not use overloads other than , , , or . ## When to suppress warnings @@ -59,7 +59,7 @@ For more information, see [How to suppress code analysis warnings](../suppress-w ### Violation The following pseudo-code sample illustrates the pattern detected by this rule. -The type of the first parameter of is not `XmlReader` or a derived class thereof. +The type of the first parameter of is not `XmlReader` or a derived class thereof. ```csharp using System.IO; diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5370.md b/docs/fundamentals/code-analysis/quality-rules/ca5370.md index d25c848565a4f..909217cb145b2 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5370.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5370.md @@ -30,7 +30,7 @@ Processing untrusted DTD and XML schemas may enable loading dangerous external r ## How to fix violations - Use `XmlValidatingReader(XmlReader)` with `ProhibitDtd` and `ProcessInlineSchema` properties set to `false`. -- Starting in .NET Framework 2.0, `XmlValidatingReader` is considered obsolete. You can instantiate a validating reader with . +- Starting in .NET Framework 2.0, `XmlValidatingReader` is considered obsolete. You can instantiate a validating reader with . ## When to suppress warnings diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5371.md b/docs/fundamentals/code-analysis/quality-rules/ca5371.md index 265979c71959c..c1d82147e8b38 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5371.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5371.md @@ -21,11 +21,11 @@ f1_keywords: ## Cause -Processing untrusted XML input with instantiated without an `XmlReader` object can potentially lead to denial of service, information disclosure, and server-side request forgery attacks. These attacks are enabled by untrusted DTD and XML schema processing, which allows for the inclusion of XML bombs and malicious external entities in the XML. Only with `XmlReader` is it possible to disable DTD. Inline XML schema processing as `XmlReader` has the `ProhibitDtd` and `ProcessInlineSchema` property set to false by default in .NET Framework starting in version 4.0. The other options such as `Stream`, `TextReader`, and `XmlSerializationReader` cannot disable DTD processing. +Processing untrusted XML input with instantiated without an `XmlReader` object can potentially lead to denial of service, information disclosure, and server-side request forgery attacks. These attacks are enabled by untrusted DTD and XML schema processing, which allows for the inclusion of XML bombs and malicious external entities in the XML. Only with `XmlReader` is it possible to disable DTD. Inline XML schema processing as `XmlReader` has the `ProhibitDtd` and `ProcessInlineSchema` property set to false by default in .NET Framework starting in version 4.0. The other options such as `Stream`, `TextReader`, and `XmlSerializationReader` cannot disable DTD processing. ## Rule description -Processing untrusted DTD and XML schemas may enable loading dangerous external references. Using an `XmlReader` with a secure resolver or with DTD and XML inline schema processing disabled restricts this. This rule detects code that uses the method without `XmlReader` as a parameter. +Processing untrusted DTD and XML schemas may enable loading dangerous external references. Using an `XmlReader` with a secure resolver or with DTD and XML inline schema processing disabled restricts this. This rule detects code that uses the method without `XmlReader` as a parameter. ## How to fix violations @@ -33,7 +33,7 @@ Use `XmlSchema.Read(XmlReader, *)` overloads. ## When to suppress warnings -You can potentially suppress this warning if the method is always used to process XML that comes from a trusted source and hence cannot be tampered with. +You can potentially suppress this warning if the method is always used to process XML that comes from a trusted source and hence cannot be tampered with. ## Suppress a warning @@ -59,7 +59,7 @@ For more information, see [How to suppress code analysis warnings](../suppress-w ### Violation The following pseudo-code sample illustrates the pattern detected by this rule. -The type of the first parameter of is not `XmlReader`. +The type of the first parameter of is not `XmlReader`. ```csharp using System.IO; diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5373.md b/docs/fundamentals/code-analysis/quality-rules/ca5373.md index f9c6cc8cfddfc..80d065ba31fdd 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5373.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5373.md @@ -21,16 +21,16 @@ f1_keywords: ## Cause -Cryptographically weak key derivation methods and/or are used to generate a key. +Cryptographically weak key derivation methods and/or are used to generate a key. ## Rule description -This rule detects the invocation of weak key derivation methods and . - used a weak algorithm PBKDF1. does not use iteration count and salt from the `Rfc2898DeriveBytes` object, which makes it weak. +This rule detects the invocation of weak key derivation methods and . + used a weak algorithm PBKDF1. does not use iteration count and salt from the `Rfc2898DeriveBytes` object, which makes it weak. ## How to fix violations -Password-based key derivation should use the PBKDF2 algorithm with SHA-2 hashing. can be used to achieve that. +Password-based key derivation should use the PBKDF2 algorithm with SHA-2 hashing. can be used to achieve that. ## When to suppress warnings diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5378.md b/docs/fundamentals/code-analysis/quality-rules/ca5378.md index fcb958c49b0d9..c6ee0d30a25dd 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5378.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5378.md @@ -23,7 +23,7 @@ f1_keywords: ## Cause -A method call sets `Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols` to `true`. +A method call sets `Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols` to `true`. By default, this rule analyzes the entire codebase, but this is [configurable](#configure-code-to-analyze). @@ -33,7 +33,7 @@ Setting `Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProto ## How to fix violations -- If your application targets .NET Framework v4.7 or later, you can either remove the method call, or set the switch's value to `false`. +- If your application targets .NET Framework v4.7 or later, you can either remove the method call, or set the switch's value to `false`. - If your application targets .NET Framework v4.6.2 or earlier and runs on .NET Framework v4.7 or later, set the switch's value to `false`. - Otherwise, refer to [Transport Layer Security (TLS) best practices with .NET Framework](../../../framework/network-programming/tls.md) for mitigations. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5382.md b/docs/fundamentals/code-analysis/quality-rules/ca5382.md index fbd42e21cbd52..d21910da0e5fc 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5382.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5382.md @@ -20,7 +20,7 @@ f1_keywords: ## Cause -The property is set as `false` when invoking . For now, this rule only looks at the Microsoft.AspNetCore.Http.Internal.ResponseCookies class, which is one of the implementations of . +The property is set as `false` when invoking . For now, this rule only looks at the Microsoft.AspNetCore.Http.Internal.ResponseCookies class, which is one of the implementations of . This rule is similar to [CA5383](ca5383.md), but analysis can determine that the property is definitely `false` or not set. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5383.md b/docs/fundamentals/code-analysis/quality-rules/ca5383.md index 4280635516982..422608c8e062d 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5383.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5383.md @@ -20,7 +20,7 @@ f1_keywords: ## Cause -The property may be set as `false` when invoking . For now, this rule only looks at the Microsoft.AspNetCore.Http.Internal.ResponseCookies class, which is one of the implementations of . +The property may be set as `false` when invoking . For now, this rule only looks at the Microsoft.AspNetCore.Http.Internal.ResponseCookies class, which is one of the implementations of . This rule is similar to [CA5382](ca5382.md), but analysis can't determine that the property is definitely `false` or not set. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5384.md b/docs/fundamentals/code-analysis/quality-rules/ca5384.md index 000c304b2e89c..8e40cc31e14d9 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5384.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5384.md @@ -23,7 +23,7 @@ f1_keywords: Using DSA in one of the following ways: - Returning or instantiating derived classes of -- Using or to create a DSA object. +- Using or to create a DSA object. By default, this rule analyzes the entire codebase, but this is [configurable](#configure-code-to-analyze). diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5385.md b/docs/fundamentals/code-analysis/quality-rules/ca5385.md index 6e619699e6bd9..40c40b74569c5 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5385.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5385.md @@ -24,10 +24,10 @@ Using asymmetric encryption algorithm RSA with key size less than 2048 in one of - Instantiating any descendant classes of and specifying the `KeySize` parameter as less than 2048. - Returning any object whose type is descendant of . -- Using without parameter which would create RSA with the default key size 1024. -- Using and specifying the `algName` parameter as `RSA` with the default key size 1024. -- Using and specifying the `name` parameter as `RSA` with the default key size 1024. -- Using and specifying the `name` parameter as `RSA` and specifying the key size as smaller than 2048 explicitly by `args`. +- Using without parameter which would create RSA with the default key size 1024. +- Using and specifying the `algName` parameter as `RSA` with the default key size 1024. +- Using and specifying the `name` parameter as `RSA` with the default key size 1024. +- Using and specifying the `name` parameter as `RSA` and specifying the key size as smaller than 2048 explicitly by `args`. ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5387.md b/docs/fundamentals/code-analysis/quality-rules/ca5387.md index 876a75a76a918..6bc4d336326aa 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5387.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5387.md @@ -19,7 +19,7 @@ f1_keywords: ## Cause -Using with the default iteration count or specifying an iteration count of less than 100,000. +Using with the default iteration count or specifying an iteration count of less than 100,000. By default, this rule analyzes the entire codebase, but this is [configurable](#configure-code-to-analyze). @@ -31,7 +31,7 @@ This rule is similar to [CA5388](ca5388.md), but analysis determines that the it ## How to fix violations -Set the iteration count greater than or equal with 100,000 before calling . +Set the iteration count greater than or equal with 100,000 before calling . ## When to suppress warnings diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5388.md b/docs/fundamentals/code-analysis/quality-rules/ca5388.md index b4bf0a050c1d9..f7a0c0e9711c1 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5388.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5388.md @@ -19,7 +19,7 @@ f1_keywords: ## Cause -Iteration count may be smaller than 100,000 when deriving cryptographic key by . +Iteration count may be smaller than 100,000 when deriving cryptographic key by . By default, this rule analyzes the entire codebase, but this is [configurable](#configure-code-to-analyze). @@ -31,7 +31,7 @@ This rule is similar to [CA5387](ca5387.md), but analysis can't determine if the ## How to fix violations -Set the iteration count greater than or equal with 100k before calling explicitly. +Set the iteration count greater than or equal with 100k before calling explicitly. ## When to suppress warnings diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5389.md b/docs/fundamentals/code-analysis/quality-rules/ca5389.md index c73f7fb958672..61482122b7e75 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5389.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5389.md @@ -23,10 +23,10 @@ f1_keywords: A non-sanitized source file path is used as the target file path in one of these parameters: -- parameter `destinationFileName` of method -- parameter `path` of method -- parameter `path` of method -- parameter `path` of method +- parameter `destinationFileName` of method +- parameter `path` of method +- parameter `path` of method +- parameter `path` of method - parameter `path` of constructor for - parameter `fileName` of constructor for diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5390.md b/docs/fundamentals/code-analysis/quality-rules/ca5390.md index 290479ecacd56..ae135635d91d4 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5390.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5390.md @@ -19,11 +19,11 @@ f1_keywords: ## Cause -The `key` parameter of the or constructor, property, or the `rgbKey` parameter of the or method is hard-coded by one of the following: +The `key` parameter of the or constructor, property, or the `rgbKey` parameter of the or method is hard-coded by one of the following: - Byte array. -- . -- All the overloads of . +- . +- All the overloads of . By default, this rule analyzes the entire codebase, but this is [configurable](#configure-code-to-analyze). diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5391.md b/docs/fundamentals/code-analysis/quality-rules/ca5391.md index 7fb5ef95a3b36..da8eedb0b78fd 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5391.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5391.md @@ -30,7 +30,7 @@ Handling a `POST`, `PUT`, `PATCH`, or `DELETE` request without validating an ant - Mark the modifying action with a valid antiforgery token attribute: - . - Attribute whose name is like `%Validate%Anti_orgery%Attribute`. -- Add the valid forgery token attribute into the global filter with . +- Add the valid forgery token attribute into the global filter with . - Add any custom or Mvc-provided antiforgery filter class that calls `Validate` on any class that implements the interface. ## When to suppress warnings diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5401.md b/docs/fundamentals/code-analysis/quality-rules/ca5401.md index 39910b9dddeaf..bca5462aaf6bc 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5401.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5401.md @@ -19,7 +19,7 @@ f1_keywords: ## Cause -Using with non-default `rgbIV`. +Using with non-default `rgbIV`. ## Rule description @@ -29,13 +29,13 @@ This rule is similar to [CA5402](ca5402.md), but analysis determines that the in ## How to fix violations -Use the default `rgbIV` value, that is, use the overload of the which doesn't have any parameter. +Use the default `rgbIV` value, that is, use the overload of the which doesn't have any parameter. ## When to suppress warnings It's safe to suppress a warning from this rule if: -- The `rgbIV` parameter was generated by . +- The `rgbIV` parameter was generated by . - You're sure that the `rgbIV` is really random and non-repeatable. ## Suppress a warning diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5402.md b/docs/fundamentals/code-analysis/quality-rules/ca5402.md index c1563c7edd443..7c1bd2ae85ea2 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5402.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5402.md @@ -19,7 +19,7 @@ f1_keywords: ## Cause -The `rgbIV` could be non-default when using . +The `rgbIV` could be non-default when using . ## Rule description @@ -29,13 +29,13 @@ This rule is similar to [CA5401](ca5401.md), but analysis can't determine that t ## How to fix violations -Use the default `rgbIV` value explicitly, that is, use the overload of the which doesn't have any parameter. +Use the default `rgbIV` value explicitly, that is, use the overload of the which doesn't have any parameter. ## When to suppress warnings It's safe to suppress a warning from this rule if: -- The `rgbIV` parameter was generated by . +- The `rgbIV` parameter was generated by . - You're sure that the `rgbIV` parameter is really random and non-repeatable. - You're sure that the initialization vector is used. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca5403.md b/docs/fundamentals/code-analysis/quality-rules/ca5403.md index 627febea00c3e..34b095485086a 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca5403.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca5403.md @@ -26,7 +26,7 @@ The `data` or `rawData` parameter of a . -- All the overloads of . +- All the overloads of . ## Rule description diff --git a/docs/fundamentals/code-analysis/quality-rules/design-warnings.md b/docs/fundamentals/code-analysis/quality-rules/design-warnings.md index 49beba9b677a9..874784a445db2 100644 --- a/docs/fundamentals/code-analysis/quality-rules/design-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/design-warnings.md @@ -63,8 +63,8 @@ Design rules support adherence to the [.NET Framework design guidelines](../../. | [CA1063: Implement IDisposable correctly](ca1063.md) | All IDisposable types should implement the Dispose pattern correctly. | | [CA1064: Exceptions should be public](ca1064.md) | An internal exception is visible only inside its own internal scope. After the exception falls outside the internal scope, only the base exception can be used to catch the exception. If the internal exception is inherited from , , or , the external code will not have sufficient information to know what to do with the exception. | | [CA1065: Do not raise exceptions in unexpected locations](ca1065.md) | A method that is not expected to throw exceptions throws an exception. | -| [CA1066: Implement IEquatable when overriding Equals](ca1066.md) | A value type overrides method, but does not implement . | -| [CA1067: Override Equals when implementing IEquatable](ca1067.md) | A type implements , but does not override method. | +| [CA1066: Implement IEquatable when overriding Equals](ca1066.md) | A value type overrides method, but does not implement . | +| [CA1067: Override Equals when implementing IEquatable](ca1067.md) | A type implements , but does not override method. | | [CA1068: CancellationToken parameters must come last](ca1068.md) | A method has a CancellationToken parameter that is not the last parameter. | | [CA1069: Enums should not have duplicate values](ca1069.md) | An enumeration has multiple members which are explicitly assigned the same constant value. | | [CA1070: Do not declare event fields as virtual](ca1070.md) | A [field-like event](../../../csharp/event-pattern.md#define-and-raise-field-like-events) was declared as virtual. | diff --git a/docs/fundamentals/code-analysis/quality-rules/index.md b/docs/fundamentals/code-analysis/quality-rules/index.md index 152e509a557f6..e88df83dcf8d9 100644 --- a/docs/fundamentals/code-analysis/quality-rules/index.md +++ b/docs/fundamentals/code-analysis/quality-rules/index.md @@ -59,8 +59,8 @@ The following table lists code quality analysis rules. > | [CA1063: Implement IDisposable correctly](ca1063.md) | All IDisposable types should implement the Dispose pattern correctly. | > | [CA1064: Exceptions should be public](ca1064.md) | An internal exception is visible only inside its own internal scope. After the exception falls outside the internal scope, only the base exception can be used to catch the exception. If the internal exception is inherited from , , or , the external code will not have sufficient information to know what to do with the exception. | > | [CA1065: Do not raise exceptions in unexpected locations](ca1065.md) | A method that is not expected to throw exceptions throws an exception. | -> | [CA1066: Implement IEquatable when overriding Equals](ca1066.md) | A value type overrides method, but does not implement . | -> | [CA1067: Override Equals when implementing IEquatable](ca1067.md) | A type implements , but does not override method. | +> | [CA1066: Implement IEquatable when overriding Equals](ca1066.md) | A value type overrides method, but does not implement . | +> | [CA1067: Override Equals when implementing IEquatable](ca1067.md) | A type implements , but does not override method. | > | [CA1068: CancellationToken parameters must come last](ca1068.md) | A method has a CancellationToken parameter that is not the last parameter. | > | [CA1069: Enums should not have duplicate values](ca1069.md) | An enumeration has multiple members which are explicitly assigned the same constant value. | > | [CA1070: Do not declare event fields as virtual](ca1070.md) | A [field-like event](../../../csharp/event-pattern.md#define-and-raise-field-like-events) was declared as virtual. | @@ -127,18 +127,18 @@ The following table lists code quality analysis rules. > | [CA1822: Mark members as static](ca1822.md) | Members that do not access instance data or call instance methods can be marked as static (Shared in Visual Basic). After you mark the methods as static, the compiler will emit nonvirtual call sites to these members. This can give you a measurable performance gain for performance-sensitive code. | > | [CA1823: Avoid unused private fields](ca1823.md) | Private fields were detected that do not appear to be accessed in the assembly. | > | [CA1824: Mark assemblies with NeutralResourcesLanguageAttribute](ca1824.md) | The NeutralResourcesLanguage attribute informs the resource manager of the language that was used to display the resources of a neutral culture for an assembly. This improves lookup performance for the first resource that you load and can reduce your working set. | -> | [CA1825: Avoid zero-length array allocations](ca1825.md) | Initializing a zero-length array leads to unnecessary memory allocation. Instead, use the statically allocated empty array instance by calling . The memory allocation is shared across all invocations of this method. | +> | [CA1825: Avoid zero-length array allocations](ca1825.md) | Initializing a zero-length array leads to unnecessary memory allocation. Instead, use the statically allocated empty array instance by calling . The memory allocation is shared across all invocations of this method. | > | [CA1826: Use property instead of Linq Enumerable method](ca1826.md) | LINQ method was used on a type that supports an equivalent, more efficient property. | -> | [CA1827: Do not use Count/LongCount when Any can be used](ca1827.md) | or method was used where method would be more efficient. | -> | [CA1828: Do not use CountAsync/LongCountAsync when AnyAsync can be used](ca1828.md) | or method was used where method would be more efficient. | -> | [CA1829: Use Length/Count property instead of Enumerable.Count method](ca1829.md) | LINQ method was used on a type that supports an equivalent, more efficient `Length` or `Count` property. | -> | [CA1830: Prefer strongly-typed Append and Insert method overloads on StringBuilder](ca1830.md) | and provide overloads for multiple types beyond . When possible, prefer the strongly-typed overloads over using ToString() and the string-based overload. | -> | [CA1831: Use AsSpan instead of Range-based indexers for string when appropriate](ca1831.md) | When using a range-indexer on a string and implicitly assigning the value to ReadOnlySpan<char> type, the method will be used instead of , which produces a copy of requested portion of the string. | -> | [CA1832: Use AsSpan or AsMemory instead of Range-based indexers for getting ReadOnlySpan or ReadOnlyMemory portion of an array](ca1832.md) | When using a range-indexer on an array and implicitly assigning the value to a or type, the method will be used instead of , which produces a copy of requested portion of the array. | -> | [CA1833: Use AsSpan or AsMemory instead of Range-based indexers for getting Span or Memory portion of an array](ca1833.md) | When using a range-indexer on an array and implicitly assigning the value to a or type, the method will be used instead of , which produces a copy of requested portion of the array. | +> | [CA1827: Do not use Count/LongCount when Any can be used](ca1827.md) | or method was used where method would be more efficient. | +> | [CA1828: Do not use CountAsync/LongCountAsync when AnyAsync can be used](ca1828.md) | or method was used where method would be more efficient. | +> | [CA1829: Use Length/Count property instead of Enumerable.Count method](ca1829.md) | LINQ method was used on a type that supports an equivalent, more efficient `Length` or `Count` property. | +> | [CA1830: Prefer strongly-typed Append and Insert method overloads on StringBuilder](ca1830.md) | and provide overloads for multiple types beyond . When possible, prefer the strongly-typed overloads over using ToString() and the string-based overload. | +> | [CA1831: Use AsSpan instead of Range-based indexers for string when appropriate](ca1831.md) | When using a range-indexer on a string and implicitly assigning the value to ReadOnlySpan<char> type, the method will be used instead of , which produces a copy of requested portion of the string. | +> | [CA1832: Use AsSpan or AsMemory instead of Range-based indexers for getting ReadOnlySpan or ReadOnlyMemory portion of an array](ca1832.md) | When using a range-indexer on an array and implicitly assigning the value to a or type, the method will be used instead of , which produces a copy of requested portion of the array. | +> | [CA1833: Use AsSpan or AsMemory instead of Range-based indexers for getting Span or Memory portion of an array](ca1833.md) | When using a range-indexer on an array and implicitly assigning the value to a or type, the method will be used instead of , which produces a copy of requested portion of the array. | > | [CA1834: Use StringBuilder.Append(char) for single character strings](ca1834.md) | has an `Append` overload that takes a `char` as its argument. Prefer calling the `char` overload for performance reasons. | > | [CA1835: Prefer the `Memory`-based overloads for `ReadAsync` and `WriteAsync`](ca1835.md) | `Stream` has a `ReadAsync` overload that takes a `Memory` as the first argument, and a `WriteAsync` overload that takes a `ReadOnlyMemory` as the first argument. Prefer calling the memory based overloads, which are more efficient. | -> | [CA1836: Prefer `IsEmpty` over `Count` when available](ca1836.md) | Prefer `IsEmpty` property that is more efficient than `Count`, `Length`, or to determine whether the object contains or not any items. | +> | [CA1836: Prefer `IsEmpty` over `Count` when available](ca1836.md) | Prefer `IsEmpty` property that is more efficient than `Count`, `Length`, or to determine whether the object contains or not any items. | > | [CA1837: Use `Environment.ProcessId` instead of `Process.GetCurrentProcess().Id`](ca1837.md) | `Environment.ProcessId` is simpler and faster than `Process.GetCurrentProcess().Id`. | > | [CA1838: Avoid `StringBuilder` parameters for P/Invokes](ca1838.md) | Marshalling of `StringBuilder` always creates a native buffer copy, resulting in multiple allocations for one marshalling operation. | > | [CA1839: Use Environment.ProcessPath instead of Process.GetCurrentProcess().MainModule.FileName](ca1839.md) | `Environment.ProcessPath` is simpler and faster than `Process.GetCurrentProcess().MainModule.FileName`. | @@ -155,24 +155,24 @@ The following table lists code quality analysis rules. > | [CA1850: Prefer static `HashData` method over `ComputeHash`](ca1850.md) | It's more efficient to use the static `HashData` method over creating and managing a `HashAlgorithm` instance to call `ComputeHash`. | > | [CA1851: Possible multiple enumerations of `IEnumerable` collection](ca1851.md) | Possible multiple enumerations of `IEnumerable` collection. Consider using an implementation that avoids multiple enumerations. | > | [CA1852: Seal internal types](ca1852.md) | A type that's not accessible outside its assembly and has no subtypes within its containing assembly is not sealed. | -> | [CA1853: Unnecessary call to `Dictionary.ContainsKey(key)`](ca1853.md) | There's no need to guard `Dictionary.Remove(key)` with `Dictionary.ContainsKey(key)`. already checks whether the key exists and doesn't throw if it doesn't exist. | +> | [CA1853: Unnecessary call to `Dictionary.ContainsKey(key)`](ca1853.md) | There's no need to guard `Dictionary.Remove(key)` with `Dictionary.ContainsKey(key)`. already checks whether the key exists and doesn't throw if it doesn't exist. | > | [CA1854: Prefer the `IDictionary.TryGetValue(TKey, out TValue)` method](ca1854.md) | Prefer `TryGetValue` over a Dictionary indexer access guarded by a `ContainsKey` check. `ContainsKey` and the indexer both look up the key, so using `TryGetValue` avoids the extra lookup. | -> | [CA1855: Use Span\.Clear() instead of Span\.Fill()](ca1855.md) | It's more efficient to call than to call to fill the elements of the span with a default value. | +> | [CA1855: Use Span\.Clear() instead of Span\.Fill()](ca1855.md) | It's more efficient to call than to call to fill the elements of the span with a default value. | > | [CA1856: Incorrect usage of ConstantExpected attribute](ca1856.md) | The attribute is not applied correctly on a parameter. | > | [CA1857: The parameter expects a constant for optimal performance](ca1857.md) | An invalid argument is passed to a parameter that's annotated with . | -> | [CA1858: Use StartsWith instead of IndexOf](ca1858.md) | It's more efficient to call than to call to check whether a string starts with a given prefix. | +> | [CA1858: Use StartsWith instead of IndexOf](ca1858.md) | It's more efficient to call than to call to check whether a string starts with a given prefix. | > | [CA1859: Use concrete types when possible for improved performance](ca1859.md) | Code uses interface types or abstract types, leading to unnecessary interface calls or virtual calls. | -> | [CA1860: Avoid using `Enumerable.Any()` extension method](ca1860.md) | It's more efficient and clearer to use `Length`, `Count`, or `IsEmpty` (if possible) than to call to determine whether a collection type has any elements. | +> | [CA1860: Avoid using `Enumerable.Any()` extension method](ca1860.md) | It's more efficient and clearer to use `Length`, `Count`, or `IsEmpty` (if possible) than to call to determine whether a collection type has any elements. | > | [CA1861: Avoid constant arrays as arguments](ca1861.md) | Constant arrays passed as arguments are not reused which implies a performance overhead. Consider extracting them to `static readonly` fields to improve performance. | > | [CA1862: Use the `StringComparison` method overloads to perform case-insensitive string comparisons](ca1862.md) | When code calls or to perform a case-insensitive string comparison, an unnecessary allocation is performed. | > | [CA1863: Use `CompositeFormat`](ca1863.md) | To reduce the formatting cost, cache and use a instance as the argument to `String.Format` or `StringBuilder.AppendFormat`. | -> | [CA1864: Prefer the `IDictionary.TryAdd(TKey, TValue)` method](ca1864.md) | Both and perform a lookup, which is redundant. It's is more efficient to call , which returns a `bool` indicating if the value was added or not. `TryAdd` doesn't overwrite the key's value if the key is already present. | +> | [CA1864: Prefer the `IDictionary.TryAdd(TKey, TValue)` method](ca1864.md) | Both and perform a lookup, which is redundant. It's is more efficient to call , which returns a `bool` indicating if the value was added or not. `TryAdd` doesn't overwrite the key's value if the key is already present. | > | [CA1865-CA1867: Use char overload](ca1865-ca1867.md) | The char overload is a better performing overload for a string with a single char. | -> | [CA1868: Unnecessary call to `Contains` for sets](ca1868.md) | Both and perform a lookup, which makes it redundant to call beforehand. It's more efficient to call or directly, which returns a Boolean value indicating whether the item was added or removed. | +> | [CA1868: Unnecessary call to `Contains` for sets](ca1868.md) | Both and perform a lookup, which makes it redundant to call beforehand. It's more efficient to call or directly, which returns a Boolean value indicating whether the item was added or removed. | > | [CA1869: Cache and reuse `JsonSerializerOptions` instances](ca1869.md) | Using a local instance of for serialization or deserialization can substantially degrade the performance of your application if your code executes multiple times, since System.Text.Json internally caches serialization-related metadata into the provided instance. | -> | [CA1870: Use a cached `SearchValues` instance](ca1870.md) | Using a cached instance is more efficient than passing values to `IndexOfAny` or `ContainsAny` directly. | +> | [CA1870: Use a cached `SearchValues` instance](ca1870.md) | Using a cached instance is more efficient than passing values to `IndexOfAny` or `ContainsAny` directly. | > | [CA1871: Do not pass a nullable struct to `ArgumentNullException.ThrowIfNull`](ca1871.md) | `ArgumentNullException.ThrowIfNull` accepts an `object`, so passing a nullable struct might cause the value to be boxed. | -> | [CA1872: Prefer `Convert.ToHexString` and `Convert.ToHexStringLower` over call chains based on `BitConverter.ToString`](ca1872.md) | Use or when encoding bytes to a hexadecimal string representation. These methods are more efficient and allocation-friendly than using in combination with to replace dashes and . | +> | [CA1872: Prefer `Convert.ToHexString` and `Convert.ToHexStringLower` over call chains based on `BitConverter.ToString`](ca1872.md) | Use or when encoding bytes to a hexadecimal string representation. These methods are more efficient and allocation-friendly than using in combination with to replace dashes and . | > | [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`. | @@ -184,15 +184,15 @@ The following table lists code quality analysis rules. > | [CA2009: Do not call ToImmutableCollection on an ImmutableCollection value](ca2009.md) | `ToImmutable` method was unnecessarily called on an immutable collection from namespace. | > | [CA2011: Do not assign property within its setter](ca2011.md) | A property was accidentally assigned a value within its own [set accessor](../../../csharp/programming-guide/classes-and-structs/using-properties.md#the-set-accessor). | > | [CA2012: Use ValueTasks correctly](ca2012.md) | ValueTasks returned from member invocations are intended to be directly awaited. Attempts to consume a ValueTask multiple times or to directly access one's result before it's known to be completed might result in an exception or corruption. Ignoring such a ValueTask is likely an indication of a functional bug and might degrade performance. | -> | [CA2013: Do not use ReferenceEquals with value types](ca2013.md) | When comparing values using , if objA and objB are value types, they are boxed before they are passed to the method. This means that even if both objA and objB represent the same instance of a value type, the method nevertheless returns false. | +> | [CA2013: Do not use ReferenceEquals with value types](ca2013.md) | When comparing values using , if objA and objB are value types, they are boxed before they are passed to the method. This means that even if both objA and objB represent the same instance of a value type, the method nevertheless returns false. | > | [CA2014: Do not use stackalloc in loops.](ca2014.md) | Stack space allocated by a stackalloc is only released at the end of the current method's invocation. Using it in a loop can result in unbounded stack growth and eventual stack overflow conditions. | -> | [CA2015: Do not define finalizers for types derived from MemoryManager<T>](ca2015.md) | Adding a finalizer to a type derived from might permit memory to be freed while it is still in use by a . | +> | [CA2015: Do not define finalizers for types derived from MemoryManager<T>](ca2015.md) | Adding a finalizer to a type derived from might permit memory to be freed while it is still in use by a . | > | [CA2016: Forward the CancellationToken parameter to methods that take one](ca2016.md) | Forward the `CancellationToken` parameter to methods that take one to ensure the operation cancellation notifications gets properly propagated, or pass in `CancellationToken.None` explicitly to indicate intentionally not propagating the token. | > | [CA2017: Parameter count mismatch](ca2017.md) | Number of parameters supplied in the logging message template do not match the number of named placeholders. | > | [CA2018: The `count` argument to `Buffer.BlockCopy` should specify the number of bytes to copy](ca2018.md) | When using `Buffer.BlockCopy`, the `count` argument specifies the number of bytes to copy. You should only use `Array.Length` for the `count` argument on arrays whose elements are exactly one byte in size. `byte`, `sbyte`, and `bool` arrays have elements that are one byte in size. | > | [CA2019: `ThreadStatic` fields should not use inline initialization](ca2019.md) | A field that's annotated with is initialized inline or explicitly in a `static` (`Shared` in Visual Basic) constructor. | > | [CA2020: Prevent behavioral change caused by built-in operators of IntPtr/UIntPtr](ca2020.md) | Some built-in operators added in .NET 7 behave differently than the user-defined operators in .NET 6 and earlier versions. Some operators that used to throw in unchecked context while overflowing don't throw anymore unless wrapped within checked context. Some operators that previously didn't throw in checked context now throw unless wrapped within unchecked context. | -> | [CA2021: Don't call Enumerable.Cast\ or Enumerable.OfType\ with incompatible types](ca2021.md) | A call to or specifies a type parameter that's incompatible with the type of the input collection. | +> | [CA2021: Don't call Enumerable.Cast\ or Enumerable.OfType\ with incompatible types](ca2021.md) | A call to or specifies a type parameter that's incompatible with the type of the input collection. | > | [CA2022: Avoid inexact read with Stream.Read](ca2022.md) | A call to `Stream.Read` might return fewer bytes than requested, resulting in unreliable code if the return value isn't checked. | > | [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. | @@ -213,9 +213,9 @@ The following table lists code quality analysis rules. > | [CA2215: Dispose methods should call base class dispose](ca2215.md) | If a type inherits from a disposable type, it must call the Dispose method of the base type from its own Dispose method. | > | [CA2216: Disposable types should declare finalizer](ca2216.md) | A type that implements System.IDisposable and has fields that suggest the use of unmanaged resources does not implement a finalizer, as described by Object.Finalize. | > | [CA2217: Do not mark enums with FlagsAttribute](ca2217.md) | An externally visible enumeration is marked by using FlagsAttribute, and it has one or more values that are not powers of two or a combination of the other defined values on the enumeration. | -> | [CA2218: Override GetHashCode on overriding Equals](ca2218.md) | A public type overrides but does not override . | +> | [CA2218: Override GetHashCode on overriding Equals](ca2218.md) | A public type overrides but does not override . | > | [CA2219: Do not raise exceptions in exception clauses](ca2219.md) | When an exception is raised in a finally or fault clause, the new exception hides the active exception. When an exception is raised in a filter clause, the runtime silently catches the exception. This makes the original error difficult to detect and debug. | -> | [CA2224: Override equals on overloading operator equals](ca2224.md) | A public type implements the equality operator but doesn't override . | +> | [CA2224: Override equals on overloading operator equals](ca2224.md) | A public type implements the equality operator but doesn't override . | > | [CA2225: Operator overloads have named alternates](ca2225.md) | An operator overload was detected, and the expected named alternative method was not found. The named alternative member provides access to the same functionality as the operator and is provided for developers who program in languages that do not support overloaded operators. | > | [CA2226: Operators should have symmetrical overloads](ca2226.md) | A type implements the equality or inequality operator and does not implement the opposite operator. | > | [CA2227: Collection properties should be read only](ca2227.md) | A writable collection property allows a user to replace the collection with a different collection. A read-only property stops the collection from being replaced but still allows the individual members to be set. | diff --git a/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md b/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md index f090189a1c2ef..b891ce58ffba8 100644 --- a/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md @@ -34,18 +34,18 @@ Performance rules support high-performance libraries and applications. | [CA1822: Mark members as static](ca1822.md) | Members that do not access instance data or call instance methods can be marked as static (Shared in Visual Basic). After you mark the methods as static, the compiler will emit nonvirtual call sites to these members. This can give you a measurable performance gain for performance-sensitive code. | | [CA1823: Avoid unused private fields](ca1823.md) | Private fields were detected that do not appear to be accessed in the assembly. | | [CA1824: Mark assemblies with NeutralResourcesLanguageAttribute](ca1824.md) | The NeutralResourcesLanguage attribute informs the Resource Manager of the language that was used to display the resources of a neutral culture for an assembly. This improves lookup performance for the first resource that you load and can reduce your working set. | -| [CA1825: Avoid zero-length array allocations](ca1825.md) | Initializing a zero-length array leads to unnecessary memory allocation. Instead, use the statically allocated empty array instance by calling . The memory allocation is shared across all invocations of this method. | +| [CA1825: Avoid zero-length array allocations](ca1825.md) | Initializing a zero-length array leads to unnecessary memory allocation. Instead, use the statically allocated empty array instance by calling . The memory allocation is shared across all invocations of this method. | | [CA1826: Use property instead of Linq Enumerable method](ca1826.md) | LINQ method was used on a type that supports an equivalent, more efficient property. | -| [CA1827: Do not use Count/LongCount when Any can be used](ca1827.md) | or method was used where method would be more efficient. | -| [CA1828: Do not use CountAsync/LongCountAsync when AnyAsync can be used](ca1828.md) | or method was used where method would be more efficient. | -| [CA1829: Use Length/Count property instead of Enumerable.Count method](ca1829.md) | LINQ method was used on a type that supports an equivalent, more efficient `Length` or `Count` property. | -| [CA1830: Prefer strongly-typed Append and Insert method overloads on StringBuilder](ca1830.md) | and provide overloads for multiple types beyond System.String. When possible, prefer the strongly-typed overloads over using ToString() and the string-based overload. | -| [CA1831: Use AsSpan instead of Range-based indexers for string when appropriate](ca1831.md) | When using a range-indexer on a string and implicitly assigning the value to a ReadOnlySpan<char> type, the method will be used instead of , which produces a copy of requested portion of the string. | -| [CA1832: Use AsSpan or AsMemory instead of Range-based indexers for getting ReadOnlySpan or ReadOnlyMemory portion of an array](ca1832.md) | When using a range-indexer on an array and implicitly assigning the value to a or type, the method will be used instead of , which produces a copy of requested portion of the array. | -| [CA1833: Use AsSpan or AsMemory instead of Range-based indexers for getting Span or Memory portion of an array](ca1833.md) | When using a range-indexer on an array and implicitly assigning the value to a or type, the method will be used instead of , which produces a copy of requested portion of the array. | +| [CA1827: Do not use Count/LongCount when Any can be used](ca1827.md) | or method was used where method would be more efficient. | +| [CA1828: Do not use CountAsync/LongCountAsync when AnyAsync can be used](ca1828.md) | or method was used where method would be more efficient. | +| [CA1829: Use Length/Count property instead of Enumerable.Count method](ca1829.md) | LINQ method was used on a type that supports an equivalent, more efficient `Length` or `Count` property. | +| [CA1830: Prefer strongly-typed Append and Insert method overloads on StringBuilder](ca1830.md) | and provide overloads for multiple types beyond System.String. When possible, prefer the strongly-typed overloads over using ToString() and the string-based overload. | +| [CA1831: Use AsSpan instead of Range-based indexers for string when appropriate](ca1831.md) | When using a range-indexer on a string and implicitly assigning the value to a ReadOnlySpan<char> type, the method will be used instead of , which produces a copy of requested portion of the string. | +| [CA1832: Use AsSpan or AsMemory instead of Range-based indexers for getting ReadOnlySpan or ReadOnlyMemory portion of an array](ca1832.md) | When using a range-indexer on an array and implicitly assigning the value to a or type, the method will be used instead of , which produces a copy of requested portion of the array. | +| [CA1833: Use AsSpan or AsMemory instead of Range-based indexers for getting Span or Memory portion of an array](ca1833.md) | When using a range-indexer on an array and implicitly assigning the value to a or type, the method will be used instead of , which produces a copy of requested portion of the array. | | [CA1834: Use StringBuilder.Append(char) for single character strings](ca1834.md) | has an `Append` overload that takes a `char` as its argument. Prefer calling the `char` overload to improve performance. | | [CA1835: Prefer the 'Memory'-based overloads for 'ReadAsync' and 'WriteAsync'](ca1835.md) | 'Stream' has a 'ReadAsync' overload that takes a 'Memory<Byte>' as the first argument, and a 'WriteAsync' overload that takes a 'ReadOnlyMemory<Byte>' as the first argument. Prefer calling the memory based overloads, which are more efficient. | -| [CA1836: Prefer `IsEmpty` over `Count` when available](ca1836.md) | Prefer `IsEmpty` property that is more efficient than `Count`, `Length`, or to determine whether the object contains or not any items. | +| [CA1836: Prefer `IsEmpty` over `Count` when available](ca1836.md) | Prefer `IsEmpty` property that is more efficient than `Count`, `Length`, or to determine whether the object contains or not any items. | | [CA1837: Use `Environment.ProcessId` instead of `Process.GetCurrentProcess().Id`](ca1837.md) | `Environment.ProcessId` is simpler and faster than `Process.GetCurrentProcess().Id`. | | [CA1838: Avoid `StringBuilder` parameters for P/Invokes](ca1838.md) | Marshalling of `StringBuilder` always creates a native buffer copy, resulting in multiple allocations for one marshalling operation. | | [CA1839: Use Environment.ProcessPath instead of Process.GetCurrentProcess().MainModule.FileName](ca1839.md) | `Environment.ProcessPath` is simpler and faster than `Process.GetCurrentProcess().MainModule.FileName`. | @@ -62,25 +62,25 @@ Performance rules support high-performance libraries and applications. | [CA1850: Prefer static `HashData` method over `ComputeHash`](ca1850.md) | It's more efficient to use the static `HashData` method over creating and managing a `HashAlgorithm` instance to call `ComputeHash`. | | [CA1851: Possible multiple enumerations of `IEnumerable` collection](ca1851.md) | Possible multiple enumerations of `IEnumerable` collection. Consider using an implementation that avoids multiple enumerations. | | [CA1852: Seal internal types](ca1852.md) | A type that's not accessible outside its assembly and has no subtypes within its containing assembly is not sealed. | -| [CA1853: Unnecessary call to 'Dictionary.ContainsKey(key)'](ca1853.md) | There's no need to guard `Dictionary.Remove(key)` with `Dictionary.ContainsKey(key)`. already checks whether the key exists and doesn't throw if it doesn't exist. | +| [CA1853: Unnecessary call to 'Dictionary.ContainsKey(key)'](ca1853.md) | There's no need to guard `Dictionary.Remove(key)` with `Dictionary.ContainsKey(key)`. already checks whether the key exists and doesn't throw if it doesn't exist. | | [CA1854: Prefer the 'IDictionary.TryGetValue(TKey, out TValue)' method](ca1854.md) | Prefer 'TryGetValue' over a Dictionary indexer access guarded by a 'ContainsKey' check. 'ContainsKey' and the indexer both look up the key, so using 'TryGetValue' avoids the extra lookup. | -| [CA1855: Use Span\.Clear() instead of Span\.Fill()](ca1855.md) | It's more efficient to call than to call to fill the elements of the span with a default value. | +| [CA1855: Use Span\.Clear() instead of Span\.Fill()](ca1855.md) | It's more efficient to call than to call to fill the elements of the span with a default value. | | [CA1856: Incorrect usage of ConstantExpected attribute](ca1856.md) | The attribute is not applied correctly on a parameter. | | [CA1857: The parameter expects a constant for optimal performance](ca1857.md) | An invalid argument is passed to a parameter that's annotated with . | -| [CA1858: Use StartsWith instead of IndexOf](ca1858.md) | It's more efficient to call than to call to check whether a string starts with a given prefix. | +| [CA1858: Use StartsWith instead of IndexOf](ca1858.md) | It's more efficient to call than to call to check whether a string starts with a given prefix. | | [CA1859: Use concrete types when possible for improved performance](ca1859.md) | Code uses interface types or abstract types, leading to unnecessary interface calls or virtual calls. | -| [CA1860: Avoid using 'Enumerable.Any()' extension method](ca1860.md) | It's more efficient and clearer to use `Length`, `Count`, or `IsEmpty` (if possible) than to call to determine whether a collection type has any elements. | +| [CA1860: Avoid using 'Enumerable.Any()' extension method](ca1860.md) | It's more efficient and clearer to use `Length`, `Count`, or `IsEmpty` (if possible) than to call to determine whether a collection type has any elements. | | [CA1861: Avoid constant arrays as arguments](ca1861.md) | Constant arrays passed as arguments are not reused which implies a performance overhead. Consider extracting them to 'static readonly' fields to improve performance. | | [CA1862: Use the 'StringComparison' method overloads to perform case-insensitive string comparisons](ca1862.md) | When code calls or to perform a case-insensitive string comparison, an unnecessary allocation is performed. | | [CA1863: Use 'CompositeFormat'](ca1863.md) | To reduce the formatting cost, cache and use a instance as the argument to `String.Format` or `StringBuilder.AppendFormat`. | -| [CA1864: Prefer the 'IDictionary.TryAdd(TKey, TValue)' method](ca1864.md) | Both and perform a lookup, which is redundant. It's is more efficient to call , which returns a `bool` indicating if the value was added or not. `TryAdd` doesn't overwrite the key's value if the key is already present. | +| [CA1864: Prefer the 'IDictionary.TryAdd(TKey, TValue)' method](ca1864.md) | Both and perform a lookup, which is redundant. It's is more efficient to call , which returns a `bool` indicating if the value was added or not. `TryAdd` doesn't overwrite the key's value if the key is already present. | | [CA1865-CA1867: Use char overload](ca1865-ca1867.md) | The char overload is a better performing overload for a string with a single char. | -| [CA1868: Unnecessary call to 'Contains' for sets](ca1868.md) | Both and perform a lookup, which makes it redundant to call beforehand. It's more efficient to call or directly, which returns a Boolean value indicating whether the item was added or removed. | +| [CA1868: Unnecessary call to 'Contains' for sets](ca1868.md) | Both and perform a lookup, which makes it redundant to call beforehand. It's more efficient to call or directly, which returns a Boolean value indicating whether the item was added or removed. | | [CA1869: Cache and reuse 'JsonSerializerOptions' instances](ca1869.md) | Using a local instance of for serialization or deserialization can substantially degrade the performance of your application if your code executes multiple times, since System.Text.Json internally caches serialization-related metadata into the provided instance. | -| [CA1870: Use a cached 'SearchValues' instance](ca1870.md) | Using a cached instance is more efficient than passing values to 'IndexOfAny' or 'ContainsAny' directly. | +| [CA1870: Use a cached 'SearchValues' instance](ca1870.md) | Using a cached instance is more efficient than passing values to 'IndexOfAny' or 'ContainsAny' directly. | | [CA1871: Do not pass a nullable struct to 'ArgumentNullException.ThrowIfNull'](ca1871.md) | 'ArgumentNullException.ThrowIfNull' accepts an 'object', so passing a nullable struct might cause the value to be boxed. | -| [CA1872: Prefer 'Convert.ToHexString' and 'Convert.ToHexStringLower' over call chains based on 'BitConverter.ToString'](ca1872.md) | Use or when encoding bytes to a hexadecimal string representation. These methods are more efficient and allocation-friendly than using in combination with to replace dashes and . | -| [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. | +| [CA1872: Prefer 'Convert.ToHexString' and 'Convert.ToHexStringLower' over call chains based on 'BitConverter.ToString'](ca1872.md) | Use or when encoding bytes to a hexadecimal string representation. These methods are more efficient and allocation-friendly than using in combination with to replace dashes and . | +| [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. | +| [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 41120f7ae0107..fcf91febdf241 100644 --- a/docs/fundamentals/code-analysis/quality-rules/reliability-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/reliability-warnings.md @@ -22,17 +22,17 @@ Reliability rules support library and application reliability, such as correct m | [CA2009: Do not call ToImmutableCollection on an ImmutableCollection value](ca2009.md) | `ToImmutable` method was unnecessarily called on an immutable collection from namespace. | | [CA2011: Do not assign property within its setter](ca2011.md) | A property was accidentally assigned a value within its own [set accessor](../../../csharp/programming-guide/classes-and-structs/using-properties.md#the-set-accessor). | | [CA2012: Use ValueTasks correctly](ca2012.md) | ValueTasks returned from member invocations are intended to be directly awaited. Attempts to consume a ValueTask multiple times or to directly access one's result before it's known to be completed may result in an exception or corruption. Ignoring such a ValueTask is likely an indication of a functional bug and may degrade performance. | -| [CA2013: Do not use ReferenceEquals with value types](ca2013.md) | When comparing values using , if objA and objB are value types, they are boxed before they are passed to the method. This means that even if both objA and objB represent the same instance of a value type, the method nevertheless returns false. | +| [CA2013: Do not use ReferenceEquals with value types](ca2013.md) | When comparing values using , if objA and objB are value types, they are boxed before they are passed to the method. This means that even if both objA and objB represent the same instance of a value type, the method nevertheless returns false. | | [CA2014: Do not use stackalloc in loops.](ca2014.md) | Stack space allocated by a stackalloc is only released at the end of the current method's invocation. Using it in a loop can result in unbounded stack growth and eventual stack overflow conditions. | -| [CA2015: Do not define finalizers for types derived from MemoryManager<T>](ca2015.md) | Adding a finalizer to a type derived from may permit memory to be freed while it is still in use by a . | +| [CA2015: Do not define finalizers for types derived from MemoryManager<T>](ca2015.md) | Adding a finalizer to a type derived from may permit memory to be freed while it is still in use by a . | | [CA2016: Forward the CancellationToken parameter to methods that take one](ca2016.md) | Forward the `CancellationToken` parameter to methods that take one to ensure the operation cancellation notifications gets properly propagated, or pass in `CancellationToken.None` explicitly to indicate intentionally not propagating the token. | | [CA2017: Parameter count mismatch](ca2017.md) | Number of parameters supplied in the logging message template do not match the number of named placeholders. | | [CA2018: The `count` argument to `Buffer.BlockCopy` should specify the number of bytes to copy](ca2018.md) | When using `Buffer.BlockCopy`, the `count` argument specifies the number of bytes to copy. You should only use `Array.Length` for the `count` argument on arrays whose elements are exactly one byte in size. `byte`, `sbyte`, and `bool` arrays have elements that are one byte in size. | | [CA2019: `ThreadStatic` fields should not use inline initialization](ca2019.md) | A field that's annotated with is initialized inline or explicitly in a `static` (`Shared` in Visual Basic) constructor. | | [CA2020: Prevent behavioral change caused by built-in operators of IntPtr/UIntPtr](ca2020.md) | Some built-in operators added in .NET 7 behave differently than the user-defined operators in .NET 6 and earlier versions. Some operators that used to throw in unchecked context while overflowing don't throw anymore unless wrapped within checked context. Some operators that previously didn't throw in checked context now throw unless wrapped within unchecked context. | -| [CA2021: Don't call Enumerable.Cast\ or Enumerable.OfType\ with incompatible types](ca2021.md) | A call to or specifies a type parameter that's incompatible with the type of the input collection. | +| [CA2021: Don't call Enumerable.Cast\ or Enumerable.OfType\ with incompatible types](ca2021.md) | A call to or specifies a type parameter that's incompatible with the type of the input collection. | | [CA2022: Avoid inexact read with Stream.Read](ca2022.md) | A call to `Stream.Read` might return fewer bytes than requested, resulting in unreliable code if the return value isn't checked. | | [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`. | +| [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/usage-warnings.md b/docs/fundamentals/code-analysis/quality-rules/usage-warnings.md index 1c425e8bb6525..39ab1b3132689 100644 --- a/docs/fundamentals/code-analysis/quality-rules/usage-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/usage-warnings.md @@ -29,9 +29,9 @@ Usage rules support proper usage of .NET. |[CA2215: Dispose methods should call base class dispose](ca2215.md)|If a type inherits from a disposable type, it must call the `Dispose` method of the base type from its own `Dispose` method.| |[CA2216: Disposable types should declare finalizer](ca2216.md)|A type that implements , and has fields that suggest the use of unmanaged resources, does not implement a finalizer as described by `Object.Finalize`.| |[CA2217: Do not mark enums with FlagsAttribute](ca2217.md)|An externally visible enumeration is marked with `FlagsAttribute`, and it has one or more values that are not powers of two or a combination of the other defined values on the enumeration.| -|[CA2218: Override GetHashCode on overriding Equals](ca2218.md)|A public type overrides but does not override .| +|[CA2218: Override GetHashCode on overriding Equals](ca2218.md)|A public type overrides but does not override .| |[CA2219: Do not raise exceptions in exception clauses](ca2219.md)|When an exception is raised in a finally or fault clause, the new exception hides the active exception. When an exception is raised in a filter clause, the runtime silently catches the exception. This makes the original error hard to detect and debug.| -|[CA2224: Override equals on overloading operator equals](ca2224.md)|A public type implements the equality operator but doesn't override .| +|[CA2224: Override equals on overloading operator equals](ca2224.md)|A public type implements the equality operator but doesn't override .| |[CA2225: Operator overloads have named alternates](ca2225.md)|An operator overload was detected, and the expected named alternative method was not found. The named alternative member provides access to the same functionality as the operator, and is provided for developers who program in languages that do not support overloaded operators.| |[CA2226: Operators should have symmetrical overloads](ca2226.md)|A type implements the equality or inequality operator, and does not implement the opposite operator.| |[CA2227: Collection properties should be read only](ca2227.md)|A writable collection property allows a user to replace the collection with a different collection. A read-only property stops the collection from being replaced but still allows the individual members to be set.| @@ -40,7 +40,7 @@ Usage rules support proper usage of .NET. |[CA2234: Pass System.Uri objects instead of strings](ca2234.md)|A call is made to a method that has a string parameter whose name contains "uri", "URI", "urn", "URN", "url", or "URL". The declaring type of the method contains a corresponding method overload that has a parameter.| |[CA2235: Mark all non-serializable fields](ca2235.md)|An instance field of a type that is not serializable is declared in a type that is serializable.| |[CA2237: Mark ISerializable types with SerializableAttribute](ca2237.md)|To be recognized by the common language runtime as serializable, types must be marked with the SerializableAttribute attribute even if the type uses a custom serialization routine through implementation of the `ISerializable` interface.| -|[CA2241: Provide correct arguments to formatting methods](ca2241.md)|The format argument passed to does not contain a format item that corresponds to each object argument, or vice versa.| +|[CA2241: Provide correct arguments to formatting methods](ca2241.md)|The format argument passed to does not contain a format item that corresponds to each object argument, or vice versa.| |[CA2242: Test for NaN correctly](ca2242.md)|This expression tests a value against `Single.Nan` or `Double.Nan`. Use `Single.IsNan(Single)` or `Double.IsNan(Double)` to test the value.| |[CA2243: Attribute string literals should parse correctly](ca2243.md)|An attribute's string literal parameter does not parse correctly for a URL, a GUID, or a version.| |[CA2244: Do not duplicate indexed element initializations](ca2244.md)|An object initializer has more than one indexed element initializer with the same constant index. All but the last initializer are redundant.| diff --git a/docs/fundamentals/code-analysis/style-rules/ide0070.md b/docs/fundamentals/code-analysis/style-rules/ide0070.md index 5c8e830448ca0..3ede93b30cd1c 100644 --- a/docs/fundamentals/code-analysis/style-rules/ide0070.md +++ b/docs/fundamentals/code-analysis/style-rules/ide0070.md @@ -24,7 +24,7 @@ dev_langs: ## Overview -This rule recommends the use of the method to compute a hash code instead of using custom hash code computation logic. +This rule recommends the use of the method to compute a hash code instead of using custom hash code computation logic. ## Options diff --git a/docs/fundamentals/code-analysis/style-rules/ide0120.md b/docs/fundamentals/code-analysis/style-rules/ide0120.md index 09542756a115b..4c9386b8f0bbb 100644 --- a/docs/fundamentals/code-analysis/style-rules/ide0120.md +++ b/docs/fundamentals/code-analysis/style-rules/ide0120.md @@ -21,18 +21,18 @@ dev_langs: ## Overview -This rule flags overly complex LINQ expressions, specifically expressions that call followed by one of the following methods: - -- -- -- -- -- -- -- -- - -Such expressions can be simplified by removing the call to and instead calling an overload of `Any()`, `Count()`, `First()`, `FirstOrDefault()`, `Last()`, `LastOrDefault()`, `Single`, or `SingleOrDefault()` that accepts a predicate function to filter the elements. +This rule flags overly complex LINQ expressions, specifically expressions that call followed by one of the following methods: + +- +- +- +- +- +- +- +- + +Such expressions can be simplified by removing the call to and instead calling an overload of `Any()`, `Count()`, `First()`, `FirstOrDefault()`, `Last()`, `LastOrDefault()`, `Single`, or `SingleOrDefault()` that accepts a predicate function to filter the elements. ## Options diff --git a/docs/fundamentals/code-analysis/style-rules/ide0304.md b/docs/fundamentals/code-analysis/style-rules/ide0304.md index 62429b34d1215..e0f4b47ca2545 100644 --- a/docs/fundamentals/code-analysis/style-rules/ide0304.md +++ b/docs/fundamentals/code-analysis/style-rules/ide0304.md @@ -22,7 +22,7 @@ dev_langs: ## Overview -This rule flags places where a `CreateBuilder()` or similar method is called to create a builder type that adds elements and finally constructs a collection type that has the attribute (for example, by calling ). Instead, a [collection expression](../../../csharp/language-reference/operators/collection-expressions.md) (`[...]`) could be used to initialize the collection. +This rule flags places where a `CreateBuilder()` or similar method is called to create a builder type that adds elements and finally constructs a collection type that has the attribute (for example, by calling ). Instead, a [collection expression](../../../csharp/language-reference/operators/collection-expressions.md) (`[...]`) could be used to initialize the collection. > [!NOTE] > This rule requires more recent versions of the immutable APIs (for example, ), which opt in to the collection-expression pattern. diff --git a/docs/fundamentals/code-analysis/style-rules/includes/dotnet-style-prefer-collection-expression.md b/docs/fundamentals/code-analysis/style-rules/includes/dotnet-style-prefer-collection-expression.md index 177fef32f4d61..8287558e91a13 100644 --- a/docs/fundamentals/code-analysis/style-rules/includes/dotnet-style-prefer-collection-expression.md +++ b/docs/fundamentals/code-analysis/style-rules/includes/dotnet-style-prefer-collection-expression.md @@ -8,7 +8,7 @@ ms.topic: include |--------------------------|-------------------------------------------|---------------------------------------| | **Option name** | dotnet_style_prefer_collection_expression | | | **Option values** | `true` | `when_types_exactly_match` | Prefer to use collection expressions only when types match exactly, for example, `List list = new List() { 1, 2 };`. | -| | `when_types_loosely_match`\* | Prefer to use collection expressions even when types match loosely, for example, `IEnumerable list = new List() { 1, 2 };`. The targeted type must match the type on the right-hand side or be one of the following types: , , , , . | +| | `when_types_loosely_match`\* | Prefer to use collection expressions even when types match loosely, for example, `IEnumerable list = new List() { 1, 2 };`. The targeted type must match the type on the right-hand side or be one of the following types: , , , , . | | | `false` | `never` | Disables the rule. | | **Default option value** | `when_types_loosely_match`\* | | diff --git a/docs/fundamentals/code-analysis/style-rules/index.md b/docs/fundamentals/code-analysis/style-rules/index.md index 28cb8fc1ca893..e9837df7a16f6 100644 --- a/docs/fundamentals/code-analysis/style-rules/index.md +++ b/docs/fundamentals/code-analysis/style-rules/index.md @@ -95,7 +95,7 @@ The following table list all the code-style rules by ID and [options](../code-st > | [IDE0064](ide0064.md) | Make struct fields writable | | > | [IDE0065](ide0065.md) | `using` directive placement | [csharp_using_directive_placement](ide0065.md#csharp_using_directive_placement) | > | [IDE0066](ide0066.md) | Use switch expression | [csharp_style_prefer_switch_expression](ide0066.md#csharp_style_prefer_switch_expression) | -> | [IDE0070](ide0070.md) | Use | | +> | [IDE0070](ide0070.md) | Use | | > | [IDE0071](ide0071.md) | Simplify interpolation | [dotnet_style_prefer_simplified_interpolation](ide0071.md#dotnet_style_prefer_simplified_interpolation) | > | [IDE0072](ide0072.md) | Add missing cases to switch expression | | > | [IDE0073](ide0073.md) | Use file header | [file_header_template](ide0073.md#file_header_template) | diff --git a/docs/fundamentals/diagnostics/runtime-loader-binder-events.md b/docs/fundamentals/diagnostics/runtime-loader-binder-events.md index 2b1a6701973c9..1ed75de2605b9 100644 --- a/docs/fundamentals/diagnostics/runtime-loader-binder-events.md +++ b/docs/fundamentals/diagnostics/runtime-loader-binder-events.md @@ -289,7 +289,7 @@ The events described in this article collect information relating to loading and |Event|Event ID|Description| |-----------|--------------|-----------------| -|`AssemblyLoadFromResolveHandlerInvoked`|295|An handler has been invoked.| +|`AssemblyLoadFromResolveHandlerInvoked`|295|An handler has been invoked.| |Field name|Data type|Description| |----------------|---------------|-----------------| diff --git a/docs/fundamentals/networking/http/httpclient.md b/docs/fundamentals/networking/http/httpclient.md index 4bdf84ecf4824..710c9a2f53a0c 100644 --- a/docs/fundamentals/networking/http/httpclient.md +++ b/docs/fundamentals/networking/http/httpclient.md @@ -46,20 +46,20 @@ To make an HTTP request, you call any of the following API methods: | HTTP method | API | |------------------------------|-------------------------------------------------------------------------------------| -| `GET` | | -| `GET` | | -| `GET` | | -| `GET` | | -| `POST` | | -| `PUT` | | -| `PATCH` | | -| `DELETE` | | -| †`USER SPECIFIED` | | +| `GET` | | +| `GET` | | +| `GET` | | +| `GET` | | +| `POST` | | +| `PUT` | | +| `PATCH` | | +| `DELETE` | | +| †`USER SPECIFIED` | | > †A `USER SPECIFIED` request indicates that the `SendAsync` method accepts any valid object. > [!WARNING] -> Making HTTP requests is considered network I/O-bound work. A synchronous method exists, but the recommendation is to use the asynchronous APIs instead, unless you have good reason not to. +> Making HTTP requests is considered network I/O-bound work. A synchronous method exists, but the recommendation is to use the asynchronous APIs instead, unless you have good reason not to. > [!NOTE] > While targeting Android devices (such as with .NET MAUI development), you must add the `android:usesCleartextTraffic="true"` definition to the `` section in the _AndroidManifest.xml_ file. This setting enables clear-text traffic, such as HTTP requests, which is otherwise disabled by default due to Android security policies. Consider the following example XML settings: @@ -83,7 +83,7 @@ The type is used to represent an HTTP entity - : Provides HTTP content based on JSON. - : Provides a collection of HttpContent objects that get serialized by using the `"multipart/*"` MIME type specification. - : Provides a container for content encoded by using the `"multipart/form-data"` MIME type. -- : Provides HTTP content based on an value. +- : Provides HTTP content based on an value. - : Provides HTTP content based on a stream. - : Provides HTTP content based on a string. @@ -91,7 +91,7 @@ The `HttpContent` class is also used to represent the response body of the object, use the method: +A `GET` request shouldn't send a body. This request is used (as the method name indicates) to retrieve (or get) data from a resource. To make an HTTP `GET` request given an `HttpClient` instance and a object, use the method: :::code source="../snippets/httpclient/Program.Get.cs" id="get"::: @@ -142,7 +142,7 @@ The C# `Todo` object is defined as follows: :::code source="../snippets/httpclient/Todo.cs"::: -It's a `record class` type, with optional `Id`, `Title`, `Completed`, and `UserId` properties. For more information on the `record` type, see [Introduction to record types in C#](../../../csharp/fundamentals/types/records.md). To automatically deserialize `GET` requests into a strongly typed C# object, use the extension method that's part of the [📦 System.Net.Http.Json](https://www.nuget.org/packages/System.Net.Http.Json) NuGet package. +It's a `record class` type, with optional `Id`, `Title`, `Completed`, and `UserId` properties. For more information on the `record` type, see [Introduction to record types in C#](../../../csharp/fundamentals/types/records.md). To automatically deserialize `GET` requests into a strongly typed C# object, use the extension method that's part of the [📦 System.Net.Http.Json](https://www.nuget.org/packages/System.Net.Http.Json) NuGet package. :::code source="../snippets/httpclient/Program.GetFromJson.cs" id="getfromjson"::: @@ -156,7 +156,7 @@ The code completes the following tasks: ### Use an HTTP POST request -A `POST` request sends data to the server for processing. The `Content-Type` header of the request signifies what [MIME type](xref:System.Net.Mime.ContentType) the body is sending. To make an HTTP `POST` request given an `HttpClient` instance and a object, use the method: +A `POST` request sends data to the server for processing. The `Content-Type` header of the request signifies what [MIME type](xref:System.Net.Mime.ContentType) the body is sending. To make an HTTP `POST` request given an `HttpClient` instance and a object, use the method: :::code source="../snippets/httpclient/Program.Post.cs" id="post"::: @@ -169,7 +169,7 @@ The code completes the following tasks: #### Create the HTTP POST request as JSON -To automatically serialize `POST` request arguments and deserialize responses into strongly typed C# objects, use the and the extension methods, respectively, that are part of the [System.Net.Http.Json](https://www.nuget.org/packages/System.Net.Http.Json) NuGet package. +To automatically serialize `POST` request arguments and deserialize responses into strongly typed C# objects, use the and the extension methods, respectively, that are part of the [System.Net.Http.Json](https://www.nuget.org/packages/System.Net.Http.Json) NuGet package. :::code source="../snippets/httpclient/Program.PostAsJson.cs" id="postasjson"::: @@ -181,7 +181,7 @@ The code completes the following tasks: ### Use an HTTP PUT request -The `PUT` request method either replaces an existing resource or creates a new one by using the request body payload. To make an HTTP `PUT` request given an `HttpClient` instance and a object, use the method: +The `PUT` request method either replaces an existing resource or creates a new one by using the request body payload. To make an HTTP `PUT` request given an `HttpClient` instance and a object, use the method: :::code source="../snippets/httpclient/Program.Put.cs" id="put"::: @@ -193,8 +193,8 @@ The code completes the following tasks: #### Create the HTTP PUT request as JSON -To automatically serialize `PUT` request arguments and deserialize responses into strongly typed C# objects, use the and the - extension methods, respectively, that are part of the [System.Net.Http.Json](https://www.nuget.org/packages/System.Net.Http.Json) NuGet package. +To automatically serialize `PUT` request arguments and deserialize responses into strongly typed C# objects, use the and the + extension methods, respectively, that are part of the [System.Net.Http.Json](https://www.nuget.org/packages/System.Net.Http.Json) NuGet package. :::code source="../snippets/httpclient/Program.PutAsJson.cs" id="putasjson"::: @@ -206,7 +206,7 @@ The code completes the following tasks: ### Use an HTTP PATCH request -The `PATCH` request is a partial update to an existing resource. This request doesn't create a new resource and it isn't intended to replace an existing resource. Instead, this method only partially updates a resource. To make an HTTP `PATCH` request given an `HttpClient` instance and a object, use the method: +The `PATCH` request is a partial update to an existing resource. This request doesn't create a new resource and it isn't intended to replace an existing resource. Instead, this method only partially updates a resource. To make an HTTP `PATCH` request given an `HttpClient` instance and a object, use the method: :::code source="../snippets/httpclient/Program.Patch.cs" id="patch"::: @@ -220,7 +220,7 @@ No extension methods exist for `PATCH` requests in the `System.Net.Http.Json` Nu ### Use an HTTP DELETE request -A `DELETE` request removes an existing resource and the request is _idempotent_, but not _safe_. Multiple `DELETE` requests to the same resources yield the same result, but the request affects the state of the resource. To make an HTTP `DELETE` request given an `HttpClient` instance and a object, use the method: +A `DELETE` request removes an existing resource and the request is _idempotent_, but not _safe_. Multiple `DELETE` requests to the same resources yield the same result, but the request affects the state of the resource. To make an HTTP `DELETE` request given an `HttpClient` instance and a object, use the method: :::code source="../snippets/httpclient/Program.Delete.cs" id="delete"::: @@ -234,7 +234,7 @@ The code completes the following tasks: ### Explore the HTTP HEAD request -The `HEAD` request is similar to a `GET` request. Instead of returning the resource, this request returns only the headers associated with the resource. A response to the `HEAD` request doesn't return a body. To make an HTTP `HEAD` request given an `HttpClient` instance and a object, use the method with the type set to `HttpMethod.Head`: +The `HEAD` request is similar to a `GET` request. Instead of returning the resource, this request returns only the headers associated with the resource. A response to the `HEAD` request doesn't return a body. To make an HTTP `HEAD` request given an `HttpClient` instance and a object, use the method with the type set to `HttpMethod.Head`: :::code source="../snippets/httpclient/Program.Head.cs" id="head"::: @@ -246,7 +246,7 @@ The code completes the following tasks: ### Explore the HTTP OPTIONS request -The `OPTIONS` request is used to identify which HTTP methods a server or endpoint supports. To make an HTTP `OPTIONS` request given an `HttpClient` instance and a object, use the method with the type set to `HttpMethod.Options`: +The `OPTIONS` request is used to identify which HTTP methods a server or endpoint supports. To make an HTTP `OPTIONS` request given an `HttpClient` instance and a object, use the method with the type set to `HttpMethod.Options`: :::code source="../snippets/httpclient/Program.Options.cs" id="options"::: @@ -321,22 +321,22 @@ Likewise, when you make an HTTP request, if the server doesn't respond before th In the code, when the inner exception is an type, then the time-out occurred and the cancellation token doesn't cancel the request. -To evaluate the HTTP status code when you catch the object, you can evaluate the property: +To evaluate the HTTP status code when you catch the object, you can evaluate the property: :::code source="../snippets/httpclient/Program.CancellationStatusCode.cs" id="statuscode"::: -In the code, the method is called to throw an exception if the response isn't successful. The property is then evaluated to determine if the response was a `404` (HTTP status code 404). There are several helper methods on the `HttpClient` object that implicitly call the `EnsureSuccessStatusCode` method on your behalf. +In the code, the method is called to throw an exception if the response isn't successful. The property is then evaluated to determine if the response was a `404` (HTTP status code 404). There are several helper methods on the `HttpClient` object that implicitly call the `EnsureSuccessStatusCode` method on your behalf. For HTTP error handing, consider the following APIs: -- method -- method -- method +- method +- method +- method > [!TIP] > All `HttpClient` methods used to make HTTP requests that don't return an `HttpResponseMessage` type implicitly call the `EnsureSuccessStatusCode` method on your behalf. -When you call these methods, you can handle the `HttpRequestException` object and evaluate the property to determine the HTTP status code of the response: +When you call these methods, you can handle the `HttpRequestException` object and evaluate the property to determine the HTTP status code of the response: :::code source="../snippets/httpclient/Program.CancellationStream.cs" id="helpers"::: diff --git a/docs/fundamentals/networking/includes/ip-endpoint.md b/docs/fundamentals/networking/includes/ip-endpoint.md index cec70ef1df8ab..55b4d052eb97a 100644 --- a/docs/fundamentals/networking/includes/ip-endpoint.md +++ b/docs/fundamentals/networking/includes/ip-endpoint.md @@ -9,7 +9,7 @@ When working with , you repres TCP/IP uses a network address and a service port number to uniquely identify a service. The network address identifies a specific network destination; the port number identifies the specific service on that device to connect to. The combination of network address and service port is called an endpoint, which is represented in the .NET by the class. A descendant of `EndPoint` is defined for each supported address family; for the IP address family, the class is . -The class provides domain-name services to apps that use TCP/IP internet services. The method queries a DNS server to map a user-friendly domain name (such as "host.contoso.com") to a numeric Internet address (such as `192.168.1.1`). `GetHostEntryAsync` returns a `Task` that when awaited contains a list of addresses and aliases for the requested name. In most cases, you can use the first address returned in the array. The following code gets an containing the IP address for the server `host.contoso.com`. +The class provides domain-name services to apps that use TCP/IP internet services. The method queries a DNS server to map a user-friendly domain name (such as "host.contoso.com") to a numeric Internet address (such as `192.168.1.1`). `GetHostEntryAsync` returns a `Task` that when awaited contains a list of addresses and aliases for the requested name. In most cases, you can use the first address returned in the array. The following code gets an containing the IP address for the server `host.contoso.com`. ```csharp IPHostEntry ipHostInfo = await Dns.GetHostEntryAsync("host.contoso.com"); @@ -17,7 +17,7 @@ IPAddress ipAddress = ipHostInfo.AddressList[0]; ``` > [!TIP] -> For manual testing and debugging purposes, you can typically use the method with the resulting host name from the value to resolve the localhost name to an IP address. Consider the following code snippet: +> For manual testing and debugging purposes, you can typically use the method with the resulting host name from the value to resolve the localhost name to an IP address. Consider the following code snippet: > > ```csharp > var hostName = Dns.GetHostName(); diff --git a/docs/fundamentals/networking/sockets/socket-services.md b/docs/fundamentals/networking/sockets/socket-services.md index 344d749c4f55e..5554835e7a797 100644 --- a/docs/fundamentals/networking/sockets/socket-services.md +++ b/docs/fundamentals/networking/sockets/socket-services.md @@ -32,15 +32,15 @@ With the `endPoint` object created, create a client socket to connect to the ser The preceding C# code: - Instantiates a new `Socket` object with a given `endPoint` instances address family, the , and . -- Calls the method with the `endPoint` instance as an argument. +- Calls the method with the `endPoint` instance as an argument. - In a `while` loop: - - Encodes and sends a message to the server using . + - Encodes and sends a message to the server using . - Writes the sent message to the console. - - Initializes a buffer to receive data from the server using . + - Initializes a buffer to receive data from the server using . - When the `response` is an acknowledgment, it's written to the console and the loop is exited. -- Finally, the `client` socket calls given , which shuts down both send and receive operations. +- Finally, the `client` socket calls given , which shuts down both send and receive operations. ## Create a `Socket` server @@ -51,14 +51,14 @@ To create the server socket, the `endPoint` object can listen for incoming conne The preceding C# code: - Instantiates a new `Socket` object with a given `endPoint` instances address family, the , and . -- The `listener` calls the method with the `endPoint` instance as an argument to associate the socket with the network address. +- The `listener` calls the method with the `endPoint` instance as an argument to associate the socket with the network address. - The method is called to listen for incoming connections. -- The `listener` calls the method to accept an incoming connection on the `handler` socket. +- The `listener` calls the method to accept an incoming connection on the `handler` socket. - In a `while` loop: - - Calls to receive data from the client. + - Calls to receive data from the client. - When the data is received, it's decoded and written to the console. - - If the `response` message ends with `<|EOM|>`, an acknowledgment is sent to the client using the . + - If the `response` message ends with `<|EOM|>`, an acknowledgment is sent to the client using the . ## Run the sample client and server diff --git a/docs/fundamentals/networking/sockets/sockets-overview.md b/docs/fundamentals/networking/sockets/sockets-overview.md index 519a0339b11aa..c5ca20bcf7753 100644 --- a/docs/fundamentals/networking/sockets/sockets-overview.md +++ b/docs/fundamentals/networking/sockets/sockets-overview.md @@ -23,7 +23,7 @@ The namespace contains a managed, cross-platform socke The class is a managed-code version of the socket services provided relying on native interoperability with Linux, macOS, or Windows. In most cases, the `Socket` class methods simply marshal data into their native counterparts and handle any necessary security checks. -The `Socket` class supports two basic modes, synchronous and asynchronous. In synchronous mode, calls to functions that perform network operations (such as and ) wait until the operation completes before returning control to the calling program. In asynchronous mode, these calls return immediately. +The `Socket` class supports two basic modes, synchronous and asynchronous. In synchronous mode, calls to functions that perform network operations (such as and ) wait until the operation completes before returning control to the calling program. In asynchronous mode, these calls return immediately. ## See also diff --git a/docs/fundamentals/networking/sockets/tcp-classes.md b/docs/fundamentals/networking/sockets/tcp-classes.md index 74573e033e351..8cb105247a35c 100644 --- a/docs/fundamentals/networking/sockets/tcp-classes.md +++ b/docs/fundamentals/networking/sockets/tcp-classes.md @@ -2,7 +2,7 @@ title: Use TcpClient and TcpListener description: Learn how to use the TcpClient class to create a socket to request and receive data using TCP in .NET. ms.date: 10/20/2025 -helpviewer_keywords: +helpviewer_keywords: - "protocols, TCP" - "network resources, TCP" - "sending data, TCP" @@ -26,7 +26,7 @@ To work with Transmission Control Protocol (TCP), you have two options: either u The protocol classes use the underlying `Socket` class to provide simple access to network services without the overhead of maintaining state information or knowing the details of setting up protocol-specific sockets. To use asynchronous `Socket` methods, you can use the asynchronous methods supplied by the class. To access features of the `Socket` class not exposed by the protocol classes, you must use the `Socket` class. -`TcpClient` and `TcpListener` represent the network using the `NetworkStream` class. You use the method to return the network stream, and then call the stream's and methods. The `NetworkStream` does not own the protocol classes' underlying socket, so closing it does not affect the socket. +`TcpClient` and `TcpListener` represent the network using the `NetworkStream` class. You use the method to return the network stream, and then call the stream's and methods. The `NetworkStream` does not own the protocol classes' underlying socket, so closing it does not affect the socket. ## Use `TcpClient` and `TcpListener` @@ -46,7 +46,7 @@ The preceding C# code: - Creates an `IPEndPoint` from a known `IPAddress` and port. - Instantiate a new `TcpClient` object. -- Connects the `client` to the remote TCP time server on port 13 using . +- Connects the `client` to the remote TCP time server on port 13 using . - Uses a to read data from the remote host. - Declares a read buffer of `1_024` bytes. - Reads data from the `stream` into the read buffer. @@ -59,7 +59,7 @@ Since the client knows that the message is small, the entire message can be read ## Create a `TcpListener` -The type is used to monitor a TCP port for incoming requests and then create either a `Socket` or a `TcpClient` that manages the connection to the client. The method enables listening, and the method disables listening on the port. The method accepts incoming connection requests and creates a `TcpClient` to handle the request, and the method accepts incoming connection requests and creates a `Socket` to handle the request. +The type is used to monitor a TCP port for incoming requests and then create either a `Socket` or a `TcpClient` that manages the connection to the client. The method enables listening, and the method disables listening on the port. The method accepts incoming connection requests and creates a `TcpClient` to handle the request, and the method accepts incoming connection requests and creates a `Socket` to handle the request. The following example demonstrates creating a network time server using a `TcpListener` to monitor TCP port 13. When an incoming connection request is accepted, the time server responds with the current date and time from the host server. @@ -69,12 +69,12 @@ The preceding C# code: - Creates an `IPEndPoint` with and port. - Instantiate a new `TcpListener` object. -- Calls the method to start listening on the port. -- Uses a `TcpClient` from the method to accept incoming connection requests. +- Calls the method to start listening on the port. +- Uses a `TcpClient` from the method to accept incoming connection requests. - Encodes the current date and time as a string message. - Uses a to write data to the connected client. - Writes the sent message to the console. -- Finally, calls the method to stop listening on the port. +- Finally, calls the method to stop listening on the port. ## Finite TCP control with the `Socket` class @@ -188,7 +188,7 @@ using var socket = new Socket(ep.AddressFamily, SocketType.Stream, ProtocolType. ### Start listening on the server -The method is a wrapper combining `Socket`'s and functionality. +The method is a wrapper combining `Socket`'s and functionality. Consider the following TCP listener code: @@ -259,7 +259,7 @@ using var stream = new NetworkStream(socket, ownsSocket: true); ``` > [!TIP] -> If your code doesn't need to work with a instance, you can rely on `Socket`'s Send/Receive methods (, , and ) directly instead of creating a . +> If your code doesn't need to work with a instance, you can rely on `Socket`'s Send/Receive methods (, , and ) directly instead of creating a . ## See also diff --git a/docs/fundamentals/networking/telemetry/events.md b/docs/fundamentals/networking/telemetry/events.md index a83b4e9bea773..d88c525948ed1 100644 --- a/docs/fundamentals/networking/telemetry/events.md +++ b/docs/fundamentals/networking/telemetry/events.md @@ -456,6 +456,6 @@ If you're using the [`Yarp.Telemetry.Consumption`] library and have any suggesti [`INetSecurityTelemetryConsumer`]: https://github.com/microsoft/reverse-proxy/blob/main/src/TelemetryConsumption/NetSecurity/INetSecurityTelemetryConsumer.cs [`ISocketsTelemetryConsumer`]: https://github.com/microsoft/reverse-proxy/blob/main/src/TelemetryConsumption/Sockets/ISocketsTelemetryConsumer.cs [`IKestrelTelemetryConsumer`]: https://github.com/microsoft/reverse-proxy/blob/main/src/TelemetryConsumption/Kestrel/IKestrelTelemetryConsumer.cs -[`AsyncLocal`]: xref:System.Threading.AsyncLocal%601 +[`AsyncLocal`]: xref:System.Threading.AsyncLocal`1 [`ActivityID`]: ../../../core/diagnostics/eventsource-activity-ids.md [microsoft/reverse-proxy issue]: https://github.com/microsoft/reverse-proxy/issues/new diff --git a/docs/fundamentals/networking/telemetry/metrics.md b/docs/fundamentals/networking/telemetry/metrics.md index 58fe45c99a043..8c0d41a690eba 100644 --- a/docs/fundamentals/networking/telemetry/metrics.md +++ b/docs/fundamentals/networking/telemetry/metrics.md @@ -141,7 +141,7 @@ This allows you to intercept and modify the requests before they're forwarded to :::code language="csharp" source="snippets/metrics/Program.cs" id="snippet_Enrichment"::: -If you're working with [`IHttpClientFactory`](../../../core/extensions/httpclient-factory.md), you can use to register the `EnrichmentHandler`: +If you're working with [`IHttpClientFactory`](../../../core/extensions/httpclient-factory.md), you can use to register the `EnrichmentHandler`: :::code language="csharp" source="snippets/metrics/Program.cs" id="snippet_EnrichmentWithFactory"::: @@ -160,7 +160,7 @@ By default, a global is used to emit all When working with [`Microsoft.Extensions.Http`](https://www.nuget.org/packages/microsoft.extensions.http) and [`IHttpClientFactory`](../../../core/extensions/httpclient-factory.md) on .NET 8+, the default `IHttpClientFactory` implementation automatically picks the `IMeterFactory` instance registered in the and assigns it to the primary handler it creates internally. > [!NOTE] -> Starting with .NET 8, the method automatically calls to initialize the metrics services and register the default implementation with . The default caches instances by name, meaning that there's one with the name `System.Net.Http` per . +> Starting with .NET 8, the method automatically calls to initialize the metrics services and register the default implementation with . The default caches instances by name, meaning that there's one with the name `System.Net.Http` per . ### Test metrics diff --git a/docs/fundamentals/networking/telemetry/tracing.md b/docs/fundamentals/networking/telemetry/tracing.md index afc82e50e26ce..9fb6ff58f441c 100644 --- a/docs/fundamentals/networking/telemetry/tracing.md +++ b/docs/fundamentals/networking/telemetry/tracing.md @@ -12,7 +12,7 @@ ms.date: 10/4/2024 The tracing system in .NET is designed to work with OpenTelemetry (OTel), and uses OTel to export the data to monitoring systems. Tracing in .NET is implemented using the APIs, where a unit of work is represented by the class, which corresponds to an OTel [span](https://opentelemetry.io/docs/concepts/signals/traces/#spans). OpenTelemetry defines an industry-wide standard naming scheme for spans (activities) together with their attributes (tags), known as [semantic conventions](https://opentelemetry.io/docs/concepts/semantic-conventions). The .NET telemetry uses existing semantic conventions wherever possible. > [!NOTE] -> The terms *span* and *activity* are synonymous in this article. In context of .NET code, they refer to a instance. Don't confuse the OTel span with . +> The terms *span* and *activity* are synonymous in this article. In context of .NET code, they refer to a instance. Don't confuse the OTel span with . > [!TIP] > For a comprehensive list of all built-in activities together with their tags/attributes, see [Built-in activities in .NET](../../../core/diagnostics/distributed-tracing-builtin-activities.md). @@ -29,7 +29,7 @@ The built-in instrumentation evolved with .NET versions. ## Collect System.Net traces -At the [lowest level](../../../core/diagnostics/distributed-tracing-collection-walkthroughs.md#collect-traces-using-custom-logic), trace collection is supported via the method, which registers objects containing user-defined logic. +At the [lowest level](../../../core/diagnostics/distributed-tracing-collection-walkthroughs.md#collect-traces-using-custom-logic), trace collection is supported via the method, which registers objects containing user-defined logic. However, as an application developer, you would likely prefer to rely on the rich ecosystem built upon the features provided by the [OpenTelemetry .NET SDK](https://opentelemetry.io/docs/languages/net/) to collect, export, and monitor traces. @@ -132,7 +132,7 @@ To add additional tags/attributes to the HTTP client request activity, the simpl ### Manual enrichment -It's possible to implement the enrichment of the `HTTP client request` activity manually. For this you need to access in the code that is running in the scope of the request activity, before the activity is finished. This can be done by implementing an `IObserver` and subscribing it to to get callbacks for when networking activity is occurring. In fact, this is how the [OpenTelemetry HttpClient and HttpWebRequest instrumentation library](#enrichment-api-in-the-opentelemetry-instrumentation-library) is implemented. For a code example, see the subscription code in [`DiagnosticSourceSubscriber.cs`](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/bfdf02928ea7f958c481493bc1adc238472b9b9c/src/Shared/DiagnosticSourceSubscriber.cs#L44) and the underlying implementation in [HttpHandlerDiagnosticListener.cs](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/bfdf02928ea7f958c481493bc1adc238472b9b9c/src/OpenTelemetry.Instrumentation.Http/Implementation/HttpHandlerDiagnosticListener.cs) where the notifications are delegated to. +It's possible to implement the enrichment of the `HTTP client request` activity manually. For this you need to access in the code that is running in the scope of the request activity, before the activity is finished. This can be done by implementing an `IObserver` and subscribing it to to get callbacks for when networking activity is occurring. In fact, this is how the [OpenTelemetry HttpClient and HttpWebRequest instrumentation library](#enrichment-api-in-the-opentelemetry-instrumentation-library) is implemented. For a code example, see the subscription code in [`DiagnosticSourceSubscriber.cs`](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/bfdf02928ea7f958c481493bc1adc238472b9b9c/src/Shared/DiagnosticSourceSubscriber.cs#L44) and the underlying implementation in [HttpHandlerDiagnosticListener.cs](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/bfdf02928ea7f958c481493bc1adc238472b9b9c/src/OpenTelemetry.Instrumentation.Http/Implementation/HttpHandlerDiagnosticListener.cs) where the notifications are delegated to. ## Need more tracing? diff --git a/docs/fundamentals/reflection/accessing-custom-attributes.md b/docs/fundamentals/reflection/accessing-custom-attributes.md index 20cbf5f901a4a..e0d4313bd54e8 100644 --- a/docs/fundamentals/reflection/accessing-custom-attributes.md +++ b/docs/fundamentals/reflection/accessing-custom-attributes.md @@ -16,11 +16,11 @@ After attributes have been associated with program elements, reflection can be u ## -Code loaded into the context cannot be executed. This means that instances of custom attributes cannot be created, because that would require executing their constructors. To load and examine custom attributes in the context, use the class. You can obtain instances of this class by using the appropriate overload of the static method. For more information, see [How to: Inspect assembly contents using MetadataLoadContext](../../standard/assembly/inspect-contents-using-metadataloadcontext.md). +Code loaded into the context cannot be executed. This means that instances of custom attributes cannot be created, because that would require executing their constructors. To load and examine custom attributes in the context, use the class. You can obtain instances of this class by using the appropriate overload of the static method. For more information, see [How to: Inspect assembly contents using MetadataLoadContext](../../standard/assembly/inspect-contents-using-metadataloadcontext.md). ## The execution context -The main reflection methods to query attributes in the execution context are and . +The main reflection methods to query attributes in the execution context are and . The accessibility of a custom attribute is checked with respect to the assembly in which it's attached. This is equivalent to checking whether a method on a type in the assembly in which the custom attribute is attached can call the constructor of the custom attribute. @@ -55,7 +55,7 @@ If the runtime is attempting to retrieve the custom attributes for the public cu 3. The runtime checks that the constructor of `MyDescriptionAttribute` is visible and accessible within the System.Web.dll assembly. 4. The runtime calls the constructor of `MyDescriptionAttribute` with the custom attribute parameters and returns the new object to the caller. -The custom attribute reflection model could leak instances of user-defined types outside the assembly in which the type is defined. This is no different from the members in the runtime system library that return instances of user-defined types, such as returning an array of `RuntimeMethodInfo` objects. To prevent a client from discovering information about a user-defined custom attribute type, define the type's members to be nonpublic. +The custom attribute reflection model could leak instances of user-defined types outside the assembly in which the type is defined. This is no different from the members in the runtime system library that return instances of user-defined types, such as returning an array of `RuntimeMethodInfo` objects. To prevent a client from discovering information about a user-defined custom attribute type, define the type's members to be nonpublic. The following example demonstrates the basic way of using reflection to get access to custom attributes. @@ -64,6 +64,6 @@ The following example demonstrates the basic way of using reflection to get acce ## See also -- -- +- +- - [View Type Information](viewing-type-information.md) diff --git a/docs/fundamentals/reflection/dynamically-loading-and-using-types.md b/docs/fundamentals/reflection/dynamically-loading-and-using-types.md index ee531bac4d2fb..20683809a34e6 100644 --- a/docs/fundamentals/reflection/dynamically-loading-and-using-types.md +++ b/docs/fundamentals/reflection/dynamically-loading-and-using-types.md @@ -16,7 +16,7 @@ helpviewer_keywords: Reflection provides infrastructure used by language compilers to implement implicit late binding. Binding is the process of locating the declaration (that is, the implementation) that corresponds to a uniquely specified type. When this process occurs at runtime rather than at compile time, it's called late binding. Visual Basic allows you to use implicit late binding in your code; the Visual Basic compiler calls a helper method that uses reflection to obtain the object type. The arguments passed to the helper method cause the appropriate method to be invoked at runtime. These arguments are the instance (an object) on which to invoke the method, the name of the invoked method (a string), and the arguments passed to the invoked method (an array of objects). -In the following example, the Visual Basic compiler uses reflection implicitly to call a method on an object whose type is not known at compile time. A `HelloWorld` class has a `PrintHello` method that prints out "Hello World" concatenated with some text that's passed to the `PrintHello` method. The `PrintHello` method called in this example is actually a ; the Visual Basic code allows the `PrintHello` method to be invoked as if the type of the object (`helloObj`) were known at compile time (early binding) rather than at runtime (late binding). +In the following example, the Visual Basic compiler uses reflection implicitly to call a method on an object whose type is not known at compile time. A `HelloWorld` class has a `PrintHello` method that prints out "Hello World" concatenated with some text that's passed to the `PrintHello` method. The `PrintHello` method called in this example is actually a ; the Visual Basic code allows the `PrintHello` method to be invoked as if the type of the object (`helloObj`) were known at compile time (early binding) rather than at runtime (late binding). ```vb Module Hello @@ -47,18 +47,18 @@ The following example demonstrates a simple custom binder that provides no argum ### InvokeMember and CreateInstance -Use to invoke a member of a type. The `CreateInstance` methods of various classes, such as and , are specialized forms of `InvokeMember` that create new instances of the specified type. The `Binder` class is used for overload resolution and argument coercion in these methods. +Use to invoke a member of a type. The `CreateInstance` methods of various classes, such as and , are specialized forms of `InvokeMember` that create new instances of the specified type. The `Binder` class is used for overload resolution and argument coercion in these methods. The following example shows the three possible combinations of argument coercion (type conversion) and member selection. In Case 1, no argument coercion or member selection is needed. In Case 2, only member selection is needed. In Case 3, only argument coercion is needed. [!code-csharp[Conceptual.Types.Dynamic#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.types.dynamic/cs/source2.cs#2)] [!code-vb[Conceptual.Types.Dynamic#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.types.dynamic/vb/source2.vb#2)] -Overload resolution is needed when more than one member with the same name is available. The and methods are used to resolve binding to a single member. `Binder.BindToMethod` also provides property resolution through the `get` and `set` property accessors. +Overload resolution is needed when more than one member with the same name is available. The and methods are used to resolve binding to a single member. `Binder.BindToMethod` also provides property resolution through the `get` and `set` property accessors. `BindToMethod` returns the to invoke, or a null reference (`Nothing` in Visual Basic) if no such invocation is possible. The `MethodBase` return value need not be one of those contained in the *match* parameter, although that is the usual case. -When ByRef arguments are present, the caller might want to get them back. Therefore, `Binder` allows a client to map the array of arguments back to its original form if `BindToMethod` has manipulated the argument array. To do this, the caller must be guaranteed that the order of the arguments is unchanged. When arguments are passed by name, `Binder` reorders the argument array, and that's what the caller sees. For more information, see . +When ByRef arguments are present, the caller might want to get them back. Therefore, `Binder` allows a client to map the array of arguments back to its original form if `BindToMethod` has manipulated the argument array. To do this, the caller must be guaranteed that the order of the arguments is unchanged. When arguments are passed by name, `Binder` reorders the argument array, and that's what the caller sees. For more information, see . The set of available members are those members defined in the type or any base type. If is specified, members of any accessibility are returned in the set. If `BindingFlags.NonPublic` is not specified, the binder must enforce accessibility rules. When specifying the `Public` or `NonPublic` binding flag, you must also specify the `Instance` or `Static` binding flag, or no members will be returned. @@ -66,7 +66,7 @@ If there is only one member of the given name, no callback is necessary, and bin If there is more than one member in the available set, all these methods are passed to `BindToMethod`, which selects the appropriate method and returns it. In Case 2 of the code example, there are two methods named `PrintValue`. The appropriate method is selected by the call to `BindToMethod`. - performs argument coercion (type conversion), which converts the actual arguments to the type of the formal arguments of the selected method. `ChangeType` is called for every argument even if the types match exactly. + performs argument coercion (type conversion), which converts the actual arguments to the type of the formal arguments of the selected method. `ChangeType` is called for every argument even if the types match exactly. In Case 3 of the code example, an actual argument of type `String` with a value of "5.5" is passed to a method with a formal argument of type `Double`. For the invocation to succeed, the string value "5.5" must be converted to a double value. `ChangeType` performs this conversion. @@ -88,11 +88,11 @@ In Case 3 of the code example, an actual argument of type `String` with a value | `Single` | `Double` | | Nonreference type | Reference type | -The class has `Get` methods that use parameters of type `Binder` to resolve references to a particular member. , , and search for a particular member of the current type by providing signature information for that member. and are called back on to select the given signature information of the appropriate methods. +The class has `Get` methods that use parameters of type `Binder` to resolve references to a particular member. , , and search for a particular member of the current type by providing signature information for that member. and are called back on to select the given signature information of the appropriate methods. ## See also -- -- +- +- - [View Type Information](viewing-type-information.md) - [Type Conversion in .NET](../../standard/base-types/type-conversion.md) diff --git a/docs/fundamentals/reflection/get-type-member-information.md b/docs/fundamentals/reflection/get-type-member-information.md index 4d6142e6cce1a..8ebff6b76193a 100644 --- a/docs/fundamentals/reflection/get-type-member-information.md +++ b/docs/fundamentals/reflection/get-type-member-information.md @@ -12,7 +12,7 @@ dev_langs: --- # How to: Get type and member information by using reflection -The namespace contains many methods for obtaining information about types and their members. This article demonstrates one of these methods, . For additional information, see [Reflection overview](overview.md). +The namespace contains many methods for obtaining information about types and their members. This article demonstrates one of these methods, . For additional information, see [Reflection overview](overview.md). ## Example diff --git a/docs/fundamentals/reflection/how-to-define-a-generic-method-with-reflection-emit.md b/docs/fundamentals/reflection/how-to-define-a-generic-method-with-reflection-emit.md index 2d863095664ae..bb76802fba07e 100644 --- a/docs/fundamentals/reflection/how-to-define-a-generic-method-with-reflection-emit.md +++ b/docs/fundamentals/reflection/how-to-define-a-generic-method-with-reflection-emit.md @@ -27,7 +27,7 @@ The third procedure shows how to invoke the generic method. ## Define a generic method -1. Before beginning, it is useful to look at how the generic method appears when written using a high-level language. The following code is included in the example code for this article, along with code to call the generic method. The method has two type parameters, `TInput` and `TOutput`, the second of which must be a reference type (`class`), must have a parameterless constructor (`new`), and must implement `ICollection`. This interface constraint ensures that the method can be used to add elements to the `TOutput` collection that the method creates. The method has one formal parameter, `input`, which is an array of `TInput`. The method creates a collection of type `TOutput` and copies the elements of `input` to the collection. +1. Before beginning, it is useful to look at how the generic method appears when written using a high-level language. The following code is included in the example code for this article, along with code to call the generic method. The method has two type parameters, `TInput` and `TOutput`, the second of which must be a reference type (`class`), must have a parameterless constructor (`new`), and must implement `ICollection`. This interface constraint ensures that the method can be used to add elements to the `TOutput` collection that the method creates. The method has one formal parameter, `input`, which is an array of `TInput`. The method creates a collection of type `TOutput` and copies the elements of `input` to the collection. [!code-csharp[GenericMethodHowTo#20](./snippets/csharp/construct-generic-method/source.cs#20)] [!code-vb[GenericMethodHowTo#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#20)] @@ -42,32 +42,32 @@ The third procedure shows how to invoke the generic method. [!code-csharp[GenericMethodHowTo#3](./snippets/csharp/construct-generic-method/source.cs#3)] [!code-vb[GenericMethodHowTo#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#3)] -1. Define the generic method. If the types of a generic method's formal parameters are specified by generic type parameters of the generic method, use the method overload to define the method. The generic type parameters of the method are not yet defined, so you cannot specify the types of the method's formal parameters in the call to . In this example, the method is named `Factory`. The method is public and `static` (`Shared` in Visual Basic). +1. Define the generic method. If the types of a generic method's formal parameters are specified by generic type parameters of the generic method, use the method overload to define the method. The generic type parameters of the method are not yet defined, so you cannot specify the types of the method's formal parameters in the call to . In this example, the method is named `Factory`. The method is public and `static` (`Shared` in Visual Basic). [!code-csharp[GenericMethodHowTo#4](./snippets/csharp/construct-generic-method/source.cs#4)] [!code-vb[GenericMethodHowTo#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#4)] -1. Define the generic type parameters of `DemoMethod` by passing an array of strings containing the names of the parameters to the method. This makes the method a generic method. The following code makes `Factory` a generic method with type parameters `TInput` and `TOutput`. To make the code easier to read, variables with these names are created to hold the objects representing the two type parameters. +1. Define the generic type parameters of `DemoMethod` by passing an array of strings containing the names of the parameters to the method. This makes the method a generic method. The following code makes `Factory` a generic method with type parameters `TInput` and `TOutput`. To make the code easier to read, variables with these names are created to hold the objects representing the two type parameters. [!code-csharp[GenericMethodHowTo#5](./snippets/csharp/construct-generic-method/source.cs#5)] [!code-vb[GenericMethodHowTo#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#5)] -1. Optionally add special constraints to the type parameters. Special constraints are added using the method. In this example, `TOutput` is constrained to be a reference type and to have a parameterless constructor. +1. Optionally add special constraints to the type parameters. Special constraints are added using the method. In this example, `TOutput` is constrained to be a reference type and to have a parameterless constructor. [!code-csharp[GenericMethodHowTo#6](./snippets/csharp/construct-generic-method/source.cs#6)] [!code-vb[GenericMethodHowTo#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#6)] -1. Optionally add class and interface constraints to the type parameters. In this example, type parameter `TOutput` is constrained to types that implement the `ICollection(Of TInput)` (`ICollection` in C#) interface. This ensures that the method can be used to add elements. +1. Optionally add class and interface constraints to the type parameters. In this example, type parameter `TOutput` is constrained to types that implement the `ICollection(Of TInput)` (`ICollection` in C#) interface. This ensures that the method can be used to add elements. [!code-csharp[GenericMethodHowTo#7](./snippets/csharp/construct-generic-method/source.cs#7)] [!code-vb[GenericMethodHowTo#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#7)] -1. Define the formal parameters of the method, using the method. In this example, the `Factory` method has one parameter, an array of `TInput`. This type is created by calling the method on the that represents `TInput`. The argument of is an array of objects. +1. Define the formal parameters of the method, using the method. In this example, the `Factory` method has one parameter, an array of `TInput`. This type is created by calling the method on the that represents `TInput`. The argument of is an array of objects. [!code-csharp[GenericMethodHowTo#8](./snippets/csharp/construct-generic-method/source.cs#8)] [!code-vb[GenericMethodHowTo#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#8)] -1. Define the return type for the method, using the method. In this example, an instance of `TOutput` is returned. +1. Define the return type for the method, using the method. In this example, an instance of `TOutput` is returned. [!code-csharp[GenericMethodHowTo#9](./snippets/csharp/construct-generic-method/source.cs#9)] [!code-vb[GenericMethodHowTo#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#9)] @@ -84,14 +84,14 @@ The third procedure shows how to invoke the generic method. ## Emit the method body -1. Get a code generator and declare local variables and labels. The method is used to declare local variables. The `Factory` method has four local variables: `retVal` to hold the new `TOutput` that is returned by the method, `ic` to hold the `TOutput` when it is cast to `ICollection`, `input` to hold the input array of `TInput` objects, and `index` to iterate through the array. The method also has two labels, one to enter the loop (`enterLoop`) and one for the top of the loop (`loopAgain`), defined using the method. +1. Get a code generator and declare local variables and labels. The method is used to declare local variables. The `Factory` method has four local variables: `retVal` to hold the new `TOutput` that is returned by the method, `ic` to hold the `TOutput` when it is cast to `ICollection`, `input` to hold the input array of `TInput` objects, and `index` to iterate through the array. The method also has two labels, one to enter the loop (`enterLoop`) and one for the top of the loop (`loopAgain`), defined using the method. The first thing the method does is to load its argument using opcode and to store it in the local variable `input` using opcode. [!code-csharp[GenericMethodHowTo#10](./snippets/csharp/construct-generic-method/source.cs#10)] [!code-vb[GenericMethodHowTo#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#10)] -2. Emit code to create an instance of `TOutput`, using the generic method overload of the method. Using this overload requires the specified type to have a parameterless constructor, which is the reason for adding that constraint to `TOutput`. Create the constructed generic method by passing `TOutput` to . After emitting code to call the method, emit code to store it in the local variable `retVal` using +2. Emit code to create an instance of `TOutput`, using the generic method overload of the method. Using this overload requires the specified type to have a parameterless constructor, which is the reason for adding that constraint to `TOutput`. Create the constructed generic method by passing `TOutput` to . After emitting code to call the method, emit code to store it in the local variable `retVal` using [!code-csharp[GenericMethodHowTo#11](./snippets/csharp/construct-generic-method/source.cs#11)] [!code-vb[GenericMethodHowTo#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#11)] @@ -101,7 +101,7 @@ The third procedure shows how to invoke the generic method. [!code-csharp[GenericMethodHowTo#31](./snippets/csharp/construct-generic-method/source.cs#31)] [!code-vb[GenericMethodHowTo#31](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#31)] -4. Get a representing the method. The method is acting on an `ICollection`, so it's necessary to get the `Add` method specific to that constructed type. You cannot use the method to get this directly from `icollOfTInput`, because is not supported on a type that has been constructed with a . Instead, call on `icoll`, which contains the generic type definition for the generic interface. Then use the `static` method to produce the for the constructed type. The following code demonstrates this. +4. Get a representing the method. The method is acting on an `ICollection`, so it's necessary to get the `Add` method specific to that constructed type. You cannot use the method to get this directly from `icollOfTInput`, because is not supported on a type that has been constructed with a . Instead, call on `icoll`, which contains the generic type definition for the generic interface. Then use the `static` method to produce the for the constructed type. The following code demonstrates this. [!code-csharp[GenericMethodHowTo#12](./snippets/csharp/construct-generic-method/source.cs#12)] [!code-vb[GenericMethodHowTo#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#12)] @@ -111,26 +111,26 @@ The third procedure shows how to invoke the generic method. [!code-csharp[GenericMethodHowTo#32](./snippets/csharp/construct-generic-method/source.cs#32)] [!code-vb[GenericMethodHowTo#32](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#32)] -6. Emit code for the loop. The first step is to mark the top of the loop, by calling with the `loopAgain` label. Branch statements that use the label will now branch to this point in the code. The next step is to push the `TOutput` object, cast to `ICollection(Of TInput)`, onto the stack. It is not needed immediately, but needs to be in position for calling the `Add` method. Next the input array is pushed onto the stack, then the `index` variable containing the current index into the array. The opcode pops the index and the array off the stack and pushes the indexed array element onto the stack. The stack is now ready for the call to the method, which pops the collection and the new element off the stack and adds the element to the collection. +6. Emit code for the loop. The first step is to mark the top of the loop, by calling with the `loopAgain` label. Branch statements that use the label will now branch to this point in the code. The next step is to push the `TOutput` object, cast to `ICollection(Of TInput)`, onto the stack. It is not needed immediately, but needs to be in position for calling the `Add` method. Next the input array is pushed onto the stack, then the `index` variable containing the current index into the array. The opcode pops the index and the array off the stack and pushes the indexed array element onto the stack. The stack is now ready for the call to the method, which pops the collection and the new element off the stack and adds the element to the collection. - The rest of the code in the loop increments the index and tests to see whether the loop is finished: The index and a 32-bit integer 1 are pushed onto the stack and added, leaving the sum on the stack; the sum is stored in `index`. is called to set this point as the entry point for the loop. The index is loaded again. The input array is pushed on the stack, and is emitted to get its length. The index and the length are now on the stack, and is emitted to compare them. If the index is less than the length, branches back to the beginning of the loop. + The rest of the code in the loop increments the index and tests to see whether the loop is finished: The index and a 32-bit integer 1 are pushed onto the stack and added, leaving the sum on the stack; the sum is stored in `index`. is called to set this point as the entry point for the loop. The index is loaded again. The input array is pushed on the stack, and is emitted to get its length. The index and the length are now on the stack, and is emitted to compare them. If the index is less than the length, branches back to the beginning of the loop. [!code-csharp[GenericMethodHowTo#13](./snippets/csharp/construct-generic-method/source.cs#13)] [!code-vb[GenericMethodHowTo#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#13)] -7. Emit code to push the `TOutput` object onto the stack and return from the method. The local variables `retVal` and `ic` both contain references to the new `TOutput`; `ic` is used only to access the method. +7. Emit code to push the `TOutput` object onto the stack and return from the method. The local variables `retVal` and `ic` both contain references to the new `TOutput`; `ic` is used only to access the method. [!code-csharp[GenericMethodHowTo#33](./snippets/csharp/construct-generic-method/source.cs#33)] [!code-vb[GenericMethodHowTo#33](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#33)] ## Invoke the generic method -1. `Factory` is a generic method definition. In order to invoke it, you must assign types to its generic type parameters. Use the method to do this. The following code creates a constructed generic method, specifying for `TInput` and `List(Of String)` (`List` in C#) for `TOutput`, and displays a string representation of the method. +1. `Factory` is a generic method definition. In order to invoke it, you must assign types to its generic type parameters. Use the method to do this. The following code creates a constructed generic method, specifying for `TInput` and `List(Of String)` (`List` in C#) for `TOutput`, and displays a string representation of the method. [!code-csharp[GenericMethodHowTo#21](./snippets/csharp/construct-generic-method/source.cs#21)] [!code-vb[GenericMethodHowTo#21](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#21)] -2. To invoke the method late-bound, use the method. The following code creates an array of , containing as its only element an array of strings, and passes it as the argument list for the generic method. The first parameter of is a null reference because the method is `static`. The return value is cast to `List(Of String)`, and its first element is displayed. +2. To invoke the method late-bound, use the method. The following code creates an array of , containing as its only element an array of strings, and passes it as the argument list for the generic method. The first parameter of is a null reference because the method is `static`. The return value is cast to `List(Of String)`, and its first element is displayed. [!code-csharp[GenericMethodHowTo#22](./snippets/csharp/construct-generic-method/source.cs#22)] [!code-vb[GenericMethodHowTo#22](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#22)] @@ -146,7 +146,7 @@ The third procedure shows how to invoke the generic method. The following code example creates a nongeneric type, `DemoType`, with a generic method, `Factory`. This method has two generic type parameters, `TInput` to specify an input type and `TOutput` to specify an output type. The `TOutput` type parameter is constrained to implement `ICollection` (`ICollection(Of TInput)` in Visual Basic), to be a reference type, and to have a parameterless constructor. -The method has one formal parameter, which is an array of `TInput`. The method returns an instance of `TOutput` that contains all the elements of the input array. `TOutput` can be any generic collection type that implements the generic interface. +The method has one formal parameter, which is an array of `TInput`. The method returns an instance of `TOutput` that contains all the elements of the input array. `TOutput` can be any generic collection type that implements the generic interface. When the code is executed, the dynamic assembly is saved as DemoGenericMethod1.dll, and can be examined using the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md). diff --git a/docs/fundamentals/reflection/how-to-define-a-generic-type-with-reflection-emit.md b/docs/fundamentals/reflection/how-to-define-a-generic-type-with-reflection-emit.md index fd2374abd662d..73c4cc60afbeb 100644 --- a/docs/fundamentals/reflection/how-to-define-a-generic-type-with-reflection-emit.md +++ b/docs/fundamentals/reflection/how-to-define-a-generic-type-with-reflection-emit.md @@ -42,7 +42,7 @@ This article shows you how to: [!code-csharp[EmitGenericType#4](./snippets/csharp/emit-generic-type/source.cs#4)] [!code-vb[EmitGenericType#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb#4)] -1. Define the generic type parameters of `Sample` by passing an array of strings containing the names of the parameters to the method. This makes the class a generic type. The return value is an array of objects representing the type parameters, which can be used in your emitted code. +1. Define the generic type parameters of `Sample` by passing an array of strings containing the names of the parameters to the method. This makes the class a generic type. The return value is an array of objects representing the type parameters, which can be used in your emitted code. In the following code, `Sample` becomes a generic type with type parameters `TFirst` and `TSecond`. To make the code easier to read, each is placed in a variable with the same name as the type parameter. @@ -64,21 +64,21 @@ This article shows you how to: [!code-csharp[EmitGenericType#21](./snippets/csharp/emit-generic-type/source.cs#21)] [!code-vb[EmitGenericType#21](../../../samples/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb#21)] -1. Define a method that uses the type parameters of the generic type. Note that such methods are not generic unless they have their own type parameter lists. The following code defines a `static` method (`Shared` in Visual Basic) that takes an array of `TFirst` and returns a `List` (`List(Of TFirst)` in Visual Basic) containing all the elements of the array. To define this method, it is necessary to create the type `List` by calling on the generic type definition, `List`. (The `T` is omitted when you use the `typeof` operator (`GetType` in Visual Basic) to get the generic type definition.) The parameter type is created by using the method. +1. Define a method that uses the type parameters of the generic type. Note that such methods are not generic unless they have their own type parameter lists. The following code defines a `static` method (`Shared` in Visual Basic) that takes an array of `TFirst` and returns a `List` (`List(Of TFirst)` in Visual Basic) containing all the elements of the array. To define this method, it is necessary to create the type `List` by calling on the generic type definition, `List`. (The `T` is omitted when you use the `typeof` operator (`GetType` in Visual Basic) to get the generic type definition.) The parameter type is created by using the method. [!code-csharp[EmitGenericType#22](./snippets/csharp/emit-generic-type/source.cs#22)] [!code-vb[EmitGenericType#22](../../../samples/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb#22)] -1. Emit the method body. The method body consists of three opcodes that load the input array onto the stack, call the `List` constructor that takes `IEnumerable` (which does all the work of putting the input elements into the list), and return (leaving the new object on the stack). The difficult part of emitting this code is getting the constructor. +1. Emit the method body. The method body consists of three opcodes that load the input array onto the stack, call the `List` constructor that takes `IEnumerable` (which does all the work of putting the input elements into the list), and return (leaving the new object on the stack). The difficult part of emitting this code is getting the constructor. - The method is not supported on a , so it is not possible to get the constructor of `List` directly. First, it is necessary to get the constructor of the generic type definition `List` and then to call a method that converts it to the corresponding constructor of `List`. + The method is not supported on a , so it is not possible to get the constructor of `List` directly. First, it is necessary to get the constructor of the generic type definition `List` and then to call a method that converts it to the corresponding constructor of `List`. - The constructor used for this code example takes an `IEnumerable`. Note, however, that this is not the generic type definition of the generic interface; instead, the type parameter `T` from `List` must be substituted for the type parameter `T` of `IEnumerable`. (This seems confusing only because both types have type parameters named `T`. That is why this code example uses the names `TFirst` and `TSecond`.) To get the type of the constructor argument, start with the generic type definition `IEnumerable` and call with the first generic type parameter of `List`. The constructor argument list must be passed as an array, with just one argument in this case. + The constructor used for this code example takes an `IEnumerable`. Note, however, that this is not the generic type definition of the generic interface; instead, the type parameter `T` from `List` must be substituted for the type parameter `T` of `IEnumerable`. (This seems confusing only because both types have type parameters named `T`. That is why this code example uses the names `TFirst` and `TSecond`.) To get the type of the constructor argument, start with the generic type definition `IEnumerable` and call with the first generic type parameter of `List`. The constructor argument list must be passed as an array, with just one argument in this case. > [!NOTE] > The generic type definition is expressed as `IEnumerable<>` when you use the `typeof` operator in C#, or `IEnumerable(Of )` when you use the `GetType` operator in Visual Basic. - Now it is possible to get the constructor of `List` by calling on the generic type definition. To convert this constructor to the corresponding constructor of `List`, pass `List` and the constructor from `List` to the static method. + Now it is possible to get the constructor of `List` by calling on the generic type definition. To convert this constructor to the corresponding constructor of `List`, pass `List` and the constructor from `List` to the static method. [!code-csharp[EmitGenericType#23](./snippets/csharp/emit-generic-type/source.cs#23)] [!code-vb[EmitGenericType#23](../../../samples/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb#23)] @@ -88,12 +88,12 @@ This article shows you how to: [!code-csharp[EmitGenericType#8](./snippets/csharp/emit-generic-type/source.cs#8)] [!code-vb[EmitGenericType#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb#8)] -1. Invoke the method. `ExampleMethod` is not generic, but the type it belongs to is generic, so to get a that can be invoked, it's necessary to create a constructed type from the type definition for `Sample`. The constructed type uses the `Example` class, which satisfies the constraints on `TFirst` because it is a reference type and has a default parameterless constructor, and the `ExampleDerived` class which satisfies the constraints on `TSecond`. (The code for `ExampleDerived` can be found in the example code section.) These two types are passed to to create the constructed type. The is then obtained using the method. +1. Invoke the method. `ExampleMethod` is not generic, but the type it belongs to is generic, so to get a that can be invoked, it's necessary to create a constructed type from the type definition for `Sample`. The constructed type uses the `Example` class, which satisfies the constraints on `TFirst` because it is a reference type and has a default parameterless constructor, and the `ExampleDerived` class which satisfies the constraints on `TSecond`. (The code for `ExampleDerived` can be found in the example code section.) These two types are passed to to create the constructed type. The is then obtained using the method. [!code-csharp[EmitGenericType#9](./snippets/csharp/emit-generic-type/source.cs#9)] [!code-vb[EmitGenericType#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb#9)] -1. The following code creates an array of `Example` objects, places that array in an array of type representing the arguments of the method to be invoked, and passes them to the method. The first argument of the method is a null reference because the method is `static`. +1. The following code creates an array of `Example` objects, places that array in an array of type representing the arguments of the method to be invoked, and passes them to the method. The first argument of the method is a null reference because the method is `static`. [!code-csharp[EmitGenericType#10](./snippets/csharp/emit-generic-type/source.cs#10)] [!code-vb[EmitGenericType#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb#10)] diff --git a/docs/fundamentals/reflection/how-to-define-and-execute-dynamic-methods.md b/docs/fundamentals/reflection/how-to-define-and-execute-dynamic-methods.md index 39026225aa5ca..cfded7760e754 100644 --- a/docs/fundamentals/reflection/how-to-define-and-execute-dynamic-methods.md +++ b/docs/fundamentals/reflection/how-to-define-and-execute-dynamic-methods.md @@ -40,7 +40,7 @@ The following procedures show how to define and execute a simple dynamic method [!code-csharp[DynamicMethodHowTo#5](../../../samples/snippets/csharp/VS_Snippets_CLR/DynamicMethodHowTo/cs/source.cs#5)] [!code-vb[DynamicMethodHowTo#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/DynamicMethodHowTo/vb/source.vb#5)] -1. Create an instance of the delegate (declared in step 1) that represents the dynamic method by calling the method. Creating the delegate completes the method, and any further attempts to change the method — for example, adding more CIL — are ignored. The following code creates the delegate and invokes it, using a generic delegate. +1. Create an instance of the delegate (declared in step 1) that represents the dynamic method by calling the method. Creating the delegate completes the method, and any further attempts to change the method — for example, adding more CIL — are ignored. The following code creates the delegate and invokes it, using a generic delegate. [!code-csharp[DynamicMethodHowTo#6](../../../samples/snippets/csharp/VS_Snippets_CLR/DynamicMethodHowTo/cs/source.cs#6)] [!code-vb[DynamicMethodHowTo#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/DynamicMethodHowTo/vb/source.vb#6)] @@ -70,7 +70,7 @@ The following procedures show how to define and execute a simple dynamic method 1. Create an instance of the delegate (declared in step 1) that represents the dynamic method by calling the method overload. Creating the delegate completes the method, and any further attempts to change the method—for example, adding more CIL—are ignored. > [!NOTE] - > You can call the method multiple times to create delegates bound to other instances of the target type. + > You can call the method multiple times to create delegates bound to other instances of the target type. The following code binds the method to a new instance of the `Example` class whose private test field is set to 42. That is, each time the delegate is invoked the instance of `Example` is passed to the first parameter of the method. diff --git a/docs/fundamentals/reflection/how-to-examine-and-instantiate-generic-types-with-reflection.md b/docs/fundamentals/reflection/how-to-examine-and-instantiate-generic-types-with-reflection.md index bf95243803f2f..dec94a7d9668c 100644 --- a/docs/fundamentals/reflection/how-to-examine-and-instantiate-generic-types-with-reflection.md +++ b/docs/fundamentals/reflection/how-to-examine-and-instantiate-generic-types-with-reflection.md @@ -27,7 +27,7 @@ You can create a object that represents a constructed type by [!code-csharp[HowToGeneric#3](snippets/csharp/instantiate-generic-type/GenericTypes.cs#3)] [!code-vb[HowToGeneric#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToGeneric/VB/ur.vb#3)] -3. Get an array that contains the generic type arguments, using the method. +3. Get an array that contains the generic type arguments, using the method. [!code-csharp[HowToGeneric#4](snippets/csharp/instantiate-generic-type/GenericTypes.cs#4)] [!code-vb[HowToGeneric#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToGeneric/VB/ur.vb#4)] @@ -42,7 +42,7 @@ You can create a object that represents a constructed type by [!code-csharp[HowToGeneric#6](snippets/csharp/instantiate-generic-type/GenericTypes.cs#6)] [!code-vb[HowToGeneric#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToGeneric/VB/ur.vb#6)] -6. Determine the base type constraint and the interface constraints of a generic type parameter by using the method to obtain all the constraints in a single array. Constraints are not guaranteed to be in any particular order. +6. Determine the base type constraint and the interface constraints of a generic type parameter by using the method to obtain all the constraints in a single array. Constraints are not guaranteed to be in any particular order. [!code-csharp[HowToGeneric#7](snippets/csharp/instantiate-generic-type/GenericTypes.cs#7)] [!code-vb[HowToGeneric#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToGeneric/VB/ur.vb#7)] @@ -59,9 +59,9 @@ You can create a object that represents a constructed type by ## Construct an instance of a generic type -A generic type is like a template. You can't create instances of it unless you specify real types for its generic type parameters. To do this at runtime, using reflection, requires the method. +A generic type is like a template. You can't create instances of it unless you specify real types for its generic type parameters. To do this at runtime, using reflection, requires the method. -1. Get a object that represents the generic type. The following code gets the generic type in two different ways: by using the method overload with a string describing the type, and by calling the method on the constructed type `Dictionary\` (`Dictionary(Of String, Example)` in Visual Basic). The method requires a generic type definition. +1. Get a object that represents the generic type. The following code gets the generic type in two different ways: by using the method overload with a string describing the type, and by calling the method on the constructed type `Dictionary\` (`Dictionary(Of String, Example)` in Visual Basic). The method requires a generic type definition. [!code-csharp[HowToGeneric#10](snippets/csharp/instantiate-generic-type/GenericTypes.cs#10)] [!code-vb[HowToGeneric#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToGeneric/VB/ur.vb#10)] @@ -71,7 +71,7 @@ A generic type is like a template. You can't create instances of it unless you s [!code-csharp[HowToGeneric#11](snippets/csharp/instantiate-generic-type/GenericTypes.cs#11)] [!code-vb[HowToGeneric#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToGeneric/VB/ur.vb#11)] -3. Call the method to bind the type arguments to the type parameters and construct the type. +3. Call the method to bind the type arguments to the type parameters and construct the type. [!code-csharp[HowToGeneric#12](snippets/csharp/instantiate-generic-type/GenericTypes.cs#12)] [!code-vb[HowToGeneric#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToGeneric/VB/ur.vb#12)] @@ -83,13 +83,13 @@ A generic type is like a template. You can't create instances of it unless you s ## Example -The following code example defines a `DisplayGenericType` method to examine the generic type definitions and constructed types used in the code and display their information. The `DisplayGenericType` method shows how to use the , , and properties and the method. +The following code example defines a `DisplayGenericType` method to examine the generic type definitions and constructed types used in the code and display their information. The `DisplayGenericType` method shows how to use the , , and properties and the method. The example also defines a `DisplayGenericParameter` method to examine a generic type parameter and display its constraints. The code example defines a set of test types, including a generic type that illustrates type parameter constraints, and shows how to display information about these types. -The example constructs a type from the class by creating an array of type arguments and calling the method. The program compares the object constructed using with a object obtained using `typeof` (`GetType` in Visual Basic), demonstrating that they are the same. Similarly, the program uses the method to obtain the generic type definition of the constructed type, and compares it to the object representing the class. +The example constructs a type from the class by creating an array of type arguments and calling the method. The program compares the object constructed using with a object obtained using `typeof` (`GetType` in Visual Basic), demonstrating that they are the same. Similarly, the program uses the method to obtain the generic type definition of the constructed type, and compares it to the object representing the class. [!code-csharp[HowToGeneric#1](snippets/csharp/instantiate-generic-type/GenericTypes.cs#1)] [!code-vb[HowToGeneric#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToGeneric/VB/ur.vb#1)] diff --git a/docs/fundamentals/reflection/how-to-hook-up-a-delegate-using-reflection.md b/docs/fundamentals/reflection/how-to-hook-up-a-delegate-using-reflection.md index ee0d0e816fd4b..b74babdfbd2a9 100644 --- a/docs/fundamentals/reflection/how-to-hook-up-a-delegate-using-reflection.md +++ b/docs/fundamentals/reflection/how-to-hook-up-a-delegate-using-reflection.md @@ -15,16 +15,16 @@ helpviewer_keywords: When you use reflection to load and run assemblies, you can't use language features like the C# `+=` operator or the Visual Basic [AddHandler statement](../../visual-basic/language-reference/statements/addhandler-statement.md) to hook up events. The following procedures show how to hook up an existing method to an event by getting all the necessary types through reflection, and how to create a dynamic method using reflection emit and hook it up to an event. > [!NOTE] -> For another way to hook up an event-handling delegate, see the code example for the method of the class. +> For another way to hook up an event-handling delegate, see the code example for the method of the class. ## To hook up a delegate using reflection -1. Load an assembly that contains a type that raises events. Assemblies are usually loaded with the method. To keep this example simple, a derived form in the current assembly is used, so the method is used to load the current assembly. +1. Load an assembly that contains a type that raises events. Assemblies are usually loaded with the method. To keep this example simple, a derived form in the current assembly is used, so the method is used to load the current assembly. [!code-csharp[HookUpDelegate#3](../../../samples/snippets/csharp/VS_Snippets_CLR/HookUpDelegate/cs/source.cs#3)] [!code-vb[HookUpDelegate#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HookUpDelegate/vb/source.vb#3)] -2. Get a object representing the type, and create an instance of the type. The method is used in the following code because the form has a parameterless constructor. There are several other overloads of the method that you can use if the type you are creating does not have a parameterless constructor. The new instance is stored as type to maintain the fiction that nothing is known about the assembly. (Reflection allows you to get the types in an assembly without knowing their names in advance.) +2. Get a object representing the type, and create an instance of the type. The method is used in the following code because the form has a parameterless constructor. There are several other overloads of the method that you can use if the type you are creating does not have a parameterless constructor. The new instance is stored as type to maintain the fiction that nothing is known about the assembly. (Reflection allows you to get the types in an assembly without knowing their names in advance.) [!code-csharp[HookUpDelegate#4](../../../samples/snippets/csharp/VS_Snippets_CLR/HookUpDelegate/cs/source.cs#4)] [!code-vb[HookUpDelegate#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HookUpDelegate/vb/source.vb#4)] @@ -39,7 +39,7 @@ When you use reflection to load and run assemblies, you can't use language featu [!code-csharp[HookUpDelegate#6](../../../samples/snippets/csharp/VS_Snippets_CLR/HookUpDelegate/cs/source.cs#6)] [!code-vb[HookUpDelegate#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HookUpDelegate/vb/source.vb#6)] -5. Create an instance of the delegate, using the method. This method is static (`Shared` in Visual Basic), so the delegate type must be supplied. Using the overloads of that take a is recommended. +5. Create an instance of the delegate, using the method. This method is static (`Shared` in Visual Basic), so the delegate type must be supplied. Using the overloads of that take a is recommended. [!code-csharp[HookUpDelegate#7](../../../samples/snippets/csharp/VS_Snippets_CLR/HookUpDelegate/cs/source.cs#7)] [!code-vb[HookUpDelegate#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HookUpDelegate/vb/source.vb#7)] @@ -63,12 +63,12 @@ When you use reflection to load and run assemblies, you can't use language featu [!code-csharp[HookUpDelegate#9](../../../samples/snippets/csharp/VS_Snippets_CLR/HookUpDelegate/cs/source.cs#9)] [!code-vb[HookUpDelegate#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HookUpDelegate/vb/source.vb#9)] -2. Generate a method body. This method loads a string, calls the overload of the method that takes a string, pops the return value off the stack (because the handler has no return type), and returns. To learn more about emitting dynamic methods, see [How to: Define and Execute Dynamic Methods](how-to-define-and-execute-dynamic-methods.md). +2. Generate a method body. This method loads a string, calls the overload of the method that takes a string, pops the return value off the stack (because the handler has no return type), and returns. To learn more about emitting dynamic methods, see [How to: Define and Execute Dynamic Methods](how-to-define-and-execute-dynamic-methods.md). [!code-csharp[HookUpDelegate#10](../../../samples/snippets/csharp/VS_Snippets_CLR/HookUpDelegate/cs/source.cs#10)] [!code-vb[HookUpDelegate#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HookUpDelegate/vb/source.vb#10)] -3. Complete the dynamic method by calling its method. Use the `add` accessor to add the delegate to the invocation list for the event. +3. Complete the dynamic method by calling its method. Use the `add` accessor to add the delegate to the invocation list for the event. [!code-csharp[HookUpDelegate#11](../../../samples/snippets/csharp/VS_Snippets_CLR/HookUpDelegate/cs/source.cs#11)] [!code-vb[HookUpDelegate#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HookUpDelegate/vb/source.vb#11)] @@ -87,9 +87,9 @@ The following code example shows how to hook up an existing method to an event u ## See also -- +- - -- -- +- +- - [How to: Define and Execute Dynamic Methods](how-to-define-and-execute-dynamic-methods.md) - [Reflection](overview.md) diff --git a/docs/fundamentals/reflection/overview.md b/docs/fundamentals/reflection/overview.md index c322238fd45d1..35033f3f6edee 100644 --- a/docs/fundamentals/reflection/overview.md +++ b/docs/fundamentals/reflection/overview.md @@ -32,8 +32,8 @@ The classes in the namespace, together with to define and load assemblies, load modules that are listed in the assembly manifest, and locate a type from this assembly and create an instance of it. - Use to discover information such as the assembly that contains the module and the classes in the module. You can also get all global methods or other specific, non-global methods defined on the module. -- Use to discover information such as the name, parameters, access modifiers (such as `public` or `private`), and implementation details (such as `abstract` or `virtual`) of a constructor. Use the or method of a to invoke a specific constructor. -- Use to discover information such as the name, return type, parameters, access modifiers, and implementation details (such as `abstract` or `virtual`) of a method. Use the or method of a to invoke a specific method. +- Use to discover information such as the name, parameters, access modifiers (such as `public` or `private`), and implementation details (such as `abstract` or `virtual`) of a constructor. Use the or method of a to invoke a specific constructor. +- Use to discover information such as the name, return type, parameters, access modifiers, and implementation details (such as `abstract` or `virtual`) of a method. Use the or method of a to invoke a specific method. - Use to discover information such as the name, access modifiers, and implementation details (such as `static`) of a field, and to get or set field values. - Use to discover information such as the name, event-handler data type, custom attributes, declaring type, and reflected type of an event, and to add or remove event handlers. - Use to discover information such as the name, data type, declaring type, reflected type, and read-only or writable status of a property, and to get or set property values. diff --git a/docs/fundamentals/reflection/reflection-and-generic-types.md b/docs/fundamentals/reflection/reflection-and-generic-types.md index c8f383930c106..ce610ba1e7f39 100644 --- a/docs/fundamentals/reflection/reflection-and-generic-types.md +++ b/docs/fundamentals/reflection/reflection-and-generic-types.md @@ -25,7 +25,7 @@ There are two keys to understanding how reflection handles generic types and met - The type parameters of generic type definitions and generic method definitions are represented by instances of the class. > [!NOTE] - > Many properties and methods of have different behavior when a object represents a generic type parameter. These differences are documented in the property and method articles. For example, see and . In addition, some members are valid only when a object represents a generic type parameter. For example, see . + > Many properties and methods of have different behavior when a object represents a generic type parameter. These differences are documented in the property and method articles. For example, see and . In addition, some members are valid only when a object represents a generic type parameter. For example, see . - If an instance of represents a generic type, then it includes an array of types that represent the type parameters (for generic type definitions) or the type arguments (for constructed types). The same is true of an instance of the class that represents a generic method. @@ -37,39 +37,39 @@ The following discussion assumes familiarity with the terminology of generics, s ## Is this a generic type or method? -When you use reflection to examine an unknown type, represented by an instance of , use the property to determine whether the unknown type is generic. It returns `true` if the type is generic. Similarly, when you examine an unknown method, represented by an instance of the class, use the property to determine whether the method is generic. +When you use reflection to examine an unknown type, represented by an instance of , use the property to determine whether the unknown type is generic. It returns `true` if the type is generic. Similarly, when you examine an unknown method, represented by an instance of the class, use the property to determine whether the method is generic. ## Is this a generic type or method definition? -Use the property to determine whether a object represents a generic type definition, and use the method to determine whether a represents a generic method definition. +Use the property to determine whether a object represents a generic type definition, and use the method to determine whether a represents a generic method definition. -Generic type and method definitions are the templates from which instantiable types are created. Generic types in the .NET libraries, such as , are generic type definitions. +Generic type and method definitions are the templates from which instantiable types are created. Generic types in the .NET libraries, such as , are generic type definitions. ## Is the type or method open or closed? -A generic type or method is closed if instantiable types have been substituted for all its type parameters, including all the type parameters of all enclosing types. You can only create an instance of a generic type if it's closed. The property returns `true` if a type is open. For methods, the method performs the same function. +A generic type or method is closed if instantiable types have been substituted for all its type parameters, including all the type parameters of all enclosing types. You can only create an instance of a generic type if it's closed. The property returns `true` if a type is open. For methods, the method performs the same function. ## Generate closed generic types -Once you have a generic type or method definition, use the method to create a closed generic type or the method to create a for a closed generic method. +Once you have a generic type or method definition, use the method to create a closed generic type or the method to create a for a closed generic method. ### Get the generic type or method definition -If you have an open generic type or method that's not a generic type or method definition, you cannot create instances of it and you cannot supply the type parameters that are missing. You must have a generic type or method definition. Use the method to obtain the generic type definition or the method to obtain the generic method definition. +If you have an open generic type or method that's not a generic type or method definition, you cannot create instances of it and you cannot supply the type parameters that are missing. You must have a generic type or method definition. Use the method to obtain the generic type definition or the method to obtain the generic method definition. -For example, if you have a object representing `Dictionary` and you want to create the type `Dictionary`, you can use the method to get a representing `Dictionary` and then use the method to produce a representing `Dictionary`. +For example, if you have a object representing `Dictionary` and you want to create the type `Dictionary`, you can use the method to get a representing `Dictionary` and then use the method to produce a representing `Dictionary`. For an example of an open generic type that is not a generic type, see [Type parameter or type argument](#type-parameter-or-type-argument). ## Examine type arguments and type parameters -Use the method to obtain an array of objects that represent the type parameters or type arguments of a generic type, and use the method to do the same for a generic method. +Use the method to obtain an array of objects that represent the type parameters or type arguments of a generic type, and use the method to do the same for a generic method. Once you know that a object represents a type parameter, there are many additional questions reflection can answer. You can determine the type parameter's source, its position, and its constraints. ### Type parameter or type argument -To determine whether a particular element of the array is a type parameter or a type argument, use the property. The property is `true` if the element is a type parameter. +To determine whether a particular element of the array is a type parameter or a type argument, use the property. The property is `true` if the element is a type parameter. A generic type can be open without being a generic type definition, in which case it has a mixture of type arguments and type parameters. For example, in the following code, class `D` derives from a type created by substituting the first type parameter of `D` for the second type parameter of `B`. @@ -99,11 +99,11 @@ If the type parameter belongs to a generic method, the object representing the `B` type from the preceding example. The method gives you a list of type arguments, and when you examine `V` you can use the and properties to discover where it comes from. You can then use the property to determine its position in the type parameter list where it was defined. In this example, `V` is at position 0 (zero) in the type parameter list where it was defined. +In rare situations, it's necessary to determine the position of a type parameter in the type parameter list of its declaring class. For example, suppose you have a object representing the `B` type from the preceding example. The method gives you a list of type arguments, and when you examine `V` you can use the and properties to discover where it comes from. You can then use the property to determine its position in the type parameter list where it was defined. In this example, `V` is at position 0 (zero) in the type parameter list where it was defined. ### Base type and interface constraints -Use the method to obtain the base type constraint and interface constraints of a type parameter. The order of the elements of the array is not significant. An element represents an interface constraint if it's an interface type. +Use the method to obtain the base type constraint and interface constraints of a type parameter. The order of the elements of the array is not significant. An element represents an interface constraint if it's an interface type. ### Generic parameter attributes @@ -119,4 +119,4 @@ To determine the special constraints of a type parameter, apply the . For additional terms relating to generic methods, see . +For a table of the invariant conditions for common terms in reflection for generic types, see . For additional terms relating to generic methods, see . diff --git a/docs/fundamentals/reflection/specifying-fully-qualified-type-names.md b/docs/fundamentals/reflection/specifying-fully-qualified-type-names.md index ddd64225f1673..5f05df55dd3de 100644 --- a/docs/fundamentals/reflection/specifying-fully-qualified-type-names.md +++ b/docs/fundamentals/reflection/specifying-fully-qualified-type-names.md @@ -20,7 +20,7 @@ ms.assetid: d90b1e39-9115-4f2a-81c0-05e7e74e5580 # Specify fully qualified type names -You must specify type names to have valid input to various reflection operations. A fully qualified type name consists of an assembly name specification, a namespace specification, and a type name. Type name specifications are used by methods such as , , , and . +You must specify type names to have valid input to various reflection operations. A fully qualified type name consists of an assembly name specification, a namespace specification, and a type name. Type name specifications are used by methods such as , , , and . ## Grammar for type names @@ -140,7 +140,7 @@ Use the backslash (\\) as an escape character to separate the following tokens w In all TypeSpec components except AssemblyNameSpec, spaces are relevant. In the AssemblyNameSpec, spaces before the ',' separator are relevant, but spaces after the ',' separator are ignored. -Reflection classes, such as , return the mangled name so that the returned name can be used in a call to , as in `MyType.GetType(myType.FullName)`. +Reflection classes, such as , return the mangled name so that the returned name can be used in a call to , as in `MyType.GetType(myType.FullName)`. For example, the fully qualified name for a type might be `Ozzy.OutBack.Kangaroo+Wallaby,MyAssembly`. @@ -224,7 +224,7 @@ SimpleTypeSpec & represents a managed pointer or reference. For example, to get ## Specify arrays -In the BNF Grammar, ReflectionEmitDimension only applies to incomplete type definitions retrieved using . Incomplete type definitions are objects constructed using but on which has not been called. ReflectionDimension can be used to retrieve any type definition that has been completed, that is, a type that has been loaded. +In the BNF Grammar, ReflectionEmitDimension only applies to incomplete type definitions retrieved using . Incomplete type definitions are objects constructed using but on which has not been called. ReflectionDimension can be used to retrieve any type definition that has been completed, that is, a type that has been loaded. Arrays are accessed in reflection by specifying the rank of the array: @@ -243,6 +243,6 @@ For `ModuleBuilder.GetType`, `MyArray[0..5]` indicates a single-dimension array - - - -- +- - - [View type information](viewing-type-information.md) diff --git a/docs/fundamentals/reflection/viewing-type-information.md b/docs/fundamentals/reflection/viewing-type-information.md index 01e35fcd8d614..80db326a008b5 100644 --- a/docs/fundamentals/reflection/viewing-type-information.md +++ b/docs/fundamentals/reflection/viewing-type-information.md @@ -15,7 +15,7 @@ helpviewer_keywords: The class is central to reflection. The common language runtime creates the `Type` for a loaded type when reflection requests it. You can use a `Type` object's methods, fields, properties, and nested classes to find out everything about that type. -Use or to obtain `Type` objects from assemblies that have not been loaded, passing in the name of the type or types you want. Use to get the `Type` objects from an assembly that is already loaded. Use and to obtain module `Type` objects. +Use or to obtain `Type` objects from assemblies that have not been loaded, passing in the name of the type or types you want. Use to get the `Type` objects from an assembly that is already loaded. Use and to obtain module `Type` objects. > [!NOTE] > If you want to examine and manipulate generic types and methods, please see the additional information provided in [Reflection and Generic Types](reflection-and-generic-types.md) and [How to: Examine and Instantiate Generic Types with Reflection](how-to-examine-and-instantiate-generic-types-with-reflection.md). @@ -30,9 +30,9 @@ The following example demonstrates getting `Type` objects from a loaded assembly [!code-csharp[Conceptual.Types.ViewInfo#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.types.viewinfo/cs/source5.cs#7)] [!code-vb[Conceptual.Types.ViewInfo#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.types.viewinfo/vb/source5.vb#7)] -Once you obtain a `Type`, there are many ways you can discover information about the members of that type. For example, you can find out about all the type's members by calling the method, which obtains an array of objects describing each of the members of the current type. +Once you obtain a `Type`, there are many ways you can discover information about the members of that type. For example, you can find out about all the type's members by calling the method, which obtains an array of objects describing each of the members of the current type. -You can also use methods on the `Type` class to retrieve information about one or more constructors, methods, events, fields, or properties that you specify by name. For example, encapsulates a specific constructor of the current class. +You can also use methods on the `Type` class to retrieve information about one or more constructors, methods, events, fields, or properties that you specify by name. For example, encapsulates a specific constructor of the current class. If you have a `Type`, you can use the property to obtain an object that encapsulates the module containing that type. Use the property to locate an object that encapsulates the assembly containing the module. You can obtain the assembly that encapsulates the type directly by using the property. @@ -47,7 +47,7 @@ The following example shows how to list the constructors for a class, in this ca Obtain information about the type's methods, properties, events, and fields using , , , or objects. -The following example uses `MemberInfo` to list the number of members in the `System.IO.File` class and uses the property to determine the visibility of the class. +The following example uses `MemberInfo` to list the number of members in the `System.IO.File` class and uses the property to determine the visibility of the class. [!code-csharp[Conceptual.Types.ViewInfo#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.types.viewinfo/cs/source2.cs#2)] [!code-vb[Conceptual.Types.ViewInfo#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.types.viewinfo/vb/source2.vb#2)] diff --git a/docs/fundamentals/runtime-libraries/system-collections-generic-list{t}.md b/docs/fundamentals/runtime-libraries/system-collections-generic-list{t}.md index c20b8677fadf3..409cfee48c557 100644 --- a/docs/fundamentals/runtime-libraries/system-collections-generic-list{t}.md +++ b/docs/fundamentals/runtime-libraries/system-collections-generic-list{t}.md @@ -17,9 +17,9 @@ You can add items to a by using the class uses both an equality comparer and an ordering comparer. -- Methods such as , , , and use an equality comparer for the list elements. The default equality comparer for type `T` is determined as follows. If type `T` implements the generic interface, then the equality comparer is the method of that interface; otherwise, the default equality comparer is . +- Methods such as , , , and use an equality comparer for the list elements. The default equality comparer for type `T` is determined as follows. If type `T` implements the generic interface, then the equality comparer is the method of that interface; otherwise, the default equality comparer is . -- Methods such as and use an ordering comparer for the list elements. The default comparer for type `T` is determined as follows. If type `T` implements the generic interface, then the default comparer is the method of that interface; otherwise, if type `T` implements the nongeneric interface, then the default comparer is the method of that interface. If type `T` implements neither interface, then there is no default comparer, and a comparer or comparison delegate must be provided explicitly. +- Methods such as and use an ordering comparer for the list elements. The default comparer for type `T` is determined as follows. If type `T` implements the generic interface, then the default comparer is the method of that interface; otherwise, if type `T` implements the nongeneric interface, then the default comparer is the method of that interface. If type `T` implements neither interface, then there is no default comparer, and a comparer or comparison delegate must be provided explicitly. The is not guaranteed to be sorted. You must sort the before performing operations (such as ) that require the to be sorted. diff --git a/docs/fundamentals/runtime-libraries/system-console.md b/docs/fundamentals/runtime-libraries/system-console.md index 4dc27524e30f3..b44e1b2b98d4d 100644 --- a/docs/fundamentals/runtime-libraries/system-console.md +++ b/docs/fundamentals/runtime-libraries/system-console.md @@ -22,7 +22,7 @@ By default, the value of the property is a [!NOTE] > Do not use the class to display output in unattended applications, such as server applications. Calls to methods such as and have no effect in GUI applications. - class members that work normally when the underlying stream is directed to a console might throw an exception if the stream is redirected, for example, to a file. Program your application to catch exceptions if you redirect a standard stream. You can also use the , , and properties to determine whether a standard stream is redirected before performing an operation that throws an exception. + class members that work normally when the underlying stream is directed to a console might throw an exception if the stream is redirected, for example, to a file. Program your application to catch exceptions if you redirect a standard stream. You can also use the , , and properties to determine whether a standard stream is redirected before performing an operation that throws an exception. It is sometimes useful to explicitly call the members of the stream objects represented by the , , and properties. For example, by default, the method reads input from the standard input stream. Similarly, the method writes data to the standard output stream, and the data is followed by the default line termination string, which can be found at . However, the class does not provide a corresponding method to write data to the standard error output stream, or a property to change the line termination string for data written to that stream. diff --git a/docs/fundamentals/runtime-libraries/system-enum.md b/docs/fundamentals/runtime-libraries/system-enum.md index febd9bbaff0e2..8117cb3b75796 100644 --- a/docs/fundamentals/runtime-libraries/system-enum.md +++ b/docs/fundamentals/runtime-libraries/system-enum.md @@ -100,7 +100,7 @@ Although the class provides explicit interface implementation ### Parse enumeration values -The and methods allow you to convert the string representation of an enumeration value to that value. The string representation can be either the name or the underlying value of an enumeration constant. Note that the parsing methods will successfully convert string representations of numbers that are not members of a particular enumeration if the strings can be converted to a value of the enumeration's underlying type. To prevent this, the method can be called to ensure that the result of the parsing method is a valid enumeration value. The example illustrates this approach and demonstrates calls to both the and methods. Note that the non-generic parsing method returns an object that you may have to cast (in C# and F#) or convert (in Visual Basic) to the appropriate enumeration type. +The and methods allow you to convert the string representation of an enumeration value to that value. The string representation can be either the name or the underlying value of an enumeration constant. Note that the parsing methods will successfully convert string representations of numbers that are not members of a particular enumeration if the strings can be converted to a value of the enumeration's underlying type. To prevent this, the method can be called to ensure that the result of the parsing method is a valid enumeration value. The example illustrates this approach and demonstrates calls to both the and methods. Note that the non-generic parsing method returns an object that you may have to cast (in C# and F#) or convert (in Visual Basic) to the appropriate enumeration type. :::code language="csharp" source="./snippets/System/Enum/Overview/csharp/classparse1.cs" id="Snippet9"::: :::code language="fsharp" source="./snippets/System/Enum/Overview/fsharp/classparse1.fs" id="Snippet9"::: diff --git a/docs/fundamentals/runtime-libraries/system-globalization-compareinfo.md b/docs/fundamentals/runtime-libraries/system-globalization-compareinfo.md index 5a61525e11265..0d7233dc9aa78 100644 --- a/docs/fundamentals/runtime-libraries/system-globalization-compareinfo.md +++ b/docs/fundamentals/runtime-libraries/system-globalization-compareinfo.md @@ -12,7 +12,7 @@ Conventions for comparing and sorting data vary from culture to culture. For exa Typically, you do not have to instantiate a object directly, because one is used implicitly by all non-ordinal string comparison operations, including calls to the method. However, if you do want to retrieve a object, you can do it in one of these ways: -- By retrieving the value of the property for a particular culture. +- By retrieving the value of the property for a particular culture. - By calling the static method with a culture name. This allows for late-bound access to a object. diff --git a/docs/fundamentals/runtime-libraries/system-globalization-cultureinfo-currentculture.md b/docs/fundamentals/runtime-libraries/system-globalization-cultureinfo-currentculture.md index 6ff34fbd18d73..16b09529cfd41 100644 --- a/docs/fundamentals/runtime-libraries/system-globalization-cultureinfo-currentculture.md +++ b/docs/fundamentals/runtime-libraries/system-globalization-cultureinfo-currentculture.md @@ -57,7 +57,7 @@ Starting with .NET Framework 4, you can explicitly change the current thread cul :::code language="csharp" source="./snippets/System.Globalization/CultureInfo/CurrentCulture/csharp/specific12.cs" id="Snippet12"::: :::code language="vb" source="./snippets/System.Globalization/CultureInfo/CurrentCulture/vb/specific12.vb" id="Snippet12"::: -You can also use the property along with the property to set the property of an ASP.NET application to the user's preferred culture, as the following example illustrates. +You can also use the property along with the property to set the property of an ASP.NET application to the user's preferred culture, as the following example illustrates. :::code language="csharp" source="./snippets/System.Globalization/CultureInfo/CurrentCulture/csharp/aspculture13.cs" id="Snippet13"::: :::code language="vb" source="./snippets/System.Globalization/CultureInfo/CurrentCulture/vb/aspculture13.vb" id="Snippet13"::: diff --git a/docs/fundamentals/runtime-libraries/system-globalization-datetimeformatinfo.md b/docs/fundamentals/runtime-libraries/system-globalization-datetimeformatinfo.md index 5ace5917514a3..9d5976795dbf0 100644 --- a/docs/fundamentals/runtime-libraries/system-globalization-datetimeformatinfo.md +++ b/docs/fundamentals/runtime-libraries/system-globalization-datetimeformatinfo.md @@ -99,7 +99,7 @@ The culture-specific data for formatting date and time values provided by the data to change. For example, the current culture can be changed either programmatically or through user action. When this happens, the object returned by the property changes to an object associated with the current culture. Similarly, a culture's calendar can change, which can result in changes to numerous property values. -- User preferences. Users of your application might choose to override some of the values associated with the current system culture through the regional and language options in Control Panel. For example, users might choose to display the date in a different format. If the property is set to `true`, the properties of the object is also retrieved from the user settings. If the user settings are incompatible with the culture associated with the object (for example, if the selected calendar is not one of the calendars indicated by the property), the results of the methods and the values of the properties are undefined. +- User preferences. Users of your application might choose to override some of the values associated with the current system culture through the regional and language options in Control Panel. For example, users might choose to display the date in a different format. If the property is set to `true`, the properties of the object is also retrieved from the user settings. If the user settings are incompatible with the culture associated with the object (for example, if the selected calendar is not one of the calendars indicated by the property), the results of the methods and the values of the properties are undefined. To minimize the possibility of inconsistent data, all user-overridable properties of a object are initialized when the object is created. There is still a possibility of inconsistency, because neither object creation nor the user override process is atomic and the relevant values can change during object creation. However, this situation should be extremely rare. diff --git a/docs/fundamentals/runtime-libraries/system-globalization-numberformatinfo.md b/docs/fundamentals/runtime-libraries/system-globalization-numberformatinfo.md index 1bf0ee2558d42..ba0c41f1c1443 100644 --- a/docs/fundamentals/runtime-libraries/system-globalization-numberformatinfo.md +++ b/docs/fundamentals/runtime-libraries/system-globalization-numberformatinfo.md @@ -96,7 +96,7 @@ The culture-specific data for formatting numeric values provided by the data to change. For example, the current culture can be changed either programmatically or through user action. When this happens, the object returned by the property changes to an object associated with the current culture. -- **User preferences.** Users of your application might override some of the values associated with the current system culture through the region and language options in Control Panel. For example, users might choose a different currency symbol or a different decimal separator symbol. If the property is set to `true` (its default value), the properties of the object are also retrieved from the user settings. +- **User preferences.** Users of your application might override some of the values associated with the current system culture through the region and language options in Control Panel. For example, users might choose a different currency symbol or a different decimal separator symbol. If the property is set to `true` (its default value), the properties of the object are also retrieved from the user settings. All user-overridable properties of a object are initialized when the object is created. There is still a possibility of inconsistency, because neither object creation nor the user override process is atomic, and the relevant values may change during object creation. However, these inconsistencies should be extremely rare. diff --git a/docs/fundamentals/runtime-libraries/system-globalization-sortkey.md b/docs/fundamentals/runtime-libraries/system-globalization-sortkey.md index 655c177067f0e..74d5987ea8a7f 100644 --- a/docs/fundamentals/runtime-libraries/system-globalization-sortkey.md +++ b/docs/fundamentals/runtime-libraries/system-globalization-sortkey.md @@ -35,7 +35,7 @@ Use the following steps to obtain a sort key: 1. Retrieve the invariant culture from the property. -2. Retrieve a object for the invariant culture from the property. +2. Retrieve a object for the invariant culture from the property. 3. Call the method. diff --git a/docs/fundamentals/runtime-libraries/system-invalidoperationexception.md b/docs/fundamentals/runtime-libraries/system-invalidoperationexception.md index 63fd9c1318752..1bf217c09d2f3 100644 --- a/docs/fundamentals/runtime-libraries/system-invalidoperationexception.md +++ b/docs/fundamentals/runtime-libraries/system-invalidoperationexception.md @@ -116,7 +116,7 @@ You can eliminate the exception in any of three ways: - If you cannot modify the source code for the type you are trying to sort, you can define a special-purpose sorting class that implements the interface. You can call an overload of the `Sort` method that includes an parameter. This approach is especially useful if you want to develop a specialized sorting class that can sort objects based on multiple criteria. - The following example uses the approach by developing a custom `PersonComparer` class that is used to sort `Person` collections. It then passes an instance of this class to the method. + The following example uses the approach by developing a custom `PersonComparer` class that is used to sort `Person` collections. It then passes an instance of this class to the method. :::code language="csharp" source="./snippets/System/InvalidOperationException/Overview/csharp/Other/List_Sort3.cs" id="Snippet14"::: :::code language="fsharp" source="./snippets/System/InvalidOperationException/Overview/fsharp/List_Sort3.fs" id="Snippet14"::: @@ -132,7 +132,7 @@ You can eliminate the exception in any of three ways: int Comparison(T x, T y) ``` - The following example uses the approach by defining a `PersonComparison` method that matches the delegate signature. It then passes this delegate to the method. + The following example uses the approach by defining a `PersonComparison` method that matches the delegate signature. It then passes this delegate to the method. :::code language="csharp" source="./snippets/System/InvalidOperationException/Overview/csharp/Other/List_Sort4.cs" id="Snippet15"::: :::code language="fsharp" source="./snippets/System/InvalidOperationException/Overview/fsharp/List_Sort4.fs" id="Snippet15"::: @@ -181,7 +181,7 @@ How you eliminate or handle the exception depends on your application's assumpti - If your failure to check for an empty sequence was inadvertent, you can call one of the overloads of the overload to determine whether a sequence contains any elements. > [!TIP] - > Calling the method before generating a sequence can improve performance if the data to be processed might contain a large number of elements or if operation that generates the sequence is expensive. + > Calling the method before generating a sequence can improve performance if the data to be processed might contain a large number of elements or if operation that generates the sequence is expensive. - If you've called a method such as , , or , you can substitute an alternate method, such as , , or , that returns a default value instead of a member of the sequence. @@ -201,7 +201,7 @@ The exception can be eliminated by calling the method returns the first item in a sequence or the first element in a sequence that satisfies a specified condition. If the sequence is empty and therefore does not have a first element, it throws an exception. -In the following example, the method throws an exception because the dbQueryResults array doesn't contain an element greater than 4. +In the following example, the method throws an exception because the dbQueryResults array doesn't contain an element greater than 4. :::code language="csharp" source="./snippets/System/InvalidOperationException/Overview/csharp/Other/Enumerable3.cs" id="Snippet8"::: :::code language="fsharp" source="./snippets/System/InvalidOperationException/Overview/fsharp/Enumerable3.fs" id="Snippet8"::: @@ -212,7 +212,7 @@ You can call the [!NOTE] > Interpreting the value returned by the method is often complicated by the fact that the default value of the type can be a valid value in the sequence. In this case, you an call the method to determine whether the sequence has valid members before calling the method. -The following example calls the method to prevent the exception thrown in the previous example. +The following example calls the method to prevent the exception thrown in the previous example. :::code language="csharp" source="./snippets/System/InvalidOperationException/Overview/csharp/Other/Enumerable4.cs" id="Snippet9"::: :::code language="fsharp" source="./snippets/System/InvalidOperationException/Overview/fsharp/Enumerable4.fs" id="Snippet9"::: diff --git a/docs/fundamentals/runtime-libraries/system-linq-expressions-expression-add.md b/docs/fundamentals/runtime-libraries/system-linq-expressions-expression-add.md index 1856b5edea920..bcaeffc639fcf 100644 --- a/docs/fundamentals/runtime-libraries/system-linq-expressions-expression-add.md +++ b/docs/fundamentals/runtime-libraries/system-linq-expressions-expression-add.md @@ -7,7 +7,7 @@ ms.date: 01/24/2024 [!INCLUDE [context](includes/context.md)] -The method returns a that has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. +The method returns a that has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. diff --git a/docs/fundamentals/runtime-libraries/system-net-httplistener.md b/docs/fundamentals/runtime-libraries/system-net-httplistener.md index ff42dd78c96f4..2ab06509f7bf2 100644 --- a/docs/fundamentals/runtime-libraries/system-net-httplistener.md +++ b/docs/fundamentals/runtime-libraries/system-net-httplistener.md @@ -45,7 +45,7 @@ The class is built on top of `HTTP.sys`, which is `HTTP.sys` provides connection management, bandwidth throttling, and web server logging. Use the [HttpCfg.exe](/windows/win32/http/httpcfg-exe) tool to add SSL certificates. -Starting in .NET 11, the Windows `HTTP.sys` implementation of supports enabling kernel-level response buffering. When enabled, response data is buffered by `HTTP.sys` before being sent to the client, which can improve throughput for high-latency connections. This can be enabled by calling the method as follows: +Starting in .NET 11, the Windows `HTTP.sys` implementation of supports enabling kernel-level response buffering. When enabled, response data is buffered by `HTTP.sys` before being sent to the client, which can improve throughput for high-latency connections. This can be enabled by calling the method as follows: ```csharp AppContext.SetSwitch("System.Net.HttpListener.EnableKernelResponseBuffering", true); diff --git a/docs/fundamentals/runtime-libraries/system-object-gethashcode.md b/docs/fundamentals/runtime-libraries/system-object-gethashcode.md index a65d98b56bfe3..7f15850440dd5 100644 --- a/docs/fundamentals/runtime-libraries/system-object-gethashcode.md +++ b/docs/fundamentals/runtime-libraries/system-object-gethashcode.md @@ -58,7 +58,7 @@ Frequently, a type has multiple data fields that can participate in generating t :::code language="fsharp" source="./snippets/System/Object/GetHashCode/fsharp/xor1.fs" id="Snippet2"::: :::code language="vb" source="./snippets/System/Object/GetHashCode/vb/xor1.vb" id="Snippet2"::: -The previous example returns the same hash code for (n1, n2) and (n2, n1), and so it might generate more collisions than are desirable. On .NET 5+, the recommended solution is to use . It avoids the symmetry problem and produces a well-distributed hash code without the overhead of creating a `Tuple` object. +The previous example returns the same hash code for (n1, n2) and (n2, n1), and so it might generate more collisions than are desirable. On .NET 5+, the recommended solution is to use . It avoids the symmetry problem and produces a well-distributed hash code without the overhead of creating a `Tuple` object. :::code language="csharp" source="./snippets/System/Object/GetHashCode/csharp/xor2.cs" id="Snippet3"::: :::code language="fsharp" source="./snippets/System/Object/GetHashCode/fsharp/xor2.fs" id="Snippet3"::: diff --git a/docs/fundamentals/runtime-libraries/system-reflection-context-customreflectioncontext.md b/docs/fundamentals/runtime-libraries/system-reflection-context-customreflectioncontext.md index 4a0c4689f0480..a40f8a724451f 100644 --- a/docs/fundamentals/runtime-libraries/system-reflection-context-customreflectioncontext.md +++ b/docs/fundamentals/runtime-libraries/system-reflection-context-customreflectioncontext.md @@ -17,14 +17,14 @@ To use effectively, the To modify the attributes that are applied to a reflected parameter or member, override the or method. These methods take the reflected object and the list of attributes under its current reflection context, and return the list of attributes it should have under the custom reflection context. > [!WARNING] -> methods should not access the list of attributes of a reflected object or method directly by calling the method on the provided or instance, but should instead use the `declaredAttributes` list, which is passed as a parameter to the method overloads. +> methods should not access the list of attributes of a reflected object or method directly by calling the method on the provided or instance, but should instead use the `declaredAttributes` list, which is passed as a parameter to the method overloads. -To add properties to a reflected type, override the method. The method accepts a parameter that specifies the reflected type, and returns a list of additional properties. You should use the method to create property objects to return. You can specify delegates when creating the property that serve as the property accessor, and you can omit one of the accessors to create a read-only or write-only property. Note that such dummy properties have no metadata or Common Intermediate Language (CIL) backing. +To add properties to a reflected type, override the method. The method accepts a parameter that specifies the reflected type, and returns a list of additional properties. You should use the method to create property objects to return. You can specify delegates when creating the property that serve as the property accessor, and you can omit one of the accessors to create a read-only or write-only property. Note that such dummy properties have no metadata or Common Intermediate Language (CIL) backing. > [!WARNING] > -> - Be cautious about equality among reflected objects when you work with reflection contexts, because objects might represent the same reflected object in multiple contexts. You can use the method to obtain a particular reflection context's version of a reflected object. -> - A object alters the attributes returned by a particular reflection object, such as those obtained by the method. It doesn't alter the custom attribute data returned by the method, and these two lists won't match when you use a custom reflection context. +> - Be cautious about equality among reflected objects when you work with reflection contexts, because objects might represent the same reflected object in multiple contexts. You can use the method to obtain a particular reflection context's version of a reflected object. +> - A object alters the attributes returned by a particular reflection object, such as those obtained by the method. It doesn't alter the custom attribute data returned by the method, and these two lists won't match when you use a custom reflection context. ## Example diff --git a/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicilinfo.md b/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicilinfo.md index 154e1c1aac1b9..60069de84f817 100644 --- a/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicilinfo.md +++ b/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicilinfo.md @@ -10,11 +10,11 @@ ai-usage: ai-assisted Use the class to write your own MSIL generators instead of using . -To create instances of other types, call methods, access fields, or reference types, the MSIL you generate must include tokens for those entities. The class provides several overloads of the method, which return tokens valid in the scope of the current . For example, if you need to call an overload of the method, you can obtain a for that overload and pass it to the method to obtain a token to embed in your MSIL. +To create instances of other types, call methods, access fields, or reference types, the MSIL you generate must include tokens for those entities. The class provides several overloads of the method, which return tokens valid in the scope of the current . For example, if you need to call an overload of the method, you can obtain a for that overload and pass it to the method to obtain a token to embed in your MSIL. -Once you have created arrays for your local variable signature, exceptions, and code body, you can use the , , and methods to insert them into the associated with your object. +Once you have created arrays for your local variable signature, exceptions, and code body, you can use the , , and methods to insert them into the associated with your object. Generating your own metadata and MSIL requires familiarity with the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics" and "Partition III: CIL Instruction Set". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). > [!NOTE] -> Don't use to generate code that creates a delegate to another dynamic method by calling the delegate constructor directly. Instead, use the method to create the delegate. A delegate that is created with the delegate constructor doesn't have a reference to the target dynamic method. The dynamic method might be reclaimed by garbage collection while the delegate is still in use. +> Don't use to generate code that creates a delegate to another dynamic method by calling the delegate constructor directly. Instead, use the method to create the delegate. A delegate that is created with the delegate constructor doesn't have a reference to the target dynamic method. The dynamic method might be reclaimed by garbage collection while the delegate is still in use. diff --git a/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod-issecuritycritical.md b/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod-issecuritycritical.md index 1969a33bfeeb0..b144c4a689389 100644 --- a/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod-issecuritycritical.md +++ b/docs/fundamentals/runtime-libraries/system-reflection-emit-dynamicmethod-issecuritycritical.md @@ -11,7 +11,7 @@ ai-usage: ai-assisted > [!NOTE] > The remarks in this article apply only to .NET Framework and not to modern .NET. -The , , and properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: +The , , and properties report the transparency level of the dynamic method as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: | Security level | IsSecurityCritical | IsSecuritySafeCritical | IsSecurityTransparent | |----------------|--------------------|-----------------------|-----------------------| diff --git a/docs/fundamentals/runtime-libraries/system-string.md b/docs/fundamentals/runtime-libraries/system-string.md index 7e04dc799e737..c8ec4dc5e8e77 100644 --- a/docs/fundamentals/runtime-libraries/system-string.md +++ b/docs/fundamentals/runtime-libraries/system-string.md @@ -262,7 +262,7 @@ Sort rules determine the alphabetic order of Unicode characters and how two stri - An ordinal sort compares strings based on the numeric value of each object in the string. An ordinal comparison is automatically case-sensitive because the lowercase and uppercase versions of a character have different code points. However, if case is not important, you can specify an ordinal comparison that ignores case. This is equivalent to converting the string to uppercase by using the invariant culture and then performing an ordinal comparison on the result. For a list of the methods that compare two strings using ordinal sort rules, see the [String operations by category](#string-operations-by-category) section. -A culture-sensitive comparison is any comparison that explicitly or implicitly uses a object, including the invariant culture that is specified by the property. The implicit culture is the current culture, which is specified by the and properties. There is considerable variation in the sort order of alphabetic characters (that is, characters for which the property returns `true`) across cultures. You can specify a culture-sensitive comparison that uses the conventions of a specific culture by supplying a object to a string comparison method such as . You can specify a culture-sensitive comparison that uses the conventions of the current culture by supplying , , or any member of the enumeration other than or to an appropriate overload of the method. A culture-sensitive comparison is generally appropriate for sorting whereas an ordinal comparison is not. An ordinal comparison is generally appropriate for determining whether two strings are equal (that is, for determining identity) whereas a culture-sensitive comparison is not. +A culture-sensitive comparison is any comparison that explicitly or implicitly uses a object, including the invariant culture that is specified by the property. The implicit culture is the current culture, which is specified by the and properties. There is considerable variation in the sort order of alphabetic characters (that is, characters for which the method returns `true`) across cultures. You can specify a culture-sensitive comparison that uses the conventions of a specific culture by supplying a object to a string comparison method such as . You can specify a culture-sensitive comparison that uses the conventions of the current culture by supplying , , or any member of the enumeration other than or to an appropriate overload of the method. A culture-sensitive comparison is generally appropriate for sorting whereas an ordinal comparison is not. An ordinal comparison is generally appropriate for determining whether two strings are equal (that is, for determining identity) whereas a culture-sensitive comparison is not. The following example illustrates the difference between culture-sensitive and ordinal comparison. The example evaluates three strings, "Apple", "Æble", and "AEble", using ordinal comparison and the conventions of the da-DK and en-US cultures (each of which is the default culture at the time the method is called). Because the Danish language treats the character "Æ" as an individual letter and sorts it after "Z" in the alphabet, the string "Æble" is greater than "Apple". However, "Æble" is not considered equivalent to "AEble", so "Æble" is also greater than "AEble". The en-US culture doesn't include the letter"Æ" but treats it as equivalent to "AE", which explains why "Æble" is less than "Apple" but equal to "AEble". Ordinal comparison, on the other hand, considers "Apple" to be less than "Æble", and "Æble" to be greater than "AEble". diff --git a/docs/fundamentals/runtime-libraries/system-text-regularexpressions-regex.md b/docs/fundamentals/runtime-libraries/system-text-regularexpressions-regex.md index f6ccf02ce92bb..79a03d4bbdd26 100644 --- a/docs/fundamentals/runtime-libraries/system-text-regularexpressions-regex.md +++ b/docs/fundamentals/runtime-libraries/system-text-regularexpressions-regex.md @@ -22,7 +22,7 @@ The class represents .NET's regular To use regular expressions, you define the pattern that you want to identify in a text stream by using the syntax documented in [Regular expression language - quick reference](../../standard/base-types/regular-expression-language-quick-reference.md). Next, you can optionally instantiate a object. Finally, you call a method that performs some operation, such as replacing text that matches the regular expression pattern, or identifying a pattern match. > [!IMPORTANT] -> The regular expression engine assumes that patterns are trusted. Do not pass patterns from untrusted sources to methods. Untrusted patterns can cause excessive resource consumption regardless of the input text. If your application needs to accept search expressions from users, use a restricted syntax that you translate into a regex pattern, or use to treat user input as a literal string. For more information, see [Best Practices for Regular Expressions - Use trusted patterns](../../standard/base-types/best-practices-regex.md#use-trusted-patterns). +> The regular expression engine assumes that patterns are trusted. Do not pass patterns from untrusted sources to methods. Untrusted patterns can cause excessive resource consumption regardless of the input text. If your application needs to accept search expressions from users, use a restricted syntax that you translate into a regex pattern, or use to treat user input as a literal string. For more information, see [Best Practices for Regular Expressions - Use trusted patterns](../../standard/base-types/best-practices-regex.md#use-trusted-patterns). For more information about the regular expression language, see [Regular expression language - quick reference](../../standard/base-types/regular-expression-language-quick-reference.md) or download and print one of these brochures: diff --git a/docs/fundamentals/runtime-libraries/system-threading-tasks-task.md b/docs/fundamentals/runtime-libraries/system-threading-tasks-task.md index dabd78b29b965..3dd1a566012fd 100644 --- a/docs/fundamentals/runtime-libraries/system-threading-tasks-task.md +++ b/docs/fundamentals/runtime-libraries/system-threading-tasks-task.md @@ -11,7 +11,7 @@ dev_langs: [!INCLUDE [context](includes/context.md)] -The class represents a single operation that does not return a value and that usually executes asynchronously. objects are one of the central components of the [task-based asynchronous pattern](../../standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md) first introduced in .NET Framework 4. Because the work performed by a object typically executes asynchronously on a thread pool thread rather than synchronously on the main application thread, you can use the property, as well as the , , and properties, to determine the state of a task. Most commonly, a lambda expression is used to specify the work that the task is to perform. +The class represents a single operation that does not return a value and that usually executes asynchronously. objects are one of the central components of the [task-based asynchronous pattern](../../standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md) first introduced in .NET Framework 4. Because the work performed by a object typically executes asynchronously on a thread pool thread rather than synchronously on the main application thread, you can use the property, as well as the , , and properties, to determine the state of a task. Most commonly, a lambda expression is used to specify the work that the task is to perform. For operations that return values, you use the class. diff --git a/docs/fundamentals/syslib-diagnostics/experimental-overview.md b/docs/fundamentals/syslib-diagnostics/experimental-overview.md index 3c8a3d7e37de5..9413420e4b292 100644 --- a/docs/fundamentals/syslib-diagnostics/experimental-overview.md +++ b/docs/fundamentals/syslib-diagnostics/experimental-overview.md @@ -25,7 +25,7 @@ The following table provides an index to the `SYSLIB5XXX` experimental APIs in . | Diagnostic ID | Introduced | Description | |-------------------------------|------------|----------------------------------------------------------------------| -| SYSLIB5001 | .NET 9 | and related APIs in are experimental | +| SYSLIB5001 | .NET 9 | and related APIs in are experimental | | SYSLIB5002 | .NET 9 | alternate colors are experimental | | [SYSLIB5003](./syslib5003.md) | .NET 9 | is experimental | | SYSLIB5004 | .NET 9 | is experimental since performance is not as optimized as `T.DivRem` | diff --git a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md index e51ade0be5a79..5503cd0a93934 100644 --- a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md +++ b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md @@ -40,7 +40,7 @@ The following table lists the `SYSLIB0XXX` obsoletions in .NET 5+. | [SYSLIB0013](syslib0013.md) | Warning | can corrupt the Uri string in some cases. Consider using for query string components instead. | | [SYSLIB0014](syslib0014.md) | Warning | , , , and are obsolete. Use instead. | | [SYSLIB0015](syslib0015.md) | Warning | has no effect in .NET 6+. | -| [SYSLIB0016](syslib0016.md) | Warning | Use the overloads that accept arguments for better performance and fewer allocations. | +| [SYSLIB0016](syslib0016.md) | Warning | Use the overloads that accept arguments for better performance and fewer allocations. | | [SYSLIB0017](syslib0017.md) | Warning | Strong-name signing is not supported and throws . | | [SYSLIB0018](syslib0018.md) | Warning | Reflection-only loading is not supported and throws . | | [SYSLIB0019](syslib0019.md) | Warning | The members , , and are no longer supported and throw . | @@ -60,7 +60,7 @@ The following table lists the `SYSLIB0XXX` obsoletions in .NET 5+. | [SYSLIB0033](syslib0033.md) | Warning | is obsolete and is not supported. Use instead. | | [SYSLIB0034](syslib0034.md) | Warning | is obsolete. Use an alternative constructor instead. | | [SYSLIB0035](syslib0035.md) | Warning | is obsolete. Use the overload that accepts a instead. | -| [SYSLIB0036](syslib0036.md) | Warning | is obsolete and not supported. Use `RegexGeneratorAttribute` with the regular expression source generator instead. | +| [SYSLIB0036](syslib0036.md) | Warning | is obsolete and not supported. Use `RegexGeneratorAttribute` with the regular expression source generator instead. | | [SYSLIB0037](syslib0037.md) | Warning | members , , and are obsolete and not supported. | | [SYSLIB0038](syslib0038.md) | Warning | is obsolete and should not be used. | | [SYSLIB0039](syslib0039.md) | Warning | TLS versions 1.0 and 1.1 have known vulnerabilities and are not recommended. Use a newer TLS version instead, or use to defer to OS defaults. | @@ -72,19 +72,19 @@ The following table lists the `SYSLIB0XXX` obsoletions in .NET 5+. | [SYSLIB0045](syslib0045.md) | Warning | Cryptographic factory methods accepting an algorithm name are obsolete. Use the parameterless `Create` factory method on the algorithm type instead. | | [SYSLIB0046](syslib0046.md) | Warning | The method might corrupt the process and should not be used in production code. | | [SYSLIB0047](syslib0047.md) | Warning | is obsolete. Use `XmlResolver.ThrowingResolver` instead when attempting to forbid XML external entity resolution. | -| [SYSLIB0048](syslib0048.md) | Warning | and are obsolete. Use and instead. | +| [SYSLIB0048](syslib0048.md) | Warning | and are obsolete. Use and instead. | | [SYSLIB0049](syslib0049.md) | Warning | JsonSerializerOptions.AddContext is obsolete. To register a JsonSerializerContext, use either the TypeInfoResolver or TypeInfoResolverChain property. | | [SYSLIB0050](syslib0050.md) | Warning | Formatter-based serialization is obsolete and should not be used. | | [SYSLIB0051](syslib0051.md) | Warning | APIs that support obsolete formatter-based serialization are obsolete. They should not be called or extended by application code. | | [SYSLIB0052](syslib0052.md) | Warning | APIs that support obsolete mechanisms for Regex extensibility are obsolete. | | [SYSLIB0053](syslib0053.md) | Warning | should indicate the required tag size for encryption and decryption. Use a constructor that accepts the tag size. | -| [SYSLIB0054](syslib0054.md) | Warning | and are obsolete. Use or instead. | +| [SYSLIB0054](syslib0054.md) | Warning | and are obsolete. Use or instead. | | [SYSLIB0055](syslib0055.md) | Warning | `AdvSimd.ShiftRightLogicalRoundedNarrowingSaturate*` methods with signed parameters are obsolete. Use the unsigned overloads instead. | | [SYSLIB0056](syslib0056.md) | Warning | `Assembly.LoadFrom` with a custom `AssemblyHashAlgorithm` is obsolete. Use overloads without an `AssemblyHashAlgorithm`. | | [SYSLIB0057](syslib0057.md) | Warning | `X509Certificate2` and `X509Certificate` constructors for binary and file content are obsolete. | | [SYSLIB0058](syslib0058.md) | Warning | The `KeyExchangeAlgorithm`, `KeyExchangeStrength`, `CipherAlgorithm`, `CipherAlgorithmStrength`, `HashAlgorithm`, and `HashStrength` properties of are obsolete. Use instead. | | [SYSLIB0059](syslib0059.md) | Warning | callbacks aren't run before the process exits. Use instead. | -| [SYSLIB0060](syslib0060.md) | Warning | Constructors on are obsolete. Use instead. | +| [SYSLIB0060](syslib0060.md) | Warning | Constructors on are obsolete. Use instead. | | [SYSLIB0061](syslib0061.md) | Warning | The `Queryable` and taking an `IComparer` are obsolete. Use the new ones that take an `IComparer`. | | [SYSLIB0062](syslib0062.md) | Warning | is obsolete. | diff --git a/docs/fundamentals/syslib-diagnostics/syslib0001.md b/docs/fundamentals/syslib-diagnostics/syslib0001.md index f7035774e90a9..da40c53268d67 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0001.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0001.md @@ -12,7 +12,7 @@ The UTF-7 encoding is no longer in wide use among applications, and many specs n Consequently, the following APIs are marked obsolete, starting in .NET 5. Use of these APIs generates warning `SYSLIB0001` at compile time. - property -- constructors +- constructors ## Workarounds diff --git a/docs/fundamentals/syslib-diagnostics/syslib0003.md b/docs/fundamentals/syslib-diagnostics/syslib0003.md index 3bc860fda406c..e4ce3457bc779 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0003.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0003.md @@ -139,9 +139,9 @@ The complete list of obsolete CAS APIs is as follows: - - - -- +- - -- +- - - - diff --git a/docs/fundamentals/syslib-diagnostics/syslib0004.md b/docs/fundamentals/syslib-diagnostics/syslib0004.md index 35f4f66441a32..8a3cd30eafb42 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0004.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0004.md @@ -24,7 +24,7 @@ The following CER-related APIs are obsolete: However, the following CER-related APIs are *not* obsolete: - -- +- - ## Workarounds diff --git a/docs/fundamentals/syslib-diagnostics/syslib0006.md b/docs/fundamentals/syslib-diagnostics/syslib0006.md index 0d3fff4512735..38349940709b1 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0006.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0006.md @@ -12,11 +12,11 @@ The following APIs are marked obsolete, starting in .NET 5. Use of these APIs ge - - -When you call to abort a thread other than the current thread, you don't know what code has executed or failed to execute when the is thrown. You also cannot be certain of the state of your application or any application and user state that it's responsible for preserving. For example, calling may prevent the execution of static constructors or the release of managed or unmanaged resources. For this reason, always throws a on .NET Core and .NET 5+. +When you call to abort a thread other than the current thread, you don't know what code has executed or failed to execute when the is thrown. You also cannot be certain of the state of your application or any application and user state that it's responsible for preserving. For example, calling may prevent the execution of static constructors or the release of managed or unmanaged resources. For this reason, always throws a on .NET Core and .NET 5+. ## Workarounds -Use a to abort processing of a unit of work instead of calling . The following example illustrates the use of . +Use a to abort processing of a unit of work instead of calling . The following example illustrates the use of . ```csharp void ProcessPendingWorkItemsNew(CancellationToken cancellationToken) diff --git a/docs/fundamentals/syslib-diagnostics/syslib0009.md b/docs/fundamentals/syslib-diagnostics/syslib0009.md index 3e0c6f408a8ca..390fb39e73789 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0009.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0009.md @@ -10,15 +10,15 @@ f1_keywords: The following APIs are marked obsolete, starting in .NET 5. Use of these APIs generates warning `SYSLIB0009` at compile time and throws a at runtime. -- -- +- +- In .NET 9 and later versions, the entire class is marked obsolete. Use of this class generates warning `SYSLIB0009` at compile time. The methods in this class either no-op or throw a at runtime. ## Workarounds -Implement , which has methods that were previously called by . +Implement , which has methods that were previously called by . ## Suppress a warning diff --git a/docs/fundamentals/syslib-diagnostics/syslib0011.md b/docs/fundamentals/syslib-diagnostics/syslib0011.md index e23597d286efd..3c1b7f9150605 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0011.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0011.md @@ -10,14 +10,14 @@ f1_keywords: Due to [security vulnerabilities](../../standard/serialization/binaryformatter-security-guide.md#binaryformatter-security-vulnerabilities) in , the following APIs were marked as obsolete in .NET 5. Using them in code generates warning or error `SYSLIB0011` at compile time. - -- -- +- +- - - - - -Starting in .NET 8, and throw a at runtime on most project types. In addition, is obsolete *as warning*, and the following APIs are obsolete *as error*: +Starting in .NET 8, and throw a at runtime on most project types. In addition, is obsolete *as warning*, and the following APIs are obsolete *as error*: - - diff --git a/docs/fundamentals/syslib-diagnostics/syslib0014.md b/docs/fundamentals/syslib-diagnostics/syslib0014.md index 13cc445bd6973..2c736551a18ef 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0014.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0014.md @@ -10,12 +10,12 @@ f1_keywords: The following APIs are marked as obsolete, starting in .NET 6. Using them in code generates warning `SYSLIB0014` at compile time. - -- -- +- +- - - - (Starting in .NET 9) -- +- - To reduce the number of analyzer warnings, the class is not marked as obsolete, but all ways of obtaining its instances are. diff --git a/docs/fundamentals/syslib-diagnostics/syslib0016.md b/docs/fundamentals/syslib-diagnostics/syslib0016.md index c58bf310329a5..ca073dd5fd382 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0016.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0016.md @@ -13,7 +13,7 @@ For more information, see . ## Workarounds -For better performance and fewer allocations, use the overloads that accept arguments: +For better performance and fewer allocations, use the overloads that accept arguments: - - diff --git a/docs/fundamentals/syslib-diagnostics/syslib0018.md b/docs/fundamentals/syslib-diagnostics/syslib0018.md index a6e5b6a1e227c..cfb909b30c3a3 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0018.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0018.md @@ -9,7 +9,7 @@ f1_keywords: The following methods are marked as obsolete, starting in .NET 6. Calling them in code generates warning `SYSLIB0018` at compile time. These methods throw a at runtime. -- +- - - diff --git a/docs/fundamentals/syslib-diagnostics/syslib0021.md b/docs/fundamentals/syslib-diagnostics/syslib0021.md index 7966f865fe320..0c0abf5e36860 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0021.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0021.md @@ -26,7 +26,7 @@ The following derived cryptographic types are marked as obsolete, starting in .N ## Workarounds -Use the `Create` method on the base type instead. For example, use instead of . +Use the `Create` method on the base type instead. For example, use instead of . ## Suppress a warning diff --git a/docs/fundamentals/syslib-diagnostics/syslib0026.md b/docs/fundamentals/syslib-diagnostics/syslib0026.md index 1cef34e19fd14..78f26ec271a5d 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0026.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0026.md @@ -10,9 +10,9 @@ f1_keywords: The following mutable x509 certificate APIs are marked as obsolete, starting in .NET 6. Using these APIs in code generates warning `SYSLIB0026` at compile time. - -- +- - -- +- ## Workarounds diff --git a/docs/fundamentals/syslib-diagnostics/syslib0036.md b/docs/fundamentals/syslib-diagnostics/syslib0036.md index 3979604b06f1c..7ddb1cd95c9bf 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0036.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0036.md @@ -7,9 +7,9 @@ f1_keywords: --- # SYSLIB0036: Regex.CompileToAssembly is obsolete -The method is marked as obsolete, starting in .NET 7. Using this API in code generates warning `SYSLIB0036` at compile time. +The method is marked as obsolete, starting in .NET 7. Using this API in code generates warning `SYSLIB0036` at compile time. -In .NET 5, .NET 6, and all versions of .NET Core, throws a . In .NET Framework, allows a regular expression instance to be compiled into an assembly. +In .NET 5, .NET 6, and all versions of .NET Core, throws a . In .NET Framework, allows a regular expression instance to be compiled into an assembly. ## Workaround diff --git a/docs/fundamentals/syslib-diagnostics/syslib0045.md b/docs/fundamentals/syslib-diagnostics/syslib0045.md index c84c5996d4c17..d538c0a0431e3 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0045.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0045.md @@ -7,7 +7,7 @@ f1_keywords: --- # SYSLIB0045: Some cryptographic factory methods are obsolete -The following `System.Security.Cryptography` methods are obsolete, starting in .NET 7. Using them in code generates warning `SYSLIB0045` at compile time. Each of these factory methods accepts a string argument that represents the algorithm name. These methods call into and cast the result to the return type. +The following `System.Security.Cryptography` methods are obsolete, starting in .NET 7. Using them in code generates warning `SYSLIB0045` at compile time. Each of these factory methods accepts a string argument that represents the algorithm name. These methods call into and cast the result to the return type. - - @@ -33,7 +33,7 @@ These methods were marked `[Obsolete]` because in trimmed applications, they can Calls that pass a constant string should be changed to either the parameterless factory method or a strong call to create the appropriate type. For example, a call to `Aes.Create("AES")` can be replaced with either `Aes.Create()` or `new AesCryptoServiceProvider()`. Since the type is also marked `[Obsolete]`, `Aes.Create()` is the preferred replacement. -Calls that pass a non-constant string can either use their own lookup table or be changed to call directly. +Calls that pass a non-constant string can either use their own lookup table or be changed to call directly. ## Suppress a warning diff --git a/docs/fundamentals/syslib-diagnostics/syslib0048.md b/docs/fundamentals/syslib-diagnostics/syslib0048.md index 56f7a7428d775..ec6524806314b 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0048.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0048.md @@ -16,7 +16,7 @@ The following methods are obsolete, starting in .NET 8. Calling them in code gen ## Workaround -Use and instead. +Use and instead. ## Suppress a warning diff --git a/docs/fundamentals/syslib-diagnostics/syslib0049.md b/docs/fundamentals/syslib-diagnostics/syslib0049.md index c726e41a193c6..a9dd4149a755f 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0049.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0049.md @@ -7,9 +7,9 @@ f1_keywords: --- # SYSLIB0049: JsonSerializerOptions.AddContext is obsolete -The method is obsolete, starting in .NET 8. Calling it in code generates warning `SYSLIB0049` at compile time. +The method is obsolete, starting in .NET 8. Calling it in code generates warning `SYSLIB0049` at compile time. -The method was introduced in .NET 6 as a means to associate instances with a specified type. This method was largely superseded in .NET 7 with the introduction of [contract customization](../../standard/serialization/system-text-json/custom-contracts.md) and the property. +The method was introduced in .NET 6 as a means to associate instances with a specified type. This method was largely superseded in .NET 7 with the introduction of [contract customization](../../standard/serialization/system-text-json/custom-contracts.md) and the property. ## Workaround diff --git a/docs/fundamentals/syslib-diagnostics/syslib0052.md b/docs/fundamentals/syslib-diagnostics/syslib0052.md index 92a97f697f914..d6a7f79c986fb 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0052.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0052.md @@ -7,7 +7,7 @@ f1_keywords: --- # SYSLIB0052: APIs that support obsolete mechanisms for Regex extensibility are obsolete -The following and APIs are obsolete, starting in .NET 8. Calling them in code generates warning `SYSLIB0052` at compile time. These APIs supported the now obsolete . +The following and APIs are obsolete, starting in .NET 8. Calling them in code generates warning `SYSLIB0052` at compile time. These APIs supported the now obsolete . - - diff --git a/docs/fundamentals/syslib-diagnostics/syslib0053.md b/docs/fundamentals/syslib-diagnostics/syslib0053.md index 8650096688e57..b7a35640fc185 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0053.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0053.md @@ -16,7 +16,7 @@ Calling them in code generates warning `SYSLIB0053` at compile time. ## Reason for obsoletion -AES-GCM supports tags of various lengths, from 12 to 16 bytes, depending on the platform. Previously, the class would determine the desired tag size based on the size of the tag itself. For example, if was called with a 14 byte tag, it was assumed the tag was supposed to be 14 bytes. +AES-GCM supports tags of various lengths, from 12 to 16 bytes, depending on the platform. Previously, the class would determine the desired tag size based on the size of the tag itself. For example, if was called with a 14 byte tag, it was assumed the tag was supposed to be 14 bytes. However, AES-GCM supports these various lengths by truncation. AES-GCM natively produces 16 byte tags, and shorter tags are produced by truncating the tag. diff --git a/docs/fundamentals/syslib-diagnostics/syslib0054.md b/docs/fundamentals/syslib-diagnostics/syslib0054.md index ada70bdc8572d..ead9165526861 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0054.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0054.md @@ -7,15 +7,15 @@ f1_keywords: --- # SYSLIB0054: Thread.VolatileRead and Thread.VolatileWrite are obsolete -All overloads of the and methods are obsolete, starting in .NET 9. Calling them in code generates warning `SYSLIB0054` at compile time. +All overloads of the and methods are obsolete, starting in .NET 9. Calling them in code generates warning `SYSLIB0054` at compile time. ## Reason for obsoletion -The .NET Framework implementation of the 64-bit overloads of the and methods had incorrect atomicity. In .NET (Core), the implementation was changed to delegate to the and , respectively, which provide proper acquire/release semantics. In addition, the methods in the class don't include an overload that accepts a Boolean argument, whereas the methods do. The methods were obsoleted to encourage use of the methods. +The .NET Framework implementation of the 64-bit overloads of the and methods had incorrect atomicity. In .NET (Core), the implementation was changed to delegate to the and , respectively, which provide proper acquire/release semantics. In addition, the methods in the class don't include an overload that accepts a Boolean argument, whereas the methods do. The methods were obsoleted to encourage use of the methods. ## Workaround -Call or instead. +Call or instead. ## Suppress a warning diff --git a/docs/fundamentals/syslib-diagnostics/syslib0056.md b/docs/fundamentals/syslib-diagnostics/syslib0056.md index b682a4620dcf2..4a66985e46353 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0056.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0056.md @@ -7,7 +7,7 @@ f1_keywords: --- # SYSLIB0056: Assembly.LoadFrom that takes an AssemblyHashAlgorithm is obsolete -The overload of that takes an is obsolete, starting in .NET 9. Calling it in code generates warning `SYSLIB0056` at compile time. +The overload of that takes an is obsolete, starting in .NET 9. Calling it in code generates warning `SYSLIB0056` at compile time. ## Reason for obsoletion @@ -15,7 +15,7 @@ The overload of that doesn't take an . +Use an overload of that doesn't take an . ## Suppress a warning diff --git a/docs/fundamentals/syslib-diagnostics/syslib0057.md b/docs/fundamentals/syslib-diagnostics/syslib0057.md index 92858cc0686bd..3020dd0fe7bdd 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0057.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0057.md @@ -7,7 +7,7 @@ f1_keywords: --- # SYSLIB0057: X509Certificate2 and X509Certificate constructors for binary and file content are obsolete -The constructors on and that accept content as a `byte[]`, `ReadOnlySpan`, or a `string` file path are obsolete, starting in .NET 9. The methods on X509Certificate2Collection are also obsolete. Calling them in code generates warning `SYSLIB0057` at compile time. +The constructors on and that accept content as a `byte[]`, `ReadOnlySpan`, or a `string` file path are obsolete, starting in .NET 9. The methods on X509Certificate2Collection are also obsolete. Calling them in code generates warning `SYSLIB0057` at compile time. ## Reason for obsoletion @@ -24,7 +24,7 @@ A new class called from the System.Security.Cryptography.Pkcs package to inspect certificates in PKCS7 content. -- If you're uncertain about the content type you're loading, use to determine the content type and call the appropriate API. +- If you're uncertain about the content type you're loading, use to determine the content type and call the appropriate API. The [Microsoft.Bcl.Cryptography package](https://www.nuget.org/packages/Microsoft.Bcl.Cryptography/) supplies `X509CertificateLoader` for .NET Framework and .NET Standard. diff --git a/docs/fundamentals/syslib-diagnostics/syslib1034.md b/docs/fundamentals/syslib-diagnostics/syslib1034.md index 05eb169f5ec4d..ea474155c0e45 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib1034.md +++ b/docs/fundamentals/syslib-diagnostics/syslib1034.md @@ -12,6 +12,6 @@ The non-generic re ## Workarounds -Use instead, which doesn't require runtime code generation. +Use instead, which doesn't require runtime code generation. [!INCLUDE [suppress-syslib-warning](includes/suppress-source-generator-diagnostics.md)] diff --git a/docs/machine-learning/how-to-guides/how-to-use-the-automl-api.md b/docs/machine-learning/how-to-guides/how-to-use-the-automl-api.md index 8a833a278c0cc..bc5d65513ff1c 100644 --- a/docs/machine-learning/how-to-guides/how-to-use-the-automl-api.md +++ b/docs/machine-learning/how-to-guides/how-to-use-the-automl-api.md @@ -48,7 +48,7 @@ Given a dataset stored in a comma-separated file called *taxi-fare-train.csv* th Start by initializing your . `MLContext` is a starting point for all ML.NET operations. Initializing mlContext creates a new ML.NET environment that can be shared across the model creation workflow objects. It's similar, conceptually, to `DBContext` in Entity Framework. -Then, to load your data, use the method. +Then, to load your data, use the method. ```csharp // Initialize MLContext @@ -62,11 +62,11 @@ ColumnInferenceResults columnInference = ctx.Auto().InferColumns(dataPath, labelColumnName: "fare_amount", groupColumns: false); ``` - loads a few rows from the dataset. It then inspects the data and tries to guess or infer the data type for each of the columns based on their content. + loads a few rows from the dataset. It then inspects the data and tries to guess or infer the data type for each of the columns based on their content. The default behavior is to group columns of the same type into feature vectors or arrays containing the elements for each of the individual columns. Setting `groupColumns` to `false` overrides that default behavior and only performs column inference without grouping columns. By keeping columns separate, it allows you to apply different data transformations when preprocessing the data at the individual column level rather than the column grouping. -The result of is a object that contains the options needed to create a as well as column information. +The result of is a object that contains the options needed to create a as well as column information. For the sample dataset in *taxi-fare-train.csv*, column information might look like the following: @@ -84,7 +84,7 @@ TextLoader loader = ctx.Data.CreateTextLoader(columnInference.TextLoaderOptions) IDataView data = loader.Load(dataPath); ``` -It's often good practice to split your data into train and validation sets. Use to create an 80% training and 20% validation split of your dataset. +It's often good practice to split your data into train and validation sets. Use to create an 80% training and 20% validation split of your dataset. ```csharp TrainTestData trainValidationData = ctx.Data.TrainTestSplit(data, testFraction: 0.2); @@ -102,20 +102,20 @@ SweepablePipeline pipeline = A is a collection of . A is an ML.NET with a . -The is a convenience API that builds a sweepable pipeline of data processing sweepable estimators based on the column information you provide. Instead of building a pipeline from scratch, automates the data preprocessing step. For more information on supported transforms by ML.NET, see the [data transformations guide](../resources/transforms.md). +The is a convenience API that builds a sweepable pipeline of data processing sweepable estimators based on the column information you provide. Instead of building a pipeline from scratch, automates the data preprocessing step. For more information on supported transforms by ML.NET, see the [data transformations guide](../resources/transforms.md). -The output is a single column containing a numerical feature vector representing the transformed data for each of the columns. This feature vector is then used as input for the algorithms used to train a machine learning model. +The output is a single column containing a numerical feature vector representing the transformed data for each of the columns. This feature vector is then used as input for the algorithms used to train a machine learning model. If you want finer control over your data preprocessing, you can create a pipeline with each of the individual preprocessing steps. For more information, see the [prepare data for building a model guide](prepare-data-ml-net.md). > [!TIP] -> Use with to maximize the utility of AutoML. +> Use with to maximize the utility of AutoML. For training, AutoML provides a sweepable pipeline with default trainers and search space configurations for the following machine learning tasks: -- -- -- +- +- +- For the taxi fare prediction problem, since the goal is to predict a numerical value, use `Regression`. For more information on choosing a task, see [Machine learning tasks in ML.NET](../resources/tasks.md). @@ -139,10 +139,10 @@ experiment In this example, you: -- Set the sweepable pipeline to run during the experiment by calling . -- Choose `RSquared` as the metric to optimize during training by calling . For more information on evaluation metrics, see the [evaluate your ML.NET model with metrics](../resources/metrics.md) guide. -- Set 60 seconds as the amount of time you want to train for by calling . A good heuristic to determine how long to train for is the size of your data. Typically, larger datasets require longer training time. For more information, see [training time guidance](../automate-training-with-model-builder.md#how-long-should-i-train-for). -- Provide the training and validation datasets to use by calling . +- Set the sweepable pipeline to run during the experiment by calling . +- Choose `RSquared` as the metric to optimize during training by calling . For more information on evaluation metrics, see the [evaluate your ML.NET model with metrics](../resources/metrics.md) guide. +- Set 60 seconds as the amount of time you want to train for by calling . A good heuristic to determine how long to train for is the size of your data. Typically, larger datasets require longer training time. For more information, see [training time guidance](../automate-training-with-model-builder.md#how-long-should-i-train-for). +- Provide the training and validation datasets to use by calling . Once your experiment is defined, you'll want some way to track its progress. The quickest way to track progress is by modifying the event from . @@ -158,7 +158,7 @@ ctx.Log += (_, e) => { ### Run your experiment -Now that you've defined your experiment, use the method to start your experiment. +Now that you've defined your experiment, use the method to start your experiment. ```csharp TrialResult experimentResults = await experiment.RunAsync(); @@ -173,9 +173,9 @@ At this point, you can save your model or use it for making predictions. For mor ## Modify column inference results -Because only loads a subset of your data, it's possible that edge cases contained outside of the samples used to infer columns aren't caught and the wrong data types are set for your columns. You can update the properties of to account for those cases where the column inference results aren't correct. +Because only loads a subset of your data, it's possible that edge cases contained outside of the samples used to infer columns aren't caught and the wrong data types are set for your columns. You can update the properties of to account for those cases where the column inference results aren't correct. -For example, in the taxi fare dataset, the data in the `rate_code` column is a number. However, that numerical value represents a category. By default, calling will place `rate_code` in the `NumericColumnNames` property instead of `CategoricalColumnNames`. Because these properties are .NET collections, you can use standard operations to add and remove items from them. +For example, in the taxi fare dataset, the data in the `rate_code` column is a number. However, that numerical value represents a category. By default, calling will place `rate_code` in the `NumericColumnNames` property instead of `CategoricalColumnNames`. Because these properties are .NET collections, you can use standard operations to add and remove items from them. You can do the following to update the for `rate_code`. @@ -207,9 +207,9 @@ When you want to more granular customization of estimator options included as pa AutoML provides a set of preconfigured search spaces for trainers in the following machine learning tasks: -- -- -- +- +- +- In this example, the search space used is for the . Initialize it by using . @@ -233,7 +233,7 @@ var sdcaFactory = (MLContext ctx, SdcaOption param) => }; ``` -A sweepable estimator is the combination of an estimator and a search space. Now that you've defined a search space and used it to create a custom factory method for generating trainers, use the method to create a new sweepable estimator. +A sweepable estimator is the combination of an estimator and a search space. Now that you've defined a search space and used it to create a custom factory method for generating trainers, use the method to create a new sweepable estimator. ```csharp // Define Sdca sweepable estimator (SdcaRegressionTrainer + SdcaOption search space) @@ -501,7 +501,7 @@ To use AutoML with the text classification trainer, you'll have to: var tcRunner = new TCRunner(context: ctx, data: trainValidationData, pipeline: pipeline); ``` -1. Create and configure your experiment. Use the extension method to add your custom trial runner to your experiment. +1. Create and configure your experiment. Use the extension method to add your custom trial runner to your experiment. ```csharp AutoMLExperiment experiment = ctx.Auto().CreateExperiment(); @@ -528,11 +528,11 @@ AutoML supports various tuning algorithms to iterate through the search space in Use the following methods to set your tuner: -- **SMAC** - -- **Grid Search** - -- **Random Search** - -- **Cost Frugal** - -- **Eci Cost Frugal** - +- **SMAC** - +- **Grid Search** - +- **Random Search** - +- **Cost Frugal** - +- **Eci Cost Frugal** - For example, to use the grid search tuner, your code might look like the following: @@ -589,17 +589,17 @@ public class AutoMLMonitor : IMonitor The interface has four lifecycle events: -- -- -- -- +- +- +- +- > [!TIP] > Although it's not required, include your in your monitor so you can inspect the pipeline that was generated for a trial using the property of the . -In this example, only the and are implemented. +In this example, only the and are implemented. -Once you've implemented your monitor, set it as part of your experiment configuration using . +Once you've implemented your monitor, set it as part of your experiment configuration using . ```csharp var monitor = new AutoMLMonitor(pipeline); @@ -646,7 +646,7 @@ Inside your monitor: } ``` -1. Append each trial result inside your lifecycle method. +1. Append each trial result inside your lifecycle method. ```csharp public void ReportCompletedTrial(TrialResult result) @@ -678,7 +678,7 @@ TrialResult experimentResults = await experiment.RunAsync(cts.Token); ## Set checkpoints -Checkpoints provide a way for you to save intermediary outputs from the training process in the event of an early termination or error. To set a checkpoint, use the extension method and provide a directory to store the intermediary outputs. +Checkpoints provide a way for you to save intermediary outputs from the training process in the event of an early termination or error. To set a checkpoint, use the extension method and provide a directory to store the intermediary outputs. ```csharp var checkpointPath = Path.Join(Directory.GetCurrentDirectory(), "automl"); @@ -706,7 +706,7 @@ To determine feature importance using AutoML: var transformedData = bestModel.Transform(trainValidationData.TrainSet); ``` -1. Calculate feature importance using +1. Calculate feature importance using In this case, the task is regression but the same concept applies to other tasks like ranking and classification. diff --git a/docs/machine-learning/how-to-guides/inspect-intermediate-data-ml-net.md b/docs/machine-learning/how-to-guides/inspect-intermediate-data-ml-net.md index 4348a7442f6de..842060fdcb35d 100644 --- a/docs/machine-learning/how-to-guides/inspect-intermediate-data-ml-net.md +++ b/docs/machine-learning/how-to-guides/inspect-intermediate-data-ml-net.md @@ -61,7 +61,7 @@ In ML.NET, you can inspect intermediate data like this that's loaded into an [`I ## Convert IDataView to IEnumerable -One of the quickest ways to inspect an [`IDataView`](xref:Microsoft.ML.IDataView) is to convert it to an [`IEnumerable`](xref:System.Collections.Generic.IEnumerable%601). To do this conversion, use the [`CreateEnumerable`](xref:Microsoft.ML.DataOperationsCatalog.CreateEnumerable%2A) method. +One of the quickest ways to inspect an [`IDataView`](xref:Microsoft.ML.IDataView) is to convert it to an [`IEnumerable`](xref:System.Collections.Generic.IEnumerable`1). To do this conversion, use the [`CreateEnumerable`](xref:Microsoft.ML.DataOperationsCatalog.CreateEnumerable%2A) method. To optimize performance, set `reuseRowObject` to `true`. Doing so lazily populates the same object with the data of the current row as it's being evaluated as opposed to creating a new object for each row in the dataset. @@ -80,7 +80,7 @@ foreach (HousingData row in housingDataEnumerable) ## Access specific indices with IEnumerable -If you only need access to a portion of the data or specific indices, use [`CreateEnumerable`](xref:Microsoft.ML.DataOperationsCatalog.CreateEnumerable%2A) and set the `reuseRowObject` parameter value to `false` so a new object is created for each of the requested rows in the dataset. Then, convert the [`IEnumerable`](xref:System.Collections.Generic.IEnumerable%601) to an array or list. +If you only need access to a portion of the data or specific indices, use [`CreateEnumerable`](xref:Microsoft.ML.DataOperationsCatalog.CreateEnumerable%2A) and set the `reuseRowObject` parameter value to `false` so a new object is created for each of the requested rows in the dataset. Then, convert the [`IEnumerable`](xref:System.Collections.Generic.IEnumerable`1) to an array or list. > [!WARNING] > Converting the result of [`CreateEnumerable`](xref:Microsoft.ML.DataOperationsCatalog.CreateEnumerable%2A) to an array or list loads all the requested [`IDataView`](xref:Microsoft.ML.IDataView) rows into memory, which might affect performance. @@ -103,7 +103,7 @@ float averageCurrentPrice = (firstRow.CurrentPrice + secondRow.CurrentPrice + th ## Inspect values in a single column -At any point in the model building process, values in a single column of an [`IDataView`](xref:Microsoft.ML.IDataView) can be accessed using the [`GetColumn`](xref:Microsoft.ML.Data.ColumnCursorExtensions.GetColumn%2A) method. The [`GetColumn`](xref:Microsoft.ML.Data.ColumnCursorExtensions.GetColumn%2A) method returns all of the values in a single column as an [`IEnumerable`](xref:System.Collections.Generic.IEnumerable%601). +At any point in the model building process, values in a single column of an [`IDataView`](xref:Microsoft.ML.IDataView) can be accessed using the [`GetColumn`](xref:Microsoft.ML.Data.ColumnCursorExtensions.GetColumn%2A) method. The [`GetColumn`](xref:Microsoft.ML.Data.ColumnCursorExtensions.GetColumn%2A) method returns all of the values in a single column as an [`IEnumerable`](xref:System.Collections.Generic.IEnumerable`1). ```csharp IEnumerable sizeColumn = data.GetColumn("Size").ToList(); @@ -111,10 +111,10 @@ IEnumerable sizeColumn = data.GetColumn("Size").ToList(); ## Inspect IDataView values one row at a time -[`IDataView`](xref:Microsoft.ML.IDataView) is lazily evaluated. To iterate over the rows of an [`IDataView`](xref:Microsoft.ML.IDataView) without converting to an [`IEnumerable`](xref:System.Collections.Generic.IEnumerable%601) as demonstrated in previous sections of this document, create a [`DataViewRowCursor`](xref:Microsoft.ML.DataViewRowCursor) by using the [`GetRowCursor`](xref:Microsoft.ML.IDataView.GetRowCursor%2A) method and passing in the [DataViewSchema](xref:Microsoft.ML.DataViewSchema) of your [`IDataView`](xref:Microsoft.ML.IDataView) as a parameter. Then, to iterate over rows, use the [`MoveNext`](xref:Microsoft.ML.DataViewRowCursor.MoveNext%2A) cursor method along with [`ValueGetter`](xref:Microsoft.ML.ValueGetter%601) delegates to extract the respective values from each of the columns. +[`IDataView`](xref:Microsoft.ML.IDataView) is lazily evaluated. To iterate over the rows of an [`IDataView`](xref:Microsoft.ML.IDataView) without converting to an [`IEnumerable`](xref:System.Collections.Generic.IEnumerable`1) as demonstrated in previous sections of this document, create a [`DataViewRowCursor`](xref:Microsoft.ML.DataViewRowCursor) by using the [`GetRowCursor`](xref:Microsoft.ML.IDataView.GetRowCursor%2A) method and passing in the [DataViewSchema](xref:Microsoft.ML.DataViewSchema) of your [`IDataView`](xref:Microsoft.ML.IDataView) as a parameter. Then, to iterate over rows, use the [`MoveNext`](xref:Microsoft.ML.DataViewRowCursor.MoveNext%2A) cursor method along with [`ValueGetter`](xref:Microsoft.ML.ValueGetter`1) delegates to extract the respective values from each of the columns. > [!IMPORTANT] -> For performance purposes, vectors in ML.NET use [`VBuffer`](xref:Microsoft.ML.Data.VBuffer%601) instead of native collection types (that is, `Vector` and `float[]`). +> For performance purposes, vectors in ML.NET use [`VBuffer`](xref:Microsoft.ML.Data.VBuffer`1) instead of native collection types (that is, `Vector` and `float[]`). ```csharp // Get DataViewSchema of IDataView @@ -149,7 +149,7 @@ using (DataViewRowCursor cursor = data.GetRowCursor(columns)) > [!WARNING] > Do not use `Preview` in production code because it is intended for debugging and may reduce performance. -The model building process is experimental and iterative. To preview what data would look like after preprocessing or training a machine learning model on a subset of the data, use the [`Preview`](xref:Microsoft.ML.DebuggerExtensions.Preview%2A) method, which returns a [`DataDebuggerPreview`](xref:Microsoft.ML.Data.DataDebuggerPreview). The result is an object with `ColumnView` and `RowView` properties that are both an [`IEnumerable`](xref:System.Collections.Generic.IEnumerable%601) and contain the values in a particular column or row. Specify the number of rows to apply the transformation to with the `maxRows` parameter. +The model building process is experimental and iterative. To preview what data would look like after preprocessing or training a machine learning model on a subset of the data, use the [`Preview`](xref:Microsoft.ML.DebuggerExtensions.Preview%2A) method, which returns a [`DataDebuggerPreview`](xref:Microsoft.ML.Data.DataDebuggerPreview). The result is an object with `ColumnView` and `RowView` properties that are both an [`IEnumerable`](xref:System.Collections.Generic.IEnumerable`1) and contain the values in a particular column or row. Specify the number of rows to apply the transformation to with the `maxRows` parameter. ![Data Debugger Preview Object](./media/inspect-intermediate-data-ml-net/data-debugger-preview-01.png) diff --git a/docs/machine-learning/how-to-guides/machine-learning-model-predictions-ml-net.md b/docs/machine-learning/how-to-guides/machine-learning-model-predictions-ml-net.md index ce203e92c88a4..01ba6c41f861b 100644 --- a/docs/machine-learning/how-to-guides/machine-learning-model-predictions-ml-net.md +++ b/docs/machine-learning/how-to-guides/machine-learning-model-predictions-ml-net.md @@ -62,14 +62,14 @@ ITransformer predictionPipeline = mlContext.Model.Load("model.zip", out predicti ## Single prediction -To make a single prediction, create a [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) using the loaded prediction pipeline. +To make a single prediction, create a [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) using the loaded prediction pipeline. ```csharp // Create PredictionEngines PredictionEngine predictionEngine = mlContext.Model.CreatePredictionEngine(predictionPipeline); ``` -Then, use the [`Predict`](xref:Microsoft.ML.PredictionEngineBase%602.Predict%2A) method and pass in your input data as a parameter. Notice that using the [`Predict`](xref:Microsoft.ML.PredictionEngineBase%602.Predict%2A) method doesn't require the input to be an [`IDataView`](xref:Microsoft.ML.IDataView). That's because it conveniently internalizes the input data type manipulation so you can pass in an object of the input data type. Additionally, since `CurrentPrice` is the target or label you're trying to predict using new data, it's assumed there's no value for it at the moment. +Then, use the [`Predict`](xref:Microsoft.ML.PredictionEngineBase`2.Predict%2A) method and pass in your input data as a parameter. Notice that using the [`Predict`](xref:Microsoft.ML.PredictionEngineBase`2.Predict%2A) method doesn't require the input to be an [`IDataView`](xref:Microsoft.ML.IDataView). That's because it conveniently internalizes the input data type manipulation so you can pass in an object of the input data type. Additionally, since `CurrentPrice` is the target or label you're trying to predict using new data, it's assumed there's no value for it at the moment. ```csharp // Input Data @@ -86,9 +86,9 @@ HousingPrediction prediction = predictionEngine.Predict(inputData); If you access the `Score` property of the `prediction` object, you should get a value similar to `150079`. > [!TIP] -> [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) is not thread-safe. Additionally, you have to create an instance of it everywhere it is needed within your application. As your application grows, this process can become unmanageable. For improved performance and thread safety, use a combination of dependency injection and the [PredictionEnginePool](xref:Microsoft.Extensions.ML.PredictionEnginePool%602) service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool%601) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) objects for use throughout your application. +> [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) is not thread-safe. Additionally, you have to create an instance of it everywhere it is needed within your application. As your application grows, this process can become unmanageable. For improved performance and thread safety, use a combination of dependency injection and the [PredictionEnginePool](xref:Microsoft.Extensions.ML.PredictionEnginePool`2) service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool`1) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) objects for use throughout your application. > -> For examples on how to use the [PredictionEnginePool](xref:Microsoft.Extensions.ML.PredictionEnginePool%602) service, see [deploy a model to a web API](serve-model-web-api-ml-net.md) and [deploy a model to Azure Functions](serve-model-serverless-azure-functions-ml-net.md). +> For examples on how to use the [PredictionEnginePool](xref:Microsoft.Extensions.ML.PredictionEnginePool`2) service, see [deploy a model to a web API](serve-model-web-api-ml-net.md) and [deploy a model to Azure Functions](serve-model-serverless-azure-functions-ml-net.md). > > For more information, see [Dependency injection in ASP.NET Core](/aspnet/core/fundamentals/dependency-injection). @@ -142,9 +142,9 @@ The predicted values in the score column should resemble the following values: ## Multiple predictions (PredictionEnginePool) -To make multiple predictions using [PredictionEnginePool](xref:Microsoft.Extensions.ML.PredictionEnginePool%602), you can take an `IEnumerable` containing multiple instances of your model input. For example, take an `IEnumerable` and apply the [`Predict`](xref:Microsoft.Extensions.ML.PredictionEnginePoolExtensions.Predict%2A) method to each element using the LINQ [`Select`](xref:System.Linq.Enumerable.Select%2A) method. +To make multiple predictions using [PredictionEnginePool](xref:Microsoft.Extensions.ML.PredictionEnginePool`2), you can take an `IEnumerable` containing multiple instances of your model input. For example, take an `IEnumerable` and apply the [`Predict`](xref:Microsoft.Extensions.ML.PredictionEnginePoolExtensions.Predict%2A) method to each element using the LINQ [`Select`](xref:System.Linq.Enumerable.Select%2A) method. -This code sample assumes you have a [PredictionEnginePool](xref:Microsoft.Extensions.ML.PredictionEnginePool%602) called `predictionEnginePool` and an `IEnumerable` called `housingData`. +This code sample assumes you have a [PredictionEnginePool](xref:Microsoft.Extensions.ML.PredictionEnginePool`2) called `predictionEnginePool` and an `IEnumerable` called `housingData`. ```csharp IEnumerable predictions = housingData.Select(input => predictionEnginePool.Predict(input)); diff --git a/docs/machine-learning/how-to-guides/prepare-data-ml-net.md b/docs/machine-learning/how-to-guides/prepare-data-ml-net.md index 8c9ab41a1d848..737353914f6e9 100644 --- a/docs/machine-learning/how-to-guides/prepare-data-ml-net.md +++ b/docs/machine-learning/how-to-guides/prepare-data-ml-net.md @@ -73,7 +73,7 @@ The result is with two I ## Filter data -Sometimes, not all data in a dataset is relevant for analysis. An approach to remove irrelevant data is filtering. The [`DataOperationsCatalog`](xref:Microsoft.ML.DataOperationsCatalog) contains a set of filter operations that take in an [`IDataView`](xref:Microsoft.ML.IDataView) containing all of the data and return an [IDataView](xref:Microsoft.ML.IDataView) containing only the data points of interest. It's important to note that because filter operations are not an [`IEstimator`](xref:Microsoft.ML.IEstimator%601) or [`ITransformer`](xref:Microsoft.ML.ITransformer) like those in the [`TransformsCatalog`](xref:Microsoft.ML.TransformsCatalog), they cannot be included as part of an [`EstimatorChain`](xref:Microsoft.ML.Data.EstimatorChain%601) or [`TransformerChain`](xref:Microsoft.ML.Data.TransformerChain%601) data preparation pipeline. +Sometimes, not all data in a dataset is relevant for analysis. An approach to remove irrelevant data is filtering. The [`DataOperationsCatalog`](xref:Microsoft.ML.DataOperationsCatalog) contains a set of filter operations that take in an [`IDataView`](xref:Microsoft.ML.IDataView) containing all of the data and return an [IDataView](xref:Microsoft.ML.IDataView) containing only the data points of interest. It's important to note that because filter operations are not an [`IEstimator`](xref:Microsoft.ML.IEstimator`1) or [`ITransformer`](xref:Microsoft.ML.ITransformer) like those in the [`TransformsCatalog`](xref:Microsoft.ML.TransformsCatalog), they cannot be included as part of an [`EstimatorChain`](xref:Microsoft.ML.Data.EstimatorChain`1) or [`TransformerChain`](xref:Microsoft.ML.Data.TransformerChain`1) data preparation pipeline. Take the following input data and load it into an [`IDataView`](xref:Microsoft.ML.IDataView) called `data`: diff --git a/docs/machine-learning/how-to-guides/retrain-model-ml-net.md b/docs/machine-learning/how-to-guides/retrain-model-ml-net.md index 71e0eaaccd284..16c4ec18ab5e6 100644 --- a/docs/machine-learning/how-to-guides/retrain-model-ml-net.md +++ b/docs/machine-learning/how-to-guides/retrain-model-ml-net.md @@ -48,7 +48,7 @@ ITransformer trainedModel = mlContext.Model.Load("ogd_model.zip", out modelSchem ## Extract pretrained model parameters -Once the model is loaded, extract the learned model parameters by accessing the [`Model`](xref:Microsoft.ML.Data.PredictionTransformerBase%601.Model%2A) property of the pretrained model. The pretrained model was trained using the linear regression model [`OnlineGradientDescentTrainer`](xref:Microsoft.ML.Trainers.OnlineGradientDescentTrainer), which creates a [`RegressionPredictionTransformer`](xref:Microsoft.ML.Data.RegressionPredictionTransformer%601) that outputs [`LinearRegressionModelParameters`](xref:Microsoft.ML.Trainers.LinearRegressionModelParameters). These model parameters contain the learned bias and weights or coefficients of the model. These values are used as a starting point for the new retrained model. +Once the model is loaded, extract the learned model parameters by accessing the [`Model`](xref:Microsoft.ML.Data.PredictionTransformerBase`1.Model%2A) property of the pretrained model. The pretrained model was trained using the linear regression model [`OnlineGradientDescentTrainer`](xref:Microsoft.ML.Trainers.OnlineGradientDescentTrainer), which creates a [`RegressionPredictionTransformer`](xref:Microsoft.ML.Data.RegressionPredictionTransformer`1) that outputs [`LinearRegressionModelParameters`](xref:Microsoft.ML.Trainers.LinearRegressionModelParameters). These model parameters contain the learned bias and weights or coefficients of the model. These values are used as a starting point for the new retrained model. ```csharp // Extract trained model parameters diff --git a/docs/machine-learning/how-to-guides/save-load-machine-learning-models-ml-net.md b/docs/machine-learning/how-to-guides/save-load-machine-learning-models-ml-net.md index dec99c6a37ca0..4741480af1cb1 100644 --- a/docs/machine-learning/how-to-guides/save-load-machine-learning-models-ml-net.md +++ b/docs/machine-learning/how-to-guides/save-load-machine-learning-models-ml-net.md @@ -57,7 +57,7 @@ ITransformer trainedModel = pipelineEstimator.Fit(data); mlContext.Model.Save(trainedModel, data.Schema, "model.zip"); ``` -Because most models and data preparation pipelines inherit from the same set of classes, the save and load method signatures for these components is the same. Depending on your use case, you can either combine the data preparation pipeline and model into a single [`EstimatorChain`](xref:Microsoft.ML.Data.TransformerChain%601) which would output a single [`ITransformer`](xref:Microsoft.ML.ITransformer) or separate them thus creating a separate [`ITransformer`](xref:Microsoft.ML.ITransformer) for each. +Because most models and data preparation pipelines inherit from the same set of classes, the save and load method signatures for these components is the same. Depending on your use case, you can either combine the data preparation pipeline and model into a single [`EstimatorChain`](xref:Microsoft.ML.Data.TransformerChain`1) which would output a single [`ITransformer`](xref:Microsoft.ML.ITransformer) or separate them thus creating a separate [`ITransformer`](xref:Microsoft.ML.ITransformer) for each. ## Save a model locally diff --git a/docs/machine-learning/how-to-guides/serve-model-serverless-azure-functions-ml-net.md b/docs/machine-learning/how-to-guides/serve-model-serverless-azure-functions-ml-net.md index 3a61ead769375..57dca84336479 100644 --- a/docs/machine-learning/how-to-guides/serve-model-serverless-azure-functions-ml-net.md +++ b/docs/machine-learning/how-to-guides/serve-model-serverless-azure-functions-ml-net.md @@ -102,7 +102,7 @@ You need to create some classes for your input data and predictions. Add a new c ## Register PredictionEnginePool service -To make a single prediction, you have to create a [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602). [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) is not thread-safe. Additionally, you have to create an instance of it everywhere it is needed within your application. As your application grows, this process can become unmanageable. For improved performance and thread safety, use a combination of dependency injection and the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool%601) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) objects for use throughout your application. +To make a single prediction, you have to create a [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2). [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) is not thread-safe. Additionally, you have to create an instance of it everywhere it is needed within your application. As your application grows, this process can become unmanageable. For improved performance and thread safety, use a combination of dependency injection and the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool`1) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) objects for use throughout your application. The following link provides more information if you want to learn more about [dependency injection](https://en.wikipedia.org/wiki/Dependency_injection). diff --git a/docs/machine-learning/how-to-guides/serve-model-web-api-ml-net.md b/docs/machine-learning/how-to-guides/serve-model-web-api-ml-net.md index 3200c0aefc0f7..6368ce8ff6344 100644 --- a/docs/machine-learning/how-to-guides/serve-model-web-api-ml-net.md +++ b/docs/machine-learning/how-to-guides/serve-model-web-api-ml-net.md @@ -99,7 +99,7 @@ In your *Program.cs* file: ## Register PredictionEnginePool for use in the application -To make a single prediction, you have to create a [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602). [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) is not thread-safe. Additionally, you have to create an instance of it everywhere it is needed within your application. As your application grows, this process can become unmanageable. For improved performance and thread safety, use a combination of dependency injection and the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool%601) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) objects for use throughout your application. +To make a single prediction, you have to create a [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2). [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) is not thread-safe. Additionally, you have to create an instance of it everywhere it is needed within your application. As your application grows, this process can become unmanageable. For improved performance and thread safety, use a combination of dependency injection and the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool`1) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) objects for use throughout your application. The following link provides more information if you want to learn more about [dependency injection in ASP.NET Core](/aspnet/core/fundamentals/dependency-injection). diff --git a/docs/machine-learning/how-to-guides/train-machine-learning-model-cross-validation-ml-net.md b/docs/machine-learning/how-to-guides/train-machine-learning-model-cross-validation-ml-net.md index 869121288861c..5dee5fe0131e6 100644 --- a/docs/machine-learning/how-to-guides/train-machine-learning-model-cross-validation-ml-net.md +++ b/docs/machine-learning/how-to-guides/train-machine-learning-model-cross-validation-ml-net.md @@ -86,11 +86,11 @@ var cvResults = mlContext.Regression.CrossValidate(transformedData, sdcaEstimato 1. Each model's performance is evaluated using the [`Evaluate`](xref:Microsoft.ML.RegressionCatalog.Evaluate%2A) method on the test data set. 1. The model along with its metrics are returned for each of the models. -The result stored in `cvResults` is a collection of [`CrossValidationResult`](xref:Microsoft.ML.TrainCatalogBase.CrossValidationResult%601) objects. This object includes the trained model as well as metrics which are both accessible form the [`Model`](xref:Microsoft.ML.TrainCatalogBase.CrossValidationResult%601.Model) and [`Metrics`](xref:Microsoft.ML.TrainCatalogBase.CrossValidationResult%601.Metrics) properties respectively. In this sample, the `Model` property is of type [`ITransformer`](xref:Microsoft.ML.ITransformer) and the `Metrics` property is of type [`RegressionMetrics`](xref:Microsoft.ML.Data.RegressionMetrics). +The result stored in `cvResults` is a collection of [`CrossValidationResult`](xref:Microsoft.ML.TrainCatalogBase.CrossValidationResult`1) objects. This object includes the trained model as well as metrics which are both accessible form the [`Model`](xref:Microsoft.ML.TrainCatalogBase.CrossValidationResult`1.Model) and [`Metrics`](xref:Microsoft.ML.TrainCatalogBase.CrossValidationResult`1.Metrics) properties respectively. In this sample, the `Model` property is of type [`ITransformer`](xref:Microsoft.ML.ITransformer) and the `Metrics` property is of type [`RegressionMetrics`](xref:Microsoft.ML.Data.RegressionMetrics). ## Evaluate the model -Metrics for the different trained models can be accessed through the `Metrics` property of the individual [`CrossValidationResult`](xref:Microsoft.ML.TrainCatalogBase.CrossValidationResult%601) object. In this case, the [R-Squared metric](https://en.wikipedia.org/wiki/Coefficient_of_determination) is accessed and stored in the variable `rSquared`. +Metrics for the different trained models can be accessed through the `Metrics` property of the individual [`CrossValidationResult`](xref:Microsoft.ML.TrainCatalogBase.CrossValidationResult`1) object. In this case, the [R-Squared metric](https://en.wikipedia.org/wiki/Coefficient_of_determination) is accessed and stored in the variable `rSquared`. ```csharp IEnumerable rSquared = diff --git a/docs/machine-learning/how-to-guides/train-machine-learning-model-ml-net.md b/docs/machine-learning/how-to-guides/train-machine-learning-model-ml-net.md index d8f54c9608f45..1dd66f5530e95 100644 --- a/docs/machine-learning/how-to-guides/train-machine-learning-model-ml-net.md +++ b/docs/machine-learning/how-to-guides/train-machine-learning-model-ml-net.md @@ -130,11 +130,11 @@ var UserDefinedColumnSdcaEstimator = mlContext.Regression.Trainers.Sdca(labelCol ## Caching data -By default, when data is processed, it's lazily loaded or streamed, which means that trainers might load the data from disk and iterate over it multiple times during training. Therefore, caching is recommended for datasets that fit into memory to reduce the number of times data is loaded from disk. Caching is done as part of an [`EstimatorChain`](xref:Microsoft.ML.Data.EstimatorChain%601) by using [`AppendCacheCheckpoint`](xref:Microsoft.ML.Data.EstimatorChain%601.AppendCacheCheckpoint%2A). +By default, when data is processed, it's lazily loaded or streamed, which means that trainers might load the data from disk and iterate over it multiple times during training. Therefore, caching is recommended for datasets that fit into memory to reduce the number of times data is loaded from disk. Caching is done as part of an [`EstimatorChain`](xref:Microsoft.ML.Data.EstimatorChain`1) by using [`AppendCacheCheckpoint`](xref:Microsoft.ML.Data.EstimatorChain`1.AppendCacheCheckpoint%2A). -It's recommended to use [`AppendCacheCheckpoint`](xref:Microsoft.ML.Data.EstimatorChain%601.AppendCacheCheckpoint%2A) before any trainers in the pipeline. +It's recommended to use [`AppendCacheCheckpoint`](xref:Microsoft.ML.Data.EstimatorChain`1.AppendCacheCheckpoint%2A) before any trainers in the pipeline. -Using the following [`EstimatorChain`](xref:Microsoft.ML.Data.EstimatorChain%601), adding [`AppendCacheCheckpoint`](xref:Microsoft.ML.Data.EstimatorChain%601.AppendCacheCheckpoint%2A) before the [`StochasticDualCoordinateAscent`](xref:Microsoft.ML.Trainers.SdcaRegressionTrainer) trainer caches the results of the previous estimators for later use by the trainer. +Using the following [`EstimatorChain`](xref:Microsoft.ML.Data.EstimatorChain`1), adding [`AppendCacheCheckpoint`](xref:Microsoft.ML.Data.EstimatorChain`1.AppendCacheCheckpoint%2A) before the [`StochasticDualCoordinateAscent`](xref:Microsoft.ML.Trainers.SdcaRegressionTrainer) trainer caches the results of the previous estimators for later use by the trainer. ```csharp // 1. Concatenate Size and Historical into a single feature vector output to a new column called Features @@ -150,7 +150,7 @@ IEstimator dataPrepEstimator = ## Train the machine learning model -Once the data is preprocessed, use the [`Fit`](xref:Microsoft.ML.Trainers.TrainerEstimatorBase%602.Fit%2A) method to train the machine learning model with the [`StochasticDualCoordinateAscent`](xref:Microsoft.ML.Trainers.SdcaRegressionTrainer) regression algorithm. +Once the data is preprocessed, use the [`Fit`](xref:Microsoft.ML.Trainers.TrainerEstimatorBase`2.Fit%2A) method to train the machine learning model with the [`StochasticDualCoordinateAscent`](xref:Microsoft.ML.Trainers.SdcaRegressionTrainer) regression algorithm. ```csharp // Define StochasticDualCoordinateAscent regression algorithm estimator @@ -162,7 +162,7 @@ var trainedModel = sdcaEstimator.Fit(transformedTrainingData); ## Extract model parameters -After the model has been trained, extract the learned [`ModelParameters`](xref:Microsoft.ML.Trainers.ModelParametersBase%601) for inspection or retraining. The [`LinearRegressionModelParameters`](xref:Microsoft.ML.Trainers.LinearRegressionModelParameters) provide the bias and learned coefficients or weights of the trained model. +After the model has been trained, extract the learned [`ModelParameters`](xref:Microsoft.ML.Trainers.ModelParametersBase`1) for inspection or retraining. The [`LinearRegressionModelParameters`](xref:Microsoft.ML.Trainers.LinearRegressionModelParameters) provide the bias and learned coefficients or weights of the trained model. ```csharp var trainedModelParameters = trainedModel.Model as LinearRegressionModelParameters; diff --git a/docs/machine-learning/resources/glossary.md b/docs/machine-learning/resources/glossary.md index de9dc85738851..ba3dfdf5cf4da 100644 --- a/docs/machine-learning/resources/glossary.md +++ b/docs/machine-learning/resources/glossary.md @@ -48,9 +48,9 @@ Data is central to any machine learning application. In ML.NET data is represent ## Estimator -A class in ML.NET that implements the interface. +A class in ML.NET that implements the interface. -An estimator is a specification of a transformation (both data preparation transformation and machine learning model training transformation). Estimators can be chained together into a pipeline of transformations. The parameters of an estimator or pipeline of estimators are learned when is called. The result of is a [Transformer](#transformer). +An estimator is a specification of a transformation (both data preparation transformation and machine learning model training transformation). Estimators can be chained together into a pipeline of transformations. The parameters of an estimator or pipeline of estimators are learned when is called. The result of is a [Transformer](#transformer). ## Extension method diff --git a/docs/machine-learning/resources/tasks.md b/docs/machine-learning/resources/tasks.md index 5b6ab4636b01d..6f7f1bb6060c1 100644 --- a/docs/machine-learning/resources/tasks.md +++ b/docs/machine-learning/resources/tasks.md @@ -282,7 +282,7 @@ The forecasting task use past time-series data to make predictions about future You can train a forecasting model with the following algorithm: - + ## Object detection diff --git a/docs/machine-learning/resources/transforms.md b/docs/machine-learning/resources/transforms.md index 80e3f0bfa3628..c82fced054850 100644 --- a/docs/machine-learning/resources/transforms.md +++ b/docs/machine-learning/resources/transforms.md @@ -13,123 +13,123 @@ Data transformations are used to: - Apply an imported model in TensorFlow or ONNX format. - Post-process data after it has been passed through a model. -The transformations in this guide return classes that implement the [IEstimator](xref:Microsoft.ML.IEstimator%601) interface. Data transformations can be chained together. Each transformation both expects and produces data of specific types and formats, which are specified in the linked reference documentation. +The transformations in this guide return classes that implement the [IEstimator](xref:Microsoft.ML.IEstimator`1) interface. Data transformations can be chained together. Each transformation both expects and produces data of specific types and formats, which are specified in the linked reference documentation. -Some data transformations require training data to calculate their parameters. For example: the transformer calculates the mean and variance of the training data during the `Fit()` operation, and uses those parameters in the `Transform()` operation. +Some data transformations require training data to calculate their parameters. For example: the transformer calculates the mean and variance of the training data during the `Fit()` operation, and uses those parameters in the `Transform()` operation. -Other data transformations don't require training data. For example: the transformation can perform the `Transform()` operation without having seen any training data during the `Fit()` operation. +Other data transformations don't require training data. For example: the transformation can perform the `Transform()` operation without having seen any training data during the `Fit()` operation. ## Column mapping and grouping | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Concatenate one or more input columns into a new output column | Yes | -| | Copy and rename one or more input columns | Yes | -| | Drop one or more input columns | Yes | -| | Select one or more columns to keep from the input data | Yes | +| | Concatenate one or more input columns into a new output column | Yes | +| | Copy and rename one or more input columns | Yes | +| | Drop one or more input columns | Yes | +| | Select one or more columns to keep from the input data | Yes | ## Normalization and scaling | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Subtract the mean (of the training data) and divide by the variance (of the training data) | Yes | -| | Normalize based on the logarithm of the training data | Yes | -| | Scale input vectors by their [lp-norm](https://en.wikipedia.org/wiki/Lp_space#The_p-norm_in_finite_dimensions), where p is 1, 2 or infinity. Defaults to the l2 (Euclidean distance) norm | Yes | -| | Scale each value in a row by subtracting the mean of the row data and divide by either the standard deviation or l2-norm (of the row data), and multiply by a configurable scale factor (default 2) | Yes | -| | Assign the input value to a bin index and divide by the number of bins to produce a float value between 0 and 1. The bin boundaries are calculated to evenly distribute the training data across bins | Yes | -| | Assign the input value to a bin based on its correlation with label column | Yes | -| | Scale the input by the difference between the minimum and maximum values in the training data | Yes | -| | Scale each value using statistics that are robust to outliers that will center the data around 0 and scales the data according to the quantile range. | Yes | +| | Subtract the mean (of the training data) and divide by the variance (of the training data) | Yes | +| | Normalize based on the logarithm of the training data | Yes | +| | Scale input vectors by their [lp-norm](https://en.wikipedia.org/wiki/Lp_space#The_p-norm_in_finite_dimensions), where p is 1, 2 or infinity. Defaults to the l2 (Euclidean distance) norm | Yes | +| | Scale each value in a row by subtracting the mean of the row data and divide by either the standard deviation or l2-norm (of the row data), and multiply by a configurable scale factor (default 2) | Yes | +| | Assign the input value to a bin index and divide by the number of bins to produce a float value between 0 and 1. The bin boundaries are calculated to evenly distribute the training data across bins | Yes | +| | Assign the input value to a bin based on its correlation with label column | Yes | +| | Scale the input by the difference between the minimum and maximum values in the training data | Yes | +| | Scale each value using statistics that are robust to outliers that will center the data around 0 and scales the data according to the quantile range. | Yes | ## Conversions between data types | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Convert the type of an input column to a new type | Yes | -| | Map values to keys (categories) based on the supplied dictionary of mappings | No | -| | Map values to keys (categories) by creating the mapping from the input data | Yes | -| | Convert keys back to their original values | Yes | -| | Convert keys back to vectors of original values | Yes | -| | Convert keys back to a binary vector of original values | No | -| | Hash the value in the input column | Yes | +| | Convert the type of an input column to a new type | Yes | +| | Map values to keys (categories) based on the supplied dictionary of mappings | No | +| | Map values to keys (categories) by creating the mapping from the input data | Yes | +| | Convert keys back to their original values | Yes | +| | Convert keys back to vectors of original values | Yes | +| | Convert keys back to a binary vector of original values | No | +| | Hash the value in the input column | Yes | ## Text transformations | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Transform a text column into a float array of normalized ngrams and char-grams counts | No | -| | Split one or more text columns into individual words | Yes | -| | Split one or more text columns into individual characters floats over a set of topics | Yes | -| | Change case, remove diacritical marks, punctuation marks, and numbers | Yes | -| | Transform text column into a bag of counts of ngrams (sequences of consecutive words)| Yes | -| | Transform text column into a bag of counts of ngrams vector | Yes | -| | Transform text column into a vector of hashed ngram counts | No | -| | Transform text column into a bag of hashed ngram counts | Yes | -| | Remove default stop words for the specified language from input columns | Yes | -| | Removes specified stop words from input columns | Yes | -| | Transform a document (represented as a vector of floats) into a vector of floats over a set of topics | Yes | -| | Convert vectors of text tokens into sentence vectors using a pretrained model | Yes | +| | Transform a text column into a float array of normalized ngrams and char-grams counts | No | +| | Split one or more text columns into individual words | Yes | +| | Split one or more text columns into individual characters floats over a set of topics | Yes | +| | Change case, remove diacritical marks, punctuation marks, and numbers | Yes | +| | Transform text column into a bag of counts of ngrams (sequences of consecutive words)| Yes | +| | Transform text column into a bag of counts of ngrams vector | Yes | +| | Transform text column into a vector of hashed ngram counts | No | +| | Transform text column into a bag of hashed ngram counts | Yes | +| | Remove default stop words for the specified language from input columns | Yes | +| | Removes specified stop words from input columns | Yes | +| | Transform a document (represented as a vector of floats) into a vector of floats over a set of topics | Yes | +| | Convert vectors of text tokens into sentence vectors using a pretrained model | Yes | ## Image transformations | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Convert an image to grayscale | No | -| | Convert a vector of pixels to | No | -| | Convert pixels from input image into a vector of numbers | No | -| | Load images from a folder into memory | No | -| | Loads images of raw bytes into a new column. | No | -| | Resize images | No | -| | Applies a pretrained deep neural network (DNN) model to transform an input image into a feature vector | No | +| | Convert an image to grayscale | No | +| | Convert a vector of pixels to | No | +| | Convert pixels from input image into a vector of numbers | No | +| | Load images from a folder into memory | No | +| | Loads images of raw bytes into a new column. | No | +| | Resize images | No | +| | Applies a pretrained deep neural network (DNN) model to transform an input image into a feature vector | No | ## Categorical data transformations | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Convert one or more text columns into [one-hot](https://en.wikipedia.org/wiki/One-hot) encoded vectors | Yes | -| | Convert one or more text columns into hash-based one-hot encoded vectors | No | +| | Convert one or more text columns into [one-hot](https://en.wikipedia.org/wiki/One-hot) encoded vectors | Yes | +| | Convert one or more text columns into hash-based one-hot encoded vectors | No | ## Time series data transformations | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Detect anomalies in the input time series data using the Spectral Residual (SR) algorithm | No | -| | Detect change points in time series data using singular spectrum analysis (SSA) | No | -| | Detect change points in independent and identically distributed (IID) time series data using adaptive kernel density estimations and martingale scores | No | -| | Forecast time series data using singular spectrum analysis (SSA) | No | -| | Detect spikes in time series data using singular spectrum analysis (SSA) | No | -| | Detect spikes in independent and identically distributed (IID) time series data using adaptive kernel density estimations and martingale scores | No | -| | Detect anomalies for the entire input data using the SRCNN algorithm. | No | -| | Detect seasonality using fourier analysis. | No | -| | Localizes root cause from time series input using a decision tree algorithm. | No | -| | Localizes root causes from tie series input. | No | +| | Detect anomalies in the input time series data using the Spectral Residual (SR) algorithm | No | +| | Detect change points in time series data using singular spectrum analysis (SSA) | No | +| | Detect change points in independent and identically distributed (IID) time series data using adaptive kernel density estimations and martingale scores | No | +| | Forecast time series data using singular spectrum analysis (SSA) | No | +| | Detect spikes in time series data using singular spectrum analysis (SSA) | No | +| | Detect spikes in independent and identically distributed (IID) time series data using adaptive kernel density estimations and martingale scores | No | +| | Detect anomalies for the entire input data using the SRCNN algorithm. | No | +| | Detect seasonality using fourier analysis. | No | +| | Localizes root cause from time series input using a decision tree algorithm. | No | +| | Localizes root causes from tie series input. | No | ## Missing values | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Create a new boolean output column, the value of which is true when the value in the input column is missing | Yes | -| | Create a new output column, the value of which is set to a default value if the value is missing from the input column, and the input value otherwise | Yes | +| | Create a new boolean output column, the value of which is true when the value in the input column is missing | Yes | +| | Create a new output column, the value of which is set to a default value if the value is missing from the input column, and the input value otherwise | Yes | ## Feature selection | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Select features whose non-default values are greater than a threshold | Yes | -| | Select the features on which the data in the label column is most dependent | Yes | +| | Select features whose non-default values are greater than a threshold | Yes | +| | Select the features on which the data in the label column is most dependent | Yes | ## Feature transformations | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Map each input vector onto a lower dimensional feature space, where inner products approximate a kernel function, so that the features can be used as inputs to the linear algorithms | No | -| | Reduce the dimensions of the input feature vector by applying the Principal Component Analysis algorithm | | +| | Map each input vector onto a lower dimensional feature space, where inner products approximate a kernel function, so that the features can be used as inputs to the linear algorithms | No | +| | Reduce the dimensions of the input feature vector by applying the Principal Component Analysis algorithm | | ## Explainability transformations | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Calculate contribution scores for each element of a feature vector | No | +| | Calculate contribution scores for each element of a feature vector | No | ## Calibration transformations @@ -137,21 +137,21 @@ Other data transformations don't require training data. For example: the | Transforms a binary classifier raw score into a class probability using logistic regression with parameters estimated using the training data | Yes | | | Transforms a binary classifier raw score into a class probability using logistic regression with fixed parameters | Yes | -| | Transforms a binary classifier raw score into a class probability by assigning scores to bins, and calculating the probability based on the distribution among the bins | Yes | -| | Transforms a binary classifier raw score into a class probability by assigning scores to bins, where the position of boundaries and the size of bins are estimated using the training data | No | +| | Transforms a binary classifier raw score into a class probability by assigning scores to bins, and calculating the probability based on the distribution among the bins | Yes | +| | Transforms a binary classifier raw score into a class probability by assigning scores to bins, where the position of boundaries and the size of bins are estimated using the training data | No | ## Deep learning transformations | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Transform the input data with an imported ONNX model | No | -| | Transform the input data with an imported TensorFlow model | No | +| | Transform the input data with an imported ONNX model | No | +| | Transform the input data with an imported TensorFlow model | No | ## Custom transformations | Transform | Definition | ONNX Exportable | | --- | --- | --- | -| | Drops rows where a specified predicate returns true. | No | -| | Drops rows where a specified predicate returns true, but allows for a specified state. | No | -| | Transform existing columns onto new ones with a user-defined mapping | No | -| | Apply an expression to transform columns into new ones | No | +| | Drops rows where a specified predicate returns true. | No | +| | Drops rows where a specified predicate returns true, but allows for a specified state. | No | +| | Transform existing columns onto new ones with a user-defined mapping | No | +| | Apply an expression to transform columns into new ones | No | diff --git a/docs/machine-learning/tutorials/github-issue-classification.md b/docs/machine-learning/tutorials/github-issue-classification.md index 740743b7772ae..e71384628295f 100644 --- a/docs/machine-learning/tutorials/github-issue-classification.md +++ b/docs/machine-learning/tutorials/github-issue-classification.md @@ -69,7 +69,7 @@ Create three global fields to hold the paths to the recently downloaded files, a * `_modelPath` has the path where the trained model is saved. * `_mlContext` is the that provides processing context. * `_trainingDataView` is the used to process the training dataset. -* `_predEngine` is the used for single predictions. +* `_predEngine` is the used for single predictions. Add the following code to the line directly below the `using` directives to specify those paths and the other variables: @@ -118,7 +118,7 @@ To initialize and load the `_trainingDataView` global variable in order to use i [!code-csharp[LoadTrainData](./snippets/github-issue-classification/csharp/Program.cs#LoadTrainData)] -The [LoadFromTextFile()](xref:Microsoft.ML.TextLoaderSaverCatalog.LoadFromTextFile%60%601%28Microsoft.ML.DataOperationsCatalog,System.String,System.Char,System.Boolean,System.Boolean,System.Boolean,System.Boolean%29) defines the data schema and reads in the file. It takes in the data path variables and returns an `IDataView`. +The [LoadFromTextFile()](xref:Microsoft.ML.TextLoaderSaverCatalog.LoadFromTextFile``1%28Microsoft.ML.DataOperationsCatalog,System.String,System.Char,System.Boolean,System.Boolean,System.Boolean,System.Boolean%29) defines the data schema and reads in the file. It takes in the data path variables and returns an `IDataView`. Add the following after calling the `LoadFromTextFile()` method: @@ -152,7 +152,7 @@ The last step in data preparation combines all of the feature columns into the * [!code-csharp[Concatenate](./snippets/github-issue-classification/csharp/Program.cs#Concatenate)] -Next, append a to cache the DataView so when you iterate over the data multiple times using the cache might get better performance, as with the following code: +Next, append a to cache the DataView so when you iterate over the data multiple times using the cache might get better performance, as with the following code: [!code-csharp[AppendCache](./snippets/github-issue-classification/csharp/Program.cs#AppendCache)] @@ -210,7 +210,7 @@ Fit the model to the `splitTrainSet` data and return the trained model by adding The `Fit()`method trains your model by transforming the dataset and applying the training. -The [PredictionEngine](xref:Microsoft.ML.PredictionEngine%602) is a convenience API that allows you to pass in and then perform a prediction on a single instance of data. Add this as the next line in the `BuildAndTrainModel()` method: +The [PredictionEngine](xref:Microsoft.ML.PredictionEngine`2) is a convenience API that allows you to pass in and then perform a prediction on a single instance of data. Add this as the next line in the `BuildAndTrainModel()` method: [!code-csharp[CreatePredictionEngine1](./snippets/github-issue-classification/csharp/Program.cs#CreatePredictionEngine1)] @@ -220,7 +220,7 @@ Add a GitHub issue to test the trained model's prediction in the `Predict` metho [!code-csharp[CreateTestIssue1](./snippets/github-issue-classification/csharp/Program.cs#CreateTestIssue1)] -Use the [Predict()](xref:Microsoft.ML.PredictionEngine%602.Predict%2A) function to make a prediction on a single row of data: +Use the [Predict()](xref:Microsoft.ML.PredictionEngine`2.Predict%2A) function to make a prediction on a single row of data: [!code-csharp[Predict](./snippets/github-issue-classification/csharp/Program.cs#Predict)] @@ -335,7 +335,7 @@ As you did previously, create a `PredictionEngine` instance with the following c [!code-csharp[CreatePredictionEngine](./snippets/github-issue-classification/csharp/Program.cs#CreatePredictionEngine)] -The [PredictionEngine](xref:Microsoft.ML.PredictionEngine%602) is a convenience API that allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool%601) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). +The [PredictionEngine](xref:Microsoft.ML.PredictionEngine`2) is a convenience API that allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool`1) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). > [!NOTE] > `PredictionEnginePool` service extension is currently in preview. diff --git a/docs/machine-learning/tutorials/image-classification-api-transfer-learning.md b/docs/machine-learning/tutorials/image-classification-api-transfer-learning.md index 851c6e04cdf2a..a457509773d74 100644 --- a/docs/machine-learning/tutorials/image-classification-api-transfer-learning.md +++ b/docs/machine-learning/tutorials/image-classification-api-transfer-learning.md @@ -198,8 +198,8 @@ The previous code: - Calls the `LoadImagesFromDirectory` utility method to get the list of images used for training after initializing the `mlContext` variable. - Loads the images into an [`IDataView`](xref:Microsoft.ML.IDataView) using the [`LoadFromEnumerable`](xref:Microsoft.ML.DataOperationsCatalog.LoadFromEnumerable%2A) method. - Shuffles the data using the [`ShuffleRows`](xref:Microsoft.ML.DataOperationsCatalog.ShuffleRows%2A) method. The data is loaded in the order it was read from the directories. The shuffle is performed to balance it. -- Performs some preprocessing on the data prior to training. This is done because machine learning models expect input to be in numerical format. The preprocessing code creates an [`EstimatorChain`](xref:Microsoft.ML.Data.EstimatorChain%601) made up of the [`MapValueToKey`](xref:Microsoft.ML.ConversionsExtensionsCatalog.MapValueToKey%2A) and `LoadRawImageBytes` transforms. The `MapValueToKey` transform takes the categorical value in the `Label` column, converts it to a numerical `KeyType` value and stores it in a new column called `LabelAsKey`. The `LoadImages` takes the values from the `ImagePath` column along with the `imageFolder` parameter to load images for training. -- Uses the [`Fit`](xref:Microsoft.ML.Data.EstimatorChain%601.Fit%2A) method to apply the data to the `preprocessingPipeline` [`EstimatorChain`](xref:Microsoft.ML.Data.EstimatorChain%601) followed by the [`Transform`](xref:Microsoft.ML.Data.TransformerChain%601.Transform%2A) method, which returns an [`IDataView`](xref:Microsoft.ML.IDataView) containing the preprocessed data. +- Performs some preprocessing on the data prior to training. This is done because machine learning models expect input to be in numerical format. The preprocessing code creates an [`EstimatorChain`](xref:Microsoft.ML.Data.EstimatorChain`1) made up of the [`MapValueToKey`](xref:Microsoft.ML.ConversionsExtensionsCatalog.MapValueToKey%2A) and `LoadRawImageBytes` transforms. The `MapValueToKey` transform takes the categorical value in the `Label` column, converts it to a numerical `KeyType` value and stores it in a new column called `LabelAsKey`. The `LoadImages` takes the values from the `ImagePath` column along with the `imageFolder` parameter to load images for training. +- Uses the [`Fit`](xref:Microsoft.ML.Data.EstimatorChain`1.Fit%2A) method to apply the data to the `preprocessingPipeline` [`EstimatorChain`](xref:Microsoft.ML.Data.EstimatorChain`1) followed by the [`Transform`](xref:Microsoft.ML.Data.TransformerChain`1.Transform%2A) method, which returns an [`IDataView`](xref:Microsoft.ML.IDataView) containing the preprocessed data. - Splits the data into training, validation, and test sets. To train a model, it's important to have a training dataset as well as a validation dataset. The model is trained on the training set. How well it makes predictions on unseen data is measured by the performance against the validation set. Based on the results of that performance, the model makes adjustments to what it has learned in an effort to improve. The validation set can come from either splitting your original dataset or from another source that has already been set aside for this purpose. @@ -229,8 +229,8 @@ The previous code: - `ReuseTrainSetBottleneckCachedValues` tells the model whether to use the cached values from the bottleneck phase in subsequent runs. The bottleneck phase is a one-time pass-through computation that is computationally intensive the first time it's performed. If the training data does not change and you want to experiment using a different number of epochs or batch size, using the cached values significantly reduces the amount of time required to train a model. - `ReuseValidationSetBottleneckCachedValues` is similar to `ReuseTrainSetBottleneckCachedValues` only that in this case it's for the validation dataset. -- Defines the [`EstimatorChain`](xref:Microsoft.ML.Data.EstimatorChain%601) training pipeline that consists of both the `mapLabelEstimator` and the . -- Uses the [`Fit`](xref:Microsoft.ML.Data.EstimatorChain%601.Fit%2A) method to train the model. +- Defines the [`EstimatorChain`](xref:Microsoft.ML.Data.EstimatorChain`1) training pipeline that consists of both the `mapLabelEstimator` and the . +- Uses the [`Fit`](xref:Microsoft.ML.Data.EstimatorChain`1.Fit%2A) method to train the model. ## Use the model @@ -248,9 +248,9 @@ Create a new utility method called `OutputPrediction` to display prediction info The `ClassifySingleImage` method: - - Creates a [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) inside the `ClassifySingleImage` method. The [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) is a convenience API that allows you to pass in and then perform a prediction on a single instance of data. - - To access a single `ModelInput` instance, converts the `data` [`IDataView`](xref:Microsoft.ML.IDataView) into an [`IEnumerable`](xref:System.Collections.Generic.IEnumerable%601) using the [`CreateEnumerable`](xref:Microsoft.ML.DataOperationsCatalog.CreateEnumerable%2A) method and then gets the first observation. - - Uses the [`Predict`](xref:Microsoft.ML.PredictionEngine%602.Predict%2A) method to classify the image. + - Creates a [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) inside the `ClassifySingleImage` method. The [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) is a convenience API that allows you to pass in and then perform a prediction on a single instance of data. + - To access a single `ModelInput` instance, converts the `data` [`IDataView`](xref:Microsoft.ML.IDataView) into an [`IEnumerable`](xref:System.Collections.Generic.IEnumerable`1) using the [`CreateEnumerable`](xref:Microsoft.ML.DataOperationsCatalog.CreateEnumerable%2A) method and then gets the first observation. + - Uses the [`Predict`](xref:Microsoft.ML.PredictionEngine`2.Predict%2A) method to classify the image. - Outputs the prediction to the console with the `OutputPrediction` method. 1. Call `ClassifySingleImage` after you call the `Fit` method using the test set of images. @@ -266,7 +266,7 @@ Create a new utility method called `OutputPrediction` to display prediction info The `ClassifyImages` method: - Creates an [`IDataView`](xref:Microsoft.ML.IDataView) containing the predictions by using the [`Transform`](xref:Microsoft.ML.ITransformer.Transform%2A) method. - - In order to iterate over the predictions, converts the `predictionData` [`IDataView`](xref:Microsoft.ML.IDataView) into an [`IEnumerable`](xref:System.Collections.Generic.IEnumerable%601) using the [`CreateEnumerable`](xref:Microsoft.ML.DataOperationsCatalog.CreateEnumerable%2A) method and then gets the first 10 observations. + - In order to iterate over the predictions, converts the `predictionData` [`IDataView`](xref:Microsoft.ML.IDataView) into an [`IEnumerable`](xref:System.Collections.Generic.IEnumerable`1) using the [`CreateEnumerable`](xref:Microsoft.ML.DataOperationsCatalog.CreateEnumerable%2A) method and then gets the first 10 observations. - Iterates and outputs the original and predicted labels for the predictions. 1. Call `ClassifyImages` after you call the `ClassifySingleImage()` method using the test set of images. diff --git a/docs/machine-learning/tutorials/image-classification.md b/docs/machine-learning/tutorials/image-classification.md index 5243d8f7fc951..3a4dbe52aa5d0 100644 --- a/docs/machine-learning/tutorials/image-classification.md +++ b/docs/machine-learning/tutorials/image-classification.md @@ -219,7 +219,7 @@ Since you'll display the image data and the related predictions more than once, [!code-csharp[PredictSingle](./snippets/image-classification/csharp/Program.cs#PredictSingle)] - To get the prediction, use the [Predict()](xref:Microsoft.ML.PredictionEngine%602.Predict%2A) method. The [PredictionEngine](xref:Microsoft.ML.PredictionEngine%602) is a convenience API, which allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool%601) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). + To get the prediction, use the [Predict()](xref:Microsoft.ML.PredictionEngine`2.Predict%2A) method. The [PredictionEngine](xref:Microsoft.ML.PredictionEngine`2) is a convenience API, which allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool`1) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). > [!NOTE] > `PredictionEnginePool` service extension is currently in preview. diff --git a/docs/machine-learning/tutorials/iris-clustering.md b/docs/machine-learning/tutorials/iris-clustering.md index f3c2aa41259d1..59e05a7fc44c2 100644 --- a/docs/machine-learning/tutorials/iris-clustering.md +++ b/docs/machine-learning/tutorials/iris-clustering.md @@ -119,7 +119,7 @@ Add the following code below the `MLContext` to set up the way to load data: [!code-csharp[Create text loader](./snippets/iris-clustering/csharp/Program.cs#CreateDataView)] -The generic [`MLContext.Data.LoadFromTextFile` extension method](xref:Microsoft.ML.TextLoaderSaverCatalog.LoadFromTextFile%60%601%28Microsoft.ML.DataOperationsCatalog,System.String,System.Char,System.Boolean,System.Boolean,System.Boolean,System.Boolean%29) infers the data set schema from the provided `IrisData` type and returns which can be used as input for transformers. +The generic [`MLContext.Data.LoadFromTextFile` extension method](xref:Microsoft.ML.TextLoaderSaverCatalog.LoadFromTextFile``1%28Microsoft.ML.DataOperationsCatalog,System.String,System.Char,System.Boolean,System.Boolean,System.Boolean,System.Boolean%29) infers the data set schema from the provided `IrisData` type and returns which can be used as input for transformers. ## Create a learning pipeline @@ -148,11 +148,11 @@ At this point, you have a model that can be integrated into any of your existing ## Use the model for predictions -To make predictions, use the class that takes instances of the input type through the transformer pipeline and produces instances of the output type. Add the following line to create an instance of that class: +To make predictions, use the class that takes instances of the input type through the transformer pipeline and produces instances of the output type. Add the following line to create an instance of that class: [!code-csharp[Create predictor](./snippets/iris-clustering/csharp/Program.cs#Predictor)] -The [PredictionEngine](xref:Microsoft.ML.PredictionEngine%602) is a convenience API, which allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool%601) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). +The [PredictionEngine](xref:Microsoft.ML.PredictionEngine`2) is a convenience API, which allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool`1) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). > [!NOTE] > `PredictionEnginePool` service extension is currently in preview. diff --git a/docs/machine-learning/tutorials/movie-recommendation-model-builder.md b/docs/machine-learning/tutorials/movie-recommendation-model-builder.md index 1e2b5c169c700..bca588183a6ef 100644 --- a/docs/machine-learning/tutorials/movie-recommendation-model-builder.md +++ b/docs/machine-learning/tutorials/movie-recommendation-model-builder.md @@ -98,7 +98,7 @@ Throughout the training process, progress data is displayed in the `Training res Once training is complete the `mbconfig` file will have the generated model called `MovieRecommender.zip` after training and two C# files with it: -- **MovieRecommender.consumption.cs**: This file has a public method `Predict` that loads the model and creates a [PredictionEngine](xref:Microsoft.ML.PredictionEngine%602) to make predictions. [PredictionEngine](xref:Microsoft.ML.PredictionEngine%602) is a convenience API for making predictions on a single data instance. +- **MovieRecommender.consumption.cs**: This file has a public method `Predict` that loads the model and creates a [PredictionEngine](xref:Microsoft.ML.PredictionEngine`2) to make predictions. [PredictionEngine](xref:Microsoft.ML.PredictionEngine`2) is a convenience API for making predictions on a single data instance. - **MovieRecommender.training.cs**: This file consists of the training pipeline that Model Builder came up with to build the best model including any hyperparameters that it used. Click the **Next step** button to navigate to the evaluate step. diff --git a/docs/machine-learning/tutorials/movie-recommendation.md b/docs/machine-learning/tutorials/movie-recommendation.md index 2e233692096e6..938585af5c12b 100644 --- a/docs/machine-learning/tutorials/movie-recommendation.md +++ b/docs/machine-learning/tutorials/movie-recommendation.md @@ -159,7 +159,7 @@ Initialize your data path variables, load the data from the \*.csv files, and re Data in ML.NET is represented as an [IDataView interface](xref:Microsoft.ML.IDataView). `IDataView` is a flexible, efficient way of describing tabular data (numeric and text). Data can be loaded from a text file or in real time (for example, SQL database or log files) to an `IDataView` object. -The [LoadFromTextFile()](xref:Microsoft.ML.TextLoaderSaverCatalog.LoadFromTextFile%60%601%28Microsoft.ML.DataOperationsCatalog,System.String,System.Char,System.Boolean,System.Boolean,System.Boolean,System.Boolean%29) defines the data schema and reads in the file. It takes in the data path variables and returns an `IDataView`. In this case, you provide the path for your `Test` and `Train` files and indicate both the text file header (so it can use the column names properly) and the comma character data separator (the default separator is a tab). +The [LoadFromTextFile()](xref:Microsoft.ML.TextLoaderSaverCatalog.LoadFromTextFile``1%28Microsoft.ML.DataOperationsCatalog,System.String,System.Char,System.Boolean,System.Boolean,System.Boolean,System.Boolean%29) defines the data schema and reads in the file. It takes in the data path variables and returns an `IDataView`. In this case, you provide the path for your `Test` and `Train` files and indicate both the text file header (so it can use the column names properly) and the comma character data separator (the default separator is a tab). Add the following code to call your `LoadData()` method and return the `Train` and `Test` data: @@ -308,7 +308,7 @@ Use the `PredictionEngine` to predict the rating by adding the following code to [!code-csharp[PredictionEngine](./snippets/movie-recommendation/csharp/Program.cs#PredictionEngine "Create Prediction Engine")] -The [PredictionEngine](xref:Microsoft.ML.PredictionEngine%602) is a convenience API, which allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool%601) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). +The [PredictionEngine](xref:Microsoft.ML.PredictionEngine`2) is a convenience API, which allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool`1) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). > [!NOTE] > `PredictionEnginePool` service extension is currently in preview. @@ -317,7 +317,7 @@ Create an instance of `MovieRating` called `testInput` and pass it to the Predic [!code-csharp[MakeSinglePrediction](./snippets/movie-recommendation/csharp/Program.cs#MakeSinglePrediction "Make a single prediction with the Prediction Engine")] -The [Predict()](xref:Microsoft.ML.PredictionEngine%602.Predict%2A) function makes a prediction on a single column of data. +The [Predict()](xref:Microsoft.ML.PredictionEngine`2.Predict%2A) function makes a prediction on a single column of data. You can then use the `Score`, or the predicted rating, to determine whether you want to recommend the movie with movieId 10 to user 6. The higher the `Score`, the higher the likelihood of a user liking a particular movie. In this case, let’s say that you recommend movies with a predicted rating of > 3.5. diff --git a/docs/machine-learning/tutorials/object-detection-custom-vision-onnx.md b/docs/machine-learning/tutorials/object-detection-custom-vision-onnx.md index e07e4ae32ec81..202655a6478f5 100644 --- a/docs/machine-learning/tutorials/object-detection-custom-vision-onnx.md +++ b/docs/machine-learning/tutorials/object-detection-custom-vision-onnx.md @@ -275,7 +275,7 @@ Loop through the file paths to make a prediction with the model and output the r var prediction = predictionEngine.Predict(new StopSignInput { Image = testImage }); ``` -1. With the prediction, you can get the bounding boxes. Use the method to determine how many objects the model has detected. Do this by taking the count of the predicted bounding boxes and dividing that by the number of labels that were predicted. For example, if you had three objects detected in an image, there would be 12 items in the `BoundingBoxes` array and three labels predicted. The `Chunk` method would then give you three arrays of four to represent the bounding boxes for each object. +1. With the prediction, you can get the bounding boxes. Use the method to determine how many objects the model has detected. Do this by taking the count of the predicted bounding boxes and dividing that by the number of labels that were predicted. For example, if you had three objects detected in an image, there would be 12 items in the `BoundingBoxes` array and three labels predicted. The `Chunk` method would then give you three arrays of four to represent the bounding boxes for each object. ```csharp var boundingBoxes = prediction.BoundingBoxes.Chunk(prediction.BoundingBoxes.Count() / prediction.PredictedLabels.Count()); diff --git a/docs/machine-learning/tutorials/object-detection-onnx.md b/docs/machine-learning/tutorials/object-detection-onnx.md index 8a0d6cedf6c1b..74dc939b5f060 100644 --- a/docs/machine-learning/tutorials/object-detection-onnx.md +++ b/docs/machine-learning/tutorials/object-detection-onnx.md @@ -486,7 +486,7 @@ Just like with post-processing, there are a few steps in the scoring steps. To h [!code-csharp [LoadModelLog](~/machinelearning-samples/samples/csharp/getting-started/DeepLearning_ObjectDetection_Onnx/ObjectDetectionConsoleApp/OnnxModelScorer.cs#L47-L49)] - ML.NET pipelines need to know the data schema to operate on when the [`Fit`](xref:Microsoft.ML.IEstimator%601.Fit%2A) method is called. In this case, a process similar to training will be used. However, because no actual training is happening, it is acceptable to use an empty [`IDataView`](xref:Microsoft.ML.IDataView). Create a new [`IDataView`](xref:Microsoft.ML.IDataView) for the pipeline from an empty list. + ML.NET pipelines need to know the data schema to operate on when the [`Fit`](xref:Microsoft.ML.IEstimator`1.Fit%2A) method is called. In this case, a process similar to training will be used. However, because no actual training is happening, it is acceptable to use an empty [`IDataView`](xref:Microsoft.ML.IDataView). Create a new [`IDataView`](xref:Microsoft.ML.IDataView) for the pipeline from an empty list. [!code-csharp [LoadEmptyIDV](~/machinelearning-samples/samples/csharp/getting-started/DeepLearning_ObjectDetection_Onnx/ObjectDetectionConsoleApp/OnnxModelScorer.cs#L52)] @@ -501,7 +501,7 @@ Just like with post-processing, there are a few steps in the scoring steps. To h [!code-csharp [ScoringPipeline](~/machinelearning-samples/samples/csharp/getting-started/DeepLearning_ObjectDetection_Onnx/ObjectDetectionConsoleApp/OnnxModelScorer.cs#L55-L58)] - Now it's time to instantiate the model for scoring. Call the [`Fit`](xref:Microsoft.ML.IEstimator%601.Fit%2A) method on the pipeline and return it for further processing. + Now it's time to instantiate the model for scoring. Call the [`Fit`](xref:Microsoft.ML.IEstimator`1.Fit%2A) method on the pipeline and return it for further processing. [!code-csharp [FitReturnModel](~/machinelearning-samples/samples/csharp/getting-started/DeepLearning_ObjectDetection_Onnx/ObjectDetectionConsoleApp/OnnxModelScorer.cs#L61-L63)] diff --git a/docs/machine-learning/tutorials/phone-calls-anomaly-detection.md b/docs/machine-learning/tutorials/phone-calls-anomaly-detection.md index 0f1efd11f60b6..205247ee3da10 100644 --- a/docs/machine-learning/tutorials/phone-calls-anomaly-detection.md +++ b/docs/machine-learning/tutorials/phone-calls-anomaly-detection.md @@ -117,7 +117,7 @@ Data in ML.NET is represented as an [IDataView interface](xref:Microsoft.ML.IDat [!code-csharp[LoadData](./snippets/phone-calls-anomaly-detection/csharp/Program.cs#LoadData "loading dataset")] - The [LoadFromTextFile()](xref:Microsoft.ML.TextLoaderSaverCatalog.LoadFromTextFile%60%601%28Microsoft.ML.DataOperationsCatalog,System.String,System.Char,System.Boolean,System.Boolean,System.Boolean,System.Boolean%29) defines the data schema and reads in the file. It takes in the data path variables and returns an `IDataView`. + The [LoadFromTextFile()](xref:Microsoft.ML.TextLoaderSaverCatalog.LoadFromTextFile``1%28Microsoft.ML.DataOperationsCatalog,System.String,System.Char,System.Boolean,System.Boolean,System.Boolean,System.Boolean%29) defines the data schema and reads in the file. It takes in the data path variables and returns an `IDataView`. ## Time series anomaly detection @@ -142,7 +142,7 @@ In the first step, you invoke the `DetectSeasonality` function to determine the } ``` -2. Use the function to detect period. Add it to the `DetectPeriod` method with the following code: +2. Use the function to detect period. Add it to the `DetectPeriod` method with the following code: [!code-csharp[DetectSeasonality](./snippets/phone-calls-anomaly-detection/csharp/Program.cs#DetectSeasonality)] @@ -168,7 +168,7 @@ Period of the series is: 7. ## Detect Anomaly -In this step, you use the method to find anomalies. +In this step, you use the method to find anomalies. ### Create the DetectAnomaly method diff --git a/docs/machine-learning/tutorials/predict-prices.md b/docs/machine-learning/tutorials/predict-prices.md index 3c65293481cf8..0557a59b48625 100644 --- a/docs/machine-learning/tutorials/predict-prices.md +++ b/docs/machine-learning/tutorials/predict-prices.md @@ -244,7 +244,7 @@ Use the `PredictionEngine` to predict the fare by adding the following code to ` [!code-csharp[MakePredictionEngine](./snippets/predict-prices/csharp/Program.cs#22 "Create the PredictionFunction")] -The [PredictionEngine](xref:Microsoft.ML.PredictionEngine%602) is a convenience API, which allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool%601) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). +The [PredictionEngine](xref:Microsoft.ML.PredictionEngine`2) is a convenience API, which allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool`1) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). > [!NOTE] > `PredictionEnginePool` service extension is currently in preview. @@ -257,7 +257,7 @@ Next, predict the fare based on a single instance of the taxi trip data and pass [!code-csharp[Predict](./snippets/predict-prices/csharp/Program.cs#24 "Create a prediction of taxi fare")] -The [Predict()](xref:Microsoft.ML.PredictionEngine%602.Predict%2A) function makes a prediction on a single instance of data. +The [Predict()](xref:Microsoft.ML.PredictionEngine`2.Predict%2A) function makes a prediction on a single instance of data. To display the predicted fare of the specified trip, add the following code into the `TestSinglePrediction` method: diff --git a/docs/machine-learning/tutorials/sales-anomaly-detection.md b/docs/machine-learning/tutorials/sales-anomaly-detection.md index f695b5cccc193..1202e2449c89d 100644 --- a/docs/machine-learning/tutorials/sales-anomaly-detection.md +++ b/docs/machine-learning/tutorials/sales-anomaly-detection.md @@ -120,7 +120,7 @@ Data in ML.NET is represented as an [IDataView interface](xref:Microsoft.ML.IDat [!code-csharp[LoadData](./snippets/sales-anomaly-detection/csharp/Program.cs#LoadData "loading dataset")] - The [LoadFromTextFile()](xref:Microsoft.ML.TextLoaderSaverCatalog.LoadFromTextFile%60%601%28Microsoft.ML.DataOperationsCatalog,System.String,System.Char,System.Boolean,System.Boolean,System.Boolean,System.Boolean%29) defines the data schema and reads in the file. It takes in the data path variables and returns an `IDataView`. + The [LoadFromTextFile()](xref:Microsoft.ML.TextLoaderSaverCatalog.LoadFromTextFile``1%28Microsoft.ML.DataOperationsCatalog,System.String,System.Char,System.Boolean,System.Boolean,System.Boolean,System.Boolean%29) defines the data schema and reads in the file. It takes in the data path variables and returns an `IDataView`. ## Time series anomaly detection diff --git a/docs/machine-learning/tutorials/sentiment-analysis-model-builder.md b/docs/machine-learning/tutorials/sentiment-analysis-model-builder.md index b2edf6ca562a2..1326b69f92b5f 100644 --- a/docs/machine-learning/tutorials/sentiment-analysis-model-builder.md +++ b/docs/machine-learning/tutorials/sentiment-analysis-model-builder.md @@ -121,7 +121,7 @@ In the *Consume* step, Model Builder provides project templates that you can use ### Configure the PredictionEngine pool -To make a single prediction, you have to create a . is not thread-safe. Additionally, you have to create an instance of it everywhere it's needed within your application. As your application grows, this process can become unmanageable. For improved performance and thread safety, use a combination of dependency injection and the `PredictionEnginePool` service, which creates an of objects for use throughout your application. +To make a single prediction, you have to create a . is not thread-safe. Additionally, you have to create an instance of it everywhere it's needed within your application. As your application grows, this process can become unmanageable. For improved performance and thread safety, use a combination of dependency injection and the `PredictionEnginePool` service, which creates an of objects for use throughout your application. 1. Install the *Microsoft.Extensions.ML* NuGet package: @@ -140,7 +140,7 @@ To make a single prediction, you have to create a for your application in the *Program.cs* file: +1. Configure the for your application in the *Program.cs* file: ```csharp builder.Services.AddPredictionEnginePool() @@ -149,7 +149,7 @@ To make a single prediction, you have to create a to return a prediction needs to be added. +Predictions will be made inside the main page of the application. Therefore, a method that takes the user input and uses the to return a prediction needs to be added. 1. Open the *Index.cshtml.cs* file located in the *Pages* directory and add the following `using` directives: @@ -158,15 +158,15 @@ Predictions will be made inside the main page of the application. Therefore, a m using static SentimentRazor.SentimentAnalysis; ``` - In order to use the configured in the *Program.cs* file, you have to inject it into the constructor of the model where you want to use it. + In order to use the configured in the *Program.cs* file, you have to inject it into the constructor of the model where you want to use it. -1. Add a variable to reference the inside the `IndexModel` class inside the *Pages/Index.cshtml.cs* file. +1. Add a variable to reference the inside the `IndexModel` class inside the *Pages/Index.cshtml.cs* file. ```csharp private readonly PredictionEnginePool _predictionEnginePool; ``` -1. Modify the constructor in the `IndexModel` class and inject the service into it. +1. Modify the constructor in the `IndexModel` class and inject the service into it. ```csharp public IndexModel(ILogger logger, PredictionEnginePool predictionEnginePool) @@ -199,7 +199,7 @@ Predictions will be made inside the main page of the application. Therefore, a m var input = new ModelInput { SentimentText = text }; ``` - 1. Use the to predict sentiment. + 1. Use the to predict sentiment. ```csharp var prediction = _predictionEnginePool.Predict(input); @@ -359,7 +359,7 @@ When the application launches, enter *This model doesn't have enough data!* into ![Running window with the predicted sentiment window](./media/sentiment-analysis-model-builder/web-app.png) > [!NOTE] -> creates multiple instances of . Because of the size of the model, the first time you use it to make a prediction, it can take a couple of seconds. Subsequent predictions should be instantaneous. +> creates multiple instances of . Because of the size of the model, the first time you use it to make a prediction, it can take a couple of seconds. Subsequent predictions should be instantaneous. ## Next steps diff --git a/docs/machine-learning/tutorials/sentiment-analysis.md b/docs/machine-learning/tutorials/sentiment-analysis.md index 8c1290c17e576..0a461fc4c171b 100644 --- a/docs/machine-learning/tutorials/sentiment-analysis.md +++ b/docs/machine-learning/tutorials/sentiment-analysis.md @@ -130,7 +130,7 @@ You prepare the app, and then load data: [!code-csharp[LoadData](./snippets/sentiment-analysis/csharp/Program.cs#LoadData "loading dataset")] - The [LoadFromTextFile()](xref:Microsoft.ML.TextLoaderSaverCatalog.LoadFromTextFile%60%601%28Microsoft.ML.DataOperationsCatalog,System.String,System.Char,System.Boolean,System.Boolean,System.Boolean,System.Boolean%29) method defines the data schema and reads in the file. It takes in the data path variables and returns an `IDataView`. + The [LoadFromTextFile()](xref:Microsoft.ML.TextLoaderSaverCatalog.LoadFromTextFile``1%28Microsoft.ML.DataOperationsCatalog,System.String,System.Char,System.Boolean,System.Boolean,System.Boolean,System.Boolean%29) method defines the data schema and reads in the file. It takes in the data path variables and returns an `IDataView`. ### Split the dataset for model training and testing @@ -281,7 +281,7 @@ Use the following code to display the metrics: [!code-csharp[CreatePredictionEngine](./snippets/sentiment-analysis/csharp/Program.cs#CreatePredictionEngine1 "Create the PredictionEngine")] - The [PredictionEngine](xref:Microsoft.ML.PredictionEngine%602) is a convenience API, which allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool%601) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). + The [PredictionEngine](xref:Microsoft.ML.PredictionEngine`2) is a convenience API, which allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool`1) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). > [!NOTE] > `PredictionEnginePool` service extension is currently in preview. @@ -290,11 +290,11 @@ Use the following code to display the metrics: [!code-csharp[PredictionData](./snippets/sentiment-analysis/csharp/Program.cs#CreateTestIssue1 "Create test data for single prediction")] -5. Pass the test comment data to the [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) by adding the following as the next lines of code in the `UseModelWithSingleItem()` method: +5. Pass the test comment data to the [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) by adding the following as the next lines of code in the `UseModelWithSingleItem()` method: [!code-csharp[Predict](./snippets/sentiment-analysis/csharp/Program.cs#Predict "Create a prediction of sentiment")] - The [Predict()](xref:Microsoft.ML.PredictionEngine%602.Predict%2A) function makes a prediction on a single row of data. + The [Predict()](xref:Microsoft.ML.PredictionEngine`2.Predict%2A) function makes a prediction on a single row of data. 6. Display `SentimentText` and corresponding sentiment prediction using the following code: diff --git a/docs/machine-learning/tutorials/text-classification-tf.md b/docs/machine-learning/tutorials/text-classification-tf.md index b0ce518e34caa..487a24b16a707 100644 --- a/docs/machine-learning/tutorials/text-classification-tf.md +++ b/docs/machine-learning/tutorials/text-classification-tf.md @@ -211,7 +211,7 @@ The [MLContext class](xref:Microsoft.ML.MLContext) is a starting point for all M [!code-csharp[CreatePredictionEngine](./snippets/text-classification-tf/csharp/Program.cs#CreatePredictionEngine)] - The [PredictionEngine](xref:Microsoft.ML.PredictionEngine%602) is a convenience API, which allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool%601) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine%602) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). + The [PredictionEngine](xref:Microsoft.ML.PredictionEngine`2) is a convenience API, which allows you to perform a prediction on a single instance of data. [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) is not thread-safe. It's acceptable to use in single-threaded or prototype environments. For improved performance and thread safety in production environments, use the `PredictionEnginePool` service, which creates an [`ObjectPool`](xref:Microsoft.Extensions.ObjectPool.ObjectPool`1) of [`PredictionEngine`](xref:Microsoft.ML.PredictionEngine`2) objects for use throughout your application. See this guide on how to [use `PredictionEnginePool` in an ASP.NET Core Web API](../how-to-guides/serve-model-web-api-ml-net.md#register-predictionenginepool-for-use-in-the-application). > [!NOTE] > `PredictionEnginePool` service extension is currently in preview. @@ -224,7 +224,7 @@ The [MLContext class](xref:Microsoft.ML.MLContext) is a starting point for all M [!code-csharp[Predict](./snippets/text-classification-tf/csharp/Program.cs#Predict)] -1. The [Predict()](xref:Microsoft.ML.PredictionEngine%602.Predict%2A) function makes a prediction on a single row of data: +1. The [Predict()](xref:Microsoft.ML.PredictionEngine`2.Predict%2A) function makes a prediction on a single row of data: |Property| Value|Type| |-------------|-----------------------|------| diff --git a/docs/machine-learning/tutorials/time-series-demand-forecasting.md b/docs/machine-learning/tutorials/time-series-demand-forecasting.md index 06f3f6cf569c4..6bd3ca187794a 100644 --- a/docs/machine-learning/tutorials/time-series-demand-forecasting.md +++ b/docs/machine-learning/tutorials/time-series-demand-forecasting.md @@ -216,11 +216,11 @@ Evaluate how well the model performs by forecasting next year's data and compari If you're satisfied with your model, save it for later use in other applications. -1. Below the `Evaluate()` method create a [`TimeSeriesPredictionEngine`](xref:Microsoft.ML.Transforms.TimeSeries.TimeSeriesPredictionEngine%602). [`TimeSeriesPredictionEngine`](xref:Microsoft.ML.Transforms.TimeSeries.TimeSeriesPredictionEngine%602) is a convenience method to make single predictions. +1. Below the `Evaluate()` method create a [`TimeSeriesPredictionEngine`](xref:Microsoft.ML.Transforms.TimeSeries.TimeSeriesPredictionEngine`2). [`TimeSeriesPredictionEngine`](xref:Microsoft.ML.Transforms.TimeSeries.TimeSeriesPredictionEngine`2) is a convenience method to make single predictions. [!code-csharp [CreateTimeSeriesEngine](~/machinelearning-samples/samples/csharp/getting-started/Forecasting_BikeSharingDemand/BikeDemandForecasting/Program.cs#L41)] -1. Save the model to a file called `MLModel.zip` as specified by the previously defined `modelPath` variable. Use the [`Checkpoint`](xref:Microsoft.ML.Transforms.TimeSeries.TimeSeriesPredictionEngine%602.CheckPoint%2A) method to save the model. +1. Save the model to a file called `MLModel.zip` as specified by the previously defined `modelPath` variable. Use the [`Checkpoint`](xref:Microsoft.ML.Transforms.TimeSeries.TimeSeriesPredictionEngine`2.CheckPoint%2A) method to save the model. [!code-csharp [SaveModel](~/machinelearning-samples/samples/csharp/getting-started/Forecasting_BikeSharingDemand/BikeDemandForecasting/Program.cs#L42)] @@ -235,7 +235,7 @@ If you're satisfied with your model, save it for later use in other applications } ``` -1. Inside the `Forecast` method, use the [`Predict`](xref:Microsoft.ML.Transforms.TimeSeries.TimeSeriesPredictionEngine%602.Predict%2A) method to forecast rentals for the next seven days. +1. Inside the `Forecast` method, use the [`Predict`](xref:Microsoft.ML.Transforms.TimeSeries.TimeSeriesPredictionEngine`2.Predict%2A) method to forecast rentals for the next seven days. [!code-csharp [SingleForecast](~/machinelearning-samples/samples/csharp/getting-started/Forecasting_BikeSharingDemand/BikeDemandForecasting/Program.cs#L78)] diff --git a/docs/orleans/deployment/consul-deployment.md b/docs/orleans/deployment/consul-deployment.md index 1df3c625badcc..3191923063b3e 100644 --- a/docs/orleans/deployment/consul-deployment.md +++ b/docs/orleans/deployment/consul-deployment.md @@ -59,10 +59,10 @@ The preceding code: - Creates an with defaults from . - Chains a call to to configure the Orleans silo. -- Given the , calls . +- Given the , calls . - Configures the cluster membership provider to use Consul, given the Consul `address`. -To configure the client, reference the same NuGet package and call the extension method. +To configure the client, reference the same NuGet package and call the extension method. ## Client SDK diff --git a/docs/orleans/deployment/handling-failures.md b/docs/orleans/deployment/handling-failures.md index f08ad4460fd11..add7a61cca148 100644 --- a/docs/orleans/deployment/handling-failures.md +++ b/docs/orleans/deployment/handling-failures.md @@ -33,7 +33,7 @@ Part of the recovery job is automatic in Orleans. If a grain is no longer access After observing a grain operation failure, take one or more of the following actions: - **Retry the action**: Often suitable, especially if the action doesn't involve state changes that might be left half-done. This is the most common approach. -- **Fix/reset state**: Try to correct the partially changed state. Do this by calling a method that resets the state to the last known correct state or by simply reading the correct state from storage using . +- **Fix/reset state**: Try to correct the partially changed state. Do this by calling a method that resets the state to the last known correct state or by simply reading the correct state from storage using . - **Reset related states**: Reset the state of all related activations as well to ensure a consistent state across all involved grains. - **Use transactions or process managers**: Perform multi-grain state manipulations using a Process Manager pattern or database transactions. This ensures the operation either completes entirely or leaves the state unchanged, avoiding partial updates. diff --git a/docs/orleans/deployment/kubernetes.md b/docs/orleans/deployment/kubernetes.md index 0defea5dd842a..bd9fcf1eb325c 100644 --- a/docs/orleans/deployment/kubernetes.md +++ b/docs/orleans/deployment/kubernetes.md @@ -12,7 +12,7 @@ ms.custom: Kubernetes is a popular choice for hosting Orleans applications. Orleans runs in Kubernetes without specific configuration; however, it can also take advantage of extra knowledge the hosting platform provides. -The [`Microsoft.Orleans.Hosting.Kubernetes`](https://www.nuget.org/packages/Microsoft.Orleans.Hosting.Kubernetes) package adds integration for hosting an Orleans application in a Kubernetes cluster. The package provides an extension method, , performing the following actions: +The [`Microsoft.Orleans.Hosting.Kubernetes`](https://www.nuget.org/packages/Microsoft.Orleans.Hosting.Kubernetes) package adds integration for hosting an Orleans application in a Kubernetes cluster. The package provides an extension method, , performing the following actions: - Sets to the pod name. - Sets to the pod IP. diff --git a/docs/orleans/deployment/service-fabric.md b/docs/orleans/deployment/service-fabric.md index 1d38158b80aff..c7e770bfaf5a9 100644 --- a/docs/orleans/deployment/service-fabric.md +++ b/docs/orleans/deployment/service-fabric.md @@ -16,17 +16,17 @@ Whether creating a new Service Fabric Application or adding Orleans to an existi The Silo lifecycle follows the typical communication listener lifecycle: -- Initialized with . -- Gracefully terminated with . -- Or abruptly terminated with . +- Initialized with . +- Gracefully terminated with . +- Or abruptly terminated with . Since Orleans Silos can live within the confines of the , the implementation of `ICommunicationListener` is a wrapper around the `IHost`. The `IHost` initializes in the `OpenAsync` method and gracefully terminates in the `CloseAsync` method: | `ICommunicationListener` | `IHost` interactions | | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| | The `IHost` instance is created and a call to is made. | -| | A call to on the host instance is awaited. | -| | A call to is forcefully evaluated with `GetAwaiter().GetResult()`. | +| | The `IHost` instance is created and a call to is made. | +| | A call to on the host instance is awaited. | +| | A call to is forcefully evaluated with `GetAwaiter().GetResult()`. | ## Cluster support @@ -58,5 +58,5 @@ Pulling these two classes together, the following example shows the complete _Pr In the preceding code: -- The method registers the `OrleansHostedStatelessService` class with the Service Fabric runtime. +- The method registers the `OrleansHostedStatelessService` class with the Service Fabric runtime. - The `CreateHostAsync` delegate creates the `IHost` instance. diff --git a/docs/orleans/grains/cancellation-tokens.md b/docs/orleans/grains/cancellation-tokens.md index 0840c753d3e96..f9e7bc60f7d8f 100644 --- a/docs/orleans/grains/cancellation-tokens.md +++ b/docs/orleans/grains/cancellation-tokens.md @@ -17,8 +17,8 @@ Orleans supports cooperative cancellation in grain methods through the standard Orleans supports passing instances to grain interface methods. This works for: -- Regular grain methods that return , , etcetera -- Streaming methods that return +- Regular grain methods that return , , etcetera +- Streaming methods that return - Both client-to-grain and grain-to-grain calls Cancellation is cooperative, meaning your grain implementation must observe the token and respond appropriately for it to be effective. If a cancellation token is not observed, the runtime will not automatically stop a method from executing. This behavior is consistent with the majority of libraries that support . In other words, .NET uses cooperative cancellation. The major benefit of this approach is that cancellation can only occur at clearly identifiable points, not at any given instruction. This lets you run cleanup logic when cancellation is signalled. @@ -200,7 +200,7 @@ catch (OperationCanceledException) #### Approach 2: WithCancellation extension method -For scenarios where you have an existing instance or need to override the cancellation token, use the extension method: +For scenarios where you have an existing instance or need to override the cancellation token, use the extension method: ```csharp var grain = grainFactory.GetGrain(Guid.NewGuid()); @@ -412,7 +412,7 @@ When handling `OperationCanceledException`, always check if the cancellation is ### IAsyncEnumerable<T> behavior -For streaming scenarios with : +For streaming scenarios with : - **Pre-enumeration cancellation**: If the token is canceled before enumeration starts, no items are yielded and an `OperationCanceledException` is thrown immediately. - **Mid-enumeration cancellation**: If canceled during enumeration, the stream stops at the next cancellation check point (typically the next `yield` or `await` operation). @@ -457,7 +457,7 @@ The following information is provided for context on older systems or for specif is a wrapper around the standard . It enables cooperative cancellation between threads, thread pool work items, or objects, and can be passed as a grain method argument. -A provides a through its `Token` property and sends a cancellation message when its method is called. +A provides a through its `Token` property and sends a cancellation message when its method is called. ### Using GrainCancellationToken @@ -469,7 +469,7 @@ To use the legacy : var tcs = new GrainCancellationTokenSource(); ``` -1. Pass the token returned by the property to each grain method that should listen for cancellation. +1. Pass the token returned by the property to each grain method that should listen for cancellation. ```csharp var waitTask = grain.LongIoWork(tcs.Token, TimeSpan.FromSeconds(10)); @@ -515,7 +515,7 @@ To use the legacy : - - -- +- - - - diff --git a/docs/orleans/grains/code-generation.md b/docs/orleans/grains/code-generation.md index a082678569079..8a536081a0ba8 100644 --- a/docs/orleans/grains/code-generation.md +++ b/docs/orleans/grains/code-generation.md @@ -74,7 +74,7 @@ In Orleans 7+, nothing happens during initialization. Code generation occurs onl :::zone target="docs" pivot="orleans-3-x" -Code generation can be performed during initialization on the client and silo by installing the `Microsoft.Orleans.OrleansCodeGenerator` package and using the extension method: +Code generation can be performed during initialization on the client and silo by installing the `Microsoft.Orleans.OrleansCodeGenerator` package and using the extension method: :::code language="csharp" source="snippets-v3/code-generation/CodeGeneration.cs" id="with_code_generation"::: diff --git a/docs/orleans/grains/event-sourcing/event-sourcing-configuration.md b/docs/orleans/grains/event-sourcing/event-sourcing-configuration.md index 6c9a26d9e1d1e..d9729bcea6289 100644 --- a/docs/orleans/grains/event-sourcing/event-sourcing-configuration.md +++ b/docs/orleans/grains/event-sourcing/event-sourcing-configuration.md @@ -17,7 +17,7 @@ As before, interfaces depend only on the `Microsoft.Orleans.Core` package becaus ### Grain implementations -Journaled grains need to derive from or , which is defined in the `Microsoft.Orleans.EventSourcing` package. +Journaled grains need to derive from or , which is defined in the `Microsoft.Orleans.EventSourcing` package. ### Log-consistency providers diff --git a/docs/orleans/grains/event-sourcing/immediate-vs-delayed-confirmation.md b/docs/orleans/grains/event-sourcing/immediate-vs-delayed-confirmation.md index e2c72fbc9539a..1d9abb60d63ac 100644 --- a/docs/orleans/grains/event-sourcing/immediate-vs-delayed-confirmation.md +++ b/docs/orleans/grains/event-sourcing/immediate-vs-delayed-confirmation.md @@ -13,8 +13,8 @@ In this article, you learn the differences between immediate and delayed confirm For many applications, you want to ensure events are confirmed immediately. This prevents the persisted version from lagging behind the current version in memory and avoids the risk of losing the latest state if the grain fails. You can guarantee this by following these rules: -1. Confirm all calls using before the grain method returns. -1. Ensure tasks returned by complete before the grain method returns. +1. Confirm all calls using before the grain method returns. +1. Ensure tasks returned by complete before the grain method returns. 1. Avoid or attributes, so only one grain call processes at a time. If you follow these rules, it means that after an event is raised, no other grain code can execute until the event has been written to storage. Therefore, it's impossible to observe inconsistencies between the in-memory version and the stored version. While this is often exactly what you want, it also has some potential disadvantages. @@ -32,7 +32,7 @@ To improve availability and throughput in the situations mentioned above, grains - Allow grain methods to raise events without waiting for confirmation. - Allow reentrancy, so the grain can keep processing new calls even if previous calls get stuck waiting for confirmation. -This means grain code can execute while some events are still being confirmed. The API has specific provisions giving you precise control over how to handle unconfirmed events currently _in flight_. +This means grain code can execute while some events are still being confirmed. The API has specific provisions giving you precise control over how to handle unconfirmed events currently _in flight_. You can examine the following property to find out which events are currently unconfirmed: @@ -40,13 +40,13 @@ You can examine the following property to find out which events are currently un IEnumerable UnconfirmedEvents { get; } ``` -Also, since the state returned by the property doesn't include the effect of unconfirmed events, there's an alternative property: +Also, since the state returned by the property doesn't include the effect of unconfirmed events, there's an alternative property: ```csharp StateType TentativeState { get; } ``` -This property returns a "tentative" state, obtained from by applying all unconfirmed events. The tentative state is essentially a "best guess" at what will likely become the next confirmed state after all unconfirmed events are confirmed. However, there's no guarantee it actually will become the confirmed state. This is because the grain might fail, or the events might race against other events and lose, causing them to be canceled (if conditional) or appear later in the sequence than anticipated (if unconditional). +This property returns a "tentative" state, obtained from by applying all unconfirmed events. The tentative state is essentially a "best guess" at what will likely become the next confirmed state after all unconfirmed events are confirmed. However, there's no guarantee it actually will become the confirmed state. This is because the grain might fail, or the events might race against other events and lose, causing them to be canceled (if conditional) or appear later in the sequence than anticipated (if unconditional). ## Concurrency guarantees @@ -54,7 +54,7 @@ Note that Orleans turn-based scheduling (cooperative concurrency) guarantees alw In particular, note that: -- The properties , , , and can change during the execution of a method. +- The properties , , , and can change during the execution of a method. - However, such changes can only happen while stuck at an `await`. These guarantees assume your code stays within the [recommended practices](../external-tasks-and-grains.md) concerning tasks and async/await (in particular, doesn't use thread pool tasks, or only uses them for code that doesn't call grain functionality and that are properly awaited). diff --git a/docs/orleans/grains/event-sourcing/index.md b/docs/orleans/grains/event-sourcing/index.md index 0b24569fcd6b8..ca6ce28e87d6f 100644 --- a/docs/orleans/grains/event-sourcing/index.md +++ b/docs/orleans/grains/event-sourcing/index.md @@ -11,7 +11,7 @@ Event sourcing provides a flexible way to manage and persist grain state. An eve The documentation is structured as follows: -- [JournaledGrain basics](journaledgrain-basics.md) explains how to define event-sourced grains by deriving from , how to access the current state, and how to raise events that update the state. +- [JournaledGrain basics](journaledgrain-basics.md) explains how to define event-sourced grains by deriving from , how to access the current state, and how to raise events that update the state. - [Replicated instances](replicated-instances.md) explains how the event-sourcing mechanism handles replicated grain instances and ensures consistency. It discusses the possibility of racing events and conflicts, and how to address them. diff --git a/docs/orleans/grains/event-sourcing/journaledgrain-basics.md b/docs/orleans/grains/event-sourcing/journaledgrain-basics.md index d27a96ce71a82..6a1322206eaea 100644 --- a/docs/orleans/grains/event-sourcing/journaledgrain-basics.md +++ b/docs/orleans/grains/event-sourcing/journaledgrain-basics.md @@ -7,14 +7,14 @@ ms.topic: concept-article # JournaledGrain basics -Journaled grains derive from , with the following type parameters: +Journaled grains derive from , with the following type parameters: - `TGrainState` represents the state of the grain. It must be a class with a public default constructor. - `TEventBase` is a common supertype for all events that can be raised for this grain and can be any class or interface. All state and event objects should be serializable because log-consistency providers might need to persist them and/or send them in notification messages. -For grains whose events are POCOs (plain old C# objects), you can use as a shorthand for . +For grains whose events are POCOs (plain old C# objects), you can use as a shorthand for . ## Reading the grain state @@ -28,11 +28,11 @@ int Version { get; } The version number always equals the total number of confirmed events, and the state is the result of applying all confirmed events to the initial state. The default constructor of the `GrainState` class determines the initial state, which has version 0 (because no events have been applied to it). > [!IMPORTANT] -> Never directly modify the object returned by . It's meant for reading only. When your application needs to modify the state, do so indirectly by raising events. +> Never directly modify the object returned by . It's meant for reading only. When your application needs to modify the state, do so indirectly by raising events. ## Raise events -Raise events by calling the function. For example, a grain representing a chat can raise a `PostedEvent` to indicate that a user submitted a post: +Raise events by calling the function. For example, a grain representing a chat can raise a `PostedEvent` to indicate that a user submitted a post: ```csharp RaiseEvent(new PostedEvent() @@ -44,7 +44,7 @@ RaiseEvent(new PostedEvent() }); ``` -Note that initiates a write to storage but doesn't wait for the write to complete. For many applications, it's important to wait for confirmation that the event has been persisted. In that case, always follow up by waiting for : +Note that initiates a write to storage but doesn't wait for the write to complete. For many applications, it's important to wait for confirmation that the event has been persisted. In that case, always follow up by waiting for : ```csharp RaiseEvent(new DepositTransaction() @@ -55,7 +55,7 @@ RaiseEvent(new DepositTransaction() await ConfirmEvents(); ``` -Note that even if you don't explicitly call , the events eventually get confirmed automatically in the background. +Note that even if you don't explicitly call , the events eventually get confirmed automatically in the background. ## State transition methods @@ -96,7 +96,7 @@ Some providers, like the log-consistency ## Raise multiple events -You can make multiple calls to before calling : +You can make multiple calls to before calling : ```csharp RaiseEvent(e1); diff --git a/docs/orleans/grains/event-sourcing/journaledgrain-diagnostics.md b/docs/orleans/grains/event-sourcing/journaledgrain-diagnostics.md index bfa4d18779860..5e262e9a9a491 100644 --- a/docs/orleans/grains/event-sourcing/journaledgrain-diagnostics.md +++ b/docs/orleans/grains/event-sourcing/journaledgrain-diagnostics.md @@ -29,7 +29,7 @@ protected override void OnConnectionIssueResolved( is an abstract class with several common fields describing the issue, including how many times it has been observed since the last successful connection. Subclasses define the actual type of connection issue. Connection issues are categorized into types, such as or , and sometimes have extra keys (like ) that further narrow the category. -If the same category of issue happens multiple times (for example, you keep getting a `NotificationFailed` targeting the same `RemoteCluster`), Orleans reports it each time via . Once this category of issue resolves (for example, you finally succeed in sending a notification to that `RemoteCluster`), Orleans calls once, with the same `issue` object last reported by `OnConnectionIssue`. Connection issues and their resolutions for independent categories are reported independently. +If the same category of issue happens multiple times (for example, you keep getting a `NotificationFailed` targeting the same `RemoteCluster`), Orleans reports it each time via . Once this category of issue resolves (for example, you finally succeed in sending a notification to that `RemoteCluster`), Orleans calls once, with the same `issue` object last reported by `OnConnectionIssue`. Connection issues and their resolutions for independent categories are reported independently. ## Simple statistics diff --git a/docs/orleans/grains/event-sourcing/log-consistency-providers.md b/docs/orleans/grains/event-sourcing/log-consistency-providers.md index ff3cfa7218eb4..69dca17ed9089 100644 --- a/docs/orleans/grains/event-sourcing/log-consistency-providers.md +++ b/docs/orleans/grains/event-sourcing/log-consistency-providers.md @@ -17,7 +17,7 @@ The data kept in storage is an object containing both the grain state (specified Since the entire grain state is read/written every time storage is accessed, this provider isn't suitable for objects with very large grain states. -This provider doesn't support . It cannot retrieve events from storage because the events aren't persisted. +This provider doesn't support . It cannot retrieve events from storage because the events aren't persisted. ### Log storage @@ -25,7 +25,7 @@ The ` object and some metadata (a special tag used to avoid event duplication when storage accesses fail). -This provider supports . All events are always available and kept in memory. +This provider supports . All events are always available and kept in memory. Since the entire event sequence is read/written every time storage is accessed, this provider is *not suitable for production use* unless the event sequences are guaranteed to remain fairly short. The main purpose of this provider is to illustrate the semantics of event sourcing and for use in samples/testing environments. @@ -33,7 +33,7 @@ Since the entire event sequence is read/written every time storage is accessed, This allows you to plug in your storage interface, which the consistency protocol then calls at appropriate times. This provider doesn't make specific assumptions about whether the stored data consists of state snapshots or events – you assume control over that choice (and can store either or both). -To use this provider, a grain must derive from , as before, but must also implement the following interface: +To use this provider, a grain must derive from , as before, but must also implement the following interface: ```csharp public interface ICustomStorageInterface @@ -48,9 +48,9 @@ public interface ICustomStorageInterface The consistency provider expects these methods to behave in a certain way. Be aware that: -- The first method, , is expected to return both the version and the state read. If nothing is stored yet, it should return zero for the version and a state corresponding to the default constructor for `StateType`. +- The first method, , is expected to return both the version and the state read. If nothing is stored yet, it should return zero for the version and a state corresponding to the default constructor for `StateType`. -- must return `false` if the expected version doesn't match the actual version (this is analogous to an e-tag check). +- must return `false` if the expected version doesn't match the actual version (this is analogous to an e-tag check). - If `ApplyUpdatesToStorage` fails with an exception, the consistency provider retries. This means some events could be duplicated if such an exception is thrown but the event was persisted. You are responsible for ensuring this is safe: for example,, either avoid this case by not throwing an exception, ensure duplicated events are harmless for the application logic, or add an extra mechanism to filter duplicates. diff --git a/docs/orleans/grains/event-sourcing/notifications.md b/docs/orleans/grains/event-sourcing/notifications.md index ce1f19a9a7a8e..1e4a76d4868fa 100644 --- a/docs/orleans/grains/event-sourcing/notifications.md +++ b/docs/orleans/grains/event-sourcing/notifications.md @@ -39,4 +39,4 @@ protected override void OnTentativeStateChanged() } ``` -`OnTentativeStateChanged` is called whenever the tentative state changes, i.e., if the combined sequence (`ConfirmedEvents` + `UnconfirmedEvents`) changes. In particular, a callback to `OnTentativeStateChanged()` always happens during . +`OnTentativeStateChanged` is called whenever the tentative state changes, i.e., if the combined sequence (`ConfirmedEvents` + `UnconfirmedEvents`) changes. In particular, a callback to `OnTentativeStateChanged()` always happens during . diff --git a/docs/orleans/grains/event-sourcing/replicated-instances.md b/docs/orleans/grains/event-sourcing/replicated-instances.md index f9ed731fd0f44..1324d34f82a81 100644 --- a/docs/orleans/grains/event-sourcing/replicated-instances.md +++ b/docs/orleans/grains/event-sourcing/replicated-instances.md @@ -19,20 +19,20 @@ For a general discussion of the consistency model, see our [TechReport](https:// ## Conditional events -Racing events can be problematic if they conflict, i.e., both shouldn't commit for some reason. For example, when withdrawing money from a bank account, two instances might independently determine sufficient funds exist for a withdrawal and issue a withdrawal event. However, the combination of both events could overdraw the account. To avoid this, the `JournaledGrain` API supports the method. +Racing events can be problematic if they conflict, i.e., both shouldn't commit for some reason. For example, when withdrawing money from a bank account, two instances might independently determine sufficient funds exist for a withdrawal and issue a withdrawal event. However, the combination of both events could overdraw the account. To avoid this, the `JournaledGrain` API supports the method. ```csharp bool success = await RaiseConditionalEvent( new WithdrawalEvent() { /* ... */ }); ``` -Conditional events double-check if the local version matches the version in storage. If not, it means the event sequence has grown in the meantime, indicating this event lost a race against another event. In that case, the conditional event is *not* appended to the log, and returns `false`. +Conditional events double-check if the local version matches the version in storage. If not, it means the event sequence has grown in the meantime, indicating this event lost a race against another event. In that case, the conditional event is *not* appended to the log, and returns `false`. This is analogous to using e-tags with conditional storage updates and provides a simple mechanism to avoid committing conflicting events. It's possible and sensible to use both conditional and unconditional events for the same grain, such as `DepositEvent` and `WithdrawalEvent`. Deposits don't need to be conditional: even if a `DepositEvent` loses a race, it doesn't have to be canceled but can still be appended to the global event sequence. -Awaiting the task returned by is sufficient to confirm the event; you don't need to call as well. +Awaiting the task returned by is sufficient to confirm the event; you don't need to call as well. ## Explicit synchronization diff --git a/docs/orleans/grains/external-tasks-and-grains.md b/docs/orleans/grains/external-tasks-and-grains.md index dfac2683db520..d76feded447e8 100644 --- a/docs/orleans/grains/external-tasks-and-grains.md +++ b/docs/orleans/grains/external-tasks-and-grains.md @@ -13,16 +13,16 @@ In some cases, grain code might need to "break out" of the Orleans task scheduli ## Task-based APIs -1. `await`, (see below), , , , and all respect the current task scheduler. This means using them in the default way, without passing a different , causes them to execute in the grain context. +1. `await`, (see below), , , , and all respect the current task scheduler. This means using them in the default way, without passing a different , causes them to execute in the grain context. -1. Both and the `endMethod` delegate of do *not* respect the current task scheduler. They both use the `TaskScheduler.Default` scheduler, the .NET thread pool task scheduler. Therefore, code inside `Task.Run` and the `endMethod` in `Task.Factory.FromAsync` *always* runs on the .NET thread pool, outside the single-threaded execution model for Orleans grains. However, any code after `await Task.Run` or `await Task.Factory.FromAsync` runs back under the scheduler active at the point the task was created, which is the grain's scheduler. +1. Both and the `endMethod` delegate of do *not* respect the current task scheduler. They both use the `TaskScheduler.Default` scheduler, the .NET thread pool task scheduler. Therefore, code inside `Task.Run` and the `endMethod` in `Task.Factory.FromAsync` *always* runs on the .NET thread pool, outside the single-threaded execution model for Orleans grains. However, any code after `await Task.Run` or `await Task.Factory.FromAsync` runs back under the scheduler active at the point the task was created, which is the grain's scheduler. -1. with `false` is an explicit API to escape the current task scheduler. It causes the code after an awaited to execute on the scheduler (the .NET thread pool), thus breaking the single-threaded execution of the grain. +1. with `false` is an explicit API to escape the current task scheduler. It causes the code after an awaited to execute on the scheduler (the .NET thread pool), thus breaking the single-threaded execution of the grain. > [!CAUTION] > Generally, **never use `ConfigureAwait(false)` directly in grain code.** -1. Methods with the signature `async void` should not be used with grains. They are intended for graphical user interface event handlers. An `async void` method can immediately crash the current process if it allows an exception to escape, with no way to handle the exception. This also applies to `List.ForEach(async element => ...)` and any other method accepting an , since the asynchronous delegate coerces into an `async void` delegate. +1. Methods with the signature `async void` should not be used with grains. They are intended for graphical user interface event handlers. An `async void` method can immediately crash the current process if it allows an exception to escape, with no way to handle the exception. This also applies to `List.ForEach(async element => ...)` and any other method accepting an , since the asynchronous delegate coerces into an `async void` delegate. ### `Task.Factory.StartNew` and `async` delegates @@ -136,7 +136,7 @@ If some *sync-over-async* work is unavoidable, moving that work to a separate sc | What are you trying to do? | How to do it | |--|--| | Run background work on .NET thread-pool threads. No grain code or grain calls are allowed. | `Task.Run` | -| Run asynchronous worker task from grain code with Orleans turn-based concurrency guarantees ([see above](#taskfactorystartnew-and-async-delegates)). | `Task.Factory.StartNew(WorkerAsync).Unwrap()` () | +| Run asynchronous worker task from grain code with Orleans turn-based concurrency guarantees ([see above](#taskfactorystartnew-and-async-delegates)). | `Task.Factory.StartNew(WorkerAsync).Unwrap()` () | | Run synchronous worker task from grain code with Orleans turn-based concurrency guarantees. | `Task.Factory.StartNew(WorkerSync)` | | Timeouts for executing work items | `Task.Delay` + `Task.WhenAny` | | Call an asynchronous library method | `await` the library call | diff --git a/docs/orleans/grains/grain-extensions.md b/docs/orleans/grains/grain-extensions.md index 9cdd4a95382b0..e0c13e9a747c1 100644 --- a/docs/orleans/grains/grain-extensions.md +++ b/docs/orleans/grains/grain-extensions.md @@ -53,7 +53,7 @@ public sealed class GrainDeactivateExtension : IGrainDeactivateExtension ### Deactivate extension registration and usage -Now that the interface and implementation are defined, register the extension when configuring the silo using the method. +Now that the interface and implementation are defined, register the extension when configuring the silo using the method. ```csharp siloBuilder.AddGrainExtension(); @@ -115,7 +115,7 @@ public sealed class GrainStateAccessor : IGrainStateAccessor } ``` -In the preceding implementation, the `GrainStateAccessor` class takes `getter` and `setter` arguments in its constructor. These delegates read and modify the target grain's state. The `GetState()` method returns a wrapping the current value of the `T` state, while the `SetState(T state)` method sets the new value of the `T` state. +In the preceding implementation, the `GrainStateAccessor` class takes `getter` and `setter` arguments in its constructor. These delegates read and modify the target grain's state. The `GetState()` method returns a wrapping the current value of the `T` state, while the `SetState(T state)` method sets the new value of the `T` state. ### State manipulation extension registration and usage @@ -136,7 +136,7 @@ public override Task OnActivateAsync() } ``` -In the preceding example, create a new instance of `GrainStateAccessor` taking a `getter` and `setter` for an integer state value. The `getter` reads the `Value` property of the target grain, while the `setter` sets the new value of the `Value` property. Then, set this instance as a component of the target grain's context using the method. +In the preceding example, create a new instance of `GrainStateAccessor` taking a `getter` and `setter` for an integer state value. The `getter` reads the `Value` property of the target grain, while the `setter` sets the new value of the `Value` property. Then, set this instance as a component of the target grain's context using the method. Once the extension is registered, use it to get and set the target grain's state by accessing it through a reference to the extension. diff --git a/docs/orleans/grains/grain-identity.md b/docs/orleans/grains/grain-identity.md index 1ab54007bcfc4..2d4dd072e6336 100644 --- a/docs/orleans/grains/grain-identity.md +++ b/docs/orleans/grains/grain-identity.md @@ -135,7 +135,7 @@ public interface IExampleGrain : Orleans.IGrainWithIntegerCompoundKey } ``` -In client code, this adds a second argument to the method on the grain factory: +In client code, this adds a second argument to the method on the grain factory: ```csharp var grain = grainFactory.GetGrain(0, "a string!", null); diff --git a/docs/orleans/grains/grain-lifecycle.md b/docs/orleans/grains/grain-lifecycle.md index d28857d4176c5..b46004984669c 100644 --- a/docs/orleans/grains/grain-lifecycle.md +++ b/docs/orleans/grains/grain-lifecycle.md @@ -29,8 +29,8 @@ public static class GrainLifecycleStage ``` - `First`: First stage in a grain's lifecycle. -- `SetupState`: Set up grain state before activation. For stateful grains, this is the stage where Orleans loads from storage if is `true`. -- `Activate`: Stage where Orleans calls and . +- `SetupState`: Set up grain state before activation. For stateful grains, this is the stage where Orleans loads from storage if is `true`. +- `Activate`: Stage where Orleans calls and . - `Last`: Last stage in a grain's lifecycle. While Orleans uses the grain lifecycle during grain activation, grains aren't always deactivated during some error cases (such as silo crashes). Therefore, applications shouldn't rely on the grain lifecycle always executing during grain deactivations. @@ -59,13 +59,13 @@ builder.Configure(options => { // Enable memory-based activation shedding options.EnableActivationSheddingOnMemoryPressure = true; - + // Memory usage percentage (0-100) at which grain collection triggers options.MemoryUsageLimitPercentage = 80; // default: 80 - + // Target memory usage percentage to reach after collection options.MemoryUsageTargetPercentage = 75; // default: 75 - + // How often to poll memory usage options.MemoryUsagePollingPeriod = TimeSpan.FromSeconds(5); // default: 5s }); @@ -124,7 +124,7 @@ public override void Participate(IGrainLifecycle lifecycle) } ``` -In the preceding example, overrides the method to tell the lifecycle to call its `OnSetupState` method during the stage of the lifecycle. +In the preceding example, overrides the method to tell the lifecycle to call its `OnSetupState` method during the stage of the lifecycle. :::zone target="docs" pivot="orleans-8-0,orleans-7-0" @@ -288,7 +288,7 @@ public class MyMigratableGrain : Grain, IMyGrain, IGrainMigrationParticipant #### Option 2: Use Grain<TState> or IPersistentState<T> -Grains using or automatically support migration. Their state is serialized and restored without additional code: +Grains using or automatically support migration. Their state is serialized and restored without additional code: ```csharp // Automatic migration support via Grain diff --git a/docs/orleans/grains/grain-persistence/azure-storage.md b/docs/orleans/grains/grain-persistence/azure-storage.md index ea2f597152c11..3c019b1449d56 100644 --- a/docs/orleans/grains/grain-persistence/azure-storage.md +++ b/docs/orleans/grains/grain-persistence/azure-storage.md @@ -16,7 +16,7 @@ The Azure Storage grain persistence provider supports both [Azure Blob Storage]( Install the [Microsoft.Orleans.Persistence.AzureStorage](https://www.nuget.org/packages/Microsoft.Orleans.Persistence.AzureStorage) package from NuGet. The Azure Table Storage provider stores state in a table row, splitting the state across multiple columns if it exceeds the limits of a single column. Each row can hold a maximum of 1 megabyte, as [imposed by Azure Table Storage](/azure/storage/common/storage-scalability-targets#azure-table-storage-scale-targets). -Configure the Azure Table Storage grain persistence provider using the extension method. +Configure the Azure Table Storage grain persistence provider using the extension method. ### [Microsoft Entra ID (recommended)](#tab/entra-id) @@ -60,7 +60,7 @@ siloBuilder.AddAzureTableGrainStorage( The Azure Blob Storage provider stores state in a blob. -Configure the Azure Blob Storage grain persistence provider using the extension method. +Configure the Azure Blob Storage grain persistence provider using the extension method. ### [Microsoft Entra ID (recommended)](#tab/entra-id) @@ -183,14 +183,14 @@ For comprehensive documentation on Orleans and .NET Aspire integration, see [Orl Install the [Microsoft.Orleans.Persistence.AzureStorage](https://www.nuget.org/packages/Microsoft.Orleans.Persistence.AzureStorage) package from NuGet. The Azure Table Storage provider stores state in a table row, splitting the state across multiple columns if it exceeds the limits of a single column. Each row can hold a maximum of 1 megabyte, as [imposed by Azure Table Storage](/azure/storage/common/storage-scalability-targets#azure-table-storage-scale-targets). -Configure the Azure Table Storage grain persistence provider using the extension method. +Configure the Azure Table Storage grain persistence provider using the extension method. ```csharp siloBuilder.AddAzureTableGrainStorage( name: "profileStore", configureOptions: options => { - options.ConnectionString = + options.ConnectionString = "DefaultEndpointsProtocol=https;AccountName=data1;AccountKey=SOMETHING1"; }); ``` @@ -199,14 +199,14 @@ siloBuilder.AddAzureTableGrainStorage( The Azure Blob Storage provider stores state in a blob. -Configure the Azure Blob Storage grain persistence provider using the extension method. +Configure the Azure Blob Storage grain persistence provider using the extension method. ```csharp siloBuilder.AddAzureBlobGrainStorage( name: "profileStore", configureOptions: options => { - options.ConnectionString = + options.ConnectionString = "DefaultEndpointsProtocol=https;AccountName=data1;AccountKey=SOMETHING1"; }); ``` diff --git a/docs/orleans/grains/grain-persistence/dynamodb-storage.md b/docs/orleans/grains/grain-persistence/dynamodb-storage.md index a981f81e56e91..bb889b2f516ae 100644 --- a/docs/orleans/grains/grain-persistence/dynamodb-storage.md +++ b/docs/orleans/grains/grain-persistence/dynamodb-storage.md @@ -17,7 +17,7 @@ Install the [`Microsoft.Orleans.Persistence.DynamoDB`](https://www.nuget.org/pac ## Configuration -Configure the DynamoDB grain persistence provider using the extension method. +Configure the DynamoDB grain persistence provider using the extension method. ```csharp siloBuilder.AddDynamoDBGrainStorage( diff --git a/docs/orleans/grains/grain-persistence/index.md b/docs/orleans/grains/grain-persistence/index.md index 5f193fb402c38..61dee7086e368 100644 --- a/docs/orleans/grains/grain-persistence/index.md +++ b/docs/orleans/grains/grain-persistence/index.md @@ -39,7 +39,7 @@ You can find Orleans grain storage providers on [NuGet](https://www.nuget.org/pa ## API -Grains interact with their persistent state using , where `TState` is the serializable state type: +Grains interact with their persistent state using , where `TState` is the serializable state type: :::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" @@ -65,7 +65,7 @@ public interface IPersistentState where TState : new() :::zone-end -Orleans injects instances of into the grain as constructor parameters. You can annotate these parameters with a attribute to identify the name of the state being injected and the name of the storage provider supplying it. The following example demonstrates this by injecting two named states into the `UserGrain` constructor: +Orleans injects instances of into the grain as constructor parameters. You can annotate these parameters with a attribute to identify the name of the state being injected and the name of the storage provider supplying it. The following example demonstrates this by injecting two named states into the `UserGrain` constructor: :::code language="csharp" source="./snippets/persistence/GrainExamples.cs" id="user_grain_multiple_states"::: @@ -75,19 +75,19 @@ Different grain types can use different configured storage providers, even if bo Grain state automatically reads when the grain activates, but grains are responsible for explicitly triggering the write for any changed grain state when necessary. -If a grain wishes to explicitly re-read its latest state from the backing store, it should call the method. This reloads the grain state from the persistent store via the storage provider. The previous in-memory copy of the grain state is overwritten and replaced when the from completes. +If a grain wishes to explicitly re-read its latest state from the backing store, it should call the method. This reloads the grain state from the persistent store via the storage provider. The previous in-memory copy of the grain state is overwritten and replaced when the from completes. -Access the value of the state using the property. For example, the following method accesses the profile state declared in the code above: +Access the value of the state using the property. For example, the following method accesses the profile state declared in the code above: :::code language="csharp" source="./snippets/persistence/GrainExamples.cs" id="read_state_example"::: -There's no need to call during normal operation; Orleans loads the state automatically during activation. However, you can use to refresh state modified externally. +There's no need to call during normal operation; Orleans loads the state automatically during activation. However, you can use to refresh state modified externally. See the [Failure modes](#failure-modes) section below for details on error-handling mechanisms. ### Write state -You can modify the state via the property. The modified state isn't automatically persisted. Instead, you decide when to persist state by calling the method. For example, the following method updates a property on and persists the updated state: +You can modify the state via the property. The modified state isn't automatically persisted. Instead, you decide when to persist state by calling the method. For example, the following method updates a property on and persists the updated state: :::code language="csharp" source="./snippets/persistence/GrainExamples.cs" id="write_state_example"::: @@ -97,7 +97,7 @@ See the [Failure modes](#failure-modes) section below for details on error handl ### Clear state -The method clears the grain's state in storage. Depending on the provider, this operation might optionally delete the grain state entirely. +The method clears the grain's state in storage. Depending on the provider, this operation might optionally delete the grain state entirely. ## Get started @@ -163,21 +163,21 @@ Now that you've configured a storage provider named `"profileStore"`, you can ac You can add persistent state to a grain in two primary ways: -1. By injecting into the grain's constructor. -1. By inheriting from . +1. By injecting into the grain's constructor. +1. By inheriting from . -The recommended way to add storage to a grain is by injecting into the grain's constructor with an associated `[PersistentState("stateName", "providerName")]` attribute. For details on , see [Using to add storage to a grain](#using-graintstate-to-add-storage-to-a-grain) below. Using is still supported but considered a legacy approach. +The recommended way to add storage to a grain is by injecting into the grain's constructor with an associated `[PersistentState("stateName", "providerName")]` attribute. For details on , see [Using to add storage to a grain](#using-graintstate-to-add-storage-to-a-grain) below. Using is still supported but considered a legacy approach. Declare a class to hold your grain's state: :::code language="csharp" source="./snippets/persistence/StateTypes.cs" id="profile_state"::: -Inject into the grain's constructor: +Inject into the grain's constructor: :::code language="csharp" source="./snippets/persistence/GrainExamples.cs" id="user_grain_constructor_injection"::: > [!IMPORTANT] -> The profile state will not be loaded at the time it is injected into the constructor, so accessing it is invalid at that time. The state will be loaded before is called. +> The profile state will not be loaded at the time it is injected into the constructor, so accessing it is invalid at that time. The state will be loaded before is called. Now that the grain has a persistent state, you can add methods to read and write the state: @@ -187,15 +187,15 @@ Now that the grain has a persistent state, you can add methods to read and write ### Failure modes for read operations -Failures returned by the storage provider during the initial read of state data for a particular grain fail the activation operation for that grain. In such cases, there won't be any call to that grain's lifecycle callback method. The original request to the grain that caused the activation faults back to the caller, just like any other failure during grain activation. Failures encountered by the storage provider when reading state data for a particular grain result in an exception from the . The grain can choose to handle or ignore the exception, just like any other in Orleans. +Failures returned by the storage provider during the initial read of state data for a particular grain fail the activation operation for that grain. In such cases, there won't be any call to that grain's lifecycle callback method. The original request to the grain that caused the activation faults back to the caller, just like any other failure during grain activation. Failures encountered by the storage provider when reading state data for a particular grain result in an exception from the . The grain can choose to handle or ignore the exception, just like any other in Orleans. Any attempt to send a message to a grain that failed to load at silo startup due to a missing or bad storage provider configuration returns the permanent error . ### Failure modes for write operations -Failures encountered by the storage provider when writing state data for a particular grain result in an exception thrown by the . Usually, this means the grain call exception is thrown back to the client caller, provided the is correctly chained into the final return for this grain method. However, in certain advanced scenarios, you can write grain code to specifically handle such write errors, just like handling any other faulted . +Failures encountered by the storage provider when writing state data for a particular grain result in an exception thrown by the . Usually, this means the grain call exception is thrown back to the client caller, provided the is correctly chained into the final return for this grain method. However, in certain advanced scenarios, you can write grain code to specifically handle such write errors, just like handling any other faulted . -Grains executing error-handling or recovery code *must* catch exceptions or faulted s and not rethrow them, signifying they have successfully handled the write error. +Grains executing error-handling or recovery code *must* catch exceptions or faulted s and not rethrow them, signifying they have successfully handled the write error. ## Recommendations @@ -212,26 +212,26 @@ Code evolves, and this often includes storage types. To accommodate these change :::zone-end -## Using to add storage to a grain +## Using to add storage to a grain > [!IMPORTANT] -> Using to add storage to a grain is considered *legacy* functionality. Add grain storage using as previously described. +> Using to add storage to a grain is considered *legacy* functionality. Add grain storage using as previously described. -Grain classes inheriting from (where `T` is an application-specific state data type needing persistence) have their state loaded automatically from the specified storage. +Grain classes inheriting from (where `T` is an application-specific state data type needing persistence) have their state loaded automatically from the specified storage. Mark such grains with a specifying a named instance of a storage provider to use for reading/writing the state data for this grain. :::code language="csharp" source="./snippets/persistence/GrainExamples.cs" id="storage_provider_attribute"::: -The base class defines the following methods for subclasses to call: +The base class defines the following methods for subclasses to call: :::code language="csharp" source="./snippets/persistence/StorageProviderTypes.cs" id="grain_base_methods"::: -The behavior of these methods corresponds to their counterparts on defined earlier. +The behavior of these methods corresponds to their counterparts on defined earlier. ## Create a storage provider -There are two parts to the state persistence APIs: the API exposed to the grain via or , and the storage provider API, centered around —the interface storage providers must implement: +There are two parts to the state persistence APIs: the API exposed to the grain via or , and the storage provider API, centered around —the interface storage providers must implement: :::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" @@ -278,7 +278,7 @@ Create a custom storage provider by implementing this interface and [registering ### Storage provider semantics -An opaque provider-specific value (`string`) *may* be set by a storage provider as part of the grain state metadata populated when the state was read. Some providers may choose to leave this as `null` if they don't use `Etag`s. +An opaque provider-specific value (`string`) *may* be set by a storage provider as part of the grain state metadata populated when the state was read. Some providers may choose to leave this as `null` if they don't use `Etag`s. Any attempt to perform a write operation when the storage provider detects an `Etag` constraint violation *should* cause the write to be faulted with transient error and wrapping the underlying storage exception. @@ -294,7 +294,7 @@ Individual storage providers should decide how best to store grain state – blo The Orleans runtime resolves a storage provider from the service provider () when a grain is created. The runtime resolves an instance of . If the storage provider is named (for example, via the `[PersistentState(stateName, storageName)]` attribute), then a named instance of is resolved. -To register a named instance of , use the extension method, following the example of the [AzureTableGrainStorage provider here](https://github.com/dotnet/orleans/blob/af974d37864f85bfde5dc02f2f60bba997f2162d/src/Azure/Orleans.Persistence.AzureStorage/Hosting/AzureTableSiloBuilderExtensions.cs#L78). +To register a named instance of , use the extension method, following the example of the [AzureTableGrainStorage provider here](https://github.com/dotnet/orleans/blob/af974d37864f85bfde5dc02f2f60bba997f2162d/src/Azure/Orleans.Persistence.AzureStorage/Hosting/AzureTableSiloBuilderExtensions.cs#L78). ## Redis grain persistence @@ -304,11 +304,11 @@ To register a named instance of , use the extension method: +Configure Redis grain storage using the extension method: :::code language="csharp" source="./snippets/persistence/StorageConfiguration.cs" id="configure_redis"::: -To configure Redis as the default grain storage provider, use : +To configure Redis as the default grain storage provider, use : :::code language="csharp" source="./snippets/persistence/StorageConfiguration.cs" id="configure_redis_default"::: @@ -319,7 +319,7 @@ The class provides the following | Property | Type | Description | |----------|------|-------------| | `ConfigurationOptions` | `ConfigurationOptions` | The StackExchange.Redis client configuration. Required. | -| `DeleteStateOnClear` | `bool` | Whether to delete state from Redis when is called. Default is `false`. | +| `DeleteStateOnClear` | `bool` | Whether to delete state from Redis when is called. Default is `false`. | | `EntryExpiry` | `TimeSpan?` | Optional expiration time for entries. Only set this for ephemeral environments like testing, as it can cause duplicate activations. Default is `null`. | | `GrainStorageSerializer` | `IGrainStorageSerializer` | The serializer to use for grain state. Default uses the Orleans serializer. | | `CreateMultiplexer` | `Func>` | Custom factory for creating the Redis connection multiplexer. | @@ -359,11 +359,11 @@ Install the [Microsoft.Orleans.Persistence.Cosmos](https://www.nuget.org/package dotnet add package Microsoft.Orleans.Persistence.Cosmos ``` -Configure Cosmos DB grain storage using the extension method: +Configure Cosmos DB grain storage using the extension method: :::code language="csharp" source="./snippets/persistence/StorageConfiguration.cs" id="configure_cosmos"::: -To configure Cosmos DB as the default grain storage provider, use : +To configure Cosmos DB as the default grain storage provider, use : :::code language="csharp" source="./snippets/persistence/StorageConfiguration.cs" id="configure_cosmos_default"::: @@ -376,7 +376,7 @@ The class provides t | `DatabaseName` | `string` | `"Orleans"` | The name of the Cosmos DB database. | | `ContainerName` | `string` | `"OrleansStorage"` | The name of the container for grain state data. | | `IsResourceCreationEnabled` | `bool` | `false` | When `true`, automatically creates the database and container if they don't exist. | -| `DeleteStateOnClear` | `bool` | `false` | Whether to delete state from Cosmos DB when is called. | +| `DeleteStateOnClear` | `bool` | `false` | Whether to delete state from Cosmos DB when is called. | | `InitStage` | `int` | `ServiceLifecycleStage.ApplicationServices` | The stage of silo lifecycle when storage is initialized. | | `StateFieldsToIndex` | `List` | Empty | JSON paths of state properties to include in the Cosmos DB index. | | `PartitionKeyPath` | `string` | `"/PartitionKey"` | The JSON path for the partition key in the container. | diff --git a/docs/orleans/grains/grain-persistence/relational-storage.md b/docs/orleans/grains/grain-persistence/relational-storage.md index 30bfa3bc312b9..faffa643d6a14 100644 --- a/docs/orleans/grains/grain-persistence/relational-storage.md +++ b/docs/orleans/grains/grain-persistence/relational-storage.md @@ -249,7 +249,7 @@ After implementing a custom serializer, configure it using the property in . `StorageSerializationPicker` is the default implementation of `IStorageSerializationPicker`. You can see an example of changing the data storage format or using serializers in [RelationalStoreTests](https://github.com/dotnet/orleans/blob/main/test/Extensions/Orleans.AdoNet.Tests/StorageTests/RelationalStoreTests.cs). Note that direct application-level access to `AdoNetGrainStorage` to configure serialization isn't available in Orleans 3.x. +After implementing the serializers, they're registered internally with the property in . `StorageSerializationPicker` is the default implementation of `IStorageSerializationPicker`. You can see an example of changing the data storage format or using serializers in [RelationalStoreTests](https://github.com/dotnet/orleans/blob/main/test/Extensions/Orleans.AdoNet.Tests/StorageTests/RelationalStoreTests.cs). Note that direct application-level access to `AdoNetGrainStorage` to configure serialization isn't available in Orleans 3.x. :::zone-end diff --git a/docs/orleans/grains/grain-references.md b/docs/orleans/grains/grain-references.md index 38d807b926dd9..f6de32754770a 100644 --- a/docs/orleans/grains/grain-references.md +++ b/docs/orleans/grains/grain-references.md @@ -11,7 +11,7 @@ Before calling a method on a grain, you first need a reference to that grain. A Since a grain reference represents the logical identity of the target grain, it's independent of the grain's physical location and remains valid even after a complete system restart. You can use grain references like any other .NET object. You can pass it to a method, use it as a method return value, and even save it to persistent storage. -You can obtain a grain reference by passing the identity of a grain to the method, where `T` is the grain interface and `key` is the unique key of the grain within its type. +You can obtain a grain reference by passing the identity of a grain to the method, where `T` is the grain interface and `key` is the unique key of the grain within its type. The following examples show how to obtain a grain reference for the `IPlayerGrain` interface defined previously. diff --git a/docs/orleans/grains/grainservices.md b/docs/orleans/grains/grainservices.md index d9b494e98885f..6ae63bd30aaca 100644 --- a/docs/orleans/grains/grainservices.md +++ b/docs/orleans/grains/grainservices.md @@ -75,7 +75,7 @@ A is a special grain: it has no stable ident :::zone-end -1. Create an interface for the `GrainServiceClient` that other grains will use to connect to the `GrainService`. +1. Create an interface for the `GrainServiceClient` that other grains will use to connect to the `GrainService`. ```csharp public interface IDataServiceClient : IGrainServiceClient, IDataService @@ -138,7 +138,7 @@ A is a special grain: it has no stable ident ## Additional notes -There's an extension method, , used to register grain services. +There's an extension method, , used to register grain services. ```csharp services.AddSingleton( diff --git a/docs/orleans/grains/index.md b/docs/orleans/grains/index.md index 7154d8c52afb7..8c10d34e22bc1 100644 --- a/docs/orleans/grains/index.md +++ b/docs/orleans/grains/index.md @@ -13,7 +13,7 @@ For more thorough instructions, see the [Project Setup](../tutorials-and-samples ## Grain interfaces and classes -Grains interact with each other and are called from outside by invoking methods declared as part of their respective grain interfaces. A grain class implements one or more previously declared grain interfaces. All methods of a grain interface must return a (for `void` methods), a , or a (for methods returning values of type `T`). +Grains interact with each other and are called from outside by invoking methods declared as part of their respective grain interfaces. A grain class implements one or more previously declared grain interfaces. All methods of a grain interface must return a (for `void` methods), a , or a (for methods returning values of type `T`). The following is an excerpt from the Orleans Presence Service sample: @@ -89,7 +89,7 @@ public interface IDataProcessingGrain : IGrainWithGuidKey // 2 minute timeout using hours, minutes, seconds [ResponseTimeout(0, 2, 0)] Task ProcessLargeDatasetAsync(Dataset data, CancellationToken cancellationToken = default); - + // 500ms timeout using TimeSpan.FromMilliseconds equivalent [ResponseTimeout("00:00:00.500")] Task GetHealthAsync(CancellationToken cancellationToken = default); @@ -116,7 +116,7 @@ Consider the following when configuring timeouts: ## Return values from grain methods -Define a grain method that returns a value of type `T` in a grain interface as returning a . +Define a grain method that returns a value of type `T` in a grain interface as returning a . For grain methods not marked with the `async` keyword, when the return value is available, you usually return it using the following statement: ```csharp @@ -174,11 +174,11 @@ public Task GrainMethod6() } ``` - can be used instead of . + can be used instead of . ## IAsyncEnumerable return values -Orleans supports returning from grain methods, enabling efficient streaming of data from a grain to a caller without loading the entire result set into memory. This is useful for scenarios like: +Orleans supports returning from grain methods, enabling efficient streaming of data from a grain to a caller without loading the entire result set into memory. This is useful for scenarios like: - Returning large collections of data progressively - Streaming real-time updates @@ -191,7 +191,7 @@ public interface IDataGrain : IGrainWithStringKey { // Returns a streaming sequence of items IAsyncEnumerable GetAllItemsAsync(); - + // Can also include CancellationToken for cancellation support IAsyncEnumerable GetItemsAsync(CancellationToken cancellationToken = default); } @@ -199,7 +199,7 @@ public interface IDataGrain : IGrainWithStringKey ### Implement the streaming method -Use the `yield return` statement or return an directly: +Use the `yield return` statement or return an directly: ```csharp public class DataGrain : Grain, IDataGrain @@ -213,7 +213,7 @@ public class DataGrain : Grain, IDataGrain yield return item; } } - + public async IAsyncEnumerable GetItemsAsync( [EnumeratorCancellation] CancellationToken cancellationToken = default) { @@ -224,8 +224,8 @@ public class DataGrain : Grain, IDataGrain yield return item; } } - - private Task FetchItemAsync(int id) => + + private Task FetchItemAsync(int id) => Task.FromResult(new DataItem { Id = id }); } @@ -245,7 +245,7 @@ var grain = client.GetGrain("mydata"); await foreach (var item in grain.GetAllItemsAsync()) { Console.WriteLine($"Received item: {item.Id}"); - + // Process each item as it arrives await ProcessItemAsync(item); } @@ -273,7 +273,7 @@ await foreach (var item in grain.GetAllItemsAsync().WithBatchSize(50)) | **Backpressure** | Built-in | Provider-dependent | | **Persistence** | No | Optional (provider-dependent) | -Use when: +Use when: - You need a simple request-response pattern with streaming results - The caller initiates the data flow and consumes all results @@ -291,7 +291,7 @@ A grain reference is a proxy object implementing the same grain interface as the Since a grain reference represents the logical identity of the target grain, it's independent of the grain's physical location and remains valid even after a complete system restart. You can use grain references like any other .NET object. You can pass it to a method, use it as a method return value, etc., and even save it to persistent storage. -You can obtain a grain reference by passing the identity of a grain to the method, where `T` is the grain interface and `key` is the unique key of the grain within its type. +You can obtain a grain reference by passing the identity of a grain to the method, where `T` is the grain interface and `key` is the unique key of the grain within its type. The following examples show how to obtain a grain reference for the `IPlayerGrain` interface defined previously. @@ -357,7 +357,7 @@ Exceptions thrown from grain methods don't cause the grain to be deactivated unl ### Virtual methods -A grain class can optionally override the and virtual methods. The Orleans runtime invokes these methods upon activation and deactivation of each grain of the class. This gives your grain code a chance to perform additional initialization and cleanup operations. An exception thrown by fails the activation process. +A grain class can optionally override the and virtual methods. The Orleans runtime invokes these methods upon activation and deactivation of each grain of the class. This gives your grain code a chance to perform additional initialization and cleanup operations. An exception thrown by fails the activation process. While (if overridden) is always called as part of the grain activation process, isn't guaranteed to be called in all situations (for example, in case of a server failure or other abnormal events). Because of this, your applications shouldn't rely on for performing critical operations, such as persisting state changes. Use it only for best-effort operations. diff --git a/docs/orleans/grains/observers.md b/docs/orleans/grains/observers.md index 5785e578d815e..7ee5d0650e52c 100644 --- a/docs/orleans/grains/observers.md +++ b/docs/orleans/grains/observers.md @@ -11,9 +11,9 @@ ai-usage: ai-assisted Sometimes, a simple message/response pattern isn't enough, and the client needs to receive asynchronous notifications. For example, a user might want notification when a friend publishes a new instant message. -Client observers are a mechanism allowing asynchronous notification of clients. Observer interfaces must inherit from , and all methods must return either `void`, , , , or . We don't recommend a return type of `void` because it might encourage using `async void` in the implementation. This is a dangerous pattern, as it can cause application crashes if an exception is thrown from the method. Instead, for best-effort notification scenarios, consider applying the to the observer's interface method. This causes the receiver not to send a response for the method invocation and makes the method return immediately at the call site, without waiting for a response from the observer. A grain calls a method on an observer by invoking it like any grain interface method. The Orleans runtime ensures the delivery of requests and responses. A common use case for observers is enlisting a client to receive notifications when an event occurs in the Orleans application. A grain publishing such notifications should provide an API to add or remove observers. Additionally, it's usually convenient to expose a method allowing cancellation of an existing subscription. +Client observers are a mechanism allowing asynchronous notification of clients. Observer interfaces must inherit from , and all methods must return either `void`, , , , or . We don't recommend a return type of `void` because it might encourage using `async void` in the implementation. This is a dangerous pattern, as it can cause application crashes if an exception is thrown from the method. Instead, for best-effort notification scenarios, consider applying the to the observer's interface method. This causes the receiver not to send a response for the method invocation and makes the method return immediately at the call site, without waiting for a response from the observer. A grain calls a method on an observer by invoking it like any grain interface method. The Orleans runtime ensures the delivery of requests and responses. A common use case for observers is enlisting a client to receive notifications when an event occurs in the Orleans application. A grain publishing such notifications should provide an API to add or remove observers. Additionally, it's usually convenient to expose a method allowing cancellation of an existing subscription. -You can use a utility class like to simplify the development of observed grain types. Unlike grains, which Orleans automatically reactivates as needed after failure, clients aren't fault-tolerant: a client that fails might never recover. For this reason, the `ObserverManager` utility removes subscriptions after a configured duration. Active clients should resubscribe on a timer to keep their subscriptions active. +You can use a utility class like to simplify the development of observed grain types. Unlike grains, which Orleans automatically reactivates as needed after failure, clients aren't fault-tolerant: a client that fails might never recover. For this reason, the `ObserverManager` utility removes subscriptions after a configured duration. Active clients should resubscribe on a timer to keep their subscriptions active. To subscribe to a notification, the client must first create a local object implementing the observer interface. It then calls the method on the grain factory to turn the object into a grain reference. You can then pass this reference to the subscription method on the notifying grain. When the observer is no longer needed, call to clean up the reference and avoid a memory leak in the client process. @@ -48,10 +48,10 @@ public class Chat : IChat } ``` -On the server, you should next have a grain that sends these chat messages to clients. The grain should also provide a mechanism for clients to subscribe and unsubscribe from notifications. For subscriptions, the grain can use an instance of the utility class [ObserverManager\](). +On the server, you should next have a grain that sends these chat messages to clients. The grain should also provide a mechanism for clients to subscribe and unsubscribe from notifications. For subscriptions, the grain can use an instance of the utility class [ObserverManager\](). > [!NOTE] -> is part of Orleans since version 7.0. For older versions, the following [implementation](https://github.com/dotnet/orleans/blob/e997335d2d689bb39e67f6bcf6fd70862a22c02f/test/Grains/TestGrains/ObserverManager.cs#L12) can be copied. +> is part of Orleans since version 7.0. For older versions, the following [implementation](https://github.com/dotnet/orleans/blob/e997335d2d689bb39e67f6bcf6fd70862a22c02f/test/Grains/TestGrains/ObserverManager.cs#L12) can be copied. ```csharp class HelloGrain : Grain, IHello @@ -83,7 +83,7 @@ class HelloGrain : Grain, IHello } ``` -To send a message to clients, use the method of the [ObserverManager\]() instance. The method takes an `Action` method or lambda expression (where `T` is of type `IChat` here). You can call any method on the interface to send it to clients. In our case, we only have one method, `ReceiveMessage`, and our sending code on the server looks like this: +To send a message to clients, use the method of the [ObserverManager\]() instance. The method takes an `Action` method or lambda expression (where `T` is of type `IChat` here). You can call any method on the interface to send it to clients. In our case, we only have one method, `ReceiveMessage`, and our sending code on the server looks like this: ```csharp public Task SendUpdateMessage(string message) @@ -123,18 +123,18 @@ _grainFactory.DeleteObjectReference(obj); ``` > [!IMPORTANT] -> The client holds observer instances passed to in its internal object manager by using a , so the observer instance itself might be garbage collected if no other references exist, but the object reference registration stays active until you delete it. +> The client holds observer instances passed to in its internal object manager by using a , so the observer instance itself might be garbage collected if no other references exist, but the object reference registration stays active until you delete it. > > Always call when you no longer need an observer to remove that registration. Without it, a reference remains in the client's internal object manager, causing a memory leak that can eventually crash the client process. You should maintain a reference for each observer you don't want collected. > [!NOTE] -> Observers are inherently unreliable because a client hosting an observer might fail, and observers created after recovery have different (randomized) identities. relies on periodic resubscription by observers, as discussed above, so it can remove inactive observers. +> Observers are inherently unreliable because a client hosting an observer might fail, and observers created after recovery have different (randomized) identities. relies on periodic resubscription by observers, as discussed above, so it can remove inactive observers. ## Execution model -Implementations of are registered via a call to . Each call to that method creates a new reference pointing to that implementation. Orleans executes requests sent to each of these references one by one, to completion. Observers are non-reentrant; therefore, Orleans doesn't interleave concurrent requests to an observer. If multiple observers receive requests concurrently, those requests can execute in parallel. Attributes such as or don't affect the execution of observer methods; you cannot customize the execution model. +Implementations of are registered via a call to . Each call to that method creates a new reference pointing to that implementation. Orleans executes requests sent to each of these references one by one, to completion. Observers are non-reentrant; therefore, Orleans doesn't interleave concurrent requests to an observer. If multiple observers receive requests concurrently, those requests can execute in parallel. Attributes such as or don't affect the execution of observer methods; you cannot customize the execution model. ## CancellationToken support diff --git a/docs/orleans/grains/oneway.md b/docs/orleans/grains/oneway.md index 6ee85718c86da..0a426917b2bcd 100644 --- a/docs/orleans/grains/oneway.md +++ b/docs/orleans/grains/oneway.md @@ -21,4 +21,4 @@ public interface IOneWayGrain : IGrainWithGuidKey } ``` -One-way requests must return either or . They must not return generic variants of those types ( and ). +One-way requests must return either or . They must not return generic variants of those types ( and ). diff --git a/docs/orleans/grains/request-context.md b/docs/orleans/grains/request-context.md index 66abf04f124b7..ca76bf26a766e 100644 --- a/docs/orleans/grains/request-context.md +++ b/docs/orleans/grains/request-context.md @@ -23,10 +23,10 @@ Use the preceding API to retrieve a value from the current request context. The backing storage for is async-local. When a caller (client-side or within Orleans) sends a request, the contents of the caller's are included with the Orleans message for the request. When the grain code receives the request, that metadata is accessible from the local . If the grain code doesn't modify the , then any grain it requests receives the same metadata, and so on. -Application metadata is also maintained when you schedule a future computation using or . In both cases, the continuation executes with the same metadata as the scheduling code had when the computation was scheduled. That is, the system copies the current metadata and passes it to the continuation, so the continuation won't see changes made after the call to or . +Application metadata is also maintained when you schedule a future computation using or . In both cases, the continuation executes with the same metadata as the scheduling code had when the computation was scheduled. That is, the system copies the current metadata and passes it to the continuation, so the continuation won't see changes made after the call to or . > [!IMPORTANT] -> Application metadata doesn't flow back with responses. Code that runs as a result of receiving a response (either within a continuation or after a call to or ) still runs within the current context set by the original request. +> Application metadata doesn't flow back with responses. Code that runs as a result of receiving a response (either within a continuation or after a call to or ) still runs within the current context set by the original request. For example, to set a trace ID in the client to a new , call: diff --git a/docs/orleans/grains/timers-and-reminders.md b/docs/orleans/grains/timers-and-reminders.md index 50ab81bf95043..54b4bd9832b22 100644 --- a/docs/orleans/grains/timers-and-reminders.md +++ b/docs/orleans/grains/timers-and-reminders.md @@ -133,7 +133,7 @@ public class MyGrain : Grain, IMyGrain null, TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(10)); - + return base.OnActivateAsync(); } @@ -272,7 +272,7 @@ For more information about Orleans and .NET Aspire integration, see [Orleans and ## Reminder usage -A grain using reminders must implement the method. +A grain using reminders must implement the method. ```csharp Task IRemindable.ReceiveReminder(string reminderName, TickStatus status) @@ -282,7 +282,7 @@ Task IRemindable.ReceiveReminder(string reminderName, TickStatus status) } ``` - To start a reminder, use the method, which returns an object: + To start a reminder, use the method, which returns an object: ```csharp protected Task RegisterOrUpdateReminder( @@ -295,17 +295,17 @@ protected Task RegisterOrUpdateReminder( - `dueTime`: specifies a quantity of time to wait before issuing the first-timer tick. - `period`: specifies the period of the timer. -Since reminders survive the lifetime of any single activation, you must explicitly cancel them (as opposed to disposing of them). Cancel a reminder by calling : +Since reminders survive the lifetime of any single activation, you must explicitly cancel them (as opposed to disposing of them). Cancel a reminder by calling : ```csharp protected Task UnregisterReminder(IGrainReminder reminder) ``` -The `reminder` is the handle object returned by . +The `reminder` is the handle object returned by . Instances of `IGrainReminder` aren't guaranteed to be valid beyond the lifespan of an activation. If you wish to identify a reminder persistently, use a string containing the reminder's name. -If you only have the reminder's name and need the corresponding `IGrainReminder` instance, call the method: +If you only have the reminder's name and need the corresponding `IGrainReminder` instance, call the method: ```csharp protected Task GetReminder(string reminderName) diff --git a/docs/orleans/grains/transactions.md b/docs/orleans/grains/transactions.md index 04efe656718f3..d758005fc6419 100644 --- a/docs/orleans/grains/transactions.md +++ b/docs/orleans/grains/transactions.md @@ -16,7 +16,7 @@ Orleans supports distributed ACID transactions against persistent grain state. T ## Setup -Orleans transactions are opt-in. Both the silo and the client must be configured to use transactions. If they aren't configured, any calls to transactional methods on a grain implementation receive an . To enable transactions on a silo, call on the silo host builder: +Orleans transactions are opt-in. Both the silo and the client must be configured to use transactions. If they aren't configured, any calls to transactional methods on a grain implementation receive an . To enable transactions on a silo, call on the silo host builder: ```csharp var builder = Host.CreateDefaultBuilder(args) @@ -26,7 +26,7 @@ var builder = Host.CreateDefaultBuilder(args) }); ``` -Likewise, to enable transactions on the client, call on the client host builder: +Likewise, to enable transactions on the client, call on the client host builder: ```csharp var builder = Host.CreateDefaultBuilder(args) @@ -38,7 +38,7 @@ var builder = Host.CreateDefaultBuilder(args) ### Transactional state storage -To use transactions, you need to configure a data store. To support various data stores with transactions, Orleans uses the storage abstraction . This abstraction is specific to the needs of transactions, unlike generic grain storage (). To use transaction-specific storage, configure the silo using any implementation of `ITransactionalStateStorage`, such as Azure (). +To use transactions, you need to configure a data store. To support various data stores with transactions, Orleans uses the storage abstraction . This abstraction is specific to the needs of transactions, unlike generic grain storage (). To use transaction-specific storage, configure the silo using any implementation of `ITransactionalStateStorage`, such as Azure (). For example, consider the following host builder configuration: @@ -71,7 +71,7 @@ You cannot mark as transactional because a ## Grain implementations -A grain implementation needs to use an facet to manage grain state via [ACID transactions](../overview.md#distributed-acid-transactions). +A grain implementation needs to use an facet to manage grain state via [ACID transactions](../overview.md#distributed-acid-transactions). ```csharp public interface ITransactionalState @@ -114,7 +114,7 @@ The `Balance` state object is then used in the `AccountGrain` implementation as > [!IMPORTANT] > A transactional grain must be marked with the to ensure that the transaction context is correctly passed to the grain call. -In the preceding example, the declares that the `balance` constructor parameter should be associated with a transactional state named `"balance"`. With this declaration, Orleans injects an instance with state loaded from the transactional state storage named `"TransactionStore"`. You can modify the state via or read it via . The transaction infrastructure ensures that any such changes performed as part of a transaction (even among multiple grains distributed across an Orleans cluster) are either all committed or all undone upon completion of the grain call that created the transaction (`IAtmGrain.Transfer` in the preceding example). +In the preceding example, the declares that the `balance` constructor parameter should be associated with a transactional state named `"balance"`. With this declaration, Orleans injects an instance with state loaded from the transactional state storage named `"TransactionStore"`. You can modify the state via or read it via . The transaction infrastructure ensures that any such changes performed as part of a transaction (even among multiple grains distributed across an Orleans cluster) are either all committed or all undone upon completion of the grain call that created the transaction (`IAtmGrain.Transfer` in the preceding example). ## Call transaction methods from a client diff --git a/docs/orleans/host/client.md b/docs/orleans/host/client.md index d74301342933c..973d225206477 100644 --- a/docs/orleans/host/client.md +++ b/docs/orleans/host/client.md @@ -62,7 +62,7 @@ Before you can use a grain client to make calls to grains hosted in an Orleans c :::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" -Provide configuration via and several supplemental option classes containing a hierarchy of configuration properties for programmatically configuring a client. For more information, see [Client configuration](configuration-guide/client-configuration.md). +Provide configuration via and several supplemental option classes containing a hierarchy of configuration properties for programmatically configuring a client. For more information, see [Client configuration](configuration-guide/client-configuration.md). Consider the following example of a client configuration: @@ -140,7 +140,7 @@ Finally, you need to call the `Connect()` method on the constructed client objec ### Make calls to grains -Making calls to grains from a client is no different from [making such calls from within grain code](../grains/index.md). Use the same method (where `T` is the target grain interface) in both cases [to obtain grain references](../grains/grain-references.md). The difference lies in which factory object invokes . In client code, you do this through the connected client object, as the following example shows: +Making calls to grains from a client is no different from [making such calls from within grain code](../grains/index.md). Use the same method (where `T` is the target grain interface) in both cases [to obtain grain references](../grains/grain-references.md). The difference lies in which factory object invokes . In client code, you do this through the connected client object, as the following example shows: ```csharp IPlayerGrain player = client.GetGrain(playerId); @@ -149,7 +149,7 @@ Task joinGameTask = player.JoinGame(game) await joinGameTask; ``` -A call to a grain method returns a or , as required by the [grain interface rules](../grains/index.md). The client can use the `await` keyword to asynchronously await the returned without blocking the thread, or in some cases, use the `Wait()` method to block the current thread of execution. +A call to a grain method returns a or , as required by the [grain interface rules](../grains/index.md). The client can use the `await` keyword to asynchronously await the returned without blocking the thread, or in some cases, use the `Wait()` method to block the current thread of execution. The major difference between making calls to grains from client code and from within another grain is the single-threaded execution model of grains. The Orleans runtime constrains grains to be single-threaded, while clients can be multi-threaded. Orleans doesn't provide any such guarantee on the client-side, so it's up to the client to manage its concurrency using appropriate synchronization constructs for its environment—locks, events, `Tasks`, etc. diff --git a/docs/orleans/host/configuration-guide/activation-collection.md b/docs/orleans/host/configuration-guide/activation-collection.md index 239d6300d052a..8624644b9a018 100644 --- a/docs/orleans/host/configuration-guide/activation-collection.md +++ b/docs/orleans/host/configuration-guide/activation-collection.md @@ -50,7 +50,7 @@ The time after which an idle grain activation becomes subject to collection is c ### Delay activation collection -A grain activation can delay its collection by calling the method: +A grain activation can delay its collection by calling the method: ```csharp protected void DelayDeactivation(TimeSpan timeSpan) diff --git a/docs/orleans/host/configuration-guide/list-of-options-classes.md b/docs/orleans/host/configuration-guide/list-of-options-classes.md index 1feda00ae71af..0cf2451a93f63 100644 --- a/docs/orleans/host/configuration-guide/list-of-options-classes.md +++ b/docs/orleans/host/configuration-guide/list-of-options-classes.md @@ -79,7 +79,7 @@ All options classes used to configure Orleans are found in the `Orleans.Configur | | Setting the Silo endpoint options | | | Options for grain garbage collection | | | Governs grain implementation selection in heterogeneous deployments | -| | Settings for load shedding configuration. Must have a registered implementation of such as through or (Windows only) for `LoadShedding` to function. | +| | Settings for load shedding configuration. Must have a registered implementation of such as through or (Windows only) for `LoadShedding` to function. | | | Performance tuning options (networking, number of threads) | | | Configure silo behavior on process exit | | | Configuring scheduler behavior | diff --git a/docs/orleans/host/configuration-guide/local-development-configuration.md b/docs/orleans/host/configuration-guide/local-development-configuration.md index 49c9df60682f1..f91a2c128dcf3 100644 --- a/docs/orleans/host/configuration-guide/local-development-configuration.md +++ b/docs/orleans/host/configuration-guide/local-development-configuration.md @@ -17,7 +17,7 @@ For a working sample application targeting Orleans 7.0, see [Orleans: Hello Worl :::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" -We recommend using the [Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting) NuGet package to configure and run the silo. Also, when developing an Orleans silo, you need the [Microsoft.Orleans.Server](https://www.nuget.org/packages/Microsoft.Orleans.Server) NuGet package. For local Orleans silo development, configure localhost clustering, which uses the loopback address. To use localhost clustering, call the extension method. Consider this example _Program.cs_ file for the silo host: +We recommend using the [Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting) NuGet package to configure and run the silo. Also, when developing an Orleans silo, you need the [Microsoft.Orleans.Server](https://www.nuget.org/packages/Microsoft.Orleans.Server) NuGet package. For local Orleans silo development, configure localhost clustering, which uses the loopback address. To use localhost clustering, call the extension method. Consider this example _Program.cs_ file for the silo host: ```csharp using Microsoft.Extensions.Hosting; @@ -65,7 +65,7 @@ Here's an example of how you can start a local silo: :::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" -We recommend using the [Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting) NuGet package to configure and run clients (in addition to the silo). You also need the [Microsoft.Orleans.Client](https://www.nuget.org/packages/Microsoft.Orleans.Client) NuGet package. To use localhost clustering on the consuming client, call the extension method. Consider this example _Program.cs_ file for the client host: +We recommend using the [Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting) NuGet package to configure and run clients (in addition to the silo). You also need the [Microsoft.Orleans.Client](https://www.nuget.org/packages/Microsoft.Orleans.Client) NuGet package. To use localhost clustering on the consuming client, call the extension method. Consider this example _Program.cs_ file for the client host: ```csharp using Microsoft.Extensions.Hosting; diff --git a/docs/orleans/host/configuration-guide/serialization-configuration.md b/docs/orleans/host/configuration-guide/serialization-configuration.md index 0b72b8520a855..c5b7597fad622 100644 --- a/docs/orleans/host/configuration-guide/serialization-configuration.md +++ b/docs/orleans/host/configuration-guide/serialization-configuration.md @@ -25,7 +25,7 @@ siloBuilder.Services.AddSerializer(serializerBuilder => }); ``` -In the preceding example, the call to adds support for serializing and deserializing values using `Newtonsoft.Json.JsonSerializer`. You must perform similar configuration on all clients that need to handle those types. +In the preceding example, the call to adds support for serializing and deserializing values using `Newtonsoft.Json.JsonSerializer`. You must perform similar configuration on all clients that need to handle those types. For types marked with , Orleans prefers the generated serializer over the `Newtonsoft.Json` serializer. @@ -34,7 +34,7 @@ For types marked with , Orleans prefer Alternatively, to configure Orleans to use `System.Text.Json` to serialize your types, reference the [Microsoft.Orleans.Serialization.SystemTextJson](https://nuget.org/packages/Microsoft.Orleans.Serialization.SystemTextJson) NuGet package. Then, configure the serializer, specifying which types it will be responsible for. In the following example, we specify that the `System.Text.Json` serializer is responsible for all types in the `Example.Namespace` namespace. - Install the [Microsoft.Orleans.Serialization.SystemTextJson](https://nuget.org/packages/Microsoft.Orleans.Serialization.SystemTextJson) NuGet package. -- Configure the serializer using the method. +- Configure the serializer using the method. Consider the following example when interacting with the : diff --git a/docs/orleans/host/configuration-guide/serialization-customization.md b/docs/orleans/host/configuration-guide/serialization-customization.md index 63adab5ef278d..b38519d141b58 100644 --- a/docs/orleans/host/configuration-guide/serialization-customization.md +++ b/docs/orleans/host/configuration-guide/serialization-customization.md @@ -38,7 +38,7 @@ internal sealed class CustomOrleansSerializer : IGeneralizedCodec, IGeneralizedCopier, ITypeFilter { void IFieldCodec.WriteField( - ref Writer writer, + ref Writer writer, uint fieldIdDelta, Type expectedType, object value) => @@ -133,7 +133,7 @@ Serializers are registered for each supported data type at silo start-up and whe A hand-crafted serializer routine will rarely perform better than the generated versions. If you are tempted to write one, you should first consider the following options: -- If there are fields or properties within your data types that don't have to be serialized or copied, you can mark them with the . This will cause the generated code to skip these fields when copying and serializing. Use and where possible to avoid copying immutable data. For more information, see [Optimize copying](serialization-immutability.md#optimize-copying). If you're avoiding using the standard generic collection types, don't. The Orleans runtime contains custom serializers for the generic collections that use the semantics of the collections to optimize copying, serializing, and deserializing. These collections also have special "abbreviated" representations in the serialized byte stream, resulting in even more performance advantages. For instance, a `Dictionary` will be faster than a `List>`. +- If there are fields or properties within your data types that don't have to be serialized or copied, you can mark them with the . This will cause the generated code to skip these fields when copying and serializing. Use and where possible to avoid copying immutable data. For more information, see [Optimize copying](serialization-immutability.md#optimize-copying). If you're avoiding using the standard generic collection types, don't. The Orleans runtime contains custom serializers for the generic collections that use the semantics of the collections to optimize copying, serializing, and deserializing. These collections also have special "abbreviated" representations in the serialized byte stream, resulting in even more performance advantages. For instance, a `Dictionary` will be faster than a `List>`. - The most common case where a custom serializer can provide a noticeable performance gain is when there is significant semantic information encoded in the data type that is not available by simply copying field values. For instance, arrays that are sparsely populated may often be more efficiently serialized by treating the array as a collection of index/value pairs, even if the app keeps the data as a fully realized array for speed of operation. @@ -159,14 +159,14 @@ static private object Copy(object input, ICopyContext context) Copiers are usually the simplest serializer routines to write. They take an object, guaranteed to be of the same type as the type the copier is defined in, and must return a semantically-equivalent copy of the object. -If, as part of copying the object, a sub-object needs to be copied, the best way to do so is to use the routine: +If, as part of copying the object, a sub-object needs to be copied, the best way to do so is to use the routine: ```csharp var fooCopy = SerializationManager.DeepCopyInner(foo, context); ``` > [!IMPORTANT] -> It is important to use , instead of , to maintain the object identity context for the full copy operation. +> It is important to use , instead of , to maintain the object identity context for the full copy operation. #### Maintain object identity @@ -181,7 +181,7 @@ if (fooCopy is null) } ``` -The last line is the call to , which is required so that possible future references to the same object as `foo` references will get found properly by . +The last line is the call to , which is required so that possible future references to the same object as `foo` references will get found properly by . > [!NOTE] > This should only be done for class instances, _not_ `struct` instances or .NET primitives such as `string`, `Uri`, and `enum`. @@ -205,7 +205,7 @@ static private void Serialize( As with copiers, the "input" object passed to a serializer is guaranteed to be an instance of the defining type. The "expected" type may be ignored; it is based on compile-time type information about the data item, and is used at a higher level to form the type prefix in the byte stream. -To serialize sub-objects, use the routine: +To serialize sub-objects, use the routine: ```csharp SerializationManager.SerializeInner(foo, context, typeof(FooType)); @@ -231,7 +231,7 @@ static private object Deserialize( The "expected" type may be ignored; it is based on compile-time type information about the data item and is used at a higher level to form the type prefix in the byte stream. The actual type of the object to be created will always be the type of class in which the deserializer is defined. -To deserialize sub-objects, use the routine: +To deserialize sub-objects, use the routine: ```csharp var foo = SerializationManager.DeserializeInner(typeof(FooType), context); diff --git a/docs/orleans/host/configuration-guide/serialization-immutability.md b/docs/orleans/host/configuration-guide/serialization-immutability.md index d6f0b7488d711..376a2e647b6df 100644 --- a/docs/orleans/host/configuration-guide/serialization-immutability.md +++ b/docs/orleans/host/configuration-guide/serialization-immutability.md @@ -23,7 +23,7 @@ Note that all three processes—copying, serializing, and deserializing—respec In many cases, deep copying is unnecessary. For instance, consider a scenario where a web front-end receives a byte array from its client and passes that request, including the byte array, to a grain for processing. The front-end process does nothing with the array after passing it to the grain; specifically, it doesn't reuse the array for future requests. Inside the grain, the byte array is parsed to fetch input data but isn't modified. The grain returns another byte array it created back to the web client and discards the array immediately after returning it. The web front-end passes the result byte array back to its client without modification. -In such a scenario, there's no need to copy either the request or response byte arrays. Unfortunately, the Orleans runtime can't figure this out automatically, as it can't determine whether the web front-end or the grain modifies the arrays later. Ideally, a .NET mechanism would indicate that a value is no longer modified. Lacking that, we've added Orleans-specific mechanisms: the wrapper class and the . +In such a scenario, there's no need to copy either the request or response byte arrays. Unfortunately, the Orleans runtime can't figure this out automatically, as it can't determine whether the web front-end or the grain modifies the arrays later. Ideally, a .NET mechanism would indicate that a value is no longer modified. Lacking that, we've added Orleans-specific mechanisms: the wrapper class and the . ### Use the attribute to mark a type, parameter, property, or field as immutable @@ -68,11 +68,11 @@ Sometimes, you might not control the object; for example, it might be a `List +### Use -Use the wrapper class to indicate a value can be considered immutable; that is, the underlying value won't be modified, so no copying is required for safe sharing. Note that using implies neither the provider nor the recipient of the value will modify it in the future. It's a mutual, dual-sided commitment, not a one-sided one. +Use the wrapper class to indicate a value can be considered immutable; that is, the underlying value won't be modified, so no copying is required for safe sharing. Note that using implies neither the provider nor the recipient of the value will modify it in the future. It's a mutual, dual-sided commitment, not a one-sided one. -To use in your grain interface, pass instead of `T`. For instance, in the scenario described above, the grain method was: +To use in your grain interface, pass instead of `T`. For instance, in the scenario described above, the grain method was: ```csharp Task ProcessRequest(byte[] request); @@ -84,7 +84,7 @@ Which would then become: Task> ProcessRequest(Immutable request); ``` -To create an , simply use its constructor: +To create an , simply use its constructor: ```csharp Immutable immutable = new(buffer); diff --git a/docs/orleans/host/configuration-guide/serialization.md b/docs/orleans/host/configuration-guide/serialization.md index 84d16999c3bdb..c6ffe84a1f43e 100644 --- a/docs/orleans/host/configuration-guide/serialization.md +++ b/docs/orleans/host/configuration-guide/serialization.md @@ -33,7 +33,7 @@ Orleans includes an advanced and extensible serialization framework referred to High-fidelity representation of types is fairly uncommon for serializers, so some points warrant further explanation: -1. **Dynamic types and arbitrary polymorphism**: Orleans doesn't enforce restrictions on the types passed in grain calls and maintains the dynamic nature of the actual data type. This means, for example, if a method in a grain interface is declared to accept , but at runtime the sender passes a , the receiver indeed gets a `SortedDictionary` (even though the "static contract"/grain interface didn't specify this behavior). +1. **Dynamic types and arbitrary polymorphism**: Orleans doesn't enforce restrictions on the types passed in grain calls and maintains the dynamic nature of the actual data type. This means, for example, if a method in a grain interface is declared to accept , but at runtime the sender passes a , the receiver indeed gets a `SortedDictionary` (even though the "static contract"/grain interface didn't specify this behavior). 1. **Maintaining object identity**: If the same object is passed multiple times in the arguments of a grain call or is indirectly pointed to more than once from the arguments, Orleans serializes it only once. On the receiver side, Orleans restores all references correctly so that two pointers to the same object still point to the same object after deserialization. Preserving object identity is important in scenarios like the following: Imagine grain A sends a dictionary with 100 entries to grain B, and 10 keys in the dictionary point to the same object, `obj`, on A's side. Without preserving object identity, B would receive a dictionary of 100 entries with those 10 keys pointing to 10 different clones of `obj`. With object identity preserved, the dictionary on B's side looks exactly like on A's side, with those 10 keys pointing to a single object `obj`. Note that because default string hash code implementations in .NET are randomized per process, the ordering of values in dictionaries and hash sets (for example) might not be preserved. @@ -143,9 +143,9 @@ In the preceding code: - `MyForeignLibraryValueType` is a type outside your control, defined in a consuming library. - `MyForeignLibraryValueTypeSurrogate` is a surrogate type mapping to `MyForeignLibraryValueType`. -- specifies that `MyForeignLibraryValueTypeSurrogateConverter` acts as a converter to map between the two types. The class implements the interface. +- specifies that `MyForeignLibraryValueTypeSurrogateConverter` acts as a converter to map between the two types. The class implements the interface. -Orleans supports serialization of types in type hierarchies (types deriving from other types). If a foreign type might appear in a type hierarchy (e.g., as the base class for one of your own types), you must additionally implement the interface. Consider the following example: +Orleans supports serialization of types in type hierarchies (types deriving from other types). If a foreign type might appear in a type hierarchy (e.g., as the base class for one of your own types), you must additionally implement the interface. Consider the following example: :::code source="./snippets/serialization/SurrogateExamples.cs" id="surrogate_class_with_populator"::: @@ -192,7 +192,7 @@ Orleans promotes safety by default, including safety from some classes of concur ## Grain storage serializers -Orleans includes a provider-backed persistence model for grains, accessed via the property or by injecting one or more values into your grain. Before Orleans 7.0, each provider had a different mechanism for configuring serialization. In Orleans 7.0, there's now a general-purpose grain state serializer interface, , offering a consistent way to customize state serialization for each provider. Supported storage providers implement a pattern involving setting the property on the provider's options class, for example: +Orleans includes a provider-backed persistence model for grains, accessed via the property or by injecting one or more values into your grain. Before Orleans 7.0, each provider had a different mechanism for configuring serialization. In Orleans 7.0, there's now a general-purpose grain state serializer interface, , offering a consistent way to customize state serialization for each provider. Supported storage providers implement a pattern involving setting the property on the provider's options class, for example: - - @@ -231,7 +231,7 @@ Orleans includes an advanced and extensible serialization framework referred to High-fidelity representation of types is fairly uncommon for serializers, so some points warrant further explanation: -1. **Dynamic types and arbitrary polymorphism**: Orleans doesn't enforce restrictions on the types passed in grain calls and maintains the dynamic nature of the actual data type. This means, for example, if a method in a grain interface is declared to accept , but at runtime the sender passes a , the receiver indeed gets a `SortedDictionary` (even though the "static contract"/grain interface didn't specify this behavior). +1. **Dynamic types and arbitrary polymorphism**: Orleans doesn't enforce restrictions on the types passed in grain calls and maintains the dynamic nature of the actual data type. This means, for example, if a method in a grain interface is declared to accept , but at runtime the sender passes a , the receiver indeed gets a `SortedDictionary` (even though the "static contract"/grain interface didn't specify this behavior). 1. **Maintaining object identity**: If the same object is passed multiple times in the arguments of a grain call or is indirectly pointed to more than once from the arguments, Orleans serializes it only once. On the receiver side, Orleans restores all references correctly so that two pointers to the same object still point to the same object after deserialization. Preserving object identity is important in scenarios like the following: Imagine grain A sends a dictionary with 100 entries to grain B, and 10 keys in the dictionary point to the same object, `obj`, on A's side. Without preserving object identity, B would receive a dictionary of 100 entries with those 10 keys pointing to 10 different clones of `obj`. With object identity preserved, the dictionary on B's side looks exactly like on A's side, with those 10 keys pointing to a single object `obj`. Note that because default string hash code implementations in .NET are randomized per process, the ordering of values in dictionaries and hash sets (for example) might not be preserved. @@ -369,9 +369,9 @@ In the preceding code: - `MyForeignLibraryValueType` is a type outside your control, defined in a consuming library. - `MyForeignLibraryValueTypeSurrogate` is a surrogate type mapping to `MyForeignLibraryValueType`. -- specifies that `MyForeignLibraryValueTypeSurrogateConverter` acts as a converter to map between the two types. The class implements the interface. +- specifies that `MyForeignLibraryValueTypeSurrogateConverter` acts as a converter to map between the two types. The class implements the interface. -Orleans supports serialization of types in type hierarchies (types deriving from other types). If a foreign type might appear in a type hierarchy (e.g., as the base class for one of your own types), you must additionally implement the interface. Consider the following example: +Orleans supports serialization of types in type hierarchies (types deriving from other types). If a foreign type might appear in a type hierarchy (e.g., as the base class for one of your own types), you must additionally implement the interface. Consider the following example: ``` csharp // The foreign type is not sealed, allowing other types to inherit from it. @@ -493,7 +493,7 @@ Orleans promotes safety by default, including safety from some classes of concur [Id(0)] public int MyBaseInt { get; set; } } - + [GenerateSerializer] public sealed class MySubClass : MyBaseClass { @@ -508,7 +508,7 @@ Orleans promotes safety by default, including safety from some classes of concur ## Grain storage serializers -Orleans includes a provider-backed persistence model for grains, accessed via the property or by injecting one or more values into your grain. Before Orleans 7.0, each provider had a different mechanism for configuring serialization. In Orleans 7.0, there's now a general-purpose grain state serializer interface, , offering a consistent way to customize state serialization for each provider. Supported storage providers implement a pattern involving setting the property on the provider's options class, for example: +Orleans includes a provider-backed persistence model for grains, accessed via the property or by injecting one or more values into your grain. Before Orleans 7.0, each provider had a different mechanism for configuring serialization. In Orleans 7.0, there's now a general-purpose grain state serializer interface, , offering a consistent way to customize state serialization for each provider. Supported storage providers implement a pattern involving setting the property on the provider's options class, for example: - - @@ -537,7 +537,7 @@ Orleans has an advanced and extensible serialization framework. Orleans serializ Two important features of Orleans' serializer set it apart from many other third-party serialization frameworks: dynamic types/arbitrary polymorphism and object identity. -1. **Dynamic types and arbitrary polymorphism**: Orleans doesn't enforce restrictions on the types passed in grain calls and maintains the dynamic nature of the actual data type. This means, for example, if a method in a grain interface is declared to accept , but at runtime the sender passes a , the receiver indeed gets a `SortedDictionary` (even though the "static contract"/grain interface didn't specify this behavior). +1. **Dynamic types and arbitrary polymorphism**: Orleans doesn't enforce restrictions on the types passed in grain calls and maintains the dynamic nature of the actual data type. This means, for example, if a method in a grain interface is declared to accept , but at runtime the sender passes a , the receiver indeed gets a `SortedDictionary` (even though the "static contract"/grain interface didn't specify this behavior). 1. **Maintaining object identity**: If the same object is passed multiple times in the arguments of a grain call or is indirectly pointed to more than once from the arguments, Orleans serializes it only once. On the receiver side, Orleans restores all references correctly so that two pointers to the same object still point to the same object after deserialization. Preserving object identity is important in scenarios like the following: Imagine grain A sends a dictionary with 100 entries to grain B, and 10 keys in the dictionary point to the same object, `obj`, on A's side. Without preserving object identity, B would receive a dictionary of 100 entries with those 10 keys pointing to 10 different clones of `obj`. With object identity preserved, the dictionary on B's side looks exactly like on A's side, with those 10 keys pointing to a single object `obj`. diff --git a/docs/orleans/host/configuration-guide/server-configuration.md b/docs/orleans/host/configuration-guide/server-configuration.md index 2d808e6e39a19..de4d74b4b38ad 100644 --- a/docs/orleans/host/configuration-guide/server-configuration.md +++ b/docs/orleans/host/configuration-guide/server-configuration.md @@ -102,7 +102,7 @@ In this sample, we use Azure Table as the membership provider. ## Orleans clustering information -To optionally configure clustering, use as the type parameter for the method on the instance. +To optionally configure clustering, use as the type parameter for the method on the instance. ```csharp siloBuilder.Configure(options => @@ -241,6 +241,6 @@ Supplement assemblies added by the above methods using the following extension m - : Adds all referenced assemblies from the added parts. This immediately loads any transitively referenced assemblies. Assembly loading errors are ignored. - : Generates support code for the added parts and adds it to the part manager. Note that this requires installing the `Microsoft.Orleans.OrleansCodeGenerator` package and is commonly referred to as runtime code generation. -Type discovery requires the provided Application Parts to include specific attributes. Adding the build-time code generation package (`Microsoft.Orleans.CodeGenerator.MSBuild` or `Microsoft.Orleans.OrleansCodeGenerator.Build`) to each project containing Grains, Grain Interfaces, or Serializers is the recommended approach to ensure these attributes are present. Build-time code generation only supports C#. For F#, Visual Basic, and other .NET languages, you can generate code during configuration time via the method described above. Find more info regarding code generation in [the corresponding section](../../grains/code-generation.md). +Type discovery requires the provided Application Parts to include specific attributes. Adding the build-time code generation package (`Microsoft.Orleans.CodeGenerator.MSBuild` or `Microsoft.Orleans.OrleansCodeGenerator.Build`) to each project containing Grains, Grain Interfaces, or Serializers is the recommended approach to ensure these attributes are present. Build-time code generation only supports C#. For F#, Visual Basic, and other .NET languages, you can generate code during configuration time via the method described above. Find more info regarding code generation in [the corresponding section](../../grains/code-generation.md). :::zone-end diff --git a/docs/orleans/host/configuration-guide/shutting-down-orleans.md b/docs/orleans/host/configuration-guide/shutting-down-orleans.md index c31cce667a17f..635d5316b3336 100644 --- a/docs/orleans/host/configuration-guide/shutting-down-orleans.md +++ b/docs/orleans/host/configuration-guide/shutting-down-orleans.md @@ -26,9 +26,9 @@ await Host.CreateDefaultBuilder(args) .RunConsoleAsync(); ``` -The preceding code relies on the [Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting) and [Microsoft.Orleans.Server](https://www.nuget.org/packages/Microsoft.Orleans.Server) NuGet packages. The extension method extends to help manage the app's lifetime accordingly, listening for process termination signals and shutting down the silo gracefully. +The preceding code relies on the [Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting) and [Microsoft.Orleans.Server](https://www.nuget.org/packages/Microsoft.Orleans.Server) NuGet packages. The extension method extends to help manage the app's lifetime accordingly, listening for process termination signals and shutting down the silo gracefully. -Internally, the `RunConsoleAsync` method calls , which ensures the app shuts down gracefully. Orleans is hosted within the .NET Generic Host, so it shuts down when the host application does, regardless of the lifetime model used. +Internally, the `RunConsoleAsync` method calls , which ensures the app shuts down gracefully. Orleans is hosted within the .NET Generic Host, so it shuts down when the host application does, regardless of the lifetime model used. For more information on host shutdown, see [.NET Generic Host: Host shutdown](../../../core/extensions/generic-host.md#host-shutdown). diff --git a/docs/orleans/host/monitoring/index.md b/docs/orleans/host/monitoring/index.md index ee8e805c6e693..2fb73dd1b7cee 100644 --- a/docs/orleans/host/monitoring/index.md +++ b/docs/orleans/host/monitoring/index.md @@ -13,7 +13,7 @@ Observability is one of the most important aspects of a distributed system. It's ## Logging -Orleans uses [Microsoft.Extensions.Logging](https://www.nuget.org/packages/Microsoft.Extensions.Logging) for all silo and client logs. You can use any logging provider compatible with `Microsoft.Extensions.Logging`. Your app code relies on [dependency injection](../../../core/extensions/dependency-injection/overview.md) to get an instance of and uses it to log messages. For more information, see [Logging in .NET](../../../core/extensions/logging/overview.md). +Orleans uses [Microsoft.Extensions.Logging](https://www.nuget.org/packages/Microsoft.Extensions.Logging) for all silo and client logs. You can use any logging provider compatible with `Microsoft.Extensions.Logging`. Your app code relies on [dependency injection](../../../core/extensions/dependency-injection/overview.md) to get an instance of and uses it to log messages. For more information, see [Logging in .NET](../../../core/extensions/logging/overview.md). :::zone target="docs" pivot="orleans-10-0,orleans-9-0,orleans-8-0,orleans-7-0" @@ -89,8 +89,8 @@ The following table shows a collection of networking meters used to monitor the | Meter name | Type | Description | |--|--|--| -| `orleans-networking-sockets-closed` | | A count of sockets that have closed. | -| `orleans-networking-sockets-opened` | | A count of sockets that have opened. | +| `orleans-networking-sockets-closed` | | A count of sockets that have closed. | +| `orleans-networking-sockets-opened` | | A count of sockets that have opened. | #### Messaging @@ -98,26 +98,26 @@ The following table shows a collection of messaging meters used to monitor the O | Meter name | Type | Description | |--|--|--| -| `orleans-messaging-sent-messages-size` | | A histogram representing the size of messages in bytes that have been sent. | -| `orleans-messaging-received-messages-size` | | A histogram representing the size of messages in bytes that have been received. | -| `orleans-messaging-sent-header-size` | | An observable counter representing the number of header bytes sent. | -| `orleans-messaging-received-header-size` | | An observable counter representing the number of header bytes received. | -| `orleans-messaging-sent-failed` | | A count of failed sent messages. | -| `orleans-messaging-sent-dropped` | | A count of dropped sent messages. | -| `orleans-messaging-processing-dispatcher-received` | | An observable counter representing the number dispatcher received messages. | -| `orleans-messaging-processing-dispatcher-processed` | | An observable counter representing the number dispatcher processed messages. | -| `orleans-messaging-processing-dispatcher-forwarded` | | An observable counter representing the number dispatcher forwarded messages. | -| `orleans-messaging-processing-ima-received` | | An observable counter representing the number of incoming messages received. | -| `orleans-messaging-processing-ima-enqueued` | | An observable counter representing the number of incoming messages enqueued. | -| `orleans-messaging-processing-activation-data` | | An observable gauge representing all of the processing activation data. | -| `orleans-messaging-pings-sent` | | A count of pings sent. | -| `orleans-messaging-pings-received` | | A count of pings received. | -| `orleans-messaging-pings-reply-received` | | A count of ping replies received. | -| `orleans-messaging-pings-reply-missed` | | A count of ping replies missed. | -| `orleans-messaging-expired"` | | A count of messages that have expired. | -| `orleans-messaging-rejected` | | A count of messages that have been rejected. | -| `orleans-messaging-rerouted` | | A count of messages that have been rerouted. | -| `orleans-messaging-sent-local` | | An observable counter representing the number of local messages sent. | +| `orleans-messaging-sent-messages-size` | | A histogram representing the size of messages in bytes that have been sent. | +| `orleans-messaging-received-messages-size` | | A histogram representing the size of messages in bytes that have been received. | +| `orleans-messaging-sent-header-size` | | An observable counter representing the number of header bytes sent. | +| `orleans-messaging-received-header-size` | | An observable counter representing the number of header bytes received. | +| `orleans-messaging-sent-failed` | | A count of failed sent messages. | +| `orleans-messaging-sent-dropped` | | A count of dropped sent messages. | +| `orleans-messaging-processing-dispatcher-received` | | An observable counter representing the number dispatcher received messages. | +| `orleans-messaging-processing-dispatcher-processed` | | An observable counter representing the number dispatcher processed messages. | +| `orleans-messaging-processing-dispatcher-forwarded` | | An observable counter representing the number dispatcher forwarded messages. | +| `orleans-messaging-processing-ima-received` | | An observable counter representing the number of incoming messages received. | +| `orleans-messaging-processing-ima-enqueued` | | An observable counter representing the number of incoming messages enqueued. | +| `orleans-messaging-processing-activation-data` | | An observable gauge representing all of the processing activation data. | +| `orleans-messaging-pings-sent` | | A count of pings sent. | +| `orleans-messaging-pings-received` | | A count of pings received. | +| `orleans-messaging-pings-reply-received` | | A count of ping replies received. | +| `orleans-messaging-pings-reply-missed` | | A count of ping replies missed. | +| `orleans-messaging-expired"` | | A count of messages that have expired. | +| `orleans-messaging-rejected` | | A count of messages that have been rejected. | +| `orleans-messaging-rerouted` | | A count of messages that have been rerouted. | +| `orleans-messaging-sent-local` | | An observable counter representing the number of local messages sent. | #### Gateway @@ -125,10 +125,10 @@ The following table shows a collection of gateway meters used to monitor the Orl | Meter name | Type | Description | |--|--|--| -| `orleans-gateway-connected-clients` | | An up/down counter representing the number of connected clients. | -| `orleans-gateway-sent` | | A count of gateway messages sent. | -| `orleans-gateway-received` | | A count of gateway messages received. | -| `orleans-gateway-load-shedding` | | A count of gateway (load shedding) messages that have been rejected due to the gateway being overloaded. | +| `orleans-gateway-connected-clients` | | An up/down counter representing the number of connected clients. | +| `orleans-gateway-sent` | | A count of gateway messages sent. | +| `orleans-gateway-received` | | A count of gateway messages received. | +| `orleans-gateway-load-shedding` | | A count of gateway (load shedding) messages that have been rejected due to the gateway being overloaded. | #### Runtime @@ -136,9 +136,9 @@ The following table shows a collection of runtime meters used to monitor the Orl | Meter name | Type | Description | |--|--|--| -| `orleans-scheduler-long-running-turns` | | A count of long running turns within the scheduler. | -| `orleans-runtime-total-physical-memory` | | An observable counter representing the total number of memory (in MB) of the Orleans runtime. | -| `orleans-runtime-available-memory` | | An observable counter representing the available memory (in MB) for the Orleans runtime. | +| `orleans-scheduler-long-running-turns` | | A count of long running turns within the scheduler. | +| `orleans-runtime-total-physical-memory` | | An observable counter representing the total number of memory (in MB) of the Orleans runtime. | +| `orleans-runtime-available-memory` | | An observable counter representing the available memory (in MB) for the Orleans runtime. | #### Catalog @@ -146,15 +146,15 @@ The following table shows a collection of catalog meters used to monitor the Orl | Meter name | Type | Description | |--|--|--| -| `orleans-catalog-activations` | | An observable gauge representing the number of catalog activations. | -| `orleans-catalog-activation-working-set` | | An observable gauge representing the number of activations within the working set. | -| `orleans-catalog-activation-created` | | A count of created activations. | -| `orleans-catalog-activation-destroyed` | | A count of destroyed activations. | -| `orleans-catalog-activation-failed-to-activate` | | A count of activations that failed to activate. | -| `orleans-catalog-activation-collections` | | A count of idle activation collections. | -| `orleans-catalog-activation-shutdown` | | A count of shutdown activations. | -| `orleans-catalog-activation-non-existent` | | A count of non-existent activations. | -| `orleans-catalog-activation-concurrent-registration-attempts` | | A count of concurrent activation registration attempts. | +| `orleans-catalog-activations` | | An observable gauge representing the number of catalog activations. | +| `orleans-catalog-activation-working-set` | | An observable gauge representing the number of activations within the working set. | +| `orleans-catalog-activation-created` | | A count of created activations. | +| `orleans-catalog-activation-destroyed` | | A count of destroyed activations. | +| `orleans-catalog-activation-failed-to-activate` | | A count of activations that failed to activate. | +| `orleans-catalog-activation-collections` | | A count of idle activation collections. | +| `orleans-catalog-activation-shutdown` | | A count of shutdown activations. | +| `orleans-catalog-activation-non-existent` | | A count of non-existent activations. | +| `orleans-catalog-activation-concurrent-registration-attempts` | | A count of concurrent activation registration attempts. | #### Directory @@ -162,34 +162,34 @@ The following table shows a collection of directory meters used to monitor the O | Meter name | Type | Description | |--|--|--| -| `orleans-directory-lookups-local-issued` | | A count of local lookups issued. | -| `orleans-directory-lookups-local-successes` | | A count of local successful lookups. | -| `orleans-directory-lookups-full-issued` | | A count of full directory lookups issued. | -| `orleans-directory-lookups-remote-sent` | | A count of remote directory lookups sent. | -| `orleans-directory-lookups-remote-received` | | A count of remote directory lookups received. | -| `orleans-directory-lookups-local-directory-issued` | | A count of local directory lookups issued. | -| `orleans-directory-lookups-local-directory-successes` | | A count of local directory successful lookups. | -| `orleans-directory-lookups-cache-issued` | | A count cached lookups issued. | -| `orleans-directory-lookups-cache-successes` | | A count of cached successful lookups. | -| `orleans-directory-validations-cache-sent` | | A count of directory cache validations sent. | -| `orleans-directory-validations-cache-received` | | A count of directory cache validations received. | -| `orleans-directory-partition-size` | | An observable gauge representing the directory partition size. | -| `orleans-directory-cache-size` | | An observable gauge representing the directory cache size. | -| `orleans-directory-ring-size` | | An observable gauge representing the directory ring size. | -| `orleans-directory-ring-local-portion-distance` | | An observable gauge representing the ring range owned by the local directory partition. | -| `orleans-directory-ring-local-portion-percentage` | | An observable gauge representing the ring range owned by the local directory, represented as a percentage of the total range. | -| `orleans-directory-ring-local-portion-average-percentage` | | An observable gauge representing the average percentage of the directory ring range owned by each silo, giving a representation of how balanced directory ownership. | -| `orleans-directory-registrations-single-act-issued` | | A count of directory single activation registrations issued. | -| `orleans-directory-registrations-single-act-local` | | A count of directory single activation registrations handled by the local directory partition. | -| `orleans-directory-registrations-single-act-remote-sent` | | A count of directory single activation registrations sent to a remote directory partition. | -| `orleans-directory-registrations-single-act-remote-received` | | A count of directory single activation registrations received from remote hosts. | -| `orleans-directory-unregistrations-issued` | | A count of directory deregistrations issued. | -| `orleans-directory-unregistrations-local` | | A count of directory deregistrations handled by the local directory partition. | -| `orleans-directory-unregistrations-remote-sent` | | A count of directory deregistrations sent to remote directory partitions. | -| `orleans-directory-unregistrations-remote-received` | | A count of directory deregistrations received from remote hosts. | -| `orleans-directory-unregistrations-many-issued` | | A count of directory multi-activation deregistrations issued. | -| `orleans-directory-unregistrations-many-remote-sent` | | A count of directory multi-activations deregistrations sent to remote directory partitions. | -| `orleans-directory-unregistrations-many-remote-received` | | A count of directory multi-activation deregistrations received from remote hosts. | +| `orleans-directory-lookups-local-issued` | | A count of local lookups issued. | +| `orleans-directory-lookups-local-successes` | | A count of local successful lookups. | +| `orleans-directory-lookups-full-issued` | | A count of full directory lookups issued. | +| `orleans-directory-lookups-remote-sent` | | A count of remote directory lookups sent. | +| `orleans-directory-lookups-remote-received` | | A count of remote directory lookups received. | +| `orleans-directory-lookups-local-directory-issued` | | A count of local directory lookups issued. | +| `orleans-directory-lookups-local-directory-successes` | | A count of local directory successful lookups. | +| `orleans-directory-lookups-cache-issued` | | A count cached lookups issued. | +| `orleans-directory-lookups-cache-successes` | | A count of cached successful lookups. | +| `orleans-directory-validations-cache-sent` | | A count of directory cache validations sent. | +| `orleans-directory-validations-cache-received` | | A count of directory cache validations received. | +| `orleans-directory-partition-size` | | An observable gauge representing the directory partition size. | +| `orleans-directory-cache-size` | | An observable gauge representing the directory cache size. | +| `orleans-directory-ring-size` | | An observable gauge representing the directory ring size. | +| `orleans-directory-ring-local-portion-distance` | | An observable gauge representing the ring range owned by the local directory partition. | +| `orleans-directory-ring-local-portion-percentage` | | An observable gauge representing the ring range owned by the local directory, represented as a percentage of the total range. | +| `orleans-directory-ring-local-portion-average-percentage` | | An observable gauge representing the average percentage of the directory ring range owned by each silo, giving a representation of how balanced directory ownership. | +| `orleans-directory-registrations-single-act-issued` | | A count of directory single activation registrations issued. | +| `orleans-directory-registrations-single-act-local` | | A count of directory single activation registrations handled by the local directory partition. | +| `orleans-directory-registrations-single-act-remote-sent` | | A count of directory single activation registrations sent to a remote directory partition. | +| `orleans-directory-registrations-single-act-remote-received` | | A count of directory single activation registrations received from remote hosts. | +| `orleans-directory-unregistrations-issued` | | A count of directory deregistrations issued. | +| `orleans-directory-unregistrations-local` | | A count of directory deregistrations handled by the local directory partition. | +| `orleans-directory-unregistrations-remote-sent` | | A count of directory deregistrations sent to remote directory partitions. | +| `orleans-directory-unregistrations-remote-received` | | A count of directory deregistrations received from remote hosts. | +| `orleans-directory-unregistrations-many-issued` | | A count of directory multi-activation deregistrations issued. | +| `orleans-directory-unregistrations-many-remote-sent` | | A count of directory multi-activations deregistrations sent to remote directory partitions. | +| `orleans-directory-unregistrations-many-remote-received` | | A count of directory multi-activation deregistrations received from remote hosts. | #### Consistent ring @@ -197,9 +197,9 @@ The following table shows a collection of consistent ring meters used to monitor | Meter name | Type | Description | |--|--|--| -| `orleans-consistent-ring-size` | | An observable gauge representing the consistent ring size. | -| `orleans-consistent-ring-range-percentage-local` | | An observable gauge representing the consistent ring local percentage. | -| `orleans-consistent-ring-range-percentage-average` | | An observable gauge representing the consistent ring average percentage. | +| `orleans-consistent-ring-size` | | An observable gauge representing the consistent ring size. | +| `orleans-consistent-ring-range-percentage-local` | | An observable gauge representing the consistent ring local percentage. | +| `orleans-consistent-ring-range-percentage-average` | | An observable gauge representing the consistent ring average percentage. | #### Watchdog @@ -207,8 +207,8 @@ The following table shows a collection of watchdog meters used to monitor the Or | Meter name | Type | Description | |--|--|--| -| `orleans-watchdog-health-checks` | | A count of watchdog health checks. | -| `orleans-watchdog-health-checks-failed` | | A count of failed watchdog health checks. | +| `orleans-watchdog-health-checks` | | A count of watchdog health checks. | +| `orleans-watchdog-health-checks-failed` | | A count of failed watchdog health checks. | #### Client @@ -216,7 +216,7 @@ The following table shows a collection of client meters used to monitor the Orle | Meter name | Type | Description | |--|--|--| -| `orleans-client-connected-gateways` | | An observable gauge representing the number of connected gateway clients. | +| `orleans-client-connected-gateways` | | An observable gauge representing the number of connected gateway clients. | #### Miscellaneous @@ -224,8 +224,8 @@ The following table shows a collection of miscellaneous meters used to monitor v | Meter name | Type | Description | |--|--|--| -| `orleans-grains` | | A count representing the number of grains. | -| `orleans-system-targets` | | A count representing the number of system targets. | +| `orleans-grains` | | A count representing the number of grains. | +| `orleans-system-targets` | | A count representing the number of system targets. | #### App requests @@ -233,8 +233,8 @@ The following table shows a collection of app request meters used to monitor the | Meter name | Type | Description | |--|--|--| -| `orleans-app-requests-latency` | | An observable counter representing app request latency. | -| `orleans-app-requests-timedout` | | An observable counter representing app requests that have timed out. | +| `orleans-app-requests-latency` | | An observable counter representing app request latency. | +| `orleans-app-requests-timedout` | | An observable counter representing app requests that have timed out. | #### Reminders @@ -242,9 +242,9 @@ The following table shows a collection of reminder meters used to monitor the Or | Meter name | Type | Description | |--|--|--| -| `orleans-reminders-tardiness` | | A histogram representing the number of seconds a reminder is tardy. | -| `orleans-reminders-active` | | An observable gauge representing the number active reminders. | -| `orleans-reminders-ticks-delivered` | | A count representing the number of reminder ticks that have been delivered. | +| `orleans-reminders-tardiness` | | A histogram representing the number of seconds a reminder is tardy. | +| `orleans-reminders-active` | | An observable gauge representing the number active reminders. | +| `orleans-reminders-ticks-delivered` | | A count representing the number of reminder ticks that have been delivered. | #### Storage @@ -252,12 +252,12 @@ The following table shows a collection of storage meters used to monitor the Orl | Meter name | Type | Description | |--|--|--| -| `orleans-storage-read-errors` | | A count representing the number of storage read errors. | -| `orleans-storage-write-errors` | | A count representing the number of storage write errors. | -| `orleans-storage-clear-errors` | | A count representing the number of storage clear errors. | -| `orleans-storage-read-latency` | | A histogram representing the storage read latency in milliseconds. | -| `orleans-storage-write-latency` | | A histogram representing the storage write latency in milliseconds. | -| `orleans-storage-clear-latency` | | A histogram representing the storage clear latency in milliseconds. | +| `orleans-storage-read-errors` | | A count representing the number of storage read errors. | +| `orleans-storage-write-errors` | | A count representing the number of storage write errors. | +| `orleans-storage-clear-errors` | | A count representing the number of storage clear errors. | +| `orleans-storage-read-latency` | | A histogram representing the storage read latency in milliseconds. | +| `orleans-storage-write-latency` | | A histogram representing the storage write latency in milliseconds. | +| `orleans-storage-clear-latency` | | A histogram representing the storage clear latency in milliseconds. | #### Streams @@ -265,44 +265,44 @@ The following table shows a collection of stream meters used to monitor the Orle | Meter name | Type | Description | |--|--|--| -| `orleans-streams-pubsub-producers-added` | | A count of streaming pubsub producers added. | -| `orleans-streams-pubsub-producers-removed` | | A count of streaming pubsub producers removed. | -| `orleans-streams-pubsub-producers` | | A count of streaming pubsub producers. | -| `orleans-streams-pubsub-consumers-added` | | A count of streaming pubsub consumers added. | -| `orleans-streams-pubsub-consumers-removed` | | A count of streaming pubsub consumers removed. | -| `orleans-streams-pubsub-consumers` | | A count of streaming pubsub consumers. | -| `orleans-streams-persistent-stream-pulling-agents` | | An observable gauge representing the number of persistent stream pulling agents. | -| `orleans-streams-persistent-stream-messages-read` | | A count of persistent stream messages read. | -| `orleans-streams-persistent-stream-messages-sent` | | A count of persistent stream messages sent. | -| `orleans-streams-persistent-stream-pubsub-cache-size` | | An observable gauge representing the persistent stream pubsub cache size. | -| `orleans-streams-queue-initialization-failures` | | A count of steam queue initialization failures. | -| `orleans-streams-queue-initialization-duration` | | A count of steam queue initialization occurrences. | -| `orleans-streams-queue-initialization-exceptions` | | A count of steam queue initialization exceptions. | -| `orleans-streams-queue-read-failures` | | A count of steam queue read failures. | -| `orleans-streams-queue-read-duration` | | A count of steam queue read occurrences. | -| `orleans-streams-queue-read-exceptions` | | A count of steam queue read exceptions. | -| `orleans-streams-queue-shutdown-failures` | | A count of steam queue shutdown failures. | -| `orleans-streams-queue-shutdown-duration` | | A count of steam queue shutdown occurrences. | -| `orleans-streams-queue-shutdown-exceptions` | | A count of steam queue shutdown exceptions. | -| `orleans-streams-queue-messages-received` | | An observable counter representing the number of stream queue messages received. | -| `orleans-streams-queue-oldest-message-enqueue-age` | | An observable gauge representing the age of the oldest enqueued message. | -| `orleans-streams-queue-newest-message-enqueue-age` | | An observable gauge representing the age of the newest enqueued message. | -| `orleans-streams-block-pool-total-memory` | | An observable counter representing the stream block pool total memory in bytes. | -| `orleans-streams-block-pool-available-memory` | | An observable counter representing the stream block pool available memory in bytes. | -| `orleans-streams-block-pool-claimed-memory` | | An observable counter representing the stream block pool claimed memory in bytes. | -| `orleans-streams-block-pool-released-memory` | | An observable counter representing the stream block pool released memory in bytes. | -| `orleans-streams-block-pool-allocated-memory` | | An observable counter representing the stream block pool allocated memory in bytes. | -| `orleans-streams-queue-cache-size` | | An observable counter representing the stream queue cache size in bytes. | -| `orleans-streams-queue-cache-length` | | An observable counter representing the stream queue length. | -| `orleans-streams-queue-cache-messages-added` | | An observable counter representing the stream queue messages added. | -| `orleans-streams-queue-cache-messages-purged` | | An observable counter representing the stream queue messages purged. | -| `orleans-streams-queue-cache-memory-allocated` | | An observable counter representing the stream queue memory allocated. | -| `orleans-streams-queue-cache-memory-released` | | An observable counter representing the stream queue memory released. | -| `orleans-streams-queue-cache-oldest-to-newest-duration` | | An observable gauge representing the duration from the oldest to the newest stream queue cache. | -| `orleans-streams-queue-cache-oldest-age` | | An observable gauge representing the age of the oldest cached message. | -| `orleans-streams-queue-cache-pressure` | | An observable gauge representing the pressure on the stream queue cache. | -| `orleans-streams-queue-cache-under-pressure` | | An observable gauge representing whether the stream queue cache is under pressure. | -| `orleans-streams-queue-cache-pressure-contribution-count` | | An observable counter representing the stream queue cache pressure contributions. | +| `orleans-streams-pubsub-producers-added` | | A count of streaming pubsub producers added. | +| `orleans-streams-pubsub-producers-removed` | | A count of streaming pubsub producers removed. | +| `orleans-streams-pubsub-producers` | | A count of streaming pubsub producers. | +| `orleans-streams-pubsub-consumers-added` | | A count of streaming pubsub consumers added. | +| `orleans-streams-pubsub-consumers-removed` | | A count of streaming pubsub consumers removed. | +| `orleans-streams-pubsub-consumers` | | A count of streaming pubsub consumers. | +| `orleans-streams-persistent-stream-pulling-agents` | | An observable gauge representing the number of persistent stream pulling agents. | +| `orleans-streams-persistent-stream-messages-read` | | A count of persistent stream messages read. | +| `orleans-streams-persistent-stream-messages-sent` | | A count of persistent stream messages sent. | +| `orleans-streams-persistent-stream-pubsub-cache-size` | | An observable gauge representing the persistent stream pubsub cache size. | +| `orleans-streams-queue-initialization-failures` | | A count of steam queue initialization failures. | +| `orleans-streams-queue-initialization-duration` | | A count of steam queue initialization occurrences. | +| `orleans-streams-queue-initialization-exceptions` | | A count of steam queue initialization exceptions. | +| `orleans-streams-queue-read-failures` | | A count of steam queue read failures. | +| `orleans-streams-queue-read-duration` | | A count of steam queue read occurrences. | +| `orleans-streams-queue-read-exceptions` | | A count of steam queue read exceptions. | +| `orleans-streams-queue-shutdown-failures` | | A count of steam queue shutdown failures. | +| `orleans-streams-queue-shutdown-duration` | | A count of steam queue shutdown occurrences. | +| `orleans-streams-queue-shutdown-exceptions` | | A count of steam queue shutdown exceptions. | +| `orleans-streams-queue-messages-received` | | An observable counter representing the number of stream queue messages received. | +| `orleans-streams-queue-oldest-message-enqueue-age` | | An observable gauge representing the age of the oldest enqueued message. | +| `orleans-streams-queue-newest-message-enqueue-age` | | An observable gauge representing the age of the newest enqueued message. | +| `orleans-streams-block-pool-total-memory` | | An observable counter representing the stream block pool total memory in bytes. | +| `orleans-streams-block-pool-available-memory` | | An observable counter representing the stream block pool available memory in bytes. | +| `orleans-streams-block-pool-claimed-memory` | | An observable counter representing the stream block pool claimed memory in bytes. | +| `orleans-streams-block-pool-released-memory` | | An observable counter representing the stream block pool released memory in bytes. | +| `orleans-streams-block-pool-allocated-memory` | | An observable counter representing the stream block pool allocated memory in bytes. | +| `orleans-streams-queue-cache-size` | | An observable counter representing the stream queue cache size in bytes. | +| `orleans-streams-queue-cache-length` | | An observable counter representing the stream queue length. | +| `orleans-streams-queue-cache-messages-added` | | An observable counter representing the stream queue messages added. | +| `orleans-streams-queue-cache-messages-purged` | | An observable counter representing the stream queue messages purged. | +| `orleans-streams-queue-cache-memory-allocated` | | An observable counter representing the stream queue memory allocated. | +| `orleans-streams-queue-cache-memory-released` | | An observable counter representing the stream queue memory released. | +| `orleans-streams-queue-cache-oldest-to-newest-duration` | | An observable gauge representing the duration from the oldest to the newest stream queue cache. | +| `orleans-streams-queue-cache-oldest-age` | | An observable gauge representing the age of the oldest cached message. | +| `orleans-streams-queue-cache-pressure` | | An observable gauge representing the pressure on the stream queue cache. | +| `orleans-streams-queue-cache-under-pressure` | | An observable gauge representing whether the stream queue cache is under pressure. | +| `orleans-streams-queue-cache-pressure-contribution-count` | | An observable counter representing the stream queue cache pressure contributions. | #### Transactions @@ -310,10 +310,10 @@ The following table shows a collection of transaction meters used to monitor the | Meter name | Type | Description | |--|--|--| -| `orleans-transactions-started` | | An observable counter representing the number of started transactions. | -| `orleans-transactions-successful` | | An observable counter representing the number of successful transactions. | -| `orleans-transactions-failed` | | An observable counter representing the number of failed transactions. | -| `orleans-transactions-throttled` | | An observable counter representing the number of throttled transactions. | +| `orleans-transactions-started` | | An observable counter representing the number of started transactions. | +| `orleans-transactions-successful` | | An observable counter representing the number of successful transactions. | +| `orleans-transactions-failed` | | An observable counter representing the number of failed transactions. | +| `orleans-transactions-throttled` | | An observable counter representing the number of throttled transactions. | ### Export metrics @@ -331,7 +331,7 @@ builder.Services.AddOpenTelemetry() }); ``` -The `AddOtlpExporter` method ensures the OTLP exporter is added to the `builder`. Orleans uses a named `"Microsoft.Orleans"` to create instances for many Orleans-specific metrics. Use the `AddMeter` method to specify the name of the meter to subscribe to, in this case, `"Microsoft.Orleans"`. +The `AddOtlpExporter` method ensures the OTLP exporter is added to the `builder`. Orleans uses a named `"Microsoft.Orleans"` to create instances for many Orleans-specific metrics. Use the `AddMeter` method to specify the name of the meter to subscribe to, in this case, `"Microsoft.Orleans"`. You can configure the OTLP exporter endpoint and other options as needed. For example: diff --git a/docs/orleans/host/silo-lifecycle.md b/docs/orleans/host/silo-lifecycle.md index 4e727639d4bbb..950097a07399b 100644 --- a/docs/orleans/host/silo-lifecycle.md +++ b/docs/orleans/host/silo-lifecycle.md @@ -60,7 +60,7 @@ Information, Orleans.Runtime.SiloLifecycleSubject, "Lifecycle observer Orleans.S ## Silo lifecycle participation -Your application logic can participate in the silo's lifecycle by registering a participating service in the silo's service container. Register the service as an , where `T` is . +Your application logic can participate in the silo's lifecycle by registering a participating service in the silo's service container. Register the service as an , where `T` is . ```csharp public interface ISiloLifecycle : ILifecycleObservable @@ -74,7 +74,7 @@ public interface ILifecycleParticipant } ``` -When the silo starts, all participants (`ILifecycleParticipant`) in the container can participate by having their behavior called. Once all have had the opportunity to participate, the silo's observable lifecycle starts all stages in order. +When the silo starts, all participants (`ILifecycleParticipant`) in the container can participate by having their behavior called. Once all have had the opportunity to participate, the silo's observable lifecycle starts all stages in order. ### Example @@ -118,7 +118,7 @@ siloBuilder.AddStartupTask( { var logger = serviceProvider.GetRequiredService>(); logger.LogInformation("Silo is starting up..."); - + // Perform initialization logic, such as warming caches or validating configuration var config = serviceProvider.GetRequiredService(); await ValidateExternalDependenciesAsync(config, cancellationToken); diff --git a/docs/orleans/host/transport-layer-security.md b/docs/orleans/host/transport-layer-security.md index 47ed8f8c2f616..75760d86c99a8 100644 --- a/docs/orleans/host/transport-layer-security.md +++ b/docs/orleans/host/transport-layer-security.md @@ -24,7 +24,7 @@ Before configuring TLS, ensure you have: ## Configure TLS on silos -To enable TLS on an Orleans silo, use the extension method. This method provides several overloads for different certificate configuration scenarios. +To enable TLS on an Orleans silo, use the extension method. This method provides several overloads for different certificate configuration scenarios. ### Basic TLS configuration @@ -49,7 +49,7 @@ For development and testing, you might need to use self-signed certificates. The In the preceding code: - The `context.HostingEnvironment.IsDevelopment()` method checks if the application is running in a development environment. -- The method disables certificate validation in development. +- The method disables certificate validation in development. > [!WARNING] > Never use `AllowAnyRemoteCertificate()` or `allowInvalid: true` in production deployments. These settings disable important security checks and expose your application to security vulnerabilities. @@ -62,7 +62,7 @@ If you have a certificate file instead of using the certificate store, configure In the preceding code: -- The method loads a certificate from a PKCS#12 file (PFX format). +- The method loads a certificate from a PKCS#12 file (PFX format). - The certificate is passed directly to the `UseTls` method. ### Advanced TLS configuration @@ -73,9 +73,9 @@ For production deployments, you might need more control over certificate selecti In the preceding code: -- The callback dynamically selects the appropriate server certificate. -- The callback provides custom validation logic for remote certificates. -- The property enables certificate revocation checking. +- The callback dynamically selects the appropriate server certificate. +- The callback provides custom validation logic for remote certificates. +- The property enables certificate revocation checking. ## Configure TLS on clients @@ -89,8 +89,8 @@ The following example shows how to configure TLS on an Orleans client: In the preceding code: -- The extension method configures TLS for the client. -- The callback configures client-side TLS options and sets the `TargetHost` to match the server certificate name. +- The extension method configures TLS for the client. +- The callback configures client-side TLS options and sets the `TargetHost` to match the server certificate name. - When you call `UseTls` with a client certificate, the client sends that certificate during the TLS handshake so the silo can enforce mutual TLS. ### Development client configuration @@ -112,7 +112,7 @@ Follow these best practices when configuring TLS in Orleans: - **Use the latest TLS protocol**: Always prefer TLS 1.2 or TLS 1.3 for the strongest security. Avoid TLS 1.0 and TLS 1.1, which have known vulnerabilities. - **Let the OS choose the protocol version**: Don't explicitly set TLS protocol versions in production code. Instead, defer to operating system defaults to automatically select the best protocol. Only explicitly set protocol versions if you have a specific compatibility requirement with legacy systems. When you explicitly set protocol versions, your application can't automatically benefit from newer protocols added in future OS updates. - **Validate certificates**: Always validate certificate chains, expiration dates, and hostname matches in production. Never use `AllowAnyRemoteCertificate()` or disable certificate validation outside of development environments. -- **Enable certificate revocation checking**: Use to verify that certificates haven't been revoked. +- **Enable certificate revocation checking**: Use to verify that certificates haven't been revoked. - **Use strong certificates**: Ensure your X.509 certificates use strong key lengths (at least 2048 bits for RSA) and are signed by a trusted Certificate Authority (CA). - **Secure certificate storage**: Protect private keys with appropriate file permissions or by using hardware security modules (HSMs). - **Keep certificates current**: Monitor certificate expiration dates and renew certificates before they expire. @@ -125,5 +125,5 @@ For more information on .NET TLS best practices, see [TLS/SSL best practices](.. - [Client configuration](configuration-guide/client-configuration.md) - [Server configuration](configuration-guide/server-configuration.md) - -- +- - [Orleans Transport Layer Security (TLS) sample](/samples/dotnet/samples/orleans-transport-layer-security-tls/) diff --git a/docs/orleans/implementation/cluster-management.md b/docs/orleans/implementation/cluster-management.md index 47b7dbce6cb4e..b3d898f040dfa 100644 --- a/docs/orleans/implementation/cluster-management.md +++ b/docs/orleans/implementation/cluster-management.md @@ -101,7 +101,7 @@ The following official implementations of `IMembershipTable` are currently avail ### Configure Redis clustering -Configure Redis as the clustering provider using the extension method: +Configure Redis as the clustering provider using the extension method: ```csharp using StackExchange.Redis; @@ -261,7 +261,7 @@ For more information about Orleans and .NET Aspire integration, see [Orleans and ### Configure Cassandra clustering -Configure Apache Cassandra as the clustering provider using the extension method. Install the [Microsoft.Orleans.Clustering.Cassandra](https://www.nuget.org/packages/Microsoft.Orleans.Clustering.Cassandra) NuGet package: +Configure Apache Cassandra as the clustering provider using the extension method. Install the [Microsoft.Orleans.Clustering.Cassandra](https://www.nuget.org/packages/Microsoft.Orleans.Clustering.Cassandra) NuGet package: ```dotnetcli dotnet add package Microsoft.Orleans.Clustering.Cassandra @@ -329,7 +329,7 @@ Consider Cassandra for clustering when: ### Configure Azure Cosmos DB clustering -Configure Azure Cosmos DB as the clustering provider using the extension method. Install the [Microsoft.Orleans.Clustering.Cosmos](https://www.nuget.org/packages/Microsoft.Orleans.Clustering.Cosmos) NuGet package: +Configure Azure Cosmos DB as the clustering provider using the extension method. Install the [Microsoft.Orleans.Clustering.Cosmos](https://www.nuget.org/packages/Microsoft.Orleans.Clustering.Cosmos) NuGet package: ```dotnetcli dotnet add package Microsoft.Orleans.Clustering.Cosmos diff --git a/docs/orleans/implementation/orleans-lifecycle.md b/docs/orleans/implementation/orleans-lifecycle.md index b7416dda7dde2..28f8b3a8aee31 100644 --- a/docs/orleans/implementation/orleans-lifecycle.md +++ b/docs/orleans/implementation/orleans-lifecycle.md @@ -39,7 +39,7 @@ public interface ILifecycleObserver } ``` -Both and are called when the subscribed stage is reached during startup or shutdown. +Both and are called when the subscribed stage is reached during startup or shutdown. ## Utilities diff --git a/docs/orleans/implementation/scheduler.md b/docs/orleans/implementation/scheduler.md index 265b541c0ea71..d8b74214596c1 100644 --- a/docs/orleans/implementation/scheduler.md +++ b/docs/orleans/implementation/scheduler.md @@ -61,7 +61,7 @@ When `TaskScheduler.Default` is used, continuations schedule directly onto the . ### Task scheduling in Orleans -Each grain activation has its own instance responsible for enforcing the *single-threaded* execution model of grains. Internally, this is implemented via `ActivationTaskScheduler` and `WorkItemGroup`. `WorkItemGroup` keeps enqueued tasks in a (where `T` is internally a ) and implements . To execute each currently enqueued , `WorkItemGroup` schedules *itself* on the .NET . When the .NET invokes the `WorkItemGroup`'s `IThreadPoolWorkItem.Execute()` method, the `WorkItemGroup` executes the enqueued instances one by one. +Each grain activation has its own instance responsible for enforcing the *single-threaded* execution model of grains. Internally, this is implemented via `ActivationTaskScheduler` and `WorkItemGroup`. `WorkItemGroup` keeps enqueued tasks in a (where `T` is internally a ) and implements . To execute each currently enqueued , `WorkItemGroup` schedules *itself* on the .NET . When the .NET invokes the `WorkItemGroup`'s `IThreadPoolWorkItem.Execute()` method, the `WorkItemGroup` executes the enqueued instances one by one. Each grain has a scheduler that executes by scheduling itself on the .NET : diff --git a/docs/orleans/implementation/streams-implementation/index.md b/docs/orleans/implementation/streams-implementation/index.md index f8e273b56ec10..d5e436c643a73 100644 --- a/docs/orleans/implementation/streams-implementation/index.md +++ b/docs/orleans/implementation/streams-implementation/index.md @@ -59,7 +59,7 @@ The above code configures the method. The returned messages are put in the internal per-agent data structure called . Every message is inspected to find out its destination stream. The agent uses the Pub-Sub to find out the list of stream consumers that subscribed to this stream. Once the consumer list is retrieved, the agent stores it locally (in its pub-sub cache) so it does not need to consult with Pub-Sub on every message. The agent also subscribes to the pub-sub to receive notification of any new consumers that subscribe to that stream. This handshake between the agent and the pub-sub guarantees **strong streaming subscription semantics**: once the consumer has subscribed to the stream it will see all events that were generated after it has subscribed. In addition, using allows it to subscribe in the past. +Every pulling agent runs a periodic timer that pulls from the queue by invoking the method. The returned messages are put in the internal per-agent data structure called . Every message is inspected to find out its destination stream. The agent uses the Pub-Sub to find out the list of stream consumers that subscribed to this stream. Once the consumer list is retrieved, the agent stores it locally (in its pub-sub cache) so it does not need to consult with Pub-Sub on every message. The agent also subscribes to the pub-sub to receive notification of any new consumers that subscribe to that stream. This handshake between the agent and the pub-sub guarantees **strong streaming subscription semantics**: once the consumer has subscribed to the stream it will see all events that were generated after it has subscribed. In addition, using allows it to subscribe in the past. ### Queue cache diff --git a/docs/orleans/migration-guide.md b/docs/orleans/migration-guide.md index 089b977d872f2..80952606129c8 100644 --- a/docs/orleans/migration-guide.md +++ b/docs/orleans/migration-guide.md @@ -309,7 +309,7 @@ For more information, see [ImplicitUsings](../core/project-sdk/msbuild-props.md# ## Hosting -The type is replaced with the extension method on . The `IHostBuilder` type comes from the [Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting) NuGet package. This means an Orleans client can be added to an existing host without creating a separate dependency injection container. The client connects to the cluster during startup. Once completes, the client connects automatically. Services added to the `IHostBuilder` start in the order of registration. Calling before calling , for example, ensures Orleans starts before ASP.NET Core starts, allowing immediate access to the client from the ASP.NET Core application. +The type is replaced with the extension method on . The `IHostBuilder` type comes from the [Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting) NuGet package. This means an Orleans client can be added to an existing host without creating a separate dependency injection container. The client connects to the cluster during startup. Once completes, the client connects automatically. Services added to the `IHostBuilder` start in the order of registration. Calling before calling , for example, ensures Orleans starts before ASP.NET Core starts, allowing immediate access to the client from the ASP.NET Core application. To emulate the previous behavior, create a separate `HostBuilder` and configure it with an Orleans client. An `IHostBuilder` can be configured with either an Orleans client or an Orleans silo. All silos register an instance of and that the application can use, so configuring a client separately is unnecessary and unsupported. @@ -556,7 +556,7 @@ In the preceding code, OpenTelemetry is configured to monitor: - `Microsoft.Orleans.Runtime` - `Microsoft.Orleans.Application` -To propagate activity, call : +To propagate activity, call : ```csharp builder.Host.UseOrleans((_, clientBuilder) => diff --git a/docs/orleans/overview.md b/docs/orleans/overview.md index 4ffd867a4ef3a..88ce797faba44 100644 --- a/docs/orleans/overview.md +++ b/docs/orleans/overview.md @@ -158,7 +158,7 @@ Orleans is a framework for building cloud-native apps and should be considered w Orleans provides a simple persistence model ensuring state availability before processing a request and maintaining consistency. Grains can have multiple named persistent data objects. For example, one might be called "profile" for a user's profile and another "inventory" for their inventory. This state can be stored in any storage system. -While a grain runs, Orleans keeps the state in memory to serve read requests without accessing storage. When the grain updates its state, calling ensures the backing store updates for durability and consistency. +While a grain runs, Orleans keeps the state in memory to serve read requests without accessing storage. When the grain updates its state, calling ensures the backing store updates for durability and consistency. For more information, see [Grain persistence](grains/grain-persistence/index.md). diff --git a/docs/orleans/quickstarts/build-your-first-orleans-app.md b/docs/orleans/quickstarts/build-your-first-orleans-app.md index dedaf6b4b2d21..3d5aead3e3d50 100644 --- a/docs/orleans/quickstarts/build-your-first-orleans-app.md +++ b/docs/orleans/quickstarts/build-your-first-orleans-app.md @@ -134,7 +134,7 @@ Orleans grains can also use a custom interface to define their methods and prope :::code source="snippets/url-shortener/orleansurlshortener/Program.cs" id="graininterface"::: -1. Create a `UrlShortenerGrain` class using the following code. This class inherits from the class provided by Orleans and implements the `IUrlShortenerGrain` interface you created. The class also uses the interface of Orleans to manage reading and writing state values for the URLs to the configured silo storage. +1. Create a `UrlShortenerGrain` class using the following code. This class inherits from the class provided by Orleans and implements the `IUrlShortenerGrain` interface you created. The class also uses the interface of Orleans to manage reading and writing state values for the URLs to the configured silo storage. :::code source="snippets/url-shortener/orleansurlshortener/Program.cs" id="grain"::: diff --git a/docs/orleans/resources/best-practices.md b/docs/orleans/resources/best-practices.md index 3167110a746a7..ab3d9547440df 100644 --- a/docs/orleans/resources/best-practices.md +++ b/docs/orleans/resources/best-practices.md @@ -116,9 +116,9 @@ Orleans' grain state persistence APIs are designed to be easy-to-use and provide extensible storage functionality. - is extended by a .NET interface that contains fields that should be included in the grain's persisted state. -- Grains are persisted by using [IPersistentState\](../grains/grain-persistence/index.md) is extended by the grain class that adds a strongly typed property into the grain's base class. -- The initial automatically occurs before `ActiveAsync()` has been called for a grain. -- When the grain's state object's data is changed, then the grain should call . +- Grains are persisted by using [IPersistentState\](../grains/grain-persistence/index.md) is extended by the grain class that adds a strongly typed property into the grain's base class. +- The initial automatically occurs before `ActiveAsync()` has been called for a grain. +- When the grain's state object's data is changed, then the grain should call . - Typically, grains call `State.WriteStateAsync()` at the end of grain method to return the Write promise. - The Storage provider *could* try to batch Writes that may increase efficiency, but behavioral contracts and configurations are orthogonal (independent) to the storage API used by the grain. - A **timer** is an alternative method to write updates periodically. @@ -177,7 +177,7 @@ External changing data: Writing custom providers: - Storage providers are simple to write which is also a significant extension element for Orleans. -- The API API contract drives the storage API contract (`Write`, `Clear`, ). +- The API API contract drives the storage API contract (`Write`, `Clear`, ). - The storage behavior is typically configurable (Batch writing, Hard or Soft Deletions, and so on) and defined by the storage provider. ## Cluster management diff --git a/docs/orleans/streaming/broadcast-channel.md b/docs/orleans/streaming/broadcast-channel.md index f5328e623f27b..db53f7a6f6fcb 100644 --- a/docs/orleans/streaming/broadcast-channel.md +++ b/docs/orleans/streaming/broadcast-channel.md @@ -31,7 +31,7 @@ The broadcast channel decouples the producer and consumer of the stock price upd ## Define a consumer grain -To consume broadcast channel messages, your grain needs to implement the interface. This interface enables implicit subscriptions, meaning grains are automatically subscribed to the broadcast channel when they're activated. Your implementation uses the method to attach to the broadcast channel. The `Attach` method takes a generic-type parameter for the message type you're going to receive. +To consume broadcast channel messages, your grain needs to implement the interface. This interface enables implicit subscriptions, meaning grains are automatically subscribed to the broadcast channel when they're activated. Your implementation uses the method to attach to the broadcast channel. The `Attach` method takes a generic-type parameter for the message type you're going to receive. First, define the grain interface that consumers use to interact with the grain: @@ -54,7 +54,7 @@ This example grain contains the latest stock prices as published on the broadcas ## Publish messages to a broadcast channel -To publish messages to the broadcast channel, you need to get a reference to the broadcast channel. To do this, get the from the . With the provider, call the method to get an instance of . The writer is used to publish messages to the broadcast channel. +To publish messages to the broadcast channel, you need to get a reference to the broadcast channel. To do this, get the from the . With the provider, call the method to get an instance of . The writer is used to publish messages to the broadcast channel. First, define a constant for the channel name to ensure the producer and consumers use the same channel identifier: @@ -68,7 +68,7 @@ In the preceding code: - The `StockWorker` class is a background service that publishes messages to the broadcast channel. - The constructor takes a `StockClient` and as parameters. -- From the cluster client instance, the method is used to get the broadcast channel provider for the `LiveStockTicker` channel. +- From the cluster client instance, the method is used to get the broadcast channel provider for the `LiveStockTicker` channel. - The `ChannelId.Create` method creates a channel identifier using: - The channel name (`ChannelNames.LiveStockTicker`)—this must match the name used when configuring the broadcast channel in the silo setup. - `Guid.Empty` as the namespace—for broadcast channels, all subscribers receive all messages, so the namespace is typically set to `Guid.Empty` to indicate a single shared broadcast. diff --git a/docs/orleans/streaming/stream-providers.md b/docs/orleans/streaming/stream-providers.md index de9af9792609f..9399f6abc3937 100644 --- a/docs/orleans/streaming/stream-providers.md +++ b/docs/orleans/streaming/stream-providers.md @@ -148,7 +148,7 @@ For comprehensive documentation on Orleans and .NET Aspire integration, see [Orl ## Simple message stream provider -The simple message stream provider, also known as the SMS provider, delivers events over TCP using regular Orleans grain messaging. Since SMS events are delivered over unreliable TCP links, SMS does _not_ guarantee reliable event delivery and doesn't automatically resend failed messages for SMS streams. By default, the producer's call to returns a representing the stream consumer's processing status. This tells the producer whether the consumer successfully received and processed the event. If this task fails, the producer can decide to send the same event again, achieving reliability at the application level. Although stream message delivery is best-effort, SMS streams themselves are reliable. That is, the subscriber-to-producer binding performed by Pub-Sub is fully reliable. +The simple message stream provider, also known as the SMS provider, delivers events over TCP using regular Orleans grain messaging. Since SMS events are delivered over unreliable TCP links, SMS does _not_ guarantee reliable event delivery and doesn't automatically resend failed messages for SMS streams. By default, the producer's call to returns a representing the stream consumer's processing status. This tells the producer whether the consumer successfully received and processed the event. If this task fails, the producer can decide to send the same event again, achieving reliability at the application level. Although stream message delivery is best-effort, SMS streams themselves are reliable. That is, the subscriber-to-producer binding performed by Pub-Sub is fully reliable. :::zone-end diff --git a/docs/orleans/streaming/streams-programming-apis.md b/docs/orleans/streaming/streams-programming-apis.md index 7aa9720504e8d..0629f1d98f3f2 100644 --- a/docs/orleans/streaming/streams-programming-apis.md +++ b/docs/orleans/streaming/streams-programming-apis.md @@ -29,13 +29,13 @@ IAsyncStream stream = streamProvider.GetStream(Guid, "MyStreamNamespace"); :::zone-end -You can get a reference to the stream provider either by calling the method when inside a grain or by calling the method on the client instance. +You can get a reference to the stream provider either by calling the method when inside a grain or by calling the method on the client instance. - is a logical, strongly typed handle to a virtual stream, similar in spirit to an Orleans Grain Reference. Calls to and `GetStream` are purely local. The arguments to `GetStream` are a GUID and an additional string called a stream namespace (which can be null). Together, the GUID and the namespace string comprise the stream identity (similar to the arguments for ). This combination provides extra flexibility in determining stream identities. Just like grain 7 might exist within the `PlayerGrain` type and a different grain 7 might exist within the `ChatRoomGrain` type, Stream 123 can exist within the `PlayerEventsStream` namespace, and a different stream 123 can exist within the `ChatRoomMessagesStream` namespace. + is a logical, strongly typed handle to a virtual stream, similar in spirit to an Orleans Grain Reference. Calls to and `GetStream` are purely local. The arguments to `GetStream` are a GUID and an additional string called a stream namespace (which can be null). Together, the GUID and the namespace string comprise the stream identity (similar to the arguments for ). This combination provides extra flexibility in determining stream identities. Just like grain 7 might exist within the `PlayerGrain` type and a different grain 7 might exist within the `ChatRoomGrain` type, Stream 123 can exist within the `PlayerEventsStream` namespace, and a different stream 123 can exist within the `ChatRoomMessagesStream` namespace. ### Producing and consuming - implements both the and interfaces. This allows your application to use the stream either to produce new events using or to subscribe to and consume events using `IAsyncObservable`. + implements both the and interfaces. This allows your application to use the stream either to produce new events using or to subscribe to and consume events using `IAsyncObservable`. ```csharp public interface IAsyncObserver @@ -63,7 +63,7 @@ To subscribe to a stream, your application calls: StreamSubscriptionHandle subscriptionHandle = await stream.SubscribeAsync(IAsyncObserver) ``` -The argument to can be either an object implementing the interface or a combination of lambda functions to process incoming events. More options for are available via the class. returns a , an opaque handle used to unsubscribe from the stream (similar to an asynchronous version of ). +The argument to can be either an object implementing the interface or a combination of lambda functions to process incoming events. More options for are available via the class. returns a , an opaque handle used to unsubscribe from the stream (similar to an asynchronous version of ). ```csharp await subscriptionHandle.UnsubscribeAsync() @@ -75,7 +75,7 @@ It's important to note that the subscription is for a grain, not for activation. An Orleans stream can have multiple producers and multiple consumers. A message published by a producer is delivered to all consumers subscribed to the stream before the message was published. -Additionally, a consumer can subscribe to the same stream multiple times. Each time it subscribes, it gets back a unique . If a grain (or client) subscribes X times to the same stream, it receives the same event X times, once for each subscription. The consumer can also unsubscribe from an individual subscription. You can find all current subscriptions by calling: +Additionally, a consumer can subscribe to the same stream multiple times. Each time it subscribes, it gets back a unique . If a grain (or client) subscribes X times to the same stream, it receives the same event X times, once for each subscription. The consumer can also unsubscribe from an individual subscription. You can find all current subscriptions by calling: ```csharp IList> allMyHandles = @@ -86,16 +86,16 @@ IList> allMyHandles = If the producer of a stream dies (or its grain is deactivated), it doesn't need to do anything. The next time this grain wants to produce more events, it can get the stream handle again and produce new events as usual. -Consumer logic is slightly more involved. As mentioned before, once a consumer grain subscribes to a stream, this subscription is valid until the grain explicitly unsubscribes. If the consumer of the stream dies (or its grain is deactivated) and a new event is generated on the stream, the consumer grain automatically reactivates (just like any regular Orleans grain automatically activates when a message is sent to it). The only thing the grain code needs to do now is provide an to process the data. The consumer needs to re-attach processing logic as part of the method. To do that, it can call: +Consumer logic is slightly more involved. As mentioned before, once a consumer grain subscribes to a stream, this subscription is valid until the grain explicitly unsubscribes. If the consumer of the stream dies (or its grain is deactivated) and a new event is generated on the stream, the consumer grain automatically reactivates (just like any regular Orleans grain automatically activates when a message is sent to it). The only thing the grain code needs to do now is provide an to process the data. The consumer needs to re-attach processing logic as part of the method. To do that, it can call: ```csharp StreamSubscriptionHandle newHandle = await subscriptionHandle.ResumeAsync(IAsyncObserver); ``` -The consumer uses the previous handle obtained during the initial subscription to "resume processing". Note that merely updates an existing subscription with the new instance of logic and doesn't change the fact that this consumer is already subscribed to this stream. +The consumer uses the previous handle obtained during the initial subscription to "resume processing". Note that merely updates an existing subscription with the new instance of logic and doesn't change the fact that this consumer is already subscribed to this stream. -How does the consumer get the old `subscriptionHandle`? There are two options. The consumer might have persisted the handle returned from the original operation and can use it now. Alternatively, if the consumer doesn't have the handle, it can ask the for all its active subscription handles by calling: +How does the consumer get the old `subscriptionHandle`? There are two options. The consumer might have persisted the handle returned from the original operation and can use it now. Alternatively, if the consumer doesn't have the handle, it can ask the for all its active subscription handles by calling: ```csharp IList> allMyHandles = @@ -105,7 +105,7 @@ IList> allMyHandles = The consumer can then resume all of them or unsubscribe from some if desired. > [!TIP] -> If the consumer grain implements the interface directly (`public class MyGrain : Grain, IAsyncObserver`), it shouldn't theoretically need to re-attach the and thus wouldn't need to call `ResumeAsync`. The streaming runtime should automatically figure out that the grain already implements and invoke those methods. However, the streaming runtime currently doesn't support this, and the grain code still needs to explicitly call `ResumeAsync`, even if the grain implements directly. +> If the consumer grain implements the interface directly (`public class MyGrain : Grain, IAsyncObserver`), it shouldn't theoretically need to re-attach the and thus wouldn't need to call `ResumeAsync`. The streaming runtime should automatically figure out that the grain already implements and invoke those methods. However, the streaming runtime currently doesn't support this, and the grain code still needs to explicitly call `ResumeAsync`, even if the grain implements directly. ### Explicit and implicit subscriptions @@ -115,7 +115,7 @@ Additionally, Orleans streams support *implicit subscriptions*. In this model, t The grain implementation `MyGrainType` can declare an attribute `[ImplicitStreamSubscription("MyStreamNamespace")]`. This tells the streaming runtime that when an event is generated on a stream with identity GUID XXX and namespace `"MyStreamNamespace"`, it should be delivered to the grain with identity XXX of type `MyGrainType`. That is, the runtime maps stream `` to consumer grain ``. -The presence of `ImplicitStreamSubscription` causes the streaming runtime to automatically subscribe this grain to the stream and deliver stream events to it. However, the grain code still needs to tell the runtime how it wants events processed. Essentially, it needs to attach the . Therefore, when the grain activates, the grain code inside needs to call: +The presence of `ImplicitStreamSubscription` causes the streaming runtime to automatically subscribe this grain to the stream and deliver stream events to it. However, the grain code still needs to tell the runtime how it wants events processed. Essentially, it needs to attach the . Therefore, when the grain activates, the grain code inside needs to call: :::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" @@ -143,9 +143,9 @@ Below are guidelines for writing subscription logic for various cases: explicit **Implicit subscriptions:** -For implicit subscriptions, the grain still needs to subscribe to attach the processing logic. You can do this in the consumer grain by implementing the `IStreamSubscriptionObserver` and interfaces, allowing the grain to activate separately from subscribing. To subscribe to the stream, the grain creates a handle and calls `await handle.ResumeAsync(this)` in its `OnSubscribed(...)` method. +For implicit subscriptions, the grain still needs to subscribe to attach the processing logic. You can do this in the consumer grain by implementing the `IStreamSubscriptionObserver` and interfaces, allowing the grain to activate separately from subscribing. To subscribe to the stream, the grain creates a handle and calls `await handle.ResumeAsync(this)` in its `OnSubscribed(...)` method. -To process messages, implement the `IAsyncObserver.OnNextAsync(...)` method to receive stream data and a sequence token. Alternatively, the `ResumeAsync` method can take a set of delegates representing the methods of the interface: `onNextAsync`, `onErrorAsync`, and `onCompletedAsync`. +To process messages, implement the `IAsyncObserver.OnNextAsync(...)` method to receive stream data and a sequence token. Alternatively, the `ResumeAsync` method can take a set of delegates representing the methods of the interface: `onNextAsync`, `onErrorAsync`, and `onCompletedAsync`. :::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" @@ -173,7 +173,7 @@ public override async Task OnActivateAsync() **Explicit subscriptions:** -For explicit subscriptions, a grain must call to subscribe to the stream. This creates a subscription and attaches the processing logic. The explicit subscription exists until the grain unsubscribes. If a grain deactivates and reactivates, it's still explicitly subscribed, but no processing logic is attached. In this case, the grain needs to re-attach the processing logic. To do this, in its , the grain first needs to find out its subscriptions by calling . The grain must execute `ResumeAsync` on each handle it wishes to continue processing or `UnsubscribeAsync` on any handles it's done with. The grain can also optionally specify the as an argument to the `ResumeAsync` calls, causing this explicit subscription to start consuming from that token. +For explicit subscriptions, a grain must call to subscribe to the stream. This creates a subscription and attaches the processing logic. The explicit subscription exists until the grain unsubscribes. If a grain deactivates and reactivates, it's still explicitly subscribed, but no processing logic is attached. In this case, the grain needs to re-attach the processing logic. To do this, in its , the grain first needs to find out its subscriptions by calling . The grain must execute `ResumeAsync` on each handle it wishes to continue processing or `UnsubscribeAsync` on any handles it's done with. The grain can also optionally specify the as an argument to the `ResumeAsync` calls, causing this explicit subscription to start consuming from that token. :::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" @@ -204,17 +204,17 @@ public async override Task OnActivateAsync() The order of event delivery between an individual producer and consumer depends on the stream provider. -With SMS, the producer explicitly controls the order of events seen by the consumer by controlling how they publish them. By default (if the option for the SMS provider is `false`) and if the producer awaits every call, events arrive in FIFO order. In SMS, the producer decides how to handle delivery failures indicated by a broken returned by the call. +With SMS, the producer explicitly controls the order of events seen by the consumer by controlling how they publish them. By default (if the option for the SMS provider is `false`) and if the producer awaits every call, events arrive in FIFO order. In SMS, the producer decides how to handle delivery failures indicated by a broken returned by the call. Azure Queue streams don't guarantee FIFO order because the underlying Azure Queues don't guarantee order in failure cases (though they do guarantee FIFO order in failure-free executions). When a producer produces an event into an Azure Queue, if the queue operation fails, the producer must attempt another queue and later deal with potential duplicate messages. On the delivery side, the Orleans Streaming runtime dequeues the event and attempts to deliver it for processing to consumers. The runtime deletes the event from the queue only upon successful processing. If delivery or processing fails, the event isn't deleted from the queue and automatically reappears later. The Streaming runtime tries to deliver it again, potentially breaking FIFO order. This behavior matches the normal semantics of Azure Queues. -**Application-defined order**: To handle the ordering issues above, your application can optionally specify its ordering. Achieve this using a , an opaque object used to order events. A producer can pass an optional to the call. This passes to the consumer and is delivered with the event. This way, your application can reason about and reconstruct its order independently of the streaming runtime. +**Application-defined order**: To handle the ordering issues above, your application can optionally specify its ordering. Achieve this using a , an opaque object used to order events. A producer can pass an optional to the call. This passes to the consumer and is delivered with the event. This way, your application can reason about and reconstruct its order independently of the streaming runtime. ### Rewindable streams Some streams only allow subscribing starting from the latest point in time, while others allow "going back in time." This capability depends on the underlying queuing technology and the specific stream provider. For example, Azure Queues only allow consuming the latest enqueued events, while Event Hubs allows replaying events from an arbitrary point in time (up to some expiration time). Streams supporting going back in time are called *rewindable streams*. -The consumer of a rewindable stream can pass a to the call. The runtime delivers events starting from that . A null token means the consumer wants to receive events starting from the latest. +The consumer of a rewindable stream can pass a to the call. The runtime delivers events starting from that . A null token means the consumer wants to receive events starting from the latest. The ability to rewind a stream is very useful in recovery scenarios. For example, consider a grain that subscribes to a stream and periodically checkpoints its state along with the latest sequence token. When recovering from a failure, the grain can re-subscribe to the same stream from the latest checkpointed sequence token, recovering without losing any events generated since the last checkpoint. diff --git a/docs/orleans/streaming/streams-quick-start.md b/docs/orleans/streaming/streams-quick-start.md index e260381059207..e542bccdd929d 100644 --- a/docs/orleans/streaming/streams-quick-start.md +++ b/docs/orleans/streaming/streams-quick-start.md @@ -19,14 +19,14 @@ In this guide, you use a memory-based stream that uses grain messaging to send s Orleans streaming requires the [Microsoft.Orleans.Streaming](https://www.nuget.org/packages/Microsoft.Orleans.Streaming) NuGet package. This package provides the streaming functionality for both the client and server, including the `AddMemoryStreams` extension method used in this guide. -On the silo, where `silo` is an , call : +On the silo, where `silo` is an , call : ```csharp silo.AddMemoryStreams("StreamProvider") .AddMemoryGrainStorage("PubSubStore"); ``` -On the cluster client, where `client` is an , call . +On the cluster client, where `client` is an , call . ```csharp client.AddMemoryStreams("StreamProvider"); @@ -38,11 +38,11 @@ client.AddMemoryStreams("StreamProvider"); In this guide, use a simple message-based stream that uses grain messaging to send stream data to subscribers. Use the in-memory storage provider to store lists of subscriptions; this isn't a wise choice for real production applications. -On the silo, where `hostBuilder` is an , call : +On the silo, where `hostBuilder` is an , call : :::code language="csharp" source="snippets-v3/streams-quickstart/StreamConfiguration.cs" id="silo_sms_provider"::: -On the cluster client, where `clientBuilder` is an , call . +On the cluster client, where `clientBuilder` is an , call . :::code language="csharp" source="snippets-v3/streams-quickstart/StreamConfiguration.cs" id="client_sms_provider"::: @@ -83,7 +83,7 @@ It's relatively easy to produce events for streams. First, get access to the str As you can see, the stream has a GUID and a namespace. This makes it easy to identify unique streams. For example, the namespace for a chat room could be "Rooms", and the GUID could be the owning `RoomGrain`'s GUID. -Here, use the GUID of a known chat room. Using the method of the stream, push data to it. Let's do this inside a timer using random numbers. You could use any other data type for the stream as well. +Here, use the GUID of a known chat room. Using the method of the stream, push data to it. Let's do this inside a timer using random numbers. You could use any other data type for the stream as well. ```csharp RegisterTimer(_ => @@ -108,7 +108,7 @@ public class ReceiverGrain : Grain, IRandomReceiver Whenever data is pushed to streams in the `RANDOMDATA` namespace (as in the timer example), a grain of type `ReceiverGrain` with the same as the stream receives the message. Even if no activations of the grain currently exist, the runtime automatically creates a new one and sends the message to it. -For this to work, complete the subscription process by setting the method for receiving data. To do so, the `ReceiverGrain` should call something like this in its : +For this to work, complete the subscription process by setting the method for receiving data. To do so, the `ReceiverGrain` should call something like this in its : :::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" diff --git a/docs/orleans/streaming/streams-why.md b/docs/orleans/streaming/streams-why.md index 21b677452af64..ee229edfd2d37 100644 --- a/docs/orleans/streaming/streams-why.md +++ b/docs/orleans/streaming/streams-why.md @@ -44,7 +44,7 @@ The system should allow for dynamically evolving topologies. Existing systems me Stream.GroupBy(x=> x.key).Extract(x=>x.field).Select(x=>x+2).AverageWindow(x, 5sec).Where(x=>x > 0.8) * `` -Change the threshold condition in the filter, add a statement, or add another branch in the data-flow graph and produce a new output stream. In existing systems, this isn't possible without tearing down the entire topology and restarting the data flow from scratch. Practically, these systems checkpoint the existing computation and can restart from the latest checkpoint. Still, such a restart is disruptive and costly for an online service producing results in real-time. Such a restart becomes especially impractical when dealing with a large number of such expressions executed with similar but different parameters (per-user, per-device, etc.) that continually change. +Change the threshold condition in the filter, add a statement, or add another branch in the data-flow graph and produce a new output stream. In existing systems, this isn't possible without tearing down the entire topology and restarting the data flow from scratch. Practically, these systems checkpoint the existing computation and can restart from the latest checkpoint. Still, such a restart is disruptive and costly for an online service producing results in real-time. Such a restart becomes especially impractical when dealing with a large number of such expressions executed with similar but different parameters (per-user, per-device, etc.) that continually change. The system should allow evolving the stream processing graph at runtime by adding new links or nodes to the computation graph or changing the processing logic within the computation nodes. diff --git a/docs/orleans/tutorials-and-samples/custom-grain-storage.md b/docs/orleans/tutorials-and-samples/custom-grain-storage.md index 03a1a7424c36c..62e2fe7246f99 100644 --- a/docs/orleans/tutorials-and-samples/custom-grain-storage.md +++ b/docs/orleans/tutorials-and-samples/custom-grain-storage.md @@ -74,11 +74,11 @@ public sealed class FileGrainStorage : IGrainStorage, ILifecycleParticipant interface, accepting a generic type parameter for the underlying state type. The methods are: -- : Reads the state of a grain. -- : Writes the state of a grain. -- : Clears the state of a grain. +- : Reads the state of a grain. +- : Writes the state of a grain. +- : Clears the state of a grain. -The method subscribes to the silo's lifecycle. +The method subscribes to the silo's lifecycle. Before starting the implementation, create an options class containing the root directory where grain state files are persisted. Create an options file named `FileGrainStorageOptions` containing the following: @@ -92,7 +92,7 @@ With the options class created, explore the constructor parameters of the `FileG ## Initialize the storage -To initialize the storage, subscribe to the stage with an `onStart` function. Consider the following implementation: +To initialize the storage, subscribe to the stage with an `onStart` function. Consider the following implementation: :::code source="snippets/custom-grain-storage/FileGrainStorage.cs" id="participate"::: @@ -126,7 +126,7 @@ Clearing the state involves deleting the file if it exists. :::code source="snippets/custom-grain-storage/FileGrainStorage.cs" id="clearstateasync"::: -For the same reason as , check for inconsistency. Before deleting the file and resetting the `ETag`, check if the current `ETag` matches the last write time UTC. +For the same reason as , check for inconsistency. Before deleting the file and resetting the `ETag`, check if the current `ETag` matches the last write time UTC. ## Put it all together @@ -134,7 +134,7 @@ Next, create a factory that allows scoping the options to the provider name whil :::code source="snippets/custom-grain-storage/FileGrainStorageFactory.cs"::: -Lastly, to register the grain storage, create an extension on . This extension registers the grain storage as a keyed singleton using , the standard .NET 8+ keyed DI API. +Lastly, to register the grain storage, create an extension on . This extension registers the grain storage as a keyed singleton using , the standard .NET 8+ keyed DI API. :::code source="snippets/custom-grain-storage/FileSiloBuilderExtensions.cs"::: @@ -209,7 +209,7 @@ Clearing the state involves deleting the file if it exists. :::code language="csharp" source="snippets-v3/custom-storage/FileGrainStorage.cs" id="clearstateasync"::: -For the same reason as , check for inconsistency. Before deleting the file and resetting the ETag, check if the current ETag matches the last write time UTC. +For the same reason as , check for inconsistency. Before deleting the file and resetting the ETag, check if the current ETag matches the last write time UTC. ## Put it all together diff --git a/docs/orleans/tutorials-and-samples/index.md b/docs/orleans/tutorials-and-samples/index.md index 0b45d1a4e787f..e13c35ca82633 100644 --- a/docs/orleans/tutorials-and-samples/index.md +++ b/docs/orleans/tutorials-and-samples/index.md @@ -59,7 +59,7 @@ A social network pub/sub system where users send short text messages to each oth ### Chirper demonstrates - How to build a simplified social media / social network application using Orleans -- How to store state within a grain using grain persistence () +- How to store state within a grain using grain persistence () - Grains implementing multiple grain interfaces - Reentrant grains, allowing multiple grain calls to execute concurrently in a single-threaded, interleaving fashion - Using a *grain observer* () to receive push notifications from grains diff --git a/docs/orleans/tutorials-and-samples/tutorial-1.md b/docs/orleans/tutorials-and-samples/tutorial-1.md index a00588837b8ac..6502f3df629d7 100644 --- a/docs/orleans/tutorials-and-samples/tutorial-1.md +++ b/docs/orleans/tutorials-and-samples/tutorial-1.md @@ -103,7 +103,7 @@ Add the following code to _Program.cs_ of the **Silo** project: The preceding code: -- Configures the to use Orleans with the method. +- Configures the to use Orleans with the method. - Specifies using the localhost clustering provider with the method. - Runs the `host` and waits for the process to terminate by listening for Ctrl+C or `SIGTERM`. diff --git a/docs/standard/analyzers/platform-compat-analyzer.md b/docs/standard/analyzers/platform-compat-analyzer.md index 6f97a609f7104..1147eda92d1cd 100644 --- a/docs/standard/analyzers/platform-compat-analyzer.md +++ b/docs/standard/analyzers/platform-compat-analyzer.md @@ -14,7 +14,7 @@ But using platform-specific APIs on a component means the code no longer works a The complementary APIs include: - to annotate APIs as being platform-specific and to annotate APIs as being unsupported on a particular OS. These attributes can optionally include the version number, and have already been applied to some platform-specific APIs in the core .NET libraries. -- `Is()` and `IsVersionAtLeast(int major, int minor = 0, int build = 0, int revision = 0)` static methods in the class for safely calling platform-specific APIs. For example, can be used to guard a call to a Windows-specific API, and () can be used to guard a versioned Windows-specific API call. See these [examples](#guard-platform-specific-apis-with-guard-methods) of how these methods can be used as guards of platform-specific API references. +- `Is()` and `IsVersionAtLeast(int major, int minor = 0, int build = 0, int revision = 0)` static methods in the class for safely calling platform-specific APIs. For example, can be used to guard a call to a Windows-specific API, and () can be used to guard a versioned Windows-specific API call. See these [examples](#guard-platform-specific-apis-with-guard-methods) of how these methods can be used as guards of platform-specific API references. ## Prerequisites @@ -64,7 +64,7 @@ The analyzer does not check target framework moniker (TFM) target platforms from For example, the method is attributed `[SupportedOSPlatformGuard("MacCatalyst")]`. Therefore, the following statements apply: -- The and methods check not only the `iOS` platform, but also the `MacCatalyst` platform. +- The and methods check not only the `iOS` platform, but also the `MacCatalyst` platform. - `[SupportedOSPlatform("iOS")]` implies that the API is supported on `iOS` and also on its superset platform, `MacCatalyst`. You can use the `[UnsupportedOSPlatform("MacCatalyst")]` attribute to exclude this implied support. - `[UnsupportedOSPlatform("iOS")` implies that the API is not supported on `iOS` and `MacCatalyst`. You can use the `[SupportedOSPlatform("MacCatalyst")]` attribute to exclude this implied lack of support. @@ -281,7 +281,7 @@ The guard method's platform name should match with the calling platform-dependen } ``` -- If you need to guard code that targets `netstandard` or `netcoreapp` where new APIs are not available, the API can be used and will be respected by the analyzer. But it's not as optimized as the new APIs added in . If the platform is not supported in the struct, you can call and pass in the platform name, which the analyzer also respects. +- If you need to guard code that targets `netstandard` or `netcoreapp` where new APIs are not available, the API can be used and will be respected by the analyzer. But it's not as optimized as the new APIs added in . If the platform is not supported in the struct, you can call and pass in the platform name, which the analyzer also respects. ```csharp public void CallingSupportedOnlyApis() @@ -300,7 +300,7 @@ The guard method's platform name should match with the calling platform-dependen #### Annotate APIs with platform guard attributes and use it as a custom guard -As shown previously, the analyzer recognizes the platform-guard static methods in the type, such as `OperatingSystem.IsWindows`, and also . However, you might want to cache the guard result in a field and reuse it, or use custom guard methods for checking a platform. The analyzer needs to recognize such APIs as a custom guard and should not warn for the APIs guarded by them. The guard attributes were introduced in .NET 6 to support this scenario: +As shown previously, the analyzer recognizes the platform-guard static methods in the type, such as `OperatingSystem.IsWindows`, and also . However, you might want to cache the guard result in a field and reuse it, or use custom guard methods for checking a platform. The analyzer needs to recognize such APIs as a custom guard and should not warn for the APIs guarded by them. The guard attributes were introduced in .NET 6 to support this scenario: - `SupportedOSPlatformGuardAttribute` annotates APIs that can be used as a guard for APIs annotated with . - `UnsupportedOSPlatformGuardAttribute` annotates APIs that can be used as a guard for APIs annotated with . diff --git a/docs/standard/assembly/create-use-strong-named.md b/docs/standard/assembly/create-use-strong-named.md index b7edfb08b4ff5..fee092a5aace0 100644 --- a/docs/standard/assembly/create-use-strong-named.md +++ b/docs/standard/assembly/create-use-strong-named.md @@ -55,7 +55,7 @@ The bypass feature applies to any assembly that is signed with a strong name and - Loaded into a fully trusted . -- Loaded from a location under the property of that . +- Loaded from a location under the property of that . - Not delay-signed. diff --git a/docs/standard/assembly/disable-strong-name-bypass-feature.md b/docs/standard/assembly/disable-strong-name-bypass-feature.md index 82029c24aedcb..e499ca4268aa9 100644 --- a/docs/standard/assembly/disable-strong-name-bypass-feature.md +++ b/docs/standard/assembly/disable-strong-name-bypass-feature.md @@ -11,7 +11,7 @@ ms.topic: how-to Starting with the .NET Framework version 3.5 Service Pack 1 (SP1), strong-name signatures are not validated when an assembly is loaded into a full-trust object, such as the default for the `MyComputer` zone. This is referred to as the strong-name bypass feature. In a full-trust environment, demands for always succeed for signed, full-trust assemblies regardless of their signature. The only restriction is that the assembly must be fully trusted because its zone is fully trusted. Because the strong name is not a determining factor under these conditions, there is no reason for it to be validated. Bypassing the validation of strong-name signatures provides significant performance improvements. - The bypass feature applies to any full-trust assembly that is not delay-signed and that is loaded into any full-trust from the directory specified by its property. + The bypass feature applies to any full-trust assembly that is not delay-signed and that is loaded into any full-trust from the directory specified by its property. You can override the bypass feature for all applications on a computer by setting a registry key value. You can override the setting for a single application by using an application configuration file. You cannot reinstate the bypass feature for a single application if it has been disabled by the registry key. diff --git a/docs/standard/assembly/embed-types-visual-studio.md b/docs/standard/assembly/embed-types-visual-studio.md index 69f29c7158973..c80ac612e99f4 100644 --- a/docs/standard/assembly/embed-types-visual-studio.md +++ b/docs/standard/assembly/embed-types-visual-studio.md @@ -40,7 +40,7 @@ Because the primary function of type embedding is to support COM interop assembl - Only attributes specific to COM interop are embedded. Other attributes are ignored. - If a type uses generic parameters, and the type of the generic parameter is an embedded type, that type cannot be used across an assembly boundary. Examples of crossing an assembly boundary include calling a method from another assembly or deriving a type from a type defined in another assembly. - Constants are not embedded. -- The class does not support an embedded type as a key. You can implement your own dictionary type to support an embedded type as a key. +- The class does not support an embedded type as a key. You can implement your own dictionary type to support an embedded type as a key. ## Create an interface diff --git a/docs/standard/assembly/find-fully-qualified-name.md b/docs/standard/assembly/find-fully-qualified-name.md index 4b1ac4b558f1b..733b3f44fc454 100644 --- a/docs/standard/assembly/find-fully-qualified-name.md +++ b/docs/standard/assembly/find-fully-qualified-name.md @@ -19,9 +19,9 @@ For .NET Core assemblies, and for .NET Framework assemblies that aren't in the g - You can use code to output the information to the console or to a variable, or you can use the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) to examine the assembly's metadata, which contains the fully qualified name. -- If the assembly is already loaded by the application, you can retrieve the value of the property to get the fully qualified name. You can use the property of a defined in that assembly to retrieve a reference to the object. The example provides an illustration. +- If the assembly is already loaded by the application, you can retrieve the value of the property to get the fully qualified name. You can use the property of a defined in that assembly to retrieve a reference to the object. The example provides an illustration. -- If you know the assembly's file system path, you can call the `static` (C#) or `Shared` (Visual Basic) method to get the fully qualified assembly name. The following is a simple example. +- If you know the assembly's file system path, you can call the `static` (C#) or `Shared` (Visual Basic) method to get the fully qualified assembly name. The following is a simple example. ```csharp using System; diff --git a/docs/standard/assembly/identify.md b/docs/standard/assembly/identify.md index 611e5912913c3..37e685808a4cc 100644 --- a/docs/standard/assembly/identify.md +++ b/docs/standard/assembly/identify.md @@ -24,7 +24,7 @@ A file is an assembly if and only if it is managed, and contains an assembly ent ### Using the AssemblyName class -1. Call the method, passing the full file path and name of the file you are testing. +1. Call the method, passing the full file path and name of the file you are testing. 2. If a exception is thrown, the file is not an assembly. @@ -33,7 +33,7 @@ This example tests a DLL to see if it is an assembly. [!code-csharp[](snippets/identify/csharp/ExampleAssemblyName.cs#AssemblyName)] [!code-vb[](snippets/identify/visual-basic/ExampleAssemblyName.vb#AssemblyName)] -The method loads the test file, and then releases it once the information is read. +The method loads the test file, and then releases it once the information is read. ### Using the PEReader class @@ -48,11 +48,11 @@ The method loads the te 4. Check the value of the property. If the value is `false`, the file is not an assembly. -5. Call the method on the PE reader instance to create a metadata reader. +5. Call the method on the PE reader instance to create a metadata reader. 6. Check the value of the property. If the value is `true`, the file is an assembly. -Unlike the method, the class does not throw an exception on native Portable Executable (PE) files. This enables you to avoid the extra performance cost caused by exceptions when you need to check such files. You still need to handle exceptions in case the file does not exist or is not a PE file. +Unlike the method, the class does not throw an exception on native Portable Executable (PE) files. This enables you to avoid the extra performance cost caused by exceptions when you need to check such files. You still need to handle exceptions in case the file does not exist or is not a PE file. This example shows how to determine if a file is an assembly using the class. diff --git a/docs/standard/assembly/index.md b/docs/standard/assembly/index.md index 6d5fb3b678666..254dd1821a47e 100644 --- a/docs/standard/assembly/index.md +++ b/docs/standard/assembly/index.md @@ -33,7 +33,7 @@ Assemblies have the following properties: - You can programmatically obtain information about an assembly using reflection. For more information, see [Reflection (C#)](../../csharp/advanced-topics/reflection-and-attributes/index.md) or [Reflection (Visual Basic)](../../visual-basic/programming-guide/concepts/reflection.md). -- You can load an assembly just to inspect it using the class on .NET and .NET Framework. replaces the methods. +- You can load an assembly just to inspect it using the class on .NET and .NET Framework. replaces the methods. ## Assemblies in the common language runtime diff --git a/docs/standard/assembly/inspect-contents-using-metadataloadcontext.md b/docs/standard/assembly/inspect-contents-using-metadataloadcontext.md index 97e8733c290d1..c30f565c9cce0 100644 --- a/docs/standard/assembly/inspect-contents-using-metadataloadcontext.md +++ b/docs/standard/assembly/inspect-contents-using-metadataloadcontext.md @@ -27,7 +27,7 @@ If you need access to all BCL types, you can include all runtime assemblies in t To create the , invoke its constructor , passing the previously created as the first parameter and the core assembly name as the second parameter. You can omit the core assembly name, in which case the constructor will attempt to use default names: "mscorlib", "System.Runtime", or "netstandard". -After you've created the context, you can load assemblies into it using methods such as . You can use all reflection APIs on loaded assemblies except ones that involve code execution. The method does involve the execution of constructors, so use the method instead when you need to examine custom attributes in the . +After you've created the context, you can load assemblies into it using methods such as . You can use all reflection APIs on loaded assemblies except ones that involve code execution. The method does involve the execution of constructors, so use the method instead when you need to examine custom attributes in the . The following code sample creates , loads the assembly into it, and outputs assembly attributes into the console: diff --git a/docs/standard/assembly/load-unload.md b/docs/standard/assembly/load-unload.md index 6fe108d79d8f2..ce86248f5f04f 100644 --- a/docs/standard/assembly/load-unload.md +++ b/docs/standard/assembly/load-unload.md @@ -14,9 +14,9 @@ In .NET Framework, there is no way to unload an individual assembly without unlo To load an assembly into an application domain, use one of the several load methods contained in the classes and . For more information, see [How to: Load assemblies into an application domain](../../framework/app-domains/how-to-load-assemblies-into-an-application-domain.md). Note that .NET Core supports only a single application domain. -To unload an assembly in the .NET Framework, you must unload all of the application domains that contain it. To unload an application domain, use the method. For more information, see [How to: Unload an application domain](../../framework/app-domains/how-to-unload-an-application-domain.md). +To unload an assembly in the .NET Framework, you must unload all of the application domains that contain it. To unload an application domain, use the method. For more information, see [How to: Unload an application domain](../../framework/app-domains/how-to-unload-an-application-domain.md). -If you want to unload some assemblies but not others in a .NET Framework application, consider creating a new application domain, executing the code inside that domain, and then unloading that application domain. For more information, see [How to: Unload an application domain](../../framework/app-domains/how-to-unload-an-application-domain.md). +If you want to unload some assemblies but not others in a .NET Framework application, consider creating a new application domain, executing the code inside that domain, and then unloading that application domain. For more information, see [How to: Unload an application domain](../../framework/app-domains/how-to-unload-an-application-domain.md). ## See also diff --git a/docs/standard/assembly/names.md b/docs/standard/assembly/names.md index 7d4bc1975ac1d..5053d1591b095 100644 --- a/docs/standard/assembly/names.md +++ b/docs/standard/assembly/names.md @@ -9,7 +9,7 @@ ms.assetid: 8f8c2c90-f15d-400e-87e7-a757e4f04d0e --- # Assembly names -An assembly's name is stored in metadata and has a significant impact on the assembly's scope and use by an application. A strong-named assembly has a fully qualified name that includes the assembly's name, culture, public key, version number, and, optionally, processor architecture. Use the property to obtain the fully qualified name, frequently referred to as the display name, for loaded assemblies. +An assembly's name is stored in metadata and has a significant impact on the assembly's scope and use by an application. A strong-named assembly has a fully qualified name that includes the assembly's name, culture, public key, version number, and, optionally, processor architecture. Use the property to obtain the fully qualified name, frequently referred to as the display name, for loaded assemblies. The runtime uses the name information to locate the assembly and differentiate it from other assemblies with the same name. For example, a strong-named assembly called `myTypes` could have the following fully qualified name: @@ -45,7 +45,7 @@ The version corresponds to the version number of all .NET Framework assemblies t The runtime does not consider the file name when determining an assembly's identity. The assembly identity, which consists of the assembly name, version, culture, and strong name, must be clear to the runtime. - For example, if you have an assembly called *myAssembly.exe* that references an assembly called *myAssembly.dll*, binding occurs correctly if you execute *myAssembly.exe*. However, if another application executes *myAssembly.exe* using the method , the runtime determines that `myAssembly` is already loaded when *myAssembly.exe* requests binding to `myAssembly`. In this case, *myAssembly.dll* is never loaded. Because *myAssembly.exe* does not contain the requested type, a occurs. + For example, if you have an assembly called *myAssembly.exe* that references an assembly called *myAssembly.dll*, binding occurs correctly if you execute *myAssembly.exe*. However, if another application executes *myAssembly.exe* using the method , the runtime determines that `myAssembly` is already loaded when *myAssembly.exe* requests binding to `myAssembly`. In this case, *myAssembly.dll* is never loaded. Because *myAssembly.exe* does not contain the requested type, a occurs. To avoid this problem, make sure the assemblies that make up your application do not have the same assembly name or place assemblies with the same name in different directories. diff --git a/docs/standard/assembly/reference-assemblies.md b/docs/standard/assembly/reference-assemblies.md index 10324b43ae0f8..e6526c3b9c7fc 100644 --- a/docs/standard/assembly/reference-assemblies.md +++ b/docs/standard/assembly/reference-assemblies.md @@ -20,10 +20,10 @@ To use certain APIs from your project, you must add references to their assembli Reference assemblies for the .NET Framework libraries are distributed with targeting packs. You can obtain them by downloading a standalone installer or by selecting a component in Visual Studio installer. For more information, see [Install the .NET Framework for developers](../../framework/install/guide-for-developers.md). For .NET Core and .NET Standard, reference assemblies are automatically downloaded as necessary (via NuGet) and referenced. For .NET Core 3.0 and higher, the reference assemblies for the core framework are in the [Microsoft.NETCore.App.Ref](https://www.nuget.org/packages/Microsoft.NETCore.App.Ref) package (the [Microsoft.NETCore.App](https://www.nuget.org/packages/Microsoft.NETCore.App) package is used instead for versions before 3.0). -When you add references to .NET Framework assemblies in Visual Studio using the **Add reference** dialog, you select an assembly from the list, and Visual Studio automatically finds reference assemblies that correspond to the target framework version selected in your project. The same applies to adding references directly into MSBuild project using the [Reference](/visualstudio/msbuild/common-msbuild-project-items#reference) project item: you only need to specify the assembly name, not the full file path. When you add references to these assemblies in the command line by using the `-reference` compiler option ([in C#](../../csharp/language-reference/compiler-options/inputs.md#references) and in [Visual Basic](../../visual-basic/reference/command-line-compiler/reference.md)) or by using the method in the Roslyn API, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in the *%ProgramFiles(x86)%\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework* directory. For .NET Core, you can force publish operation to copy reference assemblies for your target platform into the *publish/refs* subdirectory of your output directory by setting the `PreserveCompilationContext` project property to `true`. Then you can pass these reference assembly files to the compiler. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locate their paths. +When you add references to .NET Framework assemblies in Visual Studio using the **Add reference** dialog, you select an assembly from the list, and Visual Studio automatically finds reference assemblies that correspond to the target framework version selected in your project. The same applies to adding references directly into MSBuild project using the [Reference](/visualstudio/msbuild/common-msbuild-project-items#reference) project item: you only need to specify the assembly name, not the full file path. When you add references to these assemblies in the command line by using the `-reference` compiler option ([in C#](../../csharp/language-reference/compiler-options/inputs.md#references) and in [Visual Basic](../../visual-basic/reference/command-line-compiler/reference.md)) or by using the method in the Roslyn API, you must manually specify reference assembly files for the correct target platform version. .NET Framework reference assembly files are located in the *%ProgramFiles(x86)%\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework* directory. For .NET Core, you can force publish operation to copy reference assemblies for your target platform into the *publish/refs* subdirectory of your output directory by setting the `PreserveCompilationContext` project property to `true`. Then you can pass these reference assembly files to the compiler. Using `DependencyContext` from [Microsoft.Extensions.DependencyModel](https://www.nuget.org/packages/Microsoft.Extensions.DependencyModel/) package can help locate their paths. Because they contain no implementation, reference assemblies can't be loaded for execution. Trying to do so results in a . If you want to examine the contents of a reference assembly, you can load it into the reflection-only context in .NET Framework (using the - method) or into the in .NET and .NET Framework. + method) or into the in .NET and .NET Framework. ## Generating reference assemblies @@ -35,7 +35,7 @@ You can generate reference assemblies: - In an MSBuild project, by using the [`ProduceReferenceAssembly` project property](/visualstudio/msbuild/common-msbuild-project-properties). - When compiling program from command line, by specifying `-refonly` ([C#](../../csharp/language-reference/compiler-options/code-generation.md#produceonlyreferenceassembly) / [Visual Basic](../../visual-basic/reference/command-line-compiler/refonly-compiler-option.md) ) or `-refout` ([C#](../../csharp/language-reference/compiler-options/output.md#producereferenceassembly) / [Visual Basic](../../visual-basic/reference/command-line-compiler/refout-compiler-option.md)) compiler options. -- When using the Roslyn API, by setting to `true` and to `false` in an object passed to the method. +- When using the Roslyn API, by setting to `true` and to `false` in an object passed to the method. If you want to distribute reference assemblies with NuGet packages, you must include them in the *ref\\* subdirectory under the package directory instead of in the *lib\\* subdirectory used for implementation assemblies. diff --git a/docs/standard/assembly/reference-strong-named.md b/docs/standard/assembly/reference-strong-named.md index 3d68f7a9d4728..4328e1bae42c9 100644 --- a/docs/standard/assembly/reference-strong-named.md +++ b/docs/standard/assembly/reference-strong-named.md @@ -38,7 +38,7 @@ csc /t:library myAssembly.cs /reference:myLibAssembly.dll ## Make a runtime reference to a strong-named assembly -When you make a runtime reference to a strong-named assembly, for example by using the or method, you must use the display name of the referenced strong-named assembly. The syntax of a display name is as follows: +When you make a runtime reference to a strong-named assembly, for example by using the or method, you must use the display name of the referenced strong-named assembly. The syntax of a display name is as follows: \<*assembly name*>**,** \<*version number*>**,** \<*culture*>**,** \<*public key token*> @@ -50,7 +50,7 @@ myDll, Version=1.1.0.0, Culture=en, PublicKeyToken=03689116d3a4ae33 In this example, `PublicKeyToken` is the hexadecimal form of the public key token. If there is no culture value, use `Culture=neutral`. -The following code example shows how to use this information with the method. +The following code example shows how to use this information with the method. ```cpp Assembly^ myDll = diff --git a/docs/standard/assembly/resolve-loads.md b/docs/standard/assembly/resolve-loads.md index 840de32308bb6..da41c3b8a349f 100644 --- a/docs/standard/assembly/resolve-loads.md +++ b/docs/standard/assembly/resolve-loads.md @@ -26,34 +26,34 @@ dev_langs: When you register a handler for the event, the handler is invoked whenever the runtime fails to bind to an assembly by name. For example, calling the following methods from user code can cause the event to be raised: -- An method overload or method overload whose first argument is a string that represents the display name of the assembly to load (that is, the string returned by the property). +- An method overload or method overload whose first argument is a string that represents the display name of the assembly to load (that is, the string returned by the property). -- An method overload or method overload whose first argument is an object that identifies the assembly to load. +- An method overload or method overload whose first argument is an object that identifies the assembly to load. -- An method overload. +- An method overload. -- An or method overload that instantiates an object in another application domain. +- An or method overload that instantiates an object in another application domain. ## What the event handler does -The handler for the event receives the display name of the assembly to be loaded, in the property. If the handler does not recognize the assembly name, it returns `null` (C#), `Nothing` (Visual Basic), or `nullptr` (Visual C++). +The handler for the event receives the display name of the assembly to be loaded, in the property. If the handler does not recognize the assembly name, it returns `null` (C#), `Nothing` (Visual Basic), or `nullptr` (Visual C++). If the handler recognizes the assembly name, it can load and return an assembly that satisfies the request. The following list describes some sample scenarios. -- If the handler knows the location of a version of the assembly, it can load the assembly by using the or method, and can return the loaded assembly if successful. +- If the handler knows the location of a version of the assembly, it can load the assembly by using the or method, and can return the loaded assembly if successful. -- If the handler has access to a database of assemblies stored as byte arrays, it can load a byte array by using one of the method overloads that take a byte array. +- If the handler has access to a database of assemblies stored as byte arrays, it can load a byte array by using one of the method overloads that take a byte array. - The handler can generate a dynamic assembly and return it. > [!NOTE] -> The handler must load the assembly into the load-from context, into the load context, or without context. If the handler loads the assembly into the reflection-only context by using the or the method, the load attempt that raised the event fails. +> The handler must load the assembly into the load-from context, into the load context, or without context. If the handler loads the assembly into the reflection-only context by using the or the method, the load attempt that raised the event fails. -It is the responsibility of the event handler to return a suitable assembly. The handler can parse the display name of the requested assembly by passing the property value to the constructor. Beginning with the .NET Framework 4, the handler can use the property to determine whether the current request is a dependency of another assembly. This information can help identify an assembly that will satisfy the dependency. +It is the responsibility of the event handler to return a suitable assembly. The handler can parse the display name of the requested assembly by passing the property value to the constructor. Beginning with the .NET Framework 4, the handler can use the property to determine whether the current request is a dependency of another assembly. This information can help identify an assembly that will satisfy the dependency. The event handler can return a different version of the assembly than the version that was requested. -In most cases, the assembly that is returned by the handler appears in the load context, regardless of the context the handler loads it into. For example, if the handler uses the method to load an assembly into the load-from context, the assembly appears in the load context when the handler returns it. However, in the following case the assembly appears without context when the handler returns it: +In most cases, the assembly that is returned by the handler appears in the load context, regardless of the context the handler loads it into. For example, if the handler uses the method to load an assembly into the load-from context, the assembly appears in the load context when the handler returns it. However, in the following case the assembly appears without context when the handler returns it: - The handler loads an assembly without context. @@ -72,7 +72,7 @@ The primary rule for handling the event > [!IMPORTANT] > Beginning with the .NET Framework 4, the event is raised for satellite assemblies. This change affects an event handler that was written for an earlier version of the .NET Framework, if the handler tries to resolve all assembly load requests. Event handlers that ignore assemblies they do not recognize are not affected by this change: They return `null`, and normal fallback mechanisms are followed. -When loading an assembly, the event handler must not use any of the or method overloads that can cause the event to be raised recursively, because this can lead to a stack overflow. (See the list provided earlier in this topic.) This happens even if you provide exception handling for the load request, because no exception is thrown until all event handlers have returned. Thus, the following code results in a stack overflow if `MyAssembly` is not found: +When loading an assembly, the event handler must not use any of the or method overloads that can cause the event to be raised recursively, because this can lead to a stack overflow. (See the list provided earlier in this topic.) This happens even if you provide exception handling for the load request, because no exception is thrown until all event handlers have returned. Thus, the following code results in a stack overflow if `MyAssembly` is not found: ```csharp using System; @@ -201,7 +201,7 @@ Process is terminated due to StackOverflowException. ### The correct way to handle AssemblyResolve -When resolving assemblies from the event handler, a will eventually be thrown if the handler uses the or method calls. Instead, use or methods, as they do not raise the `AssemblyResolve` event. +When resolving assemblies from the event handler, a will eventually be thrown if the handler uses the or method calls. Instead, use or methods, as they do not raise the `AssemblyResolve` event. Imagine that `MyAssembly.dll` is located near the executing assembly, in a known location, it can be resolved using `Assembly.LoadFile` given the path to the assembly. diff --git a/docs/standard/assembly/set-attributes.md b/docs/standard/assembly/set-attributes.md index 1128b2bfe657a..5cbfe8da39ee2 100644 --- a/docs/standard/assembly/set-attributes.md +++ b/docs/standard/assembly/set-attributes.md @@ -34,7 +34,7 @@ The following table describes the version and culture attributes. |--|--| | | Enumerated field indicating the culture that the assembly supports. An assembly can also specify culture independence, indicating that it contains the resources for the default culture. **Note:** The runtime treats any assembly that does not have the culture attribute set to null as a satellite assembly. Such assemblies are subject to satellite assembly binding rules. For more information, see [How the runtime locates assemblies](../../framework/deployment/how-the-runtime-locates-assemblies.md). | | | Value that sets assembly attributes, such as whether the assembly can be run side by side. | -| | Numeric value in the format _major_._minor_._build_._revision_ (for example, 2.4.0.0). The common language runtime uses this value to perform binding operations in strong-named assemblies. **Note:** If the attribute is not applied to an assembly, the version number specified by the attribute is used by the , , and properties. | +| | Numeric value in the format _major_._minor_._build_._revision_ (for example, 2.4.0.0). The common language runtime uses this value to perform binding operations in strong-named assemblies. **Note:** If the attribute is not applied to an assembly, the version number specified by the attribute is used by the , , and properties. | The following code example shows how to apply the version and culture attributes to an assembly. @@ -68,7 +68,7 @@ You can use informational attributes to provide additional company or product in | | String value specifying a company name. | | | String value specifying copyright information. | | | String value specifying the Win32 file version number. This normally defaults to the assembly version. | -| | String value specifying version information that is not used by the common language runtime, such as a full product version number. **Note:** If this attribute is applied to an assembly, the string it specifies can be obtained at runtime by using the property. The string is also used in the path and registry key provided by the and properties. | +| | String value specifying version information that is not used by the common language runtime, such as a full product version number. **Note:** If this attribute is applied to an assembly, the string it specifies can be obtained at runtime by using the property. The string is also used in the path and registry key provided by the and properties. | | | String value specifying product information. | | | String value specifying trademark information. | diff --git a/docs/standard/assembly/type-forwarding.md b/docs/standard/assembly/type-forwarding.md index 31a197ff80e83..ad54152445320 100644 --- a/docs/standard/assembly/type-forwarding.md +++ b/docs/standard/assembly/type-forwarding.md @@ -45,7 +45,7 @@ Continuing from the contrived example description above, imagine you're developi :::code language="xml" source="snippets/type-forwarders/before/Utility/Utility.csproj"::: -The `Example` class provides a few properties and overrides : +The `Example` class provides a few properties and overrides : :::code language="csharp" source="snippets/type-forwarders/before/Utility/Example.cs"::: diff --git a/docs/standard/assembly/unloadability.md b/docs/standard/assembly/unloadability.md index ccb573d36ae4a..31a389c9176cf 100644 --- a/docs/standard/assembly/unloadability.md +++ b/docs/standard/assembly/unloadability.md @@ -13,11 +13,11 @@ ai-usage: ai-assisted Unloadability is supported through . You can load a set of assemblies into a collectible `AssemblyLoadContext`, execute methods in them or just inspect them using reflection, and finally unload the `AssemblyLoadContext`. That unloads the assemblies loaded into the `AssemblyLoadContext`. -There's one noteworthy difference between the unloading using `AssemblyLoadContext` and using AppDomains. With AppDomains, the unloading is forced. At unload time, all threads running in the target AppDomain are aborted, managed COM objects created in the target AppDomain are destroyed, and so on. With `AssemblyLoadContext`, the unload is "cooperative". Calling the method just initiates the unloading. The unloading finishes after: +There's one noteworthy difference between the unloading using `AssemblyLoadContext` and using AppDomains. With AppDomains, the unloading is forced. At unload time, all threads running in the target AppDomain are aborted, managed COM objects created in the target AppDomain are destroyed, and so on. With `AssemblyLoadContext`, the unload is "cooperative". Calling the method just initiates the unloading. The unloading finishes after: - No threads have methods from the assemblies loaded into the `AssemblyLoadContext` on their call stacks. - None of the types from the assemblies loaded into the `AssemblyLoadContext`, instances of those types, and the assemblies themselves are referenced by: - - References outside of the `AssemblyLoadContext`, except for weak references ( or ). + - References outside of the `AssemblyLoadContext`, except for weak references ( or ). - Strong garbage collector (GC) handles ([GCHandleType.Normal](xref:System.Runtime.InteropServices.GCHandleType.Normal) or [GCHandleType.Pinned](xref:System.Runtime.InteropServices.GCHandleType.Pinned)) from both inside and outside of the `AssemblyLoadContext`. ## Use collectible AssemblyLoadContext @@ -26,7 +26,7 @@ This section contains a detailed step-by-step tutorial that shows a simple way t ### Create a collectible AssemblyLoadContext -Derive your class from the and override its method. That method resolves references to all assemblies that are dependencies of assemblies loaded into that `AssemblyLoadContext`. +Derive your class from the and override its method. That method resolves references to all assemblies that are dependencies of assemblies loaded into that `AssemblyLoadContext`. The following code is an example of the simplest custom `AssemblyLoadContext`: diff --git a/docs/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm.md b/docs/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm.md index c3d7a5eaeac54..1ef669a1e64c8 100644 --- a/docs/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm.md +++ b/docs/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm.md @@ -2,7 +2,7 @@ title: "Asynchronous Programming Model (APM)" description: Learn about the Asynchronous Programming Model (APM) in .NET. Discover how to begin and end an asynchronous operation. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "ending asynchronous operations" - "starting asynchronous operations" - "beginning asynchronous operations" @@ -14,52 +14,52 @@ ms.assetid: c9b3501e-6bc6-40f9-8efd-4b6d9e39ccf0 --- # Asynchronous Programming Model (APM) -An asynchronous operation that uses the design pattern is implemented as two methods named `BeginOperationName` and `EndOperationName` that begin and end the asynchronous operation *OperationName* respectively. For example, the class provides the and methods to asynchronously read bytes from a file. These methods implement the asynchronous version of the method. - +An asynchronous operation that uses the design pattern is implemented as two methods named `BeginOperationName` and `EndOperationName` that begin and end the asynchronous operation *OperationName* respectively. For example, the class provides the and methods to asynchronously read bytes from a file. These methods implement the asynchronous version of the method. + > [!NOTE] -> Starting with the .NET Framework 4, the Task Parallel Library provides a new model for asynchronous and parallel programming. For more information, see [Task Parallel Library (TPL)](../parallel-programming/task-parallel-library-tpl.md) and [Task-based Asynchronous Pattern (TAP)](task-based-asynchronous-pattern-tap.md)). - - After calling `BeginOperationName`, an application can continue executing instructions on the calling thread while the asynchronous operation takes place on a different thread. For each call to `BeginOperationName`, the application should also call `EndOperationName` to get the results of the operation. - -## Beginning an Asynchronous Operation - - The `BeginOperationName` method begins asynchronous operation *OperationName* and returns an object that implements the interface. objects store information about an asynchronous operation. The following table shows information about an asynchronous operation. - -|Member|Description| -|------------|-----------------| -||An optional application-specific object that contains information about the asynchronous operation.| -||A that can be used to block application execution until the asynchronous operation completes.| -||A value that indicates whether the asynchronous operation completed on the thread used to call `BeginOperationName` instead of completing on a separate thread.| -||A value that indicates whether the asynchronous operation has completed.| - - A `BeginOperationName` method takes any parameters declared in the signature of the synchronous version of the method that are passed by value or by reference. Any out parameters are not part of the `BeginOperationName` method signature. The `BeginOperationName` method signature also includes two additional parameters. The first of these defines an delegate that references a method that is called when the asynchronous operation completes. The caller can specify `null` (`Nothing` in Visual Basic) if it does not want a method invoked when the operation completes. The second additional parameter is a user-defined object. This object can be used to pass application-specific state information to the method invoked when the asynchronous operation completes. If a `BeginOperationName` method takes additional operation-specific parameters, such as a byte array to store bytes read from a file, the and application state object are the last parameters in the `BeginOperationName` method signature. - - `BeginOperationName` returns control to the calling thread immediately. If the `BeginOperationName` method throws exceptions, the exceptions are thrown before the asynchronous operation is started. If the `BeginOperationName` method throws exceptions, the callback method is not invoked. - -## Ending an Asynchronous Operation - - The `EndOperationName` method ends asynchronous operation *OperationName*. The return value of the `EndOperationName` method is the same type returned by its synchronous counterpart and is specific to the asynchronous operation. For example, the method returns the number of bytes read from a and the method returns an object that contains information about a host computer. The `EndOperationName` method takes any out or ref parameters declared in the signature of the synchronous version of the method. In addition to the parameters from the synchronous method, the `EndOperationName` method also includes an parameter. Callers must pass the instance returned by the corresponding call to `BeginOperationName`. - - If the asynchronous operation represented by the object has not completed when `EndOperationName` is called, `EndOperationName` blocks the calling thread until the asynchronous operation is complete. Exceptions thrown by the asynchronous operation are thrown from the `EndOperationName` method. The effect of calling the `EndOperationName` method multiple times with the same is not defined. Likewise, calling the `EndOperationName` method with an that was not returned by the related Begin method is also not defined. - +> Starting with the .NET Framework 4, the Task Parallel Library provides a new model for asynchronous and parallel programming. For more information, see [Task Parallel Library (TPL)](../parallel-programming/task-parallel-library-tpl.md) and [Task-based Asynchronous Pattern (TAP)](task-based-asynchronous-pattern-tap.md)). + + After calling `BeginOperationName`, an application can continue executing instructions on the calling thread while the asynchronous operation takes place on a different thread. For each call to `BeginOperationName`, the application should also call `EndOperationName` to get the results of the operation. + +## Beginning an Asynchronous Operation + + The `BeginOperationName` method begins asynchronous operation *OperationName* and returns an object that implements the interface. objects store information about an asynchronous operation. The following table shows information about an asynchronous operation. + +|Member|Description| +|------------|-----------------| +||An optional application-specific object that contains information about the asynchronous operation.| +||A that can be used to block application execution until the asynchronous operation completes.| +||A value that indicates whether the asynchronous operation completed on the thread used to call `BeginOperationName` instead of completing on a separate thread.| +||A value that indicates whether the asynchronous operation has completed.| + + A `BeginOperationName` method takes any parameters declared in the signature of the synchronous version of the method that are passed by value or by reference. Any out parameters are not part of the `BeginOperationName` method signature. The `BeginOperationName` method signature also includes two additional parameters. The first of these defines an delegate that references a method that is called when the asynchronous operation completes. The caller can specify `null` (`Nothing` in Visual Basic) if it does not want a method invoked when the operation completes. The second additional parameter is a user-defined object. This object can be used to pass application-specific state information to the method invoked when the asynchronous operation completes. If a `BeginOperationName` method takes additional operation-specific parameters, such as a byte array to store bytes read from a file, the and application state object are the last parameters in the `BeginOperationName` method signature. + + `BeginOperationName` returns control to the calling thread immediately. If the `BeginOperationName` method throws exceptions, the exceptions are thrown before the asynchronous operation is started. If the `BeginOperationName` method throws exceptions, the callback method is not invoked. + +## Ending an Asynchronous Operation + + The `EndOperationName` method ends asynchronous operation *OperationName*. The return value of the `EndOperationName` method is the same type returned by its synchronous counterpart and is specific to the asynchronous operation. For example, the method returns the number of bytes read from a and the method returns an object that contains information about a host computer. The `EndOperationName` method takes any out or ref parameters declared in the signature of the synchronous version of the method. In addition to the parameters from the synchronous method, the `EndOperationName` method also includes an parameter. Callers must pass the instance returned by the corresponding call to `BeginOperationName`. + + If the asynchronous operation represented by the object has not completed when `EndOperationName` is called, `EndOperationName` blocks the calling thread until the asynchronous operation is complete. Exceptions thrown by the asynchronous operation are thrown from the `EndOperationName` method. The effect of calling the `EndOperationName` method multiple times with the same is not defined. Likewise, calling the `EndOperationName` method with an that was not returned by the related Begin method is also not defined. + > [!NOTE] -> For either of the undefined scenarios, implementers should consider throwing . - +> For either of the undefined scenarios, implementers should consider throwing . + > [!NOTE] -> Implementers of this design pattern should notify the caller that the asynchronous operation completed by setting to true, calling the asynchronous callback method (if one was specified) and signaling the . - - Application developers have several design choices for accessing the results of the asynchronous operation. The correct choice depends on whether the application has instructions that can execute while the operation completes. If an application cannot perform any additional work until it receives the results of the asynchronous operation, the application must block until the results are available. To block until an asynchronous operation completes, you can use one of the following approaches: - -- Call `EndOperationName` from the application’s main thread, blocking application execution until the operation is complete. For an example that illustrates this technique, see [Blocking Application Execution by Ending an Async Operation](blocking-application-execution-by-ending-an-async-operation.md). - -- Use the to block application execution until one or more operations are complete. For an example that illustrates this technique, see [Blocking Application Execution Using an AsyncWaitHandle](blocking-application-execution-using-an-asyncwaithandle.md). - - Applications that do not need to block while the asynchronous operation completes can use one of the following approaches: - -- Poll for operation completion status by checking the property periodically and calling `EndOperationName` when the operation is complete. For an example that illustrates this technique, see [Polling for the Status of an Asynchronous Operation](polling-for-the-status-of-an-asynchronous-operation.md). - -- Use an delegate to specify a method to be invoked when the operation is complete. For an example that illustrates this technique, see [Using an AsyncCallback Delegate to End an Asynchronous Operation](using-an-asynccallback-delegate-to-end-an-asynchronous-operation.md). - +> Implementers of this design pattern should notify the caller that the asynchronous operation completed by setting to true, calling the asynchronous callback method (if one was specified) and signaling the . + + Application developers have several design choices for accessing the results of the asynchronous operation. The correct choice depends on whether the application has instructions that can execute while the operation completes. If an application cannot perform any additional work until it receives the results of the asynchronous operation, the application must block until the results are available. To block until an asynchronous operation completes, you can use one of the following approaches: + +- Call `EndOperationName` from the application’s main thread, blocking application execution until the operation is complete. For an example that illustrates this technique, see [Blocking Application Execution by Ending an Async Operation](blocking-application-execution-by-ending-an-async-operation.md). + +- Use the to block application execution until one or more operations are complete. For an example that illustrates this technique, see [Blocking Application Execution Using an AsyncWaitHandle](blocking-application-execution-using-an-asyncwaithandle.md). + + Applications that do not need to block while the asynchronous operation completes can use one of the following approaches: + +- Poll for operation completion status by checking the property periodically and calling `EndOperationName` when the operation is complete. For an example that illustrates this technique, see [Polling for the Status of an Asynchronous Operation](polling-for-the-status-of-an-asynchronous-operation.md). + +- Use an delegate to specify a method to be invoked when the operation is complete. For an example that illustrates this technique, see [Using an AsyncCallback Delegate to End an Asynchronous Operation](using-an-asynccallback-delegate-to-end-an-asynchronous-operation.md). + ## See also - [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md) diff --git a/docs/standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md index 4ae6bf008c95d..b6120e5634b10 100644 --- a/docs/standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md @@ -57,11 +57,11 @@ private void Form1_MethodNameCompleted(object sender, MethodNameCompletedEventAr - Ensure that you always raise the *MethodName***Completed** event. This event should be raised on successful completion, on an error, or on cancellation. Applications should never encounter a situation where they remain idle and completion never occurs. -- Ensure that you catch any exceptions that occur in the asynchronous operation and assign the caught exception to the property. +- Ensure that you catch any exceptions that occur in the asynchronous operation and assign the caught exception to the property. -- If there was an error completing the task, the results should not be accessible. When the property is not `null`, ensure that accessing any property in the structure raises an exception. Use the method to perform this verification. +- If there was an error completing the task, the results should not be accessible. When the property is not `null`, ensure that accessing any property in the structure raises an exception. Use the method to perform this verification. -- Model a time out as an error. When a time out occurs, raise the *MethodName***Completed** event and assign a to the property. +- Model a time out as an error. When a time out occurs, raise the *MethodName***Completed** event and assign a to the property. - If your class supports multiple concurrent invocations, ensure that the *MethodName***Completed** event contains the appropriate `userSuppliedState` object. @@ -79,9 +79,9 @@ private void Form1_MethodNameCompleted(object sender, MethodNameCompletedEventAr ### Accessing Results -- If there was an error during execution of the asynchronous operation, the results should not be accessible. Ensure that accessing any property in the when is not `null` raises the exception referenced by . The class provides the method for this purpose. +- If there was an error during execution of the asynchronous operation, the results should not be accessible. Ensure that accessing any property in the when is not `null` raises the exception referenced by . The class provides the method for this purpose. -- Ensure that any attempt to access the result raises an stating that the operation was canceled. Use the method to perform this verification. +- Ensure that any attempt to access the result raises an stating that the operation was canceled. Use the method to perform this verification. ### Progress Reporting @@ -89,7 +89,7 @@ private void Form1_MethodNameCompleted(object sender, MethodNameCompletedEventAr - If you implement a **ProgressChanged** or *MethodName***ProgressChanged** event, ensure that there are no such events raised for a particular asynchronous operation after that operation's *MethodName***Completed** event has been raised. -- If the standard is being populated, ensure that the can always be interpreted as a percentage. The percentage does not need to be accurate, but it should represent a percentage. If your progress reporting metric must be something other than a percentage, derive a class from the class and leave at 0. Avoid using a reporting metric other than a percentage. +- If the standard is being populated, ensure that the can always be interpreted as a percentage. The percentage does not need to be accurate, but it should represent a percentage. If your progress reporting metric must be something other than a percentage, derive a class from the class and leave at 0. Avoid using a reporting metric other than a percentage. - Ensure that the `ProgressChanged` event is raised on the appropriate thread and at the appropriate time in the application lifecycle. For more information, see the Threading and Contexts section. @@ -105,7 +105,7 @@ private void Form1_MethodNameCompleted(object sender, MethodNameCompletedEventAr - In the case of cancellation, set the flag in the object. -- Ensure that any attempt to access the result raises an stating that the operation was canceled. Use the method to perform this verification. +- Ensure that any attempt to access the result raises an stating that the operation was canceled. Use the method to perform this verification. - Ensure that calls to a cancellation method always return successfully, and never raise an exception. In general, a client is not notified as to whether an operation is truly cancelable at any given time, and is not notified as to whether a previously issued cancellation has succeeded. However, the application will always be given notification when a cancellation succeeded, because the application takes part in the completion status. @@ -113,18 +113,18 @@ private void Form1_MethodNameCompleted(object sender, MethodNameCompletedEventAr ### Errors and Exceptions -- Catch any exceptions that occur in the asynchronous operation and set the value of the property to that exception. +- Catch any exceptions that occur in the asynchronous operation and set the value of the property to that exception. ### Threading and Contexts For correct operation of your class, it is critical that the client's event handlers are invoked on the proper thread or context for the given application model, including ASP.NET and Windows Forms applications. Two important helper classes are provided to ensure that your asynchronous class behaves correctly under any application model: and . - provides one method, , which returns an . Your *MethodName***Async** method calls and your class uses the returned to track the lifetime of the asynchronous task. + provides one method, , which returns an . Your *MethodName***Async** method calls and your class uses the returned to track the lifetime of the asynchronous task. - To report progress, incremental results, and completion to the client, call the and methods on the . is responsible for marshalling calls to the client's event handlers to the proper thread or context. + To report progress, incremental results, and completion to the client, call the and methods on the . is responsible for marshalling calls to the client's event handlers to the proper thread or context. > [!NOTE] -> You can circumvent these rules if you explicitly want to go against the policy of the application model, but still benefit from the other advantages of using the Event-based Asynchronous Pattern. For example, you may want a class operating in Windows Forms to be free threaded. You can create a free threaded class, as long as developers understand the implied restrictions. Console applications do not synchronize the execution of calls. This can cause `ProgressChanged` events to be raised out of order. If you wish to have serialized execution of calls, implement and install a class. +> You can circumvent these rules if you explicitly want to go against the policy of the application model, but still benefit from the other advantages of using the Event-based Asynchronous Pattern. For example, you may want a class operating in Windows Forms to be free threaded. You can create a free threaded class, as long as developers understand the implied restrictions. Console applications do not synchronize the execution of calls. This can cause `ProgressChanged` events to be raised out of order. If you wish to have serialized execution of calls, implement and install a class. For more information about using and to enable your asynchronous operations, see [How to: Implement a Component That Supports the Event-based Asynchronous Pattern](component-that-supports-the-event-based-asynchronous-pattern.md). diff --git a/docs/standard/asynchronous-programming-patterns/blocking-application-execution-by-ending-an-async-operation.md b/docs/standard/asynchronous-programming-patterns/blocking-application-execution-by-ending-an-async-operation.md index 8170700d4b937..7027d2f763250 100644 --- a/docs/standard/asynchronous-programming-patterns/blocking-application-execution-by-ending-an-async-operation.md +++ b/docs/standard/asynchronous-programming-patterns/blocking-application-execution-by-ending-an-async-operation.md @@ -2,33 +2,33 @@ description: "Learn more about: Blocking Application Execution by Ending an Async Operation" title: "Blocking Application Execution by Ending an Async Operation" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "blocks, asynchronous operations" - "AsyncWaitHandle property" - "asynchronous programming, blocking applications" - "blocking application execution" ms.topic: how-to -dev_langs: +dev_langs: - "csharp" - "vb" --- # Blocking Application Execution by Ending an Async Operation -Applications that cannot continue to do other work while waiting for the results of an asynchronous operation must block until the operation completes. Use one of the following options to block your application's main thread while waiting for an asynchronous operation to complete: - -- Call the asynchronous operations **End**_OperationName_ method. This approach is demonstrated in this topic. - -- Use the property of the returned by the asynchronous operation's **Begin**_OperationName_ method. For an example that demonstrates this approach, see [Blocking Application Execution Using an AsyncWaitHandle](blocking-application-execution-using-an-asyncwaithandle.md). - - Applications that use the **End**_OperationName_ method to block until an asynchronous operation is complete will typically call the **Begin**_OperationName_ method, perform any work that can be done without the results of the operation, and then call **End**_OperationName_. - -## Example - - The following code example demonstrates using asynchronous methods in the class to retrieve Domain Name System information for a user-specified computer. Note that `null` (`Nothing` in Visual Basic) is passed for the `requestCallback` and `stateObject` parameters because these arguments are not required when using this approach. - +Applications that cannot continue to do other work while waiting for the results of an asynchronous operation must block until the operation completes. Use one of the following options to block your application's main thread while waiting for an asynchronous operation to complete: + +- Call the asynchronous operations **End**_OperationName_ method. This approach is demonstrated in this topic. + +- Use the property of the returned by the asynchronous operation's **Begin**_OperationName_ method. For an example that demonstrates this approach, see [Blocking Application Execution Using an AsyncWaitHandle](blocking-application-execution-using-an-asyncwaithandle.md). + + Applications that use the **End**_OperationName_ method to block until an asynchronous operation is complete will typically call the **Begin**_OperationName_ method, perform any work that can be done without the results of the operation, and then call **End**_OperationName_. + +## Example + + The following code example demonstrates using asynchronous methods in the class to retrieve Domain Name System information for a user-specified computer. Note that `null` (`Nothing` in Visual Basic) is passed for the `requestCallback` and `stateObject` parameters because these arguments are not required when using this approach. + [!code-csharp[AsyncDesignPattern#1](../../../samples/snippets/csharp/VS_Snippets_CLR/AsyncDesignPattern/CS/Async_EndBlock.cs#1)] - [!code-vb[AsyncDesignPattern#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/AsyncDesignPattern/VB/Async_EndBlock.vb#1)] - + [!code-vb[AsyncDesignPattern#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/AsyncDesignPattern/VB/Async_EndBlock.vb#1)] + ## See also - [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md) diff --git a/docs/standard/asynchronous-programming-patterns/blocking-application-execution-using-an-asyncwaithandle.md b/docs/standard/asynchronous-programming-patterns/blocking-application-execution-using-an-asyncwaithandle.md index c1a9bfb31a4d7..dcd637ec3f402 100644 --- a/docs/standard/asynchronous-programming-patterns/blocking-application-execution-using-an-asyncwaithandle.md +++ b/docs/standard/asynchronous-programming-patterns/blocking-application-execution-using-an-asyncwaithandle.md @@ -2,10 +2,10 @@ description: "Learn more about: Blocking Application Execution Using an AsyncWaitHandle" title: "Blocking Application Execution Using an AsyncWaitHandle" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "blocks, asynchronous operations" - "ending asynchronous operations" - "asynchronous programming, ending operations" @@ -16,21 +16,21 @@ ms.topic: how-to --- # Blocking Application Execution Using an AsyncWaitHandle -Applications that cannot continue to do other work while waiting for the results of an asynchronous operation must block until the operation completes. Use one of the following options to block your application's main thread while waiting for an asynchronous operation to complete: - -- Use the property of the returned by the asynchronous operation's **Begin**_OperationName_ method. This approach is demonstrated in this topic. - -- Call the asynchronous operation's **End**_OperationName_ method. For an example that demonstrates this approach, see [Blocking Application Execution by Ending an Async Operation](blocking-application-execution-by-ending-an-async-operation.md). - - Applications that use one or more objects to block until an asynchronous operation is complete will typically call the **Begin**_OperationName_ method, perform any work that can be done without the results of the operation, and then block until the asynchronous operation(s) completes. An application can block on a single operation by calling one of the methods using the . To block while waiting for a set of asynchronous operations to complete, store the associated objects in an array and call one of the methods. To block while waiting for any one of a set of asynchronous operations to complete, store the associated objects in an array and call one of the methods. - -## Example - - The following code example demonstrates using asynchronous methods in the DNS class to retrieve Domain Name System information for a user-specified computer. The example demonstrates blocking using the associated with the asynchronous operation. Note that `null` (`Nothing` in Visual Basic) is passed for the `requestCallback` and `stateObject` parameters because these are not required when using this approach. - +Applications that cannot continue to do other work while waiting for the results of an asynchronous operation must block until the operation completes. Use one of the following options to block your application's main thread while waiting for an asynchronous operation to complete: + +- Use the property of the returned by the asynchronous operation's **Begin**_OperationName_ method. This approach is demonstrated in this topic. + +- Call the asynchronous operation's **End**_OperationName_ method. For an example that demonstrates this approach, see [Blocking Application Execution by Ending an Async Operation](blocking-application-execution-by-ending-an-async-operation.md). + + Applications that use one or more objects to block until an asynchronous operation is complete will typically call the **Begin**_OperationName_ method, perform any work that can be done without the results of the operation, and then block until the asynchronous operation(s) completes. An application can block on a single operation by calling one of the methods using the . To block while waiting for a set of asynchronous operations to complete, store the associated objects in an array and call one of the methods. To block while waiting for any one of a set of asynchronous operations to complete, store the associated objects in an array and call one of the methods. + +## Example + + The following code example demonstrates using asynchronous methods in the DNS class to retrieve Domain Name System information for a user-specified computer. The example demonstrates blocking using the associated with the asynchronous operation. Note that `null` (`Nothing` in Visual Basic) is passed for the `requestCallback` and `stateObject` parameters because these are not required when using this approach. + [!code-csharp[AsyncDesignPattern#2](../../../samples/snippets/csharp/VS_Snippets_CLR/AsyncDesignPattern/CS/Async_EndBlockWait.cs#2)] - [!code-vb[AsyncDesignPattern#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/AsyncDesignPattern/VB/Async_EndBlockWait.vb#2)] - + [!code-vb[AsyncDesignPattern#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/AsyncDesignPattern/VB/Async_EndBlockWait.vb#2)] + ## See also - [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md) diff --git a/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md b/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md index 80b4e89a15443..bacc33b471fac 100644 --- a/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md +++ b/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md @@ -37,7 +37,7 @@ The code examples in this topic demonstrate four common ways to use `BeginInvoke - Do some work and then call `EndInvoke` to block until the call completes. -- Obtain a using the property, use its method to block execution until the is signaled, and then call `EndInvoke`. +- Obtain a using the property, use its method to block execution until the is signaled, and then call `EndInvoke`. - Poll the returned by `BeginInvoke` to determine when the asynchronous call has completed, and then call `EndInvoke`. @@ -67,12 +67,12 @@ The code examples in this topic demonstrate four common ways to use `BeginInvoke ## Waiting for an Asynchronous Call with WaitHandle - You can obtain a by using the property of the returned by `BeginInvoke`. The is signaled when the asynchronous call completes, and you can wait for it by calling the method. + You can obtain a by using the property of the returned by `BeginInvoke`. The is signaled when the asynchronous call completes, and you can wait for it by calling the method. If you use a , you can perform additional processing before or after the asynchronous call completes, but before calling `EndInvoke` to retrieve the results. > [!NOTE] -> The wait handle is not closed automatically when you call `EndInvoke`. If you release all references to the wait handle, system resources are freed when garbage collection reclaims the wait handle. To free the system resources as soon as you are finished using the wait handle, dispose of it by calling the method. Garbage collection works more efficiently when disposable objects are explicitly disposed. +> The wait handle is not closed automatically when you call `EndInvoke`. If you release all references to the wait handle, system resources are freed when garbage collection reclaims the wait handle. To free the system resources as soon as you are finished using the wait handle, dispose of it by calling the method. Garbage collection works more efficiently when disposable objects are explicitly disposed. [!code-csharp[AsyncDelegateExamples#3](../../../samples/snippets/csharp/VS_Snippets_CLR/AsyncDelegateExamples/CS/waithandle.cs#3)] [!code-vb[AsyncDelegateExamples#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/AsyncDelegateExamples/VB/WaitHandle.vb#3)] @@ -88,7 +88,7 @@ The code examples in this topic demonstrate four common ways to use `BeginInvoke If the thread that initiates the asynchronous call does not need to be the thread that processes the results, you can execute a callback method when the call completes. The callback method is executed on a thread. - To use a callback method, you must pass `BeginInvoke` an delegate that represents the callback method. You can also pass an object that contains information to be used by the callback method. In the callback method, you can cast the , which is the only parameter of the callback method, to an object. You can then use the property to get the delegate that was used to initiate the call so that you can call `EndInvoke`. + To use a callback method, you must pass `BeginInvoke` an delegate that represents the callback method. You can also pass an object that contains information to be used by the callback method. In the callback method, you can cast the , which is the only parameter of the callback method, to an object. You can then use the property to get the delegate that was used to initiate the call so that you can call `EndInvoke`. Notes on the example: diff --git a/docs/standard/asynchronous-programming-patterns/component-that-supports-the-event-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/component-that-supports-the-event-based-asynchronous-pattern.md index 91e84486a5acc..46e22d5654700 100644 --- a/docs/standard/asynchronous-programming-patterns/component-that-supports-the-event-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/component-that-supports-the-event-based-asynchronous-pattern.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Implement a Component That Supports the Event-based Asynchronous Pattern" title: "How to: Implement a Component That Supports the Event-based Asynchronous Pattern" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "Event-based Asynchronous Pattern" - "ProgressChangedEventArgs class" - "BackgroundWorker component" @@ -21,243 +21,243 @@ ms.topic: tutorial --- # How to: Implement a Component That Supports the Event-based Asynchronous Pattern -If you are writing a class with some operations that may incur noticeable delays, consider giving it asynchronous functionality by implementing the [Event-based Asynchronous Pattern](event-based-asynchronous-pattern-overview.md). - - This walkthrough illustrates how to create a component that implements the Event-based Asynchronous Pattern. It is implemented using helper classes from the namespace, which ensures that the component works correctly under any application model, including ASP.NET, Console applications and Windows Forms applications. This component is also designable with a control and your own custom designers. - - When you are through, you will have an application that computes prime numbers asynchronously. Your application will have a main user interface (UI) thread and a thread for each prime number calculation. Although testing whether a large number is prime can take a noticeable amount of time, the main UI thread will not be interrupted by this delay, and the form will be responsive during the calculations. You will be able to run as many calculations as you like concurrently and selectively cancel pending calculations. - - Tasks illustrated in this walkthrough include: - -- Creating the Component - -- Defining Public Asynchronous Events and Delegates - -- Defining Private Delegates - -- Implementing Public Events - -- Implementing the Completion Method - -- Implementing the Worker Methods - -- Implementing Start and Cancel Methods - - To copy the code in this topic as a single listing, see [How to: Implement a Client of the Event-based Asynchronous Pattern](how-to-implement-a-client-of-the-event-based-asynchronous-pattern.md). - -## Creating the Component - - The first step is to create the component that will implement the Event-based Asynchronous Pattern. - -### To create the component - -- Create a class called `PrimeNumberCalculator` that inherits from . - -## Defining Public Asynchronous Events and Delegates - - Your component communicates to clients using events. The _MethodName_**Completed** event alerts clients to the completion of an asynchronous task, and the _MethodName_**ProgressChanged** event informs clients of the progress of an asynchronous task. - -### To define asynchronous events for clients of your component: - -1. Import the and namespaces at the top of your file. - +If you are writing a class with some operations that may incur noticeable delays, consider giving it asynchronous functionality by implementing the [Event-based Asynchronous Pattern](event-based-asynchronous-pattern-overview.md). + + This walkthrough illustrates how to create a component that implements the Event-based Asynchronous Pattern. It is implemented using helper classes from the namespace, which ensures that the component works correctly under any application model, including ASP.NET, Console applications and Windows Forms applications. This component is also designable with a control and your own custom designers. + + When you are through, you will have an application that computes prime numbers asynchronously. Your application will have a main user interface (UI) thread and a thread for each prime number calculation. Although testing whether a large number is prime can take a noticeable amount of time, the main UI thread will not be interrupted by this delay, and the form will be responsive during the calculations. You will be able to run as many calculations as you like concurrently and selectively cancel pending calculations. + + Tasks illustrated in this walkthrough include: + +- Creating the Component + +- Defining Public Asynchronous Events and Delegates + +- Defining Private Delegates + +- Implementing Public Events + +- Implementing the Completion Method + +- Implementing the Worker Methods + +- Implementing Start and Cancel Methods + + To copy the code in this topic as a single listing, see [How to: Implement a Client of the Event-based Asynchronous Pattern](how-to-implement-a-client-of-the-event-based-asynchronous-pattern.md). + +## Creating the Component + + The first step is to create the component that will implement the Event-based Asynchronous Pattern. + +### To create the component + +- Create a class called `PrimeNumberCalculator` that inherits from . + +## Defining Public Asynchronous Events and Delegates + + Your component communicates to clients using events. The _MethodName_**Completed** event alerts clients to the completion of an asynchronous task, and the _MethodName_**ProgressChanged** event informs clients of the progress of an asynchronous task. + +### To define asynchronous events for clients of your component: + +1. Import the and namespaces at the top of your file. + [!code-csharp[System.ComponentModel.AsyncOperationManager#11](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#11)] - [!code-vb[System.ComponentModel.AsyncOperationManager#11](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#11)] - -2. Before the `PrimeNumberCalculator` class definition, declare delegates for progress and completion events. - + [!code-vb[System.ComponentModel.AsyncOperationManager#11](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#11)] + +2. Before the `PrimeNumberCalculator` class definition, declare delegates for progress and completion events. + [!code-csharp[System.ComponentModel.AsyncOperationManager#7](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#7)] - [!code-vb[System.ComponentModel.AsyncOperationManager#7](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#7)] - -3. In the `PrimeNumberCalculator` class definition, declare events for reporting progress and completion to clients. - + [!code-vb[System.ComponentModel.AsyncOperationManager#7](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#7)] + +3. In the `PrimeNumberCalculator` class definition, declare events for reporting progress and completion to clients. + [!code-csharp[System.ComponentModel.AsyncOperationManager#8](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#8)] - [!code-vb[System.ComponentModel.AsyncOperationManager#8](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#8)] - -4. After the `PrimeNumberCalculator` class definition, derive the `CalculatePrimeCompletedEventArgs` class for reporting the outcome of each calculation to the client's event handler for the `CalculatePrimeCompleted`.event. In addition to the `AsyncCompletedEventArgs` properties, this class enables the client to determine what number was tested, whether it is prime, and what the first divisor is if it is not prime. - + [!code-vb[System.ComponentModel.AsyncOperationManager#8](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#8)] + +4. After the `PrimeNumberCalculator` class definition, derive the `CalculatePrimeCompletedEventArgs` class for reporting the outcome of each calculation to the client's event handler for the `CalculatePrimeCompleted`.event. In addition to the `AsyncCompletedEventArgs` properties, this class enables the client to determine what number was tested, whether it is prime, and what the first divisor is if it is not prime. + [!code-csharp[System.ComponentModel.AsyncOperationManager#6](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#6)] - [!code-vb[System.ComponentModel.AsyncOperationManager#6](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#6)] - + [!code-vb[System.ComponentModel.AsyncOperationManager#6](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#6)] + ## Checkpoint 1 - At this point, you can build the component. - -### To test your component - -- Compile the component. - - You will receive two compiler warnings: - - ```console - warning CS0067: The event 'AsynchronousPatternExample.PrimeNumberCalculator.ProgressChanged' is never used - warning CS0067: The event 'AsynchronousPatternExample.PrimeNumberCalculator.CalculatePrimeCompleted' is never used - ``` - - These warnings will be cleared in the next section. - -## Defining Private Delegates - - The asynchronous aspects of the `PrimeNumberCalculator` component are implemented internally with a special delegate known as a . A represents a callback method that executes on a thread. The callback method must have a signature that takes a single parameter of type , which means you will need to pass state among delegates in a wrapper class. For more information, see . - -### To implement your component's internal asynchronous behavior: - -1. Declare and create the delegates in the `PrimeNumberCalculator` class. Create the objects in a utility method called `InitializeDelegates`. - - You will need two delegates: one for reporting progress to the client, and one for reporting completion to the client. + At this point, you can build the component. + +### To test your component + +- Compile the component. + + You will receive two compiler warnings: + + ```console + warning CS0067: The event 'AsynchronousPatternExample.PrimeNumberCalculator.ProgressChanged' is never used + warning CS0067: The event 'AsynchronousPatternExample.PrimeNumberCalculator.CalculatePrimeCompleted' is never used + ``` + + These warnings will be cleared in the next section. + +## Defining Private Delegates + + The asynchronous aspects of the `PrimeNumberCalculator` component are implemented internally with a special delegate known as a . A represents a callback method that executes on a thread. The callback method must have a signature that takes a single parameter of type , which means you will need to pass state among delegates in a wrapper class. For more information, see . + +### To implement your component's internal asynchronous behavior: + +1. Declare and create the delegates in the `PrimeNumberCalculator` class. Create the objects in a utility method called `InitializeDelegates`. + + You will need two delegates: one for reporting progress to the client, and one for reporting completion to the client. [!code-csharp[System.ComponentModel.AsyncOperationManager#9](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#9)] - [!code-vb[System.ComponentModel.AsyncOperationManager#9](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#9)] + [!code-vb[System.ComponentModel.AsyncOperationManager#9](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#9)] [!code-csharp[System.ComponentModel.AsyncOperationManager#20](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#20)] - [!code-vb[System.ComponentModel.AsyncOperationManager#20](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#20)] - -2. Call the `InitializeDelegates` method in your component's constructor. - + [!code-vb[System.ComponentModel.AsyncOperationManager#20](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#20)] + +2. Call the `InitializeDelegates` method in your component's constructor. + [!code-csharp[System.ComponentModel.AsyncOperationManager#21](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#21)] - [!code-vb[System.ComponentModel.AsyncOperationManager#21](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#21)] - -3. Declare a delegate in the `PrimeNumberCalculator` class that handles the actual work to be done asynchronously. This delegate wraps the worker method that tests whether a number is prime. The delegate takes an parameter, which will be used to track the lifetime of the asynchronous operation. - + [!code-vb[System.ComponentModel.AsyncOperationManager#21](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#21)] + +3. Declare a delegate in the `PrimeNumberCalculator` class that handles the actual work to be done asynchronously. This delegate wraps the worker method that tests whether a number is prime. The delegate takes an parameter, which will be used to track the lifetime of the asynchronous operation. + [!code-csharp[System.ComponentModel.AsyncOperationManager#22](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#22)] - [!code-vb[System.ComponentModel.AsyncOperationManager#22](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#22)] - -4. Create a collection for managing lifetimes of pending asynchronous operations. The client needs a way to track operations as they are executed and completed, and this tracking is done by requiring the client to pass a unique token, or task ID, when the client makes the call to the asynchronous method. The `PrimeNumberCalculator` component must keep track of each call by associating the task ID with its corresponding invocation. If the client passes a task ID that is not unique, the `PrimeNumberCalculator` component must raise an exception. - - The `PrimeNumberCalculator` component keeps track of task ID by using a special collection class called a . In the class definition, create a called `userStateToLifetime`. - + [!code-vb[System.ComponentModel.AsyncOperationManager#22](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#22)] + +4. Create a collection for managing lifetimes of pending asynchronous operations. The client needs a way to track operations as they are executed and completed, and this tracking is done by requiring the client to pass a unique token, or task ID, when the client makes the call to the asynchronous method. The `PrimeNumberCalculator` component must keep track of each call by associating the task ID with its corresponding invocation. If the client passes a task ID that is not unique, the `PrimeNumberCalculator` component must raise an exception. + + The `PrimeNumberCalculator` component keeps track of task ID by using a special collection class called a . In the class definition, create a called `userStateToLifetime`. + [!code-csharp[System.ComponentModel.AsyncOperationManager#23](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#23)] - [!code-vb[System.ComponentModel.AsyncOperationManager#23](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#23)] - -## Implementing Public Events - - Components that implement the Event-based Asynchronous Pattern communicate to clients using events. These events are invoked on the proper thread with the help of the class. - -### To raise events to your component's clients: - -1. Implement public events for reporting to clients. You will need an event for reporting progress and one for reporting completion. - + [!code-vb[System.ComponentModel.AsyncOperationManager#23](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#23)] + +## Implementing Public Events + + Components that implement the Event-based Asynchronous Pattern communicate to clients using events. These events are invoked on the proper thread with the help of the class. + +### To raise events to your component's clients: + +1. Implement public events for reporting to clients. You will need an event for reporting progress and one for reporting completion. + [!code-csharp[System.ComponentModel.AsyncOperationManager#24](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#24)] - [!code-vb[System.ComponentModel.AsyncOperationManager#24](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#24)] - -## Implementing the Completion Method - - The completion delegate is the method that the underlying, free-threaded asynchronous behavior will invoke when the asynchronous operation ends by successful completion, error, or cancellation. This invocation happens on an arbitrary thread. - - This method is where the client's task ID is removed from the internal collection of unique client tokens. This method also ends the lifetime of a particular asynchronous operation by calling the method on the corresponding . This call raises the completion event on the thread that is appropriate for the application model. After the method is called, this instance of can no longer be used, and any subsequent attempts to use it will throw an exception. - - The `CompletionMethod` signature must hold all state necessary to describe the outcome of the asynchronous operation. It holds state for the number that was tested by this particular asynchronous operation, whether the number is prime, and the value of its first divisor if it is not a prime number. It also holds state describing any exception that occurred, and the corresponding to this particular task. - -### To complete an asynchronous operation: - -- Implement the completion method. It takes six parameters, which it uses to populate a `CalculatePrimeCompletedEventArgs` that is returned to the client through the client's `CalculatePrimeCompletedEventHandler`. It removes the client's task ID token from the internal collection, and it ends the asynchronous operation's lifetime with a call to . The marshals the call to the thread or context that is appropriate for the application model. - + [!code-vb[System.ComponentModel.AsyncOperationManager#24](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#24)] + +## Implementing the Completion Method + + The completion delegate is the method that the underlying, free-threaded asynchronous behavior will invoke when the asynchronous operation ends by successful completion, error, or cancellation. This invocation happens on an arbitrary thread. + + This method is where the client's task ID is removed from the internal collection of unique client tokens. This method also ends the lifetime of a particular asynchronous operation by calling the method on the corresponding . This call raises the completion event on the thread that is appropriate for the application model. After the method is called, this instance of can no longer be used, and any subsequent attempts to use it will throw an exception. + + The `CompletionMethod` signature must hold all state necessary to describe the outcome of the asynchronous operation. It holds state for the number that was tested by this particular asynchronous operation, whether the number is prime, and the value of its first divisor if it is not a prime number. It also holds state describing any exception that occurred, and the corresponding to this particular task. + +### To complete an asynchronous operation: + +- Implement the completion method. It takes six parameters, which it uses to populate a `CalculatePrimeCompletedEventArgs` that is returned to the client through the client's `CalculatePrimeCompletedEventHandler`. It removes the client's task ID token from the internal collection, and it ends the asynchronous operation's lifetime with a call to . The marshals the call to the thread or context that is appropriate for the application model. + [!code-csharp[System.ComponentModel.AsyncOperationManager#26](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#26)] - [!code-vb[System.ComponentModel.AsyncOperationManager#26](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#26)] - + [!code-vb[System.ComponentModel.AsyncOperationManager#26](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#26)] + ## Checkpoint 2 - At this point, you can build the component. - -### To test your component - -- Compile the component. - - You will receive one compiler warning: - - ```console - warning CS0169: The private field 'AsynchronousPatternExample.PrimeNumberCalculator.workerDelegate' is never used - ``` - - This warning will be resolved in the next section. - -## Implementing the Worker Methods - - So far, you have implemented the supporting asynchronous code for the `PrimeNumberCalculator` component. Now you can implement the code that does the actual work. You will implement three methods: `CalculateWorker`, `BuildPrimeNumberList`, and `IsPrime`. Together, `BuildPrimeNumberList` and `IsPrime` comprise a well-known algorithm called the Sieve of Eratosthenes, which determines if a number is prime by finding all the prime numbers up to the square root of the test number. If no divisors are found by that point, the test number is prime. - - If this component were written for maximum efficiency, it would remember all the prime numbers discovered by various invocations for different test numbers. It would also check for trivial divisors like 2, 3, and 5. The intent of this example is to demonstrate how time-consuming operations can be executed asynchronously, however, so these optimizations are left as an exercise for you. - - The `CalculateWorker` method is wrapped in a delegate and is invoked asynchronously with a call to `BeginInvoke`. - + At this point, you can build the component. + +### To test your component + +- Compile the component. + + You will receive one compiler warning: + + ```console + warning CS0169: The private field 'AsynchronousPatternExample.PrimeNumberCalculator.workerDelegate' is never used + ``` + + This warning will be resolved in the next section. + +## Implementing the Worker Methods + + So far, you have implemented the supporting asynchronous code for the `PrimeNumberCalculator` component. Now you can implement the code that does the actual work. You will implement three methods: `CalculateWorker`, `BuildPrimeNumberList`, and `IsPrime`. Together, `BuildPrimeNumberList` and `IsPrime` comprise a well-known algorithm called the Sieve of Eratosthenes, which determines if a number is prime by finding all the prime numbers up to the square root of the test number. If no divisors are found by that point, the test number is prime. + + If this component were written for maximum efficiency, it would remember all the prime numbers discovered by various invocations for different test numbers. It would also check for trivial divisors like 2, 3, and 5. The intent of this example is to demonstrate how time-consuming operations can be executed asynchronously, however, so these optimizations are left as an exercise for you. + + The `CalculateWorker` method is wrapped in a delegate and is invoked asynchronously with a call to `BeginInvoke`. + > [!NOTE] -> Progress reporting is implemented in the `BuildPrimeNumberList` method. On fast computers, `ProgressChanged` events can be raised in rapid succession. The client thread, on which these events are raised, must be able to handle this situation. User interface code may be flooded with messages and unable to keep up, resulting in unresponsiveness. For an example user interface that handles this situation, see [How to: Implement a Client of the Event-based Asynchronous Pattern](how-to-implement-a-client-of-the-event-based-asynchronous-pattern.md). - -### To execute the prime number calculation asynchronously: - -1. Implement the `TaskCanceled` utility method. This checks the task lifetime collection for the given task ID, and returns `true` if the task ID is not found. - +> Progress reporting is implemented in the `BuildPrimeNumberList` method. On fast computers, `ProgressChanged` events can be raised in rapid succession. The client thread, on which these events are raised, must be able to handle this situation. User interface code may be flooded with messages and unable to keep up, resulting in unresponsiveness. For an example user interface that handles this situation, see [How to: Implement a Client of the Event-based Asynchronous Pattern](how-to-implement-a-client-of-the-event-based-asynchronous-pattern.md). + +### To execute the prime number calculation asynchronously: + +1. Implement the `TaskCanceled` utility method. This checks the task lifetime collection for the given task ID, and returns `true` if the task ID is not found. + [!code-csharp[System.ComponentModel.AsyncOperationManager#32](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#32)] - [!code-vb[System.ComponentModel.AsyncOperationManager#32](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#32)] - -2. Implement the `CalculateWorker` method. It takes two parameters: a number to test, and an . - + [!code-vb[System.ComponentModel.AsyncOperationManager#32](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#32)] + +2. Implement the `CalculateWorker` method. It takes two parameters: a number to test, and an . + [!code-csharp[System.ComponentModel.AsyncOperationManager#27](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#27)] - [!code-vb[System.ComponentModel.AsyncOperationManager#27](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#27)] - -3. Implement `BuildPrimeNumberList`. It takes two parameters: the number to test, and an . It uses the to report progress and incremental results. This assures that the client's event handlers are called on the proper thread or context for the application model. When `BuildPrimeNumberList` finds a prime number, it reports this as an incremental result to the client's event handler for the `ProgressChanged` event. This requires a class derived from , called `CalculatePrimeProgressChangedEventArgs`, which has one added property called `LatestPrimeNumber`. - - The `BuildPrimeNumberList` method also periodically calls the `TaskCanceled` method and exits if the method returns `true`. - + [!code-vb[System.ComponentModel.AsyncOperationManager#27](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#27)] + +3. Implement `BuildPrimeNumberList`. It takes two parameters: the number to test, and an . It uses the to report progress and incremental results. This assures that the client's event handlers are called on the proper thread or context for the application model. When `BuildPrimeNumberList` finds a prime number, it reports this as an incremental result to the client's event handler for the `ProgressChanged` event. This requires a class derived from , called `CalculatePrimeProgressChangedEventArgs`, which has one added property called `LatestPrimeNumber`. + + The `BuildPrimeNumberList` method also periodically calls the `TaskCanceled` method and exits if the method returns `true`. + [!code-csharp[System.ComponentModel.AsyncOperationManager#5](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#5)] - [!code-vb[System.ComponentModel.AsyncOperationManager#5](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#5)] - -4. Implement `IsPrime`. It takes three parameters: a list of known prime numbers, the number to test, and an output parameter for the first divisor found. Given the list of prime numbers, it determines if the test number is prime. - + [!code-vb[System.ComponentModel.AsyncOperationManager#5](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#5)] + +4. Implement `IsPrime`. It takes three parameters: a list of known prime numbers, the number to test, and an output parameter for the first divisor found. Given the list of prime numbers, it determines if the test number is prime. + [!code-csharp[System.ComponentModel.AsyncOperationManager#28](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#28)] - [!code-vb[System.ComponentModel.AsyncOperationManager#28](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#28)] - -5. Derive `CalculatePrimeProgressChangedEventArgs` from . This class is necessary for reporting incremental results to the client's event handler for the `ProgressChanged` event. It has one added property called `LatestPrimeNumber`. - + [!code-vb[System.ComponentModel.AsyncOperationManager#28](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#28)] + +5. Derive `CalculatePrimeProgressChangedEventArgs` from . This class is necessary for reporting incremental results to the client's event handler for the `ProgressChanged` event. It has one added property called `LatestPrimeNumber`. + [!code-csharp[System.ComponentModel.AsyncOperationManager#29](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#29)] - [!code-vb[System.ComponentModel.AsyncOperationManager#29](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#29)] - + [!code-vb[System.ComponentModel.AsyncOperationManager#29](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#29)] + ## Checkpoint 3 - At this point, you can build the component. - -### To test your component - -- Compile the component. - - All that remains to be written are the methods to start and cancel asynchronous operations, `CalculatePrimeAsync` and `CancelAsync`. - -## Implementing the Start and Cancel Methods - - You start the worker method on its own thread by calling `BeginInvoke` on the delegate that wraps it. To manage the lifetime of a particular asynchronous operation, you call the method on the helper class. This returns an , which marshals calls on the client's event handlers to the proper thread or context. - - You cancel a particular pending operation by calling on its corresponding . This ends that operation, and any subsequent calls to its will throw an exception. - -### To implement Start and Cancel functionality: - -1. Implement the `CalculatePrimeAsync` method. Make sure the client-supplied token (task ID) is unique with respect to all the tokens representing currently pending tasks. If the client passes in a non-unique token, `CalculatePrimeAsync` raises an exception. Otherwise, the token is added to the task ID collection. - + At this point, you can build the component. + +### To test your component + +- Compile the component. + + All that remains to be written are the methods to start and cancel asynchronous operations, `CalculatePrimeAsync` and `CancelAsync`. + +## Implementing the Start and Cancel Methods + + You start the worker method on its own thread by calling `BeginInvoke` on the delegate that wraps it. To manage the lifetime of a particular asynchronous operation, you call the method on the helper class. This returns an , which marshals calls on the client's event handlers to the proper thread or context. + + You cancel a particular pending operation by calling on its corresponding . This ends that operation, and any subsequent calls to its will throw an exception. + +### To implement Start and Cancel functionality: + +1. Implement the `CalculatePrimeAsync` method. Make sure the client-supplied token (task ID) is unique with respect to all the tokens representing currently pending tasks. If the client passes in a non-unique token, `CalculatePrimeAsync` raises an exception. Otherwise, the token is added to the task ID collection. + [!code-csharp[System.ComponentModel.AsyncOperationManager#3](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#3)] - [!code-vb[System.ComponentModel.AsyncOperationManager#3](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#3)] - -2. Implement the `CancelAsync` method. If the `taskId` parameter exists in the token collection, it is removed. This prevents canceled tasks that have not started from running. If the task is running, the `BuildPrimeNumberList` method exits when it detects that the task ID has been removed from the lifetime collection. - + [!code-vb[System.ComponentModel.AsyncOperationManager#3](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#3)] + +2. Implement the `CancelAsync` method. If the `taskId` parameter exists in the token collection, it is removed. This prevents canceled tasks that have not started from running. If the task is running, the `BuildPrimeNumberList` method exits when it detects that the task ID has been removed from the lifetime collection. + [!code-csharp[System.ComponentModel.AsyncOperationManager#4](snippets/component-that-supports-the-event-based-asynchronous-pattern/csharp/primenumbercalculatormain.cs#4)] - [!code-vb[System.ComponentModel.AsyncOperationManager#4](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#4)] - + [!code-vb[System.ComponentModel.AsyncOperationManager#4](snippets/component-that-supports-the-event-based-asynchronous-pattern/vb/primenumbercalculatormain.vb#4)] + ## Checkpoint 4 - At this point, you can build the component. - -### To test your component - -- Compile the component. - - The `PrimeNumberCalculator` component is now complete and ready to use. - - For an example client that uses the `PrimeNumberCalculator` component, see [How to: Implement a Client of the Event-based Asynchronous Pattern](how-to-implement-a-client-of-the-event-based-asynchronous-pattern.md). - -## Next Steps - - You can fill out this example by writing `CalculatePrime`, the synchronous equivalent of `CalculatePrimeAsync` method. This will make the `PrimeNumberCalculator` component fully compliant with the Event-based Asynchronous Pattern. - - You can improve this example by retaining the list of all the prime numbers discovered by various invocations for different test numbers. Using this approach, each task will benefit from the work done by previous tasks. Be careful to protect this list with `lock` regions, so access to the list by different threads is serialized. - - You can also improve this example by testing for trivial divisors, like 2, 3, and 5. - + At this point, you can build the component. + +### To test your component + +- Compile the component. + + The `PrimeNumberCalculator` component is now complete and ready to use. + + For an example client that uses the `PrimeNumberCalculator` component, see [How to: Implement a Client of the Event-based Asynchronous Pattern](how-to-implement-a-client-of-the-event-based-asynchronous-pattern.md). + +## Next Steps + + You can fill out this example by writing `CalculatePrime`, the synchronous equivalent of `CalculatePrimeAsync` method. This will make the `PrimeNumberCalculator` component fully compliant with the Event-based Asynchronous Pattern. + + You can improve this example by retaining the list of all the prime numbers discovered by various invocations for different test numbers. Using this approach, each task will benefit from the work done by previous tasks. Be careful to protect this list with `lock` regions, so access to the list by different threads is serialized. + + You can also improve this example by testing for trivial divisors, like 2, 3, and 5. + ## See also - [How to: Run an Operation in the Background](/dotnet/desktop/winforms/controls/how-to-run-an-operation-in-the-background) diff --git a/docs/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern.md index 6866445a9cfed..1499b3f21d020 100644 --- a/docs/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern.md @@ -12,23 +12,23 @@ ms.assetid: 033cf871-ae24-433d-8939-7a3793e547bf --- # Consuming the Task-based Asynchronous Pattern -When you use the Task-based Asynchronous Pattern (TAP) to work with asynchronous operations, you can use callbacks to achieve waiting without blocking. For tasks, this is achieved through methods such as . Language-based asynchronous support hides callbacks by allowing asynchronous operations to be awaited within normal control flow, and compiler-generated code provides this same API-level support. +When you use the Task-based Asynchronous Pattern (TAP) to work with asynchronous operations, you can use callbacks to achieve waiting without blocking. For tasks, this is achieved through methods such as . Language-based asynchronous support hides callbacks by allowing asynchronous operations to be awaited within normal control flow, and compiler-generated code provides this same API-level support. ## Suspending Execution with Await -You can use the [await](../../csharp/language-reference/operators/await.md) keyword in C# and the [Await Operator](../../visual-basic/language-reference/operators/await-operator.md) in Visual Basic to asynchronously await and objects. When you're awaiting a , the `await` expression is of type `void`. When you're awaiting a , the `await` expression is of type `TResult`. An `await` expression must occur inside the body of an asynchronous method. (These language features were introduced in .NET Framework 4.5.) +You can use the [await](../../csharp/language-reference/operators/await.md) keyword in C# and the [Await Operator](../../visual-basic/language-reference/operators/await-operator.md) in Visual Basic to asynchronously await and objects. When you're awaiting a , the `await` expression is of type `void`. When you're awaiting a , the `await` expression is of type `TResult`. An `await` expression must occur inside the body of an asynchronous method. (These language features were introduced in .NET Framework 4.5.) - Under the covers, the await functionality installs a callback on the task by using a continuation. This callback resumes the asynchronous method at the point of suspension. When the asynchronous method is resumed, if the awaited operation completed successfully and was a , its `TResult` is returned. If the or that was awaited ended in the state, an exception is thrown. If the or that was awaited ended in the state, the exception that caused it to fault is thrown. A `Task` can fault as a result of multiple exceptions, but only one of these exceptions is propagated. However, the property returns an exception that contains all the errors. + Under the covers, the await functionality installs a callback on the task by using a continuation. This callback resumes the asynchronous method at the point of suspension. When the asynchronous method is resumed, if the awaited operation completed successfully and was a , its `TResult` is returned. If the or that was awaited ended in the state, an exception is thrown. If the or that was awaited ended in the state, the exception that caused it to fault is thrown. A `Task` can fault as a result of multiple exceptions, but only one of these exceptions is propagated. However, the property returns an exception that contains all the errors. - If a synchronization context ( object) is associated with the thread that was executing the asynchronous method at the time of suspension (for example, if the property is not `null`), the asynchronous method resumes on that same synchronization context by using the context's method. Otherwise, it relies on the task scheduler ( object) that was current at the time of suspension. Typically, this is the default task scheduler (), which targets the thread pool. This task scheduler determines whether the awaited asynchronous operation should resume where it completed or whether the resumption should be scheduled. The default scheduler typically allows the continuation to run on the thread that the awaited operation completed. + If a synchronization context ( object) is associated with the thread that was executing the asynchronous method at the time of suspension (for example, if the property is not `null`), the asynchronous method resumes on that same synchronization context by using the context's method. Otherwise, it relies on the task scheduler ( object) that was current at the time of suspension. Typically, this is the default task scheduler (), which targets the thread pool. This task scheduler determines whether the awaited asynchronous operation should resume where it completed or whether the resumption should be scheduled. The default scheduler typically allows the continuation to run on the thread that the awaited operation completed. - When an asynchronous method is called, it synchronously executes the body of the function up until the first await expression on an awaitable instance that has not yet completed, at which point the invocation returns to the caller. If the asynchronous method does not return `void`, a or object is returned to represent the ongoing computation. In a non-void asynchronous method, if a return statement is encountered or the end of the method body is reached, the task is completed in the final state. If an unhandled exception causes control to leave the body of the asynchronous method, the task ends in the state. If that exception is an , the task instead ends in the state. In this manner, the result or exception is eventually published. + When an asynchronous method is called, it synchronously executes the body of the function up until the first await expression on an awaitable instance that has not yet completed, at which point the invocation returns to the caller. If the asynchronous method does not return `void`, a or object is returned to represent the ongoing computation. In a non-void asynchronous method, if a return statement is encountered or the end of the method body is reached, the task is completed in the final state. If an unhandled exception causes control to leave the body of the asynchronous method, the task ends in the state. If that exception is an , the task instead ends in the state. In this manner, the result or exception is eventually published. There are several important variations of this behavior. For performance reasons, if a task has already completed by the time the task is awaited, control is not yielded, and the function continues to execute. Additionally, returning to the original context isn't always the desired behavior and can be changed; this is described in more detail in the next section. ### Configuring Suspension and Resumption with Yield and ConfigureAwait - Several methods provide more control over an asynchronous method's execution. For example, you can use the method to introduce a yield point into the asynchronous method: + Several methods provide more control over an asynchronous method's execution. For example, you can use the method to introduce a yield point into the asynchronous method: ```csharp public class Task : … @@ -51,7 +51,7 @@ Task.Run(async delegate }); ``` - You can also use the method for better control over suspension and resumption in an asynchronous method. As mentioned previously, by default, the current context is captured at the time an asynchronous method is suspended, and that captured context is used to invoke the asynchronous method's continuation upon resumption. In many cases, this is the exact behavior you want. In other cases, you may not care about the continuation context, and you can achieve better performance by avoiding such posts back to the original context. To enable this, use the method to inform the await operation not to capture and resume on the context, but to continue execution wherever the asynchronous operation that was being awaited completed: + You can also use the method for better control over suspension and resumption in an asynchronous method. As mentioned previously, by default, the current context is captured at the time an asynchronous method is suspended, and that captured context is used to invoke the asynchronous method's continuation upon resumption. In many cases, this is the exact behavior you want. In other cases, you may not care about the continuation context, and you can achieve better performance by avoiding such posts back to the original context. To enable this, use the method to inform the await operation not to capture and resume on the context, but to continue execution wherever the asynchronous operation that was being awaited completed: ```csharp await someTask.ConfigureAwait(continueOnCapturedContext:false); @@ -61,7 +61,7 @@ await someTask.ConfigureAwait(continueOnCapturedContext:false); Starting with .NET Framework 4, TAP methods that support cancellation provide at least one overload that accepts a cancellation token ( object). - A cancellation token is created through a cancellation token source ( object). The source's property returns the cancellation token that will be signaled when the source's method is called. For example, if you want to download a single webpage and you want to be able to cancel the operation, you create a object, pass its token to the TAP method, and then call the source's method when you're ready to cancel the operation: + A cancellation token is created through a cancellation token source ( object). The source's property returns the cancellation token that will be signaled when the source's method is called. For example, if you want to download a single webpage and you want to be able to cancel the operation, you create a object, pass its token to the TAP method, and then call the source's method when you're ready to cancel the operation: ```csharp var cts = new CancellationTokenSource(); @@ -93,7 +93,7 @@ var cts = new CancellationTokenSource(); > [!IMPORTANT] > Cancellation requests may be initiated from any thread. - You can pass the value to any method that accepts a cancellation token to indicate that cancellation will never be requested. This causes the property to return `false`, and the called method can optimize accordingly. For testing purposes, you can also pass in a pre-canceled cancellation token that is instantiated by using the constructor that accepts a Boolean value to indicate whether the token should start in an already-canceled or not-cancelable state. + You can pass the value to any method that accepts a cancellation token to indicate that cancellation will never be requested. This causes the property to return `false`, and the called method can optimize accordingly. For testing purposes, you can also pass in a pre-canceled cancellation token that is instantiated by using the constructor that accepts a Boolean value to indicate whether the token should start in an already-canceled or not-cancelable state. This approach to cancellation has several advantages: @@ -130,7 +130,7 @@ private async void btnDownload_Click(object sender, RoutedEventArgs e) ### Task.Run - The class includes several methods that let you easily offload work as a or to the thread pool, for example: + The class includes several methods that let you easily offload work as a or to the thread pool, for example: ```csharp public async void button1_Click(object sender, EventArgs e) @@ -143,7 +143,7 @@ public async void button1_Click(object sender, EventArgs e) } ``` - Some of these methods, such as the overload, exist as shorthand for the method. This overload enable you to use await within the offloaded work, for example: + Some of these methods, such as the overload, exist as shorthand for the method. This overload enable you to use await within the offloaded work, for example: ```csharp public async void button1_Click(object sender, EventArgs e) @@ -157,11 +157,11 @@ public async void button1_Click(object sender, EventArgs e) } ``` - Such overloads are logically equivalent to using the method in conjunction with the extension method in the Task Parallel Library. + Such overloads are logically equivalent to using the method in conjunction with the extension method in the Task Parallel Library. ### Task.FromResult - Use the method in scenarios where data may already be available and just needs to be returned from a task-returning method lifted into a : + Use the method in scenarios where data may already be available and just needs to be returned from a task-returning method lifted into a : ```csharp public Task GetValueAsync(string key) @@ -180,7 +180,7 @@ private async Task GetValueAsyncInternal(string key) ### Task.WhenAll - Use the method to asynchronously wait on multiple asynchronous operations that are represented as tasks. The method has multiple overloads that support a set of non-generic tasks or a non-uniform set of generic tasks (for example, asynchronously waiting for multiple void-returning operations, or asynchronously waiting for multiple value-returning methods where each value may have a different type) and to support a uniform set of generic tasks (such as asynchronously waiting for multiple `TResult`-returning methods). + Use the method to asynchronously wait on multiple asynchronous operations that are represented as tasks. The method has multiple overloads that support a set of non-generic tasks or a non-uniform set of generic tasks (for example, asynchronously waiting for multiple void-returning operations, or asynchronously waiting for multiple value-returning methods where each value may have a different type) and to support a uniform set of generic tasks (such as asynchronously waiting for multiple `TResult`-returning methods). Let's say you want to send email messages to several customers. You can overlap sending the messages so you're not waiting for one message to complete before sending the next. You can also find out when the send operations have completed and whether any errors have occurred: @@ -189,7 +189,7 @@ IEnumerable asyncOps = from addr in addrs select SendMailAsync(addr); await Task.WhenAll(asyncOps); ``` - This code doesn't explicitly handle exceptions that may occur, but lets exceptions propagate out of the `await` on the resulting task from . To handle the exceptions, you can use code such as the following: + This code doesn't explicitly handle exceptions that may occur, but lets exceptions propagate out of the `await` on the resulting task from . To handle the exceptions, you can use code such as the following: ```csharp IEnumerable asyncOps = from addr in addrs select SendMailAsync(addr); @@ -203,7 +203,7 @@ catch(Exception exc) } ``` - In this case, if any asynchronous operation fails, all the exceptions will be consolidated in an exception, which is stored in the that is returned from the method. However, only one of those exceptions is propagated by the `await` keyword. If you want to examine all the exceptions, you can rewrite the previous code as follows: + In this case, if any asynchronous operation fails, all the exceptions will be consolidated in an exception, which is stored in the that is returned from the method. However, only one of those exceptions is propagated by the `await` keyword. If you want to examine all the exceptions, you can rewrite the previous code as follows: ```csharp Task [] asyncOps = (from addr in addrs select SendMailAsync(addr)).ToArray(); @@ -248,7 +248,7 @@ catch(Exception exc) ### Task.WhenAny - You can use the method to asynchronously wait for just one of multiple asynchronous operations represented as tasks to complete. This method serves four primary use cases: + You can use the method to asynchronously wait for just one of multiple asynchronous operations represented as tasks to complete. This method serves four primary use cases: - Redundancy: Performing an operation multiple times and selecting the one that completes first (for example, contacting multiple stock quote web services that will produce a single result and selecting the one that completes the fastest). @@ -256,11 +256,11 @@ catch(Exception exc) - Throttling: Allowing additional operations to begin as others complete. This is an extension of the interleaving scenario. -- Early bailout: For example, an operation represented by task t1 can be grouped in a task with another task t2, and you can wait on the task. Task t2 could represent a time-out, or cancellation, or some other signal that causes the task to complete before t1 completes. +- Early bailout: For example, an operation represented by task t1 can be grouped in a task with another task t2, and you can wait on the task. Task t2 could represent a time-out, or cancellation, or some other signal that causes the task to complete before t1 completes. #### Redundancy - Consider a case where you want to make a decision about whether to buy a stock. There are several stock recommendation web services that you trust, but depending on daily load, each service can end up being slow at different times. You can use the method to receive a notification when any operation completes: + Consider a case where you want to make a decision about whether to buy a stock. There are several stock recommendation web services that you trust, but depending on daily load, each service can end up being slow at different times. You can use the method to receive a notification when any operation completes: ```csharp var recommendations = new List>() @@ -273,9 +273,9 @@ Task recommendation = await Task.WhenAny(recommendations); if (await recommendation) BuyStock(symbol); ``` - Unlike , which returns the unwrapped results of all tasks that completed successfully, returns the task that completed. If a task fails, it's important to know that it failed, and if a task succeeds, it's important to know which task the return value is associated with. Therefore, you need to access the result of the returned task, or further await it, as this example shows. + Unlike , which returns the unwrapped results of all tasks that completed successfully, returns the task that completed. If a task fails, it's important to know that it failed, and if a task succeeds, it's important to know which task the return value is associated with. Therefore, you need to access the result of the returned task, or further await it, as this example shows. - As with , you have to be able to accommodate exceptions. Because you receive the completed task back, you can await the returned task to have errors propagated, and `try/catch` them appropriately; for example: + As with , you have to be able to accommodate exceptions. Because you receive the completed task back, you can await the returned task to have errors propagated, and `try/catch` them appropriately; for example: ```csharp Task [] recommendations = …; @@ -294,7 +294,7 @@ while(recommendations.Count > 0) } ``` - Additionally, even if a first task completes successfully, subsequent tasks may fail. At this point, you have several options for dealing with exceptions: You can wait until all the launched tasks have completed, in which case you can use the method, or you can decide that all exceptions are important and must be logged. For this, you can use continuations to receive a notification when tasks have completed asynchronously: + Additionally, even if a first task completes successfully, subsequent tasks may fail. At this point, you have several options for dealing with exceptions: You can wait until all the launched tasks have completed, in which case you can use the method, or you can decide that all exceptions are important and must be logged. For this, you can use continuations to receive a notification when tasks have completed asynchronously: ```csharp foreach(Task recommendation in recommendations) @@ -483,13 +483,13 @@ public async void btnRun_Click(object sender, EventArgs e) } ``` - Another example of early bailout involves using the method in conjunction with the method, as discussed in the next section. + Another example of early bailout involves using the method in conjunction with the method, as discussed in the next section. ### Task.Delay - You can use the method to introduce pauses into an asynchronous method's execution. This is useful for many kinds of functionality, including building polling loops and delaying the handling of user input for a predetermined period of time. The method can also be useful in combination with for implementing time-outs on awaits. + You can use the method to introduce pauses into an asynchronous method's execution. This is useful for many kinds of functionality, including building polling loops and delaying the handling of user input for a predetermined period of time. The method can also be useful in combination with for implementing time-outs on awaits. - If a task that's part of a larger asynchronous operation (for example, an ASP.NET web service) takes too long to complete, the overall operation could suffer, especially if it fails to ever complete. For this reason, it's important to be able to time out when waiting on an asynchronous operation. The synchronous , , and methods accept time-out values, but the corresponding / and the previously mentioned / methods do not. Instead, you can use and in combination to implement a time-out. + If a task that's part of a larger asynchronous operation (for example, an ASP.NET web service) takes too long to complete, the overall operation could suffer, especially if it fails to ever complete. For this reason, it's important to be able to time out when waiting on an asynchronous operation. The synchronous , , and methods accept time-out values, but the corresponding / and the previously mentioned / methods do not. Instead, you can use and in combination to implement a time-out. For example, in your UI application, let's say that you want to download an image and disable the UI while the image is downloading. However, if the download takes too long, you want to re-enable the UI and discard the download: @@ -518,7 +518,7 @@ public async void btnDownload_Click(object sender, EventArgs e) } ``` - The same applies to multiple downloads, because returns a task: + The same applies to multiple downloads, because returns a task: ```csharp public async void btnDownload_Click(object sender, RoutedEventArgs e) @@ -645,7 +645,7 @@ double currentPrice = await NeedOnlyOne( ### Interleaved Operations - There is a potential performance problem with using the method to support an interleaving scenario when you're working with large sets of tasks. Every call to results in a continuation being registered with each task. For N number of tasks, this results in O(N2) continuations created over the lifetime of the interleaving operation. If you're working with a large set of tasks, you can use a combinator (`Interleaved` in the following example) to address the performance issue: + There is a potential performance problem with using the method to support an interleaving scenario when you're working with large sets of tasks. Every call to results in a continuation being registered with each task. For N number of tasks, this results in O(N2) continuations created over the lifetime of the interleaving operation. If you're working with a large set of tasks, you can use a combinator (`Interleaved` in the following example) to address the performance issue: ```csharp static IEnumerable> Interleaved(IEnumerable> tasks) @@ -711,11 +711,11 @@ public static Task WhenAllOrFirstException(IEnumerable> tasks) ## Building Task-based Data Structures - In addition to the ability to build custom task-based combinators, having a data structure in and that represents both the results of an asynchronous operation and the necessary synchronization to join with it makes it a powerful type on which to build custom data structures to be used in asynchronous scenarios. + In addition to the ability to build custom task-based combinators, having a data structure in and that represents both the results of an asynchronous operation and the necessary synchronization to join with it makes it a powerful type on which to build custom data structures to be used in asynchronous scenarios. ### AsyncCache - One important aspect of a task is that it may be handed out to multiple consumers, all of whom may await it, register continuations with it, get its result or exceptions (in the case of ), and so on. This makes and perfectly suited to be used in an asynchronous caching infrastructure. Here's an example of a small but powerful asynchronous cache built on top of : + One important aspect of a task is that it may be handed out to multiple consumers, all of whom may await it, register continuations with it, get its result or exceptions (in the case of ), and so on. This makes and perfectly suited to be used in an asynchronous caching infrastructure. Here's an example of a small but powerful asynchronous cache built on top of : ```csharp public class AsyncCache @@ -742,7 +742,7 @@ public class AsyncCache } ``` - The [AsyncCache\](https://devblogs.microsoft.com/pfxteam/parallelextensionsextras-tour-12-asynccache/) class accepts as a delegate to its constructor a function that takes a `TKey` and returns a . Any previously accessed values from the cache are stored in the internal dictionary, and the `AsyncCache` ensures that only one task is generated per key, even if the cache is accessed concurrently. + The [AsyncCache\](https://devblogs.microsoft.com/pfxteam/parallelextensionsextras-tour-12-asynccache/) class accepts as a delegate to its constructor a function that takes a `TKey` and returns a . Any previously accessed values from the cache are stored in the internal dictionary, and the `AsyncCache` ensures that only one task is generated per key, even if the cache is accessed concurrently. For example, you can build a cache for downloaded web pages: @@ -828,7 +828,7 @@ private static void Produce(int data) } ``` -The namespace includes the type, which you can use in a similar manner, but without having to build a custom collection type: +The namespace includes the type, which you can use in a similar manner, but without having to build a custom collection type: ```csharp private static BufferBlock m_data = …; diff --git a/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview.md b/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview.md index b4cfa60cee0fb..7b043365fd753 100644 --- a/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview.md +++ b/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview.md @@ -2,10 +2,10 @@ title: "Event-based Asynchronous Pattern Overview" description: Review Event-based Asynchronous Patterns (EAPs) in .NET, which make available the advantages of multithreaded applications but hide some design complexities. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "Event-based Asynchronous Pattern" - "ProgressChangedEventArgs class" - "BackgroundWorker component" @@ -19,119 +19,119 @@ ms.assetid: 792aa8da-918b-458e-b154-9836b97735f3 --- # Event-based Asynchronous Pattern Overview -Applications that perform many tasks simultaneously, yet remain responsive to user interaction, often require a design that uses multiple threads. The namespace provides all the tools necessary to create high-performance multithreaded applications, but using these tools effectively requires significant experience with multithreaded software engineering. For relatively simple multithreaded applications, the component provides a straightforward solution. For more sophisticated asynchronous applications, consider implementing a class that adheres to the Event-based Asynchronous Pattern. - - The Event-based Asynchronous Pattern makes available the advantages of multithreaded applications while hiding many of the complex issues inherent in multithreaded design. Using a class that supports this pattern can allow you to: - -- Perform time-consuming tasks, such as downloads and database operations, "in the background," without interrupting your application. - -- Execute multiple operations simultaneously, receiving notifications when each completes. - -- Wait for resources to become available without stopping ("blocking") your application. - -- Communicate with pending asynchronous operations using the familiar events-and-delegates model. For more information on using event handlers and delegates, see [Events](../events/index.md). - - A class that supports the Event-based Asynchronous Pattern will have one or more methods named _MethodName_**Async**. These methods may mirror synchronous versions, which perform the same operation on the current thread. The class may also have a _MethodName_**Completed** event and it may have a _MethodName_**AsyncCancel** (or simply **CancelAsync**) method. - - is a typical component that supports the Event-based Asynchronous Pattern. You can download an image synchronously by calling its method, but if the image is large, or if the network connection is slow, your application will stop responding until the download operation is completed and the call to returns. - - If you want your application to keep running while the image is loading, you can call the method and handle the event, just as you would handle any other event. When you call the method, your application will continue to run while the download proceeds on a separate thread ("in the background"). Your event handler will be called when the image-loading operation is complete, and your event handler can examine the parameter to determine if the download completed successfully. - - The Event-based Asynchronous Pattern requires that an asynchronous operation can be canceled, and the control supports this requirement with its method. Calling submits a request to stop the pending download, and when the task is canceled, the event is raised. - +Applications that perform many tasks simultaneously, yet remain responsive to user interaction, often require a design that uses multiple threads. The namespace provides all the tools necessary to create high-performance multithreaded applications, but using these tools effectively requires significant experience with multithreaded software engineering. For relatively simple multithreaded applications, the component provides a straightforward solution. For more sophisticated asynchronous applications, consider implementing a class that adheres to the Event-based Asynchronous Pattern. + + The Event-based Asynchronous Pattern makes available the advantages of multithreaded applications while hiding many of the complex issues inherent in multithreaded design. Using a class that supports this pattern can allow you to: + +- Perform time-consuming tasks, such as downloads and database operations, "in the background," without interrupting your application. + +- Execute multiple operations simultaneously, receiving notifications when each completes. + +- Wait for resources to become available without stopping ("blocking") your application. + +- Communicate with pending asynchronous operations using the familiar events-and-delegates model. For more information on using event handlers and delegates, see [Events](../events/index.md). + + A class that supports the Event-based Asynchronous Pattern will have one or more methods named _MethodName_**Async**. These methods may mirror synchronous versions, which perform the same operation on the current thread. The class may also have a _MethodName_**Completed** event and it may have a _MethodName_**AsyncCancel** (or simply **CancelAsync**) method. + + is a typical component that supports the Event-based Asynchronous Pattern. You can download an image synchronously by calling its method, but if the image is large, or if the network connection is slow, your application will stop responding until the download operation is completed and the call to returns. + + If you want your application to keep running while the image is loading, you can call the method and handle the event, just as you would handle any other event. When you call the method, your application will continue to run while the download proceeds on a separate thread ("in the background"). Your event handler will be called when the image-loading operation is complete, and your event handler can examine the parameter to determine if the download completed successfully. + + The Event-based Asynchronous Pattern requires that an asynchronous operation can be canceled, and the control supports this requirement with its method. Calling submits a request to stop the pending download, and when the task is canceled, the event is raised. + > [!CAUTION] -> It is possible that the download will finish just as the request is made, so may not reflect the request to cancel. This is called a *race condition* and is a common issue in multithreaded programming. For more information on issues in multithreaded programming, see [Managed Threading Best Practices](../threading/managed-threading-best-practices.md). - -## Characteristics of the Event-based Asynchronous Pattern - - The Event-based Asynchronous Pattern may take several forms, depending on the complexity of the operations supported by a particular class. The simplest classes may have a single _MethodName_**Async** method and a corresponding _MethodName_**Completed** event. More complex classes may have several _MethodName_**Async** methods, each with a corresponding _MethodName_**Completed** event, as well as synchronous versions of these methods. Classes can optionally support cancellation, progress reporting, and incremental results for each asynchronous method. - - An asynchronous method may also support multiple pending calls (multiple concurrent invocations), allowing your code to call it any number of times before it completes other pending operations. Correctly handling this situation may require your application to track the completion of each operation. - -### Examples of the Event-based Asynchronous Pattern - - The and components represent simple implementations of the Event-based Asynchronous Pattern. The and components represent more complex implementations of the Event-based Asynchronous Pattern. - - Below is an example class declaration that conforms to the pattern: - -```vb -Public Class AsyncExample - ' Synchronous methods. +> It is possible that the download will finish just as the request is made, so may not reflect the request to cancel. This is called a *race condition* and is a common issue in multithreaded programming. For more information on issues in multithreaded programming, see [Managed Threading Best Practices](../threading/managed-threading-best-practices.md). + +## Characteristics of the Event-based Asynchronous Pattern + + The Event-based Asynchronous Pattern may take several forms, depending on the complexity of the operations supported by a particular class. The simplest classes may have a single _MethodName_**Async** method and a corresponding _MethodName_**Completed** event. More complex classes may have several _MethodName_**Async** methods, each with a corresponding _MethodName_**Completed** event, as well as synchronous versions of these methods. Classes can optionally support cancellation, progress reporting, and incremental results for each asynchronous method. + + An asynchronous method may also support multiple pending calls (multiple concurrent invocations), allowing your code to call it any number of times before it completes other pending operations. Correctly handling this situation may require your application to track the completion of each operation. + +### Examples of the Event-based Asynchronous Pattern + + The and components represent simple implementations of the Event-based Asynchronous Pattern. The and components represent more complex implementations of the Event-based Asynchronous Pattern. + + Below is an example class declaration that conforms to the pattern: + +```vb +Public Class AsyncExample + ' Synchronous methods. Public Function Method1(ByVal param As String) As Integer Public Sub Method2(ByVal param As Double) - - ' Asynchronous methods. + + ' Asynchronous methods. Overloads Public Sub Method1Async(ByVal param As String) Overloads Public Sub Method1Async(ByVal param As String, ByVal userState As Object) - Public Event Method1Completed As Method1CompletedEventHandler - + Public Event Method1Completed As Method1CompletedEventHandler + Overloads Public Sub Method2Async(ByVal param As Double) Overloads Public Sub Method2Async(ByVal param As Double, ByVal userState As Object) - Public Event Method2Completed As Method2CompletedEventHandler - + Public Event Method2Completed As Method2CompletedEventHandler + Public Sub CancelAsync(ByVal userState As Object) - - Public ReadOnly Property IsBusy () As Boolean - - ' Class implementation not shown. -End Class -``` - -```csharp -public class AsyncExample -{ - // Synchronous methods. - public int Method1(string param); - public void Method2(double param); - - // Asynchronous methods. - public void Method1Async(string param); - public void Method1Async(string param, object userState); - public event Method1CompletedEventHandler Method1Completed; - - public void Method2Async(double param); - public void Method2Async(double param, object userState); - public event Method2CompletedEventHandler Method2Completed; - - public void CancelAsync(object userState); - - public bool IsBusy { get; } - - // Class implementation not shown. -} -``` - - The fictitious `AsyncExample` class has two methods, both of which support synchronous and asynchronous invocations. The synchronous overloads behave like any method call and execute the operation on the calling thread; if the operation is time-consuming, there may be a noticeable delay before the call returns. The asynchronous overloads will start the operation on another thread and then return immediately, allowing the calling thread to continue while the operation executes "in the background." - -### Asynchronous Method Overloads - - There are potentially two overloads for the asynchronous operations: single-invocation and multiple-invocation. You can distinguish these two forms by their method signatures: the multiple-invocation form has an extra parameter called `userState`. This form makes it possible for your code to call `Method1Async(string param, object userState)` multiple times without waiting for any pending asynchronous operations to finish. If, on the other hand, you try to call `Method1Async(string param)` before a previous invocation has completed, the method raises an . - - The `userState` parameter for the multiple-invocation overloads allows you to distinguish among asynchronous operations. You provide a unique value (for example, a GUID or hash code) for each call to `Method1Async(string param, object userState)`, and when each operation is completed, your event handler can determine which instance of the operation raised the completion event. - -### Tracking Pending Operations - - If you use the multiple-invocation overloads, your code will need to keep track of the `userState` objects (task IDs) for pending tasks. For each call to `Method1Async(string param, object userState)`, you will typically generate a new, unique `userState` object and add it to a collection. When the task corresponding to this `userState` object raises the completion event, your completion method implementation will examine and remove it from your collection. Used this way, the `userState` parameter takes the role of a task ID. - + + Public ReadOnly Property IsBusy () As Boolean + + ' Class implementation not shown. +End Class +``` + +```csharp +public class AsyncExample +{ + // Synchronous methods. + public int Method1(string param); + public void Method2(double param); + + // Asynchronous methods. + public void Method1Async(string param); + public void Method1Async(string param, object userState); + public event Method1CompletedEventHandler Method1Completed; + + public void Method2Async(double param); + public void Method2Async(double param, object userState); + public event Method2CompletedEventHandler Method2Completed; + + public void CancelAsync(object userState); + + public bool IsBusy { get; } + + // Class implementation not shown. +} +``` + + The fictitious `AsyncExample` class has two methods, both of which support synchronous and asynchronous invocations. The synchronous overloads behave like any method call and execute the operation on the calling thread; if the operation is time-consuming, there may be a noticeable delay before the call returns. The asynchronous overloads will start the operation on another thread and then return immediately, allowing the calling thread to continue while the operation executes "in the background." + +### Asynchronous Method Overloads + + There are potentially two overloads for the asynchronous operations: single-invocation and multiple-invocation. You can distinguish these two forms by their method signatures: the multiple-invocation form has an extra parameter called `userState`. This form makes it possible for your code to call `Method1Async(string param, object userState)` multiple times without waiting for any pending asynchronous operations to finish. If, on the other hand, you try to call `Method1Async(string param)` before a previous invocation has completed, the method raises an . + + The `userState` parameter for the multiple-invocation overloads allows you to distinguish among asynchronous operations. You provide a unique value (for example, a GUID or hash code) for each call to `Method1Async(string param, object userState)`, and when each operation is completed, your event handler can determine which instance of the operation raised the completion event. + +### Tracking Pending Operations + + If you use the multiple-invocation overloads, your code will need to keep track of the `userState` objects (task IDs) for pending tasks. For each call to `Method1Async(string param, object userState)`, you will typically generate a new, unique `userState` object and add it to a collection. When the task corresponding to this `userState` object raises the completion event, your completion method implementation will examine and remove it from your collection. Used this way, the `userState` parameter takes the role of a task ID. + > [!NOTE] -> You must be careful to provide a unique value for `userState` in your calls to multiple-invocation overloads. Non-unique task IDs will cause the asynchronous class throw an . - -### Canceling Pending Operations - - It is important to be able to cancel asynchronous operations at any time before their completion. Classes that implement the Event-based Asynchronous Pattern will have a `CancelAsync` method (if there is only one asynchronous method) or a _MethodName_**AsyncCancel** method (if there are multiple asynchronous methods). - - Methods that allow multiple invocations take a `userState` parameter, which can be used to track the lifetime of each task. `CancelAsync` takes a `userState` parameter, which allows you to cancel particular pending tasks. - - Methods that support only a single pending operation at a time, like `Method1Async(string param)`, are not cancelable. - -### Receiving Progress Updates and Incremental Results - - A class that adheres to the Event-based Asynchronous Pattern may optionally provide an event for tracking progress and incremental results. This will typically be named `ProgressChanged` or _MethodName_**ProgressChanged**, and its corresponding event handler will take a parameter. - - The event handler for the `ProgressChanged` event can examine the property to determine what percentage of an asynchronous task has been completed. This property will range from 0 to 100, and it can be used to update the property of a . If multiple asynchronous operations are pending, you can use the property to distinguish which operation is reporting progress. - - Some classes may report incremental results as asynchronous operations proceed. These results will be stored in a class that derives from and they will appear as properties in the derived class. You can access these results in the event handler for the `ProgressChanged` event, just as you would access the property. If multiple asynchronous operations are pending, you can use the property to distinguish which operation is reporting incremental results. - +> You must be careful to provide a unique value for `userState` in your calls to multiple-invocation overloads. Non-unique task IDs will cause the asynchronous class throw an . + +### Canceling Pending Operations + + It is important to be able to cancel asynchronous operations at any time before their completion. Classes that implement the Event-based Asynchronous Pattern will have a `CancelAsync` method (if there is only one asynchronous method) or a _MethodName_**AsyncCancel** method (if there are multiple asynchronous methods). + + Methods that allow multiple invocations take a `userState` parameter, which can be used to track the lifetime of each task. `CancelAsync` takes a `userState` parameter, which allows you to cancel particular pending tasks. + + Methods that support only a single pending operation at a time, like `Method1Async(string param)`, are not cancelable. + +### Receiving Progress Updates and Incremental Results + + A class that adheres to the Event-based Asynchronous Pattern may optionally provide an event for tracking progress and incremental results. This will typically be named `ProgressChanged` or _MethodName_**ProgressChanged**, and its corresponding event handler will take a parameter. + + The event handler for the `ProgressChanged` event can examine the property to determine what percentage of an asynchronous task has been completed. This property will range from 0 to 100, and it can be used to update the property of a . If multiple asynchronous operations are pending, you can use the property to distinguish which operation is reporting progress. + + Some classes may report incremental results as asynchronous operations proceed. These results will be stored in a class that derives from and they will appear as properties in the derived class. You can access these results in the event handler for the `ProgressChanged` event, just as you would access the property. If multiple asynchronous operations are pending, you can use the property to distinguish which operation is reporting incremental results. + ## See also - diff --git a/docs/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern.md index b02674535d107..d8ca78b002e85 100644 --- a/docs/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern.md @@ -48,7 +48,7 @@ The following list describes the features of the Event-based Asynchronous Patter Consider implementing the Event-based Asynchronous Pattern when: -- Clients of your class do not need and objects available for asynchronous operations, meaning that polling and or will need to be built up by the client. +- Clients of your class do not need and objects available for asynchronous operations, meaning that polling and or will need to be built up by the client. - You want asynchronous operations to be managed by the client with the familiar event/delegate model. diff --git a/docs/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern.md index 7d0eeae0bcb5c..563c447bee263 100644 --- a/docs/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern.md @@ -2,10 +2,10 @@ title: "Implementing the Task-based Asynchronous Pattern" description: This article explains how to implement the Task-based Asynchronous Pattern. You can use it to implement compute-bound and I/O-bound asynchronous operations. ms.date: "06/14/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "asynchronous design patterns, .NET" - "TAP, .NET support for" - "Task-based Asynchronous Pattern, .NET support for" @@ -20,11 +20,11 @@ You can implement the Task-based Asynchronous Pattern (TAP) in three ways: by us ### Using the compilers -Starting with .NET Framework 4.5, any method that is attributed with the `async` keyword (`Async` in Visual Basic) is considered an asynchronous method, and the C# and Visual Basic compilers perform the necessary transformations to implement the method asynchronously by using TAP. An asynchronous method should return either a or a object. For the latter, the body of the function should return a `TResult`, and the compiler ensures that this result is made available through the resulting task object. Similarly, any exceptions that go unhandled within the body of the method are marshalled to the output task and cause the resulting task to end in the state. The exception to this rule is when an (or derived type) goes unhandled, in which case the resulting task ends in the state. +Starting with .NET Framework 4.5, any method that is attributed with the `async` keyword (`Async` in Visual Basic) is considered an asynchronous method, and the C# and Visual Basic compilers perform the necessary transformations to implement the method asynchronously by using TAP. An asynchronous method should return either a or a object. For the latter, the body of the function should return a `TResult`, and the compiler ensures that this result is made available through the resulting task object. Similarly, any exceptions that go unhandled within the body of the method are marshalled to the output task and cause the resulting task to end in the state. The exception to this rule is when an (or derived type) goes unhandled, in which case the resulting task ends in the state. ### Generating TAP methods manually -You may implement the TAP pattern manually for better control over implementation. The compiler relies on the public surface area exposed from the namespace and supporting types in the namespace. To implement the TAP yourself, you create a object, perform the asynchronous operation, and when it completes, call the , , or method, or the `Try` version of one of these methods. When you implement a TAP method manually, you must complete the resulting task when the represented asynchronous operation completes. For example: +You may implement the TAP pattern manually for better control over implementation. The compiler relies on the public surface area exposed from the namespace and supporting types in the namespace. To implement the TAP yourself, you create a object, perform the asynchronous operation, and when it completes, call the , , or method, or the `Try` version of one of these methods. When you implement a TAP method manually, you must complete the resulting task when the represented asynchronous operation completes. For example: [!code-csharp[Conceptual.TAP_Patterns#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap_patterns/cs/patterns1.cs#1)] [!code-vb[Conceptual.TAP_Patterns#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap_patterns/vb/patterns1.vb#1)] @@ -48,15 +48,15 @@ The class is ide You can generate compute-bound tasks in the following ways: -- In .NET Framework 4.5 and later versions (including .NET Core and .NET 5+), use the static method as a shortcut to . You may use to easily launch a compute-bound task that targets the thread pool. This is the preferred mechanism for launching a compute-bound task. Use `StartNew` directly only when you want more fine-grained control over the task. +- In .NET Framework 4.5 and later versions (including .NET Core and .NET 5+), use the static method as a shortcut to . You may use to easily launch a compute-bound task that targets the thread pool. This is the preferred mechanism for launching a compute-bound task. Use `StartNew` directly only when you want more fine-grained control over the task. -- In .NET Framework 4, use the method, which accepts a delegate (typically an or a ) to be executed asynchronously. If you provide an delegate, the method returns a object that represents the asynchronous execution of that delegate. If you provide a delegate, the method returns a object. Overloads of the method accept a cancellation token (), task creation options (), and a task scheduler (), all of which provide fine-grained control over the scheduling and execution of the task. A factory instance that targets the current task scheduler is available as a static property () of the class; for example: `Task.Factory.StartNew(…)`. +- In .NET Framework 4, use the method, which accepts a delegate (typically an or a ) to be executed asynchronously. If you provide an delegate, the method returns a object that represents the asynchronous execution of that delegate. If you provide a delegate, the method returns a object. Overloads of the method accept a cancellation token (), task creation options (), and a task scheduler (), all of which provide fine-grained control over the scheduling and execution of the task. A factory instance that targets the current task scheduler is available as a static property () of the class; for example: `Task.Factory.StartNew(…)`. - Use the constructors of the `Task` type and the `Start` method if you want to generate and schedule the task separately. Public methods must only return tasks that have already been started. -- Use the overloads of the method. This method creates a new task that is scheduled when another task completes. Some of the overloads accept a cancellation token, continuation options, and a task scheduler for better control over the scheduling and execution of the continuation task. +- Use the overloads of the method. This method creates a new task that is scheduled when another task completes. Some of the overloads accept a cancellation token, continuation options, and a task scheduler for better control over the scheduling and execution of the continuation task. -- Use the and methods. These methods create a new task that is scheduled when all or any of a supplied set of tasks completes. These methods also provide overloads to control the scheduling and execution of these tasks. +- Use the and methods. These methods create a new task that is scheduled when all or any of a supplied set of tasks completes. These methods also provide overloads to control the scheduling and execution of these tasks. In compute-bound tasks, the system can prevent the execution of a scheduled task if it receives a cancellation request before it starts running the task. As such, if you provide a cancellation token ( object), you can pass that token to the asynchronous code that monitors the token. You can also provide the token to one of the previously mentioned methods such as `StartNew` or `Run` so that the `Task` runtime may also monitor the token. @@ -75,19 +75,19 @@ If another exception goes unhandled within the body of the task, the task ends i ### I/O-bound tasks -To create a task that should not be directly backed by a thread for the entirety of its execution, use the type. This type exposes a property that returns an associated instance. The life cycle of this task is controlled by methods such as , , , and their `TrySet` variants. +To create a task that should not be directly backed by a thread for the entirety of its execution, use the type. This type exposes a property that returns an associated instance. The life cycle of this task is controlled by methods such as , , , and their `TrySet` variants. -Let's say that you want to create a task that will complete after a specified period of time. For example, you may want to delay an activity in the user interface. The class already provides the ability to asynchronously invoke a delegate after a specified period of time, and by using you can put a front on the timer, for example: +Let's say that you want to create a task that will complete after a specified period of time. For example, you may want to delay an activity in the user interface. The class already provides the ability to asynchronously invoke a delegate after a specified period of time, and by using you can put a front on the timer, for example: [!code-csharp[Conceptual.TAP_Patterns#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap_patterns/cs/patterns1.cs#4)] [!code-vb[Conceptual.TAP_Patterns#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap_patterns/vb/patterns1.vb#4)] -The method is provided for this purpose, and you can use it inside another asynchronous method, for example, to implement an asynchronous polling loop: +The method is provided for this purpose, and you can use it inside another asynchronous method, for example, to implement an asynchronous polling loop: [!code-csharp[Conceptual.TAP_Patterns#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap_patterns/cs/patterns1.cs#5)] [!code-vb[Conceptual.TAP_Patterns#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap_patterns/vb/patterns1.vb#5)] -The class doesn't have a non-generic counterpart. However, derives from , so you can use the generic object for I/O-bound methods that simply return a task. To do this, you can use a source with a dummy `TResult` ( is a good default choice, but if you're concerned about the user of the downcasting it to a , you can use a private `TResult` type instead). For example, the `Delay` method in the previous example returns the current time along with the resulting offset (`Task`). If such a result value is unnecessary, the method could instead be coded as follows (note the change of return type and the change of argument to ): +The class doesn't have a non-generic counterpart. However, derives from , so you can use the generic object for I/O-bound methods that simply return a task. To do this, you can use a source with a dummy `TResult` ( is a good default choice, but if you're concerned about the user of the downcasting it to a , you can use a private `TResult` type instead). For example, the `Delay` method in the previous example returns the current time along with the resulting offset (`Task`). If such a result value is unnecessary, the method could instead be coded as follows (note the change of return type and the change of argument to ): [!code-csharp[Conceptual.TAP_Patterns#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap_patterns/cs/patterns1.cs#6)] [!code-vb[Conceptual.TAP_Patterns#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap_patterns/vb/patterns1.vb#6)] diff --git a/docs/standard/asynchronous-programming-patterns/interop-with-other-asynchronous-patterns-and-types.md b/docs/standard/asynchronous-programming-patterns/interop-with-other-asynchronous-patterns-and-types.md index 9e36ace4610f5..b30b682db4e71 100644 --- a/docs/standard/asynchronous-programming-patterns/interop-with-other-asynchronous-patterns-and-types.md +++ b/docs/standard/asynchronous-programming-patterns/interop-with-other-asynchronous-patterns-and-types.md @@ -2,10 +2,10 @@ description: "Learn more about: Interop with Other Asynchronous Patterns and Types" title: "Interop with Other Asynchronous Patterns and Types" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "asynchronous design patterns, .NET" - "TAP, .NET support for" - "Task-based Asynchronous Pattern, .NET support for" @@ -19,86 +19,86 @@ A brief history of asynchronous patterns in .NET: - .NET Framework 1.0 introduced the pattern, otherwise known as the [Asynchronous Programming Model (APM)](asynchronous-programming-model-apm.md), or the `Begin/End` pattern. - .NET Framework 2.0 added the [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md). - .NET Framework 4 introduced the [Task-based Asynchronous Pattern (TAP)](task-based-asynchronous-pattern-tap.md), which supersedes both APM and EAP and provides the ability to easily build migration routines from the earlier patterns. - + ## Tasks and the Asynchronous Programming Model (APM) -### From APM to TAP +### From APM to TAP + + Because the [Asynchronous Programming Model (APM)](asynchronous-programming-model-apm.md) pattern is structured, it is quite easy to build a wrapper to expose an APM implementation as a TAP implementation. .NET Framework 4 and later versions include helper routines in the form of method overloads to provide this translation. + + Consider the class and its and methods, which represent the APM counterpart to the synchronous method: - Because the [Asynchronous Programming Model (APM)](asynchronous-programming-model-apm.md) pattern is structured, it is quite easy to build a wrapper to expose an APM implementation as a TAP implementation. .NET Framework 4 and later versions include helper routines in the form of method overloads to provide this translation. - - Consider the class and its and methods, which represent the APM counterpart to the synchronous method: - [!code-csharp[Conceptual.AsyncInterop#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/Stream1.cs#1)] - [!code-vb[Conceptual.AsyncInterop#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/stream1.vb#1)] + [!code-vb[Conceptual.AsyncInterop#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/stream1.vb#1)] [!code-csharp[Conceptual.AsyncInterop#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/Stream1.cs#2)] -[!code-vb[Conceptual.AsyncInterop#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/stream1.vb#2)] +[!code-vb[Conceptual.AsyncInterop#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/stream1.vb#2)] [!code-csharp[Conceptual.AsyncInterop#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/Stream1.cs#3)] -[!code-vb[Conceptual.AsyncInterop#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/stream1.vb#3)] - - You can use the method to implement a TAP wrapper for this operation as follows: - +[!code-vb[Conceptual.AsyncInterop#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/stream1.vb#3)] + + You can use the method to implement a TAP wrapper for this operation as follows: + [!code-csharp[Conceptual.AsyncInterop#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/Wrap1.cs#4)] - [!code-vb[Conceptual.AsyncInterop#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Wrap1.vb#4)] - - This implementation is similar to the following: - + [!code-vb[Conceptual.AsyncInterop#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Wrap1.vb#4)] + + This implementation is similar to the following: + [!code-csharp[Conceptual.AsyncInterop#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/Wrap2.cs#5)] - [!code-vb[Conceptual.AsyncInterop#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Wrap2.vb#5)] - -### From TAP to APM + [!code-vb[Conceptual.AsyncInterop#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Wrap2.vb#5)] + +### From TAP to APM + + If your existing infrastructure expects the APM pattern, you'll also want to take a TAP implementation and use it where an APM implementation is expected. Because tasks can be composed and the class implements , you can use a straightforward helper function to do this. The following code uses an extension of the class, but you can use an almost identical function for non-generic tasks. - If your existing infrastructure expects the APM pattern, you'll also want to take a TAP implementation and use it where an APM implementation is expected. Because tasks can be composed and the class implements , you can use a straightforward helper function to do this. The following code uses an extension of the class, but you can use an almost identical function for non-generic tasks. - [!code-csharp[Conceptual.AsyncInterop#6](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/APM1.cs#6)] - [!code-vb[Conceptual.AsyncInterop#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/APM1.vb#6)] - - Now, consider a case where you have the following TAP implementation: - + [!code-vb[Conceptual.AsyncInterop#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/APM1.vb#6)] + + Now, consider a case where you have the following TAP implementation: + [!code-csharp[Conceptual.AsyncInterop#7](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/APM2.cs#7)] - [!code-vb[Conceptual.AsyncInterop#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/APM2.vb#7)] - - and you want to provide this APM implementation: - + [!code-vb[Conceptual.AsyncInterop#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/APM2.vb#7)] + + and you want to provide this APM implementation: + [!code-csharp[Conceptual.AsyncInterop#8](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/APM2.cs#8)] - [!code-vb[Conceptual.AsyncInterop#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/APM2.vb#8)] + [!code-vb[Conceptual.AsyncInterop#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/APM2.vb#8)] [!code-csharp[Conceptual.AsyncInterop#9](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/APM2.cs#9)] -[!code-vb[Conceptual.AsyncInterop#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/APM2.vb#9)] - - The following example demonstrates one migration to APM: - +[!code-vb[Conceptual.AsyncInterop#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/APM2.vb#9)] + + The following example demonstrates one migration to APM: + [!code-csharp[Conceptual.AsyncInterop#10](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/APM2.cs#10)] - [!code-vb[Conceptual.AsyncInterop#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/APM2.vb#10)] - -## Tasks and the Event-based Asynchronous Pattern (EAP) + [!code-vb[Conceptual.AsyncInterop#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/APM2.vb#10)] + +## Tasks and the Event-based Asynchronous Pattern (EAP) + + Wrapping an [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md) implementation is more involved than wrapping an APM pattern, because the EAP pattern has more variation and less structure than the APM pattern. To demonstrate, the following code wraps the `DownloadStringAsync` method. `DownloadStringAsync` accepts a URI, raises the `DownloadProgressChanged` event while downloading in order to report multiple statistics on progress, and raises the `DownloadStringCompleted` event when it's done. The final result is a string that contains the contents of the page at the specified URI. - Wrapping an [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md) implementation is more involved than wrapping an APM pattern, because the EAP pattern has more variation and less structure than the APM pattern. To demonstrate, the following code wraps the `DownloadStringAsync` method. `DownloadStringAsync` accepts a URI, raises the `DownloadProgressChanged` event while downloading in order to report multiple statistics on progress, and raises the `DownloadStringCompleted` event when it's done. The final result is a string that contains the contents of the page at the specified URI. - [!code-csharp[Conceptual.AsyncInterop#11](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/EAP1.cs#11)] - [!code-vb[Conceptual.AsyncInterop#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/EAP1.vb#11)] - -## Tasks and Wait Handles - -### From Wait Handles to TAP - - Although wait handles don't implement an asynchronous pattern, advanced developers may use the class and the method for asynchronous notifications when a wait handle is set. You can wrap the method to enable a task-based alternative to any synchronous wait on a wait handle: - + [!code-vb[Conceptual.AsyncInterop#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/EAP1.vb#11)] + +## Tasks and Wait Handles + +### From Wait Handles to TAP + + Although wait handles don't implement an asynchronous pattern, advanced developers may use the class and the method for asynchronous notifications when a wait handle is set. You can wrap the method to enable a task-based alternative to any synchronous wait on a wait handle: + [!code-csharp[Conceptual.AsyncInterop#12](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/Wait1.cs#12)] - [!code-vb[Conceptual.AsyncInterop#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Wait1.vb#12)] - - With this method, you can use existing implementations in asynchronous methods. For example, if you want to throttle the number of asynchronous operations that are executing at any particular time, you can utilize a semaphore (a object). You can throttle to *N* the number of operations that run concurrently by initializing the semaphore's count to *N*, waiting on the semaphore any time you want to perform an operation, and releasing the semaphore when you're done with an operation: - + [!code-vb[Conceptual.AsyncInterop#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Wait1.vb#12)] + + With this method, you can use existing implementations in asynchronous methods. For example, if you want to throttle the number of asynchronous operations that are executing at any particular time, you can utilize a semaphore (a object). You can throttle to *N* the number of operations that run concurrently by initializing the semaphore's count to *N*, waiting on the semaphore any time you want to perform an operation, and releasing the semaphore when you're done with an operation: + [!code-csharp[Conceptual.AsyncInterop#13](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/Semaphore1.cs#13)] - [!code-vb[Conceptual.AsyncInterop#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Semaphore1.vb#13)] - - You can also build an asynchronous semaphore that does not rely on wait handles and instead works completely with tasks. To do this, you can use techniques such as those discussed in [Consuming the Task-based Asynchronous Pattern](consuming-the-task-based-asynchronous-pattern.md) for building data structures on top of . - -### From TAP to Wait Handles - - As previously mentioned, the class implements , and that implementation exposes an property that returns a wait handle that will be set when the completes. You can get a for a as follows: - + [!code-vb[Conceptual.AsyncInterop#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Semaphore1.vb#13)] + + You can also build an asynchronous semaphore that does not rely on wait handles and instead works completely with tasks. To do this, you can use techniques such as those discussed in [Consuming the Task-based Asynchronous Pattern](consuming-the-task-based-asynchronous-pattern.md) for building data structures on top of . + +### From TAP to Wait Handles + + As previously mentioned, the class implements , and that implementation exposes an property that returns a wait handle that will be set when the completes. You can get a for a as follows: + [!code-csharp[Conceptual.AsyncInterop#14](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/Wait1.cs#14)] - [!code-vb[Conceptual.AsyncInterop#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Wait1.vb#14)] - + [!code-vb[Conceptual.AsyncInterop#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Wait1.vb#14)] + ## See also - [Task-based Asynchronous Pattern (TAP)](task-based-asynchronous-pattern-tap.md) diff --git a/docs/standard/asynchronous-programming-patterns/polling-for-the-status-of-an-asynchronous-operation.md b/docs/standard/asynchronous-programming-patterns/polling-for-the-status-of-an-asynchronous-operation.md index 6f1423a6f832f..01d105a1bcf63 100644 --- a/docs/standard/asynchronous-programming-patterns/polling-for-the-status-of-an-asynchronous-operation.md +++ b/docs/standard/asynchronous-programming-patterns/polling-for-the-status-of-an-asynchronous-operation.md @@ -2,10 +2,10 @@ description: "Learn more about: Polling for the Status of an Asynchronous Operation" title: "Polling for the Status of an Asynchronous Operation" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "asynchronous programming, status polling" - "polling asynchronous operation status" - "status information [.NET], asynchronous operations" @@ -13,19 +13,19 @@ ms.assetid: b541af31-dacb-4e20-8847-1b1ff7c35363 --- # Polling for the Status of an Asynchronous Operation -Applications that can do other work while waiting for the results of an asynchronous operation should not block waiting until the operation completes. Use one of the following options to continue executing instructions while waiting for an asynchronous operation to complete: - -- Use the property of the returned by the asynchronous operation's **Begin**_OperationName_ method to determine whether the operation has completed. This approach is known as polling and is demonstrated in this topic. - -- Use an delegate to process the results of the asynchronous operation in a separate thread. For an example that demonstrates this approach, see [Using an AsyncCallback Delegate to End an Asynchronous Operation](using-an-asynccallback-delegate-to-end-an-asynchronous-operation.md). - -## Example +Applications that can do other work while waiting for the results of an asynchronous operation should not block waiting until the operation completes. Use one of the following options to continue executing instructions while waiting for an asynchronous operation to complete: + +- Use the property of the returned by the asynchronous operation's **Begin**_OperationName_ method to determine whether the operation has completed. This approach is known as polling and is demonstrated in this topic. + +- Use an delegate to process the results of the asynchronous operation in a separate thread. For an example that demonstrates this approach, see [Using an AsyncCallback Delegate to End an Asynchronous Operation](using-an-asynccallback-delegate-to-end-an-asynchronous-operation.md). + +## Example + + The following code example demonstrates using asynchronous methods in the class to retrieve Domain Name System information for a user-specified computer. This example starts the asynchronous operation and then prints periods (".") at the console until the operation is complete. Note that **null** (**Nothing** in Visual Basic) is passed for the and parameters because these arguments are not required when using this approach. - The following code example demonstrates using asynchronous methods in the class to retrieve Domain Name System information for a user-specified computer. This example starts the asynchronous operation and then prints periods (".") at the console until the operation is complete. Note that **null** (**Nothing** in Visual Basic) is passed for the and parameters because these arguments are not required when using this approach. - [!code-csharp[AsyncDesignPattern#3](../../../samples/snippets/csharp/VS_Snippets_CLR/AsyncDesignPattern/CS/Async_Poll.cs#3)] - [!code-vb[AsyncDesignPattern#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/AsyncDesignPattern/VB/Async_Poll.vb#3)] - + [!code-vb[AsyncDesignPattern#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/AsyncDesignPattern/VB/Async_Poll.vb#3)] + ## See also - [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md) diff --git a/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md b/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md index 9294746fd0b6c..72cb51553d342 100644 --- a/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md +++ b/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md @@ -2,7 +2,7 @@ title: "Task-based Asynchronous Pattern (TAP): Introduction and overview" description: "Learn about the Task-based Asynchronous Pattern (TAP), and compare it to the legacy patterns: Asynchronous Programming Model (APM) and Event-based Asynchronous Pattern (EAP)." ms.date: 10/22/2025 -dev_langs: +dev_langs: - "csharp" - "vb" helpviewer_keywords: @@ -14,177 +14,177 @@ ai-usage: ai-assisted --- # Task-based asynchronous pattern (TAP) in .NET: Introduction and overview -In .NET, The task-based asynchronous pattern is the recommended asynchronous design pattern for new development. It is based on the and types in the namespace, which are used to represent asynchronous operations. +In .NET, The task-based asynchronous pattern is the recommended asynchronous design pattern for new development. It is based on the and types in the namespace, which are used to represent asynchronous operations. ## Naming, parameters, and return types -TAP uses a single method to represent the initiation and completion of an asynchronous operation. This contrasts with both the Asynchronous Programming Model (APM or `IAsyncResult`) pattern and the Event-based Asynchronous Pattern (EAP). APM requires `Begin` and `End` methods. EAP requires a method that has the `Async` suffix and also requires one or more events, event handler delegate types, and `EventArg`-derived types. Asynchronous methods in TAP include the `Async` suffix after the operation name for methods that return awaitable types, such as , , , and . For example, an asynchronous `Get` operation that returns a `Task` can be named `GetAsync`. If you're adding a TAP method to a class that already contains an EAP method name with the `Async` suffix, use the suffix `TaskAsync` instead. For example, if the class already has a `GetAsync` method, use the name `GetTaskAsync`. If a method starts an asynchronous operation but doesn't return an awaitable type, its name should start with `Begin`, `Start`, or some other verb to suggest that this method doesn't return or throw the result of the operation.   - - A TAP method returns either a or a , based on whether the corresponding synchronous method returns void or a type `TResult`. - - The parameters of a TAP method should match the parameters of its synchronous counterpart and should be provided in the same order. However, `out` and `ref` parameters are exempt from this rule and should be avoided entirely. Any data that has been returned through an `out` or `ref` parameter should instead be returned as part of the `TResult` returned by , and should use a tuple or a custom data structure to accommodate multiple values. Also, consider adding a parameter even if the TAP method's synchronous counterpart doesn't offer one. - - Methods that are devoted exclusively to the creation, manipulation, or combination of tasks (where the asynchronous intent of the method is clear in the method name or in the name of the type to which the method belongs) need not follow this naming pattern; such methods are often referred to as *combinators*. Examples of combinators include and , and are discussed in the [Using the Built-in Task-based Combinators](consuming-the-task-based-asynchronous-pattern.md#combinators) section of the article [Consuming the Task-based Asynchronous Pattern](consuming-the-task-based-asynchronous-pattern.md). - - For examples of how the TAP syntax differs from the syntax used in legacy asynchronous programming patterns such as the Asynchronous Programming Model (APM) and the Event-based Asynchronous Pattern (EAP), see [Asynchronous Programming Patterns](index.md). - -## Initiating an asynchronous operation - - An asynchronous method that is based on TAP can do a small amount of work synchronously, such as validating arguments and initiating the asynchronous operation, before it returns the resulting task. Synchronous work should be kept to the minimum so the asynchronous method can return quickly. Reasons for a quick return include: - -- Asynchronous methods may be invoked from user interface (UI) threads, and any long-running synchronous work could harm the responsiveness of the application. - -- Multiple asynchronous methods may be launched concurrently. Therefore, any long-running work in the synchronous portion of an asynchronous method could delay the initiation of other asynchronous operations, thereby decreasing the benefits of concurrency. - - In some cases, the amount of work required to complete the operation is less than the amount of work required to launch the operation asynchronously. Reading from a stream where the read operation can be satisfied by data that is already buffered in memory is an example of such a scenario. In such cases, the operation may complete synchronously, and may return a task that has already been completed. - -## Exceptions - - An asynchronous method should raise an exception to be thrown out of the asynchronous method call only in response to a usage error. Usage errors should never occur in production code. For example, if passing a null reference (`Nothing` in Visual Basic) as one of the method's arguments causes an error state (usually represented by an exception), you can modify the calling code to ensure that a null reference is never passed. For all other errors, exceptions that occur when an asynchronous method is running should be assigned to the returned task, even if the asynchronous method happens to complete synchronously before the task is returned. Typically, a task contains at most one exception. However, if the task represents multiple operations (for example, ), multiple exceptions may be associated with a single task. - -## Target environment +TAP uses a single method to represent the initiation and completion of an asynchronous operation. This contrasts with both the Asynchronous Programming Model (APM or `IAsyncResult`) pattern and the Event-based Asynchronous Pattern (EAP). APM requires `Begin` and `End` methods. EAP requires a method that has the `Async` suffix and also requires one or more events, event handler delegate types, and `EventArg`-derived types. Asynchronous methods in TAP include the `Async` suffix after the operation name for methods that return awaitable types, such as , , , and . For example, an asynchronous `Get` operation that returns a `Task` can be named `GetAsync`. If you're adding a TAP method to a class that already contains an EAP method name with the `Async` suffix, use the suffix `TaskAsync` instead. For example, if the class already has a `GetAsync` method, use the name `GetTaskAsync`. If a method starts an asynchronous operation but doesn't return an awaitable type, its name should start with `Begin`, `Start`, or some other verb to suggest that this method doesn't return or throw the result of the operation.   + + A TAP method returns either a or a , based on whether the corresponding synchronous method returns void or a type `TResult`. + + The parameters of a TAP method should match the parameters of its synchronous counterpart and should be provided in the same order. However, `out` and `ref` parameters are exempt from this rule and should be avoided entirely. Any data that has been returned through an `out` or `ref` parameter should instead be returned as part of the `TResult` returned by , and should use a tuple or a custom data structure to accommodate multiple values. Also, consider adding a parameter even if the TAP method's synchronous counterpart doesn't offer one. + + Methods that are devoted exclusively to the creation, manipulation, or combination of tasks (where the asynchronous intent of the method is clear in the method name or in the name of the type to which the method belongs) need not follow this naming pattern; such methods are often referred to as *combinators*. Examples of combinators include and , and are discussed in the [Using the Built-in Task-based Combinators](consuming-the-task-based-asynchronous-pattern.md#combinators) section of the article [Consuming the Task-based Asynchronous Pattern](consuming-the-task-based-asynchronous-pattern.md). + + For examples of how the TAP syntax differs from the syntax used in legacy asynchronous programming patterns such as the Asynchronous Programming Model (APM) and the Event-based Asynchronous Pattern (EAP), see [Asynchronous Programming Patterns](index.md). + +## Initiating an asynchronous operation + + An asynchronous method that is based on TAP can do a small amount of work synchronously, such as validating arguments and initiating the asynchronous operation, before it returns the resulting task. Synchronous work should be kept to the minimum so the asynchronous method can return quickly. Reasons for a quick return include: + +- Asynchronous methods may be invoked from user interface (UI) threads, and any long-running synchronous work could harm the responsiveness of the application. + +- Multiple asynchronous methods may be launched concurrently. Therefore, any long-running work in the synchronous portion of an asynchronous method could delay the initiation of other asynchronous operations, thereby decreasing the benefits of concurrency. + + In some cases, the amount of work required to complete the operation is less than the amount of work required to launch the operation asynchronously. Reading from a stream where the read operation can be satisfied by data that is already buffered in memory is an example of such a scenario. In such cases, the operation may complete synchronously, and may return a task that has already been completed. + +## Exceptions + + An asynchronous method should raise an exception to be thrown out of the asynchronous method call only in response to a usage error. Usage errors should never occur in production code. For example, if passing a null reference (`Nothing` in Visual Basic) as one of the method's arguments causes an error state (usually represented by an exception), you can modify the calling code to ensure that a null reference is never passed. For all other errors, exceptions that occur when an asynchronous method is running should be assigned to the returned task, even if the asynchronous method happens to complete synchronously before the task is returned. Typically, a task contains at most one exception. However, if the task represents multiple operations (for example, ), multiple exceptions may be associated with a single task. + +## Target environment When you implement a TAP method, you can determine where asynchronous execution occurs. You may choose to execute the workload on the thread pool, implement it by using asynchronous I/O (without being bound to a thread for the majority of the operation's execution), run it on a specific thread (such as the UI thread), or use any number of potential contexts. A TAP method may even have nothing to execute, and may just return a that represents the occurrence of a condition elsewhere in the system (for example, a task that represents data arriving at a queued data structure). - The caller of the TAP method may block waiting for the TAP method to complete by synchronously waiting on the resulting task, or may run additional (continuation) code when the asynchronous operation completes. The creator of the continuation code has control over where that code executes. You may create the continuation code either explicitly, through methods on the class (for example, ) or implicitly, by using language support built on top of continuations (for example, `await` in C#, `Await` in Visual Basic, `AwaitValue` in F#). - -## Task status + The caller of the TAP method may block waiting for the TAP method to complete by synchronously waiting on the resulting task, or may run additional (continuation) code when the asynchronous operation completes. The creator of the continuation code has control over where that code executes. You may create the continuation code either explicitly, through methods on the class (for example, ) or implicitly, by using language support built on top of continuations (for example, `await` in C#, `Await` in Visual Basic, `AwaitValue` in F#). - The class provides a life cycle for asynchronous operations, and that cycle is represented by the enumeration. To support corner cases of types that derive from and , and to support the separation of construction from scheduling, the class exposes a method. Tasks that are created by the public constructors are referred to as *cold tasks*, because they begin their life cycle in the non-scheduled state and are scheduled only when is called on these instances. +## Task status - All other tasks begin their life cycle in a hot state, which means that the asynchronous operations they represent have already been initiated and their task status is an enumeration value other than . All tasks that are returned from TAP methods must be activated. **If a TAP method internally uses a task's constructor to instantiate the task to be returned, the TAP method must call on the object before returning it.** Consumers of a TAP method may safely assume that the returned task is active and shouldn't try to call on any that is returned from a TAP method. Calling on an active task results in an exception. - -## Cancellation (optional) + The class provides a life cycle for asynchronous operations, and that cycle is represented by the enumeration. To support corner cases of types that derive from and , and to support the separation of construction from scheduling, the class exposes a method. Tasks that are created by the public constructors are referred to as *cold tasks*, because they begin their life cycle in the non-scheduled state and are scheduled only when is called on these instances. + + All other tasks begin their life cycle in a hot state, which means that the asynchronous operations they represent have already been initiated and their task status is an enumeration value other than . All tasks that are returned from TAP methods must be activated. **If a TAP method internally uses a task's constructor to instantiate the task to be returned, the TAP method must call on the object before returning it.** Consumers of a TAP method may safely assume that the returned task is active and shouldn't try to call on any that is returned from a TAP method. Calling on an active task results in an exception. + +## Cancellation (optional) + + In TAP, cancellation is optional for both asynchronous method implementers and asynchronous method consumers. If an operation allows cancellation, it exposes an overload of the asynchronous method that accepts a cancellation token ( instance). By convention, the parameter is named `cancellationToken`. - In TAP, cancellation is optional for both asynchronous method implementers and asynchronous method consumers. If an operation allows cancellation, it exposes an overload of the asynchronous method that accepts a cancellation token ( instance). By convention, the parameter is named `cancellationToken`. - [!code-csharp[Conceptual.TAP#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap/cs/examples1.cs#1)] - [!code-vb[Conceptual.TAP#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap/vb/examples1.vb#1)] - - The asynchronous operation monitors this token for cancellation requests. If it receives a cancellation request, it may choose to honor that request and cancel the operation. If the cancellation request results in work being ended prematurely, the TAP method returns a task that ends in the state; there is no available result and no exception is thrown. The state is considered to be a final (completed) state for a task, along with the and states. Therefore, if a task is in the state, its property returns `true`. When a task completes in the state, any continuations registered with the task are scheduled or executed, unless a continuation option such as was specified to opt out of continuation. Any code that is asynchronously waiting for a canceled task through use of language features continues to run but receives an or an exception derived from it. Code that is blocked synchronously waiting on the task through methods such as and also continue to run with an exception. - + [!code-vb[Conceptual.TAP#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap/vb/examples1.vb#1)] + + The asynchronous operation monitors this token for cancellation requests. If it receives a cancellation request, it may choose to honor that request and cancel the operation. If the cancellation request results in work being ended prematurely, the TAP method returns a task that ends in the state; there is no available result and no exception is thrown. The state is considered to be a final (completed) state for a task, along with the and states. Therefore, if a task is in the state, its property returns `true`. When a task completes in the state, any continuations registered with the task are scheduled or executed, unless a continuation option such as was specified to opt out of continuation. Any code that is asynchronously waiting for a canceled task through use of language features continues to run but receives an or an exception derived from it. Code that is blocked synchronously waiting on the task through methods such as and also continue to run with an exception. + If a cancellation token has requested cancellation before the TAP method that accepts that token is called, the TAP method should return a task. However, if cancellation is requested while the asynchronous operation is running, the asynchronous operation need not accept the cancellation request. The returned task should end in the state only if the operation ends as a result of the cancellation request. If cancellation is requested but a result or an exception is still produced, the task should end in the or state. - For asynchronous methods that want to expose the ability to be canceled first and foremost, you don't have to provide an overload that doesn't accept a cancellation token. For methods that can't be canceled, don't provide overloads that accept a cancellation token; this helps indicate to the caller whether the target method is actually cancelable. Consumer code that doesn't desire cancellation may call a method that accepts a and provide as the argument value. is functionally equivalent to the default . - -## Progress reporting (optional) + For asynchronous methods that want to expose the ability to be canceled first and foremost, you don't have to provide an overload that doesn't accept a cancellation token. For methods that can't be canceled, don't provide overloads that accept a cancellation token; this helps indicate to the caller whether the target method is actually cancelable. Consumer code that doesn't desire cancellation may call a method that accepts a and provide as the argument value. is functionally equivalent to the default . + +## Progress reporting (optional) Some asynchronous operations benefit from providing progress notifications; these are typically used to update a user interface with information about the progress of the asynchronous operation. - In TAP, progress is handled through an interface, which is passed to the asynchronous method as a parameter that is usually named `progress`. Providing the progress interface when the asynchronous method is called helps eliminate race conditions that result from incorrect usage (that is, when event handlers that are incorrectly registered after the operation starts may miss updates). More importantly, the progress interface supports varying implementations of progress, as determined by the consuming code. For example, the consuming code may only care about the latest progress update, or may want to buffer all updates, or may want to invoke an action for each update, or may want to control whether the invocation is marshalled to a particular thread. All these options may be achieved by using a different implementation of the interface, customized to the particular consumer's needs. As with cancellation, TAP implementations should provide an parameter only if the API supports progress notifications. + In TAP, progress is handled through an interface, which is passed to the asynchronous method as a parameter that is usually named `progress`. Providing the progress interface when the asynchronous method is called helps eliminate race conditions that result from incorrect usage (that is, when event handlers that are incorrectly registered after the operation starts may miss updates). More importantly, the progress interface supports varying implementations of progress, as determined by the consuming code. For example, the consuming code may only care about the latest progress update, or may want to buffer all updates, or may want to invoke an action for each update, or may want to control whether the invocation is marshalled to a particular thread. All these options may be achieved by using a different implementation of the interface, customized to the particular consumer's needs. As with cancellation, TAP implementations should provide an parameter only if the API supports progress notifications. + + For example, if the `ReadAsync` method discussed earlier in this article is able to report intermediate progress in the form of the number of bytes read thus far, the progress callback could be an interface: - For example, if the `ReadAsync` method discussed earlier in this article is able to report intermediate progress in the form of the number of bytes read thus far, the progress callback could be an interface: - [!code-csharp[Conceptual.TAP#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap/cs/examples1.cs#2)] - [!code-vb[Conceptual.TAP#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap/vb/examples1.vb#2)] - - If a `FindFilesAsync` method returns a list of all files that meet a particular search pattern, the progress callback could provide an estimate of the percentage of work completed and the current set of partial results. It could provide this information with either a tuple: - + [!code-vb[Conceptual.TAP#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap/vb/examples1.vb#2)] + + If a `FindFilesAsync` method returns a list of all files that meet a particular search pattern, the progress callback could provide an estimate of the percentage of work completed and the current set of partial results. It could provide this information with either a tuple: + [!code-csharp[Conceptual.TAP#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap/cs/examples1.cs#3)] - [!code-vb[Conceptual.TAP#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap/vb/examples1.vb#3)] - - or with a data type that's specific to the API: - + [!code-vb[Conceptual.TAP#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap/vb/examples1.vb#3)] + + or with a data type that's specific to the API: + [!code-csharp[Conceptual.TAP#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap/cs/examples1.cs#4)] - [!code-vb[Conceptual.TAP#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap/vb/examples1.vb#4)] - - In the latter case, the special data type is usually suffixed with `ProgressInfo`. - - If TAP implementations provide overloads that accept a `progress` parameter, they must allow the argument to be `null`, in which case no progress is reported. TAP implementations should report the progress to the object synchronously, which enables the asynchronous method to quickly provide progress. It also allows the consumer of the progress to determine how and where best to handle the information. For example, the progress instance could choose to marshal callbacks and raise events on a captured synchronization context. - -## IProgress\ implementations - -.NET provides the class, which implements . The class is declared as follows: - -```csharp -public class Progress : IProgress -{ - public Progress(); - public Progress(Action handler); - protected virtual void OnReport(T value); - public event EventHandler? ProgressChanged; -} + [!code-vb[Conceptual.TAP#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap/vb/examples1.vb#4)] + + In the latter case, the special data type is usually suffixed with `ProgressInfo`. + + If TAP implementations provide overloads that accept a `progress` parameter, they must allow the argument to be `null`, in which case no progress is reported. TAP implementations should report the progress to the object synchronously, which enables the asynchronous method to quickly provide progress. It also allows the consumer of the progress to determine how and where best to handle the information. For example, the progress instance could choose to marshal callbacks and raise events on a captured synchronization context. + +## IProgress\ implementations + +.NET provides the class, which implements . The class is declared as follows: + +```csharp +public class Progress : IProgress +{ + public Progress(); + public Progress(Action handler); + protected virtual void OnReport(T value); + public event EventHandler? ProgressChanged; +} ``` - - An instance of exposes a event, which is raised every time the asynchronous operation reports a progress update. The event is raised on the object that was captured when the instance was instantiated. If no synchronization context was available, a default context that targets the thread pool is used. Handlers may be registered with this event. A single handler may also be provided to the constructor for convenience, and behaves just like an event handler for the event. Progress updates are raised asynchronously to avoid delaying the asynchronous operation while event handlers are executing. Another implementation could choose to apply different semantics. - -## Choosing the overloads to provide - - If a TAP implementation uses both the optional and optional parameters, it could potentially require up to four overloads: - -```csharp -public Task MethodNameAsync(…); -public Task MethodNameAsync(…, CancellationToken cancellationToken); + + An instance of exposes a event, which is raised every time the asynchronous operation reports a progress update. The event is raised on the object that was captured when the instance was instantiated. If no synchronization context was available, a default context that targets the thread pool is used. Handlers may be registered with this event. A single handler may also be provided to the constructor for convenience, and behaves just like an event handler for the event. Progress updates are raised asynchronously to avoid delaying the asynchronous operation while event handlers are executing. Another implementation could choose to apply different semantics. + +## Choosing the overloads to provide + + If a TAP implementation uses both the optional and optional parameters, it could potentially require up to four overloads: + +```csharp +public Task MethodNameAsync(…); +public Task MethodNameAsync(…, CancellationToken cancellationToken); public Task MethodNameAsync(…, IProgress progress); public Task MethodNameAsync(…, - CancellationToken cancellationToken, IProgress progress); -``` - -```vb -Public MethodNameAsync(…) As Task -Public MethodNameAsync(…, cancellationToken As CancellationToken cancellationToken) As Task + CancellationToken cancellationToken, IProgress progress); +``` + +```vb +Public MethodNameAsync(…) As Task +Public MethodNameAsync(…, cancellationToken As CancellationToken cancellationToken) As Task Public MethodNameAsync(…, progress As IProgress(Of T)) As Task Public MethodNameAsync(…, cancellationToken As CancellationToken, - progress As IProgress(Of T)) As Task -``` - - However, many TAP implementations don't provide cancellation or progress capabilities, so they require a single method: - -```csharp -public Task MethodNameAsync(…); -``` - -```vb -Public MethodNameAsync(…) As Task -``` - - If a TAP implementation supports either cancellation or progress but not both, it may provide two overloads: - -```csharp -public Task MethodNameAsync(…); -public Task MethodNameAsync(…, CancellationToken cancellationToken); - -// … or … - -public Task MethodNameAsync(…); -public Task MethodNameAsync(…, IProgress progress); -``` - -```vb -Public MethodNameAsync(…) As Task -Public MethodNameAsync(…, cancellationToken As CancellationToken) As Task - -' … or … - -Public MethodNameAsync(…) As Task -Public MethodNameAsync(…, progress As IProgress(Of T)) As Task -``` - - If a TAP implementation supports both cancellation and progress, it may expose all four overloads. However, it may provide only the following two: - -```csharp -public Task MethodNameAsync(…); + progress As IProgress(Of T)) As Task +``` + + However, many TAP implementations don't provide cancellation or progress capabilities, so they require a single method: + +```csharp +public Task MethodNameAsync(…); +``` + +```vb +Public MethodNameAsync(…) As Task +``` + + If a TAP implementation supports either cancellation or progress but not both, it may provide two overloads: + +```csharp +public Task MethodNameAsync(…); +public Task MethodNameAsync(…, CancellationToken cancellationToken); + +// … or … + +public Task MethodNameAsync(…); +public Task MethodNameAsync(…, IProgress progress); +``` + +```vb +Public MethodNameAsync(…) As Task +Public MethodNameAsync(…, cancellationToken As CancellationToken) As Task + +' … or … + +Public MethodNameAsync(…) As Task +Public MethodNameAsync(…, progress As IProgress(Of T)) As Task +``` + + If a TAP implementation supports both cancellation and progress, it may expose all four overloads. However, it may provide only the following two: + +```csharp +public Task MethodNameAsync(…); public Task MethodNameAsync(…, - CancellationToken cancellationToken, IProgress progress); -``` - -```vb -Public MethodNameAsync(…) As Task + CancellationToken cancellationToken, IProgress progress); +``` + +```vb +Public MethodNameAsync(…) As Task Public MethodNameAsync(…, cancellationToken As CancellationToken, - progress As IProgress(Of T)) As Task -``` - - To compensate for the two missing intermediate combinations, developers may pass or a default for the `cancellationToken` parameter and `null` for the `progress` parameter. - - If you expect every usage of the TAP method to support cancellation or progress, you may omit the overloads that don't accept the relevant parameter. - - If you decide to expose multiple overloads to make cancellation or progress optional, the overloads that don't support cancellation or progress should behave as if they passed for cancellation or `null` for progress to the overload that does support these. - + progress As IProgress(Of T)) As Task +``` + + To compensate for the two missing intermediate combinations, developers may pass or a default for the `cancellationToken` parameter and `null` for the `progress` parameter. + + If you expect every usage of the TAP method to support cancellation or progress, you may omit the overloads that don't accept the relevant parameter. + + If you decide to expose multiple overloads to make cancellation or progress optional, the overloads that don't support cancellation or progress should behave as if they passed for cancellation or `null` for progress to the overload that does support these. + ## Related articles - -|Title|Description| -|-----------|-----------------| -|[Asynchronous Programming Patterns](index.md)|Introduces the three patterns for performing asynchronous operations: the Task-based Asynchronous Pattern (TAP), the Asynchronous Programming Model (APM), and the Event-based Asynchronous Pattern (EAP).| -|[Implementing the Task-based Asynchronous Pattern](implementing-the-task-based-asynchronous-pattern.md)|Describes how to implement the Task-based Asynchronous Pattern (TAP) in three ways: by using the C# and Visual Basic compilers in Visual Studio, manually, or through a combination of the compiler and manual methods.| -|[Consuming the Task-based Asynchronous Pattern](consuming-the-task-based-asynchronous-pattern.md)|Describes how you can use tasks and callbacks to achieve waiting without blocking.| + +|Title|Description| +|-----------|-----------------| +|[Asynchronous Programming Patterns](index.md)|Introduces the three patterns for performing asynchronous operations: the Task-based Asynchronous Pattern (TAP), the Asynchronous Programming Model (APM), and the Event-based Asynchronous Pattern (EAP).| +|[Implementing the Task-based Asynchronous Pattern](implementing-the-task-based-asynchronous-pattern.md)|Describes how to implement the Task-based Asynchronous Pattern (TAP) in three ways: by using the C# and Visual Basic compilers in Visual Studio, manually, or through a combination of the compiler and manual methods.| +|[Consuming the Task-based Asynchronous Pattern](consuming-the-task-based-asynchronous-pattern.md)|Describes how you can use tasks and callbacks to achieve waiting without blocking.| |[Interop with Other Asynchronous Patterns and Types](interop-with-other-asynchronous-patterns-and-types.md)|Describes how to use the Task-based Asynchronous Pattern (TAP) to implement the Asynchronous Programming Model (APM) and Event-based Asynchronous Pattern (EAP).| diff --git a/docs/standard/asynchronous-programming-patterns/using-an-asynccallback-delegate-and-state-object.md b/docs/standard/asynchronous-programming-patterns/using-an-asynccallback-delegate-and-state-object.md index 0a480f1130cdd..df068484c298b 100644 --- a/docs/standard/asynchronous-programming-patterns/using-an-asynccallback-delegate-and-state-object.md +++ b/docs/standard/asynchronous-programming-patterns/using-an-asynccallback-delegate-and-state-object.md @@ -2,10 +2,10 @@ description: "Learn more about: Using an AsyncCallback Delegate and State Object" title: "Using an AsyncCallback Delegate and State Object" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "asynchronous programming, delegates" - "AsyncCallback delegate, samples" - "asynchronous programming, state objects" @@ -14,15 +14,15 @@ ms.assetid: e3e5475d-c5e9-43f0-928e-d18df8ca1f1d --- # Using an AsyncCallback Delegate and State Object -When you use an delegate to process the results of the asynchronous operation in a separate thread, you can use a state object to pass information between the callbacks and to retrieve a final result. This topic demonstrates that practice by expanding the example in [Using an AsyncCallback Delegate to End an Asynchronous Operation](using-an-asynccallback-delegate-to-end-an-asynchronous-operation.md). - -## Example +When you use an delegate to process the results of the asynchronous operation in a separate thread, you can use a state object to pass information between the callbacks and to retrieve a final result. This topic demonstrates that practice by expanding the example in [Using an AsyncCallback Delegate to End an Asynchronous Operation](using-an-asynccallback-delegate-to-end-an-asynchronous-operation.md). + +## Example + + The following code example demonstrates using asynchronous methods in the class to retrieve Domain Name System (DNS) information for user-specified computers. This example defines and uses the `HostRequest` class to store state information. A `HostRequest` object gets created for each computer name entered by the user. This object is passed to the method. The `ProcessDnsInformation` method is called each time a request completes. The `HostRequest` object is retrieved using the property. The `ProcessDnsInformation` method uses the `HostRequest` object to store the returned by the request or a thrown by the request. When all requests are complete, the application iterates over the `HostRequest` objects and displays the DNS information or error message. - The following code example demonstrates using asynchronous methods in the class to retrieve Domain Name System (DNS) information for user-specified computers. This example defines and uses the `HostRequest` class to store state information. A `HostRequest` object gets created for each computer name entered by the user. This object is passed to the method. The `ProcessDnsInformation` method is called each time a request completes. The `HostRequest` object is retrieved using the property. The `ProcessDnsInformation` method uses the `HostRequest` object to store the returned by the request or a thrown by the request. When all requests are complete, the application iterates over the `HostRequest` objects and displays the DNS information or error message. - [!code-csharp[AsyncDesignPattern#5](../../../samples/snippets/csharp/VS_Snippets_CLR/AsyncDesignPattern/CS/AsyncDelegateWithStateObject.cs#5)] - [!code-vb[AsyncDesignPattern#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/AsyncDesignPattern/VB/AsyncDelegateWithStateObject.vb#5)] - + [!code-vb[AsyncDesignPattern#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/AsyncDesignPattern/VB/AsyncDelegateWithStateObject.vb#5)] + ## See also - [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md) diff --git a/docs/standard/asynchronous-programming-patterns/using-an-asynccallback-delegate-to-end-an-asynchronous-operation.md b/docs/standard/asynchronous-programming-patterns/using-an-asynccallback-delegate-to-end-an-asynchronous-operation.md index 8155d5e42e4c8..6b38ec3a5dba9 100644 --- a/docs/standard/asynchronous-programming-patterns/using-an-asynccallback-delegate-to-end-an-asynchronous-operation.md +++ b/docs/standard/asynchronous-programming-patterns/using-an-asynccallback-delegate-to-end-an-asynchronous-operation.md @@ -2,10 +2,10 @@ description: "Learn more about: Using an AsyncCallback Delegate to End an Asynchronous Operation" title: "Using an AsyncCallback Delegate to End an Asynchronous Operation" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "ending asynchronous operations" - "asynchronous programming, ending operations" - "AsyncCallback delegate" @@ -14,21 +14,21 @@ ms.assetid: 9d97206c-8917-406c-8961-7d0909d84eeb --- # Using an AsyncCallback Delegate to End an Asynchronous Operation -Applications that can do other work while waiting for the results of an asynchronous operation should not block waiting until the operation completes. Use one of the following options to continue executing instructions while waiting for an asynchronous operation to complete: - -- Use an delegate to process the results of the asynchronous operation in a separate thread. This approach is demonstrated in this topic. - -- Use the property of the returned by the asynchronous operation's **Begin**_OperationName_ method to determine whether the operation has completed. For an example that demonstrates this approach, see [Polling for the Status of an Asynchronous Operation](polling-for-the-status-of-an-asynchronous-operation.md). - -## Example - - The following code example demonstrates using asynchronous methods in the class to retrieve Domain Name System (DNS) information for user-specified computers. This example creates an delegate that references the `ProcessDnsInformation` method. This method is called once for each asynchronous request for DNS information. - - Note that the user-specified host is passed to the parameter. For an example that demonstrates defining and using a more complex state object, see [Using an AsyncCallback Delegate and State Object](using-an-asynccallback-delegate-and-state-object.md). - +Applications that can do other work while waiting for the results of an asynchronous operation should not block waiting until the operation completes. Use one of the following options to continue executing instructions while waiting for an asynchronous operation to complete: + +- Use an delegate to process the results of the asynchronous operation in a separate thread. This approach is demonstrated in this topic. + +- Use the property of the returned by the asynchronous operation's **Begin**_OperationName_ method to determine whether the operation has completed. For an example that demonstrates this approach, see [Polling for the Status of an Asynchronous Operation](polling-for-the-status-of-an-asynchronous-operation.md). + +## Example + + The following code example demonstrates using asynchronous methods in the class to retrieve Domain Name System (DNS) information for user-specified computers. This example creates an delegate that references the `ProcessDnsInformation` method. This method is called once for each asynchronous request for DNS information. + + Note that the user-specified host is passed to the parameter. For an example that demonstrates defining and using a more complex state object, see [Using an AsyncCallback Delegate and State Object](using-an-asynccallback-delegate-and-state-object.md). + [!code-csharp[AsyncDesignPattern#4](../../../samples/snippets/csharp/VS_Snippets_CLR/AsyncDesignPattern/CS/AsyncDelegateNoStateObject.cs#4)] - [!code-vb[AsyncDesignPattern#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/AsyncDesignPattern/VB/AsyncDelegateNoState.vb#4)] - + [!code-vb[AsyncDesignPattern#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/AsyncDesignPattern/VB/AsyncDelegateNoState.vb#4)] + ## See also - [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md) diff --git a/docs/standard/attributes/retrieving-information-stored-in-attributes.md b/docs/standard/attributes/retrieving-information-stored-in-attributes.md index b80f885b32e2d..ccc91e76594a1 100644 --- a/docs/standard/attributes/retrieving-information-stored-in-attributes.md +++ b/docs/standard/attributes/retrieving-information-stored-in-attributes.md @@ -14,7 +14,7 @@ ms.topic: how-to --- # Retrieving Information Stored in Attributes -Retrieving a custom attribute is a simple process. First, declare an instance of the attribute you want to retrieve. Then, use the method to initialize the new attribute to the value of the attribute you want to retrieve. Once the new attribute is initialized, you can use its properties to get the values. +Retrieving a custom attribute is a simple process. First, declare an instance of the attribute you want to retrieve. Then, use the method to initialize the new attribute to the value of the attribute you want to retrieve. Once the new attribute is initialized, you can use its properties to get the values. > [!IMPORTANT] > This article describes how to retrieve attributes for code loaded into the execution context. To retrieve attributes for code loaded into the reflection-only context, you must use the class, as shown in [How to: Load Assemblies into the Reflection-Only Context](../../framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context.md). @@ -56,7 +56,7 @@ The attribute was not found. ## Retrieving Multiple Instances of an Attribute Applied to the Same Scope -In the preceding example, the class to inspect and the specific attribute to find are passed to the method. That code works well if only one instance of an attribute is applied on the class level. However, if multiple instances of an attribute are applied on the same class level, the `GetCustomAttribute` method doesn't retrieve all the information. In cases where multiple instances of the same attribute are applied to the same scope, you can use method to place all instances of an attribute into an array. For example, if two instances of `DeveloperAttribute` are applied on the class level of the same class, the `GetAttribute` method can be modified to display the information found in both attributes. To apply multiple attributes on the same level, the attribute must be defined with the `AllowMultiple` property set to `true` in the class. +In the preceding example, the class to inspect and the specific attribute to find are passed to the method. That code works well if only one instance of an attribute is applied on the class level. However, if multiple instances of an attribute are applied on the same class level, the `GetCustomAttribute` method doesn't retrieve all the information. In cases where multiple instances of the same attribute are applied to the same scope, you can use method to place all instances of an attribute into an array. For example, if two instances of `DeveloperAttribute` are applied on the class level of the same class, the `GetAttribute` method can be modified to display the information found in both attributes. To apply multiple attributes on the same level, the attribute must be defined with the `AllowMultiple` property set to `true` in the class. The following code example shows how to use the `GetCustomAttributes` method to create an array that references all instances of `DeveloperAttribute` in any given class. The code then outputs the values of all the attributes to the console. @@ -69,7 +69,7 @@ In the preceding example, the class to inspect and the specific attribute to fin ## Retrieving Multiple Instances of an Attribute Applied to Different Scopes - The and methods don't search an entire class and return all instances of an attribute in that class. Rather, they search only one specified method or member at a time. If you have a class with the same attribute applied to every member and you want to retrieve the values in all the attributes applied to those members, you must supply every method or member individually to `GetCustomAttributes` and `GetCustomAttribute`. + The and methods don't search an entire class and return all instances of an attribute in that class. Rather, they search only one specified method or member at a time. If you have a class with the same attribute applied to every member and you want to retrieve the values in all the attributes applied to those members, you must supply every method or member individually to `GetCustomAttributes` and `GetCustomAttribute`. The following code example takes a class as a parameter and searches for the `DeveloperAttribute` (defined previously) on the class level and on every individual method of that class: @@ -78,7 +78,7 @@ In the preceding example, the class to inspect and the specific attribute to fin If no instances of the `DeveloperAttribute` are found on the method level or class level, the `GetAttribute` method notifies the user that no attributes were found and displays the name of the method or class that doesn't contain the attribute. If an attribute is found, the console displays the `Name`, `Level`, and `Reviewed` fields. - You can use the members of the class to get the individual methods and members in the passed class. This example first queries the `Type` object to get attribute information for the class level. Next, it uses to place instances of all methods into an array of objects to retrieve attribute information for the method level. You can also use the method to check for attributes on the property level or to check for attributes on the constructor level. + You can use the members of the class to get the individual methods and members in the passed class. This example first queries the `Type` object to get attribute information for the class level. Next, it uses to place instances of all methods into an array of objects to retrieve attribute information for the method level. You can also use the method to check for attributes on the property level or to check for attributes on the constructor level. ## Retrieving Attributes from Class Members @@ -93,6 +93,6 @@ The following example demonstrates how to retrieve an attribute applied to a met ## See also - -- -- +- +- - [Attributes](index.md) diff --git a/docs/standard/attributes/writing-custom-attributes.md b/docs/standard/attributes/writing-custom-attributes.md index 9e8fee1df4764..d887432a1ed3b 100644 --- a/docs/standard/attributes/writing-custom-attributes.md +++ b/docs/standard/attributes/writing-custom-attributes.md @@ -53,7 +53,7 @@ To design custom attributes, you don't need to learn many new concepts. If you'r ### Inherited Property - The property indicates whether your attribute can be inherited by classes that are derived from the classes to which your attribute is applied. This property takes either a `true` (the default) or `false` flag. In the following example, `MyAttribute` has a default value of `true`, while `YourAttribute` has an value of `false`: + The property indicates whether your attribute can be inherited by classes that are derived from the classes to which your attribute is applied. This property takes either a `true` (the default) or `false` flag. In the following example, `MyAttribute` has a default value of `true`, while `YourAttribute` has an value of `false`: [!code-csharp[Conceptual.Attributes.Usage#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.attributes.usage/cs/source2.cs#7)] [!code-vb[Conceptual.Attributes.Usage#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.attributes.usage/vb/source2.vb#7)] @@ -70,9 +70,9 @@ To design custom attributes, you don't need to learn many new concepts. If you'r ### AllowMultiple Property - The property indicates whether multiple instances of your attribute can exist on an element. If set to `true`, multiple instances are allowed. If set to `false` (the default), only one instance is allowed. + The property indicates whether multiple instances of your attribute can exist on an element. If set to `true`, multiple instances are allowed. If set to `false` (the default), only one instance is allowed. - In the following example, `MyAttribute` has a default value of `false`, while `YourAttribute` has a value of `true`: + In the following example, `MyAttribute` has a default value of `false`, while `YourAttribute` has a value of `true`: [!code-csharp[Conceptual.Attributes.Usage#11](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.attributes.usage/cs/source2.cs#11)] [!code-vb[Conceptual.Attributes.Usage#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.attributes.usage/vb/source2.vb#11)] @@ -82,7 +82,7 @@ To design custom attributes, you don't need to learn many new concepts. If you'r [!code-csharp[Conceptual.Attributes.Usage#13](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.attributes.usage/cs/source2.cs#13)] [!code-vb[Conceptual.Attributes.Usage#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.attributes.usage/vb/source2.vb#13)] - If both the property and the property are set to `true`, a class that's inherited from another class can inherit an attribute and have another instance of the same attribute applied in the same child class. If is set to `false`, the values of any attributes in the parent class will be overwritten by new instances of the same attribute in the child class. + If both the property and the property are set to `true`, a class that's inherited from another class can inherit an attribute and have another instance of the same attribute applied in the same child class. If is set to `false`, the values of any attributes in the parent class will be overwritten by new instances of the same attribute in the child class. ## Declaring the Attribute Class diff --git a/docs/standard/base-types/anchors-in-regular-expressions.md b/docs/standard/base-types/anchors-in-regular-expressions.md index fa11783a74d01..f104935a512bb 100644 --- a/docs/standard/base-types/anchors-in-regular-expressions.md +++ b/docs/standard/base-types/anchors-in-regular-expressions.md @@ -2,10 +2,10 @@ title: "Anchors in .NET Regular Expressions" description: Learn how to use anchors in regular expression patterns. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "atomic zero-width assertions" - "regular expressions, anchors" - "regular expressions, atomic zero-width assertions" @@ -18,144 +18,144 @@ ms.assetid: 336391f6-2614-499b-8b1b-07a6837108a7 --- # Anchors in Regular Expressions -Anchors, or atomic zero-width assertions, specify a position in the string where a match must occur. When you use an anchor in your search expression, the regular expression engine does not advance through the string or consume characters; it looks for a match in the specified position only. For example, `^` specifies that the match must start at the beginning of a line or string. Therefore, the regular expression `^http:` matches "http:" only when it occurs at the beginning of a line. The following table lists the anchors supported by the regular expressions in .NET. - -|Anchor|Description| -|------------|-----------------| -|`^`|By default, the match must occur at the beginning of the string; in multiline mode, it must occur at the beginning of the line. For more information, see [Start of String or Line](#start-of-string-or-line-).| -|`$`|By default, the match must occur at the end of the string or before `\n` at the end of the string; in multiline mode, it must occur at the end of the line or before `\n` at the end of the line. For more information, see [End of String or Line](#end-of-string-or-line-).| -|`\A`|The match must occur at the beginning of the string only (no multiline support). For more information, see [Start of String Only](#start-of-string-only-a).| -|`\Z`|The match must occur at the end of the string, or before `\n` at the end of the string. For more information, see [End of String or Before Ending Newline](#end-of-string-or-before-ending-newline-z).| -|`\z`|The match must occur at the end of the string only. For more information, see [End of String Only](#end-of-string-only-z).| +Anchors, or atomic zero-width assertions, specify a position in the string where a match must occur. When you use an anchor in your search expression, the regular expression engine does not advance through the string or consume characters; it looks for a match in the specified position only. For example, `^` specifies that the match must start at the beginning of a line or string. Therefore, the regular expression `^http:` matches "http:" only when it occurs at the beginning of a line. The following table lists the anchors supported by the regular expressions in .NET. + +|Anchor|Description| +|------------|-----------------| +|`^`|By default, the match must occur at the beginning of the string; in multiline mode, it must occur at the beginning of the line. For more information, see [Start of String or Line](#start-of-string-or-line-).| +|`$`|By default, the match must occur at the end of the string or before `\n` at the end of the string; in multiline mode, it must occur at the end of the line or before `\n` at the end of the line. For more information, see [End of String or Line](#end-of-string-or-line-).| +|`\A`|The match must occur at the beginning of the string only (no multiline support). For more information, see [Start of String Only](#start-of-string-only-a).| +|`\Z`|The match must occur at the end of the string, or before `\n` at the end of the string. For more information, see [End of String or Before Ending Newline](#end-of-string-or-before-ending-newline-z).| +|`\z`|The match must occur at the end of the string only. For more information, see [End of String Only](#end-of-string-only-z).| |`\G`|The match must start at the position where the previous match ended, or if there was no previous match, at the position in the string where matching started. For more information, see [Contiguous Matches](#contiguous-matches-g).| -|`\b`|The match must occur on a word boundary. For more information, see [Word Boundary](#word-boundary-b).| -|`\B`|The match must not occur on a word boundary. For more information, see [Non-Word Boundary](#non-word-boundary-b).| - -## Start of String or Line: ^ - - By default, the `^` anchor specifies that the following pattern must begin at the first character position of the string. If you use `^` with the option (see [Regular Expression Options](regular-expression-options.md)), the match must occur at the beginning of each line. - - The following example uses the `^` anchor in a regular expression that extracts information about the years during which some professional baseball teams existed. The example calls two overloads of the method: - -- The call to the overload finds only the first substring in the input string that matches the regular expression pattern. - -- The call to the overload with the `options` parameter set to finds all five substrings. - +|`\b`|The match must occur on a word boundary. For more information, see [Word Boundary](#word-boundary-b).| +|`\B`|The match must not occur on a word boundary. For more information, see [Non-Word Boundary](#non-word-boundary-b).| + +## Start of String or Line: ^ + + By default, the `^` anchor specifies that the following pattern must begin at the first character position of the string. If you use `^` with the option (see [Regular Expression Options](regular-expression-options.md)), the match must occur at the beginning of each line. + + The following example uses the `^` anchor in a regular expression that extracts information about the years during which some professional baseball teams existed. The example calls two overloads of the method: + +- The call to the overload finds only the first substring in the input string that matches the regular expression pattern. + +- The call to the overload with the `options` parameter set to finds all five substrings. + [!code-csharp[Conceptual.RegEx.Language.Assertions#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.assertions/cs/startofstring1.cs#1)] - [!code-vb[Conceptual.RegEx.Language.Assertions#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/startofstring1.vb#1)] - - The regular expression pattern `^((\w+(\s?)){2,}),\s(\w+\s\w+),(\s\d{4}(-(\d{4}|present))?,?)+` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`^`|Begin the match at the beginning of the input string (or the beginning of the line if the method is called with the option).| -|`((\w+(\s?)){2,}`|Match one or more word characters followed either by zero or by one space at least two times. This is the first capturing group. This expression also defines a second and third capturing group: The second consists of the captured word, and the third consists of the captured white space.| -|`,\s`|Match a comma followed by a white-space character.| -|`(\w+\s\w+)`|Match one or more word characters followed by a space, followed by one or more word characters. This is the fourth capturing group.| -|`,`|Match a comma.| -|`\s\d{4}`|Match a space followed by four decimal digits.| -|(-(\d{4}|present))?|Match zero or one occurrence of a hyphen followed by four decimal digits or the string "present". This is the sixth capturing group. It also includes a seventh capturing group.| -|`,?`|Match zero or one occurrence of a comma.| + [!code-vb[Conceptual.RegEx.Language.Assertions#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/startofstring1.vb#1)] + + The regular expression pattern `^((\w+(\s?)){2,}),\s(\w+\s\w+),(\s\d{4}(-(\d{4}|present))?,?)+` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`^`|Begin the match at the beginning of the input string (or the beginning of the line if the method is called with the option).| +|`((\w+(\s?)){2,}`|Match one or more word characters followed either by zero or by one space at least two times. This is the first capturing group. This expression also defines a second and third capturing group: The second consists of the captured word, and the third consists of the captured white space.| +|`,\s`|Match a comma followed by a white-space character.| +|`(\w+\s\w+)`|Match one or more word characters followed by a space, followed by one or more word characters. This is the fourth capturing group.| +|`,`|Match a comma.| +|`\s\d{4}`|Match a space followed by four decimal digits.| +|(-(\d{4}|present))?|Match zero or one occurrence of a hyphen followed by four decimal digits or the string "present". This is the sixth capturing group. It also includes a seventh capturing group.| +|`,?`|Match zero or one occurrence of a comma.| |(\s\d{4}(-(\d{4}|present))?,?)+|Match one or more occurrences of the following: a space, four decimal digits, zero or one occurrence of a hyphen followed by four decimal digits or the string "present", and zero or one comma. This is the fifth capturing group.| -## End of String or Line: $ +## End of String or Line: $ + + The `$` anchor specifies that the preceding pattern must occur at the end of the input string, or before `\n` at the end of the input string. - The `$` anchor specifies that the preceding pattern must occur at the end of the input string, or before `\n` at the end of the input string. - If you use `$` with the option, the match can also occur at the end of a line. Note that `$` is satisfied at `\n` but not at `\r\n` (the combination of carriage return and newline characters, or CR/LF). To handle the CR/LF character combination, include `\r?$` in the regular expression pattern. Note that `\r?$` will include any `\r` in the match. - - The following example adds the `$` anchor to the regular expression pattern used in the example in the [Start of String or Line](#start-of-string-or-line-) section. When used with the original input string, which includes five lines of text, the method is unable to find a match, because the end of the first line does not match the `$` pattern. When the original input string is split into a string array, the method succeeds in matching each of the five lines. When the method is called with the `options` parameter set to , no matches are found because the regular expression pattern does not account for the carriage return character `\r`. However, when the regular expression pattern is modified by replacing `$` with `\r?$`, calling the method with the `options` parameter set to again finds five matches. - + + The following example adds the `$` anchor to the regular expression pattern used in the example in the [Start of String or Line](#start-of-string-or-line-) section. When used with the original input string, which includes five lines of text, the method is unable to find a match, because the end of the first line does not match the `$` pattern. When the original input string is split into a string array, the method succeeds in matching each of the five lines. When the method is called with the `options` parameter set to , no matches are found because the regular expression pattern does not account for the carriage return character `\r`. However, when the regular expression pattern is modified by replacing `$` with `\r?$`, calling the method with the `options` parameter set to again finds five matches. + [!code-csharp[Conceptual.RegEx.Language.Assertions#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.assertions/cs/endofstring1.cs#2)] [!code-vb[Conceptual.RegEx.Language.Assertions#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/endofstring1.vb#2)] -## Start of String Only: \A +## Start of String Only: \A + + The `\A` anchor specifies that a match must occur at the beginning of the input string. It is identical to the `^` anchor, except that `\A` ignores the option. Therefore, it can only match the start of the first line in a multiline input string. + + The following example is similar to the examples for the `^` and `$` anchors. It uses the `\A` anchor in a regular expression that extracts information about the years during which some professional baseball teams existed. The input string includes five lines. The call to the method finds only the first substring in the input string that matches the regular expression pattern. As the example shows, the option has no effect. - The `\A` anchor specifies that a match must occur at the beginning of the input string. It is identical to the `^` anchor, except that `\A` ignores the option. Therefore, it can only match the start of the first line in a multiline input string. - - The following example is similar to the examples for the `^` and `$` anchors. It uses the `\A` anchor in a regular expression that extracts information about the years during which some professional baseball teams existed. The input string includes five lines. The call to the method finds only the first substring in the input string that matches the regular expression pattern. As the example shows, the option has no effect. - [!code-csharp[Conceptual.RegEx.Language.Assertions#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.assertions/cs/startofstring2.cs#3)] [!code-vb[Conceptual.RegEx.Language.Assertions#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/startofstring2.vb#3)] -## End of String or Before Ending Newline: \Z +## End of String or Before Ending Newline: \Z + + The `\Z` anchor specifies that a match must occur at the end of the input string, or before `\n` at the end of the input string. It is identical to the `$` anchor, except that `\Z` ignores the option. Therefore, in a multiline string, it can only be satisfied by the end of the last line, or the last line before `\n`. - The `\Z` anchor specifies that a match must occur at the end of the input string, or before `\n` at the end of the input string. It is identical to the `$` anchor, except that `\Z` ignores the option. Therefore, in a multiline string, it can only be satisfied by the end of the last line, or the last line before `\n`. - Note that `\Z` is satisfied at `\n` but is not satisfied at `\r\n` (the CR/LF character combination). To treat CR/LF as if it were `\n`, include `\r?\Z` in the regular expression pattern. Note that this will make the `\r` part of the match. - - The following example uses the `\Z` anchor in a regular expression that is similar to the example in the [Start of String or Line](#start-of-string-or-line-) section, which extracts information about the years during which some professional baseball teams existed. The subexpression `\r?\Z` in the regular expression `^((\w+(\s?)){2,}),\s(\w+\s\w+),(\s\d{4}(-(\d{4}|present))?,?)+\r?\Z` is satisfied at the end of a string, and also at the end of a string that ends with `\n` or `\r\n`. As a result, each element in the array matches the regular expression pattern. - + + The following example uses the `\Z` anchor in a regular expression that is similar to the example in the [Start of String or Line](#start-of-string-or-line-) section, which extracts information about the years during which some professional baseball teams existed. The subexpression `\r?\Z` in the regular expression `^((\w+(\s?)){2,}),\s(\w+\s\w+),(\s\d{4}(-(\d{4}|present))?,?)+\r?\Z` is satisfied at the end of a string, and also at the end of a string that ends with `\n` or `\r\n`. As a result, each element in the array matches the regular expression pattern. + [!code-csharp[Conceptual.RegEx.Language.Assertions#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.assertions/cs/endofstring2.cs#4)] [!code-vb[Conceptual.RegEx.Language.Assertions#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/endofstring2.vb#4)] -## End of String Only: \z +## End of String Only: \z The `\z` anchor specifies that a match must occur at the end of the input string. Like the `$` language element, `\z` ignores the option. Unlike the `\Z` language element, `\z` is not satisfied by a `\n` character at the end of a string. Therefore, it can only match the end of the input string. - - The following example uses the `\z` anchor in a regular expression that is otherwise identical to the example in the previous section, which extracts information about the years during which some professional baseball teams existed. The example tries to match each of five elements in a string array with the regular expression pattern `^((\w+(\s?)){2,}),\s(\w+\s\w+),(\s\d{4}(-(\d{4}|present))?,?)+\r?\z`. Two of the strings end with carriage return and line feed characters, one ends with a line feed character, and two end with neither a carriage return nor a line feed character. As the output shows, only the strings without a carriage return or line feed character match the pattern. - + + The following example uses the `\z` anchor in a regular expression that is otherwise identical to the example in the previous section, which extracts information about the years during which some professional baseball teams existed. The example tries to match each of five elements in a string array with the regular expression pattern `^((\w+(\s?)){2,}),\s(\w+\s\w+),(\s\d{4}(-(\d{4}|present))?,?)+\r?\z`. Two of the strings end with carriage return and line feed characters, one ends with a line feed character, and two end with neither a carriage return nor a line feed character. As the output shows, only the strings without a carriage return or line feed character match the pattern. + [!code-csharp[Conceptual.RegEx.Language.Assertions#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.assertions/cs/endofstring3.cs#5)] [!code-vb[Conceptual.RegEx.Language.Assertions#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/endofstring3.vb#5)] -## Contiguous Matches: \G +## Contiguous Matches: \G -The `\G` anchor specifies that a match must occur at the point where the previous match ended, or if there was no previous match, at the position in the string where matching started. When you use this anchor with the or method, it ensures that all matches are contiguous. +The `\G` anchor specifies that a match must occur at the point where the previous match ended, or if there was no previous match, at the position in the string where matching started. When you use this anchor with the or method, it ensures that all matches are contiguous. > [!TIP] > Typically, you place a `\G` anchor at the left end of your pattern. In the uncommon case you're performing a right-to-left search, place the `\G` anchor at the right end of your pattern. - - The following example uses a regular expression to extract the names of rodent species from a comma-delimited string. - + + The following example uses a regular expression to extract the names of rodent species from a comma-delimited string. + [!code-csharp[Conceptual.RegEx.Language.Assertions#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.assertions/cs/contiguous1.cs#6)] - [!code-vb[Conceptual.RegEx.Language.Assertions#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/contiguous1.vb#6)] - - The regular expression `\G(\w+\s?\w*),?` is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\G`|Begin where the last match ended.| -|`\w+`|Match one or more word characters.| -|`\s?`|Match zero or one space.| -|`\w*`|Match zero or more word characters.| -|`(\w+\s?\w*)`|Match one or more word characters followed by zero or one space, followed by zero or more word characters. This is the first capturing group.| + [!code-vb[Conceptual.RegEx.Language.Assertions#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/contiguous1.vb#6)] + + The regular expression `\G(\w+\s?\w*),?` is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\G`|Begin where the last match ended.| +|`\w+`|Match one or more word characters.| +|`\s?`|Match zero or one space.| +|`\w*`|Match zero or more word characters.| +|`(\w+\s?\w*)`|Match one or more word characters followed by zero or one space, followed by zero or more word characters. This is the first capturing group.| |`,?`|Match zero or one occurrence of a literal comma character.| -## Word Boundary: \b +## Word Boundary: \b + + The `\b` anchor specifies that the match must occur on a boundary between a word character (the `\w` language element) and a non-word character (the `\W` language element). Word characters consist of alphanumeric characters and underscores; a non-word character is any character that is not alphanumeric or an underscore. (For more information, see [Character Classes](character-classes-in-regular-expressions.md).) The match may also occur on a word boundary at the beginning or end of the string. + + The `\b` anchor is frequently used to ensure that a subexpression matches an entire word instead of just the beginning or end of a word. The regular expression `\bare\w*\b` in the following example illustrates this usage. It matches any word that begins with the substring "are". The output from the example also illustrates that `\b` matches both the beginning and the end of the input string. - The `\b` anchor specifies that the match must occur on a boundary between a word character (the `\w` language element) and a non-word character (the `\W` language element). Word characters consist of alphanumeric characters and underscores; a non-word character is any character that is not alphanumeric or an underscore. (For more information, see [Character Classes](character-classes-in-regular-expressions.md).) The match may also occur on a word boundary at the beginning or end of the string. - - The `\b` anchor is frequently used to ensure that a subexpression matches an entire word instead of just the beginning or end of a word. The regular expression `\bare\w*\b` in the following example illustrates this usage. It matches any word that begins with the substring "are". The output from the example also illustrates that `\b` matches both the beginning and the end of the input string. - [!code-csharp[Conceptual.RegEx.Language.Assertions#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.assertions/cs/word1.cs#7)] - [!code-vb[Conceptual.RegEx.Language.Assertions#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/word1.vb#7)] - - The regular expression pattern is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`are`|Match the substring "are".| -|`\w*`|Match zero or more word characters.| -|`\b`|End the match at a word boundary.| - -## Non-Word Boundary: \B - - The `\B` anchor specifies that the match must not occur on a word boundary. It is the opposite of the `\b` anchor. - - The following example uses the `\B` anchor to locate occurrences of the substring "qu" in a word. The regular expression pattern `\Bqu\w+` matches a substring that begins with a "qu" that does not start a word and that continues to the end of the word. - + [!code-vb[Conceptual.RegEx.Language.Assertions#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/word1.vb#7)] + + The regular expression pattern is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`are`|Match the substring "are".| +|`\w*`|Match zero or more word characters.| +|`\b`|End the match at a word boundary.| + +## Non-Word Boundary: \B + + The `\B` anchor specifies that the match must not occur on a word boundary. It is the opposite of the `\b` anchor. + + The following example uses the `\B` anchor to locate occurrences of the substring "qu" in a word. The regular expression pattern `\Bqu\w+` matches a substring that begins with a "qu" that does not start a word and that continues to the end of the word. + [!code-csharp[Conceptual.RegEx.Language.Assertions#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.assertions/cs/nonword1.cs#8)] - [!code-vb[Conceptual.RegEx.Language.Assertions#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/nonword1.vb#8)] - - The regular expression pattern is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\B`|Do not begin the match at a word boundary.| -|`qu`|Match the substring "qu".| -|`\w+`|Match one or more word characters.| - + [!code-vb[Conceptual.RegEx.Language.Assertions#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/nonword1.vb#8)] + + The regular expression pattern is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\B`|Do not begin the match at a word boundary.| +|`qu`|Match the substring "qu".| +|`\w+`|Match one or more word characters.| + ## See also - [Regular Expression Language - Quick Reference](regular-expression-language-quick-reference.md) diff --git a/docs/standard/base-types/backreference-constructs-in-regular-expressions.md b/docs/standard/base-types/backreference-constructs-in-regular-expressions.md index 99ef2e06dbec3..e0c3bd5a41b0f 100644 --- a/docs/standard/base-types/backreference-constructs-in-regular-expressions.md +++ b/docs/standard/base-types/backreference-constructs-in-regular-expressions.md @@ -81,7 +81,7 @@ In a named backreference with `\k`, *name* can also be the string representation [!code-csharp[RegularExpressions.Language.Backreferences#3](../../../samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.backreferences/cs/backreference3.cs#3)] [!code-vb[RegularExpressions.Language.Backreferences#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.backreferences/vb/backreference3.vb#3)] -If *name* is the string representation of a number, and no capturing group has that name, `\k<`*name*`>` is the same as the backreference `\`*number*, where *number* is the ordinal position of the capture. In the following example, there is a single capturing group named `char`. The backreference construct refers to it as `\k<1>`. As the output from the example shows, the call to the succeeds because `char` is the first capturing group. +If *name* is the string representation of a number, and no capturing group has that name, `\k<`*name*`>` is the same as the backreference `\`*number*, where *number* is the ordinal position of the capture. In the following example, there is a single capturing group named `char`. The backreference construct refers to it as `\k<1>`. As the output from the example shows, the call to the succeeds because `char` is the first capturing group. [!code-csharp[Ordinal.Backreference](../../../samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.backreferences/cs/backreference6.cs)] [!code-vb[Ordinal.BackReference](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.backreferences/vb/backreference6.vb)] diff --git a/docs/standard/base-types/backtracking-in-regular-expressions.md b/docs/standard/base-types/backtracking-in-regular-expressions.md index 071ba2e92dc96..365ac7d3c7043 100644 --- a/docs/standard/base-types/backtracking-in-regular-expressions.md +++ b/docs/standard/base-types/backtracking-in-regular-expressions.md @@ -115,7 +115,7 @@ If you don't need to use any constructs that require backtracking (for example, If you don't set a time-out value explicitly, the default time-out value is determined as follows: -- By using the application-wide time-out value, if one exists. This can be any time-out value that applies to the application domain in which the object is instantiated or the static method call is made. You can set the application-wide time-out value by calling the method to assign the string representation of a value to the `REGEX_DEFAULT_MATCH_TIMEOUT` property. +- By using the application-wide time-out value, if one exists. This can be any time-out value that applies to the application domain in which the object is instantiated or the static method call is made. You can set the application-wide time-out value by calling the method to assign the string representation of a value to the `REGEX_DEFAULT_MATCH_TIMEOUT` property. - By using the value , if no application-wide time-out value has been set. By default, the time-out interval is set to and the regular expression engine does not time out. @@ -145,7 +145,7 @@ By default, the time-out interval is set to method. + The following example uses two equivalent regular expression patterns that validate the user name in an email address. The first pattern is subject to poor performance because of excessive backtracking. The second pattern modifies the first regular expression by replacing a nested quantifier with a positive lookbehind assertion. The output from the example displays the execution time of the method. :::code language="csharp" source="./snippets/regex-backtracking/csharp/backtracking5.cs" ID="5"::: :::code language="vb" source="./snippets/regex-backtracking/vb/backtracking5.vb" ID="5"::: @@ -155,7 +155,7 @@ By default, the time-out interval is set to method is called with the option.| +|`[0-9A-Z]`|Match an alphanumeric character. This comparison is case-insensitive, because the method is called with the option.| |`[-.\w]*`|Match zero, one, or more occurrences of a hyphen, period, or word character.| |`[0-9A-Z]`|Match an alphanumeric character.| |`([-.\w]*[0-9A-Z])*`|Match zero or more occurrences of the combination of zero or more hyphens, periods, or word characters, followed by an alphanumeric character. This is the first capturing group.| @@ -166,7 +166,7 @@ By default, the time-out interval is set to method is called with the option.| +|`[0-9A-Z]`|Match an alphanumeric character. This comparison is case-insensitive, because the method is called with the option.| |`[-.\w]*`|Match zero or more occurrences of a hyphen, period, or word character.| |`(?<=[0-9A-Z])`|Look back at the last matched character and continue the match if it is alphanumeric. Note that alphanumeric characters are a subset of the set that consists of periods, hyphens, and all word characters.| |`@`|Match an at sign ("\@").| @@ -177,7 +177,7 @@ By default, the time-out interval is set to method. + The following example uses two equivalent regular expression patterns that validate a fully qualified type name. The first pattern is subject to poor performance because of excessive backtracking. The second modifies the first regular expression by replacing a nested quantifier with a positive lookahead assertion. The output from the example displays the execution time of the method. :::code language="csharp" source="./snippets/regex-backtracking/csharp/backtracking6.cs" ID="6"::: :::code language="vb" source="./snippets/regex-backtracking/vb/backtracking6.vb" ID="6"::: @@ -187,7 +187,7 @@ By default, the time-out interval is set to method is called with the option.| +|`([A-Z]\w*)+\.`|Match an alphabetical character (A-Z) followed by zero or more word characters one or more times, followed by a period. This comparison is case-insensitive, because the method is called with the option.| |`(([A-Z]\w*)+\.)*`|Match the previous pattern zero or more times.| |`[A-Z]\w*`|Match an alphabetical character followed by zero or more word characters.| |`$`|End the match at the end of the input string.| @@ -197,7 +197,7 @@ By default, the time-out interval is set to method is called with the option.| +|`(?=[A-Z])`|Look ahead to the first character and continue the match if it is alphabetical (A-Z). This comparison is case-insensitive, because the method is called with the option.| |`\w+\.`|Match one or more word characters followed by a period.| |`((?=[A-Z])\w+\.)*`|Match the pattern of one or more word characters followed by a period zero or more times. The initial word character must be alphabetical.| |`[A-Z]\w*`|Match an alphabetical character followed by zero or more word characters.| @@ -213,7 +213,7 @@ The following suggestions are not specifically to prevent excessive backtracking 1. Start matching from an offset. If you know that matches will always start beyond a certain offset into the pattern, pass the offset in using an overload like . This will reduce the amount of the text the engine needs to consider. -1. Gather only the information you need. If you only need to know whether a match occurs but not where the match occurs, prefer . If you only need to know how many times something matches, prefer using . If you only need to know the bounds of a match but not anything about a match's captures, prefer using . The less information the engine needs to provide, the better. +1. Gather only the information you need. If you only need to know whether a match occurs but not where the match occurs, prefer . If you only need to know how many times something matches, prefer using . If you only need to know the bounds of a match but not anything about a match's captures, prefer using . The less information the engine needs to provide, the better. 1. Avoid unnecessary captures. Parentheses in your pattern form a capturing group by default. If you don't need captures, either specify or use [non-capturing groups](grouping-constructs-in-regular-expressions.md#noncapturing-groups) instead. This saves the engine keeping track of those captures. diff --git a/docs/standard/base-types/best-practices-display-data.md b/docs/standard/base-types/best-practices-display-data.md index 202f3e7fd86e2..65f1b20ed98b1 100644 --- a/docs/standard/base-types/best-practices-display-data.md +++ b/docs/standard/base-types/best-practices-display-data.md @@ -18,13 +18,13 @@ When you develop with .NET, use culture-sensitive formatting to display non-stri When you display non-string data such as numbers and dates and times to users, format them by using the user's cultural settings. By default, the following all use the current culture in formatting operations: - Interpolated strings supported by the [C#](../../csharp/language-reference/tokens/interpolated.md) and [Visual Basic](../../visual-basic/programming-guide/language-features/strings/interpolated-strings.md) compilers. -- String concatenation operations that use the [C#](../../csharp/language-reference/operators/addition-operator.md#string-concatenation) or [Visual Basic](../../visual-basic/programming-guide/language-features/operators-and-expressions/concatenation-operators.md) concatenation operators or that call the method directly. -- The method. +- String concatenation operations that use the [C#](../../csharp/language-reference/operators/addition-operator.md#string-concatenation) or [Visual Basic](../../visual-basic/programming-guide/language-features/operators-and-expressions/concatenation-operators.md) concatenation operators or that call the method directly. +- The method. - The `ToString` methods of the numeric types and the date and time types. To explicitly specify that a string should be formatted by using the conventions of a designated culture or the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture), you can do the following: -- When using the and `ToString` methods, call an overload that has a `provider` parameter, such as or , and pass it the property, a instance that represents the desired culture, or the property. +- When using the and `ToString` methods, call an overload that has a `provider` parameter, such as or , and pass it the property, a instance that represents the desired culture, or the property. - For string concatenation, do not allow the compiler to perform any implicit conversions. Instead, perform an explicit conversion by calling a `ToString` overload that has a `provider` parameter. For example, the compiler implicitly uses the current culture when converting a value to a string in the following code: @@ -38,7 +38,7 @@ To explicitly specify that a string should be formatted by using the conventions - For string interpolation, rather than assigning an interpolated string to a instance, assign it to a . You can then call its method to produce a result string that reflects the conventions of the current culture, or you can call the method to produce a result string that reflects the conventions of a specified culture. - You can also pass the formattable string to the static method to produce a result string that reflects the conventions of the invariant culture. The following example illustrates this approach. (The output from the example reflects a current culture of `en-US`.) + You can also pass the formattable string to the static method to produce a result string that reflects the conventions of the invariant culture. The following example illustrates this approach. (The output from the example reflects a current culture of `en-US`.) [!code-csharp[String interpolation](./snippets/best-practices-display-data/csharp/formattable/Program.cs)] [!code-vb[String interpolation](./snippets/best-practices-display-data/vb/formattable/Program.vb)] @@ -48,7 +48,7 @@ To explicitly specify that a string should be formatted by using the conventions ## Persist formatted data -You can persist non-string data either as binary data or as formatted data. If you choose to save it as formatted data, you should call a formatting method overload that includes a `provider` parameter and pass it the property. The invariant culture provides a consistent format for formatted data that is independent of culture and machine. In contrast, persisting data that is formatted by using cultures other than the invariant culture has a number of limitations: +You can persist non-string data either as binary data or as formatted data. If you choose to save it as formatted data, you should call a formatting method overload that includes a `provider` parameter and pass it the property. The invariant culture provides a consistent format for formatted data that is independent of culture and machine. In contrast, persisting data that is formatted by using cultures other than the invariant culture has a number of limitations: - The data is likely to be unusable if it is retrieved on a system that has a different culture, or if the user of the current system changes the current culture and tries to retrieve the data. - The properties of a culture on a specific computer can differ from standard values. At any time, a user can customize culture-sensitive display settings. Because of this, formatted data that is saved on a system may not be readable after the user customizes cultural settings. The portability of formatted data across computers is likely to be even more limited. @@ -59,7 +59,7 @@ The following example illustrates the limited portability that results from usin [!code-csharp[Conceptual.Strings.BestPractices#21](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.strings.bestpractices/cs/persistence.cs#21)] [!code-vb[Conceptual.Strings.BestPractices#21](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.strings.bestpractices/vb/persistence.vb#21)] -However, if you replace the property with in the calls to and , the persisted date and time data is successfully restored, as the following output shows: +However, if you replace the property with in the calls to and , the persisted date and time data is successfully restored, as the following output shows: ```console 06.05.1758 21:26 diff --git a/docs/standard/base-types/best-practices-regex.md b/docs/standard/base-types/best-practices-regex.md index a967c8f94cd82..a3e3ebb38fd62 100644 --- a/docs/standard/base-types/best-practices-regex.md +++ b/docs/standard/base-types/best-practices-regex.md @@ -27,7 +27,7 @@ The .NET regular expression engine is designed with the assumption that patterns If your application needs to accept search expressions from users, avoid passing user input directly as a regex pattern. Instead, consider these alternatives: - Support a restricted search syntax (such as simple wildcards or substring matching) that you translate into a regex pattern internally. -- Use to treat any user-supplied text as a literal string within a pattern. +- Use to treat any user-supplied text as a literal string within a pattern. Features such as [time-out values](#use-time-out-values) and (which guarantees linear-time processing in the length of the input) help protect against accidental performance problems in developer-authored patterns. They are not intended as a security boundary against malicious patterns. @@ -107,7 +107,7 @@ You should replace the preceding inefficient code with a call to the static property. +By default, the last 15 most recently used static regular expression patterns are cached. For applications that require a larger number of cached static regular expressions, the size of the cache can be adjusted by setting the property. The regular expression `\p{Sc}+\s*\d+` that's used in this example verifies that the input string has a currency symbol and at least one decimal digit. The pattern is defined as shown in the following table: @@ -231,9 +231,9 @@ The following example defines a `GetWordData` method that instantiates a regular Regular expressions in .NET support grouping constructs, which let you group a regular expression pattern into one or more subexpressions. The most commonly used grouping constructs in .NET regular expression language are `(`*subexpression*`)`, which defines a numbered capturing group, and `(?<`*name*`>`*subexpression*`)`, which defines a named capturing group. Grouping constructs are essential for creating backreferences and for defining a subexpression to which a quantifier is applied. -However, the use of these language elements has a cost. They cause the object returned by the property to be populated with the most recent unnamed or named captures. If a single grouping construct has captured multiple substrings in the input string, they also populate the object returned by the property of a particular capturing group with multiple objects. +However, the use of these language elements has a cost. They cause the object returned by the property to be populated with the most recent unnamed or named captures. If a single grouping construct has captured multiple substrings in the input string, they also populate the object returned by the property of a particular capturing group with multiple objects. -Often, grouping constructs are used in a regular expression only so that quantifiers can be applied to them. The groups captured by these subexpressions aren't used later. For example, the regular expression `\b(\w+[;,]?\s?)+[.?!]` is designed to capture an entire sentence. The following table describes the language elements in this regular expression pattern and their effect on the object's and collections: +Often, grouping constructs are used in a regular expression only so that quantifiers can be applied to them. The groups captured by these subexpressions aren't used later. For example, the regular expression `\b(\w+[;,]?\s?)+[.?!]` is designed to capture an entire sentence. The following table describes the language elements in this regular expression pattern and their effect on the object's and collections: | Pattern | Description | |---------|--------------------------------------------| diff --git a/docs/standard/base-types/best-practices-strings.md b/docs/standard/base-types/best-practices-strings.md index ece96de4dee42..17bd7ddc5015b 100644 --- a/docs/standard/base-types/best-practices-strings.md +++ b/docs/standard/base-types/best-practices-strings.md @@ -29,23 +29,23 @@ This article examines the string sorting, comparison, and casing methods in .NET When you develop with .NET, follow these recommendations when you compare strings. > [!TIP] -> Various string-related methods perform comparison. Examples include , , , and . +> Various string-related methods perform comparison. Examples include , , , and . - Use overloads that explicitly specify the string comparison rules for string operations. Typically, this involves calling a method overload that has a parameter of type . - Use or for comparisons as your safe default for culture-agnostic string matching. - Use comparisons with or for better performance. - Use string operations that are based on when you display output to the user. -- Use the non-linguistic or values instead of string operations based on when the comparison is linguistically irrelevant (symbolic, for example). -- Use the method instead of the method when you normalize strings for comparison. -- Use an overload of the method to test whether two strings are equal. -- Use the and methods to sort strings, not to check for equality. +- Use the non-linguistic or values instead of string operations based on when the comparison is linguistically irrelevant (symbolic, for example). +- Use the method instead of the method when you normalize strings for comparison. +- Use an overload of the method to test whether two strings are equal. +- Use the and methods to sort strings, not to check for equality. - Use culture-sensitive formatting to display non-string data, such as numbers and dates, in a user interface. Use formatting with the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture) to persist non-string data in string form. Avoid the following practices when you compare strings: - Don't use overloads that don't explicitly or implicitly specify the string comparison rules for string operations. - Don't use string operations based on in most cases. One of the few exceptions is when you're persisting linguistically meaningful but culturally agnostic data. -- Don't use an overload of the or method and test for a return value of zero to determine whether two strings are equal. +- Don't use an overload of the or method and test for a return value of zero to determine whether two strings are equal. > [!TIP] > The [CA1307](../../fundamentals/code-analysis/quality-rules/ca1307.md), [CA1309](../../fundamentals/code-analysis/quality-rules/ca1309.md), and [CA1310](../../fundamentals/code-analysis/quality-rules/ca1310.md) code analysis rules help identify call sites where a linguistic comparer is used unintentionally. To enable them and surface violations as build errors, set the following properties in your project file: @@ -70,7 +70,7 @@ Most of the string manipulation methods in .NET are overloaded. Typically, one o | | Performs an ordinal comparison. | | | Performs a case-insensitive ordinal comparison. | -For example, the method, which returns the index of a substring in a object that matches either a character or a string, has nine overloads: +For example, the method, which returns the index of a substring in a object that matches either a character or a string, has nine overloads: - , , and , which by default performs an ordinal (case-sensitive and culture-insensitive) search for a character in the string. - , , and , which by default performs a case-sensitive and culture-sensitive search for a substring in the string. @@ -113,12 +113,12 @@ Case-insensitive comparisons that use the current culture are the same as cultur Comparisons that use current culture semantics are the default for the following methods: -- overloads that don't include a parameter. -- overloads. +- overloads that don't include a parameter. +- overloads. - The default method, and the method with a `null` parameter. - The default method, and the method with a `null` parameter. -- overloads that accept a as a search parameter and that don't have a parameter. -- overloads that accept a as a search parameter and that don't have a parameter. +- overloads that accept a as a search parameter and that don't have a parameter. +- overloads that accept a as a search parameter and that don't have a parameter. In any case, we recommend that you call an overload that has a parameter to make the intent of the method call clear. @@ -178,10 +178,10 @@ When performing a `string.IndexOf(..., StringComparison.Ordinal)` operation, the Ordinal search and comparison routines are never affected by the current thread's culture setting. -Strings in .NET can contain embedded null characters (and other non-printing characters). One of the clearest differences between ordinal and culture-sensitive comparison (including comparisons that use the invariant culture) concerns the handling of embedded null characters in a string. These characters are ignored when you use the and methods to perform culture-sensitive comparisons (including comparisons that use the invariant culture). As a result, strings that contain embedded null characters can be considered equal to strings that don't. Embedded non-printing characters might be skipped for the purpose of string comparison methods, such as . +Strings in .NET can contain embedded null characters (and other non-printing characters). One of the clearest differences between ordinal and culture-sensitive comparison (including comparisons that use the invariant culture) concerns the handling of embedded null characters in a string. These characters are ignored when you use the and methods to perform culture-sensitive comparisons (including comparisons that use the invariant culture). As a result, strings that contain embedded null characters can be considered equal to strings that don't. Embedded non-printing characters might be skipped for the purpose of string comparison methods, such as . > [!IMPORTANT] -> Although string comparison methods disregard embedded null characters, string search methods such as , , , , and do not. +> Although string comparison methods disregard embedded null characters, string search methods such as , , , , and do not. The following example performs a culture-sensitive comparison of the string "Aa" with a similar string that contains several embedded null characters between "A" and "a", and shows how the two strings are considered equal: @@ -207,7 +207,7 @@ These comparisons are still very fast. Both and use the binary values directly, and are best suited for matching. When you aren't sure about your comparison settings, use one of these two values. However, because they perform a byte-by-byte comparison, they don't sort by a linguistic sort order (like an English dictionary) but by a binary sort order. The results may look odd in most contexts if displayed to users. -Ordinal semantics are the default for overloads that don't include a argument (including the equality operator). In any case, we recommend that you call an overload that has a parameter. +Ordinal semantics are the default for overloads that don't include a argument (including the equality operator). In any case, we recommend that you call an overload that has a parameter. ### Linguistic string comparisons @@ -254,11 +254,11 @@ When using a Hungarian culture-aware comparer, the string `"endz"` *does not* en ### String operations that use the invariant culture -Comparisons with the invariant culture use the property returned by the static property. This behavior is the same on all systems; it translates any characters outside its range into what it believes are equivalent invariant characters. This policy can be useful for maintaining one set of string behavior across cultures, but it often provides unexpected results. +Comparisons with the invariant culture use the property returned by the static property. This behavior is the same on all systems; it translates any characters outside its range into what it believes are equivalent invariant characters. This policy can be useful for maintaining one set of string behavior across cultures, but it often provides unexpected results. -Case-insensitive comparisons with the invariant culture use the static property returned by the static property for comparison information as well. Any case differences among these translated characters are ignored. +Case-insensitive comparisons with the invariant culture use the static property returned by the static property for comparison information as well. Any case differences among these translated characters are ignored. -Comparisons that use and work identically on ASCII strings. However, makes linguistic decisions that might not be appropriate for strings that have to be interpreted as a set of bytes. The `CultureInfo.InvariantCulture.CompareInfo` object makes the method interpret certain sets of characters as equivalent. For example, the following equivalence is valid under the invariant culture: +Comparisons that use and work identically on ASCII strings. However, makes linguistic decisions that might not be appropriate for strings that have to be interpreted as a set of bytes. The `CultureInfo.InvariantCulture.CompareInfo` object makes the method interpret certain sets of characters as equivalent. For example, the following equivalence is valid under the invariant culture: InvariantCulture: a + ̊ = å @@ -301,7 +301,7 @@ Default interpretation: comparison should be used instead. -The class, which is returned by the property, also includes a method that provides a large number of matching options (ordinal, ignoring white space, ignoring kana type, and so on) by means of the flag enumeration. +The class, which is returned by the property, also includes a method that provides a large number of matching options (ordinal, ignoring white space, ignoring kana type, and so on) by means of the flag enumeration. ### `String.CompareTo` @@ -309,7 +309,7 @@ Default interpretation: type. It's usually possible to convert this method to the recommended form. -Types that implement the and interfaces implement this method. Because it doesn't offer the option of a parameter, implementing types often let the user specify a in their constructor. The following example defines a `FileName` class whose class constructor includes a parameter. This object is then used in the `FileName.CompareTo` method. +Types that implement the and interfaces implement this method. Because it doesn't offer the option of a parameter, implementing types often let the user specify a in their constructor. The following example defines a `FileName` class whose class constructor includes a parameter. This object is then used in the `FileName.CompareTo` method. :::code language="csharp" source="./snippets/best-practices-strings/csharp/stringcomparer/Program.cs" id="class"::: :::code language="vb" source="./snippets/best-practices-strings/vb/stringcomparer/Program.vb" id="class"::: @@ -318,7 +318,7 @@ Types that implement the and . -The class lets you test for equality by calling either the static or instance method overloads, or by using the static equality operator. The overloads and operator use ordinal comparison by default. However, we still recommend that you call an overload that explicitly specifies the type even if you want to perform an ordinal comparison; this makes it easier to search code for a certain string interpretation. +The class lets you test for equality by calling either the static or instance method overloads, or by using the static equality operator. The overloads and operator use ordinal comparison by default. However, we still recommend that you call an overload that explicitly specifies the type even if you want to perform an ordinal comparison; this makes it easier to search code for a certain string interpretation. ### `String.ToUpper` and `String.ToLower` @@ -326,7 +326,7 @@ Default interpretation: and methods, because forcing a string to uppercase or lowercase is often used as a small normalization for comparing strings regardless of case. If so, consider using a case-insensitive comparison. -The and methods are also available. is the standard way to normalize case. Comparisons made using are behaviorally the composition of two calls: calling on both string arguments, and doing a comparison using . +The and methods are also available. is the standard way to normalize case. Comparisons made using are behaviorally the composition of two calls: calling on both string arguments, and doing a comparison using . Overloads are also available for converting to uppercase and lowercase in a specific culture, by passing a object that represents that culture to the method. @@ -346,7 +346,7 @@ There's an inconsistency in how the default overloads of these methods perform c Default interpretation: . -There's a lack of consistency in how the default overloads of these methods perform comparisons. All and methods that include a parameter perform an ordinal comparison, but the default and methods that include a parameter perform a culture-sensitive comparison. +There's a lack of consistency in how the default overloads of these methods perform comparisons. All and methods that include a parameter perform an ordinal comparison, but the default and methods that include a parameter perform a culture-sensitive comparison. If you call the or method and pass it a string to locate in the current instance, we recommend that you call an overload that explicitly specifies the type. The overloads that include a argument don't allow you to specify a type. @@ -354,7 +354,7 @@ If you call the . -Unlike , the method uses an ordinal comparison by default for both `char` and `string` overloads. However, you should still pass an explicit argument when the intent matters, to make the behavior clear at the call site. +Unlike , the method uses an ordinal comparison by default for both `char` and `string` overloads. However, you should still pass an explicit argument when the intent matters, to make the behavior clear at the call site. ### `MemoryExtensions.AsSpan.IndexOfAny` and the `SearchValues` type @@ -369,20 +369,20 @@ In .NET 9, `SearchValues` was extended to support searching for substrings withi ## Methods that perform string comparison indirectly -Some non-string methods that have string comparison as a central operation use the type. The class includes six static properties that return instances whose methods perform the following types of string comparisons: +Some non-string methods that have string comparison as a central operation use the type. The class includes six static properties that return instances whose methods perform the following types of string comparisons: -- Culture-sensitive string comparisons using the current culture. This object is returned by the property. -- Case-insensitive comparisons using the current culture. This object is returned by the property. -- Culture-insensitive comparisons using the word comparison rules of the invariant culture. This object is returned by the property. -- Case-insensitive and culture-insensitive comparisons using the word comparison rules of the invariant culture. This object is returned by the property. -- Ordinal comparison. This object is returned by the property. -- Case-insensitive ordinal comparison. This object is returned by the property. +- Culture-sensitive string comparisons using the current culture. This object is returned by the property. +- Case-insensitive comparisons using the current culture. This object is returned by the property. +- Culture-insensitive comparisons using the word comparison rules of the invariant culture. This object is returned by the property. +- Case-insensitive and culture-insensitive comparisons using the word comparison rules of the invariant culture. This object is returned by the property. +- Ordinal comparison. This object is returned by the property. +- Case-insensitive ordinal comparison. This object is returned by the property. ### `Array.Sort` and `Array.BinarySearch` Default interpretation: . -When you store any data in a collection, or read persisted data from a file or database into a collection, switching the current culture can invalidate the invariants in the collection. The method assumes that the elements in the array to be searched are already sorted. To sort any string element in the array, the method calls the method to order individual elements. Using a culture-sensitive comparer can be dangerous if the culture changes between the time that the array is sorted and its contents are searched. For example, in the following code, storage and retrieval operate on the comparer that is provided implicitly by the `Thread.CurrentThread.CurrentCulture` property. If the culture can change between the calls to `StoreNames` and `DoesNameExist`, and especially if the array contents are persisted somewhere between the two method calls, the binary search may fail. +When you store any data in a collection, or read persisted data from a file or database into a collection, switching the current culture can invalidate the invariants in the collection. The method assumes that the elements in the array to be searched are already sorted. To sort any string element in the array, the method calls the method to order individual elements. Using a culture-sensitive comparer can be dangerous if the culture changes between the time that the array is sorted and its contents are searched. For example, in the following code, storage and retrieval operate on the comparer that is provided implicitly by the `Thread.CurrentThread.CurrentCulture` property. If the culture can change between the calls to `StoreNames` and `DoesNameExist`, and especially if the array contents are persisted somewhere between the two method calls, the binary search may fail. :::code language="csharp" source="./snippets/best-practices-strings/csharp/indirect1/binarysearch.cs" id="no_compare" highlight="11,15"::: :::code language="vb" source="./snippets/best-practices-strings/vb/indirect1/binarysearch.vb" id="no_compare" highlight="10,14"::: @@ -401,7 +401,7 @@ If this data is persisted and moved across cultures, and sorting is used to pres Hashing strings provides a second example of an operation that is affected by the way in which strings are compared. -The following example instantiates a object by passing it the object that is returned by the property. Because a class that is derived from implements the interface, its method is used to compute the hash code of strings in the hash table. +The following example instantiates a object by passing it the object that is returned by the property. Because a class that is derived from implements the interface, its method is used to compute the hash code of strings in the hash table. :::code language="csharp" source="./snippets/best-practices-strings/csharp/indirect1/Program.cs"::: :::code language="vb" source="./snippets/best-practices-strings/vb/indirect1/Program.vb"::: @@ -419,21 +419,21 @@ The same locale-sensitivity issue applies when instantiating a sorted collection Because ICU and NLS implement different logic in their linguistic comparers, the results of string methods that use culture-sensitive comparison can differ between .NET and .NET Framework. This matters for any method that uses a linguistic comparer by default, including: -- -- (when the first parameter is a `string`) -- (when the first parameter is a `string`) -- (when the first parameter is a `string`) -- -- -- -- +- +- (when the first parameter is a `string`) +- (when the first parameter is a `string`) +- (when the first parameter is a `string`) +- +- +- +- - (most members) - (most members) -- (when sorting arrays of strings) -- (when the list elements are strings) -- (when the keys are strings) -- (when the keys are strings) -- (when the set contains strings) +- (when sorting arrays of strings) +- (when the list elements are strings) +- (when the keys are strings) +- (when the keys are strings) +- (when the set contains strings) > [!NOTE] > This is not an exhaustive list of affected APIs. diff --git a/docs/standard/base-types/changing-case.md b/docs/standard/base-types/changing-case.md index 4f4f6d0ec1e58..48b47669e1fdc 100644 --- a/docs/standard/base-types/changing-case.md +++ b/docs/standard/base-types/changing-case.md @@ -21,51 +21,51 @@ If you write an application that accepts input from a user, you can never be sur | Method name | Use | |--|--| -| | Converts all characters in a string to uppercase. | -| | Converts all characters in a string to lowercase. | -| | Converts a string to title case. | +| | Converts all characters in a string to uppercase. | +| | Converts all characters in a string to lowercase. | +| | Converts a string to title case. | > [!WARNING] -> The and methods should not be used to convert strings in order to compare them or test them for equality. For more information, see the [Compare strings of mixed case](#compare-strings-of-mixed-case) section. +> The and methods should not be used to convert strings in order to compare them or test them for equality. For more information, see the [Compare strings of mixed case](#compare-strings-of-mixed-case) section. ## Compare strings of mixed case -To compare strings of mixed case to determine their ordering, call one of the overloads of the method with a `comparisonType` parameter, and provide a value of either , , or for the `comparisonType` argument. For a comparison using a specific culture other than the current culture, call an overload of the method with both a `culture` and `options` parameter, and provide a value of as the `options` argument. +To compare strings of mixed case to determine their ordering, call one of the overloads of the method with a `comparisonType` parameter, and provide a value of either , , or for the `comparisonType` argument. For a comparison using a specific culture other than the current culture, call an overload of the method with both a `culture` and `options` parameter, and provide a value of as the `options` argument. -To compare strings of mixed case to determine whether they're equal, call one of the overloads of the method with a `comparisonType` parameter, and provide a value of either , , or for the `comparisonType` argument. +To compare strings of mixed case to determine whether they're equal, call one of the overloads of the method with a `comparisonType` parameter, and provide a value of either , , or for the `comparisonType` argument. For more information, see [Best practices for using strings](best-practices-strings.md). ## `ToUpper` method -The method changes all characters in a string to uppercase. The following example converts the string "Hello World!" from mixed case to uppercase. +The method changes all characters in a string to uppercase. The following example converts the string "Hello World!" from mixed case to uppercase. [!code-csharp[Strings.ChangingCase#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.ChangingCase/cs/Example.cs#1)] [!code-vb[Strings.ChangingCase#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.ChangingCase/vb/Example.vb#1)] -The preceding example is culture-sensitive by default; it applies the casing conventions of the current culture. To perform a culture-insensitive case change or to apply the casing conventions of a particular culture, use the method overload and supply a value of or a object that represents the specified culture to the `culture` parameter. For an example that demonstrates how to use the method to perform a culture-insensitive case change, see [Perform culture-insensitive case changes](../../core/extensions/performing-culture-insensitive-case-changes.md). +The preceding example is culture-sensitive by default; it applies the casing conventions of the current culture. To perform a culture-insensitive case change or to apply the casing conventions of a particular culture, use the method overload and supply a value of or a object that represents the specified culture to the `culture` parameter. For an example that demonstrates how to use the method to perform a culture-insensitive case change, see [Perform culture-insensitive case changes](../../core/extensions/performing-culture-insensitive-case-changes.md). ## `ToLower` method -The method is similar to the previous method, but instead converts all the characters in a string to lowercase. The following example converts the string "Hello World!" to lowercase. +The method is similar to the previous method, but instead converts all the characters in a string to lowercase. The following example converts the string "Hello World!" to lowercase. [!code-csharp[Strings.ChangingCase#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.ChangingCase/cs/Example.cs#2)] [!code-vb[Strings.ChangingCase#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.ChangingCase/vb/Example.vb#2)] -The preceding example is culture-sensitive by default; it applies the casing conventions of the current culture. To perform a culture-insensitive case change or to apply the casing conventions of a particular culture, use the method overload and supply a value of or a object that represents the specified culture to the `culture` parameter. For an example that demonstrates how to use the method to perform a culture-insensitive case change, see [Perform culture-insensitive case changes](../../core/extensions/performing-culture-insensitive-case-changes.md). +The preceding example is culture-sensitive by default; it applies the casing conventions of the current culture. To perform a culture-insensitive case change or to apply the casing conventions of a particular culture, use the method overload and supply a value of or a object that represents the specified culture to the `culture` parameter. For an example that demonstrates how to use the method to perform a culture-insensitive case change, see [Perform culture-insensitive case changes](../../core/extensions/performing-culture-insensitive-case-changes.md). ## `ToTitleCase` method -The converts the first character of each word to uppercase and the remaining characters to lowercase. However, words that are entirely uppercase are assumed to be acronyms and are not converted. +The converts the first character of each word to uppercase and the remaining characters to lowercase. However, words that are entirely uppercase are assumed to be acronyms and are not converted. -The method is culture-sensitive; that is, it uses the casing conventions of a particular culture. In order to call the method, you first retrieve the object that represents the casing conventions of the particular culture from the property of a particular culture. +The method is culture-sensitive; that is, it uses the casing conventions of a particular culture. In order to call the method, you first retrieve the object that represents the casing conventions of the particular culture from the property of a particular culture. -The following example passes each string in an array to the method. The strings include proper title strings as well as acronyms. The strings are converted to title case by using the casing conventions of the English (United States) culture. +The following example passes each string in an array to the method. The strings include proper title strings as well as acronyms. The strings are converted to title case by using the casing conventions of the English (United States) culture. [!code-csharp[System.Globalization.TextInfo.ToTitleCase#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.textinfo.totitlecase/cs/totitlecase2.cs#1)] [!code-vb[System.Globalization.TextInfo.ToTitleCase#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.textinfo.totitlecase/vb/totitlecase2.vb#1)] -Note that although it is culture-sensitive, the method does not provide linguistically correct casing rules. For instance, in the previous example, the method converts "a tale of two cities" to "A Tale Of Two Cities". However, the linguistically correct title casing for the en-US culture is "A Tale of Two Cities." +Note that although it is culture-sensitive, the method does not provide linguistically correct casing rules. For instance, in the previous example, the method converts "a tale of two cities" to "A Tale Of Two Cities". However, the linguistically correct title casing for the en-US culture is "A Tale of Two Cities." ## See also diff --git a/docs/standard/base-types/character-classes-in-regular-expressions.md b/docs/standard/base-types/character-classes-in-regular-expressions.md index 985fb630f8fd0..71afbb10006b6 100644 --- a/docs/standard/base-types/character-classes-in-regular-expressions.md +++ b/docs/standard/base-types/character-classes-in-regular-expressions.md @@ -3,10 +3,10 @@ title: Character Classes in .NET Regular Expressions description: Learn how to use character classes to represent a set of characters in .NET regular expressions. ms.date: 09/08/2025 no-loc: ["Ll","Lu","Lt","Lo","Lm","Mn","Nd","Pc","Lu"] -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "character classes" - "regular expressions, character classes" - "characters, matching syntax" @@ -163,7 +163,7 @@ The period character (.) matches any character except `\n` (the newline characte - If a regular expression pattern is modified by the option, or if the portion of the pattern that contains the `.` character class is modified by the `s` option, `.` matches any character. For more information, see [Regular Expression Options](regular-expression-options.md). The following example illustrates the different behavior of the `.` character class by default and with the option. The regular expression `^.+` starts at the beginning of the string and matches every character. By default, the match ends at the end of the first line; the regular expression pattern matches the carriage return character, `\r`, but it doesn't match `\n`. Because the option interprets the entire input string as a single line, it matches every character in the input string, including `\n`. - + :::code language="csharp" source="snippets/character-classes-in-regular-expressions/csharp/Program.cs" id="AnyCharacterMultiline"::: :::code language="vb" source="snippets/character-classes-in-regular-expressions/vb/Program.vb" id="AnyCharacterMultiline"::: @@ -191,7 +191,7 @@ The regular expression construct Matches any character that belongs to a Unicode general category or named block, where *name* is the category abbreviation or named block name. For a list of category abbreviations, see the [Supported Unicode General Categories](#SupportedUnicodeGeneralCategories) section later in this article. For a list of named blocks, see the [Supported Named Blocks](#SupportedNamedBlocks) section later in this article. > [!TIP] -> Matching can be improved if the string is first normalized by calling the method. +> Matching can be improved if the string is first normalized by calling the method. The following example uses the `\p{`*name*`}` construct to match both a Unicode general category (in this case, the `Pd`, or Punctuation, Dash category) and a named block (the `IsGreek` and `IsBasicLatin` named blocks). @@ -225,7 +225,7 @@ The regular expression construct Matches any character that doesn't belong to a Unicode general category or named block, where *name* is the category abbreviation or named block name. For a list of category abbreviations, see the [Supported Unicode General Categories](#SupportedUnicodeGeneralCategories) section later in this article. For a list of named blocks, see the [Supported Named Blocks](#SupportedNamedBlocks) section later in this article. > [!TIP] -> Matching can be improved if the string is first normalized by calling the method. +> Matching can be improved if the string is first normalized by calling the method. The following example uses the `\P{`*name*`}` construct to remove any currency symbols (in this case, the `Sc`, or Symbol, Currency category) from numeric strings. @@ -303,7 +303,7 @@ The following example illustrates the `\W` character class. It defines a regula :::code language="csharp" source="snippets/character-classes-in-regular-expressions/csharp/Program.cs" id="NonWordCharacter"::: :::code language="vb" source="snippets/character-classes-in-regular-expressions/vb/Program.vb" id="NonWordCharacter"::: -Because the object for the second capturing group contains only a single captured non-word character, the example retrieves all captured non-word characters from the object that is returned by the property. +Because the object for the second capturing group contains only a single captured non-word character, the example retrieves all captured non-word characters from the object that is returned by the property. @@ -446,7 +446,7 @@ Unicode defines the general categories listed in the following table. For more i |`Cn`|Other, Not Assigned or Noncharacter| |`C`|All other characters. This includes the `Cc`, `Cf`, `Cs`, `Co`, and `Cn` categories.| -You can determine the Unicode category of any particular character by passing that character to the method. The following example uses the method to determine the category of each element in an array that contains selected Latin characters. +You can determine the Unicode category of any particular character by passing that character to the method. The following example uses the method to determine the category of each element in an array that contains selected Latin characters. :::code language="csharp" source="snippets/character-classes-in-regular-expressions/csharp/Program.cs" id="GetUnicodeCategory"::: :::code language="vb" source="snippets/character-classes-in-regular-expressions/vb/Program.vb" id="GetUnicodeCategory"::: @@ -598,6 +598,6 @@ The following example defines a regular expression, `^[0-9-[2468]]+$`, that matc ## See also -- +- - [Regular Expression Language - Quick Reference](regular-expression-language-quick-reference.md) - [Regular Expression Options](regular-expression-options.md) diff --git a/docs/standard/base-types/character-encoding-introduction.md b/docs/standard/base-types/character-encoding-introduction.md index 4812e685771e1..4257a605739ad 100644 --- a/docs/standard/base-types/character-encoding-introduction.md +++ b/docs/standard/base-types/character-encoding-introduction.md @@ -200,7 +200,7 @@ The following example throws an exception because the code point is beyond the s ### Rune usage example: changing letter case -An API that takes a `char` and assumes it is working with a code point that is a scalar value doesn't work correctly if the `char` is from a surrogate pair. For example, consider the following method that calls on each char in a string: +An API that takes a `char` and assumes it is working with a code point that is a scalar value doesn't work correctly if the `char` is from a surrogate pair. For example, consider the following method that calls on each char in a string: :::code language="csharp" source="snippets/character-encoding-introduction/csharp/ConvertToUpper.cs" id="SnippetBadExample"::: @@ -208,8 +208,8 @@ If the `input` string contains the lowercase Deseret letter `er` (`𐑉`), this Here are two options for correctly converting a string to uppercase: -* Call on the input string rather than iterating `char`-by-`char`. The `string.ToUpperInvariant` method has access to both parts of each surrogate pair, so it can handle all Unicode code points correctly. -* Iterate through the Unicode scalar values as `Rune` instances instead of `char` instances, as shown in the following example. Since a `Rune` instance is a valid Unicode scalar value, it can be passed to APIs that expect to operate on a scalar value. For example, calling as shown in the following example gives correct results: +* Call on the input string rather than iterating `char`-by-`char`. The `string.ToUpperInvariant` method has access to both parts of each surrogate pair, so it can handle all Unicode code points correctly. +* Iterate through the Unicode scalar values as `Rune` instances instead of `char` instances, as shown in the following example. Since a `Rune` instance is a valid Unicode scalar value, it can be passed to APIs that expect to operate on a scalar value. For example, calling as shown in the following example gives correct results: :::code language="csharp" source="snippets/character-encoding-introduction/csharp/ConvertToUpper.cs" id="SnippetGoodExample"::: @@ -217,16 +217,16 @@ Here are two options for correctly converting a string to uppercase: The `Rune` type exposes analogs of many of the `char` APIs. For example, the following methods mirror static APIs on the `char` type: -* -* -* -* +* +* +* +* -To get the raw scalar value from a `Rune` instance, use the property. +To get the raw scalar value from a `Rune` instance, use the property. -To convert a `Rune` instance back to a sequence of `char`s, use or the method. +To convert a `Rune` instance back to a sequence of `char`s, use or the method. -Since any Unicode scalar value is representable by a single `char` or by a surrogate pair, any `Rune` instance can be represented by at most 2 `char` instances. Use to see how many `char` instances are required to represent a `Rune` instance. +Since any Unicode scalar value is representable by a single `char` or by a surrogate pair, any `Rune` instance can be represented by at most 2 `char` instances. Use to see how many `char` instances are required to represent a `Rune` instance. For more information about the .NET `Rune` type, see the [`Rune` API reference](xref:System.Text.Rune). diff --git a/docs/standard/base-types/character-encoding.md b/docs/standard/base-types/character-encoding.md index 71711e8f066a5..62a07566c5a1a 100644 --- a/docs/standard/base-types/character-encoding.md +++ b/docs/standard/base-types/character-encoding.md @@ -23,19 +23,19 @@ This article explains how to use the classes that .NET provides for encoding and Encoding and decoding can also include validation. For example, the class checks all `char` instances in the surrogate range to make sure they're in valid surrogate pairs. A fallback strategy determines how an encoder handles invalid characters or how a decoder handles invalid bytes. > [!WARNING] -> .NET encoding classes provide a way to store and convert character data. They should not be used to store binary data in string form. Depending on the encoding used, converting binary data to string format with the encoding classes can introduce unexpected behavior and produce inaccurate or corrupted data. To convert binary data to a string form, use the method. +> .NET encoding classes provide a way to store and convert character data. They should not be used to store binary data in string form. Depending on the encoding used, converting binary data to string format with the encoding classes can introduce unexpected behavior and produce inaccurate or corrupted data. To convert binary data to a string form, use the method. All character encoding classes in .NET inherit from the class, which is an abstract class that defines the functionality common to all character encodings. To access the individual encoding objects implemented in .NET, do the following: -- Use the static properties of the class, which return objects that represent the standard character encodings available in .NET (ASCII, UTF-7, UTF-8, UTF-16, and UTF-32). For example, the property returns a object. Each object uses replacement fallback to handle strings that it cannot encode and bytes that it cannot decode. For more information, see [Replacement fallback](character-encoding.md#Replacement). +- Use the static properties of the class, which return objects that represent the standard character encodings available in .NET (ASCII, UTF-7, UTF-8, UTF-16, and UTF-32). For example, the property returns a object. Each object uses replacement fallback to handle strings that it cannot encode and bytes that it cannot decode. For more information, see [Replacement fallback](character-encoding.md#Replacement). - Call the encoding's class constructor. Objects for the ASCII, UTF-7, UTF-8, UTF-16, and UTF-32 encodings can be instantiated in this way. By default, each object uses replacement fallback to handle strings that it cannot encode and bytes that it cannot decode, but you can specify that an exception should be thrown instead. For more information, see [Replacement fallback](character-encoding.md#Replacement) and [Exception fallback](character-encoding.md#Exception). - Call the constructor and pass it an integer that represents the encoding. Standard encoding objects use replacement fallback, and code page and double-byte character set (DBCS) encoding objects use best-fit fallback to handle strings that they cannot encode and bytes that they cannot decode. For more information, see [Best-fit fallback](character-encoding.md#BestFit). -- Call the method, which returns any standard, code page, or DBCS encoding available in .NET. Overloads let you specify a fallback object for both the encoder and the decoder. +- Call the method, which returns any standard, code page, or DBCS encoding available in .NET. Overloads let you specify a fallback object for both the encoder and the decoder. -You can retrieve information about all the encodings available in .NET by calling the method. .NET supports the character encoding schemes listed in the following table. +You can retrieve information about all the encodings available in .NET by calling the method. .NET supports the character encoding schemes listed in the following table. | Encoding class | Description | | -- | -- | @@ -73,31 +73,31 @@ You should consider using only for legacy appli - If your application has content that is not strictly ASCII and encodes it with , the result seems unintelligible if interpreted as ASCII. However, if the application then uses a UTF-8 decoder to decode this data, the data performs a round trip successfully. -In a web application, characters sent to the client in response to a web request should reflect the encoding used on the client. In most cases, you should set the property to the value returned by the property to display text in the encoding that the user expects. +In a web application, characters sent to the client in response to a web request should reflect the encoding used on the client. In most cases, you should set the property to the value returned by the property to display text in the encoding that the user expects. ## Using an Encoding Object -An encoder converts a string of characters (most commonly, Unicode characters) to its numeric (byte) equivalent. For example, you might use an ASCII encoder to convert Unicode characters to ASCII so that they can be displayed at the console. To perform the conversion, you call the method. If you want to determine how many bytes are needed to store the encoded characters before performing the encoding, you can call the method. +An encoder converts a string of characters (most commonly, Unicode characters) to its numeric (byte) equivalent. For example, you might use an ASCII encoder to convert Unicode characters to ASCII so that they can be displayed at the console. To perform the conversion, you call the method. If you want to determine how many bytes are needed to store the encoded characters before performing the encoding, you can call the method. The following example uses a single byte array to encode strings in two separate operations. It maintains an index that indicates the starting position in the byte array for the next set of ASCII-encoded bytes. It calls the method to ensure that the byte array is large enough to accommodate the encoded string. It then calls the method to encode the characters in the string. [!code-csharp[Conceptual.Encoding#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.encoding/cs/getbytes1.cs#8)] [!code-vb[Conceptual.Encoding#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.encoding/vb/getbytes1.vb#8)] -A decoder converts a byte array that reflects a particular character encoding into a set of characters, either in a character array or in a string. To decode a byte array into a character array, you call the method. To decode a byte array into a string, you call the method. If you want to determine how many characters are needed to store the decoded bytes before performing the decoding, you can call the method. +A decoder converts a byte array that reflects a particular character encoding into a set of characters, either in a character array or in a string. To decode a byte array into a character array, you call the method. To decode a byte array into a string, you call the method. If you want to determine how many characters are needed to store the decoded bytes before performing the decoding, you can call the method. -The following example encodes three strings and then decodes them into a single array of characters. It maintains an index that indicates the starting position in the character array for the next set of decoded characters. It calls the method to ensure that the character array is large enough to accommodate all the decoded characters. It then calls the method to decode the byte array. +The following example encodes three strings and then decodes them into a single array of characters. It maintains an index that indicates the starting position in the character array for the next set of decoded characters. It calls the method to ensure that the character array is large enough to accommodate all the decoded characters. It then calls the method to decode the byte array. [!code-csharp[Conceptual.Encoding#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.encoding/cs/getchars1.cs#9)] [!code-vb[Conceptual.Encoding#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.encoding/vb/getchars1.vb#9)] The encoding and decoding methods of a class derived from are designed to work on a complete set of data; that is, all the data to be encoded or decoded is supplied in a single method call. However, in some cases, data is available in a stream, and the data to be encoded or decoded may be available only from separate read operations. This requires the encoding or decoding operation to remember any saved state from its previous invocation. Methods of classes derived from and are able to handle encoding and decoding operations that span multiple method calls. -An object for a particular encoding is available from that encoding's property. A object for a particular encoding is available from that encoding's property. For decoding operations, note that classes derived from include a method, but they do not have a method that corresponds to . +An object for a particular encoding is available from that encoding's property. A object for a particular encoding is available from that encoding's property. For decoding operations, note that classes derived from include a method, but they do not have a method that corresponds to . -The following example illustrates the difference between using the and methods for decoding a Unicode byte array. The example encodes a string that contains some Unicode characters to a file, and then uses the two decoding methods to decode them ten bytes at a time. Because a surrogate pair occurs in the tenth and eleventh bytes, it is decoded in separate method calls. As the output shows, the method is not able to correctly decode the bytes and instead replaces them with U+FFFD (REPLACEMENT CHARACTER). On the other hand, the method is able to successfully decode the byte array to get the original string. +The following example illustrates the difference between using the and methods for decoding a Unicode byte array. The example encodes a string that contains some Unicode characters to a file, and then uses the two decoding methods to decode them ten bytes at a time. Because a surrogate pair occurs in the tenth and eleventh bytes, it is decoded in separate method calls. As the output shows, the method is not able to correctly decode the bytes and instead replaces them with U+FFFD (REPLACEMENT CHARACTER). On the other hand, the method is able to successfully decode the byte array to get the original string. [!code-csharp[Conceptual.Encoding#10](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.encoding/cs/stream1.cs#10)] [!code-vb[Conceptual.Encoding#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.encoding/vb/stream1.vb#10)] @@ -179,9 +179,9 @@ Instead of providing a best-fit fallback or a replacement string, an encoder can The and objects provide the following information about the condition that caused the exception: -- The object includes an method, which indicates whether the character or characters that cannot be encoded represent an unknown surrogate pair (in which case, the method returns `true`) or an unknown single character (in which case, the method returns `false`). The characters in the surrogate pair are available from the and properties. The unknown single character is available from the property. The property indicates the position in the string at which the first character that could not be encoded was found. +- The object includes an method, which indicates whether the character or characters that cannot be encoded represent an unknown surrogate pair (in which case, the method returns `true`) or an unknown single character (in which case, the method returns `false`). The characters in the surrogate pair are available from the and properties. The unknown single character is available from the property. The property indicates the position in the string at which the first character that could not be encoded was found. -- The object includes a property that returns an array of bytes that cannot be decoded. The property indicates the starting position of the unknown bytes. +- The object includes a property that returns an array of bytes that cannot be decoded. The property indicates the starting position of the unknown bytes. Although the and objects provide adequate diagnostic information about the exception, they do not provide access to the encoding or decoding buffer. Therefore, they do not allow invalid data to be replaced or corrected within the encoding or decoding method. @@ -213,25 +213,25 @@ To implement a custom fallback solution, you must create a class that inherits f When you create a custom fallback solution for an encoder or decoder, you must implement the following members: -- The or property, which returns the maximum possible number of characters that the best-fit, replacement, or exception fallback can return to replace a single character. For a custom exception fallback, its value is zero. +- The or property, which returns the maximum possible number of characters that the best-fit, replacement, or exception fallback can return to replace a single character. For a custom exception fallback, its value is zero. -- The or method, which returns your custom or implementation. The method is called by the encoder when it encounters the first character that it is unable to successfully encode, or by the decoder when it encounters the first byte that it is unable to successfully decode. +- The or method, which returns your custom or implementation. The method is called by the encoder when it encounters the first character that it is unable to successfully encode, or by the decoder when it encounters the first byte that it is unable to successfully decode. ### Deriving from EncoderFallbackBuffer or DecoderFallbackBuffer -To implement a custom fallback solution, you must also create a class that inherits from for encoding operations, and from for decoding operations. Instances of these classes are returned by the method of the and classes. The method is called by the encoder when it encounters the first character that it is not able to encode, and the method is called by the decoder when it encounters one or more bytes that it is not able to decode. The and classes provide the fallback implementation. Each instance represents a buffer that contains the fallback characters that will replace the character that cannot be encoded or the byte sequence that cannot be decoded. +To implement a custom fallback solution, you must also create a class that inherits from for encoding operations, and from for decoding operations. Instances of these classes are returned by the method of the and classes. The method is called by the encoder when it encounters the first character that it is not able to encode, and the method is called by the decoder when it encounters one or more bytes that it is not able to decode. The and classes provide the fallback implementation. Each instance represents a buffer that contains the fallback characters that will replace the character that cannot be encoded or the byte sequence that cannot be decoded. When you create a custom fallback solution for an encoder or decoder, you must implement the following members: -- The or method. is called by the encoder to provide the fallback buffer with information about the character that it cannot encode. Because the character to be encoded may be a surrogate pair, this method is overloaded. One overload is passed the character to be encoded and its index in the string. The second overload is passed the high and low surrogate along with its index in the string. The method is called by the decoder to provide the fallback buffer with information about the bytes that it cannot decode. This method is passed an array of bytes that it cannot decode, along with the index of the first byte. The fallback method should return `true` if the fallback buffer can supply a best-fit or replacement character or characters; otherwise, it should return `false`. For an exception fallback, the fallback method should throw an exception. +- The or method. is called by the encoder to provide the fallback buffer with information about the character that it cannot encode. Because the character to be encoded may be a surrogate pair, this method is overloaded. One overload is passed the character to be encoded and its index in the string. The second overload is passed the high and low surrogate along with its index in the string. The method is called by the decoder to provide the fallback buffer with information about the bytes that it cannot decode. This method is passed an array of bytes that it cannot decode, along with the index of the first byte. The fallback method should return `true` if the fallback buffer can supply a best-fit or replacement character or characters; otherwise, it should return `false`. For an exception fallback, the fallback method should throw an exception. -- The or method, which is called repeatedly by the encoder or decoder to get the next character from the fallback buffer. When all fallback characters have been returned, the method should return U+0000. +- The or method, which is called repeatedly by the encoder or decoder to get the next character from the fallback buffer. When all fallback characters have been returned, the method should return U+0000. -- The or property, which returns the number of characters remaining in the fallback buffer. +- The or property, which returns the number of characters remaining in the fallback buffer. -- The or method, which moves the current position in the fallback buffer to the previous character. +- The or method, which moves the current position in the fallback buffer to the previous character. -- The or method, which reinitializes the fallback buffer. +- The or method, which reinitializes the fallback buffer. If the fallback implementation is a best-fit fallback or a replacement fallback, the classes derived from and also maintain two private instance fields: the exact number of characters in the buffer; and the index of the next character in the buffer to return. @@ -239,7 +239,7 @@ If the fallback implementation is a best-fit fallback or a replacement fallback, An earlier example used replacement fallback to replace Unicode characters that did not correspond to ASCII characters with an asterisk (\*). The following example uses a custom best-fit fallback implementation instead to provide a better mapping of non-ASCII characters. -The following code defines a class named `CustomMapper` that is derived from to handle the best-fit mapping of non-ASCII characters. Its `CreateFallbackBuffer` method returns a `CustomMapperFallbackBuffer` object, which provides the implementation. The `CustomMapper` class uses a object to store the mappings of unsupported Unicode characters (the key value) and their corresponding 8-bit characters (which are stored in two consecutive bytes in a 64-bit integer). To make this mapping available to the fallback buffer, the `CustomMapper` instance is passed as a parameter to the `CustomMapperFallbackBuffer` class constructor. Because the longest mapping is the string "INF" for the Unicode character U+221E, the `MaxCharCount` property returns 3. +The following code defines a class named `CustomMapper` that is derived from to handle the best-fit mapping of non-ASCII characters. Its `CreateFallbackBuffer` method returns a `CustomMapperFallbackBuffer` object, which provides the implementation. The `CustomMapper` class uses a object to store the mappings of unsupported Unicode characters (the key value) and their corresponding 8-bit characters (which are stored in two consecutive bytes in a 64-bit integer). To make this mapping available to the fallback buffer, the `CustomMapper` instance is passed as a parameter to the `CustomMapperFallbackBuffer` class constructor. Because the longest mapping is the string "INF" for the Unicode character U+221E, the `MaxCharCount` property returns 3. [!code-csharp[Conceptual.Encoding#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.encoding/cs/custom1.cs#5)] [!code-vb[Conceptual.Encoding#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.encoding/vb/custom1.vb#5)] diff --git a/docs/standard/base-types/choosing-between-anonymous-and-tuple.md b/docs/standard/base-types/choosing-between-anonymous-and-tuple.md index 596c372e6baa9..4979e58e7c9ed 100644 --- a/docs/standard/base-types/choosing-between-anonymous-and-tuple.md +++ b/docs/standard/base-types/choosing-between-anonymous-and-tuple.md @@ -6,7 +6,7 @@ ms.date: 07/01/2020 --- # Choosing between anonymous and tuple types -Choosing the appropriate type involves considering its usability, performance, and tradeoffs compared to other types. Anonymous types have been available since C# 3.0, while generic types were introduced with .NET Framework 4.0. Since then new options have been introduced with language level support, such as - which as the name implies, provide a value type with the flexibility of anonymous types. In this article, you'll learn when it's appropriate to choose one type over the other. +Choosing the appropriate type involves considering its usability, performance, and tradeoffs compared to other types. Anonymous types have been available since C# 3.0, while generic types were introduced with .NET Framework 4.0. Since then new options have been introduced with language level support, such as - which as the name implies, provide a value type with the flexibility of anonymous types. In this article, you'll learn when it's appropriate to choose one type over the other. ## Usability and functionality @@ -64,7 +64,7 @@ foreach (var tuple in } ``` -With the , the instance exposes numbered item properties, such as `Item1`, and `Item2`. These property names can make it more difficult to understand the intent of the property values, as the property name only provides the ordinal. Furthermore, the `System.Tuple` types are reference `class` types. The however, is a value `struct` type. The following C# snippet, uses `ValueTuple` to project into. In doing so, it assigns using a literal syntax. +With the , the instance exposes numbered item properties, such as `Item1`, and `Item2`. These property names can make it more difficult to understand the intent of the property values, as the property name only provides the ordinal. Furthermore, the `System.Tuple` types are reference `class` types. The however, is a value `struct` type. The following C# snippet, uses `ValueTuple` to project into. In doing so, it assigns using a literal syntax. ```csharp var dates = new[] diff --git a/docs/standard/base-types/common-type-system.md b/docs/standard/base-types/common-type-system.md index 674a50546974a..65d009fdbed8e 100644 --- a/docs/standard/base-types/common-type-system.md +++ b/docs/standard/base-types/common-type-system.md @@ -93,7 +93,7 @@ The following additional restrictions apply to enumerations: - They cannot be generic, unless they are generic only because they are nested within a generic type. That is, an enumeration cannot have type parameters of its own. > [!NOTE] - > Nested types (including enumerations) created with Visual Basic, C#, and C++ include the type parameters of all enclosing generic types, and are therefore generic even if they do not have type parameters of their own. For more information, see "Nested Types" in the reference topic. + > Nested types (including enumerations) created with Visual Basic, C#, and C++ include the type parameters of all enclosing generic types, and are therefore generic even if they do not have type parameters of their own. For more information, see "Nested Types" in the reference topic. The attribute denotes a special kind of enumeration called a bit field. The runtime itself does not distinguish between traditional enumerations and bit fields, but your language might do so. When this distinction is made, bitwise operators can be used on bit fields, but not on enumerations, to generate unnamed values. Enumerations are generally used for lists of unique elements, such as days of the week, country or region names, and so on. Bit fields are generally used for lists of qualities or quantities that might occur in combination, such as `Red And Big And Fast`. @@ -104,7 +104,7 @@ The following example shows how to use both bit fields and traditional enumerati ### Interfaces -An interface defines a contract that specifies a "can do" relationship or a "has a" relationship. Interfaces are often used to implement functionality, such as comparing and sorting (the and interfaces), testing for equality (the interface), or enumerating items in a collection (the and interfaces). Interfaces can have properties, methods, and events, all of which are abstract members; that is, although the interface defines the members and their signatures, it leaves it to the type that implements the interface to define the functionality of each interface member. This means that any class or structure that implements an interface must supply definitions for the abstract members declared in the interface. An interface can require any implementing class or structure to also implement one or more other interfaces. +An interface defines a contract that specifies a "can do" relationship or a "has a" relationship. Interfaces are often used to implement functionality, such as comparing and sorting (the and interfaces), testing for equality (the interface), or enumerating items in a collection (the and interfaces). Interfaces can have properties, methods, and events, all of which are abstract members; that is, although the interface defines the members and their signatures, it leaves it to the type that implements the interface to define the functionality of each interface member. This means that any class or structure that implements an interface must supply definitions for the abstract members declared in the interface. An interface can require any implementing class or structure to also implement one or more other interfaces. The following restrictions apply to interfaces: @@ -136,7 +136,7 @@ Because delegates inherit from , a delegate has a In many cases, such as with callback methods, a delegate represents only one method, and the only actions you have to take are creating the delegate and invoking it. -For delegates that represent multiple methods, .NET provides methods of the and delegate classes to support operations such as adding a method to a delegate's invocation list (the method), removing a method (the method), and getting the invocation list (the method). +For delegates that represent multiple methods, .NET provides methods of the and delegate classes to support operations such as adding a method to a delegate's invocation list (the method), removing a method (the method), and getting the invocation list (the method). > [!NOTE] > It is not necessary to use these methods for event-handler delegates in C#, C++, and Visual Basic, because these languages provide syntax for adding and removing event handlers. @@ -272,7 +272,7 @@ The common type system allows type members to have a variety of characteristics; ### Overloading -Each type member has a unique signature. Method signatures consist of the method name and a parameter list (the order and types of the method's arguments). Multiple methods with the same name can be defined within a type as long as their signatures differ. When two or more methods with the same name are defined, the method is said to be overloaded. For example, in , the method is overloaded. One method takes a . The other method takes a and an . +Each type member has a unique signature. Method signatures consist of the method name and a parameter list (the order and types of the method's arguments). Multiple methods with the same name can be defined within a type as long as their signatures differ. When two or more methods with the same name are defined, the method is said to be overloaded. For example, in , the method is overloaded. One method takes a . The other method takes a and an . > [!NOTE] > The return type is not considered part of a method's signature. That is, methods cannot be overloaded if they differ only by return type. diff --git a/docs/standard/base-types/comparing.md b/docs/standard/base-types/comparing.md index fd0d70a0ccf7a..968b14e6f3481 100644 --- a/docs/standard/base-types/comparing.md +++ b/docs/standard/base-types/comparing.md @@ -25,19 +25,19 @@ helpviewer_keywords: | Method name | Use | |--|--| -| | Compares the values of two strings. Returns an integer value. | -| | Compares two strings without regard to local culture. Returns an integer value. | -| | Compares the current string object to another string. Returns an integer value. | -| | Determines whether a string begins with the string passed. Returns a Boolean value. | -| | Determines whether a string ends with the string passed. Returns a Boolean value. | -| | Determines whether a character or string occurs within another string. Returns a Boolean value. | -| | Determines whether two strings are the same. Returns a Boolean value. | -| | Returns the index position of a character or string, starting from the beginning of the string you are examining. Returns an integer value. | -| | Returns the index position of a character or string, starting from the end of the string you are examining. Returns an integer value. | +| | Compares the values of two strings. Returns an integer value. | +| | Compares two strings without regard to local culture. Returns an integer value. | +| | Compares the current string object to another string. Returns an integer value. | +| | Determines whether a string begins with the string passed. Returns a Boolean value. | +| | Determines whether a string ends with the string passed. Returns a Boolean value. | +| | Determines whether a character or string occurs within another string. Returns a Boolean value. | +| | Determines whether two strings are the same. Returns a Boolean value. | +| | Returns the index position of a character or string, starting from the beginning of the string you are examining. Returns an integer value. | +| | Returns the index position of a character or string, starting from the end of the string you are examining. Returns an integer value. | ## `Compare` method -The static method provides a thorough way of comparing two strings. This method is culturally aware. You can use this function to compare two strings or substrings of two strings. Additionally, overloads are provided that regard or disregard case and cultural variance. The following table shows the three integer values that this method might return. +The static method provides a thorough way of comparing two strings. This method is culturally aware. You can use this function to compare two strings or substrings of two strings. Additionally, overloads are provided that regard or disregard case and cultural variance. The following table shows the three integer values that this method might return. | Return value | Condition | |--|--| @@ -46,23 +46,23 @@ The static method p | A positive integer

-or-

1 | The first string follows the second string in the sort order.

-or-

The second string is `null`. | > [!IMPORTANT] -> The method is primarily intended for use when ordering or sorting strings. You should not use the method to test for equality (that is, to explicitly look for a return value of 0 with no regard for whether one string is less than or greater than the other). Instead, to determine whether two strings are equal, use the method. +> The method is primarily intended for use when ordering or sorting strings. You should not use the method to test for equality (that is, to explicitly look for a return value of 0 with no regard for whether one string is less than or greater than the other). Instead, to determine whether two strings are equal, use the method. - The following example uses the method to determine the relative values of two strings. + The following example uses the method to determine the relative values of two strings. [!code-csharp[Conceptual.String.BasicOps#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/compare.cs#6)] [!code-vb[Conceptual.String.BasicOps#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.string.basicops/vb/compare.vb#6)] This example displays `-1` to the console. - The preceding example is culture-sensitive by default. To perform a culture-insensitive string comparison, use an overload of the method that allows you to specify the culture to use by supplying a *culture* parameter. For an example that demonstrates how to use the method to perform a culture-insensitive comparison, see [Culture-insensitive string comparisons](../../core/extensions/performing-culture-insensitive-string-comparisons.md). + The preceding example is culture-sensitive by default. To perform a culture-insensitive string comparison, use an overload of the method that allows you to specify the culture to use by supplying a *culture* parameter. For an example that demonstrates how to use the method to perform a culture-insensitive comparison, see [Culture-insensitive string comparisons](../../core/extensions/performing-culture-insensitive-string-comparisons.md). ## `CompareOrdinal` method -The method compares two string objects without considering the local culture. The return values of this method are identical to the values returned by the `Compare` method in the previous table. +The method compares two string objects without considering the local culture. The return values of this method are identical to the values returned by the `Compare` method in the previous table. > [!IMPORTANT] -> The method is primarily intended for use when ordering or sorting strings. You should not use the method to test for equality (that is, to explicitly look for a return value of 0 with no regard for whether one string is less than or greater than the other). Instead, to determine whether two strings are equal, use the method. +> The method is primarily intended for use when ordering or sorting strings. You should not use the method to test for equality (that is, to explicitly look for a return value of 0 with no regard for whether one string is less than or greater than the other). Instead, to determine whether two strings are equal, use the method. The following example uses the `CompareOrdinal` method to compare the values of two strings. @@ -73,23 +73,23 @@ The method c ## `CompareTo` method -The method compares the string that the current string object encapsulates to another string or object. The return values of this method are identical to the values returned by the method in the previous table. +The method compares the string that the current string object encapsulates to another string or object. The return values of this method are identical to the values returned by the method in the previous table. > [!IMPORTANT] -> The method is primarily intended for use when ordering or sorting strings. You should not use the method to test for equality (that is, to explicitly look for a return value of 0 with no regard for whether one string is less than or greater than the other). Instead, to determine whether two strings are equal, use the method. +> The method is primarily intended for use when ordering or sorting strings. You should not use the method to test for equality (that is, to explicitly look for a return value of 0 with no regard for whether one string is less than or greater than the other). Instead, to determine whether two strings are equal, use the method. - The following example uses the method to compare the `string1` object to the `string2` object. + The following example uses the method to compare the `string1` object to the `string2` object. [!code-csharp[Conceptual.String.BasicOps#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/compare.cs#8)] [!code-vb[Conceptual.String.BasicOps#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.string.basicops/vb/compare.vb#8)] This example displays `-1` to the console. - All overloads of the method perform culture-sensitive and case-sensitive comparisons by default. No overloads of this method are provided that allow you to perform a culture-insensitive comparison. For code clarity, we recommend that you use the `String.Compare` method instead, specifying for culture-sensitive operations or for culture-insensitive operations. For examples that demonstrate how to use the `String.Compare` method to perform both culture-sensitive and culture-insensitive comparisons, see [Performing Culture-Insensitive String Comparisons](../../core/extensions/performing-culture-insensitive-string-comparisons.md). + All overloads of the method perform culture-sensitive and case-sensitive comparisons by default. No overloads of this method are provided that allow you to perform a culture-insensitive comparison. For code clarity, we recommend that you use the `String.Compare` method instead, specifying for culture-sensitive operations or for culture-insensitive operations. For examples that demonstrate how to use the `String.Compare` method to perform both culture-sensitive and culture-insensitive comparisons, see [Performing Culture-Insensitive String Comparisons](../../core/extensions/performing-culture-insensitive-string-comparisons.md). ## `Equals` method -The method can easily determine if two strings are the same. This case-sensitive method returns a `true` or `false` Boolean value. It can be used from an existing class, as illustrated in the next example. The following example uses the `Equals` method to determine whether a string object contains the phrase "Hello World". +The method can easily determine if two strings are the same. This case-sensitive method returns a `true` or `false` Boolean value. It can be used from an existing class, as illustrated in the next example. The following example uses the `Equals` method to determine whether a string object contains the phrase "Hello World". [!code-csharp[Conceptual.String.BasicOps#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/compare.cs#9)] [!code-vb[Conceptual.String.BasicOps#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.string.basicops/vb/compare.vb#9)] @@ -105,14 +105,14 @@ The method can easil ## `StartsWith` and `EndsWith` methods -You can use the method to determine whether a string object begins with the same characters that encompass another string. This case-sensitive method returns `true` if the current string object begins with the passed string and `false` if it does not. The following example uses this method to determine if a string object begins with "Hello". +You can use the method to determine whether a string object begins with the same characters that encompass another string. This case-sensitive method returns `true` if the current string object begins with the passed string and `false` if it does not. The following example uses this method to determine if a string object begins with "Hello". [!code-csharp[Conceptual.String.BasicOps#11](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/compare.cs#11)] [!code-vb[Conceptual.String.BasicOps#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.string.basicops/vb/compare.vb#11)] This example displays `True` to the console. - The method compares a passed string to the characters that exist at the end of the current string object. It also returns a Boolean value. The following example checks the end of a string using the `EndsWith` method. + The method compares a passed string to the characters that exist at the end of the current string object. It also returns a Boolean value. The following example checks the end of a string using the `EndsWith` method. [!code-csharp[Conceptual.String.BasicOps#12](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/compare.cs#12)] [!code-vb[Conceptual.String.BasicOps#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.string.basicops/vb/compare.vb#12)] @@ -121,7 +121,7 @@ You can use the ## `IndexOf` and `LastIndexOf` methods -You can use the method to determine the position of the first occurrence of a particular character within a string. This case-sensitive method starts counting from the beginning of a string and returns the position of a passed character using a zero-based index. If the character cannot be found, a value of –1 is returned. +You can use the method to determine the position of the first occurrence of a particular character within a string. This case-sensitive method starts counting from the beginning of a string and returns the position of a passed character using a zero-based index. If the character cannot be found, a value of –1 is returned. The following example uses the `IndexOf` method to search for the first occurrence of the '`l`' character in a string. @@ -130,7 +130,7 @@ The following example uses the `IndexOf` method to search for the first occurren This example displays `2` to the console. - The method is similar to the `String.IndexOf` method except that it returns the position of the last occurrence of a particular character within a string. It is case-sensitive and uses a zero-based index. + The method is similar to the `String.IndexOf` method except that it returns the position of the last occurrence of a particular character within a string. It is case-sensitive and uses a zero-based index. The following example uses the `LastIndexOf` method to search for the last occurrence of the '`l`' character in a string. @@ -139,7 +139,7 @@ The following example uses the `IndexOf` method to search for the first occurren This example displays `9` to the console. - Both methods are useful when used in conjunction with the method. You can use either the `IndexOf` or `LastIndexOf` methods to retrieve the position of a character, and then supply that position to the `Remove` method in order to remove a character or a word that begins with that character. + Both methods are useful when used in conjunction with the method. You can use either the `IndexOf` or `LastIndexOf` methods to retrieve the position of a character, and then supply that position to the `Remove` method in order to remove a character or a word that begins with that character. ## See also diff --git a/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md b/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md index 480e0fbfa46f1..81094c8ba3500 100644 --- a/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md +++ b/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md @@ -35,7 +35,7 @@ Where possible, use source-generated regular expressions instead of compiling re To improve performance, the regular expression engine maintains an application-wide cache of compiled regular expressions. The cache stores regular expression patterns that are used only in static method calls. (Regular expression patterns supplied to instance methods aren't cached.) Caching avoids the need to reparse an expression into high-level byte code each time it's used. -The maximum number of cached regular expressions is determined by the value of the `static` (`Shared` in Visual Basic) property. By default, the regular expression engine caches up to 15 compiled regular expressions. If the number of compiled regular expressions exceeds the cache size, the least recently used regular expression is discarded and the new regular expression is cached. +The maximum number of cached regular expressions is determined by the value of the `static` (`Shared` in Visual Basic) property. By default, the regular expression engine caches up to 15 compiled regular expressions. If the number of compiled regular expressions exceeds the cache size, the least recently used regular expression is discarded and the new regular expression is cached. Your application can reuse regular expressions in one of the following two ways: diff --git a/docs/standard/base-types/composite-formatting.md b/docs/standard/base-types/composite-formatting.md index 4a4be55abd5b5..b9b5a7690fdf1 100644 --- a/docs/standard/base-types/composite-formatting.md +++ b/docs/standard/base-types/composite-formatting.md @@ -24,10 +24,10 @@ The .NET composite formatting feature takes a list of objects and a composite fo The following methods support the composite formatting feature: -- , which returns a formatted result string. -- , which appends a formatted result string to a object. -- Some overloads of the method, which display a formatted result string to the console. -- Some overloads of the method, which write the formatted result string to a stream or file. The classes derived from , such as and , also share this functionality. +- , which returns a formatted result string. +- , which appends a formatted result string to a object. +- Some overloads of the method, which display a formatted result string to the console. +- Some overloads of the method, which write the formatted result string to a stream or file. The classes derived from , such as and , also share this functionality. - , which outputs a formatted message to trace listeners. - The , , and methods, which output formatted messages to trace listeners. - The method, which writes an informational method to trace listeners. @@ -36,7 +36,7 @@ The following methods support the composite formatting feature: A composite format string and object list are used as arguments of methods that support the composite formatting feature. A composite format string consists of zero or more runs of fixed text intermixed with one or more format items. The fixed text is any string that you choose, and each format item corresponds to an object or boxed structure in the list. The string representation of each object replaces the corresponding format item. -Consider the following code fragment: +Consider the following code fragment: :::code language="csharp" source="./snippets/composite-formatting/net/csharp/Program.cs" id="basic"::: :::code language="vb" source="./snippets/composite-formatting/net/vb/Program.vb" id="basic"::: @@ -139,22 +139,22 @@ One way to write your code to avoid misinterpreting escaped braces and format it ### Processing order -If the call to the composite formatting method includes an argument whose value isn't `null`, the runtime calls its method to request an implementation. If the method can return an implementation, it's cached during the call of the composite formatting method. +If the call to the composite formatting method includes an argument whose value isn't `null`, the runtime calls its method to request an implementation. If the method can return an implementation, it's cached during the call of the composite formatting method. Each value in the parameter list that corresponds to a format item is converted to a string as follows: 1. If the value to be formatted is `null`, an empty string is returned. -1. If an implementation is available, the runtime calls its method. The runtime passes the format item's `formatString` value (or `null` if it's not present) to the method. The runtime also passes the implementation to the method. If the call to the method returns `null`, execution proceeds to the next step. Otherwise, the result of the call is returned. +1. If an implementation is available, the runtime calls its method. The runtime passes the format item's `formatString` value (or `null` if it's not present) to the method. The runtime also passes the implementation to the method. If the call to the method returns `null`, execution proceeds to the next step. Otherwise, the result of the call is returned. 1. If the value implements the interface, the interface's method is called. If one is present in the format item, the `formatString` value is passed to the method. Otherwise, `null` is passed. The argument is determined as follows: - - For a numeric value, if a composite formatting method with a non-null argument is called, the runtime requests a object from its method. If it's unable to supply one, if the value of the argument is `null`, or if the composite formatting method doesn't have an parameter, the object for the current culture is used. - - For a date and time value, if a composite formatting method with a non-null argument is called, the runtime requests a object from its method. In the following situations, the object for the current culture is used instead: + - For a numeric value, if a composite formatting method with a non-null argument is called, the runtime requests a object from its method. If it's unable to supply one, if the value of the argument is `null`, or if the composite formatting method doesn't have an parameter, the object for the current culture is used. + - For a date and time value, if a composite formatting method with a non-null argument is called, the runtime requests a object from its method. In the following situations, the object for the current culture is used instead: - - The method is unable to supply a object. + - The method is unable to supply a object. - The value of the argument is `null`. - The composite formatting method doesn't have an parameter. - - For objects of other types, if a composite formatting method is called with an argument, its value is passed directly to the implementation. Otherwise, `null` is passed to the implementation. + - For objects of other types, if a composite formatting method is called with an argument, its value is passed directly to the implementation. Otherwise, `null` is passed to the implementation. 1. The type's parameterless `ToString` method, which either overrides or inherits the behavior of its base class, is called. In this case, the format string specified by the `formatString` component in the format item, if it's present, is ignored. @@ -169,7 +169,7 @@ The following example shows one string created using composite formatting and an Assuming that the current day is a Thursday in May, the value of both strings in the preceding example is `Thursday May` in the U.S. English culture. - exposes the same functionality as . The only difference between the two methods is that returns its result as a string, while writes the result to the output stream associated with the object. The following example uses the method to format the value of `myNumber` to a currency value: + exposes the same functionality as . The only difference between the two methods is that returns its result as a string, while writes the result to the output stream associated with the object. The following example uses the method to format the value of `myNumber` to a currency value: :::code language="csharp" source="./snippets/composite-formatting/net/csharp/Program.cs" id="example_currency"::: :::code language="vb" source="./snippets/composite-formatting/net/vb/Program.vb" id="example_currency"::: @@ -186,8 +186,8 @@ The following example demonstrates the use of width in formatting. The arguments ## See also -- -- +- +- - [String interpolation (C#)](../../csharp/language-reference/tokens/interpolated.md) - [String interpolation (Visual Basic)](../../visual-basic/programming-guide/language-features/strings/interpolated-strings.md) - [Formatting types](formatting-types.md) diff --git a/docs/standard/base-types/creating-new.md b/docs/standard/base-types/creating-new.md index 9c494a44a289c..ccfc8035d8cd3 100644 --- a/docs/standard/base-types/creating-new.md +++ b/docs/standard/base-types/creating-new.md @@ -1,111 +1,111 @@ ---- -title: "Creating New Strings" -description: Learn to create strings using assignment, class constructors, or System.String methods that combine several strings, arrays of strings, or objects in .NET. -ms.date: "03/16/2026" -ai-usage: ai-assisted -dev_langs: - - "csharp" - - "vb" -helpviewer_keywords: - - "CopyTo method" - - "Join method" - - "Format method" - - "Concat method" - - "strings [.NET], creating" - - "Insert method" - - "Create method" ---- -# Create new strings in .NET - -.NET allows strings to be created using simple assignment, and also overloads a class constructor to support string creation using a number of different parameters. .NET also provides several methods in the class that create new string objects by combining several strings, arrays of strings, or objects. - -## Create strings using assignment - -The easiest way to create a new object is simply to assign a string literal to a object. - -## Create strings using a class constructor - -You can use overloads of the class constructor to create strings from character arrays. You can also create a new string by duplicating a particular character a specified number of times. The constructor overload accepts a or a stack-allocated of characters and avoids allocating an intermediate character array on the managed heap when you build small strings of a known size, although the resulting string instance is still allocated on the managed heap. - -## Methods that return strings - -The following table lists several useful methods that return new string objects. - -| Method name | Use | -|---------------------------------------------------------------|--------------------------------------------------------| -| | Builds a formatted string from a set of input objects. | -| | Builds strings from two or more strings. | -| | Builds a new string by combining an array of strings. | -| | Builds a new string by inserting a string into the specified index of an existing string. | -| | Copies specified characters in a string into a specified position in an array of characters. | -| | Creates a new string of a specified length, populating characters via a callback that receives a writable and a caller-supplied state object. | - -### `String.Format` - -You can use the `String.Format` method to create formatted strings and concatenate strings representing multiple objects. This method automatically converts any passed object into a string. For example, if your application must display an `Int32` value and a `DateTime` value to the user, you can easily construct a string to represent these values using the `Format` method. For information about formatting conventions used with this method, see the section on [composite formatting](composite-formatting.md). - -The following example uses the `Format` method to create a string that uses an integer variable. - -[!code-csharp[Strings.Creating#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#1)] -[!code-vb[Strings.Creating#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#1)] - -In this example, displays the current date and time in a manner specified by the culture associated with the current thread. - -### `String.Concat` - -The `String.Concat` method can be used to easily create a new string object from two or more existing objects. It provides a language-independent way to concatenate strings. This method accepts any class that derives from `System.Object`. The following example creates a string from two existing string objects and a separating character. - -[!code-csharp[Strings.Creating#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#2)] -[!code-vb[Strings.Creating#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#2)] - -### `String.Join` - -The `String.Join` method creates a new string from an array of strings and a separator string. This method is useful if you want to concatenate multiple strings together, making a list perhaps separated by a comma. - -The following example uses a space to bind a string array. - -[!code-csharp[Strings.Creating#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#3)] -[!code-vb[Strings.Creating#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#3)] - -### `String.Insert` - -The `String.Insert` method creates a new string by inserting a string into a specified position in another string. This method uses a zero-based index. The following example inserts a string into the fifth index position of `MyString` and creates a new string with this value. - -[!code-csharp[Strings.Creating#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#4)] -[!code-vb[Strings.Creating#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#4)] - -### `String.CopyTo` - -The `String.CopyTo` method copies portions of a string into an array of characters. You can specify both the beginning index of the string and the number of characters to be copied. This method takes the source index, an array of characters, the destination index, and the number of characters to copy. All indexes are zero-based. - -The following example uses the `CopyTo` method to copy the characters of the word "Hello" from a string object to the first index position of an array of characters. - -[!code-csharp[Strings.Creating#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#5)] -[!code-vb[Strings.Creating#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#5)] - -### `String.Create` - -The method lets you programmatically fill a new string's characters using a callback. The callback receives a writable of characters and a caller-supplied state object, so you can build the string's content without allocating intermediate character buffers. The callback itself might still allocate, for example if it captures local variables or calls other allocation-heavy APIs. - -The following example uses `String.Create` to build a five-character string from consecutive alphabet characters: - -:::code language="csharp" source="./snippets/creating-new/csharp/Program.cs" id="UsingStringCreate"::: -:::code language="vb" source="./snippets/creating-new/vb/Program.vb" id="UsingStringCreate"::: - -`String.Create` is designed for performance-sensitive scenarios where you know the final string length in advance and want to avoid allocating intermediate character buffers. The runtime allocates a new string, passes its backing buffer directly to your callback as a `Span`, and returns the immutable string once the callback returns. No copy of the data occurs after the callback completes. - -#### `String.Create` vs. `new String(Span)` - -Another option for building strings efficiently is to allocate a character buffer with `stackalloc`, fill it, and pass it to the `String(ReadOnlySpan)` constructor: - -:::code language="csharp" source="./snippets/creating-new/csharp/Program.cs" id="UsingSpanConstructor"::: - -Both approaches allocate the final string exactly once. The key differences are: - -- **`stackalloc` + `new string(span)`** places the working buffer on the stack. This is fastest for *small, fixed-size* buffers, but the stack is a finite resource; large or deeply nested allocations can cause a `StackOverflowException`. This example shows the C# `stackalloc` pattern; Visual Basic doesn't support `stackalloc`, but it can still call the `String(ReadOnlySpan)` constructor when you have a `ReadOnlySpan`. -- **`String.Create`** allocates the working buffer on the heap as part of the string object itself, so there's no stack pressure. It also accepts a typed state parameter that the runtime passes to your callback without boxing, avoiding boxing allocations when the state is a reference type or a non-captured struct. -In general, prefer `stackalloc` + `new String(span)` for small strings (typically fewer than a few hundred characters) with a known, bounded size. Use `String.Create` when the size might be large, when you want to avoid stack pressure, or when passing state into the callback without boxing. - -## See also - -- [Composite Formatting](composite-formatting.md) +--- +title: "Creating New Strings" +description: Learn to create strings using assignment, class constructors, or System.String methods that combine several strings, arrays of strings, or objects in .NET. +ms.date: "03/16/2026" +ai-usage: ai-assisted +dev_langs: + - "csharp" + - "vb" +helpviewer_keywords: + - "CopyTo method" + - "Join method" + - "Format method" + - "Concat method" + - "strings [.NET], creating" + - "Insert method" + - "Create method" +--- +# Create new strings in .NET + +.NET allows strings to be created using simple assignment, and also overloads a class constructor to support string creation using a number of different parameters. .NET also provides several methods in the class that create new string objects by combining several strings, arrays of strings, or objects. + +## Create strings using assignment + +The easiest way to create a new object is simply to assign a string literal to a object. + +## Create strings using a class constructor + +You can use overloads of the class constructor to create strings from character arrays. You can also create a new string by duplicating a particular character a specified number of times. The constructor overload accepts a or a stack-allocated of characters and avoids allocating an intermediate character array on the managed heap when you build small strings of a known size, although the resulting string instance is still allocated on the managed heap. + +## Methods that return strings + +The following table lists several useful methods that return new string objects. + +| Method name | Use | +|---------------------------------------------------------------|--------------------------------------------------------| +| | Builds a formatted string from a set of input objects. | +| | Builds strings from two or more strings. | +| | Builds a new string by combining an array of strings. | +| | Builds a new string by inserting a string into the specified index of an existing string. | +| | Copies specified characters in a string into a specified position in an array of characters. | +| | Creates a new string of a specified length, populating characters via a callback that receives a writable and a caller-supplied state object. | + +### `String.Format` + +You can use the `String.Format` method to create formatted strings and concatenate strings representing multiple objects. This method automatically converts any passed object into a string. For example, if your application must display an `Int32` value and a `DateTime` value to the user, you can easily construct a string to represent these values using the `Format` method. For information about formatting conventions used with this method, see the section on [composite formatting](composite-formatting.md). + +The following example uses the `Format` method to create a string that uses an integer variable. + +[!code-csharp[Strings.Creating#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#1)] +[!code-vb[Strings.Creating#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#1)] + +In this example, displays the current date and time in a manner specified by the culture associated with the current thread. + +### `String.Concat` + +The `String.Concat` method can be used to easily create a new string object from two or more existing objects. It provides a language-independent way to concatenate strings. This method accepts any class that derives from `System.Object`. The following example creates a string from two existing string objects and a separating character. + +[!code-csharp[Strings.Creating#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#2)] +[!code-vb[Strings.Creating#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#2)] + +### `String.Join` + +The `String.Join` method creates a new string from an array of strings and a separator string. This method is useful if you want to concatenate multiple strings together, making a list perhaps separated by a comma. + +The following example uses a space to bind a string array. + +[!code-csharp[Strings.Creating#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#3)] +[!code-vb[Strings.Creating#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#3)] + +### `String.Insert` + +The `String.Insert` method creates a new string by inserting a string into a specified position in another string. This method uses a zero-based index. The following example inserts a string into the fifth index position of `MyString` and creates a new string with this value. + +[!code-csharp[Strings.Creating#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#4)] +[!code-vb[Strings.Creating#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#4)] + +### `String.CopyTo` + +The `String.CopyTo` method copies portions of a string into an array of characters. You can specify both the beginning index of the string and the number of characters to be copied. This method takes the source index, an array of characters, the destination index, and the number of characters to copy. All indexes are zero-based. + +The following example uses the `CopyTo` method to copy the characters of the word "Hello" from a string object to the first index position of an array of characters. + +[!code-csharp[Strings.Creating#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#5)] +[!code-vb[Strings.Creating#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#5)] + +### `String.Create` + +The method lets you programmatically fill a new string's characters using a callback. The callback receives a writable of characters and a caller-supplied state object, so you can build the string's content without allocating intermediate character buffers. The callback itself might still allocate, for example if it captures local variables or calls other allocation-heavy APIs. + +The following example uses `String.Create` to build a five-character string from consecutive alphabet characters: + +:::code language="csharp" source="./snippets/creating-new/csharp/Program.cs" id="UsingStringCreate"::: +:::code language="vb" source="./snippets/creating-new/vb/Program.vb" id="UsingStringCreate"::: + +`String.Create` is designed for performance-sensitive scenarios where you know the final string length in advance and want to avoid allocating intermediate character buffers. The runtime allocates a new string, passes its backing buffer directly to your callback as a `Span`, and returns the immutable string once the callback returns. No copy of the data occurs after the callback completes. + +#### `String.Create` vs. `new String(Span)` + +Another option for building strings efficiently is to allocate a character buffer with `stackalloc`, fill it, and pass it to the `String(ReadOnlySpan)` constructor: + +:::code language="csharp" source="./snippets/creating-new/csharp/Program.cs" id="UsingSpanConstructor"::: + +Both approaches allocate the final string exactly once. The key differences are: + +- **`stackalloc` + `new string(span)`** places the working buffer on the stack. This is fastest for *small, fixed-size* buffers, but the stack is a finite resource; large or deeply nested allocations can cause a `StackOverflowException`. This example shows the C# `stackalloc` pattern; Visual Basic doesn't support `stackalloc`, but it can still call the `String(ReadOnlySpan)` constructor when you have a `ReadOnlySpan`. +- **`String.Create`** allocates the working buffer on the heap as part of the string object itself, so there's no stack pressure. It also accepts a typed state parameter that the runtime passes to your callback without boxing, avoiding boxing allocations when the state is a reference type or a non-captured struct. +In general, prefer `stackalloc` + `new String(span)` for small strings (typically fewer than a few hundred characters) with a known, bounded size. Use `String.Create` when the size might be large, when you want to avoid stack pressure, or when passing state into the callback without boxing. + +## See also + +- [Composite Formatting](composite-formatting.md) diff --git a/docs/standard/base-types/custom-date-and-time-format-strings.md b/docs/standard/base-types/custom-date-and-time-format-strings.md index dd30d90e05548..925d7b3891589 100644 --- a/docs/standard/base-types/custom-date-and-time-format-strings.md +++ b/docs/standard/base-types/custom-date-and-time-format-strings.md @@ -32,7 +32,7 @@ In formatting operations, custom date and time format strings can be used either [!code-csharp[Formatting.DateAndTime.Custom#17](~/samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/custandformatting1.cs#17)] [!code-vb[Formatting.DateAndTime.Custom#17](~/samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/custandformatting1.vb#17)] -In parsing operations, custom date and time format strings can be used with the , , , and methods. These methods require that an input string conforms exactly to a particular pattern for the parse operation to succeed. The following example illustrates a call to the method to parse a date that must include a day, a month, and a two-digit year. +In parsing operations, custom date and time format strings can be used with the , , , and methods. These methods require that an input string conforms exactly to a particular pattern for the parse operation to succeed. The following example illustrates a call to the method to parse a date that must include a day, a month, and a two-digit year. [!code-csharp[Formatting.DateAndTime.Custom#18](~/samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/custandparsing1.cs#18)] [!code-vb[Formatting.DateAndTime.Custom#18](~/samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/custandparsing1.vb#18)] @@ -120,7 +120,7 @@ The following example includes the "dd" custom format specifier in a custom form ### The "ddd" custom format specifier -The "ddd" custom format specifier represents the abbreviated name of the day of the week. The localized abbreviated name of the day of the week is retrieved from the property of the current or specified culture. +The "ddd" custom format specifier represents the abbreviated name of the day of the week. The localized abbreviated name of the day of the week is retrieved from the property of the current or specified culture. The following example includes the "ddd" custom format specifier in a custom format string. @@ -131,7 +131,7 @@ The following example includes the "ddd" custom format specifier in a custom for ### The "dddd" custom format specifier -The "dddd" custom format specifier (plus any number of additional "d" specifiers) represents the full name of the day of the week. The localized name of the day of the week is retrieved from the property of the current or specified culture. +The "dddd" custom format specifier (plus any number of additional "d" specifiers) represents the full name of the day of the week. The localized name of the day of the week is retrieved from the property of the current or specified culture. The following example includes the "dddd" custom format specifier in a custom format string. @@ -148,7 +148,7 @@ The "f" custom format specifier represents the most significant digit of the sec If the "f" format specifier is used without other format specifiers, it's interpreted as the "f" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this article. -When you use "f" format specifiers as part of a format string supplied to the , , , or method, the number of "f" format specifiers indicates the number of most significant digits of the seconds fraction that must be present to successfully parse the string. +When you use "f" format specifiers as part of a format string supplied to the , , , or method, the number of "f" format specifiers indicates the number of most significant digits of the seconds fraction that must be present to successfully parse the string. The following example includes the "f" custom format specifier in a custom format string. @@ -219,7 +219,7 @@ The "F" custom format specifier represents the most significant digit of the sec If the "F" format specifier is used without other format specifiers, it's interpreted as the "F" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this article. -The number of "F" format specifiers used with the , , , or method indicates the maximum number of most significant digits of the seconds fraction that can be present to successfully parse the string. +The number of "F" format specifiers used with the , , , or method indicates the maximum number of most significant digits of the seconds fraction that can be present to successfully parse the string. The following example includes the "F" custom format specifier in a custom format string. @@ -356,13 +356,13 @@ The following example includes the "HH" custom format specifier in a custom form ### The "K" custom format specifier -The "K" custom format specifier represents the time zone information of a date and time value. When this format specifier is used with values, the result string is defined by the value of the property: +The "K" custom format specifier represents the time zone information of a date and time value. When this format specifier is used with values, the result string is defined by the value of the property: -- For the local time zone (a property value of ), this specifier produces a result string containing the local offset from Coordinated Universal Time (UTC); for example, "-07:00". +- For the local time zone (a property value of ), this specifier produces a result string containing the local offset from Coordinated Universal Time (UTC); for example, "-07:00". -- For a UTC time (a property value of ), the result string includes a "Z" character to represent a UTC date. +- For a UTC time (a property value of ), the result string includes a "Z" character to represent a UTC date. -- For a time from an unspecified time zone (a time whose property equals ), the result is equivalent to . +- For a time from an unspecified time zone (a time whose property equals ), the result is equivalent to . For values, the "K" format specifier is equivalent to the "zzz" format specifier, and produces a result string containing the value's offset from UTC. @@ -429,7 +429,7 @@ The following example includes the "MM" custom format specifier in a custom form ### The "MMM" custom format specifier -The "MMM" custom format specifier represents the abbreviated name of the month. The localized abbreviated name of the month is retrieved from the property of the current or specified culture. If there is a "d" or "dd" custom format specifier in the custom format string, it is retrieved from the property instead, except in .NET Framework. (This is known issue that's fixed in .NET.) +The "MMM" custom format specifier represents the abbreviated name of the month. The localized abbreviated name of the month is retrieved from the property of the current or specified culture. If there is a "d" or "dd" custom format specifier in the custom format string, it is retrieved from the property instead, except in .NET Framework. (This is known issue that's fixed in .NET.) The following example includes the "MMM" custom format specifier in a custom format string. @@ -440,7 +440,7 @@ The following example includes the "MMM" custom format specifier in a custom for ### The "MMMM" custom format specifier -The "MMMM" custom format specifier represents the full name of the month. The localized name of the month is retrieved from the property of the current or specified culture. If there is a "d" or "dd" custom format specifier in the custom format string, it is retrieved from the property instead. +The "MMMM" custom format specifier represents the full name of the month. The localized name of the month is retrieved from the property of the current or specified culture. If there is a "d" or "dd" custom format specifier in the custom format string, it is retrieved from the property instead. The following example includes the "MMMM" custom format specifier in a custom format string. @@ -479,7 +479,7 @@ The following example includes the "ss" custom format specifier in a custom form ### The "t" custom format specifier -The "t" custom format specifier represents the first character of the AM/PM designator. The appropriate localized designator is retrieved from the or property of the current or specific culture. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. +The "t" custom format specifier represents the first character of the AM/PM designator. The appropriate localized designator is retrieved from the or property of the current or specific culture. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. If the "t" format specifier is used without other custom format specifiers, it's interpreted as the "t" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this article. @@ -492,7 +492,7 @@ The following example includes the "t" custom format specifier in a custom forma ### The "tt" custom format specifier -The "tt" custom format specifier (plus any number of additional "t" specifiers) represents the entire AM/PM designator. The appropriate localized designator is retrieved from the or property of the current or specific culture. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. +The "tt" custom format specifier (plus any number of additional "t" specifiers) represents the entire AM/PM designator. The appropriate localized designator is retrieved from the or property of the current or specific culture. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. Make sure to use the "tt" specifier for languages for which it's necessary to maintain the distinction between AM and PM. An example is Japanese, for which the AM and PM designators differ in the second character instead of the first character. @@ -525,7 +525,7 @@ The following example includes the "y" custom format specifier in a custom forma The "yy" custom format specifier represents the year as a two-digit number. If the year has more than two digits, only the two low-order digits appear in the result. If the two-digit year has fewer than two significant digits, the number is padded with leading zeros to produce two digits. -In a parsing operation, a two-digit year that is parsed using the "yy" custom format specifier is interpreted based on the property of the format provider's current calendar. The following example parses the string representation of a date that has a two-digit year by using the default Gregorian calendar of the en-US culture, which, in this case, is the current culture. It then changes the current culture's object to use a object whose property has been modified. +In a parsing operation, a two-digit year that is parsed using the "yy" custom format specifier is interpreted based on the property of the format provider's current calendar. The following example parses the string representation of a date that has a two-digit year by using the default Gregorian calendar of the en-US culture, which, in this case, is the current culture. It then changes the current culture's object to use a object whose property has been modified. [!code-csharp[Formatting.DateAndTime.Custom#19](~/samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/parseexact2digityear1.cs#19)] [!code-vb[Formatting.DateAndTime.Custom#19](~/samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/parseexact2digityear1.vb#19)] @@ -649,10 +649,10 @@ The following example includes the "zzz" custom format specifier in a custom for ### The ":" custom format specifier -The ":" custom format specifier represents the time separator, which is used to differentiate hours, minutes, and seconds. The appropriate localized time separator is retrieved from the property of the current or specified culture. +The ":" custom format specifier represents the time separator, which is used to differentiate hours, minutes, and seconds. The appropriate localized time separator is retrieved from the property of the current or specified culture. > [!NOTE] -> To change the time separator for a particular date and time string, specify the separator character within a literal string delimiter. For example, the custom format string `hh'_'dd'_'ss` produces a result string in which "\_" (an underscore) is always used as the time separator. To change the time separator for all dates for a culture, either change the value of the property of the current culture, or instantiate a object, assign the character to its property, and call an overload of the formatting method that includes an parameter. +> To change the time separator for a particular date and time string, specify the separator character within a literal string delimiter. For example, the custom format string `hh'_'dd'_'ss` produces a result string in which "\_" (an underscore) is always used as the time separator. To change the time separator for all dates for a culture, either change the value of the property of the current culture, or instantiate a object, assign the character to its property, and call an overload of the formatting method that includes an parameter. If the ":" format specifier is used without other custom format specifiers, it's interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this article. @@ -660,10 +660,10 @@ If the ":" format specifier is used without other custom format specifiers, it's ### The "/" custom format specifier -The "/" custom format specifier represents the date separator, which is used to differentiate years, months, and days. The appropriate localized date separator is retrieved from the property of the current or specified culture. +The "/" custom format specifier represents the date separator, which is used to differentiate years, months, and days. The appropriate localized date separator is retrieved from the property of the current or specified culture. > [!NOTE] -> To change the date separator for a particular date and time string, specify the separator character within a literal string delimiter. For example, the custom format string `mm'/'dd'/'yyyy` produces a result string in which "/" is always used as the date separator. To change the date separator for all dates for a culture, either change the value of the property of the current culture, or instantiate a object, assign the character to its property, and call an overload of the formatting method that includes an parameter. +> To change the date separator for a particular date and time string, specify the separator character within a literal string delimiter. For example, the custom format string `mm'/'dd'/'yyyy` produces a result string in which "/" is always used as the date separator. To change the date separator for all dates for a culture, either change the value of the property of the current culture, or instantiate a object, assign the character to its property, and call an overload of the formatting method that includes an parameter. If the "/" format specifier is used without other custom format specifiers, it's interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this article. @@ -751,7 +751,7 @@ In addition, if you use the object, which is provided implicitly by the current culture or explicitly by the parameter of the method that invokes formatting. For the parameter, you should specify a object, which represents a culture, or a object. -The result string produced by many of the custom date and time format specifiers also depends on properties of the current object. Your application can change the result produced by some custom date and time format specifiers by changing the corresponding property. For example, the "ddd" format specifier adds an abbreviated weekday name found in the string array to the result string. Similarly, the "MMMM" format specifier adds a full month name found in the string array to the result string. +The result string produced by many of the custom date and time format specifiers also depends on properties of the current object. Your application can change the result produced by some custom date and time format specifiers by changing the corresponding property. For example, the "ddd" format specifier adds an abbreviated weekday name found in the string array to the result string. Similarly, the "MMMM" format specifier adds a full month name found in the string array to the result string. ## See also diff --git a/docs/standard/base-types/custom-numeric-format-strings.md b/docs/standard/base-types/custom-numeric-format-strings.md index b51167c22860a..979e620cc993e 100644 --- a/docs/standard/base-types/custom-numeric-format-strings.md +++ b/docs/standard/base-types/custom-numeric-format-strings.md @@ -20,7 +20,7 @@ helpviewer_keywords: You can create a custom numeric format string, which consists of one or more custom numeric specifiers, to define how to format numeric data. A custom numeric format string is any format string that is not a [standard numeric format string](standard-numeric-format-strings.md). -Custom numeric format strings are supported by some overloads of the `ToString` method of all numeric types. For example, you can supply a numeric format string to the and methods of the type. Custom numeric format strings are also supported by the .NET [composite formatting feature](composite-formatting.md), which is used by some `Write` and `WriteLine` methods of the and classes, the method, and the method. [String interpolation](../../csharp/language-reference/tokens/interpolated.md) feature also supports custom numeric format strings. +Custom numeric format strings are supported by some overloads of the `ToString` method of all numeric types. For example, you can supply a numeric format string to the and methods of the type. Custom numeric format strings are also supported by the .NET [composite formatting feature](composite-formatting.md), which is used by some `Write` and `WriteLine` methods of the and classes, the method, and the method. [String interpolation](../../csharp/language-reference/tokens/interpolated.md) feature also supports custom numeric format strings. > [!TIP] > You can download the **Formatting Utility**, a .NET Core Windows Forms application that lets you apply format strings to either numeric or date and time values and displays the result string. Source code is available for [C#](/samples/dotnet/samples/windowsforms-formatting-utility-cs) and [Visual Basic](/samples/dotnet/samples/windowsforms-formatting-utility-vb). @@ -86,7 +86,7 @@ To return a result string in which absent digits or leading zeroes are replaced The "." custom format specifier inserts a localized decimal separator into the result string. The first period in the format string determines the location of the decimal separator in the formatted value; any additional periods are ignored. If the format specifier ends with a "." only the significant digits are formatted into the result string. -The character that is used as the decimal separator in the result string is not always a period; it is determined by the property of the object that controls formatting. +The character that is used as the decimal separator in the result string is not always a period; it is determined by the property of the object that controls formatting. The following example uses the "." format specifier to define the location of the decimal point in several result strings. @@ -103,7 +103,7 @@ The "," character serves as both a group separator and a number scaling specifie - Group separator: If one or more commas are specified between two digit placeholders (0 or #) that format the integral digits of a number, a group separator character is inserted between each number group in the integral part of the output. - The and properties of the current object determine the character used as the number group separator and the size of each number group. For example, if the string "#,#" and the invariant culture are used to format the number 1000, the output is "1,000". + The and properties of the current object determine the character used as the number group separator and the size of each number group. For example, if the string "#,#" and the invariant culture are used to format the number 1000, the output is "1,000". - Number scaling specifier: If one or more commas are specified immediately to the left of the explicit or implicit decimal point, the number to be formatted is divided by 1000 for each comma. For example, if the string "0,," is used to format the number 100 million, the output is "100". @@ -125,7 +125,7 @@ The following example illustrates the use of the comma as a specifier for number ## The "%" custom specifier -A percent sign (%) in a format string causes a number to be multiplied by 100 before it is formatted. The localized percent symbol is inserted in the number at the location where the % appears in the format string. The percent character used is defined by the property of the current object. +A percent sign (%) in a format string causes a number to be multiplied by 100 before it is formatted. The localized percent symbol is inserted in the number at the location where the % appears in the format string. The percent character used is defined by the property of the current object. The following example defines several custom format strings that include the "%" custom specifier. @@ -138,7 +138,7 @@ The following example defines several custom format strings that include the "%" ## The "‰" custom specifier -A per mille character (‰ or \u2030) in a format string causes a number to be multiplied by 1000 before it is formatted. The appropriate per mille symbol is inserted in the returned string at the location where the ‰ symbol appears in the format string. The per mille character used is defined by the property of the object that provides culture-specific formatting information. +A per mille character (‰ or \u2030) in a format string causes a number to be multiplied by 1000 before it is formatted. The appropriate per mille symbol is inserted in the returned string at the location where the ‰ symbol appears in the format string. The per mille character used is defined by the property of the object that provides culture-specific formatting information. The following example defines a custom format string that includes the "‰" custom specifier. @@ -239,7 +239,7 @@ The following example uses both approaches to include reserved characters in a c ### Floating-Point infinities and NaN -Regardless of the format string, if the value of a , , or floating-point type is positive infinity, negative infinity, or not a number (NaN), the formatted string is the value of the respective , , or property specified by the currently applicable object. +Regardless of the format string, if the value of a , , or floating-point type is positive infinity, negative infinity, or not a number (NaN), the formatted string is the value of the respective , , or property specified by the currently applicable object. ### Control Panel settings diff --git a/docs/standard/base-types/custom-timespan-format-strings.md b/docs/standard/base-types/custom-timespan-format-strings.md index 018670d7e0e06..d5a103b8d5b56 100644 --- a/docs/standard/base-types/custom-timespan-format-strings.md +++ b/docs/standard/base-types/custom-timespan-format-strings.md @@ -25,12 +25,12 @@ A format string defines the string representation of a > Custom format specifiers also don't include a sign symbol that enables you to differentiate between negative and positive time intervals. To include a sign symbol, you have to construct a format string by using conditional logic. The [Other characters](#other-characters) section includes an example. -The string representations of values are produced by calls to the overloads of the method, and by methods that support composite formatting, such as . For more information, see [Formatting Types](formatting-types.md) and [Composite Formatting](composite-formatting.md). The following example illustrates the use of custom format strings in formatting operations. +The string representations of values are produced by calls to the overloads of the method, and by methods that support composite formatting, such as . For more information, see [Formatting Types](formatting-types.md) and [Composite Formatting](composite-formatting.md). The following example illustrates the use of custom format strings in formatting operations. [!code-csharp[Conceptual.TimeSpan.Custom#1](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customformatexample1.cs#1)] [!code-vb[Conceptual.TimeSpan.Custom#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customformatexample1.vb#1)] -Custom format strings are also used by the and methods to define the required format of input strings for parsing operations. (Parsing converts the string representation of a value to that value.) The following example illustrates the use of standard format strings in parsing operations. +Custom format strings are also used by the and methods to define the required format of input strings for parsing operations. (Parsing converts the string representation of a value to that value.) The following example illustrates the use of standard format strings in parsing operations. [!code-csharp[Conceptual.TimeSpan.Custom#2](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customparseexample1.cs#2)] [!code-vb[Conceptual.TimeSpan.Custom#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customparseexample1.vb#2)] @@ -67,7 +67,7 @@ Custom format strings are also used by the The `"d"` custom format specifier -The `"d"` custom format specifier outputs the value of the property, which represents the number of whole days in the time interval. It outputs the full number of days in a value, even if the value has more than one digit. If the value of the property is zero, the specifier outputs "0". +The `"d"` custom format specifier outputs the value of the property, which represents the number of whole days in the time interval. It outputs the full number of days in a value, even if the value has more than one digit. If the value of the property is zero, the specifier outputs "0". If the `"d"` custom format specifier is used alone, specify `"%d"` so that it isn't misinterpreted as a standard format string. The following example provides an illustration. @@ -83,7 +83,7 @@ The following example illustrates the use of the `"d"` custom format specifier. ## The `"dd"`-`"dddddddd"` custom format specifiers -The `"dd"`, `"ddd"`, `"dddd"`, `"ddddd"`, `"dddddd"`, `"ddddddd"`, and `"dddddddd"` custom format specifiers output the value of the property, which represents the number of whole days in the time interval. +The `"dd"`, `"ddd"`, `"dddd"`, `"ddddd"`, `"dddddd"`, `"ddddddd"`, and `"dddddddd"` custom format specifiers output the value of the property, which represents the number of whole days in the time interval. The output string includes a minimum number of digits specified by the number of `d` characters in the format specifier, and it's padded with leading zeros as needed. If the digits in the number of days exceed the number of `d` characters in the format specifier, the full number of days is output in the result string. @@ -96,7 +96,7 @@ The following example uses these format specifiers to display the string represe ## The `"h"` custom format specifier -The `"h"` custom format specifier outputs the value of the property, which represents the number of whole hours in the time interval that isn't counted as part of its day component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 23. +The `"h"` custom format specifier outputs the value of the property, which represents the number of whole hours in the time interval that isn't counted as part of its day component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 23. If the `"h"` custom format specifier is used alone, specify `"%h"` so that it isn't misinterpreted as a standard format string. The following example provides an illustration. @@ -117,7 +117,7 @@ The following example illustrates the use of the `"h"` custom format specifier. ## The `"hh"` custom format specifier -The `"hh"` custom format specifier outputs the value of the property, which represents the number of whole hours in the time interval that isn't counted as part of its day component. For values from 0 through 9, the output string includes a leading zero. +The `"hh"` custom format specifier outputs the value of the property, which represents the number of whole hours in the time interval that isn't counted as part of its day component. For values from 0 through 9, the output string includes a leading zero. Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the `"hh"` custom format specifier instead to interpret the numeric string as the number of hours. The following example provides an illustration. @@ -133,7 +133,7 @@ The following example illustrates the use of the `"hh"` custom format specifier. ## The `"m"` custom format specifier -The `"m"` custom format specifier outputs the value of the property, which represents the number of whole minutes in the time interval that isn't counted as part of its day component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 59. +The `"m"` custom format specifier outputs the value of the property, which represents the number of whole minutes in the time interval that isn't counted as part of its day component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 59. If the `"m"` custom format specifier is used alone, specify `"%m"` so that it isn't misinterpreted as a standard format string. The following example provides an illustration. @@ -154,7 +154,7 @@ The following example illustrates the use of the `"m"` custom format specifier. ## The `"mm"` custom format specifier -The `"mm"` custom format specifier outputs the value of the property, which represents the number of whole minutes in the time interval that isn't included as part of its hours or days component. For values from 0 through 9, the output string includes a leading zero. +The `"mm"` custom format specifier outputs the value of the property, which represents the number of whole minutes in the time interval that isn't included as part of its hours or days component. For values from 0 through 9, the output string includes a leading zero. Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the `"mm"` custom format specifier instead to interpret the numeric string as the number of minutes. The following example provides an illustration. @@ -170,7 +170,7 @@ The following example illustrates the use of the `"mm"` custom format specifier. ## The `"s"` custom format specifier -The `"s"` custom format specifier outputs the value of the property, which represents the number of whole seconds in the time interval that isn't included as part of its hours, days, or minutes component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 59. +The `"s"` custom format specifier outputs the value of the property, which represents the number of whole seconds in the time interval that isn't included as part of its hours, days, or minutes component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 59. If the `"s"` custom format specifier is used alone, specify `"%s"` so that it isn't misinterpreted as a standard format string. The following example provides an illustration. @@ -191,7 +191,7 @@ The following example illustrates the use of the `"s"` custom format specifier. ## The `"ss"` custom format specifier -The `"ss"` custom format specifier outputs the value of the property, which represents the number of whole seconds in the time interval that isn't included as part of its hours, days, or minutes component. For values from 0 through 9, the output string includes a leading zero. +The `"ss"` custom format specifier outputs the value of the property, which represents the number of whole seconds in the time interval that isn't included as part of its hours, days, or minutes component. For values from 0 through 9, the output string includes a leading zero. Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the `"ss"` custom format specifier instead to interpret the numeric string as the number of seconds. The following example provides an illustration. @@ -207,7 +207,7 @@ The following example illustrates the use of the `"ss"` custom format specifier. ## The `"f"` custom format specifier -The `"f"` custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly one fractional digit. +The `"f"` custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly one fractional digit. If the `"f"` custom format specifier is used alone, specify `"%f"` so that it isn't misinterpreted as a standard format string. @@ -220,7 +220,7 @@ The following example uses the `"f"` custom format specifier to display the tent ## The `"ff"` custom format specifier -The `"ff"` custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly two fractional digits. +The `"ff"` custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly two fractional digits. The following example uses the `"ff"` custom format specifier to display the hundredths of a second in a value. `"ff"` is used first as the only format specifier, and then combined with the `"s"` specifier in a custom format string. @@ -231,7 +231,7 @@ The following example uses the `"ff"` custom format specifier to display the hun ## The `"fff"` custom format specifier -The `"fff"` custom format specifier (with three `f` characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly three fractional digits. +The `"fff"` custom format specifier (with three `f` characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly three fractional digits. The following example uses the `"fff"` custom format specifier to display the milliseconds in a value. `"fff"` is used first as the only format specifier, and then combined with the `"s"` specifier in a custom format string. @@ -242,7 +242,7 @@ The following example uses the `"fff"` custom format specifier to display the mi ## The `"ffff"` custom format specifier -The `"ffff"` custom format specifier (with four `f` characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly four fractional digits. +The `"ffff"` custom format specifier (with four `f` characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly four fractional digits. The following example uses the `"ffff"` custom format specifier to display the ten-thousandths of a second in a value. `"ffff"` is used first as the only format specifier, and then combined with the `"s"` specifier in a custom format string. @@ -253,7 +253,7 @@ The following example uses the `"ffff"` custom format specifier to display the t ## The `"fffff"` custom format specifier -The `"fffff"` custom format specifier (with five `f` characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly five fractional digits. +The `"fffff"` custom format specifier (with five `f` characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly five fractional digits. The following example uses the `"fffff"` custom format specifier to display the hundred-thousandths of a second in a value. `"fffff"` is used first as the only format specifier, and then combined with the `"s"` specifier in a custom format string. @@ -264,7 +264,7 @@ The following example uses the `"fffff"` custom format specifier to display the ## The `"ffffff"` custom format specifier -The `"ffffff"` custom format specifier (with six `f` characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly six fractional digits. +The `"ffffff"` custom format specifier (with six `f` characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly six fractional digits. The following example uses the `"ffffff"` custom format specifier to display the millionths of a second in a value. It is used first as the only format specifier, and then combined with the `"s"` specifier in a custom format string. @@ -275,7 +275,7 @@ The following example uses the `"ffffff"` custom format specifier to display the ## The `"fffffff"` custom format specifier -The `"fffffff"` custom format specifier (with seven `f` characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. In a parsing operation that calls the or method, the input string must contain exactly seven fractional digits. +The `"fffffff"` custom format specifier (with seven `f` characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. In a parsing operation that calls the or method, the input string must contain exactly seven fractional digits. The following example uses the `"fffffff"` custom format specifier to display the fractional number of ticks in a value. It is used first as the only format specifier, and then combined with the `"s"` specifier in a custom format string. @@ -286,7 +286,7 @@ The following example uses the `"fffffff"` custom format specifier to display th ## The `"F"` custom format specifier -The `"F"` custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If the value of the time interval's tenths of a second is zero, it isn't included in the result string. In a parsing operation that calls the or method, the presence of the tenths of a second digit is optional. +The `"F"` custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If the value of the time interval's tenths of a second is zero, it isn't included in the result string. In a parsing operation that calls the or method, the presence of the tenths of a second digit is optional. If the `"F"` custom format specifier is used alone, specify `"%F"` so that it isn't misinterpreted as a standard format string. @@ -299,7 +299,7 @@ The following example uses the `"F"` custom format specifier to display the tent ## The `"FF"` custom format specifier -The `"FF"` custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they aren't included in the result string. In a parsing operation that calls the or method, the presence of the tenths and hundredths of a second digit is optional. +The `"FF"` custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they aren't included in the result string. In a parsing operation that calls the or method, the presence of the tenths and hundredths of a second digit is optional. The following example uses the `"FF"` custom format specifier to display the hundredths of a second in a value. It also uses this custom format specifier in a parsing operation. @@ -310,7 +310,7 @@ The following example uses the `"FF"` custom format specifier to display the hun ## The `"FFF"` custom format specifier -The `"FFF"` custom format specifier (with three `F` characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they aren't included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, and thousandths of a second digit is optional. +The `"FFF"` custom format specifier (with three `F` characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they aren't included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, and thousandths of a second digit is optional. The following example uses the `"FFF"` custom format specifier to display the thousandths of a second in a value. It also uses this custom format specifier in a parsing operation. @@ -321,7 +321,7 @@ The following example uses the `"FFF"` custom format specifier to display the th ## The `"FFFF"` custom format specifier -The `"FFFF"` custom format specifier (with four `F` characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they aren't included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, and ten-thousandths of a second digit is optional. +The `"FFFF"` custom format specifier (with four `F` characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they aren't included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, and ten-thousandths of a second digit is optional. The following example uses the `"FFFF"` custom format specifier to display the ten-thousandths of a second in a value. It also uses the `"FFFF"` custom format specifier in a parsing operation. @@ -332,7 +332,7 @@ The following example uses the `"FFFF"` custom format specifier to display the t ## The `"FFFFF"` custom format specifier -The `"FFFFF"` custom format specifier (with five `F` characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they aren't included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, ten-thousandths, and hundred-thousandths of a second digit is optional. +The `"FFFFF"` custom format specifier (with five `F` characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they aren't included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, ten-thousandths, and hundred-thousandths of a second digit is optional. The following example uses the `"FFFFF"` custom format specifier to display the hundred-thousandths of a second in a value. It also uses the `"FFFFF"` custom format specifier in a parsing operation. @@ -343,7 +343,7 @@ The following example uses the `"FFFFF"` custom format specifier to display the ## The `"FFFFFF"` custom format specifier -The `"FFFFFF"` custom format specifier (with six `F` characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they aren't included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, ten-thousandths, hundred-thousandths, and millionths of a second digit is optional. +The `"FFFFFF"` custom format specifier (with six `F` characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they aren't included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, ten-thousandths, hundred-thousandths, and millionths of a second digit is optional. The following example uses the `"FFFFFF"` custom format specifier to display the millionths of a second in a value. It also uses this custom format specifier in a parsing operation. @@ -354,7 +354,7 @@ The following example uses the `"FFFFFF"` custom format specifier to display the ## The `"FFFFFFF"` custom format specifier -The `"FFFFFFF"` custom format specifier (with seven `F` characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. If there are any trailing fractional zeros, they aren't included in the result string. In a parsing operation that calls the or method, the presence of the seven fractional digits in the input string is optional. +The `"FFFFFFF"` custom format specifier (with seven `F` characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. If there are any trailing fractional zeros, they aren't included in the result string. In a parsing operation that calls the or method, the presence of the seven fractional digits in the input string is optional. The following example uses the `"FFFFFFF"` custom format specifier to display the fractional parts of a second in a value. It also uses this custom format specifier in a parsing operation. diff --git a/docs/standard/base-types/details-of-regular-expression-behavior.md b/docs/standard/base-types/details-of-regular-expression-behavior.md index 236a10ff70c7a..5f7198fb38da0 100644 --- a/docs/standard/base-types/details-of-regular-expression-behavior.md +++ b/docs/standard/base-types/details-of-regular-expression-behavior.md @@ -60,7 +60,7 @@ The .NET regular expression engine is a backtracking regular expression matcher |Pattern|Description| |-------------|-----------------| |`\b`|Begin the match at a word boundary.| - |`[A-Z]+`|Match any alphabetic character one or more times. Because the method is called with the option, the comparison is case-insensitive.| + |`[A-Z]+`|Match any alphabetic character one or more times. Because the method is called with the option, the comparison is case-insensitive.| |`\b`|End the match at a word boundary.| |`(?=\P{P})`|Look ahead to determine whether the next character is a punctuation symbol. If it is not, the match succeeds.| diff --git a/docs/standard/base-types/divide-up-strings.md b/docs/standard/base-types/divide-up-strings.md index 6a4208f4369ba..295edaede453e 100644 --- a/docs/standard/base-types/divide-up-strings.md +++ b/docs/standard/base-types/divide-up-strings.md @@ -20,7 +20,7 @@ This article covers some different techniques for extracting parts of a string. ## String.Split method - provides a handful of overloads to help you break up a string into a group of substrings based on one or more delimiting characters that you specify. You can choose to limit the total number of substrings in the final result, trim white-space characters from substrings, or exclude empty substrings. + provides a handful of overloads to help you break up a string into a group of substrings based on one or more delimiting characters that you specify. You can choose to limit the total number of substrings in the final result, trim white-space characters from substrings, or exclude empty substrings. The following examples show three different overloads of `String.Split()`. The first example calls the overload without passing any separator characters. When you don't specify any delimiting characters, `String.Split()` uses default delimiters, which are white-space characters, to split up the string. @@ -62,7 +62,7 @@ You can also use a regular expression to extract substrings from a string based - The sequence and number of delimiter characters is variable or unknown. -For example, the method cannot be used to split the following string, because the number of `\n` (newline) characters is variable, and they don't always serve as delimiters. +For example, the method cannot be used to split the following string, because the number of `\n` (newline) characters is variable, and they don't always serve as delimiters. ```text [This is captured\ntext.]\n\n[\n[This is more captured text.]\n] @@ -82,7 +82,7 @@ The regular expression pattern `\[([^\[\]]+)\]` is defined like this: |`([^\[\]]+)`|Match any character that is not an opening or a closing bracket one or more times. This is the first capturing group.| |`\]`|Match a closing bracket.| -The method is almost identical to , except that it splits a string based on a regular expression pattern instead of a fixed character set. For example, the following example uses the method to split a string that contains substrings delimited by various combinations of hyphens and other characters. +The method is almost identical to , except that it splits a string based on a regular expression pattern instead of a fixed character set. For example, the following example uses the method to split a string that contains substrings delimited by various combinations of hyphens and other characters. :::code language="csharp" source="snippets/parse-strings/csharp/regex.cs" id="3"::: :::code language="vb" source="snippets/parse-strings/vb/regex.vb" id="3"::: @@ -99,17 +99,17 @@ The regular expression pattern `\s-\s?[+*]?\s?-\s` is defined like this: ## String.IndexOf and String.Substring methods -If you aren't interested in all of the substrings in a string, you might prefer to work with one of the string comparison methods that returns the index at which the match begins. You can then call the method to extract the substring that you want. The string comparison methods include: +If you aren't interested in all of the substrings in a string, you might prefer to work with one of the string comparison methods that returns the index at which the match begins. You can then call the method to extract the substring that you want. The string comparison methods include: -- , which returns the zero-based index of the first occurrence of a character or string in a string instance. +- , which returns the zero-based index of the first occurrence of a character or string in a string instance. -- , which returns the zero-based index in the current string instance of the first occurrence of any character in a character array. +- , which returns the zero-based index in the current string instance of the first occurrence of any character in a character array. -- , which returns the zero-based index of the last occurrence of a character or string in a string instance. +- , which returns the zero-based index of the last occurrence of a character or string in a string instance. -- , which returns a zero-based index in the current string instance of the last occurrence of any character in a character array. +- , which returns a zero-based index in the current string instance of the last occurrence of any character in a character array. -The following example uses the method to find the periods in a string. It then uses the method to return full sentences. +The following example uses the method to find the periods in a string. It then uses the method to return full sentences. :::code language="csharp" source="snippets/parse-strings/csharp/indexof.cs" id="1"::: :::code language="vb" source="snippets/parse-strings/vb/indexof.vb" id="1"::: diff --git a/docs/standard/base-types/enumeration-format-strings.md b/docs/standard/base-types/enumeration-format-strings.md index ab61b5a92c6d4..5e91e64253505 100644 --- a/docs/standard/base-types/enumeration-format-strings.md +++ b/docs/standard/base-types/enumeration-format-strings.md @@ -2,10 +2,10 @@ title: "Enumeration format strings" description: Create enumeration format strings using the Enum.ToString method in .NET. Format numeric, hexadecimal, or string values of enumeration members. ms.date: 06/19/2023 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "format specifiers, enumeration format strings" - "enumeration format strings" - "formatting [.NET], enumeration" @@ -14,7 +14,7 @@ ms.assetid: dd1ff672-1052-42cf-8666-4924fb6cd1a1 # Enumeration format strings -You can use the method to create a new string object that represents the numeric, hexadecimal, or string value of an enumeration member. This method takes one of the enumeration formatting strings to specify the value that you want returned. +You can use the method to create a new string object that represents the numeric, hexadecimal, or string value of an enumeration member. This method takes one of the enumeration formatting strings to specify the value that you want returned. The following sections list the enumeration formatting strings and the values they return. These format specifiers aren't case-sensitive. diff --git a/docs/standard/base-types/formatting-types.md b/docs/standard/base-types/formatting-types.md index 6cd13b8a0b688..eabcd5ee381a6 100644 --- a/docs/standard/base-types/formatting-types.md +++ b/docs/standard/base-types/formatting-types.md @@ -33,9 +33,9 @@ Formatting is the process of converting an instance of a class or structure, or > [!NOTE] > Parsing is the inverse of formatting. A parsing operation creates an instance of a data type from its string representation. For more information, see [Parsing Strings](parsing-strings.md). For information about serialization and deserialization, see [Serialization in .NET](../serialization/index.md). -The basic mechanism for formatting is the default implementation of the method, which is discussed in the [Default Formatting Using the ToString Method](#default-formatting-using-the-tostring-method) section later in this article. However, .NET provides several ways to modify and extend its default formatting support. These include the following: +The basic mechanism for formatting is the default implementation of the method, which is discussed in the [Default Formatting Using the ToString Method](#default-formatting-using-the-tostring-method) section later in this article. However, .NET provides several ways to modify and extend its default formatting support. These include the following: -- Overriding the method to define a custom string representation of an object's value. For more information, see the [Override the ToString Method](#override-the-tostring-method) section later in this article. +- Overriding the method to define a custom string representation of an object's value. For more information, see the [Override the ToString Method](#override-the-tostring-method) section later in this article. - Defining format specifiers that enable the string representation of an object's value to take multiple forms. For example, the "X" format specifier in the following statement converts an integer to the string representation of a hexadecimal value. @@ -74,7 +74,7 @@ Every type that is derived from , this functionality is automatically provided to your custom classes or structures. However, the functionality offered by the default `ToString` method, is limited: Although it identifies the type, it fails to provide any information about an instance of the type. To provide a string representation of an object that provides information about that object, you must override the `ToString` method. > [!NOTE] -> Structures inherit from , which in turn is derived from . Although overrides , its implementation is identical. +> Structures inherit from , which in turn is derived from . Although overrides , its implementation is identical. ## Override the ToString method @@ -125,9 +125,9 @@ For information about enumeration format strings, see [Enumeration Format String Standard format strings for numeric types usually define a result string whose precise appearance is controlled by one or more property values. For example, the "C" format specifier formats a number as a currency value. When you call the `ToString` method with the "C" format specifier as the only parameter, the following property values from the current culture's object are used to define the string representation of the numeric value: -- The property, which specifies the current culture's currency symbol. +- The property, which specifies the current culture's currency symbol. -- The or property, which returns an integer that determines the following: +- The or property, which returns an integer that determines the following: - The placement of the currency symbol. @@ -135,15 +135,15 @@ Standard format strings for numeric types usually define a result string whose p - Whether a space appears between the numeric value and the currency symbol. -- The property, which defines the number of fractional digits in the result string. +- The property, which defines the number of fractional digits in the result string. -- The property, which defines the decimal separator symbol in the result string. +- The property, which defines the decimal separator symbol in the result string. -- The property, which defines the group separator symbol. +- The property, which defines the group separator symbol. -- The property, which defines the number of digits in each group to the left of the decimal. +- The property, which defines the number of digits in each group to the left of the decimal. -- The property, which determines the negative sign used in the result string if parentheses aren't used to indicate negative values. +- The property, which determines the negative sign used in the result string if parentheses aren't used to indicate negative values. In addition, numeric format strings can include a precision specifier. The meaning of this specifier depends on the format string with which it's used, but it typically indicates either the total number of digits or the number of fractional digits that should appear in the result string. For example, the following example uses the "X4" standard numeric string and a precision specifier to create a string value that has four hexadecimal digits. @@ -152,7 +152,7 @@ In addition, numeric format strings can include a precision specifier. The meani For more information about standard numeric formatting strings, see [Standard Numeric Format Strings](standard-numeric-format-strings.md). -Standard format strings for date and time values are aliases for custom format strings stored by a particular property. For example, calling the `ToString` method of a date and time value with the "D" format specifier displays the date and time by using the custom format string stored in the current culture's property. (For more information about custom format strings, see the [next section](#custom-format-strings).) The following example illustrates this relationship. +Standard format strings for date and time values are aliases for custom format strings stored by a particular property. For example, calling the `ToString` method of a date and time value with the "D" format specifier displays the date and time by using the custom format string stored in the current culture's property. (For more information about custom format strings, see the [next section](#custom-format-strings).) The following example illustrates this relationship. [!code-csharp[Conceptual.Formatting.Overview#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/alias1.cs#5)] [!code-vb[Conceptual.Formatting.Overview#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/alias1.vb#5)] @@ -215,29 +215,29 @@ Although format specifiers let you customize the formatting of objects, producin The interface includes one method, , which has a single parameter that specifies the type of object that provides formatting information. If the method can provide an object of that type, it returns it. Otherwise, it returns a null reference (`Nothing` in Visual Basic). - is a callback method. When you call a `ToString` method overload that includes an parameter, it calls the method of that object. The method is responsible for returning an object that provides the necessary formatting information, as specified by its `formatType` parameter, to the `ToString` method. + is a callback method. When you call a `ToString` method overload that includes an parameter, it calls the method of that object. The method is responsible for returning an object that provides the necessary formatting information, as specified by its `formatType` parameter, to the `ToString` method. -Several formatting or string conversion methods include a parameter of type , but in many cases the value of the parameter is ignored when the method is called. The following table lists some of the formatting methods that use the parameter and the type of the object that they pass to the method. +Several formatting or string conversion methods include a parameter of type , but in many cases the value of the parameter is ignored when the method is called. The following table lists some of the formatting methods that use the parameter and the type of the object that they pass to the method. |Method|Type of `formatType` parameter| |------------|------------------------------------| |`ToString` method of numeric types|| |`ToString` method of date and time types|| -||| -||| +||| +||| > [!NOTE] -> The `ToString` methods of the numeric types and date and time types are overloaded, and only some of the overloads include an parameter. If a method doesn't have a parameter of type , the object that is returned by the property is passed instead. For example, a call to the default method ultimately results in a method call such as the following: `Int32.ToString("G", System.Globalization.CultureInfo.CurrentCulture)`. +> The `ToString` methods of the numeric types and date and time types are overloaded, and only some of the overloads include an parameter. If a method doesn't have a parameter of type , the object that is returned by the property is passed instead. For example, a call to the default method ultimately results in a method call such as the following: `Int32.ToString("G", System.Globalization.CultureInfo.CurrentCulture)`. .NET provides three classes that implement : -- , a class that provides formatting information for date and time values for a specific culture. Its implementation returns an instance of itself. +- , a class that provides formatting information for date and time values for a specific culture. Its implementation returns an instance of itself. -- , a class that provides numeric formatting information for a specific culture. Its implementation returns an instance of itself. +- , a class that provides numeric formatting information for a specific culture. Its implementation returns an instance of itself. -- . Its implementation can return either a object to provide numeric formatting information or a object to provide formatting information for date and time values. +- . Its implementation can return either a object to provide numeric formatting information or a object to provide formatting information for date and time values. -You can also implement your own format provider to replace any one of these classes. However, your implementation's method must return an object of the type listed in the previous table if it has to provide formatting information to the `ToString` method. +You can also implement your own format provider to replace any one of these classes. However, your implementation's method must return an object of the type listed in the previous table if it has to provide formatting information to the `ToString` method. ### Culture-sensitive formatting of numeric values @@ -248,9 +248,9 @@ By default, the formatting of numeric values is culture-sensitive. If you don't You can also format a numeric value for a specific culture by calling a `ToString` overload that has a `provider` parameter and passing it either of the following: -- A object that represents the culture whose formatting conventions are to be used. Its method returns the value of the property, which is the object that provides culture-specific formatting information for numeric values. +- A object that represents the culture whose formatting conventions are to be used. Its method returns the value of the property, which is the object that provides culture-specific formatting information for numeric values. -- A object that defines the culture-specific formatting conventions to be used. Its method returns an instance of itself. +- A object that defines the culture-specific formatting conventions to be used. Its method returns an instance of itself. The following example uses objects that represent the English (United States) and English (United Kingdom) cultures and the French and Russian neutral cultures to format a floating-point number. @@ -264,11 +264,11 @@ By default, the formatting of date and time values is culture-sensitive. If you [!code-csharp[Conceptual.Formatting.Overview#17](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/culturespecific1.cs#17)] [!code-vb[Conceptual.Formatting.Overview#17](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/culturespecific1.vb#17)] -You can also format a date and time value for a specific culture by calling a or overload that has a `provider` parameter and passing it either of the following: +You can also format a date and time value for a specific culture by calling a or overload that has a `provider` parameter and passing it either of the following: -- A object that represents the culture whose formatting conventions are to be used. Its method returns the value of the property, which is the object that provides culture-specific formatting information for date and time values. +- A object that represents the culture whose formatting conventions are to be used. Its method returns the value of the property, which is the object that provides culture-specific formatting information for date and time values. -- A object that defines the culture-specific formatting conventions to be used. Its method returns an instance of itself. +- A object that defines the culture-specific formatting conventions to be used. Its method returns an instance of itself. The following example uses objects that represent the English (United States) and English (United Kingdom) cultures and the French and Russian neutral cultures to format a date. @@ -283,21 +283,21 @@ Implementing the interface for your application-defin - Support for string conversion by the class. Calls to the and methods call your implementation automatically. -- Support for composite formatting. If a format item that includes a format string is used to format your custom type, the common language runtime automatically calls your implementation and passes it the format string. For more information about composite formatting with methods such as or , see the [Composite Formatting](#composite-formatting) section. +- Support for composite formatting. If a format item that includes a format string is used to format your custom type, the common language runtime automatically calls your implementation and passes it the format string. For more information about composite formatting with methods such as or , see the [Composite Formatting](#composite-formatting) section. The following example defines a `Temperature` class that implements the interface. It supports the "C" or "G" format specifiers to display the temperature in Celsius, the "F" format specifier to display the temperature in Fahrenheit, and the "K" format specifier to display the temperature in Kelvin. [!code-csharp[Conceptual.Formatting.Overview#12](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/iformattable.cs#12)] [!code-vb[Conceptual.Formatting.Overview#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/iformattable.vb#12)] -The following example instantiates a `Temperature` object. It then calls the method and uses several composite format strings to obtain different string representations of a `Temperature` object. Each of these method calls, in turn, calls the implementation of the `Temperature` class. +The following example instantiates a `Temperature` object. It then calls the method and uses several composite format strings to obtain different string representations of a `Temperature` object. Each of these method calls, in turn, calls the implementation of the `Temperature` class. [!code-csharp[Conceptual.Formatting.Overview#13](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/iformattable.cs#13)] [!code-vb[Conceptual.Formatting.Overview#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/iformattable.vb#13)] ## Composite formatting -Some methods, such as and , support *composite formatting*. A composite format string is a kind of template that returns a single string that incorporates the string representation of zero, one, or more objects. Each object is represented in the composite format string by an indexed format item. The index of the format item corresponds to the position of the object that it represents in the method's parameter list. Indexes are zero-based. For example, in the following call to the method, the first format item, `{0:D}`, is replaced by the string representation of `thatDate`; the second format item, `{1}`, is replaced by the string representation of `item1`; and the third format item, `{2:C2}`, is replaced by the string representation of `item1.Value`. +Some methods, such as and , support *composite formatting*. A composite format string is a kind of template that returns a single string that incorporates the string representation of zero, one, or more objects. Each object is represented in the composite format string by an indexed format item. The index of the format item corresponds to the position of the object that it represents in the method's parameter list. Indexes are zero-based. For example, in the following call to the method, the first format item, `{0:D}`, is replaced by the string representation of `thatDate`; the second format item, `{1}`, is replaced by the string representation of `item1`; and the third format item, `{2:C2}`, is replaced by the string representation of `item1.Value`. [!code-csharp[Conceptual.Formatting.Overview#14](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/composite1.cs#14)] [!code-vb[Conceptual.Formatting.Overview#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/composite1.vb#14)] @@ -317,7 +317,7 @@ For more information about composite formatting, see [Composite Formatting](comp ## Custom formatting with ICustomFormatter -Two composite formatting methods, and , include a format provider parameter that supports custom formatting. When either of these formatting methods is called, it passes a object that represents an interface to the format provider's method. The method is then responsible for returning the implementation that provides custom formatting. +Two composite formatting methods, and , include a format provider parameter that supports custom formatting. When either of these formatting methods is called, it passes a object that represents an interface to the format provider's method. The method is then responsible for returning the implementation that provides custom formatting. The interface has a single method, , that is called automatically by a composite formatting method, once for each format item in a composite format string. The method has three parameters: a format string, which represents the `formatString` argument in a format item, an object to format, and an object that provides formatting services. Typically, the class that implements also implements , so this last parameter is a reference to the custom formatting class itself. The method returns a custom formatted string representation of the object to be formatted. If the method can't format the object, it should return a null reference (`Nothing` in Visual Basic). @@ -326,7 +326,7 @@ The following example provides an implementation [!code-csharp[Conceptual.Formatting.Overview#15](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/icustomformatter1.cs#15)] [!code-vb[Conceptual.Formatting.Overview#15](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/icustomformatter1.vb#15)] -The following example uses the `ByteByByteFormatter` class to format integer values. The method is called more than once in the second method call, and that the default provider is used in the third method call because the .`ByteByByteFormatter.Format` method doesn't recognize the "N0" format string and returns a null reference (`Nothing` in Visual Basic). +The following example uses the `ByteByByteFormatter` class to format integer values. The method is called more than once in the second method call, and that the default provider is used in the third method call because the .`ByteByByteFormatter.Format` method doesn't recognize the "N0" format string and returns a null reference (`Nothing` in Visual Basic). [!code-csharp[Conceptual.Formatting.Overview#16](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/icustomformatter1.cs#16)] [!code-vb[Conceptual.Formatting.Overview#16](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/icustomformatter1.vb#16)] diff --git a/docs/standard/base-types/grouping-constructs-in-regular-expressions.md b/docs/standard/base-types/grouping-constructs-in-regular-expressions.md index 87a355d85e233..8ae475caf6781 100644 --- a/docs/standard/base-types/grouping-constructs-in-regular-expressions.md +++ b/docs/standard/base-types/grouping-constructs-in-regular-expressions.md @@ -20,7 +20,7 @@ Grouping constructs delineate the subexpressions of a regular expression and cap - Match a subexpression that's repeated in the input string. - Apply a quantifier to a subexpression that has multiple regular expression language elements. For more information about quantifiers, see [Quantifiers](quantifiers-in-regular-expressions.md). -- Include a subexpression in the string that's returned by the and methods. +- Include a subexpression in the string that's returned by the and methods. - Retrieve individual subexpressions from the property and process them separately from the matched text as a whole. The following table lists the grouping constructs supported by the .NET regular expression engine and indicates whether they are capturing or noncapturing. @@ -57,9 +57,9 @@ You can access captured groups in four ways: - By using the named backreference construct within the regular expression. The matched subexpression is referenced in the same regular expression by using the syntax `\k<`*name*`>`, where *name* is the name of a capturing group, or `\k<`*number*`>`, where *number* is the ordinal number of a capturing group. A capturing group has a default name that is identical to its ordinal number. For more information, see [Named matched subexpressions](#named-matched-subexpressions) later in this topic. -- By using the `$`*number* replacement sequence in a or method call, where *number* is the ordinal number of the captured subexpression. +- By using the `$`*number* replacement sequence in a or method call, where *number* is the ordinal number of the captured subexpression. -- Programmatically, by using the object returned by the property. The member at position zero in the collection represents the entire regular expression match. Each subsequent member represents a matched subexpression. For more information, see the [Grouping Constructs and Regular Expression Objects](#grouping-constructs-and-regular-expression-objects) section. +- Programmatically, by using the object returned by the property. The member at position zero in the collection represents the entire regular expression match. Each subsequent member represents a matched subexpression. For more information, see the [Grouping Constructs and Regular Expression Objects](#grouping-constructs-and-regular-expression-objects) section. The following example illustrates a regular expression that identifies duplicated words in text. The regular expression pattern's two capturing groups represent the two instances of the duplicated word. The second instance is captured to report its starting position in the input string. @@ -100,13 +100,13 @@ You can access named captured groups in the following ways: - By using the backreference construct within the regular expression. The matched subexpression is referenced in the same regular expression by using the syntax `\`*number*, where *number* is the ordinal number of the captured subexpression. Named matched subexpressions are numbered consecutively from left to right after matched subexpressions. -- By using the `${`*name*`}` replacement sequence in a or method call, where *name* is the name of the captured subexpression. +- By using the `${`*name*`}` replacement sequence in a or method call, where *name* is the name of the captured subexpression. -- By using the `$`*number* replacement sequence in a or method call, where *number* is the ordinal number of the captured subexpression. +- By using the `$`*number* replacement sequence in a or method call, where *number* is the ordinal number of the captured subexpression. -- Programmatically, by using the object returned by the property. The member at position zero in the collection represents the entire regular expression match. Each subsequent member represents a matched subexpression. Named captured groups are stored in the collection after numbered captured groups. +- Programmatically, by using the object returned by the property. The member at position zero in the collection represents the entire regular expression match. Each subsequent member represents a matched subexpression. Named captured groups are stored in the collection after numbered captured groups. -- Programmatically, by providing the subexpression name to the object's indexer (in C#) or to its property (in Visual Basic). +- Programmatically, by providing the subexpression name to the object's indexer (in C#) or to its property (in Visual Basic). A simple regular expression pattern illustrates how numbered (unnamed) and named groups can be referenced either programmatically or by using regular expression language syntax. The regular expression `((?abc)\d+)?(?xyz)(.*)` produces the following capturing groups by number and by name. The first capturing group (number 0) always refers to the entire pattern. (Named groups are always ordered last.) @@ -165,7 +165,7 @@ or: Here, *name1* is the current group (optional), *name2* is a previously defined group, and *subexpression* is any valid regular expression pattern. The balancing group definition deletes the definition of *name2* and stores the interval between *name2* and *name1* in *name1*. If no *name2* group is defined, the match backtracks. Because deleting the last definition of *name2* reveals the previous definition of *name2*, this construct lets you use the stack of captures for group *name2* as a counter for keeping track of nested constructs such as parentheses or opening and closing brackets. -The balancing group definition uses *name2* as a stack. The beginning character of each nested construct is placed in the group and in its collection. When the closing character is matched, its corresponding opening character is removed from the group, and the collection is decreased by one. After the opening and closing characters of all nested constructs have been matched, *name2* is empty. +The balancing group definition uses *name2* as a stack. The beginning character of each nested construct is placed in the group and in its collection. When the closing character is matched, its corresponding opening character is removed from the group, and the collection is decreased by one. After the opening and closing characters of all nested constructs have been matched, *name2* is empty. > [!NOTE] > After you modify the regular expression in the following example to use the appropriate opening and closing character of a nested construct, you can use it to handle most nested constructs, such as mathematical expressions or lines of program code that include multiple nested method calls. @@ -210,13 +210,13 @@ In the example, the regular expression engine evaluates the input string "\ |7|`[^<>]*`|Looks for non-angle bracket characters after the right angle bracket; finds no matches.| |8|`)+`|The value of the third captured group is ">".

The next character in the input string is not a right angle bracket, so the regular expression engine does not loop back to the `((?'Close-Open'>)[^<>]*)` subpattern.| |9|`)*`|The value of the first captured group is "\".

The next character in the input string is a left angle bracket, so the regular expression engine loops back to the `(((?'Open'<)` subpattern.| -|10|`(((?'Open'<)`|Matches the left angle bracket in "\ collection now has a single value, "<".| +|10|`(((?'Open'<)`|Matches the left angle bracket in "\ collection now has a single value, "<".| |11|`[^<>]*`|Matches "mno".| |12|`)+`|"
The next character in the input string is an left angle bracket, so the regular expression engine loops back to the `(?'Open'<)[^<>]*)` subpattern.| -|13|`(((?'Open'<)`|Matches the left angle bracket in "\" and assigns it to the `Open` group. The collection of the `Open` group now includes two captures: the left angle bracket from "\".| +|13|`(((?'Open'<)`|Matches the left angle bracket in "\" and assigns it to the `Open` group. The collection of the `Open` group now includes two captures: the left angle bracket from "\".| |14|`[^<>]*`|Matches "xyz".| |15|`)+`|"
The next character in the input string is not a left angle bracket, so the regular expression engine does not loop back to the `(?'Open'<)[^<>]*)` subpattern.| -|16|`((?'Close-Open'>)`|Matches the right angle bracket in "\". "xyz", assigns the substring between the `Open` group and the right angle bracket to the `Close` group, and deletes the current value of the `Open` group. The value of the previous capture (the left angle bracket in "\ collection of the `Open` group now includes a single capture, the left angle bracket from "\".| +|16|`((?'Close-Open'>)`|Matches the right angle bracket in "\". "xyz", assigns the substring between the `Open` group and the right angle bracket to the `Close` group, and deletes the current value of the `Open` group. The value of the previous capture (the left angle bracket in "\ collection of the `Open` group now includes a single capture, the left angle bracket from "\".| |17|`[^<>]*`|Looks for non-angle bracket characters; finds no matches.| |18|`)+`|The value of the third captured group is ">".

The next character in the input string is a right angle bracket, so the regular expression engine loops back to the `((?'Close-Open'>)[^<>]*)` subpattern.| |19|`((?'Close-Open'>)`|Matches the final right angle bracket in "xyz>>", assigns "mno\" (the substring between the `Open` group and the right angle bracket) to the `Close` group, and deletes the current value of the `Open` group. The `Open` group is now empty.| @@ -418,13 +418,13 @@ The nonbacktracking regular expression `(?>(\w)\1+).\b` is defined as shown in t ## Grouping constructs and regular expression objects -Substrings that are matched by a regular expression capturing group are represented by objects, which can be retrieved from the object that is returned by the property. The object is populated as follows: +Substrings that are matched by a regular expression capturing group are represented by objects, which can be retrieved from the object that is returned by the property. The object is populated as follows: - The first object in the collection (the object at index zero) represents the entire match. - The next set of objects represent unnamed (numbered) capturing groups. They appear in the order in which they are defined in the regular expression, from left to right. The index values of these groups range from 1 to the number of unnamed capturing groups in the collection. (The index of a particular group is equivalent to its numbered backreference. For more information about backreferences, see [Backreference Constructs](backreference-constructs-in-regular-expressions.md).) - The final set of objects represent named capturing groups. They appear in the order in which they are defined in the regular expression, from left to right. The index value of the first named capturing group is one greater than the index of the last unnamed capturing group. If there are no unnamed capturing groups in the regular expression, the index value of the first named capturing group is one. -If you apply a quantifier to a capturing group, the corresponding object's , , and properties reflect the last substring that is captured by a capturing group. You can retrieve a complete set of substrings that are captured by groups that have quantifiers from the object that is returned by the property. +If you apply a quantifier to a capturing group, the corresponding object's , , and properties reflect the last substring that is captured by a capturing group. You can retrieve a complete set of substrings that are captured by groups that have quantifiers from the object that is returned by the property. The following example clarifies the relationship between the and objects. @@ -440,7 +440,7 @@ The regular expression pattern `(\b(\w+)\W+)+` extracts individual words from a |`\W+`|Match one or more non-word characters.| |`(\b(\w+)\W+)`|Match the pattern of one or more word characters followed by one or more non-word characters one or more times. This is the first capturing group.| -The second capturing group matches each word of the sentence. The first capturing group matches each word along with the punctuation and white space that follow the word. The object whose index is 2 provides information about the text matched by the second capturing group. The complete set of words captured by the capturing group are available from the object returned by the property. +The second capturing group matches each word of the sentence. The first capturing group matches each word along with the punctuation and white space that follow the word. The object whose index is 2 provides information about the text matched by the second capturing group. The complete set of words captured by the capturing group are available from the object returned by the property. ## See also diff --git a/docs/standard/base-types/how-to-define-and-use-custom-numeric-format-providers.md b/docs/standard/base-types/how-to-define-and-use-custom-numeric-format-providers.md index 6ec49c52e1c52..7bcf65d60d2c1 100644 --- a/docs/standard/base-types/how-to-define-and-use-custom-numeric-format-providers.md +++ b/docs/standard/base-types/how-to-define-and-use-custom-numeric-format-providers.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Define and Use Custom Numeric Format Providers" title: "How to: Define and Use Custom Numeric Format Providers" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "numeric format strings [.NET]" - "formatting [.NET], numbers" - "number formatting [.NET]" @@ -18,66 +18,66 @@ ms.assetid: a281bfbf-6596-45ed-a2d6-3782d535ada2 --- # How to: Define and Use Custom Numeric Format Providers -.NET gives you extensive control over the string representation of numeric values. It supports the following features for customizing the format of numeric values: - -- Standard numeric format strings, which provide a predefined set of formats for converting numbers to their string representation. You can use them with any numeric formatting method, such as , that has a `format` parameter. For details, see [Standard Numeric Format Strings](standard-numeric-format-strings.md). - -- Custom numeric format strings, which provide a set of symbols that can be combined to define custom numeric format specifiers. They can also be used with any numeric formatting method, such as , that has a `format` parameter. For details, see [Custom Numeric Format Strings](custom-numeric-format-strings.md). - -- Custom or objects, which define the symbols and format patterns used in displaying the string representations of numeric values. You can use them with any numeric formatting method, such as , that has a `provider` parameter. Typically, the `provider` parameter is used to specify culture-specific formatting. - - In some cases (such as when an application must display a formatted account number, an identification number, or a postal code) these three techniques are inappropriate. .NET also enables you to define a formatting object that is neither a nor a object to determine how a numeric value is formatted. This topic provides the step-by-step instructions for implementing such an object, and provides an example that formats telephone numbers. - -## Define a custom format provider - -1. Define a class that implements the and interfaces. - -2. Implement the method. is a callback method that the formatting method (such as the method) invokes to retrieve the object that is actually responsible for performing custom formatting. A typical implementation of does the following: - - 1. Determines whether the object passed as a method parameter represents an interface. - - 2. If the parameter does represent the interface, returns an object that implements the interface that is responsible for providing custom formatting. Typically, the custom formatting object returns itself. - - 3. If the parameter does not represent the interface, returns `null`. - -3. Implement the method. This method is called by the method and is responsible for returning the string representation of a number. Implementing the method typically involves the following: - - 1. Optionally, make sure that the method is legitimately intended to provide formatting services by examining the `provider` parameter. For formatting objects that implement both and , this involves testing the `provider` parameter for equality with the current formatting object. - - 2. Determine whether the formatting object should support custom format specifiers. (For example, an "N" format specifier might indicate that a U.S. telephone number should be output in NANP format, and an "I" might indicate output in ITU-T Recommendation E.123 format.) If format specifiers are used, the method should handle the specific format specifier. It is passed to the method in the `format` parameter. If no specifier is present, the value of the `format` parameter is . - - 3. Retrieve the numeric value passed to the method as the `arg` parameter. Perform whatever manipulations are required to convert it to its string representation. - - 4. Return the string representation of the `arg` parameter. - -## Use a custom numeric formatting object - -1. Create a new instance of the custom formatting class. - -2. Call the formatting method, passing it the custom formatting object, the formatting specifier (or , if one is not used), and the numeric value to be formatted. - +.NET gives you extensive control over the string representation of numeric values. It supports the following features for customizing the format of numeric values: + +- Standard numeric format strings, which provide a predefined set of formats for converting numbers to their string representation. You can use them with any numeric formatting method, such as , that has a `format` parameter. For details, see [Standard Numeric Format Strings](standard-numeric-format-strings.md). + +- Custom numeric format strings, which provide a set of symbols that can be combined to define custom numeric format specifiers. They can also be used with any numeric formatting method, such as , that has a `format` parameter. For details, see [Custom Numeric Format Strings](custom-numeric-format-strings.md). + +- Custom or objects, which define the symbols and format patterns used in displaying the string representations of numeric values. You can use them with any numeric formatting method, such as , that has a `provider` parameter. Typically, the `provider` parameter is used to specify culture-specific formatting. + + In some cases (such as when an application must display a formatted account number, an identification number, or a postal code) these three techniques are inappropriate. .NET also enables you to define a formatting object that is neither a nor a object to determine how a numeric value is formatted. This topic provides the step-by-step instructions for implementing such an object, and provides an example that formats telephone numbers. + +## Define a custom format provider + +1. Define a class that implements the and interfaces. + +2. Implement the method. is a callback method that the formatting method (such as the method) invokes to retrieve the object that is actually responsible for performing custom formatting. A typical implementation of does the following: + + 1. Determines whether the object passed as a method parameter represents an interface. + + 2. If the parameter does represent the interface, returns an object that implements the interface that is responsible for providing custom formatting. Typically, the custom formatting object returns itself. + + 3. If the parameter does not represent the interface, returns `null`. + +3. Implement the method. This method is called by the method and is responsible for returning the string representation of a number. Implementing the method typically involves the following: + + 1. Optionally, make sure that the method is legitimately intended to provide formatting services by examining the `provider` parameter. For formatting objects that implement both and , this involves testing the `provider` parameter for equality with the current formatting object. + + 2. Determine whether the formatting object should support custom format specifiers. (For example, an "N" format specifier might indicate that a U.S. telephone number should be output in NANP format, and an "I" might indicate output in ITU-T Recommendation E.123 format.) If format specifiers are used, the method should handle the specific format specifier. It is passed to the method in the `format` parameter. If no specifier is present, the value of the `format` parameter is . + + 3. Retrieve the numeric value passed to the method as the `arg` parameter. Perform whatever manipulations are required to convert it to its string representation. + + 4. Return the string representation of the `arg` parameter. + +## Use a custom numeric formatting object + +1. Create a new instance of the custom formatting class. + +2. Call the formatting method, passing it the custom formatting object, the formatting specifier (or , if one is not used), and the numeric value to be formatted. + ## Example - The following example defines a custom numeric format provider named `TelephoneFormatter` that converts a number that represents a U.S. telephone number to its NANP or E.123 format. The method handles two format specifiers, "N" (which outputs the NANP format) and "I" (which outputs the international E.123 format). - + The following example defines a custom numeric format provider named `TelephoneFormatter` that converts a number that represents a U.S. telephone number to its NANP or E.123 format. The method handles two format specifiers, "N" (which outputs the NANP format) and "I" (which outputs the international E.123 format). + [!code-csharp[Formatting.HowTo.NumericValue#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.NumericValue/cs/Telephone1.cs#1)] - [!code-vb[Formatting.HowTo.NumericValue#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.NumericValue/vb/Telephone1.vb#1)] - - The custom numeric format provider can be used only with the method. The other overloads of numeric formatting methods (such as `ToString`) that have a parameter of type all pass the implementation a object that represents the type. In return, they expect the method to return a object. If it does not, the custom numeric format provider is ignored, and the object for the current culture is used in its place. In the example, the `TelephoneFormatter.GetFormat` method handles the possibility that it may be inappropriately passed to a numeric formatting method by examining the method parameter and returning `null` if it represents a type other than . - - If a custom numeric format provider supports a set of format specifiers, make sure you provide a default behavior if no format specifier is supplied in the format item used in the method call. In the example, "N" is the default format specifier. This allows for a number to be converted to a formatted telephone number by providing an explicit format specifier. The following example illustrates such a method call. - + [!code-vb[Formatting.HowTo.NumericValue#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.NumericValue/vb/Telephone1.vb#1)] + + The custom numeric format provider can be used only with the method. The other overloads of numeric formatting methods (such as `ToString`) that have a parameter of type all pass the implementation a object that represents the type. In return, they expect the method to return a object. If it does not, the custom numeric format provider is ignored, and the object for the current culture is used in its place. In the example, the `TelephoneFormatter.GetFormat` method handles the possibility that it may be inappropriately passed to a numeric formatting method by examining the method parameter and returning `null` if it represents a type other than . + + If a custom numeric format provider supports a set of format specifiers, make sure you provide a default behavior if no format specifier is supplied in the format item used in the method call. In the example, "N" is the default format specifier. This allows for a number to be converted to a formatted telephone number by providing an explicit format specifier. The following example illustrates such a method call. + [!code-csharp[Formatting.HowTo.NumericValue#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.NumericValue/cs/Telephone1.cs#2)] - [!code-vb[Formatting.HowTo.NumericValue#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.NumericValue/vb/Telephone1.vb#2)] - - But it also allows the conversion to occur if no format specifier is present. The following example illustrates such a method call. - + [!code-vb[Formatting.HowTo.NumericValue#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.NumericValue/vb/Telephone1.vb#2)] + + But it also allows the conversion to occur if no format specifier is present. The following example illustrates such a method call. + [!code-csharp[Formatting.HowTo.NumericValue#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.NumericValue/cs/Telephone1.cs#3)] - [!code-vb[Formatting.HowTo.NumericValue#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.NumericValue/vb/Telephone1.vb#3)] - - If no default format specifier is defined, your implementation of the method should include code such as the following so that .NET can provide formatting that your code does not support. - + [!code-vb[Formatting.HowTo.NumericValue#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.NumericValue/vb/Telephone1.vb#3)] + + If no default format specifier is defined, your implementation of the method should include code such as the following so that .NET can provide formatting that your code does not support. + [!code-csharp[System.ICustomFormatter.Format#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.ICustomFormatter.Format/cs/format.cs#1)] - [!code-vb[System.ICustomFormatter.Format#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.ICustomFormatter.Format/vb/Format.vb#1)] - - In the case of this example, the method that implements is intended to serve as a callback method for the method. Therefore, it examines the `formatProvider` parameter to determine whether it contains a reference to the current `TelephoneFormatter` object. However, the method can also be called directly from code. In that case, you can use the `formatProvider` parameter to provide a or object that supplies culture-specific formatting information. + [!code-vb[System.ICustomFormatter.Format#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.ICustomFormatter.Format/vb/Format.vb#1)] + + In the case of this example, the method that implements is intended to serve as a callback method for the method. Therefore, it examines the `formatProvider` parameter to determine whether it contains a reference to the current `TelephoneFormatter` object. However, the method can also be called directly from code. In that case, you can use the `formatProvider` parameter to provide a or object that supplies culture-specific formatting information. diff --git a/docs/standard/base-types/how-to-display-dates-in-non-gregorian-calendars.md b/docs/standard/base-types/how-to-display-dates-in-non-gregorian-calendars.md index 04ca792a37568..7f7dfcc0a6eb3 100644 --- a/docs/standard/base-types/how-to-display-dates-in-non-gregorian-calendars.md +++ b/docs/standard/base-types/how-to-display-dates-in-non-gregorian-calendars.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Display Dates in Non-Gregorian Calendars" title: "How to: Display Dates in Non-Gregorian Calendars" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "formatting [.NET], dates" - "dates [.NET], formatting" - "calendars [.NET], displaying dates" @@ -14,67 +14,67 @@ ms.assetid: ed324eff-4aff-4a76-b6c0-04e6c0d8f5a9 --- # How to: Display Dates in Non-Gregorian Calendars -The and types use the Gregorian calendar as their default calendar. This means that calling a date and time value's `ToString` method displays the string representation of that date and time in the Gregorian calendar, even if that date and time was created using another calendar. This is illustrated in the following example, which uses two different ways to create a date and time value with the Persian calendar, but still displays those date and time values in the Gregorian calendar when it calls the method. This example reflects two commonly used but incorrect techniques for displaying the date in a particular calendar. - +The and types use the Gregorian calendar as their default calendar. This means that calling a date and time value's `ToString` method displays the string representation of that date and time in the Gregorian calendar, even if that date and time was created using another calendar. This is illustrated in the following example, which uses two different ways to create a date and time value with the Persian calendar, but still displays those date and time values in the Gregorian calendar when it calls the method. This example reflects two commonly used but incorrect techniques for displaying the date in a particular calendar. + [!code-csharp[Formatting.HowTo.Calendar#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.Calendar/cs/Calendar1.cs#1)] - [!code-vb[Formatting.HowTo.Calendar#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.Calendar/vb/Calendar1.vb#1)] - - Two different techniques can be used to display the date in a particular calendar. The first requires that the calendar be the default calendar for a particular culture. The second can be used with any calendar. - -### To display the date for a culture's default calendar - -1. Instantiate a calendar object derived from the class that represents the calendar to be used. - -2. Instantiate a object representing the culture whose formatting will be used to display the date. - -3. Call the method to determine whether the calendar object is a member of the array returned by the property. This indicates that the calendar can serve as the default calendar for the object. If it is not a member of the array, follow the instructions in the "To Display the Date in Any Calendar" section. - -4. Assign the calendar object to the property of the object returned by the property. - + [!code-vb[Formatting.HowTo.Calendar#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.Calendar/vb/Calendar1.vb#1)] + + Two different techniques can be used to display the date in a particular calendar. The first requires that the calendar be the default calendar for a particular culture. The second can be used with any calendar. + +### To display the date for a culture's default calendar + +1. Instantiate a calendar object derived from the class that represents the calendar to be used. + +2. Instantiate a object representing the culture whose formatting will be used to display the date. + +3. Call the method to determine whether the calendar object is a member of the array returned by the property. This indicates that the calendar can serve as the default calendar for the object. If it is not a member of the array, follow the instructions in the "To Display the Date in Any Calendar" section. + +4. Assign the calendar object to the property of the object returned by the property. + > [!NOTE] - > The class also has a property. However, it is read-only and constant; it does not change to reflect the new default calendar assigned to the property. - -5. Call either the or the method, and pass it the object whose default calendar was modified in the previous step. - -### To display the date in any calendar - -1. Instantiate a calendar object derived from the class that represents the calendar to be used. - -2. Determine which date and time elements should appear in the string representation of the date and time value. - -3. For each date and time element that you want to display, call the calendar object's `Get`… method. The following methods are available: - - - , to display the year in the appropriate calendar. - - - , to display the month in the appropriate calendar. - - - , to display the number of the day of the month in the appropriate calendar. - - - , to display the hour of the day in the appropriate calendar. - - - , to display the minutes in the hour in the appropriate calendar. - - - , to display the seconds in the minute in the appropriate calendar. - - - , to display the milliseconds in the second in the appropriate calendar. - -## Example - - The example displays a date using two different calendars. It displays the date after defining the Hijri calendar as the default calendar for the ar-JO culture, and displays the date using the Persian calendar, which is not supported as an optional calendar by the fa-IR culture. - + > The class also has a property. However, it is read-only and constant; it does not change to reflect the new default calendar assigned to the property. + +5. Call either the or the method, and pass it the object whose default calendar was modified in the previous step. + +### To display the date in any calendar + +1. Instantiate a calendar object derived from the class that represents the calendar to be used. + +2. Determine which date and time elements should appear in the string representation of the date and time value. + +3. For each date and time element that you want to display, call the calendar object's `Get`… method. The following methods are available: + + - , to display the year in the appropriate calendar. + + - , to display the month in the appropriate calendar. + + - , to display the number of the day of the month in the appropriate calendar. + + - , to display the hour of the day in the appropriate calendar. + + - , to display the minutes in the hour in the appropriate calendar. + + - , to display the seconds in the minute in the appropriate calendar. + + - , to display the milliseconds in the second in the appropriate calendar. + +## Example + + The example displays a date using two different calendars. It displays the date after defining the Hijri calendar as the default calendar for the ar-JO culture, and displays the date using the Persian calendar, which is not supported as an optional calendar by the fa-IR culture. + [!code-csharp[Formatting.HowTo.Calendar#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.Calendar/cs/Calendar1.cs#2)] - [!code-vb[Formatting.HowTo.Calendar#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.Calendar/vb/Calendar1.vb#2)] - - Each object can support one or more calendars, which are indicated by the property. One of these is designated as the culture's default calendar and is returned by the read-only property. Another of the optional calendars can be designated as the default by assigning a object that represents that calendar to the property returned by the property. However, some calendars, such as the Persian calendar represented by the class, do not serve as optional calendars for any culture. - - The example defines a reusable calendar utility class, `CalendarUtility`, to handle many of the details of generating the string representation of a date using a particular calendar. The `CalendarUtility` class has the following members: - -- A parameterized constructor whose single parameter is a object in which a date is to be represented. This is assigned to a private field of the class. - -- `CalendarExists`, a private method that returns a Boolean value indicating whether the calendar represented by the `CalendarUtility` object is supported by the object that is passed to the method as a parameter. The method wraps a call to the method, to which it passes the array. - -- `HasSameName`, a private method assigned to the delegate that is passed as a parameter to the method. Each member of the array is passed to the method until the method returns `true`. The method determines whether the name of an optional calendar is the same as the calendar represented by the `CalendarUtility` object. - -- `DisplayDate`, an overloaded public method that is passed two parameters: either a or value to express in the calendar represented by the `CalendarUtility` object; and the culture whose formatting rules are to be used. Its behavior in returning the string representation of a date depends on whether the target calendar is supported by the culture whose formatting rules are to be used. - + [!code-vb[Formatting.HowTo.Calendar#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.Calendar/vb/Calendar1.vb#2)] + + Each object can support one or more calendars, which are indicated by the property. One of these is designated as the culture's default calendar and is returned by the read-only property. Another of the optional calendars can be designated as the default by assigning a object that represents that calendar to the property returned by the property. However, some calendars, such as the Persian calendar represented by the class, do not serve as optional calendars for any culture. + + The example defines a reusable calendar utility class, `CalendarUtility`, to handle many of the details of generating the string representation of a date using a particular calendar. The `CalendarUtility` class has the following members: + +- A parameterized constructor whose single parameter is a object in which a date is to be represented. This is assigned to a private field of the class. + +- `CalendarExists`, a private method that returns a Boolean value indicating whether the calendar represented by the `CalendarUtility` object is supported by the object that is passed to the method as a parameter. The method wraps a call to the method, to which it passes the array. + +- `HasSameName`, a private method assigned to the delegate that is passed as a parameter to the method. Each member of the array is passed to the method until the method returns `true`. The method determines whether the name of an optional calendar is the same as the calendar represented by the `CalendarUtility` object. + +- `DisplayDate`, an overloaded public method that is passed two parameters: either a or value to express in the calendar represented by the `CalendarUtility` object; and the culture whose formatting rules are to be used. Its behavior in returning the string representation of a date depends on whether the target calendar is supported by the culture whose formatting rules are to be used. + Regardless of the calendar used to create a or value in this example, that value is typically expressed as a Gregorian date. This is because the and types do not preserve any calendar information. Internally, they are represented as the number of ticks that have elapsed since midnight of January 1, 0001. The interpretation of that number depends on the calendar. For most cultures, the default calendar is the Gregorian calendar. diff --git a/docs/standard/base-types/how-to-display-milliseconds-in-date-and-time-values.md b/docs/standard/base-types/how-to-display-milliseconds-in-date-and-time-values.md index 9bf1c690845f6..18395b64f7b57 100644 --- a/docs/standard/base-types/how-to-display-milliseconds-in-date-and-time-values.md +++ b/docs/standard/base-types/how-to-display-milliseconds-in-date-and-time-values.md @@ -3,10 +3,10 @@ title: "How to: Display Milliseconds in Date and Time Values" description: In this article, learn how to include a date and time's millisecond component in formatted date and time strings in .NET. ms.date: "08/01/2022" ms.custom: devdivchpfy22 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "DateTime.ToString method" - "displaying date and time data" - "time [.NET], milliseconds" @@ -22,10 +22,10 @@ The default date and time formatting methods, such as or a value by using the static or method. -1. To extract the string representation of a time's millisecond component, call the date and time value's or method, and pass the `fff` or `FFF` custom format pattern alone or with other custom format specifiers as the `format` parameter. +1. To extract the string representation of a time's millisecond component, call the date and time value's or method, and pass the `fff` or `FFF` custom format pattern alone or with other custom format specifiers as the `format` parameter. > [!TIP] -> The property specifies the millisecond separator. +> The property specifies the millisecond separator. ## Example @@ -39,7 +39,7 @@ The `fff` format pattern includes any trailing zeros in the millisecond value. T :::code language="csharp" source="snippets/how-to-display-milliseconds-in-date-and-time-values/csharp/Program.cs" id="TrailingZero"::: :::code language="vb" source="snippets/how-to-display-milliseconds-in-date-and-time-values/vb/Program.vb" id="TrailingZero"::: -A problem with defining a complete custom format specifier that includes the millisecond component of a date and time is that it defines a hard-coded format that might not correspond to the arrangement of time elements in the application's current culture. A better alternative is to retrieve one of the date and time display patterns defined by the current culture's object and modify it to include milliseconds. The example also illustrates this approach. It retrieves the current culture's full date and time pattern from the property and then inserts the custom pattern `fff` along with the current culture's millisecond separator. The example uses a regular expression to do this operation in a single method call. +A problem with defining a complete custom format specifier that includes the millisecond component of a date and time is that it defines a hard-coded format that might not correspond to the arrangement of time elements in the application's current culture. A better alternative is to retrieve one of the date and time display patterns defined by the current culture's object and modify it to include milliseconds. The example also illustrates this approach. It retrieves the current culture's full date and time pattern from the property and then inserts the custom pattern `fff` along with the current culture's millisecond separator. The example uses a regular expression to do this operation in a single method call. You can also use a custom format specifier to display a fractional part of seconds other than milliseconds. For example, the `f` or `F` custom format specifier displays tenths of a second, the `ff` or `FF` custom format specifier displays hundredths of a second, and the `ffff` or `FFFF` custom format specifier displays ten-thousandths of a second. Fractional parts of a millisecond are truncated instead of rounded in the returned string. These format specifiers are used in the following example: diff --git a/docs/standard/base-types/how-to-extract-a-protocol-and-port-number-from-a-url.md b/docs/standard/base-types/how-to-extract-a-protocol-and-port-number-from-a-url.md index dbb652945a4dd..d3e0d05b75194 100644 --- a/docs/standard/base-types/how-to-extract-a-protocol-and-port-number-from-a-url.md +++ b/docs/standard/base-types/how-to-extract-a-protocol-and-port-number-from-a-url.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Extract a Protocol and Port Number from a URL" title: "How to: Extract a Protocol and Port Number from a URL" ms.date: "06/30/2020" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "searching with regular expressions, examples" - "parsing text with regular expressions, examples" - "regular expressions, examples" @@ -16,35 +16,35 @@ ms.assetid: ab7f62b3-6d2c-4efb-8ac6-28600df5fd5c --- # How to: Extract a Protocol and Port Number from a URL -The following example extracts a protocol and port number from a URL. +The following example extracts a protocol and port number from a URL. [!INCLUDE [regex](../../../includes/regex.md)] -## Example +## Example + + The example uses the method to return the protocol followed by a colon followed by the port number. - The example uses the method to return the protocol followed by a colon followed by the port number. - [!code-csharp[RegularExpressions.Examples.Protocol#1](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Examples.Protocol/cs/Example.cs#1)] - [!code-vb[RegularExpressions.Examples.Protocol#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.Protocol/vb/Example.vb#1)] - - The regular expression pattern `^(?\w+)://[^/]+?(?:\d+)?/` can be interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`^`|Begin the match at the start of the string.| -|`(?\w+)`|Match one or more word characters. Name this group `proto`.| -|`://`|Match a colon followed by two slash marks.| -|`[^/]+?`|Match one or more occurrences (but as few as possible) of any character other than a slash mark.| -|`(?:\d+)?`|Match zero or one occurrence of a colon followed by one or more digit characters. Name this group `port`.| -|`/`|Match a slash mark.| - - The method expands the `${proto}${port}` replacement sequence, which concatenates the value of the two named groups captured in the regular expression pattern. It is a convenient alternative to explicitly concatenating the strings retrieved from the collection object returned by the property. - - The example uses the method with two substitutions, `${proto}` and `${port}`, to include the captured groups in the output string. You can retrieve the captured groups from the match's object instead, as the following code shows. - + [!code-vb[RegularExpressions.Examples.Protocol#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.Protocol/vb/Example.vb#1)] + + The regular expression pattern `^(?\w+)://[^/]+?(?:\d+)?/` can be interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`^`|Begin the match at the start of the string.| +|`(?\w+)`|Match one or more word characters. Name this group `proto`.| +|`://`|Match a colon followed by two slash marks.| +|`[^/]+?`|Match one or more occurrences (but as few as possible) of any character other than a slash mark.| +|`(?:\d+)?`|Match zero or one occurrence of a colon followed by one or more digit characters. Name this group `port`.| +|`/`|Match a slash mark.| + + The method expands the `${proto}${port}` replacement sequence, which concatenates the value of the two named groups captured in the regular expression pattern. It is a convenient alternative to explicitly concatenating the strings retrieved from the collection object returned by the property. + + The example uses the method with two substitutions, `${proto}` and `${port}`, to include the captured groups in the output string. You can retrieve the captured groups from the match's object instead, as the following code shows. + [!code-csharp[RegularExpressions.Examples.Protocol#2](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Examples.Protocol/cs/example2.cs#2)] - [!code-vb[RegularExpressions.Examples.Protocol#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.Protocol/vb/example2.vb#2)] - + [!code-vb[RegularExpressions.Examples.Protocol#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.Protocol/vb/example2.vb#2)] + ## See also - [.NET Regular Expressions](regular-expressions.md) diff --git a/docs/standard/base-types/how-to-extract-the-day-of-the-week-from-a-specific-date.md b/docs/standard/base-types/how-to-extract-the-day-of-the-week-from-a-specific-date.md index 813ebb04cba74..b24480d5da78c 100644 --- a/docs/standard/base-types/how-to-extract-the-day-of-the-week-from-a-specific-date.md +++ b/docs/standard/base-types/how-to-extract-the-day-of-the-week-from-a-specific-date.md @@ -3,10 +3,10 @@ title: "How to: Extract the Day of the Week from a Specific Date" description: Learn how to determine the ordinal day of the week for a particular date in .NET. Learn how to display the localized weekday name for a particular date. ms.date: "08/09/2022" ms.custom: devdivchpfy22 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "formatting [.NET], dates" - "DateTime.DayOfWeek property" - "DateTime.ToString method" @@ -26,72 +26,72 @@ ms.assetid: 1c9bef76-5634-46cf-b91c-9b9eb72091d7 --- # How to: Extract the Day of the Week from a Specific Date -.NET makes it easy to determine the ordinal day of the week for a particular date, and to display the localized weekday name for a particular date. An enumerated value that indicates the day of the week corresponding to a particular date is available from the or property. In contrast, retrieving the weekday name is a formatting operation that can be performed by calling a formatting method, such as a date and time value's `ToString` method or the method. This article shows how to perform these formatting operations. - +.NET makes it easy to determine the ordinal day of the week for a particular date, and to display the localized weekday name for a particular date. An enumerated value that indicates the day of the week corresponding to a particular date is available from the or property. In contrast, retrieving the weekday name is a formatting operation that can be performed by calling a formatting method, such as a date and time value's `ToString` method or the method. This article shows how to perform these formatting operations. + ## Extract a number indicating the day of the week - -1. Use the static or method to convert the string representation of a date to a or a value. - -1. Use the or property to retrieve a value that indicates the day of the week. - -1. If necessary, cast (in C#) or convert (in Visual Basic) the value to an integer. - + +1. Use the static or method to convert the string representation of a date to a or a value. + +1. Use the or property to retrieve a value that indicates the day of the week. + +1. If necessary, cast (in C#) or convert (in Visual Basic) the value to an integer. + The following example displays an integer that represents the day of the week of a specific date: - + [!code-csharp[Formatting.Howto.WeekdayName#7](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/weekdaynumber7.cs#7)] - [!code-vb[Formatting.Howto.WeekdayName#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/weekdaynumber7.vb#7)] - + [!code-vb[Formatting.Howto.WeekdayName#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/weekdaynumber7.vb#7)] + ## Extract the abbreviated weekday name - -1. Use the static or method to convert the string representation of a date to a or a value. - -1. You can extract the abbreviated weekday name of the current culture or of a specific culture: - - 1. To extract the abbreviated weekday name for the current culture, call the date and time value's or instance method, and pass the string `ddd` as the `format` parameter. The following example illustrates the call to the method: - + +1. Use the static or method to convert the string representation of a date to a or a value. + +1. You can extract the abbreviated weekday name of the current culture or of a specific culture: + + 1. To extract the abbreviated weekday name for the current culture, call the date and time value's or instance method, and pass the string `ddd` as the `format` parameter. The following example illustrates the call to the method: + [!code-csharp[Formatting.Howto.WeekdayName#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/abbrname1.cs#1)] - [!code-vb[Formatting.Howto.WeekdayName#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/abbrname1.vb#1)] - + [!code-vb[Formatting.Howto.WeekdayName#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/abbrname1.vb#1)] + 1. To extract the abbreviated weekday name for a specific culture, call the date and time value's or instance method. Pass the string `ddd` as the `format` parameter. Pass either a or a object that represents the culture whose weekday name you want to retrieve as the `provider` parameter. The following code illustrates a call to the method using a object that represents the fr-FR culture: - + [!code-csharp[Formatting.Howto.WeekdayName#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/abbrname2.cs#2)] - [!code-vb[Formatting.Howto.WeekdayName#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/abbrname2.vb#2)] - + [!code-vb[Formatting.Howto.WeekdayName#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/abbrname2.vb#2)] + ## Extract the full weekday name - -1. Use the static or method to convert the string representation of a date to a or a value. - -1. You can extract the full weekday name of the current culture or of a specific culture: - + +1. Use the static or method to convert the string representation of a date to a or a value. + +1. You can extract the full weekday name of the current culture or of a specific culture: + 1. To extract the weekday name for the current culture, call the date and time value's or instance method, and pass the string `dddd` as the `format` parameter. The following example illustrates the call to the method: - + [!code-csharp[Formatting.Howto.WeekdayName#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/fullname4.cs#4)] - [!code-vb[Formatting.Howto.WeekdayName#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/fullname4.vb#4)] - + [!code-vb[Formatting.Howto.WeekdayName#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/fullname4.vb#4)] + 1. To extract the weekday name for a specific culture, call the date and time value's or instance method. Pass the string `dddd` as the `format` parameter. Pass either a or a object that represents the culture whose weekday name you want to retrieve as the `provider` parameter. The following code illustrates a call to the method using a object that represents the es-ES culture: - + [!code-csharp[Formatting.Howto.WeekdayName#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/fullname5.cs#5)] - [!code-vb[Formatting.Howto.WeekdayName#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/fullname5.vb#5)] - -## Example + [!code-vb[Formatting.Howto.WeekdayName#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/fullname5.vb#5)] + +## Example + + The following example illustrates calls to the and properties to retrieve the number that represents the day of the week for a particular date. It also includes calls to the and methods to extract the abbreviated weekday name and the full weekday name. - The following example illustrates calls to the and properties to retrieve the number that represents the day of the week for a particular date. It also includes calls to the and methods to extract the abbreviated weekday name and the full weekday name. - [!code-csharp[Formatting.Howto.WeekdayName#6](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/example6.cs#6)] - [!code-vb[Formatting.Howto.WeekdayName#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/example6.vb#6)] - - Individual languages might provide functionality that duplicates or supplements the functionality provided by .NET. For example, Visual Basic includes two such functions: - -- `Weekday`, which returns a number that indicates the day of the week of a particular date. It considers the ordinal value of the first day of the week to be one, whereas the property considers it to be zero. - -- `WeekdayName`, which returns the name of the week in the current culture that corresponds to a particular weekday number. - + [!code-vb[Formatting.Howto.WeekdayName#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/example6.vb#6)] + + Individual languages might provide functionality that duplicates or supplements the functionality provided by .NET. For example, Visual Basic includes two such functions: + +- `Weekday`, which returns a number that indicates the day of the week of a particular date. It considers the ordinal value of the first day of the week to be one, whereas the property considers it to be zero. + +- `WeekdayName`, which returns the name of the week in the current culture that corresponds to a particular weekday number. + The following example illustrates the use of the Visual Basic `Weekday` and `WeekdayName` functions: - - [!code-vb[Formatting.HowTo.WeekdayName#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/example9.vb#9)] - - You can also use the value returned by the property to retrieve the weekday name of a particular date. This process requires only a call to the method on the value returned by the property. However, this technique doesn't produce a localized weekday name for the current culture, as the following example illustrates: - + + [!code-vb[Formatting.HowTo.WeekdayName#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/example9.vb#9)] + + You can also use the value returned by the property to retrieve the weekday name of a particular date. This process requires only a call to the method on the value returned by the property. However, this technique doesn't produce a localized weekday name for the current culture, as the following example illustrates: + [!code-csharp[Formatting.HowTo.WeekdayName#8](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/Howto1.cs#8)] [!code-vb[Formatting.HowTo.WeekdayName#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/Howto1.vb#8)] diff --git a/docs/standard/base-types/how-to-pad-a-number-with-leading-zeros.md b/docs/standard/base-types/how-to-pad-a-number-with-leading-zeros.md index df5a9b4abb282..00a90bbe4e8f9 100644 --- a/docs/standard/base-types/how-to-pad-a-number-with-leading-zeros.md +++ b/docs/standard/base-types/how-to-pad-a-number-with-leading-zeros.md @@ -28,7 +28,7 @@ You can add leading zeros to an integer by using the "D" [standard numeric forma - To display the integer as a hexadecimal value, call its `ToString(String)` method and pass the string "X*n*" as the value of the format parameter, where *n* represents the minimum length of the string. -You can also use the format string in an interpolated string in both [C#](../../csharp/language-reference/tokens/interpolated.md) and [Visual Basic](../../visual-basic/programming-guide/language-features/strings/interpolated-strings.md). Alternatively, you can call a method such as or that uses [composite formatting](composite-formatting.md). +You can also use the format string in an interpolated string in both [C#](../../csharp/language-reference/tokens/interpolated.md) and [Visual Basic](../../visual-basic/programming-guide/language-features/strings/interpolated-strings.md). Alternatively, you can call a method such as or that uses [composite formatting](composite-formatting.md). The following example formats several integer values with leading zeros so that the total length of the formatted number is at least eight characters. diff --git a/docs/standard/base-types/how-to-round-trip-date-and-time-values.md b/docs/standard/base-types/how-to-round-trip-date-and-time-values.md index 08a3261588f2f..c4aa1cb7bd112 100644 --- a/docs/standard/base-types/how-to-round-trip-date-and-time-values.md +++ b/docs/standard/base-types/how-to-round-trip-date-and-time-values.md @@ -31,7 +31,7 @@ The following example illustrates how to round-trip a val [!code-csharp[Formatting.HowTo.RoundTrip#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.RoundTrip/cs/RoundTrip.cs#1)] [!code-vb[Formatting.HowTo.RoundTrip#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.RoundTrip/vb/RoundTrip.vb#1)] -When round-tripping a value, this technique successfully preserves the time for all local and universal times. For example, if a local value is saved on a system in the U.S. Pacific Standard Time zone and is restored on a system in the U.S. Central Standard Time zone, the restored date and time will be two hours later than the original time, which reflects the time difference between the two time zones. However, this technique is not necessarily accurate for unspecified times. All values whose property is are treated as if they are local times. If it's not a local time, the doesn't successfully identify the correct point in time. The workaround for this limitation is to tightly couple a date and time value with its time zone for the save and restore operation. +When round-tripping a value, this technique successfully preserves the time for all local and universal times. For example, if a local value is saved on a system in the U.S. Pacific Standard Time zone and is restored on a system in the U.S. Central Standard Time zone, the restored date and time will be two hours later than the original time, which reflects the time difference between the two time zones. However, this technique is not necessarily accurate for unspecified times. All values whose property is are treated as if they are local times. If it's not a local time, the doesn't successfully identify the correct point in time. The workaround for this limitation is to tightly couple a date and time value with its time zone for the save and restore operation. ## Round-trip a DateTimeOffset value @@ -48,7 +48,7 @@ The following example illustrates how to round-trip a value as a single point in time. The value can then be converted to Coordinated Universal Time (UTC) by calling the method, or it can be converted to the time in a particular time zone by calling the or method. The major limitation of this technique is that date and time arithmetic, when performed on a value that represents the time in a particular time zone, may not produce accurate results for that time zone. This is because when a value is instantiated, it is disassociated from its time zone. Therefore, that time zone's adjustment rules can no longer be applied when you perform date and time calculations. You can work around this problem by defining a custom type that includes both a date and time value and its accompanying time zone. +This technique always unambiguously identifies a value as a single point in time. The value can then be converted to Coordinated Universal Time (UTC) by calling the method, or it can be converted to the time in a particular time zone by calling the or method. The major limitation of this technique is that date and time arithmetic, when performed on a value that represents the time in a particular time zone, may not produce accurate results for that time zone. This is because when a value is instantiated, it is disassociated from its time zone. Therefore, that time zone's adjustment rules can no longer be applied when you perform date and time calculations. You can work around this problem by defining a custom type that includes both a date and time value and its accompanying time zone. ## Compile the code diff --git a/docs/standard/base-types/how-to-strip-invalid-characters-from-a-string.md b/docs/standard/base-types/how-to-strip-invalid-characters-from-a-string.md index 80204bc24e7b2..8e739ff824992 100644 --- a/docs/standard/base-types/how-to-strip-invalid-characters-from-a-string.md +++ b/docs/standard/base-types/how-to-strip-invalid-characters-from-a-string.md @@ -2,10 +2,10 @@ title: "How to: Strip Invalid Characters from a String" description: Read an example that shows how to strip potentially harmful characters from a string by using the static Regex.Replace method. ms.date: "06/30/2020" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "regular expressions, examples" - "cleaning input" - "user input, examples" @@ -19,19 +19,19 @@ ms.assetid: b4319c8a-9032-4129-a9d5-6f6fc28e7f32 --- # How to: Strip Invalid Characters from a String -The following example uses the static method to strip invalid characters from a string. +The following example uses the static method to strip invalid characters from a string. [!INCLUDE [regex](../../../includes/regex.md)] -## Example +## Example + + You can use the `CleanInput` method defined in this example to strip potentially harmful characters that have been entered into a text field that accepts user input. In this case, `CleanInput` strips out all nonalphanumeric characters except periods (.), at symbols (@), and hyphens (-), and returns the remaining string. However, you can modify the regular expression pattern so that it strips out any characters that should not be included in an input string. - You can use the `CleanInput` method defined in this example to strip potentially harmful characters that have been entered into a text field that accepts user input. In this case, `CleanInput` strips out all nonalphanumeric characters except periods (.), at symbols (@), and hyphens (-), and returns the remaining string. However, you can modify the regular expression pattern so that it strips out any characters that should not be included in an input string. - [!code-csharp[RegularExpressions.Examples.StripChars#1](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Examples.StripChars/cs/Example.cs#1)] - [!code-vb[RegularExpressions.Examples.StripChars#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.StripChars/vb/Example.vb#1)] - - The regular expression pattern `[^\w\.@-]` matches any character that is not a word character, a period, an @ symbol, or a hyphen. A word character is any letter, decimal digit, or punctuation connector such as an underscore. Any character that matches this pattern is replaced by , which is the string defined by the replacement pattern. To allow additional characters in user input, add those characters to the character class in the regular expression pattern. For example, the regular expression pattern `[^\w\.@-\\%]` also allows a percentage symbol and a backslash in an input string. - + [!code-vb[RegularExpressions.Examples.StripChars#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.StripChars/vb/Example.vb#1)] + + The regular expression pattern `[^\w\.@-]` matches any character that is not a word character, a period, an @ symbol, or a hyphen. A word character is any letter, decimal digit, or punctuation connector such as an underscore. Any character that matches this pattern is replaced by , which is the string defined by the replacement pattern. To allow additional characters in user input, add those characters to the character class in the regular expression pattern. For example, the regular expression pattern `[^\w\.@-\\%]` also allows a percentage symbol and a backslash in an input string. + ## See also - [.NET Regular Expressions](regular-expressions.md) diff --git a/docs/standard/base-types/how-to-verify-that-strings-are-in-valid-email-format.md b/docs/standard/base-types/how-to-verify-that-strings-are-in-valid-email-format.md index fa9576c669142..b849b50987396 100644 --- a/docs/standard/base-types/how-to-verify-that-strings-are-in-valid-email-format.md +++ b/docs/standard/base-types/how-to-verify-that-strings-are-in-valid-email-format.md @@ -48,7 +48,7 @@ To verify that the email address is valid, the `IsValidEmail` method calls the < | `(.+)` | Match one or more occurrences of any character. This part is the second capturing group. | | `$` | End the match at the end of the string. | -The domain name, along with the @ character, is passed to the `DomainMapper` method. The method uses the class to translate Unicode characters that are outside the US-ASCII character range to Punycode. The method also sets the `invalid` flag to `True` if the method detects any invalid characters in the domain name. The method returns the Punycode domain name preceded by the @ symbol to the `IsValidEmail` method. +The domain name, along with the @ character, is passed to the `DomainMapper` method. The method uses the class to translate Unicode characters that are outside the US-ASCII character range to Punycode. The method also sets the `invalid` flag to `True` if the method detects any invalid characters in the domain name. The method returns the Punycode domain name preceded by the @ symbol to the `IsValidEmail` method. > [!TIP] > It's recommended that you use the simple `(@)(.+)$` regular expression pattern to normalize the domain and then return a value indicating that it passed or failed. However, the example in this article describes how to use a regular expression further to validate the email. Regardless of how you validate an email, you should always send a test email to the address to ensure it exists. diff --git a/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md b/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md index 613ad79b970c3..762562b7f550d 100644 --- a/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md +++ b/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md @@ -55,7 +55,7 @@ Regular expressions in .NET include three miscellaneous language constructs. One ## Inline Comment - The `(?#` *comment*`)` construct lets you include an inline comment in a regular expression. The regular expression engine does not use any part of the comment in pattern matching, although the comment is included in the string that is returned by the method. The comment ends at the first closing parenthesis. + The `(?#` *comment*`)` construct lets you include an inline comment in a regular expression. The regular expression engine does not use any part of the comment in pattern matching, although the comment is included in the string that is returned by the method. The comment ends at the first closing parenthesis. The following example repeats the first regular expression pattern from the example in the previous section. It adds two inline comments to the regular expression to indicate whether the comparison is case-sensitive. The regular expression pattern, `\b((?# case-sensitive comparison)D\w+)\s(?ixn)((?#case-insensitive comparison)d\w+)\b`, is defined as follows. diff --git a/docs/standard/base-types/padding.md b/docs/standard/base-types/padding.md index 87846918e7366..217b607d845c4 100644 --- a/docs/standard/base-types/padding.md +++ b/docs/standard/base-types/padding.md @@ -14,27 +14,27 @@ helpviewer_keywords: --- # Pad strings in .NET -Use one of the following methods to create a new string that consists of an original string that is padded with leading or trailing characters to a specified total length. The padding character can be a space or a specified character. The resulting string appears to be either right-aligned or left-aligned. If the original string's length is already equal to or greater than the desired total length, the padding methods return the original string unchanged; for more information, see the **Returns** sections of the two overloads of the and methods. +Use one of the following methods to create a new string that consists of an original string that is padded with leading or trailing characters to a specified total length. The padding character can be a space or a specified character. The resulting string appears to be either right-aligned or left-aligned. If the original string's length is already equal to or greater than the desired total length, the padding methods return the original string unchanged; for more information, see the **Returns** sections of the two overloads of the and methods. |Method name|Use| |-----------------|---------| -||Pads a string with leading characters to a specified total length.| -||Pads a string with trailing characters to a specified total length.| +||Pads a string with leading characters to a specified total length.| +||Pads a string with trailing characters to a specified total length.| ## PadLeft - The method creates a new string by concatenating enough leading pad characters to an original string to achieve a specified total length. The method uses white space as the padding character and the method enables you to specify your own padding character. + The method creates a new string by concatenating enough leading pad characters to an original string to achieve a specified total length. The method uses white space as the padding character and the method enables you to specify your own padding character. - The following code example uses the method to create a new string that is twenty characters long. The example displays "`--------Hello World!`" to the console. + The following code example uses the method to create a new string that is twenty characters long. The example displays "`--------Hello World!`" to the console. [!code-csharp[Conceptual.String.BasicOps#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/padding.cs#3)] [!code-vb[Conceptual.String.BasicOps#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.string.basicops/vb/padding.vb#3)] ## PadRight - The method creates a new string by concatenating enough trailing pad characters to an original string to achieve a specified total length. The method uses white space as the padding character and the method enables you to specify your own padding character. + The method creates a new string by concatenating enough trailing pad characters to an original string to achieve a specified total length. The method uses white space as the padding character and the method enables you to specify your own padding character. - The following code example uses the method to create a new string that is twenty characters long. The example displays "`Hello World!--------`" to the console. + The following code example uses the method to create a new string that is twenty characters long. The example displays "`Hello World!--------`" to the console. [!code-csharp[Conceptual.String.BasicOps#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/padding.cs#4)] [!code-vb[Conceptual.String.BasicOps#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.string.basicops/vb/padding.vb#4)] diff --git a/docs/standard/base-types/parsing-datetime.md b/docs/standard/base-types/parsing-datetime.md index d05320ebe95de..07ad91a1eabff 100644 --- a/docs/standard/base-types/parsing-datetime.md +++ b/docs/standard/base-types/parsing-datetime.md @@ -64,11 +64,11 @@ The text representing a date or time might be missing some information. For exam If the date is present in the string, it must include the month and one of the day or year. If the time is present, it must include the hour, and either the minutes or the AM/PM designator. -You can specify the constant to override these defaults. When you use that constant, any missing year, month, or day properties are set to the value `1`. The [last example](#styles-example) using demonstrates this behavior. +You can specify the constant to override these defaults. When you use that constant, any missing year, month, or day properties are set to the value `1`. The [last example](#styles-example) using demonstrates this behavior. ### UTC offset and time zone handling -In addition to a date and a time component, the string representation of a date and time can include an offset that indicates how much the time differs from Coordinated Universal Time (UTC). For example, the string "2/14/2007 5:32:00 -7:00" defines a time that's seven hours earlier than UTC. If an offset is omitted from the string representation of a time, parsing returns a object with its property set to . If an offset is specified, parsing returns a object with its property set to . Its value is also adjusted to the local time zone of your machine. You can modify this behavior by using a value with the parsing method. +In addition to a date and a time component, the string representation of a date and time can include an offset that indicates how much the time differs from Coordinated Universal Time (UTC). For example, the string "2/14/2007 5:32:00 -7:00" defines a time that's seven hours earlier than UTC. If an offset is omitted from the string representation of a time, parsing returns a object with its property set to . If an offset is specified, parsing returns a object with its property set to . Its value is also adjusted to the local time zone of your machine. You can modify this behavior by using a value with the parsing method. ### Ambiguous date handling @@ -76,17 +76,17 @@ The format provider is also used to interpret an ambiguous numeric date. It's un ### DateTime.Parse -The following example shows the use of the method to convert a `string` into a . This example uses the culture associated with the current thread. If the associated with the current culture can't parse the input string, a is thrown. +The following example shows the use of the method to convert a `string` into a . This example uses the culture associated with the current thread. If the associated with the current culture can't parse the input string, a is thrown. :::code source="./snippets/parsing-datetime/csharp/Program.cs" id="DateTimeParse" language="csharp"::: :::code source="./snippets/parsing-datetime/vb/Program.vb" id="DateTimeParse" language="vb"::: -You can also explicitly define the culture whose formatting conventions are used when you parse a string. You specify one of the standard objects returned by the property. The following example uses a format provider to parse a German string into a . It creates a representing the `de-DE` culture. That `CultureInfo` object ensures successful parsing of this particular string. This process precludes whatever setting is in the of the . +You can also explicitly define the culture whose formatting conventions are used when you parse a string. You specify one of the standard objects returned by the property. The following example uses a format provider to parse a German string into a . It creates a representing the `de-DE` culture. That `CultureInfo` object ensures successful parsing of this particular string. This process precludes whatever setting is in the of the . :::code language="csharp" source="./snippets/parsing-datetime/csharp/Program.cs" id="DateTimeParseCulture"::: :::code source="./snippets/parsing-datetime/vb/Program.vb" id="DateTimeParseCulture" language="vb"::: -However, you can use overloads of the method to specify custom format providers. The method doesn't support parsing non-standard formats. To parse a date and time expressed in a non-standard format, use the method instead. +However, you can use overloads of the method to specify custom format providers. The method doesn't support parsing non-standard formats. To parse a date and time expressed in a non-standard format, use the method instead. The following example uses the enumeration to specify that the current date and time information shouldn't be added to the for unspecified fields. @@ -95,14 +95,14 @@ However, you can use overloads of the method to ### DateTime.ParseExact -The method converts a string to a object if it conforms to one of the specified string patterns. When a string that isn't one of the forms specified is passed to this method, a is thrown. You can specify one of the standard date and time format specifiers or a combination of the custom format specifiers. Using the custom format specifiers, it's possible for you to construct a custom recognition string. For an explanation of the specifiers, see the articles on [standard date and time format strings](standard-date-and-time-format-strings.md) and [custom date and time format strings](custom-date-and-time-format-strings.md). +The method converts a string to a object if it conforms to one of the specified string patterns. When a string that isn't one of the forms specified is passed to this method, a is thrown. You can specify one of the standard date and time format specifiers or a combination of the custom format specifiers. Using the custom format specifiers, it's possible for you to construct a custom recognition string. For an explanation of the specifiers, see the articles on [standard date and time format strings](standard-date-and-time-format-strings.md) and [custom date and time format strings](custom-date-and-time-format-strings.md). -In the following example, the method is passed a string object to parse, followed by a format specifier, followed by a object. This method can only parse strings that follow the long date pattern in the `en-US` culture. +In the following example, the method is passed a string object to parse, followed by a format specifier, followed by a object. This method can only parse strings that follow the long date pattern in the `en-US` culture. :::code source="./snippets/parsing-datetime/csharp/Program.cs" id="DateTimeParseExact" language="csharp"::: :::code source="./snippets/parsing-datetime/vb/Program.vb" id="DateTimeParseExact" language="vb"::: -Each overload of the and methods also has an parameter that provides culture-specific information about the formatting of the string. The object is a object that represents a standard culture or a object that's returned by the property. also uses an additional string or string array argument that defines one or more custom date and time formats. +Each overload of the and methods also has an parameter that provides culture-specific information about the formatting of the string. The object is a object that represents a standard culture or a object that's returned by the property. also uses an additional string or string array argument that defines one or more custom date and time formats. ## DateOnly parsing @@ -116,14 +116,14 @@ The structure represents only a date without time informa ### DateOnly.Parse -The method converts common date string representations to a object. The method accepts various formats and uses the current culture or a specified culture for parsing. +The method converts common date string representations to a object. The method accepts various formats and uses the current culture or a specified culture for parsing. :::code source="./snippets/parsing-datetime/csharp/Program.cs" id="DateOnlyParse" language="csharp"::: :::code source="./snippets/parsing-datetime/vb/Program.vb" id="DateOnlyParse" language="vb"::: ### DateOnly.ParseExact -The method provides precise control over the expected format of the input string. Use this method when you know the exact format of the date string and want to ensure strict parsing. +The method provides precise control over the expected format of the input string. Use this method when you know the exact format of the date string and want to ensure strict parsing. :::code source="./snippets/parsing-datetime/csharp/Program.cs" id="DateOnlyParseExact" language="csharp"::: :::code source="./snippets/parsing-datetime/vb/Program.vb" id="DateOnlyParseExact" language="vb"::: @@ -142,14 +142,14 @@ The structure represents a time-of-day value, such as a d ### TimeOnly.Parse -The method converts common time string representations to a object. The method accepts various formats including 12-hour and 24-hour notation. +The method converts common time string representations to a object. The method accepts various formats including 12-hour and 24-hour notation. :::code source="./snippets/parsing-datetime/csharp/Program.cs" id="TimeOnlyParse" language="csharp"::: :::code source="./snippets/parsing-datetime/vb/Program.vb" id="TimeOnlyParse" language="vb"::: ### TimeOnly.ParseExact -The method provides precise control over the expected format of the input time string. Use this method when you know the exact format and want to ensure strict parsing. +The method provides precise control over the expected format of the input time string. Use this method when you know the exact format and want to ensure strict parsing. :::code source="./snippets/parsing-datetime/csharp/Program.cs" id="TimeOnlyParseExact" language="csharp"::: :::code source="./snippets/parsing-datetime/vb/Program.vb" id="TimeOnlyParseExact" language="vb"::: diff --git a/docs/standard/base-types/parsing-numeric.md b/docs/standard/base-types/parsing-numeric.md index 122767e4f3e1d..44107b2f6043d 100644 --- a/docs/standard/base-types/parsing-numeric.md +++ b/docs/standard/base-types/parsing-numeric.md @@ -17,17 +17,17 @@ ms.assetid: e39324ee-72e5-42d4-a80d-bf3ee7fc6c59 All numeric types have two static parsing methods, `Parse` and `TryParse`, that you can use to convert the string representation of a number into a numeric type. These methods enable you to parse strings that were produced by using the format strings documented in [Standard Numeric Format Strings](standard-numeric-format-strings.md) and [Custom Numeric Format Strings](custom-numeric-format-strings.md). By default, the `Parse` and `TryParse` methods can successfully convert strings that contain integral decimal digits only to integer values. They can successfully convert strings that contain integral and fractional decimal digits, group separators, and a decimal separator to floating-point values. The `Parse` method throws an exception if the operation fails, whereas the `TryParse` method returns `false`. > [!NOTE] -> Starting in .NET 7, the numeric types in .NET also implement the interface, which defines the and methods. +> Starting in .NET 7, the numeric types in .NET also implement the interface, which defines the and methods. ## Parsing and format providers - Typically, the string representations of numeric values differ by culture. Elements of numeric strings, such as currency symbols, group (or thousands) separators, and decimal separators, all vary by culture. Parsing methods either implicitly or explicitly use a format provider that recognizes these culture-specific variations. If no format provider is specified in a call to the `Parse` or `TryParse` method, the format provider associated with the current culture (the object returned by the property) is used. + Typically, the string representations of numeric values differ by culture. Elements of numeric strings, such as currency symbols, group (or thousands) separators, and decimal separators, all vary by culture. Parsing methods either implicitly or explicitly use a format provider that recognizes these culture-specific variations. If no format provider is specified in a call to the `Parse` or `TryParse` method, the format provider associated with the current culture (the object returned by the property) is used. - A format provider is represented by an implementation. This interface has a single member, the method, whose single parameter is a object that represents the type to be formatted. This method returns the object that provides formatting information. .NET supports the following two implementations for parsing numeric strings: + A format provider is represented by an implementation. This interface has a single member, the method, whose single parameter is a object that represents the type to be formatted. This method returns the object that provides formatting information. .NET supports the following two implementations for parsing numeric strings: -- A object whose method returns a object that provides culture-specific formatting information. +- A object whose method returns a object that provides culture-specific formatting information. -- A object whose method returns itself. +- A object whose method returns itself. The following example tries to convert each string in an array to a value. It first tries to parse the string by using a format provider that reflects the conventions of the English (United States) culture. If this operation throws a , it tries to parse the string by using a format provider that reflects the conventions of the French (France) culture. @@ -51,15 +51,15 @@ All numeric types have two static parsing methods, `Parse` and `TryParse`, that |NumberStyles value|Effect on the string to be parsed| |------------------------|---------------------------------------| ||Only numeric digits are permitted.| -||The decimal separator and fractional digits are permitted. For integer values, only zero is permitted as a fractional digit. Valid decimal separators are determined by the or property.| +||The decimal separator and fractional digits are permitted. For integer values, only zero is permitted as a fractional digit. Valid decimal separators are determined by the or property.| ||The "e" or "E" character can be used to indicate exponential notation. For more information, see .| ||Leading white space is permitted.| ||Trailing white space is permitted.| ||A positive or negative sign can precede numeric digits.| ||A positive or negative sign can follow numeric digits.| ||Parentheses can be used to indicate negative values.| -||The group separator is permitted. The group separator character is determined by the or property.| -||The currency symbol is permitted. The currency symbol is defined by the property.| +||The group separator is permitted. The group separator character is determined by the or property.| +||The currency symbol is permitted. The currency symbol is defined by the property.| ||The string to be parsed is interpreted as a hexadecimal number. It can include the hexadecimal digits 0-9, A-F, and a-f. This flag can be used only to parse integer values.| ||The string to be parsed is interpreted as a binary number. It can include the binary digits 0 and 1. This flag can be used only to parse integer values.| @@ -83,7 +83,7 @@ When parsing with the . - The following example uses the method to parse strings that consist of digits in different writing systems. As the output from the example shows, the attempt to parse the basic Latin digits succeeds, but the attempt to parse the Fullwidth, Arabic-Indic, and Bangla digits fails. + The following example uses the method to parse strings that consist of digits in different writing systems. As the output from the example shows, the attempt to parse the basic Latin digits succeeds, but the attempt to parse the Fullwidth, Arabic-Indic, and Bangla digits fails. [!code-csharp[Parsing.Numbers#3](../../../samples/snippets/csharp/VS_Snippets_CLR/parsing.numbers/cs/unicode1.cs#3)] [!code-vb[Parsing.Numbers#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/parsing.numbers/vb/unicode1.vb#3)] diff --git a/docs/standard/base-types/quantifiers-in-regular-expressions.md b/docs/standard/base-types/quantifiers-in-regular-expressions.md index c8b1c787dfadd..3531659df3201 100644 --- a/docs/standard/base-types/quantifiers-in-regular-expressions.md +++ b/docs/standard/base-types/quantifiers-in-regular-expressions.md @@ -5,10 +5,10 @@ ms.date: "08/09/2022" ms.custom: devdivchpfy22 ms.topic: concept-article ai-usage: ai-assisted -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "regular expressions, quantifiers" - "metacharacters, quantifiers" - "minimal matching quantifiers" @@ -21,268 +21,268 @@ ms.assetid: 36b81212-6511-49ed-a8f1-ff080415312f # Quantifiers in Regular Expressions Quantifiers specify how many instances of a character, group, or character class must be present in the input for a match to be found. The following table lists the quantifiers supported by .NET: - -|Greedy quantifier|Lazy quantifier|Description| -|-----------------------|---------------------|-----------------| -|`*`|`*?`|Matches zero or more times.| -|`+`|`+?`|Matches one or more times.| -|`?`|`??`|Matches zero or one time.| -|`{` *n* `}`|`{` *n* `}?`|Matches exactly *n* times.| -|`{` *n* `,}`|`{` *n* `,}?`|Matches at least *n* times.| -|`{` *n* `,` *m* `}`|`{` *n* `,` *m* `}?`|Matches from *n* to *m* times.| - - The quantities `n` and `m` are integer constants. Ordinarily, quantifiers are greedy. They cause the regular expression engine to match as many occurrences of particular patterns as possible. Appending the `?` character to a quantifier makes it lazy. It causes the regular expression engine to match as few occurrences as possible. For a complete description of the difference between greedy and lazy quantifiers, see the section [Greedy and Lazy Quantifiers](#Greedy) later in this article. - + +|Greedy quantifier|Lazy quantifier|Description| +|-----------------------|---------------------|-----------------| +|`*`|`*?`|Matches zero or more times.| +|`+`|`+?`|Matches one or more times.| +|`?`|`??`|Matches zero or one time.| +|`{` *n* `}`|`{` *n* `}?`|Matches exactly *n* times.| +|`{` *n* `,}`|`{` *n* `,}?`|Matches at least *n* times.| +|`{` *n* `,` *m* `}`|`{` *n* `,` *m* `}?`|Matches from *n* to *m* times.| + + The quantities `n` and `m` are integer constants. Ordinarily, quantifiers are greedy. They cause the regular expression engine to match as many occurrences of particular patterns as possible. Appending the `?` character to a quantifier makes it lazy. It causes the regular expression engine to match as few occurrences as possible. For a complete description of the difference between greedy and lazy quantifiers, see the section [Greedy and Lazy Quantifiers](#Greedy) later in this article. + > [!IMPORTANT] -> Nesting quantifiers, such as the regular expression pattern `(a*)*`, can increase the number of comparisons that the regular expression engine must perform. The number of comparisons can increase as an exponential function of the number of characters in the input string. For more information about this behavior and its workarounds, see [Backtracking](backtracking-in-regular-expressions.md). - -## Regular Expression Quantifiers +> Nesting quantifiers, such as the regular expression pattern `(a*)*`, can increase the number of comparisons that the regular expression engine must perform. The number of comparisons can increase as an exponential function of the number of characters in the input string. For more information about this behavior and its workarounds, see [Backtracking](backtracking-in-regular-expressions.md). + +## Regular Expression Quantifiers The following sections list the quantifiers supported by .NET regular expressions: - + > [!NOTE] -> If the *, +, ?, {, and } characters are encountered in a regular expression pattern, the regular expression engine interprets them as quantifiers or part of quantifier constructs unless they are included in a [character class](character-classes-in-regular-expressions.md). To interpret these as literal characters outside a character class, you must escape them by preceding them with a backslash. For example, the string `\*` in a regular expression pattern is interpreted as a literal asterisk ("\*") character. - -### Match Zero or More Times: * - - The `*` quantifier matches the preceding element zero or more times. It's equivalent to the `{0,}` quantifier. `*` is a greedy quantifier whose lazy equivalent is `*?`. - - The following example illustrates this regular expression. Five of the nine digit-groups in the input string match the pattern and four (`95`, `929`, `9219`, and `9919`) don't. - +> If the *, +, ?, {, and } characters are encountered in a regular expression pattern, the regular expression engine interprets them as quantifiers or part of quantifier constructs unless they are included in a [character class](character-classes-in-regular-expressions.md). To interpret these as literal characters outside a character class, you must escape them by preceding them with a backslash. For example, the string `\*` in a regular expression pattern is interpreted as a literal asterisk ("\*") character. + +### Match Zero or More Times: * + + The `*` quantifier matches the preceding element zero or more times. It's equivalent to the `{0,}` quantifier. `*` is a greedy quantifier whose lazy equivalent is `*?`. + + The following example illustrates this regular expression. Five of the nine digit-groups in the input string match the pattern and four (`95`, `929`, `9219`, and `9919`) don't. + [!code-csharp[RegularExpressions.Quantifiers#1](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers/cs/Quantifiers1.cs#1)] - [!code-vb[RegularExpressions.Quantifiers#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#1)] - - The regular expression pattern is defined as shown in the following table: - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Specifies that the match must start at a word boundary.| -|`91*`|Matches a `9` followed by zero or more `1` characters.| -|`9*`|Matches zero or more `9` characters.| -|`\b`|Specifies that the match must end at a word boundary.| - -### Match One or More Times: + - - The `+` quantifier matches the preceding element one or more times. It's equivalent to `{1,}`. `+` is a greedy quantifier whose lazy equivalent is `+?`. - - For example, the regular expression `\ban+\w*?\b` tries to match entire words that begin with the letter `a` followed by one or more instances of the letter `n`. The following example illustrates this regular expression. The regular expression matches the words `an`, `annual`, `announcement`, and `antique`, and correctly fails to match `autumn` and `all`. - + [!code-vb[RegularExpressions.Quantifiers#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#1)] + + The regular expression pattern is defined as shown in the following table: + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Specifies that the match must start at a word boundary.| +|`91*`|Matches a `9` followed by zero or more `1` characters.| +|`9*`|Matches zero or more `9` characters.| +|`\b`|Specifies that the match must end at a word boundary.| + +### Match One or More Times: + + + The `+` quantifier matches the preceding element one or more times. It's equivalent to `{1,}`. `+` is a greedy quantifier whose lazy equivalent is `+?`. + + For example, the regular expression `\ban+\w*?\b` tries to match entire words that begin with the letter `a` followed by one or more instances of the letter `n`. The following example illustrates this regular expression. The regular expression matches the words `an`, `annual`, `announcement`, and `antique`, and correctly fails to match `autumn` and `all`. + [!code-csharp[RegularExpressions.Quantifiers#2](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers/cs/Quantifiers1.cs#2)] - [!code-vb[RegularExpressions.Quantifiers#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#2)] - - The regular expression pattern is defined as shown in the following table: - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Start at a word boundary.| -|`an+`|Matches an `a` followed by one or more `n` characters.| -|`\w*?`|Matches a word character zero or more times but as few times as possible.| -|`\b`|End at a word boundary.| - -### Match Zero or One Time: ? - - The `?` quantifier matches the preceding element zero or one time. It's equivalent to `{0,1}`. `?` is a greedy quantifier whose lazy equivalent is `??`. - + [!code-vb[RegularExpressions.Quantifiers#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#2)] + + The regular expression pattern is defined as shown in the following table: + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Start at a word boundary.| +|`an+`|Matches an `a` followed by one or more `n` characters.| +|`\w*?`|Matches a word character zero or more times but as few times as possible.| +|`\b`|End at a word boundary.| + +### Match Zero or One Time: ? + + The `?` quantifier matches the preceding element zero or one time. It's equivalent to `{0,1}`. `?` is a greedy quantifier whose lazy equivalent is `??`. + For example, the regular expression `\ban?\b` tries to match entire words that begin with the letter `a` followed by zero or one instance of the letter `n`. In other words, it tries to match the words `a` and `an`. The following example illustrates this regular expression: - + [!code-csharp[RegularExpressions.Quantifiers#3](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers/cs/Quantifiers1.cs#3)] - [!code-vb[RegularExpressions.Quantifiers#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#3)] - - The regular expression pattern is defined as shown in the following table: - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Start at a word boundary.| -|`an?`|Matches an `a` followed by zero or one `n` character.| -|`\b`|End at a word boundary.| - -### Match Exactly n Times: {n} - - The `{`*n*`}` quantifier matches the preceding element exactly *n* times, where *n* is any integer. `{`*n*`}` is a greedy quantifier whose lazy equivalent is `{`*n*`}?`. - + [!code-vb[RegularExpressions.Quantifiers#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#3)] + + The regular expression pattern is defined as shown in the following table: + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Start at a word boundary.| +|`an?`|Matches an `a` followed by zero or one `n` character.| +|`\b`|End at a word boundary.| + +### Match Exactly n Times: {n} + + The `{`*n*`}` quantifier matches the preceding element exactly *n* times, where *n* is any integer. `{`*n*`}` is a greedy quantifier whose lazy equivalent is `{`*n*`}?`. + For example, the regular expression `\b\d+\,\d{3}\b` tries to match a word boundary followed by one or more decimal digits, followed by a comma, and then three decimal digits followed by a word boundary. The following example illustrates this regular expression: - + [!code-csharp[RegularExpressions.Quantifiers#4](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers/cs/Quantifiers1.cs#4)] - [!code-vb[RegularExpressions.Quantifiers#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#4)] - + [!code-vb[RegularExpressions.Quantifiers#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#4)] + The regular expression pattern is defined as shown in the following table: - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Start at a word boundary.| -|`\d+`|Matches one or more decimal digits.| -|`\,`|Matches a comma character.| -|`\d{3}`|Matches three decimal digits.| -|`\b`|End at a word boundary.| - -### Match at Least n Times: {n,} - - The `{`*n*`,}` quantifier matches the preceding element at least *n* times, where *n* is any integer. `{`*n*`,}` is a greedy quantifier whose lazy equivalent is `{`*n*`,}?`. - - For example, the regular expression `\b\d{2,}\b\D+` tries to match a word boundary followed by at least two digits followed by a word boundary and one or more non-digit characters. The following example illustrates this regular expression. The regular expression fails to match the phrase `"7 days"` because it contains just one decimal digit, but it successfully matches the phrases `"10 weeks"` and `"300 years"`. - + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Start at a word boundary.| +|`\d+`|Matches one or more decimal digits.| +|`\,`|Matches a comma character.| +|`\d{3}`|Matches three decimal digits.| +|`\b`|End at a word boundary.| + +### Match at Least n Times: {n,} + + The `{`*n*`,}` quantifier matches the preceding element at least *n* times, where *n* is any integer. `{`*n*`,}` is a greedy quantifier whose lazy equivalent is `{`*n*`,}?`. + + For example, the regular expression `\b\d{2,}\b\D+` tries to match a word boundary followed by at least two digits followed by a word boundary and one or more non-digit characters. The following example illustrates this regular expression. The regular expression fails to match the phrase `"7 days"` because it contains just one decimal digit, but it successfully matches the phrases `"10 weeks"` and `"300 years"`. + [!code-csharp[RegularExpressions.Quantifiers#5](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers/cs/Quantifiers1.cs#5)] - [!code-vb[RegularExpressions.Quantifiers#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#5)] - + [!code-vb[RegularExpressions.Quantifiers#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#5)] + The regular expression pattern is defined as shown in the following table: - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Start at a word boundary.| -|`\d{2,}`|Matches at least two decimal digits.| -|`\b`|Matches a word boundary.| -|`\D+`|Matches at least one non-decimal digit.| - -### Match Between n and m Times: {n,m} - - The `{`*n*`,`*m*`}` quantifier matches the preceding element at least *n* times, but no more than *m* times, where *n* and *m* are integers. `{`*n*`,`*m*`}` is a greedy quantifier whose lazy equivalent is `{`*n*`,`*m*`}?`. - - In the following example, the regular expression `(00\s){2,4}` tries to match between two and four occurrences of two zero digits followed by a space. The final portion of the input string includes this pattern five times rather than the maximum of four. However, only the initial portion of this substring (up to the space and the fifth pair of zeros) matches the regular expression pattern. - + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Start at a word boundary.| +|`\d{2,}`|Matches at least two decimal digits.| +|`\b`|Matches a word boundary.| +|`\D+`|Matches at least one non-decimal digit.| + +### Match Between n and m Times: {n,m} + + The `{`*n*`,`*m*`}` quantifier matches the preceding element at least *n* times, but no more than *m* times, where *n* and *m* are integers. `{`*n*`,`*m*`}` is a greedy quantifier whose lazy equivalent is `{`*n*`,`*m*`}?`. + + In the following example, the regular expression `(00\s){2,4}` tries to match between two and four occurrences of two zero digits followed by a space. The final portion of the input string includes this pattern five times rather than the maximum of four. However, only the initial portion of this substring (up to the space and the fifth pair of zeros) matches the regular expression pattern. + [!code-csharp[RegularExpressions.Quantifiers#6](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers/cs/Quantifiers1.cs#6)] - [!code-vb[RegularExpressions.Quantifiers#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#6)] - -### Match Zero or More Times (Lazy Match): *? - - The `*?` quantifier matches the preceding element zero or more times but as few times as possible. It's the lazy counterpart of the greedy quantifier `*`. - - In the following example, the regular expression `\b\w*?oo\w*?\b` matches all words that contain the string `oo`. - + [!code-vb[RegularExpressions.Quantifiers#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#6)] + +### Match Zero or More Times (Lazy Match): *? + + The `*?` quantifier matches the preceding element zero or more times but as few times as possible. It's the lazy counterpart of the greedy quantifier `*`. + + In the following example, the regular expression `\b\w*?oo\w*?\b` matches all words that contain the string `oo`. + [!code-csharp[RegularExpressions.Quantifiers#7](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers/cs/Quantifiers1.cs#7)] - [!code-vb[RegularExpressions.Quantifiers#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#7)] - - The regular expression pattern is defined as shown in the following table: - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Start at a word boundary.| -|`\w*?`|Matches zero or more word characters but as few characters as possible.| -|`oo`|Matches the string `oo`.| -|`\w*?`|Matches zero or more word characters but as few characters as possible.| -|`\b`|End on a word boundary.| - -### Match One or More Times (Lazy Match): +? - - The `+?` quantifier matches the preceding element one or more times but as few times as possible. It's the lazy counterpart of the greedy quantifier `+`. - - For example, the regular expression `\b\w+?\b` matches one or more characters separated by word boundaries. The following example illustrates this regular expression: - + [!code-vb[RegularExpressions.Quantifiers#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#7)] + + The regular expression pattern is defined as shown in the following table: + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Start at a word boundary.| +|`\w*?`|Matches zero or more word characters but as few characters as possible.| +|`oo`|Matches the string `oo`.| +|`\w*?`|Matches zero or more word characters but as few characters as possible.| +|`\b`|End on a word boundary.| + +### Match One or More Times (Lazy Match): +? + + The `+?` quantifier matches the preceding element one or more times but as few times as possible. It's the lazy counterpart of the greedy quantifier `+`. + + For example, the regular expression `\b\w+?\b` matches one or more characters separated by word boundaries. The following example illustrates this regular expression: + [!code-csharp[RegularExpressions.Quantifiers#8](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers/cs/Quantifiers1.cs#8)] - [!code-vb[RegularExpressions.Quantifiers#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#8)] - -### Match Zero or One Time (Lazy Match): ?? - - The `??` quantifier matches the preceding element zero or one time but as few times as possible. It's the lazy counterpart of the greedy quantifier `?`. - - For example, the regular expression `^\s*(System.)??Console.Write(Line)??\(??` attempts to match the strings `Console.Write` or `Console.WriteLine`. The string can also include `System.` before `Console`, and it can be followed by an opening parenthesis. The string must be at the beginning of a line, although it can be preceded by white space. The following example illustrates this regular expression: - + [!code-vb[RegularExpressions.Quantifiers#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#8)] + +### Match Zero or One Time (Lazy Match): ?? + + The `??` quantifier matches the preceding element zero or one time but as few times as possible. It's the lazy counterpart of the greedy quantifier `?`. + + For example, the regular expression `^\s*(System.)??Console.Write(Line)??\(??` attempts to match the strings `Console.Write` or `Console.WriteLine`. The string can also include `System.` before `Console`, and it can be followed by an opening parenthesis. The string must be at the beginning of a line, although it can be preceded by white space. The following example illustrates this regular expression: + [!code-csharp[RegularExpressions.Quantifiers#9](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers/cs/Quantifiers1.cs#9)] - [!code-vb[RegularExpressions.Quantifiers#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#9)] - - The regular expression pattern is defined as shown in the following table: - -|Pattern|Description| -|-------------|-----------------| -|`^`|Matches the start of the input stream.| -|`\s*`|Matches zero or more white-space characters.| -|`(System.)??`|Matches zero or one occurrence of the string `System.`.| -|`Console.Write`|Matches the string `Console.Write`.| -|`(Line)??`|Matches zero or one occurrence of the string `Line`.| -|`\(??`|Matches zero or one occurrence of the opening parenthesis.| - -### Match Exactly n Times (Lazy Match): {n}? - - The `{`*n*`}?` quantifier matches the preceding element exactly `n` times, where *n* is any integer. It's the lazy counterpart of the greedy quantifier `{`*n*`}`. - - In the following example, the regular expression `\b(\w{3,}?\.){2}?\w{3,}?\b` is used to identify a website address. The expression matches `www.microsoft.com` and `msdn.microsoft.com` but doesn't match `mywebsite` or `mycompany.com`. - + [!code-vb[RegularExpressions.Quantifiers#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#9)] + + The regular expression pattern is defined as shown in the following table: + +|Pattern|Description| +|-------------|-----------------| +|`^`|Matches the start of the input stream.| +|`\s*`|Matches zero or more white-space characters.| +|`(System.)??`|Matches zero or one occurrence of the string `System.`.| +|`Console.Write`|Matches the string `Console.Write`.| +|`(Line)??`|Matches zero or one occurrence of the string `Line`.| +|`\(??`|Matches zero or one occurrence of the opening parenthesis.| + +### Match Exactly n Times (Lazy Match): {n}? + + The `{`*n*`}?` quantifier matches the preceding element exactly `n` times, where *n* is any integer. It's the lazy counterpart of the greedy quantifier `{`*n*`}`. + + In the following example, the regular expression `\b(\w{3,}?\.){2}?\w{3,}?\b` is used to identify a website address. The expression matches `www.microsoft.com` and `msdn.microsoft.com` but doesn't match `mywebsite` or `mycompany.com`. + [!code-csharp[RegularExpressions.Quantifiers#10](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers/cs/Quantifiers1.cs#10)] - [!code-vb[RegularExpressions.Quantifiers#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#10)] - - The regular expression pattern is defined as shown in the following table: - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Start at a word boundary.| -|`(\w{3,}?\.)`|Matches at least three word-characters but as few characters as possible, followed by a dot or period character. This pattern is the first capturing group.| -|`(\w{3,}?\.){2}?`|Matches the pattern in the first group two times but as few times as possible.| -|`\b`|End the match on a word boundary.| - -### Match at Least n Times (Lazy Match): {n,}? - - The `{`*n*`,}?` quantifier matches the preceding element at least `n` times, where *n* is any integer but as few times as possible. It's the lazy counterpart of the greedy quantifier `{`*n*`,}`. - - See the example for the `{`*n*`}?` quantifier in the previous section for an illustration. The regular expression in that example uses the `{`*n*`,}` quantifier to match a string that has at least three characters followed by a period. - -### Match Between n and m Times (Lazy Match): {n,m}? - - The `{`*n*`,`*m*`}?` quantifier matches the preceding element between `n` and `m` times, where *n* and *m* are integers but as few times as possible. It's the lazy counterpart of the greedy quantifier `{`*n*`,`*m*`}`. - - In the following example, the regular expression `\b[A-Z](\w*?\s*?){1,10}[.!?]` matches sentences that contain between 1 and 10 words. It matches all the sentences in the input string except for one sentence that contains 18 words. - + [!code-vb[RegularExpressions.Quantifiers#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#10)] + + The regular expression pattern is defined as shown in the following table: + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Start at a word boundary.| +|`(\w{3,}?\.)`|Matches at least three word-characters but as few characters as possible, followed by a dot or period character. This pattern is the first capturing group.| +|`(\w{3,}?\.){2}?`|Matches the pattern in the first group two times but as few times as possible.| +|`\b`|End the match on a word boundary.| + +### Match at Least n Times (Lazy Match): {n,}? + + The `{`*n*`,}?` quantifier matches the preceding element at least `n` times, where *n* is any integer but as few times as possible. It's the lazy counterpart of the greedy quantifier `{`*n*`,}`. + + See the example for the `{`*n*`}?` quantifier in the previous section for an illustration. The regular expression in that example uses the `{`*n*`,}` quantifier to match a string that has at least three characters followed by a period. + +### Match Between n and m Times (Lazy Match): {n,m}? + + The `{`*n*`,`*m*`}?` quantifier matches the preceding element between `n` and `m` times, where *n* and *m* are integers but as few times as possible. It's the lazy counterpart of the greedy quantifier `{`*n*`,`*m*`}`. + + In the following example, the regular expression `\b[A-Z](\w*?\s*?){1,10}[.!?]` matches sentences that contain between 1 and 10 words. It matches all the sentences in the input string except for one sentence that contains 18 words. + [!code-csharp[RegularExpressions.Quantifiers#12](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers/cs/Quantifiers1.cs#12)] - [!code-vb[RegularExpressions.Quantifiers#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#12)] - - The regular expression pattern is defined as shown in the following table: - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Start at a word boundary.| -|`[A-Z]`|Matches an uppercase character from A to Z.| -|`(\w*?\s*?)`|Matches zero or more word characters, followed by one or more white-space characters but as few times as possible. This pattern is the first capturing group.| -|`{1,10}`|Matches the previous pattern between 1 and 10 times.| -|`[.!?]`|Matches any one of the punctuation characters `.`, `!`, or `?`.| - + [!code-vb[RegularExpressions.Quantifiers#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers/vb/Quantifiers1.vb#12)] + + The regular expression pattern is defined as shown in the following table: + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Start at a word boundary.| +|`[A-Z]`|Matches an uppercase character from A to Z.| +|`(\w*?\s*?)`|Matches zero or more word characters, followed by one or more white-space characters but as few times as possible. This pattern is the first capturing group.| +|`{1,10}`|Matches the previous pattern between 1 and 10 times.| +|`[.!?]`|Matches any one of the punctuation characters `.`, `!`, or `?`.| + -## Greedy and Lazy Quantifiers - - Some quantifiers have two versions: - -- A greedy version. - - A greedy quantifier tries to match an element as many times as possible. - -- A non-greedy (or lazy) version. - - A non-greedy quantifier tries to match an element as few times as possible. You can turn a greedy quantifier into a lazy quantifier by adding a `?`. - +## Greedy and Lazy Quantifiers + + Some quantifiers have two versions: + +- A greedy version. + + A greedy quantifier tries to match an element as many times as possible. + +- A non-greedy (or lazy) version. + + A non-greedy quantifier tries to match an element as few times as possible. You can turn a greedy quantifier into a lazy quantifier by adding a `?`. + Consider a regular expression that's intended to extract the last four digits from a string of numbers, such as a credit card number. The version of the regular expression that uses the `*` greedy quantifier is `\b.*([0-9]{4})\b`. However, if a string contains two numbers, this regular expression matches the last four digits of the second number only, as the following example shows: - + [!code-csharp[RegularExpressions.Quantifiers.Greedy#1](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers.Greedy/cs/Greedy.cs#1)] - [!code-vb[RegularExpressions.Quantifiers.Greedy#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers.Greedy/vb/Greedy.vb#1)] - - The regular expression fails to match the first number because the `*` quantifier tries to match the previous element as many times as possible in the entire string, and so it finds its match at the end of the string. - + [!code-vb[RegularExpressions.Quantifiers.Greedy#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers.Greedy/vb/Greedy.vb#1)] + + The regular expression fails to match the first number because the `*` quantifier tries to match the previous element as many times as possible in the entire string, and so it finds its match at the end of the string. + This behavior isn't the desired one. Instead, you can use the `*?` lazy quantifier to extract digits from both numbers, as the following example shows: - + [!code-csharp[RegularExpressions.Quantifiers.Greedy#2](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Quantifiers.Greedy/cs/Greedy.cs#2)] - [!code-vb[RegularExpressions.Quantifiers.Greedy#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers.Greedy/vb/Greedy.vb#2)] - - In most cases, regular expressions with greedy and lazy quantifiers return the same matches. They most commonly return different results when they're used with the wildcard (`.`) metacharacter, which matches any character. - -## Quantifiers and Empty Matches - - The quantifiers `*`, `+`, and `{`*n*`,`*m*`}` and their lazy counterparts never repeat after an empty match when the minimum number of captures has been found. This rule prevents quantifiers from entering infinite loops on empty subexpression matches when the maximum number of possible group captures is infinite or near infinite. - - For example, the following code shows the result of a call to the method with the regular expression pattern `(a?)*`, which matches zero or one `a` character zero or more times. The single capturing group captures each `a` and , but there's no second empty match because the first empty match causes the quantifier to stop repeating. - + [!code-vb[RegularExpressions.Quantifiers.Greedy#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Quantifiers.Greedy/vb/Greedy.vb#2)] + + In most cases, regular expressions with greedy and lazy quantifiers return the same matches. They most commonly return different results when they're used with the wildcard (`.`) metacharacter, which matches any character. + +## Quantifiers and Empty Matches + + The quantifiers `*`, `+`, and `{`*n*`,`*m*`}` and their lazy counterparts never repeat after an empty match when the minimum number of captures has been found. This rule prevents quantifiers from entering infinite loops on empty subexpression matches when the maximum number of possible group captures is infinite or near infinite. + + For example, the following code shows the result of a call to the method with the regular expression pattern `(a?)*`, which matches zero or one `a` character zero or more times. The single capturing group captures each `a` and , but there's no second empty match because the first empty match causes the quantifier to stop repeating. + [!code-csharp[RegularExpressions.Quantifiers.EmptyMatch#1](../../../samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.quantifiers.emptymatch/cs/emptymatch1.cs#1)] - [!code-vb[RegularExpressions.Quantifiers.EmptyMatch#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.quantifiers.emptymatch/vb/emptymatch1.vb#1)] - - To see the practical difference between a capturing group that defines a minimum and a maximum number of captures and one that defines a fixed number of captures, consider the regular expression patterns `(a\1|(?(1)\1)){0,2}` and `(a\1|(?(1)\1)){2}`. Both regular expressions consist of a single capturing group, which is defined in the following table: - -|Pattern|Description| -|-------------|-----------------| -|`(a\1`|Either matches `a` along with the value of the first captured group …| -||(?(1)|… or tests whether the first captured group has been defined. The `(?(1)` construct doesn't define a capturing group.| -|`\1))`|If the first captured group exists, match its value. If the group doesn't exist, the group will match .| - - The first regular expression tries to match this pattern between zero and two times; the second, exactly two times. Because the first pattern reaches its minimum number of captures with its first capture of , it never repeats to try to match `a\1`. The `{0,2}` quantifier allows only empty matches in the last iteration. In contrast, the second regular expression does match `a` because it evaluates `a\1` a second time. The minimum number of iterations, 2, forces the engine to repeat after an empty match. - + [!code-vb[RegularExpressions.Quantifiers.EmptyMatch#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.quantifiers.emptymatch/vb/emptymatch1.vb#1)] + + To see the practical difference between a capturing group that defines a minimum and a maximum number of captures and one that defines a fixed number of captures, consider the regular expression patterns `(a\1|(?(1)\1)){0,2}` and `(a\1|(?(1)\1)){2}`. Both regular expressions consist of a single capturing group, which is defined in the following table: + +|Pattern|Description| +|-------------|-----------------| +|`(a\1`|Either matches `a` along with the value of the first captured group …| +||(?(1)|… or tests whether the first captured group has been defined. The `(?(1)` construct doesn't define a capturing group.| +|`\1))`|If the first captured group exists, match its value. If the group doesn't exist, the group will match .| + + The first regular expression tries to match this pattern between zero and two times; the second, exactly two times. Because the first pattern reaches its minimum number of captures with its first capture of , it never repeats to try to match `a\1`. The `{0,2}` quantifier allows only empty matches in the last iteration. In contrast, the second regular expression does match `a` because it evaluates `a\1` a second time. The minimum number of iterations, 2, forces the engine to repeat after an empty match. + [!code-csharp[RegularExpressions.Quantifiers.EmptyMatch#2](../../../samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.quantifiers.emptymatch/cs/emptymatch4.cs#2)] - [!code-vb[RegularExpressions.Quantifiers.EmptyMatch#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.quantifiers.emptymatch/vb/emptymatch4.vb#2)] - + [!code-vb[RegularExpressions.Quantifiers.EmptyMatch#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.quantifiers.emptymatch/vb/emptymatch4.vb#2)] + ## See also - [Regular Expression Language - Quick Reference](regular-expression-language-quick-reference.md) diff --git a/docs/standard/base-types/regular-expression-example-changing-date-formats.md b/docs/standard/base-types/regular-expression-example-changing-date-formats.md index 906b91c6b1ef9..d896fa8053791 100644 --- a/docs/standard/base-types/regular-expression-example-changing-date-formats.md +++ b/docs/standard/base-types/regular-expression-example-changing-date-formats.md @@ -2,10 +2,10 @@ description: "Learn more about: Regular Expression Example: Changing Date Formats" title: "Regular Expression Example: Changing Date Formats" ms.date: "06/30/2020" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "searching with regular expressions, examples" - "parsing text with regular expressions, examples" - "regular expressions, examples" @@ -16,44 +16,44 @@ ms.assetid: 5fcc75a5-09d7-45ae-a4c0-9ad6085ac83d --- # Regular Expression Example: Changing Date Formats -The following code example uses the method to replace dates that have the form *mm*/*dd*/*yy* with dates that have the form *dd*-*mm*-*yy*. +The following code example uses the method to replace dates that have the form *mm*/*dd*/*yy* with dates that have the form *dd*-*mm*-*yy*. [!INCLUDE [regex](../../../includes/regex.md)] -## Example +## Example [!code-csharp[RegularExpressions.Examples.ChangeDateFormats#1](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Examples.ChangeDateFormats/cs/Example_ChangeDateFormats1.cs#1)] - [!code-vb[RegularExpressions.Examples.ChangeDateFormats#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.ChangeDateFormats/vb/Example_ChangeDateFormats1.vb#1)] - - The following code shows how the `MDYToDMY` method can be called in an application. - + [!code-vb[RegularExpressions.Examples.ChangeDateFormats#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.ChangeDateFormats/vb/Example_ChangeDateFormats1.vb#1)] + + The following code shows how the `MDYToDMY` method can be called in an application. + [!code-csharp[RegularExpressions.Examples.ChangeDateFormats#2](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Examples.ChangeDateFormats/cs/Example_ChangeDateFormats1.cs#2)] - [!code-vb[RegularExpressions.Examples.ChangeDateFormats#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.ChangeDateFormats/vb/Example_ChangeDateFormats1.vb#2)] - -## Comments - - The regular expression pattern `\b(?\d{1,2})/(?\d{1,2})/(?\d{2,4})\b` is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`(?\d{1,2})`|Match one or two decimal digits. This is the `month` captured group.| -|`/`|Match the slash mark.| -|`(?\d{1,2})`|Match one or two decimal digits. This is the `day` captured group.| -|`/`|Match the slash mark.| -|`(?\d{2,4})`|Match from two to four decimal digits. This is the `year` captured group.| -|`\b`|End the match at a word boundary.| - - The pattern `${day}-${month}-${year}` defines the replacement string as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`$(day)`|Add the string captured by the `day` capturing group.| -|`-`|Add a hyphen.| -|`$(month)`|Add the string captured by the `month` capturing group.| -|`-`|Add a hyphen.| -|`$(year)`|Add the string captured by the `year` capturing group.| - + [!code-vb[RegularExpressions.Examples.ChangeDateFormats#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.ChangeDateFormats/vb/Example_ChangeDateFormats1.vb#2)] + +## Comments + + The regular expression pattern `\b(?\d{1,2})/(?\d{1,2})/(?\d{2,4})\b` is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`(?\d{1,2})`|Match one or two decimal digits. This is the `month` captured group.| +|`/`|Match the slash mark.| +|`(?\d{1,2})`|Match one or two decimal digits. This is the `day` captured group.| +|`/`|Match the slash mark.| +|`(?\d{2,4})`|Match from two to four decimal digits. This is the `year` captured group.| +|`\b`|End the match at a word boundary.| + + The pattern `${day}-${month}-${year}` defines the replacement string as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`$(day)`|Add the string captured by the `day` capturing group.| +|`-`|Add a hyphen.| +|`$(month)`|Add the string captured by the `month` capturing group.| +|`-`|Add a hyphen.| +|`$(year)`|Add the string captured by the `year` capturing group.| + ## See also - [.NET Regular Expressions](regular-expressions.md) diff --git a/docs/standard/base-types/regular-expression-example-scanning-for-hrefs.md b/docs/standard/base-types/regular-expression-example-scanning-for-hrefs.md index e3a47bb9b1981..5d9f61cc6fc36 100644 --- a/docs/standard/base-types/regular-expression-example-scanning-for-hrefs.md +++ b/docs/standard/base-types/regular-expression-example-scanning-for-hrefs.md @@ -2,10 +2,10 @@ title: "Regular Expression Example: Scanning for HREFs" description: See an example of regular expressions in .NET. The example searches an input string and displays all href attribute values and their locations. ms.date: "07/14/2021" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "searching with regular expressions, examples" - "parsing text with regular expressions, examples" - "regular expressions, examples" @@ -48,13 +48,13 @@ The regular expression pattern `href\s*=\s*(?:["'](?<1>[^"']*)["']|(?<1>[^>\s]+) ## Match result class -The results of a search are stored in the class, which provides access to all the substrings extracted by the search. It also remembers the string being searched and the regular expression being used, so it can call the method to perform another search starting where the last one ended. +The results of a search are stored in the class, which provides access to all the substrings extracted by the search. It also remembers the string being searched and the regular expression being used, so it can call the method to perform another search starting where the last one ended. ## Explicitly named captures In traditional regular expressions, capturing parentheses are automatically numbered sequentially. This leads to two problems. First, if a regular expression is modified by inserting or removing a set of parentheses, all code that refers to the numbered captures must be rewritten to reflect the new numbering. Second, because different sets of parentheses often are used to provide two alternative expressions for an acceptable match, it might be difficult to determine which of the two expressions actually returned a result. -To address these problems, the class supports the syntax `(?…)` for capturing a match into a specified slot (the slot can be named using a string or an integer; integers can be recalled more quickly). Thus, alternative matches for the same string all can be directed to the same place. In case of a conflict, the last match dropped into a slot is the successful match. (However, a complete list of multiple matches for a single slot is available. See the collection for details.) +To address these problems, the class supports the syntax `(?…)` for capturing a match into a specified slot (the slot can be named using a string or an integer; integers can be recalled more quickly). Thus, alternative matches for the same string all can be directed to the same place. In case of a conflict, the last match dropped into a slot is the successful match. (However, a complete list of multiple matches for a single slot is available. See the collection for details.) ## See also diff --git a/docs/standard/base-types/regular-expression-language-quick-reference.md b/docs/standard/base-types/regular-expression-language-quick-reference.md index 63c018117af1f..76a0c63cc828f 100644 --- a/docs/standard/base-types/regular-expression-language-quick-reference.md +++ b/docs/standard/base-types/regular-expression-language-quick-reference.md @@ -101,7 +101,7 @@ Grouping constructs delineate subexpressions of a regular expression and typical ### Lookarounds at a glance When the regular expression engine hits a **lookaround expression**, it takes a substring reaching from the current position to the start (lookbehind) or end (lookahead) of the original string, and then runs - on that substring using the lookaround pattern. Success of this subexpression's result is then determined by whether it's a positive or negative assertion. + on that substring using the lookaround pattern. Success of this subexpression's result is then determined by whether it's a positive or negative assertion. | Lookaround | Name | Function | |--------------|--------------------------|------------------------------------------------------------------------------------------| diff --git a/docs/standard/base-types/regular-expression-options.md b/docs/standard/base-types/regular-expression-options.md index 02eca90d7eeee..025e22f2331ae 100644 --- a/docs/standard/base-types/regular-expression-options.md +++ b/docs/standard/base-types/regular-expression-options.md @@ -89,14 +89,14 @@ The following five regular expression options can be set using the `options` par ## Determine options -You can determine which options were provided to a object when it was instantiated by retrieving the value of the read-only property. +You can determine which options were provided to a object when it was instantiated by retrieving the value of the read-only property. -To test for the presence of any option except , perform an AND operation with the value of the property and the value in which you are interested. Then test whether the result equals that value. The following example tests whether the option has been set. +To test for the presence of any option except , perform an AND operation with the value of the property and the value in which you are interested. Then test whether the result equals that value. The following example tests whether the option has been set. [!code-csharp[Conceptual.Regex.Language.Options#19](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/determine1.cs#19)] [!code-vb[Conceptual.Regex.Language.Options#19](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/determine1.vb#19)] -To test for , determine whether the value of the property is equal to , as the following example illustrates. +To test for , determine whether the value of the property is equal to , as the following example illustrates. [!code-csharp[Conceptual.Regex.Language.Options#20](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/determine1.cs#20)] [!code-vb[Conceptual.Regex.Language.Options#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/determine1.vb#20)] @@ -132,7 +132,7 @@ Because the option, or the `i` inline option, provides case-insensitive matching. By default, the casing conventions of the current culture are used. -The following example defines a regular expression pattern, `\bthe\w*\b`, that matches all words starting with "the". Because the first call to the method uses the default case-sensitive comparison, the output indicates that the string "The" that begins the sentence is not matched. It is matched when the method is called with options set to . +The following example defines a regular expression pattern, `\bthe\w*\b`, that matches all words starting with "the". Because the first call to the method uses the default case-sensitive comparison, the output indicates that the string "The" that begins the sentence is not matched. It is matched when the method is called with options set to . [!code-csharp[Conceptual.Regex.Language.Options#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/case1.cs#1)] [!code-vb[Conceptual.Regex.Language.Options#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/case1.vb#1)] @@ -150,7 +150,7 @@ By default, `$` will be satisfied only at the end of the input string. If you sp In neither case does `$` recognize the carriage return/line feed character combination (`\r\n`). `$` always ignores any carriage return (`\r`). To end your match with either `\r\n` or `\n`, use the subexpression `\r?$` instead of just `$`. Note that this will make the `\r` part of the match. -The following example extracts bowlers' names and scores and adds them to a collection that sorts them in descending order. The method is called twice. In the first method call, the regular expression is `^(\w+)\s(\d+)$` and no options are set. As the output shows, because the regular expression engine cannot match the input pattern along with the beginning and end of the input string, no matches are found. In the second method call, the regular expression is changed to `^(\w+)\s(\d+)\r?$` and the options are set to . As the output shows, the names and scores are successfully matched, and the scores are displayed in descending order. +The following example extracts bowlers' names and scores and adds them to a collection that sorts them in descending order. The method is called twice. In the first method call, the regular expression is `^(\w+)\s(\d+)$` and no options are set. As the output shows, because the regular expression engine cannot match the input pattern along with the beginning and end of the input string, no matches are found. In the second method call, the regular expression is changed to `^(\w+)\s(\d+)\r?$` and the options are set to . As the output shows, the names and scores are successfully matched, and the scores are displayed in descending order. [!code-csharp[Conceptual.Regex.Language.Options#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/multiline1.cs#3)] [!code-vb[Conceptual.Regex.Language.Options#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/multiline1.vb#3)] @@ -197,7 +197,7 @@ is intended only to extract sentences that end with a period, exclamation point, Capturing groups that are not subsequently used can be expensive, because the regular expression engine must populate both the and collection objects. As an alternative, you can use either the option or the `n` inline option to specify that the only valid captures are explicitly named or numbered groups that are designated by the `(?<`*name*`>` *subexpression*`)` construct. -The following example displays information about the matches returned by the `\b\(?((\w+),?\s?)+[\.!?]\)?` regular expression pattern when the method is called with and without the option. As the output from the first method call shows, the regular expression engine fully populates the and collection objects with information about captured substrings. Because the second method is called with `options` set to , it does not capture information on groups. +The following example displays information about the matches returned by the `\b\(?((\w+),?\s?)+[\.!?]\)?` regular expression pattern when the method is called with and without the option. As the output from the first method call shows, the regular expression engine fully populates the and collection objects with information about captured substrings. Because the second method is called with `options` set to , it does not capture information on groups. [!code-csharp[Conceptual.Regex.Language.Options#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/explicit1.cs#9)] [!code-vb[Conceptual.Regex.Language.Options#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/explicit1.vb#9)] @@ -246,7 +246,7 @@ However, this improvement in performance occurs only under the following conditi - A static regular expression is used in multiple calls to regular expression pattern-matching methods. (The performance improvement is possible because regular expressions used in static method calls are cached by the regular expression engine.) > [!NOTE] -> The option is unrelated to the obsolete method, which creates a special-purpose assembly that contains predefined, compiled regular expressions. +> The option is unrelated to the obsolete method, which creates a special-purpose assembly that contains predefined, compiled regular expressions. ## Ignore white space @@ -370,7 +370,7 @@ The behavior of ECMAScript and canonical regular expressions differs in three ar By default, when the regular expression engine performs case-insensitive comparisons, it uses the casing conventions of the current culture to determine equivalent uppercase and lowercase characters. -However, this behavior is undesirable for some types of comparisons, particularly when comparing user input to the names of system resources, such as passwords, files, or URLs. The following example illustrates such a scenario. The code is intended to block access to any resource whose URL is prefaced with **FILE://**. The regular expression attempts a case-insensitive match with the string by using the regular expression `$FILE://`. However, when the current system culture is tr-TR (Turkish-Türkiye), "I" is not the uppercase equivalent of "i". As a result, the call to the method returns `false`, and access to the file is allowed. +However, this behavior is undesirable for some types of comparisons, particularly when comparing user input to the names of system resources, such as passwords, files, or URLs. The following example illustrates such a scenario. The code is intended to block access to any resource whose URL is prefaced with **FILE://**. The regular expression attempts a case-insensitive match with the string by using the regular expression `$FILE://`. However, when the current system culture is tr-TR (Turkish-Türkiye), "I" is not the uppercase equivalent of "i". As a result, the call to the method returns `false`, and access to the file is allowed. [!code-csharp[Conceptual.Regex.Language.Options#14](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/culture1.cs#14)] [!code-vb[Conceptual.Regex.Language.Options#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/culture1.vb#14)] diff --git a/docs/standard/base-types/regular-expressions.md b/docs/standard/base-types/regular-expressions.md index 8bd40d8614c18..745a7449a0418 100644 --- a/docs/standard/base-types/regular-expressions.md +++ b/docs/standard/base-types/regular-expressions.md @@ -4,10 +4,10 @@ description: Use regular expressions to find specific character patterns, valida ms.topic: concept-article ms.date: "03/18/2026" ms.custom: devdivchpfy22 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "pattern-matching with regular expressions, about pattern-matching" - "substrings" - "searching with regular expressions, about regular expressions" @@ -34,33 +34,33 @@ Regular expressions provide a powerful, flexible, and efficient method for proce - Extract, edit, replace, or delete text substrings. - Add extracted strings to a collection in order to generate a report. -For many applications that deal with strings or that parse large blocks of text, regular expressions are an indispensable tool. - +For many applications that deal with strings or that parse large blocks of text, regular expressions are an indispensable tool. + ## How regular expressions work - The centerpiece of text processing with regular expressions is the regular expression engine, which is represented by the object in .NET. At a minimum, processing text using regular expressions requires that the regular expression engine be provided with the following two items of information: - -- The regular expression pattern to identify in the text. - - In .NET, regular expression patterns are defined by a special syntax or language, which is compatible with Perl 5 regular expressions and adds some other features such as right-to-left matching. For more information, see [Regular Expression Language - Quick Reference](regular-expression-language-quick-reference.md). - -- The text to parse for the regular expression pattern. - -The methods of the class let you perform the following operations: - -- Determine whether the regular expression pattern occurs in the input text by calling the method. For an example that uses the method for validating text, see [How to: Verify that Strings Are in Valid Email Format](how-to-verify-that-strings-are-in-valid-email-format.md). - -- Retrieve one or all occurrences of text that matches the regular expression pattern by calling the or method. The former method returns a object that provides information about the matching text. The latter returns a object that contains one object for each match found in the parsed text. - -- Replace text that matches the regular expression pattern by calling the method. For examples that use the method to change date formats and remove invalid characters from a string, see [How to: Strip Invalid Characters from a String](how-to-strip-invalid-characters-from-a-string.md) and [Example: Changing Date Formats](regular-expression-example-changing-date-formats.md). - -For an overview of the regular expression object model, see [The Regular Expression Object Model](the-regular-expression-object-model.md). - -For more information about the regular expression language, see [Regular Expression Language - Quick Reference](regular-expression-language-quick-reference.md) or download and print one of the following brochures: - -- [Quick Reference in Word (.docx) format](https://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.docx) -- [Quick Reference in PDF (.pdf) format](https://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.pdf) - + The centerpiece of text processing with regular expressions is the regular expression engine, which is represented by the object in .NET. At a minimum, processing text using regular expressions requires that the regular expression engine be provided with the following two items of information: + +- The regular expression pattern to identify in the text. + + In .NET, regular expression patterns are defined by a special syntax or language, which is compatible with Perl 5 regular expressions and adds some other features such as right-to-left matching. For more information, see [Regular Expression Language - Quick Reference](regular-expression-language-quick-reference.md). + +- The text to parse for the regular expression pattern. + +The methods of the class let you perform the following operations: + +- Determine whether the regular expression pattern occurs in the input text by calling the method. For an example that uses the method for validating text, see [How to: Verify that Strings Are in Valid Email Format](how-to-verify-that-strings-are-in-valid-email-format.md). + +- Retrieve one or all occurrences of text that matches the regular expression pattern by calling the or method. The former method returns a object that provides information about the matching text. The latter returns a object that contains one object for each match found in the parsed text. + +- Replace text that matches the regular expression pattern by calling the method. For examples that use the method to change date formats and remove invalid characters from a string, see [How to: Strip Invalid Characters from a String](how-to-strip-invalid-characters-from-a-string.md) and [Example: Changing Date Formats](regular-expression-example-changing-date-formats.md). + +For an overview of the regular expression object model, see [The Regular Expression Object Model](the-regular-expression-object-model.md). + +For more information about the regular expression language, see [Regular Expression Language - Quick Reference](regular-expression-language-quick-reference.md) or download and print one of the following brochures: + +- [Quick Reference in Word (.docx) format](https://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.docx) +- [Quick Reference in PDF (.pdf) format](https://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.pdf) + ## Regular expression examples The class includes string search and replacement methods that you can use when you want to locate literal strings in a larger string. Regular expressions are most useful either when you want to locate one of several substrings in a larger string, or when you want to identify patterns in a string, as the following examples illustrate. @@ -70,75 +70,75 @@ The class includes string search and replacement methods th > [!TIP] > The namespace contains many regular expression objects that implement predefined regular expression patterns for parsing strings from HTML, XML, and ASP.NET documents. For example, the class identifies start tags in a string, and the class identifies ASP.NET comments in a string. -### Example 1: Replace substrings +### Example 1: Replace substrings Assume that a mailing list contains names that sometimes include a title (Mr., Mrs., Miss, or Ms.) along with a first and last name. Suppose you don't want to include the titles when you generate envelope labels from the list. In that case, you can use a regular expression to remove the titles, as the following example illustrates: - + [!code-csharp[Conceptual.Regex#2](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex/cs/example1.cs#2)] - [!code-vb[Conceptual.Regex#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex/vb/example1.vb#2)] - - The regular expression pattern `(Mr\.? |Mrs\.? |Miss |Ms\.? )` matches any occurrence of "Mr ", "Mr. ", "Mrs ", "Mrs. ", "Miss ", "Ms ", or "Ms. ". The call to the method replaces the matched string with ; in other words, it removes it from the original string. - -### Example 2: Identify duplicated words + [!code-vb[Conceptual.Regex#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex/vb/example1.vb#2)] + + The regular expression pattern `(Mr\.? |Mrs\.? |Miss |Ms\.? )` matches any occurrence of "Mr ", "Mr. ", "Mrs ", "Mrs. ", "Miss ", "Ms ", or "Ms. ". The call to the method replaces the matched string with ; in other words, it removes it from the original string. + +### Example 2: Identify duplicated words Accidentally duplicating words is a common error that writers make. Use a regular expression to identify duplicated words, as the following example shows: - + [!code-csharp[Conceptual.Regex#3](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex/cs/example2.cs#3)] - [!code-vb[Conceptual.Regex#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex/vb/example2.vb#3)] - - The regular expression pattern `\b(\w+?)\s\1\b` can be interpreted as follows: - + [!code-vb[Conceptual.Regex#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex/vb/example2.vb#3)] + + The regular expression pattern `\b(\w+?)\s\1\b` can be interpreted as follows: + > [!div class="mx-tdCol2BreakAll"] > -> |Pattern|Interpretation| +> |Pattern|Interpretation| > |-|-| -> |`\b`|Start at a word boundary.| -> |`(\w+?)`|Match one or more word characters, but as few characters as possible. Together, they form a group that can be referred to as `\1`.| -> |`\s`|Match a white-space character.| -> |`\1`|Match the substring that's equal to the group named `\1`.| -> |`\b`|Match a word boundary.| - - The method is called with regular expression options set to . Therefore, the match operation is case-insensitive, and the example identifies the substring "This this" as a duplication. - - The input string includes the substring "this? This". However, because of the intervening punctuation mark, it isn't identified as a duplication. - -### Example 3: Dynamically build a culture-sensitive regular expression +> |`\b`|Start at a word boundary.| +> |`(\w+?)`|Match one or more word characters, but as few characters as possible. Together, they form a group that can be referred to as `\1`.| +> |`\s`|Match a white-space character.| +> |`\1`|Match the substring that's equal to the group named `\1`.| +> |`\b`|Match a word boundary.| + + The method is called with regular expression options set to . Therefore, the match operation is case-insensitive, and the example identifies the substring "This this" as a duplication. + + The input string includes the substring "this? This". However, because of the intervening punctuation mark, it isn't identified as a duplication. + +### Example 3: Dynamically build a culture-sensitive regular expression The following example illustrates the power of regular expressions combined with the flexibility that .NET globalization features provide. It uses the object to determine the format of currency values in the en-US culture. It then uses that information to dynamically construct a regular expression that extracts currency values from the text. For each match, it extracts the subgroup that contains the numeric string only, converts it to a value, and calculates a running total. While this example uses the en-US culture, you can apply the same technique with other cultures by constructing the regular expression and parsing logic with the appropriate settings. - + [!code-csharp[Conceptual.Regex#1](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex/cs/example.cs#1)] - [!code-vb[Conceptual.Regex#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex/vb/example.vb#1)] - - The example uses the en-US culture and dynamically builds the regular expression `\$\s*[-+]?([0-9]{0,3}(,[0-9]{3})*(\.[0-9]+)?)`. This regular expression pattern can be interpreted as follows: + [!code-vb[Conceptual.Regex#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex/vb/example.vb#1)] + + The example uses the en-US culture and dynamically builds the regular expression `\$\s*[-+]?([0-9]{0,3}(,[0-9]{3})*(\.[0-9]+)?)`. This regular expression pattern can be interpreted as follows: > [!div class="mx-tdCol2BreakAll"] > -> |Pattern|Interpretation| -> |-|-| -> |`\$`|Look for a single occurrence of the dollar symbol (`$`) in the input string. The regular expression pattern string includes a backslash to indicate that the dollar symbol is to be interpreted literally rather than as a regular expression anchor. The `$` symbol alone would indicate that the regular expression engine should try to begin its match at the end of a string. To ensure that the current culture's currency symbol isn't misinterpreted as a regular expression symbol, the example calls the method to escape the character.| -> |`\s*`|Look for zero or more occurrences of a white-space character.| -> |`[-+]?`|Look for zero or one occurrence of either a positive or negative sign.| -> |`([0-9]{0,3}(,[0-9]{3})*(\.[0-9]+)?)`|The outer parentheses define this expression as a capturing group or a subexpression. If a match is found, information about this part of the matching string can be retrieved from the second object in the object returned by the property. The first element in the collection represents the entire match.| -> |`[0-9]{0,3}`|Look for zero to three occurrences of the decimal digits 0 through 9.| -> |`(,[0-9]{3})*`|Look for zero or more occurrences of a group separator followed by three decimal digits.| -> |`\.`|Look for a single occurrence of the decimal separator.| -> |`[0-9]+`|Look for one or more decimal digits.| -> |`(\.[0-9]+)?`|Look for zero or one occurrence of the decimal separator followed by at least one decimal digit.| - - If each subpattern is found in the input string, the match succeeds, and a object that contains information about the match is added to the object. - -## Related articles - -|Title|Description| -|-----------|-----------------| -|[Regular Expression Language - Quick Reference](regular-expression-language-quick-reference.md)|Provides information on the set of characters, operators, and constructs that you can use to define regular expressions.| -|[The Regular Expression Object Model](the-regular-expression-object-model.md)|Provides information and code examples that illustrate how to use the regular expression classes.| +> |Pattern|Interpretation| +> |-|-| +> |`\$`|Look for a single occurrence of the dollar symbol (`$`) in the input string. The regular expression pattern string includes a backslash to indicate that the dollar symbol is to be interpreted literally rather than as a regular expression anchor. The `$` symbol alone would indicate that the regular expression engine should try to begin its match at the end of a string. To ensure that the current culture's currency symbol isn't misinterpreted as a regular expression symbol, the example calls the method to escape the character.| +> |`\s*`|Look for zero or more occurrences of a white-space character.| +> |`[-+]?`|Look for zero or one occurrence of either a positive or negative sign.| +> |`([0-9]{0,3}(,[0-9]{3})*(\.[0-9]+)?)`|The outer parentheses define this expression as a capturing group or a subexpression. If a match is found, information about this part of the matching string can be retrieved from the second object in the object returned by the property. The first element in the collection represents the entire match.| +> |`[0-9]{0,3}`|Look for zero to three occurrences of the decimal digits 0 through 9.| +> |`(,[0-9]{3})*`|Look for zero or more occurrences of a group separator followed by three decimal digits.| +> |`\.`|Look for a single occurrence of the decimal separator.| +> |`[0-9]+`|Look for one or more decimal digits.| +> |`(\.[0-9]+)?`|Look for zero or one occurrence of the decimal separator followed by at least one decimal digit.| + + If each subpattern is found in the input string, the match succeeds, and a object that contains information about the match is added to the object. + +## Related articles + +|Title|Description| +|-----------|-----------------| +|[Regular Expression Language - Quick Reference](regular-expression-language-quick-reference.md)|Provides information on the set of characters, operators, and constructs that you can use to define regular expressions.| +|[The Regular Expression Object Model](the-regular-expression-object-model.md)|Provides information and code examples that illustrate how to use the regular expression classes.| |[Details of Regular Expression Behavior](details-of-regular-expression-behavior.md)|Provides information about the capabilities and behavior of .NET regular expressions.| |[Use regular expressions in Visual Studio](/visualstudio/ide/using-regular-expressions-in-visual-studio)|| - -## Reference -- -- -- [Regular Expressions - Quick Reference (download in Word format)](https://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.docx) +## Reference + +- +- +- [Regular Expressions - Quick Reference (download in Word format)](https://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.docx) - [Regular Expressions - Quick Reference (download in PDF format)](https://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.pdf) diff --git a/docs/standard/base-types/standard-date-and-time-format-strings.md b/docs/standard/base-types/standard-date-and-time-format-strings.md index 327c047500796..5aa298816b838 100644 --- a/docs/standard/base-types/standard-date-and-time-format-strings.md +++ b/docs/standard/base-types/standard-date-and-time-format-strings.md @@ -78,11 +78,11 @@ In some cases, the standard format string serves as a convenient abbreviation fo |Standard format string|Defined by DateTimeFormatInfo.InvariantInfo property|Custom format string| |----------------------------|----------------------------------------------------------|--------------------------| |"O" or "o"|None|yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffK| -|"R" or "r"||ddd, dd MMM yyyy HH':'mm':'ss 'GMT'| +|"R" or "r"||ddd, dd MMM yyyy HH':'mm':'ss 'GMT'| |"s"||yyyy'-'MM'-'dd'T'HH':'mm':'ss| -|"u"||yyyy'-'MM'-'dd HH':'mm':'ss'Z'| +|"u"||yyyy'-'MM'-'dd HH':'mm':'ss'Z'| -Standard format strings can also be used in parsing operations with the , , , and methods, which require an input string to exactly conform to a particular pattern for the parse operation to succeed. Many standard format strings map to multiple custom format strings, so a date and time value can be represented in a variety of formats and the parse operation will still succeed. You can determine the custom format string or strings that correspond to a standard format string by calling the method. The following example displays the custom format strings that map to the "d" (short date pattern) standard format string. +Standard format strings can also be used in parsing operations with the , , , and methods, which require an input string to exactly conform to a particular pattern for the parse operation to succeed. Many standard format strings map to multiple custom format strings, so a date and time value can be represented in a variety of formats and the parse operation will still succeed. You can determine the custom format string or strings that correspond to a standard format string by calling the method. The following example displays the custom format strings that map to the "d" (short date pattern) standard format string. [!code-csharp[Formatting.DateAndTime.Standard#17](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Standard/cs/stdandparsing1.cs#17)] [!code-vb[Formatting.DateAndTime.Standard#17](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Standard/vb/stdandparsing1.vb#17)] @@ -100,14 +100,14 @@ This group includes the following formats: ### The short date ("d") format specifier -The "d" standard format specifier represents a custom date and time format string that is defined by a specific culture's property. For example, the custom format string that is returned by the property of the invariant culture is "MM/dd/yyyy". +The "d" standard format specifier represents a custom date and time format string that is defined by a specific culture's property. For example, the custom format string that is returned by the property of the invariant culture is "MM/dd/yyyy". The following table lists the object properties that control the formatting of the returned string. |Property|Description| |--------------|-----------------| -||Defines the overall format of the result string.| -||Defines the string that separates the year, month, and day components of a date.| +||Defines the overall format of the result string.| +||Defines the string that separates the year, month, and day components of a date.| The following example uses the "d" format specifier to display a date and time value. @@ -120,15 +120,15 @@ The following example uses the "d" format specifier to display a date and time v ### The long date ("D") format specifier -The "D" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "dddd, dd MMMM yyyy". +The "D" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "dddd, dd MMMM yyyy". The following table lists the properties of the object that control the formatting of the returned string. |Property|Description| |--------------|-----------------| -||Defines the overall format of the result string.| -||Defines the localized day names that can appear in the result string.| -||Defines the localized month names that can appear in the result string.| +||Defines the overall format of the result string.| +||Defines the localized day names that can appear in the result string.| +||Defines the localized month names that can appear in the result string.| The following example uses the "D" format specifier to display a date and time value. @@ -157,17 +157,17 @@ This group includes the following formats: The "f" standard format specifier represents a combination of the long date ("D") and short time ("t") patterns, separated by a space. -The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier returned by the and properties of some cultures may not make use of all properties. +The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier returned by the and properties of some cultures may not make use of all properties. |Property|Description| |--------------|-----------------| -||Defines the format of the date component of the result string.| -||Defines the format of the time component of the result string.| -||Defines the localized day names that can appear in the result string.| -||Defines the localized month names that can appear in the result string.| -||Defines the string that separates the hour, minute, and second components of a time.| -||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| -||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| +||Defines the format of the date component of the result string.| +||Defines the format of the time component of the result string.| +||Defines the localized day names that can appear in the result string.| +||Defines the localized month names that can appear in the result string.| +||Defines the string that separates the hour, minute, and second components of a time.| +||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| +||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| The following example uses the "f" format specifier to display a date and time value. @@ -180,18 +180,18 @@ The following example uses the "f" format specifier to display a date and time v ### The full date long time ("F") format specifier -The "F" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "dddd, dd MMMM yyyy HH:mm:ss". +The "F" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "dddd, dd MMMM yyyy HH:mm:ss". -The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. +The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. |Property|Description| |--------------|-----------------| -||Defines the overall format of the result string.| -||Defines the localized day names that can appear in the result string.| -||Defines the localized month names that can appear in the result string.| -||Defines the string that separates the hour, minute, and second components of a time.| -||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| -||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| +||Defines the overall format of the result string.| +||Defines the localized day names that can appear in the result string.| +||Defines the localized month names that can appear in the result string.| +||Defines the string that separates the hour, minute, and second components of a time.| +||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| +||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| The following example uses the "F" format specifier to display a date and time value. @@ -206,16 +206,16 @@ The following example uses the "F" format specifier to display a date and time v The "g" standard format specifier represents a combination of the short date ("d") and short time ("t") patterns, separated by a space. -The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the and properties of some cultures may not make use of all properties. +The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the and properties of some cultures may not make use of all properties. |Property|Description| |--------------|-----------------| -||Defines the format of the date component of the result string.| -||Defines the format of the time component of the result string.| -||Defines the string that separates the year, month, and day components of a date.| -||Defines the string that separates the hour, minute, and second components of a time.| -||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| -||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| +||Defines the format of the date component of the result string.| +||Defines the format of the time component of the result string.| +||Defines the string that separates the year, month, and day components of a date.| +||Defines the string that separates the hour, minute, and second components of a time.| +||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| +||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| The following example uses the "g" format specifier to display a date and time value. @@ -230,16 +230,16 @@ The following example uses the "g" format specifier to display a date and time v The "G" standard format specifier represents a combination of the short date ("d") and long time ("T") patterns, separated by a space. -The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the and properties of some cultures may not make use of all properties. +The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the and properties of some cultures may not make use of all properties. |Property|Description| |--------------|-----------------| -||Defines the format of the date component of the result string.| -||Defines the format of the time component of the result string.| -||Defines the string that separates the year, month, and day components of a date.| -||Defines the string that separates the hour, minute, and second components of a time.| -||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| -||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| +||Defines the format of the date component of the result string.| +||Defines the format of the time component of the result string.| +||Defines the string that separates the year, month, and day components of a date.| +||Defines the string that separates the hour, minute, and second components of a time.| +||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| +||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| The following example uses the "G" format specifier to display a date and time value. @@ -252,13 +252,13 @@ The following example uses the "G" format specifier to display a date and time v ### The round-trip ("O", "o") format specifier -The "O" or "o" standard format specifier represents a custom date and time format string using a pattern that preserves time zone information and emits a result string that complies with ISO 8601. For values, this format specifier is designed to preserve date and time values along with the property in text. The formatted string can be parsed back by using the or method if the `styles` parameter is set to . +The "O" or "o" standard format specifier represents a custom date and time format string using a pattern that preserves time zone information and emits a result string that complies with ISO 8601. For values, this format specifier is designed to preserve date and time values along with the property in text. The formatted string can be parsed back by using the or method if the `styles` parameter is set to . For values, this format specifier produces a date-only ISO 8601 string in the format "yyyy-MM-dd". For values, it produces a time-only ISO 8601 string in the format "HH:mm:ss.fffffff". The "O" or "o" standard format specifier corresponds to the "yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffK" custom format string for values and to the "yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffzzz" custom format string for values. In this string, the pairs of single quotation marks that delimit individual characters, such as the hyphens, the colons, and the letter "T", indicate that the individual character is a literal that cannot be changed. The apostrophes do not appear in the output string. -The "O" or "o" standard format specifier (and the "yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffK" custom format string) takes advantage of the three ways that ISO 8601 represents time zone information to preserve the property of values: +The "O" or "o" standard format specifier (and the "yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffK" custom format string) takes advantage of the three ways that ISO 8601 represents time zone information to preserve the property of values: - The time zone component of date and time values is an offset from UTC (for example, +01:00, -07:00). All values are also represented in this format. @@ -286,17 +286,17 @@ The following example uses the "o" format specifier to create a formatted string ### The RFC1123 ("R", "r") format specifier -The "R" or "r" standard format specifier represents a custom date and time format string that's defined by the property. The pattern reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture used or the format provider supplied. The custom format string is "ddd, dd MMM yyyy HH':'mm':'ss 'GMT'". When this standard format specifier is used, the formatting or parsing operation always uses the invariant culture. +The "R" or "r" standard format specifier represents a custom date and time format string that's defined by the property. The pattern reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture used or the format provider supplied. The custom format string is "ddd, dd MMM yyyy HH':'mm':'ss 'GMT'". When this standard format specifier is used, the formatting or parsing operation always uses the invariant culture. -The result string is affected by the following properties of the object returned by the property that represents the invariant culture. +The result string is affected by the following properties of the object returned by the property that represents the invariant culture. |Property|Description| |--------------|-----------------| -||Defines the format of the result string.| -||Defines the abbreviated day names that can appear in the result string.| -||Defines the abbreviated month names that can appear in the result string.| +||Defines the format of the result string.| +||Defines the abbreviated day names that can appear in the result string.| +||Defines the abbreviated month names that can appear in the result string.| -Although the RFC 1123 standard expresses a time as Coordinated Universal Time (UTC), the formatting operation does not modify the value of the object that's being formatted. Therefore, you must convert the value to UTC by calling the method before you perform the formatting operation. In contrast, values perform this conversion automatically; there's no need to call the method before the formatting operation. +Although the RFC 1123 standard expresses a time as Coordinated Universal Time (UTC), the formatting operation does not modify the value of the object that's being formatted. Therefore, you must convert the value to UTC by calling the method before you perform the formatting operation. In contrast, values perform this conversion automatically; there's no need to call the method before the formatting operation. The following example uses the "r" format specifier to display a and a value on a system in the U.S. Pacific Time zone. @@ -311,7 +311,7 @@ The following example uses the "r" format specifier to display a property. The pattern reflects a defined standard (ISO 8601), and the property is read-only. Therefore, it is always the same, regardless of the culture used or the format provider supplied. The custom format string is "yyyy'-'MM'-'dd'T'HH':'mm':'ss". -The purpose of the "s" format specifier is to produce result strings that sort consistently in ascending or descending order based on date and time values. As a result, although the "s" standard format specifier represents a date and time value in a consistent format, the formatting operation does not modify the value of the date and time object that is being formatted to reflect its property or its value. For example, the result strings produced by formatting the date and time values 2014-11-15T18:32:17+00:00 and 2014-11-15T18:32:17+08:00 are identical. +The purpose of the "s" format specifier is to produce result strings that sort consistently in ascending or descending order based on date and time values. As a result, although the "s" standard format specifier represents a date and time value in a consistent format, the formatting operation does not modify the value of the date and time object that is being formatted to reflect its property or its value. For example, the result strings produced by formatting the date and time values 2014-11-15T18:32:17+00:00 and 2014-11-15T18:32:17+08:00 are identical. When this standard format specifier is used, the formatting or parsing operation always uses the invariant culture. @@ -326,9 +326,9 @@ The following example uses the "s" format specifier to display a property. The pattern reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture used or the format provider supplied. The custom format string is "yyyy'-'MM'-'dd HH':'mm':'ss'Z'". When this standard format specifier is used, the formatting or parsing operation always uses the invariant culture. +The "u" standard format specifier represents a custom date and time format string that is defined by the property. The pattern reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture used or the format provider supplied. The custom format string is "yyyy'-'MM'-'dd HH':'mm':'ss'Z'". When this standard format specifier is used, the formatting or parsing operation always uses the invariant culture. -Although the result string should express a time as Coordinated Universal Time (UTC), no conversion of the original value is performed during the formatting operation. Therefore, you must convert a value to UTC by calling the method before formatting it. In contrast, values perform this conversion automatically; there is no need to call the method before the formatting operation. +Although the result string should express a time as Coordinated Universal Time (UTC), no conversion of the original value is performed during the formatting operation. Therefore, you must convert a value to UTC by calling the method before formatting it. In contrast, values perform this conversion automatically; there is no need to call the method before the formatting operation. The following example uses the "u" format specifier to display a date and time value. @@ -341,18 +341,18 @@ The following example uses the "u" format specifier to display a date and time v ### The universal full ("U") format specifier -The "U" standard format specifier represents a custom date and time format string that is defined by a specified culture's property. The pattern is the same as the "F" pattern. However, the value is automatically converted to UTC before it is formatted. +The "U" standard format specifier represents a custom date and time format string that is defined by a specified culture's property. The pattern is the same as the "F" pattern. However, the value is automatically converted to UTC before it is formatted. -The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. +The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. |Property|Description| |--------------|-----------------| -||Defines the overall format of the result string.| -||Defines the localized day names that can appear in the result string.| -||Defines the localized month names that can appear in the result string.| -||Defines the string that separates the hour, minute, and second components of a time.| -||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| -||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| +||Defines the overall format of the result string.| +||Defines the localized day names that can appear in the result string.| +||Defines the localized month names that can appear in the result string.| +||Defines the string that separates the hour, minute, and second components of a time.| +||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| +||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| The "U" format specifier is not supported by the type and throws a if it is used to format a value. @@ -374,16 +374,16 @@ This group includes the following formats: ### The short time ("t") format specifier -The "t" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "HH:mm". +The "t" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "HH:mm". -The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. +The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. |Property|Description| |--------------|-----------------| -||Defines the format of the time component of the result string.| -||Defines the string that separates the hour, minute, and second components of a time.| -||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| -||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| +||Defines the format of the time component of the result string.| +||Defines the string that separates the hour, minute, and second components of a time.| +||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| +||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| The following example uses the "t" format specifier to display a date and time value. @@ -396,16 +396,16 @@ The following example uses the "t" format specifier to display a date and time v ### The long time ("T") format specifier -The "T" standard format specifier represents a custom date and time format string that is defined by a specific culture's property. For example, the custom format string for the invariant culture is "HH:mm:ss". +The "T" standard format specifier represents a custom date and time format string that is defined by a specific culture's property. For example, the custom format string for the invariant culture is "HH:mm:ss". -The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. +The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. |Property|Description| |--------------|-----------------| -||Defines the format of the time component of the result string.| -||Defines the string that separates the hour, minute, and second components of a time.| -||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| -||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| +||Defines the format of the time component of the result string.| +||Defines the string that separates the hour, minute, and second components of a time.| +||Defines the string that indicates times from midnight to before noon in a 12-hour clock.| +||Defines the string that indicates times from noon to before midnight in a 12-hour clock.| The following example uses the "T" format specifier to display a date and time value. @@ -425,14 +425,14 @@ This group includes the following formats: ### The month ("M", "m") format specifier -The "M" or "m" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "MMMM dd". +The "M" or "m" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "MMMM dd". The following table lists the object properties that control the formatting of the returned string. |Property|Description| |--------------|-----------------| -||Defines the overall format of the result string.| -||Defines the localized month names that can appear in the result string.| +||Defines the overall format of the result string.| +||Defines the localized month names that can appear in the result string.| The following example uses the "m" format specifier to display a date and time value. @@ -445,14 +445,14 @@ The following example uses the "m" format specifier to display a date and time v ### The year month ("Y", "y") format specifier -The "Y" or "y" standard format specifier represents a custom date and time format string that is defined by the property of a specified culture. For example, the custom format string for the invariant culture is "yyyy MMMM". +The "Y" or "y" standard format specifier represents a custom date and time format string that is defined by the property of a specified culture. For example, the custom format string for the invariant culture is "yyyy MMMM". The following table lists the object properties that control the formatting of the returned string. |Property|Description| |--------------|-----------------| -||Defines the overall format of the result string.| -||Defines the localized month names that can appear in the result string.| +||Defines the overall format of the result string.| +||Defines the localized month names that can appear in the result string.| The following example uses the "y" format specifier to display a date and time value. diff --git a/docs/standard/base-types/standard-numeric-format-strings.md b/docs/standard/base-types/standard-numeric-format-strings.md index 84626b5370bce..48c9bdff393a3 100644 --- a/docs/standard/base-types/standard-numeric-format-strings.md +++ b/docs/standard/base-types/standard-numeric-format-strings.md @@ -23,7 +23,7 @@ Standard numeric format strings are used to format common numeric types. A stand - *Format specifier* is a single alphabetic character that specifies the type of number format, for example, currency or percent. Any numeric format string that contains more than one alphabetic character, including white space, is interpreted as a custom numeric format string. For more information, see [Custom numeric format strings](custom-numeric-format-strings.md). -- *Precision specifier* is an optional integer that affects the number of digits in the resulting string. In .NET 7 and later versions, the maximum precision value is 999,999,999. In .NET 6, the maximum precision value is . In previous .NET versions, the precision can range from 0 to 99. The precision specifier controls the number of digits in the string representation of a number. It does not round the number itself. To perform a rounding operation, use the , , or method. +- *Precision specifier* is an optional integer that affects the number of digits in the resulting string. In .NET 7 and later versions, the maximum precision value is 999,999,999. In .NET 6, the maximum precision value is . In previous .NET versions, the precision can range from 0 to 99. The precision specifier controls the number of digits in the string representation of a number. It does not round the number itself. To perform a rounding operation, use the , , or method. When *precision specifier* controls the number of fractional digits in the result string, the result string reflects a number that is rounded to a representable result nearest to the infinitely precise result. If there are two equally near representable results: - **On .NET Framework and .NET Core up to .NET Core 2.0**, the runtime selects the result with the greater least significant digit (that is, using ). @@ -38,7 +38,7 @@ Standard numeric format strings are supported by: - The `TryFormat` method of all numeric types, for example, and . -- The .NET [composite formatting feature](composite-formatting.md), which is used by some `Write` and `WriteLine` methods of the and classes, the method, and the method. The composite format feature allows you to include the string representation of multiple data items in a single string, to specify field width, and to align numbers in a field. For more information, see [Composite Formatting](composite-formatting.md). +- The .NET [composite formatting feature](composite-formatting.md), which is used by some `Write` and `WriteLine` methods of the and classes, the method, and the method. The composite format feature allows you to include the string representation of multiple data items in a single string, to specify field width, and to align numbers in a field. For more information, see [Composite Formatting](composite-formatting.md). - [Interpolated strings](../../csharp/language-reference/tokens/interpolated.md) in C# and Visual Basic, which provide a simplified syntax when compared to composite format strings. @@ -54,13 +54,13 @@ The following table describes the standard numeric format specifiers and display | Format specifier | Name | Description | Examples | |------------------|------|-------------|----------| | "B" or "b" | Binary | Result: A binary string.

Supported by: Integral types only (.NET 8+).

Precision specifier: Number of digits in the result string.

More information: [The Binary ("B") Format Specifier](#BFormatString). | 42 ("B")
-> 101010

255 ("b16")
-> 0000000011111111 | -| "C" or "c" | Currency | Result: A currency value.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: Defined by .

More information: [The Currency ("C") Format Specifier](#CFormatString). | 123.456 ("C", en-US)
-> \\$123.46

123.456 ("C", fr-FR)
-> 123,46 €

123.456 ("C", ja-JP)
-> ¥123

-123.456 ("C3", en-US)
-> (\\$123.456)

-123.456 ("C3", fr-FR)
-> -123,456 €

-123.456 ("C3", ja-JP)
-> -¥123.456 | +| "C" or "c" | Currency | Result: A currency value.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: Defined by .

More information: [The Currency ("C") Format Specifier](#CFormatString). | 123.456 ("C", en-US)
-> \\$123.46

123.456 ("C", fr-FR)
-> 123,46 €

123.456 ("C", ja-JP)
-> ¥123

-123.456 ("C3", en-US)
-> (\\$123.456)

-123.456 ("C3", fr-FR)
-> -123,456 €

-123.456 ("C3", ja-JP)
-> -¥123.456 | | "D" or "d" | Decimal | Result: Integer digits with optional negative sign.

Supported by: Integral types only.

Precision specifier: Minimum number of digits.

Default precision specifier: Minimum number of digits required.

More information: [The Decimal("D") Format Specifier](#DFormatString). | 1234 ("D")
-> 1234

-1234 ("D6")
-> -001234 | | "E" or "e" | Exponential (scientific) | Result: Exponential notation.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: 6.

More information: [The Exponential ("E") Format Specifier](#EFormatString). | 1052.0329112756 ("E", en-US)
-> 1.052033E+003

1052.0329112756 ("e", fr-FR)
-> 1,052033e+003

-1052.0329112756 ("e2", en-US)
-> -1.05e+003

-1052.0329112756 ("E2", fr-FR)
-> -1,05E+003 | -| "F" or "f" | Fixed-point | Result: Integral and decimal digits with optional negative sign.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: Defined by .

More information: [The Fixed-Point ("F") Format Specifier](#FFormatString). | 1234.567 ("F", en-US)
-> 1234.57

1234.567 ("F", de-DE)
-> 1234,57

1234 ("F1", en-US)
-> 1234.0

1234 ("F1", de-DE)
-> 1234,0

-1234.56 ("F4", en-US)
-> -1234.5600

-1234.56 ("F4", de-DE)
-> -1234,5600 | +| "F" or "f" | Fixed-point | Result: Integral and decimal digits with optional negative sign.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: Defined by .

More information: [The Fixed-Point ("F") Format Specifier](#FFormatString). | 1234.567 ("F", en-US)
-> 1234.57

1234.567 ("F", de-DE)
-> 1234,57

1234 ("F1", en-US)
-> 1234.0

1234 ("F1", de-DE)
-> 1234,0

-1234.56 ("F4", en-US)
-> -1234.5600

-1234.56 ("F4", de-DE)
-> -1234,5600 | | "G" or "g" | General | Result: The more compact of either fixed-point or scientific notation.

Supported by: All numeric types.

Precision specifier: Number of significant digits.

Default precision specifier: Depends on numeric type.

More information: [The General ("G") Format Specifier](#GFormatString). | -123.456 ("G", en-US)
-> -123.456

-123.456 ("G", sv-SE)
-> -123,456

123.4546 ("G4", en-US)
-> 123.5

123.4546 ("G4", sv-SE)
-> 123,5

-1.234567890e-25 ("G", en-US)
-> -1.23456789E-25

-1.234567890e-25 ("G", sv-SE)
-> -1,23456789E-25 | -| "N" or "n" | Number | Result: Integral and decimal digits, group separators, and a decimal separator with optional negative sign.

Supported by: All numeric types.

Precision specifier: Desired number of decimal places.

Default precision specifier: Defined by .

More information: [The Numeric ("N") Format Specifier](#NFormatString). | 1234.567 ("N", en-US)
-> 1,234.57

1234.567 ("N", ru-RU)
-> 1 234,57

1234 ("N1", en-US)
-> 1,234.0

1234 ("N1", ru-RU)
-> 1 234,0

-1234.56 ("N3", en-US)
-> -1,234.560

-1234.56 ("N3", ru-RU)
-> -1 234,560 | -| "P" or "p" | Percent | Result: Number multiplied by 100 and displayed with a percent symbol.

Supported by: All numeric types.

Precision specifier: Desired number of decimal places.

Default precision specifier: Defined by .

More information: [The Percent ("P") Format Specifier](#PFormatString). | 1 ("P", en-US)
-> 100.00 %

1 ("P", fr-FR)
-> 100,00 %

-0.39678 ("P1", en-US)
-> -39.7 %

-0.39678 ("P1", fr-FR)
-> -39,7 % | +| "N" or "n" | Number | Result: Integral and decimal digits, group separators, and a decimal separator with optional negative sign.

Supported by: All numeric types.

Precision specifier: Desired number of decimal places.

Default precision specifier: Defined by .

More information: [The Numeric ("N") Format Specifier](#NFormatString). | 1234.567 ("N", en-US)
-> 1,234.57

1234.567 ("N", ru-RU)
-> 1 234,57

1234 ("N1", en-US)
-> 1,234.0

1234 ("N1", ru-RU)
-> 1 234,0

-1234.56 ("N3", en-US)
-> -1,234.560

-1234.56 ("N3", ru-RU)
-> -1 234,560 | +| "P" or "p" | Percent | Result: Number multiplied by 100 and displayed with a percent symbol.

Supported by: All numeric types.

Precision specifier: Desired number of decimal places.

Default precision specifier: Defined by .

More information: [The Percent ("P") Format Specifier](#PFormatString). | 1 ("P", en-US)
-> 100.00 %

1 ("P", fr-FR)
-> 100,00 %

-0.39678 ("P1", en-US)
-> -39.7 %

-0.39678 ("P1", fr-FR)
-> -39,7 % | | "R" or "r" | Round-trip | Result: A string that can round-trip to an identical number.

Supported by: , , and .

Note: Recommended for the type only. For types, use "G17"; for types, use "G9".
Precision specifier: Ignored.

More information: [The Round-trip ("R") Format Specifier](#RFormatString). | 123456789.12345678 ("R")
-> 123456789.12345678

-1234567890.12345678 ("R")
-> -1234567890.1234567 | | "X" or "x" | Hexadecimal | Result: A hexadecimal string.

Supported by: Integral types only.

Precision specifier: Number of digits in the result string.

More information: [The Hexadecimal ("X") Format Specifier](#XFormatString). | 255 ("X")
-> FF

-1 ("x")
-> ff

255 ("x4")
-> 00ff

-1 ("X4")
-> 00FF | | Any other single character | Unknown specifier | Result: Throws a at runtime. | | @@ -74,7 +74,7 @@ A standard numeric format string can be used to define the formatting of a numer [!code-csharp[Formatting.Numeric.Standard#10](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Numeric.Standard/cs/standardusage1.cs#10)] [!code-vb[Formatting.Numeric.Standard#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Numeric.Standard/vb/standardusage1.vb#10)] -- It can be supplied as the `formatString` argument in a format item used with such methods as , , and . For more information, see [Composite Formatting](composite-formatting.md). The following example uses a format item to insert a currency value in a string. +- It can be supplied as the `formatString` argument in a format item used with such methods as , , and . For more information, see [Composite Formatting](composite-formatting.md). The following example uses a format item to insert a currency value in a string. [!code-csharp[Formatting.Numeric.Standard#11](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Numeric.Standard/cs/standardusage1.cs#11)] [!code-vb[Formatting.Numeric.Standard#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Numeric.Standard/vb/standardusage1.vb#11)] @@ -104,7 +104,7 @@ The result string is not affected by the formatting information of the current < ## Currency format specifier (C) -The "C" (or currency) format specifier converts a number to a string that represents a currency amount. The precision specifier indicates the desired number of decimal places in the result string. If the precision specifier is omitted, the default precision is defined by the property. +The "C" (or currency) format specifier converts a number to a string that represents a currency amount. The precision specifier indicates the desired number of decimal places in the result string. If the precision specifier is omitted, the default precision is defined by the property. If the value to be formatted has more than the specified or default number of decimal places, the fractional value is rounded in the result string. If the value to the right of the number of specified decimal places is 5 or greater, the last digit in the result string is rounded away from zero. @@ -112,14 +112,14 @@ The result string is affected by the formatting information of the current |Defines the placement of the currency symbol for positive values.| -||Defines the placement of the currency symbol for negative values, and specifies whether the negative sign is represented by parentheses or the property.| -||Defines the negative sign used if indicates that parentheses are not used.| -||Defines the currency symbol.| -||Defines the default number of decimal digits in a currency value. This value can be overridden by using the precision specifier.| -||Defines the string that separates integral and decimal digits.| -||Defines the string that separates groups of integral numbers.| -||Defines the number of integer digits that appear in a group.| +||Defines the placement of the currency symbol for positive values.| +||Defines the placement of the currency symbol for negative values, and specifies whether the negative sign is represented by parentheses or the property.| +||Defines the negative sign used if indicates that parentheses are not used.| +||Defines the currency symbol.| +||Defines the default number of decimal digits in a currency value. This value can be overridden by using the precision specifier.| +||Defines the string that separates integral and decimal digits.| +||Defines the string that separates groups of integral numbers.| +||Defines the number of integer digits that appear in a group.| The following example formats a value with the currency format specifier: [!code-csharp[Formatting.Numeric.Standard#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Numeric.Standard/cs/Standard.cs#1)] @@ -137,7 +137,7 @@ The result string is affected by the formatting information of the current |Defines the string that indicates that a number is negative.| +||Defines the string that indicates that a number is negative.| The following example formats an value with the decimal format specifier. [!code-csharp[Formatting.Numeric.Standard#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Numeric.Standard/cs/Standard.cs#2)] @@ -157,9 +157,9 @@ The result string is affected by the formatting information of the current |Defines the string that indicates that a number is negative for both the coefficient and exponent.| -||Defines the string that separates the integral digit from decimal digits in the coefficient.| -||Defines the string that indicates that an exponent is positive.| +||Defines the string that indicates that a number is negative for both the coefficient and exponent.| +||Defines the string that separates the integral digit from decimal digits in the coefficient.| +||Defines the string that indicates that an exponent is positive.| The following example formats a value with the exponential format specifier: [!code-csharp[Formatting.Numeric.Standard#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Numeric.Standard/cs/Standard.cs#3)] @@ -171,15 +171,15 @@ The following example formats a value with the exponential The fixed-point ("F") format specifier converts a number to a string of the form "-ddd.ddd…" where each "d" indicates a digit (0-9). The string starts with a minus sign if the number is negative. -The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the current property supplies the numeric precision. +The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the current property supplies the numeric precision. The result string is affected by the formatting information of the current object. The following table lists the properties of the object that control the formatting of the result string. |NumberFormatInfo property|Description| |-------------------------------|-----------------| -||Defines the string that indicates that a number is negative.| -||Defines the string that separates integral digits from decimal digits.| -||Defines the default number of decimal digits. This value can be overridden by using the precision specifier.| +||Defines the string that indicates that a number is negative.| +||Defines the string that separates integral digits from decimal digits.| +||Defines the default number of decimal digits. This value can be overridden by using the precision specifier.| The following example formats a and an value with the fixed-point format specifier: [!code-csharp[Formatting.Numeric.Standard#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Numeric.Standard/cs/Standard.cs#4)] @@ -218,9 +218,9 @@ The result string is affected by the formatting information of the current |Defines the string that indicates that a number is negative.| -||Defines the string that separates integral digits from decimal digits.| -||Defines the string that indicates that an exponent is positive.| +||Defines the string that indicates that a number is negative.| +||Defines the string that separates integral digits from decimal digits.| +||Defines the string that indicates that an exponent is positive.| The following example formats assorted floating-point values with the general format specifier: [!code-csharp[Formatting.Numeric.Standard#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Numeric.Standard/cs/Standard.cs#5)] @@ -230,18 +230,18 @@ The following example formats assorted floating-point values with the general fo ## Numeric format specifier (N) -The numeric ("N") format specifier converts a number to a string of the form "-d,ddd,ddd.ddd…", where "-" indicates a negative number symbol if required, "d" indicates a digit (0-9), "," indicates a group separator, and "." indicates a decimal point symbol. The precision specifier indicates the desired number of digits after the decimal point. If the precision specifier is omitted, the number of decimal places is defined by the current property. +The numeric ("N") format specifier converts a number to a string of the form "-d,ddd,ddd.ddd…", where "-" indicates a negative number symbol if required, "d" indicates a digit (0-9), "," indicates a group separator, and "." indicates a decimal point symbol. The precision specifier indicates the desired number of digits after the decimal point. If the precision specifier is omitted, the number of decimal places is defined by the current property. The result string is affected by the formatting information of the current object. The following table lists the properties that control the formatting of the result string. |NumberFormatInfo property|Description| |-------------------------------|-----------------| -||Defines the string that indicates that a number is negative.| -||Defines the format of negative values, and specifies whether the negative sign is represented by parentheses or the property.| -||Defines the number of integral digits that appear between group separators.| -||Defines the string that separates groups of integral numbers.| -||Defines the string that separates integral and decimal digits.| -||Defines the default number of decimal digits. This value can be overridden by using a precision specifier.| +||Defines the string that indicates that a number is negative.| +||Defines the format of negative values, and specifies whether the negative sign is represented by parentheses or the property.| +||Defines the number of integral digits that appear between group separators.| +||Defines the string that separates groups of integral numbers.| +||Defines the string that separates integral and decimal digits.| +||Defines the default number of decimal digits. This value can be overridden by using a precision specifier.| The following example formats assorted floating-point values with the number format specifier: [!code-csharp[Formatting.Numeric.Standard#6](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Numeric.Standard/cs/Standard.cs#6)] @@ -251,20 +251,20 @@ The following example formats assorted floating-point values with the number for ## Percent format specifier (P) -The percent ("P") format specifier multiplies a number by 100 and converts it to a string that represents a percentage. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the default numeric precision supplied by the current property is used. +The percent ("P") format specifier multiplies a number by 100 and converts it to a string that represents a percentage. The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the default numeric precision supplied by the current property is used. The following table lists the properties that control the formatting of the returned string. |NumberFormatInfo property|Description| |-------------------------------|-----------------| -||Defines the placement of the percent symbol for positive values.| -||Defines the placement of the percent symbol and the negative symbol for negative values.| -||Defines the string that indicates that a number is negative.| -||Defines the percent symbol.| -||Defines the default number of decimal digits in a percentage value. This value can be overridden by using the precision specifier.| -||Defines the string that separates integral and decimal digits.| -||Defines the string that separates groups of integral numbers.| -||Defines the number of integer digits that appear in a group.| +||Defines the placement of the percent symbol for positive values.| +||Defines the placement of the percent symbol and the negative symbol for negative values.| +||Defines the string that indicates that a number is negative.| +||Defines the percent symbol.| +||Defines the default number of decimal digits in a percentage value. This value can be overridden by using the precision specifier.| +||Defines the string that separates integral and decimal digits.| +||Defines the string that separates groups of integral numbers.| +||Defines the number of integer digits that appear in a group.| The following example formats floating-point values with the percent format specifier: [!code-csharp[Formatting.Numeric.Standard#7](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Numeric.Standard/cs/Standard.cs#7)] @@ -285,9 +285,9 @@ The result string is affected by the formatting information of the current |Defines the string that indicates that a number is negative.| -||Defines the string that separates integral digits from decimal digits.| -||Defines the string that indicates that an exponent is positive.| +||Defines the string that indicates that a number is negative.| +||Defines the string that separates integral digits from decimal digits.| +||Defines the string that indicates that an exponent is positive.| The following example formats a value with the round-trip format specifier. [!code-csharp[R format specifier with a BigInteger](../../../samples/snippets/standard/base-types/format-strings/biginteger-r.cs)] @@ -340,7 +340,7 @@ Some descriptions of standard numeric format specifiers refer to integral or flo ### Floating-point infinities and NaN -Regardless of the format string, if the value of a , , or floating-point type is positive infinity, negative infinity, or not a number (NaN), the formatted string is the value of the respective , , or property that is specified by the currently applicable object. +Regardless of the format string, if the value of a , , or floating-point type is positive infinity, negative infinity, or not a number (NaN), the formatted string is the value of the respective , , or property that is specified by the currently applicable object. ## Code example diff --git a/docs/standard/base-types/standard-timespan-format-strings.md b/docs/standard/base-types/standard-timespan-format-strings.md index 0b9b0631f31cd..72c25391b9ee3 100644 --- a/docs/standard/base-types/standard-timespan-format-strings.md +++ b/docs/standard/base-types/standard-timespan-format-strings.md @@ -21,102 +21,102 @@ helpviewer_keywords: # Standard TimeSpan format strings A standard format string uses a single format specifier to define the text representation of a value that results from a formatting operation. Any format string that contains more than one character, including white space, is interpreted as a custom format string. For more information, see [Custom TimeSpan format strings](custom-timespan-format-strings.md). - - The string representations of values are produced by calls to the overloads of the method, as well as by methods that support composite formatting, such as . For more information, see [Formatting Types](formatting-types.md) and [Composite Formatting](composite-formatting.md). The following example illustrates the use of standard format strings in formatting operations. - + + The string representations of values are produced by calls to the overloads of the method, as well as by methods that support composite formatting, such as . For more information, see [Formatting Types](formatting-types.md) and [Composite Formatting](composite-formatting.md). The following example illustrates the use of standard format strings in formatting operations. + [!code-csharp[Conceptual.TimeSpan.Standard#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.standard/cs/formatexample1.cs#2)] - [!code-vb[Conceptual.TimeSpan.Standard#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.standard/vb/formatexample1.vb#2)] - - Standard format strings are also used by the and methods to define the required format of input strings for parsing operations. (Parsing converts the string representation of a value to that value.) The following example illustrates the use of standard format strings in parsing operations. - + [!code-vb[Conceptual.TimeSpan.Standard#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.standard/vb/formatexample1.vb#2)] + + Standard format strings are also used by the and methods to define the required format of input strings for parsing operations. (Parsing converts the string representation of a value to that value.) The following example illustrates the use of standard format strings in parsing operations. + [!code-csharp[Conceptual.TimeSpan.Standard#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.standard/cs/parseexample1.cs#3)] - [!code-vb[Conceptual.TimeSpan.Standard#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.standard/vb/parseexample1.vb#3)] - -The following table lists the standard time interval format specifiers. - -|Format specifier|Name|Description|Examples| -|----------------------|----------|-----------------|--------------| -|"c"|Constant (invariant) format|This specifier is not culture-sensitive. It takes the form `[-][d'.']hh':'mm':'ss['.'fffffff]`.

(The "t" and "T" format strings produce the same results.)

More information: [The Constant ("c") Format Specifier](#the-constant-c-format-specifier).|`TimeSpan.Zero` -> 00:00:00

`New TimeSpan(0, 0, 30, 0)` -> 00:30:00

`New TimeSpan(3, 17, 25, 30, 500)` -> 3.17:25:30.5000000| -|"g"|General short format|This specifier outputs only what is needed. It is culture-sensitive and takes the form `[-][d':']h':'mm':'ss[.FFFFFFF]`.

More information: [The General Short ("g") Format Specifier](#the-general-short-g-format-specifier).|`New TimeSpan(1, 3, 16, 50, 500)` -> 1:3:16:50.5 (en-US)

`New TimeSpan(1, 3, 16, 50, 500)` -> 1:3:16:50,5 (fr-FR)

`New TimeSpan(1, 3, 16, 50, 599)` -> 1:3:16:50.599 (en-US)

`New TimeSpan(1, 3, 16, 50, 599)` -> 1:3:16:50,599 (fr-FR)| -|"G"|General long format|This specifier always outputs days and seven fractional digits. It is culture-sensitive and takes the form `[-]d':'hh':'mm':'ss.fffffff`.

More information: [The General Long ("G") Format Specifier](#the-general-long-g-format-specifier).|`New TimeSpan(18, 30, 0)` -> 0:18:30:00.0000000 (en-US)

`New TimeSpan(18, 30, 0)` -> 0:18:30:00,0000000 (fr-FR)| - -## The Constant ("c") Format Specifier - -The "c" format specifier returns the string representation of a value in the following form: - -`[-][d.]hh:mm:ss[.fffffff]` - -Elements in square brackets ([ and ]) are optional. The period (.) and colon (:) are literal symbols. The following table describes the remaining elements. - -|Element|Description| -|-------------|-----------------| -|*-*|An optional negative sign, which indicates a negative time interval.| -|*d*|The optional number of days, with no leading zeros.| -|*hh*|The number of hours, which ranges from "00" to "23".| -|*mm*|The number of minutes, which ranges from "00" to "59".| -|*ss*|The number of seconds, which ranges from "0" to "59".| -|*fffffff*|The optional fractional portion of a second. Its value can range from "0000001" (one tick, or one ten-millionth of a second) to "9999999" (9,999,999 ten-millionths of a second, or one second less one tick).| - - Unlike the "g" and "G" format specifiers, the "c" format specifier is not culture-sensitive. It produces the string representation of a value that is invariant and that's common to versions prior to .NET Framework 4. "c" is the default format string; the method formats a time interval value by using the "c" format string. - + [!code-vb[Conceptual.TimeSpan.Standard#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.standard/vb/parseexample1.vb#3)] + +The following table lists the standard time interval format specifiers. + +|Format specifier|Name|Description|Examples| +|----------------------|----------|-----------------|--------------| +|"c"|Constant (invariant) format|This specifier is not culture-sensitive. It takes the form `[-][d'.']hh':'mm':'ss['.'fffffff]`.

(The "t" and "T" format strings produce the same results.)

More information: [The Constant ("c") Format Specifier](#the-constant-c-format-specifier).|`TimeSpan.Zero` -> 00:00:00

`New TimeSpan(0, 0, 30, 0)` -> 00:30:00

`New TimeSpan(3, 17, 25, 30, 500)` -> 3.17:25:30.5000000| +|"g"|General short format|This specifier outputs only what is needed. It is culture-sensitive and takes the form `[-][d':']h':'mm':'ss[.FFFFFFF]`.

More information: [The General Short ("g") Format Specifier](#the-general-short-g-format-specifier).|`New TimeSpan(1, 3, 16, 50, 500)` -> 1:3:16:50.5 (en-US)

`New TimeSpan(1, 3, 16, 50, 500)` -> 1:3:16:50,5 (fr-FR)

`New TimeSpan(1, 3, 16, 50, 599)` -> 1:3:16:50.599 (en-US)

`New TimeSpan(1, 3, 16, 50, 599)` -> 1:3:16:50,599 (fr-FR)| +|"G"|General long format|This specifier always outputs days and seven fractional digits. It is culture-sensitive and takes the form `[-]d':'hh':'mm':'ss.fffffff`.

More information: [The General Long ("G") Format Specifier](#the-general-long-g-format-specifier).|`New TimeSpan(18, 30, 0)` -> 0:18:30:00.0000000 (en-US)

`New TimeSpan(18, 30, 0)` -> 0:18:30:00,0000000 (fr-FR)| + +## The Constant ("c") Format Specifier + +The "c" format specifier returns the string representation of a value in the following form: + +`[-][d.]hh:mm:ss[.fffffff]` + +Elements in square brackets ([ and ]) are optional. The period (.) and colon (:) are literal symbols. The following table describes the remaining elements. + +|Element|Description| +|-------------|-----------------| +|*-*|An optional negative sign, which indicates a negative time interval.| +|*d*|The optional number of days, with no leading zeros.| +|*hh*|The number of hours, which ranges from "00" to "23".| +|*mm*|The number of minutes, which ranges from "00" to "59".| +|*ss*|The number of seconds, which ranges from "0" to "59".| +|*fffffff*|The optional fractional portion of a second. Its value can range from "0000001" (one tick, or one ten-millionth of a second) to "9999999" (9,999,999 ten-millionths of a second, or one second less one tick).| + + Unlike the "g" and "G" format specifiers, the "c" format specifier is not culture-sensitive. It produces the string representation of a value that is invariant and that's common to versions prior to .NET Framework 4. "c" is the default format string; the method formats a time interval value by using the "c" format string. + > [!NOTE] -> also supports the "t" and "T" standard format strings, which are identical in behavior to the "c" standard format string. - - The following example instantiates two objects, uses them to perform arithmetic operations, and displays the result. In each case, it uses composite formatting to display the value by using the "c" format specifier. - +> also supports the "t" and "T" standard format strings, which are identical in behavior to the "c" standard format string. + + The following example instantiates two objects, uses them to perform arithmetic operations, and displays the result. In each case, it uses composite formatting to display the value by using the "c" format specifier. + [!code-csharp[Conceptual.TimeSpan.Standard#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.standard/cs/standardc1.cs#1)] - [!code-vb[Conceptual.TimeSpan.Standard#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.standard/vb/standardc1.vb#1)] - -## The General Short ("g") Format Specifier - -The "g" format specifier returns the string representation of a value in a compact form by including only the elements that are necessary. It has the following form: - -`[-][d:]h:mm:ss[.FFFFFFF]` - -Elements in square brackets ([ and ]) are optional. The colon (:) is a literal symbol. The following table describes the remaining elements. - -|Element|Description| -|-------------|-----------------| -|*-*|An optional negative sign, which indicates a negative time interval.| -|*d*|The optional number of days, with no leading zeros.| -|*h*|The number of hours, which ranges from "0" to "23", with no leading zeros.| -|*mm*|The number of minutes, which ranges from "00" to "59".| -|*ss*|The number of seconds, which ranges from "00" to "59".| -|*.*|The fractional seconds separator. It is equivalent to the specified culture's property without user overrides.| -|*FFFFFFF*|The fractional seconds. As few digits as possible are displayed.| - - Like the "G" format specifier, the "g" format specifier is localized. Its fractional seconds separator is based on either the current culture or a specified culture's property. - - The following example instantiates two objects, uses them to perform arithmetic operations, and displays the result. In each case, it uses composite formatting to display the value by using the "g" format specifier. In addition, it formats the value by using the formatting conventions of the current system culture (which, in this case, is English - United States or en-US) and the French - France (fr-FR) culture. - + [!code-vb[Conceptual.TimeSpan.Standard#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.standard/vb/standardc1.vb#1)] + +## The General Short ("g") Format Specifier + +The "g" format specifier returns the string representation of a value in a compact form by including only the elements that are necessary. It has the following form: + +`[-][d:]h:mm:ss[.FFFFFFF]` + +Elements in square brackets ([ and ]) are optional. The colon (:) is a literal symbol. The following table describes the remaining elements. + +|Element|Description| +|-------------|-----------------| +|*-*|An optional negative sign, which indicates a negative time interval.| +|*d*|The optional number of days, with no leading zeros.| +|*h*|The number of hours, which ranges from "0" to "23", with no leading zeros.| +|*mm*|The number of minutes, which ranges from "00" to "59".| +|*ss*|The number of seconds, which ranges from "00" to "59".| +|*.*|The fractional seconds separator. It is equivalent to the specified culture's property without user overrides.| +|*FFFFFFF*|The fractional seconds. As few digits as possible are displayed.| + + Like the "G" format specifier, the "g" format specifier is localized. Its fractional seconds separator is based on either the current culture or a specified culture's property. + + The following example instantiates two objects, uses them to perform arithmetic operations, and displays the result. In each case, it uses composite formatting to display the value by using the "g" format specifier. In addition, it formats the value by using the formatting conventions of the current system culture (which, in this case, is English - United States or en-US) and the French - France (fr-FR) culture. + [!code-csharp[Conceptual.TimeSpan.Standard#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.standard/cs/standardshort1.cs#4)] - [!code-vb[Conceptual.TimeSpan.Standard#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.standard/vb/standardshort1.vb#4)] - -## The General Long ("G") Format Specifier - -The "G" format specifier returns the string representation of a value in a long form that always includes both days and fractional seconds. The string that results from the "G" standard format specifier has the following form: - -`[-]d:hh:mm:ss.fffffff` - -Elements in square brackets ([ and ]) are optional. The colon (:) is a literal symbol. The following table describes the remaining elements. - -|Element|Description| -|-------------|-----------------| -|*-*|An optional negative sign, which indicates a negative time interval.| -|*d*|The number of days, with no leading zeros.| -|*hh*|The number of hours, which ranges from "00" to "23".| -|*mm*|The number of minutes, which ranges from "00" to "59".| -|*ss*|The number of seconds, which ranges from "00" to "59".| -|*.*|The fractional seconds separator. It is equivalent to the specified culture's property without user overrides.| -|*fffffff*|The fractional seconds.| - - Like the "G" format specifier, the "g" format specifier is localized. Its fractional seconds separator is based on either the current culture or a specified culture's property. - - The following example instantiates two objects, uses them to perform arithmetic operations, and displays the result. In each case, it uses composite formatting to display the value by using the "G" format specifier. In addition, it formats the value by using the formatting conventions of the current system culture (which, in this case, is English - United States or en-US) and the French - France (fr-FR) culture. - + [!code-vb[Conceptual.TimeSpan.Standard#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.standard/vb/standardshort1.vb#4)] + +## The General Long ("G") Format Specifier + +The "G" format specifier returns the string representation of a value in a long form that always includes both days and fractional seconds. The string that results from the "G" standard format specifier has the following form: + +`[-]d:hh:mm:ss.fffffff` + +Elements in square brackets ([ and ]) are optional. The colon (:) is a literal symbol. The following table describes the remaining elements. + +|Element|Description| +|-------------|-----------------| +|*-*|An optional negative sign, which indicates a negative time interval.| +|*d*|The number of days, with no leading zeros.| +|*hh*|The number of hours, which ranges from "00" to "23".| +|*mm*|The number of minutes, which ranges from "00" to "59".| +|*ss*|The number of seconds, which ranges from "00" to "59".| +|*.*|The fractional seconds separator. It is equivalent to the specified culture's property without user overrides.| +|*fffffff*|The fractional seconds.| + + Like the "G" format specifier, the "g" format specifier is localized. Its fractional seconds separator is based on either the current culture or a specified culture's property. + + The following example instantiates two objects, uses them to perform arithmetic operations, and displays the result. In each case, it uses composite formatting to display the value by using the "G" format specifier. In addition, it formats the value by using the formatting conventions of the current system culture (which, in this case, is English - United States or en-US) and the French - France (fr-FR) culture. + [!code-csharp[Conceptual.TimeSpan.Standard#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.standard/cs/standardlong1.cs#5)] [!code-vb[Conceptual.TimeSpan.Standard#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.standard/vb/standardlong1.vb#5)] - + ## See also - [Formatting Types](formatting-types.md) diff --git a/docs/standard/base-types/stringbuilder.md b/docs/standard/base-types/stringbuilder.md index 2a2e5598d91df..988e0a5f68010 100644 --- a/docs/standard/base-types/stringbuilder.md +++ b/docs/standard/base-types/stringbuilder.md @@ -37,13 +37,13 @@ The object is immutable. Every time you use one of the meth [!code-csharp[Conceptual.StringBuilder#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#2)] [!code-vb[Conceptual.StringBuilder#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#2)] - Additionally, you can use the read/write property to set the maximum length of your object. The following example uses the **Capacity** property to define the maximum object length. + Additionally, you can use the read/write property to set the maximum length of your object. The following example uses the **Capacity** property to define the maximum object length. [!code-csharp[Conceptual.StringBuilder#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#3)] [!code-vb[Conceptual.StringBuilder#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#3)] - The method can be used to check the capacity of the current **StringBuilder**. If the capacity is greater than the passed value, no change is made; however, if the capacity is smaller than the passed value, the current capacity is changed to match the passed value. + The method can be used to check the capacity of the current **StringBuilder**. If the capacity is greater than the passed value, no change is made; however, if the capacity is smaller than the passed value, the current capacity is changed to match the passed value. - The property can also be viewed or set. If you set the **Length** property to a value that is greater than the **Capacity** property, the **Capacity** property is automatically changed to the same value as the **Length** property. Setting the **Length** property to a value that is less than the length of the string within the current **StringBuilder** shortens the string. + The property can also be viewed or set. If you set the **Length** property to a value that is greater than the **Capacity** property, the **Capacity** property is automatically changed to the same value as the **Length** property. Setting the **Length** property to a value that is less than the length of the string within the current **StringBuilder** shortens the string. ## Modifying the StringBuilder String @@ -51,11 +51,11 @@ The object is immutable. Every time you use one of the meth |Method name|Use| |-----------------|---------| -||Appends information to the end of the current **StringBuilder**.| -||Replaces a format specifier passed in a string with formatted text.| -||Inserts a string or object into the specified index of the current **StringBuilder**.| -||Removes a specified number of characters from the current **StringBuilder**.| -||Replaces all occurrences of a specified character or string in the current **StringBuilder** with another specified character or string.| +||Appends information to the end of the current **StringBuilder**.| +||Replaces a format specifier passed in a string with formatted text.| +||Inserts a string or object into the specified index of the current **StringBuilder**.| +||Removes a specified number of characters from the current **StringBuilder**.| +||Replaces all occurrences of a specified character or string in the current **StringBuilder** with another specified character or string.| ### Append @@ -65,13 +65,13 @@ The object is immutable. Every time you use one of the meth ### AppendFormat - The method adds text to the end of the object. It supports the [composite formatting feature](composite-formatting.md) by calling the implementation of the object or objects to be formatted. Therefore, it accepts the standard format strings for numeric, date and time, and enumeration values, the custom format strings for numeric and date and time values, and the format strings defined for custom types. (For information about formatting, see [Formatting Types](formatting-types.md).) You can use this method to customize the format of variables and append those values to a . The following example uses the method to place an integer value formatted as a currency value at the end of a object. + The method adds text to the end of the object. It supports the [composite formatting feature](composite-formatting.md) by calling the implementation of the object or objects to be formatted. Therefore, it accepts the standard format strings for numeric, date and time, and enumeration values, the custom format strings for numeric and date and time values, and the format strings defined for custom types. (For information about formatting, see [Formatting Types](formatting-types.md).) You can use this method to customize the format of variables and append those values to a . The following example uses the method to place an integer value formatted as a currency value at the end of a object. [!code-csharp[Conceptual.StringBuilder#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#5)] [!code-vb[Conceptual.StringBuilder#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#5)] ### Insert - The method adds a string or object to a specified position in the current object. The following example uses this method to insert a word into the sixth position of a object. + The method adds a string or object to a specified position in the current object. The following example uses this method to insert a word into the sixth position of a object. [!code-csharp[Conceptual.StringBuilder#6](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#6)] [!code-vb[Conceptual.StringBuilder#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#6)] @@ -89,7 +89,7 @@ The object is immutable. Every time you use one of the meth ## Converting a StringBuilder Object to a String - You must convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. You do this conversion by calling the method. The following example calls a number of methods and then calls the method to display the string. + You must convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. You do this conversion by calling the method. The following example calls a number of methods and then calls the method to display the string. [!code-csharp[Conceptual.StringBuilder#10](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/tostringexample1.cs#10)] [!code-vb[Conceptual.StringBuilder#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/tostringexample1.vb#10)] diff --git a/docs/standard/base-types/substitutions-in-regular-expressions.md b/docs/standard/base-types/substitutions-in-regular-expressions.md index 3b72f544d6e99..cb98e1eaeb9ff 100644 --- a/docs/standard/base-types/substitutions-in-regular-expressions.md +++ b/docs/standard/base-types/substitutions-in-regular-expressions.md @@ -3,10 +3,10 @@ title: "Substitutions in Regular Expressions" description: Make substitutions to replace matched text using regular expressions in .NET. Substitutions are language elements recognized only within replacement patterns. ms.topic: reference ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "regular expressions, substitutions" - "replacement patterns" - "metacharacters, substitutions" @@ -17,191 +17,191 @@ ms.assetid: d1f52431-1c7d-4dc6-8792-6b988256892e --- # Substitutions in Regular Expressions -Substitutions are language elements that are recognized only within replacement patterns. They use a regular expression pattern to define all or part of the text that is to replace matched text in the input string. The replacement pattern can consist of one or more substitutions along with literal characters. Replacement patterns are provided to overloads of the method that have a `replacement` parameter and to the method. The methods replace the matched pattern with the pattern that is defined by the `replacement` parameter. - - .NET defines the substitution elements listed in the following table. - -|Substitution|Description| -|------------------|-----------------| -|$ *number*|Includes the last substring matched by the capturing group that is identified by *number*, where *number* is a decimal value, in the replacement string. For more information, see [Substituting a Numbered Group](#substituting-a-numbered-group).| -|${ *name* }|Includes the last substring matched by the named group that is designated by `(?<`*name*`> )` in the replacement string. For more information, see [Substituting a Named Group](#substituting-a-named-group).| -|$$|Includes a single "$" literal in the replacement string. For more information, see [Substituting a "$" Symbol](#substituting-a--character).| -|$&|Includes a copy of the entire match in the replacement string. For more information, see [Substituting the Entire Match](#substituting-the-entire-match).| -|$\`|Includes all the text of the input string before the match in the replacement string. For more information, see [Substituting the Text before the Match](#substituting-the-text-before-the-match).| -|$'|Includes all the text of the input string after the match in the replacement string. For more information, see [Substituting the Text after the Match](#substituting-the-text-after-the-match).| -|$+|Includes the last group captured in the replacement string. For more information, see [Substituting the Last Captured Group](#substituting-the-last-captured-group).| -|$\_|Includes the entire input string in the replacement string. For more information, see [Substituting the Entire Input String](#substituting-the-entire-input-string).| - -## Substitution Elements and Replacement Patterns - - Substitutions are the only special constructs recognized in a replacement pattern. None of the other regular expression language elements, including character escapes and the period (`.`), which matches any character, are supported. Similarly, substitution language elements are recognized only in replacement patterns and are never valid in regular expression patterns. - - The only character that can appear either in a regular expression pattern or in a substitution is the `$` character, although it has a different meaning in each context. In a regular expression pattern, `$` is an anchor that matches the end of the string. In a replacement pattern, `$` indicates the beginning of a substitution. - +Substitutions are language elements that are recognized only within replacement patterns. They use a regular expression pattern to define all or part of the text that is to replace matched text in the input string. The replacement pattern can consist of one or more substitutions along with literal characters. Replacement patterns are provided to overloads of the method that have a `replacement` parameter and to the method. The methods replace the matched pattern with the pattern that is defined by the `replacement` parameter. + + .NET defines the substitution elements listed in the following table. + +|Substitution|Description| +|------------------|-----------------| +|$ *number*|Includes the last substring matched by the capturing group that is identified by *number*, where *number* is a decimal value, in the replacement string. For more information, see [Substituting a Numbered Group](#substituting-a-numbered-group).| +|${ *name* }|Includes the last substring matched by the named group that is designated by `(?<`*name*`> )` in the replacement string. For more information, see [Substituting a Named Group](#substituting-a-named-group).| +|$$|Includes a single "$" literal in the replacement string. For more information, see [Substituting a "$" Symbol](#substituting-a--character).| +|$&|Includes a copy of the entire match in the replacement string. For more information, see [Substituting the Entire Match](#substituting-the-entire-match).| +|$\`|Includes all the text of the input string before the match in the replacement string. For more information, see [Substituting the Text before the Match](#substituting-the-text-before-the-match).| +|$'|Includes all the text of the input string after the match in the replacement string. For more information, see [Substituting the Text after the Match](#substituting-the-text-after-the-match).| +|$+|Includes the last group captured in the replacement string. For more information, see [Substituting the Last Captured Group](#substituting-the-last-captured-group).| +|$\_|Includes the entire input string in the replacement string. For more information, see [Substituting the Entire Input String](#substituting-the-entire-input-string).| + +## Substitution Elements and Replacement Patterns + + Substitutions are the only special constructs recognized in a replacement pattern. None of the other regular expression language elements, including character escapes and the period (`.`), which matches any character, are supported. Similarly, substitution language elements are recognized only in replacement patterns and are never valid in regular expression patterns. + + The only character that can appear either in a regular expression pattern or in a substitution is the `$` character, although it has a different meaning in each context. In a regular expression pattern, `$` is an anchor that matches the end of the string. In a replacement pattern, `$` indicates the beginning of a substitution. + > [!NOTE] -> For functionality similar to a replacement pattern within a regular expression, use a backreference. For more information about backreferences, see [Backreference Constructs](backreference-constructs-in-regular-expressions.md). - -## Substituting a Numbered Group - - The `$`*number* language element includes the last substring matched by the *number* capturing group in the replacement string, where *number* is the index of the capturing group. For example, the replacement pattern `$1` indicates that the matched substring is to be replaced by the first captured group. For more information about numbered capturing groups, see [Grouping Constructs](grouping-constructs-in-regular-expressions.md). - - All digits that follow `$` are interpreted as belonging to the *number* group. If this is not your intent, you can substitute a named group instead. For example, you can use the replacement string `${1}1` instead of `$11` to define the replacement string as the value of the first captured group along with the number "1". For more information, see [Substituting a Named Group](#substituting-a-named-group). - - Capturing groups that are not explicitly assigned names using the `(?<`*name*`>)` syntax are numbered from left to right starting at one. Named groups are also numbered from left to right, starting at one greater than the index of the last unnamed group. For example, in the regular expression `(\w)(?\d)`, the index of the `digit` named group is 2. - - If *number* does not specify a valid capturing group defined in the regular expression pattern, `$`*number* is interpreted as a literal character sequence that is used to replace each match. - - The following example uses the `$`*number* substitution to strip the currency symbol from a decimal value. It removes currency symbols found at the beginning or end of a monetary value, and recognizes the two most common decimal separators ("." and ","). - +> For functionality similar to a replacement pattern within a regular expression, use a backreference. For more information about backreferences, see [Backreference Constructs](backreference-constructs-in-regular-expressions.md). + +## Substituting a Numbered Group + + The `$`*number* language element includes the last substring matched by the *number* capturing group in the replacement string, where *number* is the index of the capturing group. For example, the replacement pattern `$1` indicates that the matched substring is to be replaced by the first captured group. For more information about numbered capturing groups, see [Grouping Constructs](grouping-constructs-in-regular-expressions.md). + + All digits that follow `$` are interpreted as belonging to the *number* group. If this is not your intent, you can substitute a named group instead. For example, you can use the replacement string `${1}1` instead of `$11` to define the replacement string as the value of the first captured group along with the number "1". For more information, see [Substituting a Named Group](#substituting-a-named-group). + + Capturing groups that are not explicitly assigned names using the `(?<`*name*`>)` syntax are numbered from left to right starting at one. Named groups are also numbered from left to right, starting at one greater than the index of the last unnamed group. For example, in the regular expression `(\w)(?\d)`, the index of the `digit` named group is 2. + + If *number* does not specify a valid capturing group defined in the regular expression pattern, `$`*number* is interpreted as a literal character sequence that is used to replace each match. + + The following example uses the `$`*number* substitution to strip the currency symbol from a decimal value. It removes currency symbols found at the beginning or end of a monetary value, and recognizes the two most common decimal separators ("." and ","). + [!code-csharp[Conceptual.RegEx.Language.Substitutions#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.substitutions/cs/numberedgroup1.cs#1)] - [!code-vb[Conceptual.RegEx.Language.Substitutions#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/numberedgroup1.vb#1)] - - The regular expression pattern `\p{Sc}*(\s?\d+[.,]?\d*)\p{Sc}*` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\p{Sc}*`|Match zero or more currency symbol characters.| -|`\s?`|Match zero or one white-space characters.| -|`\d+`|Match one or more decimal digits.| -|`[.,]?`|Match zero or one period or comma.| -|`\d*`|Match zero or more decimal digits.| -|`(\s?\d+[.,]?\d*)`|Match a white space followed by one or more decimal digits, followed by zero or one period or comma, followed by zero or more decimal digits. This is the first capturing group. Because the replacement pattern is `$1`, the call to the method replaces the entire matched substring with this captured group.| - -## Substituting a Named Group - - The `${`*name*`}` language element substitutes the last substring matched by the *name* capturing group, where *name* is the name of a capturing group defined by the `(?<`*name*`>)` language element. For more information about named capturing groups, see [Grouping Constructs](grouping-constructs-in-regular-expressions.md). - - If *name* doesn't specify a valid named capturing group defined in the regular expression pattern but consists of digits, `${`*name*`}` is interpreted as a numbered group. - - If *name* specifies neither a valid named capturing group nor a valid numbered capturing group defined in the regular expression pattern, `${`*name*`}` is interpreted as a literal character sequence that is used to replace each match. - - The following example uses the `${`*name*`}` substitution to strip the currency symbol from a decimal value. It removes currency symbols found at the beginning or end of a monetary value, and recognizes the two most common decimal separators ("." and ","). - + [!code-vb[Conceptual.RegEx.Language.Substitutions#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/numberedgroup1.vb#1)] + + The regular expression pattern `\p{Sc}*(\s?\d+[.,]?\d*)\p{Sc}*` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\p{Sc}*`|Match zero or more currency symbol characters.| +|`\s?`|Match zero or one white-space characters.| +|`\d+`|Match one or more decimal digits.| +|`[.,]?`|Match zero or one period or comma.| +|`\d*`|Match zero or more decimal digits.| +|`(\s?\d+[.,]?\d*)`|Match a white space followed by one or more decimal digits, followed by zero or one period or comma, followed by zero or more decimal digits. This is the first capturing group. Because the replacement pattern is `$1`, the call to the method replaces the entire matched substring with this captured group.| + +## Substituting a Named Group + + The `${`*name*`}` language element substitutes the last substring matched by the *name* capturing group, where *name* is the name of a capturing group defined by the `(?<`*name*`>)` language element. For more information about named capturing groups, see [Grouping Constructs](grouping-constructs-in-regular-expressions.md). + + If *name* doesn't specify a valid named capturing group defined in the regular expression pattern but consists of digits, `${`*name*`}` is interpreted as a numbered group. + + If *name* specifies neither a valid named capturing group nor a valid numbered capturing group defined in the regular expression pattern, `${`*name*`}` is interpreted as a literal character sequence that is used to replace each match. + + The following example uses the `${`*name*`}` substitution to strip the currency symbol from a decimal value. It removes currency symbols found at the beginning or end of a monetary value, and recognizes the two most common decimal separators ("." and ","). + [!code-csharp[Conceptual.RegEx.Language.Substitutions#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.substitutions/cs/namedgroup1.cs#2)] - [!code-vb[Conceptual.RegEx.Language.Substitutions#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/namedgroup1.vb#2)] - - The regular expression pattern `\p{Sc}*(?\s?\d[.,]?\d*)\p{Sc}*` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\p{Sc}*`|Match zero or more currency symbol characters.| -|`\s?`|Match zero or one white-space characters.| -|`\d+`|Match one or more decimal digits.| -|`[.,]?`|Match zero or one period or comma.| -|`\d*`|Match zero or more decimal digits.| -|`(?\s?\d[.,]?\d*)`|Match a white space, followed by one or more decimal digits, followed by zero or one period or comma, followed by zero or more decimal digits. This is the capturing group named `amount`. Because the replacement pattern is `${amount}`, the call to the method replaces the entire matched substring with this captured group.| - -## Substituting a "$" Character - - The `$$` substitution inserts a literal "$" character in the replaced string. - - The following example uses the object to determine the current culture's currency symbol and its placement in a currency string. It then builds both a regular expression pattern and a replacement pattern dynamically. If the example is run on a computer whose current culture is en-US, it generates the regular expression pattern `\b(\d+)(\.(\d+))?` and the replacement pattern `$$ $1$2`. The replacement pattern replaces the matched text with a currency symbol and a space followed by the first and second captured groups. - + [!code-vb[Conceptual.RegEx.Language.Substitutions#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/namedgroup1.vb#2)] + + The regular expression pattern `\p{Sc}*(?\s?\d[.,]?\d*)\p{Sc}*` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\p{Sc}*`|Match zero or more currency symbol characters.| +|`\s?`|Match zero or one white-space characters.| +|`\d+`|Match one or more decimal digits.| +|`[.,]?`|Match zero or one period or comma.| +|`\d*`|Match zero or more decimal digits.| +|`(?\s?\d[.,]?\d*)`|Match a white space, followed by one or more decimal digits, followed by zero or one period or comma, followed by zero or more decimal digits. This is the capturing group named `amount`. Because the replacement pattern is `${amount}`, the call to the method replaces the entire matched substring with this captured group.| + +## Substituting a "$" Character + + The `$$` substitution inserts a literal "$" character in the replaced string. + + The following example uses the object to determine the current culture's currency symbol and its placement in a currency string. It then builds both a regular expression pattern and a replacement pattern dynamically. If the example is run on a computer whose current culture is en-US, it generates the regular expression pattern `\b(\d+)(\.(\d+))?` and the replacement pattern `$$ $1$2`. The replacement pattern replaces the matched text with a currency symbol and a space followed by the first and second captured groups. + [!code-csharp[Conceptual.Regex.Language.Substitutions#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.substitutions/cs/dollarsign1.cs#8)] - [!code-vb[Conceptual.Regex.Language.Substitutions#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/dollarsign1.vb#8)] - - The regular expression pattern `\b(\d+)(\.(\d+))?` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Start the match at the beginning of a word boundary.| -|`(\d+)`|Match one or more decimal digits. This is the first capturing group.| -|`\.`|Match a period (the decimal separator).| -|`(\d+)`|Match one or more decimal digits. This is the third capturing group.| -|`(\.(\d+))?`|Match zero or one occurrence of a period followed by one or more decimal digits. This is the second capturing group.| - -## Substituting the Entire Match - - The `$&` substitution includes the entire match in the replacement string. Often, it is used to add a substring to the beginning or end of the matched string. For example, the `($&)` replacement pattern adds parentheses to the beginning and end of each match. If there is no match, the `$&` substitution has no effect. - - The following example uses the `$&` substitution to add quotation marks at the beginning and end of book titles stored in a string array. - + [!code-vb[Conceptual.Regex.Language.Substitutions#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/dollarsign1.vb#8)] + + The regular expression pattern `\b(\d+)(\.(\d+))?` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Start the match at the beginning of a word boundary.| +|`(\d+)`|Match one or more decimal digits. This is the first capturing group.| +|`\.`|Match a period (the decimal separator).| +|`(\d+)`|Match one or more decimal digits. This is the third capturing group.| +|`(\.(\d+))?`|Match zero or one occurrence of a period followed by one or more decimal digits. This is the second capturing group.| + +## Substituting the Entire Match + + The `$&` substitution includes the entire match in the replacement string. Often, it is used to add a substring to the beginning or end of the matched string. For example, the `($&)` replacement pattern adds parentheses to the beginning and end of each match. If there is no match, the `$&` substitution has no effect. + + The following example uses the `$&` substitution to add quotation marks at the beginning and end of book titles stored in a string array. + [!code-csharp[Conceptual.RegEx.Language.Substitutions#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.substitutions/cs/entirematch1.cs#3)] - [!code-vb[Conceptual.RegEx.Language.Substitutions#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/entirematch1.vb#3)] - - The regular expression pattern `^(\w+\s?)+$` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`^`|Start the match at the beginning of the input string.| -|`(\w+\s?)+`|Match the pattern of one or more word characters followed by zero or one white-space characters one or more times.| -|`$`|Match the end of the input string.| - - The `"$&"` replacement pattern adds a literal quotation mark to the beginning and end of each match. - -## Substituting the Text Before the Match - - The ``$` `` substitution replaces the matched string with the entire input string before the match. That is, it duplicates the input string up to the match while removing the matched text. Any text that follows the matched text is unchanged in the result string. If there are multiple matches in an input string, the replacement text is derived from the original input string, rather than from the string in which text has been replaced by earlier matches. \(The example provides an illustration.\) If there is no match, the ``$` `` substitution has no effect. - - The following example uses the regular expression pattern `\d+` to match a sequence of one or more decimal digits in the input string. The replacement string ``$` `` replaces these digits with the text that precedes the match. - + [!code-vb[Conceptual.RegEx.Language.Substitutions#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/entirematch1.vb#3)] + + The regular expression pattern `^(\w+\s?)+$` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`^`|Start the match at the beginning of the input string.| +|`(\w+\s?)+`|Match the pattern of one or more word characters followed by zero or one white-space characters one or more times.| +|`$`|Match the end of the input string.| + + The `"$&"` replacement pattern adds a literal quotation mark to the beginning and end of each match. + +## Substituting the Text Before the Match + + The ``$` `` substitution replaces the matched string with the entire input string before the match. That is, it duplicates the input string up to the match while removing the matched text. Any text that follows the matched text is unchanged in the result string. If there are multiple matches in an input string, the replacement text is derived from the original input string, rather than from the string in which text has been replaced by earlier matches. \(The example provides an illustration.\) If there is no match, the ``$` `` substitution has no effect. + + The following example uses the regular expression pattern `\d+` to match a sequence of one or more decimal digits in the input string. The replacement string ``$` `` replaces these digits with the text that precedes the match. + [!code-csharp[Conceptual.Regex.Language.Substitutions#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.substitutions/cs/before1.cs#4)] - [!code-vb[Conceptual.Regex.Language.Substitutions#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/before1.vb#4)] - - In this example, the input string `"aa1bb2cc3dd4ee5"` contains five matches. The following table illustrates how the ``$` `` substitution causes the regular expression engine to replace each match in the input string. Inserted text is shown in bold in the results column. - -|Match|Position|String before match|Result string| -|-----------|--------------|-------------------------|-------------------| -|1|2|aa|aa**aa**bb2cc3dd4ee5| -|2|5|aa1bb|aaaabb**aa1bb**cc3dd4ee5| -|3|8|aa1bb2cc|aaaabbaa1bbcc**aa1bb2cc**dd4ee5| -|4|11|aa1bb2cc3dd|aaaabbaa1bbccaa1bb2ccdd**aa1bb2cc3dd**ee5| + [!code-vb[Conceptual.Regex.Language.Substitutions#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/before1.vb#4)] + + In this example, the input string `"aa1bb2cc3dd4ee5"` contains five matches. The following table illustrates how the ``$` `` substitution causes the regular expression engine to replace each match in the input string. Inserted text is shown in bold in the results column. + +|Match|Position|String before match|Result string| +|-----------|--------------|-------------------------|-------------------| +|1|2|aa|aa**aa**bb2cc3dd4ee5| +|2|5|aa1bb|aaaabb**aa1bb**cc3dd4ee5| +|3|8|aa1bb2cc|aaaabbaa1bbcc**aa1bb2cc**dd4ee5| +|4|11|aa1bb2cc3dd|aaaabbaa1bbccaa1bb2ccdd**aa1bb2cc3dd**ee5| |5|14|aa1bb2cc3dd4ee|aaaabbaa1bbccaa1bb2ccddaa1bb2cc3ddee**aa1bb2cc3dd4ee**| -## Substituting the Text After the Match +## Substituting the Text After the Match + + The `$'` substitution replaces the matched string with the entire input string after the match. That is, it duplicates the input string after the match while removing the matched text. Any text that precedes the matched text is unchanged in the result string. If there is no match, the `$'` substitution has no effect. + + The following example uses the regular expression pattern `\d+` to match a sequence of one or more decimal digits in the input string. The replacement string `$'` replaces these digits with the text that follows the match. - The `$'` substitution replaces the matched string with the entire input string after the match. That is, it duplicates the input string after the match while removing the matched text. Any text that precedes the matched text is unchanged in the result string. If there is no match, the `$'` substitution has no effect. - - The following example uses the regular expression pattern `\d+` to match a sequence of one or more decimal digits in the input string. The replacement string `$'` replaces these digits with the text that follows the match. - [!code-csharp[Conceptual.Regex.Language.Substitutions#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.substitutions/cs/after1.cs#5)] - [!code-vb[Conceptual.Regex.Language.Substitutions#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/after1.vb#5)] - - In this example, the input string `"aa1bb2cc3dd4ee5"` contains five matches. The following table illustrates how the `$'` substitution causes the regular expression engine to replace each match in the input string. Inserted text is shown in bold in the results column. - -|Match|Position|String after match|Result string| -|-----------|--------------|------------------------|-------------------| -|1|2|bb2cc3dd4ee5|aa**bb2cc3dd4ee5**bb2cc3dd4ee5| -|2|5|cc3dd4ee5|aabb2cc3dd4ee5bb**cc3dd4ee5**cc3dd4ee5| -|3|8|dd4ee5|aabb2cc3dd4ee5bbcc3dd4ee5cc**dd4ee5**dd4ee5| -|4|11|ee5|aabb2cc3dd4ee5bbcc3dd4ee5ccdd4ee5dd**ee5**ee5| -|5|14||aabb2cc3dd4ee5bbcc3dd4ee5ccdd4ee5ddee5ee| - -## Substituting the Last Captured Group - - The `$+` substitution replaces the matched string with the last captured group. If there are no captured groups or if the value of the last captured group is , the `$+` substitution has no effect. - - The following example identifies duplicate words in a string and uses the `$+` substitution to replace them with a single occurrence of the word. The option is used to ensure that words that differ in case but that are otherwise identical are considered duplicates. - + [!code-vb[Conceptual.Regex.Language.Substitutions#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/after1.vb#5)] + + In this example, the input string `"aa1bb2cc3dd4ee5"` contains five matches. The following table illustrates how the `$'` substitution causes the regular expression engine to replace each match in the input string. Inserted text is shown in bold in the results column. + +|Match|Position|String after match|Result string| +|-----------|--------------|------------------------|-------------------| +|1|2|bb2cc3dd4ee5|aa**bb2cc3dd4ee5**bb2cc3dd4ee5| +|2|5|cc3dd4ee5|aabb2cc3dd4ee5bb**cc3dd4ee5**cc3dd4ee5| +|3|8|dd4ee5|aabb2cc3dd4ee5bbcc3dd4ee5cc**dd4ee5**dd4ee5| +|4|11|ee5|aabb2cc3dd4ee5bbcc3dd4ee5ccdd4ee5dd**ee5**ee5| +|5|14||aabb2cc3dd4ee5bbcc3dd4ee5ccdd4ee5ddee5ee| + +## Substituting the Last Captured Group + + The `$+` substitution replaces the matched string with the last captured group. If there are no captured groups or if the value of the last captured group is , the `$+` substitution has no effect. + + The following example identifies duplicate words in a string and uses the `$+` substitution to replace them with a single occurrence of the word. The option is used to ensure that words that differ in case but that are otherwise identical are considered duplicates. + [!code-csharp[Conceptual.Regex.Language.Substitutions#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.substitutions/cs/lastmatch1.cs#6)] - [!code-vb[Conceptual.Regex.Language.Substitutions#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/lastmatch1.vb#6)] - - The regular expression pattern `\b(\w+)\s\1\b` is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`(\w+)`|Match one or more word characters. This is the first capturing group.| -|`\s`|Match a white-space character.| -|`\1`|Match the first captured group.| -|`\b`|End the match at a word boundary.| - -## Substituting the Entire Input String - - The `$_` substitution replaces the matched string with the entire input string. That is, it removes the matched text and replaces it with the entire string, including the matched text. - - The following example matches one or more decimal digits in the input string. It uses the `$_` substitution to replace them with the entire input string. - + [!code-vb[Conceptual.Regex.Language.Substitutions#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/lastmatch1.vb#6)] + + The regular expression pattern `\b(\w+)\s\1\b` is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`(\w+)`|Match one or more word characters. This is the first capturing group.| +|`\s`|Match a white-space character.| +|`\1`|Match the first captured group.| +|`\b`|End the match at a word boundary.| + +## Substituting the Entire Input String + + The `$_` substitution replaces the matched string with the entire input string. That is, it removes the matched text and replaces it with the entire string, including the matched text. + + The following example matches one or more decimal digits in the input string. It uses the `$_` substitution to replace them with the entire input string. + [!code-csharp[Conceptual.Regex.Language.Substitutions#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.substitutions/cs/entire1.cs#7)] - [!code-vb[Conceptual.Regex.Language.Substitutions#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/entire1.vb#7)] - - In this example, the input string `"ABC123DEF456"` contains two matches. The following table illustrates how the `$_` substitution causes the regular expression engine to replace each match in the input string. Inserted text is shown in bold in the results column. - -|Match|Position|Match|Result string| -|-----------|--------------|-----------|-------------------| -|1|3|123|ABC**ABC123DEF456**DEF456| -|2|5|456|ABCABC123DEF456DEF**ABC123DEF456**| - + [!code-vb[Conceptual.Regex.Language.Substitutions#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/entire1.vb#7)] + + In this example, the input string `"ABC123DEF456"` contains two matches. The following table illustrates how the `$_` substitution causes the regular expression engine to replace each match in the input string. Inserted text is shown in bold in the results column. + +|Match|Position|Match|Result string| +|-----------|--------------|-----------|-------------------| +|1|3|123|ABC**ABC123DEF456**DEF456| +|2|5|456|ABCABC123DEF456DEF**ABC123DEF456**| + ## See also - [Regular Expression Language - Quick Reference](regular-expression-language-quick-reference.md) diff --git a/docs/standard/base-types/the-regular-expression-object-model.md b/docs/standard/base-types/the-regular-expression-object-model.md index 416160e1d1087..e7143d01aef87 100644 --- a/docs/standard/base-types/the-regular-expression-object-model.md +++ b/docs/standard/base-types/the-regular-expression-object-model.md @@ -63,7 +63,7 @@ This article describes the object model used in working with .NET regular expres ### Match a regular expression pattern - The method returns `true` if the string matches the pattern, or `false` if it does not. The method is often used to validate string input. For example, the following code ensures that a string matches a valid social security number in the United States. + The method returns `true` if the string matches the pattern, or `false` if it does not. The method is often used to validate string input. For example, the following code ensures that a string matches a valid social security number in the United States. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/validate1.cs#1)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/validate1.vb#1)] @@ -82,7 +82,7 @@ This article describes the object model used in working with .NET regular expres ### Extract a single match or the first match - The method returns a object that contains information about the first substring that matches a regular expression pattern. If the `Match.Success` property returns `true`, indicating that a match was found, you can retrieve information about subsequent matches by calling the method. These method calls can continue until the `Match.Success` property returns `false`. For example, the following code uses the method to find the first occurrence of a duplicated word in a string. It then calls the method to find any additional occurrences. The example examines the `Match.Success` property after each method call to determine whether the current match was successful and whether a call to the method should follow. + The method returns a object that contains information about the first substring that matches a regular expression pattern. If the `Match.Success` property returns `true`, indicating that a match was found, you can retrieve information about subsequent matches by calling the method. These method calls can continue until the `Match.Success` property returns `false`. For example, the following code uses the method to find the first occurrence of a duplicated word in a string. It then calls the method to find any additional occurrences. The example examines the `Match.Success` property after each method call to determine whether the current match was successful and whether a call to the method should follow. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/match1.cs#2)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/match1.vb#2)] @@ -99,14 +99,14 @@ This article describes the object model used in working with .NET regular expres ### Extract all matches - The method returns a object that contains information about all matches that the regular expression engine found in the input string. For example, the previous example could be rewritten to call the method instead of the and methods. + The method returns a object that contains information about all matches that the regular expression engine found in the input string. For example, the previous example could be rewritten to call the method instead of the and methods. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/matches1.cs#3)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/matches1.vb#3)] ### Replace a matched substring - The method replaces each substring that matches the regular expression pattern with a specified string or regular expression pattern, and returns the entire input string with replacements. For example, the following code adds a U.S. currency symbol before a decimal number in a string. + The method replaces each substring that matches the regular expression pattern with a specified string or regular expression pattern, and returns the entire input string with replacements. For example, the following code adds a U.S. currency symbol before a decimal number in a string. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/replace1.cs#4)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/replace1.vb#4)] @@ -130,7 +130,7 @@ This article describes the object model used in working with .NET regular expres ### Split a single string into an array of strings - The method splits the input string at the positions defined by a regular expression match. For example, the following code places the items in a numbered list into a string array. + The method splits the input string at the positions defined by a regular expression match. For example, the following code places the items in a numbered list into a string array. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/split1.cs#5)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/split1.vb#5)] @@ -150,9 +150,9 @@ This article describes the object model used in working with .NET regular expres ### The `MatchCollection` class - The method returns a object that contains objects that represent all the matches that the regular expression engine found, in the order in which they occur in the input string. If there are no matches, the method returns a object with no members. The property lets you access individual members of the collection by index, from zero to one less than the value of the property. is the collection's indexer (in C#) and default property (in Visual Basic). + The method returns a object that contains objects that represent all the matches that the regular expression engine found, in the order in which they occur in the input string. If there are no matches, the method returns a object with no members. The property lets you access individual members of the collection by index, from zero to one less than the value of the property. is the collection's indexer (in C#) and default property (in Visual Basic). - By default, the call to the method uses lazy evaluation to populate the object. Access to properties that require a fully populated collection, such as the and properties, may involve a performance penalty. As a result, we recommend that you access the collection by using the object that is returned by the method. Individual languages provide constructs, such as `For Each` in Visual Basic and `foreach` in C#, that wrap the collection's interface. + By default, the call to the method uses lazy evaluation to populate the object. Access to properties that require a fully populated collection, such as the and properties, may involve a performance penalty. As a result, we recommend that you access the collection by using the object that is returned by the method. Individual languages provide constructs, such as `For Each` in Visual Basic and `foreach` in C#, that wrap the collection's interface. The following example uses the method to populate a object with all the matches found in an input string. The example enumerates the collection, copies the matches to a string array, and records the character positions in an integer array. @@ -163,23 +163,23 @@ This article describes the object model used in working with .NET regular expres The class represents the result of a single regular expression match. You can access objects in two ways: -- By retrieving them from the object that is returned by the method. To retrieve individual objects, iterate the collection by using a `foreach` (in C#) or `For Each`...`Next` (in Visual Basic) construct, or use the property to retrieve a specific object either by index or by name. You can also retrieve individual objects from the collection by iterating the collection by index, from zero to one less that the number of objects in the collection. However, this method does not take advantage of lazy evaluation, because it accesses the property. +- By retrieving them from the object that is returned by the method. To retrieve individual objects, iterate the collection by using a `foreach` (in C#) or `For Each`...`Next` (in Visual Basic) construct, or use the property to retrieve a specific object either by index or by name. You can also retrieve individual objects from the collection by iterating the collection by index, from zero to one less that the number of objects in the collection. However, this method does not take advantage of lazy evaluation, because it accesses the property. The following example retrieves individual objects from a object by iterating the collection using the `foreach` or `For Each`...`Next` construct. The regular expression simply matches the string "abc" in the input string. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/match2.cs#7)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/match2.vb#7)] -- By calling the method, which returns a object that represents the first match in a string or a portion of a string. You can determine whether the match has been found by retrieving the value of the `Match.Success` property. To retrieve objects that represent subsequent matches, call the method repeatedly, until the `Success` property of the returned object is `false`. +- By calling the method, which returns a object that represents the first match in a string or a portion of a string. You can determine whether the match has been found by retrieving the value of the `Match.Success` property. To retrieve objects that represent subsequent matches, call the method repeatedly, until the `Success` property of the returned object is `false`. - The following example uses the and methods to match the string "abc" in the input string. + The following example uses the and methods to match the string "abc" in the input string. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/match3.cs#8)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/match3.vb#8)] Two properties of the class return collection objects: -- The property returns a object that contains information about the substrings that match capturing groups in the regular expression pattern. +- The property returns a object that contains information about the substrings that match capturing groups in the regular expression pattern. - The `Match.Captures` property returns a object that is of limited use. The collection is not populated for a object whose `Success` property is `false`. Otherwise, it contains a single object that has the same information as the object. @@ -189,11 +189,11 @@ Two additional properties of the cla The class also has two pattern-matching methods: -- The method finds the match after the match represented by the current object, and returns a object that represents that match. +- The method finds the match after the match represented by the current object, and returns a object that represents that match. -- The method performs a specified replacement operation on the matched string and returns the result. +- The method performs a specified replacement operation on the matched string and returns the result. - The following example uses the method to prepend a $ symbol and a space before every number that includes two fractional digits. + The following example uses the method to prepend a $ symbol and a space before every number that includes two fractional digits. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/result1.cs#9)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/result1.vb#9)] @@ -213,11 +213,11 @@ The class also has two pattern-match ## The `GroupCollection` class - The property returns a object that contains objects that represent captured groups in a single match. The first object in the collection (at index 0) represents the entire match. Each object that follows represents the results of a single capturing group. + The property returns a object that contains objects that represent captured groups in a single match. The first object in the collection (at index 0) represents the entire match. Each object that follows represents the results of a single capturing group. - You can retrieve individual objects in the collection by using the property. You can retrieve unnamed groups by their ordinal position in the collection, and retrieve named groups either by name or by ordinal position. Unnamed captures appear first in the collection, and are indexed from left to right in the order in which they appear in the regular expression pattern. Named captures are indexed after unnamed captures, from left to right in the order in which they appear in the regular expression pattern. To determine what numbered groups are available in the collection returned for a particular regular expression matching method, you can call the instance method. To determine what named groups are available in the collection, you can call the instance method. Both methods are particularly useful in general-purpose routines that analyze the matches found by any regular expression. + You can retrieve individual objects in the collection by using the property. You can retrieve unnamed groups by their ordinal position in the collection, and retrieve named groups either by name or by ordinal position. Unnamed captures appear first in the collection, and are indexed from left to right in the order in which they appear in the regular expression pattern. Named captures are indexed after unnamed captures, from left to right in the order in which they appear in the regular expression pattern. To determine what numbered groups are available in the collection returned for a particular regular expression matching method, you can call the instance method. To determine what named groups are available in the collection, you can call the instance method. Both methods are particularly useful in general-purpose routines that analyze the matches found by any regular expression. - The property is the indexer of the collection in C# and the collection object's default property in Visual Basic. This means that individual objects can be accessed by index (or by name, in the case of named groups) as follows: + The property is the indexer of the collection in C# and the collection object's default property in Visual Basic. This means that individual objects can be accessed by index (or by name, in the case of named groups) as follows: [!code-csharp[Conceptual.RegularExpressions.ObjectModel#13](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/groupsyntax1.cs#13)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/groupsyntax1.vb#13)] @@ -242,7 +242,7 @@ The class also has two pattern-match ## The captured group - The class represents the result from a single capturing group. Group objects that represent the capturing groups defined in a regular expression are returned by the property of the object returned by the property. The property is the indexer (in C#) and the default property (in Visual Basic) of the class. You can also retrieve individual members by iterating the collection using the `foreach` or `For Each` construct. For an example, see the previous section. + The class represents the result from a single capturing group. Group objects that represent the capturing groups defined in a regular expression are returned by the property of the object returned by the property. The property is the indexer (in C#) and the default property (in Visual Basic) of the class. You can also retrieve individual members by iterating the collection using the `foreach` or `For Each` construct. For an example, see the previous section. The following example uses nested grouping constructs to capture substrings into groups. The regular expression pattern `(a(b))c` matches the string "abc". It assigns the substring "ab" to the first capturing group, and the substring "b" to the second capturing group. @@ -287,11 +287,11 @@ The class also has two pattern-match ## The `CaptureCollection` class - The object contains information only about the last capture. However, the entire set of captures made by a capturing group is still available from the object that is returned by the property. Each member of the collection is a object that represents a capture made by that capturing group, in the order in which they were captured (and, therefore, in the order in which the captured strings were matched from left to right in the input string). You can retrieve individual objects from the collection in either of two ways: + The object contains information only about the last capture. However, the entire set of captures made by a capturing group is still available from the object that is returned by the property. Each member of the collection is a object that represents a capture made by that capturing group, in the order in which they were captured (and, therefore, in the order in which the captured strings were matched from left to right in the input string). You can retrieve individual objects from the collection in either of two ways: - By iterating through the collection using a construct such as `foreach` (in C#) or `For Each` (in Visual Basic). -- By using the property to retrieve a specific object by index. The property is the object's default property (in Visual Basic) or indexer (in C#). +- By using the property to retrieve a specific object by index. The property is the object's default property (in Visual Basic) or indexer (in C#). If a quantifier is not applied to a capturing group, the object contains a single object that is of little interest, because it provides information about the same match as its object. If a quantifier is applied to a capturing group, the object contains all captures made by the capturing group, and the last member of the collection represents the same capture as the object. @@ -300,14 +300,14 @@ The class also has two pattern-match [!code-csharp[Conceptual.RegularExpressions.ObjectModel#14](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/capturecollection1.cs#14)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/capturecollection1.vb#14)] - The following example uses the regular expression `(Abc)+` to find one or more consecutive runs of the string "Abc" in the string "XYZAbcAbcAbcXYZAbcAb". The example illustrates the use of the property to return multiple groups of captured substrings. + The following example uses the regular expression `(Abc)+` to find one or more consecutive runs of the string "Abc" in the string "XYZAbcAbcAbcXYZAbcAb". The example illustrates the use of the property to return multiple groups of captured substrings. [!code-csharp[RegularExpressions.Classes#5](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Classes/cs/Example.cs#5)] [!code-vb[RegularExpressions.Classes#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Classes/vb/Example.vb#5)] ## The `Capture` class - The class contains the results from a single subexpression capture. The property contains the matched text, and the property indicates the zero-based position in the input string at which the matched substring begins. + The class contains the results from a single subexpression capture. The property contains the matched text, and the property indicates the zero-based position in the input string at which the matched substring begins. The following example parses an input string for the temperature of selected cities. A comma (",") is used to separate a city and its temperature, and a semicolon (";") is used to separate each city's data. The entire input string represents a single match. In the regular expression pattern `((\w+(\s\w+)*),(\d+);)+`, which is used to parse the string, the city name is assigned to the second capturing group, and the temperature is assigned to the fourth capturing group. diff --git a/docs/standard/base-types/trimming.md b/docs/standard/base-types/trimming.md index 7449ff09cb94c..1260b3261c3fe 100644 --- a/docs/standard/base-types/trimming.md +++ b/docs/standard/base-types/trimming.md @@ -21,14 +21,14 @@ If you're parsing a sentence into individual words, you might end up with words |Method name|Use| |-----------------|---------| -||Removes white spaces or characters specified in an array of characters from the beginning and end of a string.| -||Removes characters specified in an array of characters from the end of a string.| -||Removes characters specified in an array of characters from the beginning of a string.| -||Removes a specified number of characters from a specified index position in a string.| +||Removes white spaces or characters specified in an array of characters from the beginning and end of a string.| +||Removes characters specified in an array of characters from the end of a string.| +||Removes characters specified in an array of characters from the beginning of a string.| +||Removes a specified number of characters from a specified index position in a string.| ## Trim - You can easily remove white spaces from both ends of a string by using the method, as shown in the following example: + You can easily remove white spaces from both ends of a string by using the method, as shown in the following example: [!code-csharp[Conceptual.String.BasicOps#17](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/trimming.cs#17)] [!code-vb[Conceptual.String.BasicOps#17](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.string.basicops/vb/trimming.vb#17)] @@ -65,7 +65,7 @@ If you're parsing a sentence into individual words, you might end up with words ## Remove - The method removes a specified number of characters that begin at a specified position in an existing string. This method assumes a zero-based index. + The method removes a specified number of characters that begin at a specified position in an existing string. This method assumes a zero-based index. The following example removes 10 characters from a string beginning at position five of a zero-based index of the string. [!code-csharp[Conceptual.String.BasicOps#21](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/trimming.cs#21)] diff --git a/docs/standard/base-types/type-conversion.md b/docs/standard/base-types/type-conversion.md index 604299e589879..03035d2ba6153 100644 --- a/docs/standard/base-types/type-conversion.md +++ b/docs/standard/base-types/type-conversion.md @@ -162,12 +162,12 @@ The class provides a language-neutral way to perform conve ### Custom conversions with the ChangeType method -In addition to supporting conversions to each of the base types, the class can be used to convert a custom type to one or more predefined types. This conversion is performed by the method, which in turn wraps a call to the method of the `value` parameter. This means that the object represented by the `value` parameter must provide an implementation of the interface. +In addition to supporting conversions to each of the base types, the class can be used to convert a custom type to one or more predefined types. This conversion is performed by the method, which in turn wraps a call to the method of the `value` parameter. This means that the object represented by the `value` parameter must provide an implementation of the interface. > [!NOTE] > Because the and methods use a object to specify the target type to which `value` is converted, they can be used to perform a dynamic conversion to an object whose type is not known at compile time. However, note that the implementation of `value` must still support this conversion. - The following example illustrates a possible implementation of the interface that allows a `TemperatureCelsius` object to be converted to a `TemperatureFahrenheit` object and vice versa. The example defines a base class, `Temperature`, that implements the interface and overrides the method. The derived `TemperatureCelsius` and `TemperatureFahrenheit` classes each override the `ToType` and the `ToString` methods of the base class. + The following example illustrates a possible implementation of the interface that allows a `TemperatureCelsius` object to be converted to a `TemperatureFahrenheit` object and vice versa. The example defines a base class, `Temperature`, that implements the interface and overrides the method. The derived `TemperatureCelsius` and `TemperatureFahrenheit` classes each override the `ToType` and the `ToString` methods of the base class. [!code-csharp[Conceptual.Conversion#10](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.conversion/cs/iconvertible2.cs#10)] [!code-vb[Conceptual.Conversion#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.conversion/vb/iconvertible2.vb#10)] diff --git a/docs/standard/building-console-apps.md b/docs/standard/building-console-apps.md index 0c16726680da7..2cdac1ec1f9c0 100644 --- a/docs/standard/building-console-apps.md +++ b/docs/standard/building-console-apps.md @@ -10,9 +10,9 @@ ms.assetid: c21fb997-9f0e-40a5-8741-f73bba376bd8 --- # Console apps in .NET -.NET applications can use the class to read characters from and write characters to the console. Data from the console is read from the standard input stream, data to the console is written to the standard output stream, and error data to the console is written to the standard error output stream. These streams are automatically associated with the console when the application starts and are presented as the , , and properties, respectively. +.NET applications can use the class to read characters from and write characters to the console. Data from the console is read from the standard input stream, data to the console is written to the standard output stream, and error data to the console is written to the standard error output stream. These streams are automatically associated with the console when the application starts and are presented as the , , and properties, respectively. -The value of the property is a object, whereas the values of the and properties are objects. You can associate these properties with streams that do not represent the console, making it possible for you to point the stream to a different location for input or output. For example, you can redirect the output to a file by setting the property to a , which encapsulates a by means of the method. The and properties do not need to refer to the same stream. +The value of the property is a object, whereas the values of the and properties are objects. You can associate these properties with streams that do not represent the console, making it possible for you to point the stream to a different location for input or output. For example, you can redirect the output to a file by setting the property to a , which encapsulates a by means of the method. The and properties do not need to refer to the same stream. > [!NOTE] > For more information about building console applications, including examples in C#, Visual Basic, and C++, see the documentation for the class. diff --git a/docs/standard/class-library-overview.md b/docs/standard/class-library-overview.md index 9e34f12f75029..c8a7c74eee000 100644 --- a/docs/standard/class-library-overview.md +++ b/docs/standard/class-library-overview.md @@ -47,8 +47,8 @@ The [.NET API reference documentation](../../api/index.md) provides documentatio .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. +- - 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. diff --git a/docs/standard/collections/commonly-used-collection-types.md b/docs/standard/collections/commonly-used-collection-types.md index 292f77110cb44..d4856c8296741 100644 --- a/docs/standard/collections/commonly-used-collection-types.md +++ b/docs/standard/collections/commonly-used-collection-types.md @@ -2,7 +2,7 @@ title: "Commonly Used Collection Types" description: Learn about commonly used collection types in .NET, such as hash tables, queues, stacks, bags, dictionaries, and lists. ms.date: "06/09/2021" -helpviewer_keywords: +helpviewer_keywords: - "collections [.NET], generic" - "objects [.NET], grouping in collections" - "generics [.NET], collections" @@ -17,32 +17,32 @@ ms.assetid: f5d4c6a4-0d7b-4944-a9fb-3b12d9ebfd55 Collection types represent different ways to collect data, such as hash tables, queues, stacks, bags, dictionaries, and lists. -All collections are based on the or interfaces, either directly or indirectly. and and their generic counterparts all derive from these two interfaces. +All collections are based on the or interfaces, either directly or indirectly. and and their generic counterparts all derive from these two interfaces. In collections based on or directly on , every element contains only a value. These types include: - - -- +- - -- +- - -- -- +- +- In collections based on the interface, every element contains both a key and a value. These types include: - - -- -- -- +- +- +- -The class is unique because it is a list of values with keys embedded within the values. As a result, it behaves both like a list and like a dictionary. +The class is unique because it is a list of values with keys embedded within the values. As a result, it behaves both like a list and like a dictionary. When you need efficient multi-threaded collection access, use the generic collections in the namespace. -The and classes provide first-in-first-out lists. The and classes provide last-in-first-out lists. +The and classes provide first-in-first-out lists. The and classes provide last-in-first-out lists. ## Strong typing @@ -53,48 +53,48 @@ Generic collections are the best solution to strong typing. For example, adding - ## How collections vary - + Collections vary in how they store, sort, and compare elements, and how they perform searches. -The class and the generic class provide sorted versions of the class and the generic class. +The class and the generic class provide sorted versions of the class and the generic class. All collections use zero-based indexes except , which allows arrays that are not zero-based. -You can access the elements of a or a by either the key or the element's index. You can only access the elements of a or a by the element's key. +You can access the elements of a or a by either the key or the element's index. You can only access the elements of a or a by the element's key. ## Use LINQ with collection types - -The LINQ to Objects feature provides a common pattern for accessing in-memory objects of any type that implements or . LINQ queries have several benefits over standard constructs like `foreach` loops: + +The LINQ to Objects feature provides a common pattern for accessing in-memory objects of any type that implements or . LINQ queries have several benefits over standard constructs like `foreach` loops: - They are concise and easier to understand. - They can filter, order, and group data. - They can improve performance. - -For more information, see [LINQ to Objects (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), and [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md). - -## Related topics - -|Title|Description| -|-----------|-----------------| -|[Collections and Data Structures](index.md)|Discusses the various collection types available in .NET, including stacks, queues, lists, arrays, and dictionaries.| -|[Hashtable and Dictionary Collection Types](hashtable-and-dictionary-collection-types.md)|Describes the features of generic and nongeneric hash-based dictionary types.| -|[Sorted Collection Types](sorted-collection-types.md)|Describes classes that provide sorting functionality for lists and sets.| -|[Generics](../generics/index.md)|Describes the generics feature, including the generic collections, delegates, and interfaces provided by .NET. Provides links to feature documentation for C#, Visual Basic, and Visual C++, and to supporting technologies such as reflection.| - -## Reference - - - - - - - - - - - - - - - - + +For more information, see [LINQ to Objects (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), and [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md). + +## Related topics + +|Title|Description| +|-----------|-----------------| +|[Collections and Data Structures](index.md)|Discusses the various collection types available in .NET, including stacks, queues, lists, arrays, and dictionaries.| +|[Hashtable and Dictionary Collection Types](hashtable-and-dictionary-collection-types.md)|Describes the features of generic and nongeneric hash-based dictionary types.| +|[Sorted Collection Types](sorted-collection-types.md)|Describes classes that provide sorting functionality for lists and sets.| +|[Generics](../generics/index.md)|Describes the generics feature, including the generic collections, delegates, and interfaces provided by .NET. Provides links to feature documentation for C#, Visual Basic, and Visual C++, and to supporting technologies such as reflection.| + +## Reference + + + + + + + + + + + + + + + + diff --git a/docs/standard/collections/comparisons-and-sorts-within-collections.md b/docs/standard/collections/comparisons-and-sorts-within-collections.md index e7516f8e76eae..266f95406f9cc 100644 --- a/docs/standard/collections/comparisons-and-sorts-within-collections.md +++ b/docs/standard/collections/comparisons-and-sorts-within-collections.md @@ -2,10 +2,10 @@ title: "Comparisons and Sorts Within Collections" description: Do comparisons & sorts using the System.Collections classes in .NET, which help in finding an element to remove or returning the value of a key-and-value pair. ms.date: 04/30/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "sorting data, collections" - "IComparable.CompareTo method" - "Collections classes" @@ -24,13 +24,13 @@ Collections typically utilize an equality comparer and/or an ordering comparer. ## Check for equality -Methods such as `Contains`, , , and `Remove` use an equality comparer for the collection elements. If the collection is generic, then items are compared for equality according to the following guidelines: +Methods such as `Contains`, , , and `Remove` use an equality comparer for the collection elements. If the collection is generic, then items are compared for equality according to the following guidelines: -- If type T implements the generic interface, then the equality comparer is the method of that interface. +- If type T implements the generic interface, then the equality comparer is the method of that interface. -- If type T does not implement , is used. +- If type T does not implement , is used. -In addition, some constructor overloads for dictionary collections accept an implementation, which is used to compare keys for equality. For an example, see the constructor. +In addition, some constructor overloads for dictionary collections accept an implementation, which is used to compare keys for equality. For an example, see the constructor. @@ -40,21 +40,21 @@ Methods such as `BinarySearch` and `Sort` use an ordering comparer for the colle The default comparer relies on at least one of the objects being compared to implement the **IComparable** interface. It is a good practice to implement **IComparable** on all classes which are used as values in a list collection or as keys in a dictionary collection. For a generic collection, equality comparison is determined according to the following: -- If type T implements the generic interface, then the default comparer is the method of that interface +- If type T implements the generic interface, then the default comparer is the method of that interface - If type T implements the non-generic interface, then the default comparer is the method of that interface. - If type T doesn't implement either interface, then there is no default comparer, and a comparer or comparison delegate must be provided explicitly. -To provide explicit comparisons, some methods accept an **IComparer** implementation as a parameter. For example, the method accepts an implementation. +To provide explicit comparisons, some methods accept an **IComparer** implementation as a parameter. For example, the method accepts an implementation. -The current culture setting of the system can affect the comparisons and sorts within a collection. By default, the comparisons and sorts in the **Collections** classes are culture-sensitive. To ignore the culture setting and therefore obtain consistent comparison and sorting results, use the with member overloads that accept a . For more information, see [Perform culture-insensitive string operations in collections](../../core/extensions/performing-culture-insensitive-string-operations-in-collections.md) and [Perform culture-insensitive string operations in arrays](../../core/extensions/performing-culture-insensitive-string-operations-in-arrays.md). +The current culture setting of the system can affect the comparisons and sorts within a collection. By default, the comparisons and sorts in the **Collections** classes are culture-sensitive. To ignore the culture setting and therefore obtain consistent comparison and sorting results, use the with member overloads that accept a . For more information, see [Perform culture-insensitive string operations in collections](../../core/extensions/performing-culture-insensitive-string-operations-in-collections.md) and [Perform culture-insensitive string operations in arrays](../../core/extensions/performing-culture-insensitive-string-operations-in-arrays.md). ## Equality and sort example -The following code demonstrates an implementation of and on a simple business object. In addition, when the object is stored in a list and sorted, you will see that calling the method results in the use of the default comparer for the `Part` type, and the method implemented by using an anonymous method. +The following code demonstrates an implementation of and on a simple business object. In addition, when the object is stored in a list and sorted, you will see that calling the method results in the use of the default comparer for the `Part` type, and the method implemented by using an anonymous method. [!code-csharp[System.Collections.Generic.List.Sort#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.list.sort/cs/program.cs#1)] [!code-vb[System.Collections.Generic.List.Sort#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.sort/vb/module1.vb#1)] @@ -62,7 +62,7 @@ The following code demonstrates an implementation of -- -- +- +- - -- +- diff --git a/docs/standard/collections/hashtable-and-dictionary-collection-types.md b/docs/standard/collections/hashtable-and-dictionary-collection-types.md index 1a5b015875bd4..d83bbb4258807 100644 --- a/docs/standard/collections/hashtable-and-dictionary-collection-types.md +++ b/docs/standard/collections/hashtable-and-dictionary-collection-types.md @@ -2,7 +2,7 @@ description: "Learn more about: Hashtable and Dictionary Collection Types" title: "Hashtable and Dictionary Collection Types" ms.date: "03/30/2017" -\helpviewer_keywords: +\helpviewer_keywords: - "Hashtable class, grouping data in collections" - "Hashtable collection type" - "hash tables" @@ -13,28 +13,28 @@ ms.assetid: bfc20837-3d02-4fc7-8a8f-c5215b6b7913 --- # Hashtable and Dictionary Collection Types -The class, and the and generic classes, implement the interface. The generic class also implements the generic interface. Therefore, each element in these collections is a key-and-value pair. - - A object consists of buckets that contain the elements of the collection. A bucket is a virtual subgroup of elements within the , which makes searching and retrieving easier and faster than in most collections. Each bucket is associated with a hash code, which is generated using a hash function and is based on the key of the element. - - The generic class is an unordered collection for containing unique elements. - - A hash function is an algorithm that returns a numeric hash code based on a key. The key is the value of some property of the object being stored. A hash function must always return the same hash code for the same key. It is possible for a hash function to generate the same hash code for two different keys, but a hash function that generates a unique hash code for each unique key results in better performance when retrieving elements from the hash table. - - Each object that is used as an element in a must be able to generate a hash code for itself by using an implementation of the method. However, you can also specify a hash function for all elements in a by using a constructor that accepts an implementation as one of its parameters. - - When an object is added to a , it is stored in the bucket that is associated with the hash code that matches the object's hash code. When a value is being searched for in the , the hash code is generated for that value, and the bucket associated with that hash code is searched. - - For example, a hash function for a string might take the ASCII codes of each character in the string and add them together to generate a hash code. The string "picnic" would have a hash code that is different from the hash code for the string "basket"; therefore, the strings "picnic" and "basket" would be in different buckets. In contrast, "stressed" and "desserts" would have the same hash code and would be in the same bucket. - - The and classes have the same functionality as the class. A of a specific type (other than ) provides better performance than a for value types. This is because the elements of are of type ; therefore, boxing and unboxing typically occur when you store or retrieve a value type. The class should be used when multiple threads might be accessing the collection simultaneously. - +The class, and the and generic classes, implement the interface. The generic class also implements the generic interface. Therefore, each element in these collections is a key-and-value pair. + + A object consists of buckets that contain the elements of the collection. A bucket is a virtual subgroup of elements within the , which makes searching and retrieving easier and faster than in most collections. Each bucket is associated with a hash code, which is generated using a hash function and is based on the key of the element. + + The generic class is an unordered collection for containing unique elements. + + A hash function is an algorithm that returns a numeric hash code based on a key. The key is the value of some property of the object being stored. A hash function must always return the same hash code for the same key. It is possible for a hash function to generate the same hash code for two different keys, but a hash function that generates a unique hash code for each unique key results in better performance when retrieving elements from the hash table. + + Each object that is used as an element in a must be able to generate a hash code for itself by using an implementation of the method. However, you can also specify a hash function for all elements in a by using a constructor that accepts an implementation as one of its parameters. + + When an object is added to a , it is stored in the bucket that is associated with the hash code that matches the object's hash code. When a value is being searched for in the , the hash code is generated for that value, and the bucket associated with that hash code is searched. + + For example, a hash function for a string might take the ASCII codes of each character in the string and add them together to generate a hash code. The string "picnic" would have a hash code that is different from the hash code for the string "basket"; therefore, the strings "picnic" and "basket" would be in different buckets. In contrast, "stressed" and "desserts" would have the same hash code and would be in the same bucket. + + The and classes have the same functionality as the class. A of a specific type (other than ) provides better performance than a for value types. This is because the elements of are of type ; therefore, boxing and unboxing typically occur when you store or retrieve a value type. The class should be used when multiple threads might be accessing the collection simultaneously. + ## See also - - - -- -- -- +- +- +- - [Commonly Used Collection Types](commonly-used-collection-types.md) diff --git a/docs/standard/collections/index.md b/docs/standard/collections/index.md index 150bc5a4744a7..73920df4652b6 100644 --- a/docs/standard/collections/index.md +++ b/docs/standard/collections/index.md @@ -3,7 +3,7 @@ title: "Collections and Data Structures" description: Learn how to use collections and data structures in .NET. Use generic and non-generic collections in thread-safe operations. ms.date: 10/20/2025 ms.custom: devdivchpfy22 -helpviewer_keywords: +helpviewer_keywords: - "grouping data in collections" - "objects [.NET], grouping in collections" - "Array class, grouping data in collections" @@ -25,11 +25,11 @@ In .NET Framework 4 and later versions, the collections in the interface or the interface share these features: +All collections provide methods for adding, removing, or finding items in the collection. In addition, all collections that directly or indirectly implement the interface or the interface share these features: - **The ability to enumerate the collection** - .NET collections either implement or to enable the collection to be iterated through. An enumerator can be thought of as a movable pointer to any element in the collection. The [foreach, in](../../csharp/language-reference/statements/iteration-statements.md#the-foreach-statement) statement and the [For Each...Next Statement](../../visual-basic/language-reference/statements/for-each-next-statement.md) use the enumerator exposed by the method and hide the complexity of manipulating the enumerator. In addition, any collection that implements is considered a *queryable type* and can be queried with LINQ. LINQ queries provide a common pattern for accessing data. They're typically more concise and readable than standard `foreach` loops and provide filtering, ordering, and grouping capabilities. LINQ queries can also improve performance. For more information, see [LINQ to Objects (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md), [Introduction to LINQ Queries (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), and [Basic Query Operations (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/basic-query-operations.md). + .NET collections either implement or to enable the collection to be iterated through. An enumerator can be thought of as a movable pointer to any element in the collection. The [foreach, in](../../csharp/language-reference/statements/iteration-statements.md#the-foreach-statement) statement and the [For Each...Next Statement](../../visual-basic/language-reference/statements/for-each-next-statement.md) use the enumerator exposed by the method and hide the complexity of manipulating the enumerator. In addition, any collection that implements is considered a *queryable type* and can be queried with LINQ. LINQ queries provide a common pattern for accessing data. They're typically more concise and readable than standard `foreach` loops and provide filtering, ordering, and grouping capabilities. LINQ queries can also improve performance. For more information, see [LINQ to Objects (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md), [Introduction to LINQ Queries (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), and [Basic Query Operations (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/basic-query-operations.md). - **The ability to copy the collection contents to an array** @@ -41,17 +41,17 @@ In addition, many collection classes contain the following features: The capacity of a collection is the number of elements it can contain. The count of a collection is the number of elements it actually contains. Some collections hide the capacity or the count or both. - Most collections automatically expand in capacity when the current capacity is reached. The memory is reallocated, and the elements are copied from the old collection to the new one. This design reduces the code required to use the collection. However, the performance of the collection might be negatively affected. For example, for , if is less than , adding an item is an O(1) operation. If the capacity needs to be increased to accommodate the new element, adding an item becomes an O(`n`) operation, where `n` is . The best way to avoid poor performance caused by multiple reallocations is to set the initial capacity to be the estimated size of the collection. + Most collections automatically expand in capacity when the current capacity is reached. The memory is reallocated, and the elements are copied from the old collection to the new one. This design reduces the code required to use the collection. However, the performance of the collection might be negatively affected. For example, for , if is less than , adding an item is an O(1) operation. If the capacity needs to be increased to accommodate the new element, adding an item becomes an O(`n`) operation, where `n` is . The best way to avoid poor performance caused by multiple reallocations is to set the initial capacity to be the estimated size of the collection. A is a special case; its capacity is the same as its length, which is the same as its count. - **A consistent lower bound** - The lower bound of a collection is the index of its first element. All indexed collections in the namespaces have a lower bound of zero, meaning they're 0-indexed. has a lower bound of zero by default, but a different lower bound can be defined when creating an instance of the **Array** class using . + The lower bound of a collection is the index of its first element. All indexed collections in the namespaces have a lower bound of zero, meaning they're 0-indexed. has a lower bound of zero by default, but a different lower bound can be defined when creating an instance of the **Array** class using . - **Synchronization for access from multiple threads** ( classes only). - Non-generic collection types in the namespace provide some thread safety with synchronization; typically exposed through the and members. These collections aren't thread-safe by default. If you require scalable and efficient multi-threaded access to a collection, use one of the classes in the namespace or consider using an immutable collection. For more information, see [Thread-Safe Collections](thread-safe/index.md). + Non-generic collection types in the namespace provide some thread safety with synchronization; typically exposed through the and members. These collections aren't thread-safe by default. If you require scalable and efficient multi-threaded access to a collection, use one of the classes in the namespace or consider using an immutable collection. For more information, see [Thread-Safe Collections](thread-safe/index.md). @@ -61,14 +61,14 @@ In general, you should use generic collections. The following table describes so |I want to…|Generic collection options|Non-generic collection options|Thread-safe or immutable collection options| |-|-|-|-| -|Store items as key/value pairs for quick look-up by key||

(A collection of key/value pairs that are organized based on the hash code of the key.)|



| -|Access items by index||

|

| -|Use items first-in-first-out (FIFO)|||

| -|Use data Last-In-First-Out (LIFO)|||

| -|Access items sequentially||No recommendation|No recommendation| -|Receive notifications when items are removed or added to the collection. (implements and )||No recommendation|No recommendation| -|A sorted collection|||

| -|A set for mathematical functions|

|No recommendation|

| +|Store items as key/value pairs for quick look-up by key||

(A collection of key/value pairs that are organized based on the hash code of the key.)|



| +|Access items by index||

|

| +|Use items first-in-first-out (FIFO)|||

| +|Use data Last-In-First-Out (LIFO)|||

| +|Access items sequentially||No recommendation|No recommendation| +|Receive notifications when items are removed or added to the collection. (implements and )||No recommendation|No recommendation| +|A sorted collection|||

| +|A set for mathematical functions|

|No recommendation|

| ### Algorithmic complexity of collections @@ -89,7 +89,7 @@ When choosing a [collection class](selecting-a-collection-class.md), it's worth A `List` can be efficiently enumerated using either a `for` loop or a `foreach` loop. An `ImmutableList`, however, does a poor job inside a `for` loop, due to the O(log `n`) time for its indexer. Enumerating an `ImmutableList` using a `foreach` loop is efficient because `ImmutableList` uses a binary tree to store its data instead of an array like `List` uses. An array can be quickly indexed into, whereas a binary tree must be walked down until the node with the desired index is found. -Additionally, `SortedSet` has the same complexity as `ImmutableSortedSet` because they both use binary trees. The significant difference is that `ImmutableSortedSet` uses an immutable binary tree. Since `ImmutableSortedSet` also offers a class that allows mutation, you can have both immutability and performance. +Additionally, `SortedSet` has the same complexity as `ImmutableSortedSet` because they both use binary trees. The significant difference is that `ImmutableSortedSet` uses an immutable binary tree. Since `ImmutableSortedSet` also offers a class that allows mutation, you can have both immutability and performance. @@ -98,12 +98,12 @@ Additionally, `SortedSet` has the same complexity as `ImmutableSortedSet` |Title|Description| |-----------|-----------------| |[Selecting a Collection Class](selecting-a-collection-class.md)|Describes the different collections and helps you select one for your scenario.| -|[Commonly Used Collection Types](commonly-used-collection-types.md)|Describes commonly used generic and non-generic collection types such as , , and .| +|[Commonly Used Collection Types](commonly-used-collection-types.md)|Describes commonly used generic and non-generic collection types such as , , and .| |[When to Use Generic Collections](when-to-use-generic-collections.md)|Discusses the use of generic collection types.| |[Comparisons and Sorts Within Collections](comparisons-and-sorts-within-collections.md)|Discusses the use of equality comparisons and sorting comparisons in collections.| |[Sorted Collection Types](sorted-collection-types.md)|Describes sorted collections performance and characteristics.| |[Hashtable and Dictionary Collection Types](hashtable-and-dictionary-collection-types.md)|Describes the features of generic and non-generic hash-based dictionary types.| -|[Thread-Safe Collections](thread-safe/index.md)|Describes collection types such as and that support safe and efficient concurrent access from multiple threads.| +|[Thread-Safe Collections](thread-safe/index.md)|Describes collection types such as and that support safe and efficient concurrent access from multiple threads.| ||Introduces the immutable collections and provides links to the collection types.| diff --git a/docs/standard/collections/selecting-a-collection-class.md b/docs/standard/collections/selecting-a-collection-class.md index 0459fb3fa23e5..4fb1f5beb48da 100644 --- a/docs/standard/collections/selecting-a-collection-class.md +++ b/docs/standard/collections/selecting-a-collection-class.md @@ -2,7 +2,7 @@ title: "Selecting a Collection Class" description: Learn how to decide which collection class in .NET to choose. Using the wrong type can restrict your use of the collection. ms.date: "03/18/2019" -helpviewer_keywords: +helpviewer_keywords: - "last-in-first-out collections" - "first-in-first-out collections" - "collections [.NET], selecting collection class" @@ -23,33 +23,33 @@ Consider the following questions: - Do you need a sequential list where the element is typically discarded after its value is retrieved? - - If yes, consider using the class or the generic class if you need first-in, first-out (FIFO) behavior. Consider using the class or the generic class if you need last-in, first-out (LIFO) behavior. For safe access from multiple threads, use the concurrent versions, and . For immutability, consider the immutable versions, and . + - If yes, consider using the class or the generic class if you need first-in, first-out (FIFO) behavior. Consider using the class or the generic class if you need last-in, first-out (LIFO) behavior. For safe access from multiple threads, use the concurrent versions, and . For immutability, consider the immutable versions, and . - If not, consider using the other collections. - Do you need to access the elements in a certain order, such as FIFO, LIFO, or random? - - The class, as well as the , , and generic classes all offer FIFO access. For more information, see [When to Use a Thread-Safe Collection](thread-safe/when-to-use-a-thread-safe-collection.md). + - The class, as well as the , , and generic classes all offer FIFO access. For more information, see [When to Use a Thread-Safe Collection](thread-safe/when-to-use-a-thread-safe-collection.md). - - The class, as well as the , , and generic classes all offer LIFO access. For more information, see [When to Use a Thread-Safe Collection](thread-safe/when-to-use-a-thread-safe-collection.md). + - The class, as well as the , , and generic classes all offer LIFO access. For more information, see [When to Use a Thread-Safe Collection](thread-safe/when-to-use-a-thread-safe-collection.md). - - The generic class allows sequential access either from the head to the tail, or from the tail to the head. + - The generic class allows sequential access either from the head to the tail, or from the tail to the head. - Do you need to access each element by index? - - The and classes and the generic class offer access to their elements by the zero-based index of the element. For immutability, consider the immutable generic versions, and . + - The and classes and the generic class offer access to their elements by the zero-based index of the element. For immutability, consider the immutable generic versions, and . - - The , , , and classes, and the and generic classes offer access to their elements by the key of the element. Additionally, there are immutable versions of several corresponding types: , , , and . + - The , , , and classes, and the and generic classes offer access to their elements by the key of the element. Additionally, there are immutable versions of several corresponding types: , , , and . - - The and classes, and the and generic classes offer access to their elements by either the zero-based index or the key of the element. + - The and classes, and the and generic classes offer access to their elements by either the zero-based index or the key of the element. - Will each element contain one value, a combination of one key and one value, or a combination of one key and multiple values? - - One value: Use any of the collections based on the interface or the generic interface. For an immutable option, consider the generic interface. + - One value: Use any of the collections based on the interface or the generic interface. For an immutable option, consider the generic interface. - - One key and one value: Use any of the collections based on the interface or the generic interface. For an immutable option, consider the or generic interfaces. + - One key and one value: Use any of the collections based on the interface or the generic interface. For an immutable option, consider the or generic interfaces. - - One value with embedded key: Use the generic class. + - One value with embedded key: Use the generic class. - One key and multiple values: Use the class. @@ -57,23 +57,23 @@ Consider the following questions: - The class sorts its elements by their hash codes. - - The class, and the and generic classes sort their elements by the key. The sort order is based on the implementation of the interface for the class and on the implementation of the generic interface for the and generic classes. Of the two generic types, offers better performance than , while consumes less memory. + - The class, and the and generic classes sort their elements by the key. The sort order is based on the implementation of the interface for the class and on the implementation of the generic interface for the and generic classes. Of the two generic types, offers better performance than , while consumes less memory. - - provides a method that takes an implementation as a parameter. Its generic counterpart, the generic class, provides a method that takes an implementation of the generic interface as a parameter. + - provides a method that takes an implementation as a parameter. Its generic counterpart, the generic class, provides a method that takes an implementation of the generic interface as a parameter. - Do you need fast searches and retrieval of information? - - is faster than for small collections (10 items or fewer). The generic class provides faster lookup than the generic class. The multi-threaded implementation is . provides fast multi-threaded insertion for unordered data. For more information about both multi-threaded types, see [When to Use a Thread-Safe Collection](thread-safe/when-to-use-a-thread-safe-collection.md). + - is faster than for small collections (10 items or fewer). The generic class provides faster lookup than the generic class. The multi-threaded implementation is . provides fast multi-threaded insertion for unordered data. For more information about both multi-threaded types, see [When to Use a Thread-Safe Collection](thread-safe/when-to-use-a-thread-safe-collection.md). - Do you need collections that accept only strings? - (based on ) and (based on ) are in the namespace. - - In addition, you can use any of the generic collection classes in the namespace as strongly typed string collections by specifying the class for their generic type arguments. For example, you can declare a variable to be of type [List\](xref:System.Collections.Generic.List%601) or [Dictionary](xref:System.Collections.Generic.Dictionary%602). + - In addition, you can use any of the generic collection classes in the namespace as strongly typed string collections by specifying the class for their generic type arguments. For example, you can declare a variable to be of type [List\](xref:System.Collections.Generic.List`1) or [Dictionary](xref:System.Collections.Generic.Dictionary`2). ## LINQ to Objects and PLINQ -LINQ to Objects enables developers to use LINQ queries to access in-memory objects as long as the object type implements or . LINQ queries provide a common pattern for accessing data, are typically more concise and readable than standard `foreach` loops, and provide filtering, ordering, and grouping capabilities. For more information, see [LINQ to Objects (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md) and [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md). +LINQ to Objects enables developers to use LINQ queries to access in-memory objects as long as the object type implements or . LINQ queries provide a common pattern for accessing data, are typically more concise and readable than standard `foreach` loops, and provide filtering, ordering, and grouping capabilities. For more information, see [LINQ to Objects (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md) and [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md). PLINQ provides a parallel implementation of LINQ to Objects that can offer faster query execution in many scenarios, through more efficient use of multi-core computers. For more information, see [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md). diff --git a/docs/standard/collections/sorted-collection-types.md b/docs/standard/collections/sorted-collection-types.md index 0f6ee315efad5..34ade4146e16f 100644 --- a/docs/standard/collections/sorted-collection-types.md +++ b/docs/standard/collections/sorted-collection-types.md @@ -2,7 +2,7 @@ description: "Learn more about: Sorted Collection Types" title: "Sorted Collection Types" ms.date: 04/30/2020 -helpviewer_keywords: +helpviewer_keywords: - "SortedDictionary collection type" - "SortedList class, grouping data in collections" - "grouping data in collections, SortedList collection type" @@ -13,38 +13,38 @@ ms.assetid: 3db965b2-36a6-4b12-b76e-7f074ff7275a # Sorted Collection Types -The class, the generic class, and the generic class are similar to the class and the generic class in that they implement the interface, but they maintain their elements in sort order by key, and they do not have the O(1) insertion and retrieval characteristic of hash tables. The three classes have several features in common: +The class, the generic class, and the generic class are similar to the class and the generic class in that they implement the interface, but they maintain their elements in sort order by key, and they do not have the O(1) insertion and retrieval characteristic of hash tables. The three classes have several features in common: -- All three classes implement the interface. The two generic classes also implement the generic interface. +- All three classes implement the interface. The two generic classes also implement the generic interface. - Each element is a key/value pair for enumeration purposes. > [!NOTE] - > The nongeneric class returns objects when enumerated, although the two generic types return objects. + > The nongeneric class returns objects when enumerated, although the two generic types return objects. -- Elements are sorted according to a implementation (for nongeneric ) or a implementation (for the two generic classes). +- Elements are sorted according to a implementation (for nongeneric ) or a implementation (for the two generic classes). - Each class provides properties that return collections containing only the keys or only the values. -The following table lists some of the differences between the two sorted list classes and the class. +The following table lists some of the differences between the two sorted list classes and the class. -| nongeneric class and generic class | generic class | +| nongeneric class and generic class | generic class | |--|--| | The properties that return keys and values are indexed, allowing efficient indexed retrieval. | No indexed retrieval. | | Retrieval is O(log `n`). | Retrieval is O(log `n`). | | Insertion and removal are generally O(`n`); however, insertion is O(log `n`) for data that are already in sort order, so that each element is added to the end of the list. (This assumes that a resize is not required.) | Insertion and removal are O(log `n`). | -| Uses less memory than a . | Uses more memory than the nongeneric class and the generic class. | +| Uses less memory than a . | Uses more memory than the nongeneric class and the generic class. | -For sorted lists or dictionaries that must be accessible concurrently from multiple threads, you can add sorting logic to a class that derives from . When considering immutability, the following corresponding immutable types follow similar sorting semantics: and . +For sorted lists or dictionaries that must be accessible concurrently from multiple threads, you can add sorting logic to a class that derives from . When considering immutability, the following corresponding immutable types follow similar sorting semantics: and . > [!NOTE] -> For values that contain their own keys (for example, employee records that contain an employee ID number), you can create a keyed collection that has some characteristics of a list and some characteristics of a dictionary by deriving from the generic class. +> For values that contain their own keys (for example, employee records that contain an employee ID number), you can create a keyed collection that has some characteristics of a list and some characteristics of a dictionary by deriving from the generic class. -Starting with .NET Framework 4, the class provides a self-balancing tree that maintains data in sorted order after insertions, deletions, and searches. This class and the class implement the interface. +Starting with .NET Framework 4, the class provides a self-balancing tree that maintains data in sorted order after insertions, deletions, and searches. This class and the class implement the interface. ## See also - -- -- +- +- - [Commonly Used Collection Types](commonly-used-collection-types.md) diff --git a/docs/standard/collections/thread-safe/blockingcollection-overview.md b/docs/standard/collections/thread-safe/blockingcollection-overview.md index 69be4b2ab0620..5332eebf4ed26 100644 --- a/docs/standard/collections/thread-safe/blockingcollection-overview.md +++ b/docs/standard/collections/thread-safe/blockingcollection-overview.md @@ -2,83 +2,83 @@ title: "BlockingCollection Overview" description: Read about BlockingCollection, a thread-safe collection class in .NET. This class offers features like concurrent adding & taking of items from many threads. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "BlockingCollection, overview" ms.assetid: 987ea3d7-0ad5-4238-8b64-331ce4eb3f0b --- # BlockingCollection Overview - is a thread-safe collection class that provides the following features: - -- An implementation of the Producer-Consumer pattern. - -- Concurrent adding and taking of items from multiple threads. - -- Optional maximum capacity. - -- Insertion and removal operations that block when collection is empty or full. - -- Insertion and removal "try" operations that do not block or that block up to a specified period of time. - -- Encapsulates any collection type that implements - -- Cancellation with cancellation tokens. - -- Two kinds of enumeration with `foreach` (`For Each` in Visual Basic): - - 1. Read-only enumeration. - - 2. Enumeration that removes items as they are enumerated. - -## Bounding and Blocking Support - - supports bounding and blocking. Bounding means you can set the maximum capacity of the collection. Bounding is important in certain scenarios because it enables you to control the maximum size of the collection in memory, and it prevents the producing threads from moving too far ahead of the consuming threads. - - Multiple threads or tasks can add items to the collection concurrently, and if the collection reaches its specified maximum capacity, the producing threads will block until an item is removed. Multiple consumers can remove items concurrently, and if the collection becomes empty, the consuming threads will block until a producer adds an item. A producing thread can call to indicate that no more items will be added. Consumers monitor the property to know when the collection is empty and no more items will be added. The following example shows a simple BlockingCollection with a bounded capacity of 100. A producer task adds items to the collection as long as some external condition is true, and then calls . The consumer task takes items until the property is true. - + is a thread-safe collection class that provides the following features: + +- An implementation of the Producer-Consumer pattern. + +- Concurrent adding and taking of items from multiple threads. + +- Optional maximum capacity. + +- Insertion and removal operations that block when collection is empty or full. + +- Insertion and removal "try" operations that do not block or that block up to a specified period of time. + +- Encapsulates any collection type that implements + +- Cancellation with cancellation tokens. + +- Two kinds of enumeration with `foreach` (`For Each` in Visual Basic): + + 1. Read-only enumeration. + + 2. Enumeration that removes items as they are enumerated. + +## Bounding and Blocking Support + + supports bounding and blocking. Bounding means you can set the maximum capacity of the collection. Bounding is important in certain scenarios because it enables you to control the maximum size of the collection in memory, and it prevents the producing threads from moving too far ahead of the consuming threads. + + Multiple threads or tasks can add items to the collection concurrently, and if the collection reaches its specified maximum capacity, the producing threads will block until an item is removed. Multiple consumers can remove items concurrently, and if the collection becomes empty, the consuming threads will block until a producer adds an item. A producing thread can call to indicate that no more items will be added. Consumers monitor the property to know when the collection is empty and no more items will be added. The following example shows a simple BlockingCollection with a bounded capacity of 100. A producer task adds items to the collection as long as some external condition is true, and then calls . The consumer task takes items until the property is true. + [!code-csharp[CDS_BlockingCollection#04](../../../../samples/snippets/csharp/VS_Snippets_Misc/cds_blockingcollection/cs/blockingcollection.cs#04)] - [!code-vb[CDS_BlockingCollection#04](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_blockingcollection/vb/introsnippetsbc.vb#04)] - - For a complete example, see [How to: Add and Take Items Individually from a BlockingCollection](how-to-add-and-take-items.md). - -## Timed Blocking Operations - - In timed blocking and operations on bounded collections, the method tries to add or take an item. If an item is available it is placed into the variable that was passed in by reference, and the method returns true. If no item is retrieved after a specified time-out period the method returns false. The thread is then free to do some other useful work before trying again to access the collection. For an example of timed blocking access, see the second example in [How to: Add and Take Items Individually from a BlockingCollection](how-to-add-and-take-items.md). - -## Cancelling Add and Take Operations - - Add and Take operations are typically performed in a loop. You can cancel a loop by passing in a to the or method, and then checking the value of the token's property on each iteration. If the value is true, then it is up to you to respond to the cancellation request by cleaning up any resources and exiting the loop. The following example shows an overload of that takes a cancellation token, and the code that uses it: - + [!code-vb[CDS_BlockingCollection#04](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_blockingcollection/vb/introsnippetsbc.vb#04)] + + For a complete example, see [How to: Add and Take Items Individually from a BlockingCollection](how-to-add-and-take-items.md). + +## Timed Blocking Operations + + In timed blocking and operations on bounded collections, the method tries to add or take an item. If an item is available it is placed into the variable that was passed in by reference, and the method returns true. If no item is retrieved after a specified time-out period the method returns false. The thread is then free to do some other useful work before trying again to access the collection. For an example of timed blocking access, see the second example in [How to: Add and Take Items Individually from a BlockingCollection](how-to-add-and-take-items.md). + +## Cancelling Add and Take Operations + + Add and Take operations are typically performed in a loop. You can cancel a loop by passing in a to the or method, and then checking the value of the token's property on each iteration. If the value is true, then it is up to you to respond to the cancellation request by cleaning up any resources and exiting the loop. The following example shows an overload of that takes a cancellation token, and the code that uses it: + [!code-csharp[CDS_BlockingCollection#05](../../../../samples/snippets/csharp/VS_Snippets_Misc/cds_blockingcollection/cs/blockingcollection.cs#05)] - [!code-vb[CDS_BlockingCollection#05](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_blockingcollection/vb/introsnippetsbc.vb#05)] - - For an example of how to add cancellation support, see the second example in [How to: Add and Take Items Individually from a BlockingCollection](how-to-add-and-take-items.md). - -## Specifying the Collection Type - - When you create a , you can specify not only the bounded capacity but also the type of collection to use. For example, you could specify a for first in-first out (FIFO) behavior, or a for last in-first out (LIFO) behavior. You can use any collection class that implements the interface. The default collection type for is . The following code example shows how to create a of strings that has a capacity of 1000 and uses a : - -```vb -Dim bc = New BlockingCollection(Of String)(New ConcurrentBag(Of String()), 1000) -``` - -```csharp -BlockingCollection bc = new BlockingCollection(new ConcurrentBag(), 1000 ); -``` - - For more information, see [How to: Add Bounding and Blocking Functionality to a Collection](how-to-add-bounding-and-blocking.md). - -## IEnumerable Support - - provides a method that enables consumers to use `foreach` (`For Each` in Visual Basic) to remove items until the collection is completed, which means it is empty and no more items will be added. For more information, see [How to: Use ForEach to Remove Items in a BlockingCollection](how-to-use-foreach-to-remove.md). - -## Using Many BlockingCollections As One - - For scenarios in which a consumer needs to take items from multiple collections simultaneously, you can create arrays of and use the static methods such as and that will add to or take from any of the collections in the array. If one collection is blocking, the method immediately tries another until it finds one that can perform the operation. For more information, see [How to: Use Arrays of Blocking Collections in a Pipeline](how-to-use-arrays-of-blockingcollections.md). - + [!code-vb[CDS_BlockingCollection#05](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_blockingcollection/vb/introsnippetsbc.vb#05)] + + For an example of how to add cancellation support, see the second example in [How to: Add and Take Items Individually from a BlockingCollection](how-to-add-and-take-items.md). + +## Specifying the Collection Type + + When you create a , you can specify not only the bounded capacity but also the type of collection to use. For example, you could specify a for first in-first out (FIFO) behavior, or a for last in-first out (LIFO) behavior. You can use any collection class that implements the interface. The default collection type for is . The following code example shows how to create a of strings that has a capacity of 1000 and uses a : + +```vb +Dim bc = New BlockingCollection(Of String)(New ConcurrentBag(Of String()), 1000) +``` + +```csharp +BlockingCollection bc = new BlockingCollection(new ConcurrentBag(), 1000 ); +``` + + For more information, see [How to: Add Bounding and Blocking Functionality to a Collection](how-to-add-bounding-and-blocking.md). + +## IEnumerable Support + + provides a method that enables consumers to use `foreach` (`For Each` in Visual Basic) to remove items until the collection is completed, which means it is empty and no more items will be added. For more information, see [How to: Use ForEach to Remove Items in a BlockingCollection](how-to-use-foreach-to-remove.md). + +## Using Many BlockingCollections As One + + For scenarios in which a consumer needs to take items from multiple collections simultaneously, you can create arrays of and use the static methods such as and that will add to or take from any of the collections in the array. If one collection is blocking, the method immediately tries another until it finds one that can perform the operation. For more information, see [How to: Use Arrays of Blocking Collections in a Pipeline](how-to-use-arrays-of-blockingcollections.md). + ## See also - diff --git a/docs/standard/collections/thread-safe/how-to-add-and-remove-items.md b/docs/standard/collections/thread-safe/how-to-add-and-remove-items.md index 5eb1ea8125276..267a5761c53a2 100644 --- a/docs/standard/collections/thread-safe/how-to-add-and-remove-items.md +++ b/docs/standard/collections/thread-safe/how-to-add-and-remove-items.md @@ -2,45 +2,45 @@ title: Add and Remove Items from a ConcurrentDictionary description: Read an example of how to add, retrieve, update, and remove items from the ConcurrentDictionary collection class in .NET. ms.date: 05/04/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "thread-safe collections, concurrent dictionary" ms.assetid: 81b64b95-13f7-4532-9249-ab532f629598 --- # How to add and remove items from a ConcurrentDictionary -This example shows how to add, retrieve, update, and remove items from a . This collection class is a thread-safe implementation. We recommend that you use it whenever multiple threads might be attempting to access the elements concurrently. +This example shows how to add, retrieve, update, and remove items from a . This collection class is a thread-safe implementation. We recommend that you use it whenever multiple threads might be attempting to access the elements concurrently. - provides several convenience methods that make it unnecessary for code to first check whether a key exists before it attempts to add or remove data. The following table lists these convenience methods and describes when to use them. + provides several convenience methods that make it unnecessary for code to first check whether a key exists before it attempts to add or remove data. The following table lists these convenience methods and describes when to use them. | Method | Use when… | |--|--| -| | You want to add a new value for a specified key and, if the key already exists, you want to replace its value. | -| | You want to retrieve the existing value for a specified key and, if the key does not exist, you want to specify a key/value pair. | -| , , , | You want to add, get, update, or remove a key/value pair, and, if the key already exists or the attempt fails for any other reason, you want to take some alternative action. | +| | You want to add a new value for a specified key and, if the key already exists, you want to replace its value. | +| | You want to retrieve the existing value for a specified key and, if the key does not exist, you want to specify a key/value pair. | +| , , , | You want to add, get, update, or remove a key/value pair, and, if the key already exists or the attempt fails for any other reason, you want to take some alternative action. | ## Example -The following example uses two instances to add some elements to a concurrently, and then outputs all of the contents to show that the elements were added successfully. The example also shows how to use the , , and methods to add, update, and retrieve items from the collection. +The following example uses two instances to add some elements to a concurrently, and then outputs all of the contents to show that the elements were added successfully. The example also shows how to use the , , and methods to add, update, and retrieve items from the collection. [!code-csharp[CDS#16](../../../../samples/snippets/csharp/VS_Snippets_Misc/cds/cs/cds_dictionaryhowto.cs#16)] [!code-vb[CDS#16](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds/vb/cds_concdict.vb#16)] - is designed for multithreaded scenarios. You do not have to use locks in your code to add or remove items from the collection. However, it is always possible for one thread to retrieve a value, and another thread to immediately update the collection by giving the same key a new value. + is designed for multithreaded scenarios. You do not have to use locks in your code to add or remove items from the collection. However, it is always possible for one thread to retrieve a value, and another thread to immediately update the collection by giving the same key a new value. -Also, although all methods of are thread-safe, not all methods are atomic, specifically and . To prevent unknown code from blocking all threads, the user delegate that's passed to these methods is invoked outside of the dictionary's internal lock. Therefore, it's possible for this sequence of events to occur: +Also, although all methods of are thread-safe, not all methods are atomic, specifically and . To prevent unknown code from blocking all threads, the user delegate that's passed to these methods is invoked outside of the dictionary's internal lock. Therefore, it's possible for this sequence of events to occur: -1. _threadA_ calls , finds no item, and creates a new item to add by invoking the `valueFactory` delegate. +1. _threadA_ calls , finds no item, and creates a new item to add by invoking the `valueFactory` delegate. -1. _threadB_ calls concurrently, its `valueFactory` delegate is invoked and it arrives at the internal lock before _threadA_, and so its new key-value pair is added to the dictionary. +1. _threadB_ calls concurrently, its `valueFactory` delegate is invoked and it arrives at the internal lock before _threadA_, and so its new key-value pair is added to the dictionary. 1. _threadA's_ user delegate completes, and the thread arrives at the lock, but now sees that the item exists already. 1. _threadA_ performs a "Get" and returns the data that was previously added by _threadB_. -Therefore, it is not guaranteed that the data that is returned by is the same data that was created by the thread's `valueFactory`. A similar sequence of events can occur when is called. +Therefore, it is not guaranteed that the data that is returned by is the same data that was created by the thread's `valueFactory`. A similar sequence of events can occur when is called. ## See also diff --git a/docs/standard/collections/thread-safe/how-to-add-and-take-items.md b/docs/standard/collections/thread-safe/how-to-add-and-take-items.md index ab43d74b27f30..1a8e84e399f27 100644 --- a/docs/standard/collections/thread-safe/how-to-add-and-take-items.md +++ b/docs/standard/collections/thread-safe/how-to-add-and-take-items.md @@ -2,33 +2,33 @@ description: "Learn more about: How to: Add and Take Items Individually from a BlockingCollection" title: "How to: Add and Take Items Individually from a BlockingCollection" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "thread-safe collections, blocking dictionary" ms.assetid: 38f2f3d8-15e5-4bf4-9c83-2b5b6f22bad1 --- # How to: Add and Take Items Individually from a BlockingCollection -This example shows how to add and remove items from a in both a blocking and a non-blocking manner. For more information on , see [BlockingCollection Overview](blockingcollection-overview.md). - - For an example of how to enumerate a until it is empty and no more elements will be added, see [How to: Use ForEach to Remove Items in a BlockingCollection](how-to-use-foreach-to-remove.md). - +This example shows how to add and remove items from a in both a blocking and a non-blocking manner. For more information on , see [BlockingCollection Overview](blockingcollection-overview.md). + + For an example of how to enumerate a until it is empty and no more elements will be added, see [How to: Use ForEach to Remove Items in a BlockingCollection](how-to-use-foreach-to-remove.md). + ## Example 1 - This first example shows how to add and take items so that the operations will block if the collection is either temporarily empty (when taking) or at maximum capacity (when adding), or if a specified timeout period has elapsed. Note that blocking on maximum capacity is only enabled when the BlockingCollection has been created with a maximum capacity specified in the constructor. - + This first example shows how to add and take items so that the operations will block if the collection is either temporarily empty (when taking) or at maximum capacity (when adding), or if a specified timeout period has elapsed. Note that blocking on maximum capacity is only enabled when the BlockingCollection has been created with a maximum capacity specified in the constructor. + [!code-csharp[CDS_BlockingCollection#01](../../../../samples/snippets/csharp/VS_Snippets_Misc/cds_blockingcollection/cs/example01.cs#01)] - [!code-vb[CDS_BlockingCollection#01](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_blockingcollection/vb/simpleblocking.vb#01)] - -## Example 2 + [!code-vb[CDS_BlockingCollection#01](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_blockingcollection/vb/simpleblocking.vb#01)] + +## Example 2 + + This second example shows how to add and take items so that the operations will not block. If no item is present, maximum capacity on a bounded collection has been reached, or the timeout period has elapsed, then the or operation returns false. This allows the thread to do some other useful work for a while and then try again later to either retrieve a new item, or try to add the same item that could not be added previously. The program also demonstrates how to implement cancellation when accessing a . - This second example shows how to add and take items so that the operations will not block. If no item is present, maximum capacity on a bounded collection has been reached, or the timeout period has elapsed, then the or operation returns false. This allows the thread to do some other useful work for a while and then try again later to either retrieve a new item, or try to add the same item that could not be added previously. The program also demonstrates how to implement cancellation when accessing a . - [!code-csharp[CDS_BlockingCollection#02](../../../../samples/snippets/csharp/VS_Snippets_Misc/cds_blockingcollection/cs/example02.cs#02)] - [!code-vb[CDS_BlockingCollection#02](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_blockingcollection/vb/nonblockingbc.vb#02)] - + [!code-vb[CDS_BlockingCollection#02](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_blockingcollection/vb/nonblockingbc.vb#02)] + ## See also - diff --git a/docs/standard/collections/thread-safe/how-to-add-bounding-and-blocking.md b/docs/standard/collections/thread-safe/how-to-add-bounding-and-blocking.md index 0a41882f5b38e..b66f7237e6324 100644 --- a/docs/standard/collections/thread-safe/how-to-add-bounding-and-blocking.md +++ b/docs/standard/collections/thread-safe/how-to-add-bounding-and-blocking.md @@ -2,26 +2,26 @@ description: "Learn more about: How to: Add Bounding and Blocking Functionality to a Collection" title: "How to: Add Bounding and Blocking Functionality to a Collection" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "thread-safe collections, custom blocking collections" ms.assetid: 4c2492de-3876-4873-b5a1-000bb404d770 --- # How to: Add Bounding and Blocking Functionality to a Collection -This example shows how to add bounding and blocking functionality to a custom collection class by implementing the interface in the class, and then using a class instance as the internal storage mechanism for a . For more information about bounding and blocking, see [BlockingCollection Overview](blockingcollection-overview.md). - -## Example - - The custom collection class is a basic priority queue in which the priority levels are represented as an array of objects. No additional ordering is performed within each queue. - - In the client code, three tasks are started. The first task just polls for keyboard strokes to enable cancellation at any point during execution. The second task is the producer thread; it adds new items to the blocking collection and gives each item a priority based on a random value. The third task removes items from the collection as they become available. - - You can adjust the behavior of the application by making one of the threads run faster than the other. If the producer runs faster, you will notice the bounding functionality as the blocking collection prevents items from being added if it already contains the number of items that is specified in the constructor. If the consumer runs faster, you will notice the blocking functionality as the consumer waits for a new item to be added. - - [!code-csharp[CDS_BlockingCollection#06](../../../../samples/snippets/csharp/VS_Snippets_Misc/cds_blockingcollection/cs/prodcon.cs#06)] - - By default, the storage for a is . - +This example shows how to add bounding and blocking functionality to a custom collection class by implementing the interface in the class, and then using a class instance as the internal storage mechanism for a . For more information about bounding and blocking, see [BlockingCollection Overview](blockingcollection-overview.md). + +## Example + + The custom collection class is a basic priority queue in which the priority levels are represented as an array of objects. No additional ordering is performed within each queue. + + In the client code, three tasks are started. The first task just polls for keyboard strokes to enable cancellation at any point during execution. The second task is the producer thread; it adds new items to the blocking collection and gives each item a priority based on a random value. The third task removes items from the collection as they become available. + + You can adjust the behavior of the application by making one of the threads run faster than the other. If the producer runs faster, you will notice the bounding functionality as the blocking collection prevents items from being added if it already contains the number of items that is specified in the constructor. If the consumer runs faster, you will notice the blocking functionality as the consumer waits for a new item to be added. + + [!code-csharp[CDS_BlockingCollection#06](../../../../samples/snippets/csharp/VS_Snippets_Misc/cds_blockingcollection/cs/prodcon.cs#06)] + + By default, the storage for a is . + ## See also - [Thread-Safe Collections](index.md) diff --git a/docs/standard/collections/thread-safe/how-to-create-an-object-pool.md b/docs/standard/collections/thread-safe/how-to-create-an-object-pool.md index 672a24e3fa6ca..105645d48dc0d 100644 --- a/docs/standard/collections/thread-safe/how-to-create-an-object-pool.md +++ b/docs/standard/collections/thread-safe/how-to-create-an-object-pool.md @@ -12,12 +12,12 @@ ms.assetid: 0480e7ff-b6f9-480e-a889-2ed4264d8372 # Create an object pool by using a ConcurrentBag -This example shows how to use a to implement an object pool. Object pools can improve application performance in situations where you require multiple instances of a class and the class is expensive to create or destroy. When a client program requests a new object, the object pool first attempts to provide one that has already been created and returned to the pool. If none is available, only then is a new object created. +This example shows how to use a to implement an object pool. Object pools can improve application performance in situations where you require multiple instances of a class and the class is expensive to create or destroy. When a client program requests a new object, the object pool first attempts to provide one that has already been created and returned to the pool. If none is available, only then is a new object created. -The is used to store the objects because it supports fast insertion and removal, especially when the same thread is both adding and removing items. This example could be further augmented to be built around a , which the bag data structure implements, as do and . +The is used to store the objects because it supports fast insertion and removal, especially when the same thread is both adding and removing items. This example could be further augmented to be built around a , which the bag data structure implements, as do and . > [!TIP] -> This article defines how to write your own implementation of an object pool with an underlying concurrent type to store objects for reuse. However, the type already exists under the namespace. Consider using the available type before creating your own implementation, which includes many additional features. +> This article defines how to write your own implementation of an object pool with an underlying concurrent type to store objects for reuse. However, the type already exists under the namespace. Consider using the available type before creating your own implementation, which includes many additional features. ## Example diff --git a/docs/standard/collections/thread-safe/how-to-use-arrays-of-blockingcollections.md b/docs/standard/collections/thread-safe/how-to-use-arrays-of-blockingcollections.md index 1075f0b9616d3..45d95fc6c630c 100644 --- a/docs/standard/collections/thread-safe/how-to-use-arrays-of-blockingcollections.md +++ b/docs/standard/collections/thread-safe/how-to-use-arrays-of-blockingcollections.md @@ -2,24 +2,24 @@ description: "Learn more about: How to: Use Arrays of Blocking Collections in a Pipeline" title: "How to: Use Arrays of Blocking Collections in a Pipeline" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "thread-safe collections, blocking collections in pipeline" ms.assetid: a39c7ec3-3ad7-4f4d-8fe4-b3e9dbabe2ed --- # How to: Use Arrays of Blocking Collections in a Pipeline -The following example shows how to use arrays of objects with static methods such as and to implement fast and flexible data transfer between components. - -## Example +The following example shows how to use arrays of objects with static methods such as and to implement fast and flexible data transfer between components. + +## Example + + The following example demonstrates a basic pipeline implementation in which each object is concurrently taking data from the input collection, transforming it, and passing it to the output collection. - The following example demonstrates a basic pipeline implementation in which each object is concurrently taking data from the input collection, transforming it, and passing it to the output collection. - [!code-csharp[CDS_BlockingCollection#07](../../../../samples/snippets/csharp/VS_Snippets_Misc/cds_blockingcollection/cs/example07.cs#07)] - [!code-vb[CDS_BlockingCollection#07](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_blockingcollection/vb/bcpipeline.vb#07)] - + [!code-vb[CDS_BlockingCollection#07](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_blockingcollection/vb/bcpipeline.vb#07)] + ## See also - diff --git a/docs/standard/collections/thread-safe/how-to-use-foreach-to-remove.md b/docs/standard/collections/thread-safe/how-to-use-foreach-to-remove.md index d31f1d40cfd3f..a696eb8e0c7cc 100644 --- a/docs/standard/collections/thread-safe/how-to-use-foreach-to-remove.md +++ b/docs/standard/collections/thread-safe/how-to-use-foreach-to-remove.md @@ -12,20 +12,20 @@ ms.assetid: 2096103c-22f7-420d-b631-f102bc33a6dd # Use foreach to remove items in a BlockingCollection -In addition to taking items from a by using the and method, you can also use a [foreach](../../../csharp/language-reference/statements/iteration-statements.md#the-foreach-statement) ([For Each](../../../visual-basic/language-reference/statements/for-each-next-statement.md) in Visual Basic) with the to remove items until adding is completed and the collection is empty. This is called a *mutating enumeration* or *consuming enumeration* because, unlike a typical `foreach` (`For Each`) loop, this enumerator modifies the source collection by removing items. +In addition to taking items from a by using the and method, you can also use a [foreach](../../../csharp/language-reference/statements/iteration-statements.md#the-foreach-statement) ([For Each](../../../visual-basic/language-reference/statements/for-each-next-statement.md) in Visual Basic) with the to remove items until adding is completed and the collection is empty. This is called a *mutating enumeration* or *consuming enumeration* because, unlike a typical `foreach` (`For Each`) loop, this enumerator modifies the source collection by removing items. ## Example -The following example shows how to remove all the items in a by using a `foreach` (`For Each`) loop. +The following example shows how to remove all the items in a by using a `foreach` (`For Each`) loop. [!code-csharp[CDS_BlockingCollection#03](../../../../samples/snippets/csharp/VS_Snippets_Misc/cds_blockingcollection/cs/example03.cs#03)] [!code-vb[CDS_BlockingCollection#03](../../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_blockingcollection/vb/enumeratebc.vb#03)] -This example uses a `foreach` loop with the method in the consuming thread, which causes each item to be removed from the collection as it is enumerated. limits the maximum number of items that are in the collection at any time. Enumerating the collection in this way blocks the consumer thread if no items are available or if the collection is empty. In this example blocking is not a concern because the producer thread adds items faster than they can be consumed. +This example uses a `foreach` loop with the method in the consuming thread, which causes each item to be removed from the collection as it is enumerated. limits the maximum number of items that are in the collection at any time. Enumerating the collection in this way blocks the consumer thread if no items are available or if the collection is empty. In this example blocking is not a concern because the producer thread adds items faster than they can be consumed. -The returns an `IEnumerable`, thus order cannot be guaranteed. However, internally a is used as the underlying collection type - which will dequeue objects following first-in-first-out (FIFO) ordering. If concurrent calls to are made, they will compete. One item consumed (dequeued) in one enumeration cannot be observed in the other. +The returns an `IEnumerable`, thus order cannot be guaranteed. However, internally a is used as the underlying collection type - which will dequeue objects following first-in-first-out (FIFO) ordering. If concurrent calls to are made, they will compete. One item consumed (dequeued) in one enumeration cannot be observed in the other. -To enumerate the collection without modifying it, just use `foreach` (`For Each`) without the method. However, it is important to understand that this kind of enumeration represents a snapshot of the collection at a precise point in time. If other threads are adding or removing items concurrently while you are executing the loop, then the loop might not represent the actual state of the collection. +To enumerate the collection without modifying it, just use `foreach` (`For Each`) without the method. However, it is important to understand that this kind of enumeration represents a snapshot of the collection at a precise point in time. If other threads are adding or removing items concurrently while you are executing the loop, then the loop might not represent the actual state of the collection. ## See also diff --git a/docs/standard/collections/thread-safe/index.md b/docs/standard/collections/thread-safe/index.md index 919a6cc508ff9..78dc4be3f6cee 100644 --- a/docs/standard/collections/thread-safe/index.md +++ b/docs/standard/collections/thread-safe/index.md @@ -15,7 +15,7 @@ The namespace The collection classes in the namespace include and . These classes provide some thread safety through the `Synchronized` property, which returns a thread-safe wrapper around the collection. The wrapper works by locking the entire collection on every add or remove operation. Therefore, each thread that's attempting to access the collection must wait for its turn to take the one lock. This process isn't scalable and can cause significant performance degradation for large collections. Also, the design isn't protected from race conditions. For more information, see [Synchronization in Generic Collections](/archive/blogs/bclteam/synchronization-in-generic-collections-brian-grunkemeyer). - The collection classes in the namespace include and . These classes provide improved type safety and performance compared to the classes. However, the classes don't provide any thread synchronization; user code must provide all synchronization when items are added or removed on multiple threads concurrently. + The collection classes in the namespace include and . These classes provide improved type safety and performance compared to the classes. However, the classes don't provide any thread synchronization; user code must provide all synchronization when items are added or removed on multiple threads concurrently. We recommend using the concurrent collections classes in the namespace because they provide type safety and also more efficient and complete thread safety. @@ -23,30 +23,30 @@ The namespace Some of the concurrent collection types use lightweight synchronization mechanisms such as , , , and . These synchronization types typically use *busy spinning* for brief periods before they put the thread into a true `Wait` state. When wait times are expected to be short, spinning is far less computationally expensive than waiting, which involves an expensive kernel transition. For collection classes that use spinning, this efficiency means that multiple threads can add and remove items at a high rate. For more information about spinning versus blocking, see [SpinLock](../../threading/spinlock.md) and [SpinWait](../../threading/spinwait.md). - The and classes don't use locks at all. Instead, they rely on operations to achieve thread safety. + The and classes don't use locks at all. Instead, they rely on operations to achieve thread safety. > [!NOTE] -> Because the concurrent collections classes support , they provide implementations for the and properties, even though these properties are irrelevant. `IsSynchronized` always returns `false` and, `SyncRoot` is always `null` (`Nothing` in Visual Basic). +> Because the concurrent collections classes support , they provide implementations for the and properties, even though these properties are irrelevant. `IsSynchronized` always returns `false` and, `SyncRoot` is always `null` (`Nothing` in Visual Basic). The following table lists the collection types in the namespace: |Type|Description| |----------|-----------------| -||Provides bounding and blocking functionality for any type that implements . For more information, see [BlockingCollection Overview](blockingcollection-overview.md).| -||Thread-safe implementation of a dictionary of key-value pairs.| -||Thread-safe implementation of a FIFO (first-in, first-out) queue.| -||Thread-safe implementation of a LIFO (last-in, first-out) stack.| -||Thread-safe implementation of an unordered collection of elements.| -||The interface that a type must implement to be used in a `BlockingCollection`.| +||Provides bounding and blocking functionality for any type that implements . For more information, see [BlockingCollection Overview](blockingcollection-overview.md).| +||Thread-safe implementation of a dictionary of key-value pairs.| +||Thread-safe implementation of a FIFO (first-in, first-out) queue.| +||Thread-safe implementation of a LIFO (last-in, first-out) stack.| +||Thread-safe implementation of an unordered collection of elements.| +||The interface that a type must implement to be used in a `BlockingCollection`.| ## Related articles |Title|Description| |-----------|-----------------| -|[BlockingCollection Overview](blockingcollection-overview.md)|Describes the functionality provided by the type.| -|[How to: Add and Remove Items from a ConcurrentDictionary](how-to-add-and-remove-items.md)|Describes how to add and remove elements from a | +|[BlockingCollection Overview](blockingcollection-overview.md)|Describes the functionality provided by the type.| +|[How to: Add and Remove Items from a ConcurrentDictionary](how-to-add-and-remove-items.md)|Describes how to add and remove elements from a | |[How to: Add and Take Items Individually from a BlockingCollection](how-to-add-and-take-items.md)|Describes how to add and retrieve items from a blocking collection without using the read-only enumerator.| -|[How to: Add Bounding and Blocking Functionality to a Collection](how-to-add-bounding-and-blocking.md)|Describes how to use any collection class as the underlying storage mechanism for an collection.| +|[How to: Add Bounding and Blocking Functionality to a Collection](how-to-add-bounding-and-blocking.md)|Describes how to use any collection class as the underlying storage mechanism for an collection.| |[How to: Use ForEach to Remove Items in a BlockingCollection](how-to-use-foreach-to-remove.md)|Describes how to use `foreach` (`For Each` in Visual Basic) to remove all items in a blocking collection.| |[How to: Use Arrays of Blocking Collections in a Pipeline](how-to-use-arrays-of-blockingcollections.md)|Describes how to use multiple blocking collections at the same time to implement a pipeline.| |[How to: Create an Object Pool by Using a ConcurrentBag](how-to-create-an-object-pool.md)|Shows how to use a concurrent bag to improve performance in scenarios where you can reuse objects instead of continually creating new ones.| diff --git a/docs/standard/collections/thread-safe/when-to-use-a-thread-safe-collection.md b/docs/standard/collections/thread-safe/when-to-use-a-thread-safe-collection.md index 12bf0281d9cec..8bc546921d3b8 100644 --- a/docs/standard/collections/thread-safe/when-to-use-a-thread-safe-collection.md +++ b/docs/standard/collections/thread-safe/when-to-use-a-thread-safe-collection.md @@ -2,64 +2,64 @@ title: "When to Use a Thread-Safe Collection" description: Know when to use a thread-safe collection in .NET. There are 5 collection types that are specially designed to support multithreaded add & remove operations. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "thread-safe collections, when to upgrade" ms.assetid: a9babe97-e457-4ff3-b528-a1bc940d5320 --- # When to use a thread-safe collection -.NET Framework 4 introduced five collection types that are specially designed to support multi-threaded add and remove operations. To achieve thread-safety, these types use various kinds of efficient locking and lock-free synchronization mechanisms. Synchronization adds overhead to an operation. The amount of overhead depends on the kind of synchronization that is used, the kind of operations that are performed, and other factors such as the number of threads that are trying to concurrently access the collection. - - In some scenarios, synchronization overhead is negligible and enables the multi-threaded type to perform significantly faster and scale far better than its non-thread-safe equivalent when protected by an external lock. In other scenarios, the overhead can cause the thread-safe type to perform and scale about the same or even more slowly than the externally-locked, non-thread-safe version of the type. - - The following sections provide general guidance about when to use a thread-safe collection versus its non-thread-safe equivalent that has a user-provided lock around its read and write operations. Because performance may vary depending on many factors, the guidance is not specific and is not necessarily valid in all circumstances. If performance is very important, then the best way to determine which collection type to use is to measure performance based on representative computer configurations and loads. This document uses the following terms: - +.NET Framework 4 introduced five collection types that are specially designed to support multi-threaded add and remove operations. To achieve thread-safety, these types use various kinds of efficient locking and lock-free synchronization mechanisms. Synchronization adds overhead to an operation. The amount of overhead depends on the kind of synchronization that is used, the kind of operations that are performed, and other factors such as the number of threads that are trying to concurrently access the collection. + + In some scenarios, synchronization overhead is negligible and enables the multi-threaded type to perform significantly faster and scale far better than its non-thread-safe equivalent when protected by an external lock. In other scenarios, the overhead can cause the thread-safe type to perform and scale about the same or even more slowly than the externally-locked, non-thread-safe version of the type. + + The following sections provide general guidance about when to use a thread-safe collection versus its non-thread-safe equivalent that has a user-provided lock around its read and write operations. Because performance may vary depending on many factors, the guidance is not specific and is not necessarily valid in all circumstances. If performance is very important, then the best way to determine which collection type to use is to measure performance based on representative computer configurations and loads. This document uses the following terms: + *Pure producer-consumer scenario*\ - Any given thread is either adding or removing elements, but not both. - + Any given thread is either adding or removing elements, but not both. + *Mixed producer-consumer scenario*\ - Any given thread is both adding and removing elements. - + Any given thread is both adding and removing elements. + *Speedup*\ - Faster algorithmic performance relative to another type in the same scenario. - + Faster algorithmic performance relative to another type in the same scenario. + *Scalability*\ - The increase in performance that is proportional to the number of cores on the computer. An algorithm that scales performs faster on eight cores than it does on two cores. - -## ConcurrentQueue(T) vs. Queue(T) - - In pure producer-consumer scenarios, where the processing time for each element is very small (a few instructions), then can offer modest performance benefits over a that has an external lock. In this scenario, performs best when one dedicated thread is queuing and one dedicated thread is de-queuing. If you do not enforce this rule, then might even perform slightly faster than on computers that have multiple cores. - - When processing time is around 500 FLOPS (floating point operations) or more, then the two-thread rule does not apply to , which then has very good scalability. does not scale well in this scenario. - - In mixed producer-consumer scenarios, when the processing time is very small, a that has an external lock scales better than does. However, when processing time is around 500 FLOPS or more, then the scales better. - -## ConcurrentStack vs. Stack - - In pure producer-consumer scenarios, when processing time is very small, then and that has an external lock will probably perform about the same with one dedicated pushing thread and one dedicated popping thread. However, as the number of threads increases, both types slow down because of increased contention, and might perform better than . When processing time is around 500 FLOPS or more, then both types scale at about the same rate. - - In mixed producer-consumer scenarios, is faster for both small and large workloads. - - The use of the and may greatly speed up access times. - -## ConcurrentDictionary vs. Dictionary - - In general, use a in any scenario where you are adding and updating keys or values concurrently from multiple threads. In scenarios that involve frequent updates and relatively few reads, the generally offers modest benefits. In scenarios that involve many reads and many updates, the generally is significantly faster on computers that have any number of cores. - - In scenarios that involve frequent updates, you can increase the degree of concurrency in the and then measure to see whether performance increases on computers that have more cores. If you change the concurrency level, avoid global operations as much as possible. - - If you are only reading key or values, the is faster because no synchronization is required if the dictionary is not being modified by any threads. - -## ConcurrentBag - - In pure producer-consumer scenarios, will probably perform more slowly than the other concurrent collection types. - - In mixed producer-consumer scenarios, is generally much faster and more scalable than any other concurrent collection type for both large and small workloads. - -## BlockingCollection - - When bounding and blocking semantics are required, will probably perform faster than any custom implementation. It also supports rich cancellation, enumeration, and exception handling. - + The increase in performance that is proportional to the number of cores on the computer. An algorithm that scales performs faster on eight cores than it does on two cores. + +## ConcurrentQueue(T) vs. Queue(T) + + In pure producer-consumer scenarios, where the processing time for each element is very small (a few instructions), then can offer modest performance benefits over a that has an external lock. In this scenario, performs best when one dedicated thread is queuing and one dedicated thread is de-queuing. If you do not enforce this rule, then might even perform slightly faster than on computers that have multiple cores. + + When processing time is around 500 FLOPS (floating point operations) or more, then the two-thread rule does not apply to , which then has very good scalability. does not scale well in this scenario. + + In mixed producer-consumer scenarios, when the processing time is very small, a that has an external lock scales better than does. However, when processing time is around 500 FLOPS or more, then the scales better. + +## ConcurrentStack vs. Stack + + In pure producer-consumer scenarios, when processing time is very small, then and that has an external lock will probably perform about the same with one dedicated pushing thread and one dedicated popping thread. However, as the number of threads increases, both types slow down because of increased contention, and might perform better than . When processing time is around 500 FLOPS or more, then both types scale at about the same rate. + + In mixed producer-consumer scenarios, is faster for both small and large workloads. + + The use of the and may greatly speed up access times. + +## ConcurrentDictionary vs. Dictionary + + In general, use a in any scenario where you are adding and updating keys or values concurrently from multiple threads. In scenarios that involve frequent updates and relatively few reads, the generally offers modest benefits. In scenarios that involve many reads and many updates, the generally is significantly faster on computers that have any number of cores. + + In scenarios that involve frequent updates, you can increase the degree of concurrency in the and then measure to see whether performance increases on computers that have more cores. If you change the concurrency level, avoid global operations as much as possible. + + If you are only reading key or values, the is faster because no synchronization is required if the dictionary is not being modified by any threads. + +## ConcurrentBag + + In pure producer-consumer scenarios, will probably perform more slowly than the other concurrent collection types. + + In mixed producer-consumer scenarios, is generally much faster and more scalable than any other concurrent collection type for both large and small workloads. + +## BlockingCollection + + When bounding and blocking semantics are required, will probably perform faster than any custom implementation. It also supports rich cancellation, enumeration, and exception handling. + ## See also - diff --git a/docs/standard/collections/when-to-use-generic-collections.md b/docs/standard/collections/when-to-use-generic-collections.md index 278e75dfda3d4..f6c33f43b60f3 100644 --- a/docs/standard/collections/when-to-use-generic-collections.md +++ b/docs/standard/collections/when-to-use-generic-collections.md @@ -2,7 +2,7 @@ description: "Learn more about: When to use generic collections" title: "When to Use Generic Collections" ms.date: 04/30/2020 -helpviewer_keywords: +helpviewer_keywords: - "collections [.NET], generic" - "generic collections [.NET]" ms.assetid: e7b868b1-11fe-4ac5-bed3-de68aca47739 @@ -16,52 +16,52 @@ For programs that target .NET Standard 1.0 or later, use the generic collection The following generic types correspond to existing collection types: -- is the generic class that corresponds to . +- is the generic class that corresponds to . -- and are the generic classes that correspond to . +- and are the generic classes that correspond to . -- is the generic class that corresponds to . can be used as a base class, but unlike , it is not abstract, which makes it much easier to use. +- is the generic class that corresponds to . can be used as a base class, but unlike , it is not abstract, which makes it much easier to use. -- is the generic class that corresponds to . is not abstract and has a constructor that makes it easy to expose an existing as a read-only collection. +- is the generic class that corresponds to . is not abstract and has a constructor that makes it easy to expose an existing as a read-only collection. -- The , , , , , and generic classes correspond to the respective nongeneric classes with the same names. +- The , , , , , and generic classes correspond to the respective nongeneric classes with the same names. ## Additional Types Several generic collection types do not have nongeneric counterparts. They include the following: -- is a general-purpose linked list that provides O(1) insertion and removal operations. +- is a general-purpose linked list that provides O(1) insertion and removal operations. -- is a sorted dictionary with O(log `n`) insertion and retrieval operations, which makes it a useful alternative to . +- is a sorted dictionary with O(log `n`) insertion and retrieval operations, which makes it a useful alternative to . -- is a hybrid between a list and a dictionary, which provides a way to store objects that contain their own keys. +- is a hybrid between a list and a dictionary, which provides a way to store objects that contain their own keys. -- implements a collection class with bounding and blocking functionality. +- implements a collection class with bounding and blocking functionality. -- provides fast insertion and removal of unordered elements. +- provides fast insertion and removal of unordered elements. ### Immutable builders -When you desire immutability functionality in your app, the namespace offers generic collection types you can use. All of the immutable collection types offer `Builder` classes that can optimize performance when you're performing multiple mutations. The `Builder` class batches operations in a mutable state. When all mutations have been completed, call the `ToImmutable` method to "freeze" all nodes and create an immutable generic collection, for example, an . +When you desire immutability functionality in your app, the namespace offers generic collection types you can use. All of the immutable collection types offer `Builder` classes that can optimize performance when you're performing multiple mutations. The `Builder` class batches operations in a mutable state. When all mutations have been completed, call the `ToImmutable` method to "freeze" all nodes and create an immutable generic collection, for example, an . The `Builder` object can be created by calling the nongeneric `CreateBuilder()` method. From a `Builder` instance, you can call `ToImmutable()`. Likewise, from the `Immutable*` collection, you can call `ToBuilder()` to create a builder instance from the generic immutable collection. The following are the various `Builder` types. -- -- -- -- -- -- +- +- +- +- +- +- ## LINQ to Objects -The LINQ to Objects feature enables you to use LINQ queries to access in-memory objects as long as the object type implements the or interface. LINQ queries provide a common pattern for accessing data; are typically more concise and readable than standard `foreach` loops; and provide filtering, ordering, and grouping capabilities. LINQ queries can also improve performance. For more information, see [LINQ to Objects (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), and [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md). +The LINQ to Objects feature enables you to use LINQ queries to access in-memory objects as long as the object type implements the or interface. LINQ queries provide a common pattern for accessing data; are typically more concise and readable than standard `foreach` loops; and provide filtering, ordering, and grouping capabilities. LINQ queries can also improve performance. For more information, see [LINQ to Objects (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), and [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md). ## Additional Functionality -Some of the generic types have functionality that is not found in the nongeneric collection types. For example, the class, which corresponds to the nongeneric class, has a number of methods that accept generic delegates, such as the delegate that allows you to specify methods for searching the list, the delegate that represents methods that act on each element of the list, and the delegate that lets you define conversions between types. +Some of the generic types have functionality that is not found in the nongeneric collection types. For example, the class, which corresponds to the nongeneric class, has a number of methods that accept generic delegates, such as the delegate that allows you to specify methods for searching the list, the delegate that represents methods that act on each element of the list, and the delegate that lets you define conversions between types. -The class allows you to specify your own generic interface implementations for sorting and searching the list. The and classes also have this capability. In addition, these classes let you specify comparers when the collection is created. In similar fashion, the and classes let you specify your own equality comparers. +The class allows you to specify your own generic interface implementations for sorting and searching the list. The and classes also have this capability. In addition, these classes let you specify comparers when the collection is created. In similar fashion, the and classes let you specify your own equality comparers. ## See also diff --git a/docs/standard/data/sqlite/adonet-limitations.md b/docs/standard/data/sqlite/adonet-limitations.md index 8aa74e668377b..97beb449a55ed 100644 --- a/docs/standard/data/sqlite/adonet-limitations.md +++ b/docs/standard/data/sqlite/adonet-limitations.md @@ -9,7 +9,7 @@ Microsoft.Data.Sqlite provides implementations of many of the ADO.NET abstractio ## Database schema information -Metadata about query results is available using the method. +Metadata about query results is available using the method. `DbConnection.GetSchema()` isn't implemented. This API isn't well-defined, so we recommend retrieving database metadata directly using standard SQLite APIs like the [sqlite_master](https://www.sqlite.org/fileformat.html#storage_of_the_sql_database_schema) table and the [table_info](https://www.sqlite.org/pragma.html#pragma_table_info) PRAGMA. diff --git a/docs/standard/data/sqlite/backup.md b/docs/standard/data/sqlite/backup.md index b17e66ad4754c..e8877ff1cc79b 100644 --- a/docs/standard/data/sqlite/backup.md +++ b/docs/standard/data/sqlite/backup.md @@ -5,7 +5,7 @@ description: Learn how to use SQLite's online backup feature. --- # Online backup -SQLite can back up database files while the app is running. This functionality is available in Microsoft.Data.Sqlite as the method on `SqliteConnection`. +SQLite can back up database files while the app is running. This functionality is available in Microsoft.Data.Sqlite as the method on `SqliteConnection`. [!code-csharp[](../../../../samples/snippets/standard/data/sqlite/BackupSample/Program.cs?name=snippet_Backup)] diff --git a/docs/standard/data/sqlite/batching.md b/docs/standard/data/sqlite/batching.md index 0043cca3f23b5..da0519429f0d8 100644 --- a/docs/standard/data/sqlite/batching.md +++ b/docs/standard/data/sqlite/batching.md @@ -7,7 +7,7 @@ description: Learn how to execute a batch of SQL statements in a single command. SQLite doesn't natively support batching SQL statements together into a single command. But because there's no network involved, it wouldn't really help performance anyway. Microsoft.Data.Sqlite does, however, implement statement batching as a convenience to make it behave more like other ADO.NET providers. -When calling , statements are executed up to the first one that returns results. Calling continues executing statements until the next one that returns results or until it reaches the end of the batch. Calling or executes any remaining statements that haven't been consumed by `NextResult()`. If you don't dispose a data reader, the finalizer tries to execute the remaining statements, but any errors it encounters are ignored. Because of this, it's important to dispose `DbDataReader` objects when using batches. +When calling , statements are executed up to the first one that returns results. Calling continues executing statements until the next one that returns results or until it reaches the end of the batch. Calling or executes any remaining statements that haven't been consumed by `NextResult()`. If you don't dispose a data reader, the finalizer tries to execute the remaining statements, but any errors it encounters are ignored. Because of this, it's important to dispose `DbDataReader` objects when using batches. [!code-csharp[](../../../../samples/snippets/standard/data/sqlite/BatchingSample/Program.cs?name=snippet_Batching)] diff --git a/docs/standard/data/sqlite/collation.md b/docs/standard/data/sqlite/collation.md index 79fc6811195fb..f3e6baf94ffd9 100644 --- a/docs/standard/data/sqlite/collation.md +++ b/docs/standard/data/sqlite/collation.md @@ -15,7 +15,7 @@ Collating sequences are used by SQLite when comparing TEXT values to determine o ## Custom collation -You can also define your own collating sequences or override the built-in ones using . The following example shows overriding the NOCASE collation to support Unicode characters. The [full sample code](https://github.com/dotnet/docs/blob/main/samples/snippets/standard/data/sqlite/CollationSample/Program.cs) is available on GitHub. +You can also define your own collating sequences or override the built-in ones using . The following example shows overriding the NOCASE collation to support Unicode characters. The [full sample code](https://github.com/dotnet/docs/blob/main/samples/snippets/standard/data/sqlite/CollationSample/Program.cs) is available on GitHub. [!code-csharp[](../../../../samples/snippets/standard/data/sqlite/CollationSample/Program.cs?name=snippet_Collation)] diff --git a/docs/standard/data/sqlite/database-errors.md b/docs/standard/data/sqlite/database-errors.md index e3b0561a259f2..5e4c5635b74dd 100644 --- a/docs/standard/data/sqlite/database-errors.md +++ b/docs/standard/data/sqlite/database-errors.md @@ -12,7 +12,7 @@ Errors may be encountered any time the Microsoft.Data.Sqlite interacts with the * Opening a connection. * Beginning a transaction. * Executing a command. -* Calling . +* Calling . Consider carefully how your app will handle these errors. @@ -26,14 +26,14 @@ SQLite is aggressive when it comes to locking tables and database files. If your Whenever Microsoft.Data.Sqlite encounters a busy or locked error, it will automatically retry until it succeeds or the command timeout is reached. -You can increase the timeout of a command by setting . The default timeout is 30 seconds. A value of `0` means no timeout. +You can increase the timeout of a command by setting . The default timeout is 30 seconds. A value of `0` means no timeout. ```csharp // Retry for 60 seconds while locked command.CommandTimeout = 60; ``` -Microsoft.Data.Sqlite sometimes needs to create an implicit command object. For example, during BeginTransaction. To set the timeout for these commands, use . +Microsoft.Data.Sqlite sometimes needs to create an implicit command object. For example, during BeginTransaction. To set the timeout for these commands, use . ```csharp // Set the default timeout of all commands on this connection diff --git a/docs/standard/data/sqlite/extensions.md b/docs/standard/data/sqlite/extensions.md index e039a5c4cba37..3611c57d659c2 100644 --- a/docs/standard/data/sqlite/extensions.md +++ b/docs/standard/data/sqlite/extensions.md @@ -9,7 +9,7 @@ SQLite supports loading extensions at runtime. Extensions include things like ad .NET includes additional logic for locating native libraries in additional places like referenced NuGet packages. Unfortunately, SQLite can't leverage this logic; it calls the platform API directly to load libraries. Because of this, you may need to modify the `PATH`, `LD_LIBRARY_PATH`, or `DYLD_LIBRARY_PATH` environment variables before loading SQLite extensions. There's [a sample](https://github.com/dotnet/docs/blob/main/samples/snippets/standard/data/sqlite/ExtensionsSample/Program.cs) on GitHub that demonstrates finding binaries for the current runtime inside a referenced NuGet package. -To load an extension, call the method. Microsoft.Data.Sqlite will ensure that the extension remains loaded even if the connection is closed and reopened. +To load an extension, call the method. Microsoft.Data.Sqlite will ensure that the extension remains loaded even if the connection is closed and reopened. [!code-csharp[](../../../../samples/snippets/standard/data/sqlite/ExtensionsSample/Program.cs?name=snippet_LoadExtension)] diff --git a/docs/standard/data/sqlite/metadata.md b/docs/standard/data/sqlite/metadata.md index a35998e598eb5..97a43bd84b000 100644 --- a/docs/standard/data/sqlite/metadata.md +++ b/docs/standard/data/sqlite/metadata.md @@ -10,7 +10,7 @@ There are two APIs for retrieving metadata in ADO.NET. One retrieves metadata ab ## Query result metadata -You can retrieve metadata about the results of a query using the method on `SqliteDataReader`. The returned contains the following columns: +You can retrieve metadata about the results of a query using the method on `SqliteDataReader`. The returned contains the following columns: | Column | Type | Description | | ------------------ | ------- | ------------------------------------------------------------------------- | diff --git a/docs/standard/data/sqlite/transactions.md b/docs/standard/data/sqlite/transactions.md index a9d30feb8b331..43f234e05d31e 100644 --- a/docs/standard/data/sqlite/transactions.md +++ b/docs/standard/data/sqlite/transactions.md @@ -9,7 +9,7 @@ Transactions let you group multiple SQL statements into a single unit of work th ## Concurrency -In SQLite, only one transaction is allowed to have changes pending in the database at a time. Because of this, calls to and the `Execute` methods on may time out if another transaction takes too long to complete. +In SQLite, only one transaction is allowed to have changes pending in the database at a time. Because of this, calls to and the `Execute` methods on may time out if another transaction takes too long to complete. For more information about locking, retries, and timeouts, see [Database errors](database-errors.md). @@ -25,7 +25,7 @@ SQLite also supports **read uncommitted** when using a shared cache. This level - *Phantoms* are rows that get changed or added to meet the where clause of a query during a transaction. If allowed, the same query could return different rows when executed twice in the same transaction. -Microsoft.Data.Sqlite treats the IsolationLevel passed to as a minimum level. The actual isolation level will be promoted to either read uncommitted or serializable. +Microsoft.Data.Sqlite treats the IsolationLevel passed to as a minimum level. The actual isolation level will be promoted to either read uncommitted or serializable. The following code simulates a dirty read. Note, the connection string must include `Cache=Shared`. diff --git a/docs/standard/data/sqlite/user-defined-functions.md b/docs/standard/data/sqlite/user-defined-functions.md index a1020a4db54d6..60b5099429c2c 100644 --- a/docs/standard/data/sqlite/user-defined-functions.md +++ b/docs/standard/data/sqlite/user-defined-functions.md @@ -9,7 +9,7 @@ Most databases have a procedural dialect of SQL that you can use to define your ## Scalar functions -Scalar functions return a single, scalar value for each row in a query. Define new scalar functions and override the built-in ones using . +Scalar functions return a single, scalar value for each row in a query. Define new scalar functions and override the built-in ones using . See [Data types](types.md) for a list of supported parameter and return types for the `func` argument. @@ -39,7 +39,7 @@ The following example shows how to define the regexp function to enable its corr ## Aggregate functions -Aggregate functions return a single, aggregated value for all the rows in a query. Define and override aggregate functions using . +Aggregate functions return a single, aggregated value for all the rows in a query. Define and override aggregate functions using . The `seed` argument specifies the initial state of the context. Use this to avoid closures also. diff --git a/docs/standard/data/xml/accessing-attributes-in-the-dom.md b/docs/standard/data/xml/accessing-attributes-in-the-dom.md index de8384d608aca..dcbd06cf67f4a 100644 --- a/docs/standard/data/xml/accessing-attributes-in-the-dom.md +++ b/docs/standard/data/xml/accessing-attributes-in-the-dom.md @@ -185,7 +185,7 @@ public class Sample ## Retrieving an Individual Attribute Node -To retrieve a single attribute node from an element, the method is used. It returns an object of type **XmlAttribute**. Once you have an **XmlAttribute**, all the methods and properties available in the class are available on that object, such as finding the **OwnerElement**. +To retrieve a single attribute node from an element, the method is used. It returns an object of type **XmlAttribute**. Once you have an **XmlAttribute**, all the methods and properties available in the class are available on that object, such as finding the **OwnerElement**. ```vb Imports System.IO diff --git a/docs/standard/data/xml/accessing-strongly-typed-xml-data-using-xpathnavigator.md b/docs/standard/data/xml/accessing-strongly-typed-xml-data-using-xpathnavigator.md index 8c700f4604339..72d8f6f70ab2a 100644 --- a/docs/standard/data/xml/accessing-strongly-typed-xml-data-using-xpathnavigator.md +++ b/docs/standard/data/xml/accessing-strongly-typed-xml-data-using-xpathnavigator.md @@ -2,186 +2,186 @@ description: "Learn more about: Accessing Strongly Typed XML Data Using XPathNavigator" title: "Accessing Strongly Typed XML Data Using XPathNavigator" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 898e0f52-8a7c-4d1f-afcd-6ffb28b050b4 --- # Accessing Strongly Typed XML Data Using XPathNavigator -As an instance of the XPath 2.0 data model, the class can contain strongly typed data that maps to common language runtime (CLR) types. According to the XPath 2.0 data model, only elements and attributes can contain strongly typed data. The class provides mechanisms for accessing data within an or object as strongly typed data as well as mechanisms for converting from one data type to another. - -## Type Information Exposed by XPathNavigator - - XML 1.0 data is technically without type, unless processed with a DTD, XML schema definition language (XSD) schema, or other mechanism. There are a number of categories of type information that can be associated with an XML element or attribute. - -- Simple CLR Types: None of the XML Schema languages support Common Language Runtime (CLR) types directly. Because it is useful to be able to view simple element and attribute content as the most appropriate CLR type, all simple content can be typed as in the absence of schema information with any added schema information potentially refining this content to a more appropriate type. You can find the best matching CLR type of simple element and attribute content by using the property. For more information about the mapping from schema built-in types to CLR types, see [Type Support in the System.Xml Classes](type-support-in-the-system-xml-classes.md). - -- Lists of Simple (CLR) Types: An element or attribute with simple content can contain a list of values separated by white space. The values are specified by an XML Schema to be a "list type." In the absence of an XML Schema, such simple content would be treated as a single text node. When an XML Schema is available, this simple content can be exposed as a series of atomic values each having a simple type that maps to a collection of CLR objects. For more information about the mapping from schema built-in types to CLR types, see [Type Support in the System.Xml Classes](type-support-in-the-system-xml-classes.md). - -- Typed Value: A schema-validated attribute or element with a simple type has a typed value. This value is a primitive type such as a numeric, string, or date type. All the built-in simple types in XSD can be mapped to CLR types that provide access to the value of a node as a more appropriate type instead of just as a . An element with attributes or element children is considered to be a complex type. The typed value of a complex type with simple content (only text nodes as children) is the same as that of the simple type of its content. The typed value of a complex type with complex content (one or more child elements) is the string value of the concatenation of all its child text nodes returned as a . For more information about the mapping from schema built-in types to CLR types, see [Type Support in the System.Xml Classes](type-support-in-the-system-xml-classes.md). - -- Schema-Language Specific Type Name: In most cases, the CLR types, which are set as a side-effect of applying an external schema, are used to provide access to the value of a node. However, there may be situations where you may want to examine the type associated with a particular schema applied to an XML document. For example, you may wish to search through an XML document, extracting all elements that are determined to have content of type "PurchaseOrder" according to an attached schema. Such type information can be set only as a result of schema validation and this information is accessed through the and properties of the class. For more information, see The Post Schema Validation Infoset (PSVI) section below. - -- Schema-Language Specific Type Reflection: In other cases, you may want to obtain further details of the schema-specific type applied to an XML document. For example, when reading an XML file, you may want to extract the `maxOccurs` attribute for each valid node in the XML document in order to perform some custom calculation. Because this information is set only through schema validation, it is accessed through the property of the class. For more information, see The Post Schema Validation Infoset (PSVI) section below. - -## XPathNavigator Typed Accessors - - The following table shows the various properties and methods of the class that can be used to access the type information about a node. - -|Property|Description| -|--------------|-----------------| -||This contains the XML schema type information for the node if it is valid.| -||This contains the Post Schema Validation Infoset of the node that is added after validation. This includes the XML schema type information, as well as validity information.| -||The CLR type of the typed value of the node.| -||The content of the node as one or more CLR values whose type is the closest match to the XML schema type of the node.| -||The value of the current node cast to a value, according to the XPath 2.0 casting rules for `xs:boolean`.| -||The value of the current node cast to a value, according to the XPath 2.0 casting rules for `xs:datetime`.| -||The value of the current node cast to a value, according to the XPath 2.0 casting rules for `xsd:double`.| -||The value of the current node cast to a value, according to the XPath 2.0 casting rules for `xs:integer`.| -||The value of the current node cast to a value, according to the XPath 2.0 casting rules for `xs:integer`.| -||The contents of the node cast to the target type according to the XPath 2.0 casting rules.| - - For more information about the mapping from schema built-in types to CLR types, see [Type Support in the System.Xml Classes](type-support-in-the-system-xml-classes.md). - -## The Post Schema Validation Infoset (PSVI) - - An XML Schema processor accepts an XML Infoset as input and converts it into a Post Schema Validation Infoset (PSVI). A PSVI is the original input XML infoset with new information items added and new properties added to existing information items. There are three broad classes of information added to the XML Infoset in the PSVI that are exposed by the . - -1. Validation Outcomes: Information as to whether an element or attribute was successfully validated or not. This is exposed by the property of the property of the class. - -2. Default Information: Indications as to whether the value of the element or attribute was obtained via default values specified in the schema or not. This is exposed by the property of the property of the class. - -3. Type Annotations: References to schema components that may be type definitions or element and attribute declarations. The property of the contains the specific type information of the node if it is valid. If the validity of a node is unknown, such as when it was validated then subsequently edited. then the property is set to `null` but type information is still available from the various properties of the property of the class. - - The following example illustrates using information in the Post Schema Validation Infoset exposed by the . - -```vb -Dim settings As XmlReaderSettings = New XmlReaderSettings() -settings.Schemas.Add("http://www.contoso.com/books", "books.xsd") -settings.ValidationType = ValidationType.Schema - -Dim reader As XmlReader = XmlReader.Create("books.xml", settings) - -Dim document As XmlDocument = New XmlDocument() -document.Load(reader) -Dim navigator As XPathNavigator = document.CreateNavigator() -navigator.MoveToChild("books", "http://www.contoso.com/books") -navigator.MoveToChild("book", "http://www.contoso.com/books") -navigator.MoveToChild("published", "http://www.contoso.com/books") - -Console.WriteLine(navigator.SchemaInfo.SchemaType.Name) -Console.WriteLine(navigator.SchemaInfo.Validity) -Console.WriteLine(navigator.SchemaInfo.SchemaElement.MinOccurs) -``` - -```csharp -XmlReaderSettings settings = new XmlReaderSettings(); -settings.Schemas.Add("http://www.contoso.com/books", "books.xsd"); -settings.ValidationType = ValidationType.Schema; - -XmlReader reader = XmlReader.Create("books.xml", settings); - -XmlDocument document = new XmlDocument(); -document.Load(reader); -XPathNavigator navigator = document.CreateNavigator(); -navigator.MoveToChild("books", "http://www.contoso.com/books"); -navigator.MoveToChild("book", "http://www.contoso.com/books"); -navigator.MoveToChild("published", "http://www.contoso.com/books"); - -Console.WriteLine(navigator.SchemaInfo.SchemaType.Name); -Console.WriteLine(navigator.SchemaInfo.Validity); -Console.WriteLine(navigator.SchemaInfo.SchemaElement.MinOccurs); -``` - - The example takes the `books.xml` file as input. - -```xml - - - Title - 10.00 - 2003-12-31 - - -``` - - The example also takes the `books.xsd` schema as input. - -```xml +As an instance of the XPath 2.0 data model, the class can contain strongly typed data that maps to common language runtime (CLR) types. According to the XPath 2.0 data model, only elements and attributes can contain strongly typed data. The class provides mechanisms for accessing data within an or object as strongly typed data as well as mechanisms for converting from one data type to another. + +## Type Information Exposed by XPathNavigator + + XML 1.0 data is technically without type, unless processed with a DTD, XML schema definition language (XSD) schema, or other mechanism. There are a number of categories of type information that can be associated with an XML element or attribute. + +- Simple CLR Types: None of the XML Schema languages support Common Language Runtime (CLR) types directly. Because it is useful to be able to view simple element and attribute content as the most appropriate CLR type, all simple content can be typed as in the absence of schema information with any added schema information potentially refining this content to a more appropriate type. You can find the best matching CLR type of simple element and attribute content by using the property. For more information about the mapping from schema built-in types to CLR types, see [Type Support in the System.Xml Classes](type-support-in-the-system-xml-classes.md). + +- Lists of Simple (CLR) Types: An element or attribute with simple content can contain a list of values separated by white space. The values are specified by an XML Schema to be a "list type." In the absence of an XML Schema, such simple content would be treated as a single text node. When an XML Schema is available, this simple content can be exposed as a series of atomic values each having a simple type that maps to a collection of CLR objects. For more information about the mapping from schema built-in types to CLR types, see [Type Support in the System.Xml Classes](type-support-in-the-system-xml-classes.md). + +- Typed Value: A schema-validated attribute or element with a simple type has a typed value. This value is a primitive type such as a numeric, string, or date type. All the built-in simple types in XSD can be mapped to CLR types that provide access to the value of a node as a more appropriate type instead of just as a . An element with attributes or element children is considered to be a complex type. The typed value of a complex type with simple content (only text nodes as children) is the same as that of the simple type of its content. The typed value of a complex type with complex content (one or more child elements) is the string value of the concatenation of all its child text nodes returned as a . For more information about the mapping from schema built-in types to CLR types, see [Type Support in the System.Xml Classes](type-support-in-the-system-xml-classes.md). + +- Schema-Language Specific Type Name: In most cases, the CLR types, which are set as a side-effect of applying an external schema, are used to provide access to the value of a node. However, there may be situations where you may want to examine the type associated with a particular schema applied to an XML document. For example, you may wish to search through an XML document, extracting all elements that are determined to have content of type "PurchaseOrder" according to an attached schema. Such type information can be set only as a result of schema validation and this information is accessed through the and properties of the class. For more information, see The Post Schema Validation Infoset (PSVI) section below. + +- Schema-Language Specific Type Reflection: In other cases, you may want to obtain further details of the schema-specific type applied to an XML document. For example, when reading an XML file, you may want to extract the `maxOccurs` attribute for each valid node in the XML document in order to perform some custom calculation. Because this information is set only through schema validation, it is accessed through the property of the class. For more information, see The Post Schema Validation Infoset (PSVI) section below. + +## XPathNavigator Typed Accessors + + The following table shows the various properties and methods of the class that can be used to access the type information about a node. + +|Property|Description| +|--------------|-----------------| +||This contains the XML schema type information for the node if it is valid.| +||This contains the Post Schema Validation Infoset of the node that is added after validation. This includes the XML schema type information, as well as validity information.| +||The CLR type of the typed value of the node.| +||The content of the node as one or more CLR values whose type is the closest match to the XML schema type of the node.| +||The value of the current node cast to a value, according to the XPath 2.0 casting rules for `xs:boolean`.| +||The value of the current node cast to a value, according to the XPath 2.0 casting rules for `xs:datetime`.| +||The value of the current node cast to a value, according to the XPath 2.0 casting rules for `xsd:double`.| +||The value of the current node cast to a value, according to the XPath 2.0 casting rules for `xs:integer`.| +||The value of the current node cast to a value, according to the XPath 2.0 casting rules for `xs:integer`.| +||The contents of the node cast to the target type according to the XPath 2.0 casting rules.| + + For more information about the mapping from schema built-in types to CLR types, see [Type Support in the System.Xml Classes](type-support-in-the-system-xml-classes.md). + +## The Post Schema Validation Infoset (PSVI) + + An XML Schema processor accepts an XML Infoset as input and converts it into a Post Schema Validation Infoset (PSVI). A PSVI is the original input XML infoset with new information items added and new properties added to existing information items. There are three broad classes of information added to the XML Infoset in the PSVI that are exposed by the . + +1. Validation Outcomes: Information as to whether an element or attribute was successfully validated or not. This is exposed by the property of the property of the class. + +2. Default Information: Indications as to whether the value of the element or attribute was obtained via default values specified in the schema or not. This is exposed by the property of the property of the class. + +3. Type Annotations: References to schema components that may be type definitions or element and attribute declarations. The property of the contains the specific type information of the node if it is valid. If the validity of a node is unknown, such as when it was validated then subsequently edited. then the property is set to `null` but type information is still available from the various properties of the property of the class. + + The following example illustrates using information in the Post Schema Validation Infoset exposed by the . + +```vb +Dim settings As XmlReaderSettings = New XmlReaderSettings() +settings.Schemas.Add("http://www.contoso.com/books", "books.xsd") +settings.ValidationType = ValidationType.Schema + +Dim reader As XmlReader = XmlReader.Create("books.xml", settings) + +Dim document As XmlDocument = New XmlDocument() +document.Load(reader) +Dim navigator As XPathNavigator = document.CreateNavigator() +navigator.MoveToChild("books", "http://www.contoso.com/books") +navigator.MoveToChild("book", "http://www.contoso.com/books") +navigator.MoveToChild("published", "http://www.contoso.com/books") + +Console.WriteLine(navigator.SchemaInfo.SchemaType.Name) +Console.WriteLine(navigator.SchemaInfo.Validity) +Console.WriteLine(navigator.SchemaInfo.SchemaElement.MinOccurs) +``` + +```csharp +XmlReaderSettings settings = new XmlReaderSettings(); +settings.Schemas.Add("http://www.contoso.com/books", "books.xsd"); +settings.ValidationType = ValidationType.Schema; + +XmlReader reader = XmlReader.Create("books.xml", settings); + +XmlDocument document = new XmlDocument(); +document.Load(reader); +XPathNavigator navigator = document.CreateNavigator(); +navigator.MoveToChild("books", "http://www.contoso.com/books"); +navigator.MoveToChild("book", "http://www.contoso.com/books"); +navigator.MoveToChild("published", "http://www.contoso.com/books"); + +Console.WriteLine(navigator.SchemaInfo.SchemaType.Name); +Console.WriteLine(navigator.SchemaInfo.Validity); +Console.WriteLine(navigator.SchemaInfo.SchemaElement.MinOccurs); +``` + + The example takes the `books.xml` file as input. + +```xml + + + Title + 10.00 + 2003-12-31 + + +``` + + The example also takes the `books.xsd` schema as input. + +```xml - - - - - - - - - - - - - - - - - - - - -``` - -## Obtain Typed Values Using ValueAs Properties - - The typed value of a node can be retrieved by accessing the property of the . In certain cases you may want to convert the typed value of a node to a different type. A common example is to get a numeric value from an XML node. For example, consider the following unvalidated and untyped XML document. - -```xml - - - Title - 10.00 - 2003-12-31 - - -``` - - If the is positioned on the `price` element the property would be `null`, the property would be , and the property would be the string `10.00`. - - However, it is still possible to extract the value as a numeric value using the , , , or method and properties. The following example illustrates performing such a cast using the method. - -```vb -Dim document As New XmlDocument() -document.Load("books.xml") -Dim navigator As XPathNavigator = document.CreateNavigator() -navigator.MoveToChild("books", "") -navigator.MoveToChild("book", "") -navigator.MoveToChild("price", "") - -Dim price = navigator.ValueAs(GetType(Decimal)) -Dim discount As Decimal = 0.2 - -Console.WriteLine("The price of the book has been dropped 20% from {0:C} to {1:C}", navigator.Value, (price - price * discount)) -``` - -```csharp -XmlDocument document = new XmlDocument(); -document.Load("books.xml"); -XPathNavigator navigator = document.CreateNavigator(); -navigator.MoveToChild("books", ""); -navigator.MoveToChild("book", ""); -navigator.MoveToChild("price", ""); - -Decimal price = (decimal)navigator.ValueAs(typeof(decimal)); - -Console.WriteLine("The price of the book has been dropped 20% from {0:C} to {1:C}", navigator.Value, (price - price * (decimal)0.20)); -``` - - For more information about the mapping from schema built-in types to CLR types, see [Type Support in the System.Xml Classes](type-support-in-the-system-xml-classes.md). - +xmlns:xs="http://www.w3.org/2001/XMLSchema"> + + + + + + + + + + + + + + + + + + + + +``` + +## Obtain Typed Values Using ValueAs Properties + + The typed value of a node can be retrieved by accessing the property of the . In certain cases you may want to convert the typed value of a node to a different type. A common example is to get a numeric value from an XML node. For example, consider the following unvalidated and untyped XML document. + +```xml + + + Title + 10.00 + 2003-12-31 + + +``` + + If the is positioned on the `price` element the property would be `null`, the property would be , and the property would be the string `10.00`. + + However, it is still possible to extract the value as a numeric value using the , , , or method and properties. The following example illustrates performing such a cast using the method. + +```vb +Dim document As New XmlDocument() +document.Load("books.xml") +Dim navigator As XPathNavigator = document.CreateNavigator() +navigator.MoveToChild("books", "") +navigator.MoveToChild("book", "") +navigator.MoveToChild("price", "") + +Dim price = navigator.ValueAs(GetType(Decimal)) +Dim discount As Decimal = 0.2 + +Console.WriteLine("The price of the book has been dropped 20% from {0:C} to {1:C}", navigator.Value, (price - price * discount)) +``` + +```csharp +XmlDocument document = new XmlDocument(); +document.Load("books.xml"); +XPathNavigator navigator = document.CreateNavigator(); +navigator.MoveToChild("books", ""); +navigator.MoveToChild("book", ""); +navigator.MoveToChild("price", ""); + +Decimal price = (decimal)navigator.ValueAs(typeof(decimal)); + +Console.WriteLine("The price of the book has been dropped 20% from {0:C} to {1:C}", navigator.Value, (price - price * (decimal)0.20)); +``` + + For more information about the mapping from schema built-in types to CLR types, see [Type Support in the System.Xml Classes](type-support-in-the-system-xml-classes.md). + ## See also - diff --git a/docs/standard/data/xml/attribute-and-namespace-node-navigation-using-xpathnavigator.md b/docs/standard/data/xml/attribute-and-namespace-node-navigation-using-xpathnavigator.md index b75d3fd56a91b..3750b07decc08 100644 --- a/docs/standard/data/xml/attribute-and-namespace-node-navigation-using-xpathnavigator.md +++ b/docs/standard/data/xml/attribute-and-namespace-node-navigation-using-xpathnavigator.md @@ -6,92 +6,92 @@ ms.assetid: 23975f88-e0af-4b88-93de-9e20e11880ad --- # Attribute and Namespace Node Navigation Using XPathNavigator -The class provides two sets of navigation methods, the first set, found in the [Node Set Navigation Using XPathNavigator](node-set-navigation-using-xpathnavigator.md) topic, are used to navigate *node sets* in an or object. The second set, described in this topic, are used to navigate *attribute and namespace nodes* in an or object. - -## Attribute Node Navigation - - Attributes are properties of an element, not children of an element. This distinction is important, because of the methods of the class used to navigate sibling, parent, and child nodes. - - For example, the and methods are not used to navigate from an element to an attribute or between attributes. Instead, attributes have distinct methods of navigation. - - The following are the attribute navigation methods of the class. - -- - -- - -- - - When the current node is an element, you can use the property to see if there are any attributes associated with the element. After it is known that an element has attributes, there are multiple methods for accessing attributes. To retrieve a single attribute from the element, use the method. To move the to a particular attribute, use the method. You can also iterate over each attribute of an element by using the method, followed by multiple calls to the method. - +The class provides two sets of navigation methods, the first set, found in the [Node Set Navigation Using XPathNavigator](node-set-navigation-using-xpathnavigator.md) topic, are used to navigate *node sets* in an or object. The second set, described in this topic, are used to navigate *attribute and namespace nodes* in an or object. + +## Attribute Node Navigation + + Attributes are properties of an element, not children of an element. This distinction is important, because of the methods of the class used to navigate sibling, parent, and child nodes. + + For example, the and methods are not used to navigate from an element to an attribute or between attributes. Instead, attributes have distinct methods of navigation. + + The following are the attribute navigation methods of the class. + +- + +- + +- + + When the current node is an element, you can use the property to see if there are any attributes associated with the element. After it is known that an element has attributes, there are multiple methods for accessing attributes. To retrieve a single attribute from the element, use the method. To move the to a particular attribute, use the method. You can also iterate over each attribute of an element by using the method, followed by multiple calls to the method. + > [!NOTE] -> When the object is positioned on an attribute or namespace node, the , , , , , and methods always return `false`, and have no effect on the position of the . The exceptions are the , , and methods. - -## Namespace Node Navigation - - Each element has an associated set of namespace nodes, one for each distinct namespace prefix that is bound to a namespace URI in scope for the element (including the XML prefix bound to the `http://www.w3.org/XML/1998/namespace` namespace, which is implicitly declared in every XML document) and one for the default namespace if one is in scope for the element. The element is the parent of each of these namespace nodes; however, a namespace node is not a child of its parent element. - - As with attributes, the and methods are not used to navigate from an element to a namespace node, or between namespace nodes. Instead, namespace nodes have distinct methods of navigation. - - The following are the namespace navigation methods of the class. - -- - -- - -- - - There is always at least one namespace node in scope for any element in an XML document. This is the namespace node with the prefix `xml` and namespace URI `http://www.w3.org/XML/1998/namespace`. To retrieve a namespace URI in scope given a particular prefix, use the method. To move the object to a particular namespace node, use the method. You can also iterate over each namespace node in scope for an element by using the method followed by multiple calls to the method. - +> When the object is positioned on an attribute or namespace node, the , , , , , and methods always return `false`, and have no effect on the position of the . The exceptions are the , , and methods. + +## Namespace Node Navigation + + Each element has an associated set of namespace nodes, one for each distinct namespace prefix that is bound to a namespace URI in scope for the element (including the XML prefix bound to the `http://www.w3.org/XML/1998/namespace` namespace, which is implicitly declared in every XML document) and one for the default namespace if one is in scope for the element. The element is the parent of each of these namespace nodes; however, a namespace node is not a child of its parent element. + + As with attributes, the and methods are not used to navigate from an element to a namespace node, or between namespace nodes. Instead, namespace nodes have distinct methods of navigation. + + The following are the namespace navigation methods of the class. + +- + +- + +- + + There is always at least one namespace node in scope for any element in an XML document. This is the namespace node with the prefix `xml` and namespace URI `http://www.w3.org/XML/1998/namespace`. To retrieve a namespace URI in scope given a particular prefix, use the method. To move the object to a particular namespace node, use the method. You can also iterate over each namespace node in scope for an element by using the method followed by multiple calls to the method. + > [!NOTE] -> When the object is positioned on an attribute or namespace node, the , , , , , and methods always return `false`, and have no effect on the position of the . The exceptions are the , , and methods. - -### The XPathNamespaceScope Enumeration - - When navigating namespace nodes the and methods can be called with an parameter. These methods behave differently than their counterparts called with no parameters. The enumeration has values of , , or . - - The following examples show what namespaces are returned by the and methods at various scopes in an XML document. - -```xml - - - - - -``` - - The namespace sequence (the namespace the is positioned upon after calling the method followed by a series of calls to the method) is as follows. - -- When positioned on `element2`: `xmlns:books="http://www.contoso.com/books"`, `xmlns="http://www.contoso.com"`, and `xmlns:xml="http://www.w3.org/XML/1998/namespace"`. - -- When positioned on `element1`: `xmlns:books="http://www.contoso.com/books"`, `xmlns="http://www.contoso.com"`, and `xmlns:xml="http://www.w3.org/XML/1998/namespace"`. - -- When positioned on `root`: `xmlns:xml="http://www.w3.org/XML/1998/namespace".` - +> When the object is positioned on an attribute or namespace node, the , , , , , and methods always return `false`, and have no effect on the position of the . The exceptions are the , , and methods. + +### The XPathNamespaceScope Enumeration + + When navigating namespace nodes the and methods can be called with an parameter. These methods behave differently than their counterparts called with no parameters. The enumeration has values of , , or . + + The following examples show what namespaces are returned by the and methods at various scopes in an XML document. + +```xml + + + + + +``` + + The namespace sequence (the namespace the is positioned upon after calling the method followed by a series of calls to the method) is as follows. + +- When positioned on `element2`: `xmlns:books="http://www.contoso.com/books"`, `xmlns="http://www.contoso.com"`, and `xmlns:xml="http://www.w3.org/XML/1998/namespace"`. + +- When positioned on `element1`: `xmlns:books="http://www.contoso.com/books"`, `xmlns="http://www.contoso.com"`, and `xmlns:xml="http://www.w3.org/XML/1998/namespace"`. + +- When positioned on `root`: `xmlns:xml="http://www.w3.org/XML/1998/namespace".` + > [!NOTE] -> The class returns namespace nodes in reverse document order. Therefore, essentially moves to the last namespace node in the current scope. - - The following examples show what namespaces are returned by the and methods with the enumeration specified at various scopes in an XML document. - -```xml - - - - - -``` - - When positioned on `child2`, the namespace sequence (the namespace the is positioned upon after calling the method followed by a series of calls to the method) is as follows. - -- : `xmlns:c="urn:c"`, `xmlns:a="urn:a"`, `xmlns=""`, `xmlns:b="http://www.contoso.com/b"`, `xmlns:a="http://www.contoso.com/a"`, `xmlns="http://www.contoso.com"`, and `xmlns:xml="http://www.w3.org/XML/1998/namespace"`. - -- : `xmlns:c="urn:c"`, `xmlns:a="urn:a"`, `xmlns=""`, `xmlns:b="http://www.contoso.com/b"`, `xmlns:a="http://www.contoso.com/a"`, and `xmlns="http://www.contoso.com"`. - -- : `xmlns:c="urn:c"`. - +> The class returns namespace nodes in reverse document order. Therefore, essentially moves to the last namespace node in the current scope. + + The following examples show what namespaces are returned by the and methods with the enumeration specified at various scopes in an XML document. + +```xml + + + + + +``` + + When positioned on `child2`, the namespace sequence (the namespace the is positioned upon after calling the method followed by a series of calls to the method) is as follows. + +- : `xmlns:c="urn:c"`, `xmlns:a="urn:a"`, `xmlns=""`, `xmlns:b="http://www.contoso.com/b"`, `xmlns:a="http://www.contoso.com/a"`, `xmlns="http://www.contoso.com"`, and `xmlns:xml="http://www.w3.org/XML/1998/namespace"`. + +- : `xmlns:c="urn:c"`, `xmlns:a="urn:a"`, `xmlns=""`, `xmlns:b="http://www.contoso.com/b"`, `xmlns:a="http://www.contoso.com/a"`, and `xmlns="http://www.contoso.com"`. + +- : `xmlns:c="urn:c"`. + > [!NOTE] -> The class returns namespace nodes in reverse document order. Therefore, essentially moves to the last namespace node in the current scope. - +> The class returns namespace nodes in reverse document order. Therefore, essentially moves to the last namespace node in the current scope. + ## See also - diff --git a/docs/standard/data/xml/building-xml-schemas.md b/docs/standard/data/xml/building-xml-schemas.md index d5254975adbbc..e63a15470adda 100644 --- a/docs/standard/data/xml/building-xml-schemas.md +++ b/docs/standard/data/xml/building-xml-schemas.md @@ -18,18 +18,18 @@ The classes in the namespa The code examples build the customer schema from the bottom up, creating the child elements, attributes, and their corresponding types first, and then the top-level elements. - In the following code example, the `FirstName` and `LastName` elements, as well as the `CustomerId` attribute of the customer schema are created using the and classes of the SOM. Apart from the properties of the and classes, which correspond to the "name" attribute of the `` and `` elements in an XML schema, all other attributes allowed by the schema (`defaultValue`, `fixedValue`, `form`, and so on) have corresponding properties in the and classes. + In the following code example, the `FirstName` and `LastName` elements, as well as the `CustomerId` attribute of the customer schema are created using the and classes of the SOM. Apart from the properties of the and classes, which correspond to the "name" attribute of the `` and `` elements in an XML schema, all other attributes allowed by the schema (`defaultValue`, `fixedValue`, `form`, and so on) have corresponding properties in the and classes. [!code-csharp[XmlSchemaCreateExample#2](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaCreateExample/CS/XmlSchemaCreateExample.cs#2)] [!code-vb[XmlSchemaCreateExample#2](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XmlSchemaCreateExample/VB/XmlSchemaCreateExample.vb#2)] ### Creating Schema Types - The content of elements and attributes is defined by their types. To create elements and attributes whose types are one of the built-in schema types, the property of the or classes are set with the corresponding qualified name of the built-in type using the class. To create a user-defined type for elements and attributes, a new simple or complex type is created using the or class. + The content of elements and attributes is defined by their types. To create elements and attributes whose types are one of the built-in schema types, the property of the or classes are set with the corresponding qualified name of the built-in type using the class. To create a user-defined type for elements and attributes, a new simple or complex type is created using the or class. > [!NOTE] -> To create unnamed simple or complex types that are anonymous children of an element or attribute (only simple types apply for attributes), set the property of the or classes to the unnamed simple or complex type, instead of the property of the or classes. +> To create unnamed simple or complex types that are anonymous children of an element or attribute (only simple types apply for attributes), set the property of the or classes to the unnamed simple or complex type, instead of the property of the or classes. - XML schemas allow both anonymous and named simple types to be derived by restriction from other simple types (built-in or user-defined) or constructed as a list or union of other simple types. The class is used to create a simple type by restricting the built-in `xs:string` type. You can also use the or classes to create list or union types. The property denotes whether it is a simple type restriction, list, or union. + XML schemas allow both anonymous and named simple types to be derived by restriction from other simple types (built-in or user-defined) or constructed as a list or union of other simple types. The class is used to create a simple type by restricting the built-in `xs:string` type. You can also use the or classes to create list or union types. The property denotes whether it is a simple type restriction, list, or union. In the following code example, the `FirstName` element's type is the built-in type `xs:string`, the `LastName` element's type is a named simple type that is a restriction of the built-in type `xs:string`, with a `MaxLength` facet value of 20, and the `CustomerId` attribute's type is the built-in type `xs:positiveInteger`. The `Customer` element is an anonymous complex type whose particle is the sequence of the `FirstName` and `LastName` elements and whose attributes contains the `CustomerId` attribute. @@ -40,11 +40,11 @@ The classes in the namespa ### Creating and Compiling Schemas - At this point, the child elements and attributes, their corresponding types, and the top-level `Customer` element have been created in-memory using the SOM API. In the following code example, the schema element is created using the class, the top-level elements and types are added to it using the property and the complete schema is compiled using the class and written to the console. + At this point, the child elements and attributes, their corresponding types, and the top-level `Customer` element have been created in-memory using the SOM API. In the following code example, the schema element is created using the class, the top-level elements and types are added to it using the property and the complete schema is compiled using the class and written to the console. [!code-csharp[XmlSchemaCreateExample#4](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaCreateExample/CS/XmlSchemaCreateExample.cs#4)] [!code-vb[XmlSchemaCreateExample#4](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XmlSchemaCreateExample/VB/XmlSchemaCreateExample.vb#4)] - The method validates the customer schema against the rules for an XML schema and makes post-schema-compilation properties available. + The method validates the customer schema against the rules for an XML schema and makes post-schema-compilation properties available. > [!NOTE] > All post-schema-compilation properties in the SOM API differ from the Post-Schema-Validation-Infoset. diff --git a/docs/standard/data/xml/compiled-xpath-expressions.md b/docs/standard/data/xml/compiled-xpath-expressions.md index f5ca613dc889e..466a2b16526f0 100644 --- a/docs/standard/data/xml/compiled-xpath-expressions.md +++ b/docs/standard/data/xml/compiled-xpath-expressions.md @@ -2,119 +2,119 @@ description: "Learn more about: Compiled XPath Expressions" title: "Compiled XPath Expressions" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: e25dd95f-b64c-4d8b-a3a4-379e1aa0ad55 --- # Compiled XPath Expressions -An object represents a compiled XPath query returned from either the static method of the class or the method of the class. - -## The XPathExpression Class - - A compiled XPath query represented by an object is useful if the same XPath query is being used more than once. - - For example, when calling the method multiple times, instead of using a string representing the XPath query each time, use the method of the class or the method of the class to compile and cache the XPath query in an object for reuse and improved performance. - - Once compiled, the object may be used as input to the following class methods depending on the type returned from the XPath query. - -- - -- - -- - -- - -- - - The following table describes each of the W3C XPath return types, their Microsoft .NET Framework equivalencies, and what methods the object may be used with based on its return type. - -|W3C XPath Return Type|.NET Framework Equivalent Type|Description|Methods| -|---------------------------|------------------------------------|-----------------|-------------| -|`Node set`||An unordered collection of nodes without duplicates created in document order.| or | -|`Boolean`||A `true` or `false` value.| or

| -|`Number`||A floating-point number.|| -|`String`||A sequence of UCS characters.|| - +An object represents a compiled XPath query returned from either the static method of the class or the method of the class. + +## The XPathExpression Class + + A compiled XPath query represented by an object is useful if the same XPath query is being used more than once. + + For example, when calling the method multiple times, instead of using a string representing the XPath query each time, use the method of the class or the method of the class to compile and cache the XPath query in an object for reuse and improved performance. + + Once compiled, the object may be used as input to the following class methods depending on the type returned from the XPath query. + +- + +- + +- + +- + +- + + The following table describes each of the W3C XPath return types, their Microsoft .NET Framework equivalencies, and what methods the object may be used with based on its return type. + +|W3C XPath Return Type|.NET Framework Equivalent Type|Description|Methods| +|---------------------------|------------------------------------|-----------------|-------------| +|`Node set`||An unordered collection of nodes without duplicates created in document order.| or | +|`Boolean`||A `true` or `false` value.| or

| +|`Number`||A floating-point number.|| +|`String`||A sequence of UCS characters.|| + > [!NOTE] -> The method accepts an XPath expression as its parameter. The method returns an object, not one of the W3C XPath return types. - -### The ReturnType Property - - After an XPath query has been compiled into an object, you can use the property of the object to determine what the XPath query returns. - - The property returns one of the following enumeration values representing the W3C XPath return types. - -- - -- - -- - -- - -- - -- - -- - - The following example uses the object to return a number and a node set from the `books.xml` file. The property of each object as well as the results from the and methods are written to the console. - -```vb -Dim document As XPathDocument = New XPathDocument("books.xml") -Dim navigator As XPathNavigator = document.CreateNavigator() - -' Returns a number. -Dim query1 As XPathExpression = navigator.Compile("bookstore/book/price/text()*10") -Console.WriteLine(query1.ReturnType) - -Dim number As Double = CType(navigator.Evaluate(query1), Double) -Console.WriteLine(number) - -' Returns a node set. -Dim query2 As XPathExpression = navigator.Compile("bookstore/book/price") -Console.WriteLine(query2.ReturnType) - -Dim nodes As XPathNodeIterator = navigator.Select(query2) -nodes.MoveNext() -Console.WriteLine(nodes.Current.Value) -``` - -```csharp -XPathDocument document = new XPathDocument("books.xml"); -XPathNavigator navigator = document.CreateNavigator(); - -// Returns a number. -XPathExpression query1 = navigator.Compile("bookstore/book/price/text()*10"); -Console.WriteLine(query1.ReturnType); - -Double number = (Double)navigator.Evaluate(query1); -Console.WriteLine(number); - -// Returns a node set. -XPathExpression query2 = navigator.Compile("bookstore/book/price"); -Console.WriteLine(query2.ReturnType); - -XPathNodeIterator nodes = navigator.Select(query2); -nodes.MoveNext(); -Console.WriteLine(nodes.Current.Value); -``` - - The example takes the `books.xml` file as input. - - [!code-xml[XPathXMLExamples#1](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/books.xml#1)] - -### Higher Performance XPath Expressions - - For better performance, use the most specific XPath expression possible in your queries. For example, if the `book` node is a child node of the `bookstore` node and the `bookstore` node is the top-most element in an XML document, using the XPath expression `/bookstore/book` is faster than using `//book`. The `//book` XPath expression will scan every node in the XML tree to identify matching nodes. - - Additionally, using the node set navigation methods supplied by the class may result in improved performance over the selection methods supplied by the class in cases where your selection criteria are simple. For example, if you need to select the first child of the current node, it is faster to use the method than to use the `child::*[1]` XPath expression and the method. - - For more information about the node set navigation methods of the class, see [Node Set Navigation Using XPathNavigator](node-set-navigation-using-xpathnavigator.md). - +> The method accepts an XPath expression as its parameter. The method returns an object, not one of the W3C XPath return types. + +### The ReturnType Property + + After an XPath query has been compiled into an object, you can use the property of the object to determine what the XPath query returns. + + The property returns one of the following enumeration values representing the W3C XPath return types. + +- + +- + +- + +- + +- + +- + +- + + The following example uses the object to return a number and a node set from the `books.xml` file. The property of each object as well as the results from the and methods are written to the console. + +```vb +Dim document As XPathDocument = New XPathDocument("books.xml") +Dim navigator As XPathNavigator = document.CreateNavigator() + +' Returns a number. +Dim query1 As XPathExpression = navigator.Compile("bookstore/book/price/text()*10") +Console.WriteLine(query1.ReturnType) + +Dim number As Double = CType(navigator.Evaluate(query1), Double) +Console.WriteLine(number) + +' Returns a node set. +Dim query2 As XPathExpression = navigator.Compile("bookstore/book/price") +Console.WriteLine(query2.ReturnType) + +Dim nodes As XPathNodeIterator = navigator.Select(query2) +nodes.MoveNext() +Console.WriteLine(nodes.Current.Value) +``` + +```csharp +XPathDocument document = new XPathDocument("books.xml"); +XPathNavigator navigator = document.CreateNavigator(); + +// Returns a number. +XPathExpression query1 = navigator.Compile("bookstore/book/price/text()*10"); +Console.WriteLine(query1.ReturnType); + +Double number = (Double)navigator.Evaluate(query1); +Console.WriteLine(number); + +// Returns a node set. +XPathExpression query2 = navigator.Compile("bookstore/book/price"); +Console.WriteLine(query2.ReturnType); + +XPathNodeIterator nodes = navigator.Select(query2); +nodes.MoveNext(); +Console.WriteLine(nodes.Current.Value); +``` + + The example takes the `books.xml` file as input. + + [!code-xml[XPathXMLExamples#1](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/books.xml#1)] + +### Higher Performance XPath Expressions + + For better performance, use the most specific XPath expression possible in your queries. For example, if the `book` node is a child node of the `bookstore` node and the `bookstore` node is the top-most element in an XML document, using the XPath expression `/bookstore/book` is faster than using `//book`. The `//book` XPath expression will scan every node in the XML tree to identify matching nodes. + + Additionally, using the node set navigation methods supplied by the class may result in improved performance over the selection methods supplied by the class in cases where your selection criteria are simple. For example, if you need to select the first child of the current node, it is faster to use the method than to use the `child::*[1]` XPath expression and the method. + + For more information about the node set navigation methods of the class, see [Node Set Navigation Using XPathNavigator](node-set-navigation-using-xpathnavigator.md). + ## See also - diff --git a/docs/standard/data/xml/copying-existing-nodes-from-one-document-to-another.md b/docs/standard/data/xml/copying-existing-nodes-from-one-document-to-another.md index d745bee2ddb9a..08872c7487f8a 100644 --- a/docs/standard/data/xml/copying-existing-nodes-from-one-document-to-another.md +++ b/docs/standard/data/xml/copying-existing-nodes-from-one-document-to-another.md @@ -6,33 +6,33 @@ ms.assetid: 3caa78c1-3448-4b7b-b83c-228ee857635e --- # Copying Existing Nodes from One Document to Another -The **ImportNode** method is the mechanism by which a node or entire node subtree is copied from one **XmlDocument** to another. The node returned from the call is a copy of the node from the source document, including attribute values, the node name, node type, and all namespace-related attributes such as the prefix, local name, and namespace Uniform Resource Identifier (URI). The source document is not changed. After you have imported the node, you still have to add it to the tree using one of the methods used to insert nodes. - - When the node is attached to its new document, the new document owns the node. The reason is that each node, when created, has an owning document, even if the nodes are created in separate document fragments. This is a requirement of the XML Document Object Model (DOM) and is enforced by the factory creation design on the **XmlDocument** class. For example, **CreateElement**, is the only way to create new nodes. - - Depending on the node type of the imported node and the value of the *deep* parameter, additional information is copied as appropriate. This method attempts to mirror the behavior expected if a fragment of XML or HTML source was copied from one document to another, accounting for the fact that for XML, the two documents may have different document type definitions (DTDs). - - The following table describes the specific behavior for each type of node that can be imported. - -|Node Type|*deep* parameter is true|*deep* parameter is false| -|---------------|------------------------------|-------------------------------| -|XmlAttribute|The is set to **true** on the XmlAttribute. The descendants of the source **XmlAttribute** are recursively imported and the resulting nodes reassembled to form the corresponding subtree.|The *deep* parameter does not apply to **XmlAttribute** nodes, because they always carry their child nodes with them when imported.| -|XmlCDataSection|Copies the node, including its data.|Copies the node, including its data.| -|XmlComment|Copies the node, including its data.|Copies the node, including its data.| -|XmlDocumentFragment|The descendants of the source node are recursively imported and the resulting nodes reassembled to form the corresponding subtree.|An empty **XmlDocumentFragment** is created.| -|XmlDocumentType|Copies the node, including its data.*|Copies the node, including its data.*| -|XmlElement|The descendants of the source element are recursively imported and the resulting nodes reassembled to form the corresponding subtree. **Note:** Default attributes are not copied. If the document being imported into defines default attributes for this element name, those are assigned.|Specified attribute nodes of the source element are imported, and the generated **XmlAttribute** nodes are attached to the new element. The descendant nodes are not copied. **Note:** Default attributes are not copied. If the document being imported into defines default attributes for this element name, those are assigned.| -|XmlEntityReference|Because the source and destination documents could have the entities defined differently, this method only copies the **XmlEntityReference** node. The replacement text is not included. If the destination document has the entity defined, its value is assigned.|Because the source and destination documents could have the entities defined differently, this method only copies the **XmlEntityReference** node. The replacement text is not included. If the destination document has the entity defined, its value is assigned.| -|XmlProcessingInstruction|Copies the target and data value from the imported node.|Copies the target and data value from the imported node.| -|XmlText|Copies the node, including its data.|Copies the node, including its data.| -|XmlSignificantWhitespace|Copies the node, including its data.|Copies the node, including its data.| -|XmlWhitespace|Copies the node, including its data.|Copies the node, including its data.| -|XmlDeclaration|Copies the target and data value from the imported node.|Copies the target and data value from the imported node.| -|All other node types|These node types cannot be imported.|These node types cannot be imported.| - +The **ImportNode** method is the mechanism by which a node or entire node subtree is copied from one **XmlDocument** to another. The node returned from the call is a copy of the node from the source document, including attribute values, the node name, node type, and all namespace-related attributes such as the prefix, local name, and namespace Uniform Resource Identifier (URI). The source document is not changed. After you have imported the node, you still have to add it to the tree using one of the methods used to insert nodes. + + When the node is attached to its new document, the new document owns the node. The reason is that each node, when created, has an owning document, even if the nodes are created in separate document fragments. This is a requirement of the XML Document Object Model (DOM) and is enforced by the factory creation design on the **XmlDocument** class. For example, **CreateElement**, is the only way to create new nodes. + + Depending on the node type of the imported node and the value of the *deep* parameter, additional information is copied as appropriate. This method attempts to mirror the behavior expected if a fragment of XML or HTML source was copied from one document to another, accounting for the fact that for XML, the two documents may have different document type definitions (DTDs). + + The following table describes the specific behavior for each type of node that can be imported. + +|Node Type|*deep* parameter is true|*deep* parameter is false| +|---------------|------------------------------|-------------------------------| +|XmlAttribute|The is set to **true** on the XmlAttribute. The descendants of the source **XmlAttribute** are recursively imported and the resulting nodes reassembled to form the corresponding subtree.|The *deep* parameter does not apply to **XmlAttribute** nodes, because they always carry their child nodes with them when imported.| +|XmlCDataSection|Copies the node, including its data.|Copies the node, including its data.| +|XmlComment|Copies the node, including its data.|Copies the node, including its data.| +|XmlDocumentFragment|The descendants of the source node are recursively imported and the resulting nodes reassembled to form the corresponding subtree.|An empty **XmlDocumentFragment** is created.| +|XmlDocumentType|Copies the node, including its data.*|Copies the node, including its data.*| +|XmlElement|The descendants of the source element are recursively imported and the resulting nodes reassembled to form the corresponding subtree. **Note:** Default attributes are not copied. If the document being imported into defines default attributes for this element name, those are assigned.|Specified attribute nodes of the source element are imported, and the generated **XmlAttribute** nodes are attached to the new element. The descendant nodes are not copied. **Note:** Default attributes are not copied. If the document being imported into defines default attributes for this element name, those are assigned.| +|XmlEntityReference|Because the source and destination documents could have the entities defined differently, this method only copies the **XmlEntityReference** node. The replacement text is not included. If the destination document has the entity defined, its value is assigned.|Because the source and destination documents could have the entities defined differently, this method only copies the **XmlEntityReference** node. The replacement text is not included. If the destination document has the entity defined, its value is assigned.| +|XmlProcessingInstruction|Copies the target and data value from the imported node.|Copies the target and data value from the imported node.| +|XmlText|Copies the node, including its data.|Copies the node, including its data.| +|XmlSignificantWhitespace|Copies the node, including its data.|Copies the node, including its data.| +|XmlWhitespace|Copies the node, including its data.|Copies the node, including its data.| +|XmlDeclaration|Copies the target and data value from the imported node.|Copies the target and data value from the imported node.| +|All other node types|These node types cannot be imported.|These node types cannot be imported.| + > [!NOTE] -> Although DocumentType nodes can be imported, a document can only have one DocumentType. So, once you have imported the document type, before inserting it into tree you have to make sure that there is no document type in the document. For information on removing nodes, see [Removing Nodes, Content, and Values from an XML Document](removing-nodes-content-and-values-from-an-xml-document.md). - +> Although DocumentType nodes can be imported, a document can only have one DocumentType. So, once you have imported the document type, before inserting it into tree you have to make sure that there is no document type in the document. For information on removing nodes, see [Removing Nodes, Content, and Values from an XML Document](removing-nodes-content-and-values-from-an-xml-document.md). + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/create-new-nodes-in-the-dom.md b/docs/standard/data/xml/create-new-nodes-in-the-dom.md index 9174a026fd63d..64b4955655371 100644 --- a/docs/standard/data/xml/create-new-nodes-in-the-dom.md +++ b/docs/standard/data/xml/create-new-nodes-in-the-dom.md @@ -7,43 +7,43 @@ ms.assetid: 6c2b9789-b61a-49f9-b33f-db01a945edf2 # Create New Nodes in the DOM The class has a create method for all of the node types. To create a node, supply the method with a name, when required, and content or other parameters for those nodes that have content (for example, a text node). The following methods need a name and a few other parameters filled to create an appropriate node: - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - - Other node types have more requirements than just providing data to parameters. - - For information on attributes, see [Creating New Attributes for Elements in the DOM](creating-new-attributes-for-elements-in-the-dom.md). For information on element and attribute name validation, see [XML Element and Attribute Name Verification when Creating New Nodes](xml-element-and-attribute-name-verification-when-creating-new-nodes.md). For creating entity references, see [Creating New Entity References](creating-new-entity-references.md). For information on how namespaces affect the expansion of entity references, see [Namespace Affect on Entity Reference Expansion for New Nodes Containing Elements and Attributes](namespace-affect-on-entity-ref-expansion-for-new-nodes.md). - - Once new nodes are created, there are several methods available to insert them into the tree. The table lists the methods with a description of where the new node appears in the XML Document Object Model (DOM). - -|Method|Node placement| -|------------|--------------------| -||Inserted before the reference node. For example, to insert the new node in position 5:

`XmlNode refChild = node.ChildNodes[4]; // The reference is zero-based.`

`node.InsertBefore(newChild, refChild);`

For more information, see the method.| -||Inserted after the reference node. For example:

`node.InsertAfter(newChild, refChild);`

For more information, see the method.| -||Adds the node to the end of the list of child nodes for the given node. If the node being added is an , the entire contents of the document fragment are moved into the child list of this node. For more information, see the method.| -||Adds the node to the beginning of the list of child nodes of the given node. If the node being added is an , the entire contents of the document fragment are moved into the child list of this node. For more information, see the method.| -||Appends an node to the end of the attribute collection associated with an element. For more information, see the method.| - + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + + Other node types have more requirements than just providing data to parameters. + + For information on attributes, see [Creating New Attributes for Elements in the DOM](creating-new-attributes-for-elements-in-the-dom.md). For information on element and attribute name validation, see [XML Element and Attribute Name Verification when Creating New Nodes](xml-element-and-attribute-name-verification-when-creating-new-nodes.md). For creating entity references, see [Creating New Entity References](creating-new-entity-references.md). For information on how namespaces affect the expansion of entity references, see [Namespace Affect on Entity Reference Expansion for New Nodes Containing Elements and Attributes](namespace-affect-on-entity-ref-expansion-for-new-nodes.md). + + Once new nodes are created, there are several methods available to insert them into the tree. The table lists the methods with a description of where the new node appears in the XML Document Object Model (DOM). + +|Method|Node placement| +|------------|--------------------| +||Inserted before the reference node. For example, to insert the new node in position 5:

`XmlNode refChild = node.ChildNodes[4]; // The reference is zero-based.`

`node.InsertBefore(newChild, refChild);`

For more information, see the method.| +||Inserted after the reference node. For example:

`node.InsertAfter(newChild, refChild);`

For more information, see the method.| +||Adds the node to the end of the list of child nodes for the given node. If the node being added is an , the entire contents of the document fragment are moved into the child list of this node. For more information, see the method.| +||Adds the node to the beginning of the list of child nodes of the given node. If the node being added is an , the entire contents of the document fragment are moved into the child list of this node. For more information, see the method.| +||Appends an node to the end of the attribute collection associated with an element. For more information, see the method.| + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/creating-new-attributes-for-elements-in-the-dom.md b/docs/standard/data/xml/creating-new-attributes-for-elements-in-the-dom.md index f762ca85733f2..805d971010c58 100644 --- a/docs/standard/data/xml/creating-new-attributes-for-elements-in-the-dom.md +++ b/docs/standard/data/xml/creating-new-attributes-for-elements-in-the-dom.md @@ -2,7 +2,7 @@ description: "Learn more about: Creating New Attributes for Elements in the DOM" title: Creating New Attributes for Elements in the DOM ms.date: 09/02/2021 -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: dd6dc920-b011-418a-b3db-f1580a7d9251 @@ -38,8 +38,8 @@ Public Class Sample Console.WriteLine(doc.InnerXml) End Sub End Class -``` - +``` + ```csharp using System; using System.IO; @@ -67,7 +67,7 @@ public class Sample The following example shows how to create a new attribute using the **CreateAttribute** method. The attribute is then added to the attribute collection of the **book** element using the **SetAttributeNode** method. Given the following XML: - + ```xml Pride And Prejudice @@ -104,9 +104,9 @@ doc.DocumentElement.SetAttributeNode(attr); ``` -The full code sample can be found at . +The full code sample can be found at . -If you created an **XmlNamedNodeMap** of attributes, you can add an attribute by name using the method. For more information, see [Node Collections in NamedNodeMaps and NodeLists](node-collections-in-namednodemaps-and-nodelists.md). +If you created an **XmlNamedNodeMap** of attributes, you can add an attribute by name using the method. For more information, see [Node Collections in NamedNodeMaps and NodeLists](node-collections-in-namednodemaps-and-nodelists.md). ## Default attributes diff --git a/docs/standard/data/xml/editing-xml-schemas.md b/docs/standard/data/xml/editing-xml-schemas.md index b456994d8a949..da22db26789ca 100644 --- a/docs/standard/data/xml/editing-xml-schemas.md +++ b/docs/standard/data/xml/editing-xml-schemas.md @@ -14,7 +14,7 @@ The first step in editing a schema loaded into the SOM is to traverse the schema ## Editing an XML Schema -In this section, two code examples are provided, both of which edit the customer schema created in the [Building XML Schemas](building-xml-schemas.md) topic. The first code example adds a new `PhoneNumber` element to the `Customer` element and the second code example adds a new `Title` attribute to the `FirstName` element. The first sample also uses the post-schema-compilation collection as the means of traversing the customer schema while the second code example uses the pre-schema-compilation collection. +In this section, two code examples are provided, both of which edit the customer schema created in the [Building XML Schemas](building-xml-schemas.md) topic. The first code example adds a new `PhoneNumber` element to the `Customer` element and the second code example adds a new `Title` attribute to the `FirstName` element. The first sample also uses the post-schema-compilation collection as the means of traversing the customer schema while the second code example uses the pre-schema-compilation collection. ### PhoneNumber Element Example @@ -22,17 +22,17 @@ This first code example adds a new `PhoneNumber` element to the `Customer` eleme 1. Adds the customer schema to a new object and then compiles it. Any schema validation warnings and errors encountered reading or compiling the schema are handled by the delegate. -2. Retrieves the compiled object from the by iterating over the property. Because the schema is compiled, Post-Schema-Compilation-Infoset (PSCI) properties are accessible. +2. Retrieves the compiled object from the by iterating over the property. Because the schema is compiled, Post-Schema-Compilation-Infoset (PSCI) properties are accessible. -3. Creates the `PhoneNumber` element using the class, the `xs:string` simple type restriction using the and classes, adds a pattern facet to the property of the restriction, and adds the restriction to the property of the simple type and the simple type to the of the `PhoneNumber` element. +3. Creates the `PhoneNumber` element using the class, the `xs:string` simple type restriction using the and classes, adds a pattern facet to the property of the restriction, and adds the restriction to the property of the simple type and the simple type to the of the `PhoneNumber` element. -4. Iterates over each in the collection of the post-schema-compilation collection. +4. Iterates over each in the collection of the post-schema-compilation collection. -5. If the of the element is `"Customer"`, gets the complex type of the `Customer` element using the class and the sequence particle of the complex type using the class. +5. If the of the element is `"Customer"`, gets the complex type of the `Customer` element using the class and the sequence particle of the complex type using the class. -6. Adds the new `PhoneNumber` element to the sequence containing the existing `FirstName` and `LastName` elements using the pre-schema-compilation collection of the sequence. +6. Adds the new `PhoneNumber` element to the sequence containing the existing `FirstName` and `LastName` elements using the pre-schema-compilation collection of the sequence. -7. Finally, reprocesses and compiles the modified object using the and methods of the class and writes it to the console. +7. Finally, reprocesses and compiles the modified object using the and methods of the class and writes it to the console. The following is the complete code example. [!code-csharp[XmlSchemaEditExample1#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaEditExample1/CS/XmlSchemaEditExample1.cs#1)] @@ -69,32 +69,32 @@ The code example edits the customer schema in the following steps. 1. Adds the customer schema to a new object and then compiles it. Any schema validation warnings and errors encountered reading or compiling the schema are handled by the delegate. -2. Retrieves the compiled object from the by iterating over the property. Because the schema is compiled, Post-Schema-Compilation-Infoset (PSCI) properties are accessible. +2. Retrieves the compiled object from the by iterating over the property. Because the schema is compiled, Post-Schema-Compilation-Infoset (PSCI) properties are accessible. 3. Creates a new complex type for the `FirstName` element using the class. 4. Creates a new simple content extension, with a base type of `xs:string`, using the and classes. -5. Creates the new `Title` attribute using the class, with a of `xs:string` and adds the attribute to the simple content extension. +5. Creates the new `Title` attribute using the class, with a of `xs:string` and adds the attribute to the simple content extension. 6. Sets the content model of the simple content to the simple content extension and the content model of the complex type to the simple content. -7. Adds the new complex type to the pre-schema-compilation collection. +7. Adds the new complex type to the pre-schema-compilation collection. -8. Iterates over each in the pre-schema-compilation collection. +8. Iterates over each in the pre-schema-compilation collection. > [!NOTE] -> Because the `FirstName` element is not a global element in the schema, it is not available in the or collections. The code example locates the `FirstName` element by first locating the `Customer` element. +> Because the `FirstName` element is not a global element in the schema, it is not available in the or collections. The code example locates the `FirstName` element by first locating the `Customer` element. > -> The first code example traversed the schema using the post-schema-compilation collection. In this sample, the pre-schema-compilation collection is used to traverse the schema. While both collections provide access to the global elements in the schema, iterating through the collection is more time consuming because you must iterate over all global elements in the schema and it does not have any PSCI properties. The PSCI collections (, , , and so on) provide direct access to their global elements, attributes, and types and their PSCI properties. +> The first code example traversed the schema using the post-schema-compilation collection. In this sample, the pre-schema-compilation collection is used to traverse the schema. While both collections provide access to the global elements in the schema, iterating through the collection is more time consuming because you must iterate over all global elements in the schema and it does not have any PSCI properties. The PSCI collections (, , , and so on) provide direct access to their global elements, attributes, and types and their PSCI properties. -1. If the is an element, whose is `"Customer"`, gets the complex type of the `Customer` element using the class and the sequence particle of the complex type using the class. +1. If the is an element, whose is `"Customer"`, gets the complex type of the `Customer` element using the class and the sequence particle of the complex type using the class. -2. Iterates over each in the pre-schema-compilation collection. +2. Iterates over each in the pre-schema-compilation collection. -3. If the is an element, who's is `"FirstName"`, sets the of the `FirstName` element to the new `FirstName` complex type. +3. If the is an element, who's is `"FirstName"`, sets the of the `FirstName` element to the new `FirstName` complex type. -4. Finally, reprocesses and compiles the modified object using the and methods of the class and writes it to the console. +4. Finally, reprocesses and compiles the modified object using the and methods of the class and writes it to the console. The following is the complete code example. [!code-csharp[XmlSchemaEditExample2#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaEditExample2/CS/XmlSchemaEditExample2.cs#1)] diff --git a/docs/standard/data/xml/evaluate-xpath-expressions-using-xpathnavigator.md b/docs/standard/data/xml/evaluate-xpath-expressions-using-xpathnavigator.md index e6f29a565d83b..81bed1f4eba08 100644 --- a/docs/standard/data/xml/evaluate-xpath-expressions-using-xpathnavigator.md +++ b/docs/standard/data/xml/evaluate-xpath-expressions-using-xpathnavigator.md @@ -2,45 +2,45 @@ description: "Learn more about: Evaluate XPath Expressions using XPathNavigator" title: "Evaluate XPath Expressions using XPathNavigator" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 2913ccf3-f932-4363-8028-9e2d22ce6093 --- # Evaluate XPath Expressions using XPathNavigator -The class provides the method to evaluate an XPath expression. The method takes an XPath expression, evaluates it and returns a W3C XPath type of Boolean, Number, String, or Node Set based on the result of the XPath expression. - -## The Evaluate Method - - The method takes an XPath expression, evaluates it, and returns a typed result of Boolean (), Number (), String (), or Node Set (). For example, the method could be used in a mathematical method. The following example code calculates the total price of all the books in the `books.xml` file. - -```vb -Dim document As XPathDocument = New XPathDocument("books.xml") -Dim navigator As XPathNavigator = document.CreateNavigator() - -Dim query As XPathExpression = navigator.Compile("sum(//price/text())") -Dim total As Double = CType(navigator.Evaluate(query), Double) -Console.WriteLine(total) -``` - -```csharp -XPathDocument document = new XPathDocument("books.xml"); -XPathNavigator navigator = document.CreateNavigator(); - -XPathExpression query = navigator.Compile("sum(//price/text())"); -Double total = (Double)navigator.Evaluate(query); -Console.WriteLine(total); -``` - - The example takes the `books.xml` file as input. - - [!code-xml[XPathXMLExamples#1](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/books.xml#1)] - -### position and last Functions - - The method is overloaded. One of the methods takes an object as a parameter. This particular method is identical to the method that takes only an object as a parameter, except that it allows a node set argument to specify the current context to perform the evaluation on. This context is required for the XPath `position()` and `last()` functions as they are relative to the current context node. Unless used as a predicate in a location step, the `position()` and `last()` functions require a reference to a node set in order to be evaluated otherwise, the `position` and `last` functions return `0`. - +The class provides the method to evaluate an XPath expression. The method takes an XPath expression, evaluates it and returns a W3C XPath type of Boolean, Number, String, or Node Set based on the result of the XPath expression. + +## The Evaluate Method + + The method takes an XPath expression, evaluates it, and returns a typed result of Boolean (), Number (), String (), or Node Set (). For example, the method could be used in a mathematical method. The following example code calculates the total price of all the books in the `books.xml` file. + +```vb +Dim document As XPathDocument = New XPathDocument("books.xml") +Dim navigator As XPathNavigator = document.CreateNavigator() + +Dim query As XPathExpression = navigator.Compile("sum(//price/text())") +Dim total As Double = CType(navigator.Evaluate(query), Double) +Console.WriteLine(total) +``` + +```csharp +XPathDocument document = new XPathDocument("books.xml"); +XPathNavigator navigator = document.CreateNavigator(); + +XPathExpression query = navigator.Compile("sum(//price/text())"); +Double total = (Double)navigator.Evaluate(query); +Console.WriteLine(total); +``` + + The example takes the `books.xml` file as input. + + [!code-xml[XPathXMLExamples#1](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/books.xml#1)] + +### position and last Functions + + The method is overloaded. One of the methods takes an object as a parameter. This particular method is identical to the method that takes only an object as a parameter, except that it allows a node set argument to specify the current context to perform the evaluation on. This context is required for the XPath `position()` and `last()` functions as they are relative to the current context node. Unless used as a predicate in a location step, the `position()` and `last()` functions require a reference to a node set in order to be evaluated otherwise, the `position` and `last` functions return `0`. + ## See also - diff --git a/docs/standard/data/xml/extending-the-dom.md b/docs/standard/data/xml/extending-the-dom.md index 7e6986fac2ff8..3b6679334b566 100644 --- a/docs/standard/data/xml/extending-the-dom.md +++ b/docs/standard/data/xml/extending-the-dom.md @@ -2,7 +2,7 @@ description: "Learn more about: Extending the DOM" title: "Extending the DOM" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: b5489c96-4afd-439a-a25d-fc82eb4a148d @@ -21,9 +21,9 @@ There are two general guidelines when deriving new classes: ## Creating Your Own Node Instances -The class contains node creation methods. When an XML file is loaded, these methods are called to create the nodes. You can override these methods so that your node instances are created when a document is loaded. For example, if you have extended the class, you would inherit the class and override the method. +The class contains node creation methods. When an XML file is loaded, these methods are called to create the nodes. You can override these methods so that your node instances are created when a document is loaded. For example, if you have extended the class, you would inherit the class and override the method. -The following example shows how to override the method to return your implementation of the class. +The following example shows how to override the method to return your implementation of the class. ```vb Class LineInfoDocument @@ -242,7 +242,7 @@ For more information regarding node event handling, see [Events](../../events/in ## Default Attributes and the CreateElement Method -If you are overriding the method in a derived class, default attributes are not added when you are creating new elements while editing the document. This is only an issue while editing. Because the method is responsible for adding default attributes to an , you must code this functionality in the method. If you are loading an that includes default attributes, they will be handled correctly. For more information on default attributes, see [Creating New Attributes for Elements in the DOM](creating-new-attributes-for-elements-in-the-dom.md). +If you are overriding the method in a derived class, default attributes are not added when you are creating new elements while editing the document. This is only an issue while editing. Because the method is responsible for adding default attributes to an , you must code this functionality in the method. If you are loading an that includes default attributes, they will be handled correctly. For more information on default attributes, see [Creating New Attributes for Elements in the DOM](creating-new-attributes-for-elements-in-the-dom.md). ## See also diff --git a/docs/standard/data/xml/extract-xml-data-using-xpathnavigator.md b/docs/standard/data/xml/extract-xml-data-using-xpathnavigator.md index d27a87cf68bf7..c25dc8497c467 100644 --- a/docs/standard/data/xml/extract-xml-data-using-xpathnavigator.md +++ b/docs/standard/data/xml/extract-xml-data-using-xpathnavigator.md @@ -2,162 +2,162 @@ description: "Learn more about: Extract XML Data Using XPathNavigator" title: "Extract XML Data Using XPathNavigator" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 095b0987-ee4b-4595-a160-da1c956ad576 --- # Extract XML Data Using XPathNavigator -There are several different ways to represent an XML document in the Microsoft .NET Framework. This includes using a , or by using the , , , or classes. To facilitate moving between these different representations of an XML document, the class provides a number of methods and properties for extracting the XML as a , object or object. - -## Convert an XPathNavigator to a String +There are several different ways to represent an XML document in the Microsoft .NET Framework. This includes using a , or by using the , , , or classes. To facilitate moving between these different representations of an XML document, the class provides a number of methods and properties for extracting the XML as a , object or object. + +## Convert an XPathNavigator to a String + + The property of the class is used to get the markup of the entire XML document or just the markup of a single node and its child nodes. - The property of the class is used to get the markup of the entire XML document or just the markup of a single node and its child nodes. - > [!NOTE] -> The property gets the markup of just the child nodes of a node. - - The following code example shows how to save an entire XML document contained in an object as a , as well as a single node and its child nodes. - -```vb -Dim document As XPathDocument = New XPathDocument("input.xml") -Dim navigator As XPathNavigator = document.CreateNavigator() - -' Save the entire input.xml document to a string. -Dim xml As String = navigator.OuterXml - -' Now save the Root element and its child nodes to a string. -navigator.MoveToChild(XPathNodeType.Element) -Dim root As String = navigator.OuterXml -``` - -```csharp -XPathDocument document = new XPathDocument("input.xml"); -XPathNavigator navigator = document.CreateNavigator(); - -// Save the entire input.xml document to a string. -string xml = navigator.OuterXml; - -// Now save the Root element and its child nodes to a string. -navigator.MoveToChild(XPathNodeType.Element); -string root = navigator.OuterXml; -``` - -## Convert an XPathNavigator to an XmlReader - - The method is used to stream the entire contents of an XML document or just a single node and its child nodes to an object. - - When the object is created with the current node and its child nodes, the object's property is set to . When the object's method is called for the first time, the is moved to the current node of the . The new object continues to read until the end of the XML tree is reached. At this point, the method returns `false` and the object's property is set to . - - The object's position is unchanged by the creation or movement of the object. The method is only valid when positioned on an element or root node. - - The following example shows how to get an object containing the entire XML document in an object as well as a single node and its child nodes. - -```vb -Dim document As XPathDocument = New XPathDocument("books.xml") -Dim navigator As XPathNavigator = document.CreateNavigator() - -' Stream the entire XML document to the XmlReader. -Dim xml As XmlReader = navigator.ReadSubtree() - -While xml.Read() - Console.WriteLine(xml.ReadInnerXml()) -End While - -xml.Close() - -' Stream the book element and its child nodes to the XmlReader. -navigator.MoveToChild("bookstore", "") -navigator.MoveToChild("book", "") - -Dim book As XmlReader = navigator.ReadSubtree() - -While book.Read() - Console.WriteLine(book.ReadInnerXml()) -End While - -book.Close() -``` - -```csharp -XPathDocument document = new XPathDocument("books.xml"); -XPathNavigator navigator = document.CreateNavigator(); - -// Stream the entire XML document to the XmlReader. -XmlReader xml = navigator.ReadSubtree(); - -while (xml.Read()) -{ - Console.WriteLine(xml.ReadInnerXml()); -} - -xml.Close(); - -// Stream the book element and its child nodes to the XmlReader. -navigator.MoveToChild("bookstore", ""); -navigator.MoveToChild("book", ""); - -XmlReader book = navigator.ReadSubtree(); - -while (book.Read()) -{ - Console.WriteLine(book.ReadInnerXml()); -} - -book.Close(); -``` - - The example takes the `books.xml` file as input. - - [!code-xml[XPathXMLExamples#1](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/books.xml#1)] - -## Converting an XPathNavigator to an XmlWriter - - The method is used to stream the entire contents of an XML document or just a single node and its child nodes to an object. - - The object's position is unchanged by the creation of the object. - - The following example shows how to get an object containing the entire XML document in an object as well as a single node and its child nodes. - -```vb -Dim document As XPathDocument = New XPathDocument("books.xml") -Dim navigator As XPathNavigator = document.CreateNavigator() - -' Stream the entire XML document to the XmlWriter. -Dim xml As XmlWriter = XmlWriter.Create("newbooks.xml") -navigator.WriteSubtree(xml) -xml.Close() - -' Stream the book element and its child nodes to the XmlWriter. -navigator.MoveToChild("bookstore", "") -navigator.MoveToChild("book", "") - -Dim book As XmlWriter = XmlWriter.Create("book.xml") -navigator.WriteSubtree(book) -book.Close() -``` - -```csharp -XPathDocument document = new XPathDocument("books.xml"); -XPathNavigator navigator = document.CreateNavigator(); - -// Stream the entire XML document to the XmlWriter. -XmlWriter xml = XmlWriter.Create("newbooks.xml"); -navigator.WriteSubtree(xml); -xml.Close(); - -// Stream the book element and its child nodes to the XmlWriter. -navigator.MoveToChild("bookstore", ""); -navigator.MoveToChild("book", ""); - -XmlWriter book = XmlWriter.Create("book.xml"); -navigator.WriteSubtree(book); -book.Close(); -``` - - The example takes the `books.xml` file found earlier in this topic as input. - +> The property gets the markup of just the child nodes of a node. + + The following code example shows how to save an entire XML document contained in an object as a , as well as a single node and its child nodes. + +```vb +Dim document As XPathDocument = New XPathDocument("input.xml") +Dim navigator As XPathNavigator = document.CreateNavigator() + +' Save the entire input.xml document to a string. +Dim xml As String = navigator.OuterXml + +' Now save the Root element and its child nodes to a string. +navigator.MoveToChild(XPathNodeType.Element) +Dim root As String = navigator.OuterXml +``` + +```csharp +XPathDocument document = new XPathDocument("input.xml"); +XPathNavigator navigator = document.CreateNavigator(); + +// Save the entire input.xml document to a string. +string xml = navigator.OuterXml; + +// Now save the Root element and its child nodes to a string. +navigator.MoveToChild(XPathNodeType.Element); +string root = navigator.OuterXml; +``` + +## Convert an XPathNavigator to an XmlReader + + The method is used to stream the entire contents of an XML document or just a single node and its child nodes to an object. + + When the object is created with the current node and its child nodes, the object's property is set to . When the object's method is called for the first time, the is moved to the current node of the . The new object continues to read until the end of the XML tree is reached. At this point, the method returns `false` and the object's property is set to . + + The object's position is unchanged by the creation or movement of the object. The method is only valid when positioned on an element or root node. + + The following example shows how to get an object containing the entire XML document in an object as well as a single node and its child nodes. + +```vb +Dim document As XPathDocument = New XPathDocument("books.xml") +Dim navigator As XPathNavigator = document.CreateNavigator() + +' Stream the entire XML document to the XmlReader. +Dim xml As XmlReader = navigator.ReadSubtree() + +While xml.Read() + Console.WriteLine(xml.ReadInnerXml()) +End While + +xml.Close() + +' Stream the book element and its child nodes to the XmlReader. +navigator.MoveToChild("bookstore", "") +navigator.MoveToChild("book", "") + +Dim book As XmlReader = navigator.ReadSubtree() + +While book.Read() + Console.WriteLine(book.ReadInnerXml()) +End While + +book.Close() +``` + +```csharp +XPathDocument document = new XPathDocument("books.xml"); +XPathNavigator navigator = document.CreateNavigator(); + +// Stream the entire XML document to the XmlReader. +XmlReader xml = navigator.ReadSubtree(); + +while (xml.Read()) +{ + Console.WriteLine(xml.ReadInnerXml()); +} + +xml.Close(); + +// Stream the book element and its child nodes to the XmlReader. +navigator.MoveToChild("bookstore", ""); +navigator.MoveToChild("book", ""); + +XmlReader book = navigator.ReadSubtree(); + +while (book.Read()) +{ + Console.WriteLine(book.ReadInnerXml()); +} + +book.Close(); +``` + + The example takes the `books.xml` file as input. + + [!code-xml[XPathXMLExamples#1](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/books.xml#1)] + +## Converting an XPathNavigator to an XmlWriter + + The method is used to stream the entire contents of an XML document or just a single node and its child nodes to an object. + + The object's position is unchanged by the creation of the object. + + The following example shows how to get an object containing the entire XML document in an object as well as a single node and its child nodes. + +```vb +Dim document As XPathDocument = New XPathDocument("books.xml") +Dim navigator As XPathNavigator = document.CreateNavigator() + +' Stream the entire XML document to the XmlWriter. +Dim xml As XmlWriter = XmlWriter.Create("newbooks.xml") +navigator.WriteSubtree(xml) +xml.Close() + +' Stream the book element and its child nodes to the XmlWriter. +navigator.MoveToChild("bookstore", "") +navigator.MoveToChild("book", "") + +Dim book As XmlWriter = XmlWriter.Create("book.xml") +navigator.WriteSubtree(book) +book.Close() +``` + +```csharp +XPathDocument document = new XPathDocument("books.xml"); +XPathNavigator navigator = document.CreateNavigator(); + +// Stream the entire XML document to the XmlWriter. +XmlWriter xml = XmlWriter.Create("newbooks.xml"); +navigator.WriteSubtree(xml); +xml.Close(); + +// Stream the book element and its child nodes to the XmlWriter. +navigator.MoveToChild("bookstore", ""); +navigator.MoveToChild("book", ""); + +XmlWriter book = XmlWriter.Create("book.xml"); +navigator.WriteSubtree(book); +book.Close(); +``` + + The example takes the `books.xml` file found earlier in this topic as input. + ## See also - diff --git a/docs/standard/data/xml/how-to-migrate-your-xsltransform-code.md b/docs/standard/data/xml/how-to-migrate-your-xsltransform-code.md index 079c3a8089001..9bae7b565e1ac 100644 --- a/docs/standard/data/xml/how-to-migrate-your-xsltransform-code.md +++ b/docs/standard/data/xml/how-to-migrate-your-xsltransform-code.md @@ -2,95 +2,95 @@ description: "Learn more about: How to: Migrate Your XslTransform Code" title: "How to: Migrate Your XslTransform Code" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 910beb2f-cfb3-4e8e-9936-f7e0c5f4064a --- # How to: Migrate Your XslTransform Code -The class replaced the class. This newer class was designed to be very similar to . Style sheets are compiled using the method. Transforms are executed using the method. +The class replaced the class. This newer class was designed to be very similar to . Style sheets are compiled using the method. Transforms are executed using the method. + +The following procedures show common XSLT tasks, and compare the code using the class versus the class. + +## To transform a file and output to a URI + +- Code using the class. -The following procedures show common XSLT tasks, and compare the code using the class versus the class. - -## To transform a file and output to a URI - -- Code using the class. - [!code-csharp[XML_Migration#9](../../../../samples/snippets/csharp/VS_Snippets_Data/XML_Migration/CS/migration.cs#9)] - [!code-vb[XML_Migration#9](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#9)] - -- Code using the class. - + [!code-vb[XML_Migration#9](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#9)] + +- Code using the class. + [!code-csharp[XML_Migration#10](../../../../samples/snippets/csharp/VS_Snippets_Data/XML_Migration/CS/migration.cs#10)] - [!code-vb[XML_Migration#10](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#10)] - -## To compile a style sheet and use a resolver with default credentials - -- Code using the class. - + [!code-vb[XML_Migration#10](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#10)] + +## To compile a style sheet and use a resolver with default credentials + +- Code using the class. + [!code-csharp[XML_Migration#11](../../../../samples/snippets/csharp/VS_Snippets_Data/XML_Migration/CS/migration.cs#11)] - [!code-vb[XML_Migration#11](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#11)] - -- Code using the class. - + [!code-vb[XML_Migration#11](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#11)] + +- Code using the class. + [!code-csharp[XML_Migration#12](../../../../samples/snippets/csharp/VS_Snippets_Data/XML_Migration/CS/migration.cs#12)] - [!code-vb[XML_Migration#12](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#12)] - -## To use an XSLT parameter - -- Code using the class. - + [!code-vb[XML_Migration#12](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#12)] + +## To use an XSLT parameter + +- Code using the class. + [!code-csharp[XML_Migration#13](../../../../samples/snippets/csharp/VS_Snippets_Data/XML_Migration/CS/migration.cs#13)] - [!code-vb[XML_Migration#13](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#13)] - -- Code using the class. - + [!code-vb[XML_Migration#13](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#13)] + +- Code using the class. + [!code-csharp[XML_Migration#14](../../../../samples/snippets/csharp/VS_Snippets_Data/XML_Migration/CS/migration.cs#14)] - [!code-vb[XML_Migration#14](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#14)] - + [!code-vb[XML_Migration#14](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#14)] + ## To enable XSLT scripting > [!NOTE] > Script blocks are supported only in .NET Framework. They are _not_ supported on .NET Core or .NET 5 or later. - -- Code using the class. - + +- Code using the class. + [!code-csharp[XML_Migration#15](../../../../samples/snippets/csharp/VS_Snippets_Data/XML_Migration/CS/migration.cs#15)] - [!code-vb[XML_Migration#15](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#15)] - -- Code using the class. - + [!code-vb[XML_Migration#15](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#15)] + +- Code using the class. + [!code-csharp[XML_Migration#16](../../../../samples/snippets/csharp/VS_Snippets_Data/XML_Migration/CS/migration.cs#16)] - [!code-vb[XML_Migration#16](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#16)] - -## To load the results into a DOM object - -- Code using the class. - + [!code-vb[XML_Migration#16](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#16)] + +## To load the results into a DOM object + +- Code using the class. + [!code-csharp[XML_Migration#19](../../../../samples/snippets/csharp/VS_Snippets_Data/XML_Migration/CS/migration.cs#19)] - [!code-vb[XML_Migration#19](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#19)] - -- Code using the class. - + [!code-vb[XML_Migration#19](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#19)] + +- Code using the class. + > [!NOTE] - > The class does not have a method that returns the XSLT transformation results as an object. However, you can output to an XML file and load the XML file into another object. - + > The class does not have a method that returns the XSLT transformation results as an object. However, you can output to an XML file and load the XML file into another object. + [!code-csharp[XML_Migration#20](../../../../samples/snippets/csharp/VS_Snippets_Data/XML_Migration/CS/migration.cs#20)] - [!code-vb[XML_Migration#20](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#20)] - -## To stream the results into another data store - -- Code using the class. - + [!code-vb[XML_Migration#20](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#20)] + +## To stream the results into another data store + +- Code using the class. + [!code-csharp[XML_Migration#17](../../../../samples/snippets/csharp/VS_Snippets_Data/XML_Migration/CS/migration.cs#17)] - [!code-vb[XML_Migration#17](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#17)] - -- Code using the class. - + [!code-vb[XML_Migration#17](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#17)] + +- Code using the class. + [!code-csharp[XML_Migration#18](../../../../samples/snippets/csharp/VS_Snippets_Data/XML_Migration/CS/migration.cs#18)] - [!code-vb[XML_Migration#18](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#18)] - + [!code-vb[XML_Migration#18](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XML_Migration/VB/migration.vb#18)] + ## See also - [Migrating From the XslTransform Class](migrating-from-the-xsltransform-class.md) diff --git a/docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md b/docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md index 752362690febb..6fd4c1d5a21bd 100644 --- a/docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md +++ b/docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Perform an XSLT Transformation by Using an Assembly" title: "How to: Perform an XSLT Transformation by Using an Assembly" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 76ee440b-d134-4f8f-8262-b917ad6dcbf6 @@ -12,171 +12,171 @@ ms.assetid: 76ee440b-d134-4f8f-8262-b917ad6dcbf6 > [!NOTE] > Script blocks and the XSLT compiler are supported only in .NET Framework. They are _not_ supported on .NET, and assemblies compiled using xsltc.exe cannot be referenced in .NET. For more information about .NET and .NET Framework, see [Introduction to .NET - .NET ecosystem](../../../core/introduction.md#net-ecosystem). -The XSLT compiler (xsltc.exe) compiles XSLT style sheets and generates an assembly. The assembly can be passed directly into the method. - -## To copy the XML and XSLT files to your local computer - -- Copy the XSLT file to your local computer and name it Transform.xsl. - - ```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TitleAuthorGenrePublish DatePrice
- - - - - - - - - - - -
- - - - - ``` - -- Copy the XML file to your local computer and name it `books.xml`. - - ```xml - - - - Gambardella, Matthew - XML Developer's Guide - Computer - $44.95 - 2000-10-01 - - - Ralls, Kim - Midnight Rain - Fantasy - $5.95 - 2000-12-16 - - - Corets, Eva - Maeve Ascendant - Fantasy - $5.95 - 2000-11-17 - - - Randall, Cynthia - Lover Birds - Romance - $4.95 - 2000-09-02 - - - Thurman, Paula - Splish Splash - Romance - $4.95 - 2000-11-02 - - - ``` - +The XSLT compiler (xsltc.exe) compiles XSLT style sheets and generates an assembly. The assembly can be passed directly into the method. + +## To copy the XML and XSLT files to your local computer + +- Copy the XSLT file to your local computer and name it Transform.xsl. + + ```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TitleAuthorGenrePublish DatePrice
+ + + + + + + + + + + +
+ + + + + ``` + +- Copy the XML file to your local computer and name it `books.xml`. + + ```xml + + + + Gambardella, Matthew + XML Developer's Guide + Computer + $44.95 + 2000-10-01 + + + Ralls, Kim + Midnight Rain + Fantasy + $5.95 + 2000-12-16 + + + Corets, Eva + Maeve Ascendant + Fantasy + $5.95 + 2000-11-17 + + + Randall, Cynthia + Lover Birds + Romance + $4.95 + 2000-09-02 + + + Thurman, Paula + Splish Splash + Romance + $4.95 + 2000-11-02 + + + ``` + ## To compile the style sheet with the script enabled - -The following command creates two assemblies named `Transform.dll` and `Transform_Script1.dll`. This is the default behavior. Unless otherwise specified, the name of the class and the assembly defaults to the name of the main style sheet. - + +The following command creates two assemblies named `Transform.dll` and `Transform_Script1.dll`. This is the default behavior. Unless otherwise specified, the name of the class and the assembly defaults to the name of the main style sheet. + ```console -xsltc /settings:script+ Transform.xsl +xsltc /settings:script+ Transform.xsl +``` + +The following command explicitly sets the class name to Transform: + +```console +xsltc /settings:script+ /class:Transform Transform.xsl ``` - -The following command explicitly sets the class name to Transform: -```console -xsltc /settings:script+ /class:Transform Transform.xsl -``` - ## To include the compiled assembly as a reference when you compile your code - -1. You can include an assembly in Visual Studio by adding a reference in the Solution Explorer, or from the command line. - -2. For the command line with C#, use the following: - - ```console - csc myCode.cs /r:system.dll;system.xml.dll;Transform.dll - ``` - -3. For the command line with Visual Basic, use the following - - ```console - vbc myCode.vb /r:system.dll;system.xml.dll;Transform.dll - ``` - + +1. You can include an assembly in Visual Studio by adding a reference in the Solution Explorer, or from the command line. + +2. For the command line with C#, use the following: + + ```console + csc myCode.cs /r:system.dll;system.xml.dll;Transform.dll + ``` + +3. For the command line with Visual Basic, use the following + + ```console + vbc myCode.vb /r:system.dll;system.xml.dll;Transform.dll + ``` + ## To use the compiled assembly in your code - -The following example shows how to execute the XSLT transformation by using the compiled style sheet. - + +The following example shows how to execute the XSLT transformation by using the compiled style sheet. + [!code-csharp[XslTransform_XSLTC#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XslTransform_XSLTC/CS/XslTransform_XSLTC.cs#1)] -[!code-vb[XslTransform_XSLTC#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslTransform_XSLTC/VB/XslTransform_XSLTC.vb#1)] - +[!code-vb[XslTransform_XSLTC#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslTransform_XSLTC/VB/XslTransform_XSLTC.vb#1)] + To dynamically link to the compiled assembly, replace - -```csharp -xslt.Load(typeof(Transform)); -``` - -with - + ```csharp -xslt.Load(System.Reflection.Assembly.Load("Transform").GetType("Transform")); +xslt.Load(typeof(Transform)); ``` - -For more information on the `Assembly.Load` method, see . - + +with + +```csharp +xslt.Load(System.Reflection.Assembly.Load("Transform").GetType("Transform")); +``` + +For more information on the `Assembly.Load` method, see . + ## See also - diff --git a/docs/standard/data/xml/how-to-transform-a-node-fragment.md b/docs/standard/data/xml/how-to-transform-a-node-fragment.md index d21196cce0037..6be7f96127614 100644 --- a/docs/standard/data/xml/how-to-transform-a-node-fragment.md +++ b/docs/standard/data/xml/how-to-transform-a-node-fragment.md @@ -2,48 +2,48 @@ description: "Learn more about: How to: Transform a Node Fragment" title: "How to: Transform a Node Fragment" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 73a6c582-b9d7-4fa7-9a05-6d931e1f3de8 --- # How to: Transform a Node Fragment -When you transform data contained in an or object the XSLT transformations apply to a document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create a separate object containing just the node fragment, and pass that object to the method. - -## Procedures - -#### To transform a node fragment - -1. Create an object containing the source document. - -2. Locate the node fragment you wish to transform. - -3. Create separate object with just the node fragment. - -4. Pass the node fragment to the method. - -## Example - - The following example transforms a node fragment and outputs the results to the console. - +When you transform data contained in an or object the XSLT transformations apply to a document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create a separate object containing just the node fragment, and pass that object to the method. + +## Procedures + +#### To transform a node fragment + +1. Create an object containing the source document. + +2. Locate the node fragment you wish to transform. + +3. Create separate object with just the node fragment. + +4. Pass the node fragment to the method. + +## Example + + The following example transforms a node fragment and outputs the results to the console. + [!code-csharp[XSLT_NodeFrag#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XSLT_NodeFrag/CS/xslt_frag.cs#1)] - [!code-vb[XSLT_NodeFrag#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XSLT_NodeFrag/VB/xslt_frag.vb#1)] - -### Input - -##### books.xml - - [!code-xml[XML_Core_Files#1](../../../../samples/snippets/xml/VS_Snippets_Data/XML_Core_Files/XML/books.xml#1)] - -##### single.xsl - - [!code-xml[XSLT_NodeFrag#2](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_NodeFrag/XML/single.xsl#2)] - -### Output - - Book title is The Confidence Man. - + [!code-vb[XSLT_NodeFrag#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XSLT_NodeFrag/VB/xslt_frag.vb#1)] + +### Input + +##### books.xml + + [!code-xml[XML_Core_Files#1](../../../../samples/snippets/xml/VS_Snippets_Data/XML_Core_Files/XML/books.xml#1)] + +##### single.xsl + + [!code-xml[XSLT_NodeFrag#2](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_NodeFrag/XML/single.xsl#2)] + +### Output + + Book title is The Confidence Man. + ## See also - [Using the XslCompiledTransform Class](using-the-xslcompiledtransform-class.md) diff --git a/docs/standard/data/xml/including-or-importing-xml-schemas.md b/docs/standard/data/xml/including-or-importing-xml-schemas.md index 16a8c3d79ecd0..646507badd250 100644 --- a/docs/standard/data/xml/including-or-importing-xml-schemas.md +++ b/docs/standard/data/xml/including-or-importing-xml-schemas.md @@ -20,13 +20,13 @@ An XML schema may contain ``, ``, and ` object and then compiles them. Any schema validation warnings and errors encountered reading or compiling the schemas are handled by the delegate. -2. Retrieves the compiled objects for both the customer and address schemas from the by iterating over the property. Because the schemas are compiled, Post-Schema-Compilation-Infoset (PSCI) properties are accessible. +2. Retrieves the compiled objects for both the customer and address schemas from the by iterating over the property. Because the schemas are compiled, Post-Schema-Compilation-Infoset (PSCI) properties are accessible. -3. Creates an object, sets the property of the import to the namespace of the address schema, sets the property of the import to the object of the address schema, and adds the import to the property of the customer schema. +3. Creates an object, sets the property of the import to the namespace of the address schema, sets the property of the import to the object of the address schema, and adds the import to the property of the customer schema. -4. Reprocesses and compiles the modified object of the customer schema using the and methods of the class and writes it to the console. +4. Reprocesses and compiles the modified object of the customer schema using the and methods of the class and writes it to the console. -5. Finally, recursively writes all of the schemas imported into the customer schema to the console using the property of the customer schema. The property provides access to all the includes, imports, or redefines added to a schema. +5. Finally, recursively writes all of the schemas imported into the customer schema to the console using the property of the customer schema. The property provides access to all the includes, imports, or redefines added to a schema. The following is the complete code example and the customer and address schemas written to the console. [!code-csharp[XmlSchemaImportExample#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaImportExample/CS/XmlSchemaImportExample.cs#1)] diff --git a/docs/standard/data/xml/inferring-schemas-from-xml-documents.md b/docs/standard/data/xml/inferring-schemas-from-xml-documents.md index 8a8ac504b3586..79e3b8c7b229b 100644 --- a/docs/standard/data/xml/inferring-schemas-from-xml-documents.md +++ b/docs/standard/data/xml/inferring-schemas-from-xml-documents.md @@ -30,11 +30,11 @@ This topic describes how to use the ## Inferring Schemas from XML Documents - The class uses two overloaded methods to infer a schema from an XML document. + The class uses two overloaded methods to infer a schema from an XML document. - The first method is used to create a schema based on an XML document. The second method is used to infer a schema that describes multiple XML documents. For example, you can feed multiple XML documents to the method one at a time to produce a schema that describes the entire set of XML documents. + The first method is used to create a schema based on an XML document. The second method is used to infer a schema that describes multiple XML documents. For example, you can feed multiple XML documents to the method one at a time to produce a schema that describes the entire set of XML documents. - The first method infers a schema from an XML document contained in an object, and returns an object containing the inferred schema. The second method searches an object for a schema with the same target namespace as the XML document contained in the object, refines the existing schema, and returns an object containing the inferred schema. + The first method infers a schema from an XML document contained in an object, and returns an object containing the inferred schema. The second method searches an object for a schema with the same target namespace as the XML document contained in the object, refines the existing schema, and returns an object containing the inferred schema. The changes made to the refined schema are based on new structure found in the XML document. For example, as an XML document is traversed, assumptions are made about the data types found, and the schema is created based on those assumptions. However, if data is encountered on a second inference pass that differs from the original assumption, the schema is refined. The following example illustrates the refinement process. [!code-csharp[XmlSchemaInferenceExamples#4](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaInferenceExamples/CS/XmlSchemaInferenceExamples.cs#4)] @@ -73,7 +73,7 @@ This topic describes how to use the ## Schemas that Cannot be Refined - There are W3C XML Schema constructs that the XML Schema definition language (XSD) schema process cannot handle if given a type to refine and cause an exception to be thrown. Such as a complex type whose top-level compositor is anything other than a sequence. In the Schema Object Model (SOM), this corresponds to an whose property is not an instance of . + There are W3C XML Schema constructs that the XML Schema definition language (XSD) schema process cannot handle if given a type to refine and cause an exception to be thrown. Such as a complex type whose top-level compositor is anything other than a sequence. In the Schema Object Model (SOM), this corresponds to an whose property is not an instance of . ## See also diff --git a/docs/standard/data/xml/inputs-to-the-xslcompiledtransform-class.md b/docs/standard/data/xml/inputs-to-the-xslcompiledtransform-class.md index 0b1d4ee383f67..95e71a2012780 100644 --- a/docs/standard/data/xml/inputs-to-the-xslcompiledtransform-class.md +++ b/docs/standard/data/xml/inputs-to-the-xslcompiledtransform-class.md @@ -2,54 +2,54 @@ description: "Learn more about: Inputs to the XslCompiledTransform Class" title: "Inputs to the XslCompiledTransform Class" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 834049f1-ab41-449e-9f10-4a1d0701bc48 --- # Inputs to the XslCompiledTransform Class -The method accepts three input types for the source document: an object that implements the interface, an object that reads the source document, or a string URI. - +The method accepts three input types for the source document: an object that implements the interface, an object that reads the source document, or a string URI. + > [!NOTE] -> The class preserves white space by default. This is in accordance with [section 3.4 of the W3C XSLT 1.0 recommendation](https://www.w3.org/TR/xslt.html#strip). - -## IXPathNavigable Interface - - The interface is implemented in the and classes. These classes represent an in-memory cache of XML data. - -- The class is based on the W3C Document Object Model (DOM) and includes editing capabilities. - -- The class is a read-only data store based on the XPath data model. is the recommended class for XSLT processing. It provides faster performance when compared to the class. - +> The class preserves white space by default. This is in accordance with [section 3.4 of the W3C XSLT 1.0 recommendation](https://www.w3.org/TR/xslt.html#strip). + +## IXPathNavigable Interface + + The interface is implemented in the and classes. These classes represent an in-memory cache of XML data. + +- The class is based on the W3C Document Object Model (DOM) and includes editing capabilities. + +- The class is a read-only data store based on the XPath data model. is the recommended class for XSLT processing. It provides faster performance when compared to the class. + > [!NOTE] -> Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an object containing just the node fragment, and pass that object to the method. For more information, see [How to: Transform a Node Fragment](how-to-transform-a-node-fragment.md). - - The following example uses the method to transform the books.xml file to the books.html file using the transform.xsl style sheet. The books.xml and transform.xsl files can be found in this topic: [How to: Perform an XSLT Transformation by Using an Assembly](how-to-perform-an-xslt-transformation-by-using-an-assembly.md). - +> Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an object containing just the node fragment, and pass that object to the method. For more information, see [How to: Transform a Node Fragment](how-to-transform-a-node-fragment.md). + + The following example uses the method to transform the books.xml file to the books.html file using the transform.xsl style sheet. The books.xml and transform.xsl files can be found in this topic: [How to: Perform an XSLT Transformation by Using an Assembly](how-to-perform-an-xslt-transformation-by-using-an-assembly.md). + [!code-csharp[XslCompiledTransform.Transform2#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XslCompiledTransform.Transform2/CS/Program.cs#1)] - [!code-vb[XslCompiledTransform.Transform2#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Transform2/VB/Module1.vb#1)] - -## XmlReader Object - - The method loads from the current node of the through all its children. This enables you to use a portion of a document as the context document. After the method returns, the is positioned on the next node after the end of the context document. If the end of the document is reached, the is positioned at the end of file (EOF). - - The following example uses the method to transform the books.xml file to the books.html file using the transform.xsl style sheet. The books.xml and transform.xsl files can be found in this topic: [How to: Perform an XSLT Transformation by Using an Assembly](how-to-perform-an-xslt-transformation-by-using-an-assembly.md). - + [!code-vb[XslCompiledTransform.Transform2#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Transform2/VB/Module1.vb#1)] + +## XmlReader Object + + The method loads from the current node of the through all its children. This enables you to use a portion of a document as the context document. After the method returns, the is positioned on the next node after the end of the context document. If the end of the document is reached, the is positioned at the end of file (EOF). + + The following example uses the method to transform the books.xml file to the books.html file using the transform.xsl style sheet. The books.xml and transform.xsl files can be found in this topic: [How to: Perform an XSLT Transformation by Using an Assembly](how-to-perform-an-xslt-transformation-by-using-an-assembly.md). + [!code-csharp[XslCompiledTransform.Transform2#2](../../../../samples/snippets/csharp/VS_Snippets_Data/XslCompiledTransform.Transform2/CS/Program.cs#2)] - [!code-vb[XslCompiledTransform.Transform2#2](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Transform2/VB/Module1.vb#2)] - -## String URI - - You can also specify the source document URI as your XSLT input. An is used to resolve the URI. You can specify the to use by passing it to the method. If an is not specified, the method uses a default with no credentials. - - The following example uses the method to transform the books.xml file to the books.html file using the transform.xsl style sheet. The books.xml and transform.xsl files can be found in this topic: [How to: Perform an XSLT Transformation by Using an Assembly](how-to-perform-an-xslt-transformation-by-using-an-assembly.md). - + [!code-vb[XslCompiledTransform.Transform2#2](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Transform2/VB/Module1.vb#2)] + +## String URI + + You can also specify the source document URI as your XSLT input. An is used to resolve the URI. You can specify the to use by passing it to the method. If an is not specified, the method uses a default with no credentials. + + The following example uses the method to transform the books.xml file to the books.html file using the transform.xsl style sheet. The books.xml and transform.xsl files can be found in this topic: [How to: Perform an XSLT Transformation by Using an Assembly](how-to-perform-an-xslt-transformation-by-using-an-assembly.md). + [!code-csharp[XslCompiledTransform.Transform2#3](../../../../samples/snippets/csharp/VS_Snippets_Data/XslCompiledTransform.Transform2/CS/Program.cs#3)] - [!code-vb[XslCompiledTransform.Transform2#3](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Transform2/VB/Module1.vb#3)] - - For more information, see [Resolving External Resources During XSLT Processing](resolving-external-resources-during-xslt-processing.md). - + [!code-vb[XslCompiledTransform.Transform2#3](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Transform2/VB/Module1.vb#3)] + + For more information, see [Resolving External Resources During XSLT Processing](resolving-external-resources-during-xslt-processing.md). + ## See also - [XSLT Transformations](xslt-transformations.md) diff --git a/docs/standard/data/xml/insert-xml-data-using-xpathnavigator.md b/docs/standard/data/xml/insert-xml-data-using-xpathnavigator.md index 5f26997624f7c..10367e8826b7a 100644 --- a/docs/standard/data/xml/insert-xml-data-using-xpathnavigator.md +++ b/docs/standard/data/xml/insert-xml-data-using-xpathnavigator.md @@ -10,7 +10,7 @@ dev_langs: The class provides a set of methods used to insert sibling, child, and attribute nodes in an XML document. In order to use these methods, the object must be editable, that is, its property must be `true`. - objects that can edit an XML document are created by the method of the class. objects created by the class are read-only and any attempt to use the editing methods of an object created by an object results in a . + objects that can edit an XML document are created by the method of the class. objects created by the class are read-only and any attempt to use the editing methods of an object created by an object results in a . For more information about creating editable objects, see [Reading XML Data using XPathDocument and XmlDocument](reading-xml-data-using-xpathdocument-and-xmldocument.md). @@ -22,19 +22,19 @@ The class provides a set of methods used The class provides the following methods to insert sibling nodes. -- +- -- +- -- +- -- +- These methods insert sibling nodes before and after the node an object is currently positioned on. - The and methods are overloaded and accept a `string`, object, or object containing the sibling node to add as parameters. Both methods also return an object used to insert sibling nodes. + The and methods are overloaded and accept a `string`, object, or object containing the sibling node to add as parameters. Both methods also return an object used to insert sibling nodes. - The and methods insert a single sibling node before and after the node an object is currently positioned on using the namespace prefix, local name, namespace URI, and value specified as parameters. + The and methods insert a single sibling node before and after the node an object is currently positioned on using the namespace prefix, local name, namespace URI, and value specified as parameters. In the following example a new `pages` element is inserted before the `price` child element of the first `book` element in the `contosoBooks.xml` file. [!code-csharp[XPathNavigatorMethods#19](../../../../samples/snippets/csharp/VS_Snippets_Data/XPathNavigatorMethods/CS/xpathnavigatormethods.cs#19)] @@ -44,25 +44,25 @@ The class provides a set of methods used [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] - For more information about the , , and methods, see the class reference documentation. + For more information about the , , and methods, see the class reference documentation. ### Inserting Child Nodes The class provides the following methods to insert child nodes. -- +- -- +- -- +- -- +- These methods append and prepend child nodes to the end of and the beginning of the list of child nodes of the node an object is currently positioned on. - Like the methods in the "Inserting Sibling Nodes" section, the and methods accept a `string`, object, or object containing the child node to add as parameters. Both methods also return an object used to insert child nodes. + Like the methods in the "Inserting Sibling Nodes" section, the and methods accept a `string`, object, or object containing the child node to add as parameters. Both methods also return an object used to insert child nodes. - Also like the methods in the "Inserting Sibling Nodes" section, the and methods insert a single child node to the end of and the beginning of the list of child nodes of the node an object is currently positioned on using the namespace prefix, local name, namespace URI, and value specified as parameters. + Also like the methods in the "Inserting Sibling Nodes" section, the and methods insert a single child node to the end of and the beginning of the list of child nodes of the node an object is currently positioned on using the namespace prefix, local name, namespace URI, and value specified as parameters. In the following example, a new `pages` child element is appended to the list of child elements of the first `book` element in the `contosoBooks.xml` file. [!code-csharp[XPathNavigatorMethods#2](../../../../samples/snippets/csharp/VS_Snippets_Data/XPathNavigatorMethods/CS/xpathnavigatormethods.cs#2)] @@ -72,19 +72,19 @@ The class provides a set of methods used [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] - For more information about the , , and methods, see the class reference documentation. + For more information about the , , and methods, see the class reference documentation. ### Inserting Attribute Nodes The class provides the following methods to insert attribute nodes. -- +- -- +- - These methods insert attribute nodes on the element node an object is currently positioned on. The method creates an attribute node on the element node an object is currently positioned on using the namespace prefix, local name, namespace URI, and value specified as parameters. The method returns an object used to insert attribute nodes. + These methods insert attribute nodes on the element node an object is currently positioned on. The method creates an attribute node on the element node an object is currently positioned on using the namespace prefix, local name, namespace URI, and value specified as parameters. The method returns an object used to insert attribute nodes. - In the following example, new `discount` and `currency` attributes are created on the `price` child element of the first `book` element in the `contosoBooks.xml` file using the object returned from the method. + In the following example, new `discount` and `currency` attributes are created on the `price` child element of the first `book` element in the `contosoBooks.xml` file using the object returned from the method. [!code-csharp[XPathNavigatorMethods#8](../../../../samples/snippets/csharp/VS_Snippets_Data/XPathNavigatorMethods/CS/xpathnavigatormethods.cs#8)] [!code-vb[XPathNavigatorMethods#8](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb#8)] @@ -92,15 +92,15 @@ The class provides a set of methods used [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] - For more information about the and methods, see the class reference documentation. + For more information about the and methods, see the class reference documentation. ## Copying Nodes In certain cases you may want to populate an XML document with the contents from another XML document. Both the class and the class can copy nodes to an object from an existing object or object. - The , , and methods of the class all have overloads that can accept an object or an object as a parameter. + The , , and methods of the class all have overloads that can accept an object or an object as a parameter. - The method of the class has overloads that can accept an , , or object. + The method of the class has overloads that can accept an , , or object. The following example copies all the `book` elements from one document to another. @@ -142,13 +142,13 @@ document.Save("newBooks.xml"); ## Inserting Values - The class provides the and methods to insert values for a node into an object. + The class provides the and methods to insert values for a node into an object. ### Inserting Untyped Values - The method simply inserts the untyped `string` value passed as a parameter as the value of the node the object is currently positioned on. The value is inserted without any type or without verifying that the new value is valid according to the type of the node if schema information is available. + The method simply inserts the untyped `string` value passed as a parameter as the value of the node the object is currently positioned on. The value is inserted without any type or without verifying that the new value is valid according to the type of the node if schema information is available. - In the following example, the method is used to update all `price` elements in the `contosoBooks.xml` file. + In the following example, the method is used to update all `price` elements in the `contosoBooks.xml` file. [!code-csharp[XPathNavigatorMethods#47](../../../../samples/snippets/csharp/VS_Snippets_Data/XPathNavigatorMethods/CS/xpathnavigatormethods.cs#47)] [!code-vb[XPathNavigatorMethods#47](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb#47)] @@ -158,7 +158,7 @@ document.Save("newBooks.xml"); ### Inserting Typed Values - When the type of a node is a W3C XML Schema simple type, the new value inserted by the method is checked against the facets of the simple type before the value is set. If the new value is not valid according to the type of the node (for example, setting a value of `-1` on an element whose type is `xs:positiveInteger`), it results in an exception. + When the type of a node is a W3C XML Schema simple type, the new value inserted by the method is checked against the facets of the simple type before the value is set. If the new value is not valid according to the type of the node (for example, setting a value of `-1` on an element whose type is `xs:positiveInteger`), it results in an exception. The following example attempts to change the value of the `price` element of the first `book` element in the `contosoBooks.xml` file to a value. Because the XML Schema type of the `price` element is defined as `xs:decimal` in the `contosoBooks.xsd` files, this results in an exception. @@ -208,15 +208,15 @@ navigator.SetTypedValue(DateTime.Now); ## The InnerXml and OuterXml Properties - The and properties of the class change the XML markup of the nodes an object is currently positioned on. + The and properties of the class change the XML markup of the nodes an object is currently positioned on. - The property changes the XML markup of the child nodes an object is currently positioned on with the parsed contents of the given XML `string`. Similarly, the property changes the XML markup of the child nodes an object is currently positioned on as well as the current node itself. + The property changes the XML markup of the child nodes an object is currently positioned on with the parsed contents of the given XML `string`. Similarly, the property changes the XML markup of the child nodes an object is currently positioned on as well as the current node itself. - In addition to the methods described in this topic, the and properties can be used to insert nodes and values in an XML document. For more information about using the and properties to insert nodes and values, see the [Modify XML Data using XPathNavigator](modify-xml-data-using-xpathnavigator.md) topic. + In addition to the methods described in this topic, the and properties can be used to insert nodes and values in an XML document. For more information about using the and properties to insert nodes and values, see the [Modify XML Data using XPathNavigator](modify-xml-data-using-xpathnavigator.md) topic. ## Namespace and xml:lang Conflicts - Certain conflicts related to the scope of namespace and `xml:lang` declarations can occur when inserting XML data using the , , and methods of the class that take objects as parameters. + Certain conflicts related to the scope of namespace and `xml:lang` declarations can occur when inserting XML data using the , , and methods of the class that take objects as parameters. The following are the possible namespace conflicts. @@ -243,7 +243,7 @@ navigator.SetTypedValue(DateTime.Now); ## Inserting Nodes with XmlWriter - The methods used to insert sibling, child and attribute nodes described in the "Inserting Nodes and Values" section are overloaded. The , , , and methods of the class return an object used to insert nodes. + The methods used to insert sibling, child and attribute nodes described in the "Inserting Nodes and Values" section are overloaded. The , , , and methods of the class return an object used to insert nodes. ### Unsupported XmlWriter Methods @@ -253,11 +253,11 @@ navigator.SetTypedValue(DateTime.Now); |Method|Description| |------------|-----------------| -||Throws a exception.| -||Ignored at the root level and throws a exception if called at any other level in the XML document.| -||Treated as a call to the method for the equivalent character or characters.| -||Treated as a call to the method for the equivalent character or characters.| -||Treated as a call to the method for the equivalent character or characters.| +||Throws a exception.| +||Ignored at the root level and throws a exception if called at any other level in the XML document.| +||Treated as a call to the method for the equivalent character or characters.| +||Treated as a call to the method for the equivalent character or characters.| +||Treated as a call to the method for the equivalent character or characters.| For more information about the class, see the class reference documentation. @@ -267,13 +267,13 @@ navigator.SetTypedValue(DateTime.Now); The following are important notes to consider when using multiple objects. -- XML fragments written by objects are added to the XML document when the method of each object is called. Until that point, the object is writing a disconnected fragment. If an operation is performed on the XML document, any fragments being written by an object, before the has been called, are not affected. +- XML fragments written by objects are added to the XML document when the method of each object is called. Until that point, the object is writing a disconnected fragment. If an operation is performed on the XML document, any fragments being written by an object, before the has been called, are not affected. - If there is an open object on a particular XML subtree and that subtree is deleted, the object may still add to the sub-tree. The subtree simply becomes a deleted fragment. - If multiple objects are opened at the same point in the XML document, they are added to the XML document in the order in which the objects are closed, not in the order in which they were opened. - The following example creates an object, creates an object, and then uses the object returned by the method to create the structure of the first book in the `books.xml` file. The example then saves it as the `book.xml` file. + The following example creates an object, creates an object, and then uses the object returned by the method to create the structure of the first book in the `books.xml` file. The example then saves it as the `book.xml` file. ```vb Dim document As XmlDocument = New XmlDocument() diff --git a/docs/standard/data/xml/load-data-from-a-reader.md b/docs/standard/data/xml/load-data-from-a-reader.md index 7a3fbd8b0151d..01688cbfdd424 100644 --- a/docs/standard/data/xml/load-data-from-a-reader.md +++ b/docs/standard/data/xml/load-data-from-a-reader.md @@ -6,22 +6,22 @@ ms.assetid: 7e74918c-bc72-4977-a49b-e1520a6d8f60 --- # Load Data from a Reader -If an XML document is loaded using the method and a parameter of an , there are differences in the behavior that occurs when compared to the behavior of loading data from the other formats. If the reader is in its initial state, consumes the entire contents from the reader and builds the XML Document Object Model (DOM) from all the data in the reader. - - If the reader is already positioned on a node somewhere in the document, and the reader is then passed to the method, attempts to read the current node and all of its siblings, up to the end tag that closes the current depth into memory. The success of the attempted depends on the node that the reader is on when the load is attempted, as verifies that the XML from the reader is well-formed. If the XML is not well-formed, the throws an exception. For example, the following set of nodes contain two root-level elements, the XML is not well-formed, and throws an exception. - -- Comment node, followed by an Element node, followed by an Element node, followed by an EndElement node. - - The following set of nodes creates an incomplete DOM, because there is no root-level element. - -- Comment node followed by a ProcessingInstruction node followed by a Comment node followed by an EndElement node. - - This does not throw an exception, and the data is loaded. You can add a root element to the top of these nodes and create well-formed XML that can be saved without error. - - If the reader is positioned on a leaf node that is invalid for the root level of a document (for example, a white space or attribute node), the reader continues to read until it is positioned on a node that can be used for the root. The document begins loading at this point. - - By default, does not verify whether the XML is valid using document type definition (DTD) or schema validation. It only verifies whether the XML is well-formed. In order for validation to occur, you need to create an using the class. The class can enforce validation using a DTD or Schema definition language (XSD) schema. The property on the class determines whether the instance enforces validation. For more information about validating XML data, see the Remarks section of the reference page. - +If an XML document is loaded using the method and a parameter of an , there are differences in the behavior that occurs when compared to the behavior of loading data from the other formats. If the reader is in its initial state, consumes the entire contents from the reader and builds the XML Document Object Model (DOM) from all the data in the reader. + + If the reader is already positioned on a node somewhere in the document, and the reader is then passed to the method, attempts to read the current node and all of its siblings, up to the end tag that closes the current depth into memory. The success of the attempted depends on the node that the reader is on when the load is attempted, as verifies that the XML from the reader is well-formed. If the XML is not well-formed, the throws an exception. For example, the following set of nodes contain two root-level elements, the XML is not well-formed, and throws an exception. + +- Comment node, followed by an Element node, followed by an Element node, followed by an EndElement node. + + The following set of nodes creates an incomplete DOM, because there is no root-level element. + +- Comment node followed by a ProcessingInstruction node followed by a Comment node followed by an EndElement node. + + This does not throw an exception, and the data is loaded. You can add a root element to the top of these nodes and create well-formed XML that can be saved without error. + + If the reader is positioned on a leaf node that is invalid for the root level of a document (for example, a white space or attribute node), the reader continues to read until it is positioned on a node that can be used for the root. The document begins loading at this point. + + By default, does not verify whether the XML is valid using document type definition (DTD) or schema validation. It only verifies whether the XML is well-formed. In order for validation to occur, you need to create an using the class. The class can enforce validation using a DTD or Schema definition language (XSD) schema. The property on the class determines whether the instance enforces validation. For more information about validating XML data, see the Remarks section of the reference page. + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/managing-namespaces-in-an-xml-document.md b/docs/standard/data/xml/managing-namespaces-in-an-xml-document.md index 8b5fbde7fb01f..6d1c0f3ffc5e1 100644 --- a/docs/standard/data/xml/managing-namespaces-in-an-xml-document.md +++ b/docs/standard/data/xml/managing-namespaces-in-an-xml-document.md @@ -6,80 +6,80 @@ ms.assetid: 682643fc-b848-4e42-8c0d-50deeaeb5f2a --- # Managing Namespaces in an XML Document -XML namespaces associate element and attribute names in an XML document with custom and predefined URIs. To create these associations, you define prefixes for namespace URIs, and use those prefixes to qualify element and attribute names in XML data. Namespaces prevent element and attribute name collisions, and enable elements and attributes of the same name to be handled and validated differently. - +XML namespaces associate element and attribute names in an XML document with custom and predefined URIs. To create these associations, you define prefixes for namespace URIs, and use those prefixes to qualify element and attribute names in XML data. Namespaces prevent element and attribute name collisions, and enable elements and attributes of the same name to be handled and validated differently. + -## Declaring namespaces - - To declare a namespace on an element, you use the `xmlns:` attribute: - - `xmlns:=<"uri">` - - where `` is the namespace prefix and `<"uri">` is the URI that identifies the namespace. After you declare the prefix, you can use it to qualify elements and attributes in an XML document and associate them with the namespace URI. Because the namespace prefix is used throughout a document, it should be short in length. - - This example defines two `BOOK` elements. The first element is qualified by the prefix, `mybook`, and the second element is qualified by the prefix, `bb`. Each prefix is associated with a different namespace URI: - -```xml - +## Declaring namespaces + + To declare a namespace on an element, you use the `xmlns:` attribute: + + `xmlns:=<"uri">` + + where `` is the namespace prefix and `<"uri">` is the URI that identifies the namespace. After you declare the prefix, you can use it to qualify elements and attributes in an XML document and associate them with the namespace URI. Because the namespace prefix is used throughout a document, it should be short in length. + + This example defines two `BOOK` elements. The first element is qualified by the prefix, `mybook`, and the second element is qualified by the prefix, `bb`. Each prefix is associated with a different namespace URI: + +```xml + -``` - - To signify that an element is a part of a particular namespace, add the namespace prefix to it. For example, if an `Author` element belongs to the `mybook` namespace, it is declared as ``. - +``` + + To signify that an element is a part of a particular namespace, add the namespace prefix to it. For example, if an `Author` element belongs to the `mybook` namespace, it is declared as ``. + -## Declaration scope - - A namespace is effective from its point of declaration until the end of the element it was declared in. In this example, the namespace defined in the `BOOK` element doesn't apply to elements outside the `BOOK` element, such as the `Publisher` element: - -```xml -Joe Smith - - My Wonderful Day - $3.95 - - - MSPress - -``` - - A namespace must be declared before it can be used, but it doesn't have to appear at the top of the XML document. - - When you use multiple namespaces in an XML document, you can define one namespace as the default namespace to create a cleaner looking document. The default namespace is declared in the root element and applies to all unqualified elements in the document. Default namespaces apply to elements only, not to attributes. - - To use the default namespace, omit the prefix and the colon from the declaration on the element: - -```xml - +## Declaration scope + + A namespace is effective from its point of declaration until the end of the element it was declared in. In this example, the namespace defined in the `BOOK` element doesn't apply to elements outside the `BOOK` element, such as the `Publisher` element: + +```xml +Joe Smith + + My Wonderful Day + $3.95 + + + MSPress + +``` + + A namespace must be declared before it can be used, but it doesn't have to appear at the top of the XML document. + + When you use multiple namespaces in an XML document, you can define one namespace as the default namespace to create a cleaner looking document. The default namespace is declared in the root element and applies to all unqualified elements in the document. Default namespaces apply to elements only, not to attributes. + + To use the default namespace, omit the prefix and the colon from the declaration on the element: + +```xml + ... -``` - -## Managing namespaces - - The class stores a collection of namespace URIs and their prefixes, and lets you look up, add, and remove namespaces from this collection. In certain contexts, this class is required for better XML processing performance. For example, the class uses for XPath support. - - The namespace manager doesn't perform any validation on the namespaces, but assumes that prefixes and namespaces have already been verified and conform to the [W3C Namespaces](https://www.w3.org/TR/REC-xml-names/) specification. - +``` + +## Managing namespaces + + The class stores a collection of namespace URIs and their prefixes, and lets you look up, add, and remove namespaces from this collection. In certain contexts, this class is required for better XML processing performance. For example, the class uses for XPath support. + + The namespace manager doesn't perform any validation on the namespaces, but assumes that prefixes and namespaces have already been verified and conform to the [W3C Namespaces](https://www.w3.org/TR/REC-xml-names/) specification. + > [!NOTE] -> LINQ TO XML in [C#](../../linq/linq-xml-overview.md) and [Visual Basic](../../linq/linq-xml-overview.md) don't use to manage namespaces. See [Working with XML Namespaces (C#)](../../linq/namespaces-overview.md) and [Working with XML Namespaces (Visual Basic)](../../linq/namespaces-overview.md) in the LINQ documentation for information about managing namespaces when using LINQ to XML. - - Here are some of the management and lookup tasks you can perform with the class. For more information and examples, follow the links to the reference page for each method or property. - -|To|Use| -|--------|---------| -|Add a namespace| method| -|Remove a namespace| method| -|Find the URI for the default namespace| property| -|Find the URI for a namespace prefix| method| -|Find the prefix for a namespace URI| method| -|Get a list of namespaces in the current node| method| -|Scope a namespace| and methods| -|Check whether a prefix is defined in the current scope| method| -|Get the name table used to look up prefixes and URIs| property| - +> LINQ TO XML in [C#](../../linq/linq-xml-overview.md) and [Visual Basic](../../linq/linq-xml-overview.md) don't use to manage namespaces. See [Working with XML Namespaces (C#)](../../linq/namespaces-overview.md) and [Working with XML Namespaces (Visual Basic)](../../linq/namespaces-overview.md) in the LINQ documentation for information about managing namespaces when using LINQ to XML. + + Here are some of the management and lookup tasks you can perform with the class. For more information and examples, follow the links to the reference page for each method or property. + +|To|Use| +|--------|---------| +|Add a namespace| method| +|Remove a namespace| method| +|Find the URI for the default namespace| property| +|Find the URI for a namespace prefix| method| +|Find the prefix for a namespace URI| method| +|Get a list of namespaces in the current node| method| +|Scope a namespace| and methods| +|Check whether a prefix is defined in the current scope| method| +|Get the name table used to look up prefixes and URIs| property| + ## See also - diff --git a/docs/standard/data/xml/matching-nodes-using-xpathnavigator.md b/docs/standard/data/xml/matching-nodes-using-xpathnavigator.md index c756857f6d9ca..d556e6ae0518a 100644 --- a/docs/standard/data/xml/matching-nodes-using-xpathnavigator.md +++ b/docs/standard/data/xml/matching-nodes-using-xpathnavigator.md @@ -2,36 +2,36 @@ description: "Learn more about: Matching Nodes using XPathNavigator" title: "Matching Nodes using XPathNavigator" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: e6848c47-ee5d-401a-89a5-50b5eed40f30 --- # Matching Nodes using XPathNavigator -The class provides the method to determine if a node matches an XPath expression. The method takes an XPath expression as input and returns a that indicates if the current node matches the given XPath expression or the given compiled object. - -## Matching Nodes +The class provides the method to determine if a node matches an XPath expression. The method takes an XPath expression as input and returns a that indicates if the current node matches the given XPath expression or the given compiled object. + +## Matching Nodes + + The method returns `true` if the current node matches the XPath expression specified. For example, in the code example that follows, the method will return `true` if the current node is the element `b`, and element `b` has an attribute `c`. - The method returns `true` if the current node matches the XPath expression specified. For example, in the code example that follows, the method will return `true` if the current node is the element `b`, and element `b` has an attribute `c`. - > [!NOTE] -> The method does not change the state of the . - -```vb -Dim document as XPathDocument = New XPathDocument("input.xml") -Dim navigator as XPathNavigator = document.CreateNavigator() - -navigator.Matches("b[@c]") -``` - -```csharp -XPathDocument document = new XPathDocument("input.xml"); -XPathNavigator navigator = document.CreateNavigator(); - -navigator.Matches("b[@c]"); -``` - +> The method does not change the state of the . + +```vb +Dim document as XPathDocument = New XPathDocument("input.xml") +Dim navigator as XPathNavigator = document.CreateNavigator() + +navigator.Matches("b[@c]") +``` + +```csharp +XPathDocument document = new XPathDocument("input.xml"); +XPathNavigator navigator = document.CreateNavigator(); + +navigator.Matches("b[@c]"); +``` + ## See also - diff --git a/docs/standard/data/xml/migrating-from-the-xsltransform-class.md b/docs/standard/data/xml/migrating-from-the-xsltransform-class.md index 49d014f221d24..c194cc6dc163f 100644 --- a/docs/standard/data/xml/migrating-from-the-xsltransform-class.md +++ b/docs/standard/data/xml/migrating-from-the-xsltransform-class.md @@ -21,11 +21,11 @@ The class includes many performance i The class also includes other optimizations that make it much faster than the class. > [!NOTE] -> Although the overall performance of the class is better than the class, the method of the class might perform more slowly than the method of the class the first time it is called on a transformation. This is because the XSLT file must be compiled before it is loaded. For more information, see the following blog post: [XslCompiledTransform Slower than XslTransform?](/archive/blogs/antosha/xslcompiledtransform-slower-than-xsltransform) +> Although the overall performance of the class is better than the class, the method of the class might perform more slowly than the method of the class the first time it is called on a transformation. This is because the XSLT file must be compiled before it is loaded. For more information, see the following blog post: [XslCompiledTransform Slower than XslTransform?](/archive/blogs/antosha/xslcompiledtransform-slower-than-xsltransform) ## Security -By default, the class disables support for the XSLT `document()` function and embedded scripting. These features can be enabled by creating an object that has the features enabled and passing it to the method. The following example shows how to enable scripting and perform an XSLT transformation. +By default, the class disables support for the XSLT `document()` function and embedded scripting. These features can be enabled by creating an object that has the features enabled and passing it to the method. The following example shows how to enable scripting and perform an XSLT transformation. > [!NOTE] > Script blocks are supported only in .NET Framework. They are _not_ supported on .NET Core or .NET 5 or later. @@ -41,11 +41,11 @@ For more information, see [XSLT Security Considerations](xslt-security-considera Temporary files are sometimes generated during XSLT processing. If a style sheet contains script blocks, or if it is compiled with the debug setting set to true, temporary files may be created in the %TEMP% folder. There may be instances when some temporary files are not deleted due to timing issues. For example, if the files are in use by the current AppDomain or by the debugger, the finalizer of the object will not be able to remove them. -The property can be used for additional cleanup to make sure that all temporary files are removed from the client. +The property can be used for additional cleanup to make sure that all temporary files are removed from the client. ### Support for the xsl:output Element and XmlWriter -The class ignored `xsl:output` settings when the transform output was sent to an object. The class has an property that returns an object containing the output information derived from the `xsl:output` element of the style sheet. The object is used to create an object with the correct settings that can be passed to the method. The following C# code illustrates this behavior: +The class ignored `xsl:output` settings when the transform output was sent to an object. The class has an property that returns an object containing the output information derived from the `xsl:output` element of the style sheet. The object is used to create an object with the correct settings that can be passed to the method. The following C# code illustrates this behavior: ```csharp // Create the XslTransform object and load the style sheet. @@ -83,7 +83,7 @@ XmlDocument doc = new XmlDocument(); doc.Load(xslt.Transform(input, (XsltArgumentList)null)); ``` -The class does not support transforming to an object. However, you can do something similar by using the method to load the resulting XML tree directly from an . The following C# code shows how to accomplish the same task using . +The class does not support transforming to an object. However, you can do something similar by using the method to load the resulting XML tree directly from an . The following C# code shows how to accomplish the same task using . ```csharp // Transform input document to XmlDocument for additional processing diff --git a/docs/standard/data/xml/modify-xml-data-using-xpathnavigator.md b/docs/standard/data/xml/modify-xml-data-using-xpathnavigator.md index 2070534824094..31f208d5f6ff9 100644 --- a/docs/standard/data/xml/modify-xml-data-using-xpathnavigator.md +++ b/docs/standard/data/xml/modify-xml-data-using-xpathnavigator.md @@ -10,13 +10,13 @@ dev_langs: The class provides a set of methods used to modify nodes and values in an XML document. In order to use these methods, the object must be editable, that is, its property must be `true`. - objects that can edit an XML document are created by the method of the class. objects created by the class are read-only and any attempt to use the editing methods of an object created by an object result in a . + objects that can edit an XML document are created by the method of the class. objects created by the class are read-only and any attempt to use the editing methods of an object created by an object result in a . For more information about creating editable objects, see [Reading XML Data using XPathDocument and XmlDocument](reading-xml-data-using-xpathdocument-and-xmldocument.md). ## Modifying Nodes - A simple technique for changing the value of a node is to use the and methods of the class. + A simple technique for changing the value of a node is to use the and methods of the class. The following table lists the effects of these methods on different node types. @@ -37,9 +37,9 @@ The class provides a set of methods used ### Modifying Untyped Values - The method simply inserts the untyped `string` value passed as a parameter as the value of the node the object is currently positioned on. The value is inserted without any type or without verifying that the new value is valid according to the type of the node if schema information is available. + The method simply inserts the untyped `string` value passed as a parameter as the value of the node the object is currently positioned on. The value is inserted without any type or without verifying that the new value is valid according to the type of the node if schema information is available. - In the following example, the method is used to update all `price` elements in the `contosoBooks.xml` file. + In the following example, the method is used to update all `price` elements in the `contosoBooks.xml` file. [!code-csharp[XPathNavigatorMethods#47](../../../../samples/snippets/csharp/VS_Snippets_Data/XPathNavigatorMethods/CS/xpathnavigatormethods.cs#47)] [!code-vb[XPathNavigatorMethods#47](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XPathNavigatorMethods/VB/xpathnavigatormethods.vb#47)] @@ -49,7 +49,7 @@ The class provides a set of methods used ### Modifying Typed Values - When the type of a node is a W3C XML Schema simple type, the new value inserted by the method is checked against the facets of the simple type before the value is set. If the new value is not valid according to the type of the node (for example, setting a value of `-1` on an element whose type is `xs:positiveInteger`), it results in an exception. + When the type of a node is a W3C XML Schema simple type, the new value inserted by the method is checked against the facets of the simple type before the value is set. If the new value is not valid according to the type of the node (for example, setting a value of `-1` on an element whose type is `xs:positiveInteger`), it results in an exception. The following example attempts to change the value of the `price` element of the first `book` element in the `contosoBooks.xml` file to a value. Because the XML Schema type of the `price` element is defined as `xs:decimal` in the `contosoBooks.xsd` files, this results in an exception. @@ -106,13 +106,13 @@ navigator.SetTypedValue(DateTime.Now); An element or attribute can be considered to be schema-valid if it conforms to all the rules specific to its type definition. An element that has the simple type `xs:int` has to contain a numeric value between -2147483648 and 2147483647 to be schema-valid. For complex types, the schema-validity of the element is dependent on the schema-validity of its child elements and attributes. Thus if an element is valid against its complex type definition, all its child elements and attributes are valid against their type definitions. Similarly, if even one of the child elements or attributes of an element is invalid against its type definition, or has an unknown validity, the element is also either invalid or of unknown validity. - Given that the validity of an element is dependent on the validity of its child elements and attributes, modifications to either result in altering the validity of the element if it was previously valid. Specifically, if the child elements or attributes of an element are inserted, updated, or deleted, then the validity of the element becomes unknown. This is represented by the property of the element's property being set to . Furthermore, this effect cascades upwards recursively across the XML document, because the validity of the element's parent element (and its parent element, and so on) also becomes unknown. + Given that the validity of an element is dependent on the validity of its child elements and attributes, modifications to either result in altering the validity of the element if it was previously valid. Specifically, if the child elements or attributes of an element are inserted, updated, or deleted, then the validity of the element becomes unknown. This is represented by the property of the element's property being set to . Furthermore, this effect cascades upwards recursively across the XML document, because the validity of the element's parent element (and its parent element, and so on) also becomes unknown. For more information about schema validation and the class, see [Schema Validation using XPathNavigator](schema-validation-using-xpathnavigator.md). ### Modifying Attributes - The and methods can be used to modify untyped and typed attribute nodes as well as the other node types listed in the "Modifying Nodes" section. + The and methods can be used to modify untyped and typed attribute nodes as well as the other node types listed in the "Modifying Nodes" section. The following example changes the value of the `genre` attribute of the first `book` element in the `books.xml` file. @@ -146,15 +146,15 @@ navigator.MoveToRoot(); Console.WriteLine(navigator.OuterXml); ``` - For more information about the and methods, see the "Modifying Untyped Values" and "Modifying Typed Values" sections. + For more information about the and methods, see the "Modifying Untyped Values" and "Modifying Typed Values" sections. ## InnerXml and OuterXml Properties - The and properties of the class change the XML markup of the nodes an object is currently positioned on. + The and properties of the class change the XML markup of the nodes an object is currently positioned on. - The property changes the XML markup of the child nodes an object is currently positioned on with the parsed contents of the given XML `string`. Similarly, the property changes the XML markup of the child nodes an object is currently positioned on as well as the current node itself. + The property changes the XML markup of the child nodes an object is currently positioned on with the parsed contents of the given XML `string`. Similarly, the property changes the XML markup of the child nodes an object is currently positioned on as well as the current node itself. - The following example uses the property to modify the value of the `price` element and insert a new `discount` attribute on the first `book` element in the `contosoBooks.xml` file. + The following example uses the property to modify the value of the `price` element and insert a new `discount` attribute on the first `book` element in the `contosoBooks.xml` file. ```vb Dim document As XmlDocument = New XmlDocument() @@ -228,7 +228,7 @@ Console.WriteLine(navigator.OuterXml); ``` - In the XML example above, the attribute `a:parent-id` is inserted on the `parent` element in the `http://www.contoso.com/parent-id` namespace. The method is used to insert the attribute while positioned on the `parent` element. The `http://www.contoso.com` namespace declaration is automatically inserted by the class to preserve the consistency of the rest of the XML document. + In the XML example above, the attribute `a:parent-id` is inserted on the `parent` element in the `http://www.contoso.com/parent-id` namespace. The method is used to insert the attribute while positioned on the `parent` element. The `http://www.contoso.com` namespace declaration is automatically inserted by the class to preserve the consistency of the rest of the XML document. ## Modifying Entity Reference Nodes diff --git a/docs/standard/data/xml/modifying-nodes-content-and-values-in-an-xml-document.md b/docs/standard/data/xml/modifying-nodes-content-and-values-in-an-xml-document.md index 0b827a37fdf1d..ae4c03b1cddba 100644 --- a/docs/standard/data/xml/modifying-nodes-content-and-values-in-an-xml-document.md +++ b/docs/standard/data/xml/modifying-nodes-content-and-values-in-an-xml-document.md @@ -6,39 +6,39 @@ ms.assetid: 761773e0-db72-4986-b9f5-a522213d8397 --- # Modifying Nodes, Content, and Values in an XML Document -There are many ways you can modify the nodes and content in a document. You can: - -- Change the value of nodes using the property. - -- Modify an entire set of nodes by replacing the nodes with new nodes. This is done using the property. - -- Replace existing nodes with new nodes using the method. - -- Add additional characters to nodes that inherit from the class using the , , or methods. - -- Modify the content by removing a range of characters using the method on node types that inherit from . - - A simple technique for changing the value of a node is to use `node.Value = "new value";`. The following table lists the node types that this single line of code works on and exactly what data for that node type is changed. - -|Node type|Data changed| -|---------------|------------------| -|Attribute|The value of the attribute.| -|CDATASection|The content of the CDATASection.| -|Comment|The content of the comment.| -|ProcessingInstruction|The content, excluding the target.| -|Text|The content of the text.| -|XmlDeclaration|The content of the declaration, excluding the `` markup.| -|Whitespace|The value of the white space. You can set the value to be one of the four recognized XML white space characters: space, tab, CR, or LF.| -|SignificantWhitespace|The value of the significant white space. You can set the value to be one of the four recognized XML white space characters: space, tab, CR, or LF.| - - Any node type not listed in the table is not a valid node type to set a value on. Setting a value on any other node type throws an . - - The property changes the markup of the child nodes for the current node. Setting this property replaces the child nodes with the parsed contents of the given string. The parsing is done in the current namespace context. In addition, removes redundant namespace declarations. As a result, numerous cut and paste operations do not increase the size of your document with redundant namespace declarations. For a code example showing the effect of namespaces on the operation, see the property. - - When using the and methods, the methods return the replaced or removed node. This node can then be reinserted somewhere else in the XML Document Object Model (DOM). The method does two validation checks on the node being inserted into the document. The first check ensures that the node is becoming a child of a node that can have child nodes of its type. The second check ensures that the node being inserted is not an ancestor of the node it is becoming a child of. Violating either of these conditions throws an . - - It is valid to add or remove a read-only child from a node that can be edited. However, attempts to modify the read-only node itself throws an . An example of this is modifying the children of an node. The children are read-only and cannot be modified. Any attempt to modify them throws an . - +There are many ways you can modify the nodes and content in a document. You can: + +- Change the value of nodes using the property. + +- Modify an entire set of nodes by replacing the nodes with new nodes. This is done using the property. + +- Replace existing nodes with new nodes using the method. + +- Add additional characters to nodes that inherit from the class using the , , or methods. + +- Modify the content by removing a range of characters using the method on node types that inherit from . + + A simple technique for changing the value of a node is to use `node.Value = "new value";`. The following table lists the node types that this single line of code works on and exactly what data for that node type is changed. + +|Node type|Data changed| +|---------------|------------------| +|Attribute|The value of the attribute.| +|CDATASection|The content of the CDATASection.| +|Comment|The content of the comment.| +|ProcessingInstruction|The content, excluding the target.| +|Text|The content of the text.| +|XmlDeclaration|The content of the declaration, excluding the `` markup.| +|Whitespace|The value of the white space. You can set the value to be one of the four recognized XML white space characters: space, tab, CR, or LF.| +|SignificantWhitespace|The value of the significant white space. You can set the value to be one of the four recognized XML white space characters: space, tab, CR, or LF.| + + Any node type not listed in the table is not a valid node type to set a value on. Setting a value on any other node type throws an . + + The property changes the markup of the child nodes for the current node. Setting this property replaces the child nodes with the parsed contents of the given string. The parsing is done in the current namespace context. In addition, removes redundant namespace declarations. As a result, numerous cut and paste operations do not increase the size of your document with redundant namespace declarations. For a code example showing the effect of namespaces on the operation, see the property. + + When using the and methods, the methods return the replaced or removed node. This node can then be reinserted somewhere else in the XML Document Object Model (DOM). The method does two validation checks on the node being inserted into the document. The first check ensures that the node is becoming a child of a node that can have child nodes of its type. The second check ensures that the node being inserted is not an ancestor of the node it is becoming a child of. Violating either of these conditions throws an . + + It is valid to add or remove a read-only child from a node that can be edited. However, attempts to modify the read-only node itself throws an . An example of this is modifying the children of an node. The children are read-only and cannot be modified. Any attempt to modify them throws an . + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/node-set-navigation-using-xpathnavigator.md b/docs/standard/data/xml/node-set-navigation-using-xpathnavigator.md index 1e1066a179b62..9a968f0092ed7 100644 --- a/docs/standard/data/xml/node-set-navigation-using-xpathnavigator.md +++ b/docs/standard/data/xml/node-set-navigation-using-xpathnavigator.md @@ -6,47 +6,47 @@ ms.assetid: 1a954b41-7173-40bc-8544-d430f209b1e5 --- # Node Set Navigation Using XPathNavigator -You can navigate over nodes in an or object using the node set navigation methods of the class. You can navigate over all the nodes or over a selected set of nodes returned by one of the selection methods of the class. - -## Element Node Set Navigation - - The class provides several methods used to navigate element nodes. The following table shows the navigation methods available and a description of how they move; this does not include methods used to navigate attribute and namespace nodes. - - For more information about selecting nodes in an object, see [Selecting, Evaluating and Matching XML Data using XPathNavigator](selecting-evaluating-and-matching-xml-data-using-xpathnavigator.md). For more information about navigating attribute and namespace nodes, see [Attribute and Namespace Node Navigation Using XPathNavigator](attribute-and-namespace-node-navigation-using-xpathnavigator.md). - -|Method|Description| -|------------|-----------------| -||Moves the to the same position of the specified.| -||Moves the to a child node of the current node.| -||Moves the to the first sibling node of the current node.| -||Moves the to the first child node of the current node.| -||Moves the to the specified element in document order.| -||Moves the to the node that has an attribute of type `ID` with a value that matches the given .| -||Moves the to the next sibling node of the current node.| -||Moves the to the parent node of the current node.| -||Moves the to the previous sibling node of the current node.| -||Moves the to the root node of the XML document.| - -## Comments and Processing Instruction Node Navigation - - The following class methods are valid for moving to comments or processing instructions from other nodes in an XML document. - -- - -- - -- - -- - -- - -- - -- - -- - +You can navigate over nodes in an or object using the node set navigation methods of the class. You can navigate over all the nodes or over a selected set of nodes returned by one of the selection methods of the class. + +## Element Node Set Navigation + + The class provides several methods used to navigate element nodes. The following table shows the navigation methods available and a description of how they move; this does not include methods used to navigate attribute and namespace nodes. + + For more information about selecting nodes in an object, see [Selecting, Evaluating and Matching XML Data using XPathNavigator](selecting-evaluating-and-matching-xml-data-using-xpathnavigator.md). For more information about navigating attribute and namespace nodes, see [Attribute and Namespace Node Navigation Using XPathNavigator](attribute-and-namespace-node-navigation-using-xpathnavigator.md). + +|Method|Description| +|------------|-----------------| +||Moves the to the same position of the specified.| +||Moves the to a child node of the current node.| +||Moves the to the first sibling node of the current node.| +||Moves the to the first child node of the current node.| +||Moves the to the specified element in document order.| +||Moves the to the node that has an attribute of type `ID` with a value that matches the given .| +||Moves the to the next sibling node of the current node.| +||Moves the to the parent node of the current node.| +||Moves the to the previous sibling node of the current node.| +||Moves the to the root node of the XML document.| + +## Comments and Processing Instruction Node Navigation + + The following class methods are valid for moving to comments or processing instructions from other nodes in an XML document. + +- + +- + +- + +- + +- + +- + +- + +- + ## See also - diff --git a/docs/standard/data/xml/object-comparison-using-xmlnametable.md b/docs/standard/data/xml/object-comparison-using-xmlnametable.md index 4bf5cfb38052f..fc7e7cbf11c3f 100644 --- a/docs/standard/data/xml/object-comparison-using-xmlnametable.md +++ b/docs/standard/data/xml/object-comparison-using-xmlnametable.md @@ -2,50 +2,50 @@ description: "Learn more about: Object Comparison Using XmlNameTable" title: "Object Comparison Using XmlNameTable" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 8d94e041-d340-4ddf-9a2c-d7319e3f4f86 --- # Object Comparison Using XmlNameTable -**XmlDocuments**, when created, have a name table created specifically for that document. When XML is loaded into the document, or new elements or attributes are created, the attribute and element names are put into the **XmlNameTable**. You can also create an **XmlDocument** using an existing **NameTable** from another document. When **XmlDocuments** are created with the constructor that takes an **XmlNameTable** parameter, the document has access to the node names, namespaces, and prefixes already stored in the **XmlNameTable**. Regardless of how the name table is loaded with names, once the names are stored in the table, names can be compared quickly using object comparison instead of string comparison. Strings can also be added to the name table using the . The following code sample shows a name table being created and the string **MyString** being added to the table. After that, an **XmlDocument** is created using that table, and the element and attribute names in **Myfile.xml** are added to the existing name table. - -```vb -Dim nt As New NameTable() -nt.Add("MyString") -Dim doc As New XmlDocument(nt) -doc.Load("Myfile.xml") -``` - -```csharp -NameTable nt = new NameTable(); -nt.Add("MyString"); -XmlDocument doc = new XmlDocument(nt); -doc.Load("Myfile.xml"); -``` - - The following code example shows the creation of a document, two new elements being added to the document, which also adds them to the document name table, and the object comparison on the names. - -```vb -Dim doc1 As XmlDocument = imp.CreateDocument() -Dim node1 As XmlElement = doc.CreateElement("node1") -Dim doc2 As XmlDocument = imp.CreateDocument() -Dim node2 As XmlElement = doc.CreateElement("node2") -if (CType(node1.Name, object) = CType(node2.Name, object)) -``` - -```csharp -XmlDocument doc1 = imp.CreateDocument(); -node1 = doc1.CreateElement ("node1"); -XmlDocument doc2 = imp.CreateDocument(); -node2 = doc2.CreateElement ("node1"); -if (((object)node1.Name) == ((object)node2.Name)) -{ ... -``` - - The above scenario of a name table passed between two documents is typical when the same type of document is being processed repeatedly, such as order documents at an ecommerce site, which conform to an XML Schema definition language (XSD) schema or document type definition (DTD) and the same strings are repeated. Using the same name table gives a performance improvement, as the same element name occurs in multiple documents. - +**XmlDocuments**, when created, have a name table created specifically for that document. When XML is loaded into the document, or new elements or attributes are created, the attribute and element names are put into the **XmlNameTable**. You can also create an **XmlDocument** using an existing **NameTable** from another document. When **XmlDocuments** are created with the constructor that takes an **XmlNameTable** parameter, the document has access to the node names, namespaces, and prefixes already stored in the **XmlNameTable**. Regardless of how the name table is loaded with names, once the names are stored in the table, names can be compared quickly using object comparison instead of string comparison. Strings can also be added to the name table using the . The following code sample shows a name table being created and the string **MyString** being added to the table. After that, an **XmlDocument** is created using that table, and the element and attribute names in **Myfile.xml** are added to the existing name table. + +```vb +Dim nt As New NameTable() +nt.Add("MyString") +Dim doc As New XmlDocument(nt) +doc.Load("Myfile.xml") +``` + +```csharp +NameTable nt = new NameTable(); +nt.Add("MyString"); +XmlDocument doc = new XmlDocument(nt); +doc.Load("Myfile.xml"); +``` + + The following code example shows the creation of a document, two new elements being added to the document, which also adds them to the document name table, and the object comparison on the names. + +```vb +Dim doc1 As XmlDocument = imp.CreateDocument() +Dim node1 As XmlElement = doc.CreateElement("node1") +Dim doc2 As XmlDocument = imp.CreateDocument() +Dim node2 As XmlElement = doc.CreateElement("node2") +if (CType(node1.Name, object) = CType(node2.Name, object)) +``` + +```csharp +XmlDocument doc1 = imp.CreateDocument(); +node1 = doc1.CreateElement ("node1"); +XmlDocument doc2 = imp.CreateDocument(); +node2 = doc2.CreateElement ("node1"); +if (((object)node1.Name) == ((object)node2.Name)) +{ ... +``` + + The above scenario of a name table passed between two documents is typical when the same type of document is being processed repeatedly, such as order documents at an ecommerce site, which conform to an XML Schema definition language (XSD) schema or document type definition (DTD) and the same strings are repeated. Using the same name table gives a performance improvement, as the same element name occurs in multiple documents. + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/output-options-on-the-xslcompiledtransform-class.md b/docs/standard/data/xml/output-options-on-the-xslcompiledtransform-class.md index c37c1b3e3f3a8..8c5f1f84ab2fd 100644 --- a/docs/standard/data/xml/output-options-on-the-xslcompiledtransform-class.md +++ b/docs/standard/data/xml/output-options-on-the-xslcompiledtransform-class.md @@ -6,11 +6,11 @@ ms.topic: reference --- # Output Options on the XslCompiledTransform Class -This article discusses the available XSLT output options. You can specify output options in the style sheet, or on the method. +This article discusses the available XSLT output options. You can specify output options in the style sheet, or on the method. ## xsl:output Element - The `xsl:output` element specifies options for the output. The output type specified by the method determines the behavior of the `xsl:output` options. + The `xsl:output` element specifies options for the output. The output type specified by the method determines the behavior of the `xsl:output` options. The following table describes the behavior for each of the attributes available on the `xsl:output` element when the output type is a stream or a . @@ -18,7 +18,7 @@ This article discusses the available XSLT output options. You can specify output |--------------------|--------------| |method|Supported.| |version|Ignored. The version is always 1.0 for XML and 4.0 for HTML.| -|encoding|Ignored when outputting to a . The property is used instead.| +|encoding|Ignored when outputting to a . The property is used instead.| |omit-xml-declaration|Supported.| |standalone|Supported.| |doctype-public|Supported.| @@ -29,11 +29,11 @@ This article discusses the available XSLT output options. You can specify output ### Sending Output to an XmlWriter - If your style sheet uses the `xsl:output` element and the output type is an object, you should use the property when you create the object. The property returns an object that contains information derived from the `xsl:output` element of a compiled style sheet. This object can be passed to the method to create an object with the correct settings. + If your style sheet uses the `xsl:output` element and the output type is an object, you should use the property when you create the object. The property returns an object that contains information derived from the `xsl:output` element of a compiled style sheet. This object can be passed to the method to create an object with the correct settings. ## Output Types - The following list describes the output types available on the command. + The following list describes the output types available on the command. ### XmlWriter diff --git a/docs/standard/data/xml/post-schema-compilation-infoset.md b/docs/standard/data/xml/post-schema-compilation-infoset.md index 6db91c4340919..641784e4e9ec5 100644 --- a/docs/standard/data/xml/post-schema-compilation-infoset.md +++ b/docs/standard/data/xml/post-schema-compilation-infoset.md @@ -8,24 +8,24 @@ dev_langs: --- # Post-schema compilation infoset -The [World Wide Web Consortium (W3C) XML Schema Recommendation](https://www.w3.org/XML/Schema) discusses the information set (infoset) that must be exposed for pre-schema validation and post-schema compilation. The XML Schema Object Model (SOM) views this exposure before and after the method of the is called. +The [World Wide Web Consortium (W3C) XML Schema Recommendation](https://www.w3.org/XML/Schema) discusses the information set (infoset) that must be exposed for pre-schema validation and post-schema compilation. The XML Schema Object Model (SOM) views this exposure before and after the method of the is called. - The pre-schema validation infoset is built during the editing of the schema. The post-schema compilation infoset is generated after the method of the is called, during compilation of the schema, and is exposed as properties. + The pre-schema validation infoset is built during the editing of the schema. The post-schema compilation infoset is generated after the method of the is called, during compilation of the schema, and is exposed as properties. The SOM is the object model that represents the pre-schema validation and post-schema compilation infosets; it consists of the classes in the namespace. All read and write properties of classes in the namespace belong to the pre-schema validation infoset, while all read-only properties of classes in the namespace belong to the post-schema compilation infoset. The exception to this rule are the following properties, which are both pre-schema validation infoset and post-schema compilation infoset properties. |Class|Property| |-----------|--------------| -||| -||, , , , | -||| -||| -||, | -||| +||| +||, , , , | +||| +||| +||, | +||| For example, the and classes both have `BlockResolved` and `FinalResolved` properties. These properties are used to hold the values for the `Block` and `Final` properties after the schema has been compiled and validated. `BlockResolved` and `FinalResolved` are read-only properties that are part of the post-schema compilation infoset. - The following example shows the property of the class set after validating the schema. Before validation, the property contains a `null` reference, and the is set to the name of the type in question. After validation, the is resolved to a valid type, and the type object is available through the property. + The following example shows the property of the class set after validating the schema. Before validation, the property contains a `null` reference, and the is set to the name of the type in question. After validation, the is resolved to a valid type, and the type object is available through the property. [!code-csharp[PsciSample#1](../../../../samples/snippets/csharp/VS_Snippets_Data/PsciSample/CS/PsciSample.cs#1)] [!code-vb[PsciSample#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/PsciSample/VB/PsciSample.vb#1)] diff --git a/docs/standard/data/xml/reading-an-xml-document-into-the-dom.md b/docs/standard/data/xml/reading-an-xml-document-into-the-dom.md index acb6274f62ef9..148f34eae890d 100644 --- a/docs/standard/data/xml/reading-an-xml-document-into-the-dom.md +++ b/docs/standard/data/xml/reading-an-xml-document-into-the-dom.md @@ -2,67 +2,67 @@ description: "Learn more about: Reading an XML Document into the DOM" title: "Reading an XML Document into the DOM" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: a4fb291f-5630-49ba-a49a-5b66c3b71e49 --- # Reading an XML Document into the DOM -XML information is read into memory from different formats. It can be read from a string, stream, URL, text reader, or a class derived from the . - - The method brings the document into memory and has overloaded methods available to take data from each of the different formats. There is also a method that reads XML from a string. - - Different methods affect which nodes are created when the XML Document Object Model (DOM) is loaded. The following table lists the differences between some of the methods and topics that address them. - -|Subject|Topic| -|-------------|-----------| -|Creation of white space nodes|The object used to load the DOM has an affect on the white space and significant white space nodes generated in the DOM. For more information, see [White Space and Significant White Space Handling when Loading the DOM](white-space-and-significant-white-space-handling-when-loading-the-dom.md).| -|Loading XML starting from a specific node or loading the entire XML document|Using the method data can be loaded from a specific node into the DOM. For more information, see [Load Data from a Reader](load-data-from-a-reader.md).| -|Validating the XML as it is loaded|The XML data loaded into the DOM can be validated as it is loaded. This is accomplished using a validating . For more information about validating XML as it is loaded, see [Validating an XML Document in the DOM](validating-an-xml-document-in-the-dom.md).| - - The following example shows XML being loaded with the method and the data subsequently saved to a text file called `data.xml`. - -```vb -Imports System -Imports System.IO -Imports System.Xml - -Public Class Sample - - Public Shared Sub Main() - ' Create the XmlDocument. - Dim doc As New XmlDocument() - doc.LoadXml(("" & _ - "Pride And Prejudice" & _ - "")) - ' Save the document to a file. - doc.Save("data.xml") - End Sub 'Main -End Class 'Sample -``` - -```csharp -using System; -using System.IO; -using System.Xml; - -public class Sample -{ - public static void Main() - { - // Create the XmlDocument. - XmlDocument doc = new XmlDocument(); - doc.LoadXml("" + - "Pride And Prejudice" + - ""); - - // Save the document to a file. - doc.Save("data.xml"); - } -} -``` - +XML information is read into memory from different formats. It can be read from a string, stream, URL, text reader, or a class derived from the . + + The method brings the document into memory and has overloaded methods available to take data from each of the different formats. There is also a method that reads XML from a string. + + Different methods affect which nodes are created when the XML Document Object Model (DOM) is loaded. The following table lists the differences between some of the methods and topics that address them. + +|Subject|Topic| +|-------------|-----------| +|Creation of white space nodes|The object used to load the DOM has an affect on the white space and significant white space nodes generated in the DOM. For more information, see [White Space and Significant White Space Handling when Loading the DOM](white-space-and-significant-white-space-handling-when-loading-the-dom.md).| +|Loading XML starting from a specific node or loading the entire XML document|Using the method data can be loaded from a specific node into the DOM. For more information, see [Load Data from a Reader](load-data-from-a-reader.md).| +|Validating the XML as it is loaded|The XML data loaded into the DOM can be validated as it is loaded. This is accomplished using a validating . For more information about validating XML as it is loaded, see [Validating an XML Document in the DOM](validating-an-xml-document-in-the-dom.md).| + + The following example shows XML being loaded with the method and the data subsequently saved to a text file called `data.xml`. + +```vb +Imports System +Imports System.IO +Imports System.Xml + +Public Class Sample + + Public Shared Sub Main() + ' Create the XmlDocument. + Dim doc As New XmlDocument() + doc.LoadXml(("" & _ + "Pride And Prejudice" & _ + "")) + ' Save the document to a file. + doc.Save("data.xml") + End Sub 'Main +End Class 'Sample +``` + +```csharp +using System; +using System.IO; +using System.Xml; + +public class Sample +{ + public static void Main() + { + // Create the XmlDocument. + XmlDocument doc = new XmlDocument(); + doc.LoadXml("" + + "Pride And Prejudice" + + ""); + + // Save the document to a file. + doc.Save("data.xml"); + } +} +``` + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/reading-and-writing-xml-schemas.md b/docs/standard/data/xml/reading-and-writing-xml-schemas.md index 7f0920f6a72f2..ae9441562698d 100644 --- a/docs/standard/data/xml/reading-and-writing-xml-schemas.md +++ b/docs/standard/data/xml/reading-and-writing-xml-schemas.md @@ -12,11 +12,11 @@ The Schema Object Model (SOM) API can be used to read and write XML Schema defin ## Reading and Writing XML Schemas - The class provides the and methods to read and write XML schemas. The method returns an object representing the XML schema and takes an optional as a parameter to handle schema validation warnings and errors encountered while reading an XML schema. + The class provides the and methods to read and write XML schemas. The method returns an object representing the XML schema and takes an optional as a parameter to handle schema validation warnings and errors encountered while reading an XML schema. - The method writes XML schemas to , and objects and can take an optional object as a parameter. An is used to handle namespaces encountered in an XML schema. For more information about the class, see [Managing Namespaces in an XML Document](managing-namespaces-in-an-xml-document.md). + The method writes XML schemas to , and objects and can take an optional object as a parameter. An is used to handle namespaces encountered in an XML schema. For more information about the class, see [Managing Namespaces in an XML Document](managing-namespaces-in-an-xml-document.md). - The following code example illustrates reading and writing XML schemas from and to a file. The code example takes the `example.xsd` file, reads it into an object using the `static` method, and then writes the file to the console and a new `new.xsd` file. The code example also provides a as a parameter to the `static` method to handle any schema validation warnings or errors encountered while reading the XML schema. If the is not specified (`null`), no warnings or errors are reported. + The following code example illustrates reading and writing XML schemas from and to a file. The code example takes the `example.xsd` file, reads it into an object using the `static` method, and then writes the file to the console and a new `new.xsd` file. The code example also provides a as a parameter to the `static` method to handle any schema validation warnings or errors encountered while reading the XML schema. If the is not specified (`null`), no warnings or errors are reported. [!code-csharp[XmlSchemaReadWriteExample#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaReadWriteExample/CS/XmlSchemaReadWriteExample.cs#1)] [!code-vb[XmlSchemaReadWriteExample#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XmlSchemaReadWriteExample/VB/XmlSchemaReadWriteExample.vb#1)] diff --git a/docs/standard/data/xml/reading-xml-data-using-xpathdocument-and-xmldocument.md b/docs/standard/data/xml/reading-xml-data-using-xpathdocument-and-xmldocument.md index c842a33ea4160..65f0770688b87 100644 --- a/docs/standard/data/xml/reading-xml-data-using-xpathdocument-and-xmldocument.md +++ b/docs/standard/data/xml/reading-xml-data-using-xpathdocument-and-xmldocument.md @@ -2,74 +2,74 @@ description: "Learn more about: Reading XML Data using XPathDocument and XmlDocument" title: "Reading XML Data using XPathDocument and XmlDocument" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 5711b225-6aa2-4e4f-9898-19f2d518ad1a --- # Reading XML Data using XPathDocument and XmlDocument -There are two ways to read an XML document in the namespace. One is to read an XML document using the read-only class and the other is to read an XML document using the editable class in the namespace. - -## Reading XML Documents using the XPathDocument Class - - The class provides a fast, read-only, in-memory representation of an XML document using the XPath data model. Instances of the class are created using one of its six constructors. These constructors allow you to read an XML document using a , , or object, as well as the `string` path to an XML file. - - The following example illustrates using the class's `string` constructor to read an XML document. - -```vb -Dim document As XPathDocument = New XPathDocument("books.xml") -``` - -```csharp -XPathDocument document = new XPathDocument("books.xml"); -``` - -## Reading XML Documents using the XmlDocument Class - - The class is an editable in-memory representation of an XML document implementing W3C Document Object Model (DOM) Level 1 Core and Core DOM Level 2. Instances of the class are created using one of its three constructors. You can create a new, empty object by calling the class constructor with no parameters. After calling the constructor, use the method to load XML data into the new object from a , , or object, as well as the `string` path to an XML file. - - The following example illustrates using the class constructor with no parameters and the method to read an XML document. - -```vb -Dim document As XmlDocument = New XmlDocument() -document.Load("books.xml") -``` - -```csharp -XmlDocument document = new XmlDocument(); -document.Load("books.xml"); -``` - -## Determining the Encoding of an XML Document - - An object can be used to read an XML document and to create and objects as shown in the previous sections. However, an object may read data that is not encoded and as a result does not provide any encoding information. - - The class inherits from the class, provides encoding information using its property, and can be used to create an object or object. - - For more information about the encoding information provided by the class, see the property in the class reference documentation. - -## Creating XPathNavigator Objects - - After you have read an XML document into either an or object, you can create an object to select, evaluate, navigate, and in some cases, edit the underlying XML data. - - Both the and classes, in addition to the class, implement the interface of the namespace. As a result, all three classes provide a method that returns an object. - -### Editing XML Documents using the XPathNavigator Class - - In addition to selecting, evaluating, and navigating XML data, the class can be used to edit an XML document in some cases, based on the object that created it. - - The class is read-only while the class is editable and as a result, objects created from an object cannot be used to edit an XML document while those created from an object can. The class should be used to read an XML document only. In cases where you need to edit an XML document, or require access to the additional functionality provided by the class, like event handling, the class should be used. - - The property of the class specifies if an object may edit XML data. - - The following table describes the value of the property for each class. - -| Implementation| Value| -|--------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| -||`false`| -||`true`| - +There are two ways to read an XML document in the namespace. One is to read an XML document using the read-only class and the other is to read an XML document using the editable class in the namespace. + +## Reading XML Documents using the XPathDocument Class + + The class provides a fast, read-only, in-memory representation of an XML document using the XPath data model. Instances of the class are created using one of its six constructors. These constructors allow you to read an XML document using a , , or object, as well as the `string` path to an XML file. + + The following example illustrates using the class's `string` constructor to read an XML document. + +```vb +Dim document As XPathDocument = New XPathDocument("books.xml") +``` + +```csharp +XPathDocument document = new XPathDocument("books.xml"); +``` + +## Reading XML Documents using the XmlDocument Class + + The class is an editable in-memory representation of an XML document implementing W3C Document Object Model (DOM) Level 1 Core and Core DOM Level 2. Instances of the class are created using one of its three constructors. You can create a new, empty object by calling the class constructor with no parameters. After calling the constructor, use the method to load XML data into the new object from a , , or object, as well as the `string` path to an XML file. + + The following example illustrates using the class constructor with no parameters and the method to read an XML document. + +```vb +Dim document As XmlDocument = New XmlDocument() +document.Load("books.xml") +``` + +```csharp +XmlDocument document = new XmlDocument(); +document.Load("books.xml"); +``` + +## Determining the Encoding of an XML Document + + An object can be used to read an XML document and to create and objects as shown in the previous sections. However, an object may read data that is not encoded and as a result does not provide any encoding information. + + The class inherits from the class, provides encoding information using its property, and can be used to create an object or object. + + For more information about the encoding information provided by the class, see the property in the class reference documentation. + +## Creating XPathNavigator Objects + + After you have read an XML document into either an or object, you can create an object to select, evaluate, navigate, and in some cases, edit the underlying XML data. + + Both the and classes, in addition to the class, implement the interface of the namespace. As a result, all three classes provide a method that returns an object. + +### Editing XML Documents using the XPathNavigator Class + + In addition to selecting, evaluating, and navigating XML data, the class can be used to edit an XML document in some cases, based on the object that created it. + + The class is read-only while the class is editable and as a result, objects created from an object cannot be used to edit an XML document while those created from an object can. The class should be used to read an XML document only. In cases where you need to edit an XML document, or require access to the additional functionality provided by the class, like event handling, the class should be used. + + The property of the class specifies if an object may edit XML data. + + The following table describes the value of the property for each class. + +| Implementation| Value| +|--------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| +||`false`| +||`true`| + ## See also - diff --git a/docs/standard/data/xml/remove-xml-data-using-xpathnavigator.md b/docs/standard/data/xml/remove-xml-data-using-xpathnavigator.md index 5c2d1bbac08fb..53868a9a41de4 100644 --- a/docs/standard/data/xml/remove-xml-data-using-xpathnavigator.md +++ b/docs/standard/data/xml/remove-xml-data-using-xpathnavigator.md @@ -2,188 +2,188 @@ description: "Learn more about: Remove XML Data using XPathNavigator" title: "Remove XML Data using XPathNavigator" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 9f436bca-1b96-494b-a6d2-e102c7551752 --- # Remove XML Data using XPathNavigator -The class provides a set of methods used to remove nodes and values from an XML document. In order to use these methods, the object must be editable, that is, its property must be `true`. - - objects that can edit an XML document are created by the method of the class. objects created by the class are read-only and any attempt to use the editing methods of an object created by an object results in a . - - For more information about creating editable objects, see [Reading XML Data using XPathDocument and XmlDocument](reading-xml-data-using-xpathdocument-and-xmldocument.md). - -## Removing Nodes - - The class provides the method to remove nodes from an XML document. - -### Removing a Node - - The class provides the method to delete the current node an object is currently positioned on from an XML document. - - After a node has been deleted using the method, it is no longer reachable from the root of the object. After a node has been deleted, the is positioned on the parent node of the deleted node. - - A delete operation doesn't affect the position of any object positioned on the deleted node. These objects are valid in the sense that they can move within the deleted subtree, but cannot be moved to the main node tree using the regular node set navigation methods of the class. - +The class provides a set of methods used to remove nodes and values from an XML document. In order to use these methods, the object must be editable, that is, its property must be `true`. + + objects that can edit an XML document are created by the method of the class. objects created by the class are read-only and any attempt to use the editing methods of an object created by an object results in a . + + For more information about creating editable objects, see [Reading XML Data using XPathDocument and XmlDocument](reading-xml-data-using-xpathdocument-and-xmldocument.md). + +## Removing Nodes + + The class provides the method to remove nodes from an XML document. + +### Removing a Node + + The class provides the method to delete the current node an object is currently positioned on from an XML document. + + After a node has been deleted using the method, it is no longer reachable from the root of the object. After a node has been deleted, the is positioned on the parent node of the deleted node. + + A delete operation doesn't affect the position of any object positioned on the deleted node. These objects are valid in the sense that they can move within the deleted subtree, but cannot be moved to the main node tree using the regular node set navigation methods of the class. + > [!NOTE] -> The method of the class can be used to move these objects back into the main node tree, or from the main node tree to the deleted subtree. - - In the following example, the `price` element of the first `book` element of the `contosoBooks.xml` file is deleted using the method. The position of the object after the `price` element is deleted is on the parent `book` element. - -```vb -Dim document As XmlDocument = New XmlDocument() -document.Load("contosoBooks.xml") -Dim navigator As XPathNavigator = document.CreateNavigator() - -navigator.MoveToChild("bookstore", "http://www.contoso.com/books") -navigator.MoveToChild("book", "http://www.contoso.com/books") -navigator.MoveToChild("price", "http://www.contoso.com/books") - -navigator.DeleteSelf() - -Console.WriteLine("Position after delete: {0}", navigator.Name) -Console.WriteLine(navigator.OuterXml) -``` - -```csharp -XmlDocument document = new XmlDocument(); -document.Load("contosoBooks.xml"); -XPathNavigator navigator = document.CreateNavigator(); - -navigator.MoveToChild("bookstore", "http://www.contoso.com/books"); -navigator.MoveToChild("book", "http://www.contoso.com/books"); -navigator.MoveToChild("price", "http://www.contoso.com/books"); - -navigator.DeleteSelf(); - -Console.WriteLine("Position after delete: {0}", navigator.Name); -Console.WriteLine(navigator.OuterXml); -``` - - The example takes the `contosoBooks.xml` file as an input. - - [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] - -### Removing an Attribute Node - - Attribute nodes are removed from an XML document using the method. - - After an attribute node has been deleted, it is no longer reachable from the root node of an object and the object is positioned on the parent element. - -#### Default Attributes - - Regardless of the method used to remove attributes, there are special limitations on removing attributes that are defined as default attributes in the DTD or XML Schema for the XML document. Default attributes cannot be removed unless the element they belong to is also removed. Default attributes are always present for elements that have default attributes declared, and as a result, deleting a default attribute results in a replacement attribute being inserted into the element and initialized to the default value that was declared. - -## Removing Values - - The class provides the and methods to remove untyped and typed values from an XML document. - -### Removing Untyped Values - - The method simply inserts the untyped `string` value passed as a parameter as the value of the node the object is currently positioned on. Passing an empty string to the method removes the value of the current node. - - The following example removes the value of the `price` element of the first `book` element in the `contosoBooks.xml` file using the method. - -```vb -Dim document As XmlDocument = New XmlDocument() -document.Load("contosoBooks.xml") -Dim navigator As XPathNavigator = document.CreateNavigator() - -navigator.MoveToChild("bookstore", "http://www.contoso.com/books") -navigator.MoveToChild("book", "http://www.contoso.com/books") -navigator.MoveToChild("price", "http://www.contoso.com/books") - -navigator.SetValue("") - -navigator.MoveToRoot() -Console.WriteLine(navigator.OuterXml) -``` - -```csharp -XmlDocument document = new XmlDocument(); -document.Load("contosoBooks.xml"); -XPathNavigator navigator = document.CreateNavigator(); - -navigator.MoveToChild("bookstore", "http://www.contoso.com/books"); -navigator.MoveToChild("book", "http://www.contoso.com/books"); -navigator.MoveToChild("price", "http://www.contoso.com/books"); - -navigator.SetValue(""); - -navigator.MoveToRoot(); -Console.WriteLine(navigator.OuterXml); -``` - - The example takes the `contosoBooks.xml` file as an input. - - [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] - -### Removing Typed Values - - When the type of a node is a W3C XML Schema simple type, the new value inserted by the method is checked against the facets of the simple type before the value is set. If the new value is not valid according to the type of the node (for example, setting a value of `-1` on an element whose type is `xs:positiveInteger`), it results in an exception. The method also cannot be passed `null` as a parameter. As a result removing the value of a typed node must comply with the schema type of the node. - - The following example removes the value of the `price` element of the first `book` element in the `contosoBooks.xml` file using the method by setting the value to `0`. The value of the node is not removed, but the price of the book has been removed according to its data type of `xs:decimal`. - -```vb -Dim settings As XmlReaderSettings = New XmlReaderSettings() -settings.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd") -settings.ValidationType = ValidationType.Schema - -Dim reader As XmlReader = XmlReader.Create("contosoBooks.xml", settings) - -Dim document As XmlDocument = New XmlDocument() -document.Load(reader) -Dim navigator As XPathNavigator = document.CreateNavigator() - -navigator.MoveToChild("bookstore", "http://www.contoso.com/books") -navigator.MoveToChild("book", "http://www.contoso.com/books") -navigator.MoveToChild("price", "http://www.contoso.com/books") - -navigator.SetTypedValue(0) - -navigator.MoveToRoot() -Console.WriteLine(navigator.OuterXml) -``` - -```csharp -XmlReaderSettings settings = new XmlReaderSettings(); -settings.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd"); -settings.ValidationType = ValidationType.Schema; - -XmlReader reader = XmlReader.Create("contosoBooks.xml", settings); - -XmlDocument document = new XmlDocument(); -document.Load(reader); -XPathNavigator navigator = document.CreateNavigator(); - -navigator.MoveToChild("bookstore", "http://www.contoso.com/books"); -navigator.MoveToChild("book", "http://www.contoso.com/books"); -navigator.MoveToChild("price", "http://www.contoso.com/books"); - -navigator.SetTypedValue(0); - -navigator.MoveToRoot(); -Console.WriteLine(navigator.OuterXml); -``` - -## Namespace Nodes - - Namespace nodes cannot be deleted from an object. Attempts to delete namespace nodes using the method results in an exception. - -## The InnerXml and OuterXml Properties - - The and properties of the class change the XML markup of the nodes an object is currently positioned on. - - The property changes the XML markup of the child nodes an object is currently positioned on with the parsed contents of the given XML `string`. Similarly, the property changes the XML markup of the child nodes an object is currently positioned on as well as the current node itself. - - In addition to the methods described in this topic, the and properties can be used to remove nodes and values from an XML document. For more information about using the and properties to modify nodes, see the [Modify XML Data using XPathNavigator](modify-xml-data-using-xpathnavigator.md) topic. - -## Saving an XML Document - - Saving changes made to an object as the result of the methods described in this topic is performed using the methods of the class. For more information about saving changes made to an object, see [Saving and Writing a Document](saving-and-writing-a-document.md). - +> The method of the class can be used to move these objects back into the main node tree, or from the main node tree to the deleted subtree. + + In the following example, the `price` element of the first `book` element of the `contosoBooks.xml` file is deleted using the method. The position of the object after the `price` element is deleted is on the parent `book` element. + +```vb +Dim document As XmlDocument = New XmlDocument() +document.Load("contosoBooks.xml") +Dim navigator As XPathNavigator = document.CreateNavigator() + +navigator.MoveToChild("bookstore", "http://www.contoso.com/books") +navigator.MoveToChild("book", "http://www.contoso.com/books") +navigator.MoveToChild("price", "http://www.contoso.com/books") + +navigator.DeleteSelf() + +Console.WriteLine("Position after delete: {0}", navigator.Name) +Console.WriteLine(navigator.OuterXml) +``` + +```csharp +XmlDocument document = new XmlDocument(); +document.Load("contosoBooks.xml"); +XPathNavigator navigator = document.CreateNavigator(); + +navigator.MoveToChild("bookstore", "http://www.contoso.com/books"); +navigator.MoveToChild("book", "http://www.contoso.com/books"); +navigator.MoveToChild("price", "http://www.contoso.com/books"); + +navigator.DeleteSelf(); + +Console.WriteLine("Position after delete: {0}", navigator.Name); +Console.WriteLine(navigator.OuterXml); +``` + + The example takes the `contosoBooks.xml` file as an input. + + [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] + +### Removing an Attribute Node + + Attribute nodes are removed from an XML document using the method. + + After an attribute node has been deleted, it is no longer reachable from the root node of an object and the object is positioned on the parent element. + +#### Default Attributes + + Regardless of the method used to remove attributes, there are special limitations on removing attributes that are defined as default attributes in the DTD or XML Schema for the XML document. Default attributes cannot be removed unless the element they belong to is also removed. Default attributes are always present for elements that have default attributes declared, and as a result, deleting a default attribute results in a replacement attribute being inserted into the element and initialized to the default value that was declared. + +## Removing Values + + The class provides the and methods to remove untyped and typed values from an XML document. + +### Removing Untyped Values + + The method simply inserts the untyped `string` value passed as a parameter as the value of the node the object is currently positioned on. Passing an empty string to the method removes the value of the current node. + + The following example removes the value of the `price` element of the first `book` element in the `contosoBooks.xml` file using the method. + +```vb +Dim document As XmlDocument = New XmlDocument() +document.Load("contosoBooks.xml") +Dim navigator As XPathNavigator = document.CreateNavigator() + +navigator.MoveToChild("bookstore", "http://www.contoso.com/books") +navigator.MoveToChild("book", "http://www.contoso.com/books") +navigator.MoveToChild("price", "http://www.contoso.com/books") + +navigator.SetValue("") + +navigator.MoveToRoot() +Console.WriteLine(navigator.OuterXml) +``` + +```csharp +XmlDocument document = new XmlDocument(); +document.Load("contosoBooks.xml"); +XPathNavigator navigator = document.CreateNavigator(); + +navigator.MoveToChild("bookstore", "http://www.contoso.com/books"); +navigator.MoveToChild("book", "http://www.contoso.com/books"); +navigator.MoveToChild("price", "http://www.contoso.com/books"); + +navigator.SetValue(""); + +navigator.MoveToRoot(); +Console.WriteLine(navigator.OuterXml); +``` + + The example takes the `contosoBooks.xml` file as an input. + + [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] + +### Removing Typed Values + + When the type of a node is a W3C XML Schema simple type, the new value inserted by the method is checked against the facets of the simple type before the value is set. If the new value is not valid according to the type of the node (for example, setting a value of `-1` on an element whose type is `xs:positiveInteger`), it results in an exception. The method also cannot be passed `null` as a parameter. As a result removing the value of a typed node must comply with the schema type of the node. + + The following example removes the value of the `price` element of the first `book` element in the `contosoBooks.xml` file using the method by setting the value to `0`. The value of the node is not removed, but the price of the book has been removed according to its data type of `xs:decimal`. + +```vb +Dim settings As XmlReaderSettings = New XmlReaderSettings() +settings.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd") +settings.ValidationType = ValidationType.Schema + +Dim reader As XmlReader = XmlReader.Create("contosoBooks.xml", settings) + +Dim document As XmlDocument = New XmlDocument() +document.Load(reader) +Dim navigator As XPathNavigator = document.CreateNavigator() + +navigator.MoveToChild("bookstore", "http://www.contoso.com/books") +navigator.MoveToChild("book", "http://www.contoso.com/books") +navigator.MoveToChild("price", "http://www.contoso.com/books") + +navigator.SetTypedValue(0) + +navigator.MoveToRoot() +Console.WriteLine(navigator.OuterXml) +``` + +```csharp +XmlReaderSettings settings = new XmlReaderSettings(); +settings.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd"); +settings.ValidationType = ValidationType.Schema; + +XmlReader reader = XmlReader.Create("contosoBooks.xml", settings); + +XmlDocument document = new XmlDocument(); +document.Load(reader); +XPathNavigator navigator = document.CreateNavigator(); + +navigator.MoveToChild("bookstore", "http://www.contoso.com/books"); +navigator.MoveToChild("book", "http://www.contoso.com/books"); +navigator.MoveToChild("price", "http://www.contoso.com/books"); + +navigator.SetTypedValue(0); + +navigator.MoveToRoot(); +Console.WriteLine(navigator.OuterXml); +``` + +## Namespace Nodes + + Namespace nodes cannot be deleted from an object. Attempts to delete namespace nodes using the method results in an exception. + +## The InnerXml and OuterXml Properties + + The and properties of the class change the XML markup of the nodes an object is currently positioned on. + + The property changes the XML markup of the child nodes an object is currently positioned on with the parsed contents of the given XML `string`. Similarly, the property changes the XML markup of the child nodes an object is currently positioned on as well as the current node itself. + + In addition to the methods described in this topic, the and properties can be used to remove nodes and values from an XML document. For more information about using the and properties to modify nodes, see the [Modify XML Data using XPathNavigator](modify-xml-data-using-xpathnavigator.md) topic. + +## Saving an XML Document + + Saving changes made to an object as the result of the methods described in this topic is performed using the methods of the class. For more information about saving changes made to an object, see [Saving and Writing a Document](saving-and-writing-a-document.md). + ## See also - diff --git a/docs/standard/data/xml/removing-attributes-from-an-element-node-in-the-dom.md b/docs/standard/data/xml/removing-attributes-from-an-element-node-in-the-dom.md index 6a668310216d8..c1e02ca3cbb08 100644 --- a/docs/standard/data/xml/removing-attributes-from-an-element-node-in-the-dom.md +++ b/docs/standard/data/xml/removing-attributes-from-an-element-node-in-the-dom.md @@ -6,32 +6,32 @@ ms.topic: how-to --- # Removing Attributes from an Element Node in the DOM -There are many ways to remove attributes. One technique is to remove them from the attribute collection. To do this, the following steps are performed: - -1. Get the attribute collection from the element using `XmlAttributeCollection attrs = elem.Attributes;`. - -2. Remove the attribute from the attribute collection using one of three methods: - - - Use to remove a specific attribute. - - - Use to remove all attributes from the collection and leave the element with no attributes. - - - Use to remove an attribute from the attribute collection by using its index number. - - The following methods remove attributes from the element node. - -- Use to remove the attribute collection. - -- Use to remove a single attribute by name from the collection. - -- Use to remove a single attribute by index number from the collection. - - One more alternative is to get the element, get the attribute from the attribute collection, and remove the attribute node directly. To get the attribute from the attribute collection, you can use a name, `XmlAttribute attr = attrs["attr_name"];`, an index `XmlAttribute attr = attrs[0];`, or by fully qualifying the name with the namespace `XmlAttribute attr = attrs["attr_localName", "attr_namespace"]`. - - Regardless of the method used to remove attributes, there are special limitations on removing attributes that are defined as default attributes in the document type definition (DTD). Default attributes cannot be removed unless the element they belong to is removed. Default attributes are always present for elements that have default attributes declared. Removing a default attribute from an or from the results in a replacement attribute inserted into the of the element, initialized to the default value that was declared. If you have an element defined as ``, then you have a `book` element with three default attributes declared. The XML Document Object Model (DOM) implementation guarantees that as long as this `book` element exists, it has these three default attributes of `att1`, `att2`, and `att3`. - - When called with an , the method sets the value of the attribute to String.Empty, as an attribute cannot exist without a value. - +There are many ways to remove attributes. One technique is to remove them from the attribute collection. To do this, the following steps are performed: + +1. Get the attribute collection from the element using `XmlAttributeCollection attrs = elem.Attributes;`. + +2. Remove the attribute from the attribute collection using one of three methods: + + - Use to remove a specific attribute. + + - Use to remove all attributes from the collection and leave the element with no attributes. + + - Use to remove an attribute from the attribute collection by using its index number. + + The following methods remove attributes from the element node. + +- Use to remove the attribute collection. + +- Use to remove a single attribute by name from the collection. + +- Use to remove a single attribute by index number from the collection. + + One more alternative is to get the element, get the attribute from the attribute collection, and remove the attribute node directly. To get the attribute from the attribute collection, you can use a name, `XmlAttribute attr = attrs["attr_name"];`, an index `XmlAttribute attr = attrs[0];`, or by fully qualifying the name with the namespace `XmlAttribute attr = attrs["attr_localName", "attr_namespace"]`. + + Regardless of the method used to remove attributes, there are special limitations on removing attributes that are defined as default attributes in the document type definition (DTD). Default attributes cannot be removed unless the element they belong to is removed. Default attributes are always present for elements that have default attributes declared. Removing a default attribute from an or from the results in a replacement attribute inserted into the of the element, initialized to the default value that was declared. If you have an element defined as ``, then you have a `book` element with three default attributes declared. The XML Document Object Model (DOM) implementation guarantees that as long as this `book` element exists, it has these three default attributes of `att1`, `att2`, and `att3`. + + When called with an , the method sets the value of the attribute to String.Empty, as an attribute cannot exist without a value. + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/removing-node-content-in-the-dom.md b/docs/standard/data/xml/removing-node-content-in-the-dom.md index 946888cb8bc27..216a6b946b480 100644 --- a/docs/standard/data/xml/removing-node-content-in-the-dom.md +++ b/docs/standard/data/xml/removing-node-content-in-the-dom.md @@ -6,8 +6,8 @@ ms.assetid: 615d81a7-f44f-416c-a9ab-bfe03f85e6e4 --- # Removing Node Content in the DOM -For node types that inherit from , which are the , , , , and node types, you can remove characters using the method, which removes a range of characters from the node. If you want to remove content completely, you remove the node that contains the content. If you want to keep the node, but the content is incorrect, then modify the content. For information on modifying the content of a node, see [Modifying Nodes, Content, and Values in an XML Document](modifying-nodes-content-and-values-in-an-xml-document.md). - +For node types that inherit from , which are the , , , , and node types, you can remove characters using the method, which removes a range of characters from the node. If you want to remove content completely, you remove the node that contains the content. If you want to keep the node, but the content is incorrect, then modify the content. For information on modifying the content of a node, see [Modifying Nodes, Content, and Values in an XML Document](modifying-nodes-content-and-values-in-an-xml-document.md). + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/removing-nodes-from-the-dom.md b/docs/standard/data/xml/removing-nodes-from-the-dom.md index 0fe93b698fc18..ee7e78a7298cc 100644 --- a/docs/standard/data/xml/removing-nodes-from-the-dom.md +++ b/docs/standard/data/xml/removing-nodes-from-the-dom.md @@ -6,14 +6,14 @@ ms.assetid: 0a98e0ca-0555-45c1-ab69-0d8d20ca1abd --- # Removing Nodes from the DOM -To remove a node from the XML Document Object Model (DOM), use the method to remove a specific node. When you remove a node, the method removes the subtree belonging to the node being removed; that is, if it is not a leaf node. - - To remove multiple nodes from the DOM, use the method to remove all the children and attributes, if applicable, of the current node. - - If you are working with an , you can remove a node using the method. - - To remove attributes, see [Removing Attributes from an Element Node in the DOM](removing-attributes-from-an-element-node-in-the-dom.md). - +To remove a node from the XML Document Object Model (DOM), use the method to remove a specific node. When you remove a node, the method removes the subtree belonging to the node being removed; that is, if it is not a leaf node. + + To remove multiple nodes from the DOM, use the method to remove all the children and attributes, if applicable, of the current node. + + If you are working with an , you can remove a node using the method. + + To remove attributes, see [Removing Attributes from an Element Node in the DOM](removing-attributes-from-an-element-node-in-the-dom.md). + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/resolving-external-resources-during-xslt-processing.md b/docs/standard/data/xml/resolving-external-resources-during-xslt-processing.md index 10862da3f8072..e3cbd8bb669d6 100644 --- a/docs/standard/data/xml/resolving-external-resources-during-xslt-processing.md +++ b/docs/standard/data/xml/resolving-external-resources-during-xslt-processing.md @@ -2,43 +2,43 @@ description: "Learn more about: Resolving External Resources During XSLT Processing" title: "Resolving External Resources During XSLT Processing" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 3a59d31c-0ec5-4de6-a2a9-558531c8116e --- # Resolving External Resources During XSLT Processing -There are several times during an XSLT transformation when you may need to resolve external resources. - -## Using the XmlResolver Class - - The class is used to resolve external resources. The following table describes when the becomes involved during XSLT processing. - -|XSLT task|What the XmlResolver is used for| -|---------------|--------------------------------------| -|Compile the style sheet.|Resolve the URI of the style sheet.

-and-

Resolve URI references in any `xsl:import` or `xsl:include` elements.| -|Execute the style sheet.|Resolve the URI of the context document.

-and-

Resolve URI references in any XSLT `document()` functions.| - - The and methods include overloads that take an object as one of its arguments. If an is not specified, a default with no credentials is used. - - The following list describes when you may want to specify an object: - -- If the XSLT process needs to access a network resource that requires authentication, you can use an with the necessary credentials. - -- If you want to restrict the resources that the XSLT process can access, you can use an with the correct permission set. Use the class if you need to open a resource that you do not control, or that is untrusted. - -- If you want to customize behavior, you can implement your own class and use it to resolve resources. - -- If you want to ensure that no external resources are accessed, you can specify `null` for the argument. - -## Example - - The following example compiles a style sheet that is stored on a network resource. An object specifies the credentials necessary to access the style sheet. - +There are several times during an XSLT transformation when you may need to resolve external resources. + +## Using the XmlResolver Class + + The class is used to resolve external resources. The following table describes when the becomes involved during XSLT processing. + +|XSLT task|What the XmlResolver is used for| +|---------------|--------------------------------------| +|Compile the style sheet.|Resolve the URI of the style sheet.

-and-

Resolve URI references in any `xsl:import` or `xsl:include` elements.| +|Execute the style sheet.|Resolve the URI of the context document.

-and-

Resolve URI references in any XSLT `document()` functions.| + + The and methods include overloads that take an object as one of its arguments. If an is not specified, a default with no credentials is used. + + The following list describes when you may want to specify an object: + +- If the XSLT process needs to access a network resource that requires authentication, you can use an with the necessary credentials. + +- If you want to restrict the resources that the XSLT process can access, you can use an with the correct permission set. Use the class if you need to open a resource that you do not control, or that is untrusted. + +- If you want to customize behavior, you can implement your own class and use it to resolve resources. + +- If you want to ensure that no external resources are accessed, you can specify `null` for the argument. + +## Example + + The following example compiles a style sheet that is stored on a network resource. An object specifies the credentials necessary to access the style sheet. + [!code-csharp[XslCompiledTransform.Load#11](../../../../samples/snippets/csharp/VS_Snippets_Data/XslCompiledTransform.Load/CS/Xslt_Load_v2.cs#11)] - [!code-vb[XslCompiledTransform.Load#11](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Load/VB/Xslt_Load_v2.vb#11)] - + [!code-vb[XslCompiledTransform.Load#11](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Load/VB/Xslt_Load_v2.vb#11)] + ## See also - diff --git a/docs/standard/data/xml/rules-for-inferring-schema-node-types-and-structure.md b/docs/standard/data/xml/rules-for-inferring-schema-node-types-and-structure.md index 30dd02c629734..9a0756e75832f 100644 --- a/docs/standard/data/xml/rules-for-inferring-schema-node-types-and-structure.md +++ b/docs/standard/data/xml/rules-for-inferring-schema-node-types-and-structure.md @@ -34,7 +34,7 @@ This topic describes how the schema inference process translates the node types ### Simple Typed Element - The following table shows the XML input to the method, and the XML schema generated. The bolded element shows the schema inferred for the simple type element. + The following table shows the XML input to the method, and the XML schema generated. The bolded element shows the schema inferred for the simple type element. For more information about the schema inference process, see [Inferring Schemas from XML Documents](inferring-schemas-from-xml-documents.md). @@ -44,7 +44,7 @@ This topic describes how the schema inference process translates the node types ### Empty Element - The following table shows the XML input to the method, and the XML schema generated. The bolded element shows the schema inferred for the empty element. + The following table shows the XML input to the method, and the XML schema generated. The bolded element shows the schema inferred for the empty element. For more information about the schema inference process, see [Inferring Schemas from XML Documents](inferring-schemas-from-xml-documents.md). @@ -54,7 +54,7 @@ This topic describes how the schema inference process translates the node types ### Empty Element with Attributes - The following table shows the XML input to the method, and the XML schema generated. The bolded elements show the schema inferred for the empty element with attributes. + The following table shows the XML input to the method, and the XML schema generated. The bolded elements show the schema inferred for the empty element with attributes. For more information about the schema inference process, see [Inferring Schemas from XML Documents](inferring-schemas-from-xml-documents.md). @@ -64,7 +64,7 @@ This topic describes how the schema inference process translates the node types ### Element with Attributes and Simple Content - The following table shows the XML input to the method, and the XML schema generated. The bolded elements show the schema inferred for an element with attributes and simple content. + The following table shows the XML input to the method, and the XML schema generated. The bolded elements show the schema inferred for an element with attributes and simple content. For more information about the schema inference process, see [Inferring Schemas from XML Documents](inferring-schemas-from-xml-documents.md). @@ -74,7 +74,7 @@ This topic describes how the schema inference process translates the node types ### Element with a Sequence of Child Elements - The following table shows the XML input to the method, and the XML schema generated. The bolded elements show the schema inferred for an element with a sequence of child elements. + The following table shows the XML input to the method, and the XML schema generated. The bolded elements show the schema inferred for an element with a sequence of child elements. > [!NOTE] > Even if an element has only one child element, it is still treated as a sequence. @@ -87,7 +87,7 @@ This topic describes how the schema inference process translates the node types ### Element with a Sequence of Child Elements and Attributes - The following table shows the XML input to the method, and the XML schema generated. The bolded elements show the schema inferred for an element with a sequence of child elements and attributes. + The following table shows the XML input to the method, and the XML schema generated. The bolded elements show the schema inferred for an element with a sequence of child elements and attributes. > [!NOTE] > Even if an element has only one child element, it is still treated as a sequence. @@ -100,7 +100,7 @@ This topic describes how the schema inference process translates the node types ### Element with a Sequence and Choices of Child Elements - The following table shows the XML input to the method, and the XML schema generated. The bolded elements show the schema inferred for an element with a sequence and choice of child elements. + The following table shows the XML input to the method, and the XML schema generated. The bolded elements show the schema inferred for an element with a sequence and choice of child elements. > [!NOTE] > The `maxOccurs` attribute of the `xs:choice` element is set to `"unbounded"` in the inferred schema. @@ -113,7 +113,7 @@ This topic describes how the schema inference process translates the node types ### Element with a Sequence and Choice of Child Elements and Attributes - The following table shows the XML input to the method, and the XML schema generated. The bolded elements show the schema inferred for an element with a sequence and choice of child elements and attributes. + The following table shows the XML input to the method, and the XML schema generated. The bolded elements show the schema inferred for an element with a sequence and choice of child elements and attributes. > [!NOTE] > The `maxOccurs` attribute of the `xs:choice` element is set to `"unbounded"` in the inferred schema. @@ -144,7 +144,7 @@ This topic describes how the schema inference process translates the node types |---------------|-----------------| |Processing instruction|Ignored.| |Comment|Ignored.| -|Entity reference|The class does not handle entity references. If an XML document contains entity references, you need to use a reader that expands the entities. For example, you can pass an with the property set to as a parameter. If entity references are encountered and the reader does not expand entities, an exception is throw.| +|Entity reference|The class does not handle entity references. If an XML document contains entity references, you need to use a reader that expands the entities. For example, you can pass an with the property set to as a parameter. If entity references are encountered and the reader does not expand entities, an exception is throw.| |CDATA|Any `, the saved document may differ from the original in the following ways: - -- If the property is set to `true` before the method is called, white space in the document is preserved in the output; if this property is `false`, auto-indents the output. - -- All the white space between attributes is reduced to a single space character. - -- The white space between elements is changed. Significant white space is preserved and insignificant white space is not. But when the document is saved, it will use the **Indenting** mode by default to neatly print the output to make it more readable. - -- The quote character used around attribute values is changed to double quote by default. You can use the property on to set the quote character to either double quote or single quote. - -- By default, numeric character entities like `{` are expanded. - -- The byte-order mark found in the input document is not preserved. UCS-2 is saved as UTF-8 unless you explicitly create an XML declaration that specifies a different encoding. - -- If you want to write out the into a file or stream, the output written out is the same as the content of the document. That is, the is written out only if there is one contained in the document, and the encoding used when writing out the document is the same encoding given in the declaration node. - -## Writing an XmlDeclaration - - The and members of , , and , in addition to the methods of and , create an XML declaration. - - For the properties of , , and the , , and methods, the encoding written out in the XML declaration is taken from the node. If there is no node, is not written out. If there is no encoding in the node, encoding is not written out in the XML declaration. - - The and methods always write out an . These methods take the encoding from the writer that it is writing to. That is, the encoding value on the writer overrides the encoding on the document and in the . For example, the following code does not write an encoding in the XML declaration found in the output file `out.xml`. - -```vb -Dim doc As New XmlDocument() -Dim tw As XmlTextWriter = New XmlTextWriter("out.xml", Nothing) -doc.Load("text.xml") -doc.Save(tw) -``` - -```csharp -XmlDocument doc = new XmlDocument(); -XmlTextWriter tw = new XmlTextWriter("out.xml", null); -doc.Load("text.xml"); -doc.Save(tw); -``` - - For the method, the XML declaration is written out using the method in the class. Therefore, overwriting the method changes how the start of the document is written. - - For the members of , , and , if the property is not set, no encoding is written out. Otherwise, the encoding written out in the XML declaration is the same as the encoding found in the property. - -## Writing Document Content Using the OuterXml Property - - The property is a Microsoft extension to the World Wide Web Consortium (W3C) XML Document Object Model (DOM) standards. The property is used to get the markup of the whole XML document, or just the markup of a single node and its child nodes. returns the markup representing the given node and all its child nodes. - - The following code sample shows how to save a document in its entirety as a string. - -```vb -Dim mydoc As New XmlDocument() -' Perform application needs here, like mydoc.Load("myfile"); -' Now save the entire document to a string variable called "xml". -Dim xml As String = mydoc.OuterXml -``` - -```csharp -XmlDocument mydoc = new XmlDocument(); -// Perform application needs here, like mydoc.Load("myfile"); -// Now save the entire document to a string variable called "xml". -string xml = mydoc.OuterXml; -``` - - The following code sample shows how to save only the document element. - -```vb -' For the content of the Document Element only. -Dim xml As String = mydoc.DocumentElement.OuterXml -``` - -```csharp -// For the content of the Document Element only. -string xml = mydoc.DocumentElement.OuterXml; -``` - - In contrast, you can use the property if you want the content of child nodes. - +When you load and save an , the saved document may differ from the original in the following ways: + +- If the property is set to `true` before the method is called, white space in the document is preserved in the output; if this property is `false`, auto-indents the output. + +- All the white space between attributes is reduced to a single space character. + +- The white space between elements is changed. Significant white space is preserved and insignificant white space is not. But when the document is saved, it will use the **Indenting** mode by default to neatly print the output to make it more readable. + +- The quote character used around attribute values is changed to double quote by default. You can use the property on to set the quote character to either double quote or single quote. + +- By default, numeric character entities like `{` are expanded. + +- The byte-order mark found in the input document is not preserved. UCS-2 is saved as UTF-8 unless you explicitly create an XML declaration that specifies a different encoding. + +- If you want to write out the into a file or stream, the output written out is the same as the content of the document. That is, the is written out only if there is one contained in the document, and the encoding used when writing out the document is the same encoding given in the declaration node. + +## Writing an XmlDeclaration + + The and members of , , and , in addition to the methods of and , create an XML declaration. + + For the properties of , , and the , , and methods, the encoding written out in the XML declaration is taken from the node. If there is no node, is not written out. If there is no encoding in the node, encoding is not written out in the XML declaration. + + The and methods always write out an . These methods take the encoding from the writer that it is writing to. That is, the encoding value on the writer overrides the encoding on the document and in the . For example, the following code does not write an encoding in the XML declaration found in the output file `out.xml`. + +```vb +Dim doc As New XmlDocument() +Dim tw As XmlTextWriter = New XmlTextWriter("out.xml", Nothing) +doc.Load("text.xml") +doc.Save(tw) +``` + +```csharp +XmlDocument doc = new XmlDocument(); +XmlTextWriter tw = new XmlTextWriter("out.xml", null); +doc.Load("text.xml"); +doc.Save(tw); +``` + + For the method, the XML declaration is written out using the method in the class. Therefore, overwriting the method changes how the start of the document is written. + + For the members of , , and , if the property is not set, no encoding is written out. Otherwise, the encoding written out in the XML declaration is the same as the encoding found in the property. + +## Writing Document Content Using the OuterXml Property + + The property is a Microsoft extension to the World Wide Web Consortium (W3C) XML Document Object Model (DOM) standards. The property is used to get the markup of the whole XML document, or just the markup of a single node and its child nodes. returns the markup representing the given node and all its child nodes. + + The following code sample shows how to save a document in its entirety as a string. + +```vb +Dim mydoc As New XmlDocument() +' Perform application needs here, like mydoc.Load("myfile"); +' Now save the entire document to a string variable called "xml". +Dim xml As String = mydoc.OuterXml +``` + +```csharp +XmlDocument mydoc = new XmlDocument(); +// Perform application needs here, like mydoc.Load("myfile"); +// Now save the entire document to a string variable called "xml". +string xml = mydoc.OuterXml; +``` + + The following code sample shows how to save only the document element. + +```vb +' For the content of the Document Element only. +Dim xml As String = mydoc.DocumentElement.OuterXml +``` + +```csharp +// For the content of the Document Element only. +string xml = mydoc.DocumentElement.OuterXml; +``` + + In contrast, you can use the property if you want the content of child nodes. + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/schema-validation-using-xpathnavigator.md b/docs/standard/data/xml/schema-validation-using-xpathnavigator.md index e870dec3b2b75..39f9fdc38653e 100644 --- a/docs/standard/data/xml/schema-validation-using-xpathnavigator.md +++ b/docs/standard/data/xml/schema-validation-using-xpathnavigator.md @@ -2,361 +2,361 @@ description: "Learn more about: Schema Validation using XPathNavigator" title: "Schema Validation using XPathNavigator" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 81fa0e41-d9c9-46f0-b22b-50da839c77f5 --- # Schema Validation using XPathNavigator -Using the class, you can validate the XML content contained in an object in two ways. The first way is to validate the XML content using a validating object and the second way is to use the method of the class. You can also perform read-only validation of XML content using the class. - -## Validating XML Data - - The class does not validate an XML document using either DTD or XML schema definition language (XSD) schema validation by default. It only verifies that the XML document is well formed. - - The first way to validate an XML document is to validate the document as it is loaded into an object using a validating object. The second way is to validate a previously untyped XML document using the method of the class. In both cases, changes to the validated XML document can be revalidated using the method of the class. - -### Validating a Document as it is Loaded - - A validating object is created by passing an object to the method of the class that takes an object as a parameter. The object passed as a parameter has a property set to `Schema` and an XML Schema for the XML document contained in the object added to its property. The validating object is then used to create the object. - - The following example validates the `contosoBooks.xml` file as it is loaded into the object by creating the object using a validating object. Because the XML document is valid according to its schema, no schema validation errors or warnings are generated. - -```vb -Imports System -Imports System.Xml -Imports System.Xml.Schema -Imports System.Xml.XPath - -Class ValidatingReaderExample - - Shared Sub Main(ByVal args() As String) - - Try - Dim settings As XmlReaderSettings = New XmlReaderSettings() - settings.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd") - settings.ValidationType = ValidationType.Schema - - Dim reader As XmlReader = XmlReader.Create("contosoBooks.xml", settings) - - Dim document As XmlDocument = New XmlDocument() - document.Load(reader) - Dim navigator As XPathNavigator = document.CreateNavigator() - - Catch e As Exception - Console.WriteLine("ValidatingReaderExample.Exception: {0}", e.Message) - End Try - - End Sub - - Shared Sub SchemaValidationHandler(ByVal sender As Object, ByVal e As ValidationEventArgs) - - Select Case e.Severity - Case XmlSeverityType.Error - Console.WriteLine("Schema Validation Error: {0}", e.Message) - Exit Sub - Case XmlSeverityType.Warning - Console.WriteLine("Schema Validation Warning: {0}", e.Message) - Exit Sub - End Select - - End Sub - -End Class -``` - -```csharp -using System; -using System.Xml; -using System.Xml.Schema; -using System.Xml.XPath; - -class ValidatingReaderExample -{ - static void Main(string[] args) - { - try - { - XmlReaderSettings settings = new XmlReaderSettings(); - settings.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd"); - settings.ValidationType = ValidationType.Schema; - - XmlReader reader = XmlReader.Create("contosoBooks.xml", settings); - - XmlDocument document = new XmlDocument(); - document.Load(reader); - XPathNavigator navigator = document.CreateNavigator(); - } - catch (Exception e) - { - Console.WriteLine("ValidatingReaderExample.Exception: {0}", e.Message); - } - } - - static void SchemaValidationHandler(object sender, ValidationEventArgs e) - { - switch (e.Severity) - { - case XmlSeverityType.Error: - Console.WriteLine("Schema Validation Error: {0}", e.Message); - break; - case XmlSeverityType.Warning: - Console.WriteLine("Schema Validation Warning: {0}", e.Message); - break; - } - } -} -``` - - The example takes the `contosoBooks.xml` file as an input. - - [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] - - The example also takes the `contosoBooks.xsd` as an input. - - [!code-xml[XPathXMLExamples#3](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xsd#3)] - - In the above example, an will be thrown when is called if any attribute or element type does not match the corresponding type specified in the validating schema. If a is set on the validating , the will get called whenever an invalid type is encountered. - - An will be thrown when an attribute or element with set to `invalid` is accessed by the . - - The property can be used to determine whether or not an individual attribute or element is valid when accessing attributes or elements with the . - +Using the class, you can validate the XML content contained in an object in two ways. The first way is to validate the XML content using a validating object and the second way is to use the method of the class. You can also perform read-only validation of XML content using the class. + +## Validating XML Data + + The class does not validate an XML document using either DTD or XML schema definition language (XSD) schema validation by default. It only verifies that the XML document is well formed. + + The first way to validate an XML document is to validate the document as it is loaded into an object using a validating object. The second way is to validate a previously untyped XML document using the method of the class. In both cases, changes to the validated XML document can be revalidated using the method of the class. + +### Validating a Document as it is Loaded + + A validating object is created by passing an object to the method of the class that takes an object as a parameter. The object passed as a parameter has a property set to `Schema` and an XML Schema for the XML document contained in the object added to its property. The validating object is then used to create the object. + + The following example validates the `contosoBooks.xml` file as it is loaded into the object by creating the object using a validating object. Because the XML document is valid according to its schema, no schema validation errors or warnings are generated. + +```vb +Imports System +Imports System.Xml +Imports System.Xml.Schema +Imports System.Xml.XPath + +Class ValidatingReaderExample + + Shared Sub Main(ByVal args() As String) + + Try + Dim settings As XmlReaderSettings = New XmlReaderSettings() + settings.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd") + settings.ValidationType = ValidationType.Schema + + Dim reader As XmlReader = XmlReader.Create("contosoBooks.xml", settings) + + Dim document As XmlDocument = New XmlDocument() + document.Load(reader) + Dim navigator As XPathNavigator = document.CreateNavigator() + + Catch e As Exception + Console.WriteLine("ValidatingReaderExample.Exception: {0}", e.Message) + End Try + + End Sub + + Shared Sub SchemaValidationHandler(ByVal sender As Object, ByVal e As ValidationEventArgs) + + Select Case e.Severity + Case XmlSeverityType.Error + Console.WriteLine("Schema Validation Error: {0}", e.Message) + Exit Sub + Case XmlSeverityType.Warning + Console.WriteLine("Schema Validation Warning: {0}", e.Message) + Exit Sub + End Select + + End Sub + +End Class +``` + +```csharp +using System; +using System.Xml; +using System.Xml.Schema; +using System.Xml.XPath; + +class ValidatingReaderExample +{ + static void Main(string[] args) + { + try + { + XmlReaderSettings settings = new XmlReaderSettings(); + settings.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd"); + settings.ValidationType = ValidationType.Schema; + + XmlReader reader = XmlReader.Create("contosoBooks.xml", settings); + + XmlDocument document = new XmlDocument(); + document.Load(reader); + XPathNavigator navigator = document.CreateNavigator(); + } + catch (Exception e) + { + Console.WriteLine("ValidatingReaderExample.Exception: {0}", e.Message); + } + } + + static void SchemaValidationHandler(object sender, ValidationEventArgs e) + { + switch (e.Severity) + { + case XmlSeverityType.Error: + Console.WriteLine("Schema Validation Error: {0}", e.Message); + break; + case XmlSeverityType.Warning: + Console.WriteLine("Schema Validation Warning: {0}", e.Message); + break; + } + } +} +``` + + The example takes the `contosoBooks.xml` file as an input. + + [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] + + The example also takes the `contosoBooks.xsd` as an input. + + [!code-xml[XPathXMLExamples#3](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xsd#3)] + + In the above example, an will be thrown when is called if any attribute or element type does not match the corresponding type specified in the validating schema. If a is set on the validating , the will get called whenever an invalid type is encountered. + + An will be thrown when an attribute or element with set to `invalid` is accessed by the . + + The property can be used to determine whether or not an individual attribute or element is valid when accessing attributes or elements with the . + > [!NOTE] -> When an XML document is loaded into an object with an associated schema that defines default values, the object treats these defaults as if they appeared in the XML document. This means that the property always returns `false` for an element that was defaulted from the schema, even if in the XML document it was written as an empty element. - -### Validating a Document using the Validate Method - - The method of the class validates the XML document contained in an object against the schemas specified in the object's property and performs infoset augmentation. The result is a previously untyped XML document in the object replaced with a typed document. - - The object reports schema validation errors and warnings using the delegate passed as a parameter to the method. - - The following example validates the `contosoBooks.xml` file contained in the object against the `contosoBooks.xsd` schema contained in the object's property. - -```vb -Imports System -Imports System.Xml -Imports System.Xml.Schema -Imports System.Xml.XPath - -Class ValidateExample - - Shared Sub Main(ByVal args() As String) - - Dim document As XmlDocument = New XmlDocument() - document.Load("contosoBooks.xml") - Dim navigator As XPathNavigator = document.CreateNavigator() - - document.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd") - Dim validation As ValidationEventHandler = New ValidationEventHandler(AddressOf SchemaValidationHandler) - - document.Validate(validation) - - End Sub - - Shared Sub SchemaValidationHandler(ByVal sender As Object, ByVal e As ValidationEventArgs) - - Select Case e.Severity - Case XmlSeverityType.Error - Console.WriteLine("Schema Validation Error: {0}", e.Message) - Exit Sub - Case XmlSeverityType.Warning - Console.WriteLine("Schema Validation Warning: {0}", e.Message) - Exit Sub - End Select - - End Sub - -End Class -``` - -```csharp -using System; -using System.Xml; -using System.Xml.Schema; -using System.Xml.XPath; - -class ValidateExample -{ - static void Main(string[] args) - { - XmlDocument document = new XmlDocument(); - document.Load("contosoBooks.xml"); - XPathNavigator navigator = document.CreateNavigator(); - - document.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd"); - ValidationEventHandler validation = new ValidationEventHandler(SchemaValidationHandler); - - document.Validate(validation); - } - - static void SchemaValidationHandler(object sender, ValidationEventArgs e) - { - switch (e.Severity) - { - case XmlSeverityType.Error: - Console.WriteLine("Schema Validation Error: {0}", e.Message); - break; - case XmlSeverityType.Warning: - Console.WriteLine("Schema Validation Warning: {0}", e.Message); - break; - } - } -} -``` - - The example takes the `contosoBooks.xml` file as an input. - - [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] - - The example also takes the `contosoBooks.xsd` as an input. - - [!code-xml[XPathXMLExamples#3](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xsd#3)] - -### Validating Modifications - - After modifications are made to an XML document, you can validate the modifications against the schema for the XML document using the method of the class. - - The following example validates the `contosoBooks.xml` file as it is loaded into the object by creating the object using a validating object. The XML document is validated successfully as it is loaded without generating any schema validation errors or warnings. The example then makes two modifications to the XML document that are invalid according to the `contosoBooks.xsd` schema. The first modification inserts an invalid child element resulting in a schema validation error, and the second modification sets the value of a typed node to a value that is invalid according to the type of the node resulting in an exception. - -```vb -Imports System -Imports System.Xml -Imports System.Xml.Schema -Imports System.Xml.XPath - -Class ValidatingReaderExample - - Shared Sub Main(ByVal args() As String) - - Try - Dim settings As XmlReaderSettings = New XmlReaderSettings() - settings.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd") - settings.ValidationType = ValidationType.Schema - - Dim reader As XmlReader = XmlReader.Create("contosoBooks.xml", settings) - - Dim document As XmlDocument = New XmlDocument() - document.Load(reader) - Dim navigator As XPathNavigator = document.CreateNavigator() - - Dim validation As ValidationEventHandler = New ValidationEventHandler(AddressOf SchemaValidationHandler) - - navigator.MoveToChild("bookstore", "http://www.contoso.com/books") - navigator.MoveToChild("book", "http://www.contoso.com/books") - navigator.MoveToChild("author", "http://www.contoso.com/books") - - navigator.AppendChild("Book Title") - - document.Validate(validation) - - navigator.MoveToParent() - navigator.MoveToChild("price", "http://www.contoso.com/books") - navigator.SetTypedValue(DateTime.Now) - Catch e As Exception - Console.WriteLine("ValidatingReaderExample.Exception: {0}", e.Message) - End Try - - End Sub - - Shared Sub SchemaValidationHandler(ByVal sender As Object, ByVal e As ValidationEventArgs) - - Select Case e.Severity - Case XmlSeverityType.Error - Console.WriteLine("Schema Validation Error: {0}", e.Message) - Exit Sub - Case XmlSeverityType.Warning - Console.WriteLine("Schema Validation Warning: {0}", e.Message) - Exit Sub - End Select - - End Sub - -End Class -``` - -```csharp -using System; -using System.Xml; -using System.Xml.Schema; -using System.Xml.XPath; - -class ValidatingReaderExample -{ - static void Main(string[] args) - { - try - { - XmlReaderSettings settings = new XmlReaderSettings(); - settings.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd"); - settings.ValidationType = ValidationType.Schema; - - XmlReader reader = XmlReader.Create("contosoBooks.xml", settings); - - XmlDocument document = new XmlDocument(); - document.Load(reader); - XPathNavigator navigator = document.CreateNavigator(); - - ValidationEventHandler validation = new ValidationEventHandler(SchemaValidationHandler); - - navigator.MoveToChild("bookstore", "http://www.contoso.com/books"); - navigator.MoveToChild("book", "http://www.contoso.com/books"); - navigator.MoveToChild("author", "http://www.contoso.com/books"); - - navigator.AppendChild("Book Title"); - - document.Validate(validation); - - navigator.MoveToParent(); - navigator.MoveToChild("price", "http://www.contoso.com/books"); - navigator.SetTypedValue(DateTime.Now); - } - catch (Exception e) - { - Console.WriteLine("ValidatingReaderExample.Exception: {0}", e.Message); - } - } - - static void SchemaValidationHandler(object sender, ValidationEventArgs e) - { - switch (e.Severity) - { - case XmlSeverityType.Error: - Console.WriteLine("Schema Validation Error: {0}", e.Message); - break; - case XmlSeverityType.Warning: - Console.WriteLine("Schema Validation Warning: {0}", e.Message); - break; - } - } -} -``` - - The example takes the `contosoBooks.xml` file as an input. - - [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] - - The example also takes the `contosoBooks.xsd` as an input. - - [!code-xml[XPathXMLExamples#3](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xsd#3)] - - In the example above, two modifications are made to the XML document contained in the object. As the XML document was loaded, any schema validation errors encountered would have been handled by the validation event handler method and written to the console. - - In this example, the validation errors were introduced after the XML document was loaded and were found using the method of the class. - - Modifications made using the method of the class resulted in an because the new value was invalid according to the schema type of the node. - - For more information about modifying values using the method, see the [Modify XML Data using XPathNavigator](modify-xml-data-using-xpathnavigator.md) topic. - -### Read-Only Validation - - The class is a read-only, in-memory representation of an XML document. Both the class and the class create objects to navigate and edit XML documents. Because the class is a read-only class, object's returned from objects cannot edit the XML document contained in the object. - - In the case of validation, you can create an object just like you create an object using a validating object as described earlier in this topic. The object validates the XML document as it is loaded, but because you cannot edit the XML data in the object, you cannot revalidate the XML document. - - For more information about read-only and editable objects, see the [Reading XML Data using XPathDocument and XmlDocument](reading-xml-data-using-xpathdocument-and-xmldocument.md) topic. - +> When an XML document is loaded into an object with an associated schema that defines default values, the object treats these defaults as if they appeared in the XML document. This means that the property always returns `false` for an element that was defaulted from the schema, even if in the XML document it was written as an empty element. + +### Validating a Document using the Validate Method + + The method of the class validates the XML document contained in an object against the schemas specified in the object's property and performs infoset augmentation. The result is a previously untyped XML document in the object replaced with a typed document. + + The object reports schema validation errors and warnings using the delegate passed as a parameter to the method. + + The following example validates the `contosoBooks.xml` file contained in the object against the `contosoBooks.xsd` schema contained in the object's property. + +```vb +Imports System +Imports System.Xml +Imports System.Xml.Schema +Imports System.Xml.XPath + +Class ValidateExample + + Shared Sub Main(ByVal args() As String) + + Dim document As XmlDocument = New XmlDocument() + document.Load("contosoBooks.xml") + Dim navigator As XPathNavigator = document.CreateNavigator() + + document.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd") + Dim validation As ValidationEventHandler = New ValidationEventHandler(AddressOf SchemaValidationHandler) + + document.Validate(validation) + + End Sub + + Shared Sub SchemaValidationHandler(ByVal sender As Object, ByVal e As ValidationEventArgs) + + Select Case e.Severity + Case XmlSeverityType.Error + Console.WriteLine("Schema Validation Error: {0}", e.Message) + Exit Sub + Case XmlSeverityType.Warning + Console.WriteLine("Schema Validation Warning: {0}", e.Message) + Exit Sub + End Select + + End Sub + +End Class +``` + +```csharp +using System; +using System.Xml; +using System.Xml.Schema; +using System.Xml.XPath; + +class ValidateExample +{ + static void Main(string[] args) + { + XmlDocument document = new XmlDocument(); + document.Load("contosoBooks.xml"); + XPathNavigator navigator = document.CreateNavigator(); + + document.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd"); + ValidationEventHandler validation = new ValidationEventHandler(SchemaValidationHandler); + + document.Validate(validation); + } + + static void SchemaValidationHandler(object sender, ValidationEventArgs e) + { + switch (e.Severity) + { + case XmlSeverityType.Error: + Console.WriteLine("Schema Validation Error: {0}", e.Message); + break; + case XmlSeverityType.Warning: + Console.WriteLine("Schema Validation Warning: {0}", e.Message); + break; + } + } +} +``` + + The example takes the `contosoBooks.xml` file as an input. + + [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] + + The example also takes the `contosoBooks.xsd` as an input. + + [!code-xml[XPathXMLExamples#3](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xsd#3)] + +### Validating Modifications + + After modifications are made to an XML document, you can validate the modifications against the schema for the XML document using the method of the class. + + The following example validates the `contosoBooks.xml` file as it is loaded into the object by creating the object using a validating object. The XML document is validated successfully as it is loaded without generating any schema validation errors or warnings. The example then makes two modifications to the XML document that are invalid according to the `contosoBooks.xsd` schema. The first modification inserts an invalid child element resulting in a schema validation error, and the second modification sets the value of a typed node to a value that is invalid according to the type of the node resulting in an exception. + +```vb +Imports System +Imports System.Xml +Imports System.Xml.Schema +Imports System.Xml.XPath + +Class ValidatingReaderExample + + Shared Sub Main(ByVal args() As String) + + Try + Dim settings As XmlReaderSettings = New XmlReaderSettings() + settings.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd") + settings.ValidationType = ValidationType.Schema + + Dim reader As XmlReader = XmlReader.Create("contosoBooks.xml", settings) + + Dim document As XmlDocument = New XmlDocument() + document.Load(reader) + Dim navigator As XPathNavigator = document.CreateNavigator() + + Dim validation As ValidationEventHandler = New ValidationEventHandler(AddressOf SchemaValidationHandler) + + navigator.MoveToChild("bookstore", "http://www.contoso.com/books") + navigator.MoveToChild("book", "http://www.contoso.com/books") + navigator.MoveToChild("author", "http://www.contoso.com/books") + + navigator.AppendChild("Book Title") + + document.Validate(validation) + + navigator.MoveToParent() + navigator.MoveToChild("price", "http://www.contoso.com/books") + navigator.SetTypedValue(DateTime.Now) + Catch e As Exception + Console.WriteLine("ValidatingReaderExample.Exception: {0}", e.Message) + End Try + + End Sub + + Shared Sub SchemaValidationHandler(ByVal sender As Object, ByVal e As ValidationEventArgs) + + Select Case e.Severity + Case XmlSeverityType.Error + Console.WriteLine("Schema Validation Error: {0}", e.Message) + Exit Sub + Case XmlSeverityType.Warning + Console.WriteLine("Schema Validation Warning: {0}", e.Message) + Exit Sub + End Select + + End Sub + +End Class +``` + +```csharp +using System; +using System.Xml; +using System.Xml.Schema; +using System.Xml.XPath; + +class ValidatingReaderExample +{ + static void Main(string[] args) + { + try + { + XmlReaderSettings settings = new XmlReaderSettings(); + settings.Schemas.Add("http://www.contoso.com/books", "contosoBooks.xsd"); + settings.ValidationType = ValidationType.Schema; + + XmlReader reader = XmlReader.Create("contosoBooks.xml", settings); + + XmlDocument document = new XmlDocument(); + document.Load(reader); + XPathNavigator navigator = document.CreateNavigator(); + + ValidationEventHandler validation = new ValidationEventHandler(SchemaValidationHandler); + + navigator.MoveToChild("bookstore", "http://www.contoso.com/books"); + navigator.MoveToChild("book", "http://www.contoso.com/books"); + navigator.MoveToChild("author", "http://www.contoso.com/books"); + + navigator.AppendChild("Book Title"); + + document.Validate(validation); + + navigator.MoveToParent(); + navigator.MoveToChild("price", "http://www.contoso.com/books"); + navigator.SetTypedValue(DateTime.Now); + } + catch (Exception e) + { + Console.WriteLine("ValidatingReaderExample.Exception: {0}", e.Message); + } + } + + static void SchemaValidationHandler(object sender, ValidationEventArgs e) + { + switch (e.Severity) + { + case XmlSeverityType.Error: + Console.WriteLine("Schema Validation Error: {0}", e.Message); + break; + case XmlSeverityType.Warning: + Console.WriteLine("Schema Validation Warning: {0}", e.Message); + break; + } + } +} +``` + + The example takes the `contosoBooks.xml` file as an input. + + [!code-xml[XPathXMLExamples#2](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xml#2)] + + The example also takes the `contosoBooks.xsd` as an input. + + [!code-xml[XPathXMLExamples#3](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/contosoBooks.xsd#3)] + + In the example above, two modifications are made to the XML document contained in the object. As the XML document was loaded, any schema validation errors encountered would have been handled by the validation event handler method and written to the console. + + In this example, the validation errors were introduced after the XML document was loaded and were found using the method of the class. + + Modifications made using the method of the class resulted in an because the new value was invalid according to the schema type of the node. + + For more information about modifying values using the method, see the [Modify XML Data using XPathNavigator](modify-xml-data-using-xpathnavigator.md) topic. + +### Read-Only Validation + + The class is a read-only, in-memory representation of an XML document. Both the class and the class create objects to navigate and edit XML documents. Because the class is a read-only class, object's returned from objects cannot edit the XML document contained in the object. + + In the case of validation, you can create an object just like you create an object using a validating object as described earlier in this topic. The object validates the XML document as it is loaded, but because you cannot edit the XML data in the object, you cannot revalidate the XML document. + + For more information about read-only and editable objects, see the [Reading XML Data using XPathDocument and XmlDocument](reading-xml-data-using-xpathdocument-and-xmldocument.md) topic. + ## See also - diff --git a/docs/standard/data/xml/script-blocks-using-msxsl-script.md b/docs/standard/data/xml/script-blocks-using-msxsl-script.md index 3b36d3cf9eb6d..0e4f6d942149d 100644 --- a/docs/standard/data/xml/script-blocks-using-msxsl-script.md +++ b/docs/standard/data/xml/script-blocks-using-msxsl-script.md @@ -16,7 +16,7 @@ The class supports embedded scripts u ## Enable XSLT script -Support for embedded scripts is an optional XSLT setting on the class. Script support is disabled by default. To enable script support, create an object with the property set to `true` and pass the object to the method. +Support for embedded scripts is an optional XSLT setting on the class. Script support is disabled by default. To enable script support, create an object with the property set to `true` and pass the object to the method. > [!WARNING] > Starting in .NET 10, the property is marked as obsolete and generates warning SYSLIB0062. Since script blocks aren't supported on .NET Core or .NET 5+, this property has no effect and setting it to `true` throws a at runtime. @@ -34,7 +34,7 @@ Support for embedded scripts is an optional XSLT setting on the method. The class can support any Microsoft .NET language, assuming the appropriate provider is installed on the machine and is registered in the system.codedom section of the machine.config file. If a `language` attribute is not specified, the language defaults to JScript. The language name is not case-sensitive so 'JavaScript' and 'javascript' are equivalent. + The `language` attribute is optional. Its value is the code language of the embedded code block. The language is mapped to the appropriate CodeDOM compiler using the method. The class can support any Microsoft .NET language, assuming the appropriate provider is installed on the machine and is registered in the system.codedom section of the machine.config file. If a `language` attribute is not specified, the language defaults to JScript. The language name is not case-sensitive so 'JavaScript' and 'javascript' are equivalent. The `implements-prefix` attribute is mandatory. This attribute is used to declare a namespace and associate it with the script block. The value of this attribute is the prefix that represents the namespace. This prefix can be defined somewhere in a style sheet. diff --git a/docs/standard/data/xml/select-nodes-using-xpath-navigation.md b/docs/standard/data/xml/select-nodes-using-xpath-navigation.md index 5ddf373a02f14..abf33d368a34d 100644 --- a/docs/standard/data/xml/select-nodes-using-xpath-navigation.md +++ b/docs/standard/data/xml/select-nodes-using-xpath-navigation.md @@ -2,162 +2,162 @@ title: "Select Nodes Using XPath Navigation" description: Learn to select XML nodes in .NET. Use Document Object Model (DOM) methods allowing you to use XML Path Language (XPath) navigation to query DOM information. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.topic: how-to --- # Select Nodes Using XPath Navigation -The XML Document Object Model (DOM) contains methods that allow you to use XML Path Language (XPath) navigation to query information in the DOM. You can use XPath to find a single, specific node or to find all nodes that match some criteria. - -## XPath Select Methods - - The DOM classes provide two methods for XPath selection: the method and the method. The method returns the first node that matches the selection criteria. The method returns an that contains the matching nodes. - - The following example uses the method to select the first `book` node in which the author's last name meets the specified criteria. The bookstore.xml file (which is provided at the end of this topic) is used as the input file. - -```vb -Dim doc As New XmlDocument() -doc.Load("bookstore.xml") -Dim root As XmlNode = doc.DocumentElement - -' Add the namespace. -Dim nsmgr As New XmlNamespaceManager(doc.NameTable) -nsmgr.AddNamespace("bk", "urn:newbooks-schema") - +The XML Document Object Model (DOM) contains methods that allow you to use XML Path Language (XPath) navigation to query information in the DOM. You can use XPath to find a single, specific node or to find all nodes that match some criteria. + +## XPath Select Methods + + The DOM classes provide two methods for XPath selection: the method and the method. The method returns the first node that matches the selection criteria. The method returns an that contains the matching nodes. + + The following example uses the method to select the first `book` node in which the author's last name meets the specified criteria. The bookstore.xml file (which is provided at the end of this topic) is used as the input file. + +```vb +Dim doc As New XmlDocument() +doc.Load("bookstore.xml") +Dim root As XmlNode = doc.DocumentElement + +' Add the namespace. +Dim nsmgr As New XmlNamespaceManager(doc.NameTable) +nsmgr.AddNamespace("bk", "urn:newbooks-schema") + ' Select and display the first node in which the author's -' last name is Kingsolver. -Dim node As XmlNode = root.SelectSingleNode( _ - "descendant::bk:book[bk:author/bk:last-name='Kingsolver']", nsmgr) -Console.WriteLine(node.InnerXml) -``` - -```csharp -// Load the document and set the root element. -XmlDocument doc = new XmlDocument(); -doc.Load("bookstore.xml"); -XmlNode root = doc.DocumentElement; - -// Add the namespace. -XmlNamespaceManager nsmgr = new XmlNamespaceManager(doc.NameTable); -nsmgr.AddNamespace("bk", "urn:newbooks-schema"); - +' last name is Kingsolver. +Dim node As XmlNode = root.SelectSingleNode( _ + "descendant::bk:book[bk:author/bk:last-name='Kingsolver']", nsmgr) +Console.WriteLine(node.InnerXml) +``` + +```csharp +// Load the document and set the root element. +XmlDocument doc = new XmlDocument(); +doc.Load("bookstore.xml"); +XmlNode root = doc.DocumentElement; + +// Add the namespace. +XmlNamespaceManager nsmgr = new XmlNamespaceManager(doc.NameTable); +nsmgr.AddNamespace("bk", "urn:newbooks-schema"); + // Select and display the first node in which the author's -// last name is Kingsolver. -XmlNode node = root.SelectSingleNode( - "descendant::bk:book[bk:author/bk:last-name='Kingsolver']", nsmgr); -Console.WriteLine(node.InnerXml); -``` - - The next example uses the method to select all the book nodes in which the price is greater than a specified amount. The price for each book in the selected list is then programmatically reduced by ten percent. Finally, the updated file is written to the console. The bookstore.xml file (which is provided at the end of this topic) is used as the input file. - -```vb -' Load the document and set the root element. -Dim doc As New XmlDocument() -doc.Load("bookstore.xml") -Dim root As XmlNode = doc.DocumentElement - -' Add the namespace. -Dim nsmgr As New XmlNamespaceManager(doc.NameTable) -nsmgr.AddNamespace("bk", "urn:newbooks-schema") - -' Select all nodes where the book price is greater than 10.00. -Dim nodeList As XmlNodeList = root.SelectNodes( _ - "descendant::bk:book[bk:price>10.00]", nsmgr) -For Each book As XmlNode In nodeList - Dim price As Double - price = Math.Round(Convert.ToSingle( _ - book.LastChild.InnerText) * 0.9, 2) - book.LastChild.InnerText = price.ToString() -Next - -' Display the updated document. -doc.Save(Console.Out) -``` - -```csharp -// Load the document and set the root element. -XmlDocument doc = new XmlDocument(); -doc.Load("bookstore.xml"); -XmlNode root = doc.DocumentElement; - -// Add the namespace. -XmlNamespaceManager nsmgr = new XmlNamespaceManager(doc.NameTable); -nsmgr.AddNamespace("bk", "urn:newbooks-schema"); - -// Select all nodes where the book price is greater than 10.00. -XmlNodeList nodeList = root.SelectNodes( - "descendant::bk:book[bk:price>10.00]", nsmgr); -foreach (XmlNode book in nodeList) -{ - // Discount prices by 10%. - double price; - price = Math.Round(Convert.ToSingle( - book.LastChild.InnerText) * 0.9, 2); - book.LastChild.InnerText = price.ToString(); -} - -// Display the updated document. -doc.Save(Console.Out); -``` - - The examples above start the XPath query at the document element. Setting the starting point for the XPath query sets the context node, which is the starting point for the XPath query. If you do not want to start at the document element, but want to start from the first child of the document element, you can code the select statement as follows: - -```vb -doc.DocumentElement.FirstChild.SelectNodes(. . . ) -``` - -```csharp -this doc.DocumentElement.FirstChild.SelectNodes(. . .); -``` - - All objects are synchronized with the underlying document. Therefore, if you iterate through the node list and modify the value of a node, that node is also updated in the document it came from. Notice in the previous example that when a node is modified in the selected the underlying document is also modified. - +// last name is Kingsolver. +XmlNode node = root.SelectSingleNode( + "descendant::bk:book[bk:author/bk:last-name='Kingsolver']", nsmgr); +Console.WriteLine(node.InnerXml); +``` + + The next example uses the method to select all the book nodes in which the price is greater than a specified amount. The price for each book in the selected list is then programmatically reduced by ten percent. Finally, the updated file is written to the console. The bookstore.xml file (which is provided at the end of this topic) is used as the input file. + +```vb +' Load the document and set the root element. +Dim doc As New XmlDocument() +doc.Load("bookstore.xml") +Dim root As XmlNode = doc.DocumentElement + +' Add the namespace. +Dim nsmgr As New XmlNamespaceManager(doc.NameTable) +nsmgr.AddNamespace("bk", "urn:newbooks-schema") + +' Select all nodes where the book price is greater than 10.00. +Dim nodeList As XmlNodeList = root.SelectNodes( _ + "descendant::bk:book[bk:price>10.00]", nsmgr) +For Each book As XmlNode In nodeList + Dim price As Double + price = Math.Round(Convert.ToSingle( _ + book.LastChild.InnerText) * 0.9, 2) + book.LastChild.InnerText = price.ToString() +Next + +' Display the updated document. +doc.Save(Console.Out) +``` + +```csharp +// Load the document and set the root element. +XmlDocument doc = new XmlDocument(); +doc.Load("bookstore.xml"); +XmlNode root = doc.DocumentElement; + +// Add the namespace. +XmlNamespaceManager nsmgr = new XmlNamespaceManager(doc.NameTable); +nsmgr.AddNamespace("bk", "urn:newbooks-schema"); + +// Select all nodes where the book price is greater than 10.00. +XmlNodeList nodeList = root.SelectNodes( + "descendant::bk:book[bk:price>10.00]", nsmgr); +foreach (XmlNode book in nodeList) +{ + // Discount prices by 10%. + double price; + price = Math.Round(Convert.ToSingle( + book.LastChild.InnerText) * 0.9, 2); + book.LastChild.InnerText = price.ToString(); +} + +// Display the updated document. +doc.Save(Console.Out); +``` + + The examples above start the XPath query at the document element. Setting the starting point for the XPath query sets the context node, which is the starting point for the XPath query. If you do not want to start at the document element, but want to start from the first child of the document element, you can code the select statement as follows: + +```vb +doc.DocumentElement.FirstChild.SelectNodes(. . . ) +``` + +```csharp +this doc.DocumentElement.FirstChild.SelectNodes(. . .); +``` + + All objects are synchronized with the underlying document. Therefore, if you iterate through the node list and modify the value of a node, that node is also updated in the document it came from. Notice in the previous example that when a node is modified in the selected the underlying document is also modified. + > [!NOTE] -> When the underlying document is modified, it is advisable to rerun the select. If the node modified is one that could cause the node to be added to the node list when it was not previously, or would now cause it to be removed from the node list, there is no guarantee that the node list is now accurate. - -## Namespaces in XPath Expressions +> When the underlying document is modified, it is advisable to rerun the select. If the node modified is one that could cause the node to be added to the node list when it was not previously, or would now cause it to be removed from the node list, there is no guarantee that the node list is now accurate. + +## Namespaces in XPath Expressions + + XPath expressions can include namespaces. Namespace resolution is supported using the . If the XPath expression includes a prefix, the prefix and namespace URI pair must be added to the , and the is passed to the or method. Notice that the code examples above use the to resolve the namespace of the bookstore.xml document. - XPath expressions can include namespaces. Namespace resolution is supported using the . If the XPath expression includes a prefix, the prefix and namespace URI pair must be added to the , and the is passed to the or method. Notice that the code examples above use the to resolve the namespace of the bookstore.xml document. - > [!NOTE] -> If the XPath expression does not include a prefix, it is assumed that the namespace Uniform Resource Identifier (URI) is the empty namespace. If your XML includes a default namespace, you must still add a prefix and namespace URI to the ; otherwise, no nodes will be selected. - -#### Input File - - The following is the bookstore.xml file that is used as the input file in the examples in this topic: - -```xml - - - - The Handmaid's Tale - - Margaret - Atwood - - 19.95 - - - The Poisonwood Bible - - Barbara - Kingsolver - - 11.99 - - - The Bean Trees - - Barbara - Kingsolver - - 5.99 - - -``` - +> If the XPath expression does not include a prefix, it is assumed that the namespace Uniform Resource Identifier (URI) is the empty namespace. If your XML includes a default namespace, you must still add a prefix and namespace URI to the ; otherwise, no nodes will be selected. + +#### Input File + + The following is the bookstore.xml file that is used as the input file in the examples in this topic: + +```xml + + + + The Handmaid's Tale + + Margaret + Atwood + + 19.95 + + + The Poisonwood Bible + + Barbara + Kingsolver + + 11.99 + + + The Bean Trees + + Barbara + Kingsolver + + 5.99 + + +``` + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/select-xml-data-using-xpathnavigator.md b/docs/standard/data/xml/select-xml-data-using-xpathnavigator.md index 6ada6d975c36c..5bd66192196e1 100644 --- a/docs/standard/data/xml/select-xml-data-using-xpathnavigator.md +++ b/docs/standard/data/xml/select-xml-data-using-xpathnavigator.md @@ -2,62 +2,62 @@ description: "Learn more about: Select XML Data Using XPathNavigator" title: "Select XML Data Using XPathNavigator" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.topic: how-to --- # Select XML Data Using XPathNavigator -The class provides a set of methods used to select a set of nodes in an or object using an XPath expression. Once selected, you can iterate over the selected set of nodes. - -## XPathNavigator Selection Methods - - The class provides a set of methods used to select a set of nodes in an or object using an XPath expression. The class also provides a set of optimized methods for selecting ancestor, child and descendant nodes faster than using an XPath expression. The selected set of nodes is returned in an object or an object in the case of a single selected node. - -### Selecting Nodes Using XPath Expressions - - To select a set of nodes using an XPath expression, use one of the following selection methods. - -- - -- - - When called, these methods return a set of nodes that you can navigate freely using an object or an object in the case of a single selected node. - - Navigating with an object does not affect the position of the object used to create it. The object returned from the methods is positioned on the single returned node and also does not affect the position of the object used to create it. - - The following example shows the creation of an object from an object, the use of the method to select nodes in the object, and the use of the object to iterate over the selected nodes. - -```vb -Dim document As XPathDocument = New XPathDocument("books.xml") -Dim navigator As XPathNavigator = document.CreateNavigator() -Dim nodes As XPathNodeIterator = navigator.Select("/bookstore/book") - -While nodes.MoveNext() - Console.WriteLine(nodes.Current.Name) -End While -``` - -```csharp -XPathDocument document = new XPathDocument("books.xml"); -XPathNavigator navigator = document.CreateNavigator(); -XPathNodeIterator nodes = navigator.Select("/bookstore/book"); - -while(nodes.MoveNext()) -{ - Console.WriteLine(nodes.Current.Name); -} -``` - - The example takes the `books.xml` file as input. - - [!code-xml[XPathXMLExamples#1](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/books.xml#1)] - -### Optimized Selection Methods - - The , , and methods of the class represent XPath expressions commonly used to retrieve child, descendant, and ancestor nodes. These methods are optimized for performance and are faster than their corresponding XPath expressions. The , , and methods selects ancestor, child, and descendant nodes based on an value or the local name and namespace URI of the nodes to select. The selected ancestor, child, and descendant nodes are returned in an object. - +The class provides a set of methods used to select a set of nodes in an or object using an XPath expression. Once selected, you can iterate over the selected set of nodes. + +## XPathNavigator Selection Methods + + The class provides a set of methods used to select a set of nodes in an or object using an XPath expression. The class also provides a set of optimized methods for selecting ancestor, child and descendant nodes faster than using an XPath expression. The selected set of nodes is returned in an object or an object in the case of a single selected node. + +### Selecting Nodes Using XPath Expressions + + To select a set of nodes using an XPath expression, use one of the following selection methods. + +- + +- + + When called, these methods return a set of nodes that you can navigate freely using an object or an object in the case of a single selected node. + + Navigating with an object does not affect the position of the object used to create it. The object returned from the methods is positioned on the single returned node and also does not affect the position of the object used to create it. + + The following example shows the creation of an object from an object, the use of the method to select nodes in the object, and the use of the object to iterate over the selected nodes. + +```vb +Dim document As XPathDocument = New XPathDocument("books.xml") +Dim navigator As XPathNavigator = document.CreateNavigator() +Dim nodes As XPathNodeIterator = navigator.Select("/bookstore/book") + +While nodes.MoveNext() + Console.WriteLine(nodes.Current.Name) +End While +``` + +```csharp +XPathDocument document = new XPathDocument("books.xml"); +XPathNavigator navigator = document.CreateNavigator(); +XPathNodeIterator nodes = navigator.Select("/bookstore/book"); + +while(nodes.MoveNext()) +{ + Console.WriteLine(nodes.Current.Name); +} +``` + + The example takes the `books.xml` file as input. + + [!code-xml[XPathXMLExamples#1](../../../../samples/snippets/xml/VS_Snippets_Data/XPathXMLExamples/XML/books.xml#1)] + +### Optimized Selection Methods + + The , , and methods of the class represent XPath expressions commonly used to retrieve child, descendant, and ancestor nodes. These methods are optimized for performance and are faster than their corresponding XPath expressions. The , , and methods selects ancestor, child, and descendant nodes based on an value or the local name and namespace URI of the nodes to select. The selected ancestor, child, and descendant nodes are returned in an object. + ## See also - diff --git a/docs/standard/data/xml/selecting-evaluating-and-matching-xml-data-using-xpathnavigator.md b/docs/standard/data/xml/selecting-evaluating-and-matching-xml-data-using-xpathnavigator.md index 10f0a89eefff0..dfbb14a33245c 100644 --- a/docs/standard/data/xml/selecting-evaluating-and-matching-xml-data-using-xpathnavigator.md +++ b/docs/standard/data/xml/selecting-evaluating-and-matching-xml-data-using-xpathnavigator.md @@ -6,28 +6,28 @@ ms.assetid: 46e059f8-4dc8-4185-9236-784be95228ed --- # Selecting, Evaluating and Matching XML Data using XPathNavigator -The class provides methods to select nodes in an or object using an XPath query, evaluate and examine the results of an XPath expression, and determine if a node in an or object matches a given XPath expression. These and other concepts that relate to selecting, evaluating and matching nodes in an or object are described in the following topics. - -## In This Section - - [Select XML Data Using XPathNavigator](select-xml-data-using-xpathnavigator.md) - Describes the set of class methods used to select a set of nodes in an or object using an XPath expression. - - [Evaluate XPath Expressions using XPathNavigator](evaluate-xpath-expressions-using-xpathnavigator.md) - Describes the method of the class used to evaluate an XPath expression. - - [Matching Nodes using XPathNavigator](matching-nodes-using-xpathnavigator.md) - Describes the method of the class used to determine if a node matches an XPath expression. - - [Node Types Recognized with XPath Queries](node-types-recognized-with-xpath-queries.md) - Describes the types of nodes recognized in an XPath query. - - [XPath Queries and Namespaces](xpath-queries-and-namespaces.md) - Describes the use of namespaces in an XPath query. - - [Compiled XPath Expressions](compiled-xpath-expressions.md) - Describes the class that represents a compiled XPath query. - +The class provides methods to select nodes in an or object using an XPath query, evaluate and examine the results of an XPath expression, and determine if a node in an or object matches a given XPath expression. These and other concepts that relate to selecting, evaluating and matching nodes in an or object are described in the following topics. + +## In This Section + + [Select XML Data Using XPathNavigator](select-xml-data-using-xpathnavigator.md) + Describes the set of class methods used to select a set of nodes in an or object using an XPath expression. + + [Evaluate XPath Expressions using XPathNavigator](evaluate-xpath-expressions-using-xpathnavigator.md) + Describes the method of the class used to evaluate an XPath expression. + + [Matching Nodes using XPathNavigator](matching-nodes-using-xpathnavigator.md) + Describes the method of the class used to determine if a node matches an XPath expression. + + [Node Types Recognized with XPath Queries](node-types-recognized-with-xpath-queries.md) + Describes the types of nodes recognized in an XPath query. + + [XPath Queries and Namespaces](xpath-queries-and-namespaces.md) + Describes the use of namespaces in an XPath query. + + [Compiled XPath Expressions](compiled-xpath-expressions.md) + Describes the class that represents a compiled XPath query. + ## See also - diff --git a/docs/standard/data/xml/traversing-xml-schemas.md b/docs/standard/data/xml/traversing-xml-schemas.md index da3850550dd08..a0f09de4f3b93 100644 --- a/docs/standard/data/xml/traversing-xml-schemas.md +++ b/docs/standard/data/xml/traversing-xml-schemas.md @@ -16,20 +16,20 @@ The following properties of the class provide |Property|Object type stored in the collection or array| |--------------|---------------------------------------------------| -||| -||| -||| -||| -||, , , or | -|| (provides access to all global level elements, attributes, and types).| -||| -||, , | -|| (provides access to attributes that do not belong to the schema namespace)| +||| +||| +||| +||| +||, , , or | +|| (provides access to all global level elements, attributes, and types).| +||| +||, , | +|| (provides access to attributes that do not belong to the schema namespace)| > [!NOTE] -> All of the properties listed in the table above, except for the property, are Post-Schema-Compilation-Infoset (PSCI) properties that are not available until the schema has been compiled. The property is a pre-schema-compilation property that can be used before the schema has been compiled to access and edit all global level elements, attributes, and types. +> All of the properties listed in the table above, except for the property, are Post-Schema-Compilation-Infoset (PSCI) properties that are not available until the schema has been compiled. The property is a pre-schema-compilation property that can be used before the schema has been compiled to access and edit all global level elements, attributes, and types. > -> The property provides access to all the attributes that do not belong to the schema namespace. These attributes are not processed by the schema processor. +> The property provides access to all the attributes that do not belong to the schema namespace. These attributes are not processed by the schema processor. The code example that follows demonstrates traversing the customer schema created in the [Building XML Schemas](building-xml-schemas.md) topic. The code example demonstrates traversing the schema using the collections described above and writes all the elements and attributes in the schema to the console. @@ -37,9 +37,9 @@ The sample traverses the customer schema in the following steps. 1. Adds the customer schema to a new object and then compiles it. Any schema validation warnings and errors encountered reading or compiling the schema are handled by the delegate. -2. Retrieves the compiled object from the by iterating over the property. Because the schema is compiled, Post-Schema-Compilation-Infoset (PSCI) properties are accessible. +2. Retrieves the compiled object from the by iterating over the property. Because the schema is compiled, Post-Schema-Compilation-Infoset (PSCI) properties are accessible. -3. Iterates over each in the collection of the post-schema-compilation collection writing the name of each element to the console. +3. Iterates over each in the collection of the post-schema-compilation collection writing the name of each element to the console. 4. Gets the complex type of the `Customer` element using the class. @@ -47,15 +47,15 @@ The sample traverses the customer schema in the following steps. 6. Gets the sequence particle of the complex type using the class. -7. Iterates over each in the collection writing the name of each child element to the console. +7. Iterates over each in the collection writing the name of each child element to the console. The following is the complete code example. [!code-csharp[XmlSchemaTraverseExample#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaTraverseExample/CS/XmlSchemaTraverseExample.cs#1)] [!code-vb[XmlSchemaTraverseExample#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XmlSchemaTraverseExample/VB/XmlSchemaTraverseExample.vb#1)] -The property can be , or if it is a user-defined simple type or a complex type. It can also be if it is one of the built-in datatypes defined in the W3C XML Schema Recommendation. In the customer schema, the of the `Customer` element is , and the `FirstName` and `LastName` elements are . +The property can be , or if it is a user-defined simple type or a complex type. It can also be if it is one of the built-in datatypes defined in the W3C XML Schema Recommendation. In the customer schema, the of the `Customer` element is , and the `FirstName` and `LastName` elements are . -The code example in the [Building XML Schemas](building-xml-schemas.md) topic used the collection to add the attribute `CustomerId` to the `Customer` element. This is a pre-schema-compilation property. The corresponding Post-Schema-Compilation-Infoset property is the collection, which holds all the attributes of the complex type, including the ones that are inherited through type derivation. +The code example in the [Building XML Schemas](building-xml-schemas.md) topic used the collection to add the attribute `CustomerId` to the `Customer` element. This is a pre-schema-compilation property. The corresponding Post-Schema-Compilation-Infoset property is the collection, which holds all the attributes of the complex type, including the ones that are inherited through type derivation. ## See also diff --git a/docs/standard/data/xml/type-support-in-the-system-xml-classes.md b/docs/standard/data/xml/type-support-in-the-system-xml-classes.md index 1ad27a5e1cd97..e52581a09ca45 100644 --- a/docs/standard/data/xml/type-support-in-the-system-xml-classes.md +++ b/docs/standard/data/xml/type-support-in-the-system-xml-classes.md @@ -6,32 +6,32 @@ ms.assetid: 63570538-06e3-4401-ad4d-ac50be90c7bf --- # Type Support in the System.Xml Classes -In .NET Framework version 2.0, the core XML classes have been enhanced to include type support features. The , , and classes include type support features including the ability to convert between XML Schema types and common language runtime (CLR) types. - - In .NET Framework version 2.0, the , , and classes have been enhanced to include type support features. - -- The and classes each include a **SchemaInfo** property that returns the schema information on a node. - -- The **ReadContentAs** and **ReadElementContentAs** and methods on the class read a text value and convert it to a CLR value in a single method call. - -- The method on the class converts a CLR type to an XML Schema type when writing out XML. - -- The **ValueAs** and properties on the class return a node value and convert it to a CLR value in a single method call. - +In .NET Framework version 2.0, the core XML classes have been enhanced to include type support features. The , , and classes include type support features including the ability to convert between XML Schema types and common language runtime (CLR) types. + + In .NET Framework version 2.0, the , , and classes have been enhanced to include type support features. + +- The and classes each include a **SchemaInfo** property that returns the schema information on a node. + +- The **ReadContentAs** and **ReadElementContentAs** and methods on the class read a text value and convert it to a CLR value in a single method call. + +- The method on the class converts a CLR type to an XML Schema type when writing out XML. + +- The **ValueAs** and properties on the class return a node value and convert it to a CLR value in a single method call. + > [!NOTE] -> In the .NET Framework version 1.0 the class was needed to convert between XML Schema and CLR types. - -## In This Section - - [Mapping XML Data Types to CLR Types](mapping-xml-data-types-to-clr-types.md) - Describes the default mappings of XML data types to CLR types. - - [XML Type Support Implementation Notes](xml-type-support-implementation-notes.md) - Discusses some of the type support implementation details. - - [Conversion of XML Data Types](conversion-of-xml-data-types.md) - Describes how to use the class to convert between XML Schema and CLR types. - -## Related Sections +> In the .NET Framework version 1.0 the class was needed to convert between XML Schema and CLR types. + +## In This Section + + [Mapping XML Data Types to CLR Types](mapping-xml-data-types-to-clr-types.md) + Describes the default mappings of XML data types to CLR types. + + [XML Type Support Implementation Notes](xml-type-support-implementation-notes.md) + Discusses some of the type support implementation details. + + [Conversion of XML Data Types](conversion-of-xml-data-types.md) + Describes how to use the class to convert between XML Schema and CLR types. + +## Related Sections [Accessing Strongly Typed XML Data Using XPathNavigator](accessing-strongly-typed-xml-data-using-xpathnavigator.md) diff --git a/docs/standard/data/xml/types-of-xml-nodes.md b/docs/standard/data/xml/types-of-xml-nodes.md index b40fd8c81781e..33d2c5e4b59eb 100644 --- a/docs/standard/data/xml/types-of-xml-nodes.md +++ b/docs/standard/data/xml/types-of-xml-nodes.md @@ -6,39 +6,39 @@ ms.topic: reference --- # Types of XML Nodes -When an XML document is read into memory as a tree of nodes, the node types for the nodes are decided when the nodes are created. The XML Document Object Model (DOM) has several kinds of node types, determined by the World Wide Web Consortium (W3C) and listed in section 1.1.1 The DOM Structure Model. The following table lists the node types, the object assigned to that node type, and a short description of each. - -|DOM node type|Object|Description| -|-------------------|------------|-----------------| -|Document||The container of all the nodes in the tree. It is also known as the document root, which is not always the same as the root element.| -|DocumentFragment||A temporary bag containing one or more nodes without any tree structure.| -|DocumentType||Represents the `` node.| -|EntityReference||Represents the non-expanded entity reference text.| -|Element||Represents an element node.| -|Attr||Is an attribute of an element.| -|ProcessingInstruction||Is a processing instruction node.| -|Comment||A comment node.| -|Text||Text belonging to an element or attribute.| -|CDATASection||Represents CDATA.| -|Entity||Represents the `` declarations in an XML document, either from an internal document type definition (DTD) subset or from external DTDs and parameter entities.| -|Notation||Represents a notation declared in the DTD.| - - Even though an attribute (*attr*) is listed in the W3C DOM Level 1 section 1.2 Fundamental Interfaces as a node, it is not considered a child of any element node. - - The following table shows additional node types not defined by the W3C, however they are available for use in the Microsoft .NET Framework object model as **XmlNodeType** enumerations. Therefore, there is no matching DOM node type column for these node types. - -|Node type|Description| -|---------------|-----------------| -||Represents the declaration node ``.| -||Represents significant white space, which is white space in mixed content.| -||Represents the white space in the content of an element.| -|EndElement|Returned when **XmlReader** gets to the end of an element.

Example XML: **\**

For more information, see .| -|EndEntity|Returned when **XmlReader** gets to the end of the entity replacement as a result of a call to . For more information, see .| - - To view a code example that reads in XML and uses a case construct on the node types to print information about the node and its contents, see . - - For more information on the object hierarchy of the node types and their equivalent object name, see [XML Document Object Model (DOM) Hierarchy](xml-document-object-model-dom-hierarchy.md). For more information on the objects created in the node tree, see [Mapping the Object Hierarchy to XML Data](mapping-the-object-hierarchy-to-xml-data.md). - +When an XML document is read into memory as a tree of nodes, the node types for the nodes are decided when the nodes are created. The XML Document Object Model (DOM) has several kinds of node types, determined by the World Wide Web Consortium (W3C) and listed in section 1.1.1 The DOM Structure Model. The following table lists the node types, the object assigned to that node type, and a short description of each. + +|DOM node type|Object|Description| +|-------------------|------------|-----------------| +|Document||The container of all the nodes in the tree. It is also known as the document root, which is not always the same as the root element.| +|DocumentFragment||A temporary bag containing one or more nodes without any tree structure.| +|DocumentType||Represents the `` node.| +|EntityReference||Represents the non-expanded entity reference text.| +|Element||Represents an element node.| +|Attr||Is an attribute of an element.| +|ProcessingInstruction||Is a processing instruction node.| +|Comment||A comment node.| +|Text||Text belonging to an element or attribute.| +|CDATASection||Represents CDATA.| +|Entity||Represents the `` declarations in an XML document, either from an internal document type definition (DTD) subset or from external DTDs and parameter entities.| +|Notation||Represents a notation declared in the DTD.| + + Even though an attribute (*attr*) is listed in the W3C DOM Level 1 section 1.2 Fundamental Interfaces as a node, it is not considered a child of any element node. + + The following table shows additional node types not defined by the W3C, however they are available for use in the Microsoft .NET Framework object model as **XmlNodeType** enumerations. Therefore, there is no matching DOM node type column for these node types. + +|Node type|Description| +|---------------|-----------------| +||Represents the declaration node ``.| +||Represents significant white space, which is white space in mixed content.| +||Represents the white space in the content of an element.| +|EndElement|Returned when **XmlReader** gets to the end of an element.

Example XML: **\**

For more information, see .| +|EndEntity|Returned when **XmlReader** gets to the end of the entity replacement as a result of a call to . For more information, see .| + + To view a code example that reads in XML and uses a case construct on the node types to print information about the node and its contents, see . + + For more information on the object hierarchy of the node types and their equivalent object name, see [XML Document Object Model (DOM) Hierarchy](xml-document-object-model-dom-hierarchy.md). For more information on the objects created in the node tree, see [Mapping the Object Hierarchy to XML Data](mapping-the-object-hierarchy-to-xml-data.md). + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/unordered-node-retrieval-by-name-or-index.md b/docs/standard/data/xml/unordered-node-retrieval-by-name-or-index.md index aceba5e7179af..9d47303ebb28b 100644 --- a/docs/standard/data/xml/unordered-node-retrieval-by-name-or-index.md +++ b/docs/standard/data/xml/unordered-node-retrieval-by-name-or-index.md @@ -2,116 +2,116 @@ description: "Learn more about: Unordered Node Retrieval by Name or Index" title: "Unordered Node Retrieval by Name or Index" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 2038a90b-92af-4a0a-baaa-08e688d95194 --- # Unordered Node Retrieval by Name or Index -The **XmlNamedNodeMap** is described in the World Wide Web Consortium (W3C) specification as the NamedNodeMap and is required to handle an unordered set of nodes with the ability to reference nodes by their name or index. The only way you have access to an **XmlNamedNodeMap** is when an **XmlNamedNodeMap** is returned through a method or property. There are three methods or properties that return an **XmlNamedNodeMap**: - -- XmlElement.Attributes - -- XmlDocumentType.Entities - -- XmlDocumentType.Notations - - For example, the **XmlDocumentType.Entities** property gets the collection of **XmlEntity** nodes declared in the document type declaration. This collection is returned as an **XmlNamedNodeMap**, and you can iterate through the collection with the use of the **Count** property and display entity information. For an example of iterating through an **XmlNamedNodeMap**, see . - - The **XmlAttributeCollection** is derived from **XmlNamedNodeMap** and only attributes are modifiable, while notations and entities are read-only. Using the **XmlNamedNodeMap** for the attributes, you can get nodes for those attributes based on their XML names. This provides an easy method for manipulating the collection of attributes on an element node. This can be contrasted directly with **XmlNodeList**, which also implements the **IEnumerable** interface, but with an index accessor rather than a string. The **RemoveNamedItem** and **SetNamedItem** methods are only used against an **XmlAttributeCollection**. Adding or removing from an attribute collection, whether using the **AttributeCollection** or the **XmlNamedNodeMap** implementation, modifies the attribute collection on the element. The following code example shows how to move an attribute and create a new attribute. - -```vb -Imports System -Imports System.Xml - -Class test - - Public Shared Sub Main() - Dim doc As New XmlDocument() - doc.LoadXml(" text1 text2 ") - - ' Get the attributes of node "child2 " - Dim ac As XmlAttributeCollection = doc.DocumentElement.ChildNodes(1).Attributes - - ' Print out the number of attributes and their names. - Console.WriteLine(("Number of Attributes: " + ac.Count)) - Dim i As Integer - For i = 0 To ac.Count - 1 - Console.WriteLine((i + 1 + ". Attribute Name: '" + ac(i).Name + "' Attribute Value: '" + ac(i).Value + "'")) - Next i - ' Get the 'attr1' from child1. - Dim attr As XmlAttribute = doc.DocumentElement.ChildNodes(0).Attributes(0) - - ' Add this attribute to the attributecollection "ac". - ac.SetNamedItem(attr) - - ''attr1' will be removed from 'child1' and added to 'child2'. - ' Print out the number of attributes and their names. - Console.WriteLine(("Number of Attributes: " + ac.Count)) - - For i = 0 To ac.Count - 1 - Console.WriteLine((i + 1 + ". Attribute Name: '" + ac(i).Name + "' Attribute Value: '" + ac(i).Value + "'")) - Next i - ' Create a new attribute and add to the collection. - Dim attr2 As XmlAttribute = doc.CreateAttribute("attr4") - attr2.Value = "val4" - ac.SetNamedItem(attr2) - - ' Print out the number of attributes and their names. - Console.WriteLine(("Number of Attributes: " + ac.Count)) - - For i = 0 To ac.Count - 1 - Console.WriteLine((i + 1 + ". Attribute Name: '" + ac(i).Name + "' Attribute Value: '" + ac(i).Value + "'")) - Next i - End Sub 'Main -End Class 'test -``` - -```csharp -using System; -using System.Xml; -class test { - public static void Main() { - XmlDocument doc = new XmlDocument(); - doc.LoadXml( " text1 text2 " ); - - // Get the attributes of node "child2" - XmlAttributeCollection ac = doc.DocumentElement.ChildNodes[1].Attributes; - - // Print out the number of attributes and their names. - Console.WriteLine( "Number of Attributes: "+ac.Count ); - for( int i = 0; i < ac.Count; i++ ) +The **XmlNamedNodeMap** is described in the World Wide Web Consortium (W3C) specification as the NamedNodeMap and is required to handle an unordered set of nodes with the ability to reference nodes by their name or index. The only way you have access to an **XmlNamedNodeMap** is when an **XmlNamedNodeMap** is returned through a method or property. There are three methods or properties that return an **XmlNamedNodeMap**: + +- XmlElement.Attributes + +- XmlDocumentType.Entities + +- XmlDocumentType.Notations + + For example, the **XmlDocumentType.Entities** property gets the collection of **XmlEntity** nodes declared in the document type declaration. This collection is returned as an **XmlNamedNodeMap**, and you can iterate through the collection with the use of the **Count** property and display entity information. For an example of iterating through an **XmlNamedNodeMap**, see . + + The **XmlAttributeCollection** is derived from **XmlNamedNodeMap** and only attributes are modifiable, while notations and entities are read-only. Using the **XmlNamedNodeMap** for the attributes, you can get nodes for those attributes based on their XML names. This provides an easy method for manipulating the collection of attributes on an element node. This can be contrasted directly with **XmlNodeList**, which also implements the **IEnumerable** interface, but with an index accessor rather than a string. The **RemoveNamedItem** and **SetNamedItem** methods are only used against an **XmlAttributeCollection**. Adding or removing from an attribute collection, whether using the **AttributeCollection** or the **XmlNamedNodeMap** implementation, modifies the attribute collection on the element. The following code example shows how to move an attribute and create a new attribute. + +```vb +Imports System +Imports System.Xml + +Class test + + Public Shared Sub Main() + Dim doc As New XmlDocument() + doc.LoadXml(" text1 text2 ") + + ' Get the attributes of node "child2 " + Dim ac As XmlAttributeCollection = doc.DocumentElement.ChildNodes(1).Attributes + + ' Print out the number of attributes and their names. + Console.WriteLine(("Number of Attributes: " + ac.Count)) + Dim i As Integer + For i = 0 To ac.Count - 1 + Console.WriteLine((i + 1 + ". Attribute Name: '" + ac(i).Name + "' Attribute Value: '" + ac(i).Value + "'")) + Next i + ' Get the 'attr1' from child1. + Dim attr As XmlAttribute = doc.DocumentElement.ChildNodes(0).Attributes(0) + + ' Add this attribute to the attributecollection "ac". + ac.SetNamedItem(attr) + + ''attr1' will be removed from 'child1' and added to 'child2'. + ' Print out the number of attributes and their names. + Console.WriteLine(("Number of Attributes: " + ac.Count)) + + For i = 0 To ac.Count - 1 + Console.WriteLine((i + 1 + ". Attribute Name: '" + ac(i).Name + "' Attribute Value: '" + ac(i).Value + "'")) + Next i + ' Create a new attribute and add to the collection. + Dim attr2 As XmlAttribute = doc.CreateAttribute("attr4") + attr2.Value = "val4" + ac.SetNamedItem(attr2) + + ' Print out the number of attributes and their names. + Console.WriteLine(("Number of Attributes: " + ac.Count)) + + For i = 0 To ac.Count - 1 + Console.WriteLine((i + 1 + ". Attribute Name: '" + ac(i).Name + "' Attribute Value: '" + ac(i).Value + "'")) + Next i + End Sub 'Main +End Class 'test +``` + +```csharp +using System; +using System.Xml; +class test { + public static void Main() { + XmlDocument doc = new XmlDocument(); + doc.LoadXml( " text1 text2 " ); + + // Get the attributes of node "child2" + XmlAttributeCollection ac = doc.DocumentElement.ChildNodes[1].Attributes; + + // Print out the number of attributes and their names. + Console.WriteLine( "Number of Attributes: "+ac.Count ); + for( int i = 0; i < ac.Count; i++ ) Console.WriteLine( (i+1) + ". Attribute Name: '" +ac[i].Name+ "' Attribute Value: '"+ ac[i].Value +"'" ); - - // Get the 'attr1' from child1. - XmlAttribute attr = doc.DocumentElement.ChildNodes[0].Attributes[0]; - - // Add this attribute to the attributecollection "ac". - ac.SetNamedItem( attr ); - - // 'attr1' will be removed from 'child1' and added to 'child2'. - // Print out the number of attributes and their names. + + // Get the 'attr1' from child1. + XmlAttribute attr = doc.DocumentElement.ChildNodes[0].Attributes[0]; + + // Add this attribute to the attributecollection "ac". + ac.SetNamedItem( attr ); + + // 'attr1' will be removed from 'child1' and added to 'child2'. + // Print out the number of attributes and their names. Console.WriteLine( "Number of Attributes: "+ac.Count ); - for( int i = 0; i < ac.Count; i++ ) + for( int i = 0; i < ac.Count; i++ ) Console.WriteLine( (i+1) + ". Attribute Name: '" +ac[i].Name+ "' Attribute Value: '"+ ac[i].Value +"'" ); - - // Create a new attribute and add to the collection. - XmlAttribute attr2 = doc.CreateAttribute( "attr4" ); - attr2.Value = "val4"; - ac.SetNamedItem( attr2 ); - - // Print out the number of attributes and their names. + + // Create a new attribute and add to the collection. + XmlAttribute attr2 = doc.CreateAttribute( "attr4" ); + attr2.Value = "val4"; + ac.SetNamedItem( attr2 ); + + // Print out the number of attributes and their names. Console.WriteLine( "Number of Attributes: "+ac.Count ); - for( int i = 0; i < ac.Count; i++ ) + for( int i = 0; i < ac.Count; i++ ) Console.WriteLine( (i+1) + ". Attribute Name: '" +ac[i].Name+ "' Attribute Value: '"+ ac[i].Value +"'" ); - - } -} -``` - - To see an additional code example which shows an attribute being removed from an **AttributeCollection**, see [XmlNamedNodeMap.RemoveNamedItem Method](xref:System.Xml.XmlNamedNodeMap.RemoveNamedItem%2A). For more information on the methods and properties, see [XmlNamedNodeMap Members](xref:System.Xml.XmlNamedNodeMap). - + + } +} +``` + + To see an additional code example which shows an attribute being removed from an **AttributeCollection**, see [XmlNamedNodeMap.RemoveNamedItem Method](xref:System.Xml.XmlNamedNodeMap.RemoveNamedItem%2A). For more information on the methods and properties, see [XmlNamedNodeMap Members](xref:System.Xml.XmlNamedNodeMap). + ## See also - [XML Document Object Model (DOM)](xml-document-object-model-dom.md) diff --git a/docs/standard/data/xml/user-defined-functions-and-variables.md b/docs/standard/data/xml/user-defined-functions-and-variables.md index a08a11f474413..32570bd04197f 100644 --- a/docs/standard/data/xml/user-defined-functions-and-variables.md +++ b/docs/standard/data/xml/user-defined-functions-and-variables.md @@ -9,7 +9,7 @@ ms.assetid: 4772f20e-1e7f-496e-93c2-1484473be555 --- # User Defined Functions and Variables -The class provides a set of methods that are used to interact with data. You can supplement the standard XPath functions by implementing extension functions and variables for use by XPath query expressions. The method can accept a user defined context derived from . User defined functions are resolved by the custom context. +The class provides a set of methods that are used to interact with data. You can supplement the standard XPath functions by implementing extension functions and variables for use by XPath query expressions. The method can accept a user defined context derived from . User defined functions are resolved by the custom context. Extension functions and variables can be useful in prevention of XML injection attacks. In these scenarios user input is assigned to custom variables and processed by extension functions, not as raw input concatenated with processing instructions. Extension functions and variables contain user input so that it only acts on XML data as intended by the designer. @@ -29,7 +29,7 @@ The class provides a set of methods that [!code-csharp[XPathExtensionFunctions#3](../../../../samples/snippets/csharp/VS_Snippets_Data/xpathextensionfunctions/cs/xpathextensionfunctions.cs#3)] [!code-vb[XPathExtensionFunctions#3](../../../../samples/snippets/visualbasic/VS_Snippets_Data/xpathextensionfunctions/vb/xpathextensionfunctions.vb#3)] - The following code implements . This class resolves references to user-defined variables in XPath query expressions at runtime. An instance of this class is created and returned by the overridden method of the custom class. + The following code implements . This class resolves references to user-defined variables in XPath query expressions at runtime. An instance of this class is created and returned by the overridden method of the custom class. Code comments describe the class members. diff --git a/docs/standard/data/xml/using-the-xslcompiledtransform-class.md b/docs/standard/data/xml/using-the-xslcompiledtransform-class.md index 4b6c9e98d5c64..c1ab2e5885224 100644 --- a/docs/standard/data/xml/using-the-xslcompiledtransform-class.md +++ b/docs/standard/data/xml/using-the-xslcompiledtransform-class.md @@ -6,35 +6,35 @@ ms.assetid: f9b074f6-d6f4-49dd-a093-df510bf0cf7b --- # Using the XslCompiledTransform Class -The class is the Microsoft .NET Framework XSLT processor. This class is used to compile style sheets and execute XSLT transformations. - +The class is the Microsoft .NET Framework XSLT processor. This class is used to compile style sheets and execute XSLT transformations. + > [!NOTE] -> Although the overall performance of the class is better than the class, the method of the class might perform more slowly than the method of the class the first time it is called on a transformation. This is because the XSLT file must be compiled before it is loaded. For more information, see the following blog post: [XslCompiledTransform Slower than XslTransform?](/archive/blogs/antosha/xslcompiledtransform-slower-than-xsltransform) - -## In This Section - - [Inputs to the XslCompiledTransform Class](inputs-to-the-xslcompiledtransform-class.md) - Describes the available XSLT input options. - - [Output Options on the XslCompiledTransform Class](output-options-on-the-xslcompiledtransform-class.md) - Describes the available XSLT output options. - - [Resolving External Resources During XSLT Processing](resolving-external-resources-during-xslt-processing.md) - Discusses using the class to resolve external resources. - - [Extending XSLT Style Sheets](extending-xslt-style-sheets.md) - Discusses how XSLT extensions are supported. - -| Article | Description | -|-|-| -|[Recoverable XSLT Errors](recoverable-xslt-errors.md)|Lists discretionary behaviors allowed by the World Wide Web Consortium (W3C) XSLT 1.0 recommendation and describes how these behaviors are handled by the class.| -|[How to: Transform a Node Fragment](how-to-transform-a-node-fragment.md)|Describes how to transform a node fragment.| - -## Related Sections - - [Migrating From the XslTransform Class](migrating-from-the-xsltransform-class.md) - Discusses how to migrate code from the class - +> Although the overall performance of the class is better than the class, the method of the class might perform more slowly than the method of the class the first time it is called on a transformation. This is because the XSLT file must be compiled before it is loaded. For more information, see the following blog post: [XslCompiledTransform Slower than XslTransform?](/archive/blogs/antosha/xslcompiledtransform-slower-than-xsltransform) + +## In This Section + + [Inputs to the XslCompiledTransform Class](inputs-to-the-xslcompiledtransform-class.md) + Describes the available XSLT input options. + + [Output Options on the XslCompiledTransform Class](output-options-on-the-xslcompiledtransform-class.md) + Describes the available XSLT output options. + + [Resolving External Resources During XSLT Processing](resolving-external-resources-during-xslt-processing.md) + Discusses using the class to resolve external resources. + + [Extending XSLT Style Sheets](extending-xslt-style-sheets.md) + Discusses how XSLT extensions are supported. + +| Article | Description | +|-|-| +|[Recoverable XSLT Errors](recoverable-xslt-errors.md)|Lists discretionary behaviors allowed by the World Wide Web Consortium (W3C) XSLT 1.0 recommendation and describes how these behaviors are handled by the class.| +|[How to: Transform a Node Fragment](how-to-transform-a-node-fragment.md)|Describes how to transform a node fragment.| + +## Related Sections + + [Migrating From the XslTransform Class](migrating-from-the-xsltransform-class.md) + Discusses how to migrate code from the class + ## See also - diff --git a/docs/standard/data/xml/validating-an-xml-document-in-the-dom.md b/docs/standard/data/xml/validating-an-xml-document-in-the-dom.md index aa605810aa610..20169c41314cd 100644 --- a/docs/standard/data/xml/validating-an-xml-document-in-the-dom.md +++ b/docs/standard/data/xml/validating-an-xml-document-in-the-dom.md @@ -10,11 +10,11 @@ dev_langs: The class does not validate the XML in the Document Object Model (DOM) against an XML Schema definition language (XSD) schema or document type definition (DTD) by default; the XML is only verified to be well-formed. -To validate the XML in the DOM, you can validate the XML as it is loaded into the DOM by passing a schema-validating to the method of the class, or validate a previously unvalidated XML document in the DOM using the method of the class. +To validate the XML in the DOM, you can validate the XML as it is loaded into the DOM by passing a schema-validating to the method of the class, or validate a previously unvalidated XML document in the DOM using the method of the class. ## Validating an XML Document As It Is Loaded into the DOM -The class validates the XML data as it is loaded into the DOM when a validating is passed to the method of the class. +The class validates the XML data as it is loaded into the DOM when a validating is passed to the method of the class. After successful validation, schema defaults are applied, text values are converted to atomic values as necessary, and type information is associated with validated information items. As a result, typed XML data replaces previously untyped XML data. @@ -24,13 +24,13 @@ To create an XML schema-validating , follow these ste 1. Construct a new instance. -2. Add an XML schema to the property of the instance. +2. Add an XML schema to the property of the instance. -3. Specify `Schema` as the . +3. Specify `Schema` as the . -4. Optionally specify and a to handle schema validation errors and warnings encountered during validation. +4. Optionally specify and a to handle schema validation errors and warnings encountered during validation. -5. Finally, pass the object to the method of the class along with the XML document, creating a schema-validating . +5. Finally, pass the object to the method of the class along with the XML document, creating a schema-validating . ### Example @@ -48,15 +48,15 @@ The example also takes the `contosoBooks.xsd` file as input. Consider the following when validating XML data as it is loaded into the DOM. -- In the above example, the is called whenever an invalid type is encountered. If a is not set on the validating ,an is thrown when is called if any attribute or element type does not match the corresponding type specified in the validating schema. +- In the above example, the is called whenever an invalid type is encountered. If a is not set on the validating ,an is thrown when is called if any attribute or element type does not match the corresponding type specified in the validating schema. - When an XML document is loaded into an object with an associated schema that defines default values, the treats these defaults as if they appeared in the XML document. This means that the property always returns `false` for an element that was defaulted from the schema. Even if in the XML document, it was written as an empty element. ## Validating an XML Document in the DOM -The method of the class validates the XML data loaded in the DOM against the schemas in the object's property. After successful validation, schema defaults are applied, text values are converted to atomic values as necessary, and type information is associated with validated information items. As a result, typed XML data replaces previously untyped XML data. +The method of the class validates the XML data loaded in the DOM against the schemas in the object's property. After successful validation, schema defaults are applied, text values are converted to atomic values as necessary, and type information is associated with validated information items. As a result, typed XML data replaces previously untyped XML data. -The example below is similar to the example in "Validating an XML Document As It Is Loaded into the DOM" above. In this example, the XML document is not validated as it is loaded into the DOM, but rather is validated after it has been loaded into the DOM using the method of the class. The method validates the XML document against the XML schemas contained in the property of the . Invalid modifications are then made to the XML document, and the document is then revalidated, causing schema validation errors. Finally, one of the errors is corrected, and then part of the XML document is partially validated. +The example below is similar to the example in "Validating an XML Document As It Is Loaded into the DOM" above. In this example, the XML document is not validated as it is loaded into the DOM, but rather is validated after it has been loaded into the DOM using the method of the class. The method validates the XML document against the XML schemas contained in the property of the . Invalid modifications are then made to the XML document, and the document is then revalidated, causing schema validation errors. Finally, one of the errors is corrected, and then part of the XML document is partially validated. [!code-csharp[XmlDocumentValidation.Validate#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlDocumentValidation.Validate/CS/XmlDocumentValidationExample.cs#1)] [!code-vb[XmlDocumentValidation.Validate#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XmlDocumentValidation.Validate/VB/XmlDocumentValidationExample.vb#1)] @@ -67,7 +67,7 @@ The example takes as input the `contosoBooks.xml` and `contosoBooks.xsd` files r XML schema validation errors are reported when validating XML data loaded in the DOM. You are notified about all schema validation errors found while validating the XML data as it is being loaded, or when validating a previously unvalidated XML document. -Validation errors are handled by the . If a was assigned to the instance, or passed to the method of the class, the will handle schema validation errors; otherwise an is raised when a schema validation error is encountered. +Validation errors are handled by the . If a was assigned to the instance, or passed to the method of the class, the will handle schema validation errors; otherwise an is raised when a schema validation error is encountered. > [!NOTE] > The XML data is loaded into the DOM despite schema validation errors unless your raises an exception to stop the process. diff --git a/docs/standard/data/xml/xdr-validation-with-xmlschemacollection.md b/docs/standard/data/xml/xdr-validation-with-xmlschemacollection.md index 5b6319f2b72eb..2afa90d6d4521 100644 --- a/docs/standard/data/xml/xdr-validation-with-xmlschemacollection.md +++ b/docs/standard/data/xml/xdr-validation-with-xmlschemacollection.md @@ -2,7 +2,7 @@ description: "Learn more about: XDR Validation with XmlSchemaCollection" title: "XDR Validation with XmlSchemaCollection" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 00833027-1428-4586-83c1-42f5de3323d1 @@ -150,5 +150,5 @@ The following outlines the contents of the XDR schema file, *HeadCount.xdr*, to ## See also -- +- - [XmlSchemaCollection Schema Compilation](xmlschemacollection-schema-compilation.md) diff --git a/docs/standard/data/xml/xml-processing-options.md b/docs/standard/data/xml/xml-processing-options.md index 0b216ca029358..bd9ca24cdd38c 100644 --- a/docs/standard/data/xml/xml-processing-options.md +++ b/docs/standard/data/xml/xml-processing-options.md @@ -6,26 +6,26 @@ ms.topic: reference --- # XML Processing Options -See the following tables for a list of Microsoft technologies you can use to process XML data. - -## .NET Framework Options - -|**Option**|**Processing type**|**Description**| -|----------------|-------------------------|---------------------| -|[LINQ to XML (C#)](../../linq/linq-xml-overview.md)
[LINQ to XML (Visual Basic)](../../linq/linq-xml-overview.md)
( namespace)|In-memory|- Based on the .NET Framework Language-Integrated Query (LINQ) technology.
- Provides query experience that is similar to SQL for objects, relational data, and XML data.
- Provides intuitive document creation and transformation capabilities.
- Use this option if you're writing new code.| -||Stream-based|- Provides a fast, non-cached, forward-only way to access XML data.
- You can create objects by using the method, and specify the set of features to enable on the object by using the class.| -||Stream-based|- Provides a fast, non-cached, forward-only way to generate XML data.
- You can create objects by using the method, and specify the set of features to enable on the object by using the class.| -||In-memory|- Implements the [W3C Document Object Model (DOM) Level 1 Core](https://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html) and [DOM Level 2 Core](https://www.w3.org/TR/DOM-Level-2-Core/) recommendations.
- You can create, insert, remove, and modify nodes by using methods and properties based on the familiar DOM model.
- Use this option if you're modifying existing code that utilizes the W3C DOM.| -||In-memory|- Offers several editing options and navigation capabilities using a cursor model.
- XML documents can be contained in an or object.
- Provides excellent performance for read-only processing of XML.
- Use this option if you're modifying existing code with XPath queries or XSLT transformations.| -||In-memory|- Provides options for transforming XML data using XSL transformations.
- The [XSLT Compiler (xsltc.exe)](xslt-compiler-xsltc-exe.md) lets you reference pre-compiled transformations in your app.| - -## Win32 and COM-based Options - -|**Option**|**Description**| -|----------------|---------------------| -|[XmlLite](/previous-versions/windows/desktop/ms752872(v=vs.85))|- A fast, secure, non-caching, forward-only XML parser that helps you build high-performance XML apps.
- Works with any language that can use dynamic link libraries (DLLs); we recommend using C++.| -|[MSXML](/previous-versions/windows/desktop/ms763742(v=vs.85))|- COM-based technology for processing XML that is included with the Windows operating system.
- Provides a native implementation of the DOM with support for XPath and XSLT.
- Contains the SAX2 event-based parser.| - +See the following tables for a list of Microsoft technologies you can use to process XML data. + +## .NET Framework Options + +|**Option**|**Processing type**|**Description**| +|----------------|-------------------------|---------------------| +|[LINQ to XML (C#)](../../linq/linq-xml-overview.md)
[LINQ to XML (Visual Basic)](../../linq/linq-xml-overview.md)
( namespace)|In-memory|- Based on the .NET Framework Language-Integrated Query (LINQ) technology.
- Provides query experience that is similar to SQL for objects, relational data, and XML data.
- Provides intuitive document creation and transformation capabilities.
- Use this option if you're writing new code.| +||Stream-based|- Provides a fast, non-cached, forward-only way to access XML data.
- You can create objects by using the method, and specify the set of features to enable on the object by using the class.| +||Stream-based|- Provides a fast, non-cached, forward-only way to generate XML data.
- You can create objects by using the method, and specify the set of features to enable on the object by using the class.| +||In-memory|- Implements the [W3C Document Object Model (DOM) Level 1 Core](https://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html) and [DOM Level 2 Core](https://www.w3.org/TR/DOM-Level-2-Core/) recommendations.
- You can create, insert, remove, and modify nodes by using methods and properties based on the familiar DOM model.
- Use this option if you're modifying existing code that utilizes the W3C DOM.| +||In-memory|- Offers several editing options and navigation capabilities using a cursor model.
- XML documents can be contained in an or object.
- Provides excellent performance for read-only processing of XML.
- Use this option if you're modifying existing code with XPath queries or XSLT transformations.| +||In-memory|- Provides options for transforming XML data using XSL transformations.
- The [XSLT Compiler (xsltc.exe)](xslt-compiler-xsltc-exe.md) lets you reference pre-compiled transformations in your app.| + +## Win32 and COM-based Options + +|**Option**|**Description**| +|----------------|---------------------| +|[XmlLite](/previous-versions/windows/desktop/ms752872(v=vs.85))|- A fast, secure, non-caching, forward-only XML parser that helps you build high-performance XML apps.
- Works with any language that can use dynamic link libraries (DLLs); we recommend using C++.| +|[MSXML](/previous-versions/windows/desktop/ms763742(v=vs.85))|- COM-based technology for processing XML that is included with the Windows operating system.
- Provides a native implementation of the DOM with support for XPath and XSLT.
- Contains the SAX2 event-based parser.| + ## See also - [Process XML Data Using the DOM Model](process-xml-data-using-the-dom-model.md) diff --git a/docs/standard/data/xml/xml-schema-object-model-overview.md b/docs/standard/data/xml/xml-schema-object-model-overview.md index 5d7f5e2345492..adefc97f6f26a 100644 --- a/docs/standard/data/xml/xml-schema-object-model-overview.md +++ b/docs/standard/data/xml/xml-schema-object-model-overview.md @@ -6,32 +6,32 @@ ms.assetid: 896a1e12-5655-42c6-8cdd-89c12862b34b --- # XML Schema Object Model Overview -The Schema Object Model (SOM) in the Microsoft .NET Framework is a rich API that allows you to create, edit, and validate schemas programmatically. The SOM operates on XML schema documents similarly to the way the Document Object Model (DOM) operates on XML documents. XML schema documents are valid XML files that, once loaded into the SOM, convey meaning about the structure and validity of other XML documents which conform to the schema. - - A schema is an XML document that defines a class of XML documents by specifying the structure or model of XML documents for a particular schema. A schema identifies the constraints on the content of the XML documents, and describes the vocabulary (rules or grammar) that compliant XML documents must follow in order to be considered schema-valid with that particular schema. Validation of an XML document is the process that ensures that the document conforms to the grammar specified by the schema. - - The following are ways the SOM API in the .NET Framework enables you to create, edit, and validate schemas. - -- Load and save valid schemas to and from files. - -- Create in-memory schemas using strongly typed classes. - -- Interact with the class to cache, compile, and retrieve schemas. - -- Interact with the method of the class to validate XML instance documents against schemas. - -- Build editors for creating and maintaining schemas. - -- Dynamically edit a schema that can be complied and saved for use in the validation of XML instance documents. - -## The Schema Object Model - - The SOM consists of an extensive set of classes in the namespace corresponding to the elements in an XML schema. For example, the `...` element maps to the class, and all the information that can be contained within an `` element can be represented using the class. Similarly, the `...` and `...` elements map to the and classes respectively. This mapping continues for all the elements of an XML schema creating an XML schema object model in the namespace illustrated in the diagram that follows. - - ![System.Xml.Schema Object Model](./media/xml-schema-object-model-overview/xml-schema-object-model.gif) - - For more information about each class in the namespace, see the namespace reference documentation in the .NET Framework class library. - +The Schema Object Model (SOM) in the Microsoft .NET Framework is a rich API that allows you to create, edit, and validate schemas programmatically. The SOM operates on XML schema documents similarly to the way the Document Object Model (DOM) operates on XML documents. XML schema documents are valid XML files that, once loaded into the SOM, convey meaning about the structure and validity of other XML documents which conform to the schema. + + A schema is an XML document that defines a class of XML documents by specifying the structure or model of XML documents for a particular schema. A schema identifies the constraints on the content of the XML documents, and describes the vocabulary (rules or grammar) that compliant XML documents must follow in order to be considered schema-valid with that particular schema. Validation of an XML document is the process that ensures that the document conforms to the grammar specified by the schema. + + The following are ways the SOM API in the .NET Framework enables you to create, edit, and validate schemas. + +- Load and save valid schemas to and from files. + +- Create in-memory schemas using strongly typed classes. + +- Interact with the class to cache, compile, and retrieve schemas. + +- Interact with the method of the class to validate XML instance documents against schemas. + +- Build editors for creating and maintaining schemas. + +- Dynamically edit a schema that can be complied and saved for use in the validation of XML instance documents. + +## The Schema Object Model + + The SOM consists of an extensive set of classes in the namespace corresponding to the elements in an XML schema. For example, the `...` element maps to the class, and all the information that can be contained within an `` element can be represented using the class. Similarly, the `...` and `...` elements map to the and classes respectively. This mapping continues for all the elements of an XML schema creating an XML schema object model in the namespace illustrated in the diagram that follows. + + ![System.Xml.Schema Object Model](./media/xml-schema-object-model-overview/xml-schema-object-model.gif) + + For more information about each class in the namespace, see the namespace reference documentation in the .NET Framework class library. + ## See also - [Reading and Writing XML Schemas](reading-and-writing-xml-schemas.md) diff --git a/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemacollection.md b/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemacollection.md index c4b68493ea706..83a0134510b1c 100644 --- a/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemacollection.md +++ b/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemacollection.md @@ -2,208 +2,208 @@ description: "Learn more about: XML Schema (XSD) Validation with XmlSchemaCollection" title: "XML Schema (XSD) Validation with XmlSchemaCollection" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: ad0b5717-3d32-41ad-a4d7-072c3e492b82 --- # XML Schema (XSD) Validation with XmlSchemaCollection -You can use the to validate an XML document against XML Schema definition language (XSD) schemas. The improves performance by storing schemas in the collection so they are not loaded into memory each time validation occurs. If the schema exists in the schema collection, the `schemaLocation` attribute is used to look up the schema in the collection. - +You can use the to validate an XML document against XML Schema definition language (XSD) schemas. The improves performance by storing schemas in the collection so they are not loaded into memory each time validation occurs. If the schema exists in the schema collection, the `schemaLocation` attribute is used to look up the schema in the collection. + > [!IMPORTANT] -> The class is now obsolete and has been replaced with the class. For more information about the class see, [XmlSchemaSet for Schema Compilation](xmlschemaset-for-schema-compilation.md). - - The following example shows the root element of a data file. - -```xml - -``` - - For this example, the value of the `targetNamespace` attribute is `urn:bookstore-schema`, which is the same namespace that is used when adding the schema to the . - - The following code example adds an XML Schema to the . - -```vb -Dim xsc As New XmlSchemaCollection() -' XML Schema. +> The class is now obsolete and has been replaced with the class. For more information about the class see, [XmlSchemaSet for Schema Compilation](xmlschemaset-for-schema-compilation.md). + + The following example shows the root element of a data file. + +```xml + +``` + + For this example, the value of the `targetNamespace` attribute is `urn:bookstore-schema`, which is the same namespace that is used when adding the schema to the . + + The following code example adds an XML Schema to the . + +```vb +Dim xsc As New XmlSchemaCollection() +' XML Schema. xsc.Add("urn:bookstore-schema", schema) -reader = New XmlTextReader(filename) -vreader = New XmlValidatingReader(reader) -vreader.Schemas.Add(xsc) -``` - -```csharp -XmlSchemaCollection xsc = new XmlSchemaCollection(); -// XML Schema. -xsc.Add("urn:bookstore-schema", schema); -reader = new XmlTextReader (filename); -vreader = new XmlValidatingReader (reader); -vreader.Schemas.Add(xsc); -``` - - The `targetNamespace` attribute is generally used when you add the `namespaceURI` property in the method for the . You can specify a null reference before adding the schema to the . An empty string ("") should be used for schemas without a namespace. The can have only one schema without a namespace. - - The following code example adds an XML Schema, HeadCount.xsd, to the and validates HeadCount.xml. - -```vb -Imports System -Imports System.IO -Imports System.Xml -Imports System.Xml.Schema - -Namespace ValidationSample - - Class Sample - - Public Shared Sub Main() - Dim tr As New XmlTextReader("HeadCount.xml") - Dim vr As New XmlValidatingReader(tr) - - vr.Schemas.Add("xsdHeadCount", "HeadCount.xsd") - vr.ValidationType = ValidationType.Schema - AddHandler vr.ValidationEventHandler, AddressOf ValidationHandler - - While vr.Read() - End While - Console.WriteLine("Validation finished") - End Sub - ' Main - - Public Shared Sub ValidationHandler(sender As Object, args As ValidationEventArgs) - Console.WriteLine("***Validation error") - Console.WriteLine("Severity:{0}", args.Severity) - Console.WriteLine("Message:{0}", args.Message) - End Sub - ' ValidationHandler - End Class - ' Sample -End Namespace -' ValidationSample -``` - -```csharp -using System; -using System.IO; -using System.Xml; -using System.Xml.Schema; - -namespace ValidationSample -{ - class Sample - { - public static void Main() - { - XmlTextReader tr = new XmlTextReader("HeadCount.xml"); - XmlValidatingReader vr = new XmlValidatingReader(tr); - - vr.Schemas.Add("xsdHeadCount", "HeadCount.xsd"); - vr.ValidationType = ValidationType.Schema; - vr.ValidationEventHandler += new ValidationEventHandler (ValidationHandler); - - while(vr.Read()); - Console.WriteLine("Validation finished"); - } - - public static void ValidationHandler(object sender, ValidationEventArgs args) - { - Console.WriteLine("***Validation error"); - Console.WriteLine("\tSeverity:{0}", args.Severity); - Console.WriteLine("\tMessage :{0}", args.Message); - } - } -} -``` - - The following outlines the contents of the input file, HeadCount.xml, to be validated. - -```xml - - - Waldo Pepper - Red Pepper - -``` - - The following outlines the contents of the XML Schema file, HeadCount.xsd, to be validated against. - -```xml - - - - - - - - - -``` - - The following code example creates an that takes an . The input file, sample4.xml, is validated against the XML Schema, sample4.xsd. - -```vb -Dim tr As New XmlTextReader("sample4.xml") -Dim vr As New XmlValidatingReader(tr) -vr.ValidationType = ValidationType.Schema -vr.Schemas.Add("datatypesTest", "sample4.xsd") -AddHandler vr.ValidationEventHandler, AddressOf ValidationCallBack -While vr.Read() - Console.WriteLine("NodeType: {0} NodeName: {1}", vr.NodeType, vr.Name) -End While -``` - -```csharp -XmlTextReader tr = new XmlTextReader("sample4.xml"); -XmlValidatingReader vr = new XmlValidatingReader(tr); -vr.ValidationType = ValidationType.Schema; - vr.Schemas.Add("datatypesTest", "sample4.xsd"); -vr.ValidationEventHandler += new ValidationEventHandler(ValidationCallBack); -while(vr.Read()) { - Console.WriteLine("NodeType: {0} NodeName: {1}", vr.NodeType, vr.Name); - } -``` - - The following outlines the contents of the input file, sample4.xml, to be validated. - -```xml - - - 123 - - -``` - - The following outlines the contents of the XML Schema file, sample4.xsd, to be validated against. - -```xml +reader = New XmlTextReader(filename) +vreader = New XmlValidatingReader(reader) +vreader.Schemas.Add(xsc) +``` + +```csharp +XmlSchemaCollection xsc = new XmlSchemaCollection(); +// XML Schema. +xsc.Add("urn:bookstore-schema", schema); +reader = new XmlTextReader (filename); +vreader = new XmlValidatingReader (reader); +vreader.Schemas.Add(xsc); +``` + + The `targetNamespace` attribute is generally used when you add the `namespaceURI` property in the method for the . You can specify a null reference before adding the schema to the . An empty string ("") should be used for schemas without a namespace. The can have only one schema without a namespace. + + The following code example adds an XML Schema, HeadCount.xsd, to the and validates HeadCount.xml. + +```vb +Imports System +Imports System.IO +Imports System.Xml +Imports System.Xml.Schema + +Namespace ValidationSample + + Class Sample + + Public Shared Sub Main() + Dim tr As New XmlTextReader("HeadCount.xml") + Dim vr As New XmlValidatingReader(tr) + + vr.Schemas.Add("xsdHeadCount", "HeadCount.xsd") + vr.ValidationType = ValidationType.Schema + AddHandler vr.ValidationEventHandler, AddressOf ValidationHandler + + While vr.Read() + End While + Console.WriteLine("Validation finished") + End Sub + ' Main + + Public Shared Sub ValidationHandler(sender As Object, args As ValidationEventArgs) + Console.WriteLine("***Validation error") + Console.WriteLine("Severity:{0}", args.Severity) + Console.WriteLine("Message:{0}", args.Message) + End Sub + ' ValidationHandler + End Class + ' Sample +End Namespace +' ValidationSample +``` + +```csharp +using System; +using System.IO; +using System.Xml; +using System.Xml.Schema; + +namespace ValidationSample +{ + class Sample + { + public static void Main() + { + XmlTextReader tr = new XmlTextReader("HeadCount.xml"); + XmlValidatingReader vr = new XmlValidatingReader(tr); + + vr.Schemas.Add("xsdHeadCount", "HeadCount.xsd"); + vr.ValidationType = ValidationType.Schema; + vr.ValidationEventHandler += new ValidationEventHandler (ValidationHandler); + + while(vr.Read()); + Console.WriteLine("Validation finished"); + } + + public static void ValidationHandler(object sender, ValidationEventArgs args) + { + Console.WriteLine("***Validation error"); + Console.WriteLine("\tSeverity:{0}", args.Severity); + Console.WriteLine("\tMessage :{0}", args.Message); + } + } +} +``` + + The following outlines the contents of the input file, HeadCount.xml, to be validated. + +```xml + + + Waldo Pepper + Red Pepper + +``` + + The following outlines the contents of the XML Schema file, HeadCount.xsd, to be validated against. + +```xml + + + + + + + + + +``` + + The following code example creates an that takes an . The input file, sample4.xml, is validated against the XML Schema, sample4.xsd. + +```vb +Dim tr As New XmlTextReader("sample4.xml") +Dim vr As New XmlValidatingReader(tr) +vr.ValidationType = ValidationType.Schema +vr.Schemas.Add("datatypesTest", "sample4.xsd") +AddHandler vr.ValidationEventHandler, AddressOf ValidationCallBack +While vr.Read() + Console.WriteLine("NodeType: {0} NodeName: {1}", vr.NodeType, vr.Name) +End While +``` + +```csharp +XmlTextReader tr = new XmlTextReader("sample4.xml"); +XmlValidatingReader vr = new XmlValidatingReader(tr); +vr.ValidationType = ValidationType.Schema; + vr.Schemas.Add("datatypesTest", "sample4.xsd"); +vr.ValidationEventHandler += new ValidationEventHandler(ValidationCallBack); +while(vr.Read()) { + Console.WriteLine("NodeType: {0} NodeName: {1}", vr.NodeType, vr.Name); + } +``` + + The following outlines the contents of the input file, sample4.xml, to be validated. + +```xml + + + 123 + + +``` + + The following outlines the contents of the XML Schema file, sample4.xsd, to be validated against. + +```xml - - - - - - - - - - - - - - - -``` - + targetNamespace="datatypesTest" + elementFormDefault="qualified"> + + + + + + + + + + + + + + + +``` + ## See also - - -- +- - [XmlSchemaCollection Schema Compilation](xmlschemacollection-schema-compilation.md) diff --git a/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemaset.md b/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemaset.md index 79a803b78bdb4..f24876ec32d77 100644 --- a/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemaset.md +++ b/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemaset.md @@ -12,12 +12,12 @@ XML documents can be validated against an XML schema definition language (XSD) s ## Validate XML documents - XML documents are validated by the method of the class. To validate an XML document, construct an object that contains an XML schema definition language (XSD) schema with which to validate the XML document. + XML documents are validated by the method of the class. To validate an XML document, construct an object that contains an XML schema definition language (XSD) schema with which to validate the XML document. > [!NOTE] > The namespace contains extension methods that make it easy to validate an XML tree against an XSD file when using [LINQ to XML (C#)](../../linq/linq-xml-overview.md) and [LINQ to XML (Visual Basic)](../../linq/linq-xml-overview.md). For more information on validating XML documents with LINQ to XML, see [How to validate using XSD (LINQ to XML) (C#)](../../linq/validate-xsd.md) and [How to: Validate Using XSD (LINQ to XML) (Visual Basic)](../../linq/validate-xsd.md). - An individual schema or a set of schemas (as an ) can be added to an by passing either one as a parameter to the method of . When validating a document the target namespace of the document must match the target namespace of the schema in the schema set. + An individual schema or a set of schemas (as an ) can be added to an by passing either one as a parameter to the method of . When validating a document the target namespace of the document must match the target namespace of the schema in the schema set. The following is an example XML document. @@ -27,9 +27,9 @@ XML documents can be validated against an XML schema definition language (XSD) s [!code-xml[XSDInference Examples #6](../../../../samples/snippets/xml/VS_Snippets_Data/XSDInference Examples/XML/contosoBooks.xsd#6)] - In the code example that follows, the schema above is added to the property of the object. The object is passed as a parameter to the method of the object, which validates the XML document above. + In the code example that follows, the schema above is added to the property of the object. The object is passed as a parameter to the method of the object, which validates the XML document above. - The property of the object is set to `Schema` to enforce validation of the XML document by the method of the object. A is added to the object to handle any or events raised by errors found during the validation process of both the XML document and the schema. + The property of the object is set to `Schema` to enforce validation of the XML document by the method of the object. A is added to the object to handle any or events raised by errors found during the validation process of both the XML document and the schema. [!code-csharp[XmlSchemaSetOverall Example #1](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaSetOverall Example/CS/xmlschemasetexample.cs#1)] [!code-vb[XmlSchemaSetOverall Example #1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XmlSchemaSetOverall Example/VB/xmlschemasetexample.vb#1)] diff --git a/docs/standard/data/xml/xml-type-support-implementation-notes.md b/docs/standard/data/xml/xml-type-support-implementation-notes.md index 5a9f8774ade51..0264f58c0af93 100644 --- a/docs/standard/data/xml/xml-type-support-implementation-notes.md +++ b/docs/standard/data/xml/xml-type-support-implementation-notes.md @@ -6,46 +6,46 @@ ms.assetid: 26b071f3-1261-47ef-8690-0717f5cd93c1 --- # XML Type Support Implementation Notes -This topic describes some implementation details that you want to be aware of. - -## List Mappings - - The , , , **Type[]**, and types are used to represent XML Schema definition language (XSD) list types. - -## Union Mappings - - Union types are represented using the or type. The source type or the destination type must therefore always be either or . - - If the object represents a list type the object converts the input string value to a list of one or more objects. If the represents a union type then an attempt is made to parse the input value as a member type of the union. If the parse attempt fails then the conversion is attempted with the next member of the union and so on until the conversion is successful, or there are no other member types to try, in which case an exception is thrown. - -## Differences Between CLR and XML Data Types - - The following describes certain mismatches that can occur between CLR types and XML data types and how they are handled. - +This topic describes some implementation details that you want to be aware of. + +## List Mappings + + The , , , **Type[]**, and types are used to represent XML Schema definition language (XSD) list types. + +## Union Mappings + + Union types are represented using the or type. The source type or the destination type must therefore always be either or . + + If the object represents a list type the object converts the input string value to a list of one or more objects. If the represents a union type then an attempt is made to parse the input value as a member type of the union. If the parse attempt fails then the conversion is attempted with the next member of the union and so on until the conversion is successful, or there are no other member types to try, in which case an exception is thrown. + +## Differences Between CLR and XML Data Types + + The following describes certain mismatches that can occur between CLR types and XML data types and how they are handled. + > [!NOTE] > The `xs` prefix is mapped to the and namespace URI. - -### System.TimeSpan and xs:duration - The `xs:duration` type is partially ordered in that there are certain duration values that are different but equivalent. This means that for the `xs:duration` type value such as 1 month (P1M) is less than 32 days (P32D), larger than 27 days (P27D) and equivalent to 28, 29 or 30 days. - - The class does not support this partial ordering. Instead, it picks a specific number of days for 1 year and 1 month; 365 days and 30 days respectively. - +### System.TimeSpan and xs:duration + + The `xs:duration` type is partially ordered in that there are certain duration values that are different but equivalent. This means that for the `xs:duration` type value such as 1 month (P1M) is less than 32 days (P32D), larger than 27 days (P27D) and equivalent to 28, 29 or 30 days. + + The class does not support this partial ordering. Instead, it picks a specific number of days for 1 year and 1 month; 365 days and 30 days respectively. + For more information on the `xs:duration` type, see the W3C [XML Schema Part 2: Datatypes Recommendation](https://www.w3.org/TR/xmlschema-2/). - -### xs:time, Gregorian Date Types, and System.DateTime - When an `xs:time` value is mapped to a object, the field is used to initialize the date properties of the object (such as , , and ) to the smallest possible value. - - Similarly, instances of `xs:gMonth`, `xs:gDay`, `xs:gYear`, `xs:gYearMonth` and `xs:gMonthDay` are also mapped to a object. Unused properties on the object are initialized to those from . - +### xs:time, Gregorian Date Types, and System.DateTime + + When an `xs:time` value is mapped to a object, the field is used to initialize the date properties of the object (such as , , and ) to the smallest possible value. + + Similarly, instances of `xs:gMonth`, `xs:gDay`, `xs:gYear`, `xs:gYearMonth` and `xs:gMonthDay` are also mapped to a object. Unused properties on the object are initialized to those from . + > [!NOTE] -> You cannot rely on the value when the content is typed as `xs:gMonthDay`. The value is always set to 1904 in this case. - -### xs:anyURI and System.Uri +> You cannot rely on the value when the content is typed as `xs:gMonthDay`. The value is always set to 1904 in this case. + +### xs:anyURI and System.Uri + + When an instance of `xs:anyURI` that represents a relative URI is mapped to a , the object does not have a base URI. - When an instance of `xs:anyURI` that represents a relative URI is mapped to a , the object does not have a base URI. - ## See also - [Type Support in the System.Xml Classes](type-support-in-the-system-xml-classes.md) diff --git a/docs/standard/data/xml/xmlschemaset-for-schema-compilation.md b/docs/standard/data/xml/xmlschemaset-for-schema-compilation.md index 18a86d8bb2a25..d10d5099404de 100644 --- a/docs/standard/data/xml/xmlschemaset-for-schema-compilation.md +++ b/docs/standard/data/xml/xmlschemaset-for-schema-compilation.md @@ -2,265 +2,265 @@ description: "Learn more about: XmlSchemaSet for Schema Compilation" title: "XmlSchemaSet for Schema Compilation" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 55c4b175-3170-4071-9d60-dd5a42f79b54 --- # XmlSchemaSet for Schema Compilation -Describes the , a cache where XML Schema definition language (XSD) schemas can be stored and validated. - -## The XmlSchemaSet Class - - The is a cache where XML Schema definition language (XSD) schemas can be stored and validated. - - In version 1.0, XML schemas were loaded into an class as a library of schemas. In version 2.0, the and the classes are obsolete, and have been replaced by the methods, and the class respectively. - - The has been introduced to fix a number of issues including standards compatibility, performance, and the obsolete Microsoft XML-Data Reduced (XDR) schema format. - - The following is a comparison between the class and the class. - -|XmlSchemaCollection|XmlSchemaSet| -|-------------------------|------------------| -|Supports Microsoft XDR and W3C XML schemas.|Only supports W3C XML schemas.| -|Schemas are compiled when the method is called.|Schemas are not compiled when the method is called. This provides a performance improvement during creation of the schema library.| -|Each schema generates an individual compiled version that can result in "schema islands." As a result, all includes and imports are scoped only within that schema.|Compiled schemas generate a single logical schema, a "set" of schemas. Any imported schemas within a schema that are added to the set are directly added to the set themselves. This means that all types are available to all schemas.| -|Only one schema for a particular target namespace can exist in the collection.|Multiple schemas for the same target namespace can be added as long as there are no type conflicts.| - -## Migrating to the XmlSchemaSet - - The following code example provides a guide to migrating to the new class from the obsolete class. The code example illustrates the following major differences between the two classes. - -- Unlike the method of the class, schemas are not compiled when calling the method of the . The method of the is explicitly called in the example code. - -- To iterate over an , you must use the property of the . - - The following is the obsolete code example. - -```vb -Dim schemaCollection As XmlSchemaCollection = New XmlSchemaCollection() -schemaCollection.Add("http://www.contoso.com/retail", "http://www.contoso.com/retail.xsd") -schemaCollection.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd") - -Dim schema As XmlSchema - -For Each schema in schemaCollection - - Console.WriteLine(schema.TargetNamespace) - -Next -``` - -```csharp -XmlSchemaCollection schemaCollection = new XmlSchemaCollection(); -schemaCollection.Add("http://www.contoso.com/retail", "http://www.contoso.com/retail.xsd"); -schemaCollection.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd"); - -foreach(XmlSchema schema in schemaCollection) -{ - Console.WriteLine(schema.TargetNamespace); -} -``` - - The following is the equivalent code example. - -```vb -Dim schemaSet As XmlSchemaSet = New XmlSchemaSet() -schemaSet.Add("http://www.contoso.com/retail", "http://www.contoso.com/retail.xsd") -schemaSet.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd") -schemaSet.Compile() - -Dim schema As XmlSchema - -For Each schema in schemaSet.Schemas() - - Console.WriteLine(schema.TargetNamespace) - -Next -``` - -```csharp -XmlSchemaSet schemaSet = new XmlSchemaSet(); -schemaSet.Add("http://www.contoso.com/retail", "http://www.contoso.com/retail.xsd"); -schemaSet.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd"); -schemaSet.Compile(); - -foreach(XmlSchema schema in schemaSet.Schemas()) -{ - Console.WriteLine(schema.TargetNamespace); -} -``` - -## Adding and Retrieving Schemas - - Schemas are added to an using the method of the . When a schema is added to an , it is associated with a target namespace URI. The target namespace URI can either be specified as a parameter to the method or if no target namespace is specified, the uses the target namespace defined in the schema. - - Schemas are retrieved from an using the property of the . The property of the allows you to iterate over the objects contained in the . The property either returns all the objects contained in the , or, given a target namespace parameter, returns all the objects that belong to the target namespace. If `null` is specified as the target namespace parameter, the property returns all schemas without a namespace. - - The following example adds the `books.xsd` schema in the `http://www.contoso.com/books` namespace to an , retrieves all schemas that belong to the `http://www.contoso.com/books` namespace from the , and then writes those schemas to the . - -```vb -Dim schemaSet As XmlSchemaSet = New XmlSchemaSet -schemaSet.Add("http://www.contoso.com/books", "books.xsd") - -Dim schema As XmlSchema - -For Each schema In schemaSet.Schemas("http://www.contoso.com/books") - - schema.Write(Console.Out) - -Next -``` - -```csharp -XmlSchemaSet schemaSet = new XmlSchemaSet(); -schemaSet.Add("http://www.contoso.com/books", "books.xsd"); - -foreach (XmlSchema schema in schemaSet.Schemas("http://www.contoso.com/books")) -{ - schema.Write(Console.Out); -} -``` - - For more information about adding and retrieving schemas from an object, see the method and the property reference documentation. - -## Compiling Schemas - - Schemas in an are compiled into one logical schema by the method of the . - +Describes the , a cache where XML Schema definition language (XSD) schemas can be stored and validated. + +## The XmlSchemaSet Class + + The is a cache where XML Schema definition language (XSD) schemas can be stored and validated. + + In version 1.0, XML schemas were loaded into an class as a library of schemas. In version 2.0, the and the classes are obsolete, and have been replaced by the methods, and the class respectively. + + The has been introduced to fix a number of issues including standards compatibility, performance, and the obsolete Microsoft XML-Data Reduced (XDR) schema format. + + The following is a comparison between the class and the class. + +|XmlSchemaCollection|XmlSchemaSet| +|-------------------------|------------------| +|Supports Microsoft XDR and W3C XML schemas.|Only supports W3C XML schemas.| +|Schemas are compiled when the method is called.|Schemas are not compiled when the method is called. This provides a performance improvement during creation of the schema library.| +|Each schema generates an individual compiled version that can result in "schema islands." As a result, all includes and imports are scoped only within that schema.|Compiled schemas generate a single logical schema, a "set" of schemas. Any imported schemas within a schema that are added to the set are directly added to the set themselves. This means that all types are available to all schemas.| +|Only one schema for a particular target namespace can exist in the collection.|Multiple schemas for the same target namespace can be added as long as there are no type conflicts.| + +## Migrating to the XmlSchemaSet + + The following code example provides a guide to migrating to the new class from the obsolete class. The code example illustrates the following major differences between the two classes. + +- Unlike the method of the class, schemas are not compiled when calling the method of the . The method of the is explicitly called in the example code. + +- To iterate over an , you must use the property of the . + + The following is the obsolete code example. + +```vb +Dim schemaCollection As XmlSchemaCollection = New XmlSchemaCollection() +schemaCollection.Add("http://www.contoso.com/retail", "http://www.contoso.com/retail.xsd") +schemaCollection.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd") + +Dim schema As XmlSchema + +For Each schema in schemaCollection + + Console.WriteLine(schema.TargetNamespace) + +Next +``` + +```csharp +XmlSchemaCollection schemaCollection = new XmlSchemaCollection(); +schemaCollection.Add("http://www.contoso.com/retail", "http://www.contoso.com/retail.xsd"); +schemaCollection.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd"); + +foreach(XmlSchema schema in schemaCollection) +{ + Console.WriteLine(schema.TargetNamespace); +} +``` + + The following is the equivalent code example. + +```vb +Dim schemaSet As XmlSchemaSet = New XmlSchemaSet() +schemaSet.Add("http://www.contoso.com/retail", "http://www.contoso.com/retail.xsd") +schemaSet.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd") +schemaSet.Compile() + +Dim schema As XmlSchema + +For Each schema in schemaSet.Schemas() + + Console.WriteLine(schema.TargetNamespace) + +Next +``` + +```csharp +XmlSchemaSet schemaSet = new XmlSchemaSet(); +schemaSet.Add("http://www.contoso.com/retail", "http://www.contoso.com/retail.xsd"); +schemaSet.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd"); +schemaSet.Compile(); + +foreach(XmlSchema schema in schemaSet.Schemas()) +{ + Console.WriteLine(schema.TargetNamespace); +} +``` + +## Adding and Retrieving Schemas + + Schemas are added to an using the method of the . When a schema is added to an , it is associated with a target namespace URI. The target namespace URI can either be specified as a parameter to the method or if no target namespace is specified, the uses the target namespace defined in the schema. + + Schemas are retrieved from an using the property of the . The property of the allows you to iterate over the objects contained in the . The property either returns all the objects contained in the , or, given a target namespace parameter, returns all the objects that belong to the target namespace. If `null` is specified as the target namespace parameter, the property returns all schemas without a namespace. + + The following example adds the `books.xsd` schema in the `http://www.contoso.com/books` namespace to an , retrieves all schemas that belong to the `http://www.contoso.com/books` namespace from the , and then writes those schemas to the . + +```vb +Dim schemaSet As XmlSchemaSet = New XmlSchemaSet +schemaSet.Add("http://www.contoso.com/books", "books.xsd") + +Dim schema As XmlSchema + +For Each schema In schemaSet.Schemas("http://www.contoso.com/books") + + schema.Write(Console.Out) + +Next +``` + +```csharp +XmlSchemaSet schemaSet = new XmlSchemaSet(); +schemaSet.Add("http://www.contoso.com/books", "books.xsd"); + +foreach (XmlSchema schema in schemaSet.Schemas("http://www.contoso.com/books")) +{ + schema.Write(Console.Out); +} +``` + + For more information about adding and retrieving schemas from an object, see the method and the property reference documentation. + +## Compiling Schemas + + Schemas in an are compiled into one logical schema by the method of the . + > [!NOTE] -> Unlike the obsolete class, schemas are not compiled when the method is called. - - If the method executes successfully, the property of the is set to `true`. - +> Unlike the obsolete class, schemas are not compiled when the method is called. + + If the method executes successfully, the property of the is set to `true`. + > [!NOTE] -> The property is not affected if schemas are edited while in the . Updates of the individual schemas in the are not tracked. As a result, the property can be `true` even though one of the schemas contained in the has been altered, as long as no schemas were added or removed from the . - - The following example adds the `books.xsd` file to the and then calls the method. - -```vb -Dim schemaSet As XmlSchemaSet = New XmlSchemaSet() -schemaSet.Add("http://www.contoso.com/books", "books.xsd") -schemaSet.Compile() -``` - -```csharp -XmlSchemaSet schemaSet = new XmlSchemaSet(); -schemaSet.Add("http://www.contoso.com/books", "books.xsd"); -schemaSet.Compile(); -``` - - For more information about compiling schemas in an , see the method reference documentation. - -## Reprocessing Schemas - - Reprocessing a schema in an performs all the preprocessing steps performed on a schema when the method of the is called. If the call to the method is successful, the property of the is set to `false`. - - The method should be used when a schema in the has been modified after the has performed compilation. - - The following example illustrates reprocessing a schema added to the using the method. After the is compiled using the method, and the schema added to the is modified, the property is set to `true` even though a schema in the has been modified. Calling the method performs all the preprocessing performed by the method, and sets the property to `false`. - -```vb -Dim schemaSet As XmlSchemaSet = New XmlSchemaSet() -Dim schema As XmlSchema = schemaSet.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd") -schemaSet.Compile() - -Dim element As XmlSchemaElement = New XmlSchemaElement() -schema.Items.Add(element) -element.Name = "book" -element.SchemaTypeName = New XmlQualifiedName("string", "http://www.w3.org/2001/XMLSchema") - -schemaSet.Reprocess(schema) -``` - -```csharp -XmlSchemaSet schemaSet = new XmlSchemaSet(); -XmlSchema schema = schemaSet.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd"); -schemaSet.Compile(); - -XmlSchemaElement element = new XmlSchemaElement(); -schema.Items.Add(element); -element.Name = "book"; -element.SchemaTypeName = new XmlQualifiedName("string", "http://www.w3.org/2001/XMLSchema"); - -schemaSet.Reprocess(schema); -``` - - For more information about reprocessing a schema in an , see the method reference documentation. - -## Checking for a Schema - - You can use the method of the to check if a schema is contained within an . The method takes either a target namespace or an object to check for. In either case, the method returns `true` if the schema is contained within the ; otherwise, it returns `false`. - - For more information about checking for a schema, see the method reference documentation. - -## Removing Schemas - - Schemas are removed from an using the and methods of the . The method removes the specified schema from the , while the method removes the specified schema and all the schemas it imports from the . - - The following example illustrates adding multiple schemas to an , then using the method to remove one of the schemas and all the schemas it imports. - -```vb -Dim schemaSet As XmlSchemaSet = New XmlSchemaSet() -schemaSet.Add("http://www.contoso.com/retail", "http://www.contoso.com/retail.xsd") -schemaSet.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd") -schemaSet.Add("http://www.contoso.com/music", "http://www.contoso.com/music.xsd") - -Dim schema As XmlSchema - -For Each schema In schemaSet.Schemas() - - If schema.TargetNamespace = "http://www.contoso.com/music" Then - schemaSet.RemoveRecursive(schema) - End If - -Next -``` - -```csharp -XmlSchemaSet schemaSet = new XmlSchemaSet(); -schemaSet.Add("http://www.contoso.com/retail", "http://www.contoso.com/retail.xsd"); -schemaSet.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd"); -schemaSet.Add("http://www.contoso.com/music", "http://www.contoso.com/music.xsd"); - -foreach (XmlSchema schema in schemaSet.Schemas()) -{ - if (schema.TargetNamespace == "http://www.contoso.com/music") - { - schemaSet.RemoveRecursive(schema); - } -} -``` - - For more information about removing schemas from an , see the and methods reference documentation. - -## Schema Resolution and xs:import - - The following examples describe the behavior for importing schemas when multiple schemas for a given namespace exist in an . - - For example, consider an that contains multiple schemas for the `http://www.contoso.com` namespace. A schema with the following `xs:import` directive is added to the . - -```xml - -``` - - The attempts to import a schema for the `http://www.contoso.com` namespace by loading it from the `http://www.contoso.com/schema.xsd` URL. Only the schema declaration and types declared in the schema document are available in the importing schema, even though there are other schema documents for the `http://www.contoso.com` namespace in the . If the `schema.xsd` file cannot be located at the `http://www.contoso.com/schema.xsd` URL, no schema for the `http://www.contoso.com` namespace is imported into the importing schema. - -## Validating XML Documents - - XML documents can be validated against schemas in an . You validate an XML document by adding a schema to the property of an object, or by adding an to the property of an object. The object is then used by the method of the class to create an object and validate the XML document. - - For more information about validating XML documents using an , see [XML Schema (XSD) Validation with XmlSchemaSet](xml-schema-xsd-validation-with-xmlschemaset.md). - +> The property is not affected if schemas are edited while in the . Updates of the individual schemas in the are not tracked. As a result, the property can be `true` even though one of the schemas contained in the has been altered, as long as no schemas were added or removed from the . + + The following example adds the `books.xsd` file to the and then calls the method. + +```vb +Dim schemaSet As XmlSchemaSet = New XmlSchemaSet() +schemaSet.Add("http://www.contoso.com/books", "books.xsd") +schemaSet.Compile() +``` + +```csharp +XmlSchemaSet schemaSet = new XmlSchemaSet(); +schemaSet.Add("http://www.contoso.com/books", "books.xsd"); +schemaSet.Compile(); +``` + + For more information about compiling schemas in an , see the method reference documentation. + +## Reprocessing Schemas + + Reprocessing a schema in an performs all the preprocessing steps performed on a schema when the method of the is called. If the call to the method is successful, the property of the is set to `false`. + + The method should be used when a schema in the has been modified after the has performed compilation. + + The following example illustrates reprocessing a schema added to the using the method. After the is compiled using the method, and the schema added to the is modified, the property is set to `true` even though a schema in the has been modified. Calling the method performs all the preprocessing performed by the method, and sets the property to `false`. + +```vb +Dim schemaSet As XmlSchemaSet = New XmlSchemaSet() +Dim schema As XmlSchema = schemaSet.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd") +schemaSet.Compile() + +Dim element As XmlSchemaElement = New XmlSchemaElement() +schema.Items.Add(element) +element.Name = "book" +element.SchemaTypeName = New XmlQualifiedName("string", "http://www.w3.org/2001/XMLSchema") + +schemaSet.Reprocess(schema) +``` + +```csharp +XmlSchemaSet schemaSet = new XmlSchemaSet(); +XmlSchema schema = schemaSet.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd"); +schemaSet.Compile(); + +XmlSchemaElement element = new XmlSchemaElement(); +schema.Items.Add(element); +element.Name = "book"; +element.SchemaTypeName = new XmlQualifiedName("string", "http://www.w3.org/2001/XMLSchema"); + +schemaSet.Reprocess(schema); +``` + + For more information about reprocessing a schema in an , see the method reference documentation. + +## Checking for a Schema + + You can use the method of the to check if a schema is contained within an . The method takes either a target namespace or an object to check for. In either case, the method returns `true` if the schema is contained within the ; otherwise, it returns `false`. + + For more information about checking for a schema, see the method reference documentation. + +## Removing Schemas + + Schemas are removed from an using the and methods of the . The method removes the specified schema from the , while the method removes the specified schema and all the schemas it imports from the . + + The following example illustrates adding multiple schemas to an , then using the method to remove one of the schemas and all the schemas it imports. + +```vb +Dim schemaSet As XmlSchemaSet = New XmlSchemaSet() +schemaSet.Add("http://www.contoso.com/retail", "http://www.contoso.com/retail.xsd") +schemaSet.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd") +schemaSet.Add("http://www.contoso.com/music", "http://www.contoso.com/music.xsd") + +Dim schema As XmlSchema + +For Each schema In schemaSet.Schemas() + + If schema.TargetNamespace = "http://www.contoso.com/music" Then + schemaSet.RemoveRecursive(schema) + End If + +Next +``` + +```csharp +XmlSchemaSet schemaSet = new XmlSchemaSet(); +schemaSet.Add("http://www.contoso.com/retail", "http://www.contoso.com/retail.xsd"); +schemaSet.Add("http://www.contoso.com/books", "http://www.contoso.com/books.xsd"); +schemaSet.Add("http://www.contoso.com/music", "http://www.contoso.com/music.xsd"); + +foreach (XmlSchema schema in schemaSet.Schemas()) +{ + if (schema.TargetNamespace == "http://www.contoso.com/music") + { + schemaSet.RemoveRecursive(schema); + } +} +``` + + For more information about removing schemas from an , see the and methods reference documentation. + +## Schema Resolution and xs:import + + The following examples describe the behavior for importing schemas when multiple schemas for a given namespace exist in an . + + For example, consider an that contains multiple schemas for the `http://www.contoso.com` namespace. A schema with the following `xs:import` directive is added to the . + +```xml + +``` + + The attempts to import a schema for the `http://www.contoso.com` namespace by loading it from the `http://www.contoso.com/schema.xsd` URL. Only the schema declaration and types declared in the schema document are available in the importing schema, even though there are other schema documents for the `http://www.contoso.com` namespace in the . If the `schema.xsd` file cannot be located at the `http://www.contoso.com/schema.xsd` URL, no schema for the `http://www.contoso.com` namespace is imported into the importing schema. + +## Validating XML Documents + + XML documents can be validated against schemas in an . You validate an XML document by adding a schema to the property of an object, or by adding an to the property of an object. The object is then used by the method of the class to create an object and validate the XML document. + + For more information about validating XML documents using an , see [XML Schema (XSD) Validation with XmlSchemaSet](xml-schema-xsd-validation-with-xmlschemaset.md). + ## See also -- -- -- -- -- -- -- +- +- +- +- +- +- +- - [XmlSchemaSet as a Schema Cache](xmlschemaset-for-schema-compilation.md) - [XML Schema (XSD) Validation with XmlSchemaSet](xml-schema-xsd-validation-with-xmlschemaset.md) diff --git a/docs/standard/data/xml/xmlschemavalidator-push-based-validation.md b/docs/standard/data/xml/xmlschemavalidator-push-based-validation.md index 0cd40e1a47462..7ed02d56a5993 100644 --- a/docs/standard/data/xml/xmlschemavalidator-push-based-validation.md +++ b/docs/standard/data/xml/xmlschemavalidator-push-based-validation.md @@ -61,31 +61,31 @@ The example also takes the `contosoBooks.xsd` as an input. ## Validating XML Data using XmlSchemaValidator -To begin validating an XML infoset, you must first initialize a new instance of the class using the constructor. +To begin validating an XML infoset, you must first initialize a new instance of the class using the constructor. -The constructor takes , , and objects as parameters as well as a value as a parameter. The object is used to atomize well-known namespace strings like the schema namespace, the XML namespace, and so on, and is passed to the method while validating simple content. The object contains the XML schemas used to validate the XML infoset. The object is used to resolve namespaces encountered during validation. The value is used to disable certain features of validation. +The constructor takes , , and objects as parameters as well as a value as a parameter. The object is used to atomize well-known namespace strings like the schema namespace, the XML namespace, and so on, and is passed to the method while validating simple content. The object contains the XML schemas used to validate the XML infoset. The object is used to resolve namespaces encountered during validation. The value is used to disable certain features of validation. -For more information about the constructor, see the class reference documentation. +For more information about the constructor, see the class reference documentation. ### Initializing Validation -After an object has been constructed, there are two overloaded methods used to initialize the state of the object. The following are the two methods. +After an object has been constructed, there are two overloaded methods used to initialize the state of the object. The following are the two methods. -- +- -- +- -The default method initializes an object to its starting state, and the overloaded method that takes an as a parameter initializes an object to its starting state for partial validation. +The default method initializes an object to its starting state, and the overloaded method that takes an as a parameter initializes an object to its starting state for partial validation. -Both methods can only be called immediately after an object has been constructed or after a call to . +Both methods can only be called immediately after an object has been constructed or after a call to . -For an example of the method, see the example in the introduction. For more information about the method, see the class reference documentation. +For an example of the method, see the example in the introduction. For more information about the method, see the class reference documentation. #### Partial Validation -The method that takes an as a parameter initializes an object to its starting state for partial validation. +The method that takes an as a parameter initializes an object to its starting state for partial validation. -In the following example, an is initialized for partial validation using the method. The `orderNumber` schema element is passed by selecting the schema element by in the collection returned by the property of the object. The object then validates this specific element. +In the following example, an is initialized for partial validation using the method. The `orderNumber` schema element is passed by selecting the schema element by in the collection returned by the property of the object. The object then validates this specific element. ```vb Dim schemaSet As XmlSchemaSet = New XmlSchemaSet() @@ -127,20 +127,20 @@ The example takes the following XML schema as input. ``` -For more information about the method, see the class reference documentation. +For more information about the method, see the class reference documentation. ### Adding Additional Schemas -The method of the class is used to add an XML schema to the set of schemas used during validation. The method can be used to simulate the effect of encountering an inline XML schema in the XML infoset being validated. +The method of the class is used to add an XML schema to the set of schemas used during validation. The method can be used to simulate the effect of encountering an inline XML schema in the XML infoset being validated. > [!NOTE] > The target namespace of the parameter cannot match that of any element or attribute already encountered by the object. > -> If the value was not passed as a parameter to the constructor, the method does nothing. +> If the value was not passed as a parameter to the constructor, the method does nothing. -The result of the method is dependant on the current XML node context being validated. For more information about validation contexts, see the "Validation Context" section of this topic. +The result of the method is dependant on the current XML node context being validated. For more information about validation contexts, see the "Validation Context" section of this topic. -For more information about the method, see the class reference documentation. +For more information about the method, see the class reference documentation. ### Validating Elements, Attributes, and Content @@ -148,14 +148,14 @@ The class provides several methods u |Method|Description| |------------|-----------------| -||Validates the element name in the current context.| -||Validates the attribute in the current element context or against the object passed as a parameter to the method.| -||Verifies whether all the required attributes in the element context are present and prepares the object to validate the child content of the element.| -||Validates whether text is allowed in the current element context, and accumulates the text for validation if the current element has simple content.| -||Validates whether white-space is allowed in the current element context, and accumulates the white-space for validation whether the current element has simple content.| -||Verifies whether the text content of the element is valid according to its data type for elements with simple content, and verifies whether the content of the current element is complete for elements with complex content.| -||Skips validation of the current element content and prepares the object to validate content in the parent element's context.| -||Ends validation and checks identity constraints for the entire XML document if the validation option is set.| +||Validates the element name in the current context.| +||Validates the attribute in the current element context or against the object passed as a parameter to the method.| +||Verifies whether all the required attributes in the element context are present and prepares the object to validate the child content of the element.| +||Validates whether text is allowed in the current element context, and accumulates the text for validation if the current element has simple content.| +||Validates whether white-space is allowed in the current element context, and accumulates the white-space for validation whether the current element has simple content.| +||Verifies whether the text content of the element is valid according to its data type for elements with simple content, and verifies whether the content of the current element is complete for elements with complex content.| +||Skips validation of the current element content and prepares the object to validate content in the parent element's context.| +||Ends validation and checks identity constraints for the entire XML document if the validation option is set.| > [!NOTE] > The class has a defined state transition that enforces the sequence and occurrence of calls made to each of the methods described in the previous table. The specific state transition of the class is described in the "XmlSchemaValidator State Transition" section of this topic. @@ -166,15 +166,15 @@ For an example of the methods used to validate elements, attributes, and content The `delegate` can be used to pass the value of attribute, text, or white-space nodes as a Common Language Runtime (CLR) types compatible with the XML Schema Definition Language (XSD) type of the attribute, text, or white-space node. An `delegate` is useful if the CLR value of an attribute, text, or white-space node is already available, and avoids the cost of converting it to a `string` and then reparsing it again for validation. -The , , and methods are overloaded and accept the value of attribute, text, or white-space nodes as a `string` or `delegate`. +The , , and methods are overloaded and accept the value of attribute, text, or white-space nodes as a `string` or `delegate`. The following methods of the class accept an `delegate` as a parameter. -- +- -- +- -- +- The following is an example `delegate` taken from the class example in the introduction. The `delegate` returns the value of an attribute as a object. To validate this object returned by the , the object first converts it to the ValueType (ValueType is the default CLR mapping for the XSD type) for the data type of the attribute and then checks facets on the converted value. @@ -212,42 +212,42 @@ For a complete example of the `delegate`, The class represents some of the Post-Schema-Validation-Information of an XML node validated by the class. Various methods of the class accept an object as an optional, (`null`) `out` parameter. -Upon successful validation, properties of the object are set with the results of the validation. For example, upon successful validation of an attribute using the method, the object's (if specified) , , , and properties are set with the results of the validation. +Upon successful validation, properties of the object are set with the results of the validation. For example, upon successful validation of an attribute using the method, the object's (if specified) , , , and properties are set with the results of the validation. The following class methods accept an object as an out parameter. -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- For a complete example of the class, see the example in the introduction. For more information about the class, see the class reference documentation. ### Retrieving Expected Particles, Attributes, and Unspecified Default Attributes -The class provides the , , and methods to retrieve the expected particles, attributes, and unspecified default attributes in the current validation context. +The class provides the , , and methods to retrieve the expected particles, attributes, and unspecified default attributes in the current validation context. #### Retrieving Expected Particles -The method returns an array of objects containing the expected particles in the current element context. The valid particles that can be returned by the method are instances of the and classes. +The method returns an array of objects containing the expected particles in the current element context. The valid particles that can be returned by the method are instances of the and classes. When the compositor for the content model is an `xs:sequence`, only the next particle in the sequence is returned. If the compositor for the content model is an `xs:all` or an `xs:choice`, then all valid particles that could follow in the current element context are returned. > [!NOTE] -> If the method is called immediately after calling the method, the method returns all global elements. +> If the method is called immediately after calling the method, the method returns all global elements. -For example, in the XML Schema Definition Language (XSD) schema and XML document that follow, after validating the `book` element, the `book` element is the current element context. The method returns an array containing a single object representing the `title` element. When the validation context is the `title` element, the method returns an empty array. If the method is called after the `title` element has been validated but before the `description` element has been validated, it returns an array containing a single object representing the `description` element. If the method is called after the `description` element has been validated then it returns an array containing a single object representing the wildcard. +For example, in the XML Schema Definition Language (XSD) schema and XML document that follow, after validating the `book` element, the `book` element is the current element context. The method returns an array containing a single object representing the `title` element. When the validation context is the `title` element, the method returns an empty array. If the method is called after the `title` element has been validated but before the `description` element has been validated, it returns an array containing a single object representing the `description` element. If the method is called after the `description` element has been validated then it returns an array containing a single object representing the wildcard. ```vb Dim reader As XmlReader = XmlReader.Create("input.xml") @@ -364,28 +364,28 @@ The example takes the following XSD schema as input: ``` > [!NOTE] -> The results of the , , and methods of the class are dependent on the current context being validated. For more information, see the "Validation Context" section of this topic. +> The results of the , , and methods of the class are dependent on the current context being validated. For more information, see the "Validation Context" section of this topic. -For an example of the method, see the example in the introduction. For more information about the method, see the class reference documentation. +For an example of the method, see the example in the introduction. For more information about the method, see the class reference documentation. #### Retrieving Expected Attributes -The method returns an array of objects containing the expected attributes in the current element context. +The method returns an array of objects containing the expected attributes in the current element context. -For example, in the example in the introduction, the method is used to retrieve all the attributes of the `book` element. +For example, in the example in the introduction, the method is used to retrieve all the attributes of the `book` element. -If you call the method immediately after the method, all the attributes that could appear in the XML document are returned. However, if you call the method after one or more calls to the method, the attributes that have not yet been validated for the current element are returned. +If you call the method immediately after the method, all the attributes that could appear in the XML document are returned. However, if you call the method after one or more calls to the method, the attributes that have not yet been validated for the current element are returned. > [!NOTE] -> The results of the , , and methods of the class are dependent on the current context being validated. For more information, see the "Validation Context" section of this topic. +> The results of the , , and methods of the class are dependent on the current context being validated. For more information, see the "Validation Context" section of this topic. -For an example of the method, see the example in the introduction. For more information about the method, see the class reference documentation. +For an example of the method, see the example in the introduction. For more information about the method, see the class reference documentation. #### Retrieving Unspecified Default Attributes -The method populates the specified with objects for any attributes with default values that have not been previously validated using the method in the element context. The method should be called after calling the method on each attribute in the element context. The method should be used to determine what default attributes are to be inserted into the XML document being validated. +The method populates the specified with objects for any attributes with default values that have not been previously validated using the method in the element context. The method should be called after calling the method on each attribute in the element context. The method should be used to determine what default attributes are to be inserted into the XML document being validated. -For more information about the method, see the class reference documentation. +For more information about the method, see the class reference documentation. ### Handling Schema Validation Events @@ -434,10 +434,10 @@ The following table describes the state transition of the ( | TopLevel*) | -|TopLevel| | | Element| -|Element| * ( Content\*)? |

\* |

\* Content\* || -|Content| | | Element| +|Validate| ( | TopLevel*) | +|TopLevel| | | Element| +|Element| * ( Content\*)? |

\* |

\* Content\* || +|Content| | | Element| > [!NOTE] > An is thrown by each of the methods in the table above when the call to the method is made in the incorrect sequence according to the current state of an object. @@ -454,24 +454,24 @@ The following table describes how the punctuation symbols found in the state tra ## Validation Context -The methods of the class used to validate elements, attributes, and content in an XML infoset, change the validation context of an object. For example, the method skips validation of the current element content and prepares the object to validate content in the parent element's context; it is equivalent to skipping validation for all the children of the current element and then calling the method. +The methods of the class used to validate elements, attributes, and content in an XML infoset, change the validation context of an object. For example, the method skips validation of the current element content and prepares the object to validate content in the parent element's context; it is equivalent to skipping validation for all the children of the current element and then calling the method. -The results of the , , and methods of the class are dependent on the current context being validated. +The results of the , , and methods of the class are dependent on the current context being validated. The following table describes the results of calling these methods after calling one of the methods of the class used to validate elements, attributes, and content in an XML infoset. |Method|GetExpectedParticles|GetExpectedAttributes|AddSchema| |------------|--------------------------|---------------------------|---------------| -||If the default method is called, returns an array containing all global elements.

If the overloaded method that takes an as a parameter is called to initialize partial validation of an element, returns only the element to which the object was initialized.|If the default method is called, returns an empty array.

If the overload of the method that takes an as a parameter is called to initialize partial validation of an attribute, returns only the attribute to which the object was initialized.|Adds the schema to the of the object if it has no preprocessing errors.| -||If the context element is valid, returns the sequence of elements expected as children of the context element.

If the context element is invalid, returns an empty array.|If the context element is valid, and if no call to has been previously made, returns a list of all the attributes defined on the context element.

If some attributes have already been validated, returns a list of the remaining attributes to be validated.

If the context element is invalid, returns an empty array.|Same as above.| -||If the context attribute is a top-level attribute, returns an empty array.

Otherwise returns the sequence of elements expected as the first child of the context element.|If the context attribute is a top-level attribute, returns an empty array.

Otherwise returns the list of remaining attributes to be validated.|Same as above.| -|| returns the sequence of elements expected as the first child of the context element.| returns a list of the required and optional attributes that are yet to be validated for the context element.|Same as above.| -|| returns the sequence of elements expected as the first child of the context element.| returns an empty array.|Same as above.| -||If the context element's contentType is Mixed, returns the sequence of elements expected in the next position.

If the context element's contentType is TextOnly or Empty, returns an empty array.

If the context element's contentType is ElementOnly, returns the sequence of elements expected in the next position but a validation error has already occurred.| returns the context element's list of attributes not validated.|Same as above.| -||If the context white-space is top-level white-space, returns an empty array.

Otherwise the method's behavior is the same as in .|If the context white-space is top-level white-space, returns an empty array.

Otherwise the method's behavior is the same as in .|Same as above.| -|| returns the sequence of elements expected after the context element (possible siblings).| returns the context element's list of attributes not validated.

If the context element has no parent then returns an empty list (the context element is the parent of the current element on which was called).|Same as above.| -||Same as .|Same as .|Same as above.| -||Returns an empty array.|Returns an empty array.|Same as above.| +||If the default method is called, returns an array containing all global elements.

If the overloaded method that takes an as a parameter is called to initialize partial validation of an element, returns only the element to which the object was initialized.|If the default method is called, returns an empty array.

If the overload of the method that takes an as a parameter is called to initialize partial validation of an attribute, returns only the attribute to which the object was initialized.|Adds the schema to the of the object if it has no preprocessing errors.| +||If the context element is valid, returns the sequence of elements expected as children of the context element.

If the context element is invalid, returns an empty array.|If the context element is valid, and if no call to has been previously made, returns a list of all the attributes defined on the context element.

If some attributes have already been validated, returns a list of the remaining attributes to be validated.

If the context element is invalid, returns an empty array.|Same as above.| +||If the context attribute is a top-level attribute, returns an empty array.

Otherwise returns the sequence of elements expected as the first child of the context element.|If the context attribute is a top-level attribute, returns an empty array.

Otherwise returns the list of remaining attributes to be validated.|Same as above.| +|| returns the sequence of elements expected as the first child of the context element.| returns a list of the required and optional attributes that are yet to be validated for the context element.|Same as above.| +|| returns the sequence of elements expected as the first child of the context element.| returns an empty array.|Same as above.| +||If the context element's contentType is Mixed, returns the sequence of elements expected in the next position.

If the context element's contentType is TextOnly or Empty, returns an empty array.

If the context element's contentType is ElementOnly, returns the sequence of elements expected in the next position but a validation error has already occurred.| returns the context element's list of attributes not validated.|Same as above.| +||If the context white-space is top-level white-space, returns an empty array.

Otherwise the method's behavior is the same as in .|If the context white-space is top-level white-space, returns an empty array.

Otherwise the method's behavior is the same as in .|Same as above.| +|| returns the sequence of elements expected after the context element (possible siblings).| returns the context element's list of attributes not validated.

If the context element has no parent then returns an empty list (the context element is the parent of the current element on which was called).|Same as above.| +||Same as .|Same as .|Same as above.| +||Returns an empty array.|Returns an empty array.|Same as above.| > [!NOTE] > The values returned by the various properties of the class are not altered by calling any of the methods in the above table. diff --git a/docs/standard/data/xml/xpath-namespace-navigation.md b/docs/standard/data/xml/xpath-namespace-navigation.md index 961349003b318..e2e3c0cd025d7 100644 --- a/docs/standard/data/xml/xpath-namespace-navigation.md +++ b/docs/standard/data/xml/xpath-namespace-navigation.md @@ -6,59 +6,59 @@ ms.assetid: 06cc7abb-7416-415c-9dd6-67751b8cabd5 --- # XPath Namespace Navigation -To use XPath queries with XML documents, you have to correctly address XML namespaces and the elements contained by namespaces. Namespaces prevent ambiguities that can occur when names are used in more than one context; for example, the name `ID` may refer to more than one identifier associated with different elements of an XML document. Namespace syntax specifies URIs, names, and prefixes that distinguish the elements of an XML document. - - The example in this topic demonstrates the use of prefixes in navigating an XML document with . For more information about namespaces and syntax, see [XML Files: Understanding XML Namespaces](/previous-versions/dotnet/articles/bb986013(v=msdn.10)). - -## Namespace Declarations - - Namespace declarations make the elements of an XML document distinguishable and addressable when using an instance of . Namespace prefixes provide a brief syntax for addressing namespaces. - - Prefixes are defined by the form: `.` In this syntax the prefix "`e`" is an abbreviation for the formal URI of the namespace. You can identify the `Body` element as a member of the `Envelope` namespace by using the syntax: `e:Body`. - - The following XML document will be referenced as `response.xml` in the navigation example in the next section. - -```xml - - - - +To use XPath queries with XML documents, you have to correctly address XML namespaces and the elements contained by namespaces. Namespaces prevent ambiguities that can occur when names are used in more than one context; for example, the name `ID` may refer to more than one identifier associated with different elements of an XML document. Namespace syntax specifies URIs, names, and prefixes that distinguish the elements of an XML document. + + The example in this topic demonstrates the use of prefixes in navigating an XML document with . For more information about namespaces and syntax, see [XML Files: Understanding XML Namespaces](/previous-versions/dotnet/articles/bb986013(v=msdn.10)). + +## Namespace Declarations + + Namespace declarations make the elements of an XML document distinguishable and addressable when using an instance of . Namespace prefixes provide a brief syntax for addressing namespaces. + + Prefixes are defined by the form: `.` In this syntax the prefix "`e`" is an abbreviation for the formal URI of the namespace. You can identify the `Body` element as a member of the `Envelope` namespace by using the syntax: `e:Body`. + + The following XML document will be referenced as `response.xml` in the navigation example in the next section. + +```xml + + + + - - - - -``` - -## Navigation by Namespace Prefix - - The code in this section uses and objects to select the `Search` element from the XML document in the previous section. The query `xpath` includes namespace prefixes on each element in the path. Specifying the precise identity of the namespaces that contain each element assures correct navigation to the `Search` element by the method. - -```csharp -using (XmlReader reader = XmlReader.Create("response.xml")) -{ - XPathDocument doc = new XPathDocument(reader); + xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> + + + + +``` + +## Navigation by Namespace Prefix + + The code in this section uses and objects to select the `Search` element from the XML document in the previous section. The query `xpath` includes namespace prefixes on each element in the path. Specifying the precise identity of the namespaces that contain each element assures correct navigation to the `Search` element by the method. + +```csharp +using (XmlReader reader = XmlReader.Create("response.xml")) +{ + XPathDocument doc = new XPathDocument(reader); XPathNavigator nav = doc.CreateNavigator(); - - XmlNamespaceManager nsmgr = new XmlNamespaceManager(nav.NameTable); - nsmgr.AddNamespace("e", @"http://schemas.xmlsoap.org/soap/envelope/"); - nsmgr.AddNamespace("s", @"http://schemas.microsoft.com/v1/Search"); - nsmgr.AddNamespace("r", @"http://schemas.microsoft.com/v1/Search/metadata"); - nsmgr.AddNamespace("i", @"http://www.w3.org/2001/XMLSchema-instance"); - - string xpath = "/e:Envelope/e:Body/s:Search"; - - XPathNavigator element = nav.SelectSingleNode(xpath, nsmgr); - + + XmlNamespaceManager nsmgr = new XmlNamespaceManager(nav.NameTable); + nsmgr.AddNamespace("e", @"http://schemas.xmlsoap.org/soap/envelope/"); + nsmgr.AddNamespace("s", @"http://schemas.microsoft.com/v1/Search"); + nsmgr.AddNamespace("r", @"http://schemas.microsoft.com/v1/Search/metadata"); + nsmgr.AddNamespace("i", @"http://www.w3.org/2001/XMLSchema-instance"); + + string xpath = "/e:Envelope/e:Body/s:Search"; + + XPathNavigator element = nav.SelectSingleNode(xpath, nsmgr); + Console.WriteLine("Element Prefix:" + element.Prefix + - " Local name:" + element.LocalName); - Console.WriteLine("Namespace URI: " + element.NamespaceURI); -} -``` - - The precision of fully qualifying namespaces and names is more than a convenience. A little experimentation with the document definition and code in the previous examples will verify that navigation without fully qualified element names throws exceptions. For example, the element definition: ``, and query: string `xpath = "/s:Envelope/s:Body/Search";` without the namespace prefix on the `Search` element returns `null` instead of the `Search` element. - + " Local name:" + element.LocalName); + Console.WriteLine("Namespace URI: " + element.NamespaceURI); +} +``` + + The precision of fully qualifying namespaces and names is more than a convenience. A little experimentation with the document definition and code in the previous examples will verify that navigation without fully qualified element names throws exceptions. For example, the element definition: ``, and query: string `xpath = "/s:Envelope/s:Body/Search";` without the namespace prefix on the `Search` element returns `null` instead of the `Search` element. + ## See also - [Accessing XML Data using XPathNavigator](accessing-xml-data-using-xpathnavigator.md) diff --git a/docs/standard/data/xml/xpath-queries-and-namespaces.md b/docs/standard/data/xml/xpath-queries-and-namespaces.md index 7d94b916b928f..8537f2924dc7c 100644 --- a/docs/standard/data/xml/xpath-queries-and-namespaces.md +++ b/docs/standard/data/xml/xpath-queries-and-namespaces.md @@ -2,77 +2,77 @@ title: "XPath Queries and Namespaces" description: Learn about XPath queries & namespaces. XPath queries know of namespaces in an XML document & can use namespace prefixes to qualify element & attribute names. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: ef6402be-2f8e-4be2-8d3e-a80891cdef8b --- # XPath Queries and Namespaces -XPath queries are aware of namespaces in an XML document and can use namespace prefixes to qualify element and attribute names. Qualifying element and attribute names with a namespace prefix limits the nodes returned by an XPath query to only those nodes that belong to a specific namespace. - - For example if the prefix `books` maps to the namespace `http://www.contoso.com/books`, then the following XPath query `/books:books/books:book` selects only those `book` elements in the namespace `http://www.contoso.com/books`. - -## The XmlNamespaceManager - - To use namespaces in an XPath query, an object derived from the interface like the class is constructed with the namespace URI and prefix to include in the XPath query. - - The object may be used in the query in each of the following ways. - -- The object is associated with an existing object by using the method of the object. You may also compile a new object using the static method which takes a string representing the XPath expression and an object as parameters and returns a new object. - -- The object itself is passed as a parameter to an accepting class method along with a string representing the XPath expression. - - The following are the methods of the class that accept an object derived from the interface as a parameter. - -- - -- - -- - -### The Default Namespace - - In the XML document that follows, the default namespace with an empty prefix is used to declare the `http://www.contoso.com/books` namespace. - -```xml - - - Title - Author Name - 5.50 - - -``` - - XPath treats the empty prefix as the `null` namespace. In other words, only prefixes mapped to namespaces can be used in XPath queries. This means that if you want to query against a namespace in an XML document, even if it is the default namespace, you need to define a prefix for it. - - For example, without defining a prefix for the XML document above, the XPath query `/books/book` would not return any results. - - A prefix must be bound to prevent ambiguity when querying documents with some nodes not in a namespace, and some in a default namespace. - - The following code defines a prefix for the default namespace and selects all the `book` elements from the `http://www.contoso.com/books` namespace. - -```vb -Dim document As XPathDocument = New XPathDocument("books.xml") -Dim navigator As XPathNavigator = document.CreateNavigator() -Dim query As XPathExpression = navigator.Compile("/books:books/books:book") -Dim manager As XmlNamespaceManager = New XmlNamespaceManager(navigator.NameTable) -manager.AddNamespace("books", "http://www.contoso.com/books") -query.SetContext(manager) -Dim nodes As XPathNodeIterator = navigator.Select(query) -``` - -```csharp -XPathDocument document = new XPathDocument("books.xml"); -XPathNavigator navigator = document.CreateNavigator(); -XPathExpression query = navigator.Compile("/books:books/books:book"); -XmlNamespaceManager manager = new XmlNamespaceManager(navigator.NameTable); -manager.AddNamespace("books", "http://www.contoso.com/books"); -query.SetContext(manager); -XPathNodeIterator nodes = navigator.Select(query); -``` - +XPath queries are aware of namespaces in an XML document and can use namespace prefixes to qualify element and attribute names. Qualifying element and attribute names with a namespace prefix limits the nodes returned by an XPath query to only those nodes that belong to a specific namespace. + + For example if the prefix `books` maps to the namespace `http://www.contoso.com/books`, then the following XPath query `/books:books/books:book` selects only those `book` elements in the namespace `http://www.contoso.com/books`. + +## The XmlNamespaceManager + + To use namespaces in an XPath query, an object derived from the interface like the class is constructed with the namespace URI and prefix to include in the XPath query. + + The object may be used in the query in each of the following ways. + +- The object is associated with an existing object by using the method of the object. You may also compile a new object using the static method which takes a string representing the XPath expression and an object as parameters and returns a new object. + +- The object itself is passed as a parameter to an accepting class method along with a string representing the XPath expression. + + The following are the methods of the class that accept an object derived from the interface as a parameter. + +- + +- + +- + +### The Default Namespace + + In the XML document that follows, the default namespace with an empty prefix is used to declare the `http://www.contoso.com/books` namespace. + +```xml + + + Title + Author Name + 5.50 + + +``` + + XPath treats the empty prefix as the `null` namespace. In other words, only prefixes mapped to namespaces can be used in XPath queries. This means that if you want to query against a namespace in an XML document, even if it is the default namespace, you need to define a prefix for it. + + For example, without defining a prefix for the XML document above, the XPath query `/books/book` would not return any results. + + A prefix must be bound to prevent ambiguity when querying documents with some nodes not in a namespace, and some in a default namespace. + + The following code defines a prefix for the default namespace and selects all the `book` elements from the `http://www.contoso.com/books` namespace. + +```vb +Dim document As XPathDocument = New XPathDocument("books.xml") +Dim navigator As XPathNavigator = document.CreateNavigator() +Dim query As XPathExpression = navigator.Compile("/books:books/books:book") +Dim manager As XmlNamespaceManager = New XmlNamespaceManager(navigator.NameTable) +manager.AddNamespace("books", "http://www.contoso.com/books") +query.SetContext(manager) +Dim nodes As XPathNodeIterator = navigator.Select(query) +``` + +```csharp +XPathDocument document = new XPathDocument("books.xml"); +XPathNavigator navigator = document.CreateNavigator(); +XPathExpression query = navigator.Compile("/books:books/books:book"); +XmlNamespaceManager manager = new XmlNamespaceManager(navigator.NameTable); +manager.AddNamespace("books", "http://www.contoso.com/books"); +query.SetContext(manager); +XPathNodeIterator nodes = navigator.Select(query); +``` + ## See also - diff --git a/docs/standard/data/xml/xslt-extension-objects.md b/docs/standard/data/xml/xslt-extension-objects.md index 3f8d6a8e34667..efd83bd11cc89 100644 --- a/docs/standard/data/xml/xslt-extension-objects.md +++ b/docs/standard/data/xml/xslt-extension-objects.md @@ -6,31 +6,31 @@ ms.assetid: a4ebdbad-087c-4cfe-acc0-17c48142f81a --- # XSLT Extension Objects -Extension objects are used to extend the functionality of style sheets. Extension objects are maintained by the class. - - The following are advantages to using an extension object rather than embedded script: - -- Provides better encapsulation and reuse of classes. - -- Allows style sheets to be smaller and more maintainable. - - XSLT extension objects are added to the object using the method. A qualified name and namespace URI are associated with the extension object at that time. - +Extension objects are used to extend the functionality of style sheets. Extension objects are maintained by the class. + + The following are advantages to using an extension object rather than embedded script: + +- Provides better encapsulation and reuse of classes. + +- Allows style sheets to be smaller and more maintainable. + + XSLT extension objects are added to the object using the method. A qualified name and namespace URI are associated with the extension object at that time. + > [!NOTE] -> The FullTrust permission set is required to call the method. For more information, see [Code Access Security](/previous-versions/dotnet/framework/code-access-security/code-access-security) and [Named Permission Sets](/previous-versions/dotnet/netframework-4.0/4652tyx7(v=vs.100)). - - The data types returned from extension objects are one of the four basic XPath data types of `number`, `string`, `Boolean`, and `node set`. - - Any method that is defined with the `params` keyword, which allows an unspecified number of parameters to be passed, is not currently supported by the class. XSLT style sheets that utilize any method defined with the `params` keyword will not work correctly. For details, see [params](../../../csharp/language-reference/keywords/method-parameters.md#params-modifier). - -### To use an XSLT extension object - -1. Create an object and add the extension object using method. - -2. Call the extension object from the style sheet. - -3. Pass the object to the method. - +> The FullTrust permission set is required to call the method. For more information, see [Code Access Security](/previous-versions/dotnet/framework/code-access-security/code-access-security) and [Named Permission Sets](/previous-versions/dotnet/netframework-4.0/4652tyx7(v=vs.100)). + + The data types returned from extension objects are one of the four basic XPath data types of `number`, `string`, `Boolean`, and `node set`. + + Any method that is defined with the `params` keyword, which allows an unspecified number of parameters to be passed, is not currently supported by the class. XSLT style sheets that utilize any method defined with the `params` keyword will not work correctly. For details, see [params](../../../csharp/language-reference/keywords/method-parameters.md#params-modifier). + +### To use an XSLT extension object + +1. Create an object and add the extension object using method. + +2. Call the extension object from the style sheet. + +3. Pass the object to the method. + ## See also - [XSLT Transformations](xslt-transformations.md) diff --git a/docs/standard/data/xml/xslt-parameters.md b/docs/standard/data/xml/xslt-parameters.md index 9c89378d2b76c..77cb4b13c4c2c 100644 --- a/docs/standard/data/xml/xslt-parameters.md +++ b/docs/standard/data/xml/xslt-parameters.md @@ -2,69 +2,69 @@ description: "Learn more about: XSLT Parameters" title: "XSLT Parameters" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: fe60aaa0-ae43-4b1c-9be1-426af66ba757 --- # XSLT Parameters -XSLT parameters are added to the using the method. A qualified name and namespace URI are associated with the parameter object at that time. - -### To use an XSLT parameter - -1. Create an object and add the parameter using the method. - -2. Call the parameter from the style sheet. - -3. Pass the object to the method. - -## Parameter Types - - The parameter object should correspond to a W3C type. The following table shows the corresponding W3C types, the equivalent Microsoft .NET classes (type), and whether the W3C type is an XPath type or XSLT type. - -|W3C type|Equivalent .NET class (type)|XPath or XSLT type| -|--------------|------------------------------------|------------------------| -|`String`||XPath| -|`Boolean`||XPath| -|`Number`||XPath| -|`Result Tree Fragment`||XSLT| -|`Node*`||XPath| -|`Node Set`|

**XPathNavigator[]**|XPath| - - *This is equivalent to a node set that contains a single node. - - If the parameter object is not one of the above classes, it is converted according to the following rules. Common language runtime (CLR) numeric types are converted to . The type is converted to . types are converted to . **XPathNavigator[]** is converted to . - - All other types throw an error. - -## Example - - The following example uses the method to create a parameter to hold calculated discount date. The discount date is calculated to be 20 days from the order date. - +XSLT parameters are added to the using the method. A qualified name and namespace URI are associated with the parameter object at that time. + +### To use an XSLT parameter + +1. Create an object and add the parameter using the method. + +2. Call the parameter from the style sheet. + +3. Pass the object to the method. + +## Parameter Types + + The parameter object should correspond to a W3C type. The following table shows the corresponding W3C types, the equivalent Microsoft .NET classes (type), and whether the W3C type is an XPath type or XSLT type. + +|W3C type|Equivalent .NET class (type)|XPath or XSLT type| +|--------------|------------------------------------|------------------------| +|`String`||XPath| +|`Boolean`||XPath| +|`Number`||XPath| +|`Result Tree Fragment`||XSLT| +|`Node*`||XPath| +|`Node Set`|

**XPathNavigator[]**|XPath| + + *This is equivalent to a node set that contains a single node. + + If the parameter object is not one of the above classes, it is converted according to the following rules. Common language runtime (CLR) numeric types are converted to . The type is converted to . types are converted to . **XPathNavigator[]** is converted to . + + All other types throw an error. + +## Example + + The following example uses the method to create a parameter to hold calculated discount date. The discount date is calculated to be 20 days from the order date. + [!code-csharp[XSLT_Param#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XSLT_Param/CS/xsltparam.cs#1)] - [!code-vb[XSLT_Param#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XSLT_Param/VB/xsltparam.vb#1)] - -### Input - -##### order.xml - - [!code-xml[XSLT_Param#2](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_Param/XML/order.xml#2)] - -##### discount.xsl - - [!code-xml[XSLT_Param#3](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_Param/XML/discount.xsl#3)] - -### Output - -```xml - - - 36.9 - 15% discount if paid by: 2/4/2004 12:00:00 AM - -``` - + [!code-vb[XSLT_Param#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XSLT_Param/VB/xsltparam.vb#1)] + +### Input + +##### order.xml + + [!code-xml[XSLT_Param#2](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_Param/XML/order.xml#2)] + +##### discount.xsl + + [!code-xml[XSLT_Param#3](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_Param/XML/discount.xsl#3)] + +### Output + +```xml + + + 36.9 + 15% discount if paid by: 2/4/2004 12:00:00 AM + +``` + ## See also - [XSLT Transformations](xslt-transformations.md) diff --git a/docs/standard/data/xml/xslt-security-considerations.md b/docs/standard/data/xml/xslt-security-considerations.md index 36bd1b4dbee2a..604f2cd934487 100644 --- a/docs/standard/data/xml/xslt-security-considerations.md +++ b/docs/standard/data/xml/xslt-security-considerations.md @@ -6,58 +6,58 @@ ms.assetid: fea695be-617c-4977-9567-140e820436fc --- # XSLT Security Considerations -The XSLT language has a rich set of features that give you a great deal of power and flexibility. It includes many features that, while useful, could also be exploited by outside sources. In order to use XSLT safely, you must understand the types of security issues that arise when using XSLT, and the basic strategies that you can employ to mitigate these risks. - -## XSLT Extensions +The XSLT language has a rich set of features that give you a great deal of power and flexibility. It includes many features that, while useful, could also be exploited by outside sources. In order to use XSLT safely, you must understand the types of security issues that arise when using XSLT, and the basic strategies that you can employ to mitigate these risks. - Two popular XSLT extensions are style sheet scripting and extension objects. These extensions allow the XSLT processor to execute code. - -- Extension objects add programming capabilities to XSL transformations. - -- Scripts can be embedded in the style sheet using the `msxsl:script` extension element. - -### Extension Objects +## XSLT Extensions - Extension objects are added using the method. The FullTrust permission set is required to support extension objects. This ensures that elevation of permissions does not happen when extension object code is executed. Attempting to call the method without FullTrust permissions results in a security exception being thrown. - -### Style Sheet Scripts + Two popular XSLT extensions are style sheet scripting and extension objects. These extensions allow the XSLT processor to execute code. - Scripts can be embedded in a style sheet using the `msxsl:script` extension element. Script support is an optional feature on the class that is disabled by default. Scripting can be enabled by setting the property to `true` and passing the object to the method. +- Extension objects add programming capabilities to XSL transformations. + +- Scripts can be embedded in the style sheet using the `msxsl:script` extension element. + +### Extension Objects + + Extension objects are added using the method. The FullTrust permission set is required to support extension objects. This ensures that elevation of permissions does not happen when extension object code is executed. Attempting to call the method without FullTrust permissions results in a security exception being thrown. + +### Style Sheet Scripts + + Scripts can be embedded in a style sheet using the `msxsl:script` extension element. Script support is an optional feature on the class that is disabled by default. Scripting can be enabled by setting the property to `true` and passing the object to the method. > [!NOTE] > Script blocks are supported only in .NET Framework. They are _not_ supported on .NET Core or .NET 5 or later. - -#### Guidelines - - Enable scripting only when the style sheet comes from a trusted source. If you cannot verify the source of the style sheet, or if the style sheet does not come from a trusted source, pass in `null` for the XSLT settings argument. - -## External Resources - - The XSLT language has features such as `xsl:import`, `xsl:include`, or the `document()` function, where the processor needs to resolve URI references. The class is used to resolve external resources. External resources may need to be resolved in the following two cases: - -- When compiling a style sheet, the is used for `xsl:import` and `xsl:include` resolution. - -- When executing the transformation, the is used to resolve the `document()` function. - + +#### Guidelines + + Enable scripting only when the style sheet comes from a trusted source. If you cannot verify the source of the style sheet, or if the style sheet does not come from a trusted source, pass in `null` for the XSLT settings argument. + +## External Resources + + The XSLT language has features such as `xsl:import`, `xsl:include`, or the `document()` function, where the processor needs to resolve URI references. The class is used to resolve external resources. External resources may need to be resolved in the following two cases: + +- When compiling a style sheet, the is used for `xsl:import` and `xsl:include` resolution. + +- When executing the transformation, the is used to resolve the `document()` function. + > [!NOTE] - > The `document()` function is disabled by default on the class. This feature can be enabled by setting the property to `true` and passing the object to the method. - - The and methods each include overloads that accept an as one of its arguments. If an is not specified, a default with no credentials is used. - -#### Guidelines - - Enable the `document()` function only when the style sheet comes from a trusted source. - - The following list describes when you may want to specify an object: - -- If the XSLT process needs to access a network resource that requires authentication, you can use an with the necessary credentials. - -- If you want to restrict the resources that the XSLT process can access, you can use an with the correct permission set. Use the class if you need to open a resource that you do not control, or that is untrusted. - -- If you want to customize behavior, you can implement your own class and use it to resolve resources. - -- If you want to ensure that no external resources are accessed, you can specify `null` for the argument. - + > The `document()` function is disabled by default on the class. This feature can be enabled by setting the property to `true` and passing the object to the method. + + The and methods each include overloads that accept an as one of its arguments. If an is not specified, a default with no credentials is used. + +#### Guidelines + + Enable the `document()` function only when the style sheet comes from a trusted source. + + The following list describes when you may want to specify an object: + +- If the XSLT process needs to access a network resource that requires authentication, you can use an with the necessary credentials. + +- If you want to restrict the resources that the XSLT process can access, you can use an with the correct permission set. Use the class if you need to open a resource that you do not control, or that is untrusted. + +- If you want to customize behavior, you can implement your own class and use it to resolve resources. + +- If you want to ensure that no external resources are accessed, you can specify `null` for the argument. + ## See also - [XSLT Transformations](xslt-transformations.md) diff --git a/docs/standard/datetime/access-utc-and-local.md b/docs/standard/datetime/access-utc-and-local.md index e9f700bb6bce9..d986d8a467892 100644 --- a/docs/standard/datetime/access-utc-and-local.md +++ b/docs/standard/datetime/access-utc-and-local.md @@ -16,28 +16,28 @@ ms.topic: how-to --- # How to: Access the predefined UTC and local time zone objects -The class provides two properties, and , that give your code access to predefined time zone objects. This topic discusses how to access the objects returned by those properties. +The class provides two properties, and , that give your code access to predefined time zone objects. This topic discusses how to access the objects returned by those properties. ### To access the Coordinated Universal Time (UTC) TimeZoneInfo object -1. Use the `static` (`Shared` in Visual Basic) property to access Coordinated Universal Time. +1. Use the `static` (`Shared` in Visual Basic) property to access Coordinated Universal Time. -2. Rather than assigning the object returned by the property to an object variable, continue to access Coordinated Universal Time through the property. +2. Rather than assigning the object returned by the property to an object variable, continue to access Coordinated Universal Time through the property. ### To access the local time zone -1. Use the `static` (`Shared` in Visual Basic) property to access the local system time zone. +1. Use the `static` (`Shared` in Visual Basic) property to access the local system time zone. -2. Rather than assigning the object returned by the property to an object variable, continue to access the local time zone through the property. +2. Rather than assigning the object returned by the property to an object variable, continue to access the local time zone through the property. ## Example -The following code uses the and properties to convert a time from the U.S. and Canadian Eastern Standard time zone, as well as to display the time zone name to the console. +The following code uses the and properties to convert a time from the U.S. and Canadian Eastern Standard time zone, as well as to display the time zone name to the console. [!code-csharp[System.TimeZone2.Concepts#13](./snippets/timezone-concepts/TimeZone2Concepts.cs#13)] [!code-vb[System.TimeZone2.Concepts#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#13)] -You should always access the local time zone through the property rather than assigning the local time zone to a object variable. Similarly, you should always access Coordinated Universal Time through the property rather than assigning the UTC zone to a object variable. This prevents the object variable from being invalidated by a call to the method. +You should always access the local time zone through the property rather than assigning the local time zone to a object variable. Similarly, you should always access Coordinated Universal Time through the property rather than assigning the UTC zone to a object variable. This prevents the object variable from being invalidated by a call to the method. ## See also diff --git a/docs/standard/datetime/choosing-between-datetime.md b/docs/standard/datetime/choosing-between-datetime.md index 6e9b310b33412..e98325b59f093 100644 --- a/docs/standard/datetime/choosing-between-datetime.md +++ b/docs/standard/datetime/choosing-between-datetime.md @@ -2,10 +2,10 @@ title: Compare types related to date and time description: Learn about differences between the DateTime, DateOnly, DateTimeOffset, TimeSpan, TimeOnly, and TimeZoneInfo types to represent date and time information in .NET. ms.date: 04/05/2023 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "DateTimeOffset structure" - "TimeZoneInfo class" - "time zones [.NET], common uses" @@ -53,7 +53,7 @@ The output shows that each date and time value in this example can belong to at ## The DateTime structure -A value defines a particular date and time. It includes a property that provides limited information about the time zone to which that date and time belongs. The value returned by the property indicates whether the value represents the local time (), Coordinated Universal Time (UTC) (), or an unspecified time (). +A value defines a particular date and time. It includes a property that provides limited information about the time zone to which that date and time belongs. The value returned by the property indicates whether the value represents the local time (), Coordinated Universal Time (UTC) (), or an unspecified time (). The structure is suitable for applications with one or more of the following characteristics: @@ -62,10 +62,10 @@ The structure is suitable for applications with one or mo - Work with UTC dates and times only. - Perform date and time arithmetic, but are concerned with general results. For example, in an addition operation that adds six months to a particular date and time, it is often not important whether the result is adjusted for daylight saving time. -Unless a particular value represents UTC, that date and time value is often ambiguous or limited in its portability. For example, if a value represents the local time, it's portable within that local time zone (that is, if the value is deserialized on another system in the same time zone, that value still unambiguously identifies a single point in time). Outside the local time zone, that value can have multiple interpretations. If the value's property is , it's even less portable: it is now ambiguous within the same time zone and possibly even on the same system where it was first serialized. Only if a value represents UTC does that value unambiguously identify a single point in time regardless of the system or time zone in which the value is used. +Unless a particular value represents UTC, that date and time value is often ambiguous or limited in its portability. For example, if a value represents the local time, it's portable within that local time zone (that is, if the value is deserialized on another system in the same time zone, that value still unambiguously identifies a single point in time). Outside the local time zone, that value can have multiple interpretations. If the value's property is , it's even less portable: it is now ambiguous within the same time zone and possibly even on the same system where it was first serialized. Only if a value represents UTC does that value unambiguously identify a single point in time regardless of the system or time zone in which the value is used. > [!IMPORTANT] -> When saving or sharing data, use UTC and set the value's property to . +> When saving or sharing data, use UTC and set the value's property to . ## The DateOnly structure @@ -87,9 +87,9 @@ For more information about `DateOnly`, see [How to use the DateOnly and TimeOnly The structure represents a time interval. Its two typical uses are: - Reflecting the time interval between two date and time values. For example, subtracting one value from another returns a value. -- Measuring elapsed time. For example, the property returns a value that reflects the time interval that has elapsed since the call to one of the methods that begins to measure elapsed time. +- Measuring elapsed time. For example, the property returns a value that reflects the time interval that has elapsed since the call to one of the methods that begins to measure elapsed time. -A value can also be used as a replacement for a value when that value reflects a time without reference to a particular day. This usage is similar to the and properties, which return a value that represents the time without reference to a date. For example, the structure can be used to reflect a store's daily opening or closing time, or it can be used to represent the time at which any regular event occurs. +A value can also be used as a replacement for a value when that value reflects a time without reference to a particular day. This usage is similar to the and properties, which return a value that represents the time without reference to a date. For example, the structure can be used to reflect a store's daily opening or closing time, or it can be used to represent the time at which any regular event occurs. The following example defines a `StoreInfo` structure that includes objects for store opening and closing times, as well as a object that represents the store's time zone. The structure also includes two methods, `IsOpenNow` and `IsOpenAt`, that indicates whether the store is open at a time specified by the user, who is assumed to be in the local time zone. diff --git a/docs/standard/datetime/converting-between-datetime-and-offset.md b/docs/standard/datetime/converting-between-datetime-and-offset.md index 7030ff28089fa..b1e7a2b44041c 100644 --- a/docs/standard/datetime/converting-between-datetime-and-offset.md +++ b/docs/standard/datetime/converting-between-datetime-and-offset.md @@ -3,10 +3,10 @@ title: "Converting between DateTime and DateTimeOffset" description: Convert between DateTimeOffset values and DateTime values in .NET. The DateTimeOffset structure provides more time zone awareness than the DateTime structure. ms.date: "08/01/2022" ms.custom: devdivchpfy22 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "DateTime structure, converting" - "time zones [.NET], conversions" - "UTC times, converting" @@ -23,17 +23,17 @@ ms.topic: how-to Although the structure provides a greater degree of time zone awareness than the structure, parameters are used more commonly in method calls. Because of this approach, the ability to convert values to values and vice versa is important. This article shows how to perform these conversions in a way that preserves as much time zone information as possible. > [!NOTE] -> Both the and the types have some limitations when representing times in time zones. With its property, is able to reflect only Coordinated Universal Time (UTC) and the system's local time zone. reflects a time's offset from UTC, but it doesn't reflect the actual time zone to which that offset belongs. For more information about time values and support for time zones, see [Choosing Between DateTime, DateTimeOffset, TimeSpan, and TimeZoneInfo](choosing-between-datetime.md). +> Both the and the types have some limitations when representing times in time zones. With its property, is able to reflect only Coordinated Universal Time (UTC) and the system's local time zone. reflects a time's offset from UTC, but it doesn't reflect the actual time zone to which that offset belongs. For more information about time values and support for time zones, see [Choosing Between DateTime, DateTimeOffset, TimeSpan, and TimeZoneInfo](choosing-between-datetime.md). ## Conversions from DateTime to DateTimeOffset The structure provides two equivalent ways to perform to conversion that are suitable for most conversions: -- The constructor, which creates a new object based on a value. +- The constructor, which creates a new object based on a value. - The implicit conversion operator, which allows you to assign a value to a object. -For UTC and local values, the property of the resulting value accurately reflects the UTC or local time zone offset. For example, the following code converts a UTC time to its equivalent value: +For UTC and local values, the property of the resulting value accurately reflects the UTC or local time zone offset. For example, the following code converts a UTC time to its equivalent value: [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#1)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#1)] @@ -43,12 +43,12 @@ In this case, the offset of the `utcTime2` variable is 00:00. Similarly, the fol [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#2](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#2)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#2)] -However, for values whose property is , these two conversion methods produce a value whose offset is that of the local time zone. The conversion is shown in the following example, which is run in the U.S. Pacific Standard Time zone: +However, for values whose property is , these two conversion methods produce a value whose offset is that of the local time zone. The conversion is shown in the following example, which is run in the U.S. Pacific Standard Time zone: [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#3](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#3)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#3)] -If the value reflects the date and time in something other than the local time zone or UTC, you can convert it to a value and preserve its time zone information by calling the overloaded constructor. For example, the following example instantiates a object that reflects Central Standard Time: +If the value reflects the date and time in something other than the local time zone or UTC, you can convert it to a value and preserve its time zone information by calling the overloaded constructor. For example, the following example instantiates a object that reflects Central Standard Time: [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#4](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#4)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#4)] @@ -57,56 +57,56 @@ The second parameter to this constructor overload is a ob ## Conversions from DateTimeOffset to DateTime -The property is most commonly used to perform to conversion. However, it returns a value whose property is , as the following example illustrates: +The property is most commonly used to perform to conversion. However, it returns a value whose property is , as the following example illustrates: [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#5](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#5)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#5)] -The preceding example shows that any information about the value's relationship to UTC is lost by the conversion when the property is used. This behavior also affects values that correspond to UTC time or the system's local time because the structure reflects only those two time zones in its property. +The preceding example shows that any information about the value's relationship to UTC is lost by the conversion when the property is used. This behavior also affects values that correspond to UTC time or the system's local time because the structure reflects only those two time zones in its property. -To preserve as much time zone information as possible when converting a to a value, you can use the and properties. +To preserve as much time zone information as possible when converting a to a value, you can use the and properties. ### Converting a UTC time -To indicate that a converted value is the UTC time, you can retrieve the value of the property. It differs from the property in two ways: +To indicate that a converted value is the UTC time, you can retrieve the value of the property. It differs from the property in two ways: -- It returns a value whose property is . +- It returns a value whose property is . -- If the property value doesn't equal , it converts the time to UTC. +- If the property value doesn't equal , it converts the time to UTC. > [!NOTE] -> If your application requires that converted values unambiguously identify a single point in time, you should consider using the property to handle all to conversions. +> If your application requires that converted values unambiguously identify a single point in time, you should consider using the property to handle all to conversions. -The following code uses the property to convert a value whose offset equals to a value: +The following code uses the property to convert a value whose offset equals to a value: [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#6](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#6)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#6)] -The following code uses the property to perform both a time zone conversion and a type conversion on a value: +The following code uses the property to perform both a time zone conversion and a type conversion on a value: [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#12](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#12)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#12)] ### Converting a local time -To indicate that a value represents the local time, you can pass the value returned by the property to the `static` (`Shared` in Visual Basic) method. The method returns the date and time passed to it as its first parameter but sets the property to the value specified by its second parameter. The following code uses the method when converting a value whose offset corresponds to that of the local time zone: +To indicate that a value represents the local time, you can pass the value returned by the property to the `static` (`Shared` in Visual Basic) method. The method returns the date and time passed to it as its first parameter but sets the property to the value specified by its second parameter. The following code uses the method when converting a value whose offset corresponds to that of the local time zone: [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#7](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#7)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#7)] -You can also use the property to convert a value to a local value. The property of the returned value is . The following code uses the property when converting a value whose offset corresponds to that of the local time zone: +You can also use the property to convert a value to a local value. The property of the returned value is . The following code uses the property when converting a value whose offset corresponds to that of the local time zone: [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#10](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#10)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#10)] -When you retrieve a value using the property, the property's `get` accessor first converts the value to UTC, then converts it to local time by calling the method. This behavior means that you can retrieve a value from the property to perform a time zone conversion at the same time that you perform a type conversion. It also means that the local time zone's adjustment rules are applied in performing the conversion. The following code illustrates the use of the property to perform both a type and a time zone conversion. The sample output is for a machine set to the Pacific Time Zone (US and Canada). The November date is Pacific Standard Time, which is UTC-8, while the June date is Daylight Savings Time, which is UTC-7. +When you retrieve a value using the property, the property's `get` accessor first converts the value to UTC, then converts it to local time by calling the method. This behavior means that you can retrieve a value from the property to perform a time zone conversion at the same time that you perform a type conversion. It also means that the local time zone's adjustment rules are applied in performing the conversion. The following code illustrates the use of the property to perform both a type and a time zone conversion. The sample output is for a machine set to the Pacific Time Zone (US and Canada). The November date is Pacific Standard Time, which is UTC-8, while the June date is Daylight Savings Time, which is UTC-7. [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#11](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#11)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#11)] ### A general-purpose conversion method -The following example defines a method named `ConvertFromDateTimeOffset` that converts values to values. Based on its offset, it determines whether the value is a UTC time, a local time, or some other time and defines the returned date and time value's property accordingly. +The following example defines a method named `ConvertFromDateTimeOffset` that converts values to values. Based on its offset, it determines whether the value is a UTC time, a local time, or some other time and defines the returned date and time value's property accordingly. [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#8](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#8)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#8)] diff --git a/docs/standard/datetime/converting-between-time-zones.md b/docs/standard/datetime/converting-between-time-zones.md index 0e2116a41d9bf..5f3d0acaf7129 100644 --- a/docs/standard/datetime/converting-between-time-zones.md +++ b/docs/standard/datetime/converting-between-time-zones.md @@ -25,7 +25,7 @@ Coordinated Universal Time (UTC) is a high-precision, atomic time standard. The > [!NOTE] > You can also serialize a structure to represent a single point in time unambiguously. Because objects store a date and time value along with its offset from UTC, they always represent a particular point in time in relation to UTC. -The easiest way to convert a time to UTC is to call the `static` (`Shared` in Visual Basic) method. The exact conversion performed by the method depends on the value of the `dateTime` parameter's property, as the following table shows: +The easiest way to convert a time to UTC is to call the `static` (`Shared` in Visual Basic) method. The exact conversion performed by the method depends on the value of the `dateTime` parameter's property, as the following table shows: | `DateTime.Kind` | Conversion | | -------------------------- | ------------------------------------------------------------------------------ | @@ -38,23 +38,23 @@ The following code converts the current local time to UTC and displays the resul [!code-csharp[System.TimeZone2.Concepts#6](./snippets/timezone-concepts/TimeZone2Concepts.cs#6)] [!code-vb[System.TimeZone2.Concepts#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#6)] -If the date and time value doesn't represent the local time or UTC, the method will likely return an erroneous result. However, you can use the method to convert the date and time from a specified time zone. For details on retrieving a object that represents the destination time zone, see [Finding the time zones defined on a local system](finding-the-time-zones-on-local-system.md). The following code uses the method to convert Eastern Standard Time to UTC: +If the date and time value doesn't represent the local time or UTC, the method will likely return an erroneous result. However, you can use the method to convert the date and time from a specified time zone. For details on retrieving a object that represents the destination time zone, see [Finding the time zones defined on a local system](finding-the-time-zones-on-local-system.md). The following code uses the method to convert Eastern Standard Time to UTC: [!code-csharp[System.TimeZone2.Concepts#7](./snippets/timezone-concepts/TimeZone2Concepts.cs#7)] [!code-vb[System.TimeZone2.Concepts#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#7)] -The method throws an if the object's property and the time zone are mismatched. A mismatch occurs if the property is but the object doesn't represent the local time zone, or if the property is but the object doesn't equal . +The method throws an if the object's property and the time zone are mismatched. A mismatch occurs if the property is but the object doesn't represent the local time zone, or if the property is but the object doesn't equal . -All of these methods take values as parameters and return a value. For values, the structure has a instance method that converts the date and time of the current instance to UTC. The following example calls the method to convert a local time and several other times to UTC: +All of these methods take values as parameters and return a value. For values, the structure has a instance method that converts the date and time of the current instance to UTC. The following example calls the method to convert a local time and several other times to UTC: [!code-csharp[System.DateTimeOffset.Methods#16](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/cs/Methods.cs#16)] [!code-vb[System.DateTimeOffset.Methods#16](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb#16)] ## Converting UTC to a designated time zone -To convert UTC to local time, see the [Converting UTC to local time](#converting-utc-to-local-time) section that follows. To convert UTC to the time in any time zone that you designate, call the method. The method takes two parameters: +To convert UTC to local time, see the [Converting UTC to local time](#converting-utc-to-local-time) section that follows. To convert UTC to the time in any time zone that you designate, call the method. The method takes two parameters: -- The UTC to convert. This must be a value whose property is set to `Unspecified` or `Utc`. +- The UTC to convert. This must be a value whose property is set to `Unspecified` or `Utc`. - The time zone to convert the UTC to. @@ -65,7 +65,7 @@ The following code converts UTC to Central Standard Time: ## Converting UTC to local time -To convert UTC to local time, call the method of the object whose time you want to convert. The exact behavior of the method depends on the value of the object's property, as the following table shows: +To convert UTC to local time, call the method of the object whose time you want to convert. The exact behavior of the method depends on the value of the object's property, as the following table shows: | `DateTime.Kind` | Conversion | | -------------------------- | ---------------------------------------------------------------------------------------- | @@ -74,32 +74,32 @@ To convert UTC to local time, call the met | `DateTimeKind.Utc` | Converts the value to local time. | > [!NOTE] -> The method behaves identically to the `DateTime.ToLocalTime` method. It takes a single parameter, which is the date and time value, to convert. +> The method behaves identically to the `DateTime.ToLocalTime` method. It takes a single parameter, which is the date and time value, to convert. -You can also convert the time in any designated time zone to local time by using the `static` (`Shared` in Visual Basic) method. This technique is discussed in the next section. +You can also convert the time in any designated time zone to local time by using the `static` (`Shared` in Visual Basic) method. This technique is discussed in the next section. ## Converting between any two time zones You can convert between any two time zones by using either of the following two `static` (`Shared` in Visual Basic) methods of the class: -- +- This method's parameters are the date and time value to convert, a `TimeZoneInfo` object that represents the time zone of the date and time value, and a `TimeZoneInfo` object that represents the time zone to convert the date and time value to. -- +- This method's parameters are the date and time value to convert, the identifier of the date and time value's time zone, and the identifier of the time zone to convert the date and time value to. -Both methods require that the property of the date and time value to convert and the object or time zone identifier that represents its time zone correspond to one another. Otherwise, an is thrown. For example, if the `Kind` property of the date and time value is `DateTimeKind.Local`, an exception is thrown if the `TimeZoneInfo` object passed as a parameter to the method isn't equal to `TimeZoneInfo.Local`. An exception is also thrown if the identifier passed as a parameter to the method isn't equal to `TimeZoneInfo.Local.Id`. +Both methods require that the property of the date and time value to convert and the object or time zone identifier that represents its time zone correspond to one another. Otherwise, an is thrown. For example, if the `Kind` property of the date and time value is `DateTimeKind.Local`, an exception is thrown if the `TimeZoneInfo` object passed as a parameter to the method isn't equal to `TimeZoneInfo.Local`. An exception is also thrown if the identifier passed as a parameter to the method isn't equal to `TimeZoneInfo.Local.Id`. -The following example uses the method to convert from Hawaiian Standard Time to local time: +The following example uses the method to convert from Hawaiian Standard Time to local time: [!code-csharp[System.TimeZone2.Concepts#9](./snippets/timezone-concepts/TimeZone2Concepts.cs#9)] [!code-vb[System.TimeZone2.Concepts#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#9)] ## Converting DateTimeOffset values -Date and time values represented by objects aren't fully time-zone aware because the object is disassociated from its time zone at the time it's instantiated. However, in many cases, an application simply needs to convert a date and time based on two different offsets from UTC rather than on time in particular time zones. To perform this conversion, you can call the current instance's method. The method's single parameter is the offset of the new date and time value the method will return. +Date and time values represented by objects aren't fully time-zone aware because the object is disassociated from its time zone at the time it's instantiated. However, in many cases, an application simply needs to convert a date and time based on two different offsets from UTC rather than on time in particular time zones. To perform this conversion, you can call the current instance's method. The method's single parameter is the offset of the new date and time value the method will return. For example, if the date and time of a user request for a web page is known and is serialized as a string in the format MM/dd/yyyy hh:mm:ss zzzz, the following `ReturnTimeOnServer` method converts this date and time value to the date and time on the web server: diff --git a/docs/standard/datetime/create-time-zones-with-adjustment-rules.md b/docs/standard/datetime/create-time-zones-with-adjustment-rules.md index b7898cead70c8..aaed96e032f45 100644 --- a/docs/standard/datetime/create-time-zones-with-adjustment-rules.md +++ b/docs/standard/datetime/create-time-zones-with-adjustment-rules.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Create time zones with adjustment rules" title: "How to: Create time zones with adjustment rules" ms.date: "04/10/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "time zones [.NET], creating" - "time zones [.NET], and adjustment rules" - "adjustment rule [.NET]" @@ -21,10 +21,10 @@ The precise time zone information that is required by an application may not be - The time zone does not have accurate information about time zone adjustments for a particular historic period. -In these cases, you can call the method to define the time zone required by your application. You can use the overloads of this method to create a time zone with or without adjustment rules. If the time zone supports daylight saving time, you can define adjustments with either fixed or floating adjustment rules. (For definitions of these terms, see the "Time Zone Terminology" section in [Time zone overview](time-zone-overview.md).) +In these cases, you can call the method to define the time zone required by your application. You can use the overloads of this method to create a time zone with or without adjustment rules. If the time zone supports daylight saving time, you can define adjustments with either fixed or floating adjustment rules. (For definitions of these terms, see the "Time Zone Terminology" section in [Time zone overview](time-zone-overview.md).) > [!IMPORTANT] -> Custom time zones created by calling the method are not added to the registry. Instead, they can be accessed only through the object reference returned by the method call. +> Custom time zones created by calling the method are not added to the registry. Instead, they can be accessed only through the object reference returned by the method call. This topic shows how to create a time zone with adjustment rules. To create a time zone that does not support daylight saving time adjustment rules, see [How to: Create Time Zones Without Adjustment Rules](create-time-zones-without-adjustment-rules.md). @@ -34,11 +34,11 @@ This topic shows how to create a time zone with adjustment rules. To create a ti 1. Define the starting transition time for the time zone adjustment. - You must call the method and pass it a value that defines the time of the transition, an integer value that defines the month of the transition, an integer value that defines the week on which the transition occurs, and a value that defines the day of the week on which the transition occurs. This method call instantiates a object. + You must call the method and pass it a value that defines the time of the transition, an integer value that defines the month of the transition, an integer value that defines the week on which the transition occurs, and a value that defines the day of the week on which the transition occurs. This method call instantiates a object. - 2. Define the ending transition time for the time zone adjustment. This requires another call to the method. This method call instantiates a second object. + 2. Define the ending transition time for the time zone adjustment. This requires another call to the method. This method call instantiates a second object. - 3. Call the method and pass it the effective start and end dates of the adjustment, a object that defines the amount of time in the transition, and the two objects that define when the transitions to and from daylight saving time occur. This method call instantiates a object. + 3. Call the method and pass it the effective start and end dates of the adjustment, a object that defines the amount of time in the transition, and the two objects that define when the transitions to and from daylight saving time occur. This method call instantiates a object. 4. Assign the object to an array of objects. @@ -63,11 +63,11 @@ The following example defines a Central Standard Time zone for the United States The time zone created in this example has multiple adjustment rules. Care must be taken to ensure that the effective start and end dates of any adjustment rule do not overlap with the dates of another adjustment rule. If there is an overlap, an is thrown. -For floating adjustment rules, the value 5 is passed to the `week` parameter of the method to indicate that the transition occurs on the last week of a particular month. +For floating adjustment rules, the value 5 is passed to the `week` parameter of the method to indicate that the transition occurs on the last week of a particular month. -In creating the array of objects to use in the method call, the code could initialize the array to the size required by the number of adjustments to be created for the time zone. Instead, this code example calls the method to add each adjustment rule to a generic collection of objects. The code then calls the method to copy the members of this collection to the array. +In creating the array of objects to use in the method call, the code could initialize the array to the size required by the number of adjustments to be created for the time zone. Instead, this code example calls the method to add each adjustment rule to a generic collection of objects. The code then calls the method to copy the members of this collection to the array. -The example also uses the method to define fixed-date adjustments. This is similar to calling the method, except that it requires only the time, month, and day of the transition parameters. +The example also uses the method to define fixed-date adjustments. This is similar to calling the method, except that it requires only the time, month, and day of the transition parameters. The example can be tested using code such as the following: diff --git a/docs/standard/datetime/create-time-zones-without-adjustment-rules.md b/docs/standard/datetime/create-time-zones-without-adjustment-rules.md index 37693f76fbefe..c9cb9963cd413 100644 --- a/docs/standard/datetime/create-time-zones-without-adjustment-rules.md +++ b/docs/standard/datetime/create-time-zones-without-adjustment-rules.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Create time zones without adjustment rules" title: "How to: Create time zones without adjustment rules" ms.date: "04/10/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "time zones [.NET], adjustment rule" - "time zones [.NET], creating" - "adjustment rule [.NET]" @@ -21,10 +21,10 @@ The precise time zone information that is required by an application may not be - The time zone exists but does not have accurate information about time zone adjustments for a particular historic period. -In these cases, you can call the method to define the time zone required by your application. You can use the overloads of this method to create a time zone with or without adjustment rules. If the time zone supports daylight saving time, you can define adjustments with either fixed or floating adjustment rules. (For definitions of these terms, see the "Time Zone Terminology" section in [Time zone overview](time-zone-overview.md).) +In these cases, you can call the method to define the time zone required by your application. You can use the overloads of this method to create a time zone with or without adjustment rules. If the time zone supports daylight saving time, you can define adjustments with either fixed or floating adjustment rules. (For definitions of these terms, see the "Time Zone Terminology" section in [Time zone overview](time-zone-overview.md).) > [!IMPORTANT] -> Custom time zones created by calling the method are not added to the registry. Instead, they can be accessed only through the object reference returned by the method call. +> Custom time zones created by calling the method are not added to the registry. Instead, they can be accessed only through the object reference returned by the method call. This topic shows how to create a time zone without adjustment rules. To create a time zone that supports daylight saving time adjustment rules, see [How to: Create time zones with adjustment rules](create-time-zones-with-adjustment-rules.md). @@ -49,7 +49,7 @@ The following example defines a custom time zone for Mawson, Antarctica, which h [!code-csharp[System.TimeZone2.CreateTimeZone#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.TimeZone2.CreateTimeZone/cs/System.TimeZone2.CreateTimeZone.cs#1)] [!code-vb[System.TimeZone2.CreateTimeZone#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.CreateTimeZone/vb/System.TimeZone2.CreateTimeZone.vb#1)] -The string assigned to the property follows a standard format in which the time zone's offset from UTC is followed by a friendly description of the time zone. +The string assigned to the property follows a standard format in which the time zone's offset from UTC is followed by a friendly description of the time zone. ## Compiling the code diff --git a/docs/standard/datetime/enumerate-time-zones.md b/docs/standard/datetime/enumerate-time-zones.md index fcbb09b54b95c..b892e2ac5d0f5 100644 --- a/docs/standard/datetime/enumerate-time-zones.md +++ b/docs/standard/datetime/enumerate-time-zones.md @@ -19,19 +19,19 @@ Successfully working with a designated time zone requires that information about ### To enumerate the time zones present on the local system -1. Call the method. The method returns a generic collection of objects. The entries in the collection are sorted by their property. For example: +1. Call the method. The method returns a generic collection of objects. The entries in the collection are sorted by their property. For example: [!code-csharp[System.TimeZone2.Concepts#1](./snippets/timezone-concepts/TimeZone2Concepts.cs#1)] [!code-vb[System.TimeZone2.Concepts#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#1)] -2. Enumerate the individual objects in the collection by using a `foreach` loop (in C#) or a `For Each`…`Next` loop (in Visual Basic), and perform any necessary processing on each object. For example, the following code enumerates the collection of objects returned in step 1 and lists the display name of each time zone on the console. +2. Enumerate the individual objects in the collection by using a `foreach` loop (in C#) or a `For Each`…`Next` loop (in Visual Basic), and perform any necessary processing on each object. For example, the following code enumerates the collection of objects returned in step 1 and lists the display name of each time zone on the console. [!code-csharp[System.TimeZone2.Concepts#12](./snippets/timezone-concepts/TimeZone2Concepts.cs#12)] [!code-vb[System.TimeZone2.Concepts#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#12)] ### To present the user with a list of time zones present on the local system -1. Call the method. The method returns a generic collection of objects. +1. Call the method. The method returns a generic collection of objects. 2. Assign the collection returned in step 1 to the `DataSource` property of a Windows forms or ASP.NET list control. @@ -41,12 +41,12 @@ The example provides an illustration for a Windows application. ## Example -The example starts a Windows application that displays the time zones defined on a system in a list box. The example then displays a dialog box that contains the value of the property of the time zone object selected by the user. +The example starts a Windows application that displays the time zones defined on a system in a list box. The example then displays a dialog box that contains the value of the property of the time zone object selected by the user. [!code-csharp[System.TimeZone2.Concepts#2](./snippets/timezone-concepts/TimeZone2Concepts.cs#2)] [!code-vb[System.TimeZone2.Concepts#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#2)] -Most list controls (such as the or control) allow you to assign a collection of object variables to their `DataSource` property as long as that collection implements the interface. (The generic class does this.) To display an individual object in the collection, the control calls that object's `ToString` method to extract the string that is used to represent the object. In the case of objects, the `ToString` method returns the object's display name (the value of its property). +Most list controls (such as the or control) allow you to assign a collection of object variables to their `DataSource` property as long as that collection implements the interface. (The generic class does this.) To display an individual object in the collection, the control calls that object's `ToString` method to extract the string that is used to represent the object. In the case of objects, the `ToString` method returns the object's display name (the value of its property). > [!NOTE] > Because list controls call an object's `ToString` method, you can assign a collection of objects to the control, have the control display a meaningful name for each object, and retrieve the object that the user has selected. This eliminates the need to extract a string for each object in the collection, assign the string to a collection that is in turn assigned to the control's `DataSource` property, retrieve the string the user has selected, and then use this string to extract the object that it describes. diff --git a/docs/standard/datetime/finding-the-time-zones-on-local-system.md b/docs/standard/datetime/finding-the-time-zones-on-local-system.md index 6045dab1bf45f..c67c836dbe82c 100644 --- a/docs/standard/datetime/finding-the-time-zones-on-local-system.md +++ b/docs/standard/datetime/finding-the-time-zones-on-local-system.md @@ -2,7 +2,7 @@ description: "Learn more about: Finding the time zones defined on a local system" title: "Finding the time zones defined on a local system" ms.date: "04/10/2017" -helpviewer_keywords: +helpviewer_keywords: - "time zones [.NET], local" - "time zones [.NET], finding local system time zones" - "time zone identifiers [.NET]" @@ -17,17 +17,17 @@ ms.topic: how-to The class does not expose a public constructor. As a result, the `new` keyword cannot be used to create a new object. Instead, objects are instantiated either by retrieving information on predefined time zones from the registry or by creating a custom time zone. This topic discusses instantiating a time zone from data stored in the registry. In addition, `static` (`shared` in Visual Basic) properties of the class provide access to Coordinated Universal Time (UTC) and the local time zone. > [!NOTE] -> For time zones that are not defined in the registry, you can create custom time zones by calling the overloads of the method. Creating a custom time zone is discussed in the [How to: Create time zones without adjustment rules](create-time-zones-without-adjustment-rules.md) and [How to: Create time zones with adjustment rules](create-time-zones-with-adjustment-rules.md) topics. In addition, you can instantiate a object by restoring it from a serialized string with the method. Serializing and deserializing a object is discussed in the [How to: Save time zones to an embedded resource](save-time-zones-to-an-embedded-resource.md) and [How to: Restore Time Zones from an Embedded Resource](restore-time-zones-from-an-embedded-resource.md) topics. +> For time zones that are not defined in the registry, you can create custom time zones by calling the overloads of the method. Creating a custom time zone is discussed in the [How to: Create time zones without adjustment rules](create-time-zones-without-adjustment-rules.md) and [How to: Create time zones with adjustment rules](create-time-zones-with-adjustment-rules.md) topics. In addition, you can instantiate a object by restoring it from a serialized string with the method. Serializing and deserializing a object is discussed in the [How to: Save time zones to an embedded resource](save-time-zones-to-an-embedded-resource.md) and [How to: Restore Time Zones from an Embedded Resource](restore-time-zones-from-an-embedded-resource.md) topics. ## Accessing individual time zones -The class provides two predefined time zone objects that represent the UTC time and the local time zone. They are available from the and properties, respectively. For instructions on accessing the UTC or local time zones, see [How to: Access the predefined UTC and local time zone objects](access-utc-and-local.md). +The class provides two predefined time zone objects that represent the UTC time and the local time zone. They are available from the and properties, respectively. For instructions on accessing the UTC or local time zones, see [How to: Access the predefined UTC and local time zone objects](access-utc-and-local.md). You can also instantiate a object that represents any time zone defined in the registry. For instructions on instantiating a specific time zone object, see [How to: Instantiate a TimeZoneInfo object](instantiate-time-zone-info.md). ## Time zone identifiers -The time zone identifier is a key field that uniquely identifies the time zone. While most keys are relatively short, the time zone identifier is comparatively long. In most cases, its value corresponds to the property, which is used to provide the name of the time zone's standard time. However, there are exceptions. The best way to make sure that you supply a valid identifier is to enumerate the time zones available on your system and note their associated identifiers. +The time zone identifier is a key field that uniquely identifies the time zone. While most keys are relatively short, the time zone identifier is comparatively long. In most cases, its value corresponds to the property, which is used to provide the name of the time zone's standard time. However, there are exceptions. The best way to make sure that you supply a valid identifier is to enumerate the time zones available on your system and note their associated identifiers. ## See also diff --git a/docs/standard/datetime/how-to-use-dateonly-timeonly.md b/docs/standard/datetime/how-to-use-dateonly-timeonly.md index 71954d5d41c04..32bacbb988962 100644 --- a/docs/standard/datetime/how-to-use-dateonly-timeonly.md +++ b/docs/standard/datetime/how-to-use-dateonly-timeonly.md @@ -52,14 +52,14 @@ Use the following examples to learn about `DateOnly`: ### Convert DateTime to DateOnly -Use the static method to create a `DateOnly` type from a `DateTime` type, as demonstrated in the following code: +Use the static method to create a `DateOnly` type from a `DateTime` type, as demonstrated in the following code: :::code language="csharp" source="./snippets/how-to-use-dateonly-timeonly/csharp/Program.cs" id="today"::: :::code language="vb" source="./snippets/how-to-use-dateonly-timeonly/vb/Program.vb" id="today"::: ### Add or subtract days, months, years -There are three methods used to adjust a structure: , , and . Each method takes an integer parameter, and increases the date by that measurement. If a negative number is provided, the date is decreased by that measurement. The methods return a new instance of `DateOnly`, as the structure is immutable. +There are three methods used to adjust a structure: , , and . Each method takes an integer parameter, and increases the date by that measurement. If a negative number is provided, the date is decreased by that measurement. The methods return a new instance of `DateOnly`, as the structure is immutable. :::code language="csharp" source="./snippets/how-to-use-dateonly-timeonly/csharp/Program.cs" id="date_adjust"::: :::code language="vb" source="./snippets/how-to-use-dateonly-timeonly/vb/Program.vb" id="date_adjust"::: @@ -104,14 +104,14 @@ Use the following examples to learn about `TimeOnly`: ### Convert DateTime to TimeOnly -Use the static method to create a `TimeOnly` type from a `DateTime` type, as demonstrated in the following code: +Use the static method to create a `TimeOnly` type from a `DateTime` type, as demonstrated in the following code: :::code language="csharp" source="./snippets/how-to-use-dateonly-timeonly/csharp/Program.cs" id="time_now"::: :::code language="vb" source="./snippets/how-to-use-dateonly-timeonly/vb/Program.vb" id="time_now"::: ### Add or subtract time -There are three methods used to adjust a structure: , , and . Both `AddHours` and `AddMinutes` take an integer parameter, and adjust the value accordingly. You can use a negative value to subtract and a positive value to add. The methods return a new instance of `TimeOnly` is returned, as the structure is immutable. The `Add` method takes a parameter and adds or subtracts the value from the `TimeOnly` value. +There are three methods used to adjust a structure: , , and . Both `AddHours` and `AddMinutes` take an integer parameter, and adjust the value accordingly. You can use a negative value to subtract and a positive value to add. The methods return a new instance of `TimeOnly` is returned, as the structure is immutable. The `Add` method takes a parameter and adds or subtracts the value from the `TimeOnly` value. Because `TimeOnly` only represents a 24-hour period, it rolls over forwards or backwards appropriately when adding values supplied to those three methods. For example, if you use a value of `01:30:00` to represent 1:30 AM, then add -4 hours from that period, it rolls backwards to `21:30:00`, which is 9:30 PM. There are method overloads for `AddHours`, `AddMinutes`, and `Add` that capture the number of days rolled over. @@ -142,9 +142,9 @@ The following example serializes an `Appointment` object, displays the resulting In the preceding code: - An `Appointment` object is instantiated and assigned to the `appointment` variable. -- The `appointment` instance is serialized to JSON using . +- The `appointment` instance is serialized to JSON using . - The resulting JSON is written to the console. -- The JSON is deserialized back into a new instance of the `Appointment` type using . +- The JSON is deserialized back into a new instance of the `Appointment` type using . - The original and newly deserialized instances are compared for equality. - The result of the comparison is written to the console. @@ -166,7 +166,7 @@ The following example creates a `DateTime` from a `TimeOnly` object, with an arb ### Arithmetic operators and comparing TimeOnly -Two instances can be compared with one another, and you can use the method to check if a time is between two other times. When an addition or subtraction operator is used on a `TimeOnly`, a is returned, representing a duration of time. +Two instances can be compared with one another, and you can use the method to check if a time is between two other times. When an addition or subtraction operator is used on a `TimeOnly`, a is returned, representing a duration of time. :::code language="csharp" source="./snippets/how-to-use-dateonly-timeonly/csharp/Program.cs" id="time_between"::: :::code language="vb" source="./snippets/how-to-use-dateonly-timeonly/vb/Program.vb" id="time_between"::: diff --git a/docs/standard/datetime/instantiate-time-zone-info.md b/docs/standard/datetime/instantiate-time-zone-info.md index 622ef6a8a585f..c77dba7f17ebf 100644 --- a/docs/standard/datetime/instantiate-time-zone-info.md +++ b/docs/standard/datetime/instantiate-time-zone-info.md @@ -12,10 +12,10 @@ ms.topic: how-to --- # How to: Obtain a TimeZoneInfo object -The most common way to obtain a object is to retrieve information about it from the registry. To obtain the object, call the `static` (`Shared` in Visual Basic) method, which looks in the registry. Handle any exceptions thrown by the method, particularly the that's thrown if the time zone isn't defined in the registry. +The most common way to obtain a object is to retrieve information about it from the registry. To obtain the object, call the `static` (`Shared` in Visual Basic) method, which looks in the registry. Handle any exceptions thrown by the method, particularly the that's thrown if the time zone isn't defined in the registry. > [!NOTE] -> Starting in .NET 8, returns a cached object instead of instantiating a new object. For more information, see [FindSystemTimeZoneById doesn't return new object](../../core/compatibility/core-libraries/8.0/timezoneinfo-object.md). +> Starting in .NET 8, returns a cached object instead of instantiating a new object. For more information, see [FindSystemTimeZoneById doesn't return new object](../../core/compatibility/core-libraries/8.0/timezoneinfo-object.md). ## Example @@ -24,11 +24,11 @@ The following code retrieves a object that represents [!code-csharp[System.TimeZone2.Concepts#5](./snippets/timezone-concepts/TimeZone2Concepts.cs#5)] [!code-vb[System.TimeZone2.Concepts#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#5)] -The method's single parameter is the identifier of the time zone that you want to retrieve, which corresponds to the object's property. The time zone identifier is a key field that uniquely identifies the time zone. While most keys are relatively short, the time zone identifier is comparatively long. In most cases, its value corresponds to the property of a object, which is used to provide the name of the time zone's standard time. However, there are exceptions. The best way to make sure that you supply a valid identifier is to enumerate the time zones available on your system and note the identifiers of the time zones present on them. For an illustration, see [How to: Enumerate time zones present on a computer](enumerate-time-zones.md). The [Finding the time zones defined on a local system](finding-the-time-zones-on-local-system.md) article also contains a list of selected time-zone identifiers. +The method's single parameter is the identifier of the time zone that you want to retrieve, which corresponds to the object's property. The time zone identifier is a key field that uniquely identifies the time zone. While most keys are relatively short, the time zone identifier is comparatively long. In most cases, its value corresponds to the property of a object, which is used to provide the name of the time zone's standard time. However, there are exceptions. The best way to make sure that you supply a valid identifier is to enumerate the time zones available on your system and note the identifiers of the time zones present on them. For an illustration, see [How to: Enumerate time zones present on a computer](enumerate-time-zones.md). The [Finding the time zones defined on a local system](finding-the-time-zones-on-local-system.md) article also contains a list of selected time-zone identifiers. If the time zone is found, the method returns its object. If the time zone is not found, the method throws a . If the time zone is found but its data is corrupted or incomplete, the method throws an . -If your application relies on a time zone that must be present, you should first call the method to retrieve the time zone information from the registry. If the method call fails, your exception handler should then either create a new instance of the time zone or re-create it by deserializing a serialized object. See [How to: Restore time zones from an embedded resource](restore-time-zones-from-an-embedded-resource.md) for an example. +If your application relies on a time zone that must be present, you should first call the method to retrieve the time zone information from the registry. If the method call fails, your exception handler should then either create a new instance of the time zone or re-create it by deserializing a serialized object. See [How to: Restore time zones from an embedded resource](restore-time-zones-from-an-embedded-resource.md) for an example. ## See also diff --git a/docs/standard/datetime/instantiating-a-datetimeoffset-object.md b/docs/standard/datetime/instantiating-a-datetimeoffset-object.md index acb583141a1e6..f02f5cb411844 100644 --- a/docs/standard/datetime/instantiating-a-datetimeoffset-object.md +++ b/docs/standard/datetime/instantiating-a-datetimeoffset-object.md @@ -2,10 +2,10 @@ title: "Instantiating a DateTimeOffset object" description: Read how to instantiate (make an instance of) a DateTimeOffset object in .NET. Learn about date & time literals, constructors, implicit type conversion, & more. ms.date: "04/10/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "instantiating time zone objects" - "time zone objects [.NET], instantiation" - "DateTimeOffset structure, converting to DateTime" @@ -47,7 +47,7 @@ The type defines six constructors. Four of them cor Note that, when the value of the object instantiated using a object as one of the arguments to its constructor is displayed to the console, it is expressed as a date in the Gregorian rather than the Persian calendar. To output a date using the Persian calendar, see the example in the topic. -The other two constructors create a object from a value. The first of these has a single parameter, the value to convert to a value. The offset of the resulting value depends on the property of the constructor's single parameter. If its value is , the offset is set equal to . Otherwise, its offset is set equal to that of the local time zone. The following example illustrates the use of this constructor to instantiate objects representing UTC and the local time zone: +The other two constructors create a object from a value. The first of these has a single parameter, the value to convert to a value. The offset of the resulting value depends on the property of the constructor's single parameter. If its value is , the offset is set equal to . Otherwise, its offset is set equal to that of the local time zone. The following example illustrates the use of this constructor to instantiate objects representing UTC and the local time zone: :::code language="csharp" source="./snippets/instantiating-a-datetimeoffset-object/csharp/Instantiate.cs" id="4"::: :::code language="vb" source="./snippets/instantiating-a-datetimeoffset-object/vb/Instantiate.vb" id="4"::: @@ -55,7 +55,7 @@ The other two constructors create a object from a < > [!NOTE] > Calling the overload of the constructor that has a single parameter is equivalent to performing an implicit conversion of a value to a value. -The second constructor that creates a object from a value has two parameters: the value to convert, and a value representing the date and time's offset from UTC. This offset value must correspond to the property of the constructor's first parameter or an is thrown. If the property of the first parameter is , the value of the second parameter must be . If the property of the first parameter is , the value of the second parameter must be the offset of the local system's time zone. If the property of the first parameter is , the offset can be any valid value. The following code illustrates calls to this constructor to convert to values. +The second constructor that creates a object from a value has two parameters: the value to convert, and a value representing the date and time's offset from UTC. This offset value must correspond to the property of the constructor's first parameter or an is thrown. If the property of the first parameter is , the value of the second parameter must be . If the property of the first parameter is , the value of the second parameter must be the offset of the local system's time zone. If the property of the first parameter is , the offset can be any valid value. The following code illustrates calls to this constructor to convert to values. :::code language="csharp" source="./snippets/instantiating-a-datetimeoffset-object/csharp/Instantiate.cs" id="5"::: :::code language="vb" source="./snippets/instantiating-a-datetimeoffset-object/vb/Instantiate.vb" id="5"::: @@ -67,19 +67,19 @@ The type supports one *implicit* type conversion: f :::code language="csharp" source="./snippets/instantiating-a-datetimeoffset-object/csharp/Instantiate.cs" id="6"::: :::code language="vb" source="./snippets/instantiating-a-datetimeoffset-object/vb/Instantiate.vb" id="6"::: -The offset of the resulting value depends on the property value. If its value is , the offset is set equal to . If its value is either or , the offset is set equal to that of the local time zone. +The offset of the resulting value depends on the property value. If its value is , the offset is set equal to . If its value is either or , the offset is set equal to that of the local time zone. ## Parsing the string representation of a date and time The type supports four methods that allow you to convert the string representation of a date and time into a value: -- , which tries to convert the string representation of a date and time to a value and throws an exception if the conversion fails. +- , which tries to convert the string representation of a date and time to a value and throws an exception if the conversion fails. -- , which tries to convert the string representation of a date and time to a value and returns `false` if the conversion fails. +- , which tries to convert the string representation of a date and time to a value and returns `false` if the conversion fails. -- , which tries to convert the string representation of a date and time in a specified format to a value. The method throws an exception if the conversion fails. +- , which tries to convert the string representation of a date and time in a specified format to a value. The method throws an exception if the conversion fails. -- , which tries to convert the string representation of a date and time in a specified format to a value. The method returns `false` if the conversion fails. +- , which tries to convert the string representation of a date and time in a specified format to a value. The method returns `false` if the conversion fails. The following example illustrates calls to each of these four string conversion methods to instantiate a value. diff --git a/docs/standard/datetime/let-users-resolve-ambiguous-times.md b/docs/standard/datetime/let-users-resolve-ambiguous-times.md index c09ee482f0512..9081e78989893 100644 --- a/docs/standard/datetime/let-users-resolve-ambiguous-times.md +++ b/docs/standard/datetime/let-users-resolve-ambiguous-times.md @@ -21,15 +21,15 @@ This topic shows how to let a user resolve an ambiguous time. 1. Get the date and time input by the user. -2. Call the method to determine whether the time is ambiguous. +2. Call the method to determine whether the time is ambiguous. -3. If the time is ambiguous, call the method to retrieve an array of objects. Each element in the array contains a UTC offset that the ambiguous time can map to. +3. If the time is ambiguous, call the method to retrieve an array of objects. Each element in the array contains a UTC offset that the ambiguous time can map to. 4. Let the user select the desired offset. 5. Get the UTC date and time by subtracting the offset selected by the user from the local time. -6. Call the `static` (`Shared` in Visual Basic .NET) method to set the UTC date and time value's property to . +6. Call the `static` (`Shared` in Visual Basic .NET) method to set the UTC date and time value's property to . ## Example @@ -38,9 +38,9 @@ The following example prompts the user to enter a date and time and, if it is am [!code-csharp[System.TimeZone2.Concepts#11](./snippets/timezone-concepts/TimeZone2Concepts.cs#11)] [!code-vb[System.TimeZone2.Concepts#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#11)] -The core of the example code uses an array of objects to indicate possible offsets of the ambiguous time from UTC. However, these offsets are unlikely to be meaningful to the user. To clarify the meaning of the offsets, the code also notes whether an offset represents the local time zone's standard time or its daylight saving time. The code determines which time is standard and which time is daylight by comparing the offset with the value of the property. This property indicates the difference between the UTC and the time zone's standard time. +The core of the example code uses an array of objects to indicate possible offsets of the ambiguous time from UTC. However, these offsets are unlikely to be meaningful to the user. To clarify the meaning of the offsets, the code also notes whether an offset represents the local time zone's standard time or its daylight saving time. The code determines which time is standard and which time is daylight by comparing the offset with the value of the property. This property indicates the difference between the UTC and the time zone's standard time. -In this example, all references to the local time zone are made through the property; the local time zone is never assigned to an object variable. This is a recommended practice because a call to the method invalidates any objects that the local time zone is assigned to. +In this example, all references to the local time zone are made through the property; the local time zone is never assigned to an object variable. This is a recommended practice because a call to the method invalidates any objects that the local time zone is assigned to. ## See also diff --git a/docs/standard/datetime/performing-arithmetic-operations.md b/docs/standard/datetime/performing-arithmetic-operations.md index 47bb879940a54..87c47afde2e14 100644 --- a/docs/standard/datetime/performing-arithmetic-operations.md +++ b/docs/standard/datetime/performing-arithmetic-operations.md @@ -2,10 +2,10 @@ description: "Learn more about: Performing arithmetic operations with dates and times" title: "Performing arithmetic operations with dates and times" ms.date: "04/10/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "times [.NET], arithmetic operations" - "dates [.NET], arithmetic operations" - "time zones [.NET], arithmetic operations" @@ -21,18 +21,18 @@ Although both the and the st ## Comparisons and arithmetic operations with DateTime values -The property allows a value to be assigned to the date and time to indicate whether it represents local time, Coordinated Universal Time (UTC), or the time in an unspecified time zone. However, this limited time zone information is ignored when comparing or performing date and time arithmetic on values. The following example, which compares the current local time with the current UTC time, illustrates how the time zone information is ignored. +The property allows a value to be assigned to the date and time to indicate whether it represents local time, Coordinated Universal Time (UTC), or the time in an unspecified time zone. However, this limited time zone information is ignored when comparing or performing date and time arithmetic on values. The following example, which compares the current local time with the current UTC time, illustrates how the time zone information is ignored. [!code-csharp[System.DateTimeOffset.Conceptual#2](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual/cs/Conceptual2.cs#2)] [!code-vb[System.DateTimeOffset.Conceptual#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual/vb/Conceptual2.vb#2)] The method reports that the local time is earlier than (or less than) the UTC time, and the subtraction operation indicates that the difference between UTC and the local time for a system in the U.S. Pacific Standard Time zone is seven hours. But because these two values provide different representations of a single point in time, it's clear in this case that the time interval is completely attributable to the local time zone's offset from UTC. -More generally, the property does not affect the results returned by comparison and arithmetic methods (as the comparison of two identical points in time indicates), although it can affect the interpretation of those results. For example: +More generally, the property does not affect the results returned by comparison and arithmetic methods (as the comparison of two identical points in time indicates), although it can affect the interpretation of those results. For example: -- The result of any arithmetic operation performed on two date and time values whose properties both equal reflects the actual time interval between the two values. Similarly, the comparison of two such date and time values accurately reflects the relationship between times. +- The result of any arithmetic operation performed on two date and time values whose properties both equal reflects the actual time interval between the two values. Similarly, the comparison of two such date and time values accurately reflects the relationship between times. -- The result of any arithmetic or comparison operation performed on two date and time values whose properties both equal or on two date and time values with different property values reflects the difference in clock time between the two values. +- The result of any arithmetic or comparison operation performed on two date and time values whose properties both equal or on two date and time values with different property values reflects the difference in clock time between the two values. - Arithmetic or comparison operations on local date and time values do not consider whether a particular value is ambiguous or invalid, nor do they take account of the effect of any adjustment rules that result from the local time zone's transition to or from daylight saving time. @@ -51,7 +51,7 @@ A value includes not only a date and time, but also [!code-csharp[System.DateTimeOffset.Conceptual#3](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual/cs/Conceptual3.cs#3)] [!code-vb[System.DateTimeOffset.Conceptual#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual/vb/Conceptual3.vb#3)] -In this example, the method indicates that the current local time and the current UTC time are equal, and subtraction of values indicates that the difference between the two times is . +In this example, the method indicates that the current local time and the current UTC time are equal, and subtraction of values indicates that the difference between the two times is . The chief limitation of using values in date and time arithmetic is that although values have some time zone awareness, they are not fully time zone aware. Although the value's offset reflects a time zone's offset from UTC when a variable is first assigned a value, it becomes disassociated from the time zone thereafter. Because it is no longer directly associated with an identifiable time, the addition and subtraction of date and time intervals does not consider a time zone's adjustment rules. @@ -64,9 +64,9 @@ To illustrate, the transition to daylight saving time in the U.S. Central Standa The class includes conversion methods that automatically apply adjustments when they convert times from one time zone to another. These conversion methods include: -- The and methods, which convert times between any two time zones. +- The and methods, which convert times between any two time zones. -- The and methods, which convert the time in a particular time zone to UTC, or convert UTC to the time in a particular time zone. +- The and methods, which convert the time in a particular time zone to UTC, or convert UTC to the time in a particular time zone. For details, see [Converting times between time zones](converting-between-time-zones.md). diff --git a/docs/standard/datetime/resolve-ambiguous-times.md b/docs/standard/datetime/resolve-ambiguous-times.md index 9de30b32cad99..33ccd45623bbc 100644 --- a/docs/standard/datetime/resolve-ambiguous-times.md +++ b/docs/standard/datetime/resolve-ambiguous-times.md @@ -22,11 +22,11 @@ This topic shows how to resolve an ambiguous time by assuming that it represents ### To map an ambiguous time to a time zone's standard time -1. Call the method to determine whether the time is ambiguous. +1. Call the method to determine whether the time is ambiguous. -2. If the time is ambiguous, subtract the time from the object returned by the time zone's property. +2. If the time is ambiguous, subtract the time from the object returned by the time zone's property. -3. Call the `static` (`Shared` in Visual Basic .NET) method to set the UTC date and time value's property to . +3. Call the `static` (`Shared` in Visual Basic .NET) method to set the UTC date and time value's property to . ## Example @@ -35,11 +35,11 @@ The following example illustrates how to convert an ambiguous time to UTC by ass [!code-csharp[System.TimeZone2.Concepts#10](./snippets/timezone-concepts/TimeZone2Concepts.cs#10)] [!code-vb[System.TimeZone2.Concepts#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#10)] -The example consists of a method named `ResolveAmbiguousTime` that determines whether the value passed to it is ambiguous. If the value is ambiguous, the method returns a value that represents the corresponding UTC time. The method handles this conversion by subtracting the value of the local time zone's property from the local time. +The example consists of a method named `ResolveAmbiguousTime` that determines whether the value passed to it is ambiguous. If the value is ambiguous, the method returns a value that represents the corresponding UTC time. The method handles this conversion by subtracting the value of the local time zone's property from the local time. -Ordinarily, an ambiguous time is handled by calling the method to retrieve an array of objects that contain the ambiguous time's possible UTC offsets. However, this example makes the arbitrary assumption that an ambiguous time should always be mapped to the time zone's standard time. The property returns the offset between UTC and a time zone's standard time. +Ordinarily, an ambiguous time is handled by calling the method to retrieve an array of objects that contain the ambiguous time's possible UTC offsets. However, this example makes the arbitrary assumption that an ambiguous time should always be mapped to the time zone's standard time. The property returns the offset between UTC and a time zone's standard time. -In this example, all references to the local time zone are made through the property; the local time zone is never assigned to an object variable. This is a recommended practice because a call to the method invalidates any objects that the local time zone is assigned to. +In this example, all references to the local time zone are made through the property; the local time zone is never assigned to an object variable. This is a recommended practice because a call to the method invalidates any objects that the local time zone is assigned to. ## See also diff --git a/docs/standard/datetime/restore-time-zones-from-an-embedded-resource.md b/docs/standard/datetime/restore-time-zones-from-an-embedded-resource.md index 4d1a8b1fc9d25..ca37f75291c9b 100644 --- a/docs/standard/datetime/restore-time-zones-from-an-embedded-resource.md +++ b/docs/standard/datetime/restore-time-zones-from-an-embedded-resource.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Restore time zones from an embedded resource" title: "How to: Restore time zones from an embedded resource" ms.date: "04/10/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "time zones [.NET], deserializing" - "time zones [.NET], restoring" ms.topic: how-to @@ -16,17 +16,17 @@ This topic describes how to restore time zones that have been saved in a resourc ### To deserialize a TimeZoneInfo object from an embedded resource -1. If the time zone to be retrieved is not a custom time zone, try to instantiate it by using the method. +1. If the time zone to be retrieved is not a custom time zone, try to instantiate it by using the method. 2. Instantiate a object by passing the fully qualified name of the embedded resource file and a reference to the assembly that contains the resource file. If you cannot determine the fully qualified name of the embedded resource file, use the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) to examine the assembly's manifest. An `.mresource` entry identifies the resource. In the example, the resource's fully qualified name is `SerializeTimeZoneData.SerializedTimeZones`. - If the resource file is embedded in the same assembly that contains the time zone instantiation code, you can retrieve a reference to it by calling the `static` (`Shared` in Visual Basic) method. + If the resource file is embedded in the same assembly that contains the time zone instantiation code, you can retrieve a reference to it by calling the `static` (`Shared` in Visual Basic) method. -3. If the call to the method fails, or if a custom time zone is to be instantiated, retrieve a string that contains the serialized time zone by calling the method. +3. If the call to the method fails, or if a custom time zone is to be instantiated, retrieve a string that contains the serialized time zone by calling the method. -4. Deserialize the time zone data by calling the method. +4. Deserialize the time zone data by calling the method. ## Example @@ -35,9 +35,9 @@ The following example deserializes a object stored in [!code-csharp[TimeZone2.Serialization#3](../../../samples/snippets/csharp/VS_Snippets_CLR/TimeZone2.Serialization/cs/SerializeTimeZoneData.cs#3)] [!code-vb[TimeZone2.Serialization#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/TimeZone2.Serialization/vb/SerializeTimeZoneData.vb#3)] -This code illustrates exception handling to ensure that a object required by the application is present. It first tries to instantiate a object by retrieving it from the registry using the method. If the time zone cannot be instantiated, the code retrieves it from the embedded resource file. +This code illustrates exception handling to ensure that a object required by the application is present. It first tries to instantiate a object by retrieving it from the registry using the method. If the time zone cannot be instantiated, the code retrieves it from the embedded resource file. -Because data for custom time zones (time zones instantiated by using the method) are not stored in the registry, the code does not call the to instantiate the time zone for Palmer, Antarctica. Instead, it immediately looks to the embedded resource file to retrieve a string that contains the time zone's data before it calls the method. +Because data for custom time zones (time zones instantiated by using the method) are not stored in the registry, the code does not call the to instantiate the time zone for Palmer, Antarctica. Instead, it immediately looks to the embedded resource file to retrieve a string that contains the time zone's data before it calls the method. ## Compiling the code diff --git a/docs/standard/datetime/save-time-zones-to-an-embedded-resource.md b/docs/standard/datetime/save-time-zones-to-an-embedded-resource.md index 1a076e2b4be4e..c98cc51cccbb8 100644 --- a/docs/standard/datetime/save-time-zones-to-an-embedded-resource.md +++ b/docs/standard/datetime/save-time-zones-to-an-embedded-resource.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Save time zones to an embedded resource" title: "How to: Save time zones to an embedded resource" ms.date: "04/10/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "time zones [.NET], saving" - "time zone objects [.NET], serializing" - "time zone objects [.NET], saving" @@ -13,7 +13,7 @@ ms.topic: how-to --- # How to: Save time zones to an embedded resource -A time zone-aware application often requires the presence of a particular time zone. However, because the availability of individual objects depends on information stored in the local system's registry, even customarily available time zones may be absent. In addition, information about custom time zones instantiated by using the method is not stored with other time zone information in the registry. To ensure that these time zones are available when they are needed, you can save them by serializing them, and later restore them by deserializing them. +A time zone-aware application often requires the presence of a particular time zone. However, because the availability of individual objects depends on information stored in the local system's registry, even customarily available time zones may be absent. In addition, information about custom time zones instantiated by using the method is not stored with other time zone information in the registry. To ensure that these time zones are available when they are needed, you can save them by serializing them, and later restore them by deserializing them. Typically, serializing a object occurs apart from the time zone-aware application. Depending on the data store used to hold serialized objects, time zone data may be serialized as part of a setup or installation routine (for example, when the data is stored in an application key of the registry), or as part of a utility routine that runs before the final application is compiled (for example, when the serialized data is stored in a .NET XML resource (.resx) file). @@ -31,21 +31,21 @@ In addition to a resource file that is compiled with the application, several ot To retrieve an existing time zone, see [How to: Access the predefined UTC and local time zone objects](access-utc-and-local.md) and [How to: Instantiate a TimeZoneInfo object](instantiate-time-zone-info.md). - To create a new time zone, call one of the overloads of the method. For more information, see [How to: Create time zones without adjustment rules](create-time-zones-without-adjustment-rules.md) and [How to: Create time zones with adjustment rules](create-time-zones-with-adjustment-rules.md). + To create a new time zone, call one of the overloads of the method. For more information, see [How to: Create time zones without adjustment rules](create-time-zones-without-adjustment-rules.md) and [How to: Create time zones with adjustment rules](create-time-zones-with-adjustment-rules.md). -2. Call the method to create a string that contains the time zone's data. +2. Call the method to create a string that contains the time zone's data. 3. Instantiate a object by providing the name and optionally the path of the .resx file to the class constructor. 4. Instantiate a object by passing the object to the class constructor. -5. Pass the time zone's serialized string to the method. +5. Pass the time zone's serialized string to the method. -6. Call the method. +6. Call the method. -7. Call the method. +7. Call the method. -8. Close the object by calling its method. +8. Close the object by calling its method. 9. Add the generated .resx file to the application's Visual Studio project. @@ -60,7 +60,7 @@ The following example serializes a object that repres This example serializes objects so that they are available in a resource file at compile time. -Because the method adds complete header information to a .NET XML resource file, it cannot be used to add resources to an existing file. The example handles this by checking for the SerializedTimeZones.resx file and, if it exists, storing all of its resources other than the two serialized time zones to a generic object. The existing file is then deleted and the existing resources are added to a new SerializedTimeZones.resx file. The serialized time zone data is also added to this file. +Because the method adds complete header information to a .NET XML resource file, it cannot be used to add resources to an existing file. The example handles this by checking for the SerializedTimeZones.resx file and, if it exists, storing all of its resources other than the two serialized time zones to a generic object. The existing file is then deleted and the existing resources are added to a new SerializedTimeZones.resx file. The serialized time zone data is also added to this file. The key (or **Name**) fields of resources should not contain embedded spaces. The method is called to remove all embedded spaces in the time zone identifiers before they are assigned to the resource file. diff --git a/docs/standard/datetime/saving-and-restoring-time-zones.md b/docs/standard/datetime/saving-and-restoring-time-zones.md index ac0c10445df65..ce7d56123cd99 100644 --- a/docs/standard/datetime/saving-and-restoring-time-zones.md +++ b/docs/standard/datetime/saving-and-restoring-time-zones.md @@ -2,10 +2,10 @@ description: "Learn more about: Saving and restoring time zones" title: "Saving and restoring time zones" ms.date: "04/10/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "restoring time zones" - "deserialization [.NET], time zones" - "serialization [.NET], time zones" @@ -32,9 +32,9 @@ The class addresses these limitations through its sup Saving and restoring a time zone by serializing and deserializing time zone data involves just two method calls: -- You can serialize a object by calling that object's method. The method takes no parameters and returns a string that contains time zone information. +- You can serialize a object by calling that object's method. The method takes no parameters and returns a string that contains time zone information. -- You can deserialize a object from a serialized string by passing that string to the `static` (`Shared` in Visual Basic) method. +- You can deserialize a object from a serialized string by passing that string to the `static` (`Shared` in Visual Basic) method. ## Serialization and deserialization scenarios diff --git a/docs/standard/datetime/system-text-json-support.md b/docs/standard/datetime/system-text-json-support.md index 8d67d2948aaf5..3db92fc917ae2 100644 --- a/docs/standard/datetime/system-text-json-support.md +++ b/docs/standard/datetime/system-text-json-support.md @@ -16,7 +16,7 @@ helpviewer_keywords: # DateTime and DateTimeOffset support in System.Text.Json The `System.Text.Json` library parses and writes and values according to the ISO 8601-1:2019 extended profile. -[Converters](xref:System.Text.Json.Serialization.JsonConverter%601) provide custom support for serializing and deserializing with . You can also use and to implement custom support. +[Converters](xref:System.Text.Json.Serialization.JsonConverter`1) provide custom support for serializing and deserializing with . You can also use and to implement custom support. ## Support for the ISO 8601-1:2019 format @@ -72,9 +72,9 @@ The following example serializes an `Appointment` object, displays the resulting In the preceding code: - An `Appointment` object is instantiated and assigned to the `appointment` variable. -- The `appointment` instance is serialized to JSON using . +- The `appointment` instance is serialized to JSON using . - The resulting JSON is written to the console. -- The JSON is deserialized back into a new instance of the `Appointment` type using . +- The JSON is deserialized back into a new instance of the `Appointment` type using . - The original and newly deserialized instances are compared for equality. - The result of the comparison is written to the console. @@ -82,7 +82,7 @@ In the preceding code: ### When using -If you want the serializer to perform custom parsing or formatting, you can implement [custom converters](xref:System.Text.Json.Serialization.JsonConverter%601). The following sections show a few examples: +If you want the serializer to perform custom parsing or formatting, you can implement [custom converters](xref:System.Text.Json.Serialization.JsonConverter`1). The following sections show a few examples: - [DateTime(Offset).Parse and DateTime(Offset).ToString](#datetimeoffsetparse-and-datetimeoffsettostring) - [Utf8Parser and Utf8Formatter](#-and-) @@ -102,7 +102,7 @@ This approach is also less performant than using the serializer's native impleme :::code language="csharp" source="snippets/system-text-json-support/csharp/datetime-converter-examples/example1/Program.cs"::: > [!NOTE] -> When implementing , and `T` is , the `typeToConvert` parameter will always be `typeof(DateTime)`. +> When implementing , and `T` is , the `typeToConvert` parameter will always be `typeof(DateTime)`. The parameter is useful for handling polymorphic cases and when using generics to get `typeof(T)` in a performant way. #### and @@ -143,8 +143,8 @@ The following converters handle Unix epoch format with or without a time zone of If you want to write a custom or text representation with , you can format your custom representation to a , `ReadOnlySpan`, `ReadOnlySpan`, or , -then pass it to the corresponding -or method. +then pass it to the corresponding +or method. The following example shows how a custom format can be created with and then written with the method: diff --git a/docs/standard/datetime/time-zone-overview.md b/docs/standard/datetime/time-zone-overview.md index 4db52e3ad91a4..fc69626fa0603 100644 --- a/docs/standard/datetime/time-zone-overview.md +++ b/docs/standard/datetime/time-zone-overview.md @@ -2,7 +2,7 @@ description: "Learn more about: Time zone overview" title: "Time zone overview" ms.date: "04/10/2017" -helpviewer_keywords: +helpviewer_keywords: - "time zones [.NET], about time zones" - "transition time [.NET]" - "TimeZoneInfo class, about TimeZoneInfo class" @@ -45,23 +45,23 @@ The following table defines terms commonly used when working with time zones and ## Time zones and the TimeZoneInfo class -In .NET, a object represents a time zone. The class includes a method that returns an array of objects. Each element of this array provides information about the transition to and from daylight saving time for a particular time period. (For time zones that do not support daylight saving time, the method returns an empty array.) Each object has a and a property that defines the particular date and time of the transition to and from daylight saving time. The property indicates whether that transition is fixed or floating. +In .NET, a object represents a time zone. The class includes a method that returns an array of objects. Each element of this array provides information about the transition to and from daylight saving time for a particular time period. (For time zones that do not support daylight saving time, the method returns an empty array.) Each object has a and a property that defines the particular date and time of the transition to and from daylight saving time. The property indicates whether that transition is fixed or floating. .NET relies on time zone information provided by the Windows operating system and stored in the registry. Due to the number of the earth's time zones, not all existing time zones are represented in the registry. In addition, because the registry is a dynamic structure, predefined time zones can be added to or removed from it. Finally, the registry does not necessarily contain historic time zone data. For example, in Windows XP the registry contains data about only a single set of time zone adjustments. Windows Vista supports dynamic time zone data, which means that a single time zone can have multiple adjustment rules that apply to specific intervals of years. However, most time zones that are defined in the Windows Vista registry and support daylight saving time have only one or two predefined adjustment rules. The dependence of the class on the registry means that a time zone-aware application cannot be certain that a particular time zone is defined in the registry. As a result, the attempt to instantiate a specific time zone (other than the local time zone or the time zone that represents UTC) should use exception handling. It should also provide some method of letting the application to continue if a required object cannot be instantiated from the registry. -To handle the absence of a required time zone, the class includes a method, which you can use to create custom time zones that are not found in the registry. For details on creating a custom time zone, see [How to: Create time zones without adjustment rules](create-time-zones-without-adjustment-rules.md) and [How to: Create time zones with adjustment rules](create-time-zones-with-adjustment-rules.md). In addition, you can use the method to convert a newly created time zone to a string and save it in a data store (such as a database, a text file, the registry, or an application resource). You can then use the method to convert this string back to a object. For details, see [How to: Save time zones to an embedded resource](save-time-zones-to-an-embedded-resource.md) and [How to: Restore time zones from an embedded resource](restore-time-zones-from-an-embedded-resource.md). +To handle the absence of a required time zone, the class includes a method, which you can use to create custom time zones that are not found in the registry. For details on creating a custom time zone, see [How to: Create time zones without adjustment rules](create-time-zones-without-adjustment-rules.md) and [How to: Create time zones with adjustment rules](create-time-zones-with-adjustment-rules.md). In addition, you can use the method to convert a newly created time zone to a string and save it in a data store (such as a database, a text file, the registry, or an application resource). You can then use the method to convert this string back to a object. For details, see [How to: Save time zones to an embedded resource](save-time-zones-to-an-embedded-resource.md) and [How to: Restore time zones from an embedded resource](restore-time-zones-from-an-embedded-resource.md). Because each time zone is characterized by a base offset from UTC, as well as by an offset from UTC that reflects any existing adjustment rules, a time in one time zone can be easily converted to the time in another time zone. For this purpose, the object includes several conversion methods, including: -- , which converts UTC to the time in a designated time zone. +- , which converts UTC to the time in a designated time zone. -- , which converts the time in a designated time zone to UTC. +- , which converts the time in a designated time zone to UTC. -- , which converts the time in one designated time zone to the time in another designated time zone. +- , which converts the time in one designated time zone to the time in another designated time zone. -- , which uses time zone identifiers (instead of objects) as parameters to convert the time in one designated time zone to the time in another designated time zone. +- , which uses time zone identifiers (instead of objects) as parameters to convert the time in one designated time zone to the time in another designated time zone. For details on converting times between time zones, see [Converting times between time zones](converting-between-time-zones.md). diff --git a/docs/standard/datetime/use-time-zones-in-arithmetic.md b/docs/standard/datetime/use-time-zones-in-arithmetic.md index 62e1f1dd8efd6..8e089307542ef 100644 --- a/docs/standard/datetime/use-time-zones-in-arithmetic.md +++ b/docs/standard/datetime/use-time-zones-in-arithmetic.md @@ -13,7 +13,7 @@ ms.topic: how-to --- # How to: Use time zones in date and time arithmetic -Ordinarily, when you perform date and time arithmetic using or values, the result does not reflect any time zone adjustment rules. This is true even when the time zone of the date and time value is clearly identifiable (for example, when the property is set to ). This topic shows how to perform arithmetic operations on date and time values that belong to a particular time zone. The results of the arithmetic operations will reflect the time zone's adjustment rules. +Ordinarily, when you perform date and time arithmetic using or values, the result does not reflect any time zone adjustment rules. This is true even when the time zone of the date and time value is clearly identifiable (for example, when the property is set to ). This topic shows how to perform arithmetic operations on date and time values that belong to a particular time zone. The results of the arithmetic operations will reflect the time zone's adjustment rules. ### To apply adjustment rules to date and time arithmetic @@ -22,7 +22,7 @@ Ordinarily, when you perform date and time arithmetic using method or the method. +2. Convert a time to Coordinated Universal Time (UTC) by calling either the method or the method. 3. Perform the arithmetic operation on the UTC time. diff --git a/docs/standard/datetime/working-with-calendars.md b/docs/standard/datetime/working-with-calendars.md index afaaf09f563a2..6b6c6767852d2 100644 --- a/docs/standard/datetime/working-with-calendars.md +++ b/docs/standard/datetime/working-with-calendars.md @@ -24,7 +24,7 @@ All calendars in .NET derive from the , which represents the Chinese lunisolar calendar. -- , which represents the Gregorian calendar. This calendar is further divided into subtypes (such as Arabic and Middle East French) that are defined by the enumeration. The property specifies the subtype of the Gregorian calendar. +- , which represents the Gregorian calendar. This calendar is further divided into subtypes (such as Arabic and Middle East French) that are defined by the enumeration. The property specifies the subtype of the Gregorian calendar. - , which represents the Hebrew calendar. @@ -60,14 +60,14 @@ Note that six calendar classes – property. The property returns an array of objects that specifies all the calendars supported by a particular culture, including that culture's default calendar. +Each culture has a default calendar, which is defined by the property. The property returns an array of objects that specifies all the calendars supported by a particular culture, including that culture's default calendar. -The following example illustrates the and properties. It creates `CultureInfo` objects for the Thai (Thailand) and Japanese (Japan) cultures and displays their default and optional calendars. Note that in both cases, the culture's default calendar is also included in the collection. +The following example illustrates the and properties. It creates `CultureInfo` objects for the Thai (Thailand) and Japanese (Japan) cultures and displays their default and optional calendars. Note that in both cases, the culture's default calendar is also included in the collection. [!code-csharp[Conceptual.Calendars#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/calendarinfo1.cs#1)] [!code-vb[Conceptual.Calendars#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/calendarinfo1.vb#1)] -The calendar currently in use by a particular object is defined by the culture's property. A culture's object is returned by the property. When a culture is created, its default value is the same as the value of the property. However, you can change the culture's current calendar to any calendar contained in the array returned by the property. If you try to set the current calendar to a calendar that is not included in the property value, an is thrown. +The calendar currently in use by a particular object is defined by the culture's property. A culture's object is returned by the property. When a culture is created, its default value is the same as the value of the property. However, you can change the culture's current calendar to any calendar contained in the array returned by the property. If you try to set the current calendar to a calendar that is not included in the property value, an is thrown. The following example changes the calendar used by the Arabic (Saudi Arabia) culture. It first instantiates a value and displays it using the current culture - which, in this case, is English (United States) - and the current culture's calendar (which, in this case, is the Gregorian calendar). Next, it changes the current culture to Arabic (Saudi Arabia) and displays the date using its default Um Al-Qura calendar. It then calls the `CalendarExists` method to determine whether the Hijri calendar is supported by the Arabic (Saudi Arabia) culture. Because the calendar is supported, it changes the current calendar to Hijri and again displays the date. Note that in each case, the date is displayed using the current culture's current calendar. @@ -76,7 +76,7 @@ The following example changes the calendar used by the Arabic (Saudi Arabia) cul ## Dates and calendars -With the exception of the constructors that include a parameter of type and allow the elements of a date (that is, the month, the day, and the year) to reflect values in a designated calendar, both and values are always based on the Gregorian calendar. This means, for example, that the property returns the year in the Gregorian calendar, and the property returns the day of the month in the Gregorian calendar. +With the exception of the constructors that include a parameter of type and allow the elements of a date (that is, the month, the day, and the year) to reflect values in a designated calendar, both and values are always based on the Gregorian calendar. This means, for example, that the property returns the year in the Gregorian calendar, and the property returns the day of the month in the Gregorian calendar. > [!IMPORTANT] > It is important to remember that there is a difference between a date value and its string representation. The former is based on the Gregorian calendar; the latter is based on the current calendar of a specific culture. @@ -88,9 +88,9 @@ The following example illustrates this difference between ### Instantiate dates based on a calendar -Because and values are based on the Gregorian calendar, you must call an overloaded constructor that includes a parameter of type to instantiate a date value if you want to use the day, month, or year values from a different calendar. You can also call one of the overloads of a specific calendar's method to instantiate a object based on the values of a particular calendar. +Because and values are based on the Gregorian calendar, you must call an overloaded constructor that includes a parameter of type to instantiate a date value if you want to use the day, month, or year values from a different calendar. You can also call one of the overloads of a specific calendar's method to instantiate a object based on the values of a particular calendar. -The following example instantiates one value by passing a object to a constructor, and instantiates a second value by calling the method. Because the two values are created with identical values from the Hebrew calendar, the call to the method shows that the two values are equal. +The following example instantiates one value by passing a object to a constructor, and instantiates a second value by calling the method. Because the two values are created with identical values from the Hebrew calendar, the call to the method shows that the two values are equal. [!code-csharp[Conceptual.Calendars#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/instantiatehcdate1.cs#4)] [!code-vb[Conceptual.Calendars#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/instantiatehcdate1.vb#4)] @@ -106,7 +106,7 @@ The following example shows how the current calendar affects the string represen ### Represent dates in a non-current calendar -To represent a date using a calendar that is not the current calendar of a particular culture, you must call methods of that object. For example, the , , and methods convert the year, month, and day to values that reflect a particular calendar. +To represent a date using a calendar that is not the current calendar of a particular culture, you must call methods of that object. For example, the , , and methods convert the year, month, and day to values that reflect a particular calendar. > [!WARNING] > Because some calendars are not optional calendars of any culture, representing dates in these calendars always requires that you call calendar methods. This is true of all calendars that derive from the , , and classes. @@ -118,9 +118,9 @@ The following example uses a object t ### Calendars and date ranges -The earliest date supported by a calendar is indicated by that calendar's property. For the class, that date is January 1, 0001 C.E. Most of the other calendars in .NET support a later date. Trying to work with a date and time value that precedes a calendar's earliest supported date throws an exception. +The earliest date supported by a calendar is indicated by that calendar's property. For the class, that date is January 1, 0001 C.E. Most of the other calendars in .NET support a later date. Trying to work with a date and time value that precedes a calendar's earliest supported date throws an exception. -However, there is one important exception. The default (uninitialized) value of a object and a object is equal to the value. If you try to format this date in a calendar that does not support January 1, 0001 C.E. and you do not provide a format specifier, the formatting method uses the "s" (sortable date/time pattern) format specifier instead of the "G" (general date/time pattern) format specifier. As a result, the formatting operation does not throw an exception. Instead, it returns the unsupported date. This is illustrated in the following example, which displays the value of when the current culture is set to Japanese (Japan) with the Japanese calendar, and to Arabic (Egypt) with the Um Al Qura calendar. It also sets the current culture to English (United States) and calls the method with each of these objects. In each case, the date is displayed by using the sortable date/time pattern. +However, there is one important exception. The default (uninitialized) value of a object and a object is equal to the value. If you try to format this date in a calendar that does not support January 1, 0001 C.E. and you do not provide a format specifier, the formatting method uses the "s" (sortable date/time pattern) format specifier instead of the "G" (general date/time pattern) format specifier. As a result, the formatting operation does not throw an exception. Instead, it returns the unsupported date. This is illustrated in the following example, which displays the value of when the current culture is set to Japanese (Japan) with the Japanese calendar, and to Arabic (Egypt) with the Um Al Qura calendar. It also sets the current culture to English (United States) and calls the method with each of these objects. In each case, the date is displayed by using the sortable date/time pattern. [!code-csharp[Conceptual.Calendars#11](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/minsupporteddatetime1.cs#11)] [!code-vb[Conceptual.Calendars#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/minsupporteddatetime1.vb#11)] @@ -140,7 +140,7 @@ An era in most calendars denotes an extremely long time period. In the Gregorian ### Eras and era names -In .NET, integers that represent the eras supported by a particular calendar implementation are stored in reverse order in the array. The current era (which is the era with the latest time range) is at index zero, and for classes that support multiple eras, each successive index reflects the previous era. The static property defines the index of the current era in the array; it is a constant whose value is always zero. Individual classes also include static fields that return the value of the current era. They are listed in the following table. +In .NET, integers that represent the eras supported by a particular calendar implementation are stored in reverse order in the array. The current era (which is the era with the latest time range) is at index zero, and for classes that support multiple eras, each successive index reflects the previous era. The static property defines the index of the current era in the array; it is a constant whose value is always zero. Individual classes also include static fields that return the value of the current era. They are listed in the following table. | Calendar class | Current era field | | ----------------------------------------------------- | ----------------------------------------------------------------- | @@ -156,7 +156,7 @@ In .NET, integers that represent the eras supported by a particular calendar imp | | | | | | -The name that corresponds to a particular era number can be retrieved by passing the era number to the or method. The following example calls these methods to retrieve information about era support in the class. It displays the Gregorian calendar date that corresponds to January 1 of the second year of the current era, as well as the Gregorian calendar date that corresponds to January 1 of the second year of each supported Japanese calendar era. +The name that corresponds to a particular era number can be retrieved by passing the era number to the or method. The following example calls these methods to retrieve information about era support in the class. It displays the Gregorian calendar date that corresponds to January 1 of the second year of the current era, as well as the Gregorian calendar date that corresponds to January 1 of the second year of each supported Japanese calendar era. [!code-csharp[Conceptual.Calendars#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/instantiatewithera1.cs)] [!code-vb[Conceptual.Calendars#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/instantiatewithera1.vb)] @@ -165,7 +165,7 @@ In addition, the "g" custom date and time format string includes a calendar's er ### Instantiate a date with an era -For the two classes that support multiple eras, a date that consists of a particular year, month, and day of the month value can be ambiguous. For example, all eras supported by the have years whose number is 1. Ordinarily, if an era is not specified, both date and time and calendar methods assume that values belong to the current era. This is true of the and constructors that include parameters of type , as well as the [JapaneseCalendar.ToDateTime](xref:System.Globalization.Calendar.ToDateTime(System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32)) and [JapaneseLunisolarCalendar.ToDateTime](xref:System.Globalization.Calendar.ToDateTime(System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32)) methods. The following example instantiates a date that represents January 1 of the second year of an unspecified era. If you execute the example when the Reiwa era is the current era, the date is interpreted as the second year of the Reiwa era. The era, 令和, precedes the year in the string returned by the method and corresponds to January 1, 2020, in the Gregorian calendar. (The Reiwa era begins in the year 2019 of the Gregorian calendar.) +For the two classes that support multiple eras, a date that consists of a particular year, month, and day of the month value can be ambiguous. For example, all eras supported by the have years whose number is 1. Ordinarily, if an era is not specified, both date and time and calendar methods assume that values belong to the current era. This is true of the and constructors that include parameters of type , as well as the [JapaneseCalendar.ToDateTime](xref:System.Globalization.Calendar.ToDateTime(System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32)) and [JapaneseLunisolarCalendar.ToDateTime](xref:System.Globalization.Calendar.ToDateTime(System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32)) methods. The following example instantiates a date that represents January 1 of the second year of an unspecified era. If you execute the example when the Reiwa era is the current era, the date is interpreted as the second year of the Reiwa era. The era, 令和, precedes the year in the string returned by the method and corresponds to January 1, 2020, in the Gregorian calendar. (The Reiwa era begins in the year 2019 of the Gregorian calendar.) [!code-csharp[A date in the current era](~/samples/snippets/standard/datetime/calendars/current-era/cs/program.cs)] [!code-vb[A date in the current era](~/samples/snippets/standard/datetime/calendars/current-era/vb/program.vb)] @@ -181,7 +181,7 @@ However, if the era changes, the intent of this code becomes ambiguous. Is the d - The method of the or class. - - A or parsing method, such as , , , or , that includes the string to be parsed and optionally a argument if the current culture is Japanese-Japan ("ja-JP") and that culture's calendar is the . The string to be parsed must include the era. + - A or parsing method, such as , , , or , that includes the string to be parsed and optionally a argument if the current culture is Japanese-Japan ("ja-JP") and that culture's calendar is the . The string to be parsed must include the era. - A or parsing method that includes a `provider` parameter of type . `provider` must be either a object that represents the Japanese-Japan ("ja-JP") culture whose current calendar is or a object whose property is . The string to be parsed must include the era. @@ -197,7 +197,7 @@ In specifying an era to the property. -- For dates in a specified era, use the method to retrieve the index that corresponds to a specified era name. This requires that the be the current calendar of the object that represents the ja-JP culture. (This technique works for the as well, since it supports the same eras as the .) The previous example illustrates this approach. +- For dates in a specified era, use the method to retrieve the index that corresponds to a specified era name. This requires that the be the current calendar of the object that represents the ja-JP culture. (This technique works for the as well, since it supports the same eras as the .) The previous example illustrates this approach. ### Calendars, eras, and date ranges: Relaxed range checks @@ -265,7 +265,7 @@ For all calendars, the "g" custom format specifier includes the era in the resul [!code-csharp[Conceptual.Calendars#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/formatstrings2.cs#9)] [!code-vb[Conceptual.Calendars#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/formatstrings2.vb#9)] -In cases where the string representation of a date is expressed in a calendar that is not the current calendar, the class includes a method that can be used along with the , , and methods to unambiguously indicate a date as well as the era to which it belongs. The following example uses the class to provide an illustration. However, note that including a meaningful name or abbreviation instead of an integer for the era in the result string requires that you instantiate a object and make its current calendar. (The calendar cannot be the current calendar of any culture, but in this case the two calendars share the same eras.) +In cases where the string representation of a date is expressed in a calendar that is not the current calendar, the class includes a method that can be used along with the , , and methods to unambiguously indicate a date as well as the era to which it belongs. The following example uses the class to provide an illustration. However, note that including a meaningful name or abbreviation instead of an integer for the era in the result string requires that you instantiate a object and make its current calendar. (The calendar cannot be the current calendar of any culture, but in this case the two calendars share the same eras.) [!code-csharp[Conceptual.Calendars#10](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/formatstrings3.cs#10)] [!code-vb[Conceptual.Calendars#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/formatstrings3.vb#10)] diff --git a/docs/standard/delegates-lambdas.md b/docs/standard/delegates-lambdas.md index c5958605b3da0..f736ecdf5808d 100644 --- a/docs/standard/delegates-lambdas.md +++ b/docs/standard/delegates-lambdas.md @@ -99,7 +99,7 @@ public class Program } ``` -As you can see, the body of the delegate is just a set of expressions, as any other delegate. But instead of it being a separate definition, we've introduced it _ad hoc_ in our call to the method. +As you can see, the body of the delegate is just a set of expressions, as any other delegate. But instead of it being a separate definition, we've introduced it _ad hoc_ in our call to the method. However, even with this approach, there is still much code that we can throw away. This is where *lambda expressions* come into play. Lambda expressions, or just "lambdas" for short, were introduced in C# 3.0 as one of the core building blocks of Language Integrated Query (LINQ). They are just a more convenient syntax for using delegates. They declare a parameter list and method body, but don't have a formal identity of their own, unless they are assigned to a delegate. Unlike delegates, they can be directly assigned as the right-hand side of event registration or in various LINQ clauses and methods. diff --git a/docs/standard/design-guidelines/abstractions-abstract-types-and-interfaces.md b/docs/standard/design-guidelines/abstractions-abstract-types-and-interfaces.md index 29fbaceb85540..ec6bfe5dd462b 100644 --- a/docs/standard/design-guidelines/abstractions-abstract-types-and-interfaces.md +++ b/docs/standard/design-guidelines/abstractions-abstract-types-and-interfaces.md @@ -13,7 +13,7 @@ ms.assetid: 0a632bc7-9b03-44ee-8842-c82f88672a45 [!INCLUDE [not-current](includes/not-current.md)] -An abstraction is a type that describes a contract but does not provide a full implementation of the contract. Abstractions are usually implemented as abstract classes or interfaces, and they come with a well-defined set of reference documentation describing the required semantics of the types implementing the contract. Some of the most important abstractions in the .NET Framework include , , and . +An abstraction is a type that describes a contract but does not provide a full implementation of the contract. Abstractions are usually implemented as abstract classes or interfaces, and they come with a well-defined set of reference documentation describing the required semantics of the types implementing the contract. Some of the most important abstractions in the .NET Framework include , , and . You can extend frameworks by implementing a concrete type that supports the contract of an abstraction and using this concrete type with framework APIs consuming (operating on) the abstraction. diff --git a/docs/standard/design-guidelines/attributes.md b/docs/standard/design-guidelines/attributes.md index 58a5fe5e6dd00..7797b08c82ebf 100644 --- a/docs/standard/design-guidelines/attributes.md +++ b/docs/standard/design-guidelines/attributes.md @@ -17,9 +17,9 @@ ms.assetid: ee0038ef-b247-4747-a650-3c5c5cd58d8b Attributes can have one or more properties that carry additional data related to the attribute. For example, `ObsoleteAttribute` could carry additional information about the release in which a type or a member got deprecated and the description of the new APIs replacing the obsolete API. - Some properties of an attribute must be specified when the attribute is applied. These are referred to as the required properties or required arguments, because they are represented as positional constructor parameters. For example, the property of the is a required property. + Some properties of an attribute must be specified when the attribute is applied. These are referred to as the required properties or required arguments, because they are represented as positional constructor parameters. For example, the property of the is a required property. - Properties that do not necessarily have to be specified when the attribute is applied are called optional properties (or optional arguments). They are represented by settable properties. Compilers provide special syntax to set these properties when an attribute is applied. For example, the property represents an optional argument. + Properties that do not necessarily have to be specified when the attribute is applied are called optional properties (or optional arguments). They are represented by settable properties. Compilers provide special syntax to set these properties when an attribute is applied. For example, the property represents an optional argument. ✔️ DO name custom attribute classes with the suffix "Attribute." diff --git a/docs/standard/design-guidelines/base-classes-for-implementing-abstractions.md b/docs/standard/design-guidelines/base-classes-for-implementing-abstractions.md index 9295bac2a66d4..e29fb2bd6b583 100644 --- a/docs/standard/design-guidelines/base-classes-for-implementing-abstractions.md +++ b/docs/standard/design-guidelines/base-classes-for-implementing-abstractions.md @@ -13,7 +13,7 @@ ms.assetid: 37a2d9a4-9721-482a-a40f-eee2c1d97875 Strictly speaking, a class becomes a base class when another class is derived from it. For the purpose of this section, however, a base class is a class designed mainly to provide a common abstraction or for other classes to reuse some default implementation though inheritance. Base classes usually sit in the middle of inheritance hierarchies, between an abstraction at the root of a hierarchy and several custom implementations at the bottom. - They serve as implementation helpers for implementing abstractions. For example, one of the Framework’s abstractions for ordered collections of items is the interface. Implementing is not trivial, and therefore the Framework provides several base classes, such as and , which serve as helpers for implementing custom collections. + They serve as implementation helpers for implementing abstractions. For example, one of the Framework’s abstractions for ordered collections of items is the interface. Implementing is not trivial, and therefore the Framework provides several base classes, such as and , which serve as helpers for implementing custom collections. Base classes are usually not suited to serve as abstractions by themselves, because they tend to contain too much implementation. For example, the `Collection` base class contains lots of implementation related to the fact that it implements the nongeneric `IList` interface (to integrate better with nongeneric collections) and to the fact that it is a collection of items stored in memory in one of its fields. diff --git a/docs/standard/design-guidelines/dependency-properties.md b/docs/standard/design-guidelines/dependency-properties.md index 64ba0e71297c1..a7334b7add35f 100644 --- a/docs/standard/design-guidelines/dependency-properties.md +++ b/docs/standard/design-guidelines/dependency-properties.md @@ -20,7 +20,7 @@ A dependency property (DP) is a regular property that stores its value in a prop ✔️ DO provide a regular CLR property and public static read-only field storing an instance of for each dependency property. - ✔️ DO implement dependency properties by calling instance methods and . + ✔️ DO implement dependency properties by calling instance methods and . ✔️ DO name the dependency property static field by suffixing the name of the property with "Property." @@ -38,7 +38,7 @@ A dependency property (DP) is a regular property that stores its value in a prop Dependency properties described in the preceding section represent intrinsic properties of the declaring type; for example, the `Text` property is a property of `TextButton`, which declares it. A special kind of dependency property is the attached dependency property. - A classic example of an attached property is the property. The property represents Button’s (not Grid’s) column position, but it is only relevant if the Button is contained in a Grid, and so it's "attached" to Buttons by Grids. + A classic example of an attached property is the property. The property represents Button’s (not Grid’s) column position, but it is only relevant if the Button is contained in a Grid, and so it's "attached" to Buttons by Grids. ```xaml diff --git a/docs/standard/design-guidelines/dispose-pattern.md b/docs/standard/design-guidelines/dispose-pattern.md index 594ab9670816a..ec044df5c1657 100644 --- a/docs/standard/design-guidelines/dispose-pattern.md +++ b/docs/standard/design-guidelines/dispose-pattern.md @@ -22,7 +22,7 @@ All programs acquire one or more system resources, such as memory, system handle Unfortunately, managed memory is just one of many types of system resources. Resources other than managed memory still need to be released explicitly and are referred to as unmanaged resources. The GC was specifically not designed to manage such unmanaged resources, which means that the responsibility for managing unmanaged resources lies in the hands of the developers. - The CLR provides some help in releasing unmanaged resources. declares a virtual method (also called the finalizer) that is called by the GC before the object’s memory is reclaimed by the GC and can be overridden to release unmanaged resources. Types that override the finalizer are referred to as finalizable types. + The CLR provides some help in releasing unmanaged resources. declares a virtual method (also called the finalizer) that is called by the GC before the object’s memory is reclaimed by the GC and can be overridden to release unmanaged resources. Types that override the finalizer are referred to as finalizable types. Although finalizers are effective in some cleanup scenarios, they have two significant drawbacks: @@ -32,11 +32,11 @@ All programs acquire one or more system resources, such as memory, system handle Therefore, relying exclusively on finalizers might not be appropriate in many scenarios when it is important to reclaim unmanaged resources as quickly as possible, when dealing with scarce resources, or in highly performant scenarios in which the added GC overhead of finalization is unacceptable. - The Framework provides the interface that should be implemented to provide the developer a manual way to release unmanaged resources as soon as they are not needed. It also provides the method that can tell the GC that an object was manually disposed of and does not need to be finalized anymore, in which case the object’s memory can be reclaimed earlier. Types that implement the `IDisposable` interface are referred to as disposable types. + The Framework provides the interface that should be implemented to provide the developer a manual way to release unmanaged resources as soon as they are not needed. It also provides the method that can tell the GC that an object was manually disposed of and does not need to be finalized anymore, in which case the object’s memory can be reclaimed earlier. Types that implement the `IDisposable` interface are referred to as disposable types. The Dispose Pattern is intended to standardize the usage and implementation of finalizers and the `IDisposable` interface. - The main motivation for the pattern is to reduce the complexity of the implementation of the and the methods. The complexity stems from the fact that the methods share some but not all code paths (the differences are described later in the chapter). In addition, there are historical reasons for some elements of the pattern related to the evolution of language support for deterministic resource management. + The main motivation for the pattern is to reduce the complexity of the implementation of the and the methods. The complexity stems from the fact that the methods share some but not all code paths (the differences are described later in the chapter). In addition, there are historical reasons for some elements of the pattern related to the evolution of language support for deterministic resource management. **✓ DO** implement the Basic Dispose Pattern on types containing instances of disposable types. See the [Basic Dispose Pattern](#basic-dispose-pattern) section for details on the basic pattern. @@ -278,8 +278,8 @@ public class ComplexResourceHolder : IDisposable { ## See also -- -- +- +- - [Framework Design Guidelines](../../../docs/standard/design-guidelines/index.md) - [Common Design Patterns](../../../docs/standard/design-guidelines/common-design-patterns.md) - [Garbage Collection](../../../docs/standard/garbage-collection/index.md) diff --git a/docs/standard/design-guidelines/equality-operators.md b/docs/standard/design-guidelines/equality-operators.md index cc395b9edb1d2..479e27b2d6842 100644 --- a/docs/standard/design-guidelines/equality-operators.md +++ b/docs/standard/design-guidelines/equality-operators.md @@ -18,7 +18,7 @@ This section discusses overloading equality operators and refers to `operator==` ❌ DO NOT overload one of the equality operators and not the other. - ✔️ DO ensure that and the equality operators have exactly the same semantics and similar performance characteristics. + ✔️ DO ensure that and the equality operators have exactly the same semantics and similar performance characteristics. This often means that `Object.Equals` needs to be overridden when the equality operators are overloaded. diff --git a/docs/standard/design-guidelines/event.md b/docs/standard/design-guidelines/event.md index e68eb0fcb6a05..4bceacaccf45a 100644 --- a/docs/standard/design-guidelines/event.md +++ b/docs/standard/design-guidelines/event.md @@ -21,7 +21,7 @@ Events are the most commonly used form of callbacks (constructs that allow the f ✔️ DO use the term "raise" for events rather than "fire" or "trigger." - ✔️ DO use instead of manually creating new delegates to be used as event handlers. + ✔️ DO use instead of manually creating new delegates to be used as event handlers. ✔️ CONSIDER using a subclass of as the event argument, unless you are absolutely sure the event will never need to carry any data to the event handling method, in which case you can use the `EventArgs` type directly. diff --git a/docs/standard/design-guidelines/exceptions-and-performance.md b/docs/standard/design-guidelines/exceptions-and-performance.md index 176c618d9a24c..3f7e4e3d33166 100644 --- a/docs/standard/design-guidelines/exceptions-and-performance.md +++ b/docs/standard/design-guidelines/exceptions-and-performance.md @@ -22,7 +22,7 @@ One common concern related to exceptions is that if exceptions are used for code ## Tester-Doer Pattern - Sometimes performance of an exception-throwing member can be improved by breaking the member into two. Let’s look at the method of the interface. + Sometimes performance of an exception-throwing member can be improved by breaking the member into two. Let’s look at the method of the interface. ```csharp ICollection numbers = ... @@ -46,7 +46,7 @@ if (!numbers.IsReadOnly) ## Try-Parse Pattern - For extremely performance-sensitive APIs, an even faster pattern than the Tester-Doer Pattern described in the previous section should be used. The pattern calls for adjusting the member name to make a well-defined test case a part of the member semantics. For example, defines a method that throws an exception if parsing of a string fails. It also defines a corresponding method that attempts to parse, but returns false if parsing is unsuccessful and returns the result of a successful parsing using an `out` parameter. + For extremely performance-sensitive APIs, an even faster pattern than the Tester-Doer Pattern described in the previous section should be used. The pattern calls for adjusting the member name to make a well-defined test case a part of the member semantics. For example, defines a method that throws an exception if parsing of a string fails. It also defines a corresponding method that attempts to parse, but returns false if parsing is unsuccessful and returns the result of a successful parsing using an `out` parameter. ```csharp public struct DateTime diff --git a/docs/standard/design-guidelines/extension-methods.md b/docs/standard/design-guidelines/extension-methods.md index c37995e61e045..10fea35698ae9 100644 --- a/docs/standard/design-guidelines/extension-methods.md +++ b/docs/standard/design-guidelines/extension-methods.md @@ -18,7 +18,7 @@ Extension methods are a language feature that allows static methods to be called ✔️ CONSIDER using extension methods in any of the following scenarios: -- To provide helper functionality relevant to every implementation of an interface, if said functionality can be written in terms of the core interface. This is because concrete implementations cannot otherwise be assigned to interfaces. For example, the `LINQ to Objects` operators are implemented as extension methods for all types. Thus, any `IEnumerable<>` implementation is automatically LINQ-enabled. +- To provide helper functionality relevant to every implementation of an interface, if said functionality can be written in terms of the core interface. This is because concrete implementations cannot otherwise be assigned to interfaces. For example, the `LINQ to Objects` operators are implemented as extension methods for all types. Thus, any `IEnumerable<>` implementation is automatically LINQ-enabled. - When an instance method would introduce a dependency on some type, but such a dependency would break dependency management rules. For example, a dependency from to is probably not desirable, and so `String.ToUri()` instance method returning `System.Uri` would be the wrong design from a dependency management perspective. A static extension method `Uri.ToUri(this string str)` returning `System.Uri` would be a much better design. diff --git a/docs/standard/design-guidelines/guidelines-for-collections.md b/docs/standard/design-guidelines/guidelines-for-collections.md index cf5e83601d836..478740a87bbc2 100644 --- a/docs/standard/design-guidelines/guidelines-for-collections.md +++ b/docs/standard/design-guidelines/guidelines-for-collections.md @@ -8,21 +8,21 @@ ms.assetid: 297b8f1d-b11f-4dc6-960a-8e990817304e [!INCLUDE [not-current](includes/not-current.md)] -Any type designed specifically to manipulate a group of objects having some common characteristic can be considered a collection. It is almost always appropriate for such types to implement or , so in this section we only consider types implementing one or both of those interfaces to be collections. +Any type designed specifically to manipulate a group of objects having some common characteristic can be considered a collection. It is almost always appropriate for such types to implement or , so in this section we only consider types implementing one or both of those interfaces to be collections. ❌ DO NOT use weakly typed collections in public APIs. The type of all return values and parameters representing collection items should be the exact item type, not any of its base types (this applies only to public members of the collection). - ❌ DO NOT use or in public APIs. + ❌ DO NOT use or in public APIs. - These types are data structures designed to be used in internal implementation, not in public APIs. `List` is optimized for performance and power at the cost of cleanness of the APIs and flexibility. For example, if you return `List`, you will not ever be able to receive notifications when client code modifies the collection. Also, `List` exposes many members, such as , that are not useful or applicable in many scenarios. The following two sections describe types (abstractions) designed specifically for use in public APIs. + These types are data structures designed to be used in internal implementation, not in public APIs. `List` is optimized for performance and power at the cost of cleanness of the APIs and flexibility. For example, if you return `List`, you will not ever be able to receive notifications when client code modifies the collection. Also, `List` exposes many members, such as , that are not useful or applicable in many scenarios. The following two sections describe types (abstractions) designed specifically for use in public APIs. ❌ DO NOT use `Hashtable` or `Dictionary` in public APIs. These types are data structures designed to be used in internal implementation. Public APIs should use , `IDictionary `, or a custom type implementing one or both of the interfaces. - ❌ DO NOT use , , or any other type that implements either of these interfaces, except as the return type of a `GetEnumerator` method. + ❌ DO NOT use , , or any other type that implements either of these interfaces, except as the return type of a `GetEnumerator` method. Types returning enumerators from methods other than `GetEnumerator` cannot be used with the `foreach` statement. @@ -32,7 +32,7 @@ Any type designed specifically to manipulate a group of objects having some comm ✔️ DO use the least-specialized type possible as a parameter type. Most members taking collections as parameters use the `IEnumerable` interface. - ❌ AVOID using or as a parameter just to access the `Count` property. + ❌ AVOID using or as a parameter just to access the `Count` property. Instead, consider using `IEnumerable` or `IEnumerable` and dynamically checking whether the object implements `ICollection` or `ICollection`. @@ -44,9 +44,9 @@ Any type designed specifically to manipulate a group of objects having some comm ✔️ DO use `Collection` or a subclass of `Collection` for properties or return values representing read/write collections. - If `Collection` does not meet some requirement (e.g., the collection must not implement ), use a custom collection by implementing `IEnumerable`, `ICollection`, or . + If `Collection` does not meet some requirement (e.g., the collection must not implement ), use a custom collection by implementing `IEnumerable`, `ICollection`, or . - ✔️ DO use , a subclass of `ReadOnlyCollection`, or in rare cases `IEnumerable` for properties or return values representing read-only collections. + ✔️ DO use , a subclass of `ReadOnlyCollection`, or in rare cases `IEnumerable` for properties or return values representing read-only collections. In general, prefer `ReadOnlyCollection`. If it does not meet some requirement (e.g., the collection must not implement `IList`), use a custom collection by implementing `IEnumerable`, `ICollection`, or `IList`. If you do implement a custom read-only collection, implement `ICollection.IsReadOnly` to return `true`. @@ -110,7 +110,7 @@ Any type designed specifically to manipulate a group of objects having some comm ### Naming Custom Collections - Collections (types that implement `IEnumerable`) are created mainly for two reasons: (1) to create a new data structure with structure-specific operations and often different performance characteristics than existing data structures (e.g., , , ), and (2) to create a specialized collection for holding a specific set of items (e.g., ). Data structures are most often used in the internal implementation of applications and libraries. Specialized collections are mainly to be exposed in APIs (as property and parameter types). + Collections (types that implement `IEnumerable`) are created mainly for two reasons: (1) to create a new data structure with structure-specific operations and often different performance characteristics than existing data structures (e.g., , , ), and (2) to create a specialized collection for holding a specific set of items (e.g., ). Data structures are most often used in the internal implementation of applications and libraries. Specialized collections are mainly to be exposed in APIs (as property and parameter types). ✔️ DO use the "Dictionary" suffix in names of abstractions implementing `IDictionary` or `IDictionary`. diff --git a/docs/standard/design-guidelines/interface.md b/docs/standard/design-guidelines/interface.md index d40d54788cbc6..9caa6f1f31dd6 100644 --- a/docs/standard/design-guidelines/interface.md +++ b/docs/standard/design-guidelines/interface.md @@ -28,11 +28,11 @@ Although most APIs are best modeled using classes and structs, there are cases i ✔️ DO provide at least one type that is an implementation of an interface. - Doing this helps to validate the design of the interface. For example, is an implementation of the interface. + Doing this helps to validate the design of the interface. For example, is an implementation of the interface. ✔️ DO provide at least one API that consumes each interface you define (a method taking the interface as a parameter or a property typed as the interface). - Doing this helps to validate the interface design. For example, consumes the interface. + Doing this helps to validate the interface design. For example, consumes the interface. ❌ DO NOT add members to an interface that has previously shipped. diff --git a/docs/standard/design-guidelines/operator-overloads.md b/docs/standard/design-guidelines/operator-overloads.md index 26c7b8ae5ca43..95bb82f4f3db2 100644 --- a/docs/standard/design-guidelines/operator-overloads.md +++ b/docs/standard/design-guidelines/operator-overloads.md @@ -84,7 +84,7 @@ Operator overloads allow framework types to appear as if they were built-in lang ### Overloading Operator == - Overloading `operator ==` is quite complicated. The semantics of the operator need to be compatible with several other members, such as . + Overloading `operator ==` is quite complicated. The semantics of the operator need to be compatible with several other members, such as . ### Conversion Operators diff --git a/docs/standard/design-guidelines/parameter-design.md b/docs/standard/design-guidelines/parameter-design.md index 6a6676abf68de..8d48f0931eb1e 100644 --- a/docs/standard/design-guidelines/parameter-design.md +++ b/docs/standard/design-guidelines/parameter-design.md @@ -58,7 +58,7 @@ This section provides broad guidelines on parameter design, including sections w Do not assume enum arguments will be in the range defined by the enum. The CLR allows casting any integer value into an enum value even if the value is not defined in the enum. - ❌ DO NOT use for enum range checks. + ❌ DO NOT use for enum range checks. ✔️ DO be aware that mutable arguments might have changed after they were validated. @@ -92,7 +92,7 @@ public class String { } ``` - A user can then call the method, as follows: + A user can then call the method, as follows: `String.Format("File {0} not found in {1}",new object[]{filename,directory});` diff --git a/docs/standard/design-guidelines/property.md b/docs/standard/design-guidelines/property.md index 37ec27513533d..edc804fa3515e 100644 --- a/docs/standard/design-guidelines/property.md +++ b/docs/standard/design-guidelines/property.md @@ -53,7 +53,7 @@ Although properties are technically very similar to methods, they are quite diff If the design requires other types of parameters, strongly reevaluate whether the API really represents an accessor to a logical collection. If it does not, use a method. Consider starting the method name with `Get` or `Set`. - ✔️ DO use the name `Item` for indexed properties unless there is an obviously better name (e.g., see the property on `System.String`). + ✔️ DO use the name `Item` for indexed properties unless there is an obviously better name (e.g., see the property on `System.String`). In C#, indexers are by default named Item. The can be used to customize this name. @@ -75,7 +75,7 @@ Although properties are technically very similar to methods, they are quite diff If there is a good scenario for a user to know when a property of an object is changing, the object should raise a change notification event for the property. - However, it is unlikely to be worth the overhead to raise such events for low-level APIs such as base types or collections. For example, would not raise such events when a new item is added to the list and the `Count` property changes. + However, it is unlikely to be worth the overhead to raise such events for low-level APIs such as base types or collections. For example, would not raise such events when a new item is added to the list and the `Count` property changes. ✔️ CONSIDER raising change notification events when the value of a property changes via external forces. diff --git a/docs/standard/design-guidelines/serialization.md b/docs/standard/design-guidelines/serialization.md index 5ec04f70c6da8..968fe64356724 100644 --- a/docs/standard/design-guidelines/serialization.md +++ b/docs/standard/design-guidelines/serialization.md @@ -60,7 +60,7 @@ Serialization is the process of converting an object into a format that can be r ✔️ CONSIDER implementing to allow round-tripping between different versions of the type. - The interface allows the serializer to ensure that no data is lost during round-tripping. The property is used to store any data from the future version of the type that is unknown to the current version, and so it cannot store it in its data members. When the current version is subsequently serialized and deserialized into a future version, the additional data will be available in the serialized stream. + The interface allows the serializer to ensure that no data is lost during round-tripping. The property is used to store any data from the future version of the type that is unknown to the current version, and so it cannot store it in its data members. When the current version is subsequently serialized and deserialized into a future version, the additional data will be available in the serialized stream. ## Supporting XML Serialization @@ -68,7 +68,7 @@ Serialization is the process of converting an object into a format that can be r ❌ AVOID designing your types specifically for XML Serialization, unless you have a very strong reason to control the shape of the XML produced. This serialization technology has been superseded by the Data Contract Serialization discussed in the previous section. - ✔️ CONSIDER implementing the interface if you want even more control over the shape of the serialized XML than what’s offered by applying the XML Serialization attributes. Two methods of the interface, and , allow you to fully control the serialized XML stream. You can also control the XML schema that gets generated for the type by applying the `XmlSchemaProviderAttribute`. + ✔️ CONSIDER implementing the interface if you want even more control over the shape of the serialized XML than what’s offered by applying the XML Serialization attributes. Two methods of the interface, and , allow you to fully control the serialized XML stream. You can also control the XML schema that gets generated for the type by applying the `XmlSchemaProviderAttribute`. ## Supporting Runtime Serialization @@ -97,7 +97,7 @@ public class Person : ISerializable ✔️ DO implement the members explicitly. - ✔️ DO apply a link demand to implementation. This ensures that only fully trusted core and the Runtime Serializer have access to the member. + ✔️ DO apply a link demand to implementation. This ensures that only fully trusted core and the Runtime Serializer have access to the member. *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* diff --git a/docs/standard/design-guidelines/struct.md b/docs/standard/design-guidelines/struct.md index b4d5751d3eb85..1583752d319df 100644 --- a/docs/standard/design-guidelines/struct.md +++ b/docs/standard/design-guidelines/struct.md @@ -30,9 +30,9 @@ The general-purpose value type is most often referred to as a struct, its C# key This prevents accidental creation of invalid instances when an array of the structs is created. - ✔️ DO implement on value types. + ✔️ DO implement on value types. - The method on value types causes boxing, and its default implementation is not very efficient, because it uses reflection. can have much better performance and can be implemented so that it will not cause boxing. + The method on value types causes boxing, and its default implementation is not very efficient, because it uses reflection. can have much better performance and can be implemented so that it will not cause boxing. ❌ DO NOT explicitly extend . In fact, most languages prevent this. diff --git a/docs/standard/design-guidelines/usage-guidelines.md b/docs/standard/design-guidelines/usage-guidelines.md index 3b5ee7139ec7c..87760565bd5fd 100644 --- a/docs/standard/design-guidelines/usage-guidelines.md +++ b/docs/standard/design-guidelines/usage-guidelines.md @@ -2,18 +2,18 @@ description: "Learn more about: Usage guidelines" title: "Usage guidelines" ms.date: "10/22/2008" -helpviewer_keywords: +helpviewer_keywords: - "class library design guidelines [.NET Framework], usage guidelines" ms.assetid: 42215ffa-a099-4a26-b14e-fb2bdb6f95b7 --- # Usage guidelines This section contains guidelines for using common types in publicly accessible APIs. It deals with direct usage of built-in Framework types (e.g., serialization attributes) and overloading common operators. - + The interface is not covered in this section, but is discussed in the [Dispose Pattern](dispose-pattern.md) section. > [!NOTE] -> For guidelines and additional information about other common, built-in .NET Framework types, see the reference topics for the following: , , , , , , , . +> For guidelines and additional information about other common, built-in .NET Framework types, see the reference topics for the following: , , , , , , , . ## In this section @@ -27,7 +27,7 @@ The interface is not cove *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - + ## See also - [Framework Design Guidelines](index.md) diff --git a/docs/standard/events/how-to-handle-multiple-events-using-event-properties.md b/docs/standard/events/how-to-handle-multiple-events-using-event-properties.md index 81bb2f6d95f0f..5d86164f1028e 100644 --- a/docs/standard/events/how-to-handle-multiple-events-using-event-properties.md +++ b/docs/standard/events/how-to-handle-multiple-events-using-event-properties.md @@ -41,5 +41,5 @@ To use event properties, you define the event properties in the class that raise - - [Events](index.md) -- +- - [How to: Declare Custom Events To Conserve Memory](../../visual-basic/programming-guide/language-features/events/how-to-declare-custom-events-to-conserve-memory.md) diff --git a/docs/standard/events/how-to-implement-a-provider.md b/docs/standard/events/how-to-implement-a-provider.md index 03c47cf45550e..17361d2918de2 100644 --- a/docs/standard/events/how-to-implement-a-provider.md +++ b/docs/standard/events/how-to-implement-a-provider.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Implement a Provider" title: "How to: Implement a Provider" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "observer design pattern [.NET], implementing providers" - "providers [.NET], in observer design pattern" - "observables [.NET], in observer design pattern" @@ -13,50 +13,50 @@ ms.assetid: 790b5d8b-d546-40a6-beeb-151b574e5ee5 --- # How to: Implement a Provider -The observer design pattern requires a division between a provider, which monitors data and sends notifications, and one or more observers, which receive notifications (callbacks) from the provider. This topic discusses how to create a provider. A related topic, [How to: Implement an Observer](how-to-implement-an-observer.md), discusses how to create an observer. - -### To create a provider - -1. Define the data that the provider is responsible for sending to observers. Although the provider and the data that it sends to observers can be a single type, they are generally represented by different types. For example, in a temperature monitoring application, the `Temperature` structure defines the data that the provider (which is represented by the `TemperatureMonitor` class defined in the next step) monitors and to which observers subscribe. - +The observer design pattern requires a division between a provider, which monitors data and sends notifications, and one or more observers, which receive notifications (callbacks) from the provider. This topic discusses how to create a provider. A related topic, [How to: Implement an Observer](how-to-implement-an-observer.md), discusses how to create an observer. + +### To create a provider + +1. Define the data that the provider is responsible for sending to observers. Although the provider and the data that it sends to observers can be a single type, they are generally represented by different types. For example, in a temperature monitoring application, the `Temperature` structure defines the data that the provider (which is represented by the `TemperatureMonitor` class defined in the next step) monitors and to which observers subscribe. + [!code-csharp[Conceptual.ObserverDesign.HowTo#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/data.cs#1)] - [!code-vb[Conceptual.ObserverDesign.HowTo#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/data.vb#1)] - -2. Define the data provider, which is a type that implements the interface. The provider's generic type argument is the type that the provider sends to observers. The following example defines a `TemperatureMonitor` class, which is a constructed implementation with a generic type argument of `Temperature`. - + [!code-vb[Conceptual.ObserverDesign.HowTo#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/data.vb#1)] + +2. Define the data provider, which is a type that implements the interface. The provider's generic type argument is the type that the provider sends to observers. The following example defines a `TemperatureMonitor` class, which is a constructed implementation with a generic type argument of `Temperature`. + [!code-csharp[Conceptual.ObserverDesign.HowTo#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/provider.cs#2)] - [!code-vb[Conceptual.ObserverDesign.HowTo#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#2)] - -3. Determine how the provider will store references to observers so that each observer can be notified when appropriate. Most commonly, a collection object such as a generic object is used for this purpose. The following example defines a private object that is instantiated in the `TemperatureMonitor` class constructor. - + [!code-vb[Conceptual.ObserverDesign.HowTo#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#2)] + +3. Determine how the provider will store references to observers so that each observer can be notified when appropriate. Most commonly, a collection object such as a generic object is used for this purpose. The following example defines a private object that is instantiated in the `TemperatureMonitor` class constructor. + [!code-csharp[Conceptual.ObserverDesign.HowTo#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/provider.cs#3)] - [!code-vb[Conceptual.ObserverDesign.HowTo#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#3)] - -4. Define an implementation that the provider can return to subscribers so that they can stop receiving notifications at any time. The following example defines a nested `Unsubscriber` class that is passed a reference to the subscribers collection and to the subscriber when the class is instantiated. This code enables the subscriber to call the object's implementation to remove itself from the subscribers collection. - + [!code-vb[Conceptual.ObserverDesign.HowTo#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#3)] + +4. Define an implementation that the provider can return to subscribers so that they can stop receiving notifications at any time. The following example defines a nested `Unsubscriber` class that is passed a reference to the subscribers collection and to the subscriber when the class is instantiated. This code enables the subscriber to call the object's implementation to remove itself from the subscribers collection. + [!code-csharp[Conceptual.ObserverDesign.HowTo#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/provider.cs#4)] - [!code-vb[Conceptual.ObserverDesign.HowTo#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#4)] - -5. Implement the method. The method is passed a reference to the interface and should be stored in the object designed for that purpose in step 3. The method should then return the implementation developed in step 4. The following example shows the implementation of the method in the `TemperatureMonitor` class. - + [!code-vb[Conceptual.ObserverDesign.HowTo#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#4)] + +5. Implement the method. The method is passed a reference to the interface and should be stored in the object designed for that purpose in step 3. The method should then return the implementation developed in step 4. The following example shows the implementation of the method in the `TemperatureMonitor` class. + [!code-csharp[Conceptual.ObserverDesign.HowTo#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/provider.cs#5)] - [!code-vb[Conceptual.ObserverDesign.HowTo#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#5)] - -6. Notify observers as appropriate by calling their , , and implementations. In some cases, a provider may not call the method when an error occurs. For example, the following `GetTemperature` method simulates a monitor that reads temperature data every five seconds and notifies observers if the temperature has changed by at least .1 degree since the previous reading. If the device does not report a temperature (that is, if its value is null), the provider notifies observers that the transmission is complete. Note that, in addition to calling each observer's method, the `GetTemperature` method clears the collection. In this case, the provider makes no calls to the method of its observers. - + [!code-vb[Conceptual.ObserverDesign.HowTo#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#5)] + +6. Notify observers as appropriate by calling their , , and implementations. In some cases, a provider may not call the method when an error occurs. For example, the following `GetTemperature` method simulates a monitor that reads temperature data every five seconds and notifies observers if the temperature has changed by at least .1 degree since the previous reading. If the device does not report a temperature (that is, if its value is null), the provider notifies observers that the transmission is complete. Note that, in addition to calling each observer's method, the `GetTemperature` method clears the collection. In this case, the provider makes no calls to the method of its observers. + [!code-csharp[Conceptual.ObserverDesign.HowTo#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/provider.cs#6)] - [!code-vb[Conceptual.ObserverDesign.HowTo#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#6)] - -## Example + [!code-vb[Conceptual.ObserverDesign.HowTo#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#6)] + +## Example + + The following example contains the complete source code for defining an implementation for a temperature monitoring application. It includes the `Temperature` structure, which is the data sent to observers, and the `TemperatureMonitor` class, which is the implementation. - The following example contains the complete source code for defining an implementation for a temperature monitoring application. It includes the `Temperature` structure, which is the data sent to observers, and the `TemperatureMonitor` class, which is the implementation. - [!code-csharp[Conceptual.ObserverDesign.HowTo#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/provider.cs#7)] - [!code-vb[Conceptual.ObserverDesign.HowTo#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#7)] - + [!code-vb[Conceptual.ObserverDesign.HowTo#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#7)] + ## See also -- +- - [Observer Design Pattern](observer-design-pattern.md) - [How to: Implement an Observer](how-to-implement-an-observer.md) - [Observer Design Pattern Best Practices](observer-design-pattern-best-practices.md) diff --git a/docs/standard/events/how-to-implement-an-observer.md b/docs/standard/events/how-to-implement-an-observer.md index 49fc27d8257ca..f7fc7c14f9f8f 100644 --- a/docs/standard/events/how-to-implement-an-observer.md +++ b/docs/standard/events/how-to-implement-an-observer.md @@ -2,50 +2,50 @@ title: "How to: Implement an Observer" description: Implement an observer in .NET. The observer design pattern requires a division between an observer, which registers for notifications, and a provider. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "observers [.NET], observer design pattern" - "observer design pattern [.NET], implementing observers" ms.assetid: 8ecfa9f5-b500-473d-bcf0-5652ffb1e53d --- # How to: Implement an Observer -The observer design pattern requires a division between an observer, which registers for notifications, and a provider, which monitors data and sends notifications to one or more observers. This topic discusses how to create an observer. A related topic, [How to: Implement a Provider](how-to-implement-a-provider.md), discusses how to create a provider. - -### To create an observer - -1. Define the observer, which is a type that implements the interface. For example, the following code defines a type named `TemperatureReporter` that is a constructed implementation with a generic type argument of `Temperature`. - +The observer design pattern requires a division between an observer, which registers for notifications, and a provider, which monitors data and sends notifications to one or more observers. This topic discusses how to create an observer. A related topic, [How to: Implement a Provider](how-to-implement-a-provider.md), discusses how to create a provider. + +### To create an observer + +1. Define the observer, which is a type that implements the interface. For example, the following code defines a type named `TemperatureReporter` that is a constructed implementation with a generic type argument of `Temperature`. + [!code-csharp[Conceptual.ObserverDesign.HowTo#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/observer.cs#8)] - [!code-vb[Conceptual.ObserverDesign.HowTo#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#8)] - -2. If the observer can stop receiving notifications before the provider calls its implementation, define a private variable that will hold the implementation returned by the provider's method. You should also define a subscription method that calls the provider's method and stores the returned object. For example, the following code defines a private variable named `unsubscriber` and defines a `Subscribe` method that calls the provider's method and assigns the returned object to the `unsubscriber` variable. - + [!code-vb[Conceptual.ObserverDesign.HowTo#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#8)] + +2. If the observer can stop receiving notifications before the provider calls its implementation, define a private variable that will hold the implementation returned by the provider's method. You should also define a subscription method that calls the provider's method and stores the returned object. For example, the following code defines a private variable named `unsubscriber` and defines a `Subscribe` method that calls the provider's method and assigns the returned object to the `unsubscriber` variable. + [!code-csharp[Conceptual.ObserverDesign.HowTo#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/observer.cs#9)] - [!code-vb[Conceptual.ObserverDesign.HowTo#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#9)] - -3. Define a method that enables the observer to stop receiving notifications before the provider calls its implementation, if this feature is required. The following example defines an `Unsubscribe` method. - + [!code-vb[Conceptual.ObserverDesign.HowTo#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#9)] + +3. Define a method that enables the observer to stop receiving notifications before the provider calls its implementation, if this feature is required. The following example defines an `Unsubscribe` method. + [!code-csharp[Conceptual.ObserverDesign.HowTo#10](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/observer.cs#10)] - [!code-vb[Conceptual.ObserverDesign.HowTo#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#10)] - -4. Provide implementations of the three methods defined by the interface: , , and . Depending on the provider and the needs of the application, the and methods can be stub implementations. Note that the method should not handle the passed object as an exception, and the method is free to call the provider's implementation. The following example shows the implementation of the `TemperatureReporter` class. - + [!code-vb[Conceptual.ObserverDesign.HowTo#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#10)] + +4. Provide implementations of the three methods defined by the interface: , , and . Depending on the provider and the needs of the application, the and methods can be stub implementations. Note that the method should not handle the passed object as an exception, and the method is free to call the provider's implementation. The following example shows the implementation of the `TemperatureReporter` class. + [!code-csharp[Conceptual.ObserverDesign.HowTo#11](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/observer.cs#11)] - [!code-vb[Conceptual.ObserverDesign.HowTo#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#11)] - -## Example + [!code-vb[Conceptual.ObserverDesign.HowTo#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#11)] + +## Example + + The following example contains the complete source code for the `TemperatureReporter` class, which provides the implementation for a temperature monitoring application. - The following example contains the complete source code for the `TemperatureReporter` class, which provides the implementation for a temperature monitoring application. - [!code-csharp[Conceptual.ObserverDesign.HowTo#12](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/observer.cs#12)] - [!code-vb[Conceptual.ObserverDesign.HowTo#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#12)] - + [!code-vb[Conceptual.ObserverDesign.HowTo#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#12)] + ## See also -- +- - [Observer Design Pattern](observer-design-pattern.md) - [How to: Implement a Provider](how-to-implement-a-provider.md) - [Observer Design Pattern Best Practices](observer-design-pattern-best-practices.md) diff --git a/docs/standard/events/index.md b/docs/standard/events/index.md index c6b27461b3618..62d30d9ebc8c4 100644 --- a/docs/standard/events/index.md +++ b/docs/standard/events/index.md @@ -40,11 +40,11 @@ A delegate is a type that holds a reference to a method. A delegate is declared Delegates have many uses in .NET. In the context of events, a delegate is an intermediary (or pointer-like mechanism) between the event source and the code that handles the event. You associate a delegate with an event by including the delegate type in the event declaration, as shown in the example in the previous section. For more information about delegates, see the class. -.NET provides the and delegates to support most event scenarios. Use the delegate for all events that don't include event data. Use the delegate for events that include data about the event. These delegates have no return type value and take two parameters (an object for the source of the event and an object for event data). +.NET provides the and delegates to support most event scenarios. Use the delegate for all events that don't include event data. Use the delegate for events that include data about the event. These delegates have no return type value and take two parameters (an object for the source of the event and an object for event data). Delegates are [multicast](xref:System.MulticastDelegate) class objects, which means they can hold references to more than one event-handling method. For more information, see the reference page. Delegates provide flexibility and fine-grained control in event handling. A delegate acts as an event dispatcher for the class that raises the event by maintaining a list of registered event handlers for the event. -Use the and delegate types to define the needed delegate. You mark a delegate with the `delegate` type in [C#](../../csharp/language-reference/builtin-types/reference-types.md#the-delegate-type) or the `Delegate` type in [Visual Basic](../../visual-basic/language-reference/statements/delegate-statement.md) in the declaration. The following example shows how to declare a delegate named `ThresholdReachedEventHandler`: +Use the and delegate types to define the needed delegate. You mark a delegate with the `delegate` type in [C#](../../csharp/language-reference/builtin-types/reference-types.md#the-delegate-type) or the `Delegate` type in [Visual Basic](../../visual-basic/language-reference/statements/delegate-statement.md) in the declaration. The following example shows how to declare a delegate named `ThresholdReachedEventHandler`: [!code-csharp[EventsOverview#4](./snippets/raise-consume/csharp/programtruncated.cs#4)] [!code-vb[EventsOverview#4](./snippets/raise-consume/vb/module1truncated.vb#4)] @@ -101,7 +101,7 @@ Specification reference documentation is available for the APIs that support eve | API name | API type | Reference | | --- | --- | --- | | EventHandler | Delegate | | -| EventHandler\ | Delegate | | +| EventHandler\ | Delegate | | | EventArgs | Class | | | Delegate | Class | | diff --git a/docs/standard/events/observer-design-pattern-best-practices.md b/docs/standard/events/observer-design-pattern-best-practices.md index 51e0fd7b0e2c9..b526b06ca7908 100644 --- a/docs/standard/events/observer-design-pattern-best-practices.md +++ b/docs/standard/events/observer-design-pattern-best-practices.md @@ -9,11 +9,11 @@ ms.assetid: c834760f-ddd4-417f-abb7-a059679d5b8c --- # Observer Design Pattern Best Practices -In .NET, the observer design pattern is implemented as a set of interfaces. The interface represents the data provider, which is also responsible for providing an implementation that lets observers unsubscribe from notifications. The interface represents the observer. This topic describes the best practices that developers should follow when implementing the observer design pattern using these interfaces. +In .NET, the observer design pattern is implemented as a set of interfaces. The interface represents the data provider, which is also responsible for providing an implementation that lets observers unsubscribe from notifications. The interface represents the observer. This topic describes the best practices that developers should follow when implementing the observer design pattern using these interfaces. ## Threading - Typically, a provider implements the method by adding a particular observer to a subscriber list that is represented by some collection object, and it implements the method by removing a particular observer from the subscriber list. An observer can call these methods at any time. In addition, because the provider/observer contract does not specify who is responsible for unsubscribing after the callback method, the provider and observer may both try to remove the same member from the list. Because of this possibility, both the and methods should be thread-safe. Typically, this involves using a [concurrent collection](../parallel-programming/data-structures-for-parallel-programming.md) or a lock. Implementations that are not thread-safe should explicitly document that they are not. + Typically, a provider implements the method by adding a particular observer to a subscriber list that is represented by some collection object, and it implements the method by removing a particular observer from the subscriber list. An observer can call these methods at any time. In addition, because the provider/observer contract does not specify who is responsible for unsubscribing after the callback method, the provider and observer may both try to remove the same member from the list. Because of this possibility, both the and methods should be thread-safe. Typically, this involves using a [concurrent collection](../parallel-programming/data-structures-for-parallel-programming.md) or a lock. Implementations that are not thread-safe should explicitly document that they are not. Any additional guarantees have to be specified in a layer on top of the provider/observer contract. Implementers should clearly call out when they impose additional requirements to avoid user confusion about the observer contract. @@ -23,33 +23,33 @@ In .NET, the observer design pattern is implemented as a set of interfaces. The ### The Provider—Calling the OnError Method - The method is intended as an informational message to observers, much like the method. However, the method is designed to provide an observer with current or updated data, whereas the method is designed to indicate that the provider is unable to provide valid data. + The method is intended as an informational message to observers, much like the method. However, the method is designed to provide an observer with current or updated data, whereas the method is designed to indicate that the provider is unable to provide valid data. - The provider should follow these best practices when handling exceptions and calling the method: + The provider should follow these best practices when handling exceptions and calling the method: - The provider must handle its own exceptions if it has any specific requirements. - The provider should not expect or require that observers handle exceptions in any particular way. -- The provider should call the method when it handles an exception that compromises its ability to provide updates. Information on such exceptions can be passed to the observer. In other cases, there is no need to notify observers of an exception. +- The provider should call the method when it handles an exception that compromises its ability to provide updates. Information on such exceptions can be passed to the observer. In other cases, there is no need to notify observers of an exception. - Once the provider calls the or method, there should be no further notifications, and the provider can unsubscribe its observers. However, the observers can also unsubscribe themselves at any time, including both before and after they receive an or notification. The observer design pattern does not dictate whether the provider or the observer is responsible for unsubscribing; therefore, there is a possibility that both may attempt to unsubscribe. Typically, when observers unsubscribe, they are removed from a subscribers collection. In a single-threaded application, the implementation should ensure that an object reference is valid and that the object is a member of the subscribers collection before attempting to remove it. In a multithreaded application, a thread-safe collection object, such as a object, should be used. + Once the provider calls the or method, there should be no further notifications, and the provider can unsubscribe its observers. However, the observers can also unsubscribe themselves at any time, including both before and after they receive an or notification. The observer design pattern does not dictate whether the provider or the observer is responsible for unsubscribing; therefore, there is a possibility that both may attempt to unsubscribe. Typically, when observers unsubscribe, they are removed from a subscribers collection. In a single-threaded application, the implementation should ensure that an object reference is valid and that the object is a member of the subscribers collection before attempting to remove it. In a multithreaded application, a thread-safe collection object, such as a object, should be used. ### The Observer—Implementing the OnError Method When an observer receives an error notification from a provider, the observer should treat the exception as informational and should not be required to take any particular action. - The observer should follow these best practices when responding to an method call from a provider: + The observer should follow these best practices when responding to an method call from a provider: -- The observer should not throw exceptions from its interface implementations, such as or . However, if the observer does throw exceptions, it should expect these exceptions to go unhandled. +- The observer should not throw exceptions from its interface implementations, such as or . However, if the observer does throw exceptions, it should expect these exceptions to go unhandled. -- To preserve the call stack, an observer that wishes to throw an object that was passed to its method should wrap the exception before throwing it. A standard exception object should be used for this purpose. +- To preserve the call stack, an observer that wishes to throw an object that was passed to its method should wrap the exception before throwing it. A standard exception object should be used for this purpose. ## Additional Best Practices - Attempting to unregister in the method may result in a null reference. Therefore, we recommend that you avoid this practice. + Attempting to unregister in the method may result in a null reference. Therefore, we recommend that you avoid this practice. - Although it is possible to attach an observer to multiple providers, the recommended pattern is to attach an instance to only one instance. + Although it is possible to attach an observer to multiple providers, the recommended pattern is to attach an instance to only one instance. ## See also diff --git a/docs/standard/events/observer-design-pattern.md b/docs/standard/events/observer-design-pattern.md index eed15f5e72a86..c015b15552bc6 100644 --- a/docs/standard/events/observer-design-pattern.md +++ b/docs/standard/events/observer-design-pattern.md @@ -16,7 +16,7 @@ ms.assetid: 3680171f-f522-453c-aa4a-54f755a78f88 # Observer design pattern -The observer design pattern enables a subscriber to register with and receive notifications from a provider. It's suitable for any scenario that requires push-based notification. The pattern defines a *provider* (also known as a *subject* or an *observable*) and zero, one, or more *observers*. Observers register with the provider, and whenever a predefined condition, event, or state change occurs, the provider automatically notifies all observers by invoking a delegate. In this method call, the provider can also provide current state information to observers. In .NET, the observer design pattern is applied by implementing the generic and interfaces. The generic type parameter represents the type that provides notification information. +The observer design pattern enables a subscriber to register with and receive notifications from a provider. It's suitable for any scenario that requires push-based notification. The pattern defines a *provider* (also known as a *subject* or an *observable*) and zero, one, or more *observers*. Observers register with the provider, and whenever a predefined condition, event, or state change occurs, the provider automatically notifies all observers by invoking a delegate. In this method call, the provider can also provide current state information to observers. In .NET, the observer design pattern is applied by implementing the generic and interfaces. The generic type parameter represents the type that provides notification information. ## When to apply the pattern @@ -24,22 +24,22 @@ The observer design pattern is suitable for distributed push-based notifications Implementing the pattern requires that you provide the following details: -- A provider or subject, which is the object that sends notifications to observers. A provider is a class or structure that implements the interface. The provider must implement a single method, , which is called by observers that wish to receive notifications from the provider. +- A provider or subject, which is the object that sends notifications to observers. A provider is a class or structure that implements the interface. The provider must implement a single method, , which is called by observers that wish to receive notifications from the provider. -- An observer, which is an object that receives notifications from a provider. An observer is a class or structure that implements the interface. The observer must implement three methods, all of which are called by the provider: +- An observer, which is an object that receives notifications from a provider. An observer is a class or structure that implements the interface. The observer must implement three methods, all of which are called by the provider: - - , which supplies the observer with new or current information. - - , which informs the observer that an error has occurred. - - , which indicates that the provider has finished sending notifications. + - , which supplies the observer with new or current information. + - , which informs the observer that an error has occurred. + - , which indicates that the provider has finished sending notifications. -- A mechanism that allows the provider to keep track of observers. Typically, the provider uses a container object, such as a object, to hold references to the implementations that have subscribed to notifications. Using a storage container for this purpose enables the provider to handle zero to an unlimited number of observers. The order in which observers receive notifications isn't defined; the provider is free to use any method to determine the order. +- A mechanism that allows the provider to keep track of observers. Typically, the provider uses a container object, such as a object, to hold references to the implementations that have subscribed to notifications. Using a storage container for this purpose enables the provider to handle zero to an unlimited number of observers. The order in which observers receive notifications isn't defined; the provider is free to use any method to determine the order. -- An implementation that enables the provider to remove observers when notification is complete. Observers receive a reference to the implementation from the method, so they can also call the method to unsubscribe before the provider has finished sending notifications. +- An implementation that enables the provider to remove observers when notification is complete. Observers receive a reference to the implementation from the method, so they can also call the method to unsubscribe before the provider has finished sending notifications. -- An object that contains the data that the provider sends to its observers. The type of this object corresponds to the generic type parameter of the and interfaces. Although this object can be the same as the implementation, most commonly it's a separate type. +- An object that contains the data that the provider sends to its observers. The type of this object corresponds to the generic type parameter of the and interfaces. Although this object can be the same as the implementation, most commonly it's a separate type. > [!NOTE] -> In addition to implementing the observer design pattern, you may be interested in exploring libraries that are built using the and interfaces. For example, [Reactive Extensions for .NET (Rx)](/previous-versions/dotnet/reactive-extensions/hh242985(v=vs.103)) consist of a set of extension methods and LINQ standard sequence operators to support asynchronous programming. +> In addition to implementing the observer design pattern, you may be interested in exploring libraries that are built using the and interfaces. For example, [Reactive Extensions for .NET (Rx)](/previous-versions/dotnet/reactive-extensions/hh242985(v=vs.103)) consist of a set of extension methods and LINQ standard sequence operators to support asynchronous programming. ## Implement the pattern @@ -58,23 +58,23 @@ The source code for the `BaggageHandler` class is shown in the following example :::code source="snippets/observables/BaggageHandler.cs"::: [!code-vb[Conceptual.ObserverDesignPattern#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesignpattern/vb/provider.vb#2)] -Clients that wish to receive updated information call the `BaggageHandler.Subscribe` method. If the client hasn't previously subscribed to notifications, a reference to the client's implementation is added to the `_observers` collection. +Clients that wish to receive updated information call the `BaggageHandler.Subscribe` method. If the client hasn't previously subscribed to notifications, a reference to the client's implementation is added to the `_observers` collection. The overloaded `BaggageHandler.BaggageStatus` method can be called to indicate that baggage from a flight either is being unloaded or is no longer being unloaded. In the first case, the method is passed a flight number, the airport from which the flight originated, and the carousel where baggage is being unloaded. In the second case, the method is passed only a flight number. For baggage that is being unloaded, the method checks whether the `BaggageInfo` information passed to the method exists in the `_flights` collection. If it doesn't, the method adds the information and calls each observer's `OnNext` method. For flights whose baggage is no longer being unloaded, the method checks whether information on that flight is stored in the `_flights` collection. If it is, the method calls each observer's `OnNext` method and removes the `BaggageInfo` object from the `_flights` collection. When the last flight of the day has landed and its baggage has been processed, the `BaggageHandler.LastBaggageClaimed` method is called. This method calls each observer's `OnCompleted` method to indicate that all notifications have completed, and then clears the `_observers` collection. -The provider's method returns an implementation that enables observers to stop receiving notifications before the method is called. The source code for this `Unsubscriber(Of BaggageInfo)` class is shown in the following example. When the class is instantiated in the `BaggageHandler.Subscribe` method, it's passed a reference to the `_observers` collection and a reference to the observer that is added to the collection. These references are assigned to local variables. When the object's `Dispose` method is called, it checks whether the observer still exists in the `_observers` collection, and, if it does, removes the observer. +The provider's method returns an implementation that enables observers to stop receiving notifications before the method is called. The source code for this `Unsubscriber(Of BaggageInfo)` class is shown in the following example. When the class is instantiated in the `BaggageHandler.Subscribe` method, it's passed a reference to the `_observers` collection and a reference to the observer that is added to the collection. These references are assigned to local variables. When the object's `Dispose` method is called, it checks whether the observer still exists in the `_observers` collection, and, if it does, removes the observer. :::code source="snippets/observables/Unsubscriber.cs"::: [!code-vb[Conceptual.ObserverDesignPattern#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesignpattern/vb/provider.vb#3)] -The following example provides an implementation named `ArrivalsMonitor`, which is a base class that displays baggage claim information. The information is displayed alphabetically, by the name of the originating city. The methods of `ArrivalsMonitor` are marked as `overridable` (in Visual Basic) or `virtual` (in C#), so they can be overridden in a derived class. +The following example provides an implementation named `ArrivalsMonitor`, which is a base class that displays baggage claim information. The information is displayed alphabetically, by the name of the originating city. The methods of `ArrivalsMonitor` are marked as `overridable` (in Visual Basic) or `virtual` (in C#), so they can be overridden in a derived class. :::code source="snippets/observables/ArrivalsMonitor.cs"::: [!code-vb[Conceptual.ObserverDesignPattern#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesignpattern/vb/observer.vb#4)] -The `ArrivalsMonitor` class includes the `Subscribe` and `Unsubscribe` methods. The `Subscribe` method enables the class to save the implementation returned by the call to to a private variable. The `Unsubscribe` method enables the class to unsubscribe from notifications by calling the provider's implementation. `ArrivalsMonitor` also provides implementations of the , , and methods. Only the implementation contains a significant amount of code. The method works with a private, sorted, generic object that maintains information about the airports of origin for arriving flights and the carousels on which their baggage is available. If the `BaggageHandler` class reports a new flight arrival, the method implementation adds information about that flight to the list. If the `BaggageHandler` class reports that the flight's baggage has been unloaded, the method removes that flight from the list. Whenever a change is made, the list is sorted and displayed to the console. +The `ArrivalsMonitor` class includes the `Subscribe` and `Unsubscribe` methods. The `Subscribe` method enables the class to save the implementation returned by the call to to a private variable. The `Unsubscribe` method enables the class to unsubscribe from notifications by calling the provider's implementation. `ArrivalsMonitor` also provides implementations of the , , and methods. Only the implementation contains a significant amount of code. The method works with a private, sorted, generic object that maintains information about the airports of origin for arriving flights and the carousels on which their baggage is available. If the `BaggageHandler` class reports a new flight arrival, the method implementation adds information about that flight to the list. If the `BaggageHandler` class reports that the flight's baggage has been unloaded, the method removes that flight from the list. Whenever a change is made, the list is sorted and displayed to the console. The following example contains the application entry point that instantiates the `BaggageHandler` class and two instances of the `ArrivalsMonitor` class, and uses the `BaggageHandler.BaggageStatus` method to add and remove information about arriving flights. In each case, the observers receive updates and correctly display baggage claim information. diff --git a/docs/standard/exceptions/best-practices-for-exceptions.md b/docs/standard/exceptions/best-practices-for-exceptions.md index 19de71b2c8890..21693ee6d7c9d 100644 --- a/docs/standard/exceptions/best-practices-for-exceptions.md +++ b/docs/standard/exceptions/best-practices-for-exceptions.md @@ -55,7 +55,7 @@ The approach to choose depends on how often you expect the event to occur. ### Call `Try*` methods to avoid exceptions -If the performance cost of exceptions is prohibitive, some .NET library methods provide alternative forms of error handling. For example, throws an if the value to be parsed is too large to be represented by . However, doesn't throw this exception. Instead, it returns a Boolean and has an `out` parameter that contains the parsed valid integer upon success. has similar behavior for attempting to get a value from a dictionary. +If the performance cost of exceptions is prohibitive, some .NET library methods provide alternative forms of error handling. For example, throws an if the value to be parsed is too large to be represented by . However, doesn't throw this exception. Instead, it returns a Boolean and has an `out` parameter that contains the parsed valid integer upon success. has similar behavior for attempting to get a value from a dictionary. ### Catch cancellation and asynchronous exceptions @@ -231,19 +231,19 @@ It's common for a class to throw the same exception from different places in its Some key .NET exception types have such static `throw` helper methods that allocate and throw the exception. You should call these methods instead of constructing and throwing the corresponding exception type: -- +- - - -- -- -- -- -- -- -- -- -- -- +- +- +- +- +- +- +- +- +- +- > [!TIP] > The following code analysis rules can help you find places in your code where you can take advantage of these static `throw` helpers: [CA1510](../../fundamentals/code-analysis/quality-rules/ca1510.md), [CA1511](../../fundamentals/code-analysis/quality-rules/ca1511.md), [CA1512](../../fundamentals/code-analysis/quality-rules/ca1512.md), and [CA1513](../../fundamentals/code-analysis/quality-rules/ca1513.md). diff --git a/docs/standard/exceptions/handling-com-interop-exceptions.md b/docs/standard/exceptions/handling-com-interop-exceptions.md index f5cb7ea21c04d..8b1fc3341493e 100644 --- a/docs/standard/exceptions/handling-com-interop-exceptions.md +++ b/docs/standard/exceptions/handling-com-interop-exceptions.md @@ -2,7 +2,7 @@ description: "Learn more about: Handling COM Interop Exceptions" title: "Handling COM Interop Exceptions" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "unmanaged code, exceptions" - "exceptions, unmanaged code" - "HRESULTs" @@ -12,17 +12,17 @@ ms.topic: how-to --- # Handling COM Interop Exceptions -Managed and unmanaged code can work together to handle exceptions. If a method throws an exception in managed code, the common language runtime can pass an HRESULT to a COM object. If a method fails in unmanaged code by returning a failure HRESULT, the runtime throws an exception that can be caught by managed code. - - The runtime automatically maps the HRESULT from COM interop to more specific exceptions. For example, E_ACCESSDENIED becomes , E_OUTOFMEMORY becomes , and so on. - - If the HRESULT is a custom result or if it is unknown to the runtime, the runtime passes a generic to the client. The **ErrorCode** property of the **COMException** contains the HRESULT value. - -## Working with IErrorInfo - - When an error is passed from COM to managed code, the runtime populates the exception object with error information. COM objects that support IErrorInfo and return HRESULTS provide this information to managed code exceptions. For example, the runtime maps the Description from the COM error to the exception's property. If the HRESULT provides no additional error information, the runtime fills many of the exception's properties with default values. - - If a method fails in unmanaged code, an exception can be passed to a managed code segment. The topic [HRESULTS and Exceptions](../../framework/interop/how-to-map-hresults-and-exceptions.md) contains a table showing how HRESULTS map to runtime exception objects. +Managed and unmanaged code can work together to handle exceptions. If a method throws an exception in managed code, the common language runtime can pass an HRESULT to a COM object. If a method fails in unmanaged code by returning a failure HRESULT, the runtime throws an exception that can be caught by managed code. + + The runtime automatically maps the HRESULT from COM interop to more specific exceptions. For example, E_ACCESSDENIED becomes , E_OUTOFMEMORY becomes , and so on. + + If the HRESULT is a custom result or if it is unknown to the runtime, the runtime passes a generic to the client. The **ErrorCode** property of the **COMException** contains the HRESULT value. + +## Working with IErrorInfo + + When an error is passed from COM to managed code, the runtime populates the exception object with error information. COM objects that support IErrorInfo and return HRESULTS provide this information to managed code exceptions. For example, the runtime maps the Description from the COM error to the exception's property. If the HRESULT provides no additional error information, the runtime fills many of the exception's properties with default values. + + If a method fails in unmanaged code, an exception can be passed to a managed code segment. The topic [HRESULTS and Exceptions](../../framework/interop/how-to-map-hresults-and-exceptions.md) contains a table showing how HRESULTS map to runtime exception objects. ## See also diff --git a/docs/standard/garbage-collection/app-domain-resource-monitoring.md b/docs/standard/garbage-collection/app-domain-resource-monitoring.md index c2f7429689566..3c25ae1a776a0 100644 --- a/docs/standard/garbage-collection/app-domain-resource-monitoring.md +++ b/docs/standard/garbage-collection/app-domain-resource-monitoring.md @@ -27,7 +27,7 @@ As soon as ARM is enabled, it begins collecting data on all application domains - The host can enable ARM by requesting the [ICLRAppDomainResourceMonitor](../../framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-interface.md) hosting interface. Once this interface is successfully obtained, ARM is enabled. -- Managed code can enable ARM by setting the static (`Shared` in Visual Basic) property to `true`. As soon as the property is set, ARM is enabled. +- Managed code can enable ARM by setting the static (`Shared` in Visual Basic) property to `true`. As soon as the property is set, ARM is enabled. - You can enable ARM after startup by listening to ETW events. ARM is enabled and begins raising events for all application domains when you enable the public provider `Microsoft-Windows-DotNETRuntime` by using the `AppDomainResourceManagementKeyword` keyword. To correlate data with application domains and threads, you must also enable the `Microsoft-Windows-DotNETRuntimeRundown` provider with the `ThreadingKeyword` keyword. @@ -37,7 +37,7 @@ ARM provides the total processor time that is used by an application domain and - **Total processor time for an application domain, in seconds**: This is calculated by adding up the thread times reported by the operating system for all threads that spent time executing in the application domain during its lifetime. Blocked or sleeping threads do not use processor time. When a thread calls into native code, the time that the thread spends in native code is included in the count for the application domain where the call was made. - - Managed API: property. + - Managed API: property. - Hosting API: [ICLRAppDomainResourceMonitor::GetCurrentCpuTime](../../framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentcputime-method.md) method. @@ -45,7 +45,7 @@ ARM provides the total processor time that is used by an application domain and - **Total managed allocations made by an application domain during its lifetime, in bytes**: Total allocations do not always reflect memory use by an application domain, because the allocated objects might be short-lived. However, if an application allocates and frees huge numbers of objects, the cost of the allocations could be significant. - - Managed API: property. + - Managed API: property. - Hosting API: [ICLRAppDomainResourceMonitor::GetCurrentAllocated](../../framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentallocated-method.md) method. @@ -53,7 +53,7 @@ ARM provides the total processor time that is used by an application domain and - **Managed memory, in bytes, that is referenced by an application domain and that survived the most recent full, blocking collection**: This number is accurate only after a full, blocking collection. (This is in contrast to concurrent collections, which occur in the background and do not block the application.) For example, the method overload causes a full, blocking collection. - - Managed API: property. + - Managed API: property. - Hosting API: [ICLRAppDomainResourceMonitor::GetCurrentSurvived](../../framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentsurvived-method.md) method, `pAppDomainBytesSurvived` parameter. @@ -61,7 +61,7 @@ ARM provides the total processor time that is used by an application domain and - **Total managed memory, in bytes, that is referenced by the process and that survived the most recent full, blocking collection**: The survived memory for individual application domains can be compared to this number. - - Managed API: property. + - Managed API: property. - Hosting API: [ICLRAppDomainResourceMonitor::GetCurrentSurvived](../../framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentsurvived-method.md) method, `pTotalBytesSurvived` parameter. @@ -73,9 +73,9 @@ To determine when counts of survived memory are accurate, you need to know when #### Managed API -If you use the properties of the class, you can use the method to register for notification of full collections. The threshold you use is not important, because you are waiting for the completion of a collection rather than the approach of a collection. You can then call the method, which blocks until a full collection has completed. You can create a thread that calls the method in a loop and does any necessary analysis whenever the method returns. +If you use the properties of the class, you can use the method to register for notification of full collections. The threshold you use is not important, because you are waiting for the completion of a collection rather than the approach of a collection. You can then call the method, which blocks until a full collection has completed. You can create a thread that calls the method in a loop and does any necessary analysis whenever the method returns. -Alternatively, you can call the method periodically to see if the count of generation 2 collections has increased. Depending on the polling frequency, this technique might not provide as accurate an indication of the occurrence of a full collection. +Alternatively, you can call the method periodically to see if the count of generation 2 collections has increased. Depending on the polling frequency, this technique might not provide as accurate an indication of the occurrence of a full collection. #### Hosting API @@ -83,7 +83,7 @@ If you use the unmanaged hosting API, your host must pass the CLR an implementat ## See also -- +- - [ICLRAppDomainResourceMonitor Interface](../../framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-interface.md) - [``](../../framework/configure-apps/file-schema/runtime/appdomainresourcemonitoring-element.md) - [CLR ETW Events](../../framework/performance/clr-etw-events.md) diff --git a/docs/standard/garbage-collection/fundamentals.md b/docs/standard/garbage-collection/fundamentals.md index 64285b55440fc..f27528ca7b48c 100644 --- a/docs/standard/garbage-collection/fundamentals.md +++ b/docs/standard/garbage-collection/fundamentals.md @@ -81,7 +81,7 @@ Garbage collection occurs when one of the following conditions is true: - The memory that's used by allocated objects on the managed heap surpasses an acceptable threshold. This threshold is continuously adjusted as the process runs. -- The method is called. In almost all cases, you don't have to call this method because the garbage collector runs continuously. This method is primarily used for unique situations and testing. +- The method is called. In almost all cases, you don't have to call this method because the garbage collector runs continuously. This method is primarily used for unique situations and testing. ## The managed heap @@ -178,7 +178,7 @@ A garbage collection has the following phases: Because generation 2 collections can occupy multiple segments, objects that are promoted into generation 2 can be moved into an older segment. Both generation 1 and generation 2 survivors can be moved to a different segment because they're promoted to generation 2. - Ordinarily, the large object heap (LOH) isn't compacted because copying large objects imposes a performance penalty. However, in .NET Core and in .NET Framework 4.5.1 and later, you can use the property to compact the large object heap on demand. In addition, the LOH is automatically compacted when a hard limit is set by specifying either: + Ordinarily, the large object heap (LOH) isn't compacted because copying large objects imposes a performance penalty. However, in .NET Core and in .NET Framework 4.5.1 and later, you can use the property to compact the large object heap on demand. In addition, the LOH is automatically compacted when a hard limit is set by specifying either: - A memory limit on a container. - The [GCHeapHardLimit](../../core/runtime-config/garbage-collector.md#heap-hard-limit) or [GCHeapHardLimitPercent](../../core/runtime-config/garbage-collector.md#heap-hard-limit-percent) runtime configuration options. diff --git a/docs/standard/garbage-collection/implementing-dispose.md b/docs/standard/garbage-collection/implementing-dispose.md index 9cb3dfb140c09..7a1b4fbbe7c6d 100644 --- a/docs/standard/garbage-collection/implementing-dispose.md +++ b/docs/standard/garbage-collection/implementing-dispose.md @@ -14,19 +14,19 @@ ai-usage: ai-assisted # Implement a Dispose method -The method is primarily implemented to release unmanaged resources. When working with instance members that are implementations, it's common to cascade calls. There are other reasons for implementing , for example, to free memory that was allocated, remove an item that was added to a collection, or signal the release of a lock that was acquired. +The method is primarily implemented to release unmanaged resources. When working with instance members that are implementations, it's common to cascade calls. There are other reasons for implementing , for example, to free memory that was allocated, remove an item that was added to a collection, or signal the release of a lock that was acquired. The [.NET garbage collector](index.md) doesn't allocate or release unmanaged memory. The pattern for disposing an object, referred to as the [dispose pattern](../design-guidelines/dispose-pattern.md), imposes order on the lifetime of an object. The dispose pattern is used for objects that implement the interface. This pattern is common when interacting with file and pipe handles, registry handles, wait handles, or pointers to blocks of unmanaged memory, because the garbage collector is unable to reclaim unmanaged objects. -To help ensure that resources are always cleaned up appropriately, a method should be idempotent, such that it's callable multiple times without throwing an exception. Furthermore, subsequent invocations of should do nothing. +To help ensure that resources are always cleaned up appropriately, a method should be idempotent, such that it's callable multiple times without throwing an exception. Furthermore, subsequent invocations of should do nothing. -The code example provided for the method shows how garbage collection can cause a finalizer to run while an unmanaged reference to the object or its members is still in use. It may make sense to utilize to make the object ineligible for garbage collection from the start of the current routine to the point where this method is called. +The code example provided for the method shows how garbage collection can cause a finalizer to run while an unmanaged reference to the object or its members is still in use. It may make sense to utilize to make the object ineligible for garbage collection from the start of the current routine to the point where this method is called. [!INCLUDE [disposables-and-dependency-injection](includes/disposables-and-dependency-injection.md)] ## Cascade dispose calls -If your class owns an instance of another type that implements , the containing class itself should also implement . Typically a class that instantiates an implementation and stores it as an instance member (or property) is also responsible for its cleanup. This helps ensure that the referenced disposable types are given the opportunity to deterministically perform cleanup through the method. In the following example, the class is `sealed` (or `NotInheritable` in Visual Basic). +If your class owns an instance of another type that implements , the containing class itself should also implement . Typically a class that instantiates an implementation and stores it as an instance member (or property) is also responsible for its cleanup. This helps ensure that the referenced disposable types are given the opportunity to deterministically perform cleanup through the method. In the following example, the class is `sealed` (or `NotInheritable` in Visual Basic). :::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.disposable/cs/Foo.cs"::: :::code language="vb" source="../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.disposable/vb/Foo.vb"::: @@ -38,11 +38,11 @@ If your class owns an instance of another type that implements interface requires the implementation of a single parameterless method, . Also, any non-sealed class should have an `Dispose(bool)` overload method. +The interface requires the implementation of a single parameterless method, . Also, any non-sealed class should have an `Dispose(bool)` overload method. Method signatures are: -- `public` non-virtual (`NotOverridable` in Visual Basic) ( implementation). +- `public` non-virtual (`NotOverridable` in Visual Basic) ( implementation). - `protected virtual` (`Overridable` in Visual Basic) `Dispose(bool)`. ### The Dispose() method @@ -52,24 +52,24 @@ Because the `public`, non-virtual (`NotOverridable` in Visual Basic), parameterl :::code language="csharp" source="./snippets/dispose-pattern/csharp/Disposable.cs" id="Dispose"::: :::code language="vb" source="./snippets/dispose-pattern/vb/Disposable.vb" id="Dispose"::: -The `Dispose` method performs all object cleanup, so the garbage collector no longer needs to call the objects' override. Therefore, the call to the method prevents the garbage collector from running the finalizer. If the type has no finalizer, the call to has no effect. The actual cleanup is performed by the `Dispose(bool)` method overload. +The `Dispose` method performs all object cleanup, so the garbage collector no longer needs to call the objects' override. Therefore, the call to the method prevents the garbage collector from running the finalizer. If the type has no finalizer, the call to has no effect. The actual cleanup is performed by the `Dispose(bool)` method overload. ### The Dispose(bool) method overload -In the overload, the `disposing` parameter is a that indicates whether the method call comes from a method (its value is `true`) or from a finalizer (its value is `false`). +In the overload, the `disposing` parameter is a that indicates whether the method call comes from a method (its value is `true`) or from a finalizer (its value is `false`). :::code language="csharp" source="./snippets/dispose-pattern/csharp/Disposable.cs" id="DisposeBool"::: :::code language="vb" source="./snippets/dispose-pattern/vb/Disposable.vb" id="DisposeBool"::: > [!IMPORTANT] - > The `disposing` parameter should be `false` when called from a finalizer, and `true` when called from the method. In other words, it is `true` when deterministically called and `false` when nondeterministically called. + > The `disposing` parameter should be `false` when called from a finalizer, and `true` when called from the method. In other words, it is `true` when deterministically called and `false` when nondeterministically called. The body of the method consists of three blocks of code: - A block for conditional return if object is already disposed. - A conditional block that frees managed resources. This block executes if the value of `disposing` is `true`. The managed resources that it frees can include: - - **Managed objects that implement .** The conditional block can be used to call their implementation (cascade dispose). If you have used a derived class of to wrap your unmanaged resource, you should call the implementation here. + - **Managed objects that implement .** The conditional block can be used to call their implementation (cascade dispose). If you have used a derived class of to wrap your unmanaged resource, you should call the implementation here. - **Managed objects that consume large amounts of memory or consume scarce resources.** Assign large managed object references to `null` to make them more likely to be unreachable. This releases them faster than if they were reclaimed nondeterministically. - A block that frees unmanaged resources. This block executes regardless of the value of the `disposing` parameter. @@ -80,19 +80,19 @@ If the method call comes from a finalizer, only the code that frees unmanaged re All non-sealed classes (or Visual Basic classes not modified as `NotInheritable`) should be considered a potential base class, because they could be inherited. If you implement the dispose pattern for any potential base class, you must add the following methods to your class: -- A implementation that calls the `Dispose(bool)` method. +- A implementation that calls the `Dispose(bool)` method. - A `Dispose(bool)` method that performs the actual cleanup. -- If your class deals with unmanaged resources, either provide an override to the method or wrap the unmanaged resource in a . +- If your class deals with unmanaged resources, either provide an override to the method or wrap the unmanaged resource in a . > [!IMPORTANT] -> A finalizer (a override) is only required if you directly reference unmanaged resources. This is a highly advanced scenario that can be typically avoided: +> A finalizer (a override) is only required if you directly reference unmanaged resources. This is a highly advanced scenario that can be typically avoided: > > - **If your class references only managed objects**, it's still possible for the class to implement the dispose pattern. There's no need to implement a finalizer. > - **If you need to deal with unmanaged resources**, we strongly recommend wrapping the unmanaged handle into a . The provides a finalizer so you don't have to write one yourself. For more information, see the [Safe handles](#safe-handles) paragraph. ### Base class with managed resources -Here's a general example of implementing the dispose pattern for a base class that only owns managed resources. The example uses to ensure thread-safe disposal. +Here's a general example of implementing the dispose pattern for a base class that only owns managed resources. The example uses to ensure thread-safe disposal. :::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.idisposable/cs/base1.cs"::: :::code language="vb" source="../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.idisposable/vb/base1.vb"::: @@ -102,25 +102,25 @@ Here's a general example of implementing the dispose pattern for a base class th ### Base class with unmanaged resources -Here's an example for implementing the dispose pattern for a base class that overrides in order to clean up unmanaged resources it owns. The example also demonstrates a way to implement `Dispose(bool)` in a thread-safe manner. Synchronization might be critical when dealing with unmanaged resources in a multi-threaded application. As mentioned earlier, this is an advanced scenario. +Here's an example for implementing the dispose pattern for a base class that overrides in order to clean up unmanaged resources it owns. The example also demonstrates a way to implement `Dispose(bool)` in a thread-safe manner. Synchronization might be critical when dealing with unmanaged resources in a multi-threaded application. As mentioned earlier, this is an advanced scenario. :::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.idisposable/cs/base2.cs"::: :::code language="vb" source="../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.idisposable/vb/base2.vb"::: > [!NOTE] > -> - The previous example uses to allocate 10 bytes on the unmanaged heap in the constructor and free the buffer in `Dispose(bool)` by calling . This is a dummy allocation for illustrational purpose. +> - The previous example uses to allocate 10 bytes on the unmanaged heap in the constructor and free the buffer in `Dispose(bool)` by calling . This is a dummy allocation for illustrational purpose. > - Again, it's recommended to avoid implementing a finalizer. See [Implement the dispose pattern using a custom safe handle](#implement-the-dispose-pattern-using-a-custom-safe-handle) for an equivalent of the previous example that delegates non-deterministic finalization and synchronization to . > [!TIP] -> In C#, you implement a finalization by providing a [finalizer](../../csharp/programming-guide/classes-and-structs/finalizers.md), not by overriding . In Visual Basic, you create a finalizer with `Protected Overrides Sub Finalize()`. +> In C#, you implement a finalization by providing a [finalizer](../../csharp/programming-guide/classes-and-structs/finalizers.md), not by overriding . In Visual Basic, you create a finalizer with `Protected Overrides Sub Finalize()`. ## Implement the dispose pattern for a derived class -A class derived from a class that implements the interface shouldn't implement , because the base class implementation of is inherited by its derived classes. Instead, to clean up a derived class, you provide the following: +A class derived from a class that implements the interface shouldn't implement , because the base class implementation of is inherited by its derived classes. Instead, to clean up a derived class, you provide the following: - A `protected override void Dispose(bool)` method that overrides the base class method and performs the actual cleanup of the derived class. This method must also call the `base.Dispose(bool)` (`MyBase.Dispose(bool)` in Visual Basic) method passing it the disposing status (`bool disposing` parameter) as an argument. -- Either a class derived from that wraps your unmanaged resource (recommended), or an override to the method. The class provides a finalizer that frees you from having to code one. If you do provide a finalizer, it must call the `Dispose(bool)` overload with `false` argument. +- Either a class derived from that wraps your unmanaged resource (recommended), or an override to the method. The class provides a finalizer that frees you from having to code one. If you do provide a finalizer, it must call the `Dispose(bool)` overload with `false` argument. Here's an example of the general pattern for implementing the dispose pattern for a derived class that uses a safe handle: @@ -130,7 +130,7 @@ Here's an example of the general pattern for implementing the dispose pattern fo > [!NOTE] > The previous example uses a object to illustrate the pattern; any object derived from could be used instead. Note that the example doesn't properly instantiate its object. -Here's the general pattern for implementing the dispose pattern for a derived class that overrides : +Here's the general pattern for implementing the dispose pattern for a derived class that overrides : :::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.idisposable/cs/derived2.cs"::: :::code language="vb" source="../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.idisposable/vb/derived2.vb"::: @@ -154,7 +154,7 @@ The following code demonstrates how to handle unmanaged resources by implementin > The behavior of the `DisposableBaseWithSafeHandle` class is equivalent to the behavior of the [`DisposableBaseWithFinalizer` class in a previous example](#base-class-with-unmanaged-resources), however the approach demonstrated here is safer: > > - There is no need to implement a finalizer, because will take care of finalization. -> - There is no need for synchronization to guarantee thread safety. Even though there is a race condition in the `Dispose` implementation of `DisposableBaseWithSafeHandle`, guarantees that is called only once. +> - There is no need for synchronization to guarantee thread safety. Even though there is a race condition in the `Dispose` implementation of `DisposableBaseWithSafeHandle`, guarantees that is called only once. ### Built-in safe handles in .NET @@ -171,11 +171,11 @@ The following derived classes in the namespac ## See also - [Disposal of services](../../core/extensions/dependency-injection/guidelines.md#disposal-of-services) -- +- - -- +- - - -- +- - [Define and consume classes and structs (C++/CLI)](/cpp/dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli) - [The SafeHandle class](../../fundamentals/runtime-libraries/system-runtime-interopservices-safehandle.md) diff --git a/docs/standard/garbage-collection/implementing-disposeasync.md b/docs/standard/garbage-collection/implementing-disposeasync.md index c0d4d788edf40..bbb096e0d67cc 100644 --- a/docs/standard/garbage-collection/implementing-disposeasync.md +++ b/docs/standard/garbage-collection/implementing-disposeasync.md @@ -76,7 +76,7 @@ In the preceding example: - The `ExampleAsyncDisposable` is a nonsealed class that implements the interface. - It contains a private `IAsyncDisposable` field, `_example`, that's initialized in the constructor. -- The `DisposeAsync` method delegates to the `DisposeAsyncCore` method and calls to notify the garbage collector that the finalizer doesn't have to run. +- The `DisposeAsync` method delegates to the `DisposeAsyncCore` method and calls to notify the garbage collector that the finalizer doesn't have to run. - It contains a `DisposeAsyncCore()` method that calls the `_example.DisposeAsync()` method, and sets the field to `null`. - The `DisposeAsyncCore()` method is `virtual`, which allows subclasses to override it with custom behavior. @@ -133,13 +133,13 @@ await using var transaction = await context.Database.BeginTransactionAsync(token In the preceding example: -- The method is awaited. +- The method is awaited. - The return type is , which implements `IAsyncDisposable`. - The `transaction` is used asynchronously, and also awaited. ## Stacked usings -In situations where you create and use multiple objects that implement , it's possible that stacking `await using` statements with could prevent calls to in errant conditions. To ensure that is always called, you should avoid stacking. The following three code examples show acceptable patterns to use instead. +In situations where you create and use multiple objects that implement , it's possible that stacking `await using` statements with could prevent calls to in errant conditions. To ensure that is always called, you should avoid stacking. The following three code examples show acceptable patterns to use instead. ### Acceptable pattern one diff --git a/docs/standard/garbage-collection/index.md b/docs/standard/garbage-collection/index.md index f9c140b6c2b0b..15a4d15780e2d 100644 --- a/docs/standard/garbage-collection/index.md +++ b/docs/standard/garbage-collection/index.md @@ -2,7 +2,7 @@ title: .NET garbage collection description: Learn about garbage collection in .NET. The .NET garbage collector manages the allocation and release of memory for your application. ms.date: 04/21/2020 -helpviewer_keywords: +helpviewer_keywords: - "memory, garbage collection" - "garbage collection, automatic memory management" - "GC [.NET]" @@ -21,35 +21,35 @@ ms.assetid: 22b6cb97-0c80-4eeb-a2cf-5ed7655e37f9 --- # Garbage collection -.NET's garbage collector manages the allocation and release of memory for your application. Each time you create a new object, the common language runtime allocates memory for the object from the managed heap. As long as address space is available in the managed heap, the runtime continues to allocate space for new objects. However, memory is not infinite. Eventually the garbage collector must perform a collection in order to free some memory. The garbage collector's optimizing engine determines the best time to perform a collection, based upon the allocations being made. When the garbage collector performs a collection, it checks for objects in the managed heap that are no longer being used by the application and performs the necessary operations to reclaim their memory. - +.NET's garbage collector manages the allocation and release of memory for your application. Each time you create a new object, the common language runtime allocates memory for the object from the managed heap. As long as address space is available in the managed heap, the runtime continues to allocate space for new objects. However, memory is not infinite. Eventually the garbage collector must perform a collection in order to free some memory. The garbage collector's optimizing engine determines the best time to perform a collection, based upon the allocations being made. When the garbage collector performs a collection, it checks for objects in the managed heap that are no longer being used by the application and performs the necessary operations to reclaim their memory. + ## In this section - -|Title|Description| -|-----------|-----------------| -|[Fundamentals of garbage collection](fundamentals.md)|Describes how garbage collection works, how objects are allocated on the managed heap, and other core concepts.| + +|Title|Description| +|-----------|-----------------| +|[Fundamentals of garbage collection](fundamentals.md)|Describes how garbage collection works, how objects are allocated on the managed heap, and other core concepts.| |[Workstation and server garbage collection](workstation-server-gc.md)|Describes the differences between workstation garbage collection for client apps and server garbage collection for server apps.| |[Background garbage collection](background-gc.md)|Describes background garbage collection, which is the collection of generation 0 and 1 objects while generation 2 collection is in progress.| |[The large object heap](large-object-heap.md)|Describes the large object heap (LOH) and how large objects are garbage-collected.| -|[Garbage collection and performance](performance.md)|Describes the performance checks you can use to diagnose garbage collection and performance issues.| -|[Induced collections](induced.md)|Describes how to make a garbage collection occur.| -|[Latency modes](latency.md)|Describes the modes that determine the intrusiveness of garbage collection.| -|[Optimization for shared web hosting](optimization-for-shared-web-hosting.md)|Describes how to optimize garbage collection on servers shared by several small Web sites.| -|[Garbage collection notifications](notifications.md)|Describes how to determine when a full garbage collection is approaching and when it has completed.| -|[Application domain resource monitoring](app-domain-resource-monitoring.md)|Describes how to monitor CPU and memory usage by an application domain.| -|[Weak references](weak-references.md)|Describes features that permit the garbage collector to collect an object while still allowing the application to access that object.| - +|[Garbage collection and performance](performance.md)|Describes the performance checks you can use to diagnose garbage collection and performance issues.| +|[Induced collections](induced.md)|Describes how to make a garbage collection occur.| +|[Latency modes](latency.md)|Describes the modes that determine the intrusiveness of garbage collection.| +|[Optimization for shared web hosting](optimization-for-shared-web-hosting.md)|Describes how to optimize garbage collection on servers shared by several small Web sites.| +|[Garbage collection notifications](notifications.md)|Describes how to determine when a full garbage collection is approaching and when it has completed.| +|[Application domain resource monitoring](app-domain-resource-monitoring.md)|Describes how to monitor CPU and memory usage by an application domain.| +|[Weak references](weak-references.md)|Describes features that permit the garbage collector to collect an object while still allowing the application to access that object.| + ## Reference -- -- -- -- -- -- -- -- - +- +- +- +- +- +- +- +- + ## See also - [Clean up unmanaged resources](unmanaged.md) diff --git a/docs/standard/garbage-collection/induced.md b/docs/standard/garbage-collection/induced.md index 9e968661fb687..762f3e2c6109b 100644 --- a/docs/standard/garbage-collection/induced.md +++ b/docs/standard/garbage-collection/induced.md @@ -2,35 +2,35 @@ description: "Learn more about: Induced Collections" title: "Induced Collections" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "garbage collection, forced" ms.assetid: 019008fe-4708-4e65-bebf-04fd9941e149 --- # Induced Collections -In most cases, the garbage collector can determine the best time to perform a collection, and you should let it run independently. There are rare situations when a forced collection might improve your application's performance. In these cases, you can induce garbage collection by using the method to force a garbage collection. - - Use the method when there is a significant reduction in the amount of memory being used at a specific point in your application's code. For example, if your application uses a complex dialog box that has several controls, calling when the dialog box is closed could improve performance by immediately reclaiming the memory used by the dialog box. Be sure that your application is not inducing garbage collection too frequently, because that can decrease performance if the garbage collector is trying to reclaim objects at non-optimal times. You can supply a enumeration value to the method to collect only when collection would be productive, as discussed in the next section. - -## GC collection mode - - You can use one of the method overloads that includes a value to specify the behavior for a forced collection as follows. - -|`GCCollectionMode` value|Description| -|------------------------------|-----------------| -||Uses the default garbage collection setting for the running version of .NET.| -||Forces garbage collection to occur immediately. This is equivalent to calling the overload. It results in a full blocking collection of all generations.

You can also compact the large object heap by setting the property to before forcing an immediate full blocking garbage collection.| -||Enables the garbage collector to determine whether the current time is optimal to reclaim objects.

The garbage collector could determine that a collection would not be productive enough to be justified, in which case it will return without reclaiming objects.| - -## Background or blocking collections - - You can call the method overload to specify whether an induced collection is blocking or not. The type of collection performed depends on a combination of the method's `mode` and `blocking` parameters. `mode` is a member of the enumeration, and `blocking` is a value. The following table summarizes the interaction of the `mode` and `blocking` arguments. - -|`mode`|`blocking` = `true`|`blocking` = `false`| -|------------|--------------------------|---------------------------| -| or |A blocking collection is performed as soon as possible. If a background collection is in progress and generation is 0 or 1, the method immediately triggers a blocking collection and returns when the collection is finished. If a background collection is in progress and the `generation` parameter is 2, the method waits until the background collection is finished, triggers a blocking generation 2 collection, and then returns.|A collection is performed as soon as possible. The method requests a background collection, but this is not guaranteed; depending on the circumstances, a blocking collection may still be performed. If a background collection is already in progress, the method returns immediately.| -||A blocking collection may be performed, depending on the state of the garbage collector and the `generation` parameter. The garbage collector tries to provide optimal performance.|A collection may be performed, depending on the state of the garbage collector. The method requests a background collection, but this is not guaranteed; depending on the circumstances, a blocking collection may still be performed. The garbage collector tries to provide optimal performance. If a background collection is already in progress, the method returns immediately.| - +In most cases, the garbage collector can determine the best time to perform a collection, and you should let it run independently. There are rare situations when a forced collection might improve your application's performance. In these cases, you can induce garbage collection by using the method to force a garbage collection. + + Use the method when there is a significant reduction in the amount of memory being used at a specific point in your application's code. For example, if your application uses a complex dialog box that has several controls, calling when the dialog box is closed could improve performance by immediately reclaiming the memory used by the dialog box. Be sure that your application is not inducing garbage collection too frequently, because that can decrease performance if the garbage collector is trying to reclaim objects at non-optimal times. You can supply a enumeration value to the method to collect only when collection would be productive, as discussed in the next section. + +## GC collection mode + + You can use one of the method overloads that includes a value to specify the behavior for a forced collection as follows. + +|`GCCollectionMode` value|Description| +|------------------------------|-----------------| +||Uses the default garbage collection setting for the running version of .NET.| +||Forces garbage collection to occur immediately. This is equivalent to calling the overload. It results in a full blocking collection of all generations.

You can also compact the large object heap by setting the property to before forcing an immediate full blocking garbage collection.| +||Enables the garbage collector to determine whether the current time is optimal to reclaim objects.

The garbage collector could determine that a collection would not be productive enough to be justified, in which case it will return without reclaiming objects.| + +## Background or blocking collections + + You can call the method overload to specify whether an induced collection is blocking or not. The type of collection performed depends on a combination of the method's `mode` and `blocking` parameters. `mode` is a member of the enumeration, and `blocking` is a value. The following table summarizes the interaction of the `mode` and `blocking` arguments. + +|`mode`|`blocking` = `true`|`blocking` = `false`| +|------------|--------------------------|---------------------------| +| or |A blocking collection is performed as soon as possible. If a background collection is in progress and generation is 0 or 1, the method immediately triggers a blocking collection and returns when the collection is finished. If a background collection is in progress and the `generation` parameter is 2, the method waits until the background collection is finished, triggers a blocking generation 2 collection, and then returns.|A collection is performed as soon as possible. The method requests a background collection, but this is not guaranteed; depending on the circumstances, a blocking collection may still be performed. If a background collection is already in progress, the method returns immediately.| +||A blocking collection may be performed, depending on the state of the garbage collector and the `generation` parameter. The garbage collector tries to provide optimal performance.|A collection may be performed, depending on the state of the garbage collector. The method requests a background collection, but this is not guaranteed; depending on the circumstances, a blocking collection may still be performed. The garbage collector tries to provide optimal performance. If a background collection is already in progress, the method returns immediately.| + ## See also - [Latency Modes](latency.md) diff --git a/docs/standard/garbage-collection/large-object-heap.md b/docs/standard/garbage-collection/large-object-heap.md index b5ab3b732831a..7392c4c9e7fbd 100644 --- a/docs/standard/garbage-collection/large-object-heap.md +++ b/docs/standard/garbage-collection/large-object-heap.md @@ -67,7 +67,7 @@ In general, a GC occurs under one of the following three conditions: This is the typical case; most GCs happen because of allocations on the managed heap. -- The method is called. +- The method is called. If the parameterless method is called or another overload is passed as an argument, the LOH is collected along with the rest of the managed heap. diff --git a/docs/standard/garbage-collection/latency.md b/docs/standard/garbage-collection/latency.md index fd9cfb788fbb2..071196741002e 100644 --- a/docs/standard/garbage-collection/latency.md +++ b/docs/standard/garbage-collection/latency.md @@ -11,7 +11,7 @@ ms.assetid: 96278bb7-6eab-4612-8594-ceebfc887d81 To reclaim objects, the garbage collector (GC) must stop all the executing threads in an application. The period of time during which the garbage collector is active is referred to as its *latency*. -In some situations, such as when an application retrieves data or displays content, a full garbage collection can occur at a critical time and impede performance. You can adjust the intrusiveness of the garbage collector by setting the property to one of the values. +In some situations, such as when an application retrieves data or displays content, a full garbage collection can occur at a critical time and impede performance. You can adjust the intrusiveness of the garbage collector by setting the property to one of the values. ## Low latency settings @@ -27,7 +27,7 @@ During low latency periods, generation 2 collections are suppressed unless the f - The system receives a low memory notification from the operating system. -- Application code induces a collection by calling the method and specifying 2 for the `generation` parameter. +- Application code induces a collection by calling the method and specifying 2 for the `generation` parameter. ## Scenarios @@ -50,7 +50,7 @@ When you use [GCLatencyMode.LowLatency](xref:System.Runtime.GCLatencyMode.LowLat - While in the low latency mode, minimize the number of new allocations, in particular allocations onto the large object heap and pinned objects. -- Be aware of threads that could be allocating. Because the property setting is process-wide, exceptions can be generated on any thread that is allocating. +- Be aware of threads that could be allocating. Because the property setting is process-wide, exceptions can be generated on any thread that is allocating. - Wrap the low latency code in constrained execution regions. For more information, see [Constrained execution regions](../../framework/performance/constrained-execution-regions.md). diff --git a/docs/standard/garbage-collection/notifications.md b/docs/standard/garbage-collection/notifications.md index 6a11b4752f13a..c074fdf21b7ef 100644 --- a/docs/standard/garbage-collection/notifications.md +++ b/docs/standard/garbage-collection/notifications.md @@ -12,18 +12,18 @@ helpviewer_keywords: There are situations in which a full garbage collection (that is, a generation 2 collection) by the common language runtime may adversely affect performance. This can be an issue particularly with servers that process large volumes of requests; in this case, a long garbage collection can cause a request time-out. To prevent a full collection from occurring during a critical period, you can be notified that a full garbage collection is approaching and then take action to redirect the workload to another server instance. You can also induce a collection yourself, provided that the current server instance does not need to process requests. - The method registers for a notification to be raised when the runtime senses that a full garbage collection is approaching. There are two parts to this notification: when the full garbage collection is approaching and when the full garbage collection has completed. + The method registers for a notification to be raised when the runtime senses that a full garbage collection is approaching. There are two parts to this notification: when the full garbage collection is approaching and when the full garbage collection has completed. > [!WARNING] -> When the [``](../../framework/configure-apps/file-schema/runtime/gcconcurrent-element.md) configuration element is enabled, may return `NotApplicable` if the full GC was done as a background GC. +> When the [``](../../framework/configure-apps/file-schema/runtime/gcconcurrent-element.md) configuration element is enabled, may return `NotApplicable` if the full GC was done as a background GC. - To determine when a notification has been raised, use the and methods. Typically, you use these methods in a `while` loop to continually obtain a enumeration that shows the status of the notification. If that value is , you can do the following: + To determine when a notification has been raised, use the and methods. Typically, you use these methods in a `while` loop to continually obtain a enumeration that shows the status of the notification. If that value is , you can do the following: -- In response to a notification obtained with the method, you can redirect the workload and possibly induce a collection yourself. +- In response to a notification obtained with the method, you can redirect the workload and possibly induce a collection yourself. -- In response to a notification obtained with the method, you can make the current server instance available to process requests again. You can also gather information. For example, you can use the method to record the number of collections. +- In response to a notification obtained with the method, you can make the current server instance available to process requests again. You can also gather information. For example, you can use the method to record the number of collections. - The and the methods are designed to work together. Using one without the other can produce indeterminate results. + The and the methods are designed to work together. Using one without the other can produce indeterminate results. ## Full Garbage Collection @@ -35,7 +35,7 @@ There are situations in which a full garbage collection (that is, a generation 2 - A collection of generation 1 is escalated to a collection of generation 2 due to other factors. - The thresholds you specify in the method apply to the first two scenarios. However, in the first scenario you will not always receive the notification at the time proportional to the threshold values you specify for two reasons: + The thresholds you specify in the method apply to the first two scenarios. However, in the first scenario you will not always receive the notification at the time proportional to the threshold values you specify for two reasons: - The runtime does not check each small object allocation (for performance reasons). @@ -45,7 +45,7 @@ There are situations in which a full garbage collection (that is, a generation 2 ## Notification Threshold Parameters - The method has two parameters to specify the threshold values of the generation 2 objects and the large object heap. When those values are met, a garbage collection notification should be raised. The following table describes these parameters. + The method has two parameters to specify the threshold values of the generation 2 objects and the large object heap. When those values are met, a garbage collection notification should be raised. The following table describes these parameters. |Parameter|Description| |---------------|-----------------| @@ -60,21 +60,21 @@ There are situations in which a full garbage collection (that is, a generation 2 ### Description - In the following example, a group of servers service incoming Web requests. To simulate the workload of processing requests, byte arrays are added to a collection. Each server registers for a garbage collection notification and then starts a thread on the `WaitForFullGCProc` user method to continuously monitor the enumeration that is returned by the and the methods. + In the following example, a group of servers service incoming Web requests. To simulate the workload of processing requests, byte arrays are added to a collection. Each server registers for a garbage collection notification and then starts a thread on the `WaitForFullGCProc` user method to continuously monitor the enumeration that is returned by the and the methods. - The and the methods call their respective event-handling user methods when a notification is raised: + The and the methods call their respective event-handling user methods when a notification is raised: - `OnFullGCApproachNotify` This method calls the `RedirectRequests` user method, which instructs the request queuing server to suspend sending requests to the server. This is simulated by setting the class-level variable `bAllocate` to `false` so that no more objects are allocated. - Next, the `FinishExistingRequests` user method is called to finish processing the pending server requests. This is simulated by clearing the collection. + Next, the `FinishExistingRequests` user method is called to finish processing the pending server requests. This is simulated by clearing the collection. Finally, a garbage collection is induced because the workload is light. - `OnFullGCCompleteNotify` - This method calls the user method `AcceptRequests` to resume accepting requests because the server is no longer susceptible to a full garbage collection. This action is simulated by setting the `bAllocate` variable to `true` so that objects can resume being added to the collection. + This method calls the user method `AcceptRequests` to resume accepting requests because the server is no longer susceptible to a full garbage collection. This action is simulated by setting the `bAllocate` variable to `true` so that objects can resume being added to the collection. The following code contains the `Main` method of the example. [!code-csharp[GCNotification#2](../../../samples/snippets/csharp/VS_Snippets_CLR/GCNotification/cs/Program.cs#2)] diff --git a/docs/standard/garbage-collection/performance.md b/docs/standard/garbage-collection/performance.md index 49aad1f58ec9d..76d1c46e91cdf 100644 --- a/docs/standard/garbage-collection/performance.md +++ b/docs/standard/garbage-collection/performance.md @@ -397,7 +397,7 @@ This section describes the following procedures to isolate the cause of your per … ``` - Using an integer instead of a string for an ID can be more efficient. If the same string is being repeated thousands of times, consider string interning. For more information about string interning, see the reference topic for the method. + Using an integer instead of a string for an ID can be more efficient. If the same string is being repeated thousands of times, consider string interning. For more information about string interning, see the reference topic for the method. @@ -445,7 +445,7 @@ This section describes the following procedures to isolate the cause of your per GC.Collect(); ``` - If the test resolves the problem, this means that the garbage collector was not reclaiming objects, because the finalizers for those objects had been suspended. The method enables the finalizers to complete their tasks, and fixes the problem. + If the test resolves the problem, this means that the garbage collector was not reclaiming objects, because the finalizers for those objects had been suspended. The method enables the finalizers to complete their tasks, and fixes the problem. diff --git a/docs/standard/garbage-collection/unmanaged.md b/docs/standard/garbage-collection/unmanaged.md index 4b9c02e2b449e..22c5fd90fd734 100644 --- a/docs/standard/garbage-collection/unmanaged.md +++ b/docs/standard/garbage-collection/unmanaged.md @@ -20,31 +20,31 @@ For a majority of the objects that your app creates, you can rely on the [.NET g If your types use unmanaged resources, you should do the following: -- Implement the [dispose pattern](implementing-dispose.md). This requires that you provide an implementation to enable the deterministic release of unmanaged resources. A consumer of your type calls when the object (and the resources it uses) are no longer needed. The method immediately releases the unmanaged resources. +- Implement the [dispose pattern](implementing-dispose.md). This requires that you provide an implementation to enable the deterministic release of unmanaged resources. A consumer of your type calls when the object (and the resources it uses) are no longer needed. The method immediately releases the unmanaged resources. -- In the event that a consumer of your type forgets to call , provide a way for your unmanaged resources to be released. There are two ways to do this: +- In the event that a consumer of your type forgets to call , provide a way for your unmanaged resources to be released. There are two ways to do this: - - Use a safe handle to wrap your unmanaged resource. This is the recommended technique. Safe handles are derived from the abstract class and include a robust method. When you use a safe handle, you simply implement the interface and call your safe handle's method in your implementation. The safe handle's finalizer is called automatically by the garbage collector if its method is not called. + - Use a safe handle to wrap your unmanaged resource. This is the recommended technique. Safe handles are derived from the abstract class and include a robust method. When you use a safe handle, you simply implement the interface and call your safe handle's method in your implementation. The safe handle's finalizer is called automatically by the garbage collector if its method is not called. —**or**— - - Define a [finalizer](../../csharp/programming-guide/classes-and-structs/finalizers.md). Finalization enables the non-deterministic release of unmanaged resources when the consumer of a type fails to call to dispose of them deterministically. + - Define a [finalizer](../../csharp/programming-guide/classes-and-structs/finalizers.md). Finalization enables the non-deterministic release of unmanaged resources when the consumer of a type fails to call to dispose of them deterministically. > [!WARNING] > Object finalization can be a complex and error-prone operation, we recommend that you use a safe handle instead of providing your own finalizer. -Consumers of your type can then call your implementation directly to free memory used by unmanaged resources. When you properly implement a method, either your safe handle's method or your own override of the method becomes a safeguard to clean up resources in the event that the method is not called. +Consumers of your type can then call your implementation directly to free memory used by unmanaged resources. When you properly implement a method, either your safe handle's method or your own override of the method becomes a safeguard to clean up resources in the event that the method is not called. ## In this section [Implementing a Dispose method](implementing-dispose.md) describes how to implement the dispose pattern for releasing unmanaged resources. -[Using objects that implement `IDisposable`](using-objects.md) describes how consumers of a type ensure that its implementation is called. We strongly recommend using the C# `using` (or the Visual Basic `Using`) statement to do this. +[Using objects that implement `IDisposable`](using-objects.md) describes how consumers of a type ensure that its implementation is called. We strongly recommend using the C# `using` (or the Visual Basic `Using`) statement to do this. ## Reference | Type / Member | Description | |--|--| -| | Defines the method for releasing unmanaged resources. | -| | Provides for object finalization if unmanaged resources are not released by the method. | -| | Suppresses finalization. This method is customarily called from a `Dispose` method to prevent a finalizer from executing. | +| | Defines the method for releasing unmanaged resources. | +| | Provides for object finalization if unmanaged resources are not released by the method. | +| | Suppresses finalization. This method is customarily called from a `Dispose` method to prevent a finalizer from executing. | diff --git a/docs/standard/garbage-collection/using-objects.md b/docs/standard/garbage-collection/using-objects.md index 864d33d2f3576..a9aac470a0199 100644 --- a/docs/standard/garbage-collection/using-objects.md +++ b/docs/standard/garbage-collection/using-objects.md @@ -14,10 +14,10 @@ ms.assetid: 81b2cdb5-c91a-4a31-9c83-eadc52da5cf0 # Using objects that implement IDisposable -The common language runtime's garbage collector (GC) reclaims the memory used by managed objects. Typically, types that use unmanaged resources implement the or interface to allow the unmanaged resources to be reclaimed. When you finish using an object that implements , you call the object's or implementation to explicitly perform cleanup. You can do this in one of two ways: +The common language runtime's garbage collector (GC) reclaims the memory used by managed objects. Typically, types that use unmanaged resources implement the or interface to allow the unmanaged resources to be reclaimed. When you finish using an object that implements , you call the object's or implementation to explicitly perform cleanup. You can do this in one of two ways: - With the C# `using` statement or declaration (`Using` in Visual Basic). -- By implementing a `try/finally` block, and calling the or method in the `finally`. +- By implementing a `try/finally` block, and calling the or method in the `finally`. > [!IMPORTANT] > The GC does ***not*** dispose your objects, as it has no knowledge of or . The GC only knows whether an object is finalizable (that is, it defines an method), and when the object's finalizer needs to be called. For more information, see [How finalization works](/dotnet/api/system.object.finalize#how-finalization-works). For additional details on implementing `Dispose` and `DisposeAsync`, see: @@ -25,7 +25,7 @@ The common language runtime's garbage collector (GC) reclaims the memory used by > - [Implement a Dispose method](implementing-dispose.md) > - [Implement a DisposeAsync method](implementing-disposeasync.md) -Objects that implement or should always be properly disposed of, regardless of variable scoping, unless otherwise explicitly stated. Types that define a finalizer to release unmanaged resources usually call from either their `Dispose` or `DisposeAsync` implementation. Calling indicates to the GC that the finalizer has already been run and the object shouldn't be promoted for finalization. +Objects that implement or should always be properly disposed of, regardless of variable scoping, unless otherwise explicitly stated. Types that define a finalizer to release unmanaged resources usually call from either their `Dispose` or `DisposeAsync` implementation. Calling indicates to the GC that the finalizer has already been run and the object shouldn't be promoted for finalization. ## The using statement @@ -40,7 +40,7 @@ A [`using` declaration](../../csharp/language-reference/statements/using.md) is :::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.disposable/cs/UsingDeclaration.cs"::: -Although the class implements the interface, which indicates that it uses an unmanaged resource, the example doesn't explicitly call the method. When the C# or Visual Basic compiler encounters the `using` statement, it emits intermediate language (IL) that is equivalent to the following code that explicitly contains a `try/finally` block. +Although the class implements the interface, which indicates that it uses an unmanaged resource, the example doesn't explicitly call the method. When the C# or Visual Basic compiler encounters the `using` statement, it emits intermediate language (IL) that is equivalent to the following code that explicitly contains a `try/finally` block. :::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.disposable/cs/TryFinallyGenerated.cs"::: :::code language="vb" source="../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.disposable/vb/TryFinallyGenerated.vb"::: @@ -56,12 +56,12 @@ Instead of wrapping a `try/finally` block in a `using` statement, you may choose - To include a `catch` block to handle exceptions thrown in the `try` block. Otherwise, any exceptions thrown within the `using` statement are unhandled. - To instantiate an object that implements whose scope is not local to the block within which it is declared. -The following example is similar to the previous example, except that it uses a `try/catch/finally` block to instantiate, use, and dispose of a object, and to handle any exceptions thrown by the constructor and its method. The code in the `finally` block checks that the object that implements isn't `null` before it calls the method. Failure to do this can result in a exception at runtime. +The following example is similar to the previous example, except that it uses a `try/catch/finally` block to instantiate, use, and dispose of a object, and to handle any exceptions thrown by the constructor and its method. The code in the `finally` block checks that the object that implements isn't `null` before it calls the method. Failure to do this can result in a exception at runtime. :::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.disposable/cs/TryExplicitCatchFinally.cs"::: :::code language="vb" source="../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.disposable/vb/TryExplicitCatchFinally.vb"::: -You can follow this basic pattern if you choose to implement or must implement a `try/finally` block, because your programming language doesn't support a `using` statement but does allow direct calls to the method. +You can follow this basic pattern if you choose to implement or must implement a `try/finally` block, because your programming language doesn't support a `using` statement but does allow direct calls to the method. ## IDisposable instance members diff --git a/docs/standard/garbage-collection/weak-references.md b/docs/standard/garbage-collection/weak-references.md index 39c038147eef5..4649924e72824 100644 --- a/docs/standard/garbage-collection/weak-references.md +++ b/docs/standard/garbage-collection/weak-references.md @@ -2,7 +2,7 @@ title: "Weak References" description: Learn about weak references, which allow the .NET garbage collector to collect an object while still allowing the application to access the object. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "weak references, short" - "weak references, using" - "weak references, long" @@ -11,42 +11,42 @@ ms.assetid: 6a600fe5-3af3-4c64-82da-10a0a8e2d79b --- # Weak References -The garbage collector cannot collect an object in use by an application while the application's code can reach that object. The application is said to have a strong reference to the object. - - A weak reference permits the garbage collector to collect the object while still allowing the application to access the object. A weak reference is valid only during the indeterminate amount of time until the object is collected when no strong references exist. When you use a weak reference, the application can still obtain a strong reference to the object, which prevents it from being collected. However, there is always the risk that the garbage collector will get to the object first before a strong reference is reestablished. - - Weak references are useful for objects that use a lot of memory, but can be recreated easily if they are reclaimed by garbage collection. - - Suppose a tree view in a Windows Forms application displays a complex hierarchical choice of options to the user. If the underlying data is large, keeping the tree in memory is inefficient when the user is involved with something else in the application. - - When the user switches away to another part of the application, you can use the class to create a weak reference to the tree and destroy all strong references. When the user switches back to the tree, the application attempts to obtain a strong reference to the tree and, if successful, avoids reconstructing the tree. - - To establish a weak reference with an object, you create a using the instance of the object to be tracked. For a code example, see in the class library. - -## Short and Long Weak References - - You can create a short weak reference or a long weak reference: - -- Short - - The target of a short weak reference becomes `null` when the object is reclaimed by garbage collection. The weak reference is itself a managed object, and is subject to garbage collection just like any other managed object. A short weak reference is the parameterless constructor for . - -- Long - - A long weak reference is retained after the object's method has been called. This allows the object to be recreated, but the state of the object remains unpredictable. To use a long reference, specify `true` in the constructor. - - If the object's type does not have a method, the short weak reference functionality applies and the weak reference is valid only until the target is collected, which can occur anytime after the finalizer is run. - - To establish a strong reference and use the object again, cast the property of a to the type of the object. If the property returns `null`, the object was collected; otherwise, you can continue to use the object because the application has regained a strong reference to it. - -## Guidelines for Using Weak References - - Use long weak references only when necessary as the state of the object is unpredictable after finalization. - - Avoid using weak references to small objects because the pointer itself may be as large or larger. - - Avoid using weak references as an automatic solution to memory management problems. Instead, develop an effective caching policy for handling your application's objects. - +The garbage collector cannot collect an object in use by an application while the application's code can reach that object. The application is said to have a strong reference to the object. + + A weak reference permits the garbage collector to collect the object while still allowing the application to access the object. A weak reference is valid only during the indeterminate amount of time until the object is collected when no strong references exist. When you use a weak reference, the application can still obtain a strong reference to the object, which prevents it from being collected. However, there is always the risk that the garbage collector will get to the object first before a strong reference is reestablished. + + Weak references are useful for objects that use a lot of memory, but can be recreated easily if they are reclaimed by garbage collection. + + Suppose a tree view in a Windows Forms application displays a complex hierarchical choice of options to the user. If the underlying data is large, keeping the tree in memory is inefficient when the user is involved with something else in the application. + + When the user switches away to another part of the application, you can use the class to create a weak reference to the tree and destroy all strong references. When the user switches back to the tree, the application attempts to obtain a strong reference to the tree and, if successful, avoids reconstructing the tree. + + To establish a weak reference with an object, you create a using the instance of the object to be tracked. For a code example, see in the class library. + +## Short and Long Weak References + + You can create a short weak reference or a long weak reference: + +- Short + + The target of a short weak reference becomes `null` when the object is reclaimed by garbage collection. The weak reference is itself a managed object, and is subject to garbage collection just like any other managed object. A short weak reference is the parameterless constructor for . + +- Long + + A long weak reference is retained after the object's method has been called. This allows the object to be recreated, but the state of the object remains unpredictable. To use a long reference, specify `true` in the constructor. + + If the object's type does not have a method, the short weak reference functionality applies and the weak reference is valid only until the target is collected, which can occur anytime after the finalizer is run. + + To establish a strong reference and use the object again, cast the property of a to the type of the object. If the property returns `null`, the object was collected; otherwise, you can continue to use the object because the application has regained a strong reference to it. + +## Guidelines for Using Weak References + + Use long weak references only when necessary as the state of the object is unpredictable after finalization. + + Avoid using weak references to small objects because the pointer itself may be as large or larger. + + Avoid using weak references as an automatic solution to memory management problems. Instead, develop an effective caching policy for handling your application's objects. + ## See also - [Garbage Collection](index.md) diff --git a/docs/standard/generics.md b/docs/standard/generics.md index b4a2622d32c3e..726baaab817bc 100644 --- a/docs/standard/generics.md +++ b/docs/standard/generics.md @@ -7,9 +7,9 @@ ms.date: 10/09/2018 --- # Generic types overview -Developers use generics all the time in .NET, whether implicitly or explicitly. When you use LINQ in .NET, did you ever notice that you're working with ? Or if you ever saw an online sample of a "generic repository" for talking to databases using Entity Framework, did you see that most methods return `IQueryable`? You may have wondered what the **T** is in these examples and why it's in there. +Developers use generics all the time in .NET, whether implicitly or explicitly. When you use LINQ in .NET, did you ever notice that you're working with ? Or if you ever saw an online sample of a "generic repository" for talking to databases using Entity Framework, did you see that most methods return `IQueryable`? You may have wondered what the **T** is in these examples and why it's in there. -First introduced in .NET Framework 2.0, generics are essentially a "code template" that allows developers to define [type-safe](/previous-versions/dotnet/netframework-4.0/hbzz1a9a(v=vs.100)) data structures without committing to an actual data type. For example, is a [generic collection](xref:System.Collections.Generic) that can be declared and used with any type, such as `List`, `List`, or `List`. +First introduced in .NET Framework 2.0, generics are essentially a "code template" that allows developers to define [type-safe](/previous-versions/dotnet/netframework-4.0/hbzz1a9a(v=vs.100)) data structures without committing to an actual data type. For example, is a [generic collection](xref:System.Collections.Generic) that can be declared and used with any type, such as `List`, `List`, or `List`. To understand why generics are useful, let's take a look at a specific class before and after adding generics: . In .NET Framework 1.0, the `ArrayList` elements were of type . Any element added to the collection was silently converted into an `Object`. The same would happen when reading elements from the list. This process is known as [boxing and unboxing](../csharp/programming-guide/types/boxing-and-unboxing.md), and it impacts performance. Aside from performance, however, there's no way to determine the type of data in the list at compile time, which makes for some fragile code. Generics solve this problem by defining the type of data each instance of list will contain. For example, you can only add integers to `List` and only add Persons to `List`. diff --git a/docs/standard/generics/collections.md b/docs/standard/generics/collections.md index 317df78e32fa7..4957a8eb91a7f 100644 --- a/docs/standard/generics/collections.md +++ b/docs/standard/generics/collections.md @@ -16,28 +16,28 @@ helpviewer_keywords: ## System.Collections.Generic - Many of the generic collection types are direct analogs of nongeneric types. is a generic version of ; it uses the generic structure for enumeration instead of . + Many of the generic collection types are direct analogs of nongeneric types. is a generic version of ; it uses the generic structure for enumeration instead of . - is a generic version of . There are generic and classes that correspond to the nongeneric versions. + is a generic version of . There are generic and classes that correspond to the nongeneric versions. - There are generic and nongeneric versions of . Both versions are hybrids of a dictionary and a list. The generic class is a pure dictionary and has no nongeneric counterpart. + There are generic and nongeneric versions of . Both versions are hybrids of a dictionary and a list. The generic class is a pure dictionary and has no nongeneric counterpart. - The generic class is a true linked list. It has no nongeneric counterpart. + The generic class is a true linked list. It has no nongeneric counterpart. ## System.Collections.ObjectModel - The generic class provides a base class for deriving your own generic collection types. The class provides an easy way to produce a read-only collection from any type that implements the generic interface. The generic class provides a way to store objects that contain their own keys. + The generic class provides a base class for deriving your own generic collection types. The class provides an easy way to produce a read-only collection from any type that implements the generic interface. The generic class provides a way to store objects that contain their own keys. ## Other generic types - The generic structure allows you to use value types as if they could be assigned `null`. This can be useful when working with database queries, where fields that contain value types can be missing. The generic type parameter can be any value type. + The generic structure allows you to use value types as if they could be assigned `null`. This can be useful when working with database queries, where fields that contain value types can be missing. The generic type parameter can be any value type. > [!NOTE] -> In C# and Visual Basic, it is not necessary to use explicitly because the language has syntax for nullable types. See [Nullable value types (C# reference)](../../csharp/language-reference/builtin-types/nullable-value-types.md) and [Nullable value types (Visual Basic)](../../visual-basic/programming-guide/language-features/data-types/nullable-value-types.md). +> In C# and Visual Basic, it is not necessary to use explicitly because the language has syntax for nullable types. See [Nullable value types (C# reference)](../../csharp/language-reference/builtin-types/nullable-value-types.md) and [Nullable value types (Visual Basic)](../../visual-basic/programming-guide/language-features/data-types/nullable-value-types.md). - The generic structure provides a way to delimit a range of elements within a one-dimensional, zero-based array of any type. The generic type parameter is the type of the array's elements. + The generic structure provides a way to delimit a range of elements within a one-dimensional, zero-based array of any type. The generic type parameter is the type of the array's elements. - The generic delegate eliminates the need to declare a delegate type to handle events, if your event follows the event-handling pattern used by .NET. For example, suppose you have created a `MyEventArgs` class, derived from , to hold the data for your event. You can then declare the event as follows: + The generic delegate eliminates the need to declare a delegate type to handle events, if your event follows the event-handling pattern used by .NET. For example, suppose you have created a `MyEventArgs` class, derived from , to hold the data for your event. You can then declare the event as follows: [!code-csharp[Conceptual.Generics.Overview#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.generics.overview/cs/source2.cs#7)] [!code-vb[Conceptual.Generics.Overview#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.generics.overview/vb/source2.vb#7)] diff --git a/docs/standard/generics/covariance-and-contravariance.md b/docs/standard/generics/covariance-and-contravariance.md index ab9ebbf65e76f..ca7e558ca1acc 100644 --- a/docs/standard/generics/covariance-and-contravariance.md +++ b/docs/standard/generics/covariance-and-contravariance.md @@ -6,7 +6,7 @@ ai-usage: ai-assisted dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "generics, covariance and contravariance" - "generics, variance" - "covariance and contravariance in generics" @@ -34,27 +34,27 @@ The following definitions and examples assume a base class named `Base` and a de Covariant type parameters enable you to make assignments that look much like ordinary [Polymorphism](../../csharp/fundamentals/object-oriented/polymorphism.md), as shown in the following code. [!code-csharp[CoContraSimpleIEnum#1](../../../samples/snippets/csharp/VS_Snippets_CLR/cocontrasimpleienum/cs/example.cs#1)] - [!code-vb[CoContraSimpleIEnum#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontrasimpleienum/vb/example.vb#1)] - - The class implements the interface, so `List` (`List(Of Derived)` in Visual Basic) implements `IEnumerable`. The covariant type parameter does the rest. - - Contravariance, on the other hand, seems counterintuitive. The following example creates a delegate of type `Action` (`Action(Of Base)` in Visual Basic), and then assigns that delegate to a variable of type `Action`. - + [!code-vb[CoContraSimpleIEnum#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontrasimpleienum/vb/example.vb#1)] + + The class implements the interface, so `List` (`List(Of Derived)` in Visual Basic) implements `IEnumerable`. The covariant type parameter does the rest. + + Contravariance, on the other hand, seems counterintuitive. The following example creates a delegate of type `Action` (`Action(Of Base)` in Visual Basic), and then assigns that delegate to a variable of type `Action`. + [!code-csharp[CoContraSimpleAction#1](../../../samples/snippets/csharp/VS_Snippets_CLR/cocontrasimpleaction/cs/example.cs#1)] - [!code-vb[CoContraSimpleAction#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontrasimpleaction/vb/example.vb#1)] - - This seems backward, but it is type-safe code that compiles and runs. The lambda expression matches the delegate it's assigned to, so it defines a method that takes one parameter of type `Base` and that has no return value. The resulting delegate can be assigned to a variable of type `Action` because the type parameter `T` of the delegate is contravariant. The code is type-safe because `T` specifies a parameter type. When the delegate of type `Action` is invoked as if it were a delegate of type `Action`, its argument must be of type `Derived`. This argument can always be passed safely to the underlying method, because the method's parameter is of type `Base`. - - In general, a covariant type parameter can be used as the return type of a delegate, and contravariant type parameters can be used as parameter types. For an interface, covariant type parameters can be used as the return types of the interface's methods, and contravariant type parameters can be used as the parameter types of the interface's methods. - - Covariance and contravariance are collectively referred to as *variance*. A generic type parameter that is not marked covariant or contravariant is referred to as *invariant*. A brief summary of facts about variance in the common language runtime: - -- Variant type parameters are restricted to generic interface and generic delegate types. - -- A generic interface or generic delegate type can have both covariant and contravariant type parameters. - -- Variance applies only to reference types; if you specify a value type for a variant type parameter, that type parameter is invariant for the resulting constructed type. - + [!code-vb[CoContraSimpleAction#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontrasimpleaction/vb/example.vb#1)] + + This seems backward, but it is type-safe code that compiles and runs. The lambda expression matches the delegate it's assigned to, so it defines a method that takes one parameter of type `Base` and that has no return value. The resulting delegate can be assigned to a variable of type `Action` because the type parameter `T` of the delegate is contravariant. The code is type-safe because `T` specifies a parameter type. When the delegate of type `Action` is invoked as if it were a delegate of type `Action`, its argument must be of type `Derived`. This argument can always be passed safely to the underlying method, because the method's parameter is of type `Base`. + + In general, a covariant type parameter can be used as the return type of a delegate, and contravariant type parameters can be used as parameter types. For an interface, covariant type parameters can be used as the return types of the interface's methods, and contravariant type parameters can be used as the parameter types of the interface's methods. + + Covariance and contravariance are collectively referred to as *variance*. A generic type parameter that is not marked covariant or contravariant is referred to as *invariant*. A brief summary of facts about variance in the common language runtime: + +- Variant type parameters are restricted to generic interface and generic delegate types. + +- A generic interface or generic delegate type can have both covariant and contravariant type parameters. + +- Variance applies only to reference types; if you specify a value type for a variant type parameter, that type parameter is invariant for the resulting constructed type. + - Variance does not apply to delegate combination. That is, given two delegates of types `Action` and `Action` (`Action(Of Derived)` and `Action(Of Base)` in Visual Basic), you cannot combine the second delegate with the first although the result would be type safe. Variance allows the second delegate to be assigned to a variable of type `Action`, but delegates can combine only if their types match exactly. - Starting in C# 9, covariant return types are supported. An overriding method can declare a more derived return type the method it overrides, and an overriding, read-only property can declare a more derived type. @@ -63,103 +63,103 @@ The following definitions and examples assume a base class named `Base` and a de ## Generic interfaces with covariant type parameters -Several generic interfaces have covariant type parameters, for example, , , , and . All the type parameters of these interfaces are covariant, so the type parameters are used only for the return types of the members. - - The following example illustrates covariant type parameters. The example defines two types: `Base` has a static method named `PrintBases` that takes an `IEnumerable` (`IEnumerable(Of Base)` in Visual Basic) and prints the elements. `Derived` inherits from `Base`. The example creates an empty `List` (`List(Of Derived)` in Visual Basic) and demonstrates that this type can be passed to `PrintBases` and assigned to a variable of type `IEnumerable` without casting. implements , which has a single covariant type parameter. The covariant type parameter is the reason why an instance of `IEnumerable` can be used instead of `IEnumerable`. - +Several generic interfaces have covariant type parameters, for example, , , , and . All the type parameters of these interfaces are covariant, so the type parameters are used only for the return types of the members. + + The following example illustrates covariant type parameters. The example defines two types: `Base` has a static method named `PrintBases` that takes an `IEnumerable` (`IEnumerable(Of Base)` in Visual Basic) and prints the elements. `Derived` inherits from `Base`. The example creates an empty `List` (`List(Of Derived)` in Visual Basic) and demonstrates that this type can be passed to `PrintBases` and assigned to a variable of type `IEnumerable` without casting. implements , which has a single covariant type parameter. The covariant type parameter is the reason why an instance of `IEnumerable` can be used instead of `IEnumerable`. + [!code-csharp[CoContravarianceInClrGenericI#1](../../../samples/snippets/csharp/VS_Snippets_CLR/cocontravarianceinclrgenerici/cs/example.cs#1)] - [!code-vb[CoContravarianceInClrGenericI#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravarianceinclrgenerici/vb/example.vb#1)] - + [!code-vb[CoContravarianceInClrGenericI#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravarianceinclrgenerici/vb/example.vb#1)] + ## Generic interfaces with contravariant type parameters -Several generic interfaces have contravariant type parameters; for example: , , and . These interfaces have only contravariant type parameters, so the type parameters are used only as parameter types in the members of the interfaces. - - The following example illustrates contravariant type parameters. The example defines an abstract (`MustInherit` in Visual Basic) `Shape` class with an `Area` property. The example also defines a `ShapeAreaComparer` class that implements `IComparer` (`IComparer(Of Shape)` in Visual Basic). The implementation of the method is based on the value of the `Area` property, so `ShapeAreaComparer` can be used to sort `Shape` objects by area. - - The `Circle` class inherits `Shape` and overrides `Area`. The example creates a of `Circle` objects, using a constructor that takes an `IComparer` (`IComparer(Of Circle)` in Visual Basic). However, instead of passing an `IComparer`, the example passes a `ShapeAreaComparer` object, which implements `IComparer`. The example can pass a comparer of a less derived type (`Shape`) when the code calls for a comparer of a more derived type (`Circle`), because the type parameter of the generic interface is contravariant. - - When a new `Circle` object is added to the `SortedSet`, the `IComparer.Compare` method (`IComparer(Of Shape).Compare` method in Visual Basic) of the `ShapeAreaComparer` object is called each time the new element is compared to an existing element. The parameter type of the method (`Shape`) is less derived than the type that is being passed (`Circle`), so the call is type safe. Contravariance enables `ShapeAreaComparer` to sort a collection of any single type, as well as a mixed collection of types, that derive from `Shape`. - +Several generic interfaces have contravariant type parameters; for example: , , and . These interfaces have only contravariant type parameters, so the type parameters are used only as parameter types in the members of the interfaces. + + The following example illustrates contravariant type parameters. The example defines an abstract (`MustInherit` in Visual Basic) `Shape` class with an `Area` property. The example also defines a `ShapeAreaComparer` class that implements `IComparer` (`IComparer(Of Shape)` in Visual Basic). The implementation of the method is based on the value of the `Area` property, so `ShapeAreaComparer` can be used to sort `Shape` objects by area. + + The `Circle` class inherits `Shape` and overrides `Area`. The example creates a of `Circle` objects, using a constructor that takes an `IComparer` (`IComparer(Of Circle)` in Visual Basic). However, instead of passing an `IComparer`, the example passes a `ShapeAreaComparer` object, which implements `IComparer`. The example can pass a comparer of a less derived type (`Shape`) when the code calls for a comparer of a more derived type (`Circle`), because the type parameter of the generic interface is contravariant. + + When a new `Circle` object is added to the `SortedSet`, the `IComparer.Compare` method (`IComparer(Of Shape).Compare` method in Visual Basic) of the `ShapeAreaComparer` object is called each time the new element is compared to an existing element. The parameter type of the method (`Shape`) is less derived than the type that is being passed (`Circle`), so the call is type safe. Contravariance enables `ShapeAreaComparer` to sort a collection of any single type, as well as a mixed collection of types, that derive from `Shape`. + [!code-csharp[CoContravarianceInClrGenericI2#1](../../../samples/snippets/csharp/VS_Snippets_CLR/cocontravarianceinclrgenerici2/cs/example.cs#1)] - [!code-vb[CoContravarianceInClrGenericI2#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravarianceinclrgenerici2/vb/example.vb#1)] + [!code-vb[CoContravarianceInClrGenericI2#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravarianceinclrgenerici2/vb/example.vb#1)] ## Generic delegates with variant type parameters -The `Func` generic delegates, such as , have covariant return types and contravariant parameter types. The `Action` generic delegates, such as , have contravariant parameter types. This means that the delegates can be assigned to variables that have more derived parameter types and (in the case of the `Func` generic delegates) less derived return types. - +The `Func` generic delegates, such as , have covariant return types and contravariant parameter types. The `Action` generic delegates, such as , have contravariant parameter types. This means that the delegates can be assigned to variables that have more derived parameter types and (in the case of the `Func` generic delegates) less derived return types. + > [!NOTE] -> The last generic type parameter of the `Func` generic delegates specifies the type of the return value in the delegate signature. It is covariant (`out` keyword), whereas the other generic type parameters are contravariant (`in` keyword). - - The following code illustrates this. The first piece of code defines a class named `Base`, a class named `Derived` that inherits `Base`, and another class with a `static` method (`Shared` in Visual Basic) named `MyMethod`. The method takes an instance of `Base` and returns an instance of `Derived`. (If the argument is an instance of `Derived`, `MyMethod` returns it; if the argument is an instance of `Base`, `MyMethod` returns a new instance of `Derived`.) In `Main()`, the example creates an instance of `Func` (`Func(Of Base, Derived)` in Visual Basic) that represents `MyMethod`, and stores it in the variable `f1`. - +> The last generic type parameter of the `Func` generic delegates specifies the type of the return value in the delegate signature. It is covariant (`out` keyword), whereas the other generic type parameters are contravariant (`in` keyword). + + The following code illustrates this. The first piece of code defines a class named `Base`, a class named `Derived` that inherits `Base`, and another class with a `static` method (`Shared` in Visual Basic) named `MyMethod`. The method takes an instance of `Base` and returns an instance of `Derived`. (If the argument is an instance of `Derived`, `MyMethod` returns it; if the argument is an instance of `Base`, `MyMethod` returns a new instance of `Derived`.) In `Main()`, the example creates an instance of `Func` (`Func(Of Base, Derived)` in Visual Basic) that represents `MyMethod`, and stores it in the variable `f1`. + [!code-csharp[CoContravarianceDelegates#2](../../../samples/snippets/csharp/VS_Snippets_CLR/cocontravariancedelegates/cs/example.cs#2)] - [!code-vb[CoContravarianceDelegates#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravariancedelegates/vb/example.vb#2)] - - The second piece of code shows that the delegate can be assigned to a variable of type `Func` (`Func(Of Base, Base)` in Visual Basic), because the return type is covariant. - + [!code-vb[CoContravarianceDelegates#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravariancedelegates/vb/example.vb#2)] + + The second piece of code shows that the delegate can be assigned to a variable of type `Func` (`Func(Of Base, Base)` in Visual Basic), because the return type is covariant. + [!code-csharp[CoContravarianceDelegates#3](../../../samples/snippets/csharp/VS_Snippets_CLR/cocontravariancedelegates/cs/example.cs#3)] - [!code-vb[CoContravarianceDelegates#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravariancedelegates/vb/example.vb#3)] - - The third piece of code shows that the delegate can be assigned to a variable of type `Func` (`Func(Of Derived, Derived)` in Visual Basic), because the parameter type is contravariant. - + [!code-vb[CoContravarianceDelegates#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravariancedelegates/vb/example.vb#3)] + + The third piece of code shows that the delegate can be assigned to a variable of type `Func` (`Func(Of Derived, Derived)` in Visual Basic), because the parameter type is contravariant. + [!code-csharp[CoContravarianceDelegates#4](../../../samples/snippets/csharp/VS_Snippets_CLR/cocontravariancedelegates/cs/example.cs#4)] - [!code-vb[CoContravarianceDelegates#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravariancedelegates/vb/example.vb#4)] - - The final piece of code shows that the delegate can be assigned to a variable of type `Func` (`Func(Of Derived, Base)` in Visual Basic), combining the effects of the contravariant parameter type and the covariant return type. - + [!code-vb[CoContravarianceDelegates#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravariancedelegates/vb/example.vb#4)] + + The final piece of code shows that the delegate can be assigned to a variable of type `Func` (`Func(Of Derived, Base)` in Visual Basic), combining the effects of the contravariant parameter type and the covariant return type. + [!code-csharp[CoContravarianceDelegates#5](../../../samples/snippets/csharp/VS_Snippets_CLR/cocontravariancedelegates/cs/example.cs#5)] - [!code-vb[CoContravarianceDelegates#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravariancedelegates/vb/example.vb#5)] - + [!code-vb[CoContravarianceDelegates#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravariancedelegates/vb/example.vb#5)] + ### Variance in non-generic delegates - In the preceding code, the signature of `MyMethod` exactly matches the signature of the constructed generic delegate: `Func` (`Func(Of Base, Derived)` in Visual Basic). The example shows that this generic delegate can be stored in variables or method parameters that have more derived parameter types and less derived return types, as long as all the delegate types are constructed from the generic delegate type . - - This is an important point. The effects of covariance and contravariance in the type parameters of generic delegates are similar to the effects of covariance and contravariance in ordinary delegate binding (see [Variance in Delegates (C#)](../../csharp/programming-guide/concepts/covariance-contravariance/variance-in-delegates.md) and [Variance in Delegates (Visual Basic)](../../visual-basic/programming-guide/concepts/covariance-contravariance/variance-in-delegates.md)). However, variance in delegate binding works with all delegate types, not just with generic delegate types that have variant type parameters. Furthermore, variance in delegate binding enables a method to be bound to any delegate that has more restrictive parameter types and a less restrictive return type, whereas the assignment of generic delegates works only if both delegate types are constructed from the same generic type definition. - - The following example shows the combined effects of variance in delegate binding and variance in generic type parameters. The example defines a type hierarchy that includes three types, from least derived (`Type1`) to most derived (`Type3`). Variance in ordinary delegate binding is used to bind a method with a parameter type of `Type1` and a return type of `Type3` to a generic delegate with a parameter type of `Type2` and a return type of `Type2`. The resulting generic delegate is then assigned to another variable whose generic delegate type has a parameter of type `Type3` and a return type of `Type1`, using the covariance and contravariance of generic type parameters. The second assignment requires both the variable type and the delegate type to be constructed from the same generic type definition, in this case, . - + In the preceding code, the signature of `MyMethod` exactly matches the signature of the constructed generic delegate: `Func` (`Func(Of Base, Derived)` in Visual Basic). The example shows that this generic delegate can be stored in variables or method parameters that have more derived parameter types and less derived return types, as long as all the delegate types are constructed from the generic delegate type . + + This is an important point. The effects of covariance and contravariance in the type parameters of generic delegates are similar to the effects of covariance and contravariance in ordinary delegate binding (see [Variance in Delegates (C#)](../../csharp/programming-guide/concepts/covariance-contravariance/variance-in-delegates.md) and [Variance in Delegates (Visual Basic)](../../visual-basic/programming-guide/concepts/covariance-contravariance/variance-in-delegates.md)). However, variance in delegate binding works with all delegate types, not just with generic delegate types that have variant type parameters. Furthermore, variance in delegate binding enables a method to be bound to any delegate that has more restrictive parameter types and a less restrictive return type, whereas the assignment of generic delegates works only if both delegate types are constructed from the same generic type definition. + + The following example shows the combined effects of variance in delegate binding and variance in generic type parameters. The example defines a type hierarchy that includes three types, from least derived (`Type1`) to most derived (`Type3`). Variance in ordinary delegate binding is used to bind a method with a parameter type of `Type1` and a return type of `Type3` to a generic delegate with a parameter type of `Type2` and a return type of `Type2`. The resulting generic delegate is then assigned to another variable whose generic delegate type has a parameter of type `Type3` and a return type of `Type1`, using the covariance and contravariance of generic type parameters. The second assignment requires both the variable type and the delegate type to be constructed from the same generic type definition, in this case, . + [!code-csharp[CoContravarianceDelegatesGenRelaxed#1](../../../samples/snippets/csharp/VS_Snippets_CLR/cocontravariancedelegatesgenrelaxed/cs/example.cs#1)] - [!code-vb[CoContravarianceDelegatesGenRelaxed#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravariancedelegatesgenrelaxed/vb/example.vb#1)] + [!code-vb[CoContravarianceDelegatesGenRelaxed#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/cocontravariancedelegatesgenrelaxed/vb/example.vb#1)] ## Define variant generic interfaces and delegates Visual Basic and C# have keywords that enable you to mark the generic type parameters of interfaces and delegates as covariant or contravariant. - - A covariant type parameter is marked with the `out` keyword (`Out` keyword in Visual Basic). You can use a covariant type parameter as the return value of a method that belongs to an interface, or as the return type of a delegate. You cannot use a covariant type parameter as a generic type constraint for interface methods. - + + A covariant type parameter is marked with the `out` keyword (`Out` keyword in Visual Basic). You can use a covariant type parameter as the return value of a method that belongs to an interface, or as the return type of a delegate. You cannot use a covariant type parameter as a generic type constraint for interface methods. + > [!NOTE] -> If a method of an interface has a parameter that is a generic delegate type, a covariant type parameter of the interface type can be used to specify a contravariant type parameter of the delegate type. - - A contravariant type parameter is marked with the `in` keyword (`In` keyword in Visual Basic). You can use a contravariant type parameter as the type of a parameter of a method that belongs to an interface, or as the type of a parameter of a delegate. You can use a contravariant type parameter as a generic type constraint for an interface method. - - Only interface types and delegate types can have variant type parameters. An interface or delegate type can have both covariant and contravariant type parameters. - +> If a method of an interface has a parameter that is a generic delegate type, a covariant type parameter of the interface type can be used to specify a contravariant type parameter of the delegate type. + + A contravariant type parameter is marked with the `in` keyword (`In` keyword in Visual Basic). You can use a contravariant type parameter as the type of a parameter of a method that belongs to an interface, or as the type of a parameter of a delegate. You can use a contravariant type parameter as a generic type constraint for an interface method. + + Only interface types and delegate types can have variant type parameters. An interface or delegate type can have both covariant and contravariant type parameters. + Visual Basic and C# do not allow you to violate the rules for using covariant and contravariant type parameters, or to add covariance and contravariance annotations to the type parameters of types other than interfaces and delegates. - - For information and example code, see [Variance in Generic Interfaces (C#)](../../csharp/programming-guide/concepts/covariance-contravariance/variance-in-generic-interfaces.md) and [Variance in Generic Interfaces (Visual Basic)](../../visual-basic/programming-guide/concepts/covariance-contravariance/variance-in-generic-interfaces.md). + + For information and example code, see [Variance in Generic Interfaces (C#)](../../csharp/programming-guide/concepts/covariance-contravariance/variance-in-generic-interfaces.md) and [Variance in Generic Interfaces (Visual Basic)](../../visual-basic/programming-guide/concepts/covariance-contravariance/variance-in-generic-interfaces.md). ## List of types -The following interface and delegate types have covariant and/or contravariant type parameters. - -|Type|Covariant type parameters|Contravariant type parameters| -|----------|-------------------------------|-----------------------------------| -| to ||Yes| -|||Yes| -||Yes|Yes| -||Yes|| -| to |Yes|Yes| -|||Yes| -|||Yes| -|||Yes| -||Yes|| -||Yes|| -|||Yes| -||Yes|| -||Yes|| -||Yes|| -||Yes|| - +The following interface and delegate types have covariant and/or contravariant type parameters. + +|Type|Covariant type parameters|Contravariant type parameters| +|----------|-------------------------------|-----------------------------------| +| to ||Yes| +|||Yes| +||Yes|Yes| +||Yes|| +| to |Yes|Yes| +|||Yes| +|||Yes| +|||Yes| +||Yes|| +||Yes|| +|||Yes| +||Yes|| +||Yes|| +||Yes|| +||Yes|| + ## See also - [Covariance and Contravariance (C#)](../../csharp/programming-guide/concepts/covariance-contravariance/index.md) diff --git a/docs/standard/generics/delegates-for-manipulating-arrays-and-lists.md b/docs/standard/generics/delegates-for-manipulating-arrays-and-lists.md index ca914dc8926fe..48bdaa99c9a57 100644 --- a/docs/standard/generics/delegates-for-manipulating-arrays-and-lists.md +++ b/docs/standard/generics/delegates-for-manipulating-arrays-and-lists.md @@ -2,7 +2,7 @@ description: "Learn more about: Generic Delegates for Manipulating Arrays and Lists" title: "Generic Delegates for Manipulating Arrays and Lists" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "delegates [.NET], generic delegates" - "chaining delegates" - "arrays [.NET], generic delegates" @@ -13,29 +13,29 @@ ms.assetid: 416be383-cc61-4102-9b1b-88b51adb963e --- # Generic Delegates for Manipulating Arrays and Lists -This topic provides an overview of generic delegates for conversions, search predicates, and actions to be taken on elements of an array or collection. - -## Generic Delegates for Manipulating Arrays and Lists +This topic provides an overview of generic delegates for conversions, search predicates, and actions to be taken on elements of an array or collection. + +## Generic Delegates for Manipulating Arrays and Lists + + The generic delegate represents a method that performs some action on an element of the specified type. You can create a method that performs the desired action on the element, create an instance of the delegate to represent that method, and then pass the array and the delegate to the static generic method. The method is called for every element of the array. + + The generic class also provides a method that uses the delegate. This method is not generic. - The generic delegate represents a method that performs some action on an element of the specified type. You can create a method that performs the desired action on the element, create an instance of the delegate to represent that method, and then pass the array and the delegate to the static generic method. The method is called for every element of the array. - - The generic class also provides a method that uses the delegate. This method is not generic. - > [!NOTE] -> This makes an interesting point about generic types and methods. The method must be static (`Shared` in Visual Basic) and generic because is not a generic type; the only reason you can specify a type for to operate on is that the method has its own type parameter list. By contrast, the nongeneric method belongs to the generic class , so it simply uses the type parameter of its class. The class is strongly typed, so the method can be an instance method. - - The generic delegate represents a method that determines whether a particular element meets criteria you define. You can use it with the following static generic methods of to search for an element or a set of elements: , , , , , , and . - - also works with the corresponding nongeneric instance methods of the generic class. - - The generic delegate allows you to provide a sort order for array or list elements that do not have a native sort order, or to override the native sort order. Create a method that performs the comparison, create an instance of the delegate to represent your method, and then pass the array and the delegate to the static generic method. The generic class provides a corresponding instance method overload, . - - The generic delegate allows you to define a conversion between two types, and to convert an array of one type into an array of the other, or to convert a list of one type to a list of the other. Create a method that converts the elements of the existing list to a new type, create a delegate instance to represent the method, and use the generic static method to produce an array of the new type from the original array, or the generic instance method to produce a list of the new type from the original list. - -### Chaining Delegates - - Many of the methods that use these delegates return an array or list, which can be passed to another method. For example, if you want to select certain elements of an array, convert those elements to a new type, and save them in a new array, you can pass the array returned by the generic method to the generic method. If the new element type lacks a natural sort order, you can pass the array returned by the generic method to the generic method. - +> This makes an interesting point about generic types and methods. The method must be static (`Shared` in Visual Basic) and generic because is not a generic type; the only reason you can specify a type for to operate on is that the method has its own type parameter list. By contrast, the nongeneric method belongs to the generic class , so it simply uses the type parameter of its class. The class is strongly typed, so the method can be an instance method. + + The generic delegate represents a method that determines whether a particular element meets criteria you define. You can use it with the following static generic methods of to search for an element or a set of elements: , , , , , , and . + + also works with the corresponding nongeneric instance methods of the generic class. + + The generic delegate allows you to provide a sort order for array or list elements that do not have a native sort order, or to override the native sort order. Create a method that performs the comparison, create an instance of the delegate to represent your method, and then pass the array and the delegate to the static generic method. The generic class provides a corresponding instance method overload, . + + The generic delegate allows you to define a conversion between two types, and to convert an array of one type into an array of the other, or to convert a list of one type to a list of the other. Create a method that converts the elements of the existing list to a new type, create a delegate instance to represent the method, and use the generic static method to produce an array of the new type from the original array, or the generic instance method to produce a list of the new type from the original list. + +### Chaining Delegates + + Many of the methods that use these delegates return an array or list, which can be passed to another method. For example, if you want to select certain elements of an array, convert those elements to a new type, and save them in a new array, you can pass the array returned by the generic method to the generic method. If the new element type lacks a natural sort order, you can pass the array returned by the generic method to the generic method. + ## See also - diff --git a/docs/standard/generics/index.md b/docs/standard/generics/index.md index c88990c75c8da..223c79dac5b38 100644 --- a/docs/standard/generics/index.md +++ b/docs/standard/generics/index.md @@ -28,7 +28,7 @@ ms.assetid: 2994d786-c5c7-4666-ab23-4c83129fe39c --- # Generics in .NET -Generics let you tailor a method, class, structure, or interface to the precise data type it acts upon. For example, instead of using the class, which allows keys and values to be of any type, you can use the generic class and specify the types allowed for the key and the value. Among the benefits of generics are increased code reusability and type safety. +Generics let you tailor a method, class, structure, or interface to the precise data type it acts upon. For example, instead of using the class, which allows keys and values to be of any type, you can use the generic class and specify the types allowed for the key and the value. Among the benefits of generics are increased code reusability and type safety. ## Define and use generics @@ -46,9 +46,9 @@ The following code illustrates a simple generic class definition. The following terms are used to discuss generics in .NET: -- A *generic type definition* is a class, structure, or interface declaration that functions as a template, with placeholders for the types that it can contain or use. For example, the class can contain two types: keys and values. Because a generic type definition is only a template, you cannot create instances of a class, structure, or interface that is a generic type definition. +- A *generic type definition* is a class, structure, or interface declaration that functions as a template, with placeholders for the types that it can contain or use. For example, the class can contain two types: keys and values. Because a generic type definition is only a template, you cannot create instances of a class, structure, or interface that is a generic type definition. -- *Generic type parameters*, or *type parameters*, are the placeholders in a generic type or method definition. The generic type has two type parameters, `TKey` and `TValue`, that represent the types of its keys and values. +- *Generic type parameters*, or *type parameters*, are the placeholders in a generic type or method definition. The generic type has two type parameters, `TKey` and `TValue`, that represent the types of its keys and values. - A *constructed generic type*, or *constructed type*, is the result of specifying types for the generic type parameters of a generic type definition. @@ -58,7 +58,7 @@ The following terms are used to discuss generics in .NET: - *Covariance* and *contravariance* of generic type parameters enable you to use constructed generic types whose type arguments are more derived (covariance) or less derived (contravariance) than a target constructed type. Covariance and contravariance are collectively referred to as *variance*. For more information, see [Covariance and contravariance](covariance-and-contravariance.md). -- *Constraints* are limits placed on generic type parameters. For example, you might limit a type parameter to types that implement the generic interface, to ensure that instances of the type can be ordered. You can also constrain type parameters to types that have a particular base class, that have a parameterless constructor, or that are reference types or value types. Users of the generic type cannot substitute type arguments that do not satisfy the constraints. +- *Constraints* are limits placed on generic type parameters. For example, you might limit a type parameter to types that implement the generic interface, to ensure that instances of the type can be ordered. You can also constrain type parameters to types that have a particular base class, that have a parameterless constructor, or that are reference types or value types. Users of the generic type cannot substitute type arguments that do not satisfy the constraints. - A *generic method definition* is a method with two parameter lists: a list of generic type parameters and a list of formal parameters. Type parameters can appear as the return type or as the types of the formal parameters, as the following code shows. @@ -76,14 +76,14 @@ There are many advantages to using generic collections and delegates: - Type safety. Generics shift the burden of type safety from you to the compiler. There is no need to write code to test for the correct data type because it is enforced at compile time. The need for type casting and the possibility of runtime errors are reduced. -- Less code and code is more easily reused. There is no need to inherit from a base type and override members. For example, the is ready for immediate use. For example, you can create a linked list of strings with the following variable declaration: +- Less code and code is more easily reused. There is no need to inherit from a base type and override members. For example, the is ready for immediate use. For example, you can create a linked list of strings with the following variable declaration: [!code-csharp[HowToGeneric#24](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToGeneric/CS/source2.cs#24)] [!code-vb[HowToGeneric#24](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToGeneric/VB/source2.vb#24)] - Better performance. Generic collection types generally perform better for storing and manipulating value types because there is no need to box the value types. -- Generic delegates enable type-safe callbacks without the need to create multiple delegate classes. For example, the generic delegate allows you to create a method that implements your own search criteria for a particular type and to use your method with methods of the type such as , , and . +- Generic delegates enable type-safe callbacks without the need to create multiple delegate classes. For example, the generic delegate allows you to create a method that implements your own search criteria for a particular type and to use your method with methods of the type such as , , and . - Generics streamline dynamically generated code. When you use generics with dynamically generated code you do not need to generate the type. This increases the number of scenarios in which you can use lightweight dynamic methods instead of generating entire assemblies. For more information, see [How to: Define and Execute Dynamic Methods](../../fundamentals/reflection/how-to-define-and-execute-dynamic-methods.md) and . @@ -95,20 +95,20 @@ The following are some limitations of generics: - Lightweight dynamic methods cannot be generic. -- In Visual Basic, C#, and C++, a nested type that is enclosed in a generic type cannot be instantiated unless types have been assigned to the type parameters of all enclosing types. Another way of saying this is that in reflection, a nested type that is defined using these languages includes the type parameters of all its enclosing types. This allows the type parameters of enclosing types to be used in the member definitions of a nested type. For more information, see "Nested Types" in . +- In Visual Basic, C#, and C++, a nested type that is enclosed in a generic type cannot be instantiated unless types have been assigned to the type parameters of all enclosing types. Another way of saying this is that in reflection, a nested type that is defined using these languages includes the type parameters of all its enclosing types. This allows the type parameters of enclosing types to be used in the member definitions of a nested type. For more information, see "Nested Types" in . > [!NOTE] > A nested type that is defined by emitting code in a dynamic assembly or by using the [Ilasm.exe (IL Assembler)](../../framework/tools/ilasm-exe-il-assembler.md) is not required to include the type parameters of its enclosing types; however, if it does not include them, the type parameters are not in scope in the nested class. - For more information, see "Nested Types" in . + For more information, see "Nested Types" in . ## Class library and language support .NET provides a number of generic collection classes in the following namespaces: -- The namespace contains most of the generic collection types provided by .NET, such as the and generic classes. +- The namespace contains most of the generic collection types provided by .NET, such as the and generic classes. -- The namespace contains additional generic collection types, such as the generic class, that are useful for exposing object models to users of your classes. +- The namespace contains additional generic collection types, such as the generic class, that are useful for exposing object models to users of your classes. Generic interfaces for implementing sort and equality comparisons are provided in the namespace, along with generic delegate types for event handlers, conversions, and search predicates. diff --git a/docs/standard/generics/interfaces.md b/docs/standard/generics/interfaces.md index bf85710da609f..9062d230e6137 100644 --- a/docs/standard/generics/interfaces.md +++ b/docs/standard/generics/interfaces.md @@ -3,7 +3,7 @@ description: "Learn more about interfaces for generic types in .NET." title: Generic interfaces titleSuffix: "" ms.date: 07/25/2022 -helpviewer_keywords: +helpviewer_keywords: - "generic interfaces [.NET]" - "equality comparisons [.NET]" - "generics [.NET], interfaces" @@ -11,39 +11,39 @@ helpviewer_keywords: --- # Generic interfaces in .NET -This article provides an overview of .NET's generic interfaces that provide common functionality across families of generic types. - -Generic interfaces provide type-safe counterparts to nongeneric interfaces for ordering and equality comparisons, and for functionality that's shared by generic collection types. .NET 7 introduces generic interfaces for number-like types, for example, . These interfaces let you define generic methods that provide mathematical functionality, where the generic type parameter is constrained to be a type that implements a generic, numeric interface. - +This article provides an overview of .NET's generic interfaces that provide common functionality across families of generic types. + +Generic interfaces provide type-safe counterparts to nongeneric interfaces for ordering and equality comparisons, and for functionality that's shared by generic collection types. .NET 7 introduces generic interfaces for number-like types, for example, . These interfaces let you define generic methods that provide mathematical functionality, where the generic type parameter is constrained to be a type that implements a generic, numeric interface. + > [!NOTE] -> The type parameters of several generic interfaces are marked covariant or contravariant, providing greater flexibility in assigning and using types that implement these interfaces. For more information, see [Covariance and Contravariance](covariance-and-contravariance.md). - -## Equality and ordering comparisons - -- In the namespace, the **** and **** generic interfaces, like their nongeneric counterparts, define methods for ordering comparisons and equality comparisons, respectively. Types implement these interfaces to provide the ability to perform such comparisons. - -- In the namespace, the **** and **** generic interfaces offer a way to define an ordering or equality comparison for types that don't implement the or interface. They also provide a way to redefine those relationships for types that do. - - These interfaces are used by methods and constructors of many of the generic collection classes. For example, you can pass a generic object to the constructor of the class to specify a sort order for a type that does not implement generic . There are overloads of the generic static method and the instance method for sorting arrays and lists using generic implementations. - - The and generic classes provide base classes for implementations of the and generic interfaces and also provide default ordering and equality comparisons through their respective and properties. - -## Collection functionality - -- The **** generic interface is the basic interface for generic collection types. It provides basic functionality for adding, removing, copying, and enumerating elements. inherits from both generic and nongeneric . - -- The **** generic interface extends the generic interface with methods for indexed retrieval. - -- The **** generic interface extends the generic interface with methods for keyed retrieval. Generic dictionary types in the .NET base class library also implement the nongeneric interface. - -- The **** generic interface provides a generic enumerator structure. The generic interface implemented by generic enumerators inherits the nongeneric interface; the and members, which do not depend on the type parameter `T`, appear only on the nongeneric interface. This means that any consumer of the nongeneric interface can also consume the generic interface. +> The type parameters of several generic interfaces are marked covariant or contravariant, providing greater flexibility in assigning and using types that implement these interfaces. For more information, see [Covariance and Contravariance](covariance-and-contravariance.md). + +## Equality and ordering comparisons + +- In the namespace, the **** and **** generic interfaces, like their nongeneric counterparts, define methods for ordering comparisons and equality comparisons, respectively. Types implement these interfaces to provide the ability to perform such comparisons. + +- In the namespace, the **** and **** generic interfaces offer a way to define an ordering or equality comparison for types that don't implement the or interface. They also provide a way to redefine those relationships for types that do. + + These interfaces are used by methods and constructors of many of the generic collection classes. For example, you can pass a generic object to the constructor of the class to specify a sort order for a type that does not implement generic . There are overloads of the generic static method and the instance method for sorting arrays and lists using generic implementations. + + The and generic classes provide base classes for implementations of the and generic interfaces and also provide default ordering and equality comparisons through their respective and properties. + +## Collection functionality + +- The **** generic interface is the basic interface for generic collection types. It provides basic functionality for adding, removing, copying, and enumerating elements. inherits from both generic and nongeneric . + +- The **** generic interface extends the generic interface with methods for indexed retrieval. + +- The **** generic interface extends the generic interface with methods for keyed retrieval. Generic dictionary types in the .NET base class library also implement the nongeneric interface. + +- The **** generic interface provides a generic enumerator structure. The generic interface implemented by generic enumerators inherits the nongeneric interface; the and members, which do not depend on the type parameter `T`, appear only on the nongeneric interface. This means that any consumer of the nongeneric interface can also consume the generic interface. ## Mathematical functionality -.NET 7 introduces generic interfaces in the namespace that describe number-like types and the functionality available to them. The 20 numeric types that the .NET base class library provides, for example, and , have been updated to implement these interfaces. The most prominent of these interfaces is , which roughly corresponds to a "real" number. +.NET 7 introduces generic interfaces in the namespace that describe number-like types and the functionality available to them. The 20 numeric types that the .NET base class library provides, for example, and , have been updated to implement these interfaces. The most prominent of these interfaces is , which roughly corresponds to a "real" number. For more information about these interfaces, see [Generic math](math.md). - + ## See also - diff --git a/docs/standard/generics/math.md b/docs/standard/generics/math.md index fbcb8bf10b323..5731d360d042e 100644 --- a/docs/standard/generics/math.md +++ b/docs/standard/generics/math.md @@ -18,13 +18,13 @@ static T Add(T left, T right) } ``` -In this method, the type parameter `T` is constrained to be a type that implements the new interface. implements the interface, which contains the [+ operator](xref:System.Numerics.IAdditionOperators%603.op_Addition(%600,%601)). That allows the method to generically add the two numbers. The method can be used with any of .NET's built-in numeric types, because they've all been updated to implement in .NET 7. +In this method, the type parameter `T` is constrained to be a type that implements the new interface. implements the interface, which contains the [+ operator](xref:System.Numerics.IAdditionOperators`3.op_Addition(`0,`1)). That allows the method to generically add the two numbers. The method can be used with any of .NET's built-in numeric types, because they've all been updated to implement in .NET 7. Library authors will benefit most from the generic math interfaces, because they can simplify their code base by removing "redundant" overloads. Other developers will benefit indirectly, because the APIs they consume may start supporting more types. ## The interfaces -The interfaces were designed to be both fine-grained enough that users can define their own interfaces on top, while also being granular enough that they're easy to consume. To that extent, there are a few core numeric interfaces that most users will interact with, such as and . The more fine-grained interfaces, such as and , support these types and are available for developers who define their own domain-specific numeric interfaces. +The interfaces were designed to be both fine-grained enough that users can define their own interfaces on top, while also being granular enough that they're easy to consume. To that extent, there are a few core numeric interfaces that most users will interact with, such as and . The more fine-grained interfaces, such as and , support these types and are available for developers who define their own domain-specific numeric interfaces. - [Numeric interfaces](#numeric-interfaces) - [Operator interfaces](#operator-interfaces) @@ -37,24 +37,24 @@ This section describes the interfaces in | Exposes APIs common to *binary* floating-point types1 that implement the IEEE 754 standard. | -| | Exposes APIs common to binary integers2. | -| | Exposes APIs common to binary numbers. | -| | Exposes APIs common to floating-point types. | -| | Exposes APIs common to floating-point types that implement the IEEE 754 standard. | -| | Exposes APIs common to comparable number types (effectively the "real" number domain). | -| | Exposes APIs common to all number types (effectively the "complex" number domain). | -| | Exposes APIs common to all signed number types (such as the concept of `NegativeOne`). | -| | Exposes APIs common to all unsigned number types. | -| | Exposes the concept of `(x + T.AdditiveIdentity) == x`. | -| | Exposes the concept of `T.MinValue` and `T.MaxValue`. | -| | Exposes the concept of `(x * T.MultiplicativeIdentity) == x`. | +| | Exposes APIs common to *binary* floating-point types1 that implement the IEEE 754 standard. | +| | Exposes APIs common to binary integers2. | +| | Exposes APIs common to binary numbers. | +| | Exposes APIs common to floating-point types. | +| | Exposes APIs common to floating-point types that implement the IEEE 754 standard. | +| | Exposes APIs common to comparable number types (effectively the "real" number domain). | +| | Exposes APIs common to all number types (effectively the "complex" number domain). | +| | Exposes APIs common to all signed number types (such as the concept of `NegativeOne`). | +| | Exposes APIs common to all unsigned number types. | +| | Exposes the concept of `(x + T.AdditiveIdentity) == x`. | +| | Exposes the concept of `T.MinValue` and `T.MaxValue`. | +| | Exposes the concept of `(x * T.MultiplicativeIdentity) == x`. | 1The binary [floating-point types](../../csharp/language-reference/builtin-types/floating-point-numeric-types.md) are (`double`), , and (`float`). 2The binary [integer types](../../csharp/language-reference/builtin-types/integral-numeric-types.md) are (`byte`), (`short`), (`int`), (`long`), , (`nint`), (`sbyte`), (`ushort`), (`uint`), (`ulong`), , and (`nuint`). -The interface you're most likely to use directly is , which roughly corresponds to a *real* number. If a type implements this interface, it means that a value has a sign (this includes `unsigned` types, which are considered positive) and can be compared to other values of the same type. confers more advanced concepts, such as *complex* and *imaginary* numbers, for example, the square root of a negative number. Other interfaces, such as , were created because not all operations make sense for all number types—for example, calculating the floor of a number only makes sense for floating-point types. In the .NET base class library, the floating-point type implements but doesn't. +The interface you're most likely to use directly is , which roughly corresponds to a *real* number. If a type implements this interface, it means that a value has a sign (this includes `unsigned` types, which are considered positive) and can be compared to other values of the same type. confers more advanced concepts, such as *complex* and *imaginary* numbers, for example, the square root of a negative number. Other interfaces, such as , were created because not all operations make sense for all number types—for example, calculating the floor of a number only makes sense for floating-point types. In the .NET base class library, the floating-point type implements but doesn't. Several of the interfaces are also implemented by various other types, including , , , , , , , and . @@ -62,17 +62,17 @@ The following table shows some of the core APIs exposed by each interface. | Interface | API name | Description | |--------------------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------| -| | `DivRem` | Computes the quotient and remainder simultaneously. | +| | `DivRem` | Computes the quotient and remainder simultaneously. | | | `LeadingZeroCount` | Counts the number of leading zero bits in the binary representation. | | | `PopCount` | Counts the number of set bits in the binary representation. | | | `RotateLeft` | Rotates bits left, sometimes also called a circular left shift. | | | `RotateRight` | Rotates bits right, sometimes also called a circular right shift. | | | `TrailingZeroCount` | Counts the number of trailing zero bits in the binary representation. | -| | `Ceiling` | Rounds the value towards positive infinity. +4.5 becomes +5, and -4.5 becomes -4. | +| | `Ceiling` | Rounds the value towards positive infinity. +4.5 becomes +5, and -4.5 becomes -4. | | | `Floor` | Rounds the value towards negative infinity. +4.5 becomes +4, and -4.5 becomes -5. | | | `Round` | Rounds the value using the specified rounding mode. | | | `Truncate` | Rounds the value towards zero. +4.5 becomes +4, and -4.5 becomes -4. | -| | `E` | Gets a value representing Euler's number for the type. | +| | `E` | Gets a value representing Euler's number for the type. | | | `Epsilon` | Gets the smallest representable value that's greater than zero for the type. | | | `NaN` | Gets a value representing `NaN` for the type. | | | `NegativeInfinity` | Gets a value representing `-Infinity` for the type. | @@ -81,14 +81,14 @@ The following table shows some of the core APIs exposed by each interface. | | `PositiveInfinity` | Gets a value representing `+Infinity` for the type. | | | `Tau` | Gets a value representing `Tau` (`2 * Pi`) for the type. | | | (Other) | (Implements the full set of interfaces listed under [Function interfaces](#function-interfaces).) | -| | `Clamp` | Restricts a value to no more and no less than the specified min and max value. | +| | `Clamp` | Restricts a value to no more and no less than the specified min and max value. | | | `CopySign` | Sets the sign of a specified value to the same as another specified value. | | | `Max` | Returns the greater of two values, returning `NaN` if either input is `NaN`. | | | `MaxNumber` | Returns the greater of two values, returning the number if one input is `NaN`. | | | `Min` | Returns the lesser of two values, returning `NaN` if either input is `NaN`. | | | `MinNumber` | Returns the lesser of two values, returning the number if one input is `NaN`. | | | `Sign` | Returns -1 for negative values, 0 for zero, and +1 for positive values. | -| | `One` | Gets the value 1 for the type. | +| | `One` | Gets the value 1 for the type. | | | `Radix` | Gets the radix, or base, for the type. returns 2. returns 10. | | | `Zero` | Gets the value 0 for the type. | | | `CreateChecked` | Creates a value, throwing an if the input can't fit.1 | @@ -109,7 +109,7 @@ The following table shows some of the core APIs exposed by each interface. | | `MaxMagnitudeNumber` | Returns the value with a greater absolute value, returning the number if one input is `NaN`. | | | `MinMagnitude` | Returns the value with a lesser absolute value, returning `NaN` if either input is `NaN`. | | | `MinMagnitudeNumber` | Returns the value with a lesser absolute value, returning the number if one input is `NaN`. | -| | `NegativeOne` | Gets the value -1 for the type. | +| | `NegativeOne` | Gets the value -1 for the type. | 1To help understand the behavior of the three `Create*` methods, consider the following examples. @@ -138,36 +138,36 @@ The operator interfaces correspond to the various operators available to the C# | Interface name | Defined operators | |----------------------------------------------------|------------------------------------------| -| | `x + y` | -| | `x & y`, 'x | y', `x ^ y`, and `~x` | -| | `x < y`, `x > y`, `x <= y`, and `x >= y` | -| | `--x` and `x--` | -| | `x / y` | -| | `x == y` and `x != y` | -| | `++x` and `x++` | -| | `x % y` | -| | `x * y` | -| | `x << y` and `x >> y` | -| | `x - y` | -| | `-x` | -| | `+x` | +| | `x + y` | +| | `x & y`, 'x | y', `x ^ y`, and `~x` | +| | `x < y`, `x > y`, `x <= y`, and `x >= y` | +| | `--x` and `x--` | +| | `x / y` | +| | `x == y` and `x != y` | +| | `++x` and `x++` | +| | `x % y` | +| | `x * y` | +| | `x << y` and `x >> y` | +| | `x - y` | +| | `-x` | +| | `+x` | > [!NOTE] -> Some of the interfaces define a checked operator in addition to a regular unchecked operator. Checked operators are called in checked contexts and allow a user-defined type to define overflow behavior. If you implement a checked operator, for example, , you must also implement the unchecked operator, for example, . +> Some of the interfaces define a checked operator in addition to a regular unchecked operator. Checked operators are called in checked contexts and allow a user-defined type to define overflow behavior. If you implement a checked operator, for example, , you must also implement the unchecked operator, for example, . ### Function interfaces -The function interfaces define common mathematical APIs that apply more broadly than to a specific [numeric interface](#numeric-interfaces). These interfaces are all implemented by , and may get implemented by other relevant types in the future. +The function interfaces define common mathematical APIs that apply more broadly than to a specific [numeric interface](#numeric-interfaces). These interfaces are all implemented by , and may get implemented by other relevant types in the future. | Interface name | Description | |----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| | Exposes exponential functions supporting `e^x`, `e^x - 1`, `2^x`, `2^x - 1`, `10^x`, and `10^x - 1`. | -| | Exposes hyperbolic functions supporting `acosh(x)`, `asinh(x)`, `atanh(x)`, `cosh(x)`, `sinh(x)`, and `tanh(x)`. | -| | Exposes logarithmic functions supporting `ln(x)`, `ln(x + 1)`, `log2(x)`, `log2(x + 1)`, `log10(x)`, and `log10(x + 1)`. | -| | Exposes power functions supporting `x^y`. | -| | Exposes root functions supporting `cbrt(x)` and `sqrt(x)`. | -| | Exposes trigonometric functions supporting `acos(x)`, `asin(x)`, `atan(x)`, `cos(x)`, `sin(x)`, and `tan(x)`. | +| | Exposes exponential functions supporting `e^x`, `e^x - 1`, `2^x`, `2^x - 1`, `10^x`, and `10^x - 1`. | +| | Exposes hyperbolic functions supporting `acosh(x)`, `asinh(x)`, `atanh(x)`, `cosh(x)`, `sinh(x)`, and `tanh(x)`. | +| | Exposes logarithmic functions supporting `ln(x)`, `ln(x + 1)`, `log2(x)`, `log2(x + 1)`, `log10(x)`, and `log10(x + 1)`. | +| | Exposes power functions supporting `x^y`. | +| | Exposes root functions supporting `cbrt(x)` and `sqrt(x)`. | +| | Exposes trigonometric functions supporting `acos(x)`, `asin(x)`, `atan(x)`, `cos(x)`, `sin(x)`, and `tan(x)`. | ### Parsing and formatting interfaces @@ -175,14 +175,14 @@ Parsing and formatting are core concepts in programming. They're commonly used w | Interface name | Description | |------------------------------------|--------------------------------------------------------------------------------------------------| -| | Exposes support for `T.Parse(string, IFormatProvider)` and `T.TryParse(string, IFormatProvider, out TSelf)`. | -| | Exposes support for `T.Parse(ReadOnlySpan, IFormatProvider)` and `T.TryParse(ReadOnlySpan, IFormatProvider, out TSelf)`. | +| | Exposes support for `T.Parse(string, IFormatProvider)` and `T.TryParse(string, IFormatProvider, out TSelf)`. | +| | Exposes support for `T.Parse(ReadOnlySpan, IFormatProvider)` and `T.TryParse(ReadOnlySpan, IFormatProvider, out TSelf)`. | | 1 | Exposes support for `value.ToString(string, IFormatProvider)`. | | 1 | Exposes support for `value.TryFormat(Span, out int, ReadOnlySpan, IFormatProvider)`. | 1This interface isn't new, nor is it generic. However, it's implemented by all number types and represents the inverse operation of `IParsable`. -For example, the following program takes two numbers as input, reading them from the console using a generic method where the type parameter is constrained to be . It calculates the average using a generic method where the type parameters for the input and result values are constrained to be , and then displays the result to the console. +For example, the following program takes two numbers as input, reading them from the console using a generic method where the type parameter is constrained to be . It calculates the average using a generic method where the type parameters for the input and result values are constrained to be , and then displays the result to the console. ```csharp using System.Globalization; diff --git a/docs/standard/io/asynchronous-file-i-o.md b/docs/standard/io/asynchronous-file-i-o.md index 4483b244ca0d6..45e0cad6f9b72 100644 --- a/docs/standard/io/asynchronous-file-i-o.md +++ b/docs/standard/io/asynchronous-file-i-o.md @@ -22,9 +22,9 @@ ms.assetid: dbdd55e7-d6b9-4f9e-8abb-ab0edd4457f7 Asynchronous operations enable you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. -Starting with .NET Framework 4.5, the I/O types include async methods to simplify asynchronous operations. An async method contains `Async` in its name, such as , , , , , and . These async methods are implemented on stream classes, such as , , and , and on classes that are used for reading from or writing to streams, such and . +Starting with .NET Framework 4.5, the I/O types include async methods to simplify asynchronous operations. An async method contains `Async` in its name, such as , , , , , and . These async methods are implemented on stream classes, such as , , and , and on classes that are used for reading from or writing to streams, such and . -In .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous I/O operations. These methods are still available in current .NET versions to support legacy code; however, the async methods help you implement asynchronous I/O operations more easily. +In .NET Framework 4 and earlier versions, you have to use methods such as and to implement asynchronous I/O operations. These methods are still available in current .NET versions to support legacy code; however, the async methods help you implement asynchronous I/O operations more easily. C# and Visual Basic each have two keywords for asynchronous programming: diff --git a/docs/standard/io/buffers.md b/docs/standard/io/buffers.md index f0005ed49af67..0f9993c5a4ad8 100644 --- a/docs/standard/io/buffers.md +++ b/docs/standard/io/buffers.md @@ -13,10 +13,10 @@ This article provides an overview of types that help read data that runs across ## IBufferWriter\ - is a contract for synchronous buffered writing. At the lowest level, the interface: + is a contract for synchronous buffered writing. At the lowest level, the interface: - Is basic and not difficult to use. -- Allows access to a or . The `Memory` or `Span` can be written to and you can determine how many `T` items were written. +- Allows access to a or . The `Memory` or `Span` can be written to and you can determine how many `T` items were written. [!code-csharp[](~/samples/snippets/csharp/buffers/MyClass.cs?name=snippet)] @@ -24,13 +24,13 @@ The preceding method: - Requests a buffer of at least 5 bytes from the `IBufferWriter` using `GetSpan(5)`. - Writes bytes for the ASCII string "Hello" to the returned `Span`. -- Calls to indicate how many bytes were written to the buffer. +- Calls to indicate how many bytes were written to the buffer. -This method of writing uses the `Memory`/`Span` buffer provided by the `IBufferWriter`. Alternatively, the extension method can be used to copy an existing buffer to the `IBufferWriter`. `Write` does the work of calling `GetSpan`/`Advance` as appropriate, so there's no need to call `Advance` after writing: +This method of writing uses the `Memory`/`Span` buffer provided by the `IBufferWriter`. Alternatively, the extension method can be used to copy an existing buffer to the `IBufferWriter`. `Write` does the work of calling `GetSpan`/`Advance` as appropriate, so there's no need to call `Advance` after writing: [!code-csharp[](~/samples/snippets/csharp/buffers/MyClass.cs?name=snippet2)] - is an implementation of `IBufferWriter` whose backing store is a single contiguous array. + is an implementation of `IBufferWriter` whose backing store is a single contiguous array. ### IBufferWriter common problems @@ -42,11 +42,11 @@ This method of writing uses the `Memory`/`Span` buffer provided by the `IB ![ReadOnlySequence showing memory in pipe and below that sequence position of read-only memory](media/buffers/ro-sequence.png) - is a struct that can represent a contiguous or noncontiguous sequence of `T`. It can be constructed from: + is a struct that can represent a contiguous or noncontiguous sequence of `T`. It can be constructed from: 1. A `T[]` 1. A `ReadOnlyMemory` -1. A pair of linked list node and index to represent the start and end position of the sequence. +1. A pair of linked list node and index to represent the start and end position of the sequence. The third representation is the most interesting one as it has performance implications on various operations on the `ReadOnlySequence`: @@ -73,13 +73,13 @@ The `ReadOnlySequence` exposes data as an enumerable of `ReadOnlyMemory`. [!code-csharp[](~/samples/snippets/csharp/buffers/MyClass.cs?name=snippet3)] The preceding method searches each segment for a specific byte. If you need to keep track of each segment's `SequencePosition`, - is more appropriate. The next sample changes the preceding code to return a `SequencePosition` instead of an integer. Returning a `SequencePosition` has the benefit of allowing the caller to avoid a second scan to get the data at a specific index. + is more appropriate. The next sample changes the preceding code to return a `SequencePosition` instead of an integer. Returning a `SequencePosition` has the benefit of allowing the caller to avoid a second scan to get the data at a specific index. [!code-csharp[](~/samples/snippets/csharp/buffers/MyClass.cs?name=snippet4)] The combination of `SequencePosition` and `TryGet` acts like an enumerator. The position field is modified at the start of each iteration to be start of each segment within the `ReadOnlySequence`. -The preceding method exists as an extension method on `ReadOnlySequence`. can be used to simplify the preceding code: +The preceding method exists as an extension method on `ReadOnlySequence`. can be used to simplify the preceding code: ```csharp SequencePosition? FindIndexOf(in ReadOnlySequence buffer, byte data) => buffer.PositionOf(data); @@ -98,7 +98,7 @@ There are a few approaches that can be used to process data in multi-segmented s - Parse data segment by segment, keeping track of the `SequencePosition` and index within the segment parsed. This avoids unnecessary allocations but may be inefficient, especially for small buffers. - Copy the `ReadOnlySequence` to a contiguous array and treat it like a single buffer: - If the size of the `ReadOnlySequence` is small, it may be reasonable to copy the data into a stack-allocated buffer using the [stackalloc](../../csharp/language-reference/operators/stackalloc.md) operator. - - Copy the `ReadOnlySequence` into a pooled array using . + - Copy the `ReadOnlySequence` into a pooled array using . - Use [`ReadOnlySequence.ToArray()`](xref:System.Buffers.BuffersExtensions.ToArray%2A). This isn't recommended in hot paths as it allocates a new `T[]` on the heap. The following examples demonstrate some common cases for processing `ReadOnlySequence`: @@ -148,7 +148,7 @@ There are several unusual outcomes when dealing with a `ReadOnlySequence`/`Se ## SequenceReader\ -: +: - Is a new type that was introduced in .NET Core 3.0 to simplify the processing of a `ReadOnlySequence`. - Unifies the differences between a single segment `ReadOnlySequence` and multi-segment `ReadOnlySequence`. diff --git a/docs/standard/io/common-i-o-tasks.md b/docs/standard/io/common-i-o-tasks.md index 2397b68219acf..056f19f790611 100644 --- a/docs/standard/io/common-i-o-tasks.md +++ b/docs/standard/io/common-i-o-tasks.md @@ -13,37 +13,37 @@ The namespace provides several classes that allow for various a |To do this...|See the example in this topic...| |-------------------|--------------------------------------| -|Create a text file| method

method

method

method| +|Create a text file| method

method

method

method| |Write to a text file|[How to: Write Text to a File](how-to-write-text-to-a-file.md)

[How to: Write a Text File (C++/CLI)](/cpp/dotnet/how-to-write-a-text-file-cpp-cli)| |Read from a text file|[How to: Read Text from a File](how-to-read-text-from-a-file.md)| -|Append text to a file|[How to: Open and Append to a Log File](how-to-open-and-append-to-a-log-file.md)

method

method| -|Rename or move a file| method

method| -|Delete a file| method

method| -|Copy a file| method

method| -|Get the size of a file| property| -|Get the attributes of a file| method| -|Set the attributes of a file| method| -|Determine whether a file exists| method| +|Append text to a file|[How to: Open and Append to a Log File](how-to-open-and-append-to-a-log-file.md)

method

method| +|Rename or move a file| method

method| +|Delete a file| method

method| +|Copy a file| method

method| +|Get the size of a file| property| +|Get the attributes of a file| method| +|Set the attributes of a file| method| +|Determine whether a file exists| method| |Read from a binary file|[How to: Read and Write to a Newly Created Data File](how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file|[How to: Read and Write to a Newly Created Data File](how-to-read-and-write-to-a-newly-created-data-file.md)| -|Retrieve a file name extension| method| -|Retrieve the fully qualified path of a file| method| -|Retrieve the file name and extension from a path| method| -|Change the extension of a file| method| +|Retrieve a file name extension| method| +|Retrieve the fully qualified path of a file| method| +|Retrieve the file name and extension from a path| method| +|Change the extension of a file| method| ## Common Directory Tasks |To do this...|See the example in this topic...| |-------------------|--------------------------------------| |Access a file in a special folder such as My Documents|[How to: Write Text to a File](how-to-write-text-to-a-file.md)| -|Create a directory| method

property| -|Create a subdirectory| method| -|Rename or move a directory| method

method| +|Create a directory| method

property| +|Create a subdirectory| method| +|Rename or move a directory| method

method| |Copy a directory|[How to: Copy Directories](how-to-copy-directories.md)| -|Delete a directory| method

method| +|Delete a directory| method

method| |See the files and subdirectories in a directory|[How to: Enumerate Directories and Files](how-to-enumerate-directories-and-files.md)| |Find the size of a directory| class| -|Determine whether a directory exists| method| +|Determine whether a directory exists| method| ## See also diff --git a/docs/standard/io/composing-streams.md b/docs/standard/io/composing-streams.md index 867e54a4fdd86..f7b5548f9d72c 100644 --- a/docs/standard/io/composing-streams.md +++ b/docs/standard/io/composing-streams.md @@ -3,10 +3,10 @@ title: Transform data by composing streams description: "Learn how stream composition can transform data. Data passing through the stream is automatically altered." #ms.topic: concept-article (for a future work item that rewrites this article in this format) ms.date: 08/02/2024 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "streams, base streams" - "I/O [.NET], composing streams" - "Stream class, composing streams" @@ -22,7 +22,7 @@ A *backing store* is a storage medium, such as a disk or memory. Each type of ba Each stream type reads and writes bytes from and to its given backing store. Streams that connect to backing stores are called *base streams*. Base streams have constructors with the parameters necessary to connect the stream to the backing store. For example, has constructors that specify an access mode parameter, which determines if the file is read from, written to, or both. -The design of the classes provides simplified stream composition. You can attach base streams to one or more pass-through streams that provide the functionality you want. You can attach a reader or writer to the end of the chain, so the preferred types can be read or written easily. +The design of the classes provides simplified stream composition. You can attach base streams to one or more pass-through streams that provide the functionality you want. You can attach a reader or writer to the end of the chain, so the preferred types can be read or written easily. ## Prerequisites @@ -95,9 +95,9 @@ The following snippet provides the `CipherStream` class, which uses a basic shif ## See also - -- -- +- +- - - -- -- +- +- diff --git a/docs/standard/io/file-path-formats.md b/docs/standard/io/file-path-formats.md index 904d59b868007..a822ea60624c7 100644 --- a/docs/standard/io/file-path-formats.md +++ b/docs/standard/io/file-path-formats.md @@ -37,7 +37,7 @@ If all three components are present, the path is absolute. If no volume or drive > [!IMPORTANT] > Note the difference between the last two paths. Both specify the optional volume specifier (`C:` in both cases), but the first begins with the root of the specified volume, whereas the second does not. As result, the first is an absolute path from the root directory of drive `C:`, whereas the second is a relative path from the current directory of drive `C:`. Use of the second form when the first is intended is a common source of bugs that involve Windows file paths. -You can determine whether a file path is fully qualified (that is, if the path is independent of the current directory and doesn't change when the current directory changes) by calling the method. Note that such a path can include relative directory segments (`.` and `..`) and still be fully qualified if the resolved path always points to the same location. +You can determine whether a file path is fully qualified (that is, if the path is independent of the current directory and doesn't change when the current directory changes) by calling the method. Note that such a path can include relative directory segments (`.` and `..`) and still be fully qualified if the resolved path always points to the same location. The following example illustrates the difference between absolute and relative paths. It assumes that the directory `D:\FY2018\` exists, and that you haven't set any current directory for `D:\` from the command prompt before running the example. @@ -114,7 +114,7 @@ Almost all paths passed to Windows APIs are normalized. During normalization, Wi - Evaluates relative directory components (`.` for the current directory and `..` for the parent directory). - Trims certain characters. -This normalization happens implicitly, but you can do it explicitly by calling the method, which wraps a call to the [GetFullPathName() function](/windows/desktop/api/fileapi/nf-fileapi-getfullpathnamea). You can also call the Windows [GetFullPathName() function](/windows/desktop/api/fileapi/nf-fileapi-getfullpathnamea) directly using P/Invoke. +This normalization happens implicitly, but you can do it explicitly by calling the method, which wraps a call to the [GetFullPathName() function](/windows/desktop/api/fileapi/nf-fileapi-getfullpathnamea). You can also call the Windows [GetFullPathName() function](/windows/desktop/api/fileapi/nf-fileapi-getfullpathnamea) directly using P/Invoke. ### Identify the path diff --git a/docs/standard/io/handling-io-errors.md b/docs/standard/io/handling-io-errors.md index cb6bafce280ef..b0af672b7cbfc 100644 --- a/docs/standard/io/handling-io-errors.md +++ b/docs/standard/io/handling-io-errors.md @@ -2,13 +2,13 @@ title: "Handling I/O errors in .NET" description: Learn how to handle I/O errors in .NET. Map error codes to exceptions, handle exceptions in I/O operations, and handle IOException. ms.date: "08/27/2018" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "I/O, exception handling" - "I/O, errors" -ms.workload: +ms.workload: - "dotnet" - "dotnetcore" --- @@ -33,7 +33,7 @@ Because the file system is an operating system resource, I/O methods in both .NE For example, on the Windows operating system, a method call that returns an error code of `ERROR_FILE_NOT_FOUND` (or 0x02) maps to a , and an error code of `ERROR_PATH_NOT_FOUND` (or 0x03) maps to a . -However, the precise conditions under which the operating system returns particular error codes is often undocumented or poorly documented. As a result, unexpected exceptions can occur. For example, because you are working with a directory rather than a file, you would expect that providing an invalid directory path to the constructor throws a . However, it may also throw a . +However, the precise conditions under which the operating system returns particular error codes is often undocumented or poorly documented. As a result, unexpected exceptions can occur. For example, because you are working with a directory rather than a file, you would expect that providing an invalid directory path to the constructor throws a . However, it may also throw a . ## Exception handling in I/O operations diff --git a/docs/standard/io/how-to-add-or-remove-access-control-list-entries.md b/docs/standard/io/how-to-add-or-remove-access-control-list-entries.md index 7364e6911d812..d5277624cbc8b 100644 --- a/docs/standard/io/how-to-add-or-remove-access-control-list-entries.md +++ b/docs/standard/io/how-to-add-or-remove-access-control-list-entries.md @@ -18,19 +18,19 @@ To add or remove access control list (ACL) entries from a file or directory, get ## From a file -1. Call the (or, for .NET Framework apps, ) method to get a object that contains the current ACL entries of a file. +1. Call the (or, for .NET Framework apps, ) method to get a object that contains the current ACL entries of a file. 2. Add or remove ACL entries from the object obtained in step 1. -3. To apply the changes, pass the object to the (or, for .NET Framework apps, ) method. +3. To apply the changes, pass the object to the (or, for .NET Framework apps, ) method. ## From a directory -1. Call the (or, for .NET Framework apps, ) method to get a object that contains the current ACL entries of a directory. +1. Call the (or, for .NET Framework apps, ) method to get a object that contains the current ACL entries of a directory. 2. Add or remove ACL entries from the object obtained in step 1. -3. To apply the changes, pass the object to the (or, for .NET Framework apps, ) method. +3. To apply the changes, pass the object to the (or, for .NET Framework apps, ) method. ## Example diff --git a/docs/standard/io/how-to-anticipate-out-of-space-conditions-with-isolated-storage.md b/docs/standard/io/how-to-anticipate-out-of-space-conditions-with-isolated-storage.md index 13801fd69af7a..487c6d1eca193 100644 --- a/docs/standard/io/how-to-anticipate-out-of-space-conditions-with-isolated-storage.md +++ b/docs/standard/io/how-to-anticipate-out-of-space-conditions-with-isolated-storage.md @@ -26,13 +26,13 @@ helpviewer_keywords: Code that uses isolated storage is constrained by a [quota](isolated-storage.md#quotas) that specifies the maximum size for the data compartment in which isolated storage files and directories exist. The quota is defined by security policy and is configurable by administrators. If the maximum allowed size is exceeded when you try to write data, an exception is thrown and the operation fails. This helps prevent malicious denial-of-service attacks that could cause the application to refuse requests because data storage is filled. -To help you determine whether a given write attempt is likely to fail for this reason, the class provides three read-only properties: , , and . You can use these properties to determine whether writing to the store will cause the maximum allowed size of the store to be exceeded. Keep in mind that isolated storage can be accessed concurrently; therefore, when you compute the amount of remaining storage, the storage space could be consumed by the time you try to write to the store. However, you can use the maximum size of the store to help determine whether the upper limit on available storage is about to be reached. +To help you determine whether a given write attempt is likely to fail for this reason, the class provides three read-only properties: , , and . You can use these properties to determine whether writing to the store will cause the maximum allowed size of the store to be exceeded. Keep in mind that isolated storage can be accessed concurrently; therefore, when you compute the amount of remaining storage, the storage space could be consumed by the time you try to write to the store. However, you can use the maximum size of the store to help determine whether the upper limit on available storage is about to be reached. -The property depends on evidence from the assembly to work properly. For this reason, you should retrieve this property only on objects that were created by using the , , or method. objects that were created in any other way (for example, objects that were returned from the method) will not return an accurate maximum size. +The property depends on evidence from the assembly to work properly. For this reason, you should retrieve this property only on objects that were created by using the , , or method. objects that were created in any other way (for example, objects that were returned from the method) will not return an accurate maximum size. ## Example -The following code example obtains an isolated store, creates a few files, and retrieves the property. The remaining space is reported in bytes. +The following code example obtains an isolated store, creates a few files, and retrieves the property. The remaining space is reported in bytes. [!code-csharp[Conceptual.IsolatedStorage#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.isolatedstorage/cs/source7.cs#8)] [!code-vb[Conceptual.IsolatedStorage#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source7.vb#8)] diff --git a/docs/standard/io/how-to-compress-and-extract-files.md b/docs/standard/io/how-to-compress-and-extract-files.md index df18143d5f25e..43673f34510ba 100644 --- a/docs/standard/io/how-to-compress-and-extract-files.md +++ b/docs/standard/io/how-to-compress-and-extract-files.md @@ -43,7 +43,7 @@ To run the sample, create a *start* folder in your program folder and populate i ## Example 2: Extract specific file extensions -The following example iterates through the contents of an existing *.zip* file and extracts files with a *.txt* extension. It uses the class to access the *.zip* file, and the class to inspect the individual entries. The extension method for the object is available in the class. +The following example iterates through the contents of an existing *.zip* file and extracts files with a *.txt* extension. It uses the class to access the *.zip* file, and the class to inspect the individual entries. The extension method for the object is available in the class. To run the sample, place a *.zip* file called *result.zip* in your program folder. When prompted, provide a folder name to extract to. diff --git a/docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md b/docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md index 666b41402464f..9406a9b3b31ba 100644 --- a/docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md +++ b/docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Convert between .NET Framework and Windows Runtime streams (Windows only)" title: "How to: Convert between .NET Framework and Windows Runtime streams (Windows only)" ms.date: "01/14/2019" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: 23a763ea-8348-4244-9f8c-a4280b870b47 @@ -17,19 +17,19 @@ The To convert from a Windows Runtime stream to a .NET Framework stream, use one of the following methods: -- converts a random-access stream in the Windows Runtime to a managed stream in .NET for UWP apps. - -- converts an output stream in the Windows Runtime to a managed stream in .NET for UWP apps. - -- converts an input stream in the Windows Runtime to a managed stream in .NET for UWP apps. +- converts a random-access stream in the Windows Runtime to a managed stream in .NET for UWP apps. + +- converts an output stream in the Windows Runtime to a managed stream in .NET for UWP apps. + +- converts an input stream in the Windows Runtime to a managed stream in .NET for UWP apps. The Windows Runtime offers stream types that support reading only, writing only, or reading and writing. These capabilities are maintained when you convert a Windows Runtime stream to a .NET Framework stream. Furthermore, if you convert a Windows Runtime stream to a .NET Framework stream and back, you get the original Windows Runtime instance back. -It's best practice to use the conversion method that matches the capabilities of the Windows Runtime stream you want to convert. However, since is readable and writeable (it implements both and ), the conversion methods maintain the capabilities of the original stream. For example, using to convert an doesn't limit the converted .NET Framework stream to being readable. It's also writable. +It's best practice to use the conversion method that matches the capabilities of the Windows Runtime stream you want to convert. However, since is readable and writeable (it implements both and ), the conversion methods maintain the capabilities of the original stream. For example, using to convert an doesn't limit the converted .NET Framework stream to being readable. It's also writable. ## Example: Convert Windows Runtime random-access to .NET Framework stream -To convert from a Windows Runtime random-access stream to a .NET Framework stream, use the method. +To convert from a Windows Runtime random-access stream to a .NET Framework stream, use the method. The following code example prompts you to select a file, opens it with Windows Runtime APIs, and then converts it to a .NET Framework stream. It reads the stream and outputs it to a text block. You would typically manipulate the stream with .NET Framework APIs before outputting the results. @@ -60,26 +60,26 @@ if (result != null) { // ... } -} +} ``` ## Convert from a .NET Framework to a Windows Runtime stream To convert from a .NET Framework stream to a Windows Runtime stream, use one of the following methods: -- converts a managed stream in .NET for UWP apps to an input stream in the Windows Runtime. - -- converts a managed stream in .NET for UWP apps to an output stream in the Windows Runtime. - -- converts a managed stream in .NET for UWP apps to a random-access stream that the Windows Runtime can use for reading or writing. +- converts a managed stream in .NET for UWP apps to an input stream in the Windows Runtime. + +- converts a managed stream in .NET for UWP apps to an output stream in the Windows Runtime. + +- converts a managed stream in .NET for UWP apps to a random-access stream that the Windows Runtime can use for reading or writing. -When you convert a .NET Framework stream to a Windows Runtime stream, the capabilities of the converted stream depend on the original stream. For example, if the original stream supports both reading and writing, and you call to convert the stream, the returned type is an `IRandomAccessStream`. `IRandomAccessStream` implements `IInputStream` and `IOutputStream`, and supports reading and writing. +When you convert a .NET Framework stream to a Windows Runtime stream, the capabilities of the converted stream depend on the original stream. For example, if the original stream supports both reading and writing, and you call to convert the stream, the returned type is an `IRandomAccessStream`. `IRandomAccessStream` implements `IInputStream` and `IOutputStream`, and supports reading and writing. -.NET Framework streams don't support cloning, even after conversion. If you convert a .NET Framework stream to a Windows Runtime stream and call or , which call , or if you call directly, an exception occurs. +.NET Framework streams don't support cloning, even after conversion. If you convert a .NET Framework stream to a Windows Runtime stream and call or , which call , or if you call directly, an exception occurs. ## Example: Convert .NET Framework to Windows Runtime random-access stream -To convert from a .NET Framework stream to a Windows Runtime random-access stream, use the method, as shown in the following example: +To convert from a .NET Framework stream to a Windows Runtime random-access stream, use the method, as shown in the following example: > [!IMPORTANT] > Make sure that the .NET Framework stream you are using supports seeking, or copy it to a stream that does. You can use the property to determine this. @@ -104,6 +104,6 @@ Image1.Source = bitmap; ## See also -- [Quickstart: Read and write a file (Windows)](/previous-versions/windows/apps/hh464978(v=win.10)) -- [.NET for Windows Store apps overview](/previous-versions/windows/apps/br230302(v=vs.140)) +- [Quickstart: Read and write a file (Windows)](/previous-versions/windows/apps/hh464978(v=win.10)) +- [.NET for Windows Store apps overview](/previous-versions/windows/apps/br230302(v=vs.140)) - [.NET for Windows Store apps APIs](/previous-versions/br230232(v=vs.120)) diff --git a/docs/standard/io/how-to-create-files-and-directories-in-isolated-storage.md b/docs/standard/io/how-to-create-files-and-directories-in-isolated-storage.md index cfae4593e4d95..d27671911477e 100644 --- a/docs/standard/io/how-to-create-files-and-directories-in-isolated-storage.md +++ b/docs/standard/io/how-to-create-files-and-directories-in-isolated-storage.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Create Files and Directories in Isolated Storage" title: "How to: Create Files and Directories in Isolated Storage" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "directories [.NET], isolated storage" - "files [.NET], isolated storage" - "isolated storage, creating files and directories" @@ -17,23 +17,23 @@ ms.assetid: 2ca4d2a4-809b-4f00-bc08-bf4a64d3a5c3 --- # How to: Create Files and Directories in Isolated Storage -After you've obtained an isolated store, you can create directories and files for storing data. Within a store, file and directory names are specified with respect to the root of the virtual file system. - - To create a directory, use the instance method. If you specify a subdirectory of a directory that doesn't exist, both directories are created. If you specify a directory that already exists, the method returns without creating a directory, and no exception is thrown. However, if you specify a directory name that contains invalid characters, an exception is thrown. - - To create a file, use the method. - - In the Windows operating system, isolated storage file and directory names are case-insensitive. That is, if you create a file named `ThisFile.txt`, and then create another file named `THISFILE.TXT`, only one file is created. The file name keeps its original casing for display purposes. +After you've obtained an isolated store, you can create directories and files for storing data. Within a store, file and directory names are specified with respect to the root of the virtual file system. + + To create a directory, use the instance method. If you specify a subdirectory of a directory that doesn't exist, both directories are created. If you specify a directory that already exists, the method returns without creating a directory, and no exception is thrown. However, if you specify a directory name that contains invalid characters, an exception is thrown. + + To create a file, use the method. + + In the Windows operating system, isolated storage file and directory names are case-insensitive. That is, if you create a file named `ThisFile.txt`, and then create another file named `THISFILE.TXT`, only one file is created. The file name keeps its original casing for display purposes. Isolated storage file creation will throw an if the path contains a directory that does not exist. - -## Example - The following code example illustrates how to create files and directories in an isolated store. - +## Example + + The following code example illustrates how to create files and directories in an isolated store. + [!code-csharp[Conceptual.IsolatedStorage#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.isolatedstorage/cs/source.cs#1)] - [!code-vb[Conceptual.IsolatedStorage#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source.vb#1)] - + [!code-vb[Conceptual.IsolatedStorage#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source.vb#1)] + ## See also - diff --git a/docs/standard/io/how-to-delete-files-and-directories-in-isolated-storage.md b/docs/standard/io/how-to-delete-files-and-directories-in-isolated-storage.md index 9adc6d2e4452c..b191ac0764be7 100644 --- a/docs/standard/io/how-to-delete-files-and-directories-in-isolated-storage.md +++ b/docs/standard/io/how-to-delete-files-and-directories-in-isolated-storage.md @@ -20,9 +20,9 @@ helpviewer_keywords: You can delete directories and files within an isolated storage file. Within a store, file and directory names are operating-system dependent and are specified as relative to the root of the virtual file system. They are not case-sensitive on Windows operating systems. - The class supplies two methods for deleting directories and files: and . An exception is thrown if you try to delete a file or directory that does not exist. If you include a wildcard character in the name, throws an exception, and throws an exception. + The class supplies two methods for deleting directories and files: and . An exception is thrown if you try to delete a file or directory that does not exist. If you include a wildcard character in the name, throws an exception, and throws an exception. - The method fails if the directory contains any files or subdirectories. You can use the and methods to retrieve the existing files and directories. For more information about searching the virtual file system of a store, see [How to: Find Existing Files and Directories in Isolated Storage](how-to-find-existing-files-and-directories-in-isolated-storage.md). + The method fails if the directory contains any files or subdirectories. You can use the and methods to retrieve the existing files and directories. For more information about searching the virtual file system of a store, see [How to: Find Existing Files and Directories in Isolated Storage](how-to-find-existing-files-and-directories-in-isolated-storage.md). ## Example diff --git a/docs/standard/io/how-to-delete-stores-in-isolated-storage.md b/docs/standard/io/how-to-delete-stores-in-isolated-storage.md index 1a9266ed8f169..540ea7fcd4667 100644 --- a/docs/standard/io/how-to-delete-stores-in-isolated-storage.md +++ b/docs/standard/io/how-to-delete-stores-in-isolated-storage.md @@ -24,7 +24,7 @@ The class supplies two meth ## Example - The following code example demonstrates the use of the static and instance methods. The class obtains two stores; one is isolated for user and assembly and the other is isolated for user, domain, and assembly. The user, domain, and assembly store is then deleted by calling the method of the isolated storage file `isoStore1`. Then, all remaining stores for the user are deleted by calling the static method . + The following code example demonstrates the use of the static and instance methods. The class obtains two stores; one is isolated for user and assembly and the other is isolated for user, domain, and assembly. The user, domain, and assembly store is then deleted by calling the method of the isolated storage file `isoStore1`. Then, all remaining stores for the user are deleted by calling the static method . [!code-csharp[Conceptual.IsolatedStorage#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.isolatedstorage/cs/source3.cs#3)] [!code-vb[Conceptual.IsolatedStorage#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source3.vb#3)] diff --git a/docs/standard/io/how-to-enumerate-directories-and-files.md b/docs/standard/io/how-to-enumerate-directories-and-files.md index aa60a4e8e7b04..fccdffe2bb780 100644 --- a/docs/standard/io/how-to-enumerate-directories-and-files.md +++ b/docs/standard/io/how-to-enumerate-directories-and-files.md @@ -2,60 +2,60 @@ title: "How to: Enumerate directories and files" description: Learn to enumerate directories and files by using enumerable collections, which can provide better performance than arrays in .NET. ms.date: "12/27/2018" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "I/O [.NET], enumerating directories and files" ms.assetid: 86b69a08-3bfa-4e5f-b4e1-3b7cb8478215 --- # How to: Enumerate directories and files -Enumerable collections provide better performance than arrays when you work with large collections of directories and files. To enumerate directories and files, use methods that return an enumerable collection of directory or file names, or their , , or objects. - -If you want to search and return only the names of directories or files, use the enumeration methods of the class. If you want to search and return other properties of directories or files, use the and classes. - -You can use enumerable collections from these methods as the parameter for constructors of collection classes like . - -The following table summarizes the methods that return enumerable collections of files and directories: - -|To search and return|Use method| -|------------------|-------------------------------------|-------------------| -|Directory names|| -|Directory information ()|| -|File names|| -|File information ()|| -|File system entry names|| -|File system entry information ()|| -|Directory and file names || +Enumerable collections provide better performance than arrays when you work with large collections of directories and files. To enumerate directories and files, use methods that return an enumerable collection of directory or file names, or their , , or objects. + +If you want to search and return only the names of directories or files, use the enumeration methods of the class. If you want to search and return other properties of directories or files, use the and classes. + +You can use enumerable collections from these methods as the parameter for constructors of collection classes like . + +The following table summarizes the methods that return enumerable collections of files and directories: + +|To search and return|Use method| +|------------------|-------------------------------------|-------------------| +|Directory names|| +|Directory information ()|| +|File names|| +|File information ()|| +|File system entry names|| +|File system entry information ()|| +|Directory and file names || > [!NOTE] -> Although you can immediately enumerate all the files in the subdirectories of a parent directory by using the option of the optional enumeration, errors may make the enumeration incomplete. You can catch these exceptions by first enumerating directories and then enumerating files. - -## Examples: Use the Directory class - -The following example uses the method to get a list of the top-level directory names in a specified path. +> Although you can immediately enumerate all the files in the subdirectories of a parent directory by using the option of the optional enumeration, errors may make the enumeration incomplete. You can catch these exceptions by first enumerating directories and then enumerating files. + +## Examples: Use the Directory class + +The following example uses the method to get a list of the top-level directory names in a specified path. [!code-csharp[System.IO.EnumDirs1#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.enumdirs1/cs/program.cs#1)] -[!code-vb[System.IO.EnumDirs1#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.enumdirs1/vb/program.vb#1)] +[!code-vb[System.IO.EnumDirs1#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.enumdirs1/vb/program.vb#1)] The following example uses the method to recursively enumerate all file names in a directory and subdirectories that match a certain pattern. It then reads each line of each file and displays the lines that contain a specified string, with their filenames and paths. [!code-csharp[System.IO.Directory.EnumerateFiles#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.directory.enumeratefiles/cs/program.cs#1)] -[!code-vb[System.IO.Directory.EnumerateFiles#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directory.enumeratefiles/vb/program.vb#1)] - -## Examples: Use the DirectoryInfo class - -The following example uses the method to list a collection of top-level directories whose is earlier than a certain value. +[!code-vb[System.IO.Directory.EnumerateFiles#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directory.enumeratefiles/vb/program.vb#1)] + +## Examples: Use the DirectoryInfo class + +The following example uses the method to list a collection of top-level directories whose is earlier than a certain value. [!code-csharp[System.IO.DirectoryInfo.EnumDirs#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.directoryinfo.enumdirs/cs/program.cs)] -[!code-vb[System.IO.DirectoryInfo.EnumDirs#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumdirs/vb/module1.vb)] - -The following example uses the method to list all files whose exceeds 10MB. This example first enumerates the top-level directories, to catch possible unauthorized access exceptions, and then enumerates the files. +[!code-vb[System.IO.DirectoryInfo.EnumDirs#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumdirs/vb/module1.vb)] + +The following example uses the method to list all files whose exceeds 10MB. This example first enumerates the top-level directories, to catch possible unauthorized access exceptions, and then enumerates the files. [!code-csharp[System.IO.DirectoryInfo.EnumerateDirectories#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.directoryinfo.enumeratedirectories/cs/program.cs#1)] -[!code-vb[System.IO.DirectoryInfo.EnumerateDirectories#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumeratedirectories/vb/program.vb#1)] - +[!code-vb[System.IO.DirectoryInfo.EnumerateDirectories#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumeratedirectories/vb/program.vb#1)] + ## See also - [File and stream I/O](index.md) diff --git a/docs/standard/io/how-to-enumerate-stores-for-isolated-storage.md b/docs/standard/io/how-to-enumerate-stores-for-isolated-storage.md index 9694223734f09..504575d5bef1e 100644 --- a/docs/standard/io/how-to-enumerate-stores-for-isolated-storage.md +++ b/docs/standard/io/how-to-enumerate-stores-for-isolated-storage.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Enumerate Stores for Isolated Storage" title: "How to: Enumerate Stores for Isolated Storage" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "enumerating stores" - "data storage using isolated storage, enumerating stores" - "storing data using isolated storage, enumerating stores" @@ -16,15 +16,15 @@ ms.assetid: 0fcf279a-f241-48f0-8034-2e3d331f1fcb --- # How to: Enumerate Stores for Isolated Storage -You can enumerate all isolated stores for the current user by using the static method. This method takes an value and returns an enumerator. To enumerate stores, you must have the permission that specifies the value. If you call the method with the value, it returns an array of objects that are defined for the current user. - -## Example +You can enumerate all isolated stores for the current user by using the static method. This method takes an value and returns an enumerator. To enumerate stores, you must have the permission that specifies the value. If you call the method with the value, it returns an array of objects that are defined for the current user. + +## Example + + The following code example obtains a store that is isolated by user and assembly, creates a few files, and retrieves those files by using the method. - The following code example obtains a store that is isolated by user and assembly, creates a few files, and retrieves those files by using the method. - [!code-csharp[Conceptual.IsolatedStorage#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.isolatedstorage/cs/source2.cs#2)] - [!code-vb[Conceptual.IsolatedStorage#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source2.vb#2)] - + [!code-vb[Conceptual.IsolatedStorage#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source2.vb#2)] + ## See also - diff --git a/docs/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage.md b/docs/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage.md index 9391af35c9a75..d03c79495cf27 100644 --- a/docs/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage.md +++ b/docs/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage.md @@ -18,15 +18,15 @@ helpviewer_keywords: --- # How to: Find existing files and directories in isolated storage -To search for a directory in isolated storage, use the method. This method takes a string that represents a search pattern. You can use both single-character (?) and multi-character (\*) wildcard characters in the search pattern, but the wildcard characters must appear in the final portion of the name. For example, `directory1/*ect*` is a valid search string, but `*ect*/directory2` is not. +To search for a directory in isolated storage, use the method. This method takes a string that represents a search pattern. You can use both single-character (?) and multi-character (\*) wildcard characters in the search pattern, but the wildcard characters must appear in the final portion of the name. For example, `directory1/*ect*` is a valid search string, but `*ect*/directory2` is not. - To search for a file, use the method. The restriction for wildcard characters in search strings that applies to also applies to . + To search for a file, use the method. The restriction for wildcard characters in search strings that applies to also applies to . Neither of these methods is recursive; the class does not supply any methods for listing all directories or files in your store. However, recursive methods are shown in the following code example. ## Example - The following code example illustrates how to create files and directories in an isolated store. First, a store that is isolated for user, domain, and assembly is retrieved and placed in the `isoStore` variable. The method is used to set up a few different directories, and the constructor creates some files in these directories. The code then loops through the results of the `GetAllDirectories` method. This method uses to find all the directory names in the current directory. These names are stored in an array, and then `GetAllDirectories` calls itself, passing in each directory it has found. As a result, all the directory names are returned in an array. Next, the code calls the `GetAllFiles` method. This method calls `GetAllDirectories` to find out the names of all the directories, and then it checks each directory for files by using the method. The result is returned in an array for display. + The following code example illustrates how to create files and directories in an isolated store. First, a store that is isolated for user, domain, and assembly is retrieved and placed in the `isoStore` variable. The method is used to set up a few different directories, and the constructor creates some files in these directories. The code then loops through the results of the `GetAllDirectories` method. This method uses to find all the directory names in the current directory. These names are stored in an array, and then `GetAllDirectories` calls itself, passing in each directory it has found. As a result, all the directory names are returned in an array. Next, the code calls the `GetAllFiles` method. This method calls `GetAllDirectories` to find out the names of all the directories, and then it checks each directory for files by using the method. The result is returned in an array for display. [!code-csharp[Conceptual.IsolatedStorage#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.isolatedstorage/cs/source8.cs#9)] [!code-vb[Conceptual.IsolatedStorage#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source8.vb#9)] diff --git a/docs/standard/io/how-to-obtain-stores-for-isolated-storage.md b/docs/standard/io/how-to-obtain-stores-for-isolated-storage.md index 993f53029197a..51e698c338dc4 100644 --- a/docs/standard/io/how-to-obtain-stores-for-isolated-storage.md +++ b/docs/standard/io/how-to-obtain-stores-for-isolated-storage.md @@ -16,29 +16,29 @@ helpviewer_keywords: An isolated store exposes a virtual file system within a data compartment. The class supplies a number of methods for interacting with an isolated store. To create and retrieve stores, provides three static methods: -- returns storage that is isolated by user and assembly. +- returns storage that is isolated by user and assembly. -- returns storage that is isolated by domain and assembly. +- returns storage that is isolated by domain and assembly. Both methods retrieve a store that belongs to the code from which they are called. -- The static method returns an isolated store that is specified by passing in a combination of scope parameters. +- The static method returns an isolated store that is specified by passing in a combination of scope parameters. The following code returns a store that is isolated by user, assembly, and domain. [!code-csharp[Conceptual.IsolatedStorage#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.isolatedstorage/cs/source6.cs#6)] [!code-vb[Conceptual.IsolatedStorage#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source6.vb#6)] - You can use the method to specify that a store should roam with a roaming user profile. For details on how to set this up, see [Types of Isolation](types-of-isolation.md). + You can use the method to specify that a store should roam with a roaming user profile. For details on how to set this up, see [Types of Isolation](types-of-isolation.md). - Isolated stores obtained from within different assemblies are, by default, different stores. You can access the store of a different assembly or domain by passing in the assembly or domain evidence in the parameters of the method. This requires permission to access isolated storage by application domain identity. For more information, see the method overloads. + Isolated stores obtained from within different assemblies are, by default, different stores. You can access the store of a different assembly or domain by passing in the assembly or domain evidence in the parameters of the method. This requires permission to access isolated storage by application domain identity. For more information, see the method overloads. - The , , and methods return an object. To help you decide which isolation type is most appropriate for your situation, see [Types of Isolation](types-of-isolation.md). When you have an isolated storage file object, you can use the isolated storage methods to read, write, create, and delete files and directories. + The , , and methods return an object. To help you decide which isolation type is most appropriate for your situation, see [Types of Isolation](types-of-isolation.md). When you have an isolated storage file object, you can use the isolated storage methods to read, write, create, and delete files and directories. - There is no mechanism that prevents code from passing an object to code that does not have sufficient access to get the store itself. Domain and assembly identities and isolated storage permissions are checked only when a reference to an object is obtained, typically in the , , or method. Protecting references to objects is, therefore, the responsibility of the code that uses these references. + There is no mechanism that prevents code from passing an object to code that does not have sufficient access to get the store itself. Domain and assembly identities and isolated storage permissions are checked only when a reference to an object is obtained, typically in the , , or method. Protecting references to objects is, therefore, the responsibility of the code that uses these references. ## Example - The following code provides a simple example of a class obtaining a store that is isolated by user and assembly. The code can be changed to retrieve a store that is isolated by user, domain, and assembly by adding to the arguments that the method passes. + The following code provides a simple example of a class obtaining a store that is isolated by user and assembly. The code can be changed to retrieve a store that is isolated by user, domain, and assembly by adding to the arguments that the method passes. After you run the code, you can confirm that a store was created by typing **StoreAdm /LIST** at the command line. This runs the [Isolated Storage tool (Storeadm.exe)](../../framework/tools/storeadm-exe-isolated-storage-tool.md) and lists all the current isolated stores for the user. [!code-csharp[Conceptual.IsolatedStorage#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.isolatedstorage/cs/source6.cs#7)] diff --git a/docs/standard/io/how-to-open-and-append-to-a-log-file.md b/docs/standard/io/how-to-open-and-append-to-a-log-file.md index 45ad83bbdaebb..7dfda5ea506ce 100644 --- a/docs/standard/io/how-to-open-and-append-to-a-log-file.md +++ b/docs/standard/io/how-to-open-and-append-to-a-log-file.md @@ -2,10 +2,10 @@ title: "How to: Open and append to a log file" description: Open and append to a log file using the StreamWriter and StreamReader classes in .NET, which write characters to and read characters from streams. ms.date: "01/21/2019" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "log files, opening" - "streams, opening and appending to log file" - "log files, appending to" @@ -16,27 +16,27 @@ ms.assetid: 74423362-1721-49cb-aa0a-e04005f72a06 and write characters to and read characters from streams. The following code example opens the *log.txt* file for input, or creates it if it doesn't exist, and appends log information to the end of the file. The example then writes the contents of the file to standard output for display. -As an alternative to this example, you could store the information as a single string or string array, and use the or method to achieve the same functionality. - +As an alternative to this example, you could store the information as a single string or string array, and use the or method to achieve the same functionality. + > [!NOTE] -> Visual Basic users may choose to use the methods and properties provided by the class or class for creating or writing to log files. - -## Example +> Visual Basic users may choose to use the methods and properties provided by the class or class for creating or writing to log files. + +## Example [!code-csharp[Conceptual.BasicIO.TextFiles#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.basicio.textfiles/cs/source2.cs#2)] - [!code-vb[Conceptual.BasicIO.TextFiles#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.basicio.textfiles/vb/source2.vb#2)] - + [!code-vb[Conceptual.BasicIO.TextFiles#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.basicio.textfiles/vb/source2.vb#2)] + ## See also -- -- -- -- -- -- [How to: Enumerate directories and files](how-to-enumerate-directories-and-files.md) -- [How to: Read and write to a newly created data file](how-to-read-and-write-to-a-newly-created-data-file.md) -- [How to: Read text from a file](how-to-read-text-from-a-file.md) -- [How to: Write text to a file](how-to-write-text-to-a-file.md) -- [How to: Read characters from a string](how-to-read-characters-from-a-string.md) -- [How to: Write characters to a string](how-to-write-characters-to-a-string.md) +- +- +- +- +- +- [How to: Enumerate directories and files](how-to-enumerate-directories-and-files.md) +- [How to: Read and write to a newly created data file](how-to-read-and-write-to-a-newly-created-data-file.md) +- [How to: Read text from a file](how-to-read-text-from-a-file.md) +- [How to: Write text to a file](how-to-write-text-to-a-file.md) +- [How to: Read characters from a string](how-to-read-characters-from-a-string.md) +- [How to: Write characters to a string](how-to-write-characters-to-a-string.md) - [File and stream I/O](index.md) diff --git a/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md b/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md index 6798f8e2faccb..3b5af313faf18 100644 --- a/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md +++ b/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md @@ -31,7 +31,7 @@ The example creates a data file called *Test.data* in the current directory, cre - - - -- +- - - [How to: Enumerate directories and files](how-to-enumerate-directories-and-files.md) - [How to: Open and append to a log file](how-to-open-and-append-to-a-log-file.md) diff --git a/docs/standard/io/how-to-read-characters-from-a-string.md b/docs/standard/io/how-to-read-characters-from-a-string.md index f13805d7e3708..63367796a57d1 100644 --- a/docs/standard/io/how-to-read-characters-from-a-string.md +++ b/docs/standard/io/how-to-read-characters-from-a-string.md @@ -34,7 +34,7 @@ The following code examples show how to read characters synchronously or asynchr ## See also - -- +- - [Asynchronous file I/O](asynchronous-file-i-o.md) - [How to: Create a directory listing](/previous-versions/dotnet/netframework-4.0/5cf8zcfh(v=vs.100)) - [How to: Read and write to a newly created data file](how-to-read-and-write-to-a-newly-created-data-file.md) diff --git a/docs/standard/io/how-to-read-text-from-a-file.md b/docs/standard/io/how-to-read-text-from-a-file.md index 1db90fbeca422..e0b62facd9a30 100644 --- a/docs/standard/io/how-to-read-text-from-a-file.md +++ b/docs/standard/io/how-to-read-text-from-a-file.md @@ -3,10 +3,10 @@ title: "Read text from a file" description: In this article, see examples of how to read text synchronously or asynchronously from a text file, using the StreamReader class in .NET for desktop apps. ms.date: 05/09/2024 ms.custom: devdivchpfy22 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "streams, reading text from files" - "reading text files" - "reading data, text files" @@ -56,5 +56,5 @@ The following example shows an asynchronous read operation within a console app. - [Asynchronous file I/O](asynchronous-file-i-o.md). - [How to: Write text to a file](how-to-write-text-to-a-file.md). - -- -- +- +- diff --git a/docs/standard/io/how-to-use-named-pipes-for-network-interprocess-communication.md b/docs/standard/io/how-to-use-named-pipes-for-network-interprocess-communication.md index 88e318d7508ed..f360288c50e75 100644 --- a/docs/standard/io/how-to-use-named-pipes-for-network-interprocess-communication.md +++ b/docs/standard/io/how-to-use-named-pipes-for-network-interprocess-communication.md @@ -43,6 +43,6 @@ Named pipes provide interprocess communication between a pipe server and one or ## See also - -- +- - [Pipes](pipe-operations.md) - [How to: Use Anonymous Pipes for Local Interprocess Communication](how-to-use-anonymous-pipes-for-local-interprocess-communication.md) diff --git a/docs/standard/io/how-to-write-characters-to-a-string.md b/docs/standard/io/how-to-write-characters-to-a-string.md index 4b0fa473016eb..6814d648b935a 100644 --- a/docs/standard/io/how-to-write-characters-to-a-string.md +++ b/docs/standard/io/how-to-write-characters-to-a-string.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Write characters to a string" title: "How to: Write characters to a string" ms.date: "01/21/2019" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "data streams, writing characters to string" - "writing characters to strings" - "streams, writing characters to strings" @@ -14,32 +14,32 @@ ms.assetid: 1222cbeb-0760-44bf-9888-914a2a37174b --- # How to: Write characters to a string -The following code examples write characters synchronously or asynchronously from a character array into a string. - -## Example: Write characters synchronously in a console app +The following code examples write characters synchronously or asynchronously from a character array into a string. + +## Example: Write characters synchronously in a console app The following example uses a to write five characters synchronously to a object. - + [!code-csharp[Conceptual.StringBuilder#9](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/example2.cs#9)] - [!code-vb[Conceptual.StringBuilder#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/example2.vb#9)] - + [!code-vb[Conceptual.StringBuilder#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/example2.vb#9)] + ## Example: Write characters asynchronously in a WPF app - The next example is the code behind a WPF app. On window load, the example asynchronously reads all characters from a control and stores them in an array. It then asynchronously writes each letter or white-space character to a separate line of a control. - + The next example is the code behind a WPF app. On window load, the example asynchronously reads all characters from a control and stores them in an array. It then asynchronously writes each letter or white-space character to a separate line of a control. + [!code-csharp[StreamReaderWriter](../../../samples/snippets/csharp/VS_Snippets_Wpf/StringReaderWriter/MainWindow.xaml.cs)] - [!code-vb[StreamReaderWriter](../../../samples/snippets/visualbasic/VS_Snippets_Wpf/StringReaderWriter/MainWindow.xaml.vb)] - + [!code-vb[StreamReaderWriter](../../../samples/snippets/visualbasic/VS_Snippets_Wpf/StringReaderWriter/MainWindow.xaml.vb)] + ## See also -- -- -- -- [File and stream I/O](index.md) -- [Asynchronous file I/O](asynchronous-file-i-o.md) -- [How to: Enumerate directories and files](how-to-enumerate-directories-and-files.md) -- [How to: Read and write to a newly created data file](how-to-read-and-write-to-a-newly-created-data-file.md) -- [How to: Open and append to a log file](how-to-open-and-append-to-a-log-file.md) -- [How to: Read text from a file](how-to-read-text-from-a-file.md) -- [How to: Write text to a file](how-to-write-text-to-a-file.md) +- +- +- +- [File and stream I/O](index.md) +- [Asynchronous file I/O](asynchronous-file-i-o.md) +- [How to: Enumerate directories and files](how-to-enumerate-directories-and-files.md) +- [How to: Read and write to a newly created data file](how-to-read-and-write-to-a-newly-created-data-file.md) +- [How to: Open and append to a log file](how-to-open-and-append-to-a-log-file.md) +- [How to: Read text from a file](how-to-read-text-from-a-file.md) +- [How to: Write text to a file](how-to-write-text-to-a-file.md) - [How to: Read characters from a string](how-to-read-characters-from-a-string.md) diff --git a/docs/standard/io/how-to-write-text-to-a-file.md b/docs/standard/io/how-to-write-text-to-a-file.md index d93eeabdd04ef..f7bd1f08e8798 100644 --- a/docs/standard/io/how-to-write-text-to-a-file.md +++ b/docs/standard/io/how-to-write-text-to-a-file.md @@ -3,10 +3,10 @@ title: "How to: Write text to a file" description: Learn ways to write or append text to a file for a .NET app. Use methods from the StreamWriter or File classes to write text synchronously or asynchronously. ms.date: "10/21/2025" ms.custom: devdivchpfy22 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "writing text to files" - "I/O [.NET], writing text to files" - "streams, writing text to files" @@ -18,50 +18,50 @@ ai-usage: ai-assisted This article shows different ways to write text to a file for a .NET app. -The following classes and methods are typically used to write text to a file: - -- contains methods to write to a file synchronously ( and ) or asynchronously ( and ). - -- provides static methods to write text to a file such as and , or to append text to a file such as , , and . - -- is for strings that have file or directory path information. It contains the method and in .NET Core 2.1 and later, the and methods. These methods let you concatenate strings for building a file or directory path. +The following classes and methods are typically used to write text to a file: + +- contains methods to write to a file synchronously ( and ) or asynchronously ( and ). + +- provides static methods to write text to a file such as and , or to append text to a file such as , , and . + +- is for strings that have file or directory path information. It contains the method and in .NET Core 2.1 and later, the and methods. These methods let you concatenate strings for building a file or directory path. > [!NOTE] -> The following examples show only the minimum amount of code needed. A real-world app usually provides more robust error checking and exception handling. - +> The following examples show only the minimum amount of code needed. A real-world app usually provides more robust error checking and exception handling. + ## Example: Synchronously write text with StreamWriter -The following example shows how to use the class to synchronously write text to a new file one line at a time. Because the object is declared and instantiated in a `using` statement, the method is invoked, which automatically flushes and closes the stream. +The following example shows how to use the class to synchronously write text to a new file one line at a time. Because the object is declared and instantiated in a `using` statement, the method is invoked, which automatically flushes and closes the stream. [!code-csharp[Conceptual.BasicIO.TextFiles#WriteLine](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.basicio.textfiles/cs/write.cs)] -[!code-vb[Conceptual.BasicIO.TextFiles#WriteLine](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.basicio.textfiles/vb/write.vb)] +[!code-vb[Conceptual.BasicIO.TextFiles#WriteLine](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.basicio.textfiles/vb/write.vb)] ## Example: Synchronously append text with StreamWriter The following example shows how to use the class to synchronously append text to the text file created in the first example: [!code-csharp[Conceptual.BasicIO.TextFiles#WriteLine](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.basicio.textfiles/cs/append.cs)] -[!code-vb[Conceptual.BasicIO.TextFiles#WriteLine](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.basicio.textfiles/vb/append.vb)] +[!code-vb[Conceptual.BasicIO.TextFiles#WriteLine](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.basicio.textfiles/vb/append.vb)] ## Example: Asynchronously write text with StreamWriter -The following example shows how to asynchronously write text to a new file using the class. To invoke the method, the method call must be within an `async` method. +The following example shows how to asynchronously write text to a new file using the class. To invoke the method, the method call must be within an `async` method. [!code-csharp[Conceptual.BasicIO.TextFiles#WriteLine](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.basicio.textfiles/cs/async.cs)] -[!code-vb[Conceptual.BasicIO.TextFiles#WriteLine](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.basicio.textfiles/vb/async.vb)] +[!code-vb[Conceptual.BasicIO.TextFiles#WriteLine](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.basicio.textfiles/vb/async.vb)] ## Example: Write and append text with the File class -The following example shows how to write text to a new file and append new lines of text to the same file using the class. The and methods open and close the file automatically. If the path you provide to the method already exists, the file is overwritten. +The following example shows how to write text to a new file and append new lines of text to the same file using the class. The and methods open and close the file automatically. If the path you provide to the method already exists, the file is overwritten. [!code-csharp[Conceptual.BasicIO.TextFiles#WriteLine](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.basicio.textfiles/cs/file.cs)] -[!code-vb[Conceptual.BasicIO.TextFiles#WriteLine](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.basicio.textfiles/vb/file.vb)] +[!code-vb[Conceptual.BasicIO.TextFiles#WriteLine](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.basicio.textfiles/vb/file.vb)] ## See also - - -- +- - [How to: Enumerate directories and files](how-to-enumerate-directories-and-files.md) - [How to: Read and write to a newly created data file](how-to-read-and-write-to-a-newly-created-data-file.md) - [How to: Open and append to a log file](how-to-open-and-append-to-a-log-file.md) diff --git a/docs/standard/io/index.md b/docs/standard/io/index.md index 56a053c2a958d..859ee47a1306e 100644 --- a/docs/standard/io/index.md +++ b/docs/standard/io/index.md @@ -2,7 +2,7 @@ title: "File and Stream I/O - .NET" description: Learn the basics of file and stream I/O, which is the transfer of data either to or from a storage medium, in .NET. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "IO namespace" - "files, I/O" - "System.IO namespace" @@ -93,7 +93,7 @@ See [How to: Read Text from a File](how-to-read-text-from-a-file.md), [How to: W Reading or writing a large amount of data can be resource-intensive. You should perform these tasks asynchronously if your application needs to remain responsive to the user. With synchronous I/O operations, the UI thread is blocked until the resource-intensive operation has completed. Use asynchronous I/O operations when developing Windows 8.x Store apps to prevent creating the impression that your app has stopped working. -The asynchronous members contain `Async` in their names, such as the , , , and methods. You use these methods with the `async` and `await` keywords. +The asynchronous members contain `Async` in their names, such as the , , , and methods. You use these methods with the `async` and `await` keywords. For more information, see [Asynchronous File I/O](asynchronous-file-i-o.md). @@ -143,7 +143,7 @@ Some important differences to note when using I/O operations in Windows 8.x Stor - Isolated storage is not available; instead, use [application data](/previous-versions/windows/apps/hh464917(v=win.10)). -- Use asynchronous methods, such as and , to prevent blocking the UI thread. +- Use asynchronous methods, such as and , to prevent blocking the UI thread. - The path-based compression types and are not available. Instead, use the types in the namespace. diff --git a/docs/standard/io/isolated-storage.md b/docs/standard/io/isolated-storage.md index 490e381bd3a09..f8ecd9d948168 100644 --- a/docs/standard/io/isolated-storage.md +++ b/docs/standard/io/isolated-storage.md @@ -233,8 +233,8 @@ Many applications use a database to store and isolate data, in which case one or |-----------|-----------------| |[Types of Isolation](types-of-isolation.md)|Describes the different types of isolation.| |[How to: Obtain Stores for Isolated Storage](how-to-obtain-stores-for-isolated-storage.md)|Provides an example of using the class to obtain a store isolated by user and assembly.| -|[How to: Enumerate Stores for Isolated Storage](how-to-enumerate-stores-for-isolated-storage.md)|Shows how to use the method to calculate the size of all isolated storage for the user.| -|[How to: Delete Stores in Isolated Storage](how-to-delete-stores-in-isolated-storage.md)|Shows how to use the method in two different ways to delete isolated stores.| +|[How to: Enumerate Stores for Isolated Storage](how-to-enumerate-stores-for-isolated-storage.md)|Shows how to use the method to calculate the size of all isolated storage for the user.| +|[How to: Delete Stores in Isolated Storage](how-to-delete-stores-in-isolated-storage.md)|Shows how to use the method in two different ways to delete isolated stores.| |[How to: Anticipate Out-of-Space Conditions with Isolated Storage](how-to-anticipate-out-of-space-conditions-with-isolated-storage.md)|Shows how to measure the remaining space in an isolated store.| |[How to: Create Files and Directories in Isolated Storage](how-to-create-files-and-directories-in-isolated-storage.md)|Provides some examples of creating files and directories in an isolated store.| |[How to: Find Existing Files and Directories in Isolated Storage](how-to-find-existing-files-and-directories-in-isolated-storage.md)|Demonstrates how to read the directory structure and files in isolated storage.| diff --git a/docs/standard/io/memory-mapped-files.md b/docs/standard/io/memory-mapped-files.md index e909aa06b90fd..57b90dbbe65cf 100644 --- a/docs/standard/io/memory-mapped-files.md +++ b/docs/standard/io/memory-mapped-files.md @@ -2,147 +2,147 @@ title: "Memory-Mapped Files" description: Explore memory-mapped files in .NET, which contain file contents in virtual memory, and allow applications to modify the file by writing directly to the memory. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "memory-mapped files" - "inter-process communication" ms.assetid: a483d1b5-64aa-45b6-86ef-11b859f7f02e --- # Memory-mapped files -A memory-mapped file contains the contents of a file in virtual memory. This mapping between a file and memory space enables an application, including multiple processes, to modify the file by reading and writing directly to the memory. You can use managed code to access memory-mapped files in the same way that native Windows functions access memory-mapped files, as described in [Managing Memory-Mapped Files](/previous-versions/ms810613(v=msdn.10)). - -There are two types of memory-mapped files: - -- Persisted memory-mapped files - - Persisted files are memory-mapped files that are associated with a source file on a disk. When the last process has finished working with the file, the data is saved to the source file on the disk. These memory-mapped files are suitable for working with extremely large source files. - -- Non-persisted memory-mapped files - - Non-persisted files are memory-mapped files that are not associated with a file on a disk. When the last process has finished working with the file, the data is lost and the file is reclaimed by garbage collection. These files are suitable for creating shared memory for inter-process communications (IPC). - -## Processes, Views, and Managing Memory - - Memory-mapped files can be shared across multiple processes. Processes can map to the same memory-mapped file by using a common name that is assigned by the process that created the file. - - To work with a memory-mapped file, you must create a view of the entire memory-mapped file or a part of it. You can also create multiple views to the same part of the memory-mapped file, thereby creating concurrent memory. For two views to remain concurrent, they have to be created from the same memory-mapped file. - - Multiple views may also be necessary if the file is greater than the size of the application's logical memory space available for memory mapping (2 GB on a 32-bit computer). - - There are two types of views: stream access view and random access view. Use stream access views for sequential access to a file; this is recommended for non-persisted files and IPC. Random access views are preferred for working with persisted files. - - Memory-mapped files are accessed through the operating system's memory manager, so the file is automatically partitioned into a number of pages and accessed as needed. You do not have to handle the memory management yourself. - +A memory-mapped file contains the contents of a file in virtual memory. This mapping between a file and memory space enables an application, including multiple processes, to modify the file by reading and writing directly to the memory. You can use managed code to access memory-mapped files in the same way that native Windows functions access memory-mapped files, as described in [Managing Memory-Mapped Files](/previous-versions/ms810613(v=msdn.10)). + +There are two types of memory-mapped files: + +- Persisted memory-mapped files + + Persisted files are memory-mapped files that are associated with a source file on a disk. When the last process has finished working with the file, the data is saved to the source file on the disk. These memory-mapped files are suitable for working with extremely large source files. + +- Non-persisted memory-mapped files + + Non-persisted files are memory-mapped files that are not associated with a file on a disk. When the last process has finished working with the file, the data is lost and the file is reclaimed by garbage collection. These files are suitable for creating shared memory for inter-process communications (IPC). + +## Processes, Views, and Managing Memory + + Memory-mapped files can be shared across multiple processes. Processes can map to the same memory-mapped file by using a common name that is assigned by the process that created the file. + + To work with a memory-mapped file, you must create a view of the entire memory-mapped file or a part of it. You can also create multiple views to the same part of the memory-mapped file, thereby creating concurrent memory. For two views to remain concurrent, they have to be created from the same memory-mapped file. + + Multiple views may also be necessary if the file is greater than the size of the application's logical memory space available for memory mapping (2 GB on a 32-bit computer). + + There are two types of views: stream access view and random access view. Use stream access views for sequential access to a file; this is recommended for non-persisted files and IPC. Random access views are preferred for working with persisted files. + + Memory-mapped files are accessed through the operating system's memory manager, so the file is automatically partitioned into a number of pages and accessed as needed. You do not have to handle the memory management yourself. + The following illustration shows how multiple processes can have multiple and overlapping views to the same memory-mapped file at the same time. - The following image shows multiple and overlapped views to a memory-mapped file: - - ![Screenshot that shows views to a memory-mapped file.](./media/memory-mapped-files/memory-map-persist-file.png) - -## Programming with Memory-Mapped Files - - The following table provides a guide for using memory-mapped file objects and their members. - -|Task|Methods or properties to use| -|----------|----------------------------------| -|To obtain a object that represents a persisted memory-mapped file from a file on disk.| method.| -|To obtain a object that represents a non-persisted memory-mapped file (not associated with a file on disk).| method.

- or -

method.| -|To obtain a object of an existing memory-mapped file (either persisted or non-persisted).| method.| -|To obtain a object for a sequentially accessed view to the memory-mapped file.| method.| -|To obtain a object for a random access view to a memory-mapped file.| method.| -|To obtain a object to use with unmanaged code.| property.

- or -

property.

- or -

property.| -|To delay allocating memory until a view is created (non-persisted files only).

(To determine the current system page size, use the property.)| method with the value.

- or -

methods that have a enumeration as a parameter.| - -### Security - - You can apply access rights when you create a memory-mapped file, by using the following methods that take a enumeration as a parameter: - -- - -- - -- - - You can specify access rights for opening an existing memory-mapped file by using the methods that take an as a parameter. - - In addition, you can include a object that contains predefined access rules. - - To apply new or changed access rules to a memory-mapped file, use the method. To retrieve access or audit rules from an existing file, use the method. - -## Examples - -### Persisted Memory-Mapped Files - - The methods create a memory-mapped file from an existing file on disk. - - The following example creates a memory-mapped view of a part of an extremely large file and manipulates a portion of it. - + The following image shows multiple and overlapped views to a memory-mapped file: + + ![Screenshot that shows views to a memory-mapped file.](./media/memory-mapped-files/memory-map-persist-file.png) + +## Programming with Memory-Mapped Files + + The following table provides a guide for using memory-mapped file objects and their members. + +|Task|Methods or properties to use| +|----------|----------------------------------| +|To obtain a object that represents a persisted memory-mapped file from a file on disk.| method.| +|To obtain a object that represents a non-persisted memory-mapped file (not associated with a file on disk).| method.

- or -

method.| +|To obtain a object of an existing memory-mapped file (either persisted or non-persisted).| method.| +|To obtain a object for a sequentially accessed view to the memory-mapped file.| method.| +|To obtain a object for a random access view to a memory-mapped file.| method.| +|To obtain a object to use with unmanaged code.| property.

- or -

property.

- or -

property.| +|To delay allocating memory until a view is created (non-persisted files only).

(To determine the current system page size, use the property.)| method with the value.

- or -

methods that have a enumeration as a parameter.| + +### Security + + You can apply access rights when you create a memory-mapped file, by using the following methods that take a enumeration as a parameter: + +- + +- + +- + + You can specify access rights for opening an existing memory-mapped file by using the methods that take an as a parameter. + + In addition, you can include a object that contains predefined access rules. + + To apply new or changed access rules to a memory-mapped file, use the method. To retrieve access or audit rules from an existing file, use the method. + +## Examples + +### Persisted Memory-Mapped Files + + The methods create a memory-mapped file from an existing file on disk. + + The following example creates a memory-mapped view of a part of an extremely large file and manipulates a portion of it. + [!code-csharp[MemoryMappedFiles.MemoryMappedFile.CreateFromFile#1](../../../samples/snippets/csharp/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.createfromfile/cs/program.cs#1)] - [!code-vb[MemoryMappedFiles.MemoryMappedFile.CreateFromFile#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.createfromfile/vb/program.vb#1)] - - The following example opens the same memory-mapped file for another process. - + [!code-vb[MemoryMappedFiles.MemoryMappedFile.CreateFromFile#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.createfromfile/vb/program.vb#1)] + + The following example opens the same memory-mapped file for another process. + [!code-csharp[MemoryMappedFiles.MemoryMappedFile.OpenExisting#1](../../../samples/snippets/csharp/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.openexisting/cs/program.cs#1)] - [!code-vb[MemoryMappedFiles.MemoryMappedFile.OpenExisting#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.openexisting/vb/program.vb#1)] - -### Non-Persisted Memory-Mapped Files - - The and methods create a memory-mapped file that is not mapped to an existing file on disk. - - The following example consists of three separate processes (console applications) that write Boolean values to a memory-mapped file. The following sequence of actions occur: - -1. `Process A` creates the memory-mapped file and writes a value to it. - -2. `Process B` opens the memory-mapped file and writes a value to it. - -3. `Process C` opens the memory-mapped file and writes a value to it. - -4. `Process A` reads and displays the values from the memory-mapped file. - -5. After `Process A` is finished with the memory-mapped file, the file is immediately reclaimed by garbage collection. - - To run this example, do the following: - -1. Compile the applications and open three Command Prompt windows. - -2. In the first Command Prompt window, run `Process A`. - -3. In the second Command Prompt window, run `Process B`. - -4. Return to `Process A` and press ENTER. - -5. In the third Command Prompt window, run `Process C`. - -6. Return to `Process A` and press ENTER. - - The output of `Process A` is as follows: - -```console -Start Process B and press ENTER to continue. -Start Process C and press ENTER to continue. -Process A says: True -Process B says: False -Process C says: True -``` - - **Process A** - + [!code-vb[MemoryMappedFiles.MemoryMappedFile.OpenExisting#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.openexisting/vb/program.vb#1)] + +### Non-Persisted Memory-Mapped Files + + The and methods create a memory-mapped file that is not mapped to an existing file on disk. + + The following example consists of three separate processes (console applications) that write Boolean values to a memory-mapped file. The following sequence of actions occur: + +1. `Process A` creates the memory-mapped file and writes a value to it. + +2. `Process B` opens the memory-mapped file and writes a value to it. + +3. `Process C` opens the memory-mapped file and writes a value to it. + +4. `Process A` reads and displays the values from the memory-mapped file. + +5. After `Process A` is finished with the memory-mapped file, the file is immediately reclaimed by garbage collection. + + To run this example, do the following: + +1. Compile the applications and open three Command Prompt windows. + +2. In the first Command Prompt window, run `Process A`. + +3. In the second Command Prompt window, run `Process B`. + +4. Return to `Process A` and press ENTER. + +5. In the third Command Prompt window, run `Process C`. + +6. Return to `Process A` and press ENTER. + + The output of `Process A` is as follows: + +```console +Start Process B and press ENTER to continue. +Start Process C and press ENTER to continue. +Process A says: True +Process B says: False +Process C says: True +``` + + **Process A** + [!code-csharp[System.IO.MemoryMappedFiles_IPC_X#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_x/cs/program.cs#1)] - [!code-vb[System.IO.MemoryMappedFiles_IPC_X#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_x/vb/program.vb#1)] - - **Process B** - + [!code-vb[System.IO.MemoryMappedFiles_IPC_X#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_x/vb/program.vb#1)] + + **Process B** + [!code-csharp[System.IO.MemoryMappedFiles_IPC_A#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_a/cs/program.cs#1)] - [!code-vb[System.IO.MemoryMappedFiles_IPC_A#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_a/vb/program.vb#1)] - - **Process C** - + [!code-vb[System.IO.MemoryMappedFiles_IPC_A#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_a/vb/program.vb#1)] + + **Process C** + [!code-csharp[System.IO.MemoryMappedFiles_IPC_B#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_b/cs/program.cs#1)] - [!code-vb[System.IO.MemoryMappedFiles_IPC_B#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_b/vb/program.vb#1)] - + [!code-vb[System.IO.MemoryMappedFiles_IPC_B#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_b/vb/program.vb#1)] + ## See also - [File and Stream I/O](index.md) diff --git a/docs/standard/io/pipelines.md b/docs/standard/io/pipelines.md index 26ee520ba4804..3993f48fa4537 100644 --- a/docs/standard/io/pipelines.md +++ b/docs/standard/io/pipelines.md @@ -87,7 +87,7 @@ In the first loop: * is called to get memory from the underlying writer. * is called to tell the `PipeWriter` how much data was written to the buffer. -* is called to make the data available to the `PipeReader`. +* is called to make the data available to the `PipeReader`. In the second loop, the `PipeReader` consumes the buffers written by `PipeWriter`. The buffers come from the socket. The call to `PipeReader.ReadAsync`: @@ -119,12 +119,12 @@ For optimal performance, there's a balance between frequent pauses and allocatin To solve the preceding problem, the `Pipe` has two settings to control the flow of data: -* : Determines how much data should be buffered before calls to pause. +* : Determines how much data should be buffered before calls to pause. * : Determines how much data the reader has to observe before calls to `PipeWriter.FlushAsync` resume. ![Diagram with ResumeWriterThreshold and PauseWriterThreshold](media/pipelines/resume-pause.png) -: +: * Returns an incomplete `ValueTask` when the amount of data in the `Pipe` crosses `PauseWriterThreshold`. * Completes `ValueTask` when it becomes lower than `ResumeWriterThreshold`. @@ -155,11 +155,11 @@ When doing I/O, it's important to have fine-grained control over where the I/O i ### Pipe reset -It's frequently efficient to reuse the `Pipe` object. To reset the pipe, call when both the `PipeReader` and `PipeWriter` are complete. +It's frequently efficient to reuse the `Pipe` object. To reset the pipe, call when both the `PipeReader` and `PipeWriter` are complete. ## PipeReader - manages memory on the caller's behalf. **Always** call after calling . This lets the `PipeReader` know when the caller is done with the memory so that it can be tracked. The `ReadOnlySequence` returned from `PipeReader.ReadAsync` is only valid until the call the `PipeReader.AdvanceTo`. It's illegal to use `ReadOnlySequence` after calling `PipeReader.AdvanceTo`. + manages memory on the caller's behalf. **Always** call after calling . This lets the `PipeReader` know when the caller is done with the memory so that it can be tracked. The `ReadOnlySequence` returned from `PipeReader.ReadAsync` is only valid until the call the `PipeReader.AdvanceTo`. It's illegal to use `ReadOnlySequence` after calling `PipeReader.AdvanceTo`. `PipeReader.AdvanceTo` takes two arguments: @@ -211,7 +211,7 @@ The following code reads all messages from a `PipeReader` and calls `ProcessMess * Supports passing a . * Throws an if the `CancellationToken` is canceled while there's a read pending. -* Supports a way to cancel the current read operation via , which avoids raising an exception. Calling `PipeReader.CancelPendingRead` causes the current or next call to `PipeReader.ReadAsync` to return a with `IsCanceled` set to `true`. This can be useful for halting the existing read loop in a non-destructive and non-exceptional way. +* Supports a way to cancel the current read operation via , which avoids raising an exception. Calling `PipeReader.CancelPendingRead` causes the current or next call to `PipeReader.ReadAsync` to return a with `IsCanceled` set to `true`. This can be useful for halting the existing read loop in a non-destructive and non-exceptional way. :::code language="csharp" source="snippets/pipelines_1/MyConnection.cs" id="snippet"::: @@ -301,35 +301,35 @@ When writing helpers that read the buffer, any returned payload should be copied ## PipeWriter -The manages buffers for writing on the caller's behalf. `PipeWriter` implements [`IBufferWriter`](xref:System.Buffers.IBufferWriter%601). `IBufferWriter` makes it possible to get access to buffers to perform writes without extra buffer copies. +The manages buffers for writing on the caller's behalf. `PipeWriter` implements [`IBufferWriter`](xref:System.Buffers.IBufferWriter`1). `IBufferWriter` makes it possible to get access to buffers to perform writes without extra buffer copies. :::code language="csharp" source="snippets/pipelines_1/MyPipeWriter.cs" id="snippet"::: The previous code: -* Requests a buffer of at least 5 bytes from the `PipeWriter` using . +* Requests a buffer of at least 5 bytes from the `PipeWriter` using . * Writes bytes for the ASCII string `"Hello"` to the returned `Memory`. -* Calls to indicate how many bytes were written to the buffer. +* Calls to indicate how many bytes were written to the buffer. * Flushes the `PipeWriter`, which sends the bytes to the underlying device. -The previous method of writing uses the buffers provided by the `PipeWriter`. It could also have used , which: +The previous method of writing uses the buffers provided by the `PipeWriter`. It could also have used , which: * Copies the existing buffer to the `PipeWriter`. -* Calls `GetSpan`, `Advance` as appropriate and calls . +* Calls `GetSpan`, `Advance` as appropriate and calls . :::code language="csharp" source="snippets/pipelines_1/MyPipeWriter.cs" id="snippet2"::: ### Cancellation - supports passing a . Passing a `CancellationToken` results in an `OperationCanceledException` if the token is canceled while there's a flush pending. `PipeWriter.FlushAsync` supports a way to cancel the current flush operation via without raising an exception. Calling `PipeWriter.CancelPendingFlush` causes the current or next call to `PipeWriter.FlushAsync` or `PipeWriter.WriteAsync` to return a with `IsCanceled` set to `true`. This can be useful for halting the yielding flush in a non-destructive and non-exceptional way. + supports passing a . Passing a `CancellationToken` results in an `OperationCanceledException` if the token is canceled while there's a flush pending. `PipeWriter.FlushAsync` supports a way to cancel the current flush operation via without raising an exception. Calling `PipeWriter.CancelPendingFlush` causes the current or next call to `PipeWriter.FlushAsync` or `PipeWriter.WriteAsync` to return a with `IsCanceled` set to `true`. This can be useful for halting the yielding flush in a non-destructive and non-exceptional way. ### PipeWriter common problems -* and return a buffer with at least the requested amount of memory. **Don't** assume exact buffer sizes. +* and return a buffer with at least the requested amount of memory. **Don't** assume exact buffer sizes. * There's no guarantee that successive calls will return the same buffer or the same-sized buffer. -* A new buffer must be requested after calling to continue writing more data. The previously acquired buffer can't be written to. +* A new buffer must be requested after calling to continue writing more data. The previously acquired buffer can't be written to. * Calling `GetMemory` or `GetSpan` while there's an incomplete call to `FlushAsync` isn't safe. * Calling `Complete` or `CompleteAsync` while there's unflushed data can result in memory corruption. @@ -337,13 +337,13 @@ The previous method of writing uses the buffers provided by the `PipeWriter`. It The following tips will help you use the classes successfully: -* Always complete the [PipeReader](xref:System.IO.Pipelines.PipeReader.Complete%2A?displayProperty=nameWithType) and [PipeWriter](xref:System.IO.Pipelines.PipeWriter.Complete%2A?displayProperty=nameWithType), including an exception where applicable. -* Always call after calling . -* Periodically `await` while writing, and always check . Abort writing if `IsCompleted` is `true`, as that indicates the reader is completed and no longer cares about what is written. -* Do call after writing something that you want the `PipeReader` to have access to. +* Always complete the [PipeReader](xref:System.IO.Pipelines.PipeReader.Complete*?displayProperty=nameWithType) and [PipeWriter](xref:System.IO.Pipelines.PipeWriter.Complete*?displayProperty=nameWithType), including an exception where applicable. +* Always call after calling . +* Periodically `await` while writing, and always check . Abort writing if `IsCompleted` is `true`, as that indicates the reader is completed and no longer cares about what is written. +* Do call after writing something that you want the `PipeReader` to have access to. * Do not call `FlushAsync` if the reader can't start until `FlushAsync` finishes, as that may cause a deadlock. * Ensure that only one context "owns" a `PipeReader` or `PipeWriter` or accesses them. These types are not thread-safe. -* Never access a after calling `AdvanceTo` or completing the `PipeReader`. +* Never access a after calling `AdvanceTo` or completing the `PipeReader`. ## IDuplexPipe @@ -353,7 +353,7 @@ The is a contract for types that support ## Streams -When reading or writing stream data, you typically read data using a de-serializer and write data using a serializer. Most of these read and write stream APIs have a `Stream` parameter. To make it easier to integrate with these existing APIs, `PipeReader` and `PipeWriter` expose an method. returns a `Stream` implementation around the `PipeReader` or `PipeWriter`. +When reading or writing stream data, you typically read data using a de-serializer and write data using a serializer. Most of these read and write stream APIs have a `Stream` parameter. To make it easier to integrate with these existing APIs, `PipeReader` and `PipeWriter` expose an method. returns a `Stream` implementation around the `PipeReader` or `PipeWriter`. ### Stream example @@ -379,4 +379,4 @@ The following code demonstrates the creation of `PipeReader` and `PipeWriter` in :::code language="csharp" source="snippets/pipelines_2/Program.cs"::: -The application uses a to read the *lorem-ipsum.txt* file as a stream, and it must end with a blank line. The is passed to , which instantiates a `PipeReader` object. The console application then passes its standard output stream to using . The example supports [cancellation](#cancellation). +The application uses a to read the *lorem-ipsum.txt* file as a stream, and it must end with a blank line. The is passed to , which instantiates a `PipeReader` object. The console application then passes its standard output stream to using . The example supports [cancellation](#cancellation). diff --git a/docs/standard/io/types-of-isolation.md b/docs/standard/io/types-of-isolation.md index 639f01b668515..93fea3adf5323 100644 --- a/docs/standard/io/types-of-isolation.md +++ b/docs/standard/io/types-of-isolation.md @@ -50,7 +50,7 @@ Access to isolated storage is always restricted to the user who created it. To i ## Isolation by User and Assembly - When the assembly that uses the data store needs to be accessible from any application's domain, isolation by user and assembly is appropriate. Typically, in this situation, isolated storage is used to store data that applies across multiple applications and is not tied to any particular application, such as the user's name or license information. To access storage isolated by user and assembly, code must be trusted to transfer information between applications. Typically, isolation by user and assembly is allowed on intranets but not on the Internet. Calling the static method and passing in a user and an assembly returns storage with this kind of isolation. + When the assembly that uses the data store needs to be accessible from any application's domain, isolation by user and assembly is appropriate. Typically, in this situation, isolated storage is used to store data that applies across multiple applications and is not tied to any particular application, such as the user's name or license information. To access storage isolated by user and assembly, code must be trusted to transfer information between applications. Typically, isolation by user and assembly is allowed on intranets but not on the Internet. Calling the static method and passing in a user and an assembly returns storage with this kind of isolation. The following code example retrieves a store that is isolated by user and assembly. The store can be accessed through the `isoFile` object. [!code-csharp[Conceptual.IsolatedStorage#17](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.isolatedstorage/cs/source11.cs#17)] @@ -58,7 +58,7 @@ Access to isolated storage is always restricted to the user who created it. To i For an example that uses the evidence parameters, see . - The method is available as a shortcut, as shown in the following code example. This shortcut cannot be used to open stores that are capable of roaming; use in such cases. + The method is available as a shortcut, as shown in the following code example. This shortcut cannot be used to open stores that are capable of roaming; use in such cases. [!code-csharp[Conceptual.IsolatedStorage#18](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.isolatedstorage/cs/source11.cs#18)] [!code-vb[Conceptual.IsolatedStorage#18](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source11.vb#18)] @@ -66,13 +66,13 @@ Access to isolated storage is always restricted to the user who created it. To i ## Isolation by User, Domain, and Assembly - If your application uses a third-party assembly that requires a private data store, you can use isolated storage to store the private data. Isolation by user, domain, and assembly ensures that only code in a given assembly can access the data, and only when the assembly is used by the application that was running when the assembly created the store, and only when the user for whom the store was created runs the application. Isolation by user, domain, and assembly keeps the third-party assembly from leaking data to other applications. This isolation type should be your default choice if you know that you want to use isolated storage but are not sure which type of isolation to use. Calling the static method of and passing in a user, domain, and assembly returns storage with this kind of isolation. + If your application uses a third-party assembly that requires a private data store, you can use isolated storage to store the private data. Isolation by user, domain, and assembly ensures that only code in a given assembly can access the data, and only when the assembly is used by the application that was running when the assembly created the store, and only when the user for whom the store was created runs the application. Isolation by user, domain, and assembly keeps the third-party assembly from leaking data to other applications. This isolation type should be your default choice if you know that you want to use isolated storage but are not sure which type of isolation to use. Calling the static method of and passing in a user, domain, and assembly returns storage with this kind of isolation. The following code example retrieves a store isolated by user, domain, and assembly. The store can be accessed through the `isoFile` object. [!code-csharp[Conceptual.IsolatedStorage#14](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.isolatedstorage/cs/source10.cs#14)] [!code-vb[Conceptual.IsolatedStorage#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source10.vb#14)] - Another method is available as a shortcut, as shown in the following code example. This shortcut cannot be used to open stores that are capable of roaming; use in such cases. + Another method is available as a shortcut, as shown in the following code example. This shortcut cannot be used to open stores that are capable of roaming; use in such cases. [!code-csharp[Conceptual.IsolatedStorage#15](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.isolatedstorage/cs/source10.cs#15)] [!code-vb[Conceptual.IsolatedStorage#15](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source10.vb#15)] diff --git a/docs/standard/language-independence.md b/docs/standard/language-independence.md index 0f9de0d3e2769..c9967d7199e22 100644 --- a/docs/standard/language-independence.md +++ b/docs/standard/language-independence.md @@ -297,7 +297,7 @@ CLS-compliant enumerations must follow these rules: For more information, see the documentation for the structure. -- The value of an enumeration is not limited to the range of its specified values. In other words, the range of values in an enumeration is the range of its underlying value. You can use the method to determine whether a specified value is a member of an enumeration. +- The value of an enumeration is not limited to the range of its specified values. In other words, the range of values in an enumeration is the range of its underlying value. You can use the method to determine whether a specified value is a member of an enumeration. ### Type members in general @@ -363,7 +363,7 @@ Constructors in CLS-compliant classes and structures must follow these rules: [!code-csharp[Conceptual.CLSCompliant#11](../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.clscompliant/cs/ctor1.cs#11)] [!code-vb[Conceptual.CLSCompliant#11](../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.clscompliant/vb/ctor1.vb#11)] -* An object constructor cannot be called except to create an object. In addition, an object cannot be initialized twice. For example, this means that and deserialization methods must not call constructors. +* An object constructor cannot be called except to create an object. In addition, an object cannot be initialized twice. For example, this means that and deserialization methods must not call constructors. ### Properties diff --git a/docs/standard/linq/add-elements-attributes-nodes-xml-tree.md b/docs/standard/linq/add-elements-attributes-nodes-xml-tree.md index 4ec4cd12a280d..fbcf5a1961af4 100644 --- a/docs/standard/linq/add-elements-attributes-nodes-xml-tree.md +++ b/docs/standard/linq/add-elements-attributes-nodes-xml-tree.md @@ -18,15 +18,15 @@ The following methods add child content to an or |Method|Description| |------------|-----------------| -||Adds content at the end of the child content of the .| -||Adds content at the beginning of the child content of the .| +||Adds content at the end of the child content of the .| +||Adds content at the beginning of the child content of the .| The following methods add content as sibling nodes of an . The most common node to which you add sibling content is , although you can add valid sibling content to other types of nodes such as or . |Method|Description| |------------|-----------------| -||Adds content after the .| -||Adds content before the .| +||Adds content after the .| +||Adds content before the .| ## Example: Create two XML trees and modify one of them diff --git a/docs/standard/linq/atomized-xname-xnamespace-objects.md b/docs/standard/linq/atomized-xname-xnamespace-objects.md index eb1e46874eebb..508ccd1e6a9d0 100644 --- a/docs/standard/linq/atomized-xname-xnamespace-objects.md +++ b/docs/standard/linq/atomized-xname-xnamespace-objects.md @@ -69,7 +69,7 @@ The name of r1 and the name in 'n' refer to the same instance. As mentioned earlier, the benefit of atomized objects is that when you use one of the axis methods that take an as a parameter, the axis method only has to determine that two names reference the same instance to select the desired elements. -The following example passes an to the method call, which then has better performance because of the atomization pattern. +The following example passes an to the method call, which then has better performance because of the atomization pattern. ```csharp var root = new XElement("Root", diff --git a/docs/standard/linq/basic-queries-linq-to-xml.md b/docs/standard/linq/basic-queries-linq-to-xml.md index 4cce46bf11c7c..7439c823d100a 100644 --- a/docs/standard/linq/basic-queries-linq-to-xml.md +++ b/docs/standard/linq/basic-queries-linq-to-xml.md @@ -10,22 +10,22 @@ This section provides examples of basic LINQ to XML queries. ## In this section -|Topic|Description| -|-----------|-----------------| +|Topic|Description| +|-----------|-----------------| |[How to find an element with a specific attribute (C#)](find-element-specific-attribute.md)|Shows how to find a particular element that has an attribute that has a specific value.| |[How to find an element with a specific child element (C#)](find-element-specific-child-element.md)|Shows how to find a particular element that has a child element that has a specific value.| -|[Querying an XDocument vs. Querying an XElement (C#)](query-xdocument-vs-query-xelement.md)|Explains the differences between writing queries on an XML tree that is rooted in and writing queries on an XML tree that is rooted in .| -|[How to find descendants with a specific element name (C#)](find-descendants-specific-element-name.md)|Shows how to find all the descendants of an element that have a specific name. This example uses the axis.| -|[How to find a single descendant using the descendants method (C#)](find-single-descendant-descendants-method.md)|Shows how to use the axis method to find a single uniquely named element.| -|[How to write queries with complex filtering (C#)](write-queries-complex-filtering.md)|Shows how to write a query with a more complex filter.| +|[Querying an XDocument vs. Querying an XElement (C#)](query-xdocument-vs-query-xelement.md)|Explains the differences between writing queries on an XML tree that is rooted in and writing queries on an XML tree that is rooted in .| +|[How to find descendants with a specific element name (C#)](find-descendants-specific-element-name.md)|Shows how to find all the descendants of an element that have a specific name. This example uses the axis.| +|[How to find a single descendant using the descendants method (C#)](find-single-descendant-descendants-method.md)|Shows how to use the axis method to find a single uniquely named element.| +|[How to write queries with complex filtering (C#)](write-queries-complex-filtering.md)|Shows how to write a query with a more complex filter.| |[How to filter on an optional element (C#)](filter-optional-element.md)|Shows how to find nodes in an irregularly shaped tree.| |[How to find all nodes in a namespace (C#)](find-all-nodes-namespace.md)|Shows how to find all nodes that are in a specific namespace.| -|[How to sort elements (C#)](sort-elements.md)|Shows how to write a query that sorts its results.| -|[How to sort elements on multiple keys (C#)](sort-elements-multiple-keys.md)|Shows how to sort on multiple keys.| -|[How to calculate intermediate values (C#)](calculate-intermediate-values.md)|Shows how to use the `Let` clause to calculate intermediate values in a LINQ to XML query.| -|[How to write a query that finds elements based on context (C#)](write-query-finds-elements-based-context.md)|Shows how to select elements based on other elements in the tree.| -|[How to debug empty query results sets (C#)](debug-empty-query-results-sets.md)|Shows the appropriate fix when debugging queries on XML that is in a default namespace.| - +|[How to sort elements (C#)](sort-elements.md)|Shows how to write a query that sorts its results.| +|[How to sort elements on multiple keys (C#)](sort-elements-multiple-keys.md)|Shows how to sort on multiple keys.| +|[How to calculate intermediate values (C#)](calculate-intermediate-values.md)|Shows how to use the `Let` clause to calculate intermediate values in a LINQ to XML query.| +|[How to write a query that finds elements based on context (C#)](write-query-finds-elements-based-context.md)|Shows how to select elements based on other elements in the tree.| +|[How to debug empty query results sets (C#)](debug-empty-query-results-sets.md)|Shows the appropriate fix when debugging queries on XML that is in a default namespace.| + ## See also - [Querying XML Trees](find-element-specific-attribute.md) diff --git a/docs/standard/linq/catch-parsing-errors.md b/docs/standard/linq/catch-parsing-errors.md index 3b5152b3dfa5e..8df7845c3a968 100644 --- a/docs/standard/linq/catch-parsing-errors.md +++ b/docs/standard/linq/catch-parsing-errors.md @@ -12,7 +12,7 @@ ms.topic: how-to This article shows how to detect badly formed or invalid XML in C# or Visual Basic. -LINQ to XML is implemented using . If badly formed or invalid XML is passed to LINQ to XML, the underlying class will throw an exception. The various methods that parse XML, such as , don't catch the exception; the exception can then be caught by your application. +LINQ to XML is implemented using . If badly formed or invalid XML is passed to LINQ to XML, the underlying class will throw an exception. The various methods that parse XML, such as , don't catch the exception; the exception can then be caught by your application. ## Example: Parse invalid XML @@ -55,7 +55,7 @@ Because of the invalid end tag ``, the example throws the following ex The 'Contacts' start tag on line 1 doesn't match the end tag of 'Contcts'. Line 5, position 13. ``` -For information about the exceptions that the , , , and methods throw, see the documentation. +For information about the exceptions that the , , , and methods throw, see the documentation. ## See also diff --git a/docs/standard/linq/chain-axis-method-calls.md b/docs/standard/linq/chain-axis-method-calls.md index d067258ec9842..26981b3780a70 100644 --- a/docs/standard/linq/chain-axis-method-calls.md +++ b/docs/standard/linq/chain-axis-method-calls.md @@ -12,11 +12,11 @@ ms.topic: how-to A common pattern that you will use in your code is to call an axis method, then call one of the extension method axes. -There are two axes with the name of `Elements` that return a collection of elements: the method and the method. You can combine these two axes to find all elements of a specified name at a given depth in the tree. +There are two axes with the name of `Elements` that return a collection of elements: the method and the method. You can combine these two axes to find all elements of a specified name at a given depth in the tree. ## Example: Retrieve all name elements -This example uses and to retrieve all `Name` elements in all `Address` elements in all `PurchaseOrder` elements. +This example uses and to retrieve all `Name` elements in all `Address` elements in all `PurchaseOrder` elements. This example uses XML document [Sample XML file: Multiple purchase orders](sample-xml-file-multiple-purchase-orders.md). @@ -53,7 +53,7 @@ This example produces the following output: Jessica Arnold ``` -This works because one of the implementations of the `Elements` axis is as an extension method on of . derives from , so you can call the method on the results of a call to the method. +This works because one of the implementations of the `Elements` axis is as an extension method on of . derives from , so you can call the method on the results of a call to the method. ## Example: Retrieve all elements at a particular depth @@ -81,7 +81,7 @@ Sometimes you want to retrieve all elements at a particular element depth when t ``` - To do this, you can use the axis, as follows: + To do this, you can use the axis, as follows: ```csharp XElement root = XElement.Load("Irregular.xml"); diff --git a/docs/standard/linq/chain-standard-query-operators-together.md b/docs/standard/linq/chain-standard-query-operators-together.md index 376733ff8e6ff..3fae4b97b15bb 100644 --- a/docs/standard/linq/chain-standard-query-operators-together.md +++ b/docs/standard/linq/chain-standard-query-operators-together.md @@ -9,13 +9,13 @@ ms.topic: how-to # Chain standard query operators together (C#) (LINQ to XML) -The standard query operators can be chained together. For example, you can interject the operator (invoked by the `where` clause), and it operates in a lazy fashion; that is, no intermediate results are materialized by it. +The standard query operators can be chained together. For example, you can interject the operator (invoked by the `where` clause), and it operates in a lazy fashion; that is, no intermediate results are materialized by it. ## Example: Interject a where clause -In this example, the method is called before calling `ConvertCollectionToUpperCase`. The method operates in almost exactly the same way as the lazy methods used in previous examples in this tutorial, `ConvertCollectionToUpperCase` and `AppendString`. +In this example, the method is called before calling `ConvertCollectionToUpperCase`. The method operates in almost exactly the same way as the lazy methods used in previous examples in this tutorial, `ConvertCollectionToUpperCase` and `AppendString`. -One difference is that in this case, the method iterates through its source collection, determines that the first item doesn't pass the predicate, and then gets the next item, which does pass. It then yields the second item. +One difference is that in this case, the method iterates through its source collection, determines that the first item doesn't pass the predicate, and then gets the next item, which does pass. It then yields the second item. However, the basic idea is the same: intermediate collections aren't materialized unless they have to be. diff --git a/docs/standard/linq/change-namespace-entire-xml-tree.md b/docs/standard/linq/change-namespace-entire-xml-tree.md index 659ea97cbef9b..f9ed847679a06 100644 --- a/docs/standard/linq/change-namespace-entire-xml-tree.md +++ b/docs/standard/linq/change-namespace-entire-xml-tree.md @@ -10,7 +10,7 @@ ms.topic: how-to # How to change the namespace for an entire XML tree (LINQ to XML) -You sometimes have to programmatically change the namespace for an element or an attribute. LINQ to XML makes this easy. The property can be set. The property can't be set, but you can easily copy the attributes into a , remove the existing attributes, and then add new attributes that are in the new desired namespace. +You sometimes have to programmatically change the namespace for an element or an attribute. LINQ to XML makes this easy. The property can be set. The property can't be set, but you can easily copy the attributes into a , remove the existing attributes, and then add new attributes that are in the new desired namespace. For more information, see [Namespaces overview](namespaces-overview.md). diff --git a/docs/standard/linq/comparison-xpath-linq-xml.md b/docs/standard/linq/comparison-xpath-linq-xml.md index 17ada1cf9a4a2..d18713dad5e91 100644 --- a/docs/standard/linq/comparison-xpath-linq-xml.md +++ b/docs/standard/linq/comparison-xpath-linq-xml.md @@ -26,7 +26,7 @@ The XPath 1.0 Recommendation states that a collection that's the result of evalu However, when iterating through a collection returned by a LINQ to XML XPath axis method, the nodes in the collection are returned in document order. This is the case even when accessing the XPath axes where predicates are expressed in terms of reverse document order, such as `preceding` and `preceding-sibling`. -By contrast, most of the LINQ to XML axes return collections in document order. However, two of them, and , return collections in reverse document order. The following table enumerates the axes, and indicates the collection order for each: +By contrast, most of the LINQ to XML axes return collections in document order. However, two of them, and , return collections in reverse document order. The following table enumerates the axes, and indicates the collection order for each: |LINQ to XML axis|Ordering| |----------------------|--------------| @@ -94,14 +94,14 @@ There are similar parallels for each of the XPath axes. |XPath axis|LINQ to XML axis| |----------------|----------------------| -|child (the default axis)|| -|Parent (..)|| -|attribute axis (@)|

or

| -|ancestor axis|| -|ancestor-or-self axis|| -|descendant axis (//)|

or

| -|descendant-or-self|

or

| -|following-sibling|

or

| -|preceding-sibling|

or

| +|child (the default axis)|| +|Parent (..)|| +|attribute axis (@)|

or

| +|ancestor axis|| +|ancestor-or-self axis|| +|descendant axis (//)|

or

| +|descendant-or-self|

or

| +|following-sibling|

or

| +|preceding-sibling|

or

| |following|No direct equivalent.| |preceding|No direct equivalent.| diff --git a/docs/standard/linq/concepts-terminology-functional-transformation.md b/docs/standard/linq/concepts-terminology-functional-transformation.md index 0374f110b8712..cbc7a98da7238 100644 --- a/docs/standard/linq/concepts-terminology-functional-transformation.md +++ b/docs/standard/linq/concepts-terminology-functional-transformation.md @@ -52,7 +52,7 @@ Essentially, an inline anonymous function that can be used wherever a delegate t For more information, see [Lambda expressions (C# Programming Guide)](../../csharp/language-reference/operators/lambda-expressions.md) and [Lambda Expressions (Visual Basic))](../../visual-basic/programming-guide/language-features/procedures/lambda-expressions.md). collection \ -A structured set of data, usually of a uniform type. To be compatible with LINQ, a collection must implement the interface or the interface (or one of their generic counterparts, or ). +A structured set of data, usually of a uniform type. To be compatible with LINQ, a collection must implement the interface or the interface (or one of their generic counterparts, or ). tuple (anonymous types) \ A mathematical concept, a tuple is a finite sequence of objects, each of a specific type. A tuple is also known as an ordered list. Anonymous types are a language implementation of this concept, which enable an unnamed class type to be declared and an object of that type to be instantiated at the same time. diff --git a/docs/standard/linq/control-namespace-prefixes.md b/docs/standard/linq/control-namespace-prefixes.md index 7cf96dc9fc112..401647dcaad52 100644 --- a/docs/standard/linq/control-namespace-prefixes.md +++ b/docs/standard/linq/control-namespace-prefixes.md @@ -18,7 +18,7 @@ Another reason is that you want users to edit the XML document manually, and you To control namespace prefixes, you insert attributes that declare namespaces. If you declare the namespaces with specific prefixes, LINQ to XML will attempt to honor the namespace prefixes when serializing. -To create an attribute that declares a namespace with a prefix, you create an attribute where the namespace of the name of the attribute is , and the name of the attribute is the namespace prefix. The value of the attribute is the URI of the namespace. +To create an attribute that declares a namespace with a prefix, you create an attribute where the namespace of the name of the attribute is , and the name of the attribute is the namespace prefix. The value of the attribute is the URI of the namespace. ## Example: Create two namespaces that have prefixes diff --git a/docs/standard/linq/control-type-projection.md b/docs/standard/linq/control-type-projection.md index 9f2c72eb4aea1..852518ac15512 100644 --- a/docs/standard/linq/control-type-projection.md +++ b/docs/standard/linq/control-type-projection.md @@ -9,11 +9,11 @@ ms.topic: how-to --- # How to control the type of a projection (LINQ to XML) -*Projection* is the process of filtering a set of data, changing its shape and perhaps its type. Most query expressions do projections. Most of the query expressions in this section evaluate to of , but you can create collections of other types. This article shows how to do this. +*Projection* is the process of filtering a set of data, changing its shape and perhaps its type. Most query expressions do projections. Most of the query expressions in this section evaluate to of , but you can create collections of other types. This article shows how to do this. ## Example: Define a new type and create a query that creates an IEnumerable of that type -The following example defines a new type, `Customer`, and the query expression instantiates new `Customer` objects in the `Select` clause. This causes the type of the query expression to be of `Customer`. The example uses XML document [Sample XML file: Customers and orders](sample-xml-file-customers-orders.md). +The following example defines a new type, `Customer`, and the query expression instantiates new `Customer` objects in the `Select` clause. This causes the type of the query expression to be of `Customer`. The example uses XML document [Sample XML file: Customers and orders](sample-xml-file-customers-orders.md). ```csharp public class Customer @@ -131,5 +131,5 @@ LETSS:Let's Stop N Shop:Jaime Yorres ## See also -- +- - [Projections and Transformations (LINQ to XML) (Visual Basic)](./work-dictionaries-linq-xml.md) diff --git a/docs/standard/linq/create-document-namespaces-csharp.md b/docs/standard/linq/create-document-namespaces-csharp.md index e9019a4fcd8c1..b4cefbc071f2c 100644 --- a/docs/standard/linq/create-document-namespaces-csharp.md +++ b/docs/standard/linq/create-document-namespaces-csharp.md @@ -34,7 +34,7 @@ This example produces the following output: ## Example: Create a document that has a namespace and an attribute -The following example creates a document with one namespace. It also creates an attribute that declares the namespace with a namespace prefix. To create an attribute that declares a namespace with a prefix, you create an attribute where the name of the attribute is the namespace prefix, and this name is in the namespace. The value of this attribute is the URI of the namespace. +The following example creates a document with one namespace. It also creates an attribute that declares the namespace with a namespace prefix. To create an attribute that declares a namespace with a prefix, you create an attribute where the name of the attribute is the namespace prefix, and this name is in the namespace. The value of this attribute is the URI of the namespace. ```csharp // Create an XML tree in a namespace, with a specified prefix diff --git a/docs/standard/linq/debug-empty-query-results-sets.md b/docs/standard/linq/debug-empty-query-results-sets.md index 694a7c6817767..1359d5e2374f4 100644 --- a/docs/standard/linq/debug-empty-query-results-sets.md +++ b/docs/standard/linq/debug-empty-query-results-sets.md @@ -72,7 +72,7 @@ End of result set This example shows creation of XML in a namespace, and a query that's coded properly. -The solution is to declare and initialize an object, and to use it when specifying objects. In this case, the argument to the method is an object. +The solution is to declare and initialize an object, and to use it when specifying objects. In this case, the argument to the method is an object. ```csharp XElement root = XElement.Parse( diff --git a/docs/standard/linq/deferred-execution-lazy-evaluation.md b/docs/standard/linq/deferred-execution-lazy-evaluation.md index 7dba4e6d9b2c3..eb7bfc9e505ec 100644 --- a/docs/standard/linq/deferred-execution-lazy-evaluation.md +++ b/docs/standard/linq/deferred-execution-lazy-evaluation.md @@ -15,14 +15,14 @@ Deferred execution means that the evaluation of an expression is delayed until i The LINQ technologies make extensive use of deferred execution in both the members of core classes and in the extension methods in the various LINQ namespaces, such as . -Deferred execution is supported directly in the C# language by the [yield (C# Reference)](../../csharp/language-reference/statements/yield.md) keyword (in the form of the `yield-return` statement) when used within an iterator block. Such an iterator must return a collection of type or (or a derived type). +Deferred execution is supported directly in the C# language by the [yield (C# Reference)](../../csharp/language-reference/statements/yield.md) keyword (in the form of the `yield-return` statement) when used within an iterator block. Such an iterator must return a collection of type or (or a derived type). ## Eager vs. lazy evaluation When you write a method that implements deferred execution, you also have to decide whether to implement the method using lazy evaluation or eager evaluation. - In *lazy evaluation*, a single element of the source collection is processed during each call to the iterator. This is the typical way in which iterators are implemented. -- In *eager evaluation*, the first call to the iterator will result in the entire collection being processed. A temporary copy of the source collection might also be required. For example, the method has to sort the entire collection before it returns the first element. +- In *eager evaluation*, the first call to the iterator will result in the entire collection being processed. A temporary copy of the source collection might also be required. For example, the method has to sort the entire collection before it returns the first element. Lazy evaluation usually yields better performance because it distributes overhead processing evenly throughout the evaluation of the collection and minimizes the use of temporary data. Of course, for some operations, there is no other option than to materialize intermediate results. diff --git a/docs/standard/linq/filter-element-names.md b/docs/standard/linq/filter-element-names.md index f8e982641eceb..1a5243aae856f 100644 --- a/docs/standard/linq/filter-element-names.md +++ b/docs/standard/linq/filter-element-names.md @@ -10,7 +10,7 @@ ms.topic: how-to # How to filter on element names (LINQ to XML) -When you call one of the methods that return of , you can filter on the element name. +When you call one of the methods that return of , you can filter on the element name. ## Example: Retrieve descendants filtered to a specified name @@ -44,15 +44,15 @@ ProductName:Lawnmower ProductName:Baby Monitor ``` -The other methods that return of collections follow the same pattern. Their signatures are similar to and . The following is the complete list of methods that have similar method signatures: +The other methods that return of collections follow the same pattern. Their signatures are similar to and . The following is the complete list of methods that have similar method signatures: -- -- -- -- -- -- -- +- +- +- +- +- +- +- ## Example: Retrieve from XML that's in a namespace diff --git a/docs/standard/linq/filter-optional-element.md b/docs/standard/linq/filter-optional-element.md index 023fd1b24d26c..21c301d19076f 100644 --- a/docs/standard/linq/filter-optional-element.md +++ b/docs/standard/linq/filter-optional-element.md @@ -14,7 +14,7 @@ Sometimes you want to filter for an element even though you're not sure it exist ## Example: Search that doesn't trigger an exception when the target element doesn't exist -In the following example, the `Child5` element doesn't have a `Type` child element, but the query still executes correctly. The example uses the extension method. +In the following example, the `Child5` element doesn't have a `Type` child element, but the query still executes correctly. The example uses the extension method. ```csharp XElement root = XElement.Parse(@" @@ -171,9 +171,9 @@ Child Four Text ## See also -- -- -- +- +- +- - [Standard Query Operators Overview (C#)](../../csharp/linq/standard-query-operators/index.md) - [Projection Operations (C#)](../../csharp/linq/standard-query-operators/projection-operations.md) - [Basic Queries (LINQ to XML) (Visual Basic)](./find-element-specific-attribute.md) diff --git a/docs/standard/linq/find-attribute-parent.md b/docs/standard/linq/find-attribute-parent.md index 3351b5db0b022..56bb409273c04 100644 --- a/docs/standard/linq/find-attribute-parent.md +++ b/docs/standard/linq/find-attribute-parent.md @@ -10,7 +10,7 @@ ms.topic: how-to # How to find an attribute of the parent (LINQ to XML) -This article shows how to use to find an attribute of a parent element, and how to use LINQ to XML query to do the same thing. +This article shows how to use to find an attribute of a parent element, and how to use LINQ to XML query to do the same thing. ## Example: Find the `Author` element, and then find the `id` attribute of its parent diff --git a/docs/standard/linq/find-attributes-siblings-specific-name.md b/docs/standard/linq/find-attributes-siblings-specific-name.md index 909bd0c4ba335..7fc5af259b1db 100644 --- a/docs/standard/linq/find-attributes-siblings-specific-name.md +++ b/docs/standard/linq/find-attributes-siblings-specific-name.md @@ -10,7 +10,7 @@ ms.topic: how-to # How to find attributes of siblings with a specific name (LINQ to XML) -This article shows how to use to find every attribute that has a specific name and that also belongs to a sibling of the context node. The article also shows how to use LINQ to XML query to do the same thing. +This article shows how to use to find every attribute that has a specific name and that also belongs to a sibling of the context node. The article also shows how to use LINQ to XML query to do the same thing. ## Example: Find all sibling elements named `Book`, and then find all attributes named `id` diff --git a/docs/standard/linq/find-child-element.md b/docs/standard/linq/find-child-element.md index 55db16f6895a2..5ab1505059991 100644 --- a/docs/standard/linq/find-child-element.md +++ b/docs/standard/linq/find-child-element.md @@ -1,6 +1,6 @@ --- title: How to find a child element - LINQ to XML -description: This article compares the XPath child element axis to the LINQ to XML method. +description: This article compares the XPath child element axis to the LINQ to XML method. ms.date: 07/20/2015 dev_langs: - "csharp" @@ -10,7 +10,7 @@ ms.topic: how-to # How to find a child element (LINQ to XML) -This article compares the XPath child element axis to the LINQ to XML method. +This article compares the XPath child element axis to the LINQ to XML method. ## Example: Find a child element in an XML document diff --git a/docs/standard/linq/find-child-elements-based-position.md b/docs/standard/linq/find-child-elements-based-position.md index 45a23d51d5ad6..76472b91c0ddd 100644 --- a/docs/standard/linq/find-child-elements-based-position.md +++ b/docs/standard/linq/find-child-elements-based-position.md @@ -10,9 +10,9 @@ ms.topic: how-to # How to find child elements based on position (LINQ to XML) -This article shows how to use to find elements based on element position – for example, to find the second element, or the third through the fifth. It also shows two ways to use LINQ to XML query to do the same thing. +This article shows how to use to find elements based on element position – for example, to find the second element, or the third through the fifth. It also shows two ways to use LINQ to XML query to do the same thing. -There are two approaches to writing this LINQ to XML query in a lazy way. You can use the and operators, or you can use the overload that takes an index. When you use the overload, you use a lambda expression that takes two arguments. The following example shows both methods of selecting based on position. +There are two approaches to writing this LINQ to XML query in a lazy way. You can use the and operators, or you can use the overload that takes an index. When you use the overload, you use a lambda expression that takes two arguments. The following example shows both methods of selecting based on position. ## Example: Find the second through the fourth `Test` elements diff --git a/docs/standard/linq/find-default-paragraph-style.md b/docs/standard/linq/find-default-paragraph-style.md index f63d2bfed25b0..dfd6823ba10b7 100644 --- a/docs/standard/linq/find-default-paragraph-style.md +++ b/docs/standard/linq/find-default-paragraph-style.md @@ -15,7 +15,7 @@ The first task in [Tutorial: Manipulate content in a WordprocessingML document]( The following example opens an Office Open XML WordprocessingML document, finds the document and style parts of the package, and then executes a query that finds the default style name. For information about Office Open XML document packages, and the parts they comprise, see [Details of Office Open XML WordprocessingML documents](wordprocessingml-document-styles.md). -The query finds a node named `w:style` that has an attribute named `w:type` with a value of "paragraph", and also has an attribute named `w:default` with a value of "1". Because there will be only one XML node with these attributes, the query uses the operator to convert a collection to a singleton. It then gets the value of the attribute with the name `w:styleId`. +The query finds a node named `w:style` that has an attribute named `w:type` with a value of "paragraph", and also has an attribute named `w:default` with a value of "1". Because there will be only one XML node with these attributes, the query uses the operator to convert a collection to a singleton. It then gets the value of the attribute with the name `w:styleId`. This example uses classes from the WindowsBase assembly. It uses types in the namespace. diff --git a/docs/standard/linq/find-descendants-child-element.md b/docs/standard/linq/find-descendants-child-element.md index 24ef2f1d5d6ab..324d4cd52aece 100644 --- a/docs/standard/linq/find-descendants-child-element.md +++ b/docs/standard/linq/find-descendants-child-element.md @@ -10,11 +10,11 @@ ms.topic: how-to # How to find descendants of a child element (LINQ to XML) -This article shows how to use to find the descendant elements of a sequence of child elements, and how to use LINQ to XML query to find the same elements. +This article shows how to use to find the descendant elements of a sequence of child elements, and how to use LINQ to XML query to find the same elements. ## Example: Find all the `Text` descendant elements of all the `Paragraph` elements -This example extracts text from an XML representation of a simple word processing document. It first selects all `Paragraph` elements, ignoring the `Comment` element, and then it selects all the `Text` descendant elements of each `Paragraph` element. It does this task in two ways: with and with LINQ to XML query. It then compares the results and finds them identical. +This example extracts text from an XML representation of a simple word processing document. It first selects all `Paragraph` elements, ignoring the `Comment` element, and then it selects all the `Text` descendant elements of each `Paragraph` element. It does this task in two ways: with and with LINQ to XML query. It then compares the results and finds them identical. The XPath expression is `./Paragraph//Text/text()`. diff --git a/docs/standard/linq/find-descendants-specific-element-name.md b/docs/standard/linq/find-descendants-specific-element-name.md index 41cb6eca504cb..233c54644670f 100644 --- a/docs/standard/linq/find-descendants-specific-element-name.md +++ b/docs/standard/linq/find-descendants-specific-element-name.md @@ -7,7 +7,7 @@ ms.topic: how-to # How to find descendants with a specific element name (LINQ to XML) -Sometimes you want to find all descendants with a specific name. You could write code to iterate through all of the descendants, but it's easier to use the axis. +Sometimes you want to find all descendants with a specific name. You could write code to iterate through all of the descendants, but it's easier to use the axis. ## Example: Find descendants with a specific element name @@ -162,4 +162,4 @@ Some text that's broken up into multiple segments. ## See also -- +- diff --git a/docs/standard/linq/find-element-specific-attribute.md b/docs/standard/linq/find-element-specific-attribute.md index a53a9e1a53dbe..e76c657aa73c3 100644 --- a/docs/standard/linq/find-element-specific-attribute.md +++ b/docs/standard/linq/find-element-specific-attribute.md @@ -99,8 +99,8 @@ This example produces the following output: ## See also -- -- +- +- - [Standard Query Operators Overview (C#)](../../csharp/linq/standard-query-operators/index.md) - [Projection Operations (C#)](../../csharp/linq/standard-query-operators/projection-operations.md) - [Basic Queries (LINQ to XML) (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/basic-query-operations.md) diff --git a/docs/standard/linq/find-element-specific-child-element.md b/docs/standard/linq/find-element-specific-child-element.md index 33d61f54969f8..da859aaa0ef42 100644 --- a/docs/standard/linq/find-element-specific-child-element.md +++ b/docs/standard/linq/find-element-specific-child-element.md @@ -89,7 +89,7 @@ This example produces the following output: ## See also -- -- +- +- - [Standard Query Operators Overview](../../csharp/linq/standard-query-operators/index.md) - [Projection Operations](../../csharp/linq/standard-query-operators/projection-operations.md) diff --git a/docs/standard/linq/find-elements-specific-attribute.md b/docs/standard/linq/find-elements-specific-attribute.md index d3cc17dced21d..aa424c6b4052f 100644 --- a/docs/standard/linq/find-elements-specific-attribute.md +++ b/docs/standard/linq/find-elements-specific-attribute.md @@ -10,7 +10,7 @@ ms.topic: how-to # How to find elements with a specific attribute (LINQ to XML) -This article shows how to use to find all elements that have a specific attribute (regardless of value), and how to use LINQ to XML query to do the same thing. +This article shows how to use to find all elements that have a specific attribute (regardless of value), and how to use LINQ to XML query to do the same thing. ## Example: Find all elements that have the `Select` attribute diff --git a/docs/standard/linq/find-immediate-preceding-sibling.md b/docs/standard/linq/find-immediate-preceding-sibling.md index edd9bda49d732..5b166af3b8032 100644 --- a/docs/standard/linq/find-immediate-preceding-sibling.md +++ b/docs/standard/linq/find-immediate-preceding-sibling.md @@ -10,11 +10,11 @@ ms.topic: how-to # How to find the immediate preceding sibling (LINQ to XML) -This article shows how to use to find the sibling that immediately precedes a node, and how to use LINQ to XML query to do the same thing. Due to the difference in the semantics of positional predicates for the preceding sibling axes in XPath as opposed to LINQ to XML, this is one of the more interesting comparisons. +This article shows how to use to find the sibling that immediately precedes a node, and how to use LINQ to XML query to do the same thing. Due to the difference in the semantics of positional predicates for the preceding sibling axes in XPath as opposed to LINQ to XML, this is one of the more interesting comparisons. ## Example: Find the next to last element -In this example, the LINQ to XML query uses the operator to find the last node in the collection returned by . By contrast, the XPath expression uses a predicate with a value of 1 to find the immediately preceding element. +In this example, the LINQ to XML query uses the operator to find the last node in the collection returned by . By contrast, the XPath expression uses a predicate with a value of 1 to find the immediately preceding element. ```csharp XElement root = XElement.Parse( diff --git a/docs/standard/linq/find-list-child-elements.md b/docs/standard/linq/find-list-child-elements.md index 1547642814884..2325a5123cd43 100644 --- a/docs/standard/linq/find-list-child-elements.md +++ b/docs/standard/linq/find-list-child-elements.md @@ -10,7 +10,7 @@ ms.assetid: 7c589dd8-f680-4cdb-9d6a-78d57e2555e8 # How to find a list of child elements (LINQ to XML) -This article compares the XPath child elements axis to the LINQ to XML axis. +This article compares the XPath child elements axis to the LINQ to XML axis. ## Example: Find all child elements of an element diff --git a/docs/standard/linq/find-preceding-siblings.md b/docs/standard/linq/find-preceding-siblings.md index dfc47c382c3a7..1829be11282c0 100644 --- a/docs/standard/linq/find-preceding-siblings.md +++ b/docs/standard/linq/find-preceding-siblings.md @@ -10,7 +10,7 @@ ms.topic: how-to # How to find preceding siblings (LINQ to XML) -This article shows how to use along the preceding-sibling axis to find sibling elements that precede a given element, and how to use to find the same elements. +This article shows how to use along the preceding-sibling axis to find sibling elements that precede a given element, and how to use to find the same elements. ## Example: Use two methods to find sibling elements that precede an element diff --git a/docs/standard/linq/find-sibling-nodes.md b/docs/standard/linq/find-sibling-nodes.md index 2ca128adafa46..d64c388c691b7 100644 --- a/docs/standard/linq/find-sibling-nodes.md +++ b/docs/standard/linq/find-sibling-nodes.md @@ -10,7 +10,7 @@ ms.topic: how-to # How to find sibling nodes (LINQ to XML) -This article shows how to use to find all siblings of a node that have a specific name, and how to use LINQ to XML query to do the same thing. +This article shows how to use to find all siblings of a node that have a specific name, and how to use LINQ to XML query to do the same thing. > [!NOTE] > The resulting collection includes the context node if it also has the specific name. diff --git a/docs/standard/linq/find-single-descendant-descendants-method.md b/docs/standard/linq/find-single-descendant-descendants-method.md index 46ae50b679f47..300a47bb6ed94 100644 --- a/docs/standard/linq/find-single-descendant-descendants-method.md +++ b/docs/standard/linq/find-single-descendant-descendants-method.md @@ -10,11 +10,11 @@ ms.topic: how-to # How to find a single descendant using the Descendants method (LINQ to XML) -You can use the axis method to find a single uniquely-named descendant element. This technique is especially useful when you want to find a particular descendant with a specific name, and may be faster and easier to use than navigating the XML tree. +You can use the axis method to find a single uniquely-named descendant element. This technique is especially useful when you want to find a particular descendant with a specific name, and may be faster and easier to use than navigating the XML tree. ## Example: Use XContainer.Descendants to find a single uniquely-named descendant element -This example uses the standard query operator. +This example uses the standard query operator. ```csharp XElement root = XElement.Parse(@" diff --git a/docs/standard/linq/find-union-two-location-paths.md b/docs/standard/linq/find-union-two-location-paths.md index 19d0311c406fe..e3d29d3f5047f 100644 --- a/docs/standard/linq/find-union-two-location-paths.md +++ b/docs/standard/linq/find-union-two-location-paths.md @@ -10,14 +10,14 @@ ms.topic: how-to # How to find a union of two location paths (LINQ to XML) -This article shows how to use to find the union of the results of two XPath location paths, and how to use the standard query operator to do the same thing. +This article shows how to use to find the union of the results of two XPath location paths, and how to use the standard query operator to do the same thing. ## Example: Find all `Category` and `Price` elements and concatenate them This example finds all of the `Category` elements and all of the `Price` elements in XML document [Sample XML file: Numerical data](sample-xml-file-numerical-data.md), and concatenates them into a single collection. The XPath expression is `//Category|//Price`. > [!NOTE] -> The LINQ to XML query calls to put the results in document order. The XPath expression results are also in document order. +> The LINQ to XML query calls to put the results in document order. The XPath expression results are also in document order. ```csharp XDocument data = XDocument.Load("Data.xml"); diff --git a/docs/standard/linq/functional-construction.md b/docs/standard/linq/functional-construction.md index ca413722e78f4..dbe511578af6a 100644 --- a/docs/standard/linq/functional-construction.md +++ b/docs/standard/linq/functional-construction.md @@ -16,7 +16,7 @@ Several key features of the LINQ to XML programming interface are used in functi - The constructor takes various types of arguments for content. For example, you can pass another object, which becomes a child element. You can pass an object, which becomes an attribute of the element. Or you can pass any other type of object, which is converted to a string and becomes the text content of the element. - The constructor takes a `params` array of type , so that you can pass any number of objects to the constructor. This enables you to create an element that has complex content. -- If an object implements , the collection in the object is enumerated, and all items in the collection are added. If the collection contains or objects, each item in the collection is added separately. This is important because it lets you pass the results of a LINQ query to the constructor. +- If an object implements , the collection in the object is enumerated, and all items in the collection are added. If the collection contains or objects, each item in the collection is added separately. This is important because it lets you pass the results of a LINQ query to the constructor. ## Example: Create an XML tree diff --git a/docs/standard/linq/intermediate-materialization.md b/docs/standard/linq/intermediate-materialization.md index 50a1fbb13dcfb..d8c272b329000 100644 --- a/docs/standard/linq/intermediate-materialization.md +++ b/docs/standard/linq/intermediate-materialization.md @@ -7,11 +7,11 @@ ms.assetid: 7922d38f-5044-41cf-8e17-7173d6553a5e # Intermediate materialization (C#) -If you're not careful you can, in some situations, drastically alter the memory and performance profile of your application by causing premature materialization of collections in your queries. Some standard query operators cause materialization of their source collection before yielding a single element. For example, first iterates through its entire source collection, then sorts all items, and then finally yields the first item. This means that it's expensive to get the first item of an ordered collection; each item thereafter isn't expensive. This makes sense; it would be impossible for that query operator to do otherwise. +If you're not careful you can, in some situations, drastically alter the memory and performance profile of your application by causing premature materialization of collections in your queries. Some standard query operators cause materialization of their source collection before yielding a single element. For example, first iterates through its entire source collection, then sorts all items, and then finally yields the first item. This means that it's expensive to get the first item of an ordered collection; each item thereafter isn't expensive. This makes sense; it would be impossible for that query operator to do otherwise. ## Example: Add a method that calls `ToList`, causing materialization -This example alters the example in [Chain queries example (C#)](chain-queries-example.md): the `AppendString` method is changed to call before iterating through the source, which causes materialization. +This example alters the example in [Chain queries example (C#)](chain-queries-example.md): the `AppendString` method is changed to call before iterating through the source, which causes materialization. ```csharp public static class LocalExtensions @@ -78,7 +78,7 @@ AppendString: source >GHI< Main: str >GHI!!!< ``` -In this example, you can see that the call to causes `AppendString` to enumerate its entire source before yielding the first item. If the source were a large array, this would significantly alter the memory profile of the application. +In this example, you can see that the call to causes `AppendString` to enumerate its entire source before yielding the first item. If the source were a large array, this would significantly alter the memory profile of the application. Standard query operators can also be chained together as shown in the final article in this tutorial: diff --git a/docs/standard/linq/language-integrated-axes.md b/docs/standard/linq/language-integrated-axes.md index 26ae957e999d8..b224962d88b28 100644 --- a/docs/standard/linq/language-integrated-axes.md +++ b/docs/standard/linq/language-integrated-axes.md @@ -11,9 +11,9 @@ Axis features are integrated into Visual Basic, making it easy to access XML. Ma |Article|Description| |-----------|-----------------| -|[XML Child Axis Property](../../visual-basic/language-reference/xml-axis/xml-child-axis-property.md)|Provides access to the children of one of the following: an object, an object, a collection of objects, or a collection of objects. This axis is equivalent to the axis.| -|[XML Descendant Axis Property](../../visual-basic/language-reference/xml-axis/xml-descendant-axis-property.md)|Provides access to the descendants of the following: an object, an object, or a collection of objects. This axis is equivalent to the axis.| -|[XML Attribute Axis Property](../../visual-basic/language-reference/xml-axis/xml-attribute-axis-property.md)|Provides access to an attribute of an object. This axis is roughly equivalent to the axis. This axis differs from the axis in that it returns the value of the attribute, not an object.| +|[XML Child Axis Property](../../visual-basic/language-reference/xml-axis/xml-child-axis-property.md)|Provides access to the children of one of the following: an object, an object, a collection of objects, or a collection of objects. This axis is equivalent to the axis.| +|[XML Descendant Axis Property](../../visual-basic/language-reference/xml-axis/xml-descendant-axis-property.md)|Provides access to the descendants of the following: an object, an object, or a collection of objects. This axis is equivalent to the axis.| +|[XML Attribute Axis Property](../../visual-basic/language-reference/xml-axis/xml-attribute-axis-property.md)|Provides access to an attribute of an object. This axis is roughly equivalent to the axis. This axis differs from the axis in that it returns the value of the attribute, not an object.| |[Extension Indexer Property](../../visual-basic/language-reference/xml-axis/extension-indexer-property.md)|Provides access to individual elements in a collection.| ## See also diff --git a/docs/standard/linq/linq-xml-annotations.md b/docs/standard/linq/linq-xml-annotations.md index d821c760a9d1b..245a161108330 100644 --- a/docs/standard/linq/linq-xml-annotations.md +++ b/docs/standard/linq/linq-xml-annotations.md @@ -8,7 +8,7 @@ ms.assetid: 54e7b9d0-07f5-488f-9065-b6e6b870f810 Annotations in LINQ to XML enable you to associate any arbitrary object of any arbitrary type with any XML component in an XML tree. -To add an annotation to an XML component, such as an or , you call the method. You retrieve annotations by type. +To add an annotation to an XML component, such as an or , you call the method. You retrieve annotations by type. Note that annotations aren't part of the XML infoset; they're not serialized or deserialized. @@ -18,7 +18,7 @@ You can use the following methods when working with annotations: |Method|Description| |------------|-----------------| -||Adds an object to the annotation list of an .| -||Gets the first annotation object of the specified type from an .| -||Gets a collection of annotations of the specified type for an .| -||Removes the annotations of the specified type from an .| +||Adds an object to the annotation list of an .| +||Gets the first annotation object of the specified type from an .| +||Gets a collection of annotations of the specified type for an .| +||Removes the annotations of the specified type from an .| diff --git a/docs/standard/linq/linq-xml-axes-overview.md b/docs/standard/linq/linq-xml-axes-overview.md index b5f176052bff3..8250cf0324cac 100644 --- a/docs/standard/linq/linq-xml-axes-overview.md +++ b/docs/standard/linq/linq-xml-axes-overview.md @@ -6,13 +6,13 @@ ms.assetid: 516792fb-461d-40a8-8a50-9993a51258fc --- # LINQ to XML axes overview -After you've created an XML tree or loaded an XML document into an XML tree, you can query it to find elements and attributes and retrieve their values. You retrieve collections through the *axis methods*, also called *axes*. Some of the axes are methods in the and classes that return collections. Some of the axes are extension methods in the class. The axes that are implemented as extension methods operate on collections and return collections. +After you've created an XML tree or loaded an XML document into an XML tree, you can query it to find elements and attributes and retrieve their values. You retrieve collections through the *axis methods*, also called *axes*. Some of the axes are methods in the and classes that return collections. Some of the axes are extension methods in the class. The axes that are implemented as extension methods operate on collections and return collections. -As described in [XElement class overview](xelement-class-overview.md), an object represents a single element node. The content of an element can be complex (sometimes called structured content), or it can be a simple element. A simple element can be empty or can contain a value. If the node contains structured content, you can use the various axis methods to retrieve enumerations of descendant elements. The most commonly used axis methods are and . +As described in [XElement class overview](xelement-class-overview.md), an object represents a single element node. The content of an element can be complex (sometimes called structured content), or it can be a simple element. A simple element can be empty or can contain a value. If the node contains structured content, you can use the various axis methods to retrieve enumerations of descendant elements. The most commonly used axis methods are and . -In addition to the axis methods, which return collections, there are two more methods that you'll commonly use in LINQ to XML queries. The method returns a single . The method returns a single . +In addition to the axis methods, which return collections, there are two more methods that you'll commonly use in LINQ to XML queries. The method returns a single . The method returns a single . -For many purposes, LINQ queries provide the most powerful way to examine a tree, extract data from it, and transform it. LINQ queries operate on objects that implement , and the LINQ to XML axes return of collections, and of collections. You need these collections to do your queries. +For many purposes, LINQ queries provide the most powerful way to examine a tree, extract data from it, and transform it. LINQ queries operate on objects that implement , and the LINQ to XML axes return of collections, and of collections. You need these collections to do your queries. In addition to the axis methods that retrieve collections of elements and attributes, there are axis methods that allow you to iterate through the tree in great detail. For example, instead of dealing with elements and attributes, you can work with the nodes of the tree. Nodes are a finer level of granularity than elements and attributes. When working with nodes, you can examine XML comments, text nodes, processing instructions, and more. This functionality is important, for example, to someone who is writing a word processor and wants to save documents as XML. However, the majority of XML programmers are primarily concerned with elements, attributes, and their values. @@ -22,13 +22,13 @@ The following is a summary of the methods of the |Method|Description| |------------|-----------------| -||Returns an of of the ancestors of this element. An overload returns an of of the ancestors that have the specified .| -||Returns an of of the descendants of this element. An overload returns an of of the descendants that have the specified .| -||Returns an of of the child elements of this element. An overload returns an of of the child elements that have the specified .| -||Returns an of of the elements that come after this element. An overload returns an of of the elements after this element that have the specified .| -||Returns an of of the elements that come before this element. An overload returns an of of the elements before this element that have the specified .| -||Returns an of of this element and its ancestors. An overload returns an of of the elements that have the specified .| -||Returns an of of this element and its descendants. An overload returns an of of the elements that have the specified .| +||Returns an of of the ancestors of this element. An overload returns an of of the ancestors that have the specified .| +||Returns an of of the descendants of this element. An overload returns an of of the descendants that have the specified .| +||Returns an of of the child elements of this element. An overload returns an of of the child elements that have the specified .| +||Returns an of of the elements that come after this element. An overload returns an of of the elements after this element that have the specified .| +||Returns an of of the elements that come before this element. An overload returns an of of the elements before this element that have the specified .| +||Returns an of of this element and its ancestors. An overload returns an of of the elements that have the specified .| +||Returns an of of this element and its descendants. An overload returns an of of the elements that have the specified .| ## Method for retrieving a single element @@ -36,7 +36,7 @@ The following method retrieves a single child from an |Returns the first child object that has the specified .| +||Returns the first child object that has the specified .| ## Method for retrieving a collection of attributes @@ -44,7 +44,7 @@ The following method retrieves attributes from an |Returns an of of all of the attributes.| +||Returns an of of all of the attributes.| ## Method for retrieving a single attribute @@ -52,4 +52,4 @@ The following method retrieves a single attribute from an |Returns the that has the specified .| +||Returns the that has the specified .| diff --git a/docs/standard/linq/linq-xml-classes-overview.md b/docs/standard/linq/linq-xml-classes-overview.md index 0f92600ef9e66..7facc59ddef3a 100644 --- a/docs/standard/linq/linq-xml-classes-overview.md +++ b/docs/standard/linq/linq-xml-classes-overview.md @@ -50,7 +50,7 @@ This article provides a list of the LINQ to XML classes in the represents names of elements () and attributes (). For detailed information and examples, see [XDocument class overview](xdocument-class-overview.md). -LINQ to XML is designed to make XML names as straightforward as possible. Due to their complexity, XML names are often considered to be an advanced article in XML. Arguably, this complexity comes not from namespaces, which developers use regularly in programming, but from namespace prefixes. Namespace prefixes can be useful to reduce the keystrokes required when you input XML, or to make XML easier to read. However, prefixes are often just a shortcut for using the full XML namespace, and aren't required in most cases. LINQ to XML simplifies XML names by resolving all prefixes to their corresponding XML namespace. Prefixes are available, if they're required, through the method. +LINQ to XML is designed to make XML names as straightforward as possible. Due to their complexity, XML names are often considered to be an advanced article in XML. Arguably, this complexity comes not from namespaces, which developers use regularly in programming, but from namespace prefixes. Namespace prefixes can be useful to reduce the keystrokes required when you input XML, or to make XML easier to read. However, prefixes are often just a shortcut for using the full XML namespace, and aren't required in most cases. LINQ to XML simplifies XML names by resolving all prefixes to their corresponding XML namespace. Prefixes are available, if they're required, through the method. it's possible, if necessary, to control namespace prefixes. In some circumstances, if you're working with other XML systems, such as XSLT or XAML, you need to control namespace prefixes. For example, if you have an XPath expression that uses namespace prefixes and is embedded in an XSLT stylesheet, you must make sure that your XML document is serialized with namespace prefixes that match those used in the XPath expression. diff --git a/docs/standard/linq/linq-xml-overview.md b/docs/standard/linq/linq-xml-overview.md index 9f66330b49e46..186ca0c81c143 100644 --- a/docs/standard/linq/linq-xml-overview.md +++ b/docs/standard/linq/linq-xml-overview.md @@ -118,7 +118,7 @@ In addition to these LINQ capabilities, LINQ to XML provides an improved XML pro - Serialize XML to files or streams. - Create XML from scratch by using functional construction. - Query XML using XPath-like axes. -- Manipulate the in-memory XML tree by using methods such as , , , and . +- Manipulate the in-memory XML tree by using methods such as , , , and . - Validate XML trees using XSD. - Use a combination of these features to transform XML trees from one shape into another. diff --git a/docs/standard/linq/linq-xml-security.md b/docs/standard/linq/linq-xml-security.md index 52cb4dffdcf2c..e455766cf3ffe 100644 --- a/docs/standard/linq/linq-xml-security.md +++ b/docs/standard/linq/linq-xml-security.md @@ -54,9 +54,9 @@ The description of an error might reveal data, such as the data being transforme An assembly can have lesser or greater permissions. An assembly that has greater permissions has greater control over the computer and its environments. -If code in an assembly with greater permissions calls in an event handler, and then the XML tree is passed to a malicious assembly that has restricted permissions, the malicious assembly can cause an event to be raised. Because the event runs code that's in the assembly with greater permissions, the malicious assembly would then be operating with elevated privileges. +If code in an assembly with greater permissions calls in an event handler, and then the XML tree is passed to a malicious assembly that has restricted permissions, the malicious assembly can cause an event to be raised. Because the event runs code that's in the assembly with greater permissions, the malicious assembly would then be operating with elevated privileges. -Microsoft recommends that you never call in an event handler. +Microsoft recommends that you never call in an event handler. ### Don't accept DTDs from untrusted sources @@ -68,13 +68,13 @@ One example of accepting DTDs from untrusted sources is a Web application that a Application developers should be aware that extremely large data sources can lead to resource exhaustion and denial of service attacks. -If a malicious user submits or uploads a very large XML document, it could cause LINQ to XML to consume excessive system resources. This can constitute a denial of service attack. To prevent this, you can set the property, and create a reader that's then limited in the size of document that it can load. You then use the reader to create the XML tree. +If a malicious user submits or uploads a very large XML document, it could cause LINQ to XML to consume excessive system resources. This can constitute a denial of service attack. To prevent this, you can set the property, and create a reader that's then limited in the size of document that it can load. You then use the reader to create the XML tree. -For example, if you know that the maximum expected size of your XML documents coming from an untrusted source will be less than 50K bytes, set to 100,000. This will not encumber your processing of XML documents, and at the same time it will mitigate denial of service threats where documents might be uploaded that would consume large amounts of memory. +For example, if you know that the maximum expected size of your XML documents coming from an untrusted source will be less than 50K bytes, set to 100,000. This will not encumber your processing of XML documents, and at the same time it will mitigate denial of service threats where documents might be uploaded that would consume large amounts of memory. ### Avoid excess entity expansion -One of the known denial of service attacks when using a DTD is a document that causes excessive entity expansion. To prevent this, you can set the property, and create a reader that's then limited in the number of characters that result from entity expansion. You then use the reader to create the XML tree. +One of the known denial of service attacks when using a DTD is a document that causes excessive entity expansion. To prevent this, you can set the property, and create a reader that's then limited in the number of characters that result from entity expansion. You then use the reader to create the XML tree. ### Limit the depth of the XML hierarchy diff --git a/docs/standard/linq/linq-xml-vs-dom.md b/docs/standard/linq/linq-xml-vs-dom.md index a48c14576ba37..16ebaeb6bebdb 100644 --- a/docs/standard/linq/linq-xml-vs-dom.md +++ b/docs/standard/linq/linq-xml-vs-dom.md @@ -171,7 +171,7 @@ LINQ to XML further simplifies XML programming by removing support for entities ## Support for fragments -LINQ to XML doesn't provide an equivalent for the `XmlDocumentFragment` class. In many cases, however, the `XmlDocumentFragment` concept can be handled by the result of a query that's typed as of , or of . +LINQ to XML doesn't provide an equivalent for the `XmlDocumentFragment` class. In many cases, however, the `XmlDocumentFragment` concept can be handled by the result of a query that's typed as of , or of . ## Support for XPathNavigator diff --git a/docs/standard/linq/load-xml-file.md b/docs/standard/linq/load-xml-file.md index da226aeeb9347..3105698584818 100644 --- a/docs/standard/linq/load-xml-file.md +++ b/docs/standard/linq/load-xml-file.md @@ -10,11 +10,11 @@ ms.topic: how-to # How to load XML from a file (LINQ to XML) -This article shows how to load XML from a file in C# and Visual Basic using the method. +This article shows how to load XML from a file in C# and Visual Basic using the method. ## Example: Load XML document from a file -The following example shows how to load an XML document from a file by providing with the URI that references the file. The example loads books.xml and outputs the XML tree to the console. +The following example shows how to load an XML document from a file by providing with the URI that references the file. The example loads books.xml and outputs the XML tree to the console. The contents of books.xml are shown in [Sample XML file: Books](sample-xml-file-books.md). diff --git a/docs/standard/linq/maintain-name-value-pairs.md b/docs/standard/linq/maintain-name-value-pairs.md index 7b6ef10261bcd..572806a766ffe 100644 --- a/docs/standard/linq/maintain-name-value-pairs.md +++ b/docs/standard/linq/maintain-name-value-pairs.md @@ -16,23 +16,23 @@ One difference between keeping the information as attributes or as child element ## SetAttributeValue and SetElementValue -The two methods that facilitate keeping name-value pairs are and . These two methods have similar semantics. +The two methods that facilitate keeping name-value pairs are and . These two methods have similar semantics. - can add, modify, and remove attributes of an element. + can add, modify, and remove attributes of an element. -- If you call with a name of an attribute that doesn't exist, the method creates a new attribute and adds it to the specified element. -- If you call with a name of an existing attribute and with some specified content, the contents of the attribute are replaced with the specified content. -- If you call with a name of an existing attribute, and specify `null` for the content, the attribute is removed from its parent. +- If you call with a name of an attribute that doesn't exist, the method creates a new attribute and adds it to the specified element. +- If you call with a name of an existing attribute and with some specified content, the contents of the attribute are replaced with the specified content. +- If you call with a name of an existing attribute, and specify `null` for the content, the attribute is removed from its parent. - can add, modify, and remove child elements of an element. + can add, modify, and remove child elements of an element. -- If you call with a name of a child element that doesn't exist, the method creates a new element and adds it to the specified element. -- If you call with a name of an existing element and with some specified content, the contents of the element are replaced with the specified content. -- If you call with a name of an existing element, and specify `null` for the content, the element is removed from its parent. +- If you call with a name of a child element that doesn't exist, the method creates a new element and adds it to the specified element. +- If you call with a name of an existing element and with some specified content, the contents of the element are replaced with the specified content. +- If you call with a name of an existing element, and specify `null` for the content, the element is removed from its parent. ## Example: Use `SetAttributeValue` to create and maintain a list of name-value pairs -The following example creates an element with no attributes. It then uses the method to create and maintain a list of name-value pairs. +The following example creates an element with no attributes. It then uses the method to create and maintain a list of name-value pairs. ```csharp // Create an element with no content. @@ -86,7 +86,7 @@ This example produces the following output: ## Example: Use `SetElementValue` to create and maintain a list of name-value pairs -The following example creates an element with no child elements. It then uses the method to create and maintain a list of name-value pairs. +The following example creates an element with no child elements. It then uses the method to create and maintain a list of name-value pairs. ```csharp // Create an element with no content. @@ -163,5 +163,5 @@ This example produces the following output: ## See also -- -- +- +- diff --git a/docs/standard/linq/mixed-declarative-imperative-code-bugs.md b/docs/standard/linq/mixed-declarative-imperative-code-bugs.md index 01babd9e2502f..ccc82e42e317f 100644 --- a/docs/standard/linq/mixed-declarative-imperative-code-bugs.md +++ b/docs/standard/linq/mixed-declarative-imperative-code-bugs.md @@ -10,7 +10,7 @@ ms.assetid: fada62d0-0680-4e73-945a-2b00d7a507af # Mixed declarative/imperative code bugs (LINQ to XML) -LINQ to XML contains various methods that allow you to modify an XML tree directly. You can add elements, delete elements, change the contents of an element, add attributes, and so on. This programming interface is described in [Modify XML trees](in-memory-xml-tree-modification-vs-functional-construction.md). If you're iterating through one of the axes, such as , and you're modifying the XML tree as you iterate through the axis, you can end up with some strange bugs. +LINQ to XML contains various methods that allow you to modify an XML tree directly. You can add elements, delete elements, change the contents of an element, add attributes, and so on. This programming interface is described in [Modify XML trees](in-memory-xml-tree-modification-vs-functional-construction.md). If you're iterating through one of the axes, such as , and you're modifying the XML tree as you iterate through the axis, you can end up with some strange bugs. This problem is sometimes known as "The Halloween Problem". @@ -58,7 +58,7 @@ Next This code goes into an infinite loop. The `foreach` statement iterates through the `Elements()` axis, adding new elements to the `doc` element. It ends up iterating also through the elements it just added. And because it allocates new objects with every iteration of the loop, it will eventually consume all available memory. -You can fix this problem by pulling the collection into memory using the standard query operator, as follows: +You can fix this problem by pulling the collection into memory using the standard query operator, as follows: ```csharp XElement root = new XElement("Root", @@ -136,7 +136,7 @@ This example produces the following output: ``` -The solution again is to call to materialize the collection, as follows: +The solution again is to call to materialize the collection, as follows: ```csharp XElement root = new XElement("Root", @@ -168,7 +168,7 @@ This example produces the following output: ``` -Alternatively, you can eliminate the iteration altogether by calling on the parent element: +Alternatively, you can eliminate the iteration altogether by calling on the parent element: ```csharp XElement root = new XElement("Root", diff --git a/docs/standard/linq/modify-elements-attributes-nodes-xml-tree.md b/docs/standard/linq/modify-elements-attributes-nodes-xml-tree.md index 1aeadb8cafdfa..4bc364a0b0b82 100644 --- a/docs/standard/linq/modify-elements-attributes-nodes-xml-tree.md +++ b/docs/standard/linq/modify-elements-attributes-nodes-xml-tree.md @@ -13,31 +13,31 @@ The following methods modify an : |Method|Description| |------------|-----------------| -||Replaces an element with parsed XML.| -||Removes all content (child nodes and attributes) of an element.| -||Removes the attributes of an element.| -||Replaces all content (child nodes and attributes) of an element.| -||Replaces the attributes of an element.| -||Sets the value of an attribute. Creates the attribute if it doesn't exist. If the value is set to `null`, removes the attribute.| -||Sets the value of a child element. Creates the element if it doesn't exist. If the value is set to `null`, removes the element.| -||Replaces the content (child nodes) of an element with the specified text.| -||Sets the value of an element.| +||Replaces an element with parsed XML.| +||Removes all content (child nodes and attributes) of an element.| +||Removes the attributes of an element.| +||Replaces all content (child nodes and attributes) of an element.| +||Replaces the attributes of an element.| +||Sets the value of an attribute. Creates the attribute if it doesn't exist. If the value is set to `null`, removes the attribute.| +||Sets the value of a child element. Creates the element if it doesn't exist. If the value is set to `null`, removes the element.| +||Replaces the content (child nodes) of an element with the specified text.| +||Sets the value of an element.| The following methods modify an : |Method|Description| |------------|-----------------| -||Sets the value of an attribute.| -||Sets the value of an attribute.| +||Sets the value of an attribute.| +||Sets the value of an attribute.| The following methods modify an (including an or ): |Method|Description| |------------|-----------------| -||Replaces a node with new content.| +||Replaces a node with new content.| The following methods modify an (an or ): |Method|Description| |------------|-----------------| -||Replaces the children nodes with new content:| +||Replaces the children nodes with new content:| diff --git a/docs/standard/linq/perform-streaming-transform-large-xml-documents.md b/docs/standard/linq/perform-streaming-transform-large-xml-documents.md index 7449e6eb40a11..af8ff77dbb0de 100644 --- a/docs/standard/linq/perform-streaming-transform-large-xml-documents.md +++ b/docs/standard/linq/perform-streaming-transform-large-xml-documents.md @@ -12,7 +12,7 @@ ms.topic: how-to Sometimes you have to transform large XML files, and write your application so that the memory footprint of the application is predictable. If you try to populate an XML tree with a very large XML file, your memory usage will be proportional to the size of the file (that is, excessive). Therefore, you should use a streaming technique instead. -Streaming techniques are best applied in situations where you need to process the source document only once, and you can process the elements in document order. Certain standard query operators, such as , iterate their source, collect all of the data, sort it, and then finally yield the first item in the sequence. Note that if you use a query operator that materializes its source before yielding the first item, you won't retain a small memory footprint for your application. +Streaming techniques are best applied in situations where you need to process the source document only once, and you can process the elements in document order. Certain standard query operators, such as , iterate their source, collect all of the data, sort it, and then finally yield the first item in the sequence. Note that if you use a query operator that materializes its source before yielding the first item, you won't retain a small memory footprint for your application. Even if you use the technique described in [How to stream XML fragments with access to header information](stream-xml-fragments-access-header-information.md), if you try to assemble an XML tree that contains the transformed document, memory usage will be too great. diff --git a/docs/standard/linq/performance-chained-queries.md b/docs/standard/linq/performance-chained-queries.md index bc9c9ccbc5331..82947d1a6168e 100644 --- a/docs/standard/linq/performance-chained-queries.md +++ b/docs/standard/linq/performance-chained-queries.md @@ -54,9 +54,9 @@ This example produces the following output: This chained query provides the same performance profile as iterating through a linked list. -- The axis has essentially the same performance as iterating through a linked list. is implemented as an iterator with deferred execution. This means that it does some work in addition to iterating through the linked list, such as allocating the iterator object and keeping track of execution state. This work can be divided into two categories: the work that is done at the time the iterator is set up, and the work that is done during each iteration. The setup work is a small, fixed amount of work and the work done during each iteration is proportional to the number of items in the source collection. -- In `query1`, the `where` clause (`Where` in Visual Basic) causes the query to call the method. This method is also implemented as an iterator. The setup work consists of instantiating the delegate that will reference the lambda expression, plus the normal setup for an iterator. With each iteration, the delegate is called to execute the predicate. The setup work and the work done during each iteration is similar to the work done while iterating through the axis. -- In `query1`, the select clause causes the query to call the method. This method has the same performance profile as the method. +- The axis has essentially the same performance as iterating through a linked list. is implemented as an iterator with deferred execution. This means that it does some work in addition to iterating through the linked list, such as allocating the iterator object and keeping track of execution state. This work can be divided into two categories: the work that is done at the time the iterator is set up, and the work that is done during each iteration. The setup work is a small, fixed amount of work and the work done during each iteration is proportional to the number of items in the source collection. +- In `query1`, the `where` clause (`Where` in Visual Basic) causes the query to call the method. This method is also implemented as an iterator. The setup work consists of instantiating the delegate that will reference the lambda expression, plus the normal setup for an iterator. With each iteration, the delegate is called to execute the predicate. The setup work and the work done during each iteration is similar to the work done while iterating through the axis. +- In `query1`, the select clause causes the query to call the method. This method has the same performance profile as the method. - In `query2`, both the `where` clause (`Where` in Visual Basic) and the `select` clause have the same performance profile as in `query1`. The iteration through `query2` is therefore directly proportional to the number of items in the source of the first query, in other words, linear time. diff --git a/docs/standard/linq/populate-xml-tree-xmlwriter.md b/docs/standard/linq/populate-xml-tree-xmlwriter.md index 9de6056a32f7e..d55d566794c79 100644 --- a/docs/standard/linq/populate-xml-tree-xmlwriter.md +++ b/docs/standard/linq/populate-xml-tree-xmlwriter.md @@ -10,13 +10,13 @@ ms.topic: how-to # How to populate an XML tree with an XmlWriter (LINQ to XML) -One way to populate an XML tree is to use to create an , and then write to the . The XML tree is populated with all nodes that are written to the . +One way to populate an XML tree is to use to create an , and then write to the . The XML tree is populated with all nodes that are written to the . You'd typically use this method when you use LINQ to XML with another class that expects to write to an , such as . ## Example: Create an XmlWriter to accept the output of an XSLT transformation -You can use to create an to accept the output of an XSLT transformation. This is shown in the following example, which does the following: +You can use to create an to accept the output of an XSLT transformation. This is shown in the following example, which does the following: - Creates an XML tree and an to read from it. - Creates a new tree and an to write to it. @@ -107,7 +107,7 @@ This example produces the following output: ## See also -- +- - - - [XML trees](functional-construction.md) diff --git a/docs/standard/linq/preserve-white-space-loading-parsing-xml.md b/docs/standard/linq/preserve-white-space-loading-parsing-xml.md index e07e503f8d90a..7d2e37bc9705f 100644 --- a/docs/standard/linq/preserve-white-space-loading-parsing-xml.md +++ b/docs/standard/linq/preserve-white-space-loading-parsing-xml.md @@ -19,10 +19,10 @@ This article describes the white space behavior of methods that populate XML tre The following methods in the and classes populate an XML tree. You can populate an XML tree from a file, a , an , or a string: -- -- -- -- +- +- +- +- If the method doesn't take as an argument, the method won't preserve insignificant white space. diff --git a/docs/standard/linq/preserve-white-space-serializing.md b/docs/standard/linq/preserve-white-space-serializing.md index 7d14477145f43..db43d8b0f5147 100644 --- a/docs/standard/linq/preserve-white-space-serializing.md +++ b/docs/standard/linq/preserve-white-space-serializing.md @@ -17,10 +17,10 @@ Another common scenario is to read and modify XML that has already been intentio The following methods in the and classes serialize an XML tree. You can serialize an XML tree to a file, a , or an . The `ToString` method serializes to a string. -- -- -- [XElement.ToString()](xref:System.Xml.Linq.XNode.ToString%2A?displayProperty=nameWithType) -- [XDocument.ToString()](xref:System.Xml.Linq.XNode.ToString%2A?displayProperty=nameWithType) +- +- +- [XElement.ToString()](xref:System.Xml.Linq.XNode.ToString*?displayProperty=nameWithType) +- [XDocument.ToString()](xref:System.Xml.Linq.XNode.ToString*?displayProperty=nameWithType) If the method doesn't take as an argument, then the method will format (indent) the serialized XML. In this case, all insignificant white space in the XML tree is discarded. diff --git a/docs/standard/linq/program-nodes.md b/docs/standard/linq/program-nodes.md index 933bb55aed526..c9c7b45a422c1 100644 --- a/docs/standard/linq/program-nodes.md +++ b/docs/standard/linq/program-nodes.md @@ -14,7 +14,7 @@ LINQ to XML developers who need to write programs such as an XML editor, a trans ## Example: The `Parent` property values of the child nodes of XDocument are set to `null` -The property contains the parent , not the parent node. Child nodes of have no parent . Their parent is the document, so the property for those nodes is set to `null`. +The property contains the parent , not the parent node. Child nodes of have no parent . Their parent is the document, so the property for those nodes is set to `null`. The following example demonstrates this: @@ -173,7 +173,7 @@ AnAttribute="abc" IsNamespaceDeclaration:False ## Example: XPath axis methods don't return the child text nodes of XDocument -LINQ to XML allows for child text nodes of an , as long as the text nodes contain only white space. However, the XPath object model doesn't include white space as child nodes of a document, so when you iterate through the children of an using the axis, white space text nodes will be returned. However, when you iterate through the children of an using the XPath axis methods, white space text nodes won't be returned. +LINQ to XML allows for child text nodes of an , as long as the text nodes contain only white space. However, the XPath object model doesn't include white space as child nodes of a document, so when you iterate through the children of an using the axis, white space text nodes will be returned. However, when you iterate through the children of an using the XPath axis methods, white space text nodes won't be returned. ```csharp // Create a document with some white space child nodes of the document. diff --git a/docs/standard/linq/project-new-type.md b/docs/standard/linq/project-new-type.md index 531e081478e8c..46437e0101345 100644 --- a/docs/standard/linq/project-new-type.md +++ b/docs/standard/linq/project-new-type.md @@ -10,7 +10,7 @@ ms.topic: how-to # How to project a new type (LINQ to XML) -Other examples in this section have shown queries that return results as of , of `string`, and of `int`. These are common result types, but they're not appropriate for every scenario. In many cases, you'll want your queries to return an of some other type. +Other examples in this section have shown queries that return results as of , of `string`, and of `int`. These are common result types, but they're not appropriate for every scenario. In many cases, you'll want your queries to return an of some other type. ## Example: Define a new type and have the `select` statement create an instance of the type @@ -72,7 +72,7 @@ Public Class Program End Class ``` -This example uses the method that was introduced in the [How to retrieve a single child element](retrieve-single-child-element.md) article. It also uses casts to retrieve the values of the elements that are returned by the method. +This example uses the method that was introduced in the [How to retrieve a single child element](retrieve-single-child-element.md) article. It also uses casts to retrieve the values of the elements that are returned by the method. This example produces the following output: diff --git a/docs/standard/linq/project-object-graph.md b/docs/standard/linq/project-object-graph.md index e0675cea92df3..9e306a24e0b39 100644 --- a/docs/standard/linq/project-object-graph.md +++ b/docs/standard/linq/project-object-graph.md @@ -496,7 +496,7 @@ Sub Main() End Sub ``` -The result of the LINQ query is returned as an of `PurchaseOrderItem`. The items in the `PurchaseOrder` class are of type of `PurchaseOrderItem`. The code uses the extension method to create a collection from the results of the query. +The result of the LINQ query is returned as an of `PurchaseOrderItem`. The items in the `PurchaseOrder` class are of type of `PurchaseOrderItem`. The code uses the extension method to create a collection from the results of the query. This example produces the following output: @@ -539,5 +539,5 @@ ShipDate: 5/21/1999 ## See also -- -- +- +- diff --git a/docs/standard/linq/query-linq-xml-xpath.md b/docs/standard/linq/query-linq-xml-xpath.md index f2392cb6673d4..c0d88188e9f5f 100644 --- a/docs/standard/linq/query-linq-xml-xpath.md +++ b/docs/standard/linq/query-linq-xml-xpath.md @@ -17,7 +17,7 @@ This article introduces the extension methods that enable you to query an XML tr ## Example -The following example creates a small XML tree and uses to select a set of elements. +The following example creates a small XML tree and uses to select a set of elements. ```csharp XElement root = new XElement("Root", diff --git a/docs/standard/linq/query-xdocument-vs-query-xelement.md b/docs/standard/linq/query-xdocument-vs-query-xelement.md index eae864a7c9d41..318ecb646f401 100644 --- a/docs/standard/linq/query-xdocument-vs-query-xelement.md +++ b/docs/standard/linq/query-xdocument-vs-query-xelement.md @@ -10,15 +10,15 @@ ms.assetid: 46221ff5-62ee-4de8-93ba-66465facb5c1 # Query an `XDocument` vs. query an `XElement` (LINQ to XML) -The query you write when you load a document via differs slightly from what you write when you load via . +The query you write when you load a document via differs slightly from what you write when you load via . ## Comparison of `XDocument.Load` and `XElement.Load` -When you load an XML document into an via , the at the root of the XML tree contains the root element of the loaded document. However, when you load the same XML document into an via , the root of the tree is an node, and the root element of the loaded document is the one allowed child node of the . The LINQ to XML axes operate relative to the root node. +When you load an XML document into an via , the at the root of the XML tree contains the root element of the loaded document. However, when you load the same XML document into an via , the root of the tree is an node, and the root element of the loaded document is the one allowed child node of the . The LINQ to XML axes operate relative to the root node. ## Example: Load an XML tree using `XElement.Load`, then query for child elements -This first example loads an XML tree using . It then queries for the child elements of the root of the tree. +This first example loads an XML tree using . It then queries for the child elements of the root of the tree. ```csharp // Create a simple document and write it to a file @@ -122,7 +122,7 @@ Querying tree loaded with XDocument.Load Notice that the same query returned the one `Root` node instead of the three child nodes. -One approach to dealing with this is to use the property before accessing the axes methods, as follows: +One approach to dealing with this is to use the property before accessing the axes methods, as follows: ```csharp // Create a simple document and write it to a file diff --git a/docs/standard/linq/read-write-encoded-document.md b/docs/standard/linq/read-write-encoded-document.md index 8f447876fda52..1ad0a38b73cd2 100644 --- a/docs/standard/linq/read-write-encoded-document.md +++ b/docs/standard/linq/read-write-encoded-document.md @@ -12,11 +12,11 @@ ms.topic: how-to To create an encoded XML document, you add an to the XML tree, setting the encoding to the desired code page name. -Any value returned by is a valid value. +Any value returned by is a valid value. -If you read an encoded document, the property will be set to the code page name. +If you read an encoded document, the property will be set to the code page name. -If you set to a valid code page name, LINQ to XML will serialize with the specified encoding. +If you set to a valid code page name, LINQ to XML will serialize with the specified encoding. ## Example: Create two documents that have different encoding and identify the encoding. @@ -112,4 +112,4 @@ Encoding of loaded document is:utf-16 ## See also -- +- diff --git a/docs/standard/linq/refactor-extension-method.md b/docs/standard/linq/refactor-extension-method.md index 3a3558574957a..55187cef13fb9 100644 --- a/docs/standard/linq/refactor-extension-method.md +++ b/docs/standard/linq/refactor-extension-method.md @@ -12,7 +12,7 @@ ms.topic: how-to This example builds on the previous example, [Retrieve the text of the paragraphs](retrieve-text-paragraphs.md), by refactoring the concatenation of strings using a pure function that's implemented as an extension method. -The previous example used the standard query operator to concatenate multiple strings into one string. However, it's more convenient to write an extension method to do this, because the resulting query is smaller and simpler. +The previous example used the standard query operator to concatenate multiple strings into one string. However, it's more convenient to write an extension method to do this, because the resulting query is smaller and simpler. ## Example: Retrieve the paragraphs, their styles, and their text diff --git a/docs/standard/linq/refactor-pure-functions.md b/docs/standard/linq/refactor-pure-functions.md index 9c05ff83c7e2c..4d4317afeef5f 100644 --- a/docs/standard/linq/refactor-pure-functions.md +++ b/docs/standard/linq/refactor-pure-functions.md @@ -106,7 +106,7 @@ Module Module1 End Module ``` -This version of the program produces the same output as the first version, because the `HyphenatedConcat` function has changed the value (state) of its first parameter by invoking the member function. Note that this alteration occurs despite the fact that `HyphenatedConcat` uses call-by-value parameter passing. +This version of the program produces the same output as the first version, because the `HyphenatedConcat` function has changed the value (state) of its first parameter by invoking the member function. Note that this alteration occurs despite the fact that `HyphenatedConcat` uses call-by-value parameter passing. > [!IMPORTANT] > For reference types, if you pass a parameter by value, it results in a copy of the reference to an object being passed. This copy is still associated with the same instance data as the original reference (until the reference variable is assigned to a new object). Call-by-reference isn't necessarily required for a function to modify a parameter. diff --git a/docs/standard/linq/remove-elements-attributes-nodes-xml-tree.md b/docs/standard/linq/remove-elements-attributes-nodes-xml-tree.md index 6e75bfba790a9..900df9b48b30e 100644 --- a/docs/standard/linq/remove-elements-attributes-nodes-xml-tree.md +++ b/docs/standard/linq/remove-elements-attributes-nodes-xml-tree.md @@ -12,7 +12,7 @@ ms.topic: how-to You can modify an XML tree, removing elements, attributes, and other types of nodes. -Removing a single element or a single attribute from an XML document is straightforward. However, when removing collections of elements or attributes, you should first materialize a collection into a list, and then delete the elements or attributes from the list. The best approach is to use the extension method to do this. +Removing a single element or a single attribute from an XML document is straightforward. However, when removing collections of elements or attributes, you should first materialize a collection into a list, and then delete the elements or attributes from the list. The best approach is to use the extension method to do this. The main reason to use this approach is that most of the collections you retrieve from an XML tree are yielded using deferred execution. If you don't first materialize them into a list, or if you don't use the extension methods, you may encounter a certain class of bugs. For more information, see [Mixed declarative/imperative code bugs](mixed-declarative-imperative-code-bugs.md). @@ -20,20 +20,20 @@ The following methods remove nodes and attributes from an XML tree. |Method|Description| |------------|-----------------| -||Remove an from its parent.| -||Remove the child nodes from an .| -||Remove content and attributes from an .| -||Remove the attributes of an .| -||Remove the attribute if you pass the value `null`.| -||Remove the child element if you pass the value `null`.| -||Remove an from its parent.| -||Remove every attribute or element in the source collection from its parent element.| +||Remove an from its parent.| +||Remove the child nodes from an .| +||Remove content and attributes from an .| +||Remove the attributes of an .| +||Remove the attribute if you pass the value `null`.| +||Remove the child element if you pass the value `null`.| +||Remove an from its parent.| +||Remove every attribute or element in the source collection from its parent element.| ## Example: Remove a single element, and remove a collection of elements in two ways -This example demonstrates three approaches to removing elements. First, it removes a single element. Second, it retrieves a collection of elements, materializes them using the operator, and then removes the collection. Finally, it retrieves a collection of elements and removes them using the extension method. +This example demonstrates three approaches to removing elements. First, it removes a single element. Second, it retrieves a collection of elements, materializes them using the operator, and then removes the collection. Finally, it retrieves a collection of elements and removes them using the extension method. -For more information on the operator, see [Converting Data Types (C#)](../../csharp/linq/standard-query-operators/converting-data-types.md) and [Converting Data Types (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/converting-data-types.md). +For more information on the operator, see [Converting Data Types (C#)](../../csharp/linq/standard-query-operators/converting-data-types.md) and [Converting Data Types (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/converting-data-types.md). ```csharp XElement root = XElement.Parse(@" diff --git a/docs/standard/linq/retrieve-collection-attributes.md b/docs/standard/linq/retrieve-collection-attributes.md index bfc4a8d2cb139..4e0073962c40d 100644 --- a/docs/standard/linq/retrieve-collection-attributes.md +++ b/docs/standard/linq/retrieve-collection-attributes.md @@ -10,7 +10,7 @@ ms.topic: how-to # How to retrieve a collection of attributes (LINQ to XML) -This article shows the use of the method to retrieve the attributes of an element. +This article shows the use of the method to retrieve the attributes of an element. ## Example: Iterate through the attributes of an element diff --git a/docs/standard/linq/retrieve-collection-elements.md b/docs/standard/linq/retrieve-collection-elements.md index 8b56c274c22d1..4e81ef2f0ba79 100644 --- a/docs/standard/linq/retrieve-collection-elements.md +++ b/docs/standard/linq/retrieve-collection-elements.md @@ -10,7 +10,7 @@ ms.topic: how-to # How to retrieve a collection of elements (LINQ to XML) -This article demonstrates the method, which retrieves a collection of the child elements of an element. +This article demonstrates the method, which retrieves a collection of the child elements of an element. ## Example: Iterate through the child elements of an element diff --git a/docs/standard/linq/retrieve-paragraphs-styles.md b/docs/standard/linq/retrieve-paragraphs-styles.md index f1ba5d80853e5..a4780dd96735b 100644 --- a/docs/standard/linq/retrieve-paragraphs-styles.md +++ b/docs/standard/linq/retrieve-paragraphs-styles.md @@ -28,7 +28,7 @@ xDoc.Root.Element(w + "body").Descendants(w + "p") xDoc.Root.... ``` -This expression is similar to the source of the query in the previous example, [Find the default paragraph style](find-default-paragraph-style.md). The main difference is that it uses the axis instead of the axis. The query uses the axis because in documents that have sections, the paragraphs won't be the direct children of the body element; rather, the paragraphs will be two levels down in the hierarchy. By using the axis, the code will work whether or not the document uses sections. +This expression is similar to the source of the query in the previous example, [Find the default paragraph style](find-default-paragraph-style.md). The main difference is that it uses the axis instead of the axis. The query uses the axis because in documents that have sections, the paragraphs won't be the direct children of the body element; rather, the paragraphs will be two levels down in the hierarchy. By using the axis, the code will work whether or not the document uses sections. ## Example: Use a `let` clause to determine the element that contains the style node @@ -42,7 +42,7 @@ let styleNode = para.Elements(w + "pPr").Elements(w + "pStyle").FirstOrDefault() Let styleNode As XElement = para...FirstOrDefault() ``` -The `let` clause (`Let` in the Visual Basic version) first uses the axis to find all elements named `pPr`, then uses the extension method to find all child elements named `pStyle`, and finally uses the standard query operator to convert the collection to a singleton. If the collection is empty, `styleNode` is set to `null` (`Nothing` in the Visual Basic version). This is a useful idiom to look for the `pStyle` descendant node. Note that if the `pPr` child node doesn't exist, the code doesn't fail by throwing an exception; instead, `styleNode` is set to `null` (`Nothing`), which is the desired behavior of this `let`(`Let`) clause. +The `let` clause (`Let` in the Visual Basic version) first uses the axis to find all elements named `pPr`, then uses the extension method to find all child elements named `pStyle`, and finally uses the standard query operator to convert the collection to a singleton. If the collection is empty, `styleNode` is set to `null` (`Nothing` in the Visual Basic version). This is a useful idiom to look for the `pStyle` descendant node. Note that if the `pPr` child node doesn't exist, the code doesn't fail by throwing an exception; instead, `styleNode` is set to `null` (`Nothing`), which is the desired behavior of this `let`(`Let`) clause. If there is no element, then `styleNode` is set to `null` (`Nothing`). diff --git a/docs/standard/linq/retrieve-shallow-value-element.md b/docs/standard/linq/retrieve-shallow-value-element.md index d6b29869938ee..fdf6a5b9d988b 100644 --- a/docs/standard/linq/retrieve-shallow-value-element.md +++ b/docs/standard/linq/retrieve-shallow-value-element.md @@ -11,7 +11,7 @@ ms.topic: how-to This article shows how to retrieve the shallow value of an element, which is the value of that element only, not including values of descendent elements. Retrieving the shallow value is useful when you want to select elements based on their content. -When you use casting or the property to retrieve an element value, the value includes the descendants. To retrieve the shallow value you can use the `ShallowValue` extension method, as shown in the following example. The example declares an extension method that retrieves the shallow value of an element. It then uses the extension method in a query to list all elements that contain a calculated value. +When you use casting or the property to retrieve an element value, the value includes the descendants. To retrieve the shallow value you can use the `ShallowValue` extension method, as shown in the following example. The example declares an extension method that retrieves the shallow value of an element. It then uses the extension method in a query to list all elements that contain a calculated value. ## Example: Use the `ShallowValue` extension method to retrieve the shallow value of an element diff --git a/docs/standard/linq/retrieve-single-attribute.md b/docs/standard/linq/retrieve-single-attribute.md index 45e9aa5c0a1be..a7c1095090e9f 100644 --- a/docs/standard/linq/retrieve-single-attribute.md +++ b/docs/standard/linq/retrieve-single-attribute.md @@ -12,11 +12,11 @@ ms.topic: how-to This article explains how to retrieve a single attribute of an element, given the attribute name. This is useful for writing query expressions where you want to find an element that has a particular attribute. -The method of the class returns the with the specified name. +The method of the class returns the with the specified name. ## Example: Retrieve attribute values, given the element and attribute names -The following example uses the method to create an element named `PhoneNumbers`. It then finds all the descendant elements named `Phone` and, for each, uses the method to obtain and output the value of the attribute named `type`: +The following example uses the method to create an element named `PhoneNumbers`. It then finds all the descendant elements named `Phone` and, for each, uses the method to obtain and output the value of the attribute named `type`: ```csharp XElement cust = new XElement("PhoneNumbers", diff --git a/docs/standard/linq/retrieve-single-child-element.md b/docs/standard/linq/retrieve-single-child-element.md index 31c85842f115a..681521bcc6731 100644 --- a/docs/standard/linq/retrieve-single-child-element.md +++ b/docs/standard/linq/retrieve-single-child-element.md @@ -7,7 +7,7 @@ ms.topic: how-to # How to retrieve a single child element (LINQ to XML) -This article explains how to retrieve a single child element, the first child element that has a specified name. In C# you do this with the method. In Visual Basic you do it with array indexer notation. +This article explains how to retrieve a single child element, the first child element that has a specified name. In C# you do this with the method. In Visual Basic you do it with array indexer notation. ## Example: Retrieve the first element that has a specified name diff --git a/docs/standard/linq/retrieve-text-paragraphs.md b/docs/standard/linq/retrieve-text-paragraphs.md index 29c8c6b17ab5e..2087e9b4e7af8 100644 --- a/docs/standard/linq/retrieve-text-paragraphs.md +++ b/docs/standard/linq/retrieve-text-paragraphs.md @@ -12,7 +12,7 @@ ms.topic: how-to This example builds on the previous example, [Retrieve the paragraphs and their styles](retrieve-paragraphs-styles.md). This new example retrieves the text of each paragraph as a string. -To retrieve the text, this example adds an additional query that iterates through the collection of anonymous types and projects a new collection of an anonymous type with the addition of a new member, `Text`. It uses the standard query operator to concatenate multiple strings into one string. +To retrieve the text, this example adds an additional query that iterates through the collection of anonymous types and projects a new collection of an anonymous type with the addition of a new member, `Text`. It uses the standard query operator to concatenate multiple strings into one string. This technique (that is, first projecting to a collection of an anonymous type, then using this collection to project to a new collection of an anonymous type) is a common and useful one. This query could have been written without projecting to the first anonymous type. However, because of lazy evaluation, doing so doesn't use much additional processing power. The technique does create more short-lived objects on the heap, but that doesn't substantially degrade performance. @@ -247,7 +247,7 @@ StyleName:Normal >< StyleName:Code >Hello World< ``` -The next article in this tutorial shows how to use an extension method, instead of , to concatenate multiple strings into a single string: +The next article in this tutorial shows how to use an extension method, instead of , to concatenate multiple strings into a single string: - [Refactor using an extension method](refactor-extension-method.md) diff --git a/docs/standard/linq/retrieve-value-attribute.md b/docs/standard/linq/retrieve-value-attribute.md index 0b8b1ed92ea31..1b8eee38bafd5 100644 --- a/docs/standard/linq/retrieve-value-attribute.md +++ b/docs/standard/linq/retrieve-value-attribute.md @@ -7,7 +7,7 @@ ms.topic: how-to # How to retrieve the value of an attribute (LINQ to XML) -This article shows how to obtain the value of attributes. There are two main ways: You can cast an to the desired type; the explicit conversion operator then converts the contents of the element or attribute to the specified type. Alternatively, you can use the property. However, casting is generally the better approach. If you cast the attribute to a nullable value type, the code is simpler to write when retrieving the value of an attribute that might or might not exist. For examples of this technique, see [How to retrieve the value of an element](retrieve-value-element.md). +This article shows how to obtain the value of attributes. There are two main ways: You can cast an to the desired type; the explicit conversion operator then converts the contents of the element or attribute to the specified type. Alternatively, you can use the property. However, casting is generally the better approach. If you cast the attribute to a nullable value type, the code is simpler to write when retrieving the value of an attribute that might or might not exist. For examples of this technique, see [How to retrieve the value of an element](retrieve-value-element.md). ## Example: Use a cast to retrieve the value of an attribute diff --git a/docs/standard/linq/retrieve-value-element.md b/docs/standard/linq/retrieve-value-element.md index 1ac2adc2af667..c2b36fcde4547 100644 --- a/docs/standard/linq/retrieve-value-element.md +++ b/docs/standard/linq/retrieve-value-element.md @@ -14,13 +14,13 @@ This article shows how to get the value of elements. There are two main ways to - Cast an or an to the desired type. The explicit conversion operator then converts the contents of the element or attribute to the specified type and assigns it to your variable. -- Use the or properties. You can also set the value using these properties. +- Use the or properties. You can also set the value using these properties. -With C#, casting is generally the better approach. If you cast the element or attribute to a nullable value type, the code is simpler to write when retrieving the value of an element (or attribute) that may not exist. The last example in this article demonstrates this. However, you can't set the contents of an element through casting, as you can through property. +With C#, casting is generally the better approach. If you cast the element or attribute to a nullable value type, the code is simpler to write when retrieving the value of an element (or attribute) that may not exist. The last example in this article demonstrates this. However, you can't set the contents of an element through casting, as you can through property. -With Visual Basic, the better approach is to use the property. +With Visual Basic, the better approach is to use the property. -## String cast example +## String cast example To retrieve the value of an element, cast the object to your desired type. You can cast an element to a string, as follows: @@ -43,9 +43,9 @@ This example produces the following output: Value of e:abcde ``` -## Integer cast example +## Integer cast example -You can also cast elements to types other than string. For example, if you have an element that contains an integer, you can cast it to `int`, as shown in the following code: +You can also cast elements to types other than string. For example, if you have an element that contains an integer, you can cast it to `int`, as shown in the following code: ```csharp XElement e = new XElement("Age", "44"); @@ -72,7 +72,7 @@ LINQ to XML provides the same cast operators for property to retrieve the contents of an element: +You can use the property to retrieve the contents of an element: ```csharp XElement e = new XElement("StringElement", "abcde"); @@ -95,7 +95,7 @@ Value of e:abcde ## Element might not exist example -Sometimes you try to retrieve the value of an element even though you're not sure if it exists. In this case, when you assign the casted element to a nullable reference type or nullable value type, if the element doesn't exist, the assigned variable is set to `null` (C#) or `nothing` (Visual Basic). The following code shows that when the element may not exist, it's easier to use casting than to use the property. +Sometimes you try to retrieve the value of an element even though you're not sure if it exists. In this case, when you assign the casted element to a nullable reference type or nullable value type, if the element doesn't exist, the assigned variable is set to `null` (C#) or `nothing` (Visual Basic). The following code shows that when the element may not exist, it's easier to use casting than to use the property. ```csharp XElement root = new XElement("Root", diff --git a/docs/standard/linq/scope-default-namespaces.md b/docs/standard/linq/scope-default-namespaces.md index 7f8852359e221..cbe71f15bef32 100644 --- a/docs/standard/linq/scope-default-namespaces.md +++ b/docs/standard/linq/scope-default-namespaces.md @@ -72,7 +72,7 @@ End of result set This example shows the creation of XML in a namespace, and a proper query. -In C#, the correct approach is to declare and initialize an object, and to use it when specifying objects. In this case, the argument to the method is an object. +In C#, the correct approach is to declare and initialize an object, and to use it when specifying objects. In this case, the argument to the method is an object. The correct approach when using Visual Basic is to declare and initialize a global default namespace. This places all XML properties in the default namespace. diff --git a/docs/standard/linq/serialize-files-textwriters-xmlwriters.md b/docs/standard/linq/serialize-files-textwriters-xmlwriters.md index 9a7fd12837d60..601e179faa597 100644 --- a/docs/standard/linq/serialize-files-textwriters-xmlwriters.md +++ b/docs/standard/linq/serialize-files-textwriters-xmlwriters.md @@ -11,16 +11,16 @@ You can serialize XML trees to a , a and , to a string by using the `ToString` method. -If you want to suppress formatting when serializing to a string, you can use the method. +If you want to suppress formatting when serializing to a string, you can use the method. The default behavior when serializing to a file is to format (indent) the resulting XML document. When you indent, the insignificant white space in the XML tree isn't preserved. To serialize with formatting, use one of the overloads of the following methods that don't take as an argument: -- -- +- +- If you want the option not to indent and to preserve the insignificant white space in the XML tree, use one of the overloads of the following methods that takes as an argument: -- -- +- +- For examples, see the appropriate reference article. diff --git a/docs/standard/linq/serialize-xml-declaration.md b/docs/standard/linq/serialize-xml-declaration.md index efd8e95a9f482..69e896641986c 100644 --- a/docs/standard/linq/serialize-xml-declaration.md +++ b/docs/standard/linq/serialize-xml-declaration.md @@ -12,7 +12,7 @@ ms.topic: how-to This article describes how to control whether an XML declaration is generated when you serialize XML in C# or Visual Basic. -Serializing to a or a using the method or the method generates an XML declaration. When you serialize to an , the writer settings (specified in an object) determine whether an XML declaration is generated. +Serializing to a or a using the method or the method generates an XML declaration. When you serialize to an , the writer settings (specified in an object) determine whether an XML declaration is generated. If you're serializing to a string using the `ToString` method, the resulting XML won't include an XML declaration. diff --git a/docs/standard/linq/serialize-xmlreader-invoke-xslt.md b/docs/standard/linq/serialize-xmlreader-invoke-xslt.md index 59b8dd47080dd..e53614a046689 100644 --- a/docs/standard/linq/serialize-xmlreader-invoke-xslt.md +++ b/docs/standard/linq/serialize-xmlreader-invoke-xslt.md @@ -10,7 +10,7 @@ ms.topic: how-to # Serialize to an XmlReader (invoke XSLT) (LINQ to XML) -When you use the interoperability capabilities of LINQ to XML, you can use to create an . The module that reads from this reads the nodes from the XML tree and processes them accordingly. +When you use the interoperability capabilities of LINQ to XML, you can use to create an . The module that reads from this reads the nodes from the XML tree and processes them accordingly. ## Example: Invoke an XSLT transformation diff --git a/docs/standard/linq/statically-compiled-queries.md b/docs/standard/linq/statically-compiled-queries.md index 094192accd170..96d3aa8e886a7 100644 --- a/docs/standard/linq/statically-compiled-queries.md +++ b/docs/standard/linq/statically-compiled-queries.md @@ -62,7 +62,7 @@ For Each el In list1 Next ``` -The method is an extension method. For more information, see [Extension Methods (C# Programming Guide)](../../csharp/programming-guide/classes-and-structs/extension-methods.md). Because is an extension method, the query above is compiled as though it were written as follows: +The method is an extension method. For more information, see [Extension Methods (C# Programming Guide)](../../csharp/programming-guide/classes-and-structs/extension-methods.md). Because is an extension method, the query above is compiled as though it were written as follows: ```csharp XDocument po = XDocument.Load("PurchaseOrders.xml"); @@ -118,7 +118,7 @@ reader.Close() This query returns the same output as the examples that use LINQ to XML; the only difference is that LINQ to XML indents the printed XML, whereas doesn't. -However, the approach generally doesn't perform as well as LINQ to XML, because the method must do the following every time it's called: +However, the approach generally doesn't perform as well as LINQ to XML, because the method must do the following every time it's called: - Parse the string that contains the XPath expression, breaking the string into tokens. - Validate the tokens to make sure that the XPath expression is valid. diff --git a/docs/standard/linq/stream-xml-fragments-access-header-information.md b/docs/standard/linq/stream-xml-fragments-access-header-information.md index 259e977e7a1d3..5c046ecce332f 100644 --- a/docs/standard/linq/stream-xml-fragments-access-header-information.md +++ b/docs/standard/linq/stream-xml-fragments-access-header-information.md @@ -14,9 +14,9 @@ Sometimes you have to read arbitrarily large XML files, and write your applicati One option is to write your application using . However, you might want to use LINQ to query the XML tree. If so, you can write your own custom axis method. For more information, see [How to write a LINQ to XML axis method](write-linq-xml-axis-method.md). -To write your own axis method, you write a small method that uses the to read nodes until it reaches one of the nodes in which you're interested. The method then calls , which reads from the and instantiates an XML fragment. It then yields each fragment through `yield return` to the method that's enumerating your custom axis method. You can then write LINQ queries on your custom axis method. +To write your own axis method, you write a small method that uses the to read nodes until it reaches one of the nodes in which you're interested. The method then calls , which reads from the and instantiates an XML fragment. It then yields each fragment through `yield return` to the method that's enumerating your custom axis method. You can then write LINQ queries on your custom axis method. -Streaming techniques are best applied in situations where you need to process the source document only once, and you can process the elements in document order. Certain standard query operators, such as , iterate their source, collect all of the data, sort it, and then finally yield the first item in the sequence. If you use a query operator that materializes its source before yielding the first item, you won't retain a small memory footprint. +Streaming techniques are best applied in situations where you need to process the source document only once, and you can process the elements in document order. Certain standard query operators, such as , iterate their source, collect all of the data, sort it, and then finally yield the first item in the sequence. If you use a query operator that materializes its source before yielding the first item, you won't retain a small memory footprint. ## Example: Implement and use a custom axis method that streams XML fragments from the file specified by a URI diff --git a/docs/standard/linq/stream-xml-fragments-xmlreader.md b/docs/standard/linq/stream-xml-fragments-xmlreader.md index cdaa877cb0323..61ec1de990eff 100644 --- a/docs/standard/linq/stream-xml-fragments-xmlreader.md +++ b/docs/standard/linq/stream-xml-fragments-xmlreader.md @@ -12,9 +12,9 @@ ms.topic: how-to When you have to process large XML files, it might not be feasible to load the whole XML tree into memory. This article shows how to stream fragments using an in C# and Visual Basic. -One of the most effective ways to use an to read objects is to write your own custom axis method. An axis method typically returns a collection such as of , as shown in the example in this article. In the custom axis method, after you create the XML fragment by calling the method, return the collection using `yield return`. This provides deferred execution semantics to your custom axis method. +One of the most effective ways to use an to read objects is to write your own custom axis method. An axis method typically returns a collection such as of , as shown in the example in this article. In the custom axis method, after you create the XML fragment by calling the method, return the collection using `yield return`. This provides deferred execution semantics to your custom axis method. -When you create an XML tree from an object, the must be positioned on an element. The method doesn't return until it has read the close tag of the element. +When you create an XML tree from an object, the must be positioned on an element. The method doesn't return until it has read the close tag of the element. If you want to create a partial tree, you can instantiate an , position the reader on the node that you want to convert to an tree, and then create the object. diff --git a/docs/standard/linq/use-xslt-transform-xml-tree.md b/docs/standard/linq/use-xslt-transform-xml-tree.md index fa6d9c899cedb..9d8390cca82fc 100644 --- a/docs/standard/linq/use-xslt-transform-xml-tree.md +++ b/docs/standard/linq/use-xslt-transform-xml-tree.md @@ -116,5 +116,5 @@ This example produces the following output: ## See also -- -- +- +- diff --git a/docs/standard/linq/valid-content-xelement-xdocument-objects.md b/docs/standard/linq/valid-content-xelement-xdocument-objects.md index 8fd3eb4c9f6b3..d97fecf0064bd 100644 --- a/docs/standard/linq/valid-content-xelement-xdocument-objects.md +++ b/docs/standard/linq/valid-content-xelement-xdocument-objects.md @@ -10,7 +10,7 @@ This article describes the valid arguments that can be passed to constructors, a ## Valid types for the XElement constructor -Queries often evaluate to of or of . You can pass collections of or objects to the constructor. That's why it's convenient to pass the results of a query as content into methods and constructors that you use to populate XML trees. +Queries often evaluate to of or of . You can pass collections of or objects to the constructor. That's why it's convenient to pass the results of a query as content into methods and constructors that you use to populate XML trees. When adding simple content, various types can be passed to this method, including: @@ -23,16 +23,16 @@ When adding simple content, various types can be passed to this method, includin - - - Any type that implements `Object.ToString`. -- Any type that implements . +- Any type that implements . When adding complex content, various types can be passed to this method, including: - - - -- Any type that implements +- Any type that implements -If an object implements , the collection in the object is enumerated, and all items in the collection are added. If the collection contains or objects, each item in the collection is added separately. If the collection contains text (or objects that are converted to text), the text in the collection is concatenated and added as a single text node. +If an object implements , the collection in the object is enumerated, and all items in the collection are added. If the collection contains or objects, each item in the collection is added separately. If the collection contains text (or objects that are converted to text), the text in the collection is concatenated and added as a single text node. If content is `null`, nothing is added. When passing a collection, items in the collection can be `null`. A `null` item in the collection has no effect on the tree. @@ -46,7 +46,7 @@ Attributes and simple content can't be added to a document. There aren't many scenarios that require you to create an . Instead, you can usually create your XML trees with an root node. Unless you have a specific requirement to create a document (for example, because you have to create processing instructions and comments at the top level, or you have to support document types), it's often more convenient to use as your root node. -Valid types for the constructor include the following: +Valid types for the constructor include the following: - Zero or one objects. The document types must come before the element. - Zero or one element. @@ -60,16 +60,16 @@ The following methods allow you to add child content to an |Constructs an .| -||Constructs a .| -||Adds to the end of the child content of the or .| -||Adds content after the .| -||Adds content before the .| -||Adds content at the beginning of the child content of the .| -||Replaces all content (child nodes and attributes) of an .| -||Replaces the attributes of an .| -||Replaces the children nodes with new content.| -||Replaces a node with new content.| +||Constructs an .| +||Constructs a .| +||Adds to the end of the child content of the or .| +||Adds content after the .| +||Adds content before the .| +||Adds content at the beginning of the child content of the .| +||Replaces all content (child nodes and attributes) of an .| +||Replaces the attributes of an .| +||Replaces the children nodes with new content.| +||Replaces a node with new content.| ## See also diff --git a/docs/standard/linq/validate-xsd.md b/docs/standard/linq/validate-xsd.md index 617e66fafbf00..d0d03dec46c1f 100644 --- a/docs/standard/linq/validate-xsd.md +++ b/docs/standard/linq/validate-xsd.md @@ -10,7 +10,7 @@ ms.topic: how-to # How to validate using XSD (LINQ to XML) -The namespace contains extension methods that make it easy to validate an XML tree against an XML Schema Definition Language (XSD) file. For more information, see the method documentation. +The namespace contains extension methods that make it easy to validate an XML tree against an XML Schema Definition Language (XSD) file. For more information, see the method documentation. ## Example: Validate XDocument objects against an XmlSchemaSet @@ -198,5 +198,5 @@ custOrdDoc did not validate ## See also -- +- - [XML trees](functional-construction.md) diff --git a/docs/standard/linq/work-dictionaries-linq-xml.md b/docs/standard/linq/work-dictionaries-linq-xml.md index 3265e8fa1b621..0f31b7607d970 100644 --- a/docs/standard/linq/work-dictionaries-linq-xml.md +++ b/docs/standard/linq/work-dictionaries-linq-xml.md @@ -10,11 +10,11 @@ ms.assetid: 57bcefe3-8433-4d3b-935a-511c9bcbdfa8 # How to work with dictionaries using LINQ to XML -It's often convenient to convert data structures of various kinds to XML, and then from XML to other data structures. This article shows a conversion of a to XML and back. +It's often convenient to convert data structures of various kinds to XML, and then from XML to other data structures. This article shows a conversion of a to XML and back. ## Example: Create a Dictionary and convert its contents to XML -This first example creates a , and then converts it to XML. +This first example creates a , and then converts it to XML. This C# version of the example uses a form of functional construction in which a query projects new objects, and the resulting collection is passed as an argument to the constructor of the Root object. diff --git a/docs/standard/linq/write-queries-complex-filtering.md b/docs/standard/linq/write-queries-complex-filtering.md index 2dadf866ee7dd..cdb18b27b7052 100644 --- a/docs/standard/linq/write-queries-complex-filtering.md +++ b/docs/standard/linq/write-queries-complex-filtering.md @@ -116,8 +116,8 @@ This example produces the following output: ## See also -- -- +- +- - [Projection Operations (C#)](../../csharp/linq/standard-query-operators/projection-operations.md) - [Quantifier Operations (C#)](../../csharp/linq/standard-query-operators/quantifier-operations.md) - [XML Child Axis Property (Visual Basic)](../../visual-basic/language-reference/xml-axis/xml-child-axis-property.md) diff --git a/docs/standard/linq/write-query-finds-elements-based-context.md b/docs/standard/linq/write-query-finds-elements-based-context.md index edab894adfd71..458ad37a8a492 100644 --- a/docs/standard/linq/write-query-finds-elements-based-context.md +++ b/docs/standard/linq/write-query-finds-elements-based-context.md @@ -172,8 +172,8 @@ id = 6 ## See also -- -- -- -- +- +- +- +- - [Basic Queries (LINQ to XML) (Visual Basic)](./find-element-specific-attribute.md) diff --git a/docs/standard/linq/xelement-class-overview.md b/docs/standard/linq/xelement-class-overview.md index 4ea10cb1414b0..fea79be30995a 100644 --- a/docs/standard/linq/xelement-class-overview.md +++ b/docs/standard/linq/xelement-class-overview.md @@ -28,8 +28,8 @@ You can construct XML trees in different ways, including the following: - You can construct an XML tree in code. For more information, see [XML trees](functional-construction.md). - You can parse XML from various sources, including a , text files, or a Web address (URL). For more information, see [Parse XML](parse-string.md). -- You can use an to populate the tree. For more information, see . -- If you have a module that can write content to an , you can use the method to create a writer, pass the writer to the module, and then use the content that's written to the to populate the XML tree. +- You can use an to populate the tree. For more information, see . +- If you have a module that can write content to an , you can use the method to create a writer, pass the writer to the module, and then use the content that's written to the to populate the XML tree. The following example creates a tree. The C# version uses nested element creations. You can use the same technique in Visual Basic, but this example uses XML literals. diff --git a/docs/standard/mef/attributed-programming-model-overview-mef.md b/docs/standard/mef/attributed-programming-model-overview-mef.md index 62cae4db7b0c3..b02014dc573f7 100644 --- a/docs/standard/mef/attributed-programming-model-overview-mef.md +++ b/docs/standard/mef/attributed-programming-model-overview-mef.md @@ -167,7 +167,7 @@ public class MyClass } ``` -For more information about how to use of the `Func` object, see . +For more information about how to use of the `Func` object, see . diff --git a/docs/standard/mef/index.md b/docs/standard/mef/index.md index 2f1ac8255a3ec..6b1959b812e43 100644 --- a/docs/standard/mef/index.md +++ b/docs/standard/mef/index.md @@ -132,7 +132,7 @@ private Program() } ``` -The call to tells the composition container to compose a specific set of parts, in this case the current instance of `Program`. At this point, however, nothing will happen, since `Program` has no imports to fill. +The call to tells the composition container to compose a specific set of parts, in this case the current instance of `Program`. At this point, however, nothing will happen, since `Program` has no imports to fill. ## Imports and Exports with attributes @@ -240,7 +240,7 @@ Public Property operations As IEnumerable(Of Lazy(Of IOperation, IOperationData) IEnumerable> operations; ``` - is a type provided by MEF to hold indirect references to exports. Here, in addition to the exported object itself, you also get *export metadata*, or information that describes the exported object. Each contains an `IOperation` object, representing an actual operation, and an `IOperationData` object, representing its metadata. + is a type provided by MEF to hold indirect references to exports. Here, in addition to the exported object itself, you also get *export metadata*, or information that describes the exported object. Each contains an `IOperation` object, representing an actual operation, and an `IOperationData` object, representing its metadata. Add the following simple interfaces to the module or `SimpleCalculator` namespace: @@ -360,7 +360,7 @@ public String Calculate(string input) } ``` -The initial steps parse the input string into left and right operands and an operator character. In the `foreach` loop, every member of the `operations` collection is examined. These objects are of type , and their metadata values and exported object can be accessed with the property and the property respectively. In this case, if the `Symbol` property of the `IOperationData` object is discovered to be a match, the calculator calls the `Operate` method of the `IOperation` object and returns the result. +The initial steps parse the input string into left and right operands and an operator character. In the `foreach` loop, every member of the `operations` collection is examined. These objects are of type , and their metadata values and exported object can be accessed with the property and the property respectively. In this case, if the `Symbol` property of the `IOperationData` object is discovered to be a match, the calculator calls the `Operate` method of the `IOperation` object and returns the result. To complete the calculator, you also need a helper method that returns the position of the first non-digit character in a string. Add the following helper method to the `MySimpleCalculator` class: diff --git a/docs/standard/memory-and-spans/index.md b/docs/standard/memory-and-spans/index.md index 9c5e8148153df..23a189090dfa2 100644 --- a/docs/standard/memory-and-spans/index.md +++ b/docs/standard/memory-and-spans/index.md @@ -14,34 +14,34 @@ helpviewer_keywords: The types include: -- , a type that's used to access a contiguous region of memory. A instance can be backed by an array of type `T`, a buffer allocated with [stackalloc](../../csharp/language-reference/operators/stackalloc.md), or a pointer to unmanaged memory. Because it has to be allocated on the stack, it has a number of restrictions. For example, a field in a class cannot be of type , nor can span be used in asynchronous operations. +- , a type that's used to access a contiguous region of memory. A instance can be backed by an array of type `T`, a buffer allocated with [stackalloc](../../csharp/language-reference/operators/stackalloc.md), or a pointer to unmanaged memory. Because it has to be allocated on the stack, it has a number of restrictions. For example, a field in a class cannot be of type , nor can span be used in asynchronous operations. -- , an immutable version of the structure. Instances can be also backed by a . +- , an immutable version of the structure. Instances can be also backed by a . -- , a wrapper over a contiguous region of memory. A instance can be backed by an array of type `T` or a memory manager. As it can be stored on the managed heap, has none of the limitations of . +- , a wrapper over a contiguous region of memory. A instance can be backed by an array of type `T` or a memory manager. As it can be stored on the managed heap, has none of the limitations of . -- , an immutable version of the structure. Instances can also be backed by a . +- , an immutable version of the structure. Instances can also be backed by a . -- , which allocates strongly typed blocks of memory from a memory pool to an owner. instances can be rented from the pool by calling and released back to the pool by calling . +- , which allocates strongly typed blocks of memory from a memory pool to an owner. instances can be rented from the pool by calling and released back to the pool by calling . -- , which represents the owner of a block of memory and controls its lifetime management. +- , which represents the owner of a block of memory and controls its lifetime management. -- , an abstract base class that can be used to replace the implementation of so that can be backed by additional types, such as safe handles. is intended for advanced scenarios. +- , an abstract base class that can be used to replace the implementation of so that can be backed by additional types, such as safe handles. is intended for advanced scenarios. -- , a wrapper for a particular number of array elements starting at a particular index. +- , a wrapper for a particular number of array elements starting at a particular index. -- , a collection of extension methods for converting strings, arrays, and array segments to blocks. +- , a collection of extension methods for converting strings, arrays, and array segments to blocks. For more information, see the namespace. ## Working with memory and span -Because the memory-related and span-related types are typically used to store data in a processing pipeline, it's important that you follow a set of best practices when using , , and related types. These best practices are documented in [Memory\ and Span\ usage guidelines](memory-t-usage-guidelines.md). +Because the memory-related and span-related types are typically used to store data in a processing pipeline, it's important that you follow a set of best practices when using , , and related types. These best practices are documented in [Memory\ and Span\ usage guidelines](memory-t-usage-guidelines.md). ## See also -- -- -- -- +- +- +- +- - diff --git a/docs/standard/memory-and-spans/memory-t-usage-guidelines.md b/docs/standard/memory-and-spans/memory-t-usage-guidelines.md index 158385eee37e3..4ccf14764ace9 100644 --- a/docs/standard/memory-and-spans/memory-t-usage-guidelines.md +++ b/docs/standard/memory-and-spans/memory-t-usage-guidelines.md @@ -8,9 +8,9 @@ helpviewer_keywords: --- # Memory\ and Span\ usage guidelines -.NET includes a number of types that represent an arbitrary contiguous region of memory. and are lightweight memory buffers that wrap references to managed or unmanaged memory. Because these types can only be stored on the stack, they're unsuitable for scenarios such as asynchronous method calls. To address this problem, .NET 2.1 added some additional types, including , , , and . Like , and its related types can be backed by both managed and unmanaged memory. Unlike , can be stored on the managed heap. +.NET includes a number of types that represent an arbitrary contiguous region of memory. and are lightweight memory buffers that wrap references to managed or unmanaged memory. Because these types can only be stored on the stack, they're unsuitable for scenarios such as asynchronous method calls. To address this problem, .NET 2.1 added some additional types, including , , , and . Like , and its related types can be backed by both managed and unmanaged memory. Unlike , can be stored on the managed heap. -Both and are wrappers over buffers of structured data that can be used in pipelines. That is, they're designed so that some or all of the data can be efficiently passed to components in the pipeline, which can process them and optionally modify the buffer. Because and its related types can be accessed by multiple components or by multiple threads, it's important to follow some standard usage guidelines to produce robust code. +Both and are wrappers over buffers of structured data that can be used in pipelines. That is, they're designed so that some or all of the data can be efficiently passed to components in the pipeline, which can process them and optionally modify the buffer. Because and its related types can be accessed by multiple components or by multiple threads, it's important to follow some standard usage guidelines to produce robust code. ## Owners, consumers, and lifetime management @@ -21,7 +21,7 @@ Buffers can be passed around between APIs and can sometimes be accessed from mul - **Consumption**. The consumer of a buffer instance is allowed to use the buffer instance by reading from it and possibly writing to it. Buffers can have one consumer at a time unless some external synchronization mechanism is provided. The active consumer of a buffer isn't necessarily the buffer's owner. - **Lease**. The lease is the length of time that a particular component is allowed to be the consumer of the buffer. -The following pseudo-code example illustrates these three concepts. `Buffer` in the pseudo-code represents a or buffer of type . The `Main` method instantiates the buffer, calls the `WriteInt32ToBuffer` method to write the string representation of an integer to the buffer, and then calls the `DisplayBufferToConsole` method to display the value of the buffer. +The following pseudo-code example illustrates these three concepts. `Buffer` in the pseudo-code represents a or buffer of type . The `Main` method instantiates the buffer, calls the `WriteInt32ToBuffer` method to write the string representation of an integer to the buffer, and then calls the `DisplayBufferToConsole` method to display the value of the buffer. ```csharp using System; @@ -52,7 +52,7 @@ class Program } ``` -The `Main` method creates the buffer and so is its owner. Therefore, `Main` is responsible for destroying the buffer when it's no longer in use. The pseudo-code illustrates this by calling a `Destroy` method on the buffer. (Neither nor actually has a `Destroy` method. You'll see actual code examples later in this article.) +The `Main` method creates the buffer and so is its owner. Therefore, `Main` is responsible for destroying the buffer when it's no longer in use. The pseudo-code illustrates this by calling a `Destroy` method on the buffer. (Neither nor actually has a `Destroy` method. You'll see actual code examples later in this article.) The buffer has two consumers, `WriteInt32ToBuffer` and `DisplayBufferToConsole`. There is only one consumer at a time (first `WriteInt32ToBuffer`, then `DisplayBufferToConsole`), and neither of the consumers owns the buffer. Note also that "consumer" in this context doesn't imply a read-only view of the buffer; consumers can modify the buffer's contents, as `WriteInt32ToBuffer` does, if given a read/write view of the buffer. @@ -65,7 +65,7 @@ As the [Owners, consumers, and lifetime management](#owners-consumers-and-lifeti - A model that supports single ownership. A buffer has a single owner for its entire lifetime. - A model that supports ownership transfer. Ownership of a buffer can be transferred from its original owner (its creator) to another component, which then becomes responsible for the buffer's lifetime management. That owner can in turn transfer ownership to another component, and so on. -You use the interface to explicitly manage the ownership of a buffer. supports both ownership models. The component that has an reference owns the buffer. The following example uses an instance to reflect the ownership of a buffer. +You use the interface to explicitly manage the ownership of a buffer. supports both ownership models. The component that has an reference owns the buffer. The following example uses an instance to reflect the ownership of a buffer. :::code language="csharp" source="snippets/usage-guidelines/owner/owner.cs"::: @@ -75,32 +75,32 @@ You can also write this example with the [`using` statement](../../csharp/langua In this code: -- The `Main` method holds the reference to the instance, so the `Main` method is the owner of the buffer. -- The `WriteInt32ToBuffer` and `DisplayBufferToConsole` methods accept as a public API. Therefore, they are consumers of the buffer. These methods consume the buffer one at a time. +- The `Main` method holds the reference to the instance, so the `Main` method is the owner of the buffer. +- The `WriteInt32ToBuffer` and `DisplayBufferToConsole` methods accept as a public API. Therefore, they are consumers of the buffer. These methods consume the buffer one at a time. -Although the `WriteInt32ToBuffer` method is intended to write a value to the buffer, the `DisplayBufferToConsole` method isn't intended to. To reflect this, it could have accepted an argument of type . For more information on , see [Rule #2: Use ReadOnlySpan\ or ReadOnlyMemory\ if the buffer should be read-only](#rule-2). +Although the `WriteInt32ToBuffer` method is intended to write a value to the buffer, the `DisplayBufferToConsole` method isn't intended to. To reflect this, it could have accepted an argument of type . For more information on , see [Rule #2: Use ReadOnlySpan\ or ReadOnlyMemory\ if the buffer should be read-only](#rule-2). ### "Ownerless" Memory\ instances -You can create a instance without using . In this case, ownership of the buffer is implicit rather than explicit, and only the single-owner model is supported. You can do this by: +You can create a instance without using . In this case, ownership of the buffer is implicit rather than explicit, and only the single-owner model is supported. You can do this by: -- Calling one of the constructors directly, passing in a `T[]`, as the following example does. +- Calling one of the constructors directly, passing in a `T[]`, as the following example does. - Calling the [String.AsMemory](xref:System.MemoryExtensions.AsMemory(System.String)) extension method to produce a `ReadOnlyMemory` instance. :::code language="csharp" source="snippets/usage-guidelines/ownerless/ownerless.cs"::: -The method that initially creates the instance is the implicit owner of the buffer. Ownership cannot be transferred to any other component because there is no instance to facilitate the transfer. (As an alternative, you can also imagine that the runtime's garbage collector owns the buffer, and all methods just consume the buffer.) +The method that initially creates the instance is the implicit owner of the buffer. Ownership cannot be transferred to any other component because there is no instance to facilitate the transfer. (As an alternative, you can also imagine that the runtime's garbage collector owns the buffer, and all methods just consume the buffer.) ## Usage guidelines -Because a memory block is owned but is intended to be passed to multiple components, some of which might operate upon a particular memory block simultaneously, it's important to establish guidelines for using both and . Guidelines are necessary because it's possible for a component to: +Because a memory block is owned but is intended to be passed to multiple components, some of which might operate upon a particular memory block simultaneously, it's important to establish guidelines for using both and . Guidelines are necessary because it's possible for a component to: - Retain a reference to a memory block after its owner has released it. - Operate on a buffer at the same time that another component is operating on it, in the process corrupting the data in the buffer. -While the stack-allocated nature of optimizes performance and makes the preferred type for operating on a memory block, it also subjects to some major restrictions. It's important to know when to use a and when to use . +While the stack-allocated nature of optimizes performance and makes the preferred type for operating on a memory block, it also subjects to some major restrictions. It's important to know when to use a and when to use . -The following are our recommendations for successfully using and its related types. Guidance that applies to and also applies to and unless noted otherwise. +The following are our recommendations for successfully using and its related types. Guidance that applies to and also applies to and unless noted otherwise. - [Rule #1: For a synchronous API, use `Span` instead of `Memory` as a parameter if possible](#rule-1-for-a-synchronous-api-use-spant-instead-of-memoryt-as-a-parameter-if-possible) - [Rule #2: Use `ReadOnlySpan` or `ReadOnlyMemory` if the buffer should be read-only](#rule-2-use-readonlyspant-or-readonlymemoryt-if-the-buffer-should-be-read-only) @@ -115,11 +115,11 @@ The following are our recommendations for successfully using instead of Memory\ as a parameter if possible - is more versatile than and can represent a wider variety of contiguous memory buffers. also offers better performance than . Finally, you can use the property to convert a instance to a , although Span\-to-Memory\ conversion isn't possible. So if your callers happen to have a instance, they'll be able to call your methods with parameters anyway. + is more versatile than and can represent a wider variety of contiguous memory buffers. also offers better performance than . Finally, you can use the property to convert a instance to a , although Span\-to-Memory\ conversion isn't possible. So if your callers happen to have a instance, they'll be able to call your methods with parameters anyway. -Using a parameter of type instead of type also helps you write a correct consuming method implementation. You'll automatically get compile-time checks to ensure that you're not attempting to access the buffer beyond your method's lease (more on this later). +Using a parameter of type instead of type also helps you write a correct consuming method implementation. You'll automatically get compile-time checks to ensure that you're not attempting to access the buffer beyond your method's lease (more on this later). -Sometimes, you'll have to use a parameter instead of a parameter, even if you're fully synchronous. Perhaps an API that you depend on accepts only arguments. This is fine, but be aware of the tradeoffs involved when using synchronously. +Sometimes, you'll have to use a parameter instead of a parameter, even if you're fully synchronous. Perhaps an API that you depend on accepts only arguments. This is fine, but be aware of the tradeoffs involved when using synchronously. @@ -141,7 +141,7 @@ The `DisplayBufferToConsole` method now works with virtually every buffer type i ### Rule #3: If your method accepts Memory\ and returns `void`, you must not use the Memory\ instance after your method returns -This relates to the "lease" concept mentioned earlier. A void-returning method's lease on the instance begins when the method is entered, and it ends when the method exits. Consider the following example, which calls `Log` in a loop based on input from the console. +This relates to the "lease" concept mentioned earlier. A void-returning method's lease on the instance begins when the method is entered, and it ends when the method exits. Consider the following example, which calls `Log` in a loop based on input from the console. :::code language="csharp" source="snippets/usage-guidelines/void-returning/void-returning.cs"::: @@ -161,7 +161,7 @@ static void Log(ReadOnlyMemory message) } ``` -In this implementation, `Log` violates its lease because it still attempts to use the instance in the background after the original method has returned. The `Main` method could mutate the buffer while `Log` attempts to read from it, which could result in data corruption. +In this implementation, `Log` violates its lease because it still attempts to use the instance in the background after the original method has returned. The `Main` method could mutate the buffer while `Log` attempts to read from it, which could result in data corruption. There are several ways to resolve this: @@ -181,7 +181,7 @@ This is just the async variant of Rule #3. The `Log` method from the earlier exa Here, "terminal state" means that the task transitions to a completed, faulted, or canceled state. In other words, "terminal state" means "anything that would cause await to throw or to continue execution." -This guidance applies to methods that return , , , or any similar type. +This guidance applies to methods that return , , , or any similar type. ### Rule #5: If your constructor accepts Memory\ as a parameter, instance methods on the constructed object are assumed to be consumers of the Memory\ instance @@ -228,24 +228,24 @@ class Person ### Rule #7: If you have an IMemoryOwner\ reference, you must at some point dispose of it or transfer its ownership (but not both) -Since a instance may be backed by either managed or unmanaged memory, the owner must call `Dispose` on when work performed on the instance is complete. Alternatively, the owner may transfer ownership of the instance to a different component, at which point the acquiring component becomes responsible for calling `Dispose` at the appropriate time (more on this later). +Since a instance may be backed by either managed or unmanaged memory, the owner must call `Dispose` on when work performed on the instance is complete. Alternatively, the owner may transfer ownership of the instance to a different component, at which point the acquiring component becomes responsible for calling `Dispose` at the appropriate time (more on this later). -Failure to call the `Dispose` method on an instance may lead to unmanaged memory leaks or other performance degradation. +Failure to call the `Dispose` method on an instance may lead to unmanaged memory leaks or other performance degradation. -This rule also applies to code that calls factory methods like . The caller becomes the owner of the returned and is responsible for disposing of the instance when finished. +This rule also applies to code that calls factory methods like . The caller becomes the owner of the returned and is responsible for disposing of the instance when finished. ### Rule #8: If you have an IMemoryOwner\ parameter in your API surface, you are accepting ownership of that instance Accepting an instance of this type signals that your component intends to take ownership of this instance. Your component becomes responsible for proper disposal according to Rule #7. -Any component that transfers ownership of the instance to a different component should no longer use that instance after the method call completes. +Any component that transfers ownership of the instance to a different component should no longer use that instance after the method call completes. > [!IMPORTANT] -> If your constructor accepts as a parameter, its type should implement , and your method should call `Dispose` on the object. +> If your constructor accepts as a parameter, its type should implement , and your method should call `Dispose` on the object. ### Rule #9: If you're wrapping a synchronous p/invoke method, your API should accept Span\ as a parameter -According to Rule #1, is generally the correct type to use for synchronous APIs. You can pin instances via the [`fixed`](../../csharp/language-reference/statements/fixed.md) keyword, as in the following example. +According to Rule #1, is generally the correct type to use for synchronous APIs. You can pin instances via the [`fixed`](../../csharp/language-reference/statements/fixed.md) keyword, as in the following example. ```csharp using System.Runtime.InteropServices; @@ -285,7 +285,7 @@ public unsafe int ManagedWrapper(Span data) ### Rule #10: If you're wrapping an asynchronous p/invoke method, your API should accept Memory\ as a parameter -Since you cannot use the [`fixed`](../../csharp/language-reference/statements/fixed.md) keyword across asynchronous operations, you use the method to pin instances, regardless of the kind of contiguous memory the instance represents. The following example shows how to use this API to perform an asynchronous p/invoke call. +Since you cannot use the [`fixed`](../../csharp/language-reference/statements/fixed.md) keyword across asynchronous operations, you use the method to pin instances, regardless of the kind of contiguous memory the instance represents. The following example shows how to use this API to perform an asynchronous p/invoke call. ```csharp using System.Runtime.InteropServices; @@ -369,6 +369,6 @@ private class MyCompletedCallbackState ## See also -- -- -- +- +- +- diff --git a/docs/standard/native-interop/best-practices.md b/docs/standard/native-interop/best-practices.md index 325a0b0a3a0ea..cd407839455cd 100644 --- a/docs/standard/native-interop/best-practices.md +++ b/docs/standard/native-interop/best-practices.md @@ -22,7 +22,7 @@ The guidance in this section applies to all interop scenarios. - ✔️ DO prefer using function pointers and as opposed to `Delegate` types, when passing callbacks to unmanaged functions in C#. For more information, see . - ✔️ DO use `[In]` and `[Out]` attributes on array parameters. - ✔️ DO only use `[In]` and `[Out]` attributes on other types when the behavior you want differs from the default behavior. -- ✔️ CONSIDER using to pool your native array buffers. +- ✔️ CONSIDER using to pool your native array buffers. - ✔️ CONSIDER wrapping your P/Invoke declarations in a class with the same name and capitalization as your native library. - This allows your `[LibraryImport]` or `[DllImport]` attributes to use the C# `nameof` language feature to pass in the name of the native library and ensure that you didn't misspell the name of the native library. - ✔️ DO use `SafeHandle` handles to manage lifetime of objects that encapsulate unmanaged resources. For more information, see [Cleaning up unmanaged resources](../garbage-collection/unmanaged.md). @@ -49,7 +49,7 @@ A `string` is pinned and used directly by native code (rather than copied) when - The argument is explicitly marked as `[MarshalAs(UnmanagedType.LPWSTR)]`. - is . -❌ DON'T use `[Out] string` parameters. String parameters passed by value with the `[Out]` attribute can destabilize the runtime if the string is an interned string. See more information about string interning in the documentation for . +❌ DON'T use `[Out] string` parameters. String parameters passed by value with the `[Out]` attribute can destabilize the runtime if the string is an interned string. See more information about string interning in the documentation for . ✔️ CONSIDER `char[]` or `byte[]` arrays from an `ArrayPool` when native code is expected to fill a character buffer. This requires passing the argument as `[Out]`. @@ -446,7 +446,7 @@ The following table maps common symptoms to their likely cause and recommended f | Symptom | Likely cause | Fix | |---------|-------------|-----| -| | Library not found at runtime | Check library name, path, and platform. Use to test loading. On Linux, verify `LD_LIBRARY_PATH` or `rpath`. | +| | Library not found at runtime | Check library name, path, and platform. Use to test loading. On Linux, verify `LD_LIBRARY_PATH` or `rpath`. | | | Export name mismatch | Inspect native exports (`dumpbin /exports` on Windows, `nm -D` on Linux). Check for C++ name mangling (missing `extern "C"`). Set `EntryPoint` explicitly. | | | Signature mismatch, use-after-free, or missing pinning | Compare managed and native signatures. Check struct sizes with `Marshal.SizeOf()` vs native `sizeof`. Verify memory lifetime. Use a blittable signature to troubleshoot marshalling issue | | Silent data corruption | Wrong type size or encoding | Add boundary logging. Compare `Marshal.SizeOf()` to native `sizeof`. Test with known input/output pairs. | @@ -455,9 +455,9 @@ The following table maps common symptoms to their likely cause and recommended f ## Prevent delegate collection with `GC.KeepAlive` -When you use to convert a delegate to a function pointer, the garbage collector does **not** track the relationship between the returned pointer and the source delegate. If the delegate is eligible for collection before the native code finishes using the pointer, the application will crash. +When you use to convert a delegate to a function pointer, the garbage collector does **not** track the relationship between the returned pointer and the source delegate. If the delegate is eligible for collection before the native code finishes using the pointer, the application will crash. -Use to prevent collection: +Use to prevent collection: ```csharp var callback = new MyDelegate((level, msgPtr) => diff --git a/docs/standard/native-interop/custom-marshalling-source-generation.md b/docs/standard/native-interop/custom-marshalling-source-generation.md index 86e6678bf0ed2..17d8031f9cd49 100644 --- a/docs/standard/native-interop/custom-marshalling-source-generation.md +++ b/docs/standard/native-interop/custom-marshalling-source-generation.md @@ -177,7 +177,7 @@ To create a custom marshaller for a generic collection type, you can use the to a marshaller entry-point type to indicate that it's for contiguous collections. The marshaller entry-point type must have one more type parameter than the associated managed type. The last type parameter is a placeholder and will be filled in by the source generator with the unmanaged type for the collection's element type. -For example, you can specify custom marshalling for a . In the following code, `ListMarshaller` is both the entry point and the implementation. It conforms to one of the [marshaller shapes](./custom-marshaller-shapes.md) expected for custom marshalling of a collection. (Note that it's an incomplete example.) +For example, you can specify custom marshalling for a . In the following code, `ListMarshaller` is both the entry point and the implementation. It conforms to one of the [marshaller shapes](./custom-marshaller-shapes.md) expected for custom marshalling of a collection. (Note that it's an incomplete example.) ```csharp [ContiguousCollectionMarshaller] @@ -214,7 +214,7 @@ public unsafe static class ListMarshaller where TUnmanaged } ``` -The `ListMarshaller` in the example is a stateless collection marshaller that implements support for marshalling from managed to unmanaged and from unmanaged to managed for a . In the following P/Invoke example, `ListMarshaller` will be used to marshal the collection container for the parameter from managed to unmanaged and to marshal the collection container for the return value from unmanaged to managed. The source generator will generate code to copy the elements from the parameter `list` to the container provided by the marshaller. Since `int` is blittable, the elements themselves do not need to be marshalled. indicates that the `numValues` parameter should be used as the element count when marshalling the return value from unmanaged to managed. +The `ListMarshaller` in the example is a stateless collection marshaller that implements support for marshalling from managed to unmanaged and from unmanaged to managed for a . In the following P/Invoke example, `ListMarshaller` will be used to marshal the collection container for the parameter from managed to unmanaged and to marshal the collection container for the return value from unmanaged to managed. The source generator will generate code to copy the elements from the parameter `list` to the container provided by the marshaller. Since `int` is blittable, the elements themselves do not need to be marshalled. indicates that the `numValues` parameter should be used as the element count when marshalling the return value from unmanaged to managed. ```csharp [LibraryImport("nativelib")] diff --git a/docs/standard/native-interop/native-library-loading.md b/docs/standard/native-interop/native-library-loading.md index b6b55ce512b72..a6187902ca95e 100644 --- a/docs/standard/native-interop/native-library-loading.md +++ b/docs/standard/native-interop/native-library-loading.md @@ -8,7 +8,7 @@ ms.date: 03/14/2022 # Native library loading This article explains which paths the runtime searches when loading native libraries via P/Invoke. It also shows how to use -. +. ## Library name variations @@ -54,7 +54,7 @@ In this case, the library name variations are tried in the following order: ## Custom import resolver -In more complex scenarios, you can use to resolve DLL imports at runtime. In the following example, `nativedep` is resolved to `nativedep_avx2` if the CPU supports it. +In more complex scenarios, you can use to resolve DLL imports at runtime. In the following example, `nativedep` is resolved to `nativedep_avx2` if the CPU supports it. > [!TIP] > This functionality is only available in .NET Core 3.1 and .NET 5+. diff --git a/docs/standard/native-interop/preserve-sig.md b/docs/standard/native-interop/preserve-sig.md index 5422d6b46ee47..8de02fe55f9bd 100644 --- a/docs/standard/native-interop/preserve-sig.md +++ b/docs/standard/native-interop/preserve-sig.md @@ -50,7 +50,7 @@ public static extern int SHAutoCompleteHRESULT(IntPtr hwndEdit, SHAutoCompleteFl ## Manually handle `HRESULT` values -When calling a `PreserveSig` method that returns an `HRESULT`, you can use the method to throw the corresponding exception if the `HRESULT` indicates a failure. Similarly, when implementing a `PreserveSig` method, you can use the method to return the `HRESULT` that indicates a corresponding value for the exception. +When calling a `PreserveSig` method that returns an `HRESULT`, you can use the method to throw the corresponding exception if the `HRESULT` indicates a failure. Similarly, when implementing a `PreserveSig` method, you can use the method to return the `HRESULT` that indicates a corresponding value for the exception. ## Marshal HRESULTs as structs diff --git a/docs/standard/numerics.md b/docs/standard/numerics.md index 27429b23c232f..08b78e2b33090 100644 --- a/docs/standard/numerics.md +++ b/docs/standard/numerics.md @@ -73,11 +73,11 @@ The structure is | | 8 | ±1.7 × 10308 | Yes | | | | 16 | ±7.9228 x 1028 | No | | -The , , and types support special values that represent not-a-number and infinity. For example, the type provides the following values: , , and . You use the , , , and methods to test for these special values. +The , , and types support special values that represent not-a-number and infinity. For example, the type provides the following values: , , and . You use the , , , and methods to test for these special values. Each floating-point type supports a set of standard arithmetic operators. The class provides methods for a broader set of mathematical functions. .NET Core 2.0 and later includes the class, which provides methods that accept arguments of the type. -You can also work with the individual bits in , , and values by using the class. The structure has its own methods, and , for working with a decimal value's individual bits, as well as its own set of methods for performing some additional mathematical operations. +You can also work with the individual bits in , , and values by using the class. The structure has its own methods, and , for working with a decimal value's individual bits, as well as its own set of methods for performing some additional mathematical operations. The , , and types are intended to be used for values that, by their nature, are imprecise (for example, the distance between two stars) and for applications in which a high degree of precision and small rounding error is not required. Use the type for cases in which greater precision is required and rounding errors should be minimized. @@ -102,10 +102,10 @@ The .NET SIMD-enabled types include the following: - The type, which represents a vector that is used to encode three-dimensional physical rotations. -- The type, which represents a vector of a specified numeric type and provides a broad set of operators that benefit from SIMD support. The count of a instance is fixed, but its value depends on the CPU of the machine, on which code is executed. +- The type, which represents a vector of a specified numeric type and provides a broad set of operators that benefit from SIMD support. The count of a instance is fixed, but its value depends on the CPU of the machine, on which code is executed. > [!NOTE] - > The type is included with .NET Core and .NET 5+, but not .NET Framework. If you're using .NET Framework, install the [System.Numerics.Vectors](https://www.nuget.org/packages/System.Numerics.Vectors) NuGet package to get access to this type. + > The type is included with .NET Core and .NET 5+, but not .NET Framework. If you're using .NET Framework, install the [System.Numerics.Vectors](https://www.nuget.org/packages/System.Numerics.Vectors) NuGet package to get access to this type. The SIMD-enabled types are implemented in such a way that they can be used with non-SIMD-enabled hardware or JIT compilers. To take advantage of SIMD instructions, your 64-bit apps must be run by the runtime that uses the RyuJIT compiler, which is included in .NET Core and in .NET Framework 4.6 and later versions. It adds SIMD support when targeting 64-bit processors. diff --git a/docs/standard/parallel-programming/attached-and-detached-child-tasks.md b/docs/standard/parallel-programming/attached-and-detached-child-tasks.md index 97634d00a7d4e..00002a7c88c32 100644 --- a/docs/standard/parallel-programming/attached-and-detached-child-tasks.md +++ b/docs/standard/parallel-programming/attached-and-detached-child-tasks.md @@ -2,83 +2,83 @@ description: "Learn more about: Attached and Detached Child Tasks" title: "Attached and Detached Child Tasks" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "tasks, child tasks" ms.assetid: c95788bf-90a6-4e96-b7bc-58e36a228cc5 --- # Attached and Detached Child Tasks -A *child task* (or *nested task*) is a instance that is created in the user delegate of another task, which is known as the *parent task*. A child task can be either detached or attached. A *detached child task* is a task that executes independently of its parent. An *attached child task* is a nested task that is created with the option whose parent does not explicitly or by default prohibit it from being attached. A task may create any number of attached and detached child tasks, limited only by system resources. - - The following table lists the basic differences between the two kinds of child tasks. - -|Category|Detached child tasks|Attached child tasks| -|--------------|--------------------------|--------------------------| -|Parent waits for child tasks to complete.|No|Yes| -|Parent propagates exceptions thrown by child tasks.|No|Yes| -|Status of parent depends on status of child.|No|Yes| - - In most scenarios, we recommend that you use detached child tasks, because their relationships with other tasks are less complex. That is why tasks created inside parent tasks are detached by default, and you must explicitly specify the option to create an attached child task. - -## Detached child tasks - - Although a child task is created by a parent task, by default it is independent of the parent task. In the following example, a parent task creates one simple child task. If you run the example code multiple times, you may notice that the output from the example differs from that shown, and also that the output may change each time you run the code. This occurs because the parent task and child tasks execute independently of each other; the child is a detached task. The example waits only for the parent task to complete, and the child task may not execute or complete before the console app terminates. - +A *child task* (or *nested task*) is a instance that is created in the user delegate of another task, which is known as the *parent task*. A child task can be either detached or attached. A *detached child task* is a task that executes independently of its parent. An *attached child task* is a nested task that is created with the option whose parent does not explicitly or by default prohibit it from being attached. A task may create any number of attached and detached child tasks, limited only by system resources. + + The following table lists the basic differences between the two kinds of child tasks. + +|Category|Detached child tasks|Attached child tasks| +|--------------|--------------------------|--------------------------| +|Parent waits for child tasks to complete.|No|Yes| +|Parent propagates exceptions thrown by child tasks.|No|Yes| +|Status of parent depends on status of child.|No|Yes| + + In most scenarios, we recommend that you use detached child tasks, because their relationships with other tasks are less complex. That is why tasks created inside parent tasks are detached by default, and you must explicitly specify the option to create an attached child task. + +## Detached child tasks + + Although a child task is created by a parent task, by default it is independent of the parent task. In the following example, a parent task creates one simple child task. If you run the example code multiple times, you may notice that the output from the example differs from that shown, and also that the output may change each time you run the code. This occurs because the parent task and child tasks execute independently of each other; the child is a detached task. The example waits only for the parent task to complete, and the child task may not execute or complete before the console app terminates. + [!code-csharp[TPL_ChildTasks#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_childtasks/cs/nested1.cs#1)] - [!code-vb[TPL_ChildTasks#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_childtasks/vb/nested1.vb#1)] - - If the child task is represented by a object rather than a object, you can ensure that the parent task will wait for the child to complete by accessing the property of the child even if it is a detached child task. The property blocks until its task completes, as the following example shows. - + [!code-vb[TPL_ChildTasks#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_childtasks/vb/nested1.vb#1)] + + If the child task is represented by a object rather than a object, you can ensure that the parent task will wait for the child to complete by accessing the property of the child even if it is a detached child task. The property blocks until its task completes, as the following example shows. + [!code-csharp[TPL_ChildTasks#4](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_childtasks/cs/childtasks.cs#4)] - [!code-vb[TPL_ChildTasks#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_childtasks/vb/tpl_childtasks.vb#4)] - -## Attached child tasks + [!code-vb[TPL_ChildTasks#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_childtasks/vb/tpl_childtasks.vb#4)] + +## Attached child tasks + + Unlike detached child tasks, attached child tasks are closely synchronized with the parent. You can change the detached child task in the previous example to an attached child task by using the option in the task creation statement, as shown in the following example. In this code, the attached child task completes before its parent. As a result, the output from the example is the same each time you run the code. - Unlike detached child tasks, attached child tasks are closely synchronized with the parent. You can change the detached child task in the previous example to an attached child task by using the option in the task creation statement, as shown in the following example. In this code, the attached child task completes before its parent. As a result, the output from the example is the same each time you run the code. - [!code-csharp[TPL_ChildTasks#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_childtasks/cs/child1.cs#2)] - [!code-vb[TPL_ChildTasks#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_childtasks/vb/child1.vb#2)] - - You can use attached child tasks to create tightly synchronized graphs of asynchronous operations. - - However, a child task can attach to its parent only if its parent does not prohibit attached child tasks. Parent tasks can explicitly prevent child tasks from attaching to them by specifying the option in the parent task's class constructor or the method. Parent tasks implicitly prevent child tasks from attaching to them if they are created by calling the method. The following example illustrates this. It is identical to the previous example, except that the parent task is created by calling the method rather than the method. Because the child task is not able to attach to its parent, the output from the example is unpredictable. Because the default task creation options for the overloads include , this example is functionally equivalent to the first example in the "Detached child tasks" section. - + [!code-vb[TPL_ChildTasks#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_childtasks/vb/child1.vb#2)] + + You can use attached child tasks to create tightly synchronized graphs of asynchronous operations. + + However, a child task can attach to its parent only if its parent does not prohibit attached child tasks. Parent tasks can explicitly prevent child tasks from attaching to them by specifying the option in the parent task's class constructor or the method. Parent tasks implicitly prevent child tasks from attaching to them if they are created by calling the method. The following example illustrates this. It is identical to the previous example, except that the parent task is created by calling the method rather than the method. Because the child task is not able to attach to its parent, the output from the example is unpredictable. Because the default task creation options for the overloads include , this example is functionally equivalent to the first example in the "Detached child tasks" section. + [!code-csharp[TPL_ChildTasks#3](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_childtasks/cs/child1a.cs#3)] - [!code-vb[TPL_ChildTasks#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_childtasks/vb/child1a.vb#3)] - -## Exceptions in child tasks - - If a detached child task throws an exception, that exception must be observed or handled directly in the parent task just as with any non-nested task. If an attached child task throws an exception, the exception is automatically propagated to the parent task and back to the thread that waits or tries to access the task's property. Therefore, by using attached child tasks, you can handle all exceptions at just one point in the call to on the calling thread. For more information, see [Exception Handling](exception-handling-task-parallel-library.md). - -## Cancellation and child tasks - - Task cancellation is cooperative. That is, to be cancelable, every attached or detached child task must monitor the status of the cancellation token. If you want to cancel a parent and all its children by using one cancellation request, you pass the same token as an argument to all tasks and provide in each task the logic to respond to the request in each task. For more information, see [Task Cancellation](task-cancellation.md) and [How to: Cancel a Task and Its Children](how-to-cancel-a-task-and-its-children.md). - -### When the parent cancels - - If a parent cancels itself before its child task is started, the child never starts. If a parent cancels itself after its child task has already started, the child runs to completion unless it has its own cancellation logic. For more information, see [Task Cancellation](task-cancellation.md). - -### When a detached child task cancels - - If a detached child task cancels itself by using the same token that was passed to the parent, and the parent does not wait for the child task, no exception is propagated, because the exception is treated as benign cooperation cancellation. This behavior is the same as that of any top-level task. - -### When an attached child task cancels - - When an attached child task cancels itself by using the same token that was passed to its parent task, a is propagated to the joining thread inside an . You must wait for the parent task so that you can handle all benign exceptions in addition to all faulting exceptions that are propagated up through a graph of attached child tasks. - - For more information, see [Exception Handling](exception-handling-task-parallel-library.md). - -## Preventing a child task from attaching to its parent - - An unhandled exception that is thrown by a child task is propagated to the parent task. You can use this behavior to observe all child task exceptions from one root task instead of traversing a tree of tasks. However, exception propagation can be problematic when a parent task does not expect attachment from other code. For example, consider an app that calls a third-party library component from a object. If the third-party library component also creates a object and specifies to attach it to the parent task, any unhandled exceptions that occur in the child task propagate to the parent. This could lead to unexpected behavior in the main app. - - To prevent a child task from attaching to its parent task, specify the option when you create the parent or object. When a task tries to attach to its parent and the parent specifies the option, the child task will not be able to attach to a parent and will execute just as if the option was not specified. - - You might also want to prevent a child task from attaching to its parent when the child task does not finish in a timely manner. Because a parent task does not finish until all child tasks finish, a long-running child task can cause the overall app to perform poorly. For an example that shows how to improve app performance by preventing a task from attaching to its parent task, see [How to: Prevent a Child Task from Attaching to its Parent](how-to-prevent-a-child-task-from-attaching-to-its-parent.md). - + [!code-vb[TPL_ChildTasks#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_childtasks/vb/child1a.vb#3)] + +## Exceptions in child tasks + + If a detached child task throws an exception, that exception must be observed or handled directly in the parent task just as with any non-nested task. If an attached child task throws an exception, the exception is automatically propagated to the parent task and back to the thread that waits or tries to access the task's property. Therefore, by using attached child tasks, you can handle all exceptions at just one point in the call to on the calling thread. For more information, see [Exception Handling](exception-handling-task-parallel-library.md). + +## Cancellation and child tasks + + Task cancellation is cooperative. That is, to be cancelable, every attached or detached child task must monitor the status of the cancellation token. If you want to cancel a parent and all its children by using one cancellation request, you pass the same token as an argument to all tasks and provide in each task the logic to respond to the request in each task. For more information, see [Task Cancellation](task-cancellation.md) and [How to: Cancel a Task and Its Children](how-to-cancel-a-task-and-its-children.md). + +### When the parent cancels + + If a parent cancels itself before its child task is started, the child never starts. If a parent cancels itself after its child task has already started, the child runs to completion unless it has its own cancellation logic. For more information, see [Task Cancellation](task-cancellation.md). + +### When a detached child task cancels + + If a detached child task cancels itself by using the same token that was passed to the parent, and the parent does not wait for the child task, no exception is propagated, because the exception is treated as benign cooperation cancellation. This behavior is the same as that of any top-level task. + +### When an attached child task cancels + + When an attached child task cancels itself by using the same token that was passed to its parent task, a is propagated to the joining thread inside an . You must wait for the parent task so that you can handle all benign exceptions in addition to all faulting exceptions that are propagated up through a graph of attached child tasks. + + For more information, see [Exception Handling](exception-handling-task-parallel-library.md). + +## Preventing a child task from attaching to its parent + + An unhandled exception that is thrown by a child task is propagated to the parent task. You can use this behavior to observe all child task exceptions from one root task instead of traversing a tree of tasks. However, exception propagation can be problematic when a parent task does not expect attachment from other code. For example, consider an app that calls a third-party library component from a object. If the third-party library component also creates a object and specifies to attach it to the parent task, any unhandled exceptions that occur in the child task propagate to the parent. This could lead to unexpected behavior in the main app. + + To prevent a child task from attaching to its parent task, specify the option when you create the parent or object. When a task tries to attach to its parent and the parent specifies the option, the child task will not be able to attach to a parent and will execute just as if the option was not specified. + + You might also want to prevent a child task from attaching to its parent when the child task does not finish in a timely manner. Because a parent task does not finish until all child tasks finish, a long-running child task can cause the overall app to perform poorly. For an example that shows how to improve app performance by preventing a task from attaching to its parent task, see [How to: Prevent a Child Task from Attaching to its Parent](how-to-prevent-a-child-task-from-attaching-to-its-parent.md). + ## See also - [Parallel Programming](index.md) diff --git a/docs/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks.md b/docs/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks.md index 49bb2b7d6077f..1292016708b76 100644 --- a/docs/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks.md +++ b/docs/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks.md @@ -28,13 +28,13 @@ Continuations are relatively easy to use but are nevertheless powerful and flexi ## About continuations -A continuation is a task that's created in the state. It's activated automatically when its antecedent task or tasks complete. Calling on a continuation in user code throws an exception. +A continuation is a task that's created in the state. It's activated automatically when its antecedent task or tasks complete. Calling on a continuation in user code throws an exception. -A continuation is itself a and doesn't block the thread on which it's started. Call the method to block until the continuation task finishes. +A continuation is itself a and doesn't block the thread on which it's started. Call the method to block until the continuation task finishes. ## Create a continuation for a single antecedent -You create a continuation that executes when its antecedent has completed by calling the method. The following example shows the basic pattern (for clarity, exception handling is omitted). It executes an antecedent task `taskA` that returns a object that indicates the name of the current day of the week. When `taskA` completes, the `antecedent` represents its results in the `ContinueWith` continuation method. The result of the antecedent task is written to the console. +You create a continuation that executes when its antecedent has completed by calling the method. The following example shows the basic pattern (for clarity, exception handling is omitted). It executes an antecedent task `taskA` that returns a object that indicates the name of the current day of the week. When `taskA` completes, the `antecedent` represents its results in the `ContinueWith` continuation method. The result of the antecedent task is written to the console. :::code language="csharp" source="snippets/cs/simple1.cs"::: @@ -42,11 +42,11 @@ You create a continuation that executes when its antecedent has completed by cal ## Create a continuation for multiple antecedents -You can also create a continuation that will run when any or all of a group of tasks have completed. To execute a continuation when all antecedent tasks have completed, you can call the static (`Shared` in Visual Basic) method or the instance method. To execute a continuation when any of the antecedent tasks have completed, you can call the static (`Shared` in Visual Basic) method or the instance method. +You can also create a continuation that will run when any or all of a group of tasks have completed. To execute a continuation when all antecedent tasks have completed, you can call the static (`Shared` in Visual Basic) method or the instance method. To execute a continuation when any of the antecedent tasks have completed, you can call the static (`Shared` in Visual Basic) method or the instance method. -Calls to the and overloads don't block the calling thread. However, you typically call all but the and methods to retrieve the returned property, which does block the calling thread. +Calls to the and overloads don't block the calling thread. However, you typically call all but the and methods to retrieve the returned property, which does block the calling thread. -The following example calls the method to create a continuation task that reflects the results of its 10 antecedent tasks. Each antecedent task squares an index value that ranges from one to 10. If the antecedents complete successfully (their property is ), the property of the continuation is an array of the values returned by each antecedent. The example adds them to compute the sum of squares for all numbers between one and 10: +The following example calls the method to create a continuation task that reflects the results of its 10 antecedent tasks. Each antecedent task squares an index value that ranges from one to 10. If the antecedents complete successfully (their property is ), the property of the continuation is an array of the values returned by each antecedent. The example adds them to compute the sum of squares for all numbers between one and 10: :::code language="csharp" source="snippets/cs/whenall1.cs"::: @@ -54,23 +54,23 @@ The following example calls the overload that takes a enumeration value to specify the conditions under which the continuation starts. For example, you can specify that the continuation is to run only if the antecedent completes successfully, or only if it completes in a faulted state. If the condition isn't true when the antecedent is ready to invoke the continuation, the continuation transitions directly to the state and can't be started later. +When you create a single-task continuation, you can use a overload that takes a enumeration value to specify the conditions under which the continuation starts. For example, you can specify that the continuation is to run only if the antecedent completes successfully, or only if it completes in a faulted state. If the condition isn't true when the antecedent is ready to invoke the continuation, the continuation transitions directly to the state and can't be started later. -Many multi-task continuation methods, such as overloads of the method, also include a parameter. However, only a subset of all enumeration members is valid. You can specify values that have counterparts in the enumeration, such as , , and . If you specify any of the `NotOn` or `OnlyOn` options with a multi-task continuation, an exception will be thrown at runtime. +Many multi-task continuation methods, such as overloads of the method, also include a parameter. However, only a subset of all enumeration members is valid. You can specify values that have counterparts in the enumeration, such as , , and . If you specify any of the `NotOn` or `OnlyOn` options with a multi-task continuation, an exception will be thrown at runtime. For more information on task continuation options, see the article. ## Pass data to a continuation -The method passes a reference to the antecedent as an argument to the user delegate of the continuation. If the antecedent is a object, and the task ran until it was completed, then the continuation can access the property of the task. +The method passes a reference to the antecedent as an argument to the user delegate of the continuation. If the antecedent is a object, and the task ran until it was completed, then the continuation can access the property of the task. -The property blocks until the task has completed. However, if the task was canceled or faulted, attempting to access the property throws an exception. You can avoid this problem by using the option, as shown in the following example: +The property blocks until the task has completed. However, if the task was canceled or faulted, attempting to access the property throws an exception. You can avoid this problem by using the option, as shown in the following example: :::code language="csharp" source="snippets/cs/result1.cs"::: [!code-vb[TPL_Continuations#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_continuations/vb/result1.vb#2)] -If you want the continuation to run even if the antecedent didn't run to successful completion, you must guard against the exception. One approach is to test the property of the antecedent, and only attempt to access the property if the status isn't or . You can also examine the property of the antecedent. For more information, see [Exception Handling](exception-handling-task-parallel-library.md). The following example modifies the preceding example to access antecedent's property only if its status is : +If you want the continuation to run even if the antecedent didn't run to successful completion, you must guard against the exception. One approach is to test the property of the antecedent, and only attempt to access the property if the status isn't or . You can also examine the property of the antecedent. For more information, see [Exception Handling](exception-handling-task-parallel-library.md). The following example modifies the preceding example to access antecedent's property only if its status is : :::code language="csharp" source="snippets/cs/result2.cs"::: @@ -78,7 +78,7 @@ If you want the continuation to run even if the antecedent didn't run to success ## Cancel a continuation -The property of a continuation is set to in the following situations: +The property of a continuation is set to in the following situations: - It throws an exception in response to a cancellation request. As with any task, if the exception contains the same token that was passed to the continuation, it's treated as an acknowledgment of cooperative cancellation. @@ -86,7 +86,7 @@ The pr - The continuation never runs because the condition set by its argument wasn't met. For example, if an antecedent goes into a state, its continuation that was passed the option won't run but will transition to the state. -If a task and its continuation represent two parts of the same logical operation, you can pass the same cancellation token to both tasks, as shown in the following example. It consists of an antecedent that generates a list of integers that are divisible by 33, which it passes to the continuation. The continuation in turn displays the list. Both the antecedent and the continuation pause regularly for random intervals. In addition, a object is used to execute the `Elapsed` method after a five-second timeout interval. This example calls the method, which causes the currently executing task to call the method. Whether the method is called when the antecedent or its continuation is executing depends on the duration of the randomly generated pauses. If the antecedent is canceled, the continuation won't start. If the antecedent isn't canceled, the token can still be used to cancel the continuation. +If a task and its continuation represent two parts of the same logical operation, you can pass the same cancellation token to both tasks, as shown in the following example. It consists of an antecedent that generates a list of integers that are divisible by 33, which it passes to the continuation. The continuation in turn displays the list. Both the antecedent and the continuation pause regularly for random intervals. In addition, a object is used to execute the `Elapsed` method after a five-second timeout interval. This example calls the method, which causes the currently executing task to call the method. Whether the method is called when the antecedent or its continuation is executing depends on the duration of the randomly generated pauses. If the antecedent is canceled, the continuation won't start. If the antecedent isn't canceled, the token can still be used to cancel the continuation. :::code language="csharp" source="snippets/cs/cancellation1.cs"::: @@ -104,7 +104,7 @@ Continuations that are disposed won't start. ## Continuations and child tasks -A continuation doesn't run until the antecedent and all of its attached child tasks have completed. A continuation doesn't wait for detached child tasks to finish. The following two examples illustrate child tasks that are attached to and detached from an antecedent that creates a continuation. In the following example, the continuation runs only after all child tasks have completed, and multiple runs of the example produces identical output each time. The example launches the antecedent by calling the method because by default the method creates a parent task whose default task creation option is . +A continuation doesn't run until the antecedent and all of its attached child tasks have completed. A continuation doesn't wait for detached child tasks to finish. The following two examples illustrate child tasks that are attached to and detached from an antecedent that creates a continuation. In the following example, the continuation runs only after all child tasks have completed, and multiple runs of the example produces identical output each time. The example launches the antecedent by calling the method because by default the method creates a parent task whose default task creation option is . :::code language="csharp" source="snippets/cs/attached1.cs"::: @@ -120,13 +120,13 @@ The final status of the antecedent task depends on the final status of any attac ## Associate state with continuations -You can associate arbitrary state with a task continuation. The method provides overloaded versions that each take an value that represents the state of the continuation. You can later access this state object by using the property. This state object is `null` if you don't provide a value. +You can associate arbitrary state with a task continuation. The method provides overloaded versions that each take an value that represents the state of the continuation. You can later access this state object by using the property. This state object is `null` if you don't provide a value. -Continuation state is useful when you convert existing code that uses the [Asynchronous Programming Model (APM)](../asynchronous-programming-patterns/asynchronous-programming-model-apm.md) to use the TPL. In the APM, you can provide object state in the **Begin**_Method_ method and later you can use the property to access that state. To preserve this state when you convert a code that uses the APM to use the TPL, you use the method. +Continuation state is useful when you convert existing code that uses the [Asynchronous Programming Model (APM)](../asynchronous-programming-patterns/asynchronous-programming-model-apm.md) to use the TPL. In the APM, you can provide object state in the **Begin**_Method_ method and later you can use the property to access that state. To preserve this state when you convert a code that uses the APM to use the TPL, you use the method. Continuation state can also be useful when you work with objects in the Visual Studio debugger. For example, in the **Parallel Tasks** window, the **Task** column displays the string representation of the state object for each task. For more information about the **Parallel Tasks** window, see [Using the Tasks Window](/visualstudio/debugger/using-the-tasks-window). -The following example shows how to use continuation state. It creates a chain of continuation tasks. Each task provides the current time, a object, for the `state` parameter of the method. Each object represents the time at which the continuation task is created. Each task produces as its result a second object that represents the time at which the task finishes. After all tasks finish, this example displays the creation time and the time at which each continuation task finishes. +The following example shows how to use continuation state. It creates a chain of continuation tasks. Each task provides the current time, a object, for the `state` parameter of the method. Each object represents the time at which the continuation task is created. Each task produces as its result a second object that represents the time at which the task finishes. After all tasks finish, this example displays the creation time and the time at which each continuation task finishes. :::code language="csharp" source="snippets/cs/continuationstate.cs"::: @@ -134,32 +134,32 @@ The following example shows how to use continuation state. It creates a chain of ## Continuations that return Task types -Sometimes you might need to chain a continuation that returns a type. These tasks are referred as nested tasks. When a parent task calls and provides a `continuationFunction` that's task-returning, you can call to create a proxy task that represents the asynchronous operation of the `>>` or `Task(Of Task(Of T))` (Visual Basic). +Sometimes you might need to chain a continuation that returns a type. These tasks are referred as nested tasks. When a parent task calls and provides a `continuationFunction` that's task-returning, you can call to create a proxy task that represents the asynchronous operation of the `>>` or `Task(Of Task(Of T))` (Visual Basic). The following example shows how to use continuations that wrap additional task returning functions. Each continuation can be unwrapped, exposing the inner task that was wrapped. :::code language="csharp" source="snippets/cs/unwrap.cs"::: :::code language="vb" source="snippets/vb/unwrap.vb"::: -For more information on using , see [How to: Unwrap a nested Task](how-to-unwrap-a-nested-task.md). +For more information on using , see [How to: Unwrap a nested Task](how-to-unwrap-a-nested-task.md). ## Handle exceptions thrown from continuations An antecedent-continuation relationship isn't a parent-child relationship. Exceptions thrown by continuations aren't propagated to the antecedent. Therefore, handle exceptions thrown by continuations as you would handle them in any other task, as follows: -- You can use the , , or method, or its generic counterpart, to wait on the continuation. You can wait for an antecedent and its continuations in the same `try` statement, as shown in the following example: +- You can use the , , or method, or its generic counterpart, to wait on the continuation. You can wait for an antecedent and its continuations in the same `try` statement, as shown in the following example: :::code language="csharp" source="snippets/cs/exception1.cs"::: [!code-vb[TPL_Continuations#6](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_continuations/vb/exception1.vb#6)] -- You can use a second continuation to observe the property of the first continuation. In the following example, a task attempts to read from a non-existent file. The continuation then displays information about the exception in the antecedent task. +- You can use a second continuation to observe the property of the first continuation. In the following example, a task attempts to read from a non-existent file. The continuation then displays information about the exception in the antecedent task. :::code language="csharp" source="snippets/cs/exception2.cs" id="example"::: [!code-vb[TPL_Continuations#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_continuations/vb/exception2.vb#4)] -Because it was run with the option, the continuation executes only if an exception occurs in the antecedent. Therefore it can assume that the antecedent's property isn't `null`. If the continuation executes whether or not an exception is thrown in the antecedent, it must check whether the antecedent's property isn't `null` before attempting to handle the exception, as the following code fragment shows: +Because it was run with the option, the continuation executes only if an exception occurs in the antecedent. Therefore it can assume that the antecedent's property isn't `null`. If the continuation executes whether or not an exception is thrown in the antecedent, it must check whether the antecedent's property isn't `null` before attempting to handle the exception, as the following code fragment shows: :::code language="csharp" source="snippets/cs/exception2.cs" id="exception"::: diff --git a/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md b/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md index dfaf5977dd82e..827e4e95f39e5 100644 --- a/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md +++ b/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md @@ -11,7 +11,7 @@ ms.assetid: 96153688-9a01-47c4-8430-909cee9a2887 --- # Custom Partitioners for PLINQ and TPL -To parallelize an operation on a data source, one of the essential steps is to *partition* the source into multiple sections that can be accessed concurrently by multiple threads. PLINQ and the Task Parallel Library (TPL) provide default partitioners that work transparently when you write a parallel query or loop. For more advanced scenarios, you can plug in your own partitioner. +To parallelize an operation on a data source, one of the essential steps is to *partition* the source into multiple sections that can be accessed concurrently by multiple threads. PLINQ and the Task Parallel Library (TPL) provide default partitioners that work transparently when you write a parallel query or loop. For more advanced scenarios, you can plug in your own partitioner. ## Kinds of Partitioning @@ -21,11 +21,11 @@ For linked lists or other collections whose length is not known, you can use *ch In general, range partitioning is only faster when the execution time of the delegate is small to moderate, and the source has a large number of elements, and the total work of each partition is roughly equivalent. Chunk partitioning is therefore generally faster in most cases. On sources with a small number of elements or longer execution times for the delegate, then the performance of chunk and range partitioning is about equal. -The TPL partitioners also support a dynamic number of partitions. This means they can create partitions on-the-fly, for example, when the loop spawns a new task. This feature enables the partitioner to scale together with the loop itself. Dynamic partitioners are also inherently load-balancing. When you create a custom partitioner, you must support dynamic partitioning to be consumable from a loop. +The TPL partitioners also support a dynamic number of partitions. This means they can create partitions on-the-fly, for example, when the loop spawns a new task. This feature enables the partitioner to scale together with the loop itself. Dynamic partitioners are also inherently load-balancing. When you create a custom partitioner, you must support dynamic partitioning to be consumable from a loop. ### Configuring Load Balancing Partitioners for PLINQ -Some overloads of the method let you create a partitioner for an array or source and specify whether it should attempt to balance the workload among the threads. When the partitioner is configured to load-balance, chunk partitioning is used, and the elements are handed off to each partition in small chunks as they are requested. This approach helps ensure that all partitions have elements to process until the entire loop or query is completed. An additional overload can be used to provide load-balancing partitioning of any source. +Some overloads of the method let you create a partitioner for an array or source and specify whether it should attempt to balance the workload among the threads. When the partitioner is configured to load-balance, chunk partitioning is used, and the elements are handed off to each partition in small chunks as they are requested. This approach helps ensure that all partitions have elements to process until the entire loop or query is completed. An additional overload can be used to provide load-balancing partitioning of any source. In general, load balancing requires the partitions to request elements relatively frequently from the partitioner. By contrast, a partitioner that does static partitioning can assign the elements to each partitioner all at once by using either range or chunk partitioning. This requires less overhead than load balancing, but it might take longer to execute if one thread ends up with significantly more work than the others. By default when it is passed an IList or an array, PLINQ always uses range partitioning without load balancing. To enable load balancing for PLINQ, use the `Partitioner.Create` method, as shown in the following example. @@ -34,13 +34,13 @@ In general, load balancing requires the partitions to request elements relativel The best way to determine whether to use load balancing in any given scenario is to experiment and measure how long it takes operations to complete under representative loads and computer configurations. For example, static partitioning might provide significant speedup on a multi-core computer that has only a few cores, but it might result in slowdowns on computers that have relatively many cores. -The following table lists the available overloads of the method. These partitioners are not limited to use only with PLINQ or . They can also be used with any custom parallel construct. +The following table lists the available overloads of the method. These partitioners are not limited to use only with PLINQ or . They can also be used with any custom parallel construct. |Overload|Uses load balancing| |--------------|-------------------------| -||Always| -||When the Boolean argument is specified as true| -||When the Boolean argument is specified as true| +||Always| +||When the Boolean argument is specified as true| +||When the Boolean argument is specified as true| ||Never| ||Never| ||Never| @@ -48,62 +48,62 @@ The following table lists the available overloads of the loop, the body of the loop is provided to the method as a delegate. The cost of invoking that delegate is about the same as a virtual method call. In some scenarios, the body of a parallel loop might be small enough that the cost of the delegate invocation on each loop iteration becomes significant. In such situations, you can use one of the overloads to create an of range partitions over the source elements. Then, you can pass this collection of ranges to a method whose body consists of a regular `for` loop. The benefit of this approach is that the delegate invocation cost is incurred only once per range, rather than once per element. The following example demonstrates the basic pattern. +In a loop, the body of the loop is provided to the method as a delegate. The cost of invoking that delegate is about the same as a virtual method call. In some scenarios, the body of a parallel loop might be small enough that the cost of the delegate invocation on each loop iteration becomes significant. In such situations, you can use one of the overloads to create an of range partitions over the source elements. Then, you can pass this collection of ranges to a method whose body consists of a regular `for` loop. The benefit of this approach is that the delegate invocation cost is incurred only once per range, rather than once per element. The following example demonstrates the basic pattern. [!code-csharp[TPL_Partitioners#01](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_partitioners/cs/partitioner01.cs#01)] [!code-vb[TPL_Partitioners#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_partitioners/vb/partitionercreate01.vb#01)] -Every thread in the loop receives its own that contains the starting and ending index values in the specified sub-range. The inner `for` loop uses the `fromInclusive` and `toExclusive` values to loop over the array or the directly. +Every thread in the loop receives its own that contains the starting and ending index values in the specified sub-range. The inner `for` loop uses the `fromInclusive` and `toExclusive` values to loop over the array or the directly. -One of the overloads lets you specify the size of the partitions, and the number of partitions. This overload can be used in scenarios where the work per element is so low that even one virtual method call per element has a noticeable impact on performance. +One of the overloads lets you specify the size of the partitions, and the number of partitions. This overload can be used in scenarios where the work per element is so low that even one virtual method call per element has a noticeable impact on performance. ## Custom Partitioners In some scenarios, it might be worthwhile or even required to implement your own partitioner. For example, you might have a custom collection class that you can partition more efficiently than the default partitioners can, based on your knowledge of the internal structure of the class. Or, you may want to create range partitions of varying sizes based on your knowledge of how long it will take to process elements at different locations in the source collection. -To create a basic custom partitioner, derive a class from and override the virtual methods, as described in the following table. +To create a basic custom partitioner, derive a class from and override the virtual methods, as described in the following table. |Method|Description| |-|-| -||This method is called once by the main thread and returns an IList(IEnumerator(TSource)). Each worker thread in the loop or query can call `GetEnumerator` on the list to retrieve a over a distinct partition.| -||Return `true` if you implement , otherwise, `false`.| -||If is `true`, this method can optionally be called instead of .| +||This method is called once by the main thread and returns an IList(IEnumerator(TSource)). Each worker thread in the loop or query can call `GetEnumerator` on the list to retrieve a over a distinct partition.| +||Return `true` if you implement , otherwise, `false`.| +||If is `true`, this method can optionally be called instead of .| -If the results must be sortable or you require indexed access into the elements, then derive from and override its virtual methods as described in the following table. +If the results must be sortable or you require indexed access into the elements, then derive from and override its virtual methods as described in the following table. |Method|Description| |-|-| -||This method is called once by the main thread and returns an `IList(IEnumerator(TSource))`. Each worker thread in the loop or query can call `GetEnumerator` on the list to retrieve a over a distinct partition.| -||Return `true` if you implement ; otherwise, false.| -||Typically, this just calls .| -||If is `true`, this method can optionally be called instead of .| +||This method is called once by the main thread and returns an `IList(IEnumerator(TSource))`. Each worker thread in the loop or query can call `GetEnumerator` on the list to retrieve a over a distinct partition.| +||Return `true` if you implement ; otherwise, false.| +||Typically, this just calls .| +||If is `true`, this method can optionally be called instead of .| -The following table provides additional details about how the three kinds of load-balancing partitioners implement the class. +The following table provides additional details about how the three kinds of load-balancing partitioners implement the class. |Method/Property|IList / Array without Load Balancing|IList / Array with Load Balancing|IEnumerable| |----------------------|-------------------------------------------|----------------------------------------|-----------------| -||Uses range partitioning|Uses chunk partitioning optimized for Lists for the partitionCount specified|Uses chunk partitioning by creating a static number of partitions.| -||Throws not-supported exception|Uses chunk partitioning optimized for Lists and dynamic partitions|Uses chunk partitioning by creating a dynamic number of partitions.| -||Returns `true`|Returns `true`|Returns `true`| -||Returns `true`|Returns `false`|Returns `false`| -||Returns `true`|Returns `true`|Returns `true`| -||Returns `false`|Returns `true`|Returns `true`| +||Uses range partitioning|Uses chunk partitioning optimized for Lists for the partitionCount specified|Uses chunk partitioning by creating a static number of partitions.| +||Throws not-supported exception|Uses chunk partitioning optimized for Lists and dynamic partitions|Uses chunk partitioning by creating a dynamic number of partitions.| +||Returns `true`|Returns `true`|Returns `true`| +||Returns `true`|Returns `false`|Returns `false`| +||Returns `true`|Returns `true`|Returns `true`| +||Returns `false`|Returns `true`|Returns `true`| ### Dynamic Partitions -If you intend the partitioner to be used in a method, you must be able to return a dynamic number of partitions. This means that the partitioner can supply an enumerator for a new partition on-demand at any time during loop execution. Basically, whenever the loop adds a new parallel task, it requests a new partition for that task. If you require the data to be orderable, then derive from so that each item in each partition is assigned a unique index. +If you intend the partitioner to be used in a method, you must be able to return a dynamic number of partitions. This means that the partitioner can supply an enumerator for a new partition on-demand at any time during loop execution. Basically, whenever the loop adds a new parallel task, it requests a new partition for that task. If you require the data to be orderable, then derive from so that each item in each partition is assigned a unique index. For more information, and an example, see [How to: Implement Dynamic Partitions](how-to-implement-dynamic-partitions.md). ### Contract for Partitioners -When you implement a custom partitioner, follow these guidelines to help ensure correct interaction with PLINQ and in the TPL: +When you implement a custom partitioner, follow these guidelines to help ensure correct interaction with PLINQ and in the TPL: -- If is called with an argument of zero or less for `partitionsCount`, throw . Although PLINQ and TPL will never pass in a `partitionCount` equal to 0, we nevertheless recommend that you guard against the possibility. +- If is called with an argument of zero or less for `partitionsCount`, throw . Although PLINQ and TPL will never pass in a `partitionCount` equal to 0, we nevertheless recommend that you guard against the possibility. -- and should always return `partitionsCount` number of partitions. If the partitioner runs out of data and cannot create as many partitions as requested, then the method should return an empty enumerator for each of the remaining partitions. Otherwise, both PLINQ and TPL will throw an . +- and should always return `partitionsCount` number of partitions. If the partitioner runs out of data and cannot create as many partitions as requested, then the method should return an empty enumerator for each of the remaining partitions. Otherwise, both PLINQ and TPL will throw an . -- , , , and should never return `null` (`Nothing` in Visual Basic). If they do, PLINQ / TPL will throw an . +- , , , and should never return `null` (`Nothing` in Visual Basic). If they do, PLINQ / TPL will throw an . - Methods that return partitions should always return partitions that can fully and uniquely enumerate the data source. There should be no duplication in the data source or skipped items unless specifically required by the design of the partitioner. If this rule is not followed, then the output order may be scrambled. diff --git a/docs/standard/parallel-programming/data-parallelism-task-parallel-library.md b/docs/standard/parallel-programming/data-parallelism-task-parallel-library.md index 7da92a36d9f6e..8d08cef800099 100644 --- a/docs/standard/parallel-programming/data-parallelism-task-parallel-library.md +++ b/docs/standard/parallel-programming/data-parallelism-task-parallel-library.md @@ -2,50 +2,50 @@ title: "Data Parallelism (Task Parallel Library)" description: Read how the Task Parallel Library (TPL) supports data parallelism to do the same operation concurrently on a source collection or array's elements in .NET. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "parallelism, data" ms.assetid: 3f05f33f-f1da-4b16-81c2-9ceff1bef449 --- # Data Parallelism (Task Parallel Library) -*Data parallelism* refers to scenarios in which the same operation is performed concurrently (that is, in parallel) on elements in a source collection or array. In data parallel operations, the source collection is partitioned so that multiple threads can operate on different segments concurrently. - - The Task Parallel Library (TPL) supports data parallelism through the class. This class provides method-based parallel implementations of [for](../../csharp/language-reference/statements/iteration-statements.md#the-for-statement) and [foreach](../../csharp/language-reference/statements/iteration-statements.md#the-foreach-statement) loops (`For` and `For Each` in Visual Basic). You write the loop logic for a or loop much as you would write a sequential loop. You do not have to create threads or queue work items. In basic loops, you do not have to take locks. The TPL handles all the low-level work for you. For in-depth information about the use of and , download the document [Patterns for Parallel Programming: Understanding and Applying Parallel Patterns with the .NET Framework 4](https://www.microsoft.com/download/details.aspx?id=19222). The following code example shows a simple `foreach` loop and its parallel equivalent. - +*Data parallelism* refers to scenarios in which the same operation is performed concurrently (that is, in parallel) on elements in a source collection or array. In data parallel operations, the source collection is partitioned so that multiple threads can operate on different segments concurrently. + + The Task Parallel Library (TPL) supports data parallelism through the class. This class provides method-based parallel implementations of [for](../../csharp/language-reference/statements/iteration-statements.md#the-for-statement) and [foreach](../../csharp/language-reference/statements/iteration-statements.md#the-foreach-statement) loops (`For` and `For Each` in Visual Basic). You write the loop logic for a or loop much as you would write a sequential loop. You do not have to create threads or queue work items. In basic loops, you do not have to take locks. The TPL handles all the low-level work for you. For in-depth information about the use of and , download the document [Patterns for Parallel Programming: Understanding and Applying Parallel Patterns with the .NET Framework 4](https://www.microsoft.com/download/details.aspx?id=19222). The following code example shows a simple `foreach` loop and its parallel equivalent. + > [!NOTE] -> This documentation uses lambda expressions to define delegates in TPL. If you are not familiar with lambda expressions in C# or Visual Basic, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). - +> This documentation uses lambda expressions to define delegates in TPL. If you are not familiar with lambda expressions in C# or Visual Basic, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). + [!code-csharp[TPL#20](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl/cs/tpl.cs#20)] - [!code-vb[TPL#20](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl/vb/tpl_vb.vb#20)] - - When a parallel loop runs, the TPL partitions the data source so that the loop can operate on multiple parts concurrently. Behind the scenes, the Task Scheduler partitions the task based on system resources and workload. When possible, the scheduler redistributes work among multiple threads and processors if the workload becomes unbalanced. - + [!code-vb[TPL#20](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl/vb/tpl_vb.vb#20)] + + When a parallel loop runs, the TPL partitions the data source so that the loop can operate on multiple parts concurrently. Behind the scenes, the Task Scheduler partitions the task based on system resources and workload. When possible, the scheduler redistributes work among multiple threads and processors if the workload becomes unbalanced. + > [!NOTE] -> You can also supply your own custom partitioner or scheduler. For more information, see [Custom Partitioners for PLINQ and TPL](custom-partitioners-for-plinq-and-tpl.md) and [Task Schedulers](xref:System.Threading.Tasks.TaskScheduler). - - Both the and methods have several overloads that let you stop or break loop execution, monitor the state of the loop on other threads, maintain thread-local state, finalize thread-local objects, control the degree of concurrency, and so on. The helper types that enable this functionality include , , , , and . - - For more information, see [Patterns for Parallel Programming: Understanding and Applying Parallel Patterns with the .NET Framework 4](https://www.microsoft.com/download/details.aspx?id=19222). - - Data parallelism with declarative, or query-like, syntax is supported by PLINQ. For more information, see [Parallel LINQ (PLINQ)](introduction-to-plinq.md). - -## Related Topics - -|Title|Description| -|-----------|-----------------| -|[How to: Write a Simple Parallel.For Loop](how-to-write-a-simple-parallel-for-loop.md)|Describes how to write a loop over any array or indexable source collection.| -|[How to: Write a Simple Parallel.ForEach Loop](how-to-write-a-simple-parallel-foreach-loop.md)|Describes how to write a loop over any source collection.| -|[How to: Stop or Break from a Parallel.For Loop](/previous-versions/dotnet/netframework-4.0/dd460721(v=vs.100))|Describes how to stop or break from a parallel loop so that all threads are informed of the action.| -|[How to: Write a Parallel.For Loop with Thread-Local Variables](how-to-write-a-parallel-for-loop-with-thread-local-variables.md)|Describes how to write a loop in which each thread maintains a private variable that is not visible to any other threads, and how to synchronize the results from all threads when the loop completes.| -|[How to: Write a Parallel.ForEach Loop with Partition-Local Variables](how-to-write-a-parallel-foreach-loop-with-partition-local-variables.md)|Describes how to write a loop in which each thread maintains a private variable that is not visible to any other threads, and how to synchronize the results from all threads when the loop completes.| -|[How to: Cancel a Parallel.For or ForEach Loop](how-to-cancel-a-parallel-for-or-foreach-loop.md)|Describes how to cancel a parallel loop by using a | -|[How to: Speed Up Small Loop Bodies](how-to-speed-up-small-loop-bodies.md)|Describes one way to speed up execution when a loop body is very small.| -|[Task Parallel Library (TPL)](task-parallel-library-tpl.md)|Provides an overview of the Task Parallel Library.| -|[Parallel Programming](index.md)|Introduces Parallel Programming in the .NET Framework.| - +> You can also supply your own custom partitioner or scheduler. For more information, see [Custom Partitioners for PLINQ and TPL](custom-partitioners-for-plinq-and-tpl.md) and [Task Schedulers](xref:System.Threading.Tasks.TaskScheduler). + + Both the and methods have several overloads that let you stop or break loop execution, monitor the state of the loop on other threads, maintain thread-local state, finalize thread-local objects, control the degree of concurrency, and so on. The helper types that enable this functionality include , , , , and . + + For more information, see [Patterns for Parallel Programming: Understanding and Applying Parallel Patterns with the .NET Framework 4](https://www.microsoft.com/download/details.aspx?id=19222). + + Data parallelism with declarative, or query-like, syntax is supported by PLINQ. For more information, see [Parallel LINQ (PLINQ)](introduction-to-plinq.md). + +## Related Topics + +|Title|Description| +|-----------|-----------------| +|[How to: Write a Simple Parallel.For Loop](how-to-write-a-simple-parallel-for-loop.md)|Describes how to write a loop over any array or indexable source collection.| +|[How to: Write a Simple Parallel.ForEach Loop](how-to-write-a-simple-parallel-foreach-loop.md)|Describes how to write a loop over any source collection.| +|[How to: Stop or Break from a Parallel.For Loop](/previous-versions/dotnet/netframework-4.0/dd460721(v=vs.100))|Describes how to stop or break from a parallel loop so that all threads are informed of the action.| +|[How to: Write a Parallel.For Loop with Thread-Local Variables](how-to-write-a-parallel-for-loop-with-thread-local-variables.md)|Describes how to write a loop in which each thread maintains a private variable that is not visible to any other threads, and how to synchronize the results from all threads when the loop completes.| +|[How to: Write a Parallel.ForEach Loop with Partition-Local Variables](how-to-write-a-parallel-foreach-loop-with-partition-local-variables.md)|Describes how to write a loop in which each thread maintains a private variable that is not visible to any other threads, and how to synchronize the results from all threads when the loop completes.| +|[How to: Cancel a Parallel.For or ForEach Loop](how-to-cancel-a-parallel-for-or-foreach-loop.md)|Describes how to cancel a parallel loop by using a | +|[How to: Speed Up Small Loop Bodies](how-to-speed-up-small-loop-bodies.md)|Describes one way to speed up execution when a loop body is very small.| +|[Task Parallel Library (TPL)](task-parallel-library-tpl.md)|Provides an overview of the Task Parallel Library.| +|[Parallel Programming](index.md)|Introduces Parallel Programming in the .NET Framework.| + ## See also - [Parallel Programming](index.md) diff --git a/docs/standard/parallel-programming/data-structures-for-parallel-programming.md b/docs/standard/parallel-programming/data-structures-for-parallel-programming.md index 0bb9b1e99baa3..3e19c25834c7c 100644 --- a/docs/standard/parallel-programming/data-structures-for-parallel-programming.md +++ b/docs/standard/parallel-programming/data-structures-for-parallel-programming.md @@ -2,69 +2,69 @@ description: "Learn more about: Data Structures for Parallel Programming" title: "Data Structures for Parallel Programming" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "data structures, multi-threading" ms.assetid: bdc82f2f-4754-45a1-a81e-fe2e9c30cef9 --- # Data Structures for Parallel Programming -.NET provides several types that are useful in parallel programming, including a set of concurrent collection classes, lightweight synchronization primitives, and types for lazy initialization. You can use these types with any multithreaded application code, including the Task Parallel Library and PLINQ. - -## Concurrent Collection Classes - - The collection classes in the namespace provide thread-safe add and remove operations that avoid locks wherever possible and use fine-grained locking where locks are necessary. A concurrent collection class does not require user code to take any locks when it accesses items. The concurrent collection classes can significantly improve performance over types such as and (with user-implemented locking) in scenarios where multiple threads add and remove items from a collection. - - The following table lists the concurrent collection classes: - -|Type|Description| -|----------|-----------------| -||Provides blocking and bounding capabilities for thread-safe collections that implement . Producer threads block if no slots are available or if the collection is full. Consumer threads block if the collection is empty. This type also supports non-blocking access by consumers and producers. can be used as a base class or backing store to provide blocking and bounding for any collection class that supports .| -||A thread-safe bag implementation that provides scalable add and get operations.| -||A concurrent and scalable dictionary type.| -||A concurrent and scalable FIFO queue.| -||A concurrent and scalable LIFO stack.| - - For more information, see [Thread-Safe Collections](../collections/thread-safe/index.md). - -## Synchronization Primitives +.NET provides several types that are useful in parallel programming, including a set of concurrent collection classes, lightweight synchronization primitives, and types for lazy initialization. You can use these types with any multithreaded application code, including the Task Parallel Library and PLINQ. + +## Concurrent Collection Classes + + The collection classes in the namespace provide thread-safe add and remove operations that avoid locks wherever possible and use fine-grained locking where locks are necessary. A concurrent collection class does not require user code to take any locks when it accesses items. The concurrent collection classes can significantly improve performance over types such as and (with user-implemented locking) in scenarios where multiple threads add and remove items from a collection. + + The following table lists the concurrent collection classes: + +|Type|Description| +|----------|-----------------| +||Provides blocking and bounding capabilities for thread-safe collections that implement . Producer threads block if no slots are available or if the collection is full. Consumer threads block if the collection is empty. This type also supports non-blocking access by consumers and producers. can be used as a base class or backing store to provide blocking and bounding for any collection class that supports .| +||A thread-safe bag implementation that provides scalable add and get operations.| +||A concurrent and scalable dictionary type.| +||A concurrent and scalable FIFO queue.| +||A concurrent and scalable LIFO stack.| + + For more information, see [Thread-Safe Collections](../collections/thread-safe/index.md). + +## Synchronization Primitives The synchronization primitives in the namespace enable fine-grained concurrency and faster performance by avoiding expensive locking mechanisms found in legacy multithreading code. - - The following table lists the synchronization types: - -|Type|Description| -|----------|-----------------| -||Enables multiple threads to work on an algorithm in parallel by providing a point at which each task can signal its arrival and then block until some or all tasks have arrived. For more information, see [Barrier](../threading/barrier.md).| -||Simplifies fork and join scenarios by providing an easy rendezvous mechanism. For more information, see [CountdownEvent](../threading/countdownevent.md).| -||A synchronization primitive similar to . is lighter-weight but can only be used for intra-process communication.| -||A synchronization primitive that limits the number of threads that can concurrently access a resource or a pool of resources. For more information, see [Semaphore and SemaphoreSlim](../threading/semaphore-and-semaphoreslim.md).| -||A mutual exclusion lock primitive that causes the thread that is trying to acquire the lock to wait in a loop, or *spin*, for a period of time before yielding its quantum. In scenarios where the wait for the lock is expected to be short, offers better performance than other forms of locking. For more information, see [SpinLock](../threading/spinlock.md).| -||A small, lightweight type that will spin for a specified time and eventually put the thread into a wait state if the spin count is exceeded. For more information, see [SpinWait](../threading/spinwait.md).| - - For more information, see: - -- [How to: Use SpinLock for Low-Level Synchronization](../threading/how-to-use-spinlock-for-low-level-synchronization.md) - -- [How to: Synchronize Concurrent Operations with a Barrier](../threading/how-to-synchronize-concurrent-operations-with-a-barrier.md). - -## Lazy Initialization Classes - - With lazy initialization, the memory for an object is not allocated until it is needed. Lazy initialization can improve performance by spreading object allocations evenly across the lifetime of a program. You can enable lazy initialization for any custom type by wrapping the type . - - The following table lists the lazy initialization types: - -|Type|Description| -|----------|-----------------| -||Provides lightweight, thread-safe lazy-initialization.| -||Provides a lazily-initialized value on a per-thread basis, with each thread lazily-invoking the initialization function.| -||Provides static methods that avoid the need to allocate a dedicated, lazy-initialization instance. Instead, they use references to ensure targets have been initialized as they are accessed.| - - For more information, see [Lazy Initialization](../../framework/performance/lazy-initialization.md). - -## Aggregate Exceptions - - The type can be used to capture multiple exceptions that are thrown concurrently on separate threads, and return them to the joining thread as a single exception. The and types and PLINQ use extensively for this purpose. For more information, see [Exception Handling](exception-handling-task-parallel-library.md) and [How to: Handle Exceptions in a PLINQ Query](how-to-handle-exceptions-in-a-plinq-query.md). - + + The following table lists the synchronization types: + +|Type|Description| +|----------|-----------------| +||Enables multiple threads to work on an algorithm in parallel by providing a point at which each task can signal its arrival and then block until some or all tasks have arrived. For more information, see [Barrier](../threading/barrier.md).| +||Simplifies fork and join scenarios by providing an easy rendezvous mechanism. For more information, see [CountdownEvent](../threading/countdownevent.md).| +||A synchronization primitive similar to . is lighter-weight but can only be used for intra-process communication.| +||A synchronization primitive that limits the number of threads that can concurrently access a resource or a pool of resources. For more information, see [Semaphore and SemaphoreSlim](../threading/semaphore-and-semaphoreslim.md).| +||A mutual exclusion lock primitive that causes the thread that is trying to acquire the lock to wait in a loop, or *spin*, for a period of time before yielding its quantum. In scenarios where the wait for the lock is expected to be short, offers better performance than other forms of locking. For more information, see [SpinLock](../threading/spinlock.md).| +||A small, lightweight type that will spin for a specified time and eventually put the thread into a wait state if the spin count is exceeded. For more information, see [SpinWait](../threading/spinwait.md).| + + For more information, see: + +- [How to: Use SpinLock for Low-Level Synchronization](../threading/how-to-use-spinlock-for-low-level-synchronization.md) + +- [How to: Synchronize Concurrent Operations with a Barrier](../threading/how-to-synchronize-concurrent-operations-with-a-barrier.md). + +## Lazy Initialization Classes + + With lazy initialization, the memory for an object is not allocated until it is needed. Lazy initialization can improve performance by spreading object allocations evenly across the lifetime of a program. You can enable lazy initialization for any custom type by wrapping the type . + + The following table lists the lazy initialization types: + +|Type|Description| +|----------|-----------------| +||Provides lightweight, thread-safe lazy-initialization.| +||Provides a lazily-initialized value on a per-thread basis, with each thread lazily-invoking the initialization function.| +||Provides static methods that avoid the need to allocate a dedicated, lazy-initialization instance. Instead, they use references to ensure targets have been initialized as they are accessed.| + + For more information, see [Lazy Initialization](../../framework/performance/lazy-initialization.md). + +## Aggregate Exceptions + + The type can be used to capture multiple exceptions that are thrown concurrently on separate threads, and return them to the joining thread as a single exception. The and types and PLINQ use extensively for this purpose. For more information, see [Exception Handling](exception-handling-task-parallel-library.md) and [How to: Handle Exceptions in a PLINQ Query](how-to-handle-exceptions-in-a-plinq-query.md). + ## See also - diff --git a/docs/standard/parallel-programming/dataflow-task-parallel-library.md b/docs/standard/parallel-programming/dataflow-task-parallel-library.md index 4a5184bbf11c5..13fba256061c1 100644 --- a/docs/standard/parallel-programming/dataflow-task-parallel-library.md +++ b/docs/standard/parallel-programming/dataflow-task-parallel-library.md @@ -2,10 +2,10 @@ title: "Dataflow (Task Parallel Library)" description: Learn how to use dataflow components in the Task Parallel Library (TPL) to improve the robustness of concurrency-enabled applications. ms.date: "10/22/2025" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "Task Parallel Library, dataflows" - "TPL dataflow library" ms.assetid: 643575d0-d26d-4c35-8de7-a9c403e97dd6 @@ -13,273 +13,273 @@ ai-usage: ai-assisted --- # Dataflow (Task Parallel Library) -The Task Parallel Library (TPL) provides dataflow components to help increase the robustness of concurrency-enabled applications. These dataflow components are collectively referred to as the *TPL Dataflow Library*. This dataflow model promotes actor-based programming by providing in-process message passing for coarse-grained dataflow and pipelining tasks. The dataflow components build on the types and scheduling infrastructure of the TPL and integrate with the C#, Visual Basic, and F# language support for asynchronous programming. These dataflow components are useful when you have multiple operations that must communicate with one another asynchronously or when you want to process data as it becomes available. For example, consider an application that processes image data from a web camera. By using the dataflow model, the application can process image frames as they become available. If the application enhances image frames, for example, by performing light correction or red-eye reduction, you can create a *pipeline* of dataflow components. Each stage of the pipeline might use more coarse-grained parallelism functionality, such as the functionality that is provided by the TPL, to transform the image. - - This document provides an overview of the TPL Dataflow Library. It describes the programming model, the predefined dataflow block types, and how to configure dataflow blocks to meet the specific requirements of your applications. +The Task Parallel Library (TPL) provides dataflow components to help increase the robustness of concurrency-enabled applications. These dataflow components are collectively referred to as the *TPL Dataflow Library*. This dataflow model promotes actor-based programming by providing in-process message passing for coarse-grained dataflow and pipelining tasks. The dataflow components build on the types and scheduling infrastructure of the TPL and integrate with the C#, Visual Basic, and F# language support for asynchronous programming. These dataflow components are useful when you have multiple operations that must communicate with one another asynchronously or when you want to process data as it becomes available. For example, consider an application that processes image data from a web camera. By using the dataflow model, the application can process image frames as they become available. If the application enhances image frames, for example, by performing light correction or red-eye reduction, you can create a *pipeline* of dataflow components. Each stage of the pipeline might use more coarse-grained parallelism functionality, such as the functionality that is provided by the TPL, to transform the image. + + This document provides an overview of the TPL Dataflow Library. It describes the programming model, the predefined dataflow block types, and how to configure dataflow blocks to meet the specific requirements of your applications. [!INCLUDE [tpl-install-instructions](../../../includes/tpl-install-instructions.md)] ## Programming Model - The TPL Dataflow Library provides a foundation for message passing and parallelizing CPU-intensive and I/O-intensive applications that have high throughput and low latency. It also gives you explicit control over how data is buffered and moves around the system. To better understand the dataflow programming model, consider an application that asynchronously loads images from disk and creates a composite of those images. Traditional programming models typically require that you use callbacks and synchronization objects, such as locks, to coordinate tasks and access to shared data. By using the dataflow programming model, you can create dataflow objects that process images as they are read from disk. Under the dataflow model, you declare how data is handled when it becomes available, and also any dependencies between data. Because the runtime manages dependencies between data, you can often avoid the requirement to synchronize access to shared data. In addition, because the runtime schedules work based on the asynchronous arrival of data, dataflow can improve responsiveness and throughput by efficiently managing the underlying threads. For an example that uses the dataflow programming model to implement image processing in a Windows Forms application, see [Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md). - -### Sources and Targets + The TPL Dataflow Library provides a foundation for message passing and parallelizing CPU-intensive and I/O-intensive applications that have high throughput and low latency. It also gives you explicit control over how data is buffered and moves around the system. To better understand the dataflow programming model, consider an application that asynchronously loads images from disk and creates a composite of those images. Traditional programming models typically require that you use callbacks and synchronization objects, such as locks, to coordinate tasks and access to shared data. By using the dataflow programming model, you can create dataflow objects that process images as they are read from disk. Under the dataflow model, you declare how data is handled when it becomes available, and also any dependencies between data. Because the runtime manages dependencies between data, you can often avoid the requirement to synchronize access to shared data. In addition, because the runtime schedules work based on the asynchronous arrival of data, dataflow can improve responsiveness and throughput by efficiently managing the underlying threads. For an example that uses the dataflow programming model to implement image processing in a Windows Forms application, see [Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md). + +### Sources and Targets + + The TPL Dataflow Library consists of *dataflow blocks*, which are data structures that buffer and process data. The TPL defines three kinds of dataflow blocks: *source blocks*, *target blocks*, and *propagator blocks*. A source block acts as a source of data and can be read from. A target block acts as a receiver of data and can be written to. A propagator block acts as both a source block and a target block, and can be read from and written to. The TPL defines the interface to represent sources, to represent targets, and to represent propagators. inherits from both , and . + + The TPL Dataflow Library provides several predefined dataflow block types that implement the , , and interfaces. These dataflow block types are described in this document in the section [Predefined Dataflow Block Types](#predefined-dataflow-block-types). + +### Connecting Blocks + + You can connect dataflow blocks to form *pipelines*, which are linear sequences of dataflow blocks, or *networks*, which are graphs of dataflow blocks. A pipeline is one form of network. In a pipeline or network, sources asynchronously propagate data to targets as that data becomes available. The method links a source dataflow block to a target block. A source can be linked to zero or more targets; targets can be linked from zero or more sources. You can add or remove dataflow blocks to or from a pipeline or network concurrently. The predefined dataflow block types handle all thread-safety aspects of linking and unlinking. + + For an example that connects dataflow blocks to form a basic pipeline, see [Walkthrough: Creating a Dataflow Pipeline](walkthrough-creating-a-dataflow-pipeline.md). For an example that connects dataflow blocks to form a more complex network, see [Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md). For an example that unlinks a target from a source after the source offers the target a message, see [How to: Unlink Dataflow Blocks](how-to-unlink-dataflow-blocks.md). - The TPL Dataflow Library consists of *dataflow blocks*, which are data structures that buffer and process data. The TPL defines three kinds of dataflow blocks: *source blocks*, *target blocks*, and *propagator blocks*. A source block acts as a source of data and can be read from. A target block acts as a receiver of data and can be written to. A propagator block acts as both a source block and a target block, and can be read from and written to. The TPL defines the interface to represent sources, to represent targets, and to represent propagators. inherits from both , and . - - The TPL Dataflow Library provides several predefined dataflow block types that implement the , , and interfaces. These dataflow block types are described in this document in the section [Predefined Dataflow Block Types](#predefined-dataflow-block-types). - -### Connecting Blocks +#### Filtering - You can connect dataflow blocks to form *pipelines*, which are linear sequences of dataflow blocks, or *networks*, which are graphs of dataflow blocks. A pipeline is one form of network. In a pipeline or network, sources asynchronously propagate data to targets as that data becomes available. The method links a source dataflow block to a target block. A source can be linked to zero or more targets; targets can be linked from zero or more sources. You can add or remove dataflow blocks to or from a pipeline or network concurrently. The predefined dataflow block types handle all thread-safety aspects of linking and unlinking. - - For an example that connects dataflow blocks to form a basic pipeline, see [Walkthrough: Creating a Dataflow Pipeline](walkthrough-creating-a-dataflow-pipeline.md). For an example that connects dataflow blocks to form a more complex network, see [Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md). For an example that unlinks a target from a source after the source offers the target a message, see [How to: Unlink Dataflow Blocks](how-to-unlink-dataflow-blocks.md). - -#### Filtering + When you call the method to link a source to a target, you can supply a delegate that determines whether the target block accepts or rejects a message based on the value of that message. This filtering mechanism is a useful way to guarantee that a dataflow block receives only certain values. For most of the predefined dataflow block types, if a source block is connected to multiple target blocks, when a target block rejects a message, the source offers that message to the next target. The order in which a source offers messages to targets is defined by the source and can vary according to the type of the source. Most source block types stop offering a message after one target accepts that message. One exception to this rule is the class, which offers each message to all targets, even if some targets reject the message. For an example that uses filtering to process only certain messages, see [Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md). - When you call the method to link a source to a target, you can supply a delegate that determines whether the target block accepts or rejects a message based on the value of that message. This filtering mechanism is a useful way to guarantee that a dataflow block receives only certain values. For most of the predefined dataflow block types, if a source block is connected to multiple target blocks, when a target block rejects a message, the source offers that message to the next target. The order in which a source offers messages to targets is defined by the source and can vary according to the type of the source. Most source block types stop offering a message after one target accepts that message. One exception to this rule is the class, which offers each message to all targets, even if some targets reject the message. For an example that uses filtering to process only certain messages, see [Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md). - > [!IMPORTANT] -> Because each predefined source dataflow block type guarantees that messages are propagated out in the order in which they are received, every message must be read from the source block before the source block can process the next message. Therefore, when you use filtering to connect multiple targets to a source, make sure that at least one target block receives each message. Otherwise, your application might deadlock. - -### Message Passing - - The dataflow programming model is related to the concept of *message passing*, where independent components of a program communicate with one another by sending messages. One way to propagate messages among application components is to call the (synchronous) and (asynchronous) methods to send messages to target dataflow blocks, and the , , and methods to receive messages from source blocks. You can combine these methods with dataflow pipelines or networks by sending input data to the head node (a target block), and by receiving output data from the terminal node of the pipeline or the terminal nodes of the network (one or more source blocks). You can also use the method to read from the first of the provided sources that has data available and perform action on that data. - - Source blocks offer data to target blocks by calling the method. The target block responds to an offered message in one of three ways: it can accept the message, decline the message, or postpone the message. When the target accepts the message, the method returns . When the target declines the message, the method returns . When the target requires that it no longer receives any messages from the source, returns . The predefined source block types don't offer messages to linked targets after such a return value is received, and they automatically unlink from such targets. - - When a target block postpones the message for later use, the method returns . A target block that postpones a message can later call the method to try to reserve the offered message. At this point, the message is either still available and can be used by the target block, or the message has been taken by another target. When the target block later requires the message or no longer needs the message, it calls the or method, respectively. Message reservation is typically used by the dataflow block types that operate in non-greedy mode. Non-greedy mode is explained later in this document. Instead of reserving a postponed message, a target block can also use the method to attempt to directly consume the postponed message. - -### Dataflow Block Completion - - Dataflow blocks also support the concept of *completion*. A dataflow block that is in the completed state doesn't perform any further work. Each dataflow block has an associated object, known as a *completion task*, that represents the completion status of the block. Because you can wait for a object to finish, by using completion tasks, you can wait for one or more terminal nodes of a dataflow network to finish. The interface defines the method, which informs the dataflow block of a request for it to complete, and the property, which returns the completion task for the dataflow block. Both and inherit the interface. - - There are two ways to determine whether a dataflow block completed without error, encountered one or more errors, or was canceled. The first way is to call the method on the completion task in a `try`-`catch` block (`Try`-`Catch` in Visual Basic). The following example creates an object that throws if its input value is less than zero. is thrown when this example calls on the completion task. The is accessed through the property of the object. - +> Because each predefined source dataflow block type guarantees that messages are propagated out in the order in which they are received, every message must be read from the source block before the source block can process the next message. Therefore, when you use filtering to connect multiple targets to a source, make sure that at least one target block receives each message. Otherwise, your application might deadlock. + +### Message Passing + + The dataflow programming model is related to the concept of *message passing*, where independent components of a program communicate with one another by sending messages. One way to propagate messages among application components is to call the (synchronous) and (asynchronous) methods to send messages to target dataflow blocks, and the , , and methods to receive messages from source blocks. You can combine these methods with dataflow pipelines or networks by sending input data to the head node (a target block), and by receiving output data from the terminal node of the pipeline or the terminal nodes of the network (one or more source blocks). You can also use the method to read from the first of the provided sources that has data available and perform action on that data. + + Source blocks offer data to target blocks by calling the method. The target block responds to an offered message in one of three ways: it can accept the message, decline the message, or postpone the message. When the target accepts the message, the method returns . When the target declines the message, the method returns . When the target requires that it no longer receives any messages from the source, returns . The predefined source block types don't offer messages to linked targets after such a return value is received, and they automatically unlink from such targets. + + When a target block postpones the message for later use, the method returns . A target block that postpones a message can later call the method to try to reserve the offered message. At this point, the message is either still available and can be used by the target block, or the message has been taken by another target. When the target block later requires the message or no longer needs the message, it calls the or method, respectively. Message reservation is typically used by the dataflow block types that operate in non-greedy mode. Non-greedy mode is explained later in this document. Instead of reserving a postponed message, a target block can also use the method to attempt to directly consume the postponed message. + +### Dataflow Block Completion + + Dataflow blocks also support the concept of *completion*. A dataflow block that is in the completed state doesn't perform any further work. Each dataflow block has an associated object, known as a *completion task*, that represents the completion status of the block. Because you can wait for a object to finish, by using completion tasks, you can wait for one or more terminal nodes of a dataflow network to finish. The interface defines the method, which informs the dataflow block of a request for it to complete, and the property, which returns the completion task for the dataflow block. Both and inherit the interface. + + There are two ways to determine whether a dataflow block completed without error, encountered one or more errors, or was canceled. The first way is to call the method on the completion task in a `try`-`catch` block (`Try`-`Catch` in Visual Basic). The following example creates an object that throws if its input value is less than zero. is thrown when this example calls on the completion task. The is accessed through the property of the object. + [!code-csharp[TPLDataflow_Overview#10](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#10)] - [!code-vb[TPLDataflow_Overview#10](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#10)] - - This example demonstrates the case in which an exception goes unhandled in the delegate of an execution dataflow block. We recommend that you handle exceptions in the bodies of such blocks. However, if you are unable to do so, the block behaves as though it was canceled and doesn't process incoming messages. - - When a dataflow block is canceled explicitly, the object contains in the property. For more information about dataflow cancellation, see [Enabling Cancellation](#enabling-cancellation) section. - - The second way to determine the completion status of a dataflow block is to use a continuation of the completion task, or to use the asynchronous language features of C# and Visual Basic to asynchronously wait for the completion task. The delegate that you provide to the method takes a object that represents the antecedent task. In the case of the property, the delegate for the continuation takes the completion task itself. The following example resembles the previous one, except that it also uses the method to create a continuation task that prints the status of the overall dataflow operation. - + [!code-vb[TPLDataflow_Overview#10](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#10)] + + This example demonstrates the case in which an exception goes unhandled in the delegate of an execution dataflow block. We recommend that you handle exceptions in the bodies of such blocks. However, if you are unable to do so, the block behaves as though it was canceled and doesn't process incoming messages. + + When a dataflow block is canceled explicitly, the object contains in the property. For more information about dataflow cancellation, see [Enabling Cancellation](#enabling-cancellation) section. + + The second way to determine the completion status of a dataflow block is to use a continuation of the completion task, or to use the asynchronous language features of C# and Visual Basic to asynchronously wait for the completion task. The delegate that you provide to the method takes a object that represents the antecedent task. In the case of the property, the delegate for the continuation takes the completion task itself. The following example resembles the previous one, except that it also uses the method to create a continuation task that prints the status of the overall dataflow operation. + [!code-csharp[TPLDataflow_Overview#11](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#11)] - [!code-vb[TPLDataflow_Overview#11](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#11)] - - You can also use properties such as in the body of the continuation task to determine additional information about the completion status of a dataflow block. For more information about continuation tasks and how they relate to cancellation and error handling, see [Chaining Tasks by Using Continuation Tasks](chaining-tasks-by-using-continuation-tasks.md), [Task Cancellation](task-cancellation.md), and [Exception Handling](exception-handling-task-parallel-library.md). + [!code-vb[TPLDataflow_Overview#11](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#11)] + + You can also use properties such as in the body of the continuation task to determine additional information about the completion status of a dataflow block. For more information about continuation tasks and how they relate to cancellation and error handling, see [Chaining Tasks by Using Continuation Tasks](chaining-tasks-by-using-continuation-tasks.md), [Task Cancellation](task-cancellation.md), and [Exception Handling](exception-handling-task-parallel-library.md). -## Predefined Dataflow Block Types +## Predefined Dataflow Block Types - The TPL Dataflow Library provides several predefined dataflow block types. These types are divided into three categories: *buffering blocks*, *execution blocks*, and *grouping blocks*. The following sections describe the block types that make up these categories. - -### Buffering Blocks + The TPL Dataflow Library provides several predefined dataflow block types. These types are divided into three categories: *buffering blocks*, *execution blocks*, and *grouping blocks*. The following sections describe the block types that make up these categories. - Buffering blocks hold data for use by data consumers. The TPL Dataflow Library provides three buffering block types: , , and . - -#### BufferBlock\ +### Buffering Blocks + + Buffering blocks hold data for use by data consumers. The TPL Dataflow Library provides three buffering block types: , , and . + +#### BufferBlock\ + + The class represents a general-purpose asynchronous messaging structure. This class stores a first in, first out (FIFO) queue of messages that can be written to by multiple sources or read from by multiple targets. When a target receives a message from a object, that message is removed from the message queue. Therefore, although a object can have multiple targets, only one target will receive each message. The class is useful when you want to pass multiple messages to another component, and that component must receive each message. + + The following basic example posts several values to a object and then reads those values back from that object. - The class represents a general-purpose asynchronous messaging structure. This class stores a first in, first out (FIFO) queue of messages that can be written to by multiple sources or read from by multiple targets. When a target receives a message from a object, that message is removed from the message queue. Therefore, although a object can have multiple targets, only one target will receive each message. The class is useful when you want to pass multiple messages to another component, and that component must receive each message. - - The following basic example posts several values to a object and then reads those values back from that object. - [!code-csharp[TPLDataflow_Overview#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#1)] - [!code-vb[TPLDataflow_Overview#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#1)] - - For a complete example that demonstrates how to write messages to and read messages from a object, see [How to: Write Messages to and Read Messages from a Dataflow Block](how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md). - -#### BroadcastBlock\ - - The class is useful when you must pass multiple messages to another component, but that component needs only the most recent value. This class is also useful when you want to broadcast a message to multiple components. - - The following basic example posts a value to a object and then reads that value back from that object several times. Because values aren't removed from objects after they are read, the same value is available every time. - + [!code-vb[TPLDataflow_Overview#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#1)] + + For a complete example that demonstrates how to write messages to and read messages from a object, see [How to: Write Messages to and Read Messages from a Dataflow Block](how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md). + +#### BroadcastBlock\ + + The class is useful when you must pass multiple messages to another component, but that component needs only the most recent value. This class is also useful when you want to broadcast a message to multiple components. + + The following basic example posts a value to a object and then reads that value back from that object several times. Because values aren't removed from objects after they are read, the same value is available every time. + [!code-csharp[TPLDataflow_Overview#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#2)] - [!code-vb[TPLDataflow_Overview#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#2)] - - For a complete example that demonstrates how to use to broadcast a message to multiple target blocks, see [How to: Specify a Task Scheduler in a Dataflow Block](how-to-specify-a-task-scheduler-in-a-dataflow-block.md). - -#### WriteOnceBlock\ - - The class resembles the class, except that a object can be written to one time only. You can think of as being similar to the C# [readonly](../../csharp/language-reference/keywords/readonly.md) ([ReadOnly](../../visual-basic/language-reference/modifiers/readonly.md) in Visual Basic) keyword, except that a object becomes immutable after it receives a value instead of at construction. Like the class, when a target receives a message from a object, that message isn't removed from that object. Therefore, multiple targets receive a copy of the message. The class is useful when you want to propagate only the first of multiple messages. - - The following basic example posts multiple values to a object and then reads the value back from that object. Because a object can be written to one time only, after a object receives a message, it discards subsequent messages. - + [!code-vb[TPLDataflow_Overview#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#2)] + + For a complete example that demonstrates how to use to broadcast a message to multiple target blocks, see [How to: Specify a Task Scheduler in a Dataflow Block](how-to-specify-a-task-scheduler-in-a-dataflow-block.md). + +#### WriteOnceBlock\ + + The class resembles the class, except that a object can be written to one time only. You can think of as being similar to the C# [readonly](../../csharp/language-reference/keywords/readonly.md) ([ReadOnly](../../visual-basic/language-reference/modifiers/readonly.md) in Visual Basic) keyword, except that a object becomes immutable after it receives a value instead of at construction. Like the class, when a target receives a message from a object, that message isn't removed from that object. Therefore, multiple targets receive a copy of the message. The class is useful when you want to propagate only the first of multiple messages. + + The following basic example posts multiple values to a object and then reads the value back from that object. Because a object can be written to one time only, after a object receives a message, it discards subsequent messages. + [!code-csharp[TPLDataflow_Overview#3](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#3)] - [!code-vb[TPLDataflow_Overview#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#3)] - - For a complete example that demonstrates how to use to receive the value of the first operation that finishes, see [How to: Unlink Dataflow Blocks](how-to-unlink-dataflow-blocks.md). - -### Execution Blocks - - Execution blocks call a user-provided delegate for each piece of received data. The TPL Dataflow Library provides three execution block types: , , and . - -#### ActionBlock\ - - The class is a target block that calls a delegate when it receives data. Think of a object as a delegate that runs asynchronously when data becomes available. The delegate that you provide to an object can be of type or type `System.Func`. When you use an object with , processing of each input element is considered completed when the delegate returns. When you use an object with `System.Func`, processing of each input element is considered completed only when the returned object is completed. By using these two mechanisms, you can use for both synchronous and asynchronous processing of each input element. - - The following basic example posts multiple values to an object. The object prints those values to the console. This example then sets the block to the completed state and waits for all dataflow tasks to finish. - + [!code-vb[TPLDataflow_Overview#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#3)] + + For a complete example that demonstrates how to use to receive the value of the first operation that finishes, see [How to: Unlink Dataflow Blocks](how-to-unlink-dataflow-blocks.md). + +### Execution Blocks + + Execution blocks call a user-provided delegate for each piece of received data. The TPL Dataflow Library provides three execution block types: , , and . + +#### ActionBlock\ + + The class is a target block that calls a delegate when it receives data. Think of a object as a delegate that runs asynchronously when data becomes available. The delegate that you provide to an object can be of type or type `System.Func`. When you use an object with , processing of each input element is considered completed when the delegate returns. When you use an object with `System.Func`, processing of each input element is considered completed only when the returned object is completed. By using these two mechanisms, you can use for both synchronous and asynchronous processing of each input element. + + The following basic example posts multiple values to an object. The object prints those values to the console. This example then sets the block to the completed state and waits for all dataflow tasks to finish. + [!code-csharp[TPLDataflow_Overview#4](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#4)] - [!code-vb[TPLDataflow_Overview#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#4)] - - For complete examples that demonstrate how to use delegates with the class, see [How to: Perform Action When a Dataflow Block Receives Data](how-to-perform-action-when-a-dataflow-block-receives-data.md). - -#### TransformBlock\ - - The class resembles the class, except that it acts as both a source and as a target. The delegate that you pass to a object returns a value of type `TOutput`. The delegate that you provide to a object can be of type `System.Func` or type `System.Func>`. When you use a object with `System.Func`, processing of each input element is considered completed when the delegate returns. When you use a object used with `System.Func>`, processing of each input element is considered completed only when the returned object is completed. As with , by using these two mechanisms, you can use for both synchronous and asynchronous processing of each input element. - - The following basic example creates a object that computes the square root of its input. The object takes values as input and produces values as output. - + [!code-vb[TPLDataflow_Overview#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#4)] + + For complete examples that demonstrate how to use delegates with the class, see [How to: Perform Action When a Dataflow Block Receives Data](how-to-perform-action-when-a-dataflow-block-receives-data.md). + +#### TransformBlock\ + + The class resembles the class, except that it acts as both a source and as a target. The delegate that you pass to a object returns a value of type `TOutput`. The delegate that you provide to a object can be of type `System.Func` or type `System.Func>`. When you use a object with `System.Func`, processing of each input element is considered completed when the delegate returns. When you use a object used with `System.Func>`, processing of each input element is considered completed only when the returned object is completed. As with , by using these two mechanisms, you can use for both synchronous and asynchronous processing of each input element. + + The following basic example creates a object that computes the square root of its input. The object takes values as input and produces values as output. + [!code-csharp[TPLDataflow_Overview#5](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#5)] - [!code-vb[TPLDataflow_Overview#5](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#5)] - - For complete examples that uses in a network of dataflow blocks that performs image processing in a Windows Forms application, see [Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md). - -#### TransformManyBlock\ - - The class resembles the class, except that produces zero or more output values for each input value, instead of only one output value for each input value. The delegate that you provide to a object can be of type `System.Func>` or type `System.Func>>`. When you use a object with `System.Func>`, processing of each input element is considered completed when the delegate returns. When you use a object with `System.Func>>`, processing of each input element is considered complete only when the returned `System.Threading.Tasks.Task>` object is completed. - - The following basic example creates a object that splits strings into their individual character sequences. The object takes values as input and produces values as output. - + [!code-vb[TPLDataflow_Overview#5](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#5)] + + For complete examples that uses in a network of dataflow blocks that performs image processing in a Windows Forms application, see [Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md). + +#### TransformManyBlock\ + + The class resembles the class, except that produces zero or more output values for each input value, instead of only one output value for each input value. The delegate that you provide to a object can be of type `System.Func>` or type `System.Func>>`. When you use a object with `System.Func>`, processing of each input element is considered completed when the delegate returns. When you use a object with `System.Func>>`, processing of each input element is considered complete only when the returned `System.Threading.Tasks.Task>` object is completed. + + The following basic example creates a object that splits strings into their individual character sequences. The object takes values as input and produces values as output. + [!code-csharp[TPLDataflow_Overview#6](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#6)] - [!code-vb[TPLDataflow_Overview#6](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#6)] - - For complete examples that use to produce multiple independent outputs for each input in a dataflow pipeline, see [Walkthrough: Creating a Dataflow Pipeline](walkthrough-creating-a-dataflow-pipeline.md). - -#### Degree of Parallelism - - Every , , and object buffers input messages until the block is ready to process them. By default, these classes process messages in the order in which they are received, one message at a time. You can also specify the degree of parallelism to enable , and objects to process multiple messages concurrently. For more information about concurrent execution, see the section Specifying the Degree of Parallelism later in this document. For an example that sets the degree of parallelism to enable an execution dataflow block to process more than one message at a time, see [How to: Specify the Degree of Parallelism in a Dataflow Block](how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md). - -#### Summary of Delegate Types - - The following table summarizes the delegate types that you can provide to , , and objects. This table also specifies whether the delegate type operates synchronously or asynchronously. - -|Type|Synchronous Delegate Type|Asynchronous Delegate Type| -|----------|-------------------------------|--------------------------------| -||`System.Action`|`System.Func`| -||`System.Func`|`System.Func>`| -||`System.Func>`|`System.Func>>`| - - You can also use lambda expressions when you work with execution block types. For an example that shows how to use a lambda expression with an execution block, see [How to: Perform Action When a Dataflow Block Receives Data](how-to-perform-action-when-a-dataflow-block-receives-data.md). - -### Grouping Blocks - - Grouping blocks combine data from one or more sources and under various constraints. The TPL Dataflow Library provides three join block types: , , and . - -#### BatchBlock\ - - The class combines sets of input data, which are known as batches, into arrays of output data. You specify the size of each batch when you create a object. When the object receives the specified count of input elements, it asynchronously propagates out an array that contains those elements. If a object is set to the completed state but doesn't contain enough elements to form a batch, it propagates out a final array that contains the remaining input elements. - - The class operates in either *greedy* or *non-greedy* mode. In greedy mode, which is the default, a object accepts every message that it is offered and propagates out an array after it receives the specified count of elements. In non-greedy mode, a object postpones all incoming messages until enough sources have offered messages to the block to form a batch. Greedy mode typically performs better than non-greedy mode because it requires less processing overhead. However, you can use non-greedy mode when you must coordinate consumption from multiple sources in an atomic fashion. Specify non-greedy mode by setting to `False` in the `dataflowBlockOptions` parameter in the constructor. - - The following basic example posts several values to a object that holds ten elements in a batch. To guarantee that all values propagate out of the , this example calls the method. The method sets the object to the completed state, and therefore, the object propagates out any remaining elements as a final batch. - + [!code-vb[TPLDataflow_Overview#6](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#6)] + + For complete examples that use to produce multiple independent outputs for each input in a dataflow pipeline, see [Walkthrough: Creating a Dataflow Pipeline](walkthrough-creating-a-dataflow-pipeline.md). + +#### Degree of Parallelism + + Every , , and object buffers input messages until the block is ready to process them. By default, these classes process messages in the order in which they are received, one message at a time. You can also specify the degree of parallelism to enable , and objects to process multiple messages concurrently. For more information about concurrent execution, see the section Specifying the Degree of Parallelism later in this document. For an example that sets the degree of parallelism to enable an execution dataflow block to process more than one message at a time, see [How to: Specify the Degree of Parallelism in a Dataflow Block](how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md). + +#### Summary of Delegate Types + + The following table summarizes the delegate types that you can provide to , , and objects. This table also specifies whether the delegate type operates synchronously or asynchronously. + +|Type|Synchronous Delegate Type|Asynchronous Delegate Type| +|----------|-------------------------------|--------------------------------| +||`System.Action`|`System.Func`| +||`System.Func`|`System.Func>`| +||`System.Func>`|`System.Func>>`| + + You can also use lambda expressions when you work with execution block types. For an example that shows how to use a lambda expression with an execution block, see [How to: Perform Action When a Dataflow Block Receives Data](how-to-perform-action-when-a-dataflow-block-receives-data.md). + +### Grouping Blocks + + Grouping blocks combine data from one or more sources and under various constraints. The TPL Dataflow Library provides three join block types: , , and . + +#### BatchBlock\ + + The class combines sets of input data, which are known as batches, into arrays of output data. You specify the size of each batch when you create a object. When the object receives the specified count of input elements, it asynchronously propagates out an array that contains those elements. If a object is set to the completed state but doesn't contain enough elements to form a batch, it propagates out a final array that contains the remaining input elements. + + The class operates in either *greedy* or *non-greedy* mode. In greedy mode, which is the default, a object accepts every message that it is offered and propagates out an array after it receives the specified count of elements. In non-greedy mode, a object postpones all incoming messages until enough sources have offered messages to the block to form a batch. Greedy mode typically performs better than non-greedy mode because it requires less processing overhead. However, you can use non-greedy mode when you must coordinate consumption from multiple sources in an atomic fashion. Specify non-greedy mode by setting to `False` in the `dataflowBlockOptions` parameter in the constructor. + + The following basic example posts several values to a object that holds ten elements in a batch. To guarantee that all values propagate out of the , this example calls the method. The method sets the object to the completed state, and therefore, the object propagates out any remaining elements as a final batch. + [!code-csharp[TPLDataflow_Overview#7](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#7)] - [!code-vb[TPLDataflow_Overview#7](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#7)] - - For a complete example that uses to improve the efficiency of database insert operations, see [Walkthrough: Using BatchBlock and BatchedJoinBlock to Improve Efficiency](walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md). - -#### JoinBlock\ - - The and classes collect input elements and propagate out or objects that contain those elements. The and classes don't inherit from . Instead, they provide properties, , , and , that implement . - - Like , and operate in either greedy or non-greedy mode. In greedy mode, which is the default, a or object accepts every message that it is offered and propagates out a tuple after each of its targets receives at least one message. In non-greedy mode, a or object postpones all incoming messages until all targets have been offered the data that is required to create a tuple. At this point, the block engages in a two-phase commit protocol to atomically retrieve all required items from the sources. This postponement makes it possible for another entity to consume the data in the meantime, to allow the overall system to make forward progress. - - The following basic example demonstrates a case in which a object requires multiple data to compute a value. This example creates a object that requires two values and a value to perform an arithmetic operation. - + [!code-vb[TPLDataflow_Overview#7](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#7)] + + For a complete example that uses to improve the efficiency of database insert operations, see [Walkthrough: Using BatchBlock and BatchedJoinBlock to Improve Efficiency](walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md). + +#### JoinBlock\ + + The and classes collect input elements and propagate out or objects that contain those elements. The and classes don't inherit from . Instead, they provide properties, , , and , that implement . + + Like , and operate in either greedy or non-greedy mode. In greedy mode, which is the default, a or object accepts every message that it is offered and propagates out a tuple after each of its targets receives at least one message. In non-greedy mode, a or object postpones all incoming messages until all targets have been offered the data that is required to create a tuple. At this point, the block engages in a two-phase commit protocol to atomically retrieve all required items from the sources. This postponement makes it possible for another entity to consume the data in the meantime, to allow the overall system to make forward progress. + + The following basic example demonstrates a case in which a object requires multiple data to compute a value. This example creates a object that requires two values and a value to perform an arithmetic operation. + [!code-csharp[TPLDataflow_Overview#8](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#8)] - [!code-vb[TPLDataflow_Overview#8](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#8)] - - For a complete example that uses objects in non-greedy mode to cooperatively share a resource, see [How to: Use JoinBlock to Read Data From Multiple Sources](how-to-use-joinblock-to-read-data-from-multiple-sources.md). - -#### BatchedJoinBlock\ - - The and classes collect batches of input elements and propagate out `System.Tuple(IList(T1), IList(T2))` or `System.Tuple(IList(T1), IList(T2), IList(T3))` objects that contain those elements. Think of as a combination of and . Specify the size of each batch when you create a object. also provides properties, and , that implement . When the specified count of input elements are received from across all targets, the object asynchronously propagates out a `System.Tuple(IList(T1), IList(T2))` object that contains those elements. - - The following basic example creates a object that holds results, values, and errors that are objects. This example performs multiple operations and writes results to the property, and errors to the property, of the object. Because the count of successful and failed operations is unknown in advance, the objects enable each target to receive zero or more values. - + [!code-vb[TPLDataflow_Overview#8](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#8)] + + For a complete example that uses objects in non-greedy mode to cooperatively share a resource, see [How to: Use JoinBlock to Read Data From Multiple Sources](how-to-use-joinblock-to-read-data-from-multiple-sources.md). + +#### BatchedJoinBlock\ + + The and classes collect batches of input elements and propagate out `System.Tuple(IList(T1), IList(T2))` or `System.Tuple(IList(T1), IList(T2), IList(T3))` objects that contain those elements. Think of as a combination of and . Specify the size of each batch when you create a object. also provides properties, and , that implement . When the specified count of input elements are received from across all targets, the object asynchronously propagates out a `System.Tuple(IList(T1), IList(T2))` object that contains those elements. + + The following basic example creates a object that holds results, values, and errors that are objects. This example performs multiple operations and writes results to the property, and errors to the property, of the object. Because the count of successful and failed operations is unknown in advance, the objects enable each target to receive zero or more values. + [!code-csharp[TPLDataflow_Overview#9](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#9)] - [!code-vb[TPLDataflow_Overview#9](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#9)] - - For a complete example that uses to capture both the results and any exceptions that occur while the program reads from a database, see [Walkthrough: Using BatchBlock and BatchedJoinBlock to Improve Efficiency](walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md). - -## Configuring Dataflow Block Behavior - - You can enable additional options by providing a object to the constructor of dataflow block types. These options control behavior such the scheduler that manages the underlying task and the degree of parallelism. The also has derived types that specify behavior that is specific to certain dataflow block types. The following table summarizes which options type is associated with each dataflow block type. - -|Dataflow Block Type| type| -|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -||| -||| -||| -||| -||| -||| -||| -||| -||| - - The following sections provide additional information about the important kinds of dataflow block options that are available through the , , and classes. - -### Specifying the Task Scheduler - - Every predefined dataflow block uses the TPL task scheduling mechanism to perform activities such as propagating data to a target, receiving data from a source, and running user-defined delegates when data becomes available. is an abstract class that represents a task scheduler that queues tasks onto threads. The default task scheduler, , uses the class to queue and execute work. You can override the default task scheduler by setting the property when you construct a dataflow block object. - - When the same task scheduler manages multiple dataflow blocks, it can enforce policies across them. For example, if multiple dataflow blocks are each configured to target the exclusive scheduler of the same object, all work that runs across these blocks is serialized. Similarly, if these blocks are configured to target the concurrent scheduler of the same object, and that scheduler is configured to have a maximum concurrency level, all work from these blocks is limited to that number of concurrent operations. For an example that uses the class to enable read operations to occur in parallel, but write operations to occur exclusively of all other operations, see [How to: Specify a Task Scheduler in a Dataflow Block](how-to-specify-a-task-scheduler-in-a-dataflow-block.md). For more information about task schedulers in the TPL, see the class topic. - -### Specifying the Degree of Parallelism - - By default, the three execution block types that the TPL Dataflow Library provides, , , and , process one message at a time. These dataflow block types also process messages in the order in which they are received. To enable these dataflow blocks to process messages concurrently, set the property when you construct the dataflow block object. - - The default value of is 1, which guarantees that the dataflow block processes one message at a time. Setting this property to a value that is larger than 1 enables the dataflow block to process multiple messages concurrently. Setting this property to enables the underlying task scheduler to manage the maximum degree of concurrency. - + [!code-vb[TPLDataflow_Overview#9](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#9)] + + For a complete example that uses to capture both the results and any exceptions that occur while the program reads from a database, see [Walkthrough: Using BatchBlock and BatchedJoinBlock to Improve Efficiency](walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md). + +## Configuring Dataflow Block Behavior + + You can enable additional options by providing a object to the constructor of dataflow block types. These options control behavior such the scheduler that manages the underlying task and the degree of parallelism. The also has derived types that specify behavior that is specific to certain dataflow block types. The following table summarizes which options type is associated with each dataflow block type. + +|Dataflow Block Type| type| +|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +||| +||| +||| +||| +||| +||| +||| +||| +||| + + The following sections provide additional information about the important kinds of dataflow block options that are available through the , , and classes. + +### Specifying the Task Scheduler + + Every predefined dataflow block uses the TPL task scheduling mechanism to perform activities such as propagating data to a target, receiving data from a source, and running user-defined delegates when data becomes available. is an abstract class that represents a task scheduler that queues tasks onto threads. The default task scheduler, , uses the class to queue and execute work. You can override the default task scheduler by setting the property when you construct a dataflow block object. + + When the same task scheduler manages multiple dataflow blocks, it can enforce policies across them. For example, if multiple dataflow blocks are each configured to target the exclusive scheduler of the same object, all work that runs across these blocks is serialized. Similarly, if these blocks are configured to target the concurrent scheduler of the same object, and that scheduler is configured to have a maximum concurrency level, all work from these blocks is limited to that number of concurrent operations. For an example that uses the class to enable read operations to occur in parallel, but write operations to occur exclusively of all other operations, see [How to: Specify a Task Scheduler in a Dataflow Block](how-to-specify-a-task-scheduler-in-a-dataflow-block.md). For more information about task schedulers in the TPL, see the class topic. + +### Specifying the Degree of Parallelism + + By default, the three execution block types that the TPL Dataflow Library provides, , , and , process one message at a time. These dataflow block types also process messages in the order in which they are received. To enable these dataflow blocks to process messages concurrently, set the property when you construct the dataflow block object. + + The default value of is 1, which guarantees that the dataflow block processes one message at a time. Setting this property to a value that is larger than 1 enables the dataflow block to process multiple messages concurrently. Setting this property to enables the underlying task scheduler to manage the maximum degree of concurrency. + > [!IMPORTANT] -> When you specify a maximum degree of parallelism that is larger than 1, multiple messages are processed simultaneously, and therefore messages might not be processed in the order in which they are received. The order in which the messages are output from the block is, however, the same one in which they are received. - - Because the property represents the maximum degree of parallelism, the dataflow block might execute with a lesser degree of parallelism than you specify. The dataflow block might use a lesser degree of parallelism to meet its functional requirements or because there is a lack of available system resources. A dataflow block never chooses more parallelism than you specify. - - The value of the property is exclusive to each dataflow block object. For example, if four dataflow block objects each specify 1 for the maximum degree of parallelism, all four dataflow block objects can potentially run in parallel. - - For an example that sets the maximum degree of parallelism to enable lengthy operations to occur in parallel, see [How to: Specify the Degree of Parallelism in a Dataflow Block](how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md). - -### Specifying the Number of Messages per Task - - The predefined dataflow block types use tasks to process multiple input elements. This helps minimize the number of task objects that are required to process data, which enables applications to run more efficiently. However, when the tasks from one set of dataflow blocks are processing data, the tasks from other dataflow blocks might need to wait for processing time by queuing messages. To enable better fairness among dataflow tasks, set the property. When is set to , which is the default, the task used by a dataflow block processes as many messages as are available. When is set to a value other than , the dataflow block processes at most this number of messages per object. Although setting the property can increase fairness among tasks, it can cause the system to create more tasks than are necessary, which can decrease performance. - -### Enabling Cancellation - - The TPL provides a mechanism that enables tasks to coordinate cancellation in a cooperative manner. To enable dataflow blocks to participate in this cancellation mechanism, set the property. When this object is set to the canceled state, all dataflow blocks that monitor this token finish execution of their current item but don't start processing subsequent items. These dataflow blocks also clear any buffered messages, release connections to any source and target blocks, and transition to the canceled state. By transitioning to the canceled state, the property has the property set to , unless an exception occurred during processing. In that case, is set to . - - For an example that demonstrates how to use cancellation in a Windows Forms application, see [How to: Cancel a Dataflow Block](how-to-cancel-a-dataflow-block.md). For more information about cancellation in the TPL, see [Task Cancellation](task-cancellation.md). - -### Specifying Greedy Versus Non-Greedy Behavior - - Several grouping dataflow block types can operate in either *greedy* or *non-greedy* mode. By default, the predefined dataflow block types operate in greedy mode. - - For join block types such as , greedy mode means that the block immediately accepts data even if the corresponding data with which to join isn't yet available. Non-greedy mode means that the block postpones all incoming messages until one is available on each of its targets to complete the join. If any of the postponed messages are no longer available, the join block releases all postponed messages and restarts the process. For the class, greedy and non-greedy behavior is similar, except that under non-greedy mode, a object postpones all incoming messages until enough are available from distinct sources to complete a batch. - - To specify non-greedy mode for a dataflow block, set to `False`. For an example that demonstrates how to use non-greedy mode to enable multiple join blocks to share a data source more efficiently, see [How to: Use JoinBlock to Read Data From Multiple Sources](how-to-use-joinblock-to-read-data-from-multiple-sources.md). - -## Custom Dataflow Blocks - - Although the TPL Dataflow Library provides many predefined block types, you can create additional block types that perform custom behavior. Implement the or interfaces directly or use the method to build a complex block that encapsulates the behavior of existing block types. For examples that show how to implement custom dataflow block functionality, see [Walkthrough: Creating a Custom Dataflow Block Type](walkthrough-creating-a-custom-dataflow-block-type.md). - -## Related Topics - -|Title|Description| -|-----------|-----------------| -|[How to: Write Messages to and Read Messages from a Dataflow Block](how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md)|Demonstrates how to write messages to and read messages from a object.| -|[How to: Implement a Producer-Consumer Dataflow Pattern](how-to-implement-a-producer-consumer-dataflow-pattern.md)|Describes how to use the dataflow model to implement a producer-consumer pattern, where the producer sends messages to a dataflow block, and the consumer reads messages from that block.| -|[How to: Perform Action When a Dataflow Block Receives Data](how-to-perform-action-when-a-dataflow-block-receives-data.md)|Describes how to provide delegates to the execution dataflow block types, , , and .| -|[Walkthrough: Creating a Dataflow Pipeline](walkthrough-creating-a-dataflow-pipeline.md)|Describes how to create a dataflow pipeline that downloads text from the web and performs operations on that text.| -|[How to: Unlink Dataflow Blocks](how-to-unlink-dataflow-blocks.md)|Demonstrates how to use the method to unlink a target block from its source after the source offers a message to the target.| -|[Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md)|Demonstrates how to create a network of dataflow blocks that perform image processing in a Windows Forms application.| -|[How to: Cancel a Dataflow Block](how-to-cancel-a-dataflow-block.md)|Demonstrates how to use cancellation in a Windows Forms application.| -|[How to: Use JoinBlock to Read Data From Multiple Sources](how-to-use-joinblock-to-read-data-from-multiple-sources.md)|Explains how to use the class to perform an operation when data is available from multiple sources, and how to use non-greedy mode to enable multiple join blocks to share a data source more efficiently.| -|[How to: Specify the Degree of Parallelism in a Dataflow Block](how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md)|Describes how to set the property to enable an execution dataflow block to process more than one message at a time.| -|[How to: Specify a Task Scheduler in a Dataflow Block](how-to-specify-a-task-scheduler-in-a-dataflow-block.md)|Demonstrates how to associate a specific task scheduler when you use dataflow in your application.| -|[Walkthrough: Using BatchBlock and BatchedJoinBlock to Improve Efficiency](walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md)|Describes how to use the class to improve the efficiency of database insert operations, and how to use the class to capture both the results and any exceptions that occur while the program reads from a database.| -|[Walkthrough: Creating a Custom Dataflow Block Type](walkthrough-creating-a-custom-dataflow-block-type.md)|Demonstrates two ways to create a dataflow block type that implements custom behavior.| +> When you specify a maximum degree of parallelism that is larger than 1, multiple messages are processed simultaneously, and therefore messages might not be processed in the order in which they are received. The order in which the messages are output from the block is, however, the same one in which they are received. + + Because the property represents the maximum degree of parallelism, the dataflow block might execute with a lesser degree of parallelism than you specify. The dataflow block might use a lesser degree of parallelism to meet its functional requirements or because there is a lack of available system resources. A dataflow block never chooses more parallelism than you specify. + + The value of the property is exclusive to each dataflow block object. For example, if four dataflow block objects each specify 1 for the maximum degree of parallelism, all four dataflow block objects can potentially run in parallel. + + For an example that sets the maximum degree of parallelism to enable lengthy operations to occur in parallel, see [How to: Specify the Degree of Parallelism in a Dataflow Block](how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md). + +### Specifying the Number of Messages per Task + + The predefined dataflow block types use tasks to process multiple input elements. This helps minimize the number of task objects that are required to process data, which enables applications to run more efficiently. However, when the tasks from one set of dataflow blocks are processing data, the tasks from other dataflow blocks might need to wait for processing time by queuing messages. To enable better fairness among dataflow tasks, set the property. When is set to , which is the default, the task used by a dataflow block processes as many messages as are available. When is set to a value other than , the dataflow block processes at most this number of messages per object. Although setting the property can increase fairness among tasks, it can cause the system to create more tasks than are necessary, which can decrease performance. + +### Enabling Cancellation + + The TPL provides a mechanism that enables tasks to coordinate cancellation in a cooperative manner. To enable dataflow blocks to participate in this cancellation mechanism, set the property. When this object is set to the canceled state, all dataflow blocks that monitor this token finish execution of their current item but don't start processing subsequent items. These dataflow blocks also clear any buffered messages, release connections to any source and target blocks, and transition to the canceled state. By transitioning to the canceled state, the property has the property set to , unless an exception occurred during processing. In that case, is set to . + + For an example that demonstrates how to use cancellation in a Windows Forms application, see [How to: Cancel a Dataflow Block](how-to-cancel-a-dataflow-block.md). For more information about cancellation in the TPL, see [Task Cancellation](task-cancellation.md). + +### Specifying Greedy Versus Non-Greedy Behavior + + Several grouping dataflow block types can operate in either *greedy* or *non-greedy* mode. By default, the predefined dataflow block types operate in greedy mode. + + For join block types such as , greedy mode means that the block immediately accepts data even if the corresponding data with which to join isn't yet available. Non-greedy mode means that the block postpones all incoming messages until one is available on each of its targets to complete the join. If any of the postponed messages are no longer available, the join block releases all postponed messages and restarts the process. For the class, greedy and non-greedy behavior is similar, except that under non-greedy mode, a object postpones all incoming messages until enough are available from distinct sources to complete a batch. + + To specify non-greedy mode for a dataflow block, set to `False`. For an example that demonstrates how to use non-greedy mode to enable multiple join blocks to share a data source more efficiently, see [How to: Use JoinBlock to Read Data From Multiple Sources](how-to-use-joinblock-to-read-data-from-multiple-sources.md). + +## Custom Dataflow Blocks + + Although the TPL Dataflow Library provides many predefined block types, you can create additional block types that perform custom behavior. Implement the or interfaces directly or use the method to build a complex block that encapsulates the behavior of existing block types. For examples that show how to implement custom dataflow block functionality, see [Walkthrough: Creating a Custom Dataflow Block Type](walkthrough-creating-a-custom-dataflow-block-type.md). + +## Related Topics + +|Title|Description| +|-----------|-----------------| +|[How to: Write Messages to and Read Messages from a Dataflow Block](how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md)|Demonstrates how to write messages to and read messages from a object.| +|[How to: Implement a Producer-Consumer Dataflow Pattern](how-to-implement-a-producer-consumer-dataflow-pattern.md)|Describes how to use the dataflow model to implement a producer-consumer pattern, where the producer sends messages to a dataflow block, and the consumer reads messages from that block.| +|[How to: Perform Action When a Dataflow Block Receives Data](how-to-perform-action-when-a-dataflow-block-receives-data.md)|Describes how to provide delegates to the execution dataflow block types, , , and .| +|[Walkthrough: Creating a Dataflow Pipeline](walkthrough-creating-a-dataflow-pipeline.md)|Describes how to create a dataflow pipeline that downloads text from the web and performs operations on that text.| +|[How to: Unlink Dataflow Blocks](how-to-unlink-dataflow-blocks.md)|Demonstrates how to use the method to unlink a target block from its source after the source offers a message to the target.| +|[Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md)|Demonstrates how to create a network of dataflow blocks that perform image processing in a Windows Forms application.| +|[How to: Cancel a Dataflow Block](how-to-cancel-a-dataflow-block.md)|Demonstrates how to use cancellation in a Windows Forms application.| +|[How to: Use JoinBlock to Read Data From Multiple Sources](how-to-use-joinblock-to-read-data-from-multiple-sources.md)|Explains how to use the class to perform an operation when data is available from multiple sources, and how to use non-greedy mode to enable multiple join blocks to share a data source more efficiently.| +|[How to: Specify the Degree of Parallelism in a Dataflow Block](how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md)|Describes how to set the property to enable an execution dataflow block to process more than one message at a time.| +|[How to: Specify a Task Scheduler in a Dataflow Block](how-to-specify-a-task-scheduler-in-a-dataflow-block.md)|Demonstrates how to associate a specific task scheduler when you use dataflow in your application.| +|[Walkthrough: Using BatchBlock and BatchedJoinBlock to Improve Efficiency](walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md)|Describes how to use the class to improve the efficiency of database insert operations, and how to use the class to capture both the results and any exceptions that occur while the program reads from a database.| +|[Walkthrough: Creating a Custom Dataflow Block Type](walkthrough-creating-a-custom-dataflow-block-type.md)|Demonstrates two ways to create a dataflow block type that implements custom behavior.| |[Task Parallel Library (TPL)](task-parallel-library-tpl.md)|Introduces the TPL, a library that simplifies parallel and concurrent programming in .NET Framework applications.| diff --git a/docs/standard/parallel-programming/exception-handling-task-parallel-library.md b/docs/standard/parallel-programming/exception-handling-task-parallel-library.md index 3692de537d4b5..a68bc0ad6e70b 100644 --- a/docs/standard/parallel-programming/exception-handling-task-parallel-library.md +++ b/docs/standard/parallel-programming/exception-handling-task-parallel-library.md @@ -2,18 +2,18 @@ title: "Exception handling (Task Parallel Library)" description: Explore exception handling using the Task Parallel Library (TPL) in .NET. See nested aggregate exceptions, inner exceptions, unobserved task exceptions, & more. ms.date: 06/08/2022 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "tasks, exceptions" ms.assetid: beb51e50-9061-4d3d-908c-56a4f7c2e8c1 --- # Exception handling (Task Parallel Library) -Unhandled exceptions that are thrown by user code that is running inside a task are propagated back to the calling thread, except in certain scenarios that are described later in this topic. Exceptions are propagated when you use one of the static or instance methods, and you handle them by enclosing the call in a `try`/`catch` statement. If a task is the parent of attached child tasks, or if you are waiting on multiple tasks, multiple exceptions could be thrown. +Unhandled exceptions that are thrown by user code that is running inside a task are propagated back to the calling thread, except in certain scenarios that are described later in this topic. Exceptions are propagated when you use one of the static or instance methods, and you handle them by enclosing the call in a `try`/`catch` statement. If a task is the parent of attached child tasks, or if you are waiting on multiple tasks, multiple exceptions could be thrown. -To propagate all the exceptions back to the calling thread, the Task infrastructure wraps them in an instance. The exception has an property that can be enumerated to examine all the original exceptions that were thrown, and handle (or not handle) each one individually. You can also handle the original exceptions by using the method. +To propagate all the exceptions back to the calling thread, the Task infrastructure wraps them in an instance. The exception has an property that can be enumerated to examine all the original exceptions that were thrown, and handle (or not handle) each one individually. You can also handle the original exceptions by using the method. Even if only one exception is thrown, it is still wrapped in an exception, as the following example shows. @@ -22,7 +22,7 @@ Even if only one exception is thrown, it is still wrapped in an and not observing any of the inner exceptions. However, we recommend that you do not do this because it is analogous to catching the base type in non-parallel scenarios. To catch an exception without taking specific actions to recover from it can leave your program in an indeterminate state. -If you do not want to call the method to wait for a task's completion, you can also retrieve the exception from the task's property, as the following example shows. For more information, see the [Observing exceptions by using the Task.Exception property](#observing-exceptions-by-using-the-taskexception-property) section in this topic. +If you do not want to call the method to wait for a task's completion, you can also retrieve the exception from the task's property, as the following example shows. For more information, see the [Observing exceptions by using the Task.Exception property](#observing-exceptions-by-using-the-taskexception-property) section in this topic. [!code-csharp[TPL_Exceptions#29](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/handling22.cs#29)] [!code-vb[TPL_Exceptions#29](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/handling22.vb#29)] @@ -30,7 +30,7 @@ If you do not want to call the [!CAUTION] > The preceding example code includes a `while` loop that polls the task's property to determine when the task has completed. This should never be done in production code as it is very inefficient. -If you do not wait on a task that propagates an exception, or access its property, the exception is escalated according to the .NET exception policy when the task is garbage-collected. +If you do not wait on a task that propagates an exception, or access its property, the exception is escalated according to the .NET exception policy when the task is garbage-collected. When exceptions are allowed to bubble up back to the joining thread, it is possible that a task may continue to process some items after the exception is raised. @@ -39,12 +39,12 @@ When exceptions are allowed to bubble up back to the joining thread, it is possi ## Attached child tasks and nested AggregateExceptions -If a task has an attached child task that throws an exception, that exception is wrapped in an before it is propagated to the parent task, which wraps that exception in its own before it propagates it back to the calling thread. In such cases, the property of the exception that is caught at the , , or method contains one or more instances, not the original exceptions that caused the fault. To avoid having to iterate over nested exceptions, you can use the method to remove all the nested exceptions, so that the property contains the original exceptions. In the following example, nested instances are flattened and handled in just one loop. +If a task has an attached child task that throws an exception, that exception is wrapped in an before it is propagated to the parent task, which wraps that exception in its own before it propagates it back to the calling thread. In such cases, the property of the exception that is caught at the , , or method contains one or more instances, not the original exceptions that caused the fault. To avoid having to iterate over nested exceptions, you can use the method to remove all the nested exceptions, so that the property contains the original exceptions. In the following example, nested instances are flattened and handled in just one loop. [!code-csharp[TPL_Exceptions#22](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/flatten2.cs#22)] [!code-vb[TPL_Exceptions#22](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/flatten2.vb#22)] -You can also use the method to rethrow the inner exceptions from multiple instances thrown by multiple tasks in a single instance, as the following example shows. +You can also use the method to rethrow the inner exceptions from multiple instances thrown by multiple tasks in a single instance, as the following example shows. [!code-csharp[TPL_Exceptions#13](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/taskexceptions2.cs#13)] [!code-vb[TPL_Exceptions#13](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/taskexceptions2.vb#13)] @@ -67,21 +67,21 @@ When user code in a task responds to a cancellation request, the correct procedu ## Using the handle method to filter inner exceptions -You can use the method to filter out exceptions that you can treat as "handled" without using any further logic. In the user delegate that is supplied to the method, you can examine the exception type, its property, or any other information about it that will let you determine whether it is benign. Any exceptions for which the delegate returns `false` are rethrown in a new instance immediately after the method returns. +You can use the method to filter out exceptions that you can treat as "handled" without using any further logic. In the user delegate that is supplied to the method, you can examine the exception type, its property, or any other information about it that will let you determine whether it is benign. Any exceptions for which the delegate returns `false` are rethrown in a new instance immediately after the method returns. -The following example is functionally equivalent to the first example in this topic, which examines each exception in the collection. Instead, this exception handler calls the method object for each exception, and only rethrows exceptions that are not `CustomException` instances. +The following example is functionally equivalent to the first example in this topic, which examines each exception in the collection. Instead, this exception handler calls the method object for each exception, and only rethrows exceptions that are not `CustomException` instances. [!code-csharp[TPL_Exceptions#26](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/handlemethod21.cs#26)] [!code-vb[TPL_Exceptions#26](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/handlemethod21.vb#26)] -The following is a more complete example that uses the method to provide special handling for an exception when enumerating files. +The following is a more complete example that uses the method to provide special handling for an exception when enumerating files. [!code-csharp[TPL_Exceptions#12](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/taskexceptions.cs#12)] [!code-vb[TPL_Exceptions#12](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/taskexceptions.vb#12)] ## Observing exceptions by using the Task.Exception property -If a task completes in the state, its property can be examined to discover which specific exception caused the fault. A good way to observe the property is to use a continuation that runs only if the antecedent task faults, as shown in the following example. +If a task completes in the state, its property can be examined to discover which specific exception caused the fault. A good way to observe the property is to use a continuation that runs only if the antecedent task faults, as shown in the following example. [!code-csharp[TPL_Exceptions#27](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/exceptionprop21.cs#27)] [!code-vb[TPL_Exceptions#27](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/exceptionprop21.vb#27)] @@ -93,7 +93,7 @@ In a meaningful application, the continuation delegate could log detailed inform - `task.Result` - `task.GetAwaiter().GetResult()` -Use a [`try-catch`](../../csharp/language-reference/statements/exception-handling-statements.md#the-try-catch-statement) statement to handle and observe thrown exceptions. Alternatively, observe the exception by accessing the property. +Use a [`try-catch`](../../csharp/language-reference/statements/exception-handling-statements.md#the-try-catch-statement) statement to handle and observe thrown exceptions. Alternatively, observe the exception by accessing the property. > [!IMPORTANT] > The cannot be explicitly caught when using the following expressions: diff --git a/docs/standard/parallel-programming/how-to-cancel-a-dataflow-block.md b/docs/standard/parallel-programming/how-to-cancel-a-dataflow-block.md index fe087ce4fb3eb..7a417b10c5801 100644 --- a/docs/standard/parallel-programming/how-to-cancel-a-dataflow-block.md +++ b/docs/standard/parallel-programming/how-to-cancel-a-dataflow-block.md @@ -23,9 +23,9 @@ This document demonstrates how to enable cancellation in your application. This 2. On the form designer for the main form, Form1.cs (Form1.vb for Visual Basic), add a control. -3. Add a control to the control. Set the property to and the property to **Add Work Items**. +3. Add a control to the control. Set the property to and the property to **Add Work Items**. -4. Add a second control to the control. Set the property to , the property to **Cancel**, and the property to `False`. +4. Add a second control to the control. Set the property to , the property to **Cancel**, and the property to `False`. 5. Add four objects to the control. @@ -57,7 +57,7 @@ This document demonstrates how to enable cancellation in your application. This [!code-csharp[TPLDataflow_CancellationWinForms#4](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_cancellationwinforms/cs/cancellationwinforms/form1.cs#4)] [!code-vb[TPLDataflow_CancellationWinForms#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_cancellationwinforms/vb/cancellationwinforms/form1.vb#4)] - Because the `incrementProgress` and `decrementProgress` dataflow blocks act on the user interface, it is important that these actions occur on the user-interface thread. To accomplish this, during construction these objects each provide an object that has the property set to . The method creates a object that performs work on the current synchronization context. Because the `Form1` constructor is called from the user-interface thread, the actions for the `incrementProgress` and `decrementProgress` dataflow blocks also run on the user-interface thread. + Because the `incrementProgress` and `decrementProgress` dataflow blocks act on the user interface, it is important that these actions occur on the user-interface thread. To accomplish this, during construction these objects each provide an object that has the property set to . The method creates a object that performs work on the current synchronization context. Because the `Form1` constructor is called from the user-interface thread, the actions for the `incrementProgress` and `decrementProgress` dataflow blocks also run on the user-interface thread. This example sets the property when it constructs the members of the pipeline. Because the property permanently cancels dataflow block execution, the whole pipeline must be recreated after the user cancels the operation and then wants to add more work items to the pipeline. For an example that demonstrates an alternative way to cancel a dataflow block so that other work can be performed after an operation is canceled, see [Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md). diff --git a/docs/standard/parallel-programming/how-to-cancel-a-parallel-for-or-foreach-loop.md b/docs/standard/parallel-programming/how-to-cancel-a-parallel-for-or-foreach-loop.md index cac8a8bdc2f0f..fa1f55c4aa689 100644 --- a/docs/standard/parallel-programming/how-to-cancel-a-parallel-for-or-foreach-loop.md +++ b/docs/standard/parallel-programming/how-to-cancel-a-parallel-for-or-foreach-loop.md @@ -13,11 +13,11 @@ ms.assetid: 9d19b591-ea95-4418-8ea7-b6266af9905b # How to: Cancel a Parallel.For or ForEach Loop -The and methods support cancellation through the use of cancellation tokens. For more information about cancellation in general, see [Cancellation](../threading/cancellation-in-managed-threads.md). In a parallel loop, you supply the to the method in the parameter and then enclose the parallel call in a try-catch block. +The and methods support cancellation through the use of cancellation tokens. For more information about cancellation in general, see [Cancellation](../threading/cancellation-in-managed-threads.md). In a parallel loop, you supply the to the method in the parameter and then enclose the parallel call in a try-catch block. ## Example -The following example shows how to cancel a call to . You can apply the same approach to a call. +The following example shows how to cancel a call to . You can apply the same approach to a call. [!code-csharp[TPL_Parallel#29](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_parallel/cs/parallel_cancel.cs#29)] [!code-vb[TPL_Parallel#29](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_parallel/vb/cancelloop.vb#29)] diff --git a/docs/standard/parallel-programming/how-to-cancel-a-plinq-query.md b/docs/standard/parallel-programming/how-to-cancel-a-plinq-query.md index cdc477f3178f5..c0f26e9d3f4c8 100644 --- a/docs/standard/parallel-programming/how-to-cancel-a-plinq-query.md +++ b/docs/standard/parallel-programming/how-to-cancel-a-plinq-query.md @@ -39,7 +39,7 @@ The following example shows how to handle cancellation when you have a computati [!code-csharp[PLINQ#17](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqsamples.cs#17)] [!code-vb[PLINQ#17](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinqsnippets1.vb#17)] -When you handle the cancellation in user code, you do not have to use in the query definition. However, we recommend that you do use , because has no effect on query performance and it enables the cancellation to be handled by query operators and your user code. +When you handle the cancellation in user code, you do not have to use in the query definition. However, we recommend that you do use , because has no effect on query performance and it enables the cancellation to be handled by query operators and your user code. In order to ensure system responsiveness, we recommend that you check for cancellation around once per millisecond; however, any period up to 10 milliseconds is considered acceptable. This frequency should not have a negative impact on your code's performance. diff --git a/docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md b/docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md index 0c0daf37a73eb..aa464acd43c0d 100644 --- a/docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md +++ b/docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md @@ -2,10 +2,10 @@ title: "How to: Cancel a Task and Its Children" description: See examples of how to cancel a task and its children in .NET. The examples cover steps from cancelable task creation, to the notice that the task was canceled. ms.date: 04/09/2024 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "tasks, how to cancel" ms.assetid: 08574301-8331-4719-ad50-9cf7f6ff3048 --- @@ -18,11 +18,11 @@ This example shows how to perform the following tasks: 3. Notice and respond to the cancellation request in your user delegate. 4. Optionally notice on the calling thread that the task was canceled. -The calling thread does not forcibly end the task; it only signals that cancellation is requested. If the task is already running, it is up to the user delegate to notice the request and respond appropriately. If cancellation is requested before the task runs, then the user delegate is never executed and the task object transitions into the Canceled state. +The calling thread does not forcibly end the task; it only signals that cancellation is requested. If the task is already running, it is up to the user delegate to notice the request and respond appropriately. If cancellation is requested before the task runs, then the user delegate is never executed and the task object transitions into the Canceled state. -## Example +## Example -This example shows how to terminate a and its children in response to a cancellation request. It also shows that when a user delegate terminates by throwing a , the calling thread can optionally use the method or method to wait for the tasks to finish. In this case, you must use a `try/catch` block to handle the exceptions on the calling thread. +This example shows how to terminate a and its children in response to a cancellation request. It also shows that when a user delegate terminates by throwing a , the calling thread can optionally use the method or method to wait for the tasks to finish. In this case, you must use a `try/catch` block to handle the exceptions on the calling thread. [!code-csharp[TPL_Cancellation#04](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_cancellation/cs/cancel1.cs#04)] [!code-vb[TPL_Cancellation#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_cancellation/vb/cancel1.vb#04)] @@ -34,7 +34,7 @@ The class is ful - - - -- +- - [Task-based Asynchronous Programming](task-based-asynchronous-programming.md) - [Attached and Detached Child Tasks](attached-and-detached-child-tasks.md) - [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md) diff --git a/docs/standard/parallel-programming/how-to-combine-parallel-and-sequential-linq-queries.md b/docs/standard/parallel-programming/how-to-combine-parallel-and-sequential-linq-queries.md index 87d555f94120e..106d020b6ad7c 100644 --- a/docs/standard/parallel-programming/how-to-combine-parallel-and-sequential-linq-queries.md +++ b/docs/standard/parallel-programming/how-to-combine-parallel-and-sequential-linq-queries.md @@ -2,31 +2,31 @@ description: "Learn more about: How to: Combine Parallel and Sequential LINQ Queries" title: "How to: Combine Parallel and Sequential LINQ Queries" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "parallel queries, combine parallel and sequential" ms.assetid: 1167cfe6-c8aa-4096-94ba-c66c3a4edf4c --- # How to: Combine Parallel and Sequential LINQ Queries -This example shows how to use the method to instruct PLINQ to process all subsequent operators in the query sequentially. Although sequential processing is often slower than parallel, sometimes it's necessary to produce correct results. - +This example shows how to use the method to instruct PLINQ to process all subsequent operators in the query sequentially. Although sequential processing is often slower than parallel, sometimes it's necessary to produce correct results. + > [!NOTE] -> This example is intended to demonstrate usage and might not run faster than the equivalent sequential LINQ to Objects query. For more information about speedup, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). - -## Example +> This example is intended to demonstrate usage and might not run faster than the equivalent sequential LINQ to Objects query. For more information about speedup, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). + +## Example + + The following example shows one scenario in which is required, namely to preserve the ordering that was established in a previous clause of the query. - The following example shows one scenario in which is required, namely to preserve the ordering that was established in a previous clause of the query. - [!code-csharp[PLINQ#24](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqsamples.cs#24)] - [!code-vb[PLINQ#24](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinqsnippets1.vb#24)] - -## Compiling the Code + [!code-vb[PLINQ#24](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinqsnippets1.vb#24)] + +## Compiling the Code + + To compile and run this code, paste it into the [PLINQ Data Sample](plinq-data-sample.md) project, add a line to call the method from `Main`, and press F5. - To compile and run this code, paste it into the [PLINQ Data Sample](plinq-data-sample.md) project, add a line to call the method from `Main`, and press F5. - ## See also - [Parallel LINQ (PLINQ)](introduction-to-plinq.md) diff --git a/docs/standard/parallel-programming/how-to-control-ordering-in-a-plinq-query.md b/docs/standard/parallel-programming/how-to-control-ordering-in-a-plinq-query.md index 226639087c285..3bebf4d8034eb 100644 --- a/docs/standard/parallel-programming/how-to-control-ordering-in-a-plinq-query.md +++ b/docs/standard/parallel-programming/how-to-control-ordering-in-a-plinq-query.md @@ -11,7 +11,7 @@ ms.assetid: c67eccc7-004d-4b2f-987e-919cbbd62ef7 --- # How to: Control Ordering in a PLINQ Query -These examples show how to control the ordering in a PLINQ query by using the extension method. +These examples show how to control the ordering in a PLINQ query by using the extension method. > [!WARNING] > These examples are primarily intended to demonstrate usage, and may or may not run faster than the equivalent sequential LINQ to Objects queries. diff --git a/docs/standard/parallel-programming/how-to-create-and-execute-a-simple-plinq-query.md b/docs/standard/parallel-programming/how-to-create-and-execute-a-simple-plinq-query.md index d9df17cad821e..294297090c032 100644 --- a/docs/standard/parallel-programming/how-to-create-and-execute-a-simple-plinq-query.md +++ b/docs/standard/parallel-programming/how-to-create-and-execute-a-simple-plinq-query.md @@ -2,27 +2,27 @@ description: "Learn more about: How to: Create and Execute a Simple PLINQ Query" title: "How to: Create and Execute a Simple PLINQ Query" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "PLINQ queries, how to create" ms.assetid: 983b4213-bddd-4a44-9262-cbe59186df4c --- # How to: Create and Execute a Simple PLINQ Query -The example in this article shows how to create a simple Parallel Language Integrated Query (LINQ) query by using the extension method on the source sequence and executing the query by using the method. - +The example in this article shows how to create a simple Parallel Language Integrated Query (LINQ) query by using the extension method on the source sequence and executing the query by using the method. + > [!NOTE] -> This documentation uses lambda expressions to define delegates in PLINQ. If you are not familiar with lambda expressions in C# or Visual Basic, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). - -## Example +> This documentation uses lambda expressions to define delegates in PLINQ. If you are not familiar with lambda expressions in C# or Visual Basic, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). + +## Example [!code-csharp[PLINQ#11](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/create1.cs#11)] - [!code-vb[PLINQ#11](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/create1.vb#11)] - - This example demonstrates the basic pattern for creating and executing any Parallel LINQ query when the ordering of the result sequence is not important. Unordered queries are generally faster than ordered queries. The query partitions the source into tasks that are executed asynchronously on multiple threads. The order in which each task completes depends not only on the amount of work involved to process the elements in the partition, but also on external factors such as how the operating system schedules each thread. This example is intended to demonstrate usage, and might not run faster than the equivalent sequential LINQ to Objects query. For more information about speedup, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). For more information about how to preserve the ordering of elements in a query, see [How to: Control Ordering in a PLINQ Query](how-to-control-ordering-in-a-plinq-query.md). - + [!code-vb[PLINQ#11](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/create1.vb#11)] + + This example demonstrates the basic pattern for creating and executing any Parallel LINQ query when the ordering of the result sequence is not important. Unordered queries are generally faster than ordered queries. The query partitions the source into tasks that are executed asynchronously on multiple threads. The order in which each task completes depends not only on the amount of work involved to process the elements in the partition, but also on external factors such as how the operating system schedules each thread. This example is intended to demonstrate usage, and might not run faster than the equivalent sequential LINQ to Objects query. For more information about speedup, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). For more information about how to preserve the ordering of elements in a query, see [How to: Control Ordering in a PLINQ Query](how-to-control-ordering-in-a-plinq-query.md). + ## See also - [Parallel LINQ (PLINQ)](introduction-to-plinq.md) diff --git a/docs/standard/parallel-programming/how-to-create-pre-computed-tasks.md b/docs/standard/parallel-programming/how-to-create-pre-computed-tasks.md index 173ea2cf13ed2..3ff5d02487abb 100644 --- a/docs/standard/parallel-programming/how-to-create-pre-computed-tasks.md +++ b/docs/standard/parallel-programming/how-to-create-pre-computed-tasks.md @@ -12,16 +12,16 @@ ms.assetid: a73eafa2-1f49-4106-a19e-997186029b58 # Create pre-computed tasks -In this article, you'll learn how to use the method to retrieve the results of asynchronous download operations that are held in a cache. The method returns a finished object that holds the provided value as its property. This method is useful when you perform an asynchronous operation that returns a object, and the result of that object is already computed. +In this article, you'll learn how to use the method to retrieve the results of asynchronous download operations that are held in a cache. The method returns a finished object that holds the provided value as its property. This method is useful when you perform an asynchronous operation that returns a object, and the result of that object is already computed. ## Example -The following example downloads strings from the web. It defines the `DownloadStringAsync` method. This method downloads strings from the web asynchronously. This example also uses a object to cache the results of previous operations. If the input address is held in this cache, `DownloadStringAsync` uses the method to produce a object that holds the content at that address. Otherwise, `DownloadStringAsync` downloads the file from the web and adds the result to the cache. +The following example downloads strings from the web. It defines the `DownloadStringAsync` method. This method downloads strings from the web asynchronously. This example also uses a object to cache the results of previous operations. If the input address is held in this cache, `DownloadStringAsync` uses the method to produce a object that holds the content at that address. Otherwise, `DownloadStringAsync` downloads the file from the web and adds the result to the cache. :::code language="csharp" source="snippets/cs/DownloadCache.cs"::: :::code language="vb" source="snippets/vb/DownloadCache.vb"::: -In the preceding example, the first time each url is downloaded, its value is stored in the cache. The method enables the `DownloadStringAsync` method to create objects that hold these pre-computed results. Subsequent calls to download the string return the cached values, and is much faster. +In the preceding example, the first time each url is downloaded, its value is stored in the cache. The method enables the `DownloadStringAsync` method to create objects that hold these pre-computed results. Subsequent calls to download the string return the cached values, and is much faster. ## See also diff --git a/docs/standard/parallel-programming/how-to-handle-exceptions-in-parallel-loops.md b/docs/standard/parallel-programming/how-to-handle-exceptions-in-parallel-loops.md index 27e16bd209f1e..f8a98ea28e503 100644 --- a/docs/standard/parallel-programming/how-to-handle-exceptions-in-parallel-loops.md +++ b/docs/standard/parallel-programming/how-to-handle-exceptions-in-parallel-loops.md @@ -2,29 +2,29 @@ title: "How to: Handle Exceptions in Parallel Loops" description: Learn how to handle exceptions in parallel loops in .NET. See an example of how to wrap all exceptions from the loop in a System.AggregateException. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "parallel loops, how to handle exceptions" ms.assetid: 512f0d5a-4636-4875-b766-88f20044f143 --- # How to: Handle Exceptions in Parallel Loops -The and overloads do not have any special mechanism to handle exceptions that might be thrown. In this respect, they resemble regular `for` and `foreach` loops (`For` and `For Each` in Visual Basic); an unhandled exception causes the loop to terminate as soon as all currently running iterations finish. - - When you add your own exception-handling logic to parallel loops, handle the case in which similar exceptions might be thrown on multiple threads concurrently, and the case in which an exception thrown on one thread causes another exception to be thrown on another thread. You can handle both cases by wrapping all exceptions from the loop in a . The following example shows one possible approach. - +The and overloads do not have any special mechanism to handle exceptions that might be thrown. In this respect, they resemble regular `for` and `foreach` loops (`For` and `For Each` in Visual Basic); an unhandled exception causes the loop to terminate as soon as all currently running iterations finish. + + When you add your own exception-handling logic to parallel loops, handle the case in which similar exceptions might be thrown on multiple threads concurrently, and the case in which an exception thrown on one thread causes another exception to be thrown on another thread. You can handle both cases by wrapping all exceptions from the loop in a . The following example shows one possible approach. + > [!NOTE] -> When "Just My Code" is enabled, Visual Studio in some cases will break on the line that throws the exception and display an error message that says "exception not handled by user code." This error is benign. You can press F5 to continue from it, and see the exception-handling behavior that is demonstrated in the example below. To prevent Visual Studio from breaking on the first error, just uncheck the "Just My Code" checkbox under **Tools, Options, Debugging, General**. - -## Example +> When "Just My Code" is enabled, Visual Studio in some cases will break on the line that throws the exception and display an error message that says "exception not handled by user code." This error is benign. You can press F5 to continue from it, and see the exception-handling behavior that is demonstrated in the example below. To prevent Visual Studio from breaking on the first error, just uncheck the "Just My Code" checkbox under **Tools, Options, Debugging, General**. + +## Example + + In this example, all exceptions are caught and then wrapped in an which is thrown. The caller can decide which exceptions to handle. - In this example, all exceptions are caught and then wrapped in an which is thrown. The caller can decide which exceptions to handle. - [!code-csharp[TPL_Exceptions#08](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/exceptions.cs#08)] - [!code-vb[TPL_Exceptions#08](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/exceptionsinloops.vb#08)] - + [!code-vb[TPL_Exceptions#08](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/exceptionsinloops.vb#08)] + ## See also - [Data Parallelism](data-parallelism-task-parallel-library.md) diff --git a/docs/standard/parallel-programming/how-to-implement-a-partitioner-for-static-partitioning.md b/docs/standard/parallel-programming/how-to-implement-a-partitioner-for-static-partitioning.md index c9cc7e3b9c65f..c49e322797299 100644 --- a/docs/standard/parallel-programming/how-to-implement-a-partitioner-for-static-partitioning.md +++ b/docs/standard/parallel-programming/how-to-implement-a-partitioner-for-static-partitioning.md @@ -2,20 +2,20 @@ description: "Learn more about: How to: Implement a Partitioner for Static Partitioning" title: "How to: Implement a Partitioner for Static Partitioning" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "tasks, how to create a static partitioner" ms.assetid: f4410508-cac6-4ba7-bef1-c5e68b2794f3 --- # How to: Implement a Partitioner for Static Partitioning -The following example shows one way to implement a simple custom partitioner for PLINQ that performs static partitioning. Because the partitioner does not support dynamic partitions, it is not consumable from . This particular partitioner might provide speedup over the default range partitioner for data sources for which each element requires an increasing amount of processing time. - -## Example +The following example shows one way to implement a simple custom partitioner for PLINQ that performs static partitioning. Because the partitioner does not support dynamic partitions, it is not consumable from . This particular partitioner might provide speedup over the default range partitioner for data sources for which each element requires an increasing amount of processing time. + +## Example + + [!code-csharp[TPL_Partitioners#05](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_partitioners/cs/00/partitioners.cs#05)] + + The partitions in this example are based on the assumption of a linear increase in processing time for each element. In the real world, it might be difficult to predict processing times in this way. If you are using a static partitioner with a specific data source, you can optimize the partitioning formula for the source, add load-balancing logic, or use a chunk partitioning approach as demonstrated in [How to: Implement Dynamic Partitions](how-to-implement-dynamic-partitions.md). - [!code-csharp[TPL_Partitioners#05](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_partitioners/cs/00/partitioners.cs#05)] - - The partitions in this example are based on the assumption of a linear increase in processing time for each element. In the real world, it might be difficult to predict processing times in this way. If you are using a static partitioner with a specific data source, you can optimize the partitioning formula for the source, add load-balancing logic, or use a chunk partitioning approach as demonstrated in [How to: Implement Dynamic Partitions](how-to-implement-dynamic-partitions.md). - ## See also - [Custom Partitioners for PLINQ and TPL](custom-partitioners-for-plinq-and-tpl.md) diff --git a/docs/standard/parallel-programming/how-to-implement-a-producer-consumer-dataflow-pattern.md b/docs/standard/parallel-programming/how-to-implement-a-producer-consumer-dataflow-pattern.md index 558cfd738e10d..625e89bfd9724 100644 --- a/docs/standard/parallel-programming/how-to-implement-a-producer-consumer-dataflow-pattern.md +++ b/docs/standard/parallel-programming/how-to-implement-a-producer-consumer-dataflow-pattern.md @@ -20,21 +20,21 @@ In this article, you'll learn how to use the TPL dataflow library to implement a ## Example -The following example demonstrates a basic producer-consumer model that uses dataflow. The `Produce` method writes arrays that contain random bytes of data to a object and the `Consume` method reads bytes from a object. By acting on the and interfaces, instead of their derived types, you can write reusable code that can act on a variety of dataflow block types. This example uses the class. Because the class acts as both a source block and as a target block, the producer and the consumer can use a shared object to transfer data. +The following example demonstrates a basic producer-consumer model that uses dataflow. The `Produce` method writes arrays that contain random bytes of data to a object and the `Consume` method reads bytes from a object. By acting on the and interfaces, instead of their derived types, you can write reusable code that can act on a variety of dataflow block types. This example uses the class. Because the class acts as both a source block and as a target block, the producer and the consumer can use a shared object to transfer data. - The `Produce` method calls the method in a loop to synchronously write data to the target block. After the `Produce` method writes all data to the target block, it calls the method to indicate that the block will never have additional data available. The `Consume` method uses the [async](../../csharp/language-reference/keywords/async.md) and [await](../../csharp/language-reference/operators/await.md) operators ([Async](../../visual-basic/language-reference/modifiers/async.md) and [Await](../../visual-basic/language-reference/operators/await-operator.md) in Visual Basic) to asynchronously compute the total number of bytes that are received from the object. To act asynchronously, the `Consume` method calls the method to receive a notification when the source block has data available and when the source block will never have additional data available. + The `Produce` method calls the method in a loop to synchronously write data to the target block. After the `Produce` method writes all data to the target block, it calls the method to indicate that the block will never have additional data available. The `Consume` method uses the [async](../../csharp/language-reference/keywords/async.md) and [await](../../csharp/language-reference/operators/await.md) operators ([Async](../../visual-basic/language-reference/modifiers/async.md) and [Await](../../visual-basic/language-reference/operators/await-operator.md) in Visual Basic) to asynchronously compute the total number of bytes that are received from the object. To act asynchronously, the `Consume` method calls the method to receive a notification when the source block has data available and when the source block will never have additional data available. [!code-csharp[TPLDataflow_ProducerConsumer#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_producerconsumer/cs/dataflowproducerconsumer.cs#1)] [!code-vb[TPLDataflow_ProducerConsumer#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_producerconsumer/vb/dataflowproducerconsumer.vb#1)] ## Robust programming - The preceding example uses just one consumer to process the source data. If you have multiple consumers in your application, use the method to read data from the source block, as shown in the following example. + The preceding example uses just one consumer to process the source data. If you have multiple consumers in your application, use the method to read data from the source block, as shown in the following example. [!code-csharp[TPLDataflow_ProducerConsumer#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_producerconsumer/cs/dataflowproducerconsumer.cs#2)] [!code-vb[TPLDataflow_ProducerConsumer#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_producerconsumer/vb/dataflowproducerconsumer.vb#2)] - The method returns `False` when no data is available. When multiple consumers must access the source block concurrently, this mechanism guarantees that data is still available after the call to . + The method returns `False` when no data is available. When multiple consumers must access the source block concurrently, this mechanism guarantees that data is still available after the call to . ## See also diff --git a/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md b/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md index 9f533e72623fc..ba8d03a3dbb02 100644 --- a/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md +++ b/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md @@ -2,27 +2,27 @@ description: "Learn more about: How to: Implement Dynamic Partitions" title: "How to: Implement Dynamic Partitions" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "tasks, how to create a dynamic partitioner" ms.assetid: c875ad12-a161-43e6-ad1c-3d6927c536a7 --- # How to: Implement Dynamic Partitions -The following example shows how to implement a custom that implements dynamic partitioning and can be used from certain overloads and from PLINQ. - +The following example shows how to implement a custom that implements dynamic partitioning and can be used from certain overloads and from PLINQ. + ## Example -Each time a partition calls on the enumerator, the enumerator provides the partition with one list element. In the case of PLINQ and , the partition is a instance. Because requests are happening concurrently on multiple threads, access to the current index is synchronized. +Each time a partition calls on the enumerator, the enumerator provides the partition with one list element. In the case of PLINQ and , the partition is a instance. Because requests are happening concurrently on multiple threads, access to the current index is synchronized. [!code-csharp[TPL_Partitioners#04](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_partitioners/cs/01/partitioner02.cs#OrderableListPartitioner)] -[!code-vb[TPL_Partitioners#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_partitioners/vb/dynamicpartitioner.vb#04)] +[!code-vb[TPL_Partitioners#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_partitioners/vb/dynamicpartitioner.vb#04)] + +This is an example of chunk partitioning, with each chunk consisting of one element. By providing more elements at a time, you could reduce the contention over the lock and theoretically achieve faster performance. However, at some point, larger chunks might require additional load-balancing logic in order to keep all threads busy until all the work is done. -This is an example of chunk partitioning, with each chunk consisting of one element. By providing more elements at a time, you could reduce the contention over the lock and theoretically achieve faster performance. However, at some point, larger chunks might require additional load-balancing logic in order to keep all threads busy until all the work is done. - ## See also * [Custom Partitioners for PLINQ and TPL](custom-partitioners-for-plinq-and-tpl.md) diff --git a/docs/standard/parallel-programming/how-to-iterate-file-directories-with-plinq.md b/docs/standard/parallel-programming/how-to-iterate-file-directories-with-plinq.md index 30c40fbbb43d3..a27d080c8b703 100644 --- a/docs/standard/parallel-programming/how-to-iterate-file-directories-with-plinq.md +++ b/docs/standard/parallel-programming/how-to-iterate-file-directories-with-plinq.md @@ -2,35 +2,35 @@ description: "Learn more about: How to: Iterate File Directories with PLINQ" title: "How to: Iterate File Directories with PLINQ" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "PLINQ queries, how to iterate directories" ms.assetid: 354e8ce3-35c4-431c-99ca-7661d1f3901b --- # How to: Iterate File Directories with PLINQ -This article shows two ways to parallelize operations on file directories. The first query uses the method to populate an array of file names in a directory and all subdirectories. This method can introduce latency at the beginning of the operation, because it doesn't return until the entire array is populated. However, after the array is populated, PLINQ can process it in parallel quickly. - -The second query uses the static and methods, which begin returning results immediately. This approach can be faster when you're iterating over large directory trees, but the processing time compared to the first example depends on many factors. - +This article shows two ways to parallelize operations on file directories. The first query uses the method to populate an array of file names in a directory and all subdirectories. This method can introduce latency at the beginning of the operation, because it doesn't return until the entire array is populated. However, after the array is populated, PLINQ can process it in parallel quickly. + +The second query uses the static and methods, which begin returning results immediately. This approach can be faster when you're iterating over large directory trees, but the processing time compared to the first example depends on many factors. + > [!NOTE] -> These examples are intended to demonstrate usage and might not run faster than the equivalent sequential LINQ to Objects query. For more information about speedup, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). - +> These examples are intended to demonstrate usage and might not run faster than the equivalent sequential LINQ to Objects query. For more information about speedup, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). + ## GetFiles example - This example shows how to iterate over file directories in simple scenarios when you have access to all directories in the tree, the file sizes aren't large, and the access times are not significant. This approach involves a period of latency at the beginning while the array of file names is being constructed. - - [!code-csharp[PLINQ#33](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqfileiteration.cs#33)] - + This example shows how to iterate over file directories in simple scenarios when you have access to all directories in the tree, the file sizes aren't large, and the access times are not significant. This approach involves a period of latency at the beginning while the array of file names is being constructed. + + [!code-csharp[PLINQ#33](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqfileiteration.cs#33)] + ## EnumerateFiles example - This example shows how to iterate over file directories in simple scenarios when you have access to all directories in the tree, the file sizes aren't large, and the access times are not significant. This approach begins producing results faster than the previous example. - - [!code-csharp[PLINQ#34](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqfileiteration.cs#34)] - - When using , be sure that you have sufficient permissions on all directories in the tree. Otherwise, an exception will be thrown and no results will be returned. When using the in a PLINQ query, it is problematic to handle I/O exceptions in a graceful way that enables you to continue iterating. If your code must handle I/O or unauthorized access exceptions, then you should consider the approach described in [How to: Iterate File Directories with the Parallel Class](how-to-iterate-file-directories-with-the-parallel-class.md). - - If I/O latency is an issue, for example with file I/O over a network, consider using one of the asynchronous I/O techniques described in [TPL and Traditional .NET Asynchronous Programming](tpl-and-traditional-async-programming.md) and in this [blog post](https://devblogs.microsoft.com/pfxteam/parallel-extensions-and-io/). - + This example shows how to iterate over file directories in simple scenarios when you have access to all directories in the tree, the file sizes aren't large, and the access times are not significant. This approach begins producing results faster than the previous example. + + [!code-csharp[PLINQ#34](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqfileiteration.cs#34)] + + When using , be sure that you have sufficient permissions on all directories in the tree. Otherwise, an exception will be thrown and no results will be returned. When using the in a PLINQ query, it is problematic to handle I/O exceptions in a graceful way that enables you to continue iterating. If your code must handle I/O or unauthorized access exceptions, then you should consider the approach described in [How to: Iterate File Directories with the Parallel Class](how-to-iterate-file-directories-with-the-parallel-class.md). + + If I/O latency is an issue, for example with file I/O over a network, consider using one of the asynchronous I/O techniques described in [TPL and Traditional .NET Asynchronous Programming](tpl-and-traditional-async-programming.md) and in this [blog post](https://devblogs.microsoft.com/pfxteam/parallel-extensions-and-io/). + ## See also - [Parallel LINQ (PLINQ)](introduction-to-plinq.md) diff --git a/docs/standard/parallel-programming/how-to-iterate-file-directories-with-the-parallel-class.md b/docs/standard/parallel-programming/how-to-iterate-file-directories-with-the-parallel-class.md index 70f1782b57f01..d6c49904e46f4 100644 --- a/docs/standard/parallel-programming/how-to-iterate-file-directories-with-the-parallel-class.md +++ b/docs/standard/parallel-programming/how-to-iterate-file-directories-with-the-parallel-class.md @@ -2,30 +2,30 @@ description: "Learn more about: How to: Iterate File Directories with the Parallel Class" title: "How to: Iterate File Directories with the Parallel Class" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "parallel loops, how to iterate directories" ms.assetid: 555e9f48-f53d-4774-9bcf-3e965c732ec5 --- # How to: Iterate File Directories with the Parallel Class -In many cases, file iteration is an operation that can be easily parallelized. The topic [How to: Iterate File Directories with PLINQ](how-to-iterate-file-directories-with-plinq.md) shows the easiest way to perform this task for many scenarios. However, complications can arise when your code has to deal with the many types of exceptions that can arise when accessing the file system. The following example shows one approach to the problem. It uses a stack-based iteration to traverse all files and folders under a specified directory, and it enables your code to catch and handle various exceptions. Of course, the way that you handle the exceptions is up to you. - -## Example +In many cases, file iteration is an operation that can be easily parallelized. The topic [How to: Iterate File Directories with PLINQ](how-to-iterate-file-directories-with-plinq.md) shows the easiest way to perform this task for many scenarios. However, complications can arise when your code has to deal with the many types of exceptions that can arise when accessing the file system. The following example shows one approach to the problem. It uses a stack-based iteration to traverse all files and folders under a specified directory, and it enables your code to catch and handle various exceptions. Of course, the way that you handle the exceptions is up to you. + +## Example + + The following example iterates the directories sequentially, but processes the files in parallel. This is probably the best approach when you have a large file-to-directory ratio. It is also possible to parallelize the directory iteration, and access each file sequentially. It is probably not efficient to parallelize both loops unless you are specifically targeting a machine with a large number of processors. However, as in all cases, you should test your application thoroughly to determine the best approach. - The following example iterates the directories sequentially, but processes the files in parallel. This is probably the best approach when you have a large file-to-directory ratio. It is also possible to parallelize the directory iteration, and access each file sequentially. It is probably not efficient to parallelize both loops unless you are specifically targeting a machine with a large number of processors. However, as in all cases, you should test your application thoroughly to determine the best approach. - [!code-csharp[TPL_Parallel#08](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_parallel/cs/parallel_file.cs#08)] - [!code-vb[TPL_Parallel#08](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_parallel/vb/fileiteration08.vb#08)] - - In this example, the file I/O is performed synchronously. When dealing with large files or slow network connections, it might be preferable to access the files asynchronously. You can combine asynchronous I/O techniques with parallel iteration. For more information, see [TPL and Traditional .NET Asynchronous Programming](tpl-and-traditional-async-programming.md). - - The example uses the local `fileCount` variable to maintain a count of the total number of files processed. Because the variable might be accessed concurrently by multiple tasks, access to it is synchronized by calling the method. - - Note that if an exception is thrown on the main thread, the threads that are started by the method might continue to run. To stop these threads, you can set a Boolean variable in your exception handlers, and check its value on each iteration of the parallel loop. If the value indicates that an exception has been thrown, use the variable to stop or break from the loop. For more information, see [How to: Stop or Break from a Parallel.For Loop](/previous-versions/dotnet/netframework-4.0/dd460721(v=vs.100)). - + [!code-vb[TPL_Parallel#08](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_parallel/vb/fileiteration08.vb#08)] + + In this example, the file I/O is performed synchronously. When dealing with large files or slow network connections, it might be preferable to access the files asynchronously. You can combine asynchronous I/O techniques with parallel iteration. For more information, see [TPL and Traditional .NET Asynchronous Programming](tpl-and-traditional-async-programming.md). + + The example uses the local `fileCount` variable to maintain a count of the total number of files processed. Because the variable might be accessed concurrently by multiple tasks, access to it is synchronized by calling the method. + + Note that if an exception is thrown on the main thread, the threads that are started by the method might continue to run. To stop these threads, you can set a Boolean variable in your exception handlers, and check its value on each iteration of the parallel loop. If the value indicates that an exception has been thrown, use the variable to stop or break from the loop. For more information, see [How to: Stop or Break from a Parallel.For Loop](/previous-versions/dotnet/netframework-4.0/dd460721(v=vs.100)). + ## See also - [Data Parallelism](data-parallelism-task-parallel-library.md) diff --git a/docs/standard/parallel-programming/how-to-perform-action-when-a-dataflow-block-receives-data.md b/docs/standard/parallel-programming/how-to-perform-action-when-a-dataflow-block-receives-data.md index 9cb9b9682e007..3e6be40f042c9 100644 --- a/docs/standard/parallel-programming/how-to-perform-action-when-a-dataflow-block-receives-data.md +++ b/docs/standard/parallel-programming/how-to-perform-action-when-a-dataflow-block-receives-data.md @@ -2,43 +2,43 @@ description: "Learn more about: How to: Perform Action When a Dataflow Block Receives Data" title: "How to: Perform Action When a Dataflow Block Receives Data" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "Task Parallel Library, dataflows" - "TPL dataflow library, receiving data" ms.assetid: fc2585dc-965e-4632-ace7-73dd02684ed3 --- # How to: Perform Action When a Dataflow Block Receives Data -*Execution dataflow block* types call a user-provided delegate when they receive data. The , , and classes are execution dataflow block types. You can use the `delegate` keyword (`Sub` in Visual Basic), , , or a lambda expression when you provide a work function to an execution dataflow block. This document describes how to use and lambda expressions to perform action in execution blocks. +*Execution dataflow block* types call a user-provided delegate when they receive data. The , , and classes are execution dataflow block types. You can use the `delegate` keyword (`Sub` in Visual Basic), , , or a lambda expression when you provide a work function to an execution dataflow block. This document describes how to use and lambda expressions to perform action in execution blocks. [!INCLUDE [tpl-install-instructions](../../../includes/tpl-install-instructions.md)] -## Example +## Example + + The following example uses dataflow to read a file from disk and computes the number of bytes in that file that are equal to zero. It uses to read the file and compute the number of zero bytes, and to print the number of zero bytes to the console. The object specifies a object to perform work when the blocks receive data. The object uses a lambda expression to print to the console the number of zero bytes that are read. - The following example uses dataflow to read a file from disk and computes the number of bytes in that file that are equal to zero. It uses to read the file and compute the number of zero bytes, and to print the number of zero bytes to the console. The object specifies a object to perform work when the blocks receive data. The object uses a lambda expression to print to the console the number of zero bytes that are read. - [!code-csharp[TPLDataflow_ExecutionBlocks#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_executionblocks/cs/dataflowexecutionblocks.cs#1)] - [!code-vb[TPLDataflow_ExecutionBlocks#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_executionblocks/vb/dataflowexecutionblocks.vb#1)] - - Although you can provide a lambda expression to a object, this example uses to enable other code to use the `CountBytes` method. The object uses a lambda expression because the work to be performed is specific to this task and is not likely to be useful from other code. For more information about how lambda expressions work in the Task Parallel Library, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). - - The section Summary of Delegate Types in the [Dataflow](dataflow-task-parallel-library.md) document summarizes the delegate types that you can provide to , , and objects. The table also specifies whether the delegate type operates synchronously or asynchronously. - -## Robust Programming - - This example provides a delegate of type to the object to perform the task of the dataflow block synchronously. To enable the dataflow block to behave asynchronously, provide a delegate of type `Func>` to the dataflow block. When a dataflow block behaves asynchronously, the task of the dataflow block is complete only when the returned object finishes. The following example modifies the `CountBytes` method and uses the [async](../../csharp/language-reference/keywords/async.md) and [await](../../csharp/language-reference/operators/await.md) operators ([Async](../../visual-basic/language-reference/modifiers/async.md) and [Await](../../visual-basic/language-reference/operators/await-operator.md) in Visual Basic) to asynchronously compute the total number of bytes that are zero in the provided file. The method performs file read operations asynchronously. - + [!code-vb[TPLDataflow_ExecutionBlocks#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_executionblocks/vb/dataflowexecutionblocks.vb#1)] + + Although you can provide a lambda expression to a object, this example uses to enable other code to use the `CountBytes` method. The object uses a lambda expression because the work to be performed is specific to this task and is not likely to be useful from other code. For more information about how lambda expressions work in the Task Parallel Library, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). + + The section Summary of Delegate Types in the [Dataflow](dataflow-task-parallel-library.md) document summarizes the delegate types that you can provide to , , and objects. The table also specifies whether the delegate type operates synchronously or asynchronously. + +## Robust Programming + + This example provides a delegate of type to the object to perform the task of the dataflow block synchronously. To enable the dataflow block to behave asynchronously, provide a delegate of type `Func>` to the dataflow block. When a dataflow block behaves asynchronously, the task of the dataflow block is complete only when the returned object finishes. The following example modifies the `CountBytes` method and uses the [async](../../csharp/language-reference/keywords/async.md) and [await](../../csharp/language-reference/operators/await.md) operators ([Async](../../visual-basic/language-reference/modifiers/async.md) and [Await](../../visual-basic/language-reference/operators/await-operator.md) in Visual Basic) to asynchronously compute the total number of bytes that are zero in the provided file. The method performs file read operations asynchronously. + [!code-csharp[TPLDataflow_ExecutionBlocks#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_executionblocks/cs/dataflowexecutionblocks.cs#2)] - [!code-vb[TPLDataflow_ExecutionBlocks#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_executionblocks/vb/dataflowexecutionblocks.vb#2)] - - You can also use asynchronous lambda expressions to perform action in an execution dataflow block. The following example modifies the object that is used in the previous example so that it uses a lambda expression to perform the work asynchronously. - + [!code-vb[TPLDataflow_ExecutionBlocks#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_executionblocks/vb/dataflowexecutionblocks.vb#2)] + + You can also use asynchronous lambda expressions to perform action in an execution dataflow block. The following example modifies the object that is used in the previous example so that it uses a lambda expression to perform the work asynchronously. + [!code-csharp[TPLDataflow_ExecutionBlocks#3](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_executionblocks/cs/dataflowexecutionblocks.cs#3)] - [!code-vb[TPLDataflow_ExecutionBlocks#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_executionblocks/vb/dataflowexecutionblocks.vb#3)] - + [!code-vb[TPLDataflow_ExecutionBlocks#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_executionblocks/vb/dataflowexecutionblocks.vb#3)] + ## See also - [Dataflow](dataflow-task-parallel-library.md) diff --git a/docs/standard/parallel-programming/how-to-prevent-a-child-task-from-attaching-to-its-parent.md b/docs/standard/parallel-programming/how-to-prevent-a-child-task-from-attaching-to-its-parent.md index 75480abd46ab3..ca94f8ddc3c66 100644 --- a/docs/standard/parallel-programming/how-to-prevent-a-child-task-from-attaching-to-its-parent.md +++ b/docs/standard/parallel-programming/how-to-prevent-a-child-task-from-attaching-to-its-parent.md @@ -2,26 +2,26 @@ description: "Learn more about: How to: Prevent a Child Task from Attaching to its Parent" title: "How to: Prevent a Child Task from Attaching to its Parent" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "tasks, preventing attachments" ms.assetid: c0fb85d4-9e80-4905-9f65-29acc54201c4 --- # How to: Prevent a Child Task from Attaching to its Parent -This document demonstrates how to prevent a child task from attaching to the parent task. Preventing a child task from attaching to its parent is useful when you call a component that is written by a third party and that also uses tasks. For example, a third-party component that uses the option to create a or object can cause problems in your code if it is long-running or throws an unhandled exception. - -## Example +This document demonstrates how to prevent a child task from attaching to the parent task. Preventing a child task from attaching to its parent is useful when you call a component that is written by a third party and that also uses tasks. For example, a third-party component that uses the option to create a or object can cause problems in your code if it is long-running or throws an unhandled exception. + +## Example + + The following example compares the effects of using the default options to the effects of preventing a child task from attaching to the parent. The example creates a object that calls into a third-party library that also uses a object. The third-party library uses the option to create the object. The application uses the option to create the parent task. This option instructs the runtime to remove the specification in child tasks. - The following example compares the effects of using the default options to the effects of preventing a child task from attaching to the parent. The example creates a object that calls into a third-party library that also uses a object. The third-party library uses the option to create the object. The application uses the option to create the parent task. This option instructs the runtime to remove the specification in child tasks. - [!code-csharp[TPL_DenyChildAttach#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_denychildattach/cs/denychildattach.cs#1)] - [!code-vb[TPL_DenyChildAttach#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_denychildattach/vb/denychildattach.vb#1)] - - Because a parent task does not finish until all child tasks finish, a long-running child task can cause the overall application to perform poorly. In this example, when the application uses the default options to create the parent task, the child task must finish before the parent task finishes. When the application uses the option, the child is not attached to the parent. Therefore, the application can perform additional work after the parent task finishes and before it must wait for the child task to finish. - + [!code-vb[TPL_DenyChildAttach#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_denychildattach/vb/denychildattach.vb#1)] + + Because a parent task does not finish until all child tasks finish, a long-running child task can cause the overall application to perform poorly. In this example, when the application uses the default options to create the parent task, the child task must finish before the parent task finishes. When the application uses the option, the child is not attached to the parent. Therefore, the application can perform additional work after the parent task finishes and before it must wait for the child task to finish. + ## See also - [Task-based Asynchronous Programming](task-based-asynchronous-programming.md) diff --git a/docs/standard/parallel-programming/how-to-return-a-value-from-a-task.md b/docs/standard/parallel-programming/how-to-return-a-value-from-a-task.md index c2512536598d8..72d7dd03ded61 100644 --- a/docs/standard/parallel-programming/how-to-return-a-value-from-a-task.md +++ b/docs/standard/parallel-programming/how-to-return-a-value-from-a-task.md @@ -3,26 +3,26 @@ title: "How to: Return a Value from a Task" description: See how to use the System.Threading.Tasks.Task type to return a value from the Result property in .NET. ms.date: "08/10/2022" ms.custom: devdivchpfy22 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "tasks, how to return a value" ms.assetid: c4bc0f44-eba2-4e96-9e03-1cc787461e61 --- # How to: Return a Value from a Task -This example shows how to use the class to return a value from the property. To use this example, you must ensure that the *C:\Users\Public\Pictures\Sample Pictures* directory exists and that it contains files. - -## Example +This example shows how to use the class to return a value from the property. To use this example, you must ensure that the *C:\Users\Public\Pictures\Sample Pictures* directory exists and that it contains files. + +## Example [!code-csharp[TPL#10](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl/cs/returnavalue10.cs#10)] - [!code-vb[TPL#10](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl/vb/10_returnavalue.vb#10)] - - The property blocks the calling thread until the task finishes. - -To see how to pass the result of a class to a continuation task, see [Chaining Tasks by Using Continuation Tasks](chaining-tasks-by-using-continuation-tasks.md). - + [!code-vb[TPL#10](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl/vb/10_returnavalue.vb#10)] + + The property blocks the calling thread until the task finishes. + +To see how to pass the result of a class to a continuation task, see [Chaining Tasks by Using Continuation Tasks](chaining-tasks-by-using-continuation-tasks.md). + ## See also - [Task-based Asynchronous Programming](task-based-asynchronous-programming.md) diff --git a/docs/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block.md b/docs/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block.md index f5fe8113be76a..fc7e8389fe287 100644 --- a/docs/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block.md +++ b/docs/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block.md @@ -13,7 +13,7 @@ ms.assetid: 27ece374-ed5b-49ef-9cec-b20db34a65e8 --- # How to: Specify a Task Scheduler in a Dataflow Block -This document demonstrates how to associate a specific task scheduler when you use dataflow in your application. The example uses the class in a Windows Forms application to show when reader tasks are active and when a writer task is active. It also uses the method to enable a dataflow block to run on the user-interface thread. +This document demonstrates how to associate a specific task scheduler when you use dataflow in your application. The example uses the class in a Windows Forms application to show when reader tasks are active and when a writer task is active. It also uses the method to enable a dataflow block to run on the user-interface thread. [!INCLUDE [tpl-install-instructions](../../../includes/tpl-install-instructions.md)] @@ -21,9 +21,9 @@ This document demonstrates how to associate a specific task scheduler when you u 1. Create a Visual C# or Visual Basic **Windows Forms Application** project. In the following steps, the project is named `WriterReadersWinForms`. -2. On the form designer for the main form, Form1.cs (Form1.vb for Visual Basic), add four controls. Set the property to **Reader 1** for `checkBox1`, **Reader 2** for `checkBox2`, **Reader 3** for `checkBox3`, and **Writer** for `checkBox4`. Set the property for each control to `False`. +2. On the form designer for the main form, Form1.cs (Form1.vb for Visual Basic), add four controls. Set the property to **Reader 1** for `checkBox1`, **Reader 2** for `checkBox2`, **Reader 3** for `checkBox3`, and **Writer** for `checkBox4`. Set the property for each control to `False`. -3. Add a control to the form. Set the property to `2500`. +3. Add a control to the form. Set the property to `2500`. ## Adding Dataflow Functionality @@ -38,17 +38,17 @@ This document demonstrates how to associate a specific task scheduler when you u [!code-csharp[TPLDataflow_WriterReadersWinForms#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/cs/writerreaderswinforms/form1.cs#1)] [!code-vb[TPLDataflow_WriterReadersWinForms#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb#1)] -3. Add a data member to the `Form1` class. +3. Add a data member to the `Form1` class. [!code-csharp[TPLDataflow_WriterReadersWinForms#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/cs/writerreaderswinforms/form1.cs#2)] [!code-vb[TPLDataflow_WriterReadersWinForms#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb#2)] -4. In the `Form1` constructor, after the call to `InitializeComponent`, create an object that toggles the state of objects. +4. In the `Form1` constructor, after the call to `InitializeComponent`, create an object that toggles the state of objects. [!code-csharp[TPLDataflow_WriterReadersWinForms#3](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/cs/writerreaderswinforms/form1.cs#3)] [!code-vb[TPLDataflow_WriterReadersWinForms#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb#3)] -5. In the `Form1` constructor, create a object and four objects, one object for each object. For each object, specify an object that has the property set to the property for the readers, and the property for the writer. +5. In the `Form1` constructor, create a object and four objects, one object for each object. For each object, specify an object that has the property set to the property for the readers, and the property for the writer. [!code-csharp[TPLDataflow_WriterReadersWinForms#4](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/cs/writerreaderswinforms/form1.cs#4)] [!code-vb[TPLDataflow_WriterReadersWinForms#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb#4)] @@ -65,7 +65,7 @@ This document demonstrates how to associate a specific task scheduler when you u [!code-csharp[TPLDataflow_WriterReadersWinForms#6](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/cs/writerreaderswinforms/form1.cs#6)] [!code-vb[TPLDataflow_WriterReadersWinForms#6](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb#6)] - Because the `toggleCheckBox` dataflow block acts on the user interface, it is important that this action occur on the user-interface thread. To accomplish this, during construction this object provides an object that has the property set to . The method creates a object that performs work on the current synchronization context. Because the `Form1` constructor is called from the user-interface thread, the action for the `toggleCheckBox` dataflow block also runs on the user-interface thread. + Because the `toggleCheckBox` dataflow block acts on the user interface, it is important that this action occur on the user-interface thread. To accomplish this, during construction this object provides an object that has the property set to . The method creates a object that performs work on the current synchronization context. Because the `Form1` constructor is called from the user-interface thread, the action for the `toggleCheckBox` dataflow block also runs on the user-interface thread. This example also uses the class to enable some dataflow blocks to act concurrently, and another dataflow block to act exclusive with respect to all other dataflow blocks that run on the same object. This technique is useful when multiple dataflow blocks share a resource and some require exclusive access to that resource, because it eliminates the requirement to manually synchronize access to that resource. The elimination of manual synchronization can make code more efficient. diff --git a/docs/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md b/docs/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md index 53401c55f9039..846c3387bbc63 100644 --- a/docs/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md +++ b/docs/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Specify the Degree of Parallelism in a Dataflow Block" title: "How to: Specify the Degree of Parallelism in a Dataflow Block" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "dataflow block, specifying parallelism in TPL" - "Task Parallel Library, dataflows" - "TPL dataflow library, specifying parallelism" @@ -13,23 +13,23 @@ ms.assetid: e4088541-ee05-40db-95f5-147cfe62fde7 --- # How to: Specify the Degree of Parallelism in a Dataflow Block -This document describes how to set the property to enable an execution dataflow block to process more than one message at a time. Doing this is useful when you have a dataflow block that performs a long-running computation and can benefit from processing messages in parallel. This example uses the class to perform multiple dataflow operations concurrently; however, you can specify the maximum degree of parallelism in any of the predefined execution block types that the TPL Dataflow Library provides, , , and . +This document describes how to set the property to enable an execution dataflow block to process more than one message at a time. Doing this is useful when you have a dataflow block that performs a long-running computation and can benefit from processing messages in parallel. This example uses the class to perform multiple dataflow operations concurrently; however, you can specify the maximum degree of parallelism in any of the predefined execution block types that the TPL Dataflow Library provides, , , and . [!INCLUDE [tpl-install-instructions](../../../includes/tpl-install-instructions.md)] -## Example +## Example + + The following example performs two dataflow computations and prints the elapsed time that is required for each computation. The first computation specifies a maximum degree of parallelism of 1, which is the default. A maximum degree of parallelism of 1 causes the dataflow block to process messages serially. The second computation resembles the first, except that it specifies a maximum degree of parallelism that is equal to the number of available processors. This enables the dataflow block to perform multiple operations in parallel. - The following example performs two dataflow computations and prints the elapsed time that is required for each computation. The first computation specifies a maximum degree of parallelism of 1, which is the default. A maximum degree of parallelism of 1 causes the dataflow block to process messages serially. The second computation resembles the first, except that it specifies a maximum degree of parallelism that is equal to the number of available processors. This enables the dataflow block to perform multiple operations in parallel. - [!code-csharp[TPLDataflow_DegreeOfParallelism#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_degreeofparallelism/cs/dataflowdegreeofparallelism.cs#1)] - [!code-vb[TPLDataflow_DegreeOfParallelism#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb#1)] - -## Robust Programming - - By default, each predefined dataflow block propagates out messages in the order in which the messages are received. Although multiple messages are processed simultaneously when you specify a maximum degree of parallelism that is greater than 1, they are still propagated out in the order in which they are received. - - Because the property represents the maximum degree of parallelism, the dataflow block might execute with a lesser degree of parallelism than you specify. The dataflow block can use a lesser degree of parallelism to meet its functional requirements or to account for a lack of available system resources. A dataflow block never chooses a greater degree of parallelism than you specify. - + [!code-vb[TPLDataflow_DegreeOfParallelism#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb#1)] + +## Robust Programming + + By default, each predefined dataflow block propagates out messages in the order in which the messages are received. Although multiple messages are processed simultaneously when you specify a maximum degree of parallelism that is greater than 1, they are still propagated out in the order in which they are received. + + Because the property represents the maximum degree of parallelism, the dataflow block might execute with a lesser degree of parallelism than you specify. The dataflow block can use a lesser degree of parallelism to meet its functional requirements or to account for a lack of available system resources. A dataflow block never chooses a greater degree of parallelism than you specify. + ## See also - [Dataflow](dataflow-task-parallel-library.md) diff --git a/docs/standard/parallel-programming/how-to-specify-the-execution-mode-in-plinq.md b/docs/standard/parallel-programming/how-to-specify-the-execution-mode-in-plinq.md index 4a9d87d3f2c1e..6efdd97b0113c 100644 --- a/docs/standard/parallel-programming/how-to-specify-the-execution-mode-in-plinq.md +++ b/docs/standard/parallel-programming/how-to-specify-the-execution-mode-in-plinq.md @@ -2,32 +2,32 @@ description: "Learn more about: How to: Specify the Execution Mode in PLINQ" title: "How to: Specify the Execution Mode in PLINQ" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "PLINQ queries, how to use execution mode" ms.assetid: e52ff26c-c5d3-4fab-9fec-c937fb387963 --- # How to: Specify the Execution Mode in PLINQ -This example shows how to force PLINQ to bypass its default heuristics and parallelize a query regardless of the query's shape. - +This example shows how to force PLINQ to bypass its default heuristics and parallelize a query regardless of the query's shape. + > [!NOTE] -> This example is intended to demonstrate usage and might not run faster than the equivalent sequential LINQ to Objects query. For more information about speedup, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). - -## Example +> This example is intended to demonstrate usage and might not run faster than the equivalent sequential LINQ to Objects query. For more information about speedup, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). + +## Example [!code-csharp[PLINQ#22](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqsamples.cs#22)] - [!code-vb[PLINQ#22](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinqsnippets1.vb#22)] - - PLINQ is designed to exploit opportunities for parallelization. However, not all queries benefit from parallel execution. For example, when a query contains a single user delegate that does little work, the query will usually run faster sequentially. Sequential execution is faster because the overhead involved in enabling parallelizing execution is more expensive than the speedup that's obtained. Therefore, PLINQ does not automatically parallelize every query. It first examines the shape of the query and the various operators that comprise it. Based on this analysis, PLINQ in the default execution mode may decide to execute some or all of the query sequentially. However, in some cases you may know more about your query than PLINQ is able to determine from its analysis. For example, you may know that a delegate is expensive and that the query will definitely benefit from parallelization. In such cases, you can use the method and specify the value to instruct PLINQ to always run the query as parallel. - -## Compiling the Code - - Cut and paste this code into the [PLINQ Data Sample](plinq-data-sample.md) and call the method from `Main`. - + [!code-vb[PLINQ#22](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinqsnippets1.vb#22)] + + PLINQ is designed to exploit opportunities for parallelization. However, not all queries benefit from parallel execution. For example, when a query contains a single user delegate that does little work, the query will usually run faster sequentially. Sequential execution is faster because the overhead involved in enabling parallelizing execution is more expensive than the speedup that's obtained. Therefore, PLINQ does not automatically parallelize every query. It first examines the shape of the query and the various operators that comprise it. Based on this analysis, PLINQ in the default execution mode may decide to execute some or all of the query sequentially. However, in some cases you may know more about your query than PLINQ is able to determine from its analysis. For example, you may know that a delegate is expensive and that the query will definitely benefit from parallelization. In such cases, you can use the method and specify the value to instruct PLINQ to always run the query as parallel. + +## Compiling the Code + + Cut and paste this code into the [PLINQ Data Sample](plinq-data-sample.md) and call the method from `Main`. + ## See also -- +- - [Parallel LINQ (PLINQ)](introduction-to-plinq.md) diff --git a/docs/standard/parallel-programming/how-to-speed-up-small-loop-bodies.md b/docs/standard/parallel-programming/how-to-speed-up-small-loop-bodies.md index 95cba275f52a8..dc3b276dbee4e 100644 --- a/docs/standard/parallel-programming/how-to-speed-up-small-loop-bodies.md +++ b/docs/standard/parallel-programming/how-to-speed-up-small-loop-bodies.md @@ -2,24 +2,24 @@ description: "Learn more about: How to: Speed Up Small Loop Bodies" title: "How to: Speed Up Small Loop Bodies" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "parallel loops, how to speed up" ms.assetid: c7a66677-cb59-4cbf-969a-d2e8fc61a6ce --- # How to: Speed Up Small Loop Bodies -When a loop has a small body, it might perform more slowly than the equivalent sequential loop, such as the [for](../../csharp/language-reference/statements/iteration-statements.md#the-for-statement) loop in C# and the [For](/previous-versions/visualstudio/visual-studio-2008/44kykk21(v=vs.90)) loop in Visual Basic. Slower performance is caused by the overhead involved in partitioning the data and the cost of invoking a delegate on each loop iteration. To address such scenarios, the class provides the method, which enables you to provide a sequential loop for the delegate body, so that the delegate is invoked only once per partition, instead of once per iteration. For more information, see [Custom Partitioners for PLINQ and TPL](custom-partitioners-for-plinq-and-tpl.md). - -## Example +When a loop has a small body, it might perform more slowly than the equivalent sequential loop, such as the [for](../../csharp/language-reference/statements/iteration-statements.md#the-for-statement) loop in C# and the [For](/previous-versions/visualstudio/visual-studio-2008/44kykk21(v=vs.90)) loop in Visual Basic. Slower performance is caused by the overhead involved in partitioning the data and the cost of invoking a delegate on each loop iteration. To address such scenarios, the class provides the method, which enables you to provide a sequential loop for the delegate body, so that the delegate is invoked only once per partition, instead of once per iteration. For more information, see [Custom Partitioners for PLINQ and TPL](custom-partitioners-for-plinq-and-tpl.md). + +## Example [!code-csharp[TPL_Partitioners#01](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_partitioners/cs/partitioner01.cs#01)] - [!code-vb[TPL_Partitioners#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_partitioners/vb/partitionercreate01.vb#01)] - - The approach demonstrated in this example is useful when the loop performs a minimal amount of work. As the work becomes more computationally expensive, you will probably get the same or better performance by using a or loop with the default partitioner. - + [!code-vb[TPL_Partitioners#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_partitioners/vb/partitionercreate01.vb#01)] + + The approach demonstrated in this example is useful when the loop performs a minimal amount of work. As the work becomes more computationally expensive, you will probably get the same or better performance by using a or loop with the default partitioner. + ## See also - [Data Parallelism](data-parallelism-task-parallel-library.md) diff --git a/docs/standard/parallel-programming/how-to-traverse-a-binary-tree-with-parallel-tasks.md b/docs/standard/parallel-programming/how-to-traverse-a-binary-tree-with-parallel-tasks.md index 940ec5ed76635..27b127faaf0ad 100644 --- a/docs/standard/parallel-programming/how-to-traverse-a-binary-tree-with-parallel-tasks.md +++ b/docs/standard/parallel-programming/how-to-traverse-a-binary-tree-with-parallel-tasks.md @@ -2,24 +2,24 @@ description: "Learn more about: How to: Traverse a Binary Tree with Parallel Tasks" title: "How to: Traverse a Binary Tree with Parallel Tasks" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "tasks, how to traverse a tree" ms.assetid: 4265d169-6c69-4f36-b10d-b7ae7f72f4df --- # How to: Traverse a Binary Tree with Parallel Tasks -The following example shows two ways in which parallel tasks can be used to traverse a tree data structure. The creation of the tree itself is left as an exercise. - -## Example +The following example shows two ways in which parallel tasks can be used to traverse a tree data structure. The creation of the tree itself is left as an exercise. + +## Example [!code-csharp[TPL#16](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl/cs/tpl.cs#16)] - [!code-vb[TPL#16](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl/vb/treewalk.vb#16)] - - The two methods shown are functionally equivalent. By using the method to create and run the tasks, you get a handle back from the tasks which can be used to wait on the tasks and handle exceptions. - + [!code-vb[TPL#16](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl/vb/treewalk.vb#16)] + + The two methods shown are functionally equivalent. By using the method to create and run the tasks, you get a handle back from the tasks which can be used to wait on the tasks and handle exceptions. + ## See also - [Task Parallel Library (TPL)](task-parallel-library-tpl.md) diff --git a/docs/standard/parallel-programming/how-to-unlink-dataflow-blocks.md b/docs/standard/parallel-programming/how-to-unlink-dataflow-blocks.md index 3c6fba0e7a793..1239f1a283676 100644 --- a/docs/standard/parallel-programming/how-to-unlink-dataflow-blocks.md +++ b/docs/standard/parallel-programming/how-to-unlink-dataflow-blocks.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Unlink Dataflow Blocks" title: "How to: Unlink Dataflow Blocks" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "dataflow blocks, unlinking in TPL" - "Task Parallel Library, dataflows" - "TPL dataflow library, unlinking dataflow blocks" @@ -17,17 +17,17 @@ This document describes how to unlink a target dataflow block from its source. [!INCLUDE [tpl-install-instructions](../../../includes/tpl-install-instructions.md)] -## Example +## Example + + The following example creates three objects, each of which calls the `TrySolution` method to compute a value. This example requires only the result from the first call to `TrySolution` to finish. - The following example creates three objects, each of which calls the `TrySolution` method to compute a value. This example requires only the result from the first call to `TrySolution` to finish. - [!code-csharp[TPLDataflow_ReceiveAny#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_receiveany/cs/dataflowreceiveany.cs#1)] - [!code-vb[TPLDataflow_ReceiveAny#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_receiveany/vb/dataflowreceiveany.vb#1)] - - To receive the value from the first object that finishes, this example defines the `ReceiveFromAny(T)` method. The `ReceiveFromAny(T)` method accepts an array of objects and links each of these objects to a object. When you use the method to link a source dataflow block to a target block, the source propagates messages to the target as data becomes available. Because the class accepts only the first message that it is offered, the `ReceiveFromAny(T)` method produces its result by calling the method. This produces the first message that is offered to the object. The method has an overloaded version that takes an object with a property that, when it is set to `1`, instructs the source block to unlink from the target after the target receives one message from the source. It is important for the object to unlink from its sources because the relationship between the array of sources and the object is no longer required after the object receives a message. - - To enable the remaining calls to `TrySolution` to end after one of them computes a value, the `TrySolution` method takes a object that is canceled after the call to `ReceiveFromAny(T)` returns. The method returns when this object is canceled. - + [!code-vb[TPLDataflow_ReceiveAny#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_receiveany/vb/dataflowreceiveany.vb#1)] + + To receive the value from the first object that finishes, this example defines the `ReceiveFromAny(T)` method. The `ReceiveFromAny(T)` method accepts an array of objects and links each of these objects to a object. When you use the method to link a source dataflow block to a target block, the source propagates messages to the target as data becomes available. Because the class accepts only the first message that it is offered, the `ReceiveFromAny(T)` method produces its result by calling the method. This produces the first message that is offered to the object. The method has an overloaded version that takes an object with a property that, when it is set to `1`, instructs the source block to unlink from the target after the target receives one message from the source. It is important for the object to unlink from its sources because the relationship between the array of sources and the object is no longer required after the object receives a message. + + To enable the remaining calls to `TrySolution` to end after one of them computes a value, the `TrySolution` method takes a object that is canceled after the call to `ReceiveFromAny(T)` returns. The method returns when this object is canceled. + ## See also - [Dataflow](dataflow-task-parallel-library.md) diff --git a/docs/standard/parallel-programming/how-to-unwrap-a-nested-task.md b/docs/standard/parallel-programming/how-to-unwrap-a-nested-task.md index 56e6c9d136218..af73048226443 100644 --- a/docs/standard/parallel-programming/how-to-unwrap-a-nested-task.md +++ b/docs/standard/parallel-programming/how-to-unwrap-a-nested-task.md @@ -2,41 +2,41 @@ description: "Learn more about: How to: Unwrap a Nested Task" title: "How to: Unwrap a Nested Task" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "tasks, how to unwrap nested tasks" ms.assetid: a0769dd2-0f6d-48ca-8418-a9d39de7f450 --- # How to: Unwrap a Nested Task -You can return a task from a method, and then wait on or continue from that task, as shown in the following example: - +You can return a task from a method, and then wait on or continue from that task, as shown in the following example: + [!code-csharp[TPL_Unwrap#01](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_unwrap/cs/unwrapprogram.cs#01)] - [!code-vb[TPL_Unwrap#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_unwrap/vb/snippets1-3.vb#01)] - - In the previous example, the property is of type `string` (`String` in Visual Basic). - - However, in some scenarios, you might want to create a task within another task, and then return the nested task. In this case, the `TResult` of the enclosing task is itself a task. In the following example, the Result property is a `Task>` in C# or `Task(Of Task(Of String))` in Visual Basic. - + [!code-vb[TPL_Unwrap#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_unwrap/vb/snippets1-3.vb#01)] + + In the previous example, the property is of type `string` (`String` in Visual Basic). + + However, in some scenarios, you might want to create a task within another task, and then return the nested task. In this case, the `TResult` of the enclosing task is itself a task. In the following example, the Result property is a `Task>` in C# or `Task(Of Task(Of String))` in Visual Basic. + [!code-csharp[TPL_Unwrap#02](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_unwrap/cs/unwrapprogram.cs#02)] - [!code-vb[TPL_Unwrap#02](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_unwrap/vb/snippets1-3.vb#02)] - - Although it is possible to write code to unwrap the outer task and retrieve the original task and its property, such code is not easy to write because you must handle exceptions and also cancellation requests. In this situation, we recommend that you use one of the extension methods, as shown in the following example. - + [!code-vb[TPL_Unwrap#02](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_unwrap/vb/snippets1-3.vb#02)] + + Although it is possible to write code to unwrap the outer task and retrieve the original task and its property, such code is not easy to write because you must handle exceptions and also cancellation requests. In this situation, we recommend that you use one of the extension methods, as shown in the following example. + [!code-csharp[TPL_UnWrap#03](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_unwrap/cs/unwrapprogram.cs#03)] - [!code-vb[TPL_UnWrap#03](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_unwrap/vb/snippets1-3.vb#03)] - - The methods can be used to transform any `Task` or `Task>` (`Task(Of Task)` or `Task(Of Task(Of TResult))` in Visual Basic) to a `Task` or `Task` (`Task(Of TResult)` in Visual Basic). The new task fully represents the inner nested task, and includes cancellation state and all exceptions. - -## Example - - The following example demonstrates how to use the extension methods. - + [!code-vb[TPL_UnWrap#03](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_unwrap/vb/snippets1-3.vb#03)] + + The methods can be used to transform any `Task` or `Task>` (`Task(Of Task)` or `Task(Of Task(Of TResult))` in Visual Basic) to a `Task` or `Task` (`Task(Of TResult)` in Visual Basic). The new task fully represents the inner nested task, and includes cancellation state and all exceptions. + +## Example + + The following example demonstrates how to use the extension methods. + [!code-csharp[TPL_UnWrap#04](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_unwrap/cs/unwrapprogram.cs#04)] - [!code-vb[TPL_UnWrap#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_unwrap/vb/snippet04.vb#04)] - + [!code-vb[TPL_UnWrap#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_unwrap/vb/snippet04.vb#04)] + ## See also - diff --git a/docs/standard/parallel-programming/how-to-use-joinblock-to-read-data-from-multiple-sources.md b/docs/standard/parallel-programming/how-to-use-joinblock-to-read-data-from-multiple-sources.md index 7c44a00960911..59dcea71e7f2b 100644 --- a/docs/standard/parallel-programming/how-to-use-joinblock-to-read-data-from-multiple-sources.md +++ b/docs/standard/parallel-programming/how-to-use-joinblock-to-read-data-from-multiple-sources.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Use JoinBlock to Read Data From Multiple Sources" title: "How to: Use JoinBlock to Read Data From Multiple Sources" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "Task Parallel Library, dataflows" - "TPL dataflow library, joining blocks in" - "dataflow blocks, joining in TPL" @@ -13,23 +13,23 @@ ms.assetid: e9c1ada4-ac57-4704-87cb-2f5117f8151d --- # How to: Use JoinBlock to Read Data From Multiple Sources -This document explains how to use the class to perform an operation when data is available from multiple sources. It also demonstrates how to use non-greedy mode to enable multiple join blocks to share a data source more efficiently. +This document explains how to use the class to perform an operation when data is available from multiple sources. It also demonstrates how to use non-greedy mode to enable multiple join blocks to share a data source more efficiently. [!INCLUDE [tpl-install-instructions](../../../includes/tpl-install-instructions.md)] -## Example +## Example + + The following example defines three resource types, `NetworkResource`, `FileResource`, and `MemoryResource`, and performs operations when resources become available. This example requires a `NetworkResource` and `MemoryResource` pair in order to perform the first operation and a `FileResource` and `MemoryResource` pair in order to perform the second operation. To enable these operations to occur when all required resources are available, this example uses the class. When a object receives data from all sources, it propagates that data to its target, which in this example is an object. Both objects read from a shared pool of `MemoryResource` objects. - The following example defines three resource types, `NetworkResource`, `FileResource`, and `MemoryResource`, and performs operations when resources become available. This example requires a `NetworkResource` and `MemoryResource` pair in order to perform the first operation and a `FileResource` and `MemoryResource` pair in order to perform the second operation. To enable these operations to occur when all required resources are available, this example uses the class. When a object receives data from all sources, it propagates that data to its target, which in this example is an object. Both objects read from a shared pool of `MemoryResource` objects. - [!code-csharp[TPLDataflow_NonGreedyJoin#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_nongreedyjoin/cs/nongreedyjoin.cs#1)] - [!code-vb[TPLDataflow_NonGreedyJoin#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_nongreedyjoin/vb/nongreedyjoin.vb#1)] - - To enable efficient use of the shared pool of `MemoryResource` objects, this example specifies a object that has the property set to `False` to create objects that act in non-greedy mode. A non-greedy join block postpones all incoming messages until one is available from each source. If any of the postponed messages were accepted by another block, the join block restarts the process. Non-greedy mode enables join blocks that share one or more source blocks to make forward progress as the other blocks wait for data. In this example, if a `MemoryResource` object is added to the `memoryResources` pool, the first join block to receive its second data source can make forward progress. If this example were to use greedy mode, which is the default, one join block might take the `MemoryResource` object and wait for the second resource to become available. However, if the other join block has its second data source available, it cannot make forward progress because the `MemoryResource` object has been taken by the other join block. - -## Robust Programming - - The use of non-greedy joins can also help you prevent deadlock in your application. In a software application, *deadlock* occurs when two or more processes each hold a resource and mutually wait for another process to release some other resource. Consider an application that defines two objects. Both objects each read data from two shared source blocks. In greedy mode, if one join block reads from the first source and the second join block reads from the second source, the application might deadlock because both join blocks mutually wait for the other to release its resource. In non-greedy mode, each join block reads from its sources only when all data is available, and therefore, the risk of deadlock is eliminated. - + [!code-vb[TPLDataflow_NonGreedyJoin#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_nongreedyjoin/vb/nongreedyjoin.vb#1)] + + To enable efficient use of the shared pool of `MemoryResource` objects, this example specifies a object that has the property set to `False` to create objects that act in non-greedy mode. A non-greedy join block postpones all incoming messages until one is available from each source. If any of the postponed messages were accepted by another block, the join block restarts the process. Non-greedy mode enables join blocks that share one or more source blocks to make forward progress as the other blocks wait for data. In this example, if a `MemoryResource` object is added to the `memoryResources` pool, the first join block to receive its second data source can make forward progress. If this example were to use greedy mode, which is the default, one join block might take the `MemoryResource` object and wait for the second resource to become available. However, if the other join block has its second data source available, it cannot make forward progress because the `MemoryResource` object has been taken by the other join block. + +## Robust Programming + + The use of non-greedy joins can also help you prevent deadlock in your application. In a software application, *deadlock* occurs when two or more processes each hold a resource and mutually wait for another process to release some other resource. Consider an application that defines two objects. Both objects each read data from two shared source blocks. In greedy mode, if one join block reads from the first source and the second join block reads from the second source, the application might deadlock because both join blocks mutually wait for the other to release its resource. In non-greedy mode, each join block reads from its sources only when all data is available, and therefore, the risk of deadlock is eliminated. + ## See also - [Dataflow](dataflow-task-parallel-library.md) diff --git a/docs/standard/parallel-programming/how-to-use-parallel-invoke-to-execute-parallel-operations.md b/docs/standard/parallel-programming/how-to-use-parallel-invoke-to-execute-parallel-operations.md index 2b1f9ca3e3aa6..314ba1c7b44c8 100644 --- a/docs/standard/parallel-programming/how-to-use-parallel-invoke-to-execute-parallel-operations.md +++ b/docs/standard/parallel-programming/how-to-use-parallel-invoke-to-execute-parallel-operations.md @@ -12,7 +12,7 @@ ms.assetid: 6b3ecd79-dec9-4ce1-abf4-62e5392a59c6 --- # How to: Use Parallel.Invoke to Execute Parallel Operations -This example shows how to parallelize operations by using in the Task Parallel Library. Three operations are performed on a shared data source. The operations can be executed in parallel in a straightforward manner, because none of them modifies the source. +This example shows how to parallelize operations by using in the Task Parallel Library. Three operations are performed on a shared data source. The operations can be executed in parallel in a straightforward manner, because none of them modifies the source. > [!NOTE] > This documentation uses lambda expressions to define delegates in TPL. If you aren't familiar with lambda expressions in C# or Visual Basic, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). @@ -22,7 +22,7 @@ This example shows how to parallelize operations by using , you simply express which actions you want to run concurrently, and the runtime handles all thread scheduling details, including scaling automatically to the number of cores on the host computer. +With , you simply express which actions you want to run concurrently, and the runtime handles all thread scheduling details, including scaling automatically to the number of cores on the host computer. This example parallelizes the operations, not the data. As an alternate approach, you can parallelize the LINQ queries by using PLINQ and run the queries sequentially. Alternatively, you could parallelize the data by using PLINQ. Another option is to parallelize both the queries and the tasks. Although the resulting overhead might degrade performance on host computers with relatively few processors, it scales better on computers with many processors. diff --git a/docs/standard/parallel-programming/how-to-wrap-eap-patterns-in-a-task.md b/docs/standard/parallel-programming/how-to-wrap-eap-patterns-in-a-task.md index 8067564b080b9..25105072ece10 100644 --- a/docs/standard/parallel-programming/how-to-wrap-eap-patterns-in-a-task.md +++ b/docs/standard/parallel-programming/how-to-wrap-eap-patterns-in-a-task.md @@ -2,22 +2,22 @@ description: "Learn more about: How to: Wrap EAP Patterns in a Task" title: "How to: Wrap EAP Patterns in a Task" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "tasks, how to wrap EAP patterns" ms.assetid: f11ed467-af2f-4504-8a2e-299a6c36d44e --- # How to: Wrap EAP Patterns in a Task -The following example shows how to expose an arbitrary sequence of Event-Based Asynchronous Pattern (EAP) operations as one task by using a . The example also shows how to use a to invoke the built-in cancellation methods on the objects. - -## Example +The following example shows how to expose an arbitrary sequence of Event-Based Asynchronous Pattern (EAP) operations as one task by using a . The example also shows how to use a to invoke the built-in cancellation methods on the objects. + +## Example [!code-csharp[FromAsync#08](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#08)] - [!code-vb[FromAsync#08](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#08)] - + [!code-vb[FromAsync#08](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#08)] + ## See also - [TPL and Traditional .NET Asynchronous Programming](tpl-and-traditional-async-programming.md) diff --git a/docs/standard/parallel-programming/how-to-write-a-custom-plinq-aggregate-function.md b/docs/standard/parallel-programming/how-to-write-a-custom-plinq-aggregate-function.md index 11a500335d53f..320721bcc7730 100644 --- a/docs/standard/parallel-programming/how-to-write-a-custom-plinq-aggregate-function.md +++ b/docs/standard/parallel-programming/how-to-write-a-custom-plinq-aggregate-function.md @@ -2,31 +2,31 @@ description: "Learn more about: How to: Write a Custom PLINQ Aggregate Function" title: "How to: Write a Custom PLINQ Aggregate Function" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "PLINQ queries, how to create aggregate function" ms.assetid: 5a70dd49-ab2a-4798-b551-196ee7042b1a --- # How to: Write a Custom PLINQ Aggregate Function -This example shows how to use the method to apply a custom aggregation function to a source sequence. - +This example shows how to use the method to apply a custom aggregation function to a source sequence. + > [!WARNING] -> This example is intended to demonstrate usage, and might not run faster than the equivalent sequential LINQ to Objects query. For more information about speedup, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). - -## Example +> This example is intended to demonstrate usage, and might not run faster than the equivalent sequential LINQ to Objects query. For more information about speedup, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). + +## Example + + The following example calculates the standard deviation of a sequence of integers. - The following example calculates the standard deviation of a sequence of integers. - [!code-csharp[PLINQ#31](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqsamples.cs#31)] - [!code-vb[PLINQ#31](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinqsnippets1.vb#31)] - - This example uses an overload of the Aggregate standard query operator that is unique to PLINQ. This overload takes an extra as the third input parameter. This delegate combines the results from all threads before it performs the final calculation on the aggregated results. In this example we add together the sums from all the threads. - - Note that when a lambda expression body consists of a single expression, the return value of the delegate is the value of the expression. - + [!code-vb[PLINQ#31](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinqsnippets1.vb#31)] + + This example uses an overload of the Aggregate standard query operator that is unique to PLINQ. This overload takes an extra as the third input parameter. This delegate combines the results from all threads before it performs the final calculation on the aggregated results. In this example we add together the sums from all the threads. + + Note that when a lambda expression body consists of a single expression, the return value of the delegate is the value of the expression. + ## See also - diff --git a/docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md b/docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md index a87eb911c26ea..19548966d3e80 100644 --- a/docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md +++ b/docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md @@ -2,42 +2,42 @@ title: "How to: Write a Parallel.For Loop with Thread-Local Variables" description: See an example of how to write a Parallel.For loop in .NET that uses thread-local variables, which store and retrieve state in each separate task in the loop. ms.date: 05/22/2023 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "parallel for loops, how to use local state" ms.assetid: 68384064-7ee7-41e2-90e3-71f00bde01bb --- # How to: Write a Parallel.For Loop with Thread-Local Variables -This example shows how to use thread-local variables to store and retrieve state in each separate task that is created by a loop. By using thread-local data, you can avoid the overhead of synchronizing a large number of accesses to shared state. Instead of writing to a shared resource on each iteration, you compute and store the value until all iterations for the task are complete. You can then write the final result once to the shared resource, or pass it to another method. - -## Example +This example shows how to use thread-local variables to store and retrieve state in each separate task that is created by a loop. By using thread-local data, you can avoid the overhead of synchronizing a large number of accesses to shared state. Instead of writing to a shared resource on each iteration, you compute and store the value until all iterations for the task are complete. You can then write the final result once to the shared resource, or pass it to another method. + +## Example + + The following example calls the method to calculate the sum of the values in an array that contains one million elements. The value of each element is equal to its index. - The following example calls the method to calculate the sum of the values in an array that contains one million elements. The value of each element is equal to its index. - [!code-csharp[TPL_Parallel#05](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_parallel/cs/forandforeach_simple.cs#05)] - [!code-vb[TPL_Parallel#05](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_parallel/vb/forwiththreadlocal.vb#05)] - - The first two parameters of every method specify the beginning and ending iteration values. In this overload of the method, the third parameter is where you initialize your local state. In this context, local state means a variable whose lifetime extends from just before the first iteration of the loop on the current thread, to just after the last iteration. - - The type of the third parameter is a where `TResult` is the type of the variable that will store the thread-local state. Its type is defined by the generic type argument supplied when calling the generic method, which in this case is . The type argument tells the compiler the type of the temporary variable that will be used to store the thread-local state. In this example, the expression `() => 0` (or `Function() 0` in Visual Basic) initializes the thread-local variable to zero. If the generic type argument is a reference type or user-defined value type, the expression would look like this: - -```csharp -() => new MyClass() -``` - -```vb -Function() new MyClass() -``` - - The fourth parameter defines the loop logic. It must be a delegate or lambda expression whose signature is `Func` in C# or `Func(Of Integer, ParallelLoopState, Long, Long)` in Visual Basic. The first parameter is the value of the loop counter for that iteration of the loop. The second is a object that can be used to break out of the loop; this object is provided by the class to each occurrence of the loop. The third parameter is the thread-local variable. The last parameter is the return type. In this case, the type is because that is the type we specified in the type argument. That variable is named `subtotal` and is returned by the lambda expression. The return value is used to initialize `subtotal` on each subsequent iteration of the loop. You can also think of this last parameter as a value that is passed to each iteration, and then passed to the `localFinally` delegate when the last iteration is complete. - - The fifth parameter defines the method that is called once, after all the iterations on a particular thread have completed. The type of the input argument again corresponds to the type argument of the method and the type returned by the body lambda expression. In this example, the value is added to a variable at class scope in a thread safe way by calling the method. By using a thread-local variable, we have avoided writing to this class variable on every iteration of the loop. - - For more information about how to use lambda expressions, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). - + [!code-vb[TPL_Parallel#05](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_parallel/vb/forwiththreadlocal.vb#05)] + + The first two parameters of every method specify the beginning and ending iteration values. In this overload of the method, the third parameter is where you initialize your local state. In this context, local state means a variable whose lifetime extends from just before the first iteration of the loop on the current thread, to just after the last iteration. + + The type of the third parameter is a where `TResult` is the type of the variable that will store the thread-local state. Its type is defined by the generic type argument supplied when calling the generic method, which in this case is . The type argument tells the compiler the type of the temporary variable that will be used to store the thread-local state. In this example, the expression `() => 0` (or `Function() 0` in Visual Basic) initializes the thread-local variable to zero. If the generic type argument is a reference type or user-defined value type, the expression would look like this: + +```csharp +() => new MyClass() +``` + +```vb +Function() new MyClass() +``` + + The fourth parameter defines the loop logic. It must be a delegate or lambda expression whose signature is `Func` in C# or `Func(Of Integer, ParallelLoopState, Long, Long)` in Visual Basic. The first parameter is the value of the loop counter for that iteration of the loop. The second is a object that can be used to break out of the loop; this object is provided by the class to each occurrence of the loop. The third parameter is the thread-local variable. The last parameter is the return type. In this case, the type is because that is the type we specified in the type argument. That variable is named `subtotal` and is returned by the lambda expression. The return value is used to initialize `subtotal` on each subsequent iteration of the loop. You can also think of this last parameter as a value that is passed to each iteration, and then passed to the `localFinally` delegate when the last iteration is complete. + + The fifth parameter defines the method that is called once, after all the iterations on a particular thread have completed. The type of the input argument again corresponds to the type argument of the method and the type returned by the body lambda expression. In this example, the value is added to a variable at class scope in a thread safe way by calling the method. By using a thread-local variable, we have avoided writing to this class variable on every iteration of the loop. + + For more information about how to use lambda expressions, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). + ## See also - [Data Parallelism](data-parallelism-task-parallel-library.md) diff --git a/docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-partition-local-variables.md b/docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-partition-local-variables.md index 553190a9b4a33..30f80aba9be42 100644 --- a/docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-partition-local-variables.md +++ b/docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-partition-local-variables.md @@ -11,23 +11,23 @@ ms.assetid: 24b10041-b30b-45cb-aa65-66cf568ca76d --- # How to: Write a Parallel.ForEach loop with partition-local variables -The following example shows how to write a method that uses partition-local variables. When a loop executes, it divides its source collection into multiple partitions. Each partition has its own copy of the partition-local variable. A partition-local variable is similar to a [thread-local variable](xref:System.Threading.ThreadLocal%601), except that multiple partitions can run on a single thread. +The following example shows how to write a method that uses partition-local variables. When a loop executes, it divides its source collection into multiple partitions. Each partition has its own copy of the partition-local variable. A partition-local variable is similar to a [thread-local variable](xref:System.Threading.ThreadLocal`1), except that multiple partitions can run on a single thread. -The code and parameters in this example closely resemble the corresponding method. For more information, see [How to: Write a Parallel.For Loop with Thread-Local Variables](how-to-write-a-parallel-for-loop-with-thread-local-variables.md). +The code and parameters in this example closely resemble the corresponding method. For more information, see [How to: Write a Parallel.For Loop with Thread-Local Variables](how-to-write-a-parallel-for-loop-with-thread-local-variables.md). -To use a partition-local variable in a loop, you must call one of the method overloads that takes two type parameters. The first type parameter, `TSource`, specifies the type of the source element, and the second type parameter, `TLocal`, specifies the type of the partition-local variable. +To use a partition-local variable in a loop, you must call one of the method overloads that takes two type parameters. The first type parameter, `TSource`, specifies the type of the source element, and the second type parameter, `TLocal`, specifies the type of the partition-local variable. ## Example -The following example calls the overload to compute the sum of an array of one million elements. This overload has four parameters: +The following example calls the overload to compute the sum of an array of one million elements. This overload has four parameters: -- `source`, which is the data source. It must implement . The data source in our example is the one million member `IEnumerable` object returned by the method. +- `source`, which is the data source. It must implement . The data source in our example is the one million member `IEnumerable` object returned by the method. -- `localInit`, or the function that initializes the partition-local variable. This function is called once for each partition in which the operation executes. Our example initializes the partition-local variable to zero. +- `localInit`, or the function that initializes the partition-local variable. This function is called once for each partition in which the operation executes. Our example initializes the partition-local variable to zero. -- `body`, a that is invoked by the parallel loop on each iteration of the loop. Its signature is `Func\`. You supply the code for the delegate, and the loop passes in the input parameters, which are: +- `body`, a that is invoked by the parallel loop on each iteration of the loop. Its signature is `Func\`. You supply the code for the delegate, and the loop passes in the input parameters, which are: - - The current element of the . + - The current element of the . - A variable that you can use in your delegate's code to examine the state of the loop. @@ -37,7 +37,7 @@ The following example calls the ` delegate that the invokes when the looping operations in each partition have completed. The method passes your `Action` delegate the final value of the partition-local variable for this loop partition, and you provide the code that performs the required action for combining the result from this partition with the results from the other partitions. This delegate can be invoked concurrently by multiple tasks. Because of this, the example uses the method to synchronize access to the `total` variable. Because the delegate type is an , there is no return value. +- `localFinally`, an `Action` delegate that the invokes when the looping operations in each partition have completed. The method passes your `Action` delegate the final value of the partition-local variable for this loop partition, and you provide the code that performs the required action for combining the result from this partition with the results from the other partitions. This delegate can be invoked concurrently by multiple tasks. Because of this, the example uses the method to synchronize access to the `total` variable. Because the delegate type is an , there is no return value. [!code-csharp[TPL_Parallel#04](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_parallel/cs/foreachthreadlocal.cs#04)] [!code-vb[TPL_Parallel#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_parallel/vb/foreachthreadlocal.vb#04)] diff --git a/docs/standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md b/docs/standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md index 41dfac9184d72..bd698c28a4b67 100644 --- a/docs/standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md +++ b/docs/standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md @@ -13,7 +13,7 @@ ms.assetid: 9029ba7f-a9d1-4526-8c84-c88716dba5d4 --- # How to: Write a Simple Parallel.For Loop -This topic contains two examples that illustrate the method. The first uses the method overload, and the second uses the overload, the two simplest overloads of the method. You can use these two overloads of the method when you do not need to cancel the loop, break out of the loop iterations, or maintain any thread-local state. +This topic contains two examples that illustrate the method. The first uses the method overload, and the second uses the overload, the two simplest overloads of the method. You can use these two overloads of the method when you do not need to cancel the loop, break out of the loop iterations, or maintain any thread-local state. > [!NOTE] > This documentation uses lambda expressions to define delegates in TPL. If you are not familiar with lambda expressions in C# or Visual Basic, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). @@ -22,14 +22,14 @@ The first example calculates the size of files in a single directory. The second ## Directory size example -This example is a simple command-line utility that calculates the total size of files in a directory. It expects a single directory path as an argument, and reports the number and total size of the files in that directory. After verifying that the directory exists, it uses the method to enumerate the files in the directory and determine their file sizes. Each file size is then added to the `totalSize` variable. Note that the addition is performed by calling the so that the addition is performed as an atomic operation. Otherwise, multiple tasks could try to update the `totalSize` variable simultaneously. +This example is a simple command-line utility that calculates the total size of files in a directory. It expects a single directory path as an argument, and reports the number and total size of the files in that directory. After verifying that the directory exists, it uses the method to enumerate the files in the directory and determine their file sizes. Each file size is then added to the `totalSize` variable. Note that the addition is performed by calling the so that the addition is performed as an atomic operation. Otherwise, multiple tasks could try to update the `totalSize` variable simultaneously. [!code-csharp[Conceptual.Parallel.For#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.parallel.for/cs/for1.cs#1)] [!code-vb[Conceptual.Parallel.For#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.parallel.for/vb/for1.vb#1)] ## Matrix and stopwatch example -This example uses the method to compute the product of two matrices. It also shows how to use the class to compare the performance of a parallel loop with a non-parallel loop. Note that, because it can generate a large volume of output, the example allows output to be redirected to a file. +This example uses the method to compute the product of two matrices. It also shows how to use the class to compare the performance of a parallel loop with a non-parallel loop. Note that, because it can generate a large volume of output, the example allows output to be redirected to a file. [!code-csharp[TPL_Parallel#01](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_parallel/cs/simpleparallelfor.cs#01)] [!code-vb[TPL_Parallel#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_parallel/vb/simpleparallelfor.vb#01)] @@ -38,7 +38,7 @@ When parallelizing any code, including loops, one important goal is to utilize t ## The Delegate -The third parameter of this overload of is a delegate of type `Action` in C# or `Action(Of Integer)` in Visual Basic. An `Action` delegate, whether it has zero, one or sixteen type parameters, always returns void. In Visual Basic, the behavior of an `Action` is defined with a `Sub`. The example uses a lambda expression to create the delegate, but you can create the delegate in other ways as well. For more information, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). +The third parameter of this overload of is a delegate of type `Action` in C# or `Action(Of Integer)` in Visual Basic. An `Action` delegate, whether it has zero, one or sixteen type parameters, always returns void. In Visual Basic, the behavior of an `Action` is defined with a `Sub`. The example uses a lambda expression to create the delegate, but you can create the delegate in other ways as well. For more information, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). ## The Iteration Value @@ -48,15 +48,15 @@ If you require more control over the concurrency level, use one of the overloads ## Return Value and Exception Handling - returns use a object when all threads have completed. This return value is useful when you are stopping or breaking loop iteration manually, because the stores information such as the last iteration that ran to completion. If one or more exceptions occur on one of the threads, a will be thrown. + returns use a object when all threads have completed. This return value is useful when you are stopping or breaking loop iteration manually, because the stores information such as the last iteration that ran to completion. If one or more exceptions occur on one of the threads, a will be thrown. -In the code in this example, the return value of is not used. +In the code in this example, the return value of is not used. ## Analysis and Performance You can use the Performance Wizard to view CPU usage on your computer. As an experiment, increase the number of columns and rows in the matrices. The larger the matrices, the greater the performance difference between the parallel and sequential versions of the computation. When the matrix is small, the sequential version will run faster because of the overhead in setting up the parallel loop. -Synchronous calls to shared resources, like the Console or the File System, will significantly degrade the performance of a parallel loop. When measuring performance, try to avoid calls such as within the loop. +Synchronous calls to shared resources, like the Console or the File System, will significantly degrade the performance of a parallel loop. When measuring performance, try to avoid calls such as within the loop. ## Compile the Code @@ -64,7 +64,7 @@ Copy and paste this code into a Visual Studio project. ## See also -- -- +- +- - [Data Parallelism](data-parallelism-task-parallel-library.md) - [Parallel Programming](index.md) diff --git a/docs/standard/parallel-programming/how-to-write-a-simple-parallel-foreach-loop.md b/docs/standard/parallel-programming/how-to-write-a-simple-parallel-foreach-loop.md index f1ff07fb32875..bc3bab5c51fa9 100644 --- a/docs/standard/parallel-programming/how-to-write-a-simple-parallel-foreach-loop.md +++ b/docs/standard/parallel-programming/how-to-write-a-simple-parallel-foreach-loop.md @@ -13,28 +13,28 @@ ms.assetid: cb5fab92-1c19-499e-ae91-8b7525dd875f --- # How to: Write a simple Parallel.ForEach loop -This article shows how to use a loop to enable data parallelism over any or data source. +This article shows how to use a loop to enable data parallelism over any or data source. > [!NOTE] > This documentation uses lambda expressions to define delegates in PLINQ. If you aren't familiar with lambda expressions in C# or Visual Basic, see [Lambda expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). ## Example -This example demonstrates for CPU-intensive operations. When you run the example, it randomly generates 2 million numbers and tries to filter to prime numbers. The first case iterates over the collection via a `for` loop. The second case iterates over the collection via . The resulting time taken by each iteration is displayed when the application is finished. +This example demonstrates for CPU-intensive operations. When you run the example, it randomly generates 2 million numbers and tries to filter to prime numbers. The first case iterates over the collection via a `for` loop. The second case iterates over the collection via . The resulting time taken by each iteration is displayed when the application is finished. [!code-csharp[TPL_Parallel#03](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_parallel/cs/simpleforeach.cs#03)] [!code-vb[TPL_Parallel#03](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_parallel/vb/simpleforeach.vb#03)] -A loop works like a loop. The loop partitions the source collection and schedules the work on multiple threads based on the system environment. The more processors on the system, the faster the parallel method runs. For some source collections, a sequential loop might be faster, depending on the size of the source and the kind of work the loop performs. For more information about performance, see [Potential pitfalls in data and task parallelism](potential-pitfalls-in-data-and-task-parallelism.md). +A loop works like a loop. The loop partitions the source collection and schedules the work on multiple threads based on the system environment. The more processors on the system, the faster the parallel method runs. For some source collections, a sequential loop might be faster, depending on the size of the source and the kind of work the loop performs. For more information about performance, see [Potential pitfalls in data and task parallelism](potential-pitfalls-in-data-and-task-parallelism.md). For more information about parallel loops, see [How to: Write a simple Parallel.For loop](how-to-write-a-simple-parallel-for-loop.md). -To use the loop with a non-generic collection, you can use the extension method to convert the collection to a generic collection, as shown in the following example: +To use the loop with a non-generic collection, you can use the extension method to convert the collection to a generic collection, as shown in the following example: [!code-csharp[TPL_Parallel#07](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_parallel/cs/nongeneric.cs#07)] [!code-vb[TPL_Parallel#07](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_parallel/vb/nongeneric.vb#07)] -You can also use Parallel LINQ (PLINQ) to parallelize the processing of data sources. PLINQ enables you to use declarative query syntax to express the loop behavior. For more information, see [Parallel LINQ (PLINQ)](introduction-to-plinq.md). +You can also use Parallel LINQ (PLINQ) to parallelize the processing of data sources. PLINQ enables you to use declarative query syntax to express the loop behavior. For more information, see [Parallel LINQ (PLINQ)](introduction-to-plinq.md). ## Compile and run the code diff --git a/docs/standard/parallel-programming/how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md b/docs/standard/parallel-programming/how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md index 52473d2b66dd2..83414a2ed6907 100644 --- a/docs/standard/parallel-programming/how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md +++ b/docs/standard/parallel-programming/how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md @@ -13,30 +13,30 @@ ms.assetid: 1a9bf078-aa82-46eb-b95a-f87237f028c5 # How to: Write and read messages from a Dataflow block -This article describes how to use the Task Parallel Library (TPL) Dataflow Library to write messages to and read messages from a dataflow block. The TPL Dataflow Library provides both synchronous and asynchronous methods for writing messages to and reading messages from a dataflow block. This article shows how to uses the class. The class buffers messages and behaves as both a message source and a message target. +This article describes how to use the Task Parallel Library (TPL) Dataflow Library to write messages to and read messages from a dataflow block. The TPL Dataflow Library provides both synchronous and asynchronous methods for writing messages to and reading messages from a dataflow block. This article shows how to uses the class. The class buffers messages and behaves as both a message source and a message target. [!INCLUDE [tpl-install-instructions](../../../includes/tpl-install-instructions.md)] ## Writing and reading synchronously -The following example uses the method to write to a dataflow block and the method to read from the same object. +The following example uses the method to write to a dataflow block and the method to read from the same object. :::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_readwrite/cs/dataflowreadwrite.cs" id="2"::: :::code language="vb" source="../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_readwrite/vb/dataflowreadwrite.vb" id="2"::: -You can also use the method to read from a dataflow block, as shown in the following example. The method does not block the current thread and is useful when you occasionally poll for data. +You can also use the method to read from a dataflow block, as shown in the following example. The method does not block the current thread and is useful when you occasionally poll for data. :::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_readwrite/cs/dataflowreadwrite.cs" id="3"::: :::code language="vb" source="../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_readwrite/vb/dataflowreadwrite.vb" id="3"::: -Because the method acts synchronously, the object in the previous examples receives all data before the second loop reads data. The following example extends the first example by using to read from and write to the message block concurrently. Because awaits all the asynchronous operations that are executing concurrently, the values are not written to the object in any specific order. +Because the method acts synchronously, the object in the previous examples receives all data before the second loop reads data. The following example extends the first example by using to read from and write to the message block concurrently. Because awaits all the asynchronous operations that are executing concurrently, the values are not written to the object in any specific order. :::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_readwrite/cs/dataflowreadwrite.cs" id="4"::: :::code language="vb" source="../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_readwrite/vb/dataflowreadwrite.vb" id="4"::: ## Writing and reading asynchronously -The following example uses the method to asynchronously write to a object and the method to asynchronously read from the same object. This example uses the [async](../../csharp/language-reference/keywords/async.md) and [await](../../csharp/language-reference/operators/await.md) operators ([Async](../../visual-basic/language-reference/modifiers/async.md) and [Await](../../visual-basic/language-reference/operators/await-operator.md) in Visual Basic) to asynchronously send data to and read data from the target block. The method is useful when you must enable a dataflow block to postpone messages. The method is useful when you want to act on data when that data becomes available. For more information about how messages propagate among message blocks, see the section Message Passing in [Dataflow](dataflow-task-parallel-library.md). +The following example uses the method to asynchronously write to a object and the method to asynchronously read from the same object. This example uses the [async](../../csharp/language-reference/keywords/async.md) and [await](../../csharp/language-reference/operators/await.md) operators ([Async](../../visual-basic/language-reference/modifiers/async.md) and [Await](../../visual-basic/language-reference/operators/await-operator.md) in Visual Basic) to asynchronously send data to and read data from the target block. The method is useful when you must enable a dataflow block to postpone messages. The method is useful when you want to act on data when that data becomes available. For more information about how messages propagate among message blocks, see the section Message Passing in [Dataflow](dataflow-task-parallel-library.md). :::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_readwrite/cs/dataflowreadwrite.cs" id="5"::: :::code language="vb" source="../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_readwrite/vb/dataflowreadwrite.vb" id="5"::: diff --git a/docs/standard/parallel-programming/introduction-to-plinq.md b/docs/standard/parallel-programming/introduction-to-plinq.md index 5500276000128..eb1288a1d9dc5 100644 --- a/docs/standard/parallel-programming/introduction-to-plinq.md +++ b/docs/standard/parallel-programming/introduction-to-plinq.md @@ -14,13 +14,13 @@ ms.assetid: eaa720d8-8999-4eb7-8df5-3c19ca61cad0 Parallel LINQ (PLINQ) is a parallel implementation of the [Language-Integrated Query (LINQ)](../../csharp/linq/index.md) pattern. PLINQ implements the full set of LINQ standard query operators as extension methods for the namespace and has additional operators for parallel operations. PLINQ combines the simplicity and readability of LINQ syntax with the power of parallel programming. > [!TIP] -> If you're not familiar with LINQ, it features a unified model for querying any enumerable data source in a type-safe manner. LINQ to Objects is the name for LINQ queries that are run against in-memory collections such as and arrays. This article assumes that you have a basic understanding of LINQ. For more information, see [Language-Integrated Query (LINQ)](../../csharp/linq/index.md). +> If you're not familiar with LINQ, it features a unified model for querying any enumerable data source in a type-safe manner. LINQ to Objects is the name for LINQ queries that are run against in-memory collections such as and arrays. This article assumes that you have a basic understanding of LINQ. For more information, see [Language-Integrated Query (LINQ)](../../csharp/linq/index.md). ## What is a Parallel query? -A PLINQ query in many ways resembles a non-parallel LINQ to Objects query. PLINQ queries, just like sequential LINQ queries, operate on any in-memory or data source, and have deferred execution, which means they do not begin executing until the query is enumerated. The primary difference is that PLINQ attempts to make full use of all the processors on the system. It does this by partitioning the data source into segments, and then executing the query on each segment on separate worker threads in parallel on multiple processors. In many cases, parallel execution means that the query runs significantly faster. +A PLINQ query in many ways resembles a non-parallel LINQ to Objects query. PLINQ queries, just like sequential LINQ queries, operate on any in-memory or data source, and have deferred execution, which means they do not begin executing until the query is enumerated. The primary difference is that PLINQ attempts to make full use of all the processors on the system. It does this by partitioning the data source into segments, and then executing the query on each segment on separate worker threads in parallel on multiple processors. In many cases, parallel execution means that the query runs significantly faster. -Through parallel execution, PLINQ can achieve significant performance improvements over legacy code for certain kinds of queries, often just by adding the query operation to the data source. However, parallelism can introduce its own complexities, and not all query operations run faster in PLINQ. In fact, parallelization actually slows down certain queries. Therefore, you should understand how issues such as ordering affect parallel queries. For more information, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). +Through parallel execution, PLINQ can achieve significant performance improvements over legacy code for certain kinds of queries, often just by adding the query operation to the data source. However, parallelism can introduce its own complexities, and not all query operations run faster in PLINQ. In fact, parallelization actually slows down certain queries. Therefore, you should understand how issues such as ordering affect parallel queries. For more information, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). > [!NOTE] > This documentation uses lambda expressions to define delegates in PLINQ. If you are not familiar with lambda expressions in C# or Visual Basic, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). @@ -37,33 +37,33 @@ In addition to the standard query operators, the |The entry point for PLINQ. Specifies that the rest of the query should be parallelized, if it is possible.| -||Specifies that the rest of the query should be run sequentially, as a non-parallel LINQ query.| -||Specifies that PLINQ should preserve the ordering of the source sequence for the rest of the query, or until the ordering is changed, for example by the use of an orderby (Order By in Visual Basic) clause.| -||Specifies that PLINQ for the rest of the query is not required to preserve the ordering of the source sequence.| -||Specifies that PLINQ should periodically monitor the state of the provided cancellation token and cancel execution if it is requested.| -||Specifies the maximum number of processors that PLINQ should use to parallelize the query.| -||Provides a hint about how PLINQ should, if it is possible, merge parallel results back into just one sequence on the consuming thread.| -||Specifies whether PLINQ should parallelize the query even when the default behavior would be to run it sequentially.| -||A multithreaded enumeration method that, unlike iterating over the results of the query, enables results to be processed in parallel without first merging back to the consumer thread.| -| overload|An overload that is unique to PLINQ and enables intermediate aggregation over thread-local partitions, plus a final aggregation function to combine the results of all partitions.| +||The entry point for PLINQ. Specifies that the rest of the query should be parallelized, if it is possible.| +||Specifies that the rest of the query should be run sequentially, as a non-parallel LINQ query.| +||Specifies that PLINQ should preserve the ordering of the source sequence for the rest of the query, or until the ordering is changed, for example by the use of an orderby (Order By in Visual Basic) clause.| +||Specifies that PLINQ for the rest of the query is not required to preserve the ordering of the source sequence.| +||Specifies that PLINQ should periodically monitor the state of the provided cancellation token and cancel execution if it is requested.| +||Specifies the maximum number of processors that PLINQ should use to parallelize the query.| +||Provides a hint about how PLINQ should, if it is possible, merge parallel results back into just one sequence on the consuming thread.| +||Specifies whether PLINQ should parallelize the query even when the default behavior would be to run it sequentially.| +||A multithreaded enumeration method that, unlike iterating over the results of the query, enables results to be processed in parallel without first merging back to the consumer thread.| +| overload|An overload that is unique to PLINQ and enables intermediate aggregation over thread-local partitions, plus a final aggregation function to combine the results of all partitions.| ## The Opt-in Model -When you write a query, opt in to PLINQ by invoking the extension method on the data source, as shown in the following example. +When you write a query, opt in to PLINQ by invoking the extension method on the data source, as shown in the following example. [!code-csharp[PLINQ#1](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinq2_cs.cs#1)] [!code-vb[PLINQ#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#1)] -The extension method binds the subsequent query operators, in this case, `where` and `select`, to the implementations. +The extension method binds the subsequent query operators, in this case, `where` and `select`, to the implementations. ## Execution Modes -By default, PLINQ is conservative. At runtime, the PLINQ infrastructure analyzes the overall structure of the query. If the query is likely to yield speedups by parallelization, PLINQ partitions the source sequence into tasks that can be run concurrently. If it is not safe to parallelize a query, PLINQ just runs the query sequentially. If PLINQ has a choice between a potentially expensive parallel algorithm or an inexpensive sequential algorithm, it chooses the sequential algorithm by default. You can use the method and the enumeration to instruct PLINQ to select the parallel algorithm. This is useful when you know by testing and measurement that a particular query executes faster in parallel. For more information, see [How to: Specify the Execution Mode in PLINQ](how-to-specify-the-execution-mode-in-plinq.md). +By default, PLINQ is conservative. At runtime, the PLINQ infrastructure analyzes the overall structure of the query. If the query is likely to yield speedups by parallelization, PLINQ partitions the source sequence into tasks that can be run concurrently. If it is not safe to parallelize a query, PLINQ just runs the query sequentially. If PLINQ has a choice between a potentially expensive parallel algorithm or an inexpensive sequential algorithm, it chooses the sequential algorithm by default. You can use the method and the enumeration to instruct PLINQ to select the parallel algorithm. This is useful when you know by testing and measurement that a particular query executes faster in parallel. For more information, see [How to: Specify the Execution Mode in PLINQ](how-to-specify-the-execution-mode-in-plinq.md). ## Degree of Parallelism -By default, PLINQ uses all of the processors on the host computer. You can instruct PLINQ to use no more than a specified number of processors by using the method. This is useful when you want to make sure that other processes running on the computer receive a certain amount of CPU time. The following snippet limits the query to utilizing a maximum of two processors. +By default, PLINQ uses all of the processors on the host computer. You can instruct PLINQ to use no more than a specified number of processors by using the method. This is useful when you want to make sure that other processes running on the computer receive a certain amount of CPU time. The following snippet limits the query to utilizing a maximum of two processors. [!code-csharp[PLINQ#5](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqsamples.cs#5)] [!code-vb[PLINQ#5](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#5)] @@ -72,7 +72,7 @@ In cases where a query is performing a significant amount of non-compute-bound w ## Ordered Versus Unordered Parallel Queries -In some queries, a query operator must produce results that preserve the ordering of the source sequence. PLINQ provides the operator for this purpose. is distinct from . An sequence is still processed in parallel, but its results are buffered and sorted. Because order preservation typically involves extra work, an sequence might be processed more slowly than the default sequence. Whether a particular ordered parallel operation is faster than a sequential version of the operation depends on many factors. +In some queries, a query operator must produce results that preserve the ordering of the source sequence. PLINQ provides the operator for this purpose. is distinct from . An sequence is still processed in parallel, but its results are buffered and sorted. Because order preservation typically involves extra work, an sequence might be processed more slowly than the default sequence. Whether a particular ordered parallel operation is faster than a sequential version of the operation depends on many factors. The following code example shows how to opt in to order preservation. @@ -83,26 +83,26 @@ For more information, see [Order Preservation in PLINQ](order-preservation-in-pl ## Parallel vs. Sequential Queries -Some operations require that the source data be delivered in a sequential manner. The query operators revert to sequential mode automatically when it is required. For user-defined query operators and user delegates that require sequential execution, PLINQ provides the method. When you use , all subsequent operators in the query are executed sequentially until is called again. For more information, see [How to: Combine Parallel and Sequential LINQ Queries](how-to-combine-parallel-and-sequential-linq-queries.md). +Some operations require that the source data be delivered in a sequential manner. The query operators revert to sequential mode automatically when it is required. For user-defined query operators and user delegates that require sequential execution, PLINQ provides the method. When you use , all subsequent operators in the query are executed sequentially until is called again. For more information, see [How to: Combine Parallel and Sequential LINQ Queries](how-to-combine-parallel-and-sequential-linq-queries.md). ## Options for Merging Query Results -When a PLINQ query executes in parallel, its results from each worker thread must be merged back onto the main thread for consumption by a `foreach` loop (`For Each` in Visual Basic), or insertion into a list or array. In some cases, it might be beneficial to specify a particular kind of merge operation, for example, to begin producing results more quickly. For this purpose, PLINQ supports the method, and the enumeration. For more information, see [Merge Options in PLINQ](merge-options-in-plinq.md). +When a PLINQ query executes in parallel, its results from each worker thread must be merged back onto the main thread for consumption by a `foreach` loop (`For Each` in Visual Basic), or insertion into a list or array. In some cases, it might be beneficial to specify a particular kind of merge operation, for example, to begin producing results more quickly. For this purpose, PLINQ supports the method, and the enumeration. For more information, see [Merge Options in PLINQ](merge-options-in-plinq.md). ## The ForAll Operator -In sequential LINQ queries, execution is deferred until the query is enumerated either in a `foreach` (`For Each` in Visual Basic) loop or by invoking a method such as , , or . In PLINQ, you can also use `foreach` to execute the query and iterate through the results. However, `foreach` itself does not run in parallel, and therefore, it requires that the output from all parallel tasks be merged back into the thread on which the loop is running. In PLINQ, you can use `foreach` when you must preserve the final ordering of the query results, and also whenever you are processing the results in a serial manner, for example when you are calling `Console.WriteLine` for each element. For faster query execution when order preservation is not required and when the processing of the results can itself be parallelized, use the method to execute a PLINQ query. does not perform this final merge step. The following code example shows how to use the method. is used here because it is optimized for multiple threads adding concurrently without attempting to remove any items. +In sequential LINQ queries, execution is deferred until the query is enumerated either in a `foreach` (`For Each` in Visual Basic) loop or by invoking a method such as , , or . In PLINQ, you can also use `foreach` to execute the query and iterate through the results. However, `foreach` itself does not run in parallel, and therefore, it requires that the output from all parallel tasks be merged back into the thread on which the loop is running. In PLINQ, you can use `foreach` when you must preserve the final ordering of the query results, and also whenever you are processing the results in a serial manner, for example when you are calling `Console.WriteLine` for each element. For faster query execution when order preservation is not required and when the processing of the results can itself be parallelized, use the method to execute a PLINQ query. does not perform this final merge step. The following code example shows how to use the method. is used here because it is optimized for multiple threads adding concurrently without attempting to remove any items. [!code-csharp[PLINQ#4](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinq2_cs.cs#4)] [!code-vb[PLINQ#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#4)] -The following illustration shows the difference between `foreach` and with regard to query execution. +The following illustration shows the difference between `foreach` and with regard to query execution. ![ForAll vs. ForEach](media/vs-isvnt-allvseach.png "VS_ISVNT_ALLvsEACH") ## Cancellation -PLINQ is integrated with the cancellation types in .NET. (For more information, see [Cancellation in Managed Threads](../threading/cancellation-in-managed-threads.md).) Therefore, unlike sequential LINQ to Objects queries, PLINQ queries can be canceled. To create a cancelable PLINQ query, use the operator on the query and provide a instance as the argument. When the property on the token is set to true, PLINQ will notice it, stop processing on all threads, and throw an . +PLINQ is integrated with the cancellation types in .NET. (For more information, see [Cancellation in Managed Threads](../threading/cancellation-in-managed-threads.md).) Therefore, unlike sequential LINQ to Objects queries, PLINQ queries can be canceled. To create a cancelable PLINQ query, use the operator on the query and provide a instance as the argument. When the property on the token is set to true, PLINQ will notice it, stop processing on all threads, and throw an . It is possible that a PLINQ query might continue to process some elements after the cancellation token is set. @@ -123,7 +123,7 @@ In some cases, you can improve query performance by writing a custom partitioner [!code-csharp[PLINQ#2](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinq2_cs.cs#2)] [!code-vb[PLINQ#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq3.vb#2)] -PLINQ supports a fixed number of partitions (although data may be dynamically reassigned to those partitions during runtime for load balancing.). and support only dynamic partitioning, which means that the number of partitions changes at runtime. For more information, see [Custom Partitioners for PLINQ and TPL](custom-partitioners-for-plinq-and-tpl.md). +PLINQ supports a fixed number of partitions (although data may be dynamically reassigned to those partitions during runtime for load balancing.). and support only dynamic partitioning, which means that the number of partitions changes at runtime. For more information, see [Custom Partitioners for PLINQ and TPL](custom-partitioners-for-plinq-and-tpl.md). ## Measuring PLINQ Performance diff --git a/docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md b/docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md index fde9b868c6a03..eea94042eba9e 100644 --- a/docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md +++ b/docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md @@ -13,14 +13,14 @@ ms.assetid: 645b2c17-29d0-4ffa-8684-430743cc2f2d --- # Lambda Expressions in PLINQ and TPL -The Task Parallel Library (TPL) contains many methods that take one of the or family of delegates as input parameters. You use these delegates to pass in your custom program logic to the parallel loop, task or query. The code examples for TPL as well as PLINQ use lambda expressions to create instances of those delegates as inline code blocks. This topic provides a brief introduction to Func and Action and shows you how to use lambda expressions in the Task Parallel Library and PLINQ. +The Task Parallel Library (TPL) contains many methods that take one of the or family of delegates as input parameters. You use these delegates to pass in your custom program logic to the parallel loop, task or query. The code examples for TPL as well as PLINQ use lambda expressions to create instances of those delegates as inline code blocks. This topic provides a brief introduction to Func and Action and shows you how to use lambda expressions in the Task Parallel Library and PLINQ. > [!NOTE] > For more information about delegates in general, see [Delegates](../../csharp/programming-guide/delegates/index.md) and [Delegates](../../visual-basic/programming-guide/language-features/delegates/index.md). For more information about lambda expressions in C# and Visual Basic, see [Lambda Expressions](../../csharp/language-reference/operators/lambda-expressions.md) and [Lambda Expressions](../../visual-basic/programming-guide/language-features/procedures/lambda-expressions.md). ## Func Delegate -A `Func` delegate encapsulates a method that returns a value. In a `Func` signature, the last, or rightmost, type parameter always specifies the return type. One common cause of compiler errors is to attempt to pass in two input parameters to a ; in fact this type takes only one input parameter. .NET defines 17 versions of `Func`: , , , and so on up through . +A `Func` delegate encapsulates a method that returns a value. In a `Func` signature, the last, or rightmost, type parameter always specifies the return type. One common cause of compiler errors is to attempt to pass in two input parameters to a ; in fact this type takes only one input parameter. .NET defines 17 versions of `Func`: , , , and so on up through . ## Action Delegate @@ -28,7 +28,7 @@ A delegate encapsulates a meth ## Example -The following example for the method shows how to express both Func and Action delegates by using lambda expressions. +The following example for the method shows how to express both Func and Action delegates by using lambda expressions. [!code-csharp[System.Threading.Tasks.Parallel#02](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.parallel/cs/parallelforeach.cs#02)] [!code-vb[System.Threading.Tasks.Parallel#02](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.parallel/vb/parallelforeach.vb#02)] diff --git a/docs/standard/parallel-programming/merge-options-in-plinq.md b/docs/standard/parallel-programming/merge-options-in-plinq.md index a9f11e82c72d8..e86c70ef73f82 100644 --- a/docs/standard/parallel-programming/merge-options-in-plinq.md +++ b/docs/standard/parallel-programming/merge-options-in-plinq.md @@ -2,64 +2,64 @@ description: "Learn more about: Merge Options in PLINQ" title: "Merge Options in PLINQ" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "PLINQ queries, merge options" ms.assetid: e8f7be3b-88de-4f33-ab14-dc008e76c1ba --- # Merge Options in PLINQ -When a query is executing as parallel, PLINQ partitions the source sequence so that multiple threads can work on different parts concurrently, typically on separate threads. If the results are to be consumed on one thread, for example, in a `foreach` (`For Each` in Visual Basic) loop, then the results from every thread must be merged back into one sequence. The kind of merge that PLINQ performs depends on the operators that are present in the query. For example, operators that impose a new order on the results must buffer all elements from all threads. From the perspective of the consuming thread (which is also that of the application user) a fully buffered query might run for a noticeable period of time before it produces its first result. Other operators, by default, are partially buffered; they yield their results in batches. One operator, is not buffered by default. It yields all elements from all threads immediately. - - By using the method, as shown in the following example, you can provide a hint to PLINQ that indicates what kind of merging to perform. - +When a query is executing as parallel, PLINQ partitions the source sequence so that multiple threads can work on different parts concurrently, typically on separate threads. If the results are to be consumed on one thread, for example, in a `foreach` (`For Each` in Visual Basic) loop, then the results from every thread must be merged back into one sequence. The kind of merge that PLINQ performs depends on the operators that are present in the query. For example, operators that impose a new order on the results must buffer all elements from all threads. From the perspective of the consuming thread (which is also that of the application user) a fully buffered query might run for a noticeable period of time before it produces its first result. Other operators, by default, are partially buffered; they yield their results in batches. One operator, is not buffered by default. It yields all elements from all threads immediately. + + By using the method, as shown in the following example, you can provide a hint to PLINQ that indicates what kind of merging to perform. + [!code-csharp[PLINQ#26](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqsamples.cs#26)] - [!code-vb[PLINQ#26](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#26)] - - For the complete example, see [How to: Specify Merge Options in PLINQ](how-to-specify-merge-options-in-plinq.md). - - If the particular query cannot support the requested option, then the option will just be ignored. In most cases, you do not have to specify a merge option for a PLINQ query. However, in some cases you may find by testing and measurement that a query executes best in a non-default mode. A common use of this option is to force a chunk-merging operator to stream its results in order to provide a more responsive user interface. - -## ParallelMergeOptions - - The enumeration includes the following options that specify, for supported query shapes, how the final output of the query is yielded when the results are consumed on one thread: - -- `Not Buffered` - - The option causes each processed element to be returned from each thread as soon as it is produced. This behavior is analogous to "streaming" the output. If the operator is present in the query, `NotBuffered` preserves the order of the source elements. Although `NotBuffered` starts yielding results as soon as they're available, the total time to produce all the results might still be longer than using one of the other merge options. - -- `Auto Buffered` - - The option causes the query to collect elements into a buffer and then periodically yield the buffer contents all at once to the consuming thread. This is analogous to yielding the source data in "chunks" instead of using the "streaming" behavior of `NotBuffered`. `AutoBuffered` may take longer than `NotBuffered` to make the first element available on the consuming thread. The size of the buffer and the exact yielding behavior are not configurable and may vary, depending on various factors that relate to the query. - -- `FullyBuffered` - - The option causes the output of the whole query to be buffered before any of the elements are yielded. When you use this option, it can take longer before the first element is available on the consuming thread, but the complete results might still be produced faster than by using the other options. - -## Query Operators that Support Merge Options - - The following table lists the operators that support all merge option modes, subject to the specified restrictions. - -|Operator|Restrictions| -|--------------|------------------| -||None| -||None| -||Non-ordered queries that have an Array or List source only.| -||None| -||None| -||Non-ordered queries that have an Array or List source only.| -||None| -||None| -||None| -||None| -||None| - - All other PLINQ query operators might ignore user-provided merge options. Some query operators, for example, and , cannot yield any elements until all have been produced and reordered. Therefore, when is used in a query that also contains an operator such as , the merge behavior will not be applied in the query until after that operator has produced its results. - - The ability of some operators to handle merge options depends on the type of the source sequence, and whether the operator was used earlier in the query. is always ; it yields its elements immediately. is always ; it must sort the whole list before it yields. - + [!code-vb[PLINQ#26](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#26)] + + For the complete example, see [How to: Specify Merge Options in PLINQ](how-to-specify-merge-options-in-plinq.md). + + If the particular query cannot support the requested option, then the option will just be ignored. In most cases, you do not have to specify a merge option for a PLINQ query. However, in some cases you may find by testing and measurement that a query executes best in a non-default mode. A common use of this option is to force a chunk-merging operator to stream its results in order to provide a more responsive user interface. + +## ParallelMergeOptions + + The enumeration includes the following options that specify, for supported query shapes, how the final output of the query is yielded when the results are consumed on one thread: + +- `Not Buffered` + + The option causes each processed element to be returned from each thread as soon as it is produced. This behavior is analogous to "streaming" the output. If the operator is present in the query, `NotBuffered` preserves the order of the source elements. Although `NotBuffered` starts yielding results as soon as they're available, the total time to produce all the results might still be longer than using one of the other merge options. + +- `Auto Buffered` + + The option causes the query to collect elements into a buffer and then periodically yield the buffer contents all at once to the consuming thread. This is analogous to yielding the source data in "chunks" instead of using the "streaming" behavior of `NotBuffered`. `AutoBuffered` may take longer than `NotBuffered` to make the first element available on the consuming thread. The size of the buffer and the exact yielding behavior are not configurable and may vary, depending on various factors that relate to the query. + +- `FullyBuffered` + + The option causes the output of the whole query to be buffered before any of the elements are yielded. When you use this option, it can take longer before the first element is available on the consuming thread, but the complete results might still be produced faster than by using the other options. + +## Query Operators that Support Merge Options + + The following table lists the operators that support all merge option modes, subject to the specified restrictions. + +|Operator|Restrictions| +|--------------|------------------| +||None| +||None| +||Non-ordered queries that have an Array or List source only.| +||None| +||None| +||Non-ordered queries that have an Array or List source only.| +||None| +||None| +||None| +||None| +||None| + + All other PLINQ query operators might ignore user-provided merge options. Some query operators, for example, and , cannot yield any elements until all have been produced and reordered. Therefore, when is used in a query that also contains an operator such as , the merge behavior will not be applied in the query until after that operator has produced its results. + + The ability of some operators to handle merge options depends on the type of the source sequence, and whether the operator was used earlier in the query. is always ; it yields its elements immediately. is always ; it must sort the whole list before it yields. + ## See also - [Parallel LINQ (PLINQ)](introduction-to-plinq.md) diff --git a/docs/standard/parallel-programming/order-preservation-in-plinq.md b/docs/standard/parallel-programming/order-preservation-in-plinq.md index 0d4b20a9a7352..6e7ab97179114 100644 --- a/docs/standard/parallel-programming/order-preservation-in-plinq.md +++ b/docs/standard/parallel-programming/order-preservation-in-plinq.md @@ -2,120 +2,120 @@ description: "Learn more about: Order Preservation in PLINQ" title: "Order Preservation in PLINQ" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "PLINQ queries, order preservation" ms.assetid: 10d202bc-19e1-4b5c-bbf1-9a977322a9ca --- # Order Preservation in PLINQ -In PLINQ, the goal is to maximize performance while maintaining correctness. A query should run as fast as possible but still produce the correct results. In some cases, correctness requires the order of the source sequence to be preserved; however, ordering can be computationally expensive. Therefore, by default, PLINQ does not preserve the order of the source sequence. In this regard, PLINQ resembles [!INCLUDE[vbtecdlinq](../../../includes/vbtecdlinq-md.md)], but is unlike LINQ to Objects, which does preserve ordering. - - To override the default behavior, you can turn on order-preservation by using the operator on the source sequence. You can then turn off order preservation later in the query by using the method. With both methods, the query is processed based on the heuristics that determine whether to execute the query as parallel or as sequential. For more information, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). - - The following example shows an unordered parallel query that filters for all the elements that match a condition, without trying to order the results in any way. - +In PLINQ, the goal is to maximize performance while maintaining correctness. A query should run as fast as possible but still produce the correct results. In some cases, correctness requires the order of the source sequence to be preserved; however, ordering can be computationally expensive. Therefore, by default, PLINQ does not preserve the order of the source sequence. In this regard, PLINQ resembles [!INCLUDE[vbtecdlinq](../../../includes/vbtecdlinq-md.md)], but is unlike LINQ to Objects, which does preserve ordering. + + To override the default behavior, you can turn on order-preservation by using the operator on the source sequence. You can then turn off order preservation later in the query by using the method. With both methods, the query is processed based on the heuristics that determine whether to execute the query as parallel or as sequential. For more information, see [Understanding Speedup in PLINQ](understanding-speedup-in-plinq.md). + + The following example shows an unordered parallel query that filters for all the elements that match a condition, without trying to order the results in any way. + [!code-csharp[PLINQ#8](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqsamples.cs#8)] - [!code-vb[PLINQ#8](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#8)] - - This query does not necessarily produce the first 1000 cities in the source sequence that meet the condition, but rather some set of 1000 cities that meet the condition. PLINQ query operators partition the source sequence into multiple subsequences that are processed as concurrent tasks. If order preservation is not specified, the results from each partition are handed off to the next stage of the query in an arbitrary order. Also, a partition may yield a subset of its results before it continues to process the remaining elements. The resulting order may be different every time. Your application cannot control this because it depends on how the operating system schedules the threads. - - The following example overrides the default behavior by using the operator on the source sequence. This ensures that the method returns the first 1000 cities in the source sequence that meet the condition. - + [!code-vb[PLINQ#8](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#8)] + + This query does not necessarily produce the first 1000 cities in the source sequence that meet the condition, but rather some set of 1000 cities that meet the condition. PLINQ query operators partition the source sequence into multiple subsequences that are processed as concurrent tasks. If order preservation is not specified, the results from each partition are handed off to the next stage of the query in an arbitrary order. Also, a partition may yield a subset of its results before it continues to process the remaining elements. The resulting order may be different every time. Your application cannot control this because it depends on how the operating system schedules the threads. + + The following example overrides the default behavior by using the operator on the source sequence. This ensures that the method returns the first 1000 cities in the source sequence that meet the condition. + [!code-csharp[PLINQ#9](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqsamples.cs#9)] - [!code-vb[PLINQ#9](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#9)] - - However, this query probably does not run as fast as the unordered version because it must keep track of the original ordering throughout the partitions and at merge time ensure that the ordering is consistent. Therefore, we recommend that you use only when it is required, and only for those parts of the query that require it. When order preservation is no longer required, use to turn it off. The following example achieves this by composing two queries. - + [!code-vb[PLINQ#9](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#9)] + + However, this query probably does not run as fast as the unordered version because it must keep track of the original ordering throughout the partitions and at merge time ensure that the ordering is consistent. Therefore, we recommend that you use only when it is required, and only for those parts of the query that require it. When order preservation is no longer required, use to turn it off. The following example achieves this by composing two queries. + [!code-csharp[PLINQ#6](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqsamples.cs#6)] - [!code-vb[PLINQ#6](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#6)] - - Note that PLINQ preserves the ordering of a sequence produced by order-imposing operators for the rest of the query. In other words, operators such as and are treated as if they were followed by a call to . - -## Query Operators and Ordering - - The following query operators introduce order preservation into all subsequent operations in a query, or until is called: - -- - -- - -- - -- - - The following PLINQ query operators may in some cases require ordered source sequences to produce correct results: - -- - -- - -- - -- - -- - - Some PLINQ query operators behave differently, depending on whether their source sequence is ordered or unordered. The following table lists these operators. - -|Operator|Result when the source sequence is ordered|Result when the source sequence is unordered| -|--------------|------------------------------------------------|--------------------------------------------------| -||Nondeterministic output for nonassociative or noncommutative operations|Nondeterministic output for nonassociative or noncommutative operations| -||Not applicable|Not applicable| -||Not applicable|Not applicable| -||Not applicable|Not applicable| -||Nondeterministic output for nonassociative or noncommutative operations|Nondeterministic output for nonassociative or noncommutative operations| -||Ordered results|Unordered results| -||Ordered results|Unordered results| -||Not applicable|Not applicable| -||Not applicable|Not applicable| -||Ordered results|Unordered results| -||Return specified element|Arbitrary element| -||Return specified element|Arbitrary element| -||Unordered results|Unordered results| -||Return specified element|Arbitrary element| -||Return specified element|Arbitrary element| -||Executes nondeterministically in parallel|Executes nondeterministically in parallel| -||Ordered results|Unordered results| -||Ordered results|Unordered results| -||Ordered results|Unordered results| -||Ordered results|Unordered results| -||Return specified element|Arbitrary element| -||Return specified element|Arbitrary element| -||Not applicable|Not applicable| -||Not applicable|Not applicable| -||Reorders the sequence|Starts new ordered section| -||Reorders the sequence|Starts new ordered section| -||Not applicable (same default as )|Not applicable| -||Not applicable (same default as )|Not applicable| -||Reverses|Does nothing| -||Ordered results|Unordered results| -| (indexed)|Ordered results|Unordered results.| -||Ordered results.|Unordered results| -| (indexed)|Ordered results.|Unordered results.| -||Ordered comparison|Unordered comparison| -||Not applicable|Not applicable| -||Not applicable|Not applicable| -||Skips first *n* elements|Skips any *n* elements| -||Ordered results.|Nondeterministic. Performs SkipWhile on the current arbitrary order| -||Nondeterministic output for nonassociative or noncommutative operations|Nondeterministic output for nonassociative or noncommutative operations| -||Takes first `n` elements|Takes any `n` elements| -||Ordered results|Nondeterministic. Performs TakeWhile on the current arbitrary order| -||Supplements `OrderBy`|Supplements `OrderBy`| -||Supplements `OrderBy`|Supplements `OrderBy`| -||Ordered results|Unordered results| -||Not applicable|Not applicable| -||Ordered results|Unordered results| -||Ordered results|Unordered results| -||Ordered results|Unordered results| -||Ordered results|Unordered results| -| (indexed)|Ordered results|Unordered results| -||Ordered results|Unordered results| - - Unordered results are not actively shuffled; they simply do not have any special ordering logic applied to them. In some cases, an unordered query may retain the ordering of the source sequence. For queries that use the indexed Select operator, PLINQ guarantees that the output elements will come out in the order of increasing indices, but makes no guarantees about which indices will be assigned to which elements. - + [!code-vb[PLINQ#6](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#6)] + + Note that PLINQ preserves the ordering of a sequence produced by order-imposing operators for the rest of the query. In other words, operators such as and are treated as if they were followed by a call to . + +## Query Operators and Ordering + + The following query operators introduce order preservation into all subsequent operations in a query, or until is called: + +- + +- + +- + +- + + The following PLINQ query operators may in some cases require ordered source sequences to produce correct results: + +- + +- + +- + +- + +- + + Some PLINQ query operators behave differently, depending on whether their source sequence is ordered or unordered. The following table lists these operators. + +|Operator|Result when the source sequence is ordered|Result when the source sequence is unordered| +|--------------|------------------------------------------------|--------------------------------------------------| +||Nondeterministic output for nonassociative or noncommutative operations|Nondeterministic output for nonassociative or noncommutative operations| +||Not applicable|Not applicable| +||Not applicable|Not applicable| +||Not applicable|Not applicable| +||Nondeterministic output for nonassociative or noncommutative operations|Nondeterministic output for nonassociative or noncommutative operations| +||Ordered results|Unordered results| +||Ordered results|Unordered results| +||Not applicable|Not applicable| +||Not applicable|Not applicable| +||Ordered results|Unordered results| +||Return specified element|Arbitrary element| +||Return specified element|Arbitrary element| +||Unordered results|Unordered results| +||Return specified element|Arbitrary element| +||Return specified element|Arbitrary element| +||Executes nondeterministically in parallel|Executes nondeterministically in parallel| +||Ordered results|Unordered results| +||Ordered results|Unordered results| +||Ordered results|Unordered results| +||Ordered results|Unordered results| +||Return specified element|Arbitrary element| +||Return specified element|Arbitrary element| +||Not applicable|Not applicable| +||Not applicable|Not applicable| +||Reorders the sequence|Starts new ordered section| +||Reorders the sequence|Starts new ordered section| +||Not applicable (same default as )|Not applicable| +||Not applicable (same default as )|Not applicable| +||Reverses|Does nothing| +||Ordered results|Unordered results| +| (indexed)|Ordered results|Unordered results.| +||Ordered results.|Unordered results| +| (indexed)|Ordered results.|Unordered results.| +||Ordered comparison|Unordered comparison| +||Not applicable|Not applicable| +||Not applicable|Not applicable| +||Skips first *n* elements|Skips any *n* elements| +||Ordered results.|Nondeterministic. Performs SkipWhile on the current arbitrary order| +||Nondeterministic output for nonassociative or noncommutative operations|Nondeterministic output for nonassociative or noncommutative operations| +||Takes first `n` elements|Takes any `n` elements| +||Ordered results|Nondeterministic. Performs TakeWhile on the current arbitrary order| +||Supplements `OrderBy`|Supplements `OrderBy`| +||Supplements `OrderBy`|Supplements `OrderBy`| +||Ordered results|Unordered results| +||Not applicable|Not applicable| +||Ordered results|Unordered results| +||Ordered results|Unordered results| +||Ordered results|Unordered results| +||Ordered results|Unordered results| +| (indexed)|Ordered results|Unordered results| +||Ordered results|Unordered results| + + Unordered results are not actively shuffled; they simply do not have any special ordering logic applied to them. In some cases, an unordered query may retain the ordering of the source sequence. For queries that use the indexed Select operator, PLINQ guarantees that the output elements will come out in the order of increasing indices, but makes no guarantees about which indices will be assigned to which elements. + ## See also - [Parallel LINQ (PLINQ)](introduction-to-plinq.md) diff --git a/docs/standard/parallel-programming/potential-pitfalls-in-data-and-task-parallelism.md b/docs/standard/parallel-programming/potential-pitfalls-in-data-and-task-parallelism.md index 496f06900952a..c09a3714060dd 100644 --- a/docs/standard/parallel-programming/potential-pitfalls-in-data-and-task-parallelism.md +++ b/docs/standard/parallel-programming/potential-pitfalls-in-data-and-task-parallelism.md @@ -2,86 +2,86 @@ title: "Potential Pitfalls in Data and Task Parallelism" description: Learn about potential pitfalls in data and task parallelism, because parallelism adds complexity that isn't encountered in sequential code. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "parallel programming, pitfalls" ms.assetid: 1e357177-e699-4b8f-9e49-56d3513ed128 --- # Potential Pitfalls in Data and Task Parallelism -In many cases, and can provide significant performance improvements over ordinary sequential loops. However, the work of parallelizing the loop introduces complexity that can lead to problems that, in sequential code, are not as common or are not encountered at all. This topic lists some practices to avoid when you write parallel loops. - -## Do Not Assume That Parallel Is Always Faster - - In certain cases a parallel loop might run slower than its sequential equivalent. The basic rule of thumb is that parallel loops that have few iterations and fast user delegates are unlikely to speedup much. However, because many factors are involved in performance, we recommend that you always measure actual results. - -## Avoid Writing to Shared Memory Locations - - In sequential code, it is not uncommon to read from or write to static variables or class fields. However, whenever multiple threads are accessing such variables concurrently, there is a big potential for race conditions. Even though you can use locks to synchronize access to the variable, the cost of synchronization can hurt performance. Therefore, we recommend that you avoid, or at least limit, access to shared state in a parallel loop as much as possible. The best way to do this is to use the overloads of and that use a variable to store thread-local state during loop execution. For more information, see [How to: Write a Parallel.For Loop with Thread-Local Variables](how-to-write-a-parallel-for-loop-with-thread-local-variables.md) and [How to: Write a Parallel.ForEach Loop with Partition-Local Variables](how-to-write-a-parallel-foreach-loop-with-partition-local-variables.md). - -## Avoid Over-Parallelization - - By using parallel loops, you incur the overhead costs of partitioning the source collection and synchronizing the worker threads. The benefits of parallelization are further limited by the number of processors on the computer. There is no speedup to be gained by running multiple compute-bound threads on just one processor. Therefore, you must be careful not to over-parallelize a loop. - - The most common scenario in which over-parallelization can occur is in nested loops. In most cases, it is best to parallelize only the outer loop unless one or more of the following conditions apply: - -- The inner loop is known to be very long. - -- You are performing an expensive computation on each order. (The operation shown in the example is not expensive.) - -- The target system is known to have enough processors to handle the number of threads that will be produced by parallelizing the processing. - - In all cases, the best way to determine the optimum query shape is to test and measure. - -## Avoid Calls to Non-Thread-Safe Methods - - Writing to non-thread-safe instance methods from a parallel loop can lead to data corruption which may or may not go undetected in your program. It can also lead to exceptions. In the following example, multiple threads would be attempting to call the method simultaneously, which is not supported by the class. - +In many cases, and can provide significant performance improvements over ordinary sequential loops. However, the work of parallelizing the loop introduces complexity that can lead to problems that, in sequential code, are not as common or are not encountered at all. This topic lists some practices to avoid when you write parallel loops. + +## Do Not Assume That Parallel Is Always Faster + + In certain cases a parallel loop might run slower than its sequential equivalent. The basic rule of thumb is that parallel loops that have few iterations and fast user delegates are unlikely to speedup much. However, because many factors are involved in performance, we recommend that you always measure actual results. + +## Avoid Writing to Shared Memory Locations + + In sequential code, it is not uncommon to read from or write to static variables or class fields. However, whenever multiple threads are accessing such variables concurrently, there is a big potential for race conditions. Even though you can use locks to synchronize access to the variable, the cost of synchronization can hurt performance. Therefore, we recommend that you avoid, or at least limit, access to shared state in a parallel loop as much as possible. The best way to do this is to use the overloads of and that use a variable to store thread-local state during loop execution. For more information, see [How to: Write a Parallel.For Loop with Thread-Local Variables](how-to-write-a-parallel-for-loop-with-thread-local-variables.md) and [How to: Write a Parallel.ForEach Loop with Partition-Local Variables](how-to-write-a-parallel-foreach-loop-with-partition-local-variables.md). + +## Avoid Over-Parallelization + + By using parallel loops, you incur the overhead costs of partitioning the source collection and synchronizing the worker threads. The benefits of parallelization are further limited by the number of processors on the computer. There is no speedup to be gained by running multiple compute-bound threads on just one processor. Therefore, you must be careful not to over-parallelize a loop. + + The most common scenario in which over-parallelization can occur is in nested loops. In most cases, it is best to parallelize only the outer loop unless one or more of the following conditions apply: + +- The inner loop is known to be very long. + +- You are performing an expensive computation on each order. (The operation shown in the example is not expensive.) + +- The target system is known to have enough processors to handle the number of threads that will be produced by parallelizing the processing. + + In all cases, the best way to determine the optimum query shape is to test and measure. + +## Avoid Calls to Non-Thread-Safe Methods + + Writing to non-thread-safe instance methods from a parallel loop can lead to data corruption which may or may not go undetected in your program. It can also lead to exceptions. In the following example, multiple threads would be attempting to call the method simultaneously, which is not supported by the class. + [!code-csharp[TPL_Pitfalls#04](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_pitfalls/cs/pitfalls.cs#04)] - [!code-vb[TPL_Pitfalls#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_pitfalls/vb/pitfalls_vb.vb#04)] - -## Limit Calls to Thread-Safe Methods + [!code-vb[TPL_Pitfalls#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_pitfalls/vb/pitfalls_vb.vb#04)] + +## Limit Calls to Thread-Safe Methods + + Most static methods in .NET are thread-safe and can be called from multiple threads concurrently. However, even in these cases, the synchronization involved can lead to significant slowdown in the query. - Most static methods in .NET are thread-safe and can be called from multiple threads concurrently. However, even in these cases, the synchronization involved can lead to significant slowdown in the query. - > [!NOTE] -> You can test for this yourself by inserting some calls to in your queries. Although this method is used in the documentation examples for demonstration purposes, do not use it in parallel loops unless necessary. - -## Be Aware of Thread Affinity Issues +> You can test for this yourself by inserting some calls to in your queries. Although this method is used in the documentation examples for demonstration purposes, do not use it in parallel loops unless necessary. + +## Be Aware of Thread Affinity Issues + + Some technologies, for example, COM interoperability for Single-Threaded Apartment (STA) components, Windows Forms, and Windows Presentation Foundation (WPF), impose thread affinity restrictions that require code to run on a specific thread. For example, in both Windows Forms and WPF, a control can only be accessed on the thread on which it was created. This means, for example, that you cannot update a list control from a parallel loop unless you configure the thread scheduler to schedule work only on the UI thread. For more information, see [Specifying a synchronization context](xref:System.Threading.Tasks.TaskScheduler#specifying-a-synchronization-context). + +## Use Caution When Waiting in Delegates That Are Called by Parallel.Invoke - Some technologies, for example, COM interoperability for Single-Threaded Apartment (STA) components, Windows Forms, and Windows Presentation Foundation (WPF), impose thread affinity restrictions that require code to run on a specific thread. For example, in both Windows Forms and WPF, a control can only be accessed on the thread on which it was created. This means, for example, that you cannot update a list control from a parallel loop unless you configure the thread scheduler to schedule work only on the UI thread. For more information, see [Specifying a synchronization context](xref:System.Threading.Tasks.TaskScheduler#specifying-a-synchronization-context). - -## Use Caution When Waiting in Delegates That Are Called by Parallel.Invoke + In certain circumstances, the Task Parallel Library will inline a task, which means it runs on the task on the currently executing thread. (For more information, see [Task Schedulers](xref:System.Threading.Tasks.TaskScheduler).) This performance optimization can lead to deadlock in certain cases. For example, two tasks might run the same delegate code, which signals when an event occurs, and then waits for the other task to signal. If the second task is inlined on the same thread as the first, and the first goes into a Wait state, the second task will never be able to signal its event. To avoid such an occurrence, you can specify a timeout on the Wait operation, or use explicit thread constructors to help ensure that one task cannot block the other. - In certain circumstances, the Task Parallel Library will inline a task, which means it runs on the task on the currently executing thread. (For more information, see [Task Schedulers](xref:System.Threading.Tasks.TaskScheduler).) This performance optimization can lead to deadlock in certain cases. For example, two tasks might run the same delegate code, which signals when an event occurs, and then waits for the other task to signal. If the second task is inlined on the same thread as the first, and the first goes into a Wait state, the second task will never be able to signal its event. To avoid such an occurrence, you can specify a timeout on the Wait operation, or use explicit thread constructors to help ensure that one task cannot block the other. - -## Do Not Assume that Iterations of ForEach, For and ForAll Always Execute in Parallel +## Do Not Assume that Iterations of ForEach, For and ForAll Always Execute in Parallel + + It is important to keep in mind that individual iterations in a , or loop may but do not have to execute in parallel. Therefore, you should avoid writing any code that depends for correctness on parallel execution of iterations or on the execution of iterations in any particular order. For example, this code is likely to deadlock: - It is important to keep in mind that individual iterations in a , or loop may but do not have to execute in parallel. Therefore, you should avoid writing any code that depends for correctness on parallel execution of iterations or on the execution of iterations in any particular order. For example, this code is likely to deadlock: - [!code-csharp[TPL_Pitfalls#01](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_pitfalls/cs/pitfalls.cs#01)] - [!code-vb[TPL_Pitfalls#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_pitfalls/vb/pitfalls_vb.vb#01)] - - In this example, one iteration sets an event, and all other iterations wait on the event. None of the waiting iterations can complete until the event-setting iteration has completed. However, it is possible that the waiting iterations block all threads that are used to execute the parallel loop, before the event-setting iteration has had a chance to execute. This results in a deadlock – the event-setting iteration will never execute, and the waiting iterations will never wake up. - - In particular, one iteration of a parallel loop should never wait on another iteration of the loop to make progress. If the parallel loop decides to schedule the iterations sequentially but in the opposite order, a deadlock will occur. - -## Avoid Executing Parallel Loops on the UI Thread - - It is important to keep your application's user interface (UI) responsive. If an operation contains enough work to warrant parallelization, then it likely should not be run on the UI thread. Instead, it should offload that operation to be run on a background thread. For example, if you want to use a parallel loop to compute some data that should then be rendered into a UI control, you should consider executing the loop within a task instance rather than directly in a UI event handler. Only when the core computation has completed should you then marshal the UI update back to the UI thread. - - If you do run parallel loops on the UI thread, be careful to avoid updating UI controls from within the loop. Attempting to update UI controls from within a parallel loop that is executing on the UI thread can lead to state corruption, exceptions, delayed updates, and even deadlocks, depending on how the UI update is invoked. In the following example, the parallel loop blocks the UI thread on which it's executing until all iterations are complete. However, if an iteration of the loop is running on a background thread (as may do), the call to Invoke causes a message to be submitted to the UI thread and blocks waiting for that message to be processed. Since the UI thread is blocked running the , the message can never be processed, and the UI thread deadlocks. - + [!code-vb[TPL_Pitfalls#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_pitfalls/vb/pitfalls_vb.vb#01)] + + In this example, one iteration sets an event, and all other iterations wait on the event. None of the waiting iterations can complete until the event-setting iteration has completed. However, it is possible that the waiting iterations block all threads that are used to execute the parallel loop, before the event-setting iteration has had a chance to execute. This results in a deadlock – the event-setting iteration will never execute, and the waiting iterations will never wake up. + + In particular, one iteration of a parallel loop should never wait on another iteration of the loop to make progress. If the parallel loop decides to schedule the iterations sequentially but in the opposite order, a deadlock will occur. + +## Avoid Executing Parallel Loops on the UI Thread + + It is important to keep your application's user interface (UI) responsive. If an operation contains enough work to warrant parallelization, then it likely should not be run on the UI thread. Instead, it should offload that operation to be run on a background thread. For example, if you want to use a parallel loop to compute some data that should then be rendered into a UI control, you should consider executing the loop within a task instance rather than directly in a UI event handler. Only when the core computation has completed should you then marshal the UI update back to the UI thread. + + If you do run parallel loops on the UI thread, be careful to avoid updating UI controls from within the loop. Attempting to update UI controls from within a parallel loop that is executing on the UI thread can lead to state corruption, exceptions, delayed updates, and even deadlocks, depending on how the UI update is invoked. In the following example, the parallel loop blocks the UI thread on which it's executing until all iterations are complete. However, if an iteration of the loop is running on a background thread (as may do), the call to Invoke causes a message to be submitted to the UI thread and blocks waiting for that message to be processed. Since the UI thread is blocked running the , the message can never be processed, and the UI thread deadlocks. + [!code-csharp[TPL_Pitfalls#02](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_pitfalls/cs/pitfalls.cs#02)] - [!code-vb[TPL_Pitfalls#02](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_pitfalls/vb/pitfalls_vb.vb#02)] - - The following example shows how to avoid the deadlock, by running the loop inside a task instance. The UI thread is not blocked by the loop, and the message can be processed. - + [!code-vb[TPL_Pitfalls#02](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_pitfalls/vb/pitfalls_vb.vb#02)] + + The following example shows how to avoid the deadlock, by running the loop inside a task instance. The UI thread is not blocked by the loop, and the message can be processed. + [!code-csharp[TPL_Pitfalls#03](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_pitfalls/cs/pitfalls.cs#03)] - [!code-vb[TPL_Pitfalls#03](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_pitfalls/vb/pitfalls_vb.vb#03)] - + [!code-vb[TPL_Pitfalls#03](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_pitfalls/vb/pitfalls_vb.vb#03)] + ## See also - [Parallel Programming](index.md) diff --git a/docs/standard/parallel-programming/potential-pitfalls-with-plinq.md b/docs/standard/parallel-programming/potential-pitfalls-with-plinq.md index ed4a313c3216e..731ffb7e1d995 100644 --- a/docs/standard/parallel-programming/potential-pitfalls-with-plinq.md +++ b/docs/standard/parallel-programming/potential-pitfalls-with-plinq.md @@ -37,7 +37,7 @@ The correct approach is to use thread-safe operations that don't require shared :::code language="csharp" source="./snippets/potential-pitfalls-with-plinq/csharp/RaceConditionExample/Program.cs" id="RaceConditionGood"::: :::code language="vb" source="./snippets/potential-pitfalls-with-plinq/vb/RaceConditionExample/Program.vb" id="RaceConditionGood"::: -The `Sum` method handles parallelization internally in a thread-safe manner, ensuring correct results without the need for explicit synchronization. Other safe approaches include using for custom aggregations or collecting results into thread-safe collections like . +The `Sum` method handles parallelization internally in a thread-safe manner, ensuring correct results without the need for explicit synchronization. Other safe approaches include using for custom aggregations or collecting results into thread-safe collections like . ## Avoid over-parallelization @@ -77,7 +77,7 @@ a.AsParallel().Where(...).OrderBy(...).Select(...).ForAll(x => fs.Write(x)); Most static methods in .NET are thread-safe and can be called from multiple threads concurrently. However, even in these cases, the synchronization involved can lead to significant slowdown in the query. > [!NOTE] -> You can test for this yourself by inserting some calls to in your queries. Although this method is used in the documentation examples for demonstration purposes, do not use it in PLINQ queries. +> You can test for this yourself by inserting some calls to in your queries. Although this method is used in the documentation examples for demonstration purposes, do not use it in PLINQ queries. ## Avoid unnecessary ordering operations @@ -85,9 +85,9 @@ When PLINQ executes a query in parallel, it divides the source sequence into par ## Prefer ForAll to ForEach when it is possible -Although PLINQ executes a query on multiple threads, if you consume the results in a `foreach` loop (`For Each` in Visual Basic), then the query results must be merged back into one thread and accessed serially by the enumerator. In some cases, this is unavoidable; however, whenever possible, use the `ForAll` method to enable each thread to output its own results, for example, by writing to a thread-safe collection such as . +Although PLINQ executes a query on multiple threads, if you consume the results in a `foreach` loop (`For Each` in Visual Basic), then the query results must be merged back into one thread and accessed serially by the enumerator. In some cases, this is unavoidable; however, whenever possible, use the `ForAll` method to enable each thread to output its own results, for example, by writing to a thread-safe collection such as . -The same issue applies to . In other words, `source.AsParallel().Where().ForAll(...)` should be strongly preferred to `Parallel.ForEach(source.AsParallel().Where(), ...)`. +The same issue applies to . In other words, `source.AsParallel().Where().ForAll(...)` should be strongly preferred to `Parallel.ForEach(source.AsParallel().Where(), ...)`. ## Be aware of thread affinity issues @@ -95,7 +95,7 @@ Some technologies, for example, COM interoperability for Single-Threaded Apartme ## Don't assume that iterations of ForEach, For, and ForAll always execute in parallel -It is important to keep in mind that individual iterations in a , , or loop may but do not have to execute in parallel. Therefore, you should avoid writing any code that depends for correctness on parallel execution of iterations or on the execution of iterations in any particular order. +It is important to keep in mind that individual iterations in a , , or loop may but do not have to execute in parallel. Therefore, you should avoid writing any code that depends for correctness on parallel execution of iterations or on the execution of iterations in any particular order. For example, this code is likely to deadlock: diff --git a/docs/standard/parallel-programming/task-based-asynchronous-programming.md b/docs/standard/parallel-programming/task-based-asynchronous-programming.md index 3990cc4288922..1683e5265a567 100644 --- a/docs/standard/parallel-programming/task-based-asynchronous-programming.md +++ b/docs/standard/parallel-programming/task-based-asynchronous-programming.md @@ -27,7 +27,7 @@ For both reasons, TPL is the preferred API for writing multi-threaded, asynchron ## Creating and running tasks implicitly -The method provides a convenient way to run any number of arbitrary statements concurrently. Just pass in an delegate for each item of work. The easiest way to create these delegates is to use lambda expressions. The lambda expression can either call a named method or provide the code inline. The following example shows a basic call that creates and starts two tasks that run concurrently. The first task is represented by a lambda expression that calls a method named `DoSomeWork`, and the second task is represented by a lambda expression that calls a method named `DoSomeOtherWork`. +The method provides a convenient way to run any number of arbitrary statements concurrently. Just pass in an delegate for each item of work. The easiest way to create these delegates is to use lambda expressions. The lambda expression can either call a named method or provide the code inline. The following example shows a basic call that creates and starts two tasks that run concurrently. The first task is represented by a lambda expression that calls a method named `DoSomeWork`, and the second task is represented by a lambda expression that calls a method named `DoSomeOtherWork`. > [!NOTE] > This documentation uses lambda expressions to define delegates in TPL. If you aren't familiar with lambda expressions in C# or Visual Basic, see [Lambda Expressions in PLINQ and TPL](lambda-expressions-in-plinq-and-tpl.md). @@ -36,7 +36,7 @@ The [!NOTE] -> The number of instances that are created behind the scenes by isn't necessarily equal to the number of delegates that are provided. The TPL might employ various optimizations, especially with large numbers of delegates. +> The number of instances that are created behind the scenes by isn't necessarily equal to the number of delegates that are provided. The TPL might employ various optimizations, especially with large numbers of delegates. For more information, see [How to: Use Parallel.Invoke to Execute Parallel Operations](how-to-use-parallel-invoke-to-execute-parallel-operations.md). @@ -44,28 +44,28 @@ For greater control over task execution or to return a value from the task, you ## Creating and running tasks explicitly -A task that doesn't return a value is represented by the class. A task that returns a value is represented by the class, which inherits from . The task object handles the infrastructure details and provides methods and properties that are accessible from the calling thread throughout the lifetime of the task. For example, you can access the property of a task at any time to determine whether it has started running, ran to completion, was canceled, or has thrown an exception. The status is represented by a enumeration. +A task that doesn't return a value is represented by the class. A task that returns a value is represented by the class, which inherits from . The task object handles the infrastructure details and provides methods and properties that are accessible from the calling thread throughout the lifetime of the task. For example, you can access the property of a task at any time to determine whether it has started running, ran to completion, was canceled, or has thrown an exception. The status is represented by a enumeration. -When you create a task, you give it a user delegate that encapsulates the code that the task will execute. The delegate can be expressed as a named delegate, an anonymous method, or a lambda expression. Lambda expressions can contain a call to a named method, as shown in the following example. The example includes a call to the method to ensure that the task completes execution before the console mode application ends. +When you create a task, you give it a user delegate that encapsulates the code that the task will execute. The delegate can be expressed as a named delegate, an anonymous method, or a lambda expression. Lambda expressions can contain a call to a named method, as shown in the following example. The example includes a call to the method to ensure that the task completes execution before the console mode application ends. [!code-csharp[TPL_TaskIntro#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/lambda1.cs#1)] [!code-vb[TPL_TaskIntro#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/lambda1.vb#1)] -You can also use the methods to create and start a task in one operation. To manage the task, the methods use the default task scheduler, regardless of which task scheduler is associated with the current thread. The methods are the preferred way to create and start tasks when more control over the creation and scheduling of the task isn't needed. +You can also use the methods to create and start a task in one operation. To manage the task, the methods use the default task scheduler, regardless of which task scheduler is associated with the current thread. The methods are the preferred way to create and start tasks when more control over the creation and scheduling of the task isn't needed. [!code-csharp[TPL_TaskIntro#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/run1.cs#2)] [!code-vb[TPL_TaskIntro#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/run1.vb#2)] -You can also use the method to create and start a task in one operation. As shown in the following example, you can use this method when: +You can also use the method to create and start a task in one operation. As shown in the following example, you can use this method when: - Creation and scheduling don't have to be separated and you require additional task creation options or the use of a specific scheduler. -- You need to pass additional state into the task that you can retrieve through its property. +- You need to pass additional state into the task that you can retrieve through its property. [!code-csharp[TPL_TaskIntro#3](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/asyncstate.cs#23)] [!code-vb[TPL_TaskIntro#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/asyncstate.vb#23)] - and each expose a static property that returns a default instance of , so that you can call the method as `Task.Factory.StartNew()`. Also, in the following example, because the tasks are of type , they each have a public property that contains the result of the computation. The tasks run asynchronously and might complete in any order. If the property is accessed before the computation finishes, the property blocks the calling thread until the value is available. + and each expose a static property that returns a default instance of , so that you can call the method as `Task.Factory.StartNew()`. Also, in the following example, because the tasks are of type , they each have a public property that contains the result of the computation. The tasks run asynchronously and might complete in any order. If the property is accessed before the computation finishes, the property blocks the calling thread until the value is available. [!code-csharp[TPL_TaskIntro#4](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/result1.cs#4)] [!code-vb[TPL_TaskIntro#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/result1.vb#4)] @@ -82,14 +82,14 @@ You can access the value on each iteration by providing a state object to a task [!code-csharp[TPL_TaskIntro#21](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/iteration1a.cs#21)] [!code-vb[TPL_TaskIntro#21](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/iteration1a.vb#21)] -This state is passed as an argument to the task delegate, and it can be accessed from the task object by using the property. The following example is a variation on the previous example. It uses the property to display information about the `CustomData` objects passed to the lambda expression. +This state is passed as an argument to the task delegate, and it can be accessed from the task object by using the property. The following example is a variation on the previous example. It uses the property to display information about the `CustomData` objects passed to the lambda expression. [!code-csharp[TPL_TaskIntro#23](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/asyncstate.cs#23)] [!code-vb[TPL_TaskIntro#23](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/asyncstate.vb#23)] ## Task ID -Every task receives an integer ID that uniquely identifies it in an application domain and can be accessed by using the property. The ID is useful for viewing task information in the Visual Studio debugger **Parallel Stacks** and **Tasks** windows. The ID is created lazily, which means it isn't created until it's requested. Therefore, a task might have a different ID every time the program is run. For more information about how to view task IDs in the debugger, see [Using the Tasks Window](/visualstudio/debugger/using-the-tasks-window) and [Using the Parallel Stacks Window](/visualstudio/debugger/using-the-parallel-stacks-window). +Every task receives an integer ID that uniquely identifies it in an application domain and can be accessed by using the property. The ID is useful for viewing task information in the Visual Studio debugger **Parallel Stacks** and **Tasks** windows. The ID is created lazily, which means it isn't created until it's requested. Therefore, a task might have a different ID every time the program is run. For more information about how to view task IDs in the debugger, see [Using the Tasks Window](/visualstudio/debugger/using-the-tasks-window) and [Using the Parallel Stacks Window](/visualstudio/debugger/using-the-parallel-stacks-window). ## Task creation options @@ -102,9 +102,9 @@ The following example shows a task that has the and properties, respectively. A thread's culture is used in operations such as formatting, parsing, sorting, and string comparison operations. A thread's UI culture is used in resource lookup. +Each thread has an associated culture and UI culture, which are defined by the and properties, respectively. A thread's culture is used in operations such as formatting, parsing, sorting, and string comparison operations. A thread's UI culture is used in resource lookup. -The system culture defines the default culture and UI culture of a thread. However, you can specify a default culture for all the threads in an application domain by using the and properties. If you explicitly set a thread's culture and launch a new thread, the new thread doesn't inherit the culture of the calling thread; instead, its culture is the default system culture. However, in task-based programming, tasks use the calling thread's culture, even if the task runs asynchronously on a different thread. +The system culture defines the default culture and UI culture of a thread. However, you can specify a default culture for all the threads in an application domain by using the and properties. If you explicitly set a thread's culture and launch a new thread, the new thread doesn't inherit the culture of the calling thread; instead, its culture is the default system culture. However, in task-based programming, tasks use the calling thread's culture, even if the task runs asynchronously on a different thread. The following example provides a simple illustration. It changes the app's current culture to French (France). If French (France) is already the current culture, it changes to English (United States). It then invokes a delegate named `formatDelegate` that returns some numbers formatted as currency values in the new culture. Whether the delegate is invoked by a task either synchronously or asynchronously, the task uses the culture of the calling thread. @@ -119,19 +119,19 @@ For more information on asynchronous tasks and culture, see the "Culture and asy ## Creating task continuations -The and methods let you specify a task to start when the *antecedent task* finishes. The delegate of the continuation task is passed a reference to the antecedent task so that it can examine the antecedent task's status. And by retrieving the value of the property, you can use the output of the antecedent as input for the continuation. +The and methods let you specify a task to start when the *antecedent task* finishes. The delegate of the continuation task is passed a reference to the antecedent task so that it can examine the antecedent task's status. And by retrieving the value of the property, you can use the output of the antecedent as input for the continuation. -In the following example, the `getData` task is started by a call to the method. The `processData` task is started automatically when `getData` finishes, and `displayData` is started when `processData` finishes. `getData` produces an integer array, which is accessible to the `processData` task through the `getData` task's property. The `processData` task processes that array and returns a result whose type is inferred from the return type of the lambda expression passed to the method. The `displayData` task executes automatically when `processData` finishes, and the object returned by the `processData` lambda expression is accessible to the `displayData` task through the `processData` task's property. The `displayData` task takes the result of the `processData` task. It produces a result whose type is inferred in a similar manner, and which is made available to the program in the property. +In the following example, the `getData` task is started by a call to the method. The `processData` task is started automatically when `getData` finishes, and `displayData` is started when `processData` finishes. `getData` produces an integer array, which is accessible to the `processData` task through the `getData` task's property. The `processData` task processes that array and returns a result whose type is inferred from the return type of the lambda expression passed to the method. The `displayData` task executes automatically when `processData` finishes, and the object returned by the `processData` lambda expression is accessible to the `displayData` task through the `processData` task's property. The `displayData` task takes the result of the `processData` task. It produces a result whose type is inferred in a similar manner, and which is made available to the program in the property. [!code-csharp[TPL_TaskIntro#5](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/continuations1.cs#5)] [!code-vb[TPL_TaskIntro#5](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/continuations1.vb#5)] -Because is an instance method, you can chain method calls together instead of instantiating a object for each antecedent task. The following example is functionally identical to the previous one, except that it chains together calls to the method. The object returned by the chain of method calls is the final continuation task. +Because is an instance method, you can chain method calls together instead of instantiating a object for each antecedent task. The following example is functionally identical to the previous one, except that it chains together calls to the method. The object returned by the chain of method calls is the final continuation task. [!code-csharp[TPL_TaskIntro#24](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/continuations2.cs#24)] [!code-vb[TPL_TaskIntro#24](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/continuations2.vb#24)] -The and methods enable you to continue from multiple tasks. +The and methods enable you to continue from multiple tasks. For more information, see [Chaining Tasks by Using Continuation Tasks](chaining-tasks-by-using-continuation-tasks.md). @@ -147,7 +147,7 @@ When user code that's running in a task creates a new task and doesn't specify t ## Creating child tasks -When user code that's running in a task creates a task with the option, the new task is known as an *attached child task* of the parent task. You can use the option to express structured task parallelism because the parent task implicitly waits for all attached child tasks to finish. The following example shows a parent task that creates 10 attached child tasks. The example calls the method to wait for the parent task to finish. It doesn't have to explicitly wait for the attached child tasks to complete. +When user code that's running in a task creates a task with the option, the new task is known as an *attached child task* of the parent task. You can use the option to express structured task parallelism because the parent task implicitly waits for all attached child tasks to finish. The following example shows a parent task that creates 10 attached child tasks. The example calls the method to wait for the parent task to finish. It doesn't have to explicitly wait for the attached child tasks to complete. [!code-csharp[TPL_TaskIntro#8](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/child1.cs#8)] [!code-vb[TPL_TaskIntro#8](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/child1.vb#8)] @@ -156,7 +156,7 @@ A parent task can use the and types provide several overloads of the methods that enable you to wait for a task to finish. In addition, overloads of the static and methods let you wait for any or all of an array of tasks to finish. +The and types provide several overloads of the methods that enable you to wait for a task to finish. In addition, overloads of the static and methods let you wait for any or all of an array of tasks to finish. Typically, you would wait for a task for one of these reasons: @@ -175,55 +175,55 @@ For an example that shows exception handling, see [Exception Handling](exception Some overloads let you specify a time-out, and others take an additional as an input parameter so that the wait itself can be canceled either programmatically or in response to user input. -When you wait for a task, you implicitly wait for all children of that task that were created by using the option. returns immediately if the task has already completed. A method throws any exceptions raised by a task, even if the method was called after the task completed. +When you wait for a task, you implicitly wait for all children of that task that were created by using the option. returns immediately if the task has already completed. A method throws any exceptions raised by a task, even if the method was called after the task completed. ## Composing tasks -The and classes provide several methods to help you compose multiple tasks. These methods implement common patterns and make better use of the asynchronous language features that are provided by C#, Visual Basic, and F#. This section describes the , , , and methods. +The and classes provide several methods to help you compose multiple tasks. These methods implement common patterns and make better use of the asynchronous language features that are provided by C#, Visual Basic, and F#. This section describes the , , , and methods. ### Task.WhenAll -The method asynchronously waits for multiple or objects to finish. It provides overloaded versions that enable you to wait for non-uniform sets of tasks. For example, you can wait for multiple and objects to complete from one method call. +The method asynchronously waits for multiple or objects to finish. It provides overloaded versions that enable you to wait for non-uniform sets of tasks. For example, you can wait for multiple and objects to complete from one method call. ### Task.WhenAny -The method asynchronously waits for one of multiple or objects to finish. As in the method, this method provides overloaded versions that enable you to wait for non-uniform sets of tasks. The method is especially useful in the following scenarios: +The method asynchronously waits for one of multiple or objects to finish. As in the method, this method provides overloaded versions that enable you to wait for non-uniform sets of tasks. The method is especially useful in the following scenarios: -- **Redundant operations**: Consider an algorithm or operation that can be performed in many ways. You can use the method to select the operation that finishes first and then cancel the remaining operations. +- **Redundant operations**: Consider an algorithm or operation that can be performed in many ways. You can use the method to select the operation that finishes first and then cancel the remaining operations. -- **Interleaved operations**: You can start multiple operations that must finish and use the method to process results as each operation finishes. After one operation finishes, you can start one or more tasks. +- **Interleaved operations**: You can start multiple operations that must finish and use the method to process results as each operation finishes. After one operation finishes, you can start one or more tasks. -- **Throttled operations**: You can use the method to extend the previous scenario by limiting the number of concurrent operations. +- **Throttled operations**: You can use the method to extend the previous scenario by limiting the number of concurrent operations. -- **Expired operations**: You can use the method to select between one or more tasks and a task that finishes after a specific time, such as a task that's returned by the method. The method is described in the following section. +- **Expired operations**: You can use the method to select between one or more tasks and a task that finishes after a specific time, such as a task that's returned by the method. The method is described in the following section. ### Task.Delay -The method produces a object that finishes after the specified time. You can use this method to build loops that poll for data, to specify time-outs, to delay the handling of user input, and so on. +The method produces a object that finishes after the specified time. You can use this method to build loops that poll for data, to specify time-outs, to delay the handling of user input, and so on. ### Task(T).FromResult -By using the method, you can create a object that holds a pre-computed result. This method is useful when you perform an asynchronous operation that returns a object, and the result of that object is already computed. For an example that uses to retrieve the results of asynchronous download operations that are held in a cache, see [How to: Create Pre-Computed Tasks](how-to-create-pre-computed-tasks.md). +By using the method, you can create a object that holds a pre-computed result. This method is useful when you perform an asynchronous operation that returns a object, and the result of that object is already computed. For an example that uses to retrieve the results of asynchronous download operations that are held in a cache, see [How to: Create Pre-Computed Tasks](how-to-create-pre-computed-tasks.md). ## Handling exceptions in tasks -When a task throws one or more exceptions, the exceptions are wrapped in an exception. That exception is propagated back to the thread that joins with the task. Typically, it's the thread waiting for the task to finish or the thread accessing the property. This behavior enforces the .NET Framework policy that all unhandled exceptions by default should terminate the process. The calling code can handle the exceptions by using any of the following in a `try`/`catch` block: +When a task throws one or more exceptions, the exceptions are wrapped in an exception. That exception is propagated back to the thread that joins with the task. Typically, it's the thread waiting for the task to finish or the thread accessing the property. This behavior enforces the .NET Framework policy that all unhandled exceptions by default should terminate the process. The calling code can handle the exceptions by using any of the following in a `try`/`catch` block: -- The method +- The method -- The method +- The method -- The method +- The method -- The property +- The property -The joining thread can also handle exceptions by accessing the property before the task is garbage-collected. By accessing this property, you prevent the unhandled exception from triggering the exception propagation behavior that terminates the process when the object is finalized. +The joining thread can also handle exceptions by accessing the property before the task is garbage-collected. By accessing this property, you prevent the unhandled exception from triggering the exception propagation behavior that terminates the process when the object is finalized. For more information about exceptions and tasks, see [Exception Handling](exception-handling-task-parallel-library.md). ## Canceling tasks -The class supports cooperative cancellation and is fully integrated with the and classes, which were introduced in the .NET Framework 4. Many of the constructors in the class take a object as an input parameter. Many of the and overloads also include a parameter. +The class supports cooperative cancellation and is fully integrated with the and classes, which were introduced in the .NET Framework 4. Many of the constructors in the class take a object as an input parameter. Many of the and overloads also include a parameter. You can create the token and issue the cancellation request at some later time, by using the class. Pass the token to the as an argument, and also reference the same token in your user delegate, which does the work of responding to a cancellation request. @@ -233,17 +233,17 @@ For more information, see [Task Cancellation](task-cancellation.md) and [How to: The class provides static methods that encapsulate common patterns for creating and starting tasks and continuation tasks. -- The most common pattern is , which creates and starts a task in one statement. +- The most common pattern is , which creates and starts a task in one statement. -- When you create continuation tasks from multiple antecedents, use the method or method or their equivalents in the class. For more information, see [Chaining Tasks by Using Continuation Tasks](chaining-tasks-by-using-continuation-tasks.md). +- When you create continuation tasks from multiple antecedents, use the method or method or their equivalents in the class. For more information, see [Chaining Tasks by Using Continuation Tasks](chaining-tasks-by-using-continuation-tasks.md). -- To encapsulate Asynchronous Programming Model `BeginX` and `EndX` methods in a or instance, use the methods. For more information, see [TPL and Traditional .NET Framework Asynchronous Programming](tpl-and-traditional-async-programming.md). +- To encapsulate Asynchronous Programming Model `BeginX` and `EndX` methods in a or instance, use the methods. For more information, see [TPL and Traditional .NET Framework Asynchronous Programming](tpl-and-traditional-async-programming.md). -The default can be accessed as a static property on the class or class. You can also instantiate a directly and specify various options that include a , a option, a option, or a . Whatever options are specified when you create the task factory are applied to all tasks that it creates unless the is created by using the enumeration, in which case the task's options override those of the task factory. +The default can be accessed as a static property on the class or class. You can also instantiate a directly and specify various options that include a , a option, a option, or a . Whatever options are specified when you create the task factory are applied to all tasks that it creates unless the is created by using the enumeration, in which case the task's options override those of the task factory. ## Tasks without delegates -In some cases, you might want to use a to encapsulate some asynchronous operation that's performed by an external component instead of your user delegate. If the operation is based on the Asynchronous Programming Model Begin/End pattern, you can use the methods. If that's not the case, you can use the object to wrap the operation in a task and thereby gain some of the benefits of programmability. For example, support for exception propagation and continuations. For more information, see . +In some cases, you might want to use a to encapsulate some asynchronous operation that's performed by an external component instead of your user delegate. If the operation is based on the Asynchronous Programming Model Begin/End pattern, you can use the methods. If that's not the case, you can use the object to wrap the operation in a task and thereby gain some of the benefits of programmability. For example, support for exception propagation and continuations. For more information, see . ## Custom schedulers @@ -255,9 +255,9 @@ The TPL has several new public types that are useful in parallel and sequential ## Custom task types -We recommend that you don't inherit from or . Instead, we recommend that you use the property to associate additional data or state with a or object. You can also use extension methods to extend the functionality of the and classes. For more information about extension methods, see [Extension Methods](../../csharp/programming-guide/classes-and-structs/extension-methods.md) and [Extension Methods](../../visual-basic/programming-guide/language-features/procedures/extension-methods.md). +We recommend that you don't inherit from or . Instead, we recommend that you use the property to associate additional data or state with a or object. You can also use extension methods to extend the functionality of the and classes. For more information about extension methods, see [Extension Methods](../../csharp/programming-guide/classes-and-structs/extension-methods.md) and [Extension Methods](../../visual-basic/programming-guide/language-features/procedures/extension-methods.md). -If you must inherit from or , you can't use or the , , or classes to create instances of your custom task type. You can't use them because these classes create only and objects. In addition, you can't use the task continuation mechanisms that are provided by , , , and to create instances of your custom task type. You can't use them because these classes also create only and objects. +If you must inherit from or , you can't use or the , , or classes to create instances of your custom task type. You can't use them because these classes create only and objects. In addition, you can't use the task continuation mechanisms that are provided by , , , and to create instances of your custom task type. You can't use them because these classes also create only and objects. ## Related sections @@ -267,13 +267,13 @@ If you must inherit from or object.| |[Exception Handling](exception-handling-task-parallel-library.md)|Describes how exceptions on concurrent threads are handled.| -|[How to: Use Parallel.Invoke to Execute Parallel Operations](how-to-use-parallel-invoke-to-execute-parallel-operations.md)|Describes how to use .| +|[How to: Use Parallel.Invoke to Execute Parallel Operations](how-to-use-parallel-invoke-to-execute-parallel-operations.md)|Describes how to use .| |[How to: Return a Value from a Task](how-to-return-a-value-from-a-task.md)|Describes how to return values from tasks.| |[How to: Cancel a Task and Its Children](how-to-cancel-a-task-and-its-children.md)|Describes how to cancel tasks.| -|[How to: Create Pre-Computed Tasks](how-to-create-pre-computed-tasks.md)|Describes how to use the method to retrieve the results of asynchronous download operations that are held in a cache.| +|[How to: Create Pre-Computed Tasks](how-to-create-pre-computed-tasks.md)|Describes how to use the method to retrieve the results of asynchronous download operations that are held in a cache.| |[How to: Traverse a Binary Tree with Parallel Tasks](how-to-traverse-a-binary-tree-with-parallel-tasks.md)|Describes how to use tasks to traverse a binary tree.| -|[How to: Unwrap a Nested Task](how-to-unwrap-a-nested-task.md)|Demonstrates how to use the extension method.| -|[Data Parallelism](data-parallelism-task-parallel-library.md)|Describes how to use and to create parallel loops over data.| +|[How to: Unwrap a Nested Task](how-to-unwrap-a-nested-task.md)|Demonstrates how to use the extension method.| +|[Data Parallelism](data-parallelism-task-parallel-library.md)|Describes how to use and to create parallel loops over data.| |[Parallel Programming](index.md)|Top-level node for .NET Framework parallel programming.| ## See also diff --git a/docs/standard/parallel-programming/task-cancellation.md b/docs/standard/parallel-programming/task-cancellation.md index 7b5b019b69a03..09e260cb2cb2c 100644 --- a/docs/standard/parallel-programming/task-cancellation.md +++ b/docs/standard/parallel-programming/task-cancellation.md @@ -3,40 +3,40 @@ title: "Task Cancellation" description: Understand task cancellation, which is supported in the Task and Task classes through the use of cancellation tokens in .NET. ms.date: 10/20/2025 ms.custom: devdivchpfy22 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "tasks, cancellation" - "asynchronous task cancellation" ms.assetid: 3ecf1ea9-e399-4a6a-a0d6-8475f48dcb28 --- # Task cancellation -The and classes support cancellation by using cancellation tokens. For more information, see [Cancellation in Managed Threads](../threading/cancellation-in-managed-threads.md). In the Task classes, cancellation involves cooperation between the user delegate, which represents a cancelable operation, and the code that requested the cancellation. A successful cancellation involves the requesting code calling the method and the user delegate terminating the operation in a timely manner. You can terminate the operation by using one of these options: - -- By returning from the delegate. In many scenarios, this option is sufficient. However, a task instance that's canceled in this way transitions to the state, not to the state. - -- By throwing an and passing it the token on which cancellation was requested. The preferred way to perform is to use the method. A task that's canceled in this way transitions to the Canceled state, which the calling code can use to verify that the task responded to its cancellation request. - +The and classes support cancellation by using cancellation tokens. For more information, see [Cancellation in Managed Threads](../threading/cancellation-in-managed-threads.md). In the Task classes, cancellation involves cooperation between the user delegate, which represents a cancelable operation, and the code that requested the cancellation. A successful cancellation involves the requesting code calling the method and the user delegate terminating the operation in a timely manner. You can terminate the operation by using one of these options: + +- By returning from the delegate. In many scenarios, this option is sufficient. However, a task instance that's canceled in this way transitions to the state, not to the state. + +- By throwing an and passing it the token on which cancellation was requested. The preferred way to perform is to use the method. A task that's canceled in this way transitions to the Canceled state, which the calling code can use to verify that the task responded to its cancellation request. + The following example shows the basic pattern for task cancellation that throws the exception: >[!NOTE] -> The token is passed to the user delegate and the task instance. - +> The token is passed to the user delegate and the task instance. + [!code-csharp[TPL_Cancellation#02](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_cancellation/cs/snippet02.cs#02)] - [!code-vb[TPL_Cancellation#02](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_cancellation/vb/module1.vb#02)] - - For a complete example, see [How to: Cancel a Task and Its Children](how-to-cancel-a-task-and-its-children.md). - - When a task instance observes an thrown by the user code, it compares the exception's token to its associated token (the one that was passed to the API that created the Task). If the tokens are same and the token's property returns `true`, the task interprets this as acknowledging cancellation and transitions to the Canceled state. If you don't use a or method to wait for the task, then the task just sets its status to . - - If you're waiting on a Task that transitions to the Canceled state, a exception (wrapped in an exception) is thrown. This exception indicates successful cancellation instead of a faulty situation. Therefore, the task's property returns `null`. - - If the token's property returns `false` or if the exception's token doesn't match the Task's token, the is treated like a normal exception, causing the Task to transition to the Faulted state. The presence of other exceptions will also cause the Task to transition to the Faulted state. You can get the status of the completed task in the property. - - It's possible that a task might continue to process some items after cancellation is requested. - + [!code-vb[TPL_Cancellation#02](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_cancellation/vb/module1.vb#02)] + + For a complete example, see [How to: Cancel a Task and Its Children](how-to-cancel-a-task-and-its-children.md). + + When a task instance observes an thrown by the user code, it compares the exception's token to its associated token (the one that was passed to the API that created the Task). If the tokens are same and the token's property returns `true`, the task interprets this as acknowledging cancellation and transitions to the Canceled state. If you don't use a or method to wait for the task, then the task just sets its status to . + + If you're waiting on a Task that transitions to the Canceled state, a exception (wrapped in an exception) is thrown. This exception indicates successful cancellation instead of a faulty situation. Therefore, the task's property returns `null`. + + If the token's property returns `false` or if the exception's token doesn't match the Task's token, the is treated like a normal exception, causing the Task to transition to the Faulted state. The presence of other exceptions will also cause the Task to transition to the Faulted state. You can get the status of the completed task in the property. + + It's possible that a task might continue to process some items after cancellation is requested. + ## See also - [Cancellation in Managed Threads](../threading/cancellation-in-managed-threads.md) diff --git a/docs/standard/parallel-programming/task-parallel-library-tpl.md b/docs/standard/parallel-programming/task-parallel-library-tpl.md index fcf377955c499..1eb7dc6b258e8 100644 --- a/docs/standard/parallel-programming/task-parallel-library-tpl.md +++ b/docs/standard/parallel-programming/task-parallel-library-tpl.md @@ -3,7 +3,7 @@ title: "Task Parallel Library (TPL)" description: Explore the Task Parallel Library (TPL), a set of public types and APIs to simplify the process of adding parallelism & concurrency to applications in .NET. ms.date: "10/22/2025" ms.custom: devdivchpfy22 -helpviewer_keywords: +helpviewer_keywords: - ".NET, concurrency in" - ".NET, parallel programming in" - "Parallel Programming" @@ -14,19 +14,19 @@ ai-usage: ai-assisted The Task Parallel Library (TPL) is a set of public types and APIs in the and namespaces. The purpose of the TPL is to make developers more productive by simplifying the process of adding parallelism and concurrency to applications. The TPL dynamically scales the degree of concurrency to use all the available processors most efficiently. In addition, the TPL handles the partitioning of the work, the scheduling of threads on the , cancellation support, state management, and other low-level details. Using TPL, you can maximize the performance of your code while focusing on the work that your program is designed to accomplish. -In .NET Framework 4, the TPL is the preferred way to write multithreaded and parallel code. However, not all code is suitable for parallelization. For example, if a loop performs only a small amount of work on each iteration, or it doesn't run for many iterations, then the overhead of parallelization can cause the code to run more slowly. Furthermore, parallelization, like any multithreaded code, adds complexity to your program execution. Although the TPL simplifies multithreaded scenarios, we recommend that you have a basic understanding of threading concepts, for example, locks, deadlocks, and race conditions, so that you can use the TPL effectively. - -## Related articles - -|Title|Description| -|-|-| -|[Data Parallelism](data-parallelism-task-parallel-library.md)|Describes how to create parallel `for` and `foreach` loops (`For` and `For Each` in Visual Basic).| -|[Task-based Asynchronous Programming](task-based-asynchronous-programming.md)|Describes how to create and run tasks implicitly by using or explicitly by using objects directly.| +In .NET Framework 4, the TPL is the preferred way to write multithreaded and parallel code. However, not all code is suitable for parallelization. For example, if a loop performs only a small amount of work on each iteration, or it doesn't run for many iterations, then the overhead of parallelization can cause the code to run more slowly. Furthermore, parallelization, like any multithreaded code, adds complexity to your program execution. Although the TPL simplifies multithreaded scenarios, we recommend that you have a basic understanding of threading concepts, for example, locks, deadlocks, and race conditions, so that you can use the TPL effectively. + +## Related articles + +|Title|Description| +|-|-| +|[Data Parallelism](data-parallelism-task-parallel-library.md)|Describes how to create parallel `for` and `foreach` loops (`For` and `For Each` in Visual Basic).| +|[Task-based Asynchronous Programming](task-based-asynchronous-programming.md)|Describes how to create and run tasks implicitly by using or explicitly by using objects directly.| |[Dataflow](dataflow-task-parallel-library.md)|Describes how to use the dataflow components in the TPL Dataflow Library to handle multiple operations. These operations must communicate with one another and process data as it becomes available.| -|[Potential Pitfalls in Data and Task Parallelism](potential-pitfalls-in-data-and-task-parallelism.md)|Describes some common pitfalls and how to avoid them.| -|[Parallel LINQ (PLINQ)](introduction-to-plinq.md)|Describes how to achieve data parallelism with LINQ queries.| -|[Parallel Programming](index.md)|Top-level node for .NET parallel programming.| - +|[Potential Pitfalls in Data and Task Parallelism](potential-pitfalls-in-data-and-task-parallelism.md)|Describes some common pitfalls and how to avoid them.| +|[Parallel LINQ (PLINQ)](introduction-to-plinq.md)|Describes how to achieve data parallelism with LINQ queries.| +|[Parallel Programming](index.md)|Top-level node for .NET parallel programming.| + ## See also - [Samples for Parallel Programming with .NET](/samples/browse/?term=parallel&terms=parallel&products=dotnet) diff --git a/docs/standard/parallel-programming/tpl-and-traditional-async-programming.md b/docs/standard/parallel-programming/tpl-and-traditional-async-programming.md index c5ce5de631cdd..60ec59b31313a 100644 --- a/docs/standard/parallel-programming/tpl-and-traditional-async-programming.md +++ b/docs/standard/parallel-programming/tpl-and-traditional-async-programming.md @@ -2,125 +2,125 @@ description: "Learn more about: TPL and traditional .NET asynchronous programming" title: "TPL and Traditional .NET Asynchronous Programming" ms.date: 03/30/2017 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "tasks, with other asynchronous models" ms.assetid: e7b31170-a156-433f-9f26-b1fc7cd1776f --- # TPL and traditional .NET asynchronous programming -.NET provides the following two standard patterns for performing I/O-bound and compute-bound asynchronous operations: - -- Asynchronous Programming Model (APM), in which asynchronous operations are represented by a pair of begin/end methods. For example: and . - -- Event-based asynchronous pattern (EAP), in which asynchronous operations are represented by a method/event pair that are named `Async` and `Completed`. For example: and . - -The Task Parallel Library (TPL) can be used in various ways in conjunction with either of the asynchronous patterns. You can expose both APM and EAP operations as `Task` objects to library consumers, or you can expose the APM patterns but use `Task` objects to implement them internally. In both scenarios, by using `Task` objects, you can simplify the code and take advantage of the following useful functionality: - -- Register callbacks, in the form of task continuations, at any time after the task has started. - -- Coordinate multiple operations that execute in response to a `Begin_` method by using the and methods, or the and methods. - -- Encapsulate asynchronous I/O-bound and compute-bound operations in the same `Task` object. - -- Monitor the status of the `Task` object. - -- Marshal the status of an operation to a `Task` object by using . - -## Wrap APM operations in a Task - - Both the and classes provide several overloads of the and methods that let you encapsulate an APM begin/end method pair in one or instance. The various overloads accommodate any begin/end method pair that have from zero to three input parameters. - - For pairs that have `End` methods that return a value (a `Function` in Visual Basic), use the methods in that create a . For `End` methods that return void (a `Sub` in Visual Basic), use the methods in that create a . - - For those few cases in which the `Begin` method has more than three parameters or contains `ref` or `out` parameters, additional `FromAsync` overloads that encapsulate only the `End` method are provided. - - The following example shows the signature for the `FromAsync` overload that matches the and methods. - +.NET provides the following two standard patterns for performing I/O-bound and compute-bound asynchronous operations: + +- Asynchronous Programming Model (APM), in which asynchronous operations are represented by a pair of begin/end methods. For example: and . + +- Event-based asynchronous pattern (EAP), in which asynchronous operations are represented by a method/event pair that are named `Async` and `Completed`. For example: and . + +The Task Parallel Library (TPL) can be used in various ways in conjunction with either of the asynchronous patterns. You can expose both APM and EAP operations as `Task` objects to library consumers, or you can expose the APM patterns but use `Task` objects to implement them internally. In both scenarios, by using `Task` objects, you can simplify the code and take advantage of the following useful functionality: + +- Register callbacks, in the form of task continuations, at any time after the task has started. + +- Coordinate multiple operations that execute in response to a `Begin_` method by using the and methods, or the and methods. + +- Encapsulate asynchronous I/O-bound and compute-bound operations in the same `Task` object. + +- Monitor the status of the `Task` object. + +- Marshal the status of an operation to a `Task` object by using . + +## Wrap APM operations in a Task + + Both the and classes provide several overloads of the and methods that let you encapsulate an APM begin/end method pair in one or instance. The various overloads accommodate any begin/end method pair that have from zero to three input parameters. + + For pairs that have `End` methods that return a value (a `Function` in Visual Basic), use the methods in that create a . For `End` methods that return void (a `Sub` in Visual Basic), use the methods in that create a . + + For those few cases in which the `Begin` method has more than three parameters or contains `ref` or `out` parameters, additional `FromAsync` overloads that encapsulate only the `End` method are provided. + + The following example shows the signature for the `FromAsync` overload that matches the and methods. + [!code-csharp[FromAsync#01](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#01)] - [!code-vb[FromAsync#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#01)] - -This overload takes three input parameters, as follows. The first parameter is a delegate that matches the signature of the method. The second parameter is a delegate that takes an and returns a `TResult`. Because returns an integer, the compiler infers the type of `TResult` as and the type of the task as . The last four parameters are identical to those in the method: - -- The buffer in which to store the file data. - -- The offset in the buffer at which to begin writing data. - -- The maximum amount of data to read from the file. - -- An optional object that stores user-defined state data to pass to the callback. - + [!code-vb[FromAsync#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#01)] + +This overload takes three input parameters, as follows. The first parameter is a delegate that matches the signature of the method. The second parameter is a delegate that takes an and returns a `TResult`. Because returns an integer, the compiler infers the type of `TResult` as and the type of the task as . The last four parameters are identical to those in the method: + +- The buffer in which to store the file data. + +- The offset in the buffer at which to begin writing data. + +- The maximum amount of data to read from the file. + +- An optional object that stores user-defined state data to pass to the callback. + ### Use ContinueWith for the callback functionality - If you require access to the data in the file, as opposed to just the number of bytes, the method is not sufficient. Instead, use , whose `Result` property contains the file data. You can do this by adding a continuation to the original task. The continuation performs the work that would typically be performed by the delegate. It is invoked when the antecedent completes, and the data buffer has been filled. (The object should be closed before returning.) - - The following example shows how to return a that encapsulates the `BeginRead`/`EndRead` pair of the class. - + If you require access to the data in the file, as opposed to just the number of bytes, the method is not sufficient. Instead, use , whose `Result` property contains the file data. You can do this by adding a continuation to the original task. The continuation performs the work that would typically be performed by the delegate. It is invoked when the antecedent completes, and the data buffer has been filled. (The object should be closed before returning.) + + The following example shows how to return a that encapsulates the `BeginRead`/`EndRead` pair of the class. + [!code-csharp[FromAsync#03](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#03)] - [!code-vb[FromAsync#03](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#03)] - - The method can then be called, as follows. - + [!code-vb[FromAsync#03](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#03)] + + The method can then be called, as follows. + [!code-csharp[FromAsync#04](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#04)] - [!code-vb[FromAsync#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#04)] - + [!code-vb[FromAsync#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#04)] + ### Provide custom state data - In typical operations, if your delegate requires some custom state data, you have to pass it in through the last parameter in the `Begin` method, so that the data can be packaged into the object that is eventually passed to the callback method. This is typically not required when the `FromAsync` methods are used. If the custom data is known to the continuation, then it can be captured directly in the continuation delegate. The following example resembles the previous example, but instead of examining the `Result` property of the antecedent, the continuation examines the custom state data that is directly accessible to the user delegate of the continuation. - + In typical operations, if your delegate requires some custom state data, you have to pass it in through the last parameter in the `Begin` method, so that the data can be packaged into the object that is eventually passed to the callback method. This is typically not required when the `FromAsync` methods are used. If the custom data is known to the continuation, then it can be captured directly in the continuation delegate. The following example resembles the previous example, but instead of examining the `Result` property of the antecedent, the continuation examines the custom state data that is directly accessible to the user delegate of the continuation. + [!code-csharp[FromAsync#05](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#05)] - [!code-vb[FromAsync#05](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#05)] - + [!code-vb[FromAsync#05](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#05)] + ### Synchronize multiple FromAsync tasks - The static and methods provide added flexibility when used in conjunction with the `FromAsync` methods. The following example shows how to initiate multiple asynchronous I/O operations, and then wait for all of them to complete before you execute the continuation. - + The static and methods provide added flexibility when used in conjunction with the `FromAsync` methods. The following example shows how to initiate multiple asynchronous I/O operations, and then wait for all of them to complete before you execute the continuation. + [!code-csharp[FromAsync#06](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#06)] - [!code-vb[FromAsync#06](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#06)] - + [!code-vb[FromAsync#06](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#06)] + ### FromAsync tasks for only the End method - For those few cases in which the `Begin` method requires more than three input parameters or has `ref` or `out` parameters, you can use the `FromAsync` overloads, for example, , that represent only the `End` method. These methods can also be used in any scenario in which you're passed an and want to encapsulate it in a Task. - + For those few cases in which the `Begin` method requires more than three input parameters or has `ref` or `out` parameters, you can use the `FromAsync` overloads, for example, , that represent only the `End` method. These methods can also be used in any scenario in which you're passed an and want to encapsulate it in a Task. + [!code-csharp[FromAsync#07](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#07)] - [!code-vb[FromAsync#07](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#07)] - + [!code-vb[FromAsync#07](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#07)] + ### Start and cancel FromAsync tasks - The task returned by a `FromAsync` method has a status of `WaitingForActivation` and will be started by the system at some point after the task is created. If you attempt to call Start on such a task, an exception will be raised. - - You cannot cancel a `FromAsync` task, because the underlying .NET APIs currently do not support in-progress cancellation of file or network I/O. You can add cancellation functionality to a method that encapsulates a `FromAsync` call, but you can only respond to the cancellation before `FromAsync` is called or after it completed (for example, in a continuation task). - - Some classes that support EAP, for example, , do support cancellation, and you can integrate that native cancellation functionality by using cancellation tokens. - + The task returned by a `FromAsync` method has a status of `WaitingForActivation` and will be started by the system at some point after the task is created. If you attempt to call Start on such a task, an exception will be raised. + + You cannot cancel a `FromAsync` task, because the underlying .NET APIs currently do not support in-progress cancellation of file or network I/O. You can add cancellation functionality to a method that encapsulates a `FromAsync` call, but you can only respond to the cancellation before `FromAsync` is called or after it completed (for example, in a continuation task). + + Some classes that support EAP, for example, , do support cancellation, and you can integrate that native cancellation functionality by using cancellation tokens. + ## Expose complex EAP operations As tasks - The TPL does not provide any methods that are specifically designed to encapsulate an event-based asynchronous operation in the same way that the `FromAsync` family of methods wrap the pattern. However, the TPL does provide the class, which can be used to represent any arbitrary set of operations as a . The operations may be synchronous or asynchronous, and may be I/O bound or compute-bound, or both. - - The following example shows how to use a to expose a set of asynchronous operations to client code as a basic . The method lets you enter an array of Web URLs, and a term or name to search for, and then returns the number of times the search term occurs on each site. - + The TPL does not provide any methods that are specifically designed to encapsulate an event-based asynchronous operation in the same way that the `FromAsync` family of methods wrap the pattern. However, the TPL does provide the class, which can be used to represent any arbitrary set of operations as a . The operations may be synchronous or asynchronous, and may be I/O bound or compute-bound, or both. + + The following example shows how to use a to expose a set of asynchronous operations to client code as a basic . The method lets you enter an array of Web URLs, and a term or name to search for, and then returns the number of times the search term occurs on each site. + [!code-csharp[FromAsync#10](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/snippet10.cs#10)] - [!code-vb[FromAsync#10](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/snippet10.vb#10)] - - For a more complete example, which includes additional exception handling and shows how to call the method from client code, see [How to: Wrap EAP Patterns in a Task](how-to-wrap-eap-patterns-in-a-task.md). - - Remember that any task that's created by a will be started by that `TaskCompletionSource` and, therefore, user code should not call the `Start` method on that task. - + [!code-vb[FromAsync#10](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/snippet10.vb#10)] + + For a more complete example, which includes additional exception handling and shows how to call the method from client code, see [How to: Wrap EAP Patterns in a Task](how-to-wrap-eap-patterns-in-a-task.md). + + Remember that any task that's created by a will be started by that `TaskCompletionSource` and, therefore, user code should not call the `Start` method on that task. + ## Implement the APM pattern by using tasks - In some scenarios, it may be desirable to directly expose the pattern by using begin/end method pairs in an API. For example, you may want to maintain consistency with existing APIs, or you may have automated tools that require this pattern. In such cases, you can use `Task` objects to simplify how the APM pattern is implemented internally. - - The following example shows how to use tasks to implement an APM begin/end method pair for a long-running compute-bound method. - + In some scenarios, it may be desirable to directly expose the pattern by using begin/end method pairs in an API. For example, you may want to maintain consistency with existing APIs, or you may have automated tools that require this pattern. In such cases, you can use `Task` objects to simplify how the APM pattern is implemented internally. + + The following example shows how to use tasks to implement an APM begin/end method pair for a long-running compute-bound method. + [!code-csharp[FromAsync#09](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#09)] - [!code-vb[FromAsync#09](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#09)] - + [!code-vb[FromAsync#09](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#09)] + ## Use the StreamExtensions sample code The *StreamExtensions.cs* file, in the [.NET Standard parallel extensions extras](/samples/dotnet/samples/parallel-programming-extensions-extras-cs/) repository, contains several reference implementations that use `Task` objects for asynchronous file and network I/O. - + ## See also - [Task Parallel Library (TPL)](task-parallel-library-tpl.md) diff --git a/docs/standard/parallel-programming/understanding-speedup-in-plinq.md b/docs/standard/parallel-programming/understanding-speedup-in-plinq.md index 3cf3ed68abc6e..c9484b6ca5626 100644 --- a/docs/standard/parallel-programming/understanding-speedup-in-plinq.md +++ b/docs/standard/parallel-programming/understanding-speedup-in-plinq.md @@ -2,10 +2,10 @@ description: "Learn more about: Understanding Speedup in PLINQ" title: "Understanding Speedup in PLINQ" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "PLINQ queries, performance tuning" ms.assetid: 53706c7e-397d-467a-98cd-c0d1fd63ba5e --- @@ -14,73 +14,73 @@ ms.assetid: 53706c7e-397d-467a-98cd-c0d1fd63ba5e This article provides information that will help you write PLINQ queries that are as efficient as possible while still yielding correct results. The primary purpose of PLINQ is to speed up the execution of LINQ to Objects queries by executing the query delegates in parallel on multi-core computers. PLINQ performs best when the processing of each element in a source collection is independent, with no shared state involved among the individual delegates. Such operations are common in LINQ to Objects and PLINQ, and are often called "*delightfully parallel*" because they lend themselves easily to scheduling on multiple threads. However, not all queries consist entirely of delightfully parallel operations. In most cases, a query involves some operators that either cannot be parallelized, or that slow down parallel execution. And even with queries that are entirely delightfully parallel, PLINQ must still partition the data source and schedule the work on the threads, and usually merge the results when the query completes. All these operations add to the computational cost of parallelization; these costs of adding parallelization are called *overhead*. To achieve optimum performance in a PLINQ query, the goal is to maximize the parts that are delightfully parallel and minimize the parts that require overhead. - -## Factors that Impact PLINQ Query Performance - - The following sections lists some of the most important factors that impact parallel query performance. These are general statements that by themselves are not sufficient to predict query performance in all cases. As always, it's important to measure actual performance of specific queries on computers with a range of representative configurations and loads. - -1. Computational cost of the overall work. - - To achieve speedup, a PLINQ query must have enough delightfully parallel work to offset the overhead. The work can be expressed as the computational cost of each delegate multiplied by the number of elements in the source collection. Assuming that an operation can be parallelized, the more computationally expensive it is, the greater the opportunity for speedup. For example, if a function takes one millisecond to execute, a sequential query over 1000 elements will take one second to perform that operation, whereas a parallel query on a computer with four cores might take only 250 milliseconds. This yields a speedup of 750 milliseconds. If the function required one second to execute for each element, then the speedup would be 750 seconds. If the delegate is very expensive, then PLINQ might offer significant speedup with only a few items in the source collection. Conversely, small source collections with trivial delegates are generally not good candidates for PLINQ. - - In the following example, queryA is probably a good candidate for PLINQ, assuming that its Select function involves a lot of work. queryB is probably not a good candidate because there is not enough work in the Select statement, and the overhead of parallelization will offset most or all of the speedup. - - ```vb - Dim queryA = From num In numberList.AsParallel() - Select ExpensiveFunction(num); 'good for PLINQ - - Dim queryB = From num In numberList.AsParallel() - Where num Mod 2 > 0 - Select num; 'not as good for PLINQ - ``` - - ```csharp - var queryA = from num in numberList.AsParallel() - select ExpensiveFunction(num); //good for PLINQ - - var queryB = from num in numberList.AsParallel() - where num % 2 > 0 - select num; //not as good for PLINQ - ``` - -2. The number of logical cores on the system (degree of parallelism). - - This point is an obvious corollary to the previous section, queries that are delightfully parallel run faster on machines with more cores because the work can be divided among more concurrent threads. The overall amount of speedup depends on what percentage of the overall work of the query is parallelizable. However, do not assume that all queries will run twice as fast on an eight core computer as a four core computer. When tuning queries for optimal performance, it is important to measure actual results on computers with various numbers of cores. This point is related to point #1: larger datasets are required to take advantage of greater computing resources. - -3. The number and kind of operations. - - PLINQ provides the AsOrdered operator for situations in which it is necessary to maintain the order of elements in the source sequence. There is a cost associated with ordering, but this cost is usually modest. GroupBy and Join operations likewise incur overhead. PLINQ performs best when it is allowed to process elements in the source collection in any order, and pass them to the next operator as soon as they are ready. For more information, see [Order Preservation in PLINQ](order-preservation-in-plinq.md). - -4. The form of query execution. - - If you are storing the results of a query by calling ToArray or ToList, then the results from all parallel threads must be merged into the single data structure. This involves an unavoidable computational cost. Likewise, if you iterate the results by using a foreach (For Each in Visual Basic) loop, the results from the worker threads need to be serialized onto the enumerator thread. But if you just want to perform some action based on the result from each thread, you can use the ForAll method to perform this work on multiple threads. - -5. The type of merge options. - - PLINQ can be configured to either buffer its output, and produce it in chunks or all at once after the entire result set is produced, or else to stream individual results as they are produced. The former results in decreased overall execution time and the latter results in decreased latency between yielded elements. While the merge options do not always have a major impact on overall query performance, they can impact perceived performance because they control how long a user must wait to see results. For more information, see [Merge Options in PLINQ](merge-options-in-plinq.md). - -6. The kind of partitioning. - - In some cases, a PLINQ query over an indexable source collection may result in an unbalanced work load. When this occurs, you might be able to increase the query performance by creating a custom partitioner. For more information, see [Custom Partitioners for PLINQ and TPL](custom-partitioners-for-plinq-and-tpl.md). - -## When PLINQ Chooses Sequential Mode - - PLINQ will always attempt to execute a query at least as fast as the query would run sequentially. Although PLINQ does not look at how computationally expensive the user delegates are, or how big the input source is, it does look for certain query "shapes." Specifically, it looks for query operators or combinations of operators that typically cause a query to execute more slowly in parallel mode. When it finds such shapes, PLINQ by default falls back to sequential mode. - - However, after measuring a specific query's performance, you may determine that it actually runs faster in parallel mode. In such cases you can use the flag via the method to instruct PLINQ to parallelize the query. For more information, see [How to: Specify the Execution Mode in PLINQ](how-to-specify-the-execution-mode-in-plinq.md). - - The following list describes the query shapes that PLINQ by default will execute in sequential mode: - -- Queries that contain a Select, indexed Where, indexed SelectMany, or ElementAt clause after an ordering or filtering operator that has removed or rearranged original indices. - -- Queries that contain a Take, TakeWhile, Skip, SkipWhile operator and where indices in the source sequence are not in the original order. - -- Queries that contain Zip or SequenceEquals, unless one of the data sources has an originally ordered index and the other data source is indexable (i.e. an array or IList(T)). - -- Queries that contain Concat, unless it is applied to indexable data sources. - -- Queries that contain Reverse, unless applied to an indexable data source. - + +## Factors that Impact PLINQ Query Performance + + The following sections lists some of the most important factors that impact parallel query performance. These are general statements that by themselves are not sufficient to predict query performance in all cases. As always, it's important to measure actual performance of specific queries on computers with a range of representative configurations and loads. + +1. Computational cost of the overall work. + + To achieve speedup, a PLINQ query must have enough delightfully parallel work to offset the overhead. The work can be expressed as the computational cost of each delegate multiplied by the number of elements in the source collection. Assuming that an operation can be parallelized, the more computationally expensive it is, the greater the opportunity for speedup. For example, if a function takes one millisecond to execute, a sequential query over 1000 elements will take one second to perform that operation, whereas a parallel query on a computer with four cores might take only 250 milliseconds. This yields a speedup of 750 milliseconds. If the function required one second to execute for each element, then the speedup would be 750 seconds. If the delegate is very expensive, then PLINQ might offer significant speedup with only a few items in the source collection. Conversely, small source collections with trivial delegates are generally not good candidates for PLINQ. + + In the following example, queryA is probably a good candidate for PLINQ, assuming that its Select function involves a lot of work. queryB is probably not a good candidate because there is not enough work in the Select statement, and the overhead of parallelization will offset most or all of the speedup. + + ```vb + Dim queryA = From num In numberList.AsParallel() + Select ExpensiveFunction(num); 'good for PLINQ + + Dim queryB = From num In numberList.AsParallel() + Where num Mod 2 > 0 + Select num; 'not as good for PLINQ + ``` + + ```csharp + var queryA = from num in numberList.AsParallel() + select ExpensiveFunction(num); //good for PLINQ + + var queryB = from num in numberList.AsParallel() + where num % 2 > 0 + select num; //not as good for PLINQ + ``` + +2. The number of logical cores on the system (degree of parallelism). + + This point is an obvious corollary to the previous section, queries that are delightfully parallel run faster on machines with more cores because the work can be divided among more concurrent threads. The overall amount of speedup depends on what percentage of the overall work of the query is parallelizable. However, do not assume that all queries will run twice as fast on an eight core computer as a four core computer. When tuning queries for optimal performance, it is important to measure actual results on computers with various numbers of cores. This point is related to point #1: larger datasets are required to take advantage of greater computing resources. + +3. The number and kind of operations. + + PLINQ provides the AsOrdered operator for situations in which it is necessary to maintain the order of elements in the source sequence. There is a cost associated with ordering, but this cost is usually modest. GroupBy and Join operations likewise incur overhead. PLINQ performs best when it is allowed to process elements in the source collection in any order, and pass them to the next operator as soon as they are ready. For more information, see [Order Preservation in PLINQ](order-preservation-in-plinq.md). + +4. The form of query execution. + + If you are storing the results of a query by calling ToArray or ToList, then the results from all parallel threads must be merged into the single data structure. This involves an unavoidable computational cost. Likewise, if you iterate the results by using a foreach (For Each in Visual Basic) loop, the results from the worker threads need to be serialized onto the enumerator thread. But if you just want to perform some action based on the result from each thread, you can use the ForAll method to perform this work on multiple threads. + +5. The type of merge options. + + PLINQ can be configured to either buffer its output, and produce it in chunks or all at once after the entire result set is produced, or else to stream individual results as they are produced. The former results in decreased overall execution time and the latter results in decreased latency between yielded elements. While the merge options do not always have a major impact on overall query performance, they can impact perceived performance because they control how long a user must wait to see results. For more information, see [Merge Options in PLINQ](merge-options-in-plinq.md). + +6. The kind of partitioning. + + In some cases, a PLINQ query over an indexable source collection may result in an unbalanced work load. When this occurs, you might be able to increase the query performance by creating a custom partitioner. For more information, see [Custom Partitioners for PLINQ and TPL](custom-partitioners-for-plinq-and-tpl.md). + +## When PLINQ Chooses Sequential Mode + + PLINQ will always attempt to execute a query at least as fast as the query would run sequentially. Although PLINQ does not look at how computationally expensive the user delegates are, or how big the input source is, it does look for certain query "shapes." Specifically, it looks for query operators or combinations of operators that typically cause a query to execute more slowly in parallel mode. When it finds such shapes, PLINQ by default falls back to sequential mode. + + However, after measuring a specific query's performance, you may determine that it actually runs faster in parallel mode. In such cases you can use the flag via the method to instruct PLINQ to parallelize the query. For more information, see [How to: Specify the Execution Mode in PLINQ](how-to-specify-the-execution-mode-in-plinq.md). + + The following list describes the query shapes that PLINQ by default will execute in sequential mode: + +- Queries that contain a Select, indexed Where, indexed SelectMany, or ElementAt clause after an ordering or filtering operator that has removed or rearranged original indices. + +- Queries that contain a Take, TakeWhile, Skip, SkipWhile operator and where indices in the source sequence are not in the original order. + +- Queries that contain Zip or SequenceEquals, unless one of the data sources has an originally ordered index and the other data source is indexable (i.e. an array or IList(T)). + +- Queries that contain Concat, unless it is applied to indexable data sources. + +- Queries that contain Reverse, unless applied to an indexable data source. + ## See also - [Parallel LINQ (PLINQ)](introduction-to-plinq.md) diff --git a/docs/standard/parallel-programming/walkthrough-creating-a-custom-dataflow-block-type.md b/docs/standard/parallel-programming/walkthrough-creating-a-custom-dataflow-block-type.md index 429339fac56fd..6dcc03fcd473f 100644 --- a/docs/standard/parallel-programming/walkthrough-creating-a-custom-dataflow-block-type.md +++ b/docs/standard/parallel-programming/walkthrough-creating-a-custom-dataflow-block-type.md @@ -2,10 +2,10 @@ description: "Learn more about: Walkthrough: Creating a Custom Dataflow Block Type" title: "Walkthrough: Creating a Custom Dataflow Block Type" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "Task Parallel Library, dataflows" - "TPL dataflow library, creating custom dataflow blocks" - "dataflow blocks, creating custom in TPL" @@ -13,43 +13,43 @@ ms.topic: tutorial --- # Walkthrough: Creating a Custom Dataflow Block Type -Although the TPL Dataflow Library provides several dataflow block types that enable a variety of functionality, you can also create custom block types. This document describes how to create a dataflow block type that implements custom behavior. - -## Prerequisites +Although the TPL Dataflow Library provides several dataflow block types that enable a variety of functionality, you can also create custom block types. This document describes how to create a dataflow block type that implements custom behavior. - Read [Dataflow](dataflow-task-parallel-library.md) before you read this document. +## Prerequisites + + Read [Dataflow](dataflow-task-parallel-library.md) before you read this document. [!INCLUDE [tpl-install-instructions](../../../includes/tpl-install-instructions.md)] - -## Defining the Sliding Window Dataflow Block - Consider a dataflow application that requires that input values be buffered and then output in a sliding window manner. For example, for the input values {0, 1, 2, 3, 4, 5} and a window size of three, a sliding window dataflow block produces the output arrays {0, 1, 2}, {1, 2, 3}, {2, 3, 4}, and {3, 4, 5}. The following sections describe two ways to create a dataflow block type that implements this custom behavior. The first technique uses the method to combine the functionality of an object and an object into one propagator block. The second technique defines a class that derives from and combines existing functionality to perform custom behavior. - -## Using the Encapsulate Method to Define the Sliding Window Dataflow Block +## Defining the Sliding Window Dataflow Block + + Consider a dataflow application that requires that input values be buffered and then output in a sliding window manner. For example, for the input values {0, 1, 2, 3, 4, 5} and a window size of three, a sliding window dataflow block produces the output arrays {0, 1, 2}, {1, 2, 3}, {2, 3, 4}, and {3, 4, 5}. The following sections describe two ways to create a dataflow block type that implements this custom behavior. The first technique uses the method to combine the functionality of an object and an object into one propagator block. The second technique defines a class that derives from and combines existing functionality to perform custom behavior. + +## Using the Encapsulate Method to Define the Sliding Window Dataflow Block + + The following example uses the method to create a propagator block from a target and a source. A propagator block enables a source block and a target block to act as a receiver and sender of data. + + This technique is useful when you require custom dataflow functionality, but you do not require a type that provides additional methods, properties, or fields. - The following example uses the method to create a propagator block from a target and a source. A propagator block enables a source block and a target block to act as a receiver and sender of data. - - This technique is useful when you require custom dataflow functionality, but you do not require a type that provides additional methods, properties, or fields. - [!code-csharp[TPLDataflow_SlidingWindowBlock#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_slidingwindowblock/cs/slidingwindowblock.cs#1)] - [!code-vb[TPLDataflow_SlidingWindowBlock#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_slidingwindowblock/vb/slidingwindowblock.vb#1)] - -## Deriving from IPropagatorBlock to Define the Sliding Window Dataflow Block - - The following example shows the `SlidingWindowBlock` class. This class derives from so that it can act as both a source and a target of data. As in the previous example, the `SlidingWindowBlock` class is built on existing dataflow block types. However, the `SlidingWindowBlock` class also implements the methods that are required by the , , and interfaces. These methods all forward work to the predefined dataflow block type members. For example, the `Post` method defers work to the `m_target` data member, which is also an object. - - This technique is useful when you require custom dataflow functionality, and also require a type that provides additional methods, properties, or fields. For example, the `SlidingWindowBlock` class also derives from so that it can provide the and methods. The `SlidingWindowBlock` class also demonstrates extensibility by providing the `WindowSize` property, which retrieves the number of elements in the sliding window. - + [!code-vb[TPLDataflow_SlidingWindowBlock#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_slidingwindowblock/vb/slidingwindowblock.vb#1)] + +## Deriving from IPropagatorBlock to Define the Sliding Window Dataflow Block + + The following example shows the `SlidingWindowBlock` class. This class derives from so that it can act as both a source and a target of data. As in the previous example, the `SlidingWindowBlock` class is built on existing dataflow block types. However, the `SlidingWindowBlock` class also implements the methods that are required by the , , and interfaces. These methods all forward work to the predefined dataflow block type members. For example, the `Post` method defers work to the `m_target` data member, which is also an object. + + This technique is useful when you require custom dataflow functionality, and also require a type that provides additional methods, properties, or fields. For example, the `SlidingWindowBlock` class also derives from so that it can provide the and methods. The `SlidingWindowBlock` class also demonstrates extensibility by providing the `WindowSize` property, which retrieves the number of elements in the sliding window. + [!code-csharp[TPLDataflow_SlidingWindowBlock#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_slidingwindowblock/cs/slidingwindowblock.cs#2)] - [!code-vb[TPLDataflow_SlidingWindowBlock#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_slidingwindowblock/vb/slidingwindowblock.vb#2)] - -## The Complete Example + [!code-vb[TPLDataflow_SlidingWindowBlock#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_slidingwindowblock/vb/slidingwindowblock.vb#2)] + +## The Complete Example + + The following example shows the complete code for this walkthrough. It also demonstrates how to use the both sliding window blocks in a method that writes to the block, reads from it, and prints the results to the console. - The following example shows the complete code for this walkthrough. It also demonstrates how to use the both sliding window blocks in a method that writes to the block, reads from it, and prints the results to the console. - [!code-csharp[TPLDataflow_SlidingWindowBlock#100](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_slidingwindowblock/cs/slidingwindowblock.cs#100)] - [!code-vb[TPLDataflow_SlidingWindowBlock#100](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_slidingwindowblock/vb/slidingwindowblock.vb#100)] - + [!code-vb[TPLDataflow_SlidingWindowBlock#100](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_slidingwindowblock/vb/slidingwindowblock.vb#100)] + ## See also - [Dataflow](dataflow-task-parallel-library.md) diff --git a/docs/standard/parallel-programming/walkthrough-creating-a-dataflow-pipeline.md b/docs/standard/parallel-programming/walkthrough-creating-a-dataflow-pipeline.md index e24a3e2ac13dc..9c2c6461d02e8 100644 --- a/docs/standard/parallel-programming/walkthrough-creating-a-dataflow-pipeline.md +++ b/docs/standard/parallel-programming/walkthrough-creating-a-dataflow-pipeline.md @@ -2,10 +2,10 @@ title: "Walkthrough: Creating a Dataflow Pipeline" description: Create a dataflow pipeline, which is a series of components, or dataflow blocks. A dataflow block does a certain task to contribute to a larger goal. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "dataflow pipelines, creating with TPL" - "Task Parallel Library, dataflows" - "TPL dataflow library, creating dataflow pipeline" @@ -13,105 +13,105 @@ ms.topic: tutorial --- # Walkthrough: Creating a Dataflow Pipeline -Although you can use the , , and methods to receive messages from source blocks, you can also connect message blocks to form a *dataflow pipeline*. A dataflow pipeline is a series of components, or *dataflow blocks*, each of which performs a specific task that contributes to a larger goal. Every dataflow block in a dataflow pipeline performs work when it receives a message from another dataflow block. An analogy to this is an assembly line for automobile manufacturing. As each vehicle passes through the assembly line, one station assembles the frame, the next one installs the engine, and so on. Because an assembly line enables multiple vehicles to be assembled at the same time, it provides better throughput than assembling complete vehicles one at a time. - - This document demonstrates a dataflow pipeline that downloads the book *The Iliad of Homer* from a website and searches the text to match individual words with words that reverse the first word's characters. The formation of the dataflow pipeline in this document consists of the following steps: - -1. Create the dataflow blocks that participate in the pipeline. - -2. Connect each dataflow block to the next block in the pipeline. Each block receives as input the output of the previous block in the pipeline. - -3. For each dataflow block, create a continuation task that sets the next block to the completed state after the previous block finishes. - -4. Post data to the head of the pipeline. - -5. Mark the head of the pipeline as completed. - -6. Wait for the pipeline to complete all work. - -## Prerequisites - - Read [Dataflow](dataflow-task-parallel-library.md) before you start this walkthrough. - -## Creating a Console Application +Although you can use the , , and methods to receive messages from source blocks, you can also connect message blocks to form a *dataflow pipeline*. A dataflow pipeline is a series of components, or *dataflow blocks*, each of which performs a specific task that contributes to a larger goal. Every dataflow block in a dataflow pipeline performs work when it receives a message from another dataflow block. An analogy to this is an assembly line for automobile manufacturing. As each vehicle passes through the assembly line, one station assembles the frame, the next one installs the engine, and so on. Because an assembly line enables multiple vehicles to be assembled at the same time, it provides better throughput than assembling complete vehicles one at a time. + + This document demonstrates a dataflow pipeline that downloads the book *The Iliad of Homer* from a website and searches the text to match individual words with words that reverse the first word's characters. The formation of the dataflow pipeline in this document consists of the following steps: + +1. Create the dataflow blocks that participate in the pipeline. + +2. Connect each dataflow block to the next block in the pipeline. Each block receives as input the output of the previous block in the pipeline. + +3. For each dataflow block, create a continuation task that sets the next block to the completed state after the previous block finishes. + +4. Post data to the head of the pipeline. + +5. Mark the head of the pipeline as completed. + +6. Wait for the pipeline to complete all work. + +## Prerequisites + + Read [Dataflow](dataflow-task-parallel-library.md) before you start this walkthrough. + +## Creating a Console Application In Visual Studio, create a Visual C# or Visual Basic Console Application project. Install the System.Threading.Tasks.Dataflow NuGet package. [!INCLUDE [tpl-install-instructions](../../../includes/tpl-install-instructions.md)] - Add the following code to your project to create the basic application. - + Add the following code to your project to create the basic application. + [!code-csharp[TPLDataflow_Palindromes#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_palindromes/cs/dataflowpalindromes.cs#2)] - [!code-vb[TPLDataflow_Palindromes#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromesemptymain.vb#2)] - -## Creating the Dataflow Blocks + [!code-vb[TPLDataflow_Palindromes#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromesemptymain.vb#2)] + +## Creating the Dataflow Blocks + + Add the following code to the `Main` method to create the dataflow blocks that participate in the pipeline. The table that follows summarizes the role of each member of the pipeline. - Add the following code to the `Main` method to create the dataflow blocks that participate in the pipeline. The table that follows summarizes the role of each member of the pipeline. - [!code-csharp[TPLDataflow_Palindromes#3](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_palindromes/cs/dataflowpalindromes.cs#3)] - [!code-vb[TPLDataflow_Palindromes#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromes.vb#3)] - -|Member|Type|Description| -|------------|----------|-----------------| -|`downloadString`||Downloads the book text from the Web.| -|`createWordList`||Separates the book text into an array of words.| -|`filterWordList`||Removes short words and duplicates from the word array.| -|`findReversedWords`||Finds all words in the filtered word array collection whose reverse also occurs in the word array.| -|`printReversedWords`||Displays words and the corresponding reverse words to the console.| - - Although you could combine multiple steps in the dataflow pipeline in this example into one step, the example illustrates the concept of composing multiple independent dataflow tasks to perform a larger task. The example uses to enable each member of the pipeline to perform an operation on its input data and send the results to the next step in the pipeline. The `findReversedWords` member of the pipeline is a object because it produces multiple independent outputs for each input. The tail of the pipeline, `printReversedWords`, is an object because it performs an action on its input, and does not produce a result. - -## Forming the Pipeline - - Add the following code to connect each block to the next block in the pipeline. - - When you call the method to connect a source dataflow block to a target dataflow block, the source dataflow block propagates data to the target block as data becomes available. If you also provide with set to true, successful or unsuccessful completion of one block in the pipeline will cause completion of the next block in the pipeline. - + [!code-vb[TPLDataflow_Palindromes#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromes.vb#3)] + +|Member|Type|Description| +|------------|----------|-----------------| +|`downloadString`||Downloads the book text from the Web.| +|`createWordList`||Separates the book text into an array of words.| +|`filterWordList`||Removes short words and duplicates from the word array.| +|`findReversedWords`||Finds all words in the filtered word array collection whose reverse also occurs in the word array.| +|`printReversedWords`||Displays words and the corresponding reverse words to the console.| + + Although you could combine multiple steps in the dataflow pipeline in this example into one step, the example illustrates the concept of composing multiple independent dataflow tasks to perform a larger task. The example uses to enable each member of the pipeline to perform an operation on its input data and send the results to the next step in the pipeline. The `findReversedWords` member of the pipeline is a object because it produces multiple independent outputs for each input. The tail of the pipeline, `printReversedWords`, is an object because it performs an action on its input, and does not produce a result. + +## Forming the Pipeline + + Add the following code to connect each block to the next block in the pipeline. + + When you call the method to connect a source dataflow block to a target dataflow block, the source dataflow block propagates data to the target block as data becomes available. If you also provide with set to true, successful or unsuccessful completion of one block in the pipeline will cause completion of the next block in the pipeline. + [!code-csharp[TPLDataflow_Palindromes#4](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_palindromes/cs/dataflowpalindromes.cs#4)] - [!code-vb[TPLDataflow_Palindromes#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromes.vb#4)] - -## Posting Data to the Pipeline + [!code-vb[TPLDataflow_Palindromes#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromes.vb#4)] + +## Posting Data to the Pipeline + + Add the following code to post the URL of the book *The Iliad of Homer* to the head of the dataflow pipeline. - Add the following code to post the URL of the book *The Iliad of Homer* to the head of the dataflow pipeline. - [!code-csharp[TPLDataflow_Palindromes#6](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_palindromes/cs/dataflowpalindromes.cs#6)] - [!code-vb[TPLDataflow_Palindromes#6](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromes.vb#6)] - - This example uses to synchronously send data to the head of the pipeline. Use the method when you must asynchronously send data to a dataflow node. - -## Completing Pipeline Activity + [!code-vb[TPLDataflow_Palindromes#6](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromes.vb#6)] + + This example uses to synchronously send data to the head of the pipeline. Use the method when you must asynchronously send data to a dataflow node. + +## Completing Pipeline Activity Add the following code to mark the head of the pipeline as completed. The head of the pipeline propagates its completion after it processes all buffered messages. - + [!code-csharp[TPLDataflow_Palindromes#7](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_palindromes/cs/dataflowpalindromes.cs#7)] - [!code-vb[TPLDataflow_Palindromes#7](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromes.vb#7)] - - This example sends one URL through the dataflow pipeline to be processed. If you send more than one input through a pipeline, call the method after you submit all the input. You can omit this step if your application has no well-defined point at which data is no longer available or the application does not have to wait for the pipeline to finish. - -## Waiting for the Pipeline to Finish - - Add the following code to wait for the pipeline to finish. The overall operation is finished when the tail of the pipeline finishes. - + [!code-vb[TPLDataflow_Palindromes#7](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromes.vb#7)] + + This example sends one URL through the dataflow pipeline to be processed. If you send more than one input through a pipeline, call the method after you submit all the input. You can omit this step if your application has no well-defined point at which data is no longer available or the application does not have to wait for the pipeline to finish. + +## Waiting for the Pipeline to Finish + + Add the following code to wait for the pipeline to finish. The overall operation is finished when the tail of the pipeline finishes. + [!code-csharp[TPLDataflow_Palindromes#8](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_palindromes/cs/dataflowpalindromes.cs#8)] - [!code-vb[TPLDataflow_Palindromes#8](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromes.vb#8)] - - You can wait for dataflow completion from any thread or from multiple threads at the same time. - -## The Complete Example - - The following example shows the complete code for this walkthrough. - + [!code-vb[TPLDataflow_Palindromes#8](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromes.vb#8)] + + You can wait for dataflow completion from any thread or from multiple threads at the same time. + +## The Complete Example + + The following example shows the complete code for this walkthrough. + [!code-csharp[TPLDataflow_Palindromes#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_palindromes/cs/dataflowpalindromes.cs#1)] - [!code-vb[TPLDataflow_Palindromes#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromes.vb#1)] - -## Next Steps - - This example sends one URL to process through the dataflow pipeline. If you send more than one input value through a pipeline, you can introduce a form of parallelism into your application that resembles how parts might move through an automobile factory. When the first member of the pipeline sends its result to the second member, it can process another item in parallel as the second member processes the first result. - - The parallelism that is achieved by using dataflow pipelines is known as *coarse-grained parallelism* because it typically consists of fewer, larger tasks. You can also use a more *fine-grained parallelism* of smaller, short-running tasks in a dataflow pipeline. In this example, the `findReversedWords` member of the pipeline uses [PLINQ](introduction-to-plinq.md) to process multiple items in the work list in parallel. The use of fine-grained parallelism in a coarse-grained pipeline can improve overall throughput. - - You can also connect a source dataflow block to multiple target blocks to create a *dataflow network*. The overloaded version of the method takes a object that defines whether the target block accepts each message based on its value. Most dataflow block types that act as sources offer messages to all connected target blocks, in the order in which they were connected, until one of the blocks accepts that message. By using this filtering mechanism, you can create systems of connected dataflow blocks that direct certain data through one path and other data through another path. For an example that uses filtering to create a dataflow network, see [Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md). - + [!code-vb[TPLDataflow_Palindromes#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_palindromes/vb/dataflowpalindromes.vb#1)] + +## Next Steps + + This example sends one URL to process through the dataflow pipeline. If you send more than one input value through a pipeline, you can introduce a form of parallelism into your application that resembles how parts might move through an automobile factory. When the first member of the pipeline sends its result to the second member, it can process another item in parallel as the second member processes the first result. + + The parallelism that is achieved by using dataflow pipelines is known as *coarse-grained parallelism* because it typically consists of fewer, larger tasks. You can also use a more *fine-grained parallelism* of smaller, short-running tasks in a dataflow pipeline. In this example, the `findReversedWords` member of the pipeline uses [PLINQ](introduction-to-plinq.md) to process multiple items in the work list in parallel. The use of fine-grained parallelism in a coarse-grained pipeline can improve overall throughput. + + You can also connect a source dataflow block to multiple target blocks to create a *dataflow network*. The overloaded version of the method takes a object that defines whether the target block accepts each message based on its value. Most dataflow block types that act as sources offer messages to all connected target blocks, in the order in which they were connected, until one of the blocks accepts that message. By using this filtering mechanism, you can create systems of connected dataflow blocks that direct certain data through one path and other data through another path. For an example that uses filtering to create a dataflow network, see [Walkthrough: Using Dataflow in a Windows Forms Application](walkthrough-using-dataflow-in-a-windows-forms-application.md). + ## See also - [Dataflow](dataflow-task-parallel-library.md) diff --git a/docs/standard/parallel-programming/walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md b/docs/standard/parallel-programming/walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md index 6b6144177956a..23d187acf330f 100644 --- a/docs/standard/parallel-programming/walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md +++ b/docs/standard/parallel-programming/walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md @@ -12,7 +12,7 @@ ms.topic: tutorial --- # Walkthrough: Using BatchBlock and BatchedJoinBlock to Improve Efficiency -The TPL Dataflow Library provides the and classes so that you can receive and buffer data from one or more sources and then propagate out that buffered data as one collection. This batching mechanism is useful when you collect data from one or more sources and then process multiple data elements as a batch. For example, consider an application that uses dataflow to insert records into a database. This operation can be more efficient if multiple items are inserted at the same time instead of one at a time sequentially. This document describes how to use the class to improve the efficiency of such database insert operations. It also describes how to use the class to capture both the results and any exceptions that occur when the program reads from a database. +The TPL Dataflow Library provides the and classes so that you can receive and buffer data from one or more sources and then propagate out that buffered data as one collection. This batching mechanism is useful when you collect data from one or more sources and then process multiple data elements as a batch. For example, consider an application that uses dataflow to insert records into a database. This operation can be more efficient if multiple items are inserted at the same time instead of one at a time sequentially. This document describes how to use the class to improve the efficiency of such database insert operations. It also describes how to use the class to capture both the results and any exceptions that occur when the program reads from a database. [!INCLUDE [tpl-install-instructions](../../../includes/tpl-install-instructions.md)] @@ -64,7 +64,7 @@ Add to the `Program` class the `AddEmployees` and `PostRandomEmployees` methods. [!code-csharp[TPLDataflow_BatchDatabase#5](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_batchdatabase/cs/dataflowbatchdatabase.cs#5)] [!code-vb[TPLDataflow_BatchDatabase#5](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_batchdatabase/vb/dataflowbatchdatabase.vb#5)] -The `AddEmployees` method adds random employee data to the database by using dataflow. It creates an object that calls the `InsertEmployees` method to add an employee entry to the database. The `AddEmployees` method then calls the `PostRandomEmployees` method to post multiple `Employee` objects to the object. The `AddEmployees` method then waits for all insert operations to finish. +The `AddEmployees` method adds random employee data to the database by using dataflow. It creates an object that calls the `InsertEmployees` method to add an employee entry to the database. The `AddEmployees` method then calls the `PostRandomEmployees` method to post multiple `Employee` objects to the object. The `AddEmployees` method then waits for all insert operations to finish. ## Using Buffering to Add Employee Data to the Database @@ -73,7 +73,7 @@ Add to the `Program` class the `AddEmployeesBatched` method. [!code-csharp[TPLDataflow_BatchDatabase#6](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_batchdatabase/cs/dataflowbatchdatabase.cs#6)] [!code-vb[TPLDataflow_BatchDatabase#6](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_batchdatabase/vb/dataflowbatchdatabase.vb#6)] -This method resembles `AddEmployees`, except that it also uses the class to buffer multiple `Employee` objects before it sends those objects to the object. Because the class propagates out multiple elements as a collection, the object is modified to act on an array of `Employee` objects. As in the `AddEmployees` method, `AddEmployeesBatched` calls the `PostRandomEmployees` method to post multiple `Employee` objects; however, `AddEmployeesBatched` posts these objects to the object. The `AddEmployeesBatched` method also waits for all insert operations to finish. +This method resembles `AddEmployees`, except that it also uses the class to buffer multiple `Employee` objects before it sends those objects to the object. Because the class propagates out multiple elements as a collection, the object is modified to act on an array of `Employee` objects. As in the `AddEmployees` method, `AddEmployeesBatched` calls the `PostRandomEmployees` method to post multiple `Employee` objects; however, `AddEmployeesBatched` posts these objects to the object. The `AddEmployeesBatched` method also waits for all insert operations to finish. ## Using Buffered Join to Read Employee Data from the Database @@ -82,7 +82,7 @@ Add to the `Program` class the `GetRandomEmployees` method. [!code-csharp[TPLDataflow_BatchDatabase#7](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_batchdatabase/cs/dataflowbatchdatabase.cs#7)] [!code-vb[TPLDataflow_BatchDatabase#7](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_batchdatabase/vb/dataflowbatchdatabase.vb#7)] -This method prints information about random employees to the console. It creates several random `Employee` objects and calls the `GetEmployeeID` method to retrieve the unique identifier for each object. Because the `GetEmployeeID` method throws an exception if there is no matching employee with the given first and last names, the `GetRandomEmployees` method uses the class to store `Employee` objects for successful calls to `GetEmployeeID` and objects for calls that fail. The object in this example acts on a object that holds a list of `Employee` objects and a list of objects. The object propagates out this data when the sum of the received `Employee` and object counts equals the batch size. +This method prints information about random employees to the console. It creates several random `Employee` objects and calls the `GetEmployeeID` method to retrieve the unique identifier for each object. Because the `GetEmployeeID` method throws an exception if there is no matching employee with the given first and last names, the `GetRandomEmployees` method uses the class to store `Employee` objects for successful calls to `GetEmployeeID` and objects for calls that fail. The object in this example acts on a object that holds a list of `Employee` objects and a list of objects. The object propagates out this data when the sum of the received `Employee` and object counts equals the batch size. ## The Complete Example diff --git a/docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md b/docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md index aca3848156b88..49a6bd66d3a8d 100644 --- a/docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md +++ b/docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md @@ -2,7 +2,7 @@ description: "Learn more about: Walkthrough: Using Dataflow in a Windows Forms Application" title: "Walkthrough: Using Dataflow in a Windows Forms Application" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "TPL dataflow library, in Windows Forms" - "Task Parallel Library, dataflows" - "Windows Forms, and TPL" @@ -10,129 +10,129 @@ ms.topic: tutorial --- # Walkthrough: Using Dataflow in a Windows Forms Application -This article demonstrates how to create a network of dataflow blocks that perform image processing in a Windows Forms application. - - This example loads image files from the specified folder, creates a composite image, and displays the result. The example uses the dataflow model to route images through the network. In the dataflow model, independent components of a program communicate with one another by sending messages. When a component receives a message, it performs some action and then passes the result to another component. Compare this with the control flow model, in which an application uses control structures, for example, conditional statements, loops, and so on, to control the order of operations in a program. - -## Prerequisites +This article demonstrates how to create a network of dataflow blocks that perform image processing in a Windows Forms application. - Read [Dataflow](dataflow-task-parallel-library.md) before you start this walkthrough. + This example loads image files from the specified folder, creates a composite image, and displays the result. The example uses the dataflow model to route images through the network. In the dataflow model, independent components of a program communicate with one another by sending messages. When a component receives a message, it performs some action and then passes the result to another component. Compare this with the control flow model, in which an application uses control structures, for example, conditional statements, loops, and so on, to control the order of operations in a program. + +## Prerequisites + + Read [Dataflow](dataflow-task-parallel-library.md) before you start this walkthrough. [!INCLUDE [tpl-install-instructions](../../../includes/tpl-install-instructions.md)] -## Sections - - This walkthrough contains the following sections: - -- [Creating the Windows Forms Application](#winforms) - -- [Creating the Dataflow Network](#network) - -- [Connecting the Dataflow Network to the User Interface](#ui) - -- [The Complete Example](#complete) - +## Sections + + This walkthrough contains the following sections: + +- [Creating the Windows Forms Application](#winforms) + +- [Creating the Dataflow Network](#network) + +- [Connecting the Dataflow Network to the User Interface](#ui) + +- [The Complete Example](#complete) + -## Creating the Windows Forms Application - - This section describes how to create the basic Windows Forms application and add controls to the main form. - -### To Create the Windows Forms Application - -1. In Visual Studio, create a Visual C# or Visual Basic **Windows Forms Application** project. In this document, the project is named `CompositeImages`. - -2. On the form designer for the main form, Form1.cs (Form1.vb for Visual Basic), add a control. - -3. Add a control to the control. Set the property to and the property to **Choose Folder**. - -4. Add a second control to the control. Set the property to , the property to **Cancel**, and the property to `False`. - -5. Add a object to the main form. Set the property to . - +## Creating the Windows Forms Application + + This section describes how to create the basic Windows Forms application and add controls to the main form. + +### To Create the Windows Forms Application + +1. In Visual Studio, create a Visual C# or Visual Basic **Windows Forms Application** project. In this document, the project is named `CompositeImages`. + +2. On the form designer for the main form, Form1.cs (Form1.vb for Visual Basic), add a control. + +3. Add a control to the control. Set the property to and the property to **Choose Folder**. + +4. Add a second control to the control. Set the property to , the property to **Cancel**, and the property to `False`. + +5. Add a object to the main form. Set the property to . + -## Creating the Dataflow Network - - This section describes how to create the dataflow network that performs image processing. - -### To Create the Dataflow Network - -1. Add a reference to System.Threading.Tasks.Dataflow.dll to your project. - -2. Ensure that Form1.cs (Form1.vb for Visual Basic) contains the following `using` (`Using` in Visual Basic) statements: - - [!code-csharp[TPLDataflow_CompositeImages#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#1)] - -3. Add the following data members to the `Form1` class: - - [!code-csharp[TPLDataflow_CompositeImages#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#2)] - -4. Add the following method, `CreateImageProcessingNetwork`, to the `Form1` class. This method creates the image processing network. - - [!code-csharp[TPLDataflow_CompositeImages#3](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#3)] - -5. Implement the `LoadBitmaps` method. - - [!code-csharp[TPLDataflow_CompositeImages#4](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#4)] - -6. Implement the `CreateCompositeBitmap` method. - - [!code-csharp[TPLDataflow_CompositeImages#5](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#5)] - +## Creating the Dataflow Network + + This section describes how to create the dataflow network that performs image processing. + +### To Create the Dataflow Network + +1. Add a reference to System.Threading.Tasks.Dataflow.dll to your project. + +2. Ensure that Form1.cs (Form1.vb for Visual Basic) contains the following `using` (`Using` in Visual Basic) statements: + + [!code-csharp[TPLDataflow_CompositeImages#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#1)] + +3. Add the following data members to the `Form1` class: + + [!code-csharp[TPLDataflow_CompositeImages#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#2)] + +4. Add the following method, `CreateImageProcessingNetwork`, to the `Form1` class. This method creates the image processing network. + + [!code-csharp[TPLDataflow_CompositeImages#3](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#3)] + +5. Implement the `LoadBitmaps` method. + + [!code-csharp[TPLDataflow_CompositeImages#4](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#4)] + +6. Implement the `CreateCompositeBitmap` method. + + [!code-csharp[TPLDataflow_CompositeImages#5](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#5)] + > [!NOTE] - > The C# version of the `CreateCompositeBitmap` method uses pointers to enable efficient processing of the objects. Therefore, you must enable the **Allow unsafe code** option in your project in order to use the [unsafe](../../csharp/language-reference/keywords/unsafe.md) keyword. For more information about how to enable unsafe code in a Visual C# project, see [Build Page, Project Designer (C#)](/visualstudio/ide/reference/build-page-project-designer-csharp). - - The following table describes the members of the network. - -|Member|Type|Description| -|------------|----------|-----------------| -|`loadBitmaps`||Takes a folder path as input and produces a collection of objects as output.| -|`createCompositeBitmap`||Takes a collection of objects as input and produces a composite bitmap as output.| -|`displayCompositeBitmap`||Displays the composite bitmap on the form.| -|`operationCancelled`||Displays an image to indicate that the operation is canceled and enables the user to select another folder.| - - To connect the dataflow blocks to form a network, this example uses the method. The method contains an overloaded version that takes a object that determines whether the target block accepts or rejects a message. This filtering mechanism enables message blocks to receive only certain values. In this example, the network can branch in one of two ways. The main branch loads the images from disk, creates the composite image, and displays that image on the form. The alternate branch cancels the current operation. The objects enable the dataflow blocks along the main branch to switch to the alternative branch by rejecting certain messages. For example, if the user cancels the operation, the dataflow block `createCompositeBitmap` produces `null` (`Nothing` in Visual Basic) as its output. The dataflow block `displayCompositeBitmap` rejects `null` input values, and therefore, the message is offered to `operationCancelled`. The dataflow block `operationCancelled` accepts all messages and therefore, displays an image to indicate that the operation is canceled. - - The following illustration shows the image processing network: - - ![Illustration that shows the image processing network.](./media/walkthrough-using-dataflow-in-a-windows-forms-application/dataflow-winforms-image-processing.png) - - Because the `displayCompositeBitmap` and `operationCancelled` dataflow blocks act on the user interface, it is important that these actions occur on the user-interface thread. To accomplish this, during construction, these objects each provide an object that has the property set to . The method creates a object that performs work on the current synchronization context. Because the `CreateImageProcessingNetwork` method is called from the handler of the **Choose Folder** button, which runs on the user-interface thread, the actions for the `displayCompositeBitmap` and `operationCancelled` dataflow blocks also run on the user-interface thread. - - This example uses a shared cancellation token instead of setting the property because the property permanently cancels dataflow block execution. A cancellation token enables this example to reuse the same dataflow network multiple times, even when the user cancels one or more operations. For an example that uses to permanently cancel the execution of a dataflow block, see [How to: Cancel a Dataflow Block](how-to-cancel-a-dataflow-block.md). - + > The C# version of the `CreateCompositeBitmap` method uses pointers to enable efficient processing of the objects. Therefore, you must enable the **Allow unsafe code** option in your project in order to use the [unsafe](../../csharp/language-reference/keywords/unsafe.md) keyword. For more information about how to enable unsafe code in a Visual C# project, see [Build Page, Project Designer (C#)](/visualstudio/ide/reference/build-page-project-designer-csharp). + + The following table describes the members of the network. + +|Member|Type|Description| +|------------|----------|-----------------| +|`loadBitmaps`||Takes a folder path as input and produces a collection of objects as output.| +|`createCompositeBitmap`||Takes a collection of objects as input and produces a composite bitmap as output.| +|`displayCompositeBitmap`||Displays the composite bitmap on the form.| +|`operationCancelled`||Displays an image to indicate that the operation is canceled and enables the user to select another folder.| + + To connect the dataflow blocks to form a network, this example uses the method. The method contains an overloaded version that takes a object that determines whether the target block accepts or rejects a message. This filtering mechanism enables message blocks to receive only certain values. In this example, the network can branch in one of two ways. The main branch loads the images from disk, creates the composite image, and displays that image on the form. The alternate branch cancels the current operation. The objects enable the dataflow blocks along the main branch to switch to the alternative branch by rejecting certain messages. For example, if the user cancels the operation, the dataflow block `createCompositeBitmap` produces `null` (`Nothing` in Visual Basic) as its output. The dataflow block `displayCompositeBitmap` rejects `null` input values, and therefore, the message is offered to `operationCancelled`. The dataflow block `operationCancelled` accepts all messages and therefore, displays an image to indicate that the operation is canceled. + + The following illustration shows the image processing network: + + ![Illustration that shows the image processing network.](./media/walkthrough-using-dataflow-in-a-windows-forms-application/dataflow-winforms-image-processing.png) + + Because the `displayCompositeBitmap` and `operationCancelled` dataflow blocks act on the user interface, it is important that these actions occur on the user-interface thread. To accomplish this, during construction, these objects each provide an object that has the property set to . The method creates a object that performs work on the current synchronization context. Because the `CreateImageProcessingNetwork` method is called from the handler of the **Choose Folder** button, which runs on the user-interface thread, the actions for the `displayCompositeBitmap` and `operationCancelled` dataflow blocks also run on the user-interface thread. + + This example uses a shared cancellation token instead of setting the property because the property permanently cancels dataflow block execution. A cancellation token enables this example to reuse the same dataflow network multiple times, even when the user cancels one or more operations. For an example that uses to permanently cancel the execution of a dataflow block, see [How to: Cancel a Dataflow Block](how-to-cancel-a-dataflow-block.md). + -## Connecting the Dataflow Network to the User Interface - - This section describes how to connect the dataflow network to the user interface. The creation of the composite image and cancellation of the operation are initiated from the **Choose Folder** and **Cancel** buttons. When the user chooses either of these buttons, the appropriate action is initiated in an asynchronous manner. - -### To Connect the Dataflow Network to the User Interface - -1. On the form designer for the main form, create an event handler for the event for the **Choose Folder** button. - -2. Implement the event for the **Choose Folder** button. - - [!code-csharp[TPLDataflow_CompositeImages#6](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#6)] - -3. On the form designer for the main form, create an event handler for the event for the **Cancel** button. - -4. Implement the event for the **Cancel** button. - - [!code-csharp[TPLDataflow_CompositeImages#7](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#7)] - +## Connecting the Dataflow Network to the User Interface + + This section describes how to connect the dataflow network to the user interface. The creation of the composite image and cancellation of the operation are initiated from the **Choose Folder** and **Cancel** buttons. When the user chooses either of these buttons, the appropriate action is initiated in an asynchronous manner. + +### To Connect the Dataflow Network to the User Interface + +1. On the form designer for the main form, create an event handler for the event for the **Choose Folder** button. + +2. Implement the event for the **Choose Folder** button. + + [!code-csharp[TPLDataflow_CompositeImages#6](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#6)] + +3. On the form designer for the main form, create an event handler for the event for the **Cancel** button. + +4. Implement the event for the **Cancel** button. + + [!code-csharp[TPLDataflow_CompositeImages#7](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#7)] + -## The Complete Example +## The Complete Example + + The following example shows the complete code for this walkthrough. + + [!code-csharp[TPLDataflow_CompositeImages#100](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#100)] + + The following illustration shows typical output for the common \Sample Pictures\ folder. - The following example shows the complete code for this walkthrough. - - [!code-csharp[TPLDataflow_CompositeImages#100](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#100)] - - The following illustration shows typical output for the common \Sample Pictures\ folder. - - ![The Windows Forms Application](media/tpldataflow-compositeimages.gif "TPLDataflow_CompositeImages") + ![The Windows Forms Application](media/tpldataflow-compositeimages.gif "TPLDataflow_CompositeImages") ## See also diff --git a/docs/standard/security/cross-platform-cryptography.md b/docs/standard/security/cross-platform-cryptography.md index 62814d52c08f8..78c7f7564c417 100644 --- a/docs/standard/security/cross-platform-cryptography.md +++ b/docs/standard/security/cross-platform-cryptography.md @@ -161,9 +161,9 @@ Padding and digest support vary by platform: * Windows CryptoAPI (CAPI) is used whenever [`new RSACryptoServiceProvider()`](xref:System.Security.Cryptography.RSACryptoServiceProvider) is used. * Windows Cryptography API Next Generation (CNG) is used whenever [`new RSACng()`](xref:System.Security.Cryptography.RSACng) is used. -* The object returned by is internally powered by Windows CNG. This use of Windows CNG is an implementation detail and is subject to change. -* The extension method for returns an instance. This use of is an implementation detail and is subject to change. -* The extension method for currently prefers an instance, but if can't open the key, will be attempted. The preferred provider is an implementation detail and is subject to change. +* The object returned by is internally powered by Windows CNG. This use of Windows CNG is an implementation detail and is subject to change. +* The extension method for returns an instance. This use of is an implementation detail and is subject to change. +* The extension method for currently prefers an instance, but if can't open the key, will be attempted. The preferred provider is an implementation detail and is subject to change. #### RSA native interop @@ -278,9 +278,9 @@ DSA (Digital Signature Algorithm) key generation is performed by the system libr * Windows CryptoAPI (CAPI) is used whenever [`new DSACryptoServiceProvider()`](xref:System.Security.Cryptography.DSACryptoServiceProvider) is used. * Windows Cryptography API Next Generation (CNG) is used whenever [`new DSACng()`](xref:System.Security.Cryptography.DSACng) is used. -* The object returned by is internally powered by Windows CNG. This use of Windows CNG is an implementation detail and is subject to change. -* The extension method for returns a instance. This use of is an implementation detail and is subject to change. -* The extension method for prefers an instance, but if can't open the key, will be attempted. The preferred provider is an implementation detail and is subject to change. +* The object returned by is internally powered by Windows CNG. This use of Windows CNG is an implementation detail and is subject to change. +* The extension method for returns a instance. This use of is an implementation detail and is subject to change. +* The extension method for prefers an instance, but if can't open the key, will be attempted. The preferred provider is an implementation detail and is subject to change. #### DSA native interop diff --git a/docs/standard/security/cryptographic-services.md b/docs/standard/security/cryptographic-services.md index 40ba60ff10891..f0b4a955fa7c9 100644 --- a/docs/standard/security/cryptographic-services.md +++ b/docs/standard/security/cryptographic-services.md @@ -182,7 +182,7 @@ The class is an implem The following cryptography classes let you obtain and verify information about manifest signatures for applications that are deployed using [ClickOnce technology](/visualstudio/deployment/clickonce-security-and-deployment): -- The class obtains information about a manifest signature when you use its method overloads. +- The class obtains information about a manifest signature when you use its method overloads. - You can use the enumeration to specify which manifests to verify. The result of the verification is one of the enumeration values. diff --git a/docs/standard/security/cryptographic-signatures.md b/docs/standard/security/cryptographic-signatures.md index c014cd3759dbd..f04882f7d9584 100644 --- a/docs/standard/security/cryptographic-signatures.md +++ b/docs/standard/security/cryptographic-signatures.md @@ -30,7 +30,7 @@ This topic explains how to generate and verify digital signatures using classes ## Generate a signature -Digital signatures are usually applied to hash values that represent larger data. The following example applies a digital signature to a hash value. First, a new instance of the class is created to generate a public/private key pair. Next, the is passed to a new instance of the class. This transfers the private key to the , which actually performs the digital signing. Before you can sign the hash code, you must specify a hash algorithm to use. This example uses the `SHA256` algorithm. Finally, the method is called to perform the signing. +Digital signatures are usually applied to hash values that represent larger data. The following example applies a digital signature to a hash value. First, a new instance of the class is created to generate a public/private key pair. Next, the is passed to a new instance of the class. This transfers the private key to the , which actually performs the digital signing. Before you can sign the hash code, you must specify a hash algorithm to use. This example uses the `SHA256` algorithm. Finally, the method is called to perform the signing. ```vb Imports System.Security.Cryptography @@ -96,13 +96,13 @@ To verify that data was signed by a particular party, you must have the followin - The data that was signed. - The hash algorithm used by the signer. -To verify a signature signed by the class, use the class. The class must be supplied the public key of the signer. For RSA, you will need at a minimal the values of the and the to specify the public key. One way to achieve this is to call during signature creation and then call during the verification process. The party that generated the public/private key pair should provide these values. First create an object to hold the public key that will verify the signature, and then initialize an structure to the modulus and exponent values that specify the public key. +To verify a signature signed by the class, use the class. The class must be supplied the public key of the signer. For RSA, you will need at a minimal the values of the and the to specify the public key. One way to achieve this is to call during signature creation and then call during the verification process. The party that generated the public/private key pair should provide these values. First create an object to hold the public key that will verify the signature, and then initialize an structure to the modulus and exponent values that specify the public key. The following code shows the sharing of an structure. The `RSA` responsible for creating the signature exports its parameters. The parameters are then imported into the new `RSA` instance that is responsible for verifying the signature. The instance is, in turn, passed to the constructor of an to transfer the key. -The following example illustrates this process. In this example, imagine that `sharedParameters`, `hash`, and `signedHash` are provided by a remote party. The remote party has signed `hash` using the `SHA256` algorithm to produce the digital signature `signedHash`. The method verifies that the digital signature is valid and was used to sign `hash`. +The following example illustrates this process. In this example, imagine that `sharedParameters`, `hash`, and `signedHash` are provided by a remote party. The remote party has signed `hash` using the `SHA256` algorithm to produce the digital signature `signedHash`. The method verifies that the digital signature is valid and was used to sign `hash`. :::code language="vb" source="./snippets/cryptographic-signatures/vb/Program.vb"::: :::code language="csharp" source="./snippets/cryptographic-signatures/csharp/Program.cs"::: diff --git a/docs/standard/security/cryptography-model.md b/docs/standard/security/cryptography-model.md index eaa9434b84dad..69e5bdff94d5a 100644 --- a/docs/standard/security/cryptography-model.md +++ b/docs/standard/security/cryptography-model.md @@ -37,7 +37,7 @@ Starting in .NET 5, simpler APIs were introduced for hashing and HMAC. While sli - Are thread safe - Use the best available implementation for the platform -The hashing and HMAC primitives expose a one-shot API through a static `HashData` method on the type, such as . The static APIs offer no built-in extensibility mechanism. If you're implementing your own algorithms, it's recommended to also offer similar static APIs of the algorithm. +The hashing and HMAC primitives expose a one-shot API through a static `HashData` method on the type, such as . The static APIs offer no built-in extensibility mechanism. If you're implementing your own algorithms, it's recommended to also offer similar static APIs of the algorithm. The class also offers static methods for creating or filling buffers with cryptographic random data. These methods always use the system's cryptographically secure pseudorandom number generator (CSPRNG). @@ -78,10 +78,10 @@ Here is a list of recommended algorithms by application: - - - Random number generation: - - - - + - + - - Generating a key from a password: - - + - ## See also diff --git a/docs/standard/security/decrypting-data.md b/docs/standard/security/decrypting-data.md index 28841b79bcfb5..8097ffb2a87b3 100644 --- a/docs/standard/security/decrypting-data.md +++ b/docs/standard/security/decrypting-data.md @@ -21,7 +21,7 @@ Decryption is the reverse operation of encryption. For secret-key encryption, yo The decryption of data encrypted with symmetric algorithms is similar to the process used to encrypt data with symmetric algorithms. The class is used with symmetric cryptography classes provided by .NET to decrypt data read from any managed stream object. -The following example illustrates how to create a new instance of the default implementation class for the algorithm. The instance is used to perform decryption on a object. This example first creates a new instance of the implementation class. It reads the initialization vector (IV) value from a managed stream variable, `fileStream`. Next it instantiates a object and initializes it to the value of the `fileStream` instance. The method from the instance is passed the IV value and the same key that was used for encryption. +The following example illustrates how to create a new instance of the default implementation class for the algorithm. The instance is used to perform decryption on a object. This example first creates a new instance of the implementation class. It reads the initialization vector (IV) value from a managed stream variable, `fileStream`. Next it instantiates a object and initializes it to the value of the `fileStream` instance. The method from the instance is passed the IV value and the same key that was used for encryption. ```vb Dim aes As Aes = Aes.Create() diff --git a/docs/standard/security/encrypting-data.md b/docs/standard/security/encrypting-data.md index 204d9d1600ad6..ce3f1e37c5b6e 100644 --- a/docs/standard/security/encrypting-data.md +++ b/docs/standard/security/encrypting-data.md @@ -60,7 +60,7 @@ The encryption failed. Asymmetric algorithms are usually used to encrypt small amounts of data such as the encryption of a symmetric key and IV. Typically, an individual performing asymmetric encryption uses the public key generated by another party. The class is provided by .NET for this purpose. -The following example uses public key information to encrypt a symmetric key and IV. Two byte arrays are initialized that represents the public key of a third party. An object is initialized to these values. Next, the **RSAParameters** object (along with the public key it represents) is imported into an **RSA** instance using the method. Finally, the private key and IV created by an class are encrypted. This example requires systems to have 128-bit encryption installed. +The following example uses public key information to encrypt a symmetric key and IV. Two byte arrays are initialized that represents the public key of a third party. An object is initialized to these values. Next, the **RSAParameters** object (along with the public key it represents) is imported into an **RSA** instance using the method. Finally, the private key and IV created by an class are encrypted. This example requires systems to have 128-bit encryption installed. ```vb Imports System diff --git a/docs/standard/security/generating-keys-for-encryption-and-decryption.md b/docs/standard/security/generating-keys-for-encryption-and-decryption.md index e34752864468f..503b43a2e1c3a 100644 --- a/docs/standard/security/generating-keys-for-encryption-and-decryption.md +++ b/docs/standard/security/generating-keys-for-encryption-and-decryption.md @@ -3,10 +3,10 @@ title: "Generating Keys for Encryption and Decryption" description: Understand how to create and manage symmetric and asymmetric keys for encryption and decryption in .NET. ms.date: 08/10/2022 ms.custom: devdivchpfy22 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "keys, encryption and decryption" - "keys, asymmetric" - "keys, symmetric" @@ -18,76 +18,76 @@ ms.topic: how-to --- # Generate keys for encryption and decryption -Creating and managing keys is an important part of the cryptographic process. Symmetric algorithms require the creation of a key and an initialization vector (IV). You must keep this key secret from anyone who shouldn't decrypt your data. The IV doesn't have to be secret but should be changed for each session. Asymmetric algorithms require the creation of a public key and a private key. The public key can be made known to anyone, but the decrypting party must only know the corresponding private key. This section describes how to generate and manage keys for both symmetric and asymmetric algorithms. - -## Symmetric Keys +Creating and managing keys is an important part of the cryptographic process. Symmetric algorithms require the creation of a key and an initialization vector (IV). You must keep this key secret from anyone who shouldn't decrypt your data. The IV doesn't have to be secret but should be changed for each session. Asymmetric algorithms require the creation of a public key and a private key. The public key can be made known to anyone, but the decrypting party must only know the corresponding private key. This section describes how to generate and manage keys for both symmetric and asymmetric algorithms. + +## Symmetric Keys + + The symmetric encryption classes supplied by .NET require a key and a new IV to encrypt and decrypt data. A new key and IV is automatically created when you create a new instance of one of the managed symmetric cryptographic classes using the parameterless `Create()` method. Anyone that you allow to decrypt your data must possess the same key and IV and use the same algorithm. Generally, a new key and IV should be created for every session, and neither the key nor the IV should be stored for use in a later session. + + To communicate a symmetric key and IV to a remote party, you usually encrypt the symmetric key by using asymmetric encryption. Sending the key across an insecure network without encryption is unsafe because anyone who intercepts the key and IV can then decrypt your data. - The symmetric encryption classes supplied by .NET require a key and a new IV to encrypt and decrypt data. A new key and IV is automatically created when you create a new instance of one of the managed symmetric cryptographic classes using the parameterless `Create()` method. Anyone that you allow to decrypt your data must possess the same key and IV and use the same algorithm. Generally, a new key and IV should be created for every session, and neither the key nor the IV should be stored for use in a later session. - - To communicate a symmetric key and IV to a remote party, you usually encrypt the symmetric key by using asymmetric encryption. Sending the key across an insecure network without encryption is unsafe because anyone who intercepts the key and IV can then decrypt your data. - The following example shows the creation of a new instance of the default implementation class for the algorithm: - -```vb -Dim aes As Aes = Aes.Create() -``` - -```csharp -Aes aes = Aes.Create(); -``` - - The execution of the preceding code generates a new key and IV and sets them as values for the **Key** and **IV** properties, respectively. - + +```vb +Dim aes As Aes = Aes.Create() +``` + +```csharp +Aes aes = Aes.Create(); +``` + + The execution of the preceding code generates a new key and IV and sets them as values for the **Key** and **IV** properties, respectively. + Sometimes you might need to generate multiple keys. In this situation, you can create a new instance of a class that implements a symmetric algorithm. Then, create a new key and IV by calling the `GenerateKey` and `GenerateIV` methods. The following code example illustrates how to create new keys and IVs after a new instance of the symmetric cryptographic class has been made: - -```vb -Dim aes As Aes = Aes.Create() -aes.GenerateIV() -aes.GenerateKey() -``` - -```csharp -Aes aes = Aes.Create(); -aes.GenerateIV(); -aes.GenerateKey(); -``` - + +```vb +Dim aes As Aes = Aes.Create() +aes.GenerateIV() +aes.GenerateKey() +``` + +```csharp +Aes aes = Aes.Create(); +aes.GenerateIV(); +aes.GenerateKey(); +``` + The execution of the preceding code creates a new instance of `Aes` and generates a key and IV. Another key and IV are created when the `GenerateKey` and `GenerateIV` methods are called. - + ## Asymmetric Keys - .NET provides the class for asymmetric encryption. When you use the parameterless `Create()` method to create a new instance, the class creates a public/private key pair. Asymmetric keys can be either stored for use in multiple sessions or generated for one session only. While you can make the public key available, you must closely guard the private key. - - A public/private key pair is generated when you create a new instance of an asymmetric algorithm class. After creating a new instance of the class, you can extract the key information using the method. This method returns an structure that holds the key information. The method also accepts a Boolean value that indicates whether to return only the public-key information or to return both the public-key and the private-key information. + .NET provides the class for asymmetric encryption. When you use the parameterless `Create()` method to create a new instance, the class creates a public/private key pair. Asymmetric keys can be either stored for use in multiple sessions or generated for one session only. While you can make the public key available, you must closely guard the private key. + + A public/private key pair is generated when you create a new instance of an asymmetric algorithm class. After creating a new instance of the class, you can extract the key information using the method. This method returns an structure that holds the key information. The method also accepts a Boolean value that indicates whether to return only the public-key information or to return both the public-key and the private-key information. You also can use other methods to extract the key information, such as: -* -* -* -* -* +* +* +* +* +* + +You can use the method to initialize an `RSA` instance to the value of an `RSAParameters` structure. Or you can use the method to create a new instance. + + Never store asymmetric private keys verbatim or as plain text on the local computer. If you need to store a private key, you must use a key container. For more information about how to store a private key in a key container, see [How to: Store Asymmetric Keys in a Key Container](how-to-store-asymmetric-keys-in-a-key-container.md). -You can use the method to initialize an `RSA` instance to the value of an `RSAParameters` structure. Or you can use the method to create a new instance. - - Never store asymmetric private keys verbatim or as plain text on the local computer. If you need to store a private key, you must use a key container. For more information about how to store a private key in a key container, see [How to: Store Asymmetric Keys in a Key Container](how-to-store-asymmetric-keys-in-a-key-container.md). - The following code example creates a new instance of the `RSA` class, creates a public/private key pair, and saves the public key information to an `RSAParameters` structure: - -```vb -'Generate a public/private key pair. -Dim rsa as RSA = RSA.Create() -'Save the public key information to an RSAParameters structure. -Dim rsaKeyInfo As RSAParameters = rsa.ExportParameters(false) -``` - -```csharp -//Generate a public/private key pair. -RSA rsa = RSA.Create(); -//Save the public key information to an RSAParameters structure. -RSAParameters rsaKeyInfo = rsa.ExportParameters(false); -``` - + +```vb +'Generate a public/private key pair. +Dim rsa as RSA = RSA.Create() +'Save the public key information to an RSAParameters structure. +Dim rsaKeyInfo As RSAParameters = rsa.ExportParameters(false) +``` + +```csharp +//Generate a public/private key pair. +RSA rsa = RSA.Create(); +//Save the public key information to an RSAParameters structure. +RSAParameters rsaKeyInfo = rsa.ExportParameters(false); +``` + ## See also * [Encrypting Data](encrypting-data.md) diff --git a/docs/standard/security/how-to-access-hardware-encryption-devices.md b/docs/standard/security/how-to-access-hardware-encryption-devices.md index aa8b6bab1d837..f44ae4c55c1ab 100644 --- a/docs/standard/security/how-to-access-hardware-encryption-devices.md +++ b/docs/standard/security/how-to-access-hardware-encryption-devices.md @@ -25,7 +25,7 @@ The class creates a cryptograp 1. Create a new instance of the class, passing the integer provider type and the provider name to the constructor. -2. Pass the appropriate flags to the property of the newly created object. For example, pass the flag. +2. Pass the appropriate flags to the property of the newly created object. For example, pass the flag. 3. Create a new instance of an class (for example, the class), passing the object to the constructor. @@ -37,7 +37,7 @@ The class creates a cryptograp 2. Create a new instance of the , passing the object to the constructor. -3. Create a random value using the or method. +3. Create a random value using the or method. ## Example diff --git a/docs/standard/security/how-to-create-a-windowsprincipal-object.md b/docs/standard/security/how-to-create-a-windowsprincipal-object.md index 4aad67145b832..47e6de4f65971 100644 --- a/docs/standard/security/how-to-create-a-windowsprincipal-object.md +++ b/docs/standard/security/how-to-create-a-windowsprincipal-object.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Create a WindowsPrincipal Object" title: "How to: Create a WindowsPrincipal Object" ms.date: 07/15/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "WindowsPrincipal objects, creating" - "security [.NET], creating a WindowsPrincipal object" - "security [.NET], principals" @@ -19,62 +19,62 @@ ms.assetid: 56eb10ca-e61d-4ed2-af7a-555fc4c25a25 > > For information about ASP.NET Core, see [ASP.NET Core Security](/aspnet/core/security/). -There are two ways to create a object, depending on whether code must repeatedly perform role-based validation or must perform it only once. - -If code must repeatedly perform role-based validation, the first of the following procedures produces less overhead. When code needs to make role-based validations only once, you can create a object by using the second of the following procedures. - -### To create a WindowsPrincipal object for repeated validation - -1. Call the method on the object that is returned by the static property, passing the method a enumeration value that indicates what the new policy should be. Supported values are , , and . The following code demonstrates this method call. - - ```csharp - AppDomain.CurrentDomain.SetPrincipalPolicy( - PrincipalPolicy.WindowsPrincipal); - ``` - - ```vb - AppDomain.CurrentDomain.SetPrincipalPolicy( _ - PrincipalPolicy.WindowsPrincipal) - ``` - -2. With the policy set, use the static property to retrieve the principal that encapsulates the current Windows user. Because the property return type is , you must cast the result to a type. The following code initializes a new object to the value of the principal associated with the current thread. - - ```csharp +There are two ways to create a object, depending on whether code must repeatedly perform role-based validation or must perform it only once. + +If code must repeatedly perform role-based validation, the first of the following procedures produces less overhead. When code needs to make role-based validations only once, you can create a object by using the second of the following procedures. + +### To create a WindowsPrincipal object for repeated validation + +1. Call the method on the object that is returned by the static property, passing the method a enumeration value that indicates what the new policy should be. Supported values are , , and . The following code demonstrates this method call. + + ```csharp + AppDomain.CurrentDomain.SetPrincipalPolicy( + PrincipalPolicy.WindowsPrincipal); + ``` + + ```vb + AppDomain.CurrentDomain.SetPrincipalPolicy( _ + PrincipalPolicy.WindowsPrincipal) + ``` + +2. With the policy set, use the static property to retrieve the principal that encapsulates the current Windows user. Because the property return type is , you must cast the result to a type. The following code initializes a new object to the value of the principal associated with the current thread. + + ```csharp WindowsPrincipal myPrincipal = - (WindowsPrincipal) Thread.CurrentPrincipal; - ``` - - ```vb - Dim myPrincipal As WindowsPrincipal = _ + (WindowsPrincipal) Thread.CurrentPrincipal; + ``` + + ```vb + Dim myPrincipal As WindowsPrincipal = _ CType(Thread.CurrentPrincipal, WindowsPrincipal) - ``` - -3. When the principal object has been created, you can use one of several methods to validate it. - -### To create a WindowsPrincipal object for a single validation - -1. Initialize a new object by calling the static method, which queries the current Windows account and places information about that account into the newly created identity object. The following code creates a new object and initializes it to the current authenticated user. - - ```csharp - WindowsIdentity myIdentity = WindowsIdentity.GetCurrent(); - ``` - - ```vb - Dim myIdentity As WindowsIdentity = WindowsIdentity.GetCurrent() - ``` - -2. Create a new object and pass it the value of the object created in the preceding step. - - ```csharp - WindowsPrincipal myPrincipal = new WindowsPrincipal(myIdentity); - ``` - - ```vb - Dim myPrincipal As New WindowsPrincipal(myIdentity) - ``` - -3. When the principal object has been created, you can use one of several methods to validate it. - + ``` + +3. When the principal object has been created, you can use one of several methods to validate it. + +### To create a WindowsPrincipal object for a single validation + +1. Initialize a new object by calling the static method, which queries the current Windows account and places information about that account into the newly created identity object. The following code creates a new object and initializes it to the current authenticated user. + + ```csharp + WindowsIdentity myIdentity = WindowsIdentity.GetCurrent(); + ``` + + ```vb + Dim myIdentity As WindowsIdentity = WindowsIdentity.GetCurrent() + ``` + +2. Create a new object and pass it the value of the object created in the preceding step. + + ```csharp + WindowsPrincipal myPrincipal = new WindowsPrincipal(myIdentity); + ``` + + ```vb + Dim myPrincipal As New WindowsPrincipal(myIdentity) + ``` + +3. When the principal object has been created, you can use one of several methods to validate it. + ## See also - [Principal and Identity Objects](principal-and-identity-objects.md) diff --git a/docs/standard/security/how-to-decrypt-xml-elements-with-asymmetric-keys.md b/docs/standard/security/how-to-decrypt-xml-elements-with-asymmetric-keys.md index c0a7ffa85743d..8a279747f7ee0 100644 --- a/docs/standard/security/how-to-decrypt-xml-elements-with-asymmetric-keys.md +++ b/docs/standard/security/how-to-decrypt-xml-elements-with-asymmetric-keys.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Decrypt XML Elements with Asymmetric Keys" title: "How to: Decrypt XML Elements with Asymmetric Keys" ms.date: 07/14/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "System.Security.Cryptography.RSA class" - "asymmetric keys" - "System.Security.Cryptography.EncryptedXml class" @@ -15,72 +15,72 @@ ms.assetid: dd5de491-dafe-4b94-966d-99714b2e754a --- # How to: Decrypt XML Elements with Asymmetric Keys -You can use the classes in the namespace to encrypt and decrypt an element within an XML document. XML Encryption is a standard way to exchange or store encrypted XML data, without worrying about the data being easily read. For more information about the XML Encryption standard, see the World Wide Web Consortium (W3C) recommendation [XML Signature Syntax and Processing](https://www.w3.org/TR/xmldsig-core/). +You can use the classes in the namespace to encrypt and decrypt an element within an XML document. XML Encryption is a standard way to exchange or store encrypted XML data, without worrying about the data being easily read. For more information about the XML Encryption standard, see the World Wide Web Consortium (W3C) recommendation [XML Signature Syntax and Processing](https://www.w3.org/TR/xmldsig-core/). > [!NOTE] > The code in this article applies to Windows. -The example in this procedure decrypts an XML element that was encrypted using the methods described in [How to: Encrypt XML Elements with Asymmetric Keys](how-to-encrypt-xml-elements-with-asymmetric-keys.md). It finds an <`EncryptedData`> element, decrypts the element, and then replaces the element with the original plaintext XML element. - -This example decrypts an XML element using two keys. It retrieves a previously generated RSA private key from a key container, and then uses the RSA key to decrypt a session key stored in the <`EncryptedKey`> element of the <`EncryptedData`> element. The example then uses the session key to decrypt the XML element. - -This example is appropriate for situations where multiple applications have to share encrypted data or where an application has to save encrypted data between the times that it runs. - -### To decrypt an XML element with an asymmetric key - -1. Create a object and specify the name of the key container. - +The example in this procedure decrypts an XML element that was encrypted using the methods described in [How to: Encrypt XML Elements with Asymmetric Keys](how-to-encrypt-xml-elements-with-asymmetric-keys.md). It finds an <`EncryptedData`> element, decrypts the element, and then replaces the element with the original plaintext XML element. + +This example decrypts an XML element using two keys. It retrieves a previously generated RSA private key from a key container, and then uses the RSA key to decrypt a session key stored in the <`EncryptedKey`> element of the <`EncryptedData`> element. The example then uses the session key to decrypt the XML element. + +This example is appropriate for situations where multiple applications have to share encrypted data or where an application has to save encrypted data between the times that it runs. + +### To decrypt an XML element with an asymmetric key + +1. Create a object and specify the name of the key container. + [!code-csharp[HowToDecryptXMLElementAsymmetric#2](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/cs/sample.cs#2)] - [!code-vb[HowToDecryptXMLElementAsymmetric#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#2)] - -2. Retrieve a previously generated asymmetric key from the container using the object. The key is automatically retrieved from the key container when you pass the object to the constructor. - + [!code-vb[HowToDecryptXMLElementAsymmetric#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#2)] + +2. Retrieve a previously generated asymmetric key from the container using the object. The key is automatically retrieved from the key container when you pass the object to the constructor. + [!code-csharp[HowToDecryptXMLElementAsymmetric#3](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/cs/sample.cs#3)] - [!code-vb[HowToDecryptXMLElementAsymmetric#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#3)] - -3. Create a new object to decrypt the document. - + [!code-vb[HowToDecryptXMLElementAsymmetric#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#3)] + +3. Create a new object to decrypt the document. + [!code-csharp[HowToDecryptXMLElementAsymmetric#5](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/cs/sample.cs#5)] - [!code-vb[HowToDecryptXMLElementAsymmetric#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#5)] - -4. Add a key/name mapping to associate the RSA key with the element within the document that should be decrypted. You must use the same name for the key that you used when you encrypted the document. Note that this name is separate from the name used to identify the key in the key container specified in step 1. - + [!code-vb[HowToDecryptXMLElementAsymmetric#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#5)] + +4. Add a key/name mapping to associate the RSA key with the element within the document that should be decrypted. You must use the same name for the key that you used when you encrypted the document. Note that this name is separate from the name used to identify the key in the key container specified in step 1. + [!code-csharp[HowToDecryptXMLElementAsymmetric#6](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/cs/sample.cs#6)] - [!code-vb[HowToDecryptXMLElementAsymmetric#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#6)] - -5. Call the method to decrypt the <`EncryptedData`> element. This method uses the RSA key to decrypt the session key and automatically uses the session key to decrypt the XML element. It also automatically replaces the <`EncryptedData`> element with the original plaintext. - + [!code-vb[HowToDecryptXMLElementAsymmetric#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#6)] + +5. Call the method to decrypt the <`EncryptedData`> element. This method uses the RSA key to decrypt the session key and automatically uses the session key to decrypt the XML element. It also automatically replaces the <`EncryptedData`> element with the original plaintext. + [!code-csharp[HowToDecryptXMLElementAsymmetric#7](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/cs/sample.cs#7)] - [!code-vb[HowToDecryptXMLElementAsymmetric#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#7)] - -6. Save the XML document. - + [!code-vb[HowToDecryptXMLElementAsymmetric#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#7)] + +6. Save the XML document. + [!code-csharp[HowToDecryptXMLElementAsymmetric#8](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/cs/sample.cs#8)] - [!code-vb[HowToDecryptXMLElementAsymmetric#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#8)] - + [!code-vb[HowToDecryptXMLElementAsymmetric#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#8)] + ## Example -This example assumes that a file named `test.xml` exists in the same directory as the compiled program. It also assumes that `test.xml` contains an XML element that was encrypted using the techniques described in [How to: Encrypt XML Elements with Asymmetric Keys](how-to-encrypt-xml-elements-with-asymmetric-keys.md). - +This example assumes that a file named `test.xml` exists in the same directory as the compiled program. It also assumes that `test.xml` contains an XML element that was encrypted using the techniques described in [How to: Encrypt XML Elements with Asymmetric Keys](how-to-encrypt-xml-elements-with-asymmetric-keys.md). + [!code-csharp[HowToDecryptXMLElementAsymmetric#1](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/cs/sample.cs#1)] -[!code-vb[HowToDecryptXMLElementAsymmetric#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#1)] - -## Compiling the Code - +[!code-vb[HowToDecryptXMLElementAsymmetric#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementAsymmetric/vb/sample.vb#1)] + +## Compiling the Code + - In a project that targets .NET Framework, include a reference to `System.Security.dll`. - In a project that targets .NET Core or .NET 5, install NuGet package [System.Security.Cryptography.Xml](https://www.nuget.org/packages/System.Security.Cryptography.Xml). - -- Include the following namespaces: , , and . - -## .NET Security - -Never store a symmetric cryptographic key in plaintext or transfer a symmetric key between machines in plaintext. Additionally, never store or transfer the private key of an asymmetric key pair in plaintext. For more information about symmetric and asymmetric cryptographic keys, see [Generating Keys for Encryption and Decryption](generating-keys-for-encryption-and-decryption.md). - - Never embed a key directly into your source code. Embedded keys can be easily read from an assembly by using [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) or by opening the assembly in a text editor such as Notepad. - - When you are done using a cryptographic key, clear it from memory by setting each byte to zero or by calling the method of the managed cryptography class. Cryptographic keys can sometimes be read from memory by a debugger or read from a hard drive if the memory location is paged to disk. - + +- Include the following namespaces: , , and . + +## .NET Security + +Never store a symmetric cryptographic key in plaintext or transfer a symmetric key between machines in plaintext. Additionally, never store or transfer the private key of an asymmetric key pair in plaintext. For more information about symmetric and asymmetric cryptographic keys, see [Generating Keys for Encryption and Decryption](generating-keys-for-encryption-and-decryption.md). + + Never embed a key directly into your source code. Embedded keys can be easily read from an assembly by using [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) or by opening the assembly in a text editor such as Notepad. + + When you are done using a cryptographic key, clear it from memory by setting each byte to zero or by calling the method of the managed cryptography class. Cryptographic keys can sometimes be read from memory by a debugger or read from a hard drive if the memory location is paged to disk. + ## See also - [Cryptography Model](cryptography-model.md) diff --git a/docs/standard/security/how-to-decrypt-xml-elements-with-symmetric-keys.md b/docs/standard/security/how-to-decrypt-xml-elements-with-symmetric-keys.md index 681a930dc4824..d679e034cd83c 100644 --- a/docs/standard/security/how-to-decrypt-xml-elements-with-symmetric-keys.md +++ b/docs/standard/security/how-to-decrypt-xml-elements-with-symmetric-keys.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Decrypt XML Elements with Symmetric Keys" title: "How to: Decrypt XML Elements with Symmetric Keys" ms.date: 07/14/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "symmetric keys" - "System.Security.Cryptography.EncryptedXml class" - "System.Security.Cryptography.Aes class" @@ -16,67 +16,67 @@ ms.assetid: 6038aff0-f92c-4e29-a618-d793410410d8 # How to: Decrypt XML Elements with Symmetric Keys You can use the classes in the namespace to encrypt an element within an XML document. XML Encryption allows you to store or transport sensitive XML, without worrying about the data being easily read. This code example decrypts an XML element using the Advanced Encryption Standard (AES) algorithm. - - For information about how to encrypt an XML element using this procedure, see [How to: Encrypt XML Elements with Symmetric Keys](how-to-encrypt-xml-elements-with-symmetric-keys.md). - - When you use a symmetric algorithm like AES to encrypt XML data, you must use the same key to encrypt and decrypt the XML data. The example in this procedure assumes that the encrypted XML was encrypted using the same key, and that the encrypting and decrypting parties agree on the algorithm and key to use. This example does not store or encrypt the AES key within the encrypted XML. - - This example is appropriate for situations where a single application needs to encrypt data based on a session key stored in memory, or based on a cryptographically strong key derived from a password. For situations where two or more applications need to share encrypted XML data, consider using an encryption scheme based on an asymmetric algorithm or an X.509 certificate. - -### To decrypt an XML element with a symmetric key - -1. Encrypt an XML element with the previously generated key using the techniques described in [How to: Encrypt XML Elements with Symmetric Keys](how-to-encrypt-xml-elements-with-symmetric-keys.md). - -2. Find the <`EncryptedData`> element (defined by the XML Encryption standard) in an object that contains the encrypted XML and create a new object to represent that element. - + + For information about how to encrypt an XML element using this procedure, see [How to: Encrypt XML Elements with Symmetric Keys](how-to-encrypt-xml-elements-with-symmetric-keys.md). + + When you use a symmetric algorithm like AES to encrypt XML data, you must use the same key to encrypt and decrypt the XML data. The example in this procedure assumes that the encrypted XML was encrypted using the same key, and that the encrypting and decrypting parties agree on the algorithm and key to use. This example does not store or encrypt the AES key within the encrypted XML. + + This example is appropriate for situations where a single application needs to encrypt data based on a session key stored in memory, or based on a cryptographically strong key derived from a password. For situations where two or more applications need to share encrypted XML data, consider using an encryption scheme based on an asymmetric algorithm or an X.509 certificate. + +### To decrypt an XML element with a symmetric key + +1. Encrypt an XML element with the previously generated key using the techniques described in [How to: Encrypt XML Elements with Symmetric Keys](how-to-encrypt-xml-elements-with-symmetric-keys.md). + +2. Find the <`EncryptedData`> element (defined by the XML Encryption standard) in an object that contains the encrypted XML and create a new object to represent that element. + [!code-csharp[HowToEncryptXMLElementSymmetric#10](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#10)] - [!code-vb[HowToEncryptXMLElementSymmetric#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#10)] - -3. Create an object by loading the raw XML data from the previously created object. - + [!code-vb[HowToEncryptXMLElementSymmetric#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#10)] + +3. Create an object by loading the raw XML data from the previously created object. + [!code-csharp[HowToEncryptXMLElementSymmetric#11](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#11)] - [!code-vb[HowToEncryptXMLElementSymmetric#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#11)] - -4. Create a new object and use it to decrypt the XML data using the same key that was used for encryption. - + [!code-vb[HowToEncryptXMLElementSymmetric#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#11)] + +4. Create a new object and use it to decrypt the XML data using the same key that was used for encryption. + [!code-csharp[HowToEncryptXMLElementSymmetric#12](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#12)] - [!code-vb[HowToEncryptXMLElementSymmetric#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#12)] - -5. Replace the encrypted element with the newly decrypted plaintext element within the XML document. - + [!code-vb[HowToEncryptXMLElementSymmetric#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#12)] + +5. Replace the encrypted element with the newly decrypted plaintext element within the XML document. + [!code-csharp[HowToEncryptXMLElementSymmetric#13](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#13)] - [!code-vb[HowToEncryptXMLElementSymmetric#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#13)] - -## Example - - This example assumes that a file named `"test.xml"` exists in the same directory as the compiled program. It also assumes that `"test.xml"` contains a `"creditcard"` element. You can place the following XML into a file called `test.xml` and use it with this example. - -```xml - - - 19834209 - 02/02/2002 - - -``` - + [!code-vb[HowToEncryptXMLElementSymmetric#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#13)] + +## Example + + This example assumes that a file named `"test.xml"` exists in the same directory as the compiled program. It also assumes that `"test.xml"` contains a `"creditcard"` element. You can place the following XML into a file called `test.xml` and use it with this example. + +```xml + + + 19834209 + 02/02/2002 + + +``` + [!code-csharp[HowToEncryptXMLElementSymmetric#1](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#1)] - [!code-vb[HowToEncryptXMLElementSymmetric#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#1)] - -## Compiling the Code - + [!code-vb[HowToEncryptXMLElementSymmetric#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#1)] + +## Compiling the Code + - In a project that targets .NET Framework, include a reference to `System.Security.dll`. - In a project that targets .NET Core or .NET 5, install NuGet package [System.Security.Cryptography.Xml](https://www.nuget.org/packages/System.Security.Cryptography.Xml). - -- Include the following namespaces: , , and . - + +- Include the following namespaces: , , and . + ## .NET Security - -Never store a cryptographic key in plaintext or transfer a key between machines in plaintext. - -When you are done using a symmetric cryptographic key, clear it from memory by setting each byte to zero or by calling the method of the managed cryptography class. - + +Never store a cryptographic key in plaintext or transfer a key between machines in plaintext. + +When you are done using a symmetric cryptographic key, clear it from memory by setting each byte to zero or by calling the method of the managed cryptography class. + ## See also - [Cryptography Model](cryptography-model.md) diff --git a/docs/standard/security/how-to-decrypt-xml-elements-with-x-509-certificates.md b/docs/standard/security/how-to-decrypt-xml-elements-with-x-509-certificates.md index c0f7f216cfa1e..0cb686d6b9815 100644 --- a/docs/standard/security/how-to-decrypt-xml-elements-with-x-509-certificates.md +++ b/docs/standard/security/how-to-decrypt-xml-elements-with-x-509-certificates.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Decrypt XML Elements with X.509 Certificates" title: "How to: Decrypt XML Elements with X.509 Certificates" ms.date: 07/14/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "System.Security.Cryptography.EncryptedXml class" - "XML encryption" - "System.Security.Cryptography.X509Certificate2 class" @@ -16,64 +16,64 @@ ms.assetid: bd015722-d88d-408d-8ca8-e4e475c441ed --- # How to: Decrypt XML Elements with X.509 Certificates -You can use the classes in the namespace to encrypt and decrypt an element within an XML document. XML Encryption is a standard way to exchange or store encrypted XML data, without worrying about the data being easily read. For more information about the XML Encryption standard, see the World Wide Web Consortium (W3C) specification for XML Encryption located at . - - This example decrypts an XML element that was encrypted using the methods described in: [How to: Encrypt XML Elements with X.509 Certificates](how-to-encrypt-xml-elements-with-x-509-certificates.md). It finds an <`EncryptedData`> element, decrypts the element, and then replaces the element with the original plaintext XML element. - -The code example in this procedure decrypts an XML element using an X.509 certificate from the local certificate store of the current user account. The example uses the method to automatically retrieve the X.509 certificate and decrypt a session key stored in the <`EncryptedKey`> element of the <`EncryptedData`> element. The method then automatically uses the session key to decrypt the XML element. - -This example is appropriate for situations where multiple applications need to share encrypted data or where an application needs to save encrypted data between the times that it runs. - -### To decrypt an XML element with an X.509 certificate - -1. Create an object by loading an XML file from disk. The object contains the XML element to decrypt. - +You can use the classes in the namespace to encrypt and decrypt an element within an XML document. XML Encryption is a standard way to exchange or store encrypted XML data, without worrying about the data being easily read. For more information about the XML Encryption standard, see the World Wide Web Consortium (W3C) specification for XML Encryption located at . + + This example decrypts an XML element that was encrypted using the methods described in: [How to: Encrypt XML Elements with X.509 Certificates](how-to-encrypt-xml-elements-with-x-509-certificates.md). It finds an <`EncryptedData`> element, decrypts the element, and then replaces the element with the original plaintext XML element. + +The code example in this procedure decrypts an XML element using an X.509 certificate from the local certificate store of the current user account. The example uses the method to automatically retrieve the X.509 certificate and decrypt a session key stored in the <`EncryptedKey`> element of the <`EncryptedData`> element. The method then automatically uses the session key to decrypt the XML element. + +This example is appropriate for situations where multiple applications need to share encrypted data or where an application needs to save encrypted data between the times that it runs. + +### To decrypt an XML element with an X.509 certificate + +1. Create an object by loading an XML file from disk. The object contains the XML element to decrypt. + [!code-csharp[HowToDecryptXMLElementX509#2](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToDecryptXMLElementX509/cs/sample.cs#2)] - [!code-vb[HowToDecryptXMLElementX509#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementX509/vb/sample.vb#2)] - -2. Create a new object by passing the object to the constructor. - + [!code-vb[HowToDecryptXMLElementX509#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementX509/vb/sample.vb#2)] + +2. Create a new object by passing the object to the constructor. + [!code-csharp[HowToDecryptXMLElementX509#3](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToDecryptXMLElementX509/cs/sample.cs#3)] - [!code-vb[HowToDecryptXMLElementX509#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementX509/vb/sample.vb#3)] - -3. Decrypt the XML document using the method. - + [!code-vb[HowToDecryptXMLElementX509#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementX509/vb/sample.vb#3)] + +3. Decrypt the XML document using the method. + [!code-csharp[HowToDecryptXMLElementX509#4](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToDecryptXMLElementX509/cs/sample.cs#4)] - [!code-vb[HowToDecryptXMLElementX509#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementX509/vb/sample.vb#4)] - -4. Save the object. - + [!code-vb[HowToDecryptXMLElementX509#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementX509/vb/sample.vb#4)] + +4. Save the object. + [!code-csharp[HowToDecryptXMLElementX509#5](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToDecryptXMLElementX509/cs/sample.cs#5)] - [!code-vb[HowToDecryptXMLElementX509#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementX509/vb/sample.vb#5)] - + [!code-vb[HowToDecryptXMLElementX509#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementX509/vb/sample.vb#5)] + ## Example -This example assumes that a file named `"test.xml"` exists in the same directory as the compiled program. It also assumes that `"test.xml"` contains a `"creditcard"` element. You can place the following XML into a file called `test.xml` and use it with this example. - -```xml - - - 19834209 - 02/02/2002 - - -``` - +This example assumes that a file named `"test.xml"` exists in the same directory as the compiled program. It also assumes that `"test.xml"` contains a `"creditcard"` element. You can place the following XML into a file called `test.xml` and use it with this example. + +```xml + + + 19834209 + 02/02/2002 + + +``` + [!code-csharp[HowToDecryptXMLElementX509#1](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToDecryptXMLElementX509/cs/sample.cs#1)] -[!code-vb[HowToDecryptXMLElementX509#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementX509/vb/sample.vb#1)] - -## Compiling the Code - +[!code-vb[HowToDecryptXMLElementX509#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToDecryptXMLElementX509/vb/sample.vb#1)] + +## Compiling the Code + - In a project that targets .NET Framework, include a reference to `System.Security.dll`. - In a project that targets .NET Core or .NET 5, install NuGet package [System.Security.Cryptography.Xml](https://www.nuget.org/packages/System.Security.Cryptography.Xml). -- Include the following namespaces: , , and . - +- Include the following namespaces: , , and . + ## .NET Security -The X.509 certificate used in this example is for test purposes only. Applications should use an X.509 certificate generated by a trusted certificate authority. - +The X.509 certificate used in this example is for test purposes only. Applications should use an X.509 certificate generated by a trusted certificate authority. + ## See also - [Cryptography Model](cryptography-model.md) diff --git a/docs/standard/security/how-to-encrypt-xml-elements-with-asymmetric-keys.md b/docs/standard/security/how-to-encrypt-xml-elements-with-asymmetric-keys.md index e3b92a29b886b..549303ca3540d 100644 --- a/docs/standard/security/how-to-encrypt-xml-elements-with-asymmetric-keys.md +++ b/docs/standard/security/how-to-encrypt-xml-elements-with-asymmetric-keys.md @@ -2,10 +2,10 @@ description: "Learn how to encrypt XML elements with asymmetric keys." title: "Encrypt XML elements with asymmetric keys" ms.date: 06/10/2021 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "cryptography [.NET], asymmetric keys" - "AES algorithm" - "System.Security.Cryptography.RSA class" @@ -30,39 +30,39 @@ To decrypt the XML element, you retrieve the RSA private key from the key contai This example is appropriate for situations where multiple applications need to share encrypted data or where an application needs to save encrypted data between the times that it runs. -### To encrypt an XML element with an asymmetric key +### To encrypt an XML element with an asymmetric key 1. Create a object and specify the name of the key container. [!code-csharp[HowToEncryptXMLElementAsymmetric#2](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/cs/sample.cs#2)] - [!code-vb[HowToEncryptXMLElementAsymmetric#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#2)] + [!code-vb[HowToEncryptXMLElementAsymmetric#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#2)] 2. Generate an asymmetric key using the class. The key is automatically saved to the key container when you pass the object to the constructor of the class. This key will be used to encrypt the AES session key and can be retrieved later to decrypt it. [!code-csharp[HowToEncryptXMLElementAsymmetric#3](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/cs/sample.cs#3)] - [!code-vb[HowToEncryptXMLElementAsymmetric#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#3)] + [!code-vb[HowToEncryptXMLElementAsymmetric#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#3)] 3. Create an object by loading an XML file from disk. The object contains the XML element to encrypt. [!code-csharp[HowToEncryptXMLElementAsymmetric#4](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/cs/sample.cs#4)] - [!code-vb[HowToEncryptXMLElementAsymmetric#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#4)] + [!code-vb[HowToEncryptXMLElementAsymmetric#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#4)] 4. Find the specified element in the object and create a new object to represent the element you want to encrypt. In this example, the `"creditcard"` element is encrypted. [!code-csharp[HowToEncryptXMLElementAsymmetric#5](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/cs/sample.cs#5)] - [!code-vb[HowToEncryptXMLElementAsymmetric#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#5)] + [!code-vb[HowToEncryptXMLElementAsymmetric#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#5)] 5. Create a new session key using the class. This key will encrypt the XML element, and then be encrypted itself and placed in the XML document. [!code-csharp[HowToEncryptXMLElementAsymmetric#6](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/cs/sample.cs#6)] - [!code-vb[HowToEncryptXMLElementAsymmetric#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#6)] + [!code-vb[HowToEncryptXMLElementAsymmetric#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#6)] -6. Create a new instance of the class and use it to encrypt the specified element using the session key. The method returns the encrypted element as an array of encrypted bytes. +6. Create a new instance of the class and use it to encrypt the specified element using the session key. The method returns the encrypted element as an array of encrypted bytes. [!code-csharp[HowToEncryptXMLElementAsymmetric#7](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/cs/sample.cs#7)] - [!code-vb[HowToEncryptXMLElementAsymmetric#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#7)] + [!code-vb[HowToEncryptXMLElementAsymmetric#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#7)] -7. Construct an object and populate it with the URL identifier of the encrypted XML element. This URL identifier lets a decrypting party know that the XML contains an encrypted element. You can use the field to specify the URL identifier. The plaintext XML element will be replaced by an `` element encapsulated by this object. +7. Construct an object and populate it with the URL identifier of the encrypted XML element. This URL identifier lets a decrypting party know that the XML contains an encrypted element. You can use the field to specify the URL identifier. The plaintext XML element will be replaced by an `` element encapsulated by this object. [!code-csharp[HowToEncryptXMLElementAsymmetric#8](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/cs/sample.cs#8)] [!code-vb[HowToEncryptXMLElementAsymmetric#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/vb/sample.vb#8)] @@ -111,13 +111,13 @@ This example is appropriate for situations where multiple applications need to s This example assumes that a file named `"test.xml"` exists in the same directory as the compiled program. It also assumes that `"test.xml"` contains a `"creditcard"` element. You can place the following XML into a file called `test.xml` and use it with this example. -```xml - - - 19834209 - 02/02/2002 - - +```xml + + + 19834209 + 02/02/2002 + + ``` [!code-csharp[HowToEncryptXMLElementAsymmetric#1](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementAsymmetric/cs/sample.cs#1)] @@ -138,7 +138,7 @@ Never store a symmetric cryptographic key in plaintext or transfer a symmetric k Never embed a key directly into your source code. Embedded keys can be easily read from an assembly using the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) or by opening the assembly in a text editor such as Notepad. -When you are done using a cryptographic key, clear it from memory by setting each byte to zero or by calling the method of the managed cryptography class. Cryptographic keys can sometimes be read from memory by a debugger or read from a hard drive if the memory location is paged to disk. +When you are done using a cryptographic key, clear it from memory by setting each byte to zero or by calling the method of the managed cryptography class. Cryptographic keys can sometimes be read from memory by a debugger or read from a hard drive if the memory location is paged to disk. ## See also diff --git a/docs/standard/security/how-to-encrypt-xml-elements-with-symmetric-keys.md b/docs/standard/security/how-to-encrypt-xml-elements-with-symmetric-keys.md index 6ff07a30aa83a..ab9da75ee4c3b 100644 --- a/docs/standard/security/how-to-encrypt-xml-elements-with-symmetric-keys.md +++ b/docs/standard/security/how-to-encrypt-xml-elements-with-symmetric-keys.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Encrypt XML Elements with Symmetric Keys" title: "How to: Encrypt XML Elements with Symmetric Keys" ms.date: 07/14/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "AES algorithm" - "cryptography [.NET], symmetric keys" - "encryption [.NET], symmetric keys" @@ -18,84 +18,84 @@ ms.assetid: d8461a44-aa2c-4ef4-b3e4-ab7cbaaee1b5 --- # How to: Encrypt XML Elements with Symmetric Keys -You can use the classes in the namespace to encrypt an element within an XML document. XML Encryption allows you to store or transport sensitive XML, without worrying about the data being easily read. This procedure encrypts an XML element using the Advanced Encryption Standard (AES) algorithm. - - For information about how to decrypt an XML element that was encrypted using this procedure, see [How to: Decrypt XML Elements with Symmetric Keys](how-to-decrypt-xml-elements-with-symmetric-keys.md). - - When you use a symmetric algorithm like AES to encrypt XML data, you must use the same key to encrypt and decrypt the XML data. The example in this procedure assumes that the encrypted XML will be decrypted using the same key, and that the encrypting and decrypting parties agree on the algorithm and key to use. This example does not store or encrypt the AES key within the encrypted XML. - - This example is appropriate for situations where a single application needs to encrypt data based on a session key stored in memory, or based on a cryptographically strong key derived from a password. For situations where two or more applications need to share encrypted XML data, consider using an encryption scheme based on an asymmetric algorithm or an X.509 certificate. - -### To encrypt an XML element with a symmetric key - -1. Generate a symmetric key using the class. This key will be used to encrypt the XML element. - +You can use the classes in the namespace to encrypt an element within an XML document. XML Encryption allows you to store or transport sensitive XML, without worrying about the data being easily read. This procedure encrypts an XML element using the Advanced Encryption Standard (AES) algorithm. + + For information about how to decrypt an XML element that was encrypted using this procedure, see [How to: Decrypt XML Elements with Symmetric Keys](how-to-decrypt-xml-elements-with-symmetric-keys.md). + + When you use a symmetric algorithm like AES to encrypt XML data, you must use the same key to encrypt and decrypt the XML data. The example in this procedure assumes that the encrypted XML will be decrypted using the same key, and that the encrypting and decrypting parties agree on the algorithm and key to use. This example does not store or encrypt the AES key within the encrypted XML. + + This example is appropriate for situations where a single application needs to encrypt data based on a session key stored in memory, or based on a cryptographically strong key derived from a password. For situations where two or more applications need to share encrypted XML data, consider using an encryption scheme based on an asymmetric algorithm or an X.509 certificate. + +### To encrypt an XML element with a symmetric key + +1. Generate a symmetric key using the class. This key will be used to encrypt the XML element. + [!code-csharp[HowToEncryptXMLElementSymmetric#2](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#2)] - [!code-vb[HowToEncryptXMLElementSymmetric#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#2)] - -2. Create an object by loading an XML file from disk. The object contains the XML element to encrypt. - + [!code-vb[HowToEncryptXMLElementSymmetric#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#2)] + +2. Create an object by loading an XML file from disk. The object contains the XML element to encrypt. + [!code-csharp[HowToEncryptXMLElementSymmetric#3](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#3)] - [!code-vb[HowToEncryptXMLElementSymmetric#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#3)] - -3. Find the specified element in the object and create a new object to represent the element you want to encrypt. In this example, the `"creditcard"` element is encrypted. - + [!code-vb[HowToEncryptXMLElementSymmetric#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#3)] + +3. Find the specified element in the object and create a new object to represent the element you want to encrypt. In this example, the `"creditcard"` element is encrypted. + [!code-csharp[HowToEncryptXMLElementSymmetric#4](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#4)] - [!code-vb[HowToEncryptXMLElementSymmetric#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#4)] - -4. Create a new instance of the class and use it to encrypt the with the symmetric key. The method returns the encrypted element as an array of encrypted bytes. - + [!code-vb[HowToEncryptXMLElementSymmetric#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#4)] + +4. Create a new instance of the class and use it to encrypt the with the symmetric key. The method returns the encrypted element as an array of encrypted bytes. + [!code-csharp[HowToEncryptXMLElementSymmetric#5](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#5)] - [!code-vb[HowToEncryptXMLElementSymmetric#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#5)] - -5. Construct an object and populate it with the URL identifier of the XML Encryption element. This URL identifier lets a decrypting party know that the XML contains an encrypted element. You can use the field to specify the URL identifier. - + [!code-vb[HowToEncryptXMLElementSymmetric#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#5)] + +5. Construct an object and populate it with the URL identifier of the XML Encryption element. This URL identifier lets a decrypting party know that the XML contains an encrypted element. You can use the field to specify the URL identifier. + [!code-csharp[HowToEncryptXMLElementSymmetric#6](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#6)] - [!code-vb[HowToEncryptXMLElementSymmetric#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#6)] - -6. Create an object that is initialized to the URL identifier of the cryptographic algorithm used to generate the key. Pass the object to the property. - + [!code-vb[HowToEncryptXMLElementSymmetric#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#6)] + +6. Create an object that is initialized to the URL identifier of the cryptographic algorithm used to generate the key. Pass the object to the property. + [!code-csharp[HowToEncryptXMLElementSymmetric#7](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#7)] - [!code-vb[HowToEncryptXMLElementSymmetric#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#7)] - -7. Add the encrypted element data to the object. - + [!code-vb[HowToEncryptXMLElementSymmetric#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#7)] + +7. Add the encrypted element data to the object. + [!code-csharp[HowToEncryptXMLElementSymmetric#8](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#8)] - [!code-vb[HowToEncryptXMLElementSymmetric#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#8)] - -8. Replace the element from the original object with the element. - + [!code-vb[HowToEncryptXMLElementSymmetric#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#8)] + +8. Replace the element from the original object with the element. + [!code-csharp[HowToEncryptXMLElementSymmetric#9](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#9)] - [!code-vb[HowToEncryptXMLElementSymmetric#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#9)] - -## Example - -```xml - - - 19834209 - 02/02/2002 - - -``` - + [!code-vb[HowToEncryptXMLElementSymmetric#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#9)] + +## Example + +```xml + + + 19834209 + 02/02/2002 + + +``` + [!code-csharp[HowToEncryptXMLElementSymmetric#1](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/cs/sample.cs#1)] - [!code-vb[HowToEncryptXMLElementSymmetric#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#1)] - -## Compiling the Code - + [!code-vb[HowToEncryptXMLElementSymmetric#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementSymmetric/vb/sample.vb#1)] + +## Compiling the Code + - In a project that targets .NET Framework, include a reference to `System.Security.dll`. - In a project that targets .NET Core or .NET 5, install NuGet package [System.Security.Cryptography.Xml](https://www.nuget.org/packages/System.Security.Cryptography.Xml). - -- Include the following namespaces: , , and . - + +- Include the following namespaces: , , and . + ## .NET Security -Never store a cryptographic key in plaintext or transfer a key between machines in plaintext. Instead, use a secure key container to store cryptographic keys. - -When you are done using a cryptographic key, clear it from memory by setting each byte to zero or by calling the method of the managed cryptography class. - +Never store a cryptographic key in plaintext or transfer a key between machines in plaintext. Instead, use a secure key container to store cryptographic keys. + +When you are done using a cryptographic key, clear it from memory by setting each byte to zero or by calling the method of the managed cryptography class. + ## See also - [Cryptography Model](cryptography-model.md) - Describes how cryptography is implemented in the base class library. diff --git a/docs/standard/security/how-to-encrypt-xml-elements-with-x-509-certificates.md b/docs/standard/security/how-to-encrypt-xml-elements-with-x-509-certificates.md index a98938d40e201..4f0a7710c62c7 100644 --- a/docs/standard/security/how-to-encrypt-xml-elements-with-x-509-certificates.md +++ b/docs/standard/security/how-to-encrypt-xml-elements-with-x-509-certificates.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Encrypt XML Elements with X.509 Certificates" title: "How to: Encrypt XML Elements with X.509 Certificates" ms.date: 07/14/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "encryption [.NET], X.509 certificates" - "cryptography [.NET], X.509 certificates" - "System.Security.Cryptography.EncryptedXml class" @@ -17,104 +17,104 @@ ms.assetid: 761f1c66-631c-47af-aa86-ad9c50cfa453 --- # How to: Encrypt XML Elements with X.509 Certificates -You can use the classes in the namespace to encrypt an element within an XML document. XML Encryption is a standard way to exchange or store encrypted XML data, without worrying about the data being easily read. For more information about the XML Encryption standard, see the World Wide Web Consortium (W3C) specification for XML Encryption located at . - - You can use XML Encryption to replace any XML element or document with an <`EncryptedData`> element that contains the encrypted XML data. The <`EncryptedData`> element can contain sub elements that include information about the keys and processes used during encryption. XML Encryption allows a document to contain multiple encrypted elements and allows an element to be encrypted multiple times. The code example in this procedure shows you how to create an <`EncryptedData`> element along with several other sub elements that you can use later during decryption. - -This example encrypts an XML element using two keys. The example programmatically retrieves a certificate and uses it to encrypt an XML element using the method. Internally, the method creates a separate session key and uses it to encrypt the XML document. This method encrypts the session key and saves it along with the encrypted XML within a new <`EncryptedData`> element. +You can use the classes in the namespace to encrypt an element within an XML document. XML Encryption is a standard way to exchange or store encrypted XML data, without worrying about the data being easily read. For more information about the XML Encryption standard, see the World Wide Web Consortium (W3C) specification for XML Encryption located at . -To decrypt the XML element, call the method, which automatically retrieves the X.509 certificate from the store and performs the necessary decryption. For more information about how to decrypt an XML element that was encrypted using this procedure, see [How to: Decrypt XML Elements with X.509 Certificates](how-to-decrypt-xml-elements-with-x-509-certificates.md). - -This example is appropriate for situations where multiple applications need to share encrypted data or where an application needs to save encrypted data between the times that it runs. - -### To encrypt an XML element with an X.509 certificate + You can use XML Encryption to replace any XML element or document with an <`EncryptedData`> element that contains the encrypted XML data. The <`EncryptedData`> element can contain sub elements that include information about the keys and processes used during encryption. XML Encryption allows a document to contain multiple encrypted elements and allows an element to be encrypted multiple times. The code example in this procedure shows you how to create an <`EncryptedData`> element along with several other sub elements that you can use later during decryption. + +This example encrypts an XML element using two keys. The example programmatically retrieves a certificate and uses it to encrypt an XML element using the method. Internally, the method creates a separate session key and uses it to encrypt the XML document. This method encrypts the session key and saves it along with the encrypted XML within a new <`EncryptedData`> element. + +To decrypt the XML element, call the method, which automatically retrieves the X.509 certificate from the store and performs the necessary decryption. For more information about how to decrypt an XML element that was encrypted using this procedure, see [How to: Decrypt XML Elements with X.509 Certificates](how-to-decrypt-xml-elements-with-x-509-certificates.md). + +This example is appropriate for situations where multiple applications need to share encrypted data or where an application needs to save encrypted data between the times that it runs. + +### To encrypt an XML element with an X.509 certificate To run this example, you need to create a test certificate and save it in a certificate store. Instructions for that task are provided only for the Windows [Certificate Creation Tool (Makecert.exe)](/windows/desktop/SecCrypto/makecert). -1. Use [Makecert.exe](/windows/desktop/SecCrypto/makecert) to generate a test X.509 certificate and place it in the local user store. You must generate an exchange key and you must make the key exportable. Run the following command: - - ```console - makecert -r -pe -n "CN=XML_ENC_TEST_CERT" -b 01/01/2020 -e 01/01/2025 -sky exchange -ss my - ``` - -2. Create an object and initialize it to open the current user store. - +1. Use [Makecert.exe](/windows/desktop/SecCrypto/makecert) to generate a test X.509 certificate and place it in the local user store. You must generate an exchange key and you must make the key exportable. Run the following command: + + ```console + makecert -r -pe -n "CN=XML_ENC_TEST_CERT" -b 01/01/2020 -e 01/01/2025 -sky exchange -ss my + ``` + +2. Create an object and initialize it to open the current user store. + [!code-csharp[HowToEncryptXMLElementX509#2](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementX509/cs/sample.cs#2)] - [!code-vb[HowToEncryptXMLElementX509#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#2)] - -3. Open the store in read-only mode. - + [!code-vb[HowToEncryptXMLElementX509#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#2)] + +3. Open the store in read-only mode. + [!code-csharp[HowToEncryptXMLElementX509#3](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementX509/cs/sample.cs#3)] - [!code-vb[HowToEncryptXMLElementX509#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#3)] - -4. Initialize an with all of the certificates in the store. - + [!code-vb[HowToEncryptXMLElementX509#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#3)] + +4. Initialize an with all of the certificates in the store. + [!code-csharp[HowToEncryptXMLElementX509#4](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementX509/cs/sample.cs#4)] - [!code-vb[HowToEncryptXMLElementX509#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#4)] - -5. Enumerate through the certificates in the store and find the certificate with the appropriate name. In this example, the certificate is named `"CN=XML_ENC_TEST_CERT"`. - + [!code-vb[HowToEncryptXMLElementX509#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#4)] + +5. Enumerate through the certificates in the store and find the certificate with the appropriate name. In this example, the certificate is named `"CN=XML_ENC_TEST_CERT"`. + [!code-csharp[HowToEncryptXMLElementX509#5](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementX509/cs/sample.cs#5)] - [!code-vb[HowToEncryptXMLElementX509#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#5)] - -6. Close the store after the certificate is located. - + [!code-vb[HowToEncryptXMLElementX509#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#5)] + +6. Close the store after the certificate is located. + [!code-csharp[HowToEncryptXMLElementX509#6](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementX509/cs/sample.cs#6)] - [!code-vb[HowToEncryptXMLElementX509#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#6)] - -7. Create an object by loading an XML file from disk. The object contains the XML element to encrypt. - + [!code-vb[HowToEncryptXMLElementX509#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#6)] + +7. Create an object by loading an XML file from disk. The object contains the XML element to encrypt. + [!code-csharp[HowToEncryptXMLElementX509#7](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementX509/cs/sample.cs#7)] - [!code-vb[HowToEncryptXMLElementX509#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#7)] - -8. Find the specified element in the object and create a new object to represent the element you want to encrypt. In this example, the `"creditcard"` element is encrypted. - + [!code-vb[HowToEncryptXMLElementX509#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#7)] + +8. Find the specified element in the object and create a new object to represent the element you want to encrypt. In this example, the `"creditcard"` element is encrypted. + [!code-csharp[HowToEncryptXMLElementX509#8](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementX509/cs/sample.cs#8)] - [!code-vb[HowToEncryptXMLElementX509#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#8)] - -9. Create a new instance of the class and use it to encrypt the specified element using the X.509 certificate. The method returns the encrypted element as an object. - + [!code-vb[HowToEncryptXMLElementX509#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#8)] + +9. Create a new instance of the class and use it to encrypt the specified element using the X.509 certificate. The method returns the encrypted element as an object. + [!code-csharp[HowToEncryptXMLElementX509#9](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementX509/cs/sample.cs#9)] - [!code-vb[HowToEncryptXMLElementX509#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#9)] - -10. Replace the element from the original object with the element. - + [!code-vb[HowToEncryptXMLElementX509#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#9)] + +10. Replace the element from the original object with the element. + [!code-csharp[HowToEncryptXMLElementX509#10](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementX509/cs/sample.cs#10)] - [!code-vb[HowToEncryptXMLElementX509#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#10)] - -11. Save the object. - + [!code-vb[HowToEncryptXMLElementX509#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#10)] + +11. Save the object. + [!code-csharp[HowToEncryptXMLElementX509#11](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementX509/cs/sample.cs#11)] - [!code-vb[HowToEncryptXMLElementX509#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#11)] - -## Example - - This example assumes that a file named `"test.xml"` exists in the same directory as the compiled program. It also assumes that `"test.xml"` contains a `"creditcard"` element. You can place the following XML into a file called `test.xml` and use it with this example. - -```xml - - - 19834209 - 02/02/2002 - - -``` - + [!code-vb[HowToEncryptXMLElementX509#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#11)] + +## Example + + This example assumes that a file named `"test.xml"` exists in the same directory as the compiled program. It also assumes that `"test.xml"` contains a `"creditcard"` element. You can place the following XML into a file called `test.xml` and use it with this example. + +```xml + + + 19834209 + 02/02/2002 + + +``` + [!code-csharp[HowToEncryptXMLElementX509#1](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEncryptXMLElementX509/cs/sample.cs#1)] - [!code-vb[HowToEncryptXMLElementX509#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#1)] - -## Compiling the Code - + [!code-vb[HowToEncryptXMLElementX509#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEncryptXMLElementX509/vb/sample.vb#1)] + +## Compiling the Code + - In a project that targets .NET Framework, include a reference to `System.Security.dll`. - In a project that targets .NET Core or .NET 5, install NuGet package [System.Security.Cryptography.Xml](https://www.nuget.org/packages/System.Security.Cryptography.Xml). - -- Include the following namespaces: , , and . - + +- Include the following namespaces: , , and . + ## .NET Security - -The X.509 certificate used in this example is for test purposes only. Applications should use an X.509 certificate generated by a trusted certificate authority. - + +The X.509 certificate used in this example is for test purposes only. Applications should use an X.509 certificate generated by a trusted certificate authority. + ## See also - [Cryptography Model](cryptography-model.md) diff --git a/docs/standard/security/how-to-sign-xml-documents-with-digital-signatures.md b/docs/standard/security/how-to-sign-xml-documents-with-digital-signatures.md index 05735566a0359..c4ff6566e6088 100644 --- a/docs/standard/security/how-to-sign-xml-documents-with-digital-signatures.md +++ b/docs/standard/security/how-to-sign-xml-documents-with-digital-signatures.md @@ -2,10 +2,10 @@ title: "How to: Sign XML Documents with Digital Signatures" description: Learn how to sign XML documents with digital signatures. Use classes in the System.Security.Cryptography.Xml namespace in .NET. ms.date: 07/14/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "signatures, XML signing" - "System.Security.Cryptography.SignedXml class" - "digital signatures, XML signing" @@ -17,107 +17,107 @@ ms.assetid: 99692ac1-d8c9-42d7-b1bf-2737b01037e4 --- # How to: Sign XML Documents with Digital Signatures -You can use the classes in the namespace to sign an XML document or part of an XML document with a digital signature. XML digital signatures (XMLDSIG) allow you to verify that data was not altered after it was signed. For more information about the XMLDSIG standard, see the World Wide Web Consortium (W3C) recommendation [XML Signature Syntax and Processing](https://www.w3.org/TR/xmldsig-core/). - +You can use the classes in the namespace to sign an XML document or part of an XML document with a digital signature. XML digital signatures (XMLDSIG) allow you to verify that data was not altered after it was signed. For more information about the XMLDSIG standard, see the World Wide Web Consortium (W3C) recommendation [XML Signature Syntax and Processing](https://www.w3.org/TR/xmldsig-core/). + > [!NOTE] > The code in this article applies to Windows. -The code example in this procedure demonstrates how to digitally sign an entire XML document and attach the signature to the document in a <`Signature`> element. The example creates an RSA signing key, adds the key to a secure key container, and then uses the key to digitally sign an XML document. The key can then be retrieved to verify the XML digital signature, or can be used to sign another XML document. - -For information about how to verify an XML digital signature that was created using this procedure, see [How to: Verify the Digital Signatures of XML Documents](how-to-verify-the-digital-signatures-of-xml-documents.md). - -### To digitally sign an XML document - -1. Create a object and specify the name of the key container. - +The code example in this procedure demonstrates how to digitally sign an entire XML document and attach the signature to the document in a <`Signature`> element. The example creates an RSA signing key, adds the key to a secure key container, and then uses the key to digitally sign an XML document. The key can then be retrieved to verify the XML digital signature, or can be used to sign another XML document. + +For information about how to verify an XML digital signature that was created using this procedure, see [How to: Verify the Digital Signatures of XML Documents](how-to-verify-the-digital-signatures-of-xml-documents.md). + +### To digitally sign an XML document + +1. Create a object and specify the name of the key container. + [!code-csharp[HowToSignXMLDocumentRSA#2](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#2)] - [!code-vb[HowToSignXMLDocumentRSA#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#2)] - -2. Generate an asymmetric key using the class. The key is automatically saved to the key container when you pass the object to the constructor of the class. This key will be used to sign the XML document. - + [!code-vb[HowToSignXMLDocumentRSA#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#2)] + +2. Generate an asymmetric key using the class. The key is automatically saved to the key container when you pass the object to the constructor of the class. This key will be used to sign the XML document. + [!code-csharp[HowToSignXMLDocumentRSA#3](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#3)] - [!code-vb[HowToSignXMLDocumentRSA#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#3)] - -3. Create an object by loading an XML file from disk. The object contains the XML element to encrypt. - + [!code-vb[HowToSignXMLDocumentRSA#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#3)] + +3. Create an object by loading an XML file from disk. The object contains the XML element to encrypt. + [!code-csharp[HowToSignXMLDocumentRSA#4](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#4)] - [!code-vb[HowToSignXMLDocumentRSA#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#4)] - -4. Create a new object and pass the object to it. - + [!code-vb[HowToSignXMLDocumentRSA#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#4)] + +4. Create a new object and pass the object to it. + [!code-csharp[HowToSignXMLDocumentRSA#5](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#5)] - [!code-vb[HowToSignXMLDocumentRSA#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#5)] - -5. Add the signing RSA key to the object. - + [!code-vb[HowToSignXMLDocumentRSA#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#5)] + +5. Add the signing RSA key to the object. + [!code-csharp[HowToSignXMLDocumentRSA#6](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#6)] - [!code-vb[HowToSignXMLDocumentRSA#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#6)] - -6. Create a object that describes what to sign. To sign the entire document, set the property to `""`. - + [!code-vb[HowToSignXMLDocumentRSA#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#6)] + +6. Create a object that describes what to sign. To sign the entire document, set the property to `""`. + [!code-csharp[HowToSignXMLDocumentRSA#7](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#7)] - [!code-vb[HowToSignXMLDocumentRSA#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#7)] - -7. Add an object to the object. A transformation allows the verifier to represent the XML data in the identical manner that the signer used. XML data can be represented in different ways, so this step is vital to verification. - + [!code-vb[HowToSignXMLDocumentRSA#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#7)] + +7. Add an object to the object. A transformation allows the verifier to represent the XML data in the identical manner that the signer used. XML data can be represented in different ways, so this step is vital to verification. + [!code-csharp[HowToSignXMLDocumentRSA#8](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#8)] - [!code-vb[HowToSignXMLDocumentRSA#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#8)] - -8. Add the object to the object. - + [!code-vb[HowToSignXMLDocumentRSA#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#8)] + +8. Add the object to the object. + [!code-csharp[HowToSignXMLDocumentRSA#9](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#9)] - [!code-vb[HowToSignXMLDocumentRSA#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#9)] - -9. Compute the signature by calling the method. - + [!code-vb[HowToSignXMLDocumentRSA#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#9)] + +9. Compute the signature by calling the method. + [!code-csharp[HowToSignXMLDocumentRSA#10](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#10)] - [!code-vb[HowToSignXMLDocumentRSA#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#10)] - -10. Retrieve the XML representation of the signature (a <`Signature`> element) and save it to a new object. - + [!code-vb[HowToSignXMLDocumentRSA#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#10)] + +10. Retrieve the XML representation of the signature (a <`Signature`> element) and save it to a new object. + [!code-csharp[HowToSignXMLDocumentRSA#11](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#11)] - [!code-vb[HowToSignXMLDocumentRSA#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#11)] - -11. Append the element to the object. - + [!code-vb[HowToSignXMLDocumentRSA#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#11)] + +11. Append the element to the object. + [!code-csharp[HowToSignXMLDocumentRSA#12](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#12)] - [!code-vb[HowToSignXMLDocumentRSA#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#12)] - -12. Save the document. - + [!code-vb[HowToSignXMLDocumentRSA#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#12)] + +12. Save the document. + [!code-csharp[HowToSignXMLDocumentRSA#13](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#13)] - [!code-vb[HowToSignXMLDocumentRSA#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#13)] - -## Example - - This example assumes that a file named `test.xml` exists in the same directory as the compiled program. You can place the following XML into a file called `test.xml` and use it with this example. - -```xml - - - 19834209 - 02/02/2002 - - -``` - + [!code-vb[HowToSignXMLDocumentRSA#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#13)] + +## Example + + This example assumes that a file named `test.xml` exists in the same directory as the compiled program. You can place the following XML into a file called `test.xml` and use it with this example. + +```xml + + + 19834209 + 02/02/2002 + + +``` + [!code-csharp[HowToSignXMLDocumentRSA#1](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToSignXMLDocumentRSA/cs/sample.cs#1)] - [!code-vb[HowToSignXMLDocumentRSA#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#1)] - -## Compiling the Code - + [!code-vb[HowToSignXMLDocumentRSA#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToSignXMLDocumentRSA/vb/sample.vb#1)] + +## Compiling the Code + - In a project that targets .NET Framework, include a reference to `System.Security.dll`. - In a project that targets .NET Core or .NET 5, install NuGet package [System.Security.Cryptography.Xml](https://www.nuget.org/packages/System.Security.Cryptography.Xml). - -- Include the following namespaces: , , and . - + +- Include the following namespaces: , , and . + ## .NET Security -Never store or transfer the private key of an asymmetric key pair in plaintext. For more information about symmetric and asymmetric cryptographic keys, see [Generating Keys for Encryption and Decryption](generating-keys-for-encryption-and-decryption.md). - -Never embed a private key directly into your source code. Embedded keys can be easily read from an assembly using the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) or by opening the assembly in a text editor such as Notepad. - +Never store or transfer the private key of an asymmetric key pair in plaintext. For more information about symmetric and asymmetric cryptographic keys, see [Generating Keys for Encryption and Decryption](generating-keys-for-encryption-and-decryption.md). + +Never embed a private key directly into your source code. Embedded keys can be easily read from an assembly using the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) or by opening the assembly in a text editor such as Notepad. + ## See also - [Cryptography Model](cryptography-model.md) diff --git a/docs/standard/security/how-to-store-asymmetric-keys-in-a-key-container.md b/docs/standard/security/how-to-store-asymmetric-keys-in-a-key-container.md index 007aeff36f728..7010d6419513e 100644 --- a/docs/standard/security/how-to-store-asymmetric-keys-in-a-key-container.md +++ b/docs/standard/security/how-to-store-asymmetric-keys-in-a-key-container.md @@ -2,10 +2,10 @@ title: "How to: store asymmetric keys in a key container" description: Learn how to store asymmetric keys in a key container in .NET. See how to create an asymmetric key, save it in a key container, and retrieve and delete the key. ms.date: 05/26/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "cryptography [.NET], asymmetric keys" - "storing asymmetric keys" - "keys, asymmetric" @@ -33,8 +33,8 @@ Asymmetric private keys should never be stored verbatim or in plain text on the > [!NOTE] > The creation and retrieval of an asymmetric key is one operation. If a key is not already in the container, it's created before being returned. > -> - -> - +> - +> - ## Delete the key from the key container @@ -50,7 +50,7 @@ Asymmetric private keys should never be stored verbatim or in plain text on the The following example demonstrates how to create an asymmetric key, save it in a key container, retrieve the key at a later time, and delete the key from the container. -Notice that code in the `GenKey_SaveInContainer` method and the `GetKeyFromContainer` method is similar. When you specify a key container name for a object and pass it to an object with the property or property set to `true`, the behavior is as follows: +Notice that code in the `GenKey_SaveInContainer` method and the `GetKeyFromContainer` method is similar. When you specify a key container name for a object and pass it to an object with the property or property set to `true`, the behavior is as follows: - If a key container with the specified name does not exist, then one is created and the key is persisted. - If a key container with the specified name does exist, then the key in the container is automatically loaded into the current object. diff --git a/docs/standard/security/how-to-use-data-protection.md b/docs/standard/security/how-to-use-data-protection.md index df9a1441ad772..82d6a27053a4f 100644 --- a/docs/standard/security/how-to-use-data-protection.md +++ b/docs/standard/security/how-to-use-data-protection.md @@ -2,10 +2,10 @@ title: "How to: Use Data Protection" description: Learn how to use data protection by accessing the data protection API (DPAPI) in .NET. ms.date: 07/14/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "DPAPI" - "encryption [.NET], data protection API" - "data [.NET], decryption" @@ -24,39 +24,39 @@ ms.assetid: 606698b0-cb1a-42ca-beeb-0bea34205d20 > > For information about ASP.NET Core, see [ASP.NET Core Data Protection](/aspnet/core/security/data-protection/introduction). -.NET provides access to the data protection API (DPAPI), which allows you to encrypt data using information from the current user account or computer. When you use the DPAPI, you alleviate the difficult problem of explicitly generating and storing a cryptographic key. - -Use the class to encrypt a copy of an array of bytes. You can specify that data encrypted by the current user account can be decrypted only by the same user account, or you can specify that data encrypted by the current user account can be decrypted by any account on the computer. See the enumeration for a detailed description of options. - -## Encrypt data to a file or stream using data protection - -1. Create random entropy. - -2. Call the static method while passing an array of bytes to encrypt, the entropy, and the data protection scope. - -3. Write the encrypted data to a file or stream. - -### To decrypt data from a file or stream using data protection - -1. Read the encrypted data from a file or stream. - -2. Call the static method while passing an array of bytes to decrypt and the data protection scope. - +.NET provides access to the data protection API (DPAPI), which allows you to encrypt data using information from the current user account or computer. When you use the DPAPI, you alleviate the difficult problem of explicitly generating and storing a cryptographic key. + +Use the class to encrypt a copy of an array of bytes. You can specify that data encrypted by the current user account can be decrypted only by the same user account, or you can specify that data encrypted by the current user account can be decrypted by any account on the computer. See the enumeration for a detailed description of options. + +## Encrypt data to a file or stream using data protection + +1. Create random entropy. + +2. Call the static method while passing an array of bytes to encrypt, the entropy, and the data protection scope. + +3. Write the encrypted data to a file or stream. + +### To decrypt data from a file or stream using data protection + +1. Read the encrypted data from a file or stream. + +2. Call the static method while passing an array of bytes to decrypt and the data protection scope. + ## Example The following code example demonstrates two forms of encryption and decryption. First, the code example encrypts and then decrypts an in-memory array of bytes. Next, the code example encrypts a copy of a byte array, saves it to a file, loads the data back from the file, and then decrypts the data. The example displays the original data, the encrypted data, and the decrypted data. [!code-csharp[DPAPI-HowTO#1](../../../samples/snippets/csharp/VS_Snippets_CLR/DPAPI-HowTO/cs/sample.cs#1)] -[!code-vb[DPAPI-HowTO#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/DPAPI-HowTO/vb/sample.vb#1)] - -## Compiling the Code +[!code-vb[DPAPI-HowTO#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/DPAPI-HowTO/vb/sample.vb#1)] + +## Compiling the Code This example compiles and runs only when targeting .NET Framework and running on Windows. -- Include a reference to `System.Security.dll`. - -- Include the , , , and namespace. - +- Include a reference to `System.Security.dll`. + +- Include the , , , and namespace. + ## See also - [Cryptography Model](cryptography-model.md) diff --git a/docs/standard/security/how-to-verify-the-digital-signatures-of-xml-documents.md b/docs/standard/security/how-to-verify-the-digital-signatures-of-xml-documents.md index 23fe089060b6e..c1f282d9b3485 100644 --- a/docs/standard/security/how-to-verify-the-digital-signatures-of-xml-documents.md +++ b/docs/standard/security/how-to-verify-the-digital-signatures-of-xml-documents.md @@ -2,10 +2,10 @@ description: "Learn more about: How to: Verify the Digital Signatures of XML Documents" title: "How to: Verify the Digital Signatures of XML Documents" ms.date: 07/14/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "System.Security.Cryptography.SignedXml class" - "signatures, cryptographic" - "System.Security.Cryptography.RSA class" @@ -18,72 +18,72 @@ ms.assetid: a4d5ceb1-b9f5-47e8-9e4a-a2b39110002f # How to: Verify the Digital Signatures of XML Documents You can use the classes in the namespace to verify XML data signed with a digital signature. XML digital signatures (XMLDSIG) allow you to verify that data was not altered after it was signed. For more information about the XMLDSIG standard, see the World Wide Web Consortium (W3C) specification at . - + > [!NOTE] > The code in this article applies to Windows. -The code example in this procedure demonstrates how to verify an XML digital signature contained in a <`Signature`> element. The example retrieves an RSA public key from a key container and then uses the key to verify the signature. - +The code example in this procedure demonstrates how to verify an XML digital signature contained in a <`Signature`> element. The example retrieves an RSA public key from a key container and then uses the key to verify the signature. + For information about how to create a digital signature that can be verified using this technique, see [How to: Sign XML Documents with Digital Signatures](how-to-sign-xml-documents-with-digital-signatures.md). - -### To verify the digital signature of an XML document - -1. To verify the document, you must use the same asymmetric key that was used for signing. Create a object and specify the name of the key container that was used for signing. - + +### To verify the digital signature of an XML document + +1. To verify the document, you must use the same asymmetric key that was used for signing. Create a object and specify the name of the key container that was used for signing. + [!code-csharp[HowToVerifyXMLDocumentRSA#2](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/cs/sample.cs#2)] - [!code-vb[HowToVerifyXMLDocumentRSA#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#2)] - -2. Retrieve the public key using the class. The key is automatically loaded from the key container by name when you pass the object to the constructor of the class. - + [!code-vb[HowToVerifyXMLDocumentRSA#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#2)] + +2. Retrieve the public key using the class. The key is automatically loaded from the key container by name when you pass the object to the constructor of the class. + [!code-csharp[HowToVerifyXMLDocumentRSA#3](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/cs/sample.cs#3)] - [!code-vb[HowToVerifyXMLDocumentRSA#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#3)] - -3. Create an object by loading an XML file from disk. The object contains the signed XML document to verify. - + [!code-vb[HowToVerifyXMLDocumentRSA#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#3)] + +3. Create an object by loading an XML file from disk. The object contains the signed XML document to verify. + [!code-csharp[HowToVerifyXMLDocumentRSA#4](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/cs/sample.cs#4)] - [!code-vb[HowToVerifyXMLDocumentRSA#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#4)] - -4. Create a new object and pass the object to it. - + [!code-vb[HowToVerifyXMLDocumentRSA#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#4)] + +4. Create a new object and pass the object to it. + [!code-csharp[HowToVerifyXMLDocumentRSA#5](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/cs/sample.cs#5)] - [!code-vb[HowToVerifyXMLDocumentRSA#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#5)] - -5. Find the <`signature`> element and create a new object. - + [!code-vb[HowToVerifyXMLDocumentRSA#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#5)] + +5. Find the <`signature`> element and create a new object. + [!code-csharp[HowToVerifyXMLDocumentRSA#6](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/cs/sample.cs#6)] - [!code-vb[HowToVerifyXMLDocumentRSA#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#6)] - -6. Load the XML of the first <`signature`> element into the object. - + [!code-vb[HowToVerifyXMLDocumentRSA#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#6)] + +6. Load the XML of the first <`signature`> element into the object. + [!code-csharp[HowToVerifyXMLDocumentRSA#7](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/cs/sample.cs#7)] - [!code-vb[HowToVerifyXMLDocumentRSA#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#7)] - -7. Check the signature using the method and the RSA public key. This method returns a Boolean value that indicates success or failure. - + [!code-vb[HowToVerifyXMLDocumentRSA#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#7)] + +7. Check the signature using the method and the RSA public key. This method returns a Boolean value that indicates success or failure. + [!code-csharp[HowToVerifyXMLDocumentRSA#8](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/cs/sample.cs#8)] - [!code-vb[HowToVerifyXMLDocumentRSA#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#8)] - + [!code-vb[HowToVerifyXMLDocumentRSA#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#8)] + ## Example -This example assumes that a file named `"test.xml"` exists in the same directory as the compiled program. The `"test.xml"` file must be signed using the techniques described in [How to: Sign XML Documents with Digital Signatures](how-to-sign-xml-documents-with-digital-signatures.md). - +This example assumes that a file named `"test.xml"` exists in the same directory as the compiled program. The `"test.xml"` file must be signed using the techniques described in [How to: Sign XML Documents with Digital Signatures](how-to-sign-xml-documents-with-digital-signatures.md). + [!code-csharp[HowToVerifyXMLDocumentRSA#1](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/cs/sample.cs#1)] -[!code-vb[HowToVerifyXMLDocumentRSA#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#1)] - -## Compiling the Code - +[!code-vb[HowToVerifyXMLDocumentRSA#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToVerifyXMLDocumentRSA/vb/sample.vb#1)] + +## Compiling the Code + - In a project that targets .NET Framework, include a reference to `System.Security.dll`. - In a project that targets .NET Core or .NET 5, install NuGet package [System.Security.Cryptography.Xml](https://www.nuget.org/packages/System.Security.Cryptography.Xml). - -- Include the following namespaces: , , and . - + +- Include the following namespaces: , , and . + ## .NET Security -Never store or transfer the private key of an asymmetric key pair in plaintext. For more information about symmetric and asymmetric cryptographic keys, see [Generating Keys for Encryption and Decryption](generating-keys-for-encryption-and-decryption.md). - -Never embed a private key directly into your source code. Embedded keys can be easily read from an assembly using the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) or by opening the assembly in a text editor such as Notepad. - +Never store or transfer the private key of an asymmetric key pair in plaintext. For more information about symmetric and asymmetric cryptographic keys, see [Generating Keys for Encryption and Decryption](generating-keys-for-encryption-and-decryption.md). + +Never embed a private key directly into your source code. Embedded keys can be easily read from an assembly using the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) or by opening the assembly in a text editor such as Notepad. + ## See also - [Cryptography Model](cryptography-model.md) diff --git a/docs/standard/security/impersonating-and-reverting.md b/docs/standard/security/impersonating-and-reverting.md index d929969a184db..c8150e2ebe8c0 100644 --- a/docs/standard/security/impersonating-and-reverting.md +++ b/docs/standard/security/impersonating-and-reverting.md @@ -2,10 +2,10 @@ description: "Learn more about: Impersonating and Reverting" title: "Impersonating and Reverting" ms.date: 07/15/2020 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "WindowsIdentity objects, impersonating" - "security [.NET], impersonating Windows accounts" - "impersonating Windows accounts" @@ -18,46 +18,46 @@ ms.assetid: b93d402c-6c28-4f50-b2bc-d9607dc3e470 > > For information about ASP.NET Core, see [ASP.NET Core Security](/aspnet/core/security/). -Sometimes you might need to obtain a Windows account token to impersonate a Windows account. For example, your ASP.NET-based application might have to act on behalf of several users at different times. Your application might accept a token that represents an administrator from Internet Information Services (IIS), impersonate that user, perform an operation, and revert to the previous identity. Next, it might accept a token from IIS that represents a user with fewer rights, perform some operation, and revert again. - - In situations where your application must impersonate a Windows account that has not been attached to the current thread by IIS, you must retrieve that account's token and use it to activate the account. You can do this by performing the following tasks: - -1. Retrieve an account token for a particular user by making a call to the unmanaged **LogonUser** method. This method is not in the .NET base class library, but is located in the unmanaged **advapi32.dll**. Accessing methods in unmanaged code is an advanced operation and is beyond the scope of this discussion. For more information, see [Interoperating with Unmanaged Code](../../framework/interop/index.md). For more information about the **LogonUser** method and **advapi32.dll**, see the Platform SDK documentation. - -2. Create a new instance of the **WindowsIdentity** class, passing the token. The following code demonstrates this call, where `hToken` represents a Windows token. - - ```csharp - WindowsIdentity impersonatedIdentity = new WindowsIdentity(hToken); - ``` - - ```vb - Dim impersonatedIdentity As New WindowsIdentity(hToken) - ``` - -3. Begin impersonation by creating a new instance of the class and initializing it with the method of the initialized class, as shown in the following code. - - ```csharp - WindowsImpersonationContext myImpersonation = impersonatedIdentity.Impersonate(); - ``` - - ```vb - WindowsImpersonationContext myImpersonation = impersonatedIdentity.Impersonate() - ``` - -4. When you no longer need to impersonate, call the method to revert the impersonation, as shown in the following code. - - ```csharp - myImpersonation.Undo(); - ``` - - ```vb - myImpersonation.Undo() - ``` - - If trusted code has already attached a object to the thread, you can call the instance method **Impersonate**, which does not take an account token. Note that this is only useful when the **WindowsPrincipal** object on the thread represents a user other than the one under which the process is currently executing. For example, you might encounter this situation using ASP.NET with Windows authentication turned on and impersonation turned off. In this case, the process is running under an account configured in Internet Information Services (IIS) while the current principal represents the Windows user that is accessing the page. - - Note that neither **Impersonate** nor **Undo** changes the **Principal** object () associated with the current call context. Rather, impersonation and reverting change the token associated with the current operating system process. - +Sometimes you might need to obtain a Windows account token to impersonate a Windows account. For example, your ASP.NET-based application might have to act on behalf of several users at different times. Your application might accept a token that represents an administrator from Internet Information Services (IIS), impersonate that user, perform an operation, and revert to the previous identity. Next, it might accept a token from IIS that represents a user with fewer rights, perform some operation, and revert again. + + In situations where your application must impersonate a Windows account that has not been attached to the current thread by IIS, you must retrieve that account's token and use it to activate the account. You can do this by performing the following tasks: + +1. Retrieve an account token for a particular user by making a call to the unmanaged **LogonUser** method. This method is not in the .NET base class library, but is located in the unmanaged **advapi32.dll**. Accessing methods in unmanaged code is an advanced operation and is beyond the scope of this discussion. For more information, see [Interoperating with Unmanaged Code](../../framework/interop/index.md). For more information about the **LogonUser** method and **advapi32.dll**, see the Platform SDK documentation. + +2. Create a new instance of the **WindowsIdentity** class, passing the token. The following code demonstrates this call, where `hToken` represents a Windows token. + + ```csharp + WindowsIdentity impersonatedIdentity = new WindowsIdentity(hToken); + ``` + + ```vb + Dim impersonatedIdentity As New WindowsIdentity(hToken) + ``` + +3. Begin impersonation by creating a new instance of the class and initializing it with the method of the initialized class, as shown in the following code. + + ```csharp + WindowsImpersonationContext myImpersonation = impersonatedIdentity.Impersonate(); + ``` + + ```vb + WindowsImpersonationContext myImpersonation = impersonatedIdentity.Impersonate() + ``` + +4. When you no longer need to impersonate, call the method to revert the impersonation, as shown in the following code. + + ```csharp + myImpersonation.Undo(); + ``` + + ```vb + myImpersonation.Undo() + ``` + + If trusted code has already attached a object to the thread, you can call the instance method **Impersonate**, which does not take an account token. Note that this is only useful when the **WindowsPrincipal** object on the thread represents a user other than the one under which the process is currently executing. For example, you might encounter this situation using ASP.NET with Windows authentication turned on and impersonation turned off. In this case, the process is running under an account configured in Internet Information Services (IIS) while the current principal represents the Windows user that is accessing the page. + + Note that neither **Impersonate** nor **Undo** changes the **Principal** object () associated with the current call context. Rather, impersonation and reverting change the token associated with the current operating system process. + ## See also - diff --git a/docs/standard/security/key-security-concepts.md b/docs/standard/security/key-security-concepts.md index 803251e93cc83..bd00813a5f5c0 100644 --- a/docs/standard/security/key-security-concepts.md +++ b/docs/standard/security/key-security-concepts.md @@ -25,7 +25,7 @@ Type-safe code accesses only the memory locations it is authorized to access. (F During just-in-time (JIT) compilation, an optional verification process examines the metadata and common intermediate language (CIL) of a method to be JIT-compiled into native machine code to verify that they are type safe. This process is skipped if the code has permission to bypass verification. For more information about verification, see [Managed Execution Process](../managed-execution-process.md). -Although verification of type safety is not mandatory to run managed code, type safety plays a crucial role in assembly isolation and security enforcement. When code is type safe, the common language runtime can completely isolate assemblies from each other. This isolation helps ensure that assemblies cannot adversely affect each other and it increases application reliability. Type-safe components can execute safely in the same process even if they are trusted at different levels. When code is not type safe, unwanted side effects can occur. For example, the runtime cannot prevent managed code from calling into native (unmanaged) code and performing malicious operations. When code is type safe, the runtime's security enforcement mechanism ensures that it does not access native code unless it has permission to do so. All code that is not type safe must have been granted with the passed enum member to run. +Although verification of type safety is not mandatory to run managed code, type safety plays a crucial role in assembly isolation and security enforcement. When code is type safe, the common language runtime can completely isolate assemblies from each other. This isolation helps ensure that assemblies cannot adversely affect each other and it increases application reliability. Type-safe components can execute safely in the same process even if they are trusted at different levels. When code is not type safe, unwanted side effects can occur. For example, the runtime cannot prevent managed code from calling into native (unmanaged) code and performing malicious operations. When code is type safe, the runtime's security enforcement mechanism ensures that it does not access native code unless it has permission to do so. All code that is not type safe must have been granted with the passed enum member to run. [!INCLUDE [cas-deprecated](../../../includes/cas-deprecated.md)] @@ -43,7 +43,7 @@ For more information, see [Principal and Identity Objects](principal-and-identit ## Authentication -Authentication is the process of discovering and verifying the identity of a principal by examining the user's credentials and validating those credentials against some authority. The information obtained during authentication is directly usable by your code. You can also use .NET role-based security to authenticate the current user and to determine whether to allow that principal to access your code. See the overloads of the method for examples of how to authenticate the principal for specific roles. For example, you can use the overload to determine if the current user is a member of the Administrators group. +Authentication is the process of discovering and verifying the identity of a principal by examining the user's credentials and validating those credentials against some authority. The information obtained during authentication is directly usable by your code. You can also use .NET role-based security to authenticate the current user and to determine whether to allow that principal to access your code. See the overloads of the method for examples of how to authenticate the principal for specific roles. For example, you can use the overload to determine if the current user is a member of the Administrators group. A variety of authentication mechanisms are used today, many of which can be used with .NET role-based security. Some of the most commonly used mechanisms are basic, digest, Passport, operating system (such as NTLM or Kerberos), or application-defined mechanisms. diff --git a/docs/standard/security/walkthrough-creating-a-cryptographic-application.md b/docs/standard/security/walkthrough-creating-a-cryptographic-application.md index 6cd72dfa9017e..58631f825942b 100644 --- a/docs/standard/security/walkthrough-creating-a-cryptographic-application.md +++ b/docs/standard/security/walkthrough-creating-a-cryptographic-application.md @@ -23,7 +23,7 @@ This walkthrough demonstrates how to encrypt and decrypt the contents of a file. This walkthrough uses the following guidelines for encryption: -- Use the class, a symmetric algorithm, to encrypt and decrypt data by using its automatically generated and . +- Use the class, a symmetric algorithm, to encrypt and decrypt data by using its automatically generated and . - Use the asymmetric algorithm to encrypt and decrypt the key to the data encrypted by . Asymmetric algorithms are best used for smaller amounts of data, such as a key. > [!NOTE] diff --git a/docs/standard/serialization/binaryformatter-event-source.md b/docs/standard/serialization/binaryformatter-event-source.md index bf5a22a52221d..027946071013a 100644 --- a/docs/standard/serialization/binaryformatter-event-source.md +++ b/docs/standard/serialization/binaryformatter-event-source.md @@ -18,7 +18,7 @@ The `BinaryFormatter` event source has the well-known name `System.Runtime.Seria ### SerializationStart event (id = `10`) -Raised when has been called and has started the serialization process. This event is paired with the `SerializationEnd` event. The `SerializationStart` event can be called recursively if an object calls `BinaryFormatter.Serialize` within its own serialization routine. +Raised when has been called and has started the serialization process. This event is paired with the `SerializationEnd` event. The `SerializationStart` event can be called recursively if an object calls `BinaryFormatter.Serialize` within its own serialization routine. This event doesn't contain a payload. @@ -40,7 +40,7 @@ This event contains a payload with one argument: ### DeserializationStart event (id = `20`) -Raised when has been called and has started the deserialization process. This event is paired with the `DeserializationEnd` event. The `DeserializationStart` event can be called recursively if an object calls `BinaryFormatter.Deserialize` within its own deserialization routine. +Raised when has been called and has started the deserialization process. This event is paired with the `DeserializationEnd` event. The `DeserializationStart` event can be called recursively if an object calls `BinaryFormatter.Deserialize` within its own deserialization routine. This event doesn't contain a payload. diff --git a/docs/standard/serialization/binaryformatter-migration-guide/read-nrbf-payloads.md b/docs/standard/serialization/binaryformatter-migration-guide/read-nrbf-payloads.md index f21049a6d1589..274bd6de382c5 100644 --- a/docs/standard/serialization/binaryformatter-migration-guide/read-nrbf-payloads.md +++ b/docs/standard/serialization/binaryformatter-migration-guide/read-nrbf-payloads.md @@ -89,7 +89,7 @@ The NRBF payload consists of serialization records that represent the serialized The method returns a instance. is an abstract class that represents the serialization record and provides three self-describing properties: , , and . > [!NOTE] -> An attacker could create a payload with cycles (example: class or an array of objects with a reference to itself). The returns an instance of which implements and amongst other things, it can be used to detect cycles in decoded records. +> An attacker could create a payload with cycles (example: class or an array of objects with a reference to itself). The returns an instance of which implements and amongst other things, it can be used to detect cycles in decoded records. exposes one method, , which compares the type name read from the payload (and exposed via property) against the specified type. This method ignores assembly names, so users don't need to worry about type forwarding and assembly versioning. It also does not consider member names or their types (because getting this information would require type loading). @@ -124,12 +124,12 @@ static Animal Pseudocode(Stream payload) There are more than a dozen different serialization [record types](/openspecs/windows_protocols/ms-nrbf/). This library provides a set of abstractions, so you only need to learn a few of them: -- : describes all primitive types natively supported by the NRBF (`string`, `bool`, `byte`, `sbyte`, `char`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `float`, `double`, `decimal`, `TimeSpan`, and `DateTime`). +- : describes all primitive types natively supported by the NRBF (`string`, `bool`, `byte`, `sbyte`, `char`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `float`, `double`, `decimal`, `TimeSpan`, and `DateTime`). - Exposes the value via the `Value` property. - - derives from the non-generic , which also exposes a property. But on the base class, the value is returned as `object` (which introduces boxing for value types). + - derives from the non-generic , which also exposes a property. But on the base class, the value is returned as `object` (which introduces boxing for value types). - : describes all `class` and `struct` besides the aforementioned primitive types. - : describes all array records, including jagged and multi-dimensional arrays. -- : describes single-dimensional, zero-indexed array records, where `T` can be either a primitive type or a . +- : describes single-dimensional, zero-indexed array records, where `T` can be either a primitive type or a . ```csharp SerializationRecord rootObject = NrbfDecoder.Decode(payload); // payload is a Stream @@ -256,7 +256,7 @@ ComplexType3D[] output = records.OfType().Select(classRecord => new `SZArrayRecord` defines the core behavior for NRBF single dimensional, zero-indexed array records and provides a base for derived classes. The `T` can be one of the natively supported primitive types or . -It provides a property and a overload that returns `T[]`. +It provides a property and a overload that returns `T[]`. ```csharp [Serializable] diff --git a/docs/standard/serialization/controlling-xml-serialization-using-attributes.md b/docs/standard/serialization/controlling-xml-serialization-using-attributes.md index 9bd0f321ebeb3..67800aa0af1a9 100644 --- a/docs/standard/serialization/controlling-xml-serialization-using-attributes.md +++ b/docs/standard/serialization/controlling-xml-serialization-using-attributes.md @@ -46,7 +46,7 @@ public class Book // 1234567890. ``` -The default behavior can be changed if you want to give the element a new name. The following code shows how an attribute enables this functionality by setting the property of an : +The default behavior can be changed if you want to give the element a new name. The following code shows how an attribute enables this functionality by setting the property of an : ```vb Public Class TaxRates @@ -159,7 +159,7 @@ The resulting XML might resemble the following code: ## Serializing Derived Classes -Another use of the is to allow the serialization of derived classes. For example, another class named `Manager` that derives from `Employee` can be added to the previous example. If you don't apply the , the code will fail at runtime because the derived class type won't be recognized. To remedy this outcome, apply the attribute twice, each time setting the property for each acceptable type (base and derived). +Another use of the is to allow the serialization of derived classes. For example, another class named `Manager` that derives from `Employee` can be added to the previous example. If you don't apply the , the code will fail at runtime because the derived class type won't be recognized. To remedy this outcome, apply the attribute twice, each time setting the property for each acceptable type (base and derived). ```vb Public Class Group diff --git a/docs/standard/serialization/examples-of-xml-serialization.md b/docs/standard/serialization/examples-of-xml-serialization.md index 6cd148d2edd2d..81387ec189669 100644 --- a/docs/standard/serialization/examples-of-xml-serialization.md +++ b/docs/standard/serialization/examples-of-xml-serialization.md @@ -339,13 +339,13 @@ public class Employees : ICollection { empArray.CopyTo(a, index); } - + public int Count => empArray.Count; - + public object SyncRoot => this; - + public bool IsSynchronized => false; - + public IEnumerator GetEnumerator() => empArray.GetEnumerator(); public void Add(Employee newEmployee) @@ -358,9 +358,9 @@ public class Employee { public string EmpName; public string EmpID; - + public Employee() {} - + public Employee(string empName, string empID) { EmpName = empName; @@ -373,7 +373,7 @@ public class Employee You can cut and paste the following example code into a text file and rename it with a .cs or .vb file name extension. Use the C# or Visual Basic compiler to compile the file. Then run it using the name of the executable. -This example uses a simple scenario to demonstrate how an instance of an object is created and serialized into a file stream using the method. The XML stream is saved to a file. The same file is then read and reconstructed into a copy of the original object using the method. +This example uses a simple scenario to demonstrate how an instance of an object is created and serialized into a file stream using the method. The XML stream is saved to a file. The same file is then read and reconstructed into a copy of the original object using the method. In this example, a class named `PurchaseOrder` is serialized and then deserialized. A second class named `Address` is also included because the public field named `ShipTo` must be set to an `Address`. Similarly, an `OrderedItem` class is included because an array of `OrderedItem` objects must be set to the `OrderedItems` field. Finally, a class named `Test` contains the code that serializes and deserializes the classes. @@ -382,7 +382,7 @@ The `CreatePO` method creates the `PurchaseOrder`, `Address`, and `OrderedItem` > [!NOTE] > The code passes the type of class that will be serialized to the constructor. The code also creates a `FileStream` that's used to write the XML stream to an XML document. -The `ReadPo` method is a little simpler. It just creates objects to deserialize and reads out their values. As with the `CreatePo` method, you must first construct an , passing the type of class to be deserialized to the constructor. Also, a is required to read the XML document. To deserialize the objects, call the method with the as an argument. The deserialized object must be cast to an object variable of type `PurchaseOrder`. The code then reads the values of the deserialized `PurchaseOrder`. +The `ReadPo` method is a little simpler. It just creates objects to deserialize and reads out their values. As with the `CreatePo` method, you must first construct an , passing the type of class to be deserialized to the constructor. Also, a is required to read the XML document. To deserialize the objects, call the method with the as an argument. The deserialized object must be cast to an object variable of type `PurchaseOrder`. The code then reads the values of the deserialized `PurchaseOrder`. > [!NOTE] > You can read the *PO.xml* file that's created to see the actual XML output. diff --git a/docs/standard/serialization/how-to-chunk-serialized-data.md b/docs/standard/serialization/how-to-chunk-serialized-data.md index 55d9ba84457ba..2c47d44fff31f 100644 --- a/docs/standard/serialization/how-to-chunk-serialized-data.md +++ b/docs/standard/serialization/how-to-chunk-serialized-data.md @@ -2,10 +2,10 @@ title: "How to: chunk serialized data" description: You can chunk data to avoid problems with large datasets. Implement the IXmlSerializable interface to control serialization and deserialization. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "chunking serialized data" - "data chunking" - "binary serialization, chunking data" @@ -19,41 +19,41 @@ ms.assetid: 22f1b818-7e0d-428a-8680-f17d6ebdd185 [!INCLUDE [binary-serialization-warning](../../../includes/binary-serialization-warning.md)] -Two issues that occur when sending large data sets in Web service messages are: - -1. A large working set (memory) due to buffering by the serialization engine. - -2. Inordinate bandwidth consumption due to 33 percent inflation after Base64 encoding. - - To solve these problems, implement the interface to control the serialization and deserialization. Specifically, implement the and methods to chunk the data. - -### To implement server-side chunking - -1. On the server machine, the Web method must turn off ASP.NET buffering and return a type that implements . - -2. The type that implements chunks the data in the method. - -### To implement client-side processing - -1. Alter the Web method on the client proxy to return the type that implements . You can use a to do this automatically, but this isn't shown here. - -2. Implement the method to read the chunked data stream and write the bytes to disk. This implementation also raises progress events that can be used by a graphic control, such as a progress bar. - -## Example - -The following code example shows the Web method on the client that turns off ASP.NET buffering. It also shows the client-side implementation of the interface that chunks the data in the method. - +Two issues that occur when sending large data sets in Web service messages are: + +1. A large working set (memory) due to buffering by the serialization engine. + +2. Inordinate bandwidth consumption due to 33 percent inflation after Base64 encoding. + + To solve these problems, implement the interface to control the serialization and deserialization. Specifically, implement the and methods to chunk the data. + +### To implement server-side chunking + +1. On the server machine, the Web method must turn off ASP.NET buffering and return a type that implements . + +2. The type that implements chunks the data in the method. + +### To implement client-side processing + +1. Alter the Web method on the client proxy to return the type that implements . You can use a to do this automatically, but this isn't shown here. + +2. Implement the method to read the chunked data stream and write the bytes to disk. This implementation also raises progress events that can be used by a graphic control, such as a progress bar. + +## Example + +The following code example shows the Web method on the client that turns off ASP.NET buffering. It also shows the client-side implementation of the interface that chunks the data in the method. + [!code-csharp[HowToChunkSerializedData#1](../../../samples/snippets/csharp/VS_Snippets_Remoting/HowToChunkSerializedData/CS/SerializationChunk.cs#1)] -[!code-vb[HowToChunkSerializedData#1](../../../samples/snippets/visualbasic/VS_Snippets_Remoting/HowToChunkSerializedData/VB/SerializationChunk.vb#1)] +[!code-vb[HowToChunkSerializedData#1](../../../samples/snippets/visualbasic/VS_Snippets_Remoting/HowToChunkSerializedData/VB/SerializationChunk.vb#1)] [!code-csharp[HowToChunkSerializedData#2](../../../samples/snippets/csharp/VS_Snippets_Remoting/HowToChunkSerializedData/CS/SerializationChunk.cs#2)] -[!code-vb[HowToChunkSerializedData#2](../../../samples/snippets/visualbasic/VS_Snippets_Remoting/HowToChunkSerializedData/VB/SerializationChunk.vb#2)] +[!code-vb[HowToChunkSerializedData#2](../../../samples/snippets/visualbasic/VS_Snippets_Remoting/HowToChunkSerializedData/VB/SerializationChunk.vb#2)] [!code-csharp[HowToChunkSerializedData#3](../../../samples/snippets/csharp/VS_Snippets_Remoting/HowToChunkSerializedData/CS/SerializationChunk.cs#3)] -[!code-vb[HowToChunkSerializedData#3](../../../samples/snippets/visualbasic/VS_Snippets_Remoting/HowToChunkSerializedData/VB/SerializationChunk.vb#3)] - -## Compiling the code - -- The code uses the following namespaces: , , , , , , and . - +[!code-vb[HowToChunkSerializedData#3](../../../samples/snippets/visualbasic/VS_Snippets_Remoting/HowToChunkSerializedData/VB/SerializationChunk.vb#3)] + +## Compiling the code + +- The code uses the following namespaces: , , , , , , and . + ## See also - [Custom Serialization](/previous-versions/dotnet/fundamentals/serialization/binary/custom-serialization) diff --git a/docs/standard/serialization/how-to-deserialize-an-object.md b/docs/standard/serialization/how-to-deserialize-an-object.md index 82764d3a19574..bf6bee2efa6f7 100644 --- a/docs/standard/serialization/how-to-deserialize-an-object.md +++ b/docs/standard/serialization/how-to-deserialize-an-object.md @@ -1,24 +1,24 @@ --- title: How to deserialize an object using XmlSerializer -description: Learn how to deserialize an object. The transport format determines whether to create a stream or file object. +description: Learn how to deserialize an object. The transport format determines whether to create a stream or file object. ms.date: 03/30/2017 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "deserializing objects" - "objects, deserializing steps" ms.assetid: 287129c8-035a-4fea-b7b3-4790057ca076 --- # How to deserialize an object using XmlSerializer -When you deserialize an object, the transport format determines whether you will create a stream or file object. After the transport format is determined, you can call the or methods, as required. +When you deserialize an object, the transport format determines whether you will create a stream or file object. After the transport format is determined, you can call the or methods, as required. ## To deserialize an object 1. Construct a using the type of the object to deserialize. -1. Call the method to produce a replica of the object. When deserializing, you must cast the returned object to the type of the original, as shown in the following example, which deserializes the object from a file (although it could also be deserialized from a stream). +1. Call the method to produce a replica of the object. When deserializing, you must cast the returned object to the type of the original, as shown in the following example, which deserializes the object from a file (although it could also be deserialized from a stream). ```vb ' Construct an instance of the XmlSerializer with the type diff --git a/docs/standard/serialization/how-to-serialize-an-object.md b/docs/standard/serialization/how-to-serialize-an-object.md index 86e4e8deee02d..9157e301489fa 100644 --- a/docs/standard/serialization/how-to-serialize-an-object.md +++ b/docs/standard/serialization/how-to-serialize-an-object.md @@ -2,50 +2,50 @@ title: "How to: Serialize an Object" description: This article shows you how to serialize an object. Select a transport format in which the XML stream is stored, either as a stream or as a file. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "serializing objects" - "objects, serializing steps" ms.assetid: a1207d05-32b2-4953-8582-959607991227 --- # How to: Serialize an Object -To serialize an object, first create the object that is to be serialized and set its public properties and fields. To do this, you must determine the transport format in which the XML stream is to be stored, either as a stream or as a file. For example, if the XML stream must be saved in a permanent form, create a object. - +To serialize an object, first create the object that is to be serialized and set its public properties and fields. To do this, you must determine the transport format in which the XML stream is to be stored, either as a stream or as a file. For example, if the XML stream must be saved in a permanent form, create a object. + > [!NOTE] -> For more examples of XML serialization, see [Examples of XML Serialization](examples-of-xml-serialization.md). - -### To serialize an object - -1. Create the object and set its public fields and properties. - -2. Construct a using the type of the object. For more information, see the class constructors. - -3. Call the method to generate either an XML stream or a file representation of the object's public properties and fields. The following example creates a file. - - ```vb - Dim myObject As MySerializableClass = New MySerializableClass() - ' Insert code to set properties and fields of the object. - Dim mySerializer As XmlSerializer = New XmlSerializer(GetType(MySerializableClass)) - ' To write to a file, create a StreamWriter object. - Dim myWriter As StreamWriter = New StreamWriter("myFileName.xml") - mySerializer.Serialize(myWriter, myObject) - myWriter.Close() - ``` - - ```csharp - MySerializableClass myObject = new MySerializableClass(); - // Insert code to set properties and fields of the object. +> For more examples of XML serialization, see [Examples of XML Serialization](examples-of-xml-serialization.md). + +### To serialize an object + +1. Create the object and set its public fields and properties. + +2. Construct a using the type of the object. For more information, see the class constructors. + +3. Call the method to generate either an XML stream or a file representation of the object's public properties and fields. The following example creates a file. + + ```vb + Dim myObject As MySerializableClass = New MySerializableClass() + ' Insert code to set properties and fields of the object. + Dim mySerializer As XmlSerializer = New XmlSerializer(GetType(MySerializableClass)) + ' To write to a file, create a StreamWriter object. + Dim myWriter As StreamWriter = New StreamWriter("myFileName.xml") + mySerializer.Serialize(myWriter, myObject) + myWriter.Close() + ``` + + ```csharp + MySerializableClass myObject = new MySerializableClass(); + // Insert code to set properties and fields of the object. XmlSerializer mySerializer = new - XmlSerializer(typeof(MySerializableClass)); - // To write to a file, create a StreamWriter object. - StreamWriter myWriter = new StreamWriter("myFileName.xml"); - mySerializer.Serialize(myWriter, myObject); - myWriter.Close(); - ``` - + XmlSerializer(typeof(MySerializableClass)); + // To write to a file, create a StreamWriter object. + StreamWriter myWriter = new StreamWriter("myFileName.xml"); + mySerializer.Serialize(myWriter, myObject); + myWriter.Close(); + ``` + ## See also - [Introducing XML Serialization](introducing-xml-serialization.md) diff --git a/docs/standard/serialization/how-to-specify-an-alternate-element-name-for-an-xml-stream.md b/docs/standard/serialization/how-to-specify-an-alternate-element-name-for-an-xml-stream.md index 8223b0cc7b865..5759e590096ce 100644 --- a/docs/standard/serialization/how-to-specify-an-alternate-element-name-for-an-xml-stream.md +++ b/docs/standard/serialization/how-to-specify-an-alternate-element-name-for-an-xml-stream.md @@ -22,11 +22,11 @@ Using the , you can generate more t 1. Create an instance of the class. -2. Set the of the to "BookID". +2. Set the of the to "BookID". 3. Create an instance of the class. -4. Add the `XmlElementAttribute` object to the collection accessed through the property of . +4. Add the `XmlElementAttribute` object to the collection accessed through the property of . 5. Create an instance of the class. diff --git a/docs/standard/serialization/system-text-json/configure-options.md b/docs/standard/serialization/system-text-json/configure-options.md index 918f85edc2792..4fb4a2ec27112 100644 --- a/docs/standard/serialization/system-text-json/configure-options.md +++ b/docs/standard/serialization/system-text-json/configure-options.md @@ -20,7 +20,7 @@ This article explains how to avoid performance problems when you use or . It's safe to use the same instance across multiple threads. The metadata caches on the options instance are thread-safe, and the instance is immutable after the first serialization or deserialization. +If you use `JsonSerializerOptions` repeatedly with the same options, don't create a new `JsonSerializerOptions` instance each time you use it. Reuse the same instance for every call. This guidance applies to code you write for custom converters and when you call or . It's safe to use the same instance across multiple threads. The metadata caches on the options instance are thread-safe, and the instance is immutable after the first serialization or deserialization. ## The `JsonSerializerOptions.Default` property @@ -39,9 +39,9 @@ The metadata cache of the existing `JsonSerializerOptions` instance isn't copied The following options have different defaults for web apps: -* = `true` +* = `true` * = -* = +* = In .NET 9 and later versions, you can use the singleton to serialize with the default options that ASP.NET Core uses for web apps. In earlier versions, call the [JsonSerializerOptions constructor](xref:System.Text.Json.JsonSerializerOptions.%23ctor(System.Text.Json.JsonSerializerDefaults)) to create a new instance with the web defaults, as shown in the following example: diff --git a/docs/standard/serialization/system-text-json/converters-how-to.md b/docs/standard/serialization/system-text-json/converters-how-to.md index da1c9cec75a91..6862eb912fb23 100644 --- a/docs/standard/serialization/system-text-json/converters-how-to.md +++ b/docs/standard/serialization/system-text-json/converters-how-to.md @@ -35,9 +35,9 @@ Visual Basic can't be used to write custom converters but can call converters th There are two patterns for creating a custom converter: the basic pattern and the factory pattern. The factory pattern is for converters that handle type `Enum` or open generics. The basic pattern is for non-generic and closed generic types. For example, converters for the following types require the factory pattern: -* +* * -* +* Some examples of types that can be handled by the basic pattern include: @@ -65,8 +65,8 @@ The following code shows a custom converter that works with `Dictionary where `T` is the type to be serialized and deserialized. -* Override the `Read` method to deserialize the incoming JSON and convert it to type `T`. Use the that's passed to the method to read the JSON. You don't have to worry about handling partial data, as the serializer passes all the data for the current JSON scope. So it isn't necessary to call or or to validate that returns `true`. +* Create a class that derives from where `T` is the type to be serialized and deserialized. +* Override the `Read` method to deserialize the incoming JSON and convert it to type `T`. Use the that's passed to the method to read the JSON. You don't have to worry about handling partial data, as the serializer passes all the data for the current JSON scope. So it isn't necessary to call or or to validate that returns `true`. * Override the `Write` method to serialize the incoming object of type `T`. Use the that is passed to the method to write the JSON. * Override the `CanConvert` method only if necessary. The default implementation returns `true` when the type to convert is of type `T`. Therefore, converters that support only type `T` don't need to override this method. For an example of a converter that does need to override this method, see the [polymorphic deserialization](#support-polymorphic-deserialization) section later in this article. @@ -285,10 +285,10 @@ A disadvantage of this method is you can't pass in the original options instance If you deserialize a JSON string into a `Stack` object and then serialize that object, the contents of the stack are in reverse order. This behavior applies to the following types and interfaces, and user-defined types that derive from them: * -* -* -* -* +* +* +* +* To support serialization and deserialization that retains the original order in the stack, a custom converter is required. @@ -310,7 +310,7 @@ In some scenarios, you might want to use the default system converter in a custo By default, the serializer handles null values as follows: -* For reference types and types: +* For reference types and types: * It doesn't pass `null` to custom converters on serialization. * It doesn't pass `JsonTokenType.Null` to custom converters on deserialization. @@ -323,13 +323,13 @@ By default, the serializer handles null values as follows: This null-handling behavior is primarily to optimize performance by skipping an extra call to the converter. In addition, it avoids forcing converters for nullable types to check for `null` at the start of every `Read` and `Write` method override. -To enable a custom converter to handle `null` for a reference or value type, override to return `true`, as shown in the following example: +To enable a custom converter to handle `null` for a reference or value type, override to return `true`, as shown in the following example: :::code language="csharp" source="snippets/how-to-contd/csharp/CustomConverterHandleNull.cs" highlight="17"::: ## Preserve references -By default, reference data is only cached for each call to or . To persist references from one `Serialize`/`Deserialize` call to another one, root the instance in the call site of `Serialize`/`Deserialize`. The following code shows an example for this scenario: +By default, reference data is only cached for each call to or . To persist references from one `Serialize`/`Deserialize` call to another one, root the instance in the call site of `Serialize`/`Deserialize`. The following code shows an example for this scenario: * You write a custom converter for the `Company` type. * You don't want to manually serialize the `Supervisor` property, which is an `Employee`. You want to delegate that to the serializer and you also want to preserve the references that you have already saved. @@ -358,7 +358,7 @@ The preceding example only does serialization, but a similar approach can be ado ### ReferenceResolver limitations with custom converters -When you use , be aware that reference handling state isn't preserved when the serializer calls into a custom converter. This means that if you have a custom converter for a type that's part of an object graph being serialized or deserialized with reference preservation enabled, the converter and any nested serialization calls won't have access to the current instance. +When you use , be aware that reference handling state isn't preserved when the serializer calls into a custom converter. This means that if you have a custom converter for a type that's part of an object graph being serialized or deserialized with reference preservation enabled, the converter and any nested serialization calls won't have access to the current instance. ## Other custom converter samples diff --git a/docs/standard/serialization/system-text-json/custom-contracts.md b/docs/standard/serialization/system-text-json/custom-contracts.md index 8c2bec09ac923..1d57b718b6397 100644 --- a/docs/standard/serialization/system-text-json/custom-contracts.md +++ b/docs/standard/serialization/system-text-json/custom-contracts.md @@ -42,7 +42,7 @@ There are two ways to plug into customization. Both involve obtaining a resolver - By writing a custom resolver that implements . - - If a type isn't handled, should return `null` for that type. + - If a type isn't handled, should return `null` for that type. - You can also combine your custom resolver with others, for example, the default resolver. The resolvers will be queried in order until a non-null value is returned for the type. ## Configurable aspects @@ -90,7 +90,7 @@ By default, `System.Text.Json` ignores private fields and properties. This examp Perhaps your model has properties with specific names or types that you don't want to expose to users. For example, you might have a property that stores credentials or some information that's useless to have in the payload. -The following example shows how to filter out properties with a specific type, `SecretHolder`. It does this by using an extension method to remove any properties that have the specified type from the list. The filtered properties completely disappear from the contract, which means `System.Text.Json` doesn't look at them either during serialization or deserialization. +The following example shows how to filter out properties with a specific type, `SecretHolder`. It does this by using an extension method to remove any properties that have the specified type from the list. The filtered properties completely disappear from the contract, which means `System.Text.Json` doesn't look at them either during serialization or deserialization. :::code language="csharp" source="snippets/custom-contracts/IgnoreType.cs"::: diff --git a/docs/standard/serialization/system-text-json/customize-properties.md b/docs/standard/serialization/system-text-json/customize-properties.md index 9e01189b86e95..6b9931a77ef3d 100644 --- a/docs/standard/serialization/system-text-json/customize-properties.md +++ b/docs/standard/serialization/system-text-json/customize-properties.md @@ -100,7 +100,7 @@ The naming policy: ## Use a custom JSON property naming policy -To use a custom JSON property naming policy, create a class that derives from and override the method, as shown in the following example: +To use a custom JSON property naming policy, create a class that derives from and override the method, as shown in the following example: :::code language="csharp" source="snippets/how-to/csharp/UpperCaseNamingPolicy.cs"::: :::code language="vb" source="snippets/how-to/vb/UpperCaseNamingPolicy.vb"::: @@ -154,7 +154,7 @@ Naming policies for dictionary keys apply to serialization only. If you deserial ## Enums as strings -By default, enums are serialized as numbers. To serialize enum names as strings, use the or converter. Only is supported by the Native AOT runtime. +By default, enums are serialized as numbers. To serialize enum names as strings, use the or converter. Only is supported by the Native AOT runtime. For example, suppose you need to serialize the following class that has an enum: @@ -193,7 +193,7 @@ The built-in can d ### JsonConverterAttribute -You can also specify the converter to use by annotating your enum with . The following example shows how to specify the (available in .NET 8 and later versions) by using the attribute. For example, suppose you need to serialize the following class that has an enum: +You can also specify the converter to use by annotating your enum with . The following example shows how to specify the (available in .NET 8 and later versions) by using the attribute. For example, suppose you need to serialize the following class that has an enum: :::code language="csharp" source="snippets/how-to/csharp/WeatherForecast.cs" id="WFWithConverterEnum"::: diff --git a/docs/standard/serialization/system-text-json/deserialization.md b/docs/standard/serialization/system-text-json/deserialization.md index 4a2ee9527691f..24e1d3c012e92 100644 --- a/docs/standard/serialization/system-text-json/deserialization.md +++ b/docs/standard/serialization/system-text-json/deserialization.md @@ -18,7 +18,7 @@ ms.custom: copilot-scenario-highlight This article shows how to use the namespace to deserialize from JavaScript Object Notation (JSON). If you're porting existing code from `Newtonsoft.Json`, see [How to migrate to `System.Text.Json`](migrate-from-newtonsoft.md). -A common way to deserialize JSON is to have (or create) a .NET class with properties and fields that represent one or more of the JSON properties. Then, to deserialize from a string or a file, call the method. For the generic overloads, the generic type parameter is the .NET class. For the non-generic overloads, you pass the type of the class as a method parameter. You can deserialize either synchronously or asynchronously. +A common way to deserialize JSON is to have (or create) a .NET class with properties and fields that represent one or more of the JSON properties. Then, to deserialize from a string or a file, call the method. For the generic overloads, the generic type parameter is the .NET class. For the non-generic overloads, you pass the type of the class as a method parameter. You can deserialize either synchronously or asynchronously. > [!TIP] > You can use AI assistance to [deserialize a JSON string](#use-ai-to-deserialize-json). @@ -37,7 +37,7 @@ To deserialize from a file by using synchronous code, read the file into a strin :::code language="csharp" source="snippets/how-to/csharp/DeserializeFromFile.cs" highlight="16-18"::: :::code language="vb" source="snippets/how-to/vb/RoundtripToFile.vb" id="Deserialize"::: -To deserialize from a file by using asynchronous code, call the method: +To deserialize from a file by using asynchronous code, call the method: :::code language="csharp" source="snippets/how-to/csharp/DeserializeFromFileAsync.cs" highlight="17-20"::: :::code language="vb" source="snippets/how-to/vb/RoundtripToFileAsync.vb" id="Deserialize"::: @@ -78,7 +78,7 @@ If you have JSON that you want to deserialize, and you don't have the class to d ## Deserialize from UTF-8 -To deserialize from UTF-8, call a overload that takes a `ReadOnlySpan` or a `Utf8JsonReader`, as shown in the following examples. The examples assume the JSON is in a byte array named jsonUtf8Bytes. +To deserialize from UTF-8, call a overload that takes a `ReadOnlySpan` or a `Utf8JsonReader`, as shown in the following examples. The examples assume the JSON is in a byte array named jsonUtf8Bytes. :::code language="csharp" source="snippets/how-to/csharp/RoundtripToUtf8.cs" id="Deserialize1"::: :::code language="vb" source="snippets/how-to/vb/RoundtripToUtf8.vb" id="Deserialize1"::: diff --git a/docs/standard/serialization/system-text-json/fields.md b/docs/standard/serialization/system-text-json/fields.md index ccdd4c907e3cd..471e6651d70bc 100644 --- a/docs/standard/serialization/system-text-json/fields.md +++ b/docs/standard/serialization/system-text-json/fields.md @@ -16,4 +16,4 @@ By default, fields aren't serialized. Use the global setting. +To ignore read-only fields, use the global setting. diff --git a/docs/standard/serialization/system-text-json/how-to.md b/docs/standard/serialization/system-text-json/how-to.md index 47cc7ac533523..033e4a1d58512 100644 --- a/docs/standard/serialization/system-text-json/how-to.md +++ b/docs/standard/serialization/system-text-json/how-to.md @@ -23,7 +23,7 @@ This article shows how to use the [!TIP] > You can use AI assistance to [serialize to JSON](#use-ai-to-serialize-to-json). -To write JSON to a string or to a file, call the method. +To write JSON to a string or to a file, call the method. ## Serialization examples @@ -89,12 +89,12 @@ Here's an example showing how a class that contains collection properties and a It's 5-10% faster to serialize to a UTF-8 byte array than to use the string-based methods. That's because the bytes (as UTF-8) don't need to be converted to strings (UTF-16). -To serialize to a UTF-8 byte array, call the method: +To serialize to a UTF-8 byte array, call the method: :::code language="csharp" source="snippets/how-to/csharp/RoundtripToUtf8.cs" id="Serialize"::: :::code language="vb" source="snippets/how-to/vb/RoundtripToUtf8.vb" id="Serialize"::: -A overload that takes a is also available. +A overload that takes a is also available. ## Serialize to formatted JSON diff --git a/docs/standard/serialization/system-text-json/httpclient-extensions.md b/docs/standard/serialization/system-text-json/httpclient-extensions.md index c3d6e4d267b8b..a103945031381 100644 --- a/docs/standard/serialization/system-text-json/httpclient-extensions.md +++ b/docs/standard/serialization/system-text-json/httpclient-extensions.md @@ -10,7 +10,7 @@ dev_langs: Serializing and deserializing JSON payloads from the network are common operations. Extension methods on [HttpClient](xref:System.Net.Http.Json.HttpClientJsonExtensions) and [HttpContent](xref:System.Net.Http.Json.HttpContentJsonExtensions) let you do these operations in a single line of code. These extension methods use [web defaults for JsonSerializerOptions](configure-options.md#web-defaults-for-jsonserializeroptions). -The following example illustrates use of and : +The following example illustrates use of and : :::code language="csharp" source="snippets/how-to-contd/csharp/HttpClientExtensionMethods.cs" highlight="23,30"::: :::code language="vb" source="snippets/how-to-contd/vb/HttpClientExtensionMethods.vb"::: diff --git a/docs/standard/serialization/system-text-json/ignore-properties.md b/docs/standard/serialization/system-text-json/ignore-properties.md index ed4d8c2c2718e..783815bd4baf0 100644 --- a/docs/standard/serialization/system-text-json/ignore-properties.md +++ b/docs/standard/serialization/system-text-json/ignore-properties.md @@ -73,7 +73,7 @@ The following example shows a type to serialize. It also shows the JSON output: } ``` -This option applies only to properties. To ignore read-only fields when [serializing fields](fields.md), use the global setting. +This option applies only to properties. To ignore read-only fields when [serializing fields](fields.md), use the global setting. > [!NOTE] > Read-only collection-type properties are still serialized even if is set to `true`. diff --git a/docs/standard/serialization/system-text-json/invalid-json.md b/docs/standard/serialization/system-text-json/invalid-json.md index f957dac1da458..36bf8aa54ca85 100644 --- a/docs/standard/serialization/system-text-json/invalid-json.md +++ b/docs/standard/serialization/system-text-json/invalid-json.md @@ -58,7 +58,7 @@ Instead of: } ``` -To serialize numbers in quotes or accept numbers in quotes across the entire input object graph, set as shown in the following example: +To serialize numbers in quotes or accept numbers in quotes across the entire input object graph, set as shown in the following example: :::code language="csharp" source="snippets/how-to-contd/csharp/QuotedNumbers.cs" highlight="26-28"::: :::code language="vb" source="snippets/how-to-contd/vb/QuotedNumbers.vb" ::: diff --git a/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md b/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md index e375c6cdccf99..843baa4f22375 100644 --- a/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md +++ b/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md @@ -195,7 +195,7 @@ For some of the following scenarios, workarounds are not practical or possible. ### Allow or write numbers in quotes -`Newtonsoft.Json` can serialize or deserialize numbers represented by JSON strings (surrounded by quotes). For example, it can accept: `{"DegreesCelsius":"23"}` instead of `{"DegreesCelsius":23}`. To enable that behavior in , set to or , or use the [[JsonNumberHandling]](xref:System.Text.Json.Serialization.JsonNumberHandlingAttribute) attribute. +`Newtonsoft.Json` can serialize or deserialize numbers represented by JSON strings (surrounded by quotes). For example, it can accept: `{"DegreesCelsius":"23"}` instead of `{"DegreesCelsius":23}`. To enable that behavior in , set to or , or use the [[JsonNumberHandling]](xref:System.Text.Json.Serialization.JsonNumberHandlingAttribute) attribute. If you're using `System.Text.Json` indirectly by using ASP.NET Core, you don't need to do anything to get behavior like `Newtonsoft.Json`. ASP.NET Core specifies [web defaults](configure-options.md#web-defaults-for-jsonserializeroptions) when it uses `System.Text.Json`, and web defaults allow quoted numbers. @@ -219,7 +219,7 @@ The `Newtonsoft.Json` `[JsonConstructor]` attribute lets you specify which const * The [[JsonIgnore]](ignore-properties.md#ignore-individual-properties) attribute on a property causes the property to be omitted from the JSON during serialization. * The [IgnoreReadOnlyProperties](ignore-properties.md#ignore-all-read-only-properties) global option lets you ignore all read-only properties. -* If you're [including fields](fields.md), the global option lets you ignore all read-only fields. +* If you're [including fields](fields.md), the global option lets you ignore all read-only fields. * The `DefaultIgnoreCondition` global option lets you [ignore all value type properties that have default values](ignore-properties.md#ignore-all-default-value-properties), or [ignore all reference type properties that have null values](ignore-properties.md#ignore-all-null-value-properties). In addition, in .NET 7 and later versions, you can customize the JSON contract to ignore properties based on arbitrary criteria. For more information, see [Custom contracts](custom-contracts.md). @@ -241,7 +241,7 @@ By default, `Newtonsoft.Json` serializes by value. For example, if an object con `Newtonsoft.Json` also has a `ReferenceLoopHandling` setting that lets you ignore circular references rather than throw an exception. -To preserve references and handle circular references in , set to . The `ReferenceHandler.Preserve` setting is equivalent to `PreserveReferencesHandling` = `PreserveReferencesHandling.All` in `Newtonsoft.Json`. +To preserve references and handle circular references in , set to . The `ReferenceHandler.Preserve` setting is equivalent to `PreserveReferencesHandling` = `PreserveReferencesHandling.All` in `Newtonsoft.Json`. The `ReferenceHandler.IgnoreCycles` option has behavior similar to Newtonsoft.Json `ReferenceLoopHandling.Ignore`. One difference is that the System.Text.Json implementation replaces reference loops with the `null` JSON token instead of ignoring the object reference. For more information, see [Ignore circular references](preserve-references.md#ignore-circular-references). @@ -554,7 +554,7 @@ Searches for JSON tokens using `JObject` or `JArray` from `Newtonsoft.Json` tend ## Utf8JsonReader vs. JsonTextReader - is a high-performance, low allocation, forward-only reader for UTF-8 encoded JSON text, read from a [ReadOnlySpan\](xref:System.ReadOnlySpan%601) or [ReadOnlySequence\](xref:System.Buffers.ReadOnlySequence%601). The `Utf8JsonReader` is a low-level type that can be used to build custom parsers and deserializers. + is a high-performance, low allocation, forward-only reader for UTF-8 encoded JSON text, read from a [ReadOnlySpan\](xref:System.ReadOnlySpan`1) or [ReadOnlySequence\](xref:System.Buffers.ReadOnlySequence`1). The `Utf8JsonReader` is a low-level type that can be used to build custom parsers and deserializers. ### Utf8JsonReader is a ref struct @@ -562,7 +562,7 @@ The `JsonTextReader` in `Newtonsoft.Json` is a class. The `Utf8JsonReader` type ### Read null values into nullable value types -`Newtonsoft.Json` provides APIs that return , such as `ReadAsBoolean`, which handles a `Null` `TokenType` for you by returning a `bool?`. The built-in `System.Text.Json` APIs return only non-nullable value types. For more information, see [Read null values into nullable value types](use-utf8jsonreader.md#read-null-values-into-nullable-value-types). +`Newtonsoft.Json` provides APIs that return , such as `ReadAsBoolean`, which handles a `Null` `TokenType` for you by returning a `bool?`. The built-in `System.Text.Json` APIs return only non-nullable value types. For more information, see [Read null values into nullable value types](use-utf8jsonreader.md#read-null-values-into-nullable-value-types). ### Multi-target for reading JSON @@ -577,7 +577,7 @@ If you need to continue to use `Newtonsoft.Json` for certain target frameworks, ### Write raw values -`Newtonsoft.Json` has a `WriteRawValue` method that writes raw JSON where a value is expected. has a direct equivalent: . For more information, see [Write raw JSON](use-utf8jsonwriter.md#write-raw-json). +`Newtonsoft.Json` has a `WriteRawValue` method that writes raw JSON where a value is expected. has a direct equivalent: . For more information, see [Write raw JSON](use-utf8jsonwriter.md#write-raw-json). ### Customize JSON format @@ -610,7 +610,7 @@ There are no workarounds that would let you customize the JSON produced by `Utf8 ### Write Timespan, Uri, or char values -`JsonTextWriter` provides `WriteValue` methods for [TimeSpan](https://www.newtonsoft.com/json/help/html/M_Newtonsoft_Json_JsonTextWriter_WriteValue_18.htm), [Uri](https://www.newtonsoft.com/json/help/html/M_Newtonsoft_Json_JsonTextWriter_WriteValue_22.htm), and [char](https://www.newtonsoft.com/json/help/html/M_Newtonsoft_Json_JsonTextWriter_WriteValue_3.htm) values. `Utf8JsonWriter` doesn't have equivalent methods. Instead, format these values as strings (by calling `ToString()`, for example) and call . +`JsonTextWriter` provides `WriteValue` methods for [TimeSpan](https://www.newtonsoft.com/json/help/html/M_Newtonsoft_Json_JsonTextWriter_WriteValue_18.htm), [Uri](https://www.newtonsoft.com/json/help/html/M_Newtonsoft_Json_JsonTextWriter_WriteValue_22.htm), and [char](https://www.newtonsoft.com/json/help/html/M_Newtonsoft_Json_JsonTextWriter_WriteValue_3.htm) values. `Utf8JsonWriter` doesn't have equivalent methods. Instead, format these values as strings (by calling `ToString()`, for example) and call . ### Multi-target for writing JSON diff --git a/docs/standard/serialization/system-text-json/preserve-references.md b/docs/standard/serialization/system-text-json/preserve-references.md index 60a7e8f4a0f0c..565f5155957df 100644 --- a/docs/standard/serialization/system-text-json/preserve-references.md +++ b/docs/standard/serialization/system-text-json/preserve-references.md @@ -20,7 +20,7 @@ This article shows how to preserve references and handle or ignore circular refe ## Preserve references and handle circular references -To preserve references and handle circular references, set to . This setting causes the following behavior: +To preserve references and handle circular references, set to . This setting causes the following behavior: * On serialize: @@ -39,15 +39,15 @@ This feature can't be used to preserve value types or immutable types. On deseri For value types, immutable types, and arrays, no reference metadata is serialized. On deserialization, an exception is thrown if `$ref` or `$id` is found. However, value types ignore `$id` (and `$values` in the case of collections) to make it possible to deserialize payloads that were serialized by using Newtonsoft.Json, which does serialize metadata for such types. -To determine if objects are equal, System.Text.Json uses , which uses reference equality () instead of value equality () when comparing two object instances. +To determine if objects are equal, System.Text.Json uses , which uses reference equality () instead of value equality () when comparing two object instances. -For more information about how references are serialized and deserialized, see . +For more information about how references are serialized and deserialized, see . The class defines the behavior of preserving references on serialization and deserialization. Create a derived class to specify custom behavior. For an example, see [GuidReferenceResolver](https://github.com/dotnet/docs/blob/main/docs/standard/serialization/system-text-json/snippets/how-to-contd/csharp/GuidReferenceResolverExample.cs). ### Persist reference metadata across multiple serialization and deserialization calls -By default, reference data is only cached for each call to or . To persist references from one `Serialize` or `Deserialize` call to another one, root the instance in the call site of `Serialize`/`Deserialize`. The following code shows an example for this scenario: +By default, reference data is only cached for each call to or . To persist references from one `Serialize` or `Deserialize` call to another one, root the instance in the call site of `Serialize`/`Deserialize`. The following code shows an example for this scenario: * You have a list of `Employee` objects and you have to serialize each one individually. * You want to take advantage of the references saved in the resolver for the `ReferenceHandler`. @@ -70,11 +70,11 @@ When the sample code calls the serializer, it uses a to . The serializer sets circular reference properties to `null`, as shown in the following example: +Instead of handling circular references, you can ignore them. To ignore circular references, set to . The serializer sets circular reference properties to `null`, as shown in the following example: :::code language="csharp" source="snippets/how-to-6-0/csharp/SerializeIgnoreCycles.cs" highlight="32,59"::: -In the preceding example, `Manager` under `Adrian King` is serialized as `null` to avoid the circular reference. This behavior has the following advantages over : +In the preceding example, `Manager` under `Adrian King` is serialized as `null` to avoid the circular reference. This behavior has the following advantages over : * It decreases payload size. * It creates JSON that is comprehensible for serializers other than System.Text.Json and Newtonsoft.Json. diff --git a/docs/standard/serialization/system-text-json/required-properties.md b/docs/standard/serialization/system-text-json/required-properties.md index ffedfc46e2a66..46d8c3b921a13 100644 --- a/docs/standard/serialization/system-text-json/required-properties.md +++ b/docs/standard/serialization/system-text-json/required-properties.md @@ -6,7 +6,7 @@ no-loc: [System.Text.Json, Newtonsoft.Json] --- # Required properties -You can mark certain properties to signify that they must be present in the JSON payload for deserialization to succeed. Similarly, you can set an option to specify that all non-optional constructor parameters are present in the JSON payload. If one or more of these required properties is not present, the methods throw a . +You can mark certain properties to signify that they must be present in the JSON payload for deserialization to succeed. Similarly, you can set an option to specify that all non-optional constructor parameters are present in the JSON payload. If one or more of these required properties is not present, the methods throw a . There are three ways to mark a property or field as required for JSON deserialization: diff --git a/docs/standard/serialization/system-text-json/source-generation.md b/docs/standard/serialization/system-text-json/source-generation.md index 5110451dcffd7..5c9a796cbcfae 100644 --- a/docs/standard/serialization/system-text-json/source-generation.md +++ b/docs/standard/serialization/system-text-json/source-generation.md @@ -27,7 +27,7 @@ To use source generation with all defaults (both modes, default options): 1. Specify the type to serialize or deserialize by applying to the context class. 1. Call a method that either: - - Takes a instance, or + - Takes a instance, or - Takes a instance, or - Takes a instance and you've set its property to the `Default` property of the context type. @@ -61,7 +61,7 @@ In the following examples, the static `Default` property of the context type pro #### Serialization examples -Using : +Using : :::code language="csharp" source="snippets/source-generation/csharp/BothModesNoOptions.cs" id="SerializeWithTypeInfo"::: @@ -75,7 +75,7 @@ Using : #### Deserialization examples -Using : +Using : :::code language="csharp" source="snippets/source-generation/csharp/BothModesNoOptions.cs" id="DeserializeWithTypeInfo"::: @@ -138,9 +138,9 @@ You can specify metadata-based mode or serialization-optimization mode for an en ## Source-generation support in ASP.NET Core -In Blazor apps, use overloads of and extension methods that take a source generation context or `TypeInfo`. +In Blazor apps, use overloads of and extension methods that take a source generation context or `TypeInfo`. -Starting with .NET 8, you can also use overloads of extension methods that accept a source generation context or `TypeInfo`. +Starting with .NET 8, you can also use overloads of extension methods that accept a source generation context or `TypeInfo`. In Razor Pages, MVC, SignalR, and Web API apps, use the property to specify the context. @@ -242,13 +242,13 @@ Any change made to the converter. Or to set a [blanket policy](#blanket-policy) for all enumerations, use the attribute. +By default, enums are serialized as numbers. To [serialize a specific enum's fields as strings](#jsonstringenumconvertert-converter) when using source generation, annotate it with the converter. Or to set a [blanket policy](#blanket-policy) for all enumerations, use the attribute. ### `JsonStringEnumConverter` converter -To serialize enum names as strings using source generation, use the converter. (The non-generic type is not supported by the Native AOT runtime.) +To serialize enum names as strings using source generation, use the converter. (The non-generic type is not supported by the Native AOT runtime.) -Annotate the enumeration type with the converter using the attribute: +Annotate the enumeration type with the converter using the attribute: :::code language="csharp" source="snippets/how-to/csharp/WeatherForecast.cs" id="WFWithConverterEnum"::: @@ -272,7 +272,7 @@ The resulting JSON looks like the following example: ### Blanket policy -Instead of using the type, you can apply a blanket policy to serialize enums as strings by using the . Create a class and annotate it with the *and * attributes: +Instead of using the type, you can apply a blanket policy to serialize enums as strings by using the . Create a class and annotate it with the *and * attributes: :::code language="csharp" source="snippets/how-to/csharp/RoundtripEnumSourceGeneration.cs" id="Context2"::: diff --git a/docs/standard/serialization/system-text-json/supported-types.md b/docs/standard/serialization/system-text-json/supported-types.md index 70f6777bad436..e33d40a228418 100644 --- a/docs/standard/serialization/system-text-json/supported-types.md +++ b/docs/standard/serialization/system-text-json/supported-types.md @@ -29,7 +29,7 @@ The following code snippet shows the serialization of a simple struct. .NET collection types serialize as JSON arrays. supports a collection type for serialization if it: -* Derives from or . +* Derives from or . * Contains elements that are serializable. The serializer calls the method and writes the elements. @@ -79,26 +79,26 @@ The following sections are organized by namespace and show which types are suppo | Type | Serialization | Deserialization | |-----------------------------------------------------------|---------------|-----------------| -| \* | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| † | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| \* | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| \* | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| | ✔️ | ❌ | -| | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| \* | ✔️ | ✔️ | -| \* | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| ‡ | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| † | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ❌ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| ‡ | ✔️ | ✔️ | \* See [Supported key types](#supported-key-types). @@ -112,11 +112,11 @@ The following examples use streams as a representation of any async source of da ##### Stream serialization -`System.Text.Json` supports serializing values as JSON arrays, as shown in the following example: +`System.Text.Json` supports serializing values as JSON arrays, as shown in the following example: :::code language="csharp" source="snippets/supported-types/csharp/IAsyncEnumerableSerialize.cs" highlight="15"::: -`IAsyncEnumerable` values are only supported by the asynchronous serialization methods, such as . +`IAsyncEnumerable` values are only supported by the asynchronous serialization methods, such as . ##### Stream deserialization @@ -126,7 +126,7 @@ The `DeserializeAsyncEnumerable` method supports streaming deserialization, as s The `DeserializeAsyncEnumerable` method only supports reading from root-level JSON arrays. -The method supports `IAsyncEnumerable`, but its signature doesn't allow streaming. It returns the final result as a single value, as shown in the following example. +The method supports `IAsyncEnumerable`, but its signature doesn't allow streaming. It returns the final result as a single value, as shown in the following example. :::code language="csharp" source="snippets/supported-types/csharp/IAsyncEnumerableDeserializeNonStreaming.cs" highlight="16"::: @@ -136,18 +136,18 @@ In this example, the deserializer buffers all `IAsyncEnumerable` contents in | Type | Serialization | Deserialization | |-------------------------------------------------------------------|---------------|-----------------| -| † | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| \* | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| † | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| † | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| \* | ✔️ | ✔️ | +| † | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| † | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| † | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | \* See [Support round trip for `Stack` types](converters-how-to.md#support-round-trip-for-stack-types). @@ -171,11 +171,11 @@ In this example, the deserializer buffers all `IAsyncEnumerable` contents in | Type | Serialization | Deserialization | |---------------------------------------------------------------|---------------|-----------------| -| | ✔️ | ❌ | -| | ✔️ | ❌ | -| † | ✔️ | ✔️ | -| | ✔️ | ✔️ | -| \* | ✔️ | ✔️ | +| | ✔️ | ❌ | +| | ✔️ | ❌ | +| † | ✔️ | ✔️ | +| | ✔️ | ✔️ | +| \* | ✔️ | ✔️ | \* See [Support round trip for `Stack` types](converters-how-to.md#support-round-trip-for-stack-types). @@ -185,12 +185,12 @@ In this example, the deserializer buffers all `IAsyncEnumerable` contents in | Type | Serialization | Deserialization | |----------------------------------------------------------------|---------------|-----------------| -| | ✔️ | ✔️ | -| [KeyedCollection\](xref:System.Collections.ObjectModel.KeyedCollection%602) \* |✔️|❌| -| | ✔️ | ✔️ | -| | ✔️ | ❌ | -| | ✔️ | ❌ | -| | ✔️ | ❌ | +| | ✔️ | ✔️ | +| [KeyedCollection\](xref:System.Collections.ObjectModel.KeyedCollection`2) \* |✔️|❌| +| | ✔️ | ✔️ | +| | ✔️ | ❌ | +| | ✔️ | ❌ | +| | ✔️ | ❌ | \* Non-`string` keys are not supported. @@ -208,17 +208,17 @@ A custom collection is supported for deserialization if it: * Has a parameterless constructor. * Contains element types that are supported by . * Implements or inherits one or more of the following interfaces or classes: - * - * \* - * + * + * \* + * * - * † + * † * - * + * * - * + * * \* - * \* + * \* \* See [Support round trip for `Stack` types](converters-how-to.md#support-round-trip-for-stack-types). diff --git a/docs/standard/serialization/system-text-json/use-dom.md b/docs/standard/serialization/system-text-json/use-dom.md index ead0601b396fa..e53732c0d2a28 100644 --- a/docs/standard/serialization/system-text-json/use-dom.md +++ b/docs/standard/serialization/system-text-json/use-dom.md @@ -75,7 +75,7 @@ The preceding code: ### `JsonNode` with `JsonSerializerOptions` -You can use `JsonSerializer` to serialize and deserialize an instance of `JsonNode`. However, if you use an overload that takes `JsonSerializerOptions`, the options instance is only used to get custom converters. Other features of the options instance are not used. For example, if you set to and call `JsonSerializer` with an overload that takes `JsonSerializerOptions`, null properties won't be ignored. +You can use `JsonSerializer` to serialize and deserialize an instance of `JsonNode`. However, if you use an overload that takes `JsonSerializerOptions`, the options instance is only used to get custom converters. Other features of the options instance are not used. For example, if you set to and call `JsonSerializer` with an overload that takes `JsonSerializerOptions`, null properties won't be ignored. The same limitation applies to the `JsonNode` methods that take a `JsonSerializerOptions` parameter: and . These APIs use `JsonSerializerOptions` only to get custom converters. @@ -109,9 +109,9 @@ The preceding code: * Assumes the JSON to analyze is in a string named `jsonString`. * Calculates an average grade for objects in a `Students` array that have a `Grade` property. * Assigns a default grade of 70 for students who don't have a grade. -* Creates the `JsonDocument` instance in a [`using` statement](../../../csharp/language-reference/statements/using.md) because `JsonDocument` implements `IDisposable`. After a `JsonDocument` instance is disposed, you lose access to all of its `JsonElement` instances also. To retain access to a `JsonElement` instance, make a copy of it before the parent `JsonDocument` instance is disposed. To make a copy, call . For more information, see [JsonDocument is IDisposable](migrate-from-newtonsoft.md#jsondocument-is-idisposable). +* Creates the `JsonDocument` instance in a [`using` statement](../../../csharp/language-reference/statements/using.md) because `JsonDocument` implements `IDisposable`. After a `JsonDocument` instance is disposed, you lose access to all of its `JsonElement` instances also. To retain access to a `JsonElement` instance, make a copy of it before the parent `JsonDocument` instance is disposed. To make a copy, call . For more information, see [JsonDocument is IDisposable](migrate-from-newtonsoft.md#jsondocument-is-idisposable). -The preceding example code counts students by incrementing a `count` variable with each iteration. An alternative is to call , as shown in the following example: +The preceding example code counts students by incrementing a `count` variable with each iteration. An alternative is to call , as shown in the following example: :::code language="csharp" source="snippets/how-to/csharp/JsonDocumentDataAccess.cs" id="AverageGrades2"::: :::code language="vb" source="snippets/how-to/vb/JsonDocumentDataAccess.vb" id="AverageGrades2"::: @@ -126,7 +126,7 @@ For a similar example that uses `JsonNode` instead of `JsonDocument`, see [JsonN Searches on `JsonElement` require a sequential search of the properties and hence are relatively slow (for example when using `TryGetProperty`). is designed to minimize initial parse time rather than lookup time. Therefore, use the following approaches to optimize performance when searching through a `JsonDocument` object: -* Use the built-in enumerators ( and ) rather than doing your own indexing or loops. +* Use the built-in enumerators ( and ) rather than doing your own indexing or loops. * Don't do a sequential search on the whole `JsonDocument` through every property by using `RootElement`. Instead, search on nested JSON objects based on the known structure of the JSON data. For example, the preceding code examples look for a `Grade` property in `Student` objects by looping through the `Student` objects and getting the value of `Grade` for each, rather than searching through all `JsonElement` objects looking for `Grade` properties. Doing the latter would result in unnecessary passes over the same data. ### Compare JsonElements @@ -146,7 +146,7 @@ The preceding code: * Reads a JSON file, loads the data into a `JsonDocument`, and writes formatted (pretty-printed) JSON to a file. * Uses to specify that comments in the input JSON are allowed but ignored. -* When finished, calls on the writer. An alternative is to let the writer auto-flush when it's disposed. +* When finished, calls on the writer. An alternative is to let the writer auto-flush when it's disposed. Here's an example of JSON input to be processed by the example code: @@ -160,7 +160,7 @@ The result is the following pretty-printed JSON output: `JsonDocument` builds an in-memory view of the data into a pooled buffer. Therefore the `JsonDocument` type implements `IDisposable` and needs to be used inside a `using` block. -Only return a `JsonDocument` from your API if you want to transfer lifetime ownership and dispose responsibility to the caller. In most scenarios, that isn't necessary. If the caller needs to work with the entire JSON document, return the of the , which is a . If the caller needs to work with a particular element within the JSON document, return the of that . If you return the `RootElement` or a sub-element directly without making a `Clone`, the caller won't be able to access the returned `JsonElement` after the `JsonDocument` that owns it is disposed. +Only return a `JsonDocument` from your API if you want to transfer lifetime ownership and dispose responsibility to the caller. In most scenarios, that isn't necessary. If the caller needs to work with the entire JSON document, return the of the , which is a . If the caller needs to work with a particular element within the JSON document, return the of that . If you return the `RootElement` or a sub-element directly without making a `Clone`, the caller won't be able to access the returned `JsonElement` after the `JsonDocument` that owns it is disposed. Here's an example that requires you to make a `Clone`: @@ -189,7 +189,7 @@ public JsonElement ReturnFileName(JsonElement source) ### `JsonDocument` with `JsonSerializerOptions` -You can use `JsonSerializer` to serialize and deserialize an instance of `JsonDocument`. However, the implementation for reading and writing `JsonDocument` instances by using `JsonSerializer` is a wrapper over the and . This wrapper does not forward any `JsonSerializerOptions` (serializer features) to `Utf8JsonReader` or `Utf8JsonWriter`. For example, if you set to and call `JsonSerializer` with an overload that takes `JsonSerializerOptions`, null properties won't be ignored. +You can use `JsonSerializer` to serialize and deserialize an instance of `JsonDocument`. However, the implementation for reading and writing `JsonDocument` instances by using `JsonSerializer` is a wrapper over the and . This wrapper does not forward any `JsonSerializerOptions` (serializer features) to `Utf8JsonReader` or `Utf8JsonWriter`. For example, if you set to and call `JsonSerializer` with an overload that takes `JsonSerializerOptions`, null properties won't be ignored. The following example illustrates the result of using methods that take a `JsonSerializerOptions` parameter and serialize a `JsonDocument` instance: diff --git a/docs/standard/serialization/system-text-json/use-utf8jsonreader.md b/docs/standard/serialization/system-text-json/use-utf8jsonreader.md index 33f7978daf207..19a9e0ced39cb 100644 --- a/docs/standard/serialization/system-text-json/use-utf8jsonreader.md +++ b/docs/standard/serialization/system-text-json/use-utf8jsonreader.md @@ -13,7 +13,7 @@ ms.topic: how-to This article shows how you can use the type for building custom parsers and deserializers. - is a high-performance, low allocation, forward-only reader for UTF-8 encoded JSON text. The text is read from a `ReadOnlySpan` or `ReadOnlySequence`. `Utf8JsonReader` is a low-level type that can be used to build custom parsers and deserializers. (The methods use `Utf8JsonReader` under the covers.) + is a high-performance, low allocation, forward-only reader for UTF-8 encoded JSON text. The text is read from a `ReadOnlySpan` or `ReadOnlySequence`. `Utf8JsonReader` is a low-level type that can be used to build custom parsers and deserializers. (The methods use `Utf8JsonReader` under the covers.) The following example shows how to use the class. This code assumes that the `jsonUtf8Bytes` variable is a byte array that contains valid JSON, encoded as UTF-8. @@ -59,7 +59,7 @@ When using the `Utf8JsonReader` to read from a stream, the following rules apply * The buffer containing the partial JSON payload must be at least as large as the largest JSON token within it so that the reader can make forward progress. * The buffer must be at least as large as the largest sequence of white space within the JSON. -* The reader doesn't keep track of the data it has read until it completely reads the next in the JSON payload. So when there are bytes left over in the buffer, you have to pass them to the reader again. You can use to determine how many bytes are left over. +* The reader doesn't keep track of the data it has read until it completely reads the next in the JSON payload. So when there are bytes left over in the buffer, you have to pass them to the reader again. You can use to determine how many bytes are left over. The following code illustrates how to read from a stream. The example shows a . Similar code will work with a , except when the `FileStream` contains a UTF-8 BOM at the start. In that case, you need to strip those three bytes from the buffer before passing the remaining bytes to the `Utf8JsonReader`. Otherwise the reader would throw an exception, since the BOM is not considered a valid part of the JSON. @@ -74,7 +74,7 @@ The preceding example sets no limit to how large the buffer can grow. If the tok Because the `Utf8JsonReader` type is a `ref struct`, it has [certain limitations](../../../csharp/language-reference/builtin-types/ref-struct.md). For example, it can't be stored as a field on a class or struct other than a `ref struct`. -To achieve high performance, `Utf8JsonReader` must be a `ref struct`, because it needs to cache the input [ReadOnlySpan\](xref:System.ReadOnlySpan%601) (which itself is a `ref struct`). In addition, the `Utf8JsonReader` type is mutable since it holds state. Therefore, **pass it by reference** rather than by value. Passing the `Utf8JsonReader` by value would result in a struct copy, and the state changes wouldn't be visible to the caller. +To achieve high performance, `Utf8JsonReader` must be a `ref struct`, because it needs to cache the input [ReadOnlySpan\](xref:System.ReadOnlySpan`1) (which itself is a `ref struct`). In addition, the `Utf8JsonReader` type is mutable since it holds state. Therefore, **pass it by reference** rather than by value. Passing the `Utf8JsonReader` by value would result in a struct copy, and the state changes wouldn't be visible to the caller. For more information about how to use ref structs, see [Avoid allocations](../../../csharp/advanced-topics/performance/index.md). @@ -84,7 +84,7 @@ To achieve the best possible performance while using `Utf8JsonReader`, read JSON ## Read with multi-segment ReadOnlySequence -If your JSON input is a [ReadOnlySpan\](xref:System.ReadOnlySpan%601), each JSON element can be accessed from the `ValueSpan` property on the reader as you go through the read loop. However, if your input is a [ReadOnlySequence\](xref:System.Buffers.ReadOnlySequence%601) (which is the result of reading from a ), some JSON elements might straddle multiple segments of the `ReadOnlySequence` object. These elements would not be accessible from in a contiguous memory block. Instead, whenever you have a multi-segment `ReadOnlySequence` as input, poll the property on the reader to figure out how to access the current JSON element. Here's a recommended pattern: +If your JSON input is a [ReadOnlySpan\](xref:System.ReadOnlySpan`1), each JSON element can be accessed from the `ValueSpan` property on the reader as you go through the read loop. However, if your input is a [ReadOnlySequence\](xref:System.Buffers.ReadOnlySequence`1) (which is the result of reading from a ), some JSON elements might straddle multiple segments of the `ReadOnlySequence` object. These elements would not be accessible from in a contiguous memory block. Instead, whenever you have a multi-segment `ReadOnlySequence` as input, poll the property on the reader to figure out how to access the current JSON element. Here's a recommended pattern: ```csharp while (reader.Read()) @@ -116,7 +116,7 @@ To stream multiple top-level values, use the to do byte-by-byte comparisons by calling . Instead, call , because this method unescapes any characters that are escaped in the JSON. Here's an example that shows how to search for a property that's named "name": +To look up property names, don't use to do byte-by-byte comparisons by calling . Instead, call , because this method unescapes any characters that are escaped in the JSON. Here's an example that shows how to search for a property that's named "name": :::code language="csharp" source="snippets/how-to/csharp/ValueTextEqualsExample.cs" id="DefineUtf8Var"::: @@ -124,7 +124,7 @@ To look up property names, don't use returns a `bool`. It throws an exception if it finds `Null` in the JSON. The following examples show two ways to handle nulls, one by returning a nullable value type and one by returning the default value: +The built-in `System.Text.Json` APIs return only non-nullable value types. For example, returns a `bool`. It throws an exception if it finds `Null` in the JSON. The following examples show two ways to handle nulls, one by returning a nullable value type and one by returning the default value: ```csharp public bool? ReadAsNullableBoolean() @@ -166,13 +166,13 @@ Use the ## Consume decoded JSON strings -Starting in .NET 7, you can use the method instead of to consume a decoded JSON string. Unlike , which always allocates a new string, lets you copy the unescaped string to a buffer that you own. The following code snippet shows an example of consuming a UTF-16 string using . +Starting in .NET 7, you can use the method instead of to consume a decoded JSON string. Unlike , which always allocates a new string, lets you copy the unescaped string to a buffer that you own. The following code snippet shows an example of consuming a UTF-16 string using . :::code language="csharp" source="snippets/how-to/csharp/Utf8ReaderCopyString.cs" id="Snippet1"::: ## Related APIs -* To deserialize a custom type from a `Utf8JsonReader` instance, call or . For an example, see [Deserialize from UTF-8](deserialization.md#deserialize-from-utf-8). +* To deserialize a custom type from a `Utf8JsonReader` instance, call or . For an example, see [Deserialize from UTF-8](deserialization.md#deserialize-from-utf-8). * and the classes that derive from it provide the ability to create a mutable DOM. You can convert a `Utf8JsonReader` instance to a `JsonNode` by calling . The following code snippet shows an example. diff --git a/docs/standard/serialization/system-text-json/use-utf8jsonwriter.md b/docs/standard/serialization/system-text-json/use-utf8jsonwriter.md index cef0d0ccc9cf5..654219a70d55c 100644 --- a/docs/standard/serialization/system-text-json/use-utf8jsonwriter.md +++ b/docs/standard/serialization/system-text-json/use-utf8jsonwriter.md @@ -13,7 +13,7 @@ ms.topic: how-to This article shows how to use the type for building custom serializers. - is a high-performance way to write UTF-8 encoded JSON text from common .NET types like `String`, `Int32`, and `DateTime`. The writer is a low-level type that can be used to build custom serializers. The method uses `Utf8JsonWriter` under the covers. + is a high-performance way to write UTF-8 encoded JSON text from common .NET types like `String`, `Int32`, and `DateTime`. The writer is a low-level type that can be used to build custom serializers. The method uses `Utf8JsonWriter` under the covers. The following example shows how to use the class: @@ -28,7 +28,7 @@ This approach also works if you need to do custom escaping. `System.Text.Json` d ## Write raw JSON -In some scenarios, you might want to write "raw" JSON to a JSON payload that you're creating with `Utf8JsonWriter`. You can use to do that. Here are typical scenarios: +In some scenarios, you might want to write "raw" JSON to a JSON payload that you're creating with `Utf8JsonWriter`. You can use to do that. Here are typical scenarios: * You have an existing JSON payload that you want to enclose in new JSON. * You want to format values differently from the default `Utf8JsonWriter` formatting. @@ -45,14 +45,14 @@ The [StringEscapeHandling](https://www.newtonsoft.com/json/help/html/T_Newtonsof To write null values by using `Utf8JsonWriter`, call: -* to write a key-value pair with null as the value. -* to write null as an element of a JSON array. +* to write a key-value pair with null as the value. +* to write null as an element of a JSON array. -For a string property, if the string is null, and are equivalent to `WriteNull` and `WriteNullValue`. +For a string property, if the string is null, and are equivalent to `WriteNull` and `WriteNullValue`. ## Write Timespan, Uri, or char values -To write `Timespan`, `Uri`, or `char` values, format them as strings (by calling `ToString()`, for example) and call . +To write `Timespan`, `Uri`, or `char` values, format them as strings (by calling `ToString()`, for example) and call . ## See also diff --git a/docs/standard/serialization/system-text-json/visual-basic-support.md b/docs/standard/serialization/system-text-json/visual-basic-support.md index 31f802a5f7e33..765b018cbde03 100644 --- a/docs/standard/serialization/system-text-json/visual-basic-support.md +++ b/docs/standard/serialization/system-text-json/visual-basic-support.md @@ -9,7 +9,7 @@ no-loc: [System.Text.Json, Newtonsoft.Json] Parts of use [ref structs](../../../csharp/language-reference/builtin-types/ref-struct.md), which are not supported by Visual Basic. If you try to use System.Text.Json ref struct APIs with Visual Basic, you get BC40000 compiler errors. The error message indicates that the problem is an obsolete API, but the actual issue is lack of ref struct support in the compiler. The following parts of System.Text.Json aren't usable from Visual Basic: -* The struct. Since the method takes a `Utf8JsonReader` parameter, this limitation means you can't use Visual Basic to write custom converters. A workaround for this is to implement custom converters in a C# library assembly, and reference that assembly from your VB project. This assumes that all you do in Visual Basic is register the converters into the serializer. You can't call the `Read` methods of the converters from Visual Basic code. -* Overloads of other APIs that include a type. Most methods include overloads that use `String` instead of `ReadOnlySpan`. +* The struct. Since the method takes a `Utf8JsonReader` parameter, this limitation means you can't use Visual Basic to write custom converters. A workaround for this is to implement custom converters in a C# library assembly, and reference that assembly from your VB project. This assumes that all you do in Visual Basic is register the converters into the serializer. You can't call the `Read` methods of the converters from Visual Basic code. +* Overloads of other APIs that include a type. Most methods include overloads that use `String` instead of `ReadOnlySpan`. These restrictions are in place because ref structs cannot be used safely without language support, even when just "passing data through." You should not subvert this error. If you do, your Visual Basic code can corrupt memory. diff --git a/docs/standard/serialization/xml-schema-definition-tool-xsd-exe.md b/docs/standard/serialization/xml-schema-definition-tool-xsd-exe.md index 4c513b87852e1..bd93ee83f2336 100644 --- a/docs/standard/serialization/xml-schema-definition-tool-xsd-exe.md +++ b/docs/standard/serialization/xml-schema-definition-tool-xsd-exe.md @@ -50,8 +50,8 @@ xsd {file.dll | file.exe} [-outputdir:directory] [/type:typename [...]][/paramet |Option|Description| |------------|-----------------| -|**/c\[lasses\]**|Generates classes that correspond to the specified schema. To read XML data into the object, use the method.| -|**/d\[ataset\]**|Generates a class derived from that corresponds to the specified schema. To read XML data into the derived class, use the method.| +|**/c\[lasses\]**|Generates classes that correspond to the specified schema. To read XML data into the object, use the method.| +|**/d\[ataset\]**|Generates a class derived from that corresponds to the specified schema. To read XML data into the derived class, use the method.| You can also specify any of the following options for .xsd files. diff --git a/docs/standard/simd.md b/docs/standard/simd.md index cbe484c6cbd73..c275fc3c1fa2a 100644 --- a/docs/standard/simd.md +++ b/docs/standard/simd.md @@ -23,10 +23,10 @@ The .NET SIMD-accelerated types include the following types: - The type, which represents a vector that is used to encode three-dimensional physical rotations using values. -- The type, which represents a vector of a specified numeric type and provides a broad set of operators that benefit from SIMD support. The count of a instance is fixed for the lifetime of an application, but its value depends on the CPU of the machine running the code. +- The type, which represents a vector of a specified numeric type and provides a broad set of operators that benefit from SIMD support. The count of a instance is fixed for the lifetime of an application, but its value depends on the CPU of the machine running the code. > [!NOTE] - > The type is not included in the .NET Framework. You must install the [System.Numerics.Vectors](https://www.nuget.org/packages/System.Numerics.Vectors) NuGet package to get access to this type. + > The type is not included in .NET Framework. You must install the [System.Numerics.Vectors](https://www.nuget.org/packages/System.Numerics.Vectors) NuGet package to get access to this type. The SIMD-accelerated types are implemented in such a way that they can be used with non-SIMD-accelerated hardware or JIT compilers. To determine whether SIMD acceleration is available at runtime, use . If that property returns `true`, at least some APIs use hardware-accelerated SIMD operations. If it returns `false`, no APIs are hardware accelerated. @@ -71,9 +71,9 @@ var mResult = Matrix4x4.Multiply(m1, m2); ## Vector\ -The gives the ability to use longer vectors. The count of a instance is fixed, but its value depends on the CPU of the machine running the code. +The gives the ability to use longer vectors. The count of a instance is fixed, but its value depends on the CPU of the machine running the code. -The following example demonstrates how to calculate the element-wise sum of two arrays using . +The following example demonstrates how to calculate the element-wise sum of two arrays using . ```csharp double[] Sum(double[] left, double[] right) diff --git a/docs/standard/threading/barrier.md b/docs/standard/threading/barrier.md index a88b2ad83357e..77448eae7369f 100644 --- a/docs/standard/threading/barrier.md +++ b/docs/standard/threading/barrier.md @@ -2,50 +2,50 @@ description: "Learn more about: Barrier" title: "Barrier" ms.date: "09/14/2018" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "synchronization primitives, Barrier" ms.assetid: 613a8bc7-6a28-4795-bd6c-1abd9050478f --- # Barrier -A is a synchronization primitive that enables multiple threads (known as *participants*) to work concurrently on an algorithm in phases. Each participant executes until it reaches the barrier point in the code. The barrier represents the end of one phase of work. When a participant reaches the barrier, it blocks until all participants have reached the same barrier. After all participants have reached the barrier, you can optionally invoke a post-phase action. This post-phase action can be used to perform actions by a single thread while all other threads are still blocked. After the action has been executed, the participants are all unblocked. - - The following code snippet shows a basic barrier pattern. - +A is a synchronization primitive that enables multiple threads (known as *participants*) to work concurrently on an algorithm in phases. Each participant executes until it reaches the barrier point in the code. The barrier represents the end of one phase of work. When a participant reaches the barrier, it blocks until all participants have reached the same barrier. After all participants have reached the barrier, you can optionally invoke a post-phase action. This post-phase action can be used to perform actions by a single thread while all other threads are still blocked. After the action has been executed, the participants are all unblocked. + + The following code snippet shows a basic barrier pattern. + [!code-csharp[CDS_Barrier#02](../../../samples/snippets/csharp/VS_Snippets_Misc/cds_barrier/cs/barrier.cs#02)] - [!code-vb[CDS_Barrier#02](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_barrier/vb/barrier_vb.vb#02)] - - For a complete example, see [How to: synchronize concurrent operations with a Barrier](how-to-synchronize-concurrent-operations-with-a-barrier.md). - + [!code-vb[CDS_Barrier#02](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_barrier/vb/barrier_vb.vb#02)] + + For a complete example, see [How to: synchronize concurrent operations with a Barrier](how-to-synchronize-concurrent-operations-with-a-barrier.md). + ## Adding and removing participants - When you create a instance, specify the number of participants. You can also add or remove participants dynamically at any time. For example, if one participant solves its part of the problem, you can store the result, stop execution on that thread, and call to decrement the number of participants in the barrier. When you add a participant by calling , the return value specifies the current phase number, which may be useful in order to initialize the work of the new participant. - + When you create a instance, specify the number of participants. You can also add or remove participants dynamically at any time. For example, if one participant solves its part of the problem, you can store the result, stop execution on that thread, and call to decrement the number of participants in the barrier. When you add a participant by calling , the return value specifies the current phase number, which may be useful in order to initialize the work of the new participant. + ## Broken barriers - Deadlocks can occur if one participant fails to reach the barrier. To avoid these deadlocks, use the overloads of the method to specify a time-out period and a cancellation token. These overloads return a Boolean value that every participant can check before it continues to the next phase. - + Deadlocks can occur if one participant fails to reach the barrier. To avoid these deadlocks, use the overloads of the method to specify a time-out period and a cancellation token. These overloads return a Boolean value that every participant can check before it continues to the next phase. + ## Post-phase exceptions - If the post-phase delegate throws an exception, it is wrapped in a object which is then propagated to all participants. - + If the post-phase delegate throws an exception, it is wrapped in a object which is then propagated to all participants. + ## Barrier versus ContinueWhenAll - Barriers are especially useful when the threads are performing multiple phases in loops. If your code requires only one or two phases of work, consider whether to use objects with any kind of implicit join, including: - -- - -- - -- - -- - - For more information, see [Chaining Tasks by Using Continuation Tasks](../parallel-programming/chaining-tasks-by-using-continuation-tasks.md). - + Barriers are especially useful when the threads are performing multiple phases in loops. If your code requires only one or two phases of work, consider whether to use objects with any kind of implicit join, including: + +- + +- + +- + +- + + For more information, see [Chaining Tasks by Using Continuation Tasks](../parallel-programming/chaining-tasks-by-using-continuation-tasks.md). + ## See also - [Threading objects and features](threading-objects-and-features.md) diff --git a/docs/standard/threading/cancellation-in-managed-threads.md b/docs/standard/threading/cancellation-in-managed-threads.md index b8eca08334bb3..9d63f01047848 100644 --- a/docs/standard/threading/cancellation-in-managed-threads.md +++ b/docs/standard/threading/cancellation-in-managed-threads.md @@ -22,10 +22,10 @@ The general pattern for implementing the cooperative cancellation model is: - Provide a mechanism for each task or thread to respond to cancellation. -- Call the method to provide notification of cancellation. +- Call the method to provide notification of cancellation. > [!IMPORTANT] -> The class implements the interface. You should be sure to call the method when you have finished using the cancellation token source to free any unmanaged resources it holds. +> The class implements the interface. You should be sure to call the method when you have finished using the cancellation token source to free any unmanaged resources it holds. The following illustration shows the relationship between a token source and all the copies of its token. @@ -55,14 +55,14 @@ The general pattern for implementing the cooperative cancellation model is: ||Lightweight value type passed to one or more listeners, typically as a method parameter. Listeners monitor the value of the `IsCancellationRequested` property of the token by polling, callback, or wait handle.| ||Overloads of this exception's constructor accept a as a parameter. Listeners can optionally throw this exception to verify the source of the cancellation and notify others that it has responded to a cancellation request.| - The cancellation model is integrated into .NET in several types. The most important ones are , , and . We recommend that you use this cooperative cancellation model for all new library and application code. + The cancellation model is integrated into .NET in several types. The most important ones are , , and . We recommend that you use this cooperative cancellation model for all new library and application code. ## Code Example In the following example, the requesting object creates a object, and then passes its property to the cancelable operation. The operation that receives the request monitors the value of the property of the token by polling. When the value becomes `true`, the listener can terminate in whatever manner is appropriate. In this example, the method just exits, which is all that is required in many cases. > [!NOTE] -> The example uses the method to demonstrate that the cooperative cancellation framework is compatible with legacy APIs. For an example that uses the preferred type, see [How to: Cancel a Task and Its Children](../parallel-programming/how-to-cancel-a-task-and-its-children.md). +> The example uses the method to demonstrate that the cooperative cancellation framework is compatible with legacy APIs. For an example that uses the preferred type, see [How to: Cancel a Task and Its Children](../parallel-programming/how-to-cancel-a-task-and-its-children.md). [!code-csharp[Cancellation#1](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/cancellationex1.cs#1)] [!code-vb[Cancellation#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/cancellationex1.vb#1)] @@ -71,7 +71,7 @@ The general pattern for implementing the cooperative cancellation model is: In the cooperative cancellation framework, cancellation refers to operations, not objects. The cancellation request means that the operation should stop as soon as possible after any required cleanup is performed. One cancellation token should refer to one "cancelable operation," however that operation may be implemented in your program. After the property of the token has been set to `true`, it cannot be reset to `false`. Therefore, cancellation tokens cannot be reused after they have been canceled. - If you require an object cancellation mechanism, you can base it on the operation cancellation mechanism by calling the method, as shown in the following example. + If you require an object cancellation mechanism, you can base it on the operation cancellation mechanism by calling the method, as shown in the following example. [!code-csharp[Cancellation#2](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/objectcancellation1.cs#2)] [!code-vb[Cancellation#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/objectcancellation1.vb#2)] @@ -82,7 +82,7 @@ The general pattern for implementing the cooperative cancellation model is: In the user delegate, the implementer of a cancelable operation determines how to terminate the operation in response to a cancellation request. In many cases, the user delegate can just perform any required cleanup and then return immediately. - However, in more complex cases, it might be necessary for the user delegate to notify library code that cancellation has occurred. In such cases, the correct way to terminate the operation is for the delegate to call the , method, which will cause an to be thrown. Library code can catch this exception on the user delegate thread and examine the exception's token to determine whether the exception indicates cooperative cancellation or some other exceptional situation. + However, in more complex cases, it might be necessary for the user delegate to notify library code that cancellation has occurred. In such cases, the correct way to terminate the operation is for the delegate to call the , method, which will cause an to be thrown. Library code can catch this exception on the user delegate thread and examine the exception's token to determine whether the exception indicates cooperative cancellation or some other exceptional situation. The class handles in this way. For more information, see [Task Cancellation](../parallel-programming/task-cancellation.md). @@ -99,7 +99,7 @@ The general pattern for implementing the cooperative cancellation model is: Some operations can become blocked in such a way that they cannot check the value of the cancellation token in a timely manner. For these cases, you can register a callback method that unblocks the method when a cancellation request is received. - The method returns a object that is used specifically for this purpose. The following example shows how to use the method to cancel an asynchronous web request. + The method returns a object that is used specifically for this purpose. The following example shows how to use the method to cancel an asynchronous web request. [!code-csharp[Cancellation#4](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/cancellationex4.cs#4)] [!code-vb[Cancellation#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/cancellationex4.vb#4)] @@ -108,17 +108,17 @@ The general pattern for implementing the cooperative cancellation model is: In order to ensure system responsiveness and to avoid deadlocks, the following guidelines must be followed when registering callbacks: -- The callback method should be fast because it is called synchronously and therefore the call to does not return until the callback returns. +- The callback method should be fast because it is called synchronously and therefore the call to does not return until the callback returns. -- If you call while the callback is running, and you hold a lock that the callback is waiting on, your program can deadlock. After `Dispose` returns, you can free any resources required by the callback. +- If you call while the callback is running, and you hold a lock that the callback is waiting on, your program can deadlock. After `Dispose` returns, you can free any resources required by the callback. -- Callbacks should not perform any manual thread or usage in a callback. If a callback must run on a particular thread, use the constructor that enables you to specify that the target syncContext is the active . Performing manual threading in a callback can cause deadlock. +- Callbacks should not perform any manual thread or usage in a callback. If a callback must run on a particular thread, use the constructor that enables you to specify that the target syncContext is the active . Performing manual threading in a callback can cause deadlock. For a more complete example, see [How to: Register Callbacks for Cancellation Requests](how-to-register-callbacks-for-cancellation-requests.md). ### Listening by Using a Wait Handle - When a cancelable operation can block while it waits on a synchronization primitive such as a or , you can use the property to enable the operation to wait on both the event and the cancellation request. The wait handle of the cancellation token will become signaled in response to a cancellation request, and the method can use the return value of the method to determine whether it was the cancellation token that signaled. The operation can then just exit, or throw an , as appropriate. + When a cancelable operation can block while it waits on a synchronization primitive such as a or , you can use the property to enable the operation to wait on both the event and the cancellation request. The wait handle of the cancellation token will become signaled in response to a cancellation request, and the method can use the return value of the method to determine whether it was the cancellation token that signaled. The operation can then just exit, or throw an , as appropriate. [!code-csharp[Cancellation#5](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/cancellationex9.cs#5)] [!code-vb[Cancellation#5](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/cancellationex9.vb#5)] diff --git a/docs/standard/threading/countdownevent.md b/docs/standard/threading/countdownevent.md index 65635f2b9ce5b..380b8712da8ba 100644 --- a/docs/standard/threading/countdownevent.md +++ b/docs/standard/threading/countdownevent.md @@ -2,46 +2,46 @@ description: "Learn more about: CountdownEvent" title: "CountdownEvent" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "synchronization primitives, CountdownEvent" ms.assetid: eec3812a-e20f-4ecd-bfef-6921d508b708 --- # CountdownEvent - is a synchronization primitive that unblocks its waiting threads after it has been signaled a certain number of times. is designed for scenarios in which you would otherwise have to use a or and manually decrement a variable before signaling the event. For example, in a fork/join scenario, you can just create a that has a signal count of 5, and then start five work items on the thread pool and have each work item call when it completes. Each call to decrements the signal count by 1. On the main thread, the call to will block until the signal count is zero. - + is a synchronization primitive that unblocks its waiting threads after it has been signaled a certain number of times. is designed for scenarios in which you would otherwise have to use a or and manually decrement a variable before signaling the event. For example, in a fork/join scenario, you can just create a that has a signal count of 5, and then start five work items on the thread pool and have each work item call when it completes. Each call to decrements the signal count by 1. On the main thread, the call to will block until the signal count is zero. + > [!NOTE] -> For code that does not have to interact with legacy .NET Framework synchronization APIs, consider using objects or the method for an even easier approach to expressing fork-join parallelism. - - has these additional features: - -- The wait operation can be canceled by using cancellation tokens. - -- Its signal count can be incremented after the instance is created. - -- Instances can be reused after has returned by calling the method. - -- Instances expose a for integration with other .NET synchronization APIs, such as . - -## Basic Usage - - The following example demonstrates how to use a with work items. - +> For code that does not have to interact with legacy .NET Framework synchronization APIs, consider using objects or the method for an even easier approach to expressing fork-join parallelism. + + has these additional features: + +- The wait operation can be canceled by using cancellation tokens. + +- Its signal count can be incremented after the instance is created. + +- Instances can be reused after has returned by calling the method. + +- Instances expose a for integration with other .NET synchronization APIs, such as . + +## Basic Usage + + The following example demonstrates how to use a with work items. + [!code-csharp[CDS_CountdownEvent#01](../../../samples/snippets/csharp/VS_Snippets_Misc/cds_countdownevent/cs/countdownevent.cs#01)] - [!code-vb[CDS_CountdownEvent#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_countdownevent/vb/module1.vb#01)] - -## CountdownEvent With Cancellation + [!code-vb[CDS_CountdownEvent#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_countdownevent/vb/module1.vb#01)] + +## CountdownEvent With Cancellation + + The following example shows how to cancel the wait operation on by using a cancellation token. The basic pattern follows the model for unified cancellation, which was introduced in .NET Framework 4. For more information, see [Cancellation in Managed Threads](cancellation-in-managed-threads.md). - The following example shows how to cancel the wait operation on by using a cancellation token. The basic pattern follows the model for unified cancellation, which was introduced in .NET Framework 4. For more information, see [Cancellation in Managed Threads](cancellation-in-managed-threads.md). - [!code-csharp[CDS_CountdownEvent#02](../../../samples/snippets/csharp/VS_Snippets_Misc/cds_countdownevent/cs/countdownevent.cs#02)] - [!code-vb[CDS_CountdownEvent#02](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_countdownevent/vb/canceleventwait.vb#02)] - - Note that the wait operation does not cancel the threads that are signaling it. Typically, cancellation is applied to a logical operation, and that can include waiting on the event as well as all the work items that the wait is synchronizing. In this example, each work item is passed a copy of the same cancellation token so that it can respond to the cancellation request. - + [!code-vb[CDS_CountdownEvent#02](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_countdownevent/vb/canceleventwait.vb#02)] + + Note that the wait operation does not cancel the threads that are signaling it. Typically, cancellation is applied to a logical operation, and that can include waiting on the event as well as all the work items that the wait is synchronizing. In this example, each work item is passed a copy of the same cancellation token so that it can respond to the cancellation request. + ## See also - diff --git a/docs/standard/threading/creating-threads-and-passing-data-at-start-time.md b/docs/standard/threading/creating-threads-and-passing-data-at-start-time.md index cba9519355040..39ee33e922074 100644 --- a/docs/standard/threading/creating-threads-and-passing-data-at-start-time.md +++ b/docs/standard/threading/creating-threads-and-passing-data-at-start-time.md @@ -13,13 +13,13 @@ ms.topic: how-to --- # Create threads and pass data at start time -When an operating-system process is created, the operating system injects a thread to execute code in that process, including any original application domain. From that point on, application domains can be created and destroyed without any operating system threads necessarily being created or destroyed. If the code being executed is managed code, then a object for the thread executing in the current application domain can be obtained by retrieving the static property of type . This topic describes thread creation and discusses alternatives for passing data to the thread procedure. +When an operating-system process is created, the operating system injects a thread to execute code in that process, including any original application domain. From that point on, application domains can be created and destroyed without any operating system threads necessarily being created or destroyed. If the code being executed is managed code, then a object for the thread executing in the current application domain can be obtained by retrieving the static property of type . This topic describes thread creation and discusses alternatives for passing data to the thread procedure. ## Creating a thread - Creating a new object creates a new managed thread. The class has constructors that take a delegate or a delegate; the delegate wraps the method that is invoked by the new thread when you call the method. Calling more than once causes a to be thrown. + Creating a new object creates a new managed thread. The class has constructors that take a delegate or a delegate; the delegate wraps the method that is invoked by the new thread when you call the method. Calling more than once causes a to be thrown. - The method returns immediately, often before the new thread has actually started. You can use the and properties to determine the state of the thread at any one moment, but these properties should never be used for synchronizing the activities of threads. + The method returns immediately, often before the new thread has actually started. You can use the and properties to determine the state of the thread at any one moment, but these properties should never be used for synchronizing the activities of threads. > [!NOTE] > Once a thread is started, it is not necessary to retain a reference to the object. The thread continues to execute until the thread procedure ends. @@ -49,6 +49,6 @@ Neither nor - - -- +- - [Threading](managed-threading-basics.md) - [Using Threads and Threading](using-threads-and-threading.md) diff --git a/docs/standard/threading/destroying-threads.md b/docs/standard/threading/destroying-threads.md index 44c4ef7a42193..b6fa0e8627c5e 100644 --- a/docs/standard/threading/destroying-threads.md +++ b/docs/standard/threading/destroying-threads.md @@ -3,68 +3,68 @@ title: "Destroying threads" description: Know your options when you need to destroy a thread in .NET, such as cooperative cancellation or the Thread.Abort method. Learn to handle ThreadAbortException. ms.date: 03/13/2026 ai-usage: ai-assisted -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "destroying threads" - "threading [.NET], destroying threads" ms.topic: how-to --- # Destroy threads -To terminate the execution of the thread, you usually use the [cooperative cancellation model](cancellation-in-managed-threads.md). However, sometimes it's not possible to stop a thread cooperatively, because it runs third-party code not designed for cooperative cancellation. In .NET Framework apps, you can use the method to terminate a managed thread forcibly. When you call , the Common Language Runtime throws a in the target thread, which the target thread can catch. (However, the .NET Framework runtime always automatically rethrows the exception after the `catch` block.) For more information, see . +To terminate the execution of the thread, you usually use the [cooperative cancellation model](cancellation-in-managed-threads.md). However, sometimes it's not possible to stop a thread cooperatively, because it runs third-party code not designed for cooperative cancellation. In .NET Framework apps, you can use the method to terminate a managed thread forcibly. When you call , the Common Language Runtime throws a in the target thread, which the target thread can catch. (However, the .NET Framework runtime always automatically rethrows the exception after the `catch` block.) For more information, see . -The method throws a at runtime in .NET Core and .NET 5 and later versions. Starting in .NET 5, it's also marked obsolete ([SYSLIB0006](../../fundamentals/syslib-diagnostics/syslib0006.md)), so calling it generates a compile-time warning. If you need to terminate the execution of third-party code forcibly in modern .NET implementations, run it in the separate process and use . +The method throws a at runtime in .NET Core and .NET 5 and later versions. Starting in .NET 5, it's also marked obsolete ([SYSLIB0006](../../fundamentals/syslib-diagnostics/syslib0006.md)), so calling it generates a compile-time warning. If you need to terminate the execution of third-party code forcibly in modern .NET implementations, run it in the separate process and use . > [!NOTE] > -> - When you call to abort a thread other than the current thread, you don't know what code has executed or failed to execute when the is thrown. You also cannot be certain of the state of your application or any application and user state that it's responsible for preserving. For example, calling may prevent the execution of static constructors or the release of managed or unmanaged resources. -> - If a thread is executing unmanaged code when its method is called, the runtime marks it . The exception is thrown when the thread returns to managed code. - - Once a thread is aborted, it cannot be restarted. - - The method does not cause the thread to abort immediately, because the target thread can catch the and execute arbitrary amounts of code in a `finally` block. You can call if you need to wait until the thread has ended. is a blocking call that does not return until the thread has actually stopped executing or an optional timeout interval has elapsed. The aborted thread could call the method or perform unbounded processing in a `finally` block, so if you do not specify a timeout, the wait is not guaranteed to end. - - Threads that are waiting on a call to the method can be interrupted by other threads that call . - -## Handling ThreadAbortException +> - When you call to abort a thread other than the current thread, you don't know what code has executed or failed to execute when the is thrown. You also cannot be certain of the state of your application or any application and user state that it's responsible for preserving. For example, calling may prevent the execution of static constructors or the release of managed or unmanaged resources. +> - If a thread is executing unmanaged code when its method is called, the runtime marks it . The exception is thrown when the thread returns to managed code. - If you expect your thread to be aborted, either as a result of calling from your own code or as a result of unloading an application domain in which the thread is running ( uses to terminate threads), your thread must handle the and perform any final processing in a `finally` clause, as shown in the following code. - -```vb -Try - ' Code that is executing when the thread is aborted. -Catch ex As ThreadAbortException - ' Clean-up code can go here. - ' If there is no Finally clause, ThreadAbortException is + Once a thread is aborted, it cannot be restarted. + + The method does not cause the thread to abort immediately, because the target thread can catch the and execute arbitrary amounts of code in a `finally` block. You can call if you need to wait until the thread has ended. is a blocking call that does not return until the thread has actually stopped executing or an optional timeout interval has elapsed. The aborted thread could call the method or perform unbounded processing in a `finally` block, so if you do not specify a timeout, the wait is not guaranteed to end. + + Threads that are waiting on a call to the method can be interrupted by other threads that call . + +## Handling ThreadAbortException + + If you expect your thread to be aborted, either as a result of calling from your own code or as a result of unloading an application domain in which the thread is running ( uses to terminate threads), your thread must handle the and perform any final processing in a `finally` clause, as shown in the following code. + +```vb +Try + ' Code that is executing when the thread is aborted. +Catch ex As ThreadAbortException + ' Clean-up code can go here. + ' If there is no Finally clause, ThreadAbortException is ' re-thrown by the system at the end of the Catch clause. -Finally - ' Clean-up code can go here. -End Try +Finally + ' Clean-up code can go here. +End Try ' Do not put clean-up code here, because the exception -' is rethrown at the end of the Finally clause. -``` - -```csharp +' is rethrown at the end of the Finally clause. +``` + +```csharp try -{ - // Code that is executing when the thread is aborted. +{ + // Code that is executing when the thread is aborted. } catch (ThreadAbortException ex) -{ - // Clean-up code can go here. - // If there is no Finally clause, ThreadAbortException is +{ + // Clean-up code can go here. + // If there is no Finally clause, ThreadAbortException is // re-thrown by the system at the end of the Catch clause. -} +} // Do not put clean-up code here, because the exception -// is rethrown at the end of the Finally clause. -``` - - Your clean-up code must be in the `catch` clause or the `finally` clause, because a is rethrown by the system at the end of the `finally` clause, or at the end of the `catch` clause if there is no `finally` clause. - - You can prevent the system from rethrowing the exception by calling the method. However, you should do this only if your own code caused the . - +// is rethrown at the end of the Finally clause. +``` + + Your clean-up code must be in the `catch` clause or the `finally` clause, because a is rethrown by the system at the end of the `finally` clause, or at the end of the `catch` clause if there is no `finally` clause. + + You can prevent the system from rethrowing the exception by calling the method. However, you should do this only if your own code caused the . + ## See also - [Thread.Abort is obsolete](../../core/compatibility/core-libraries/5.0/thread-abort-obsolete.md) diff --git a/docs/standard/threading/eventwaithandle.md b/docs/standard/threading/eventwaithandle.md index 463c5285c7c16..a51fa210f94ef 100644 --- a/docs/standard/threading/eventwaithandle.md +++ b/docs/standard/threading/eventwaithandle.md @@ -2,7 +2,7 @@ description: "Learn more about: EventWaitHandle" title: "EventWaitHandle" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "threading [.NET], EventWaitHandle class" - "EventWaitHandle class" - "event wait handles [.NET]" @@ -11,54 +11,54 @@ ms.assetid: 11ee0b38-d663-4617-b793-35eb6c64e9fc --- # EventWaitHandle -The class allows threads to communicate with each other by signaling and by waiting for signals. Event wait handles (also referred to simply as events) are wait handles that can be signaled in order to release one or more waiting threads. After it is signaled, an event wait handle is reset either manually or automatically. The class can represent either a local event wait handle (local event) or a named system event wait handle (named event or system event, visible to all processes). - +The class allows threads to communicate with each other by signaling and by waiting for signals. Event wait handles (also referred to simply as events) are wait handles that can be signaled in order to release one or more waiting threads. After it is signaled, an event wait handle is reset either manually or automatically. The class can represent either a local event wait handle (local event) or a named system event wait handle (named event or system event, visible to all processes). + > [!NOTE] -> Event wait handles are not .NET [events](../events/index.md). There are no delegates or event handlers involved. The word "event" is used to describe them because they have traditionally been referred to as operating-system events, and because the act of signaling the wait handle indicates to waiting threads that an event has occurred. - - Both local and named event wait handles use system synchronization objects, which are protected by wrappers to ensure that the resources are released. You can use the method to free the resources immediately when you have finished using the object. - -## Event Wait Handles That Reset Automatically - - You create an automatic reset event by specifying when you create the object. As its name implies, this synchronization event resets automatically when signaled, after releasing a single waiting thread. Signal the event by calling its method. - - Automatic reset events are usually used to provide exclusive access to a resource for a single thread at a time. A thread requests the resource by calling the method. If no other thread is holding the wait handle, the method returns `true` and the calling thread has control of the resource. - +> Event wait handles are not .NET [events](../events/index.md). There are no delegates or event handlers involved. The word "event" is used to describe them because they have traditionally been referred to as operating-system events, and because the act of signaling the wait handle indicates to waiting threads that an event has occurred. + + Both local and named event wait handles use system synchronization objects, which are protected by wrappers to ensure that the resources are released. You can use the method to free the resources immediately when you have finished using the object. + +## Event Wait Handles That Reset Automatically + + You create an automatic reset event by specifying when you create the object. As its name implies, this synchronization event resets automatically when signaled, after releasing a single waiting thread. Signal the event by calling its method. + + Automatic reset events are usually used to provide exclusive access to a resource for a single thread at a time. A thread requests the resource by calling the method. If no other thread is holding the wait handle, the method returns `true` and the calling thread has control of the resource. + > [!IMPORTANT] -> As with all synchronization mechanisms, you must ensure that all code paths wait on the appropriate wait handle before accessing a protected resource. Thread synchronization is cooperative. - - If an automatic reset event is signaled when no threads are waiting, it remains signaled until a thread attempts to wait on it. The event releases the thread and immediately resets, blocking subsequent threads. - -## Event Wait Handles That Reset Manually - - You create a manual reset event by specifying when you create the object. As its name implies, this synchronization event must be reset manually after it has been signaled. Until it is reset, by calling its method, threads that wait on the event handle proceed immediately without blocking. - - A manual reset event acts like the gate of a corral. When the event is not signaled, threads that wait on it block, like horses in a corral. When the event is signaled, by calling its method, all waiting threads are free to proceed. The event remains signaled until its method is called. This makes the manual reset event an ideal way to hold up threads that need to wait until one thread finishes a task. - - Like horses leaving a corral, it takes time for the released threads to be scheduled by the operating system and to resume execution. If the method is called before all the threads have resumed execution, the remaining threads once again block. Which threads resume and which threads block depends on random factors like the load on the system, the number of threads waiting for the scheduler, and so on. This is not a problem if the thread that signals the event ends after signaling, which is the most common usage pattern. If you want the thread that signaled the event to begin a new task after all the waiting threads have resumed, you must block it until all the waiting threads have resumed. Otherwise, you have a race condition, and the behavior of your code is unpredictable. - -## Features Common to Automatic and Manual Events - - Typically, one or more threads block on an until an unblocked thread calls the method, which releases one of the waiting threads (in the case of automatic reset events) or all of them (in the case of manual reset events). A thread can signal an and then block on it, as an atomic operation, by calling the static method. - - objects can be used with the static and methods. Because the and classes both derive from , you can use both classes with these methods. - -### Named Events - - The Windows operating system allows event wait handles to have names. A named event is system wide. That is, once the named event is created, it is visible to all threads in all processes. Thus, named events can be used to synchronize the activities of processes as well as threads. - - You can create an object that represents a named system event by using one of the constructors that specifies an event name. - +> As with all synchronization mechanisms, you must ensure that all code paths wait on the appropriate wait handle before accessing a protected resource. Thread synchronization is cooperative. + + If an automatic reset event is signaled when no threads are waiting, it remains signaled until a thread attempts to wait on it. The event releases the thread and immediately resets, blocking subsequent threads. + +## Event Wait Handles That Reset Manually + + You create a manual reset event by specifying when you create the object. As its name implies, this synchronization event must be reset manually after it has been signaled. Until it is reset, by calling its method, threads that wait on the event handle proceed immediately without blocking. + + A manual reset event acts like the gate of a corral. When the event is not signaled, threads that wait on it block, like horses in a corral. When the event is signaled, by calling its method, all waiting threads are free to proceed. The event remains signaled until its method is called. This makes the manual reset event an ideal way to hold up threads that need to wait until one thread finishes a task. + + Like horses leaving a corral, it takes time for the released threads to be scheduled by the operating system and to resume execution. If the method is called before all the threads have resumed execution, the remaining threads once again block. Which threads resume and which threads block depends on random factors like the load on the system, the number of threads waiting for the scheduler, and so on. This is not a problem if the thread that signals the event ends after signaling, which is the most common usage pattern. If you want the thread that signaled the event to begin a new task after all the waiting threads have resumed, you must block it until all the waiting threads have resumed. Otherwise, you have a race condition, and the behavior of your code is unpredictable. + +## Features Common to Automatic and Manual Events + + Typically, one or more threads block on an until an unblocked thread calls the method, which releases one of the waiting threads (in the case of automatic reset events) or all of them (in the case of manual reset events). A thread can signal an and then block on it, as an atomic operation, by calling the static method. + + objects can be used with the static and methods. Because the and classes both derive from , you can use both classes with these methods. + +### Named Events + + The Windows operating system allows event wait handles to have names. A named event is system wide. That is, once the named event is created, it is visible to all threads in all processes. Thus, named events can be used to synchronize the activities of processes as well as threads. + + You can create an object that represents a named system event by using one of the constructors that specifies an event name. + > [!NOTE] -> Because named events are system wide, it is possible to have multiple objects that represent the same named event. Each time you call a constructor, or the method, a new object is created. Specifying the same name repeatedly creates multiple objects that represent the same named event. - - Caution is advised in using named events. Because they are system wide, another process that uses the same name can block your threads unexpectedly. Malicious code executing on the same computer could use this as the basis of a denial-of-service attack. - - Use access control security to protect an object that represents a named event, preferably by using a constructor that specifies an object. You can also apply access control security using the method, but this leaves a window of vulnerability between the time the event wait handle is created and the time it is protected. Protecting events with access control security helps prevent malicious attacks, but it does not solve the problem of unintentional name collisions. - +> Because named events are system wide, it is possible to have multiple objects that represent the same named event. Each time you call a constructor, or the method, a new object is created. Specifying the same name repeatedly creates multiple objects that represent the same named event. + + Caution is advised in using named events. Because they are system wide, another process that uses the same name can block your threads unexpectedly. Malicious code executing on the same computer could use this as the basis of a denial-of-service attack. + + Use access control security to protect an object that represents a named event, preferably by using a constructor that specifies an object. You can also apply access control security using the method, but this leaves a window of vulnerability between the time the event wait handle is created and the time it is protected. Protecting events with access control security helps prevent malicious attacks, but it does not solve the problem of unintentional name collisions. + > [!NOTE] -> Unlike the class, the derived classes and can represent only local wait handles. They cannot represent named system events. - +> Unlike the class, the derived classes and can represent only local wait handles. They cannot represent named system events. + ## See also - diff --git a/docs/standard/threading/exceptions-in-managed-threads.md b/docs/standard/threading/exceptions-in-managed-threads.md index fa564b70f71d6..59039214c00d3 100644 --- a/docs/standard/threading/exceptions-in-managed-threads.md +++ b/docs/standard/threading/exceptions-in-managed-threads.md @@ -3,7 +3,7 @@ title: "Exceptions in Managed Threads" description: See how unhandled exceptions are handled in .NET. Most unhandled thread exceptions proceed naturally and lead to application termination. ms.date: 03/13/2026 ai-usage: ai-assisted -helpviewer_keywords: +helpviewer_keywords: - "unhandled exceptions,in managed threads" - "threading [.NET],unhandled exceptions" - "threading [.NET],exceptions in managed threads" @@ -12,31 +12,31 @@ ms.assetid: 11294769-2e89-43cb-890e-ad4ad79cfbee --- # Exceptions in managed threads -The common language runtime allows most unhandled exceptions in threads to proceed naturally. In most cases, this means that the unhandled exception causes the application to terminate. However, the common language runtime provides a backstop for certain unhandled exceptions that are used for controlling program flow: - -- A is thrown in a thread because was called. This only applies to .NET Framework apps. In .NET 5 and later versions, throws a . For more information, see [SYSLIB0006: Thread.Abort is not supported](../../fundamentals/syslib-diagnostics/syslib0006.md). - -- An is thrown in a thread because the application domain in which the thread is executing is being unloaded. - -- The common language runtime or a host process terminates the thread by throwing an internal exception. - -If any of these exceptions are unhandled in threads created by the common language runtime, the exception terminates the thread, but the common language runtime does not allow the exception to proceed further. - -If these exceptions are unhandled in the main thread, or in threads that entered the runtime from unmanaged code, they proceed normally, resulting in termination of the application. - +The common language runtime allows most unhandled exceptions in threads to proceed naturally. In most cases, this means that the unhandled exception causes the application to terminate. However, the common language runtime provides a backstop for certain unhandled exceptions that are used for controlling program flow: + +- A is thrown in a thread because was called. This only applies to .NET Framework apps. In .NET 5 and later versions, throws a . For more information, see [SYSLIB0006: Thread.Abort is not supported](../../fundamentals/syslib-diagnostics/syslib0006.md). + +- An is thrown in a thread because the application domain in which the thread is executing is being unloaded. + +- The common language runtime or a host process terminates the thread by throwing an internal exception. + +If any of these exceptions are unhandled in threads created by the common language runtime, the exception terminates the thread, but the common language runtime does not allow the exception to proceed further. + +If these exceptions are unhandled in the main thread, or in threads that entered the runtime from unmanaged code, they proceed normally, resulting in termination of the application. + > [!NOTE] -> It's possible for the runtime to throw an unhandled exception before any managed code has had a chance to install an exception handler. Even though managed code had no chance to handle such an exception, the exception is allowed to proceed naturally. - -## Expose threading problems during development +> It's possible for the runtime to throw an unhandled exception before any managed code has had a chance to install an exception handler. Even though managed code had no chance to handle such an exception, the exception is allowed to proceed naturally. + +## Expose threading problems during development + + When threads are allowed to fail silently, without terminating the application, serious programming problems can go undetected. This is a particular problem for services and other applications that run for extended periods. As threads fail, program state gradually becomes corrupted. Application performance may degrade, or the application might become unresponsive. - When threads are allowed to fail silently, without terminating the application, serious programming problems can go undetected. This is a particular problem for services and other applications that run for extended periods. As threads fail, program state gradually becomes corrupted. Application performance may degrade, or the application might become unresponsive. - Allowing unhandled exceptions in threads to proceed naturally, until the operating system terminates the program, exposes such problems during development and testing. Error reports on program terminations support debugging. - + ## Host override -An unmanaged host can use the [ICLRPolicyManager](../../framework/unmanaged-api/hosting/iclrpolicymanager-interface.md) interface in the Hosting API to override the default unhandled exception policy of the common language runtime. The [ICLRPolicyManager::SetUnhandledExceptionPolicy](../../framework/unmanaged-api/hosting/iclrpolicymanager-setunhandledexceptionpolicy-method.md) function is used to set the policy for unhandled exceptions. - +An unmanaged host can use the [ICLRPolicyManager](../../framework/unmanaged-api/hosting/iclrpolicymanager-interface.md) interface in the Hosting API to override the default unhandled exception policy of the common language runtime. The [ICLRPolicyManager::SetUnhandledExceptionPolicy](../../framework/unmanaged-api/hosting/iclrpolicymanager-setunhandledexceptionpolicy-method.md) function is used to set the policy for unhandled exceptions. + ## See also - [Managed Threading Basics](managed-threading-basics.md) diff --git a/docs/standard/threading/foreground-and-background-threads.md b/docs/standard/threading/foreground-and-background-threads.md index fdfd09895d2bd..42c86d6b55dc0 100644 --- a/docs/standard/threading/foreground-and-background-threads.md +++ b/docs/standard/threading/foreground-and-background-threads.md @@ -2,7 +2,7 @@ title: "Foreground and Background Threads" description: Determine or change whether a thread is a background thread or a foreground thread using the Thread.IsBackground property in .NET. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "threading [.NET], foreground" - "threading [.NET], background" - "foreground threads" @@ -11,20 +11,20 @@ ms.assetid: cfe0d632-dd35-47e0-91ad-f742a444005e --- # Foreground and background threads -A managed thread is either a background thread or a foreground thread. Background threads are identical to foreground threads with one exception: a background thread does not keep the managed execution environment running. Once all foreground threads have been stopped in a managed process (where the .exe file is a managed assembly), the system stops all background threads and shuts down. - +A managed thread is either a background thread or a foreground thread. Background threads are identical to foreground threads with one exception: a background thread does not keep the managed execution environment running. Once all foreground threads have been stopped in a managed process (where the .exe file is a managed assembly), the system stops all background threads and shuts down. + > [!NOTE] -> When the runtime stops a background thread because the process is shutting down, no exception is thrown in the thread. However, when threads are stopped because the method unloads the application domain, a is thrown in both foreground and background threads. - - Use the property to determine whether a thread is a background or a foreground thread, or to change its status. A thread can be changed to a background thread at any time by setting its property to `true`. - +> When the runtime stops a background thread because the process is shutting down, no exception is thrown in the thread. However, when threads are stopped because the method unloads the application domain, a is thrown in both foreground and background threads. + + Use the property to determine whether a thread is a background or a foreground thread, or to change its status. A thread can be changed to a background thread at any time by setting its property to `true`. + > [!IMPORTANT] -> The foreground or background status of a thread does not affect the outcome of an unhandled exception in the thread. An unhandled exception in either foreground or background threads results in termination of the application. See [Exceptions in Managed Threads](exceptions-in-managed-threads.md). - - Threads that belong to the managed thread pool (that is, threads whose property is `true`) are background threads. All threads that enter the managed execution environment from unmanaged code are marked as background threads. All threads generated by creating and starting a new object are by default foreground threads. - - If you use a thread to monitor an activity, such as a socket connection, set its property to `true` so that the thread does not prevent your process from terminating. - +> The foreground or background status of a thread does not affect the outcome of an unhandled exception in the thread. An unhandled exception in either foreground or background threads results in termination of the application. See [Exceptions in Managed Threads](exceptions-in-managed-threads.md). + + Threads that belong to the managed thread pool (that is, threads whose property is `true`) are background threads. All threads that enter the managed execution environment from unmanaged code are marked as background threads. All threads generated by creating and starting a new object are by default foreground threads. + + If you use a thread to monitor an activity, such as a socket connection, set its property to `true` so that the thread does not prevent your process from terminating. + ## See also - diff --git a/docs/standard/threading/how-to-listen-for-cancellation-requests-by-polling.md b/docs/standard/threading/how-to-listen-for-cancellation-requests-by-polling.md index 161a9559d4947..da5ed0b5e9bb9 100644 --- a/docs/standard/threading/how-to-listen-for-cancellation-requests-by-polling.md +++ b/docs/standard/threading/how-to-listen-for-cancellation-requests-by-polling.md @@ -2,28 +2,28 @@ description: "Learn more about: How to: Listen for Cancellation Requests by Polling" title: "How to: Listen for Cancellation Requests by Polling" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "cancellation, how to poll for requests" ms.assetid: c7f2f022-d08e-4e00-b4eb-ae84844cb1bc --- # How to: Listen for Cancellation Requests by Polling -The following example shows one way that user code can poll a cancellation token at regular intervals to see whether cancellation has been requested from the calling thread. This example uses the type, but the same pattern applies to asynchronous operations created directly by the type or the type. - -## Example +The following example shows one way that user code can poll a cancellation token at regular intervals to see whether cancellation has been requested from the calling thread. This example uses the type, but the same pattern applies to asynchronous operations created directly by the type or the type. + +## Example + + Polling requires some kind of loop or recursive code that can periodically read the value of the Boolean property. If you are using the type and you are waiting for the task to complete on the calling thread, you can use the method to check the property and throw the exception. By using this method, you ensure that the correct exception is thrown in response to a request. If you are using a , then calling this method is better than manually throwing an . If you do not have to throw the exception, then you can just check the property and return from the method if the property is `true`. - Polling requires some kind of loop or recursive code that can periodically read the value of the Boolean property. If you are using the type and you are waiting for the task to complete on the calling thread, you can use the method to check the property and throw the exception. By using this method, you ensure that the correct exception is thrown in response to a request. If you are using a , then calling this method is better than manually throwing an . If you do not have to throw the exception, then you can just check the property and return from the method if the property is `true`. - [!code-csharp[Cancellation#11](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/cancellationex11.cs#11)] - [!code-vb[Cancellation#11](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/cancellationex11.vb#11)] - - Calling is extremely fast and does not introduce significant overhead in loops. - - If you are calling , you only have to explicitly check the property if you have other work to do in response to the cancellation besides throwing the exception. In this example, you can see that the code actually accesses the property twice: once in the explicit access and again in the method. But because the act of reading the property involves only one volatile read instruction per access, the double access is not significant from a performance perspective. It is still preferable to call the method rather than manually throw the . - + [!code-vb[Cancellation#11](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/cancellationex11.vb#11)] + + Calling is extremely fast and does not introduce significant overhead in loops. + + If you are calling , you only have to explicitly check the property if you have other work to do in response to the cancellation besides throwing the exception. In this example, you can see that the code actually accesses the property twice: once in the explicit access and again in the method. But because the act of reading the property involves only one volatile read instruction per access, the double access is not significant from a performance perspective. It is still preferable to call the method rather than manually throw the . + ## See also - [Cancellation in Managed Threads](cancellation-in-managed-threads.md) diff --git a/docs/standard/threading/how-to-listen-for-multiple-cancellation-requests.md b/docs/standard/threading/how-to-listen-for-multiple-cancellation-requests.md index 400180bc01a4e..3a4fd57a7c5e6 100644 --- a/docs/standard/threading/how-to-listen-for-multiple-cancellation-requests.md +++ b/docs/standard/threading/how-to-listen-for-multiple-cancellation-requests.md @@ -2,32 +2,32 @@ description: "Learn more about: How to: Listen for Multiple Cancellation Requests" title: "How to: Listen for Multiple Cancellation Requests" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "cancellation tokens, joining" - "LinkedTokenSource, how to" ms.assetid: 6f4f3804-2ed7-41b4-a97a-6e32b93f6e05 --- # How to: Listen for Multiple Cancellation Requests -This example shows how to listen to two cancellation tokens simultaneously so that you can cancel an operation if either token requests it. - +This example shows how to listen to two cancellation tokens simultaneously so that you can cancel an operation if either token requests it. + > [!NOTE] -> When "Just My Code" is enabled, Visual Studio in some cases will break on the line that throws the exception and display an error message that says "exception not handled by user code." This error is benign. You can press F5 to continue from it, and see the exception-handling behavior that is demonstrated in the examples below. To prevent Visual Studio from breaking on the first error, just uncheck the "Just My Code" checkbox under **Tools, Options, Debugging, General**. - -## Example +> When "Just My Code" is enabled, Visual Studio in some cases will break on the line that throws the exception and display an error message that says "exception not handled by user code." This error is benign. You can press F5 to continue from it, and see the exception-handling behavior that is demonstrated in the examples below. To prevent Visual Studio from breaking on the first error, just uncheck the "Just My Code" checkbox under **Tools, Options, Debugging, General**. + +## Example + + In the following example, the method is used to join two tokens into one token. This enables the token to be passed to methods that take just one cancellation token as an argument. The example demonstrates a common scenario in which a method must observe both a token passed in from outside the class, and a token generated inside the class. - In the following example, the method is used to join two tokens into one token. This enables the token to be passed to methods that take just one cancellation token as an argument. The example demonstrates a common scenario in which a method must observe both a token passed in from outside the class, and a token generated inside the class. - [!code-csharp[Cancellation#13](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/cancellationex13.cs#13)] - [!code-vb[Cancellation#13](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/cancellationex13.vb#13)] - - When the linked token throws an , the token that is passed to the exception is the linked token, not either of the predecessor tokens. To determine which of the tokens was canceled, check the status of the predecessor tokens directly. - - In this example, should never be thrown, but it is caught here because in real-world scenarios any other exceptions besides that are thrown from the task delegate are wrapped in an . - + [!code-vb[Cancellation#13](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/cancellationex13.vb#13)] + + When the linked token throws an , the token that is passed to the exception is the linked token, not either of the predecessor tokens. To determine which of the tokens was canceled, check the status of the predecessor tokens directly. + + In this example, should never be thrown, but it is caught here because in real-world scenarios any other exceptions besides that are thrown from the task delegate are wrapped in an . + ## See also - [Cancellation in Managed Threads](cancellation-in-managed-threads.md) diff --git a/docs/standard/threading/how-to-register-callbacks-for-cancellation-requests.md b/docs/standard/threading/how-to-register-callbacks-for-cancellation-requests.md index 597a15f59395c..24f8a28e0db66 100644 --- a/docs/standard/threading/how-to-register-callbacks-for-cancellation-requests.md +++ b/docs/standard/threading/how-to-register-callbacks-for-cancellation-requests.md @@ -2,7 +2,7 @@ description: "Learn more about: Register callbacks for cancellation requests" title: Register callbacks for cancellation requests ms.date: 08/14/2020 -dev_langs: +dev_langs: - "csharp" - "vb" helpviewer_keywords: @@ -12,19 +12,19 @@ ms.assetid: 8838dd75-18ed-4b8b-b322-cd4531faac64 # Register callbacks for cancellation requests -Learn how to register a delegate that will be invoked when an property becomes true. The value changes from false to true when a call to on the object that created the token is made. Use this technique for canceling asynchronous operations that do not natively support the unified cancellation framework, and for unblocking methods that might be waiting for an asynchronous operation to finish. +Learn how to register a delegate that will be invoked when an property becomes true. The value changes from false to true when a call to on the object that created the token is made. Use this technique for canceling asynchronous operations that do not natively support the unified cancellation framework, and for unblocking methods that might be waiting for an asynchronous operation to finish. > [!NOTE] > When "Just My Code" is enabled, Visual Studio in some cases will break on the line that throws the exception and display an error message that says "exception not handled by user code." This error is benign. You can press F5 to continue from it, and see the exception-handling behavior that is demonstrated in the examples below. To prevent Visual Studio from breaking on the first error, just uncheck the "Just My Code" checkbox under **Tools, Options, Debugging, General**. ## Example -In the following example, the method is registered as the method to be invoked when cancellation is requested through the cancellation token. +In the following example, the method is registered as the method to be invoked when cancellation is requested through the cancellation token. :::code language="csharp" source="../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.cancellation.callback/cs/howtoexample1.cs"::: :::code language="vb" source="../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.cancellation.callback/vb/howtoexample1.vb"::: -If cancellation has already been requested when the callback is registered, the callback is still guaranteed to be called. In this particular case, the method will do nothing if no asynchronous operation is in progress, so it is always safe to call the method. +If cancellation has already been requested when the callback is registered, the callback is still guaranteed to be called. In this particular case, the method will do nothing if no asynchronous operation is in progress, so it is always safe to call the method. ## See also diff --git a/docs/standard/threading/how-to-use-spinlock-for-low-level-synchronization.md b/docs/standard/threading/how-to-use-spinlock-for-low-level-synchronization.md index b43ac11259bac..f84fb8cbcf616 100644 --- a/docs/standard/threading/how-to-use-spinlock-for-low-level-synchronization.md +++ b/docs/standard/threading/how-to-use-spinlock-for-low-level-synchronization.md @@ -2,26 +2,26 @@ description: "Learn more about: How to: use SpinLock for low-level synchronization" title: "How to: use SpinLock for low-level synchronization" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "SpinLock, how to use" ms.assetid: a9ed3e4e-4f29-4207-b730-ed0a51ecbc19 --- # How to: use SpinLock for low-level synchronization -The following example demonstrates how to use a . In this example, the critical section performs a minimal amount of work, which makes it a good candidate for a . Increasing the work a small amount increases the performance of the compared to a standard lock. However, there is a point at which a SpinLock becomes more expensive than a standard lock. You can use the concurrency profiling functionality in the profiling tools to see which type of lock provides better performance in your program. For more information, see [Concurrency Visualizer](/visualstudio/profiling/concurrency-visualizer). - +The following example demonstrates how to use a . In this example, the critical section performs a minimal amount of work, which makes it a good candidate for a . Increasing the work a small amount increases the performance of the compared to a standard lock. However, there is a point at which a SpinLock becomes more expensive than a standard lock. You can use the concurrency profiling functionality in the profiling tools to see which type of lock provides better performance in your program. For more information, see [Concurrency Visualizer](/visualstudio/profiling/concurrency-visualizer). + [!code-csharp[CDS_SpinLock#02](../../../samples/snippets/csharp/VS_Snippets_Misc/cds_spinlock/cs/spinlockdemo.cs#02)] - [!code-vb[CDS_SpinLock#02](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_spinlock/vb/spinlock_vb.vb#02)] - - might be useful when a lock on a shared resource is not going to be held for very long. In such cases, on multi-core computers it can be efficient for the blocked thread to spin for a few cycles until the lock is released. By spinning, the thread does not become blocked, which is a CPU-intensive process. will stop spinning under certain conditions to prevent starvation of logical processors or priority inversion on systems with Hyper-Threading. - - This example uses the class, which requires user synchronization for multi-threaded access. Another option is to use the , which does not require any user locks. - - Note the use of `false` in the call to . This provides the best performance. Specify `true` on IA64 architectures to use the memory fence, which flushes the write buffers to ensure that the lock is now available for other threads to enter. - + [!code-vb[CDS_SpinLock#02](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_spinlock/vb/spinlock_vb.vb#02)] + + might be useful when a lock on a shared resource is not going to be held for very long. In such cases, on multi-core computers it can be efficient for the blocked thread to spin for a few cycles until the lock is released. By spinning, the thread does not become blocked, which is a CPU-intensive process. will stop spinning under certain conditions to prevent starvation of logical processors or priority inversion on systems with Hyper-Threading. + + This example uses the class, which requires user synchronization for multi-threaded access. Another option is to use the , which does not require any user locks. + + Note the use of `false` in the call to . This provides the best performance. Specify `true` on IA64 architectures to use the memory fence, which flushes the write buffers to ensure that the lock is now available for other threads to enter. + ## See also - [Threading objects and features](threading-objects-and-features.md) diff --git a/docs/standard/threading/how-to-use-spinwait-to-implement-a-two-phase-wait-operation.md b/docs/standard/threading/how-to-use-spinwait-to-implement-a-two-phase-wait-operation.md index 2e7a30a16d351..3700d8151b651 100644 --- a/docs/standard/threading/how-to-use-spinwait-to-implement-a-two-phase-wait-operation.md +++ b/docs/standard/threading/how-to-use-spinwait-to-implement-a-two-phase-wait-operation.md @@ -2,28 +2,28 @@ description: "Learn more about: How to: Use SpinWait to Implement a Two-Phase Wait Operation" title: "How to: Use SpinWait to Implement a Two-Phase Wait Operation" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "SpinWait, how to synchronize two-phase wait" ms.assetid: b2ac4e4a-051a-4f65-b4b9-f8e103aff195 --- # How to: Use SpinWait to Implement a Two-Phase Wait Operation -The following example shows how to use a object to implement a two-phase wait operation. In the first phase, the synchronization object, a `Latch`, spins for a few cycles while it checks whether the lock has become available. In the second phase, if the lock becomes available, then the `Wait` method returns without using the to perform its wait; otherwise, `Wait` performs the wait. - -## Example +The following example shows how to use a object to implement a two-phase wait operation. In the first phase, the synchronization object, a `Latch`, spins for a few cycles while it checks whether the lock has become available. In the second phase, if the lock becomes available, then the `Wait` method returns without using the to perform its wait; otherwise, `Wait` performs the wait. + +## Example + + This example shows a very basic implementation of a Latch synchronization primitive. You can use this data structure when wait times are expected to be very short. This example is for demonstration purposes only. If you require latch-type functionality in your program, consider using . - This example shows a very basic implementation of a Latch synchronization primitive. You can use this data structure when wait times are expected to be very short. This example is for demonstration purposes only. If you require latch-type functionality in your program, consider using . - [!code-csharp[CDS_SpinWait#03](../../../samples/snippets/csharp/VS_Snippets_Misc/cds_spinwait/cs/spinwait03.cs#03)] - [!code-vb[CDS_SpinWait#03](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_spinwait/vb/spinwait2.vb#03)] - - The latch uses the object to spin in place only until the next call to `SpinOnce` causes the to yield the time slice of the thread. At that point, the latch causes its own context switch by calling on the and passing in the remainder of the time-out value. - - The logging output shows how often the Latch was able to increase performance by acquiring the lock without using the . - + [!code-vb[CDS_SpinWait#03](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_spinwait/vb/spinwait2.vb#03)] + + The latch uses the object to spin in place only until the next call to `SpinOnce` causes the to yield the time slice of the thread. At that point, the latch causes its own context switch by calling on the and passing in the remainder of the time-out value. + + The logging output shows how often the Latch was able to increase performance by acquiring the lock without using the . + ## See also - [SpinWait](spinwait.md) diff --git a/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md b/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md index 9e7622d7a88e8..9721c5d6bd577 100644 --- a/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md +++ b/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md @@ -3,7 +3,7 @@ description: "Learn more about: Managed and unmanaged threading in Windows" title: "Managed and Unmanaged Threading in Windows" ms.date: 03/13/2026 ai-usage: ai-assisted -elpviewer_keywords: +elpviewer_keywords: - "threading [.NET], unmanaged" - "threading [.NET], managed" - "threading [.NET], managed" @@ -13,54 +13,54 @@ ms.assetid: 4fb6452f-c071-420d-9e71-da16dee7a1eb --- # Managed and unmanaged threading in Windows -Management of all threads is done through the class, including threads created by the common language runtime and those created outside the runtime that enter the managed environment to execute code. The runtime monitors all the threads in its process that have ever executed code within the managed execution environment. It does not track any other threads. Threads can enter the managed execution environment through COM interop (because the runtime exposes managed objects as COM objects to the unmanaged world), the COM [DllGetClassObject](/windows/desktop/api/combaseapi/nf-combaseapi-dllgetclassobject) function, and platform invoke. - - When an unmanaged thread enters the runtime through, for example, a COM callable wrapper, the system checks the thread-local store of that thread to look for an internal managed object. If one is found, the runtime is already aware of this thread. If it cannot find one, however, the runtime builds a new object and installs it in the thread-local store of that thread. - - In managed threading, is the stable managed thread identification. For the lifetime of your thread, it will not collide with the value from any other thread, regardless of the application domain from which you obtain this value. - +Management of all threads is done through the class, including threads created by the common language runtime and those created outside the runtime that enter the managed environment to execute code. The runtime monitors all the threads in its process that have ever executed code within the managed execution environment. It does not track any other threads. Threads can enter the managed execution environment through COM interop (because the runtime exposes managed objects as COM objects to the unmanaged world), the COM [DllGetClassObject](/windows/desktop/api/combaseapi/nf-combaseapi-dllgetclassobject) function, and platform invoke. + + When an unmanaged thread enters the runtime through, for example, a COM callable wrapper, the system checks the thread-local store of that thread to look for an internal managed object. If one is found, the runtime is already aware of this thread. If it cannot find one, however, the runtime builds a new object and installs it in the thread-local store of that thread. + + In managed threading, is the stable managed thread identification. For the lifetime of your thread, it will not collide with the value from any other thread, regardless of the application domain from which you obtain this value. + ## Mapping from Win32 threading to managed threading - The following table maps Win32 threading elements to their approximate runtime equivalent. Note that this mapping does not represent identical functionality. For example, `TerminateThread` does not execute `finally` clauses or free up resources, and cannot be prevented. However, executes all your rollback code, reclaims all the resources, and can be denied using . Read the documentation closely before making assumptions about functionality. + The following table maps Win32 threading elements to their approximate runtime equivalent. Note that this mapping does not represent identical functionality. For example, `TerminateThread` does not execute `finally` clauses or free up resources, and cannot be prevented. However, executes all your rollback code, reclaims all the resources, and can be denied using . Read the documentation closely before making assumptions about functionality. > [!NOTE] -> is only available in .NET Framework. In .NET 5 and later versions, it throws a . For more information, see [SYSLIB0006: Thread.Abort is not supported](../../fundamentals/syslib-diagnostics/syslib0006.md). - -|In Win32|In the common language runtime| -|--------------|------------------------------------| -|**CreateThread**|Combination of **Thread** and | -|**TerminateThread**|| -|**SuspendThread**|| -|**ResumeThread**|| -|**Sleep**|| -|**WaitForSingleObject** on the thread handle|| -|**ExitThread**|No equivalent| -|**GetCurrentThread**|| -|**SetThreadPriority**|| -|No equivalent|| -|No equivalent|| -|Close to **CoInitializeEx** (OLE32.DLL)|| - +> is only available in .NET Framework. In .NET 5 and later versions, it throws a . For more information, see [SYSLIB0006: Thread.Abort is not supported](../../fundamentals/syslib-diagnostics/syslib0006.md). + +|In Win32|In the common language runtime| +|--------------|------------------------------------| +|**CreateThread**|Combination of **Thread** and | +|**TerminateThread**|| +|**SuspendThread**|| +|**ResumeThread**|| +|**Sleep**|| +|**WaitForSingleObject** on the thread handle|| +|**ExitThread**|No equivalent| +|**GetCurrentThread**|| +|**SetThreadPriority**|| +|No equivalent|| +|No equivalent|| +|Close to **CoInitializeEx** (OLE32.DLL)|| + ## Managed threads and COM apartments -A managed thread can be marked to indicate that it will host a [single-threaded](/windows/desktop/com/single-threaded-apartments) or [multithreaded](/windows/desktop/com/multithreaded-apartments) apartment. (For more information on the COM threading architecture, see [Processes, Threads, and Apartments](/windows/desktop/com/processes--threads--and-apartments).) The , , and methods of the class return and assign the apartment state of a thread. If the state has not been set, returns . - - The property can be set only when the thread is in the state; it can be set only once for a thread. - - If the apartment state is not set before the thread is started, the thread is initialized as a multithreaded apartment (MTA). The finalizer thread and all threads controlled by are MTA. - +A managed thread can be marked to indicate that it will host a [single-threaded](/windows/desktop/com/single-threaded-apartments) or [multithreaded](/windows/desktop/com/multithreaded-apartments) apartment. (For more information on the COM threading architecture, see [Processes, Threads, and Apartments](/windows/desktop/com/processes--threads--and-apartments).) The , , and methods of the class return and assign the apartment state of a thread. If the state has not been set, returns . + + The property can be set only when the thread is in the state; it can be set only once for a thread. + + If the apartment state is not set before the thread is started, the thread is initialized as a multithreaded apartment (MTA). The finalizer thread and all threads controlled by are MTA. + > [!IMPORTANT] > For application startup code, the only way to control apartment state is to apply the or the to the entry point procedure. - - Managed objects that are exposed to COM behave as if they had aggregated the free-threaded marshaller. In other words, they can be called from any COM apartment in a free-threaded manner. The only managed objects that do not exhibit this free-threaded behavior are those objects that derive from or . - - In the managed world, there is no support for the unless you use contexts and context-bound managed instances. If you are using Enterprise Services, then your object must derive from (which is itself derived from ). - - When managed code calls out to COM objects, it always follows COM rules. In other words, it calls through COM apartment proxies and COM+ 1.0 context wrappers as dictated by OLE32. - -## Blocking issues -If a thread makes an unmanaged call into the operating system that has blocked the thread in unmanaged code, the runtime will not take control of it for or . In the case of , the runtime marks the thread for **Abort** and takes control of it when it re-enters managed code. It is preferable for you to use managed blocking rather than unmanaged blocking. ,, , , , , , and so on are all responsive to and to . Also, if your thread is in a single-threaded apartment, all these managed blocking operations will correctly pump messages in your apartment while your thread is blocked. + Managed objects that are exposed to COM behave as if they had aggregated the free-threaded marshaller. In other words, they can be called from any COM apartment in a free-threaded manner. The only managed objects that do not exhibit this free-threaded behavior are those objects that derive from or . + + In the managed world, there is no support for the unless you use contexts and context-bound managed instances. If you are using Enterprise Services, then your object must derive from (which is itself derived from ). + + When managed code calls out to COM objects, it always follows COM rules. In other words, it calls through COM apartment proxies and COM+ 1.0 context wrappers as dictated by OLE32. + +## Blocking issues + +If a thread makes an unmanaged call into the operating system that has blocked the thread in unmanaged code, the runtime will not take control of it for or . In the case of , the runtime marks the thread for **Abort** and takes control of it when it re-enters managed code. It is preferable for you to use managed blocking rather than unmanaged blocking. ,, , , , , , and so on are all responsive to and to . Also, if your thread is in a single-threaded apartment, all these managed blocking operations will correctly pump messages in your apartment while your thread is blocked. ## Threads and fibers @@ -68,7 +68,7 @@ The .NET threading model does not support [fibers](/windows/desktop/procthread/f ## See also -- +- - - - diff --git a/docs/standard/threading/managed-threading-best-practices.md b/docs/standard/threading/managed-threading-best-practices.md index bcc4f26672626..dd9c3feb14d65 100644 --- a/docs/standard/threading/managed-threading-best-practices.md +++ b/docs/standard/threading/managed-threading-best-practices.md @@ -27,7 +27,7 @@ Multithreading requires careful programming. For most tasks, you can reduce comp A deadlock occurs when each of two threads tries to lock a resource the other has already locked. Neither thread can make any further progress. - Many methods of the managed threading classes provide time-outs to help you detect deadlocks. For example, the following code attempts to acquire a lock on an object named `lockObject`. If the lock is not obtained in 300 milliseconds, returns `false`. + Many methods of the managed threading classes provide time-outs to help you detect deadlocks. For example, the following code attempts to acquire a lock on an object named `lockObject`. If the lock is not obtained in 300 milliseconds, returns `false`. ```vb If Monitor.TryEnter(lockObject, 300) Then @@ -63,7 +63,7 @@ else { In a multithreaded application, a thread that has loaded and incremented the value might be preempted by another thread which performs all three steps; when the first thread resumes execution and stores its value, it overwrites `objCt` without taking into account the fact that the value has changed in the interim. - This particular race condition is easily avoided by using methods of the class, such as . To read about other techniques for synchronizing data among multiple threads, see [Synchronizing Data for Multithreading](synchronizing-data-for-multithreading.md). + This particular race condition is easily avoided by using methods of the class, such as . To read about other techniques for synchronizing data among multiple threads, see [Synchronizing Data for Multithreading](synchronizing-data-for-multithreading.md). Race conditions can also occur when you synchronize the activities of multiple threads. Whenever you write a line of code, you must consider what might happen if a thread were preempted before executing the line (or before any of the individual machine instructions that make up the line), and another thread overtook it. @@ -85,17 +85,17 @@ Use the pr Consider the following guidelines when using multiple threads: -- Don't use to terminate other threads. Calling `Abort` on another thread is akin to throwing an exception on that thread, without knowing what point that thread has reached in its processing. In .NET 5 and later versions, is obsolete and throws a . Instead, use cooperative cancellation via . For more information, see [SYSLIB0006: Thread.Abort is not supported](../../fundamentals/syslib-diagnostics/syslib0006.md). +- Don't use to terminate other threads. Calling `Abort` on another thread is akin to throwing an exception on that thread, without knowing what point that thread has reached in its processing. In .NET 5 and later versions, is obsolete and throws a . Instead, use cooperative cancellation via . For more information, see [SYSLIB0006: Thread.Abort is not supported](../../fundamentals/syslib-diagnostics/syslib0006.md). -- Don't use and to synchronize the activities of multiple threads. Do use , , , and . +- Don't use and to synchronize the activities of multiple threads. Do use , , , and . -- Don't control the execution of worker threads from your main program (using events, for example). Instead, design your program so that worker threads are responsible for waiting until work is available, executing it, and notifying other parts of your program when finished. If your worker threads do not block, consider using thread pool threads. is useful in situations where worker threads block. +- Don't control the execution of worker threads from your main program (using events, for example). Instead, design your program so that worker threads are responsible for waiting until work is available, executing it, and notifying other parts of your program when finished. If your worker threads do not block, consider using thread pool threads. is useful in situations where worker threads block. -- Don't use types as lock objects. That is, avoid code such as `lock(typeof(X))` in C# or `SyncLock(GetType(X))` in Visual Basic, or the use of with objects. For a given type, there is only one instance of per application domain. If the type you take a lock on is public, code other than your own can take locks on it, leading to deadlocks. For additional issues, see [Reliability Best Practices](../../framework/performance/reliability-best-practices.md). +- Don't use types as lock objects. That is, avoid code such as `lock(typeof(X))` in C# or `SyncLock(GetType(X))` in Visual Basic, or the use of with objects. For a given type, there is only one instance of per application domain. If the type you take a lock on is public, code other than your own can take locks on it, leading to deadlocks. For additional issues, see [Reliability Best Practices](../../framework/performance/reliability-best-practices.md). - Use caution when locking on instances, for example `lock(this)` in C# or `SyncLock(Me)` in Visual Basic. If other code in your application, external to the type, takes a lock on the object, deadlocks could occur. -- Do ensure that a thread that has entered a monitor always leaves that monitor, even if an exception occurs while the thread is in the monitor. The C# [lock](../../csharp/language-reference/statements/lock.md) statement and the Visual Basic [SyncLock](../../visual-basic/language-reference/statements/synclock-statement.md) statement provide this behavior automatically, employing a **finally** block to ensure that is called. If you cannot ensure that **Exit** will be called, consider changing your design to use **Mutex**. A mutex is automatically released when the thread that currently owns it terminates. +- Do ensure that a thread that has entered a monitor always leaves that monitor, even if an exception occurs while the thread is in the monitor. The C# [lock](../../csharp/language-reference/statements/lock.md) statement and the Visual Basic [SyncLock](../../visual-basic/language-reference/statements/synclock-statement.md) statement provide this behavior automatically, employing a **finally** block to ensure that is called. If you cannot ensure that **Exit** will be called, consider changing your design to use **Mutex**. A mutex is automatically released when the thread that currently owns it terminates. - Do use multiple threads for tasks that require different resources, and avoid assigning multiple threads to a single resource. For example, any task involving I/O benefits from having its own thread, because that thread will block during I/O operations and thus allow other threads to execute. User input is another resource that benefits from a dedicated thread. On a single-processor computer, a task that involves intensive computation coexists with user input and with tasks that involve I/O, but multiple computation-intensive tasks contend with each other. @@ -114,7 +114,7 @@ Consider the following guidelines when using multiple threads: } ``` - You can improve performance by using the method instead of the `lock` statement, as follows: + You can improve performance by using the method instead of the `lock` statement, as follows: ```vb System.Threading.Interlocked.Increment(myField) @@ -125,7 +125,7 @@ Consider the following guidelines when using multiple threads: ``` > [!NOTE] - > Use the method for atomic increments larger than 1. + > Use the method for atomic increments larger than 1. In the second example, a reference type variable is updated only if it is a null reference (`Nothing` in Visual Basic). @@ -149,7 +149,7 @@ Consider the following guidelines when using multiple threads: } ``` - Performance can be improved by using the method instead, as follows: + Performance can be improved by using the method instead, as follows: ```vb System.Threading.Interlocked.CompareExchange(x, y, Nothing) @@ -160,7 +160,7 @@ Consider the following guidelines when using multiple threads: ``` > [!NOTE] - > The method overload provides a type-safe alternative for reference types. + > The method overload provides a type-safe alternative for reference types. ## Recommendations for class libraries diff --git a/docs/standard/threading/mutexes.md b/docs/standard/threading/mutexes.md index d0975c8483ffb..eb7e7d2e17a28 100644 --- a/docs/standard/threading/mutexes.md +++ b/docs/standard/threading/mutexes.md @@ -2,7 +2,7 @@ description: "Learn how to use a Mutex from the System.Threading namespace." title: "Mutexes" ms.date: 07/19/2021 -helpviewer_keywords: +helpviewer_keywords: - "wait handles" - "threading [.NET], Mutex class" - "Mutex class, about Mutex class" @@ -14,27 +14,27 @@ ms.assetid: 9dd06e25-12c0-4a9e-855a-452dc83803e2 You can use a object to provide exclusive access to a resource. The class uses more system resources than the class, but it can be marshalled across application domain boundaries, it can be used with multiple waits, and it can be used to synchronize threads in different processes. For a comparison of managed synchronization mechanisms, see [Overview of Synchronization Primitives](overview-of-synchronization-primitives.md). -For code examples, see the reference documentation for the constructors. +For code examples, see the reference documentation for the constructors. ## Use mutexes -A thread calls the method of a mutex to request ownership. The call blocks until the mutex is available, or until the optional timeout interval elapses. The state of a mutex is signaled if no thread owns it. +A thread calls the method of a mutex to request ownership. The call blocks until the mutex is available, or until the optional timeout interval elapses. The state of a mutex is signaled if no thread owns it. -A thread releases a mutex by calling its method. Mutexes have thread affinity; that is, the mutex can be released only by the thread that owns it. If a thread releases a mutex it does not own, an is thrown in the thread. +A thread releases a mutex by calling its method. Mutexes have thread affinity; that is, the mutex can be released only by the thread that owns it. If a thread releases a mutex it does not own, an is thrown in the thread. -Because the class derives from , you can also call the static or methods of to request ownership of a in combination with other wait handles. - -If a thread owns a , that thread can specify the same in repeated wait-request calls without blocking its execution; however, it must release the as many times to release ownership. +Because the class derives from , you can also call the static or methods of to request ownership of a in combination with other wait handles. + +If a thread owns a , that thread can specify the same in repeated wait-request calls without blocking its execution; however, it must release the as many times to release ownership. ## Abandoned mutexes If a thread terminates without releasing a , the mutex is said to be abandoned. This often indicates a serious programming error because the resource the mutex is protecting might be left in an inconsistent state. An is thrown in the next thread that acquires the mutex. - + In the case of a system-wide mutex, an abandoned mutex might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). - + ## Local and system mutexes -Mutexes are of two types: local mutexes and named system mutexes. If you create a object using a constructor that accepts a name, it is associated with an operating-system object of that name. Named system mutexes are visible throughout the operating system and can be used to synchronize the activities of processes. You can create multiple objects that represent the same named system mutex, and you can use the method to open an existing named system mutex. +Mutexes are of two types: local mutexes and named system mutexes. If you create a object using a constructor that accepts a name, it is associated with an operating-system object of that name. Named system mutexes are visible throughout the operating system and can be used to synchronize the activities of processes. You can create multiple objects that represent the same named system mutex, and you can use the method to open an existing named system mutex. A local mutex exists only within your process. It can be used by any thread in your process that has a reference to the local object. Each object is a separate local mutex. @@ -42,7 +42,7 @@ A local mutex exists only within your process. It can be used by any thread in y .NET Framework provides the ability to query and set Windows access control security for named system objects. Protecting system mutexes from the moment of creation is recommended because system objects are global and therefore can be locked by code other than your own. -For information on access control security for mutexes, see the and classes, the enumeration, the , , and methods of the class, and the constructor. +For information on access control security for mutexes, see the and classes, the enumeration, the , , and methods of the class, and the constructor. > [!NOTE] > Access control security for system mutexes is only available with .NET Framework, it's not available with .NET Core or .NET 5+. @@ -50,7 +50,7 @@ For information on access control security for mutexes, see the -- +- - - - diff --git a/docs/standard/threading/overview-of-synchronization-primitives.md b/docs/standard/threading/overview-of-synchronization-primitives.md index ab14c5f4dae82..e794a77dc412d 100644 --- a/docs/standard/threading/overview-of-synchronization-primitives.md +++ b/docs/standard/threading/overview-of-synchronization-primitives.md @@ -2,7 +2,7 @@ title: "Overview of synchronization primitives" description: "Learn about .NET thread synchronization primitives used to synchronize access to a shared resource or control thread interaction" ms.date: "10/01/2018" -helpviewer_keywords: +helpviewer_keywords: - "synchronization, threads" - "threading [.NET],synchronizing threads" - "managed threading" @@ -23,7 +23,7 @@ Multiple .NET synchronization primitives derive from the , which limits the number of threads that can access a shared resource or a pool of resources concurrently. The state of a semaphore is set to signaled when its count is greater than zero, and nonsignaled when its count is zero. - , which represents a thread synchronization event and can be either in a signaled or unsignaled state. - , which derives from and, when signaled, resets automatically to an unsignaled state after releasing a single waiting thread. -- , which derives from and, when signaled, stays in a signaled state until the method is called. +- , which derives from and, when signaled, stays in a signaled state until the method is called. In .NET Framework, because derives from , these types can be used to synchronize the activities of threads across application domain boundaries. @@ -45,21 +45,21 @@ Some of those types are alternatives to the types derived from class grants mutually exclusive access to a shared resource by acquiring or releasing a lock on the object that identifies the resource. While a lock is held, the thread that holds the lock can again acquire and release the lock. Any other thread is blocked from acquiring the lock and the method waits until the lock is released. The method acquires a released lock. You can also use the method to specify the amount of time during which a thread attempts to acquire a lock. Because the class has thread affinity, the thread that acquired a lock must release the lock by calling the method. +The class grants mutually exclusive access to a shared resource by acquiring or releasing a lock on the object that identifies the resource. While a lock is held, the thread that holds the lock can again acquire and release the lock. Any other thread is blocked from acquiring the lock and the method waits until the lock is released. The method acquires a released lock. You can also use the method to specify the amount of time during which a thread attempts to acquire a lock. Because the class has thread affinity, the thread that acquired a lock must release the lock by calling the method. -You can coordinate the interaction of threads that acquire a lock on the same object by using the , , and methods. +You can coordinate the interaction of threads that acquire a lock on the same object by using the , , and methods. For more information, see the API reference. > [!NOTE] -> Use the [lock](../../csharp/language-reference/statements/lock.md) statement in C# and the [SyncLock](../../visual-basic/language-reference/statements/synclock-statement.md) statement in Visual Basic to synchronize access to a shared resource instead of using the class directly. Those statements are implemented by using the and methods and a `try…finally` block to ensure that the acquired lock is always released. +> Use the [lock](../../csharp/language-reference/statements/lock.md) statement in C# and the [SyncLock](../../visual-basic/language-reference/statements/synclock-statement.md) statement in Visual Basic to synchronize access to a shared resource instead of using the class directly. Those statements are implemented by using the and methods and a `try…finally` block to ensure that the acquired lock is always released. ### Mutex class -The class, like , grants exclusive access to a shared resource. Use one of the [Mutex.WaitOne]() method overloads to request the ownership of a mutex. Like , has thread affinity and the thread that acquired a mutex must release it by calling the method. +The class, like , grants exclusive access to a shared resource. Use one of the [Mutex.WaitOne]() method overloads to request the ownership of a mutex. Like , has thread affinity and the thread that acquired a mutex must release it by calling the method. + +Unlike , the class can be used for inter-process synchronization. To do that, use a named mutex, which is visible throughout the operating system. To create a named mutex instance, use a [Mutex constructor]() that specifies a name. You can also call the method to open an existing named system mutex. -Unlike , the class can be used for inter-process synchronization. To do that, use a named mutex, which is visible throughout the operating system. To create a named mutex instance, use a [Mutex constructor]() that specifies a name. You can also call the method to open an existing named system mutex. - For more information, see the [Mutexes](mutexes.md) article and the API reference. ### SpinLock structure @@ -70,8 +70,8 @@ For more information about the benefits and drawbacks of using spin lock, see th ### ReaderWriterLockSlim class -The class grants exclusive access to a shared resource for writing and allows multiple threads to access the resource simultaneously for reading. You might want to use to synchronize access to a shared data structure that supports thread-safe read operations, but requires exclusive access to perform write operation. When a thread requests exclusive access (for example, by calling the method), subsequent reader and writer requests block until all existing readers have exited the lock, and the writer has entered and exited the lock. - +The class grants exclusive access to a shared resource for writing and allows multiple threads to access the resource simultaneously for reading. You might want to use to synchronize access to a shared data structure that supports thread-safe read operations, but requires exclusive access to perform write operation. When a thread requests exclusive access (for example, by calling the method), subsequent reader and writer requests block until all existing readers have exited the lock, and the writer has entered and exited the lock. + For more information, see the API reference. ### Semaphore and SemaphoreSlim classes @@ -80,13 +80,13 @@ The and is a lightweight alternative to and can be used only for synchronization within a single process boundary. -On Windows, you can use for the inter-process synchronization. To do that, create a instance that represents a named system semaphore by using one of the [Semaphore constructors]() that specifies a name or the method. doesn't support named system semaphores. +On Windows, you can use for the inter-process synchronization. To do that, create a instance that represents a named system semaphore by using one of the [Semaphore constructors]() that specifies a name or the method. doesn't support named system semaphores. For more information, see the [Semaphore and SemaphoreSlim](semaphore-and-semaphoreslim.md) article and the or API reference. ## Thread interaction, or signaling -Thread interaction (or thread signaling) means that a thread must wait for notification, or a signal, from one or more threads in order to proceed. For example, if thread A calls the method of thread B, thread A is blocked until thread B completes. The synchronization primitives described in the preceding section provide a different mechanism for signaling: by releasing a lock, a thread notifies another thread that it can proceed by acquiring the lock. +Thread interaction (or thread signaling) means that a thread must wait for notification, or a signal, from one or more threads in order to proceed. For example, if thread A calls the method of thread B, thread A is blocked until thread B completes. The synchronization primitives described in the preceding section provide a different mechanism for signaling: by releasing a lock, a thread notifies another thread that it can proceed by acquiring the lock. This section describes additional signaling constructs provided by .NET. @@ -94,20 +94,20 @@ This section describes additional signaling constructs provided by .NET. The class represents a thread synchronization event. -A synchronization event can be either in an unsignaled or signaled state. When the state of an event is unsignaled, a thread that calls the event's overload is blocked until an event is signaled. The method sets the state of an event to signaled. +A synchronization event can be either in an unsignaled or signaled state. When the state of an event is unsignaled, a thread that calls the event's overload is blocked until an event is signaled. The method sets the state of an event to signaled. The behavior of an that has been signaled depends on its reset mode: - An created with the flag resets automatically after releasing a single waiting thread. It's like a turnstile that allows only one thread through each time it's signaled. The class, which derives from , represents that behavior. -- An created with the flag remains signaled until its method is called. It's like a gate that is closed until signaled and then stays open until someone closes it. The class, which derives from , represents that behavior. The class is a lightweight alternative to . +- An created with the flag remains signaled until its method is called. It's like a gate that is closed until signaled and then stays open until someone closes it. The class, which derives from , represents that behavior. The class is a lightweight alternative to . -On Windows, you can use for the inter-process synchronization. To do that, create an instance that represents a named system synchronization event by using one of the [EventWaitHandle constructors]() that specifies a name or the method. +On Windows, you can use for the inter-process synchronization. To do that, create an instance that represents a named system synchronization event by using one of the [EventWaitHandle constructors]() that specifies a name or the method. For more information, see the [EventWaitHandle](eventwaithandle.md) article. For the API reference, see , , , and . ### CountdownEvent class -The class represents an event that becomes set when its count is zero. While is greater than zero, a thread that calls is blocked. Call to decrement an event's count. +The class represents an event that becomes set when its count is zero. While is greater than zero, a thread that calls is blocked. Call to decrement an event's count. In contrast to or , which you can use to unblock multiple threads with a signal from one thread, you can use to unblock one or more threads with signals from multiple threads. @@ -115,7 +115,7 @@ For more information, see the [CountdownEvent](countdownevent.md) article and th ### Barrier class -The class represents a thread execution barrier. A thread that calls the method signals that it reached the barrier and waits until other participant threads reach the barrier. When all participant threads reach the barrier, they proceed and the barrier is reset and can be used again. +The class represents a thread execution barrier. A thread that calls the method signals that it reached the barrier and waits until other participant threads reach the barrier. When all participant threads reach the barrier, they proceed and the barrier is reset and can be used again. You might use when one or more threads require the results of other threads before proceeding to the next computation phase. diff --git a/docs/standard/threading/pausing-and-resuming-threads.md b/docs/standard/threading/pausing-and-resuming-threads.md index 827e0077a1cd1..dd70a770bebe4 100644 --- a/docs/standard/threading/pausing-and-resuming-threads.md +++ b/docs/standard/threading/pausing-and-resuming-threads.md @@ -2,10 +2,10 @@ title: "Pausing and interrupting threads" description: Learn how to pause & interrupt threads in .NET. Learn how to use methods like Thread.Sleep & Thread.Interrupt, & exceptions such as ThreadInterruptedException. ms.date: 03/13/2026 -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "interrupting threads" - "threading [.NET], pausing" - "pausing threads" @@ -14,36 +14,36 @@ ai-usage: ai-assisted --- # Pausing and interrupting threads -The most common ways to synchronize the activities of threads are to block and release threads, or to lock objects or regions of code. For more information on these locking and blocking mechanisms, see [Overview of Synchronization Primitives](overview-of-synchronization-primitives.md). - - You can also have threads put themselves to sleep. When threads are blocked or sleeping, you can use a to break them out of their wait states. - +The most common ways to synchronize the activities of threads are to block and release threads, or to lock objects or regions of code. For more information on these locking and blocking mechanisms, see [Overview of Synchronization Primitives](overview-of-synchronization-primitives.md). + + You can also have threads put themselves to sleep. When threads are blocked or sleeping, you can use a to break them out of their wait states. + ## The Thread.Sleep method - Calling the method causes the current thread to immediately block for the number of milliseconds or the time interval you pass to the method, and yields the remainder of its time slice to another thread. Once that interval elapses, the sleeping thread resumes execution. - - One thread cannot call on another thread. is a static method that always causes the current thread to sleep. - - Calling with a value of causes a thread to sleep until another thread calls the method on the sleeping thread. The following example illustrates interrupting a sleeping thread. + Calling the method causes the current thread to immediately block for the number of milliseconds or the time interval you pass to the method, and yields the remainder of its time slice to another thread. Once that interval elapses, the sleeping thread resumes execution. + + One thread cannot call on another thread. is a static method that always causes the current thread to sleep. + + Calling with a value of causes a thread to sleep until another thread calls the method on the sleeping thread. The following example illustrates interrupting a sleeping thread. :::code language="csharp" source="./snippets/pausing-and-resuming-threads/csharp/InterruptThread/Program.cs" id="Snippet1"::: :::code language="vb" source="./snippets/pausing-and-resuming-threads/vb/InterruptThread/Program.vb" id="Snippet1"::: -The example calls to block the calling thread until the interrupted thread finishes execution. +The example calls to block the calling thread until the interrupted thread finishes execution. ## Interrupting threads - You can interrupt a waiting thread by calling the method on the blocked thread to throw a , which breaks the thread out of the blocking call. The thread should catch the and do whatever is appropriate to continue working. If the thread ignores the exception, the runtime catches the exception and stops the thread. - + You can interrupt a waiting thread by calling the method on the blocked thread to throw a , which breaks the thread out of the blocking call. The thread should catch the and do whatever is appropriate to continue working. If the thread ignores the exception, the runtime catches the exception and stops the thread. + > [!NOTE] -> If the target thread is not blocked when is called, the thread is not interrupted until it blocks. If the thread never blocks, it could complete without ever being interrupted. - - If a wait is a managed wait, then wakes the thread immediately. If a wait is an unmanaged wait (for example, a platform invoke call to the Win32 [WaitForSingleObject](/windows/desktop/api/synchapi/nf-synchapi-waitforsingleobject) function), can't take control of the thread until it returns to or calls into managed code. In managed code, the behavior is as follows: +> If the target thread is not blocked when is called, the thread is not interrupted until it blocks. If the thread never blocks, it could complete without ever being interrupted. + + If a wait is a managed wait, then wakes the thread immediately. If a wait is an unmanaged wait (for example, a platform invoke call to the Win32 [WaitForSingleObject](/windows/desktop/api/synchapi/nf-synchapi-waitforsingleobject) function), can't take control of the thread until it returns to or calls into managed code. In managed code, the behavior is as follows: + +- wakes a thread out of any wait it might be in and causes a to be thrown in the destination thread. -- wakes a thread out of any wait it might be in and causes a to be thrown in the destination thread. +- .NET Framework only: wakes a thread out of any wait it might be in and causes a to be thrown on the thread. For details, see [Destroy threads](destroying-threads.md) and [SYSLIB0006: Thread.Abort is not supported](../../fundamentals/syslib-diagnostics/syslib0006.md). -- .NET Framework only: wakes a thread out of any wait it might be in and causes a to be thrown on the thread. For details, see [Destroy threads](destroying-threads.md) and [SYSLIB0006: Thread.Abort is not supported](../../fundamentals/syslib-diagnostics/syslib0006.md). - ## See also - diff --git a/docs/standard/threading/semaphore-and-semaphoreslim.md b/docs/standard/threading/semaphore-and-semaphoreslim.md index 823038c815edd..d914c4d11f10e 100644 --- a/docs/standard/threading/semaphore-and-semaphoreslim.md +++ b/docs/standard/threading/semaphore-and-semaphoreslim.md @@ -2,7 +2,7 @@ title: "Semaphore and SemaphoreSlim" description: Learn about Semaphore & SemaphoreSlim. Class Semaphore is a thin wrapper around the Win32 semaphore object. Class SemaphoreSlim is a fast lightweight semaphore. ms.date: "03/12/2026" -helpviewer_keywords: +helpviewer_keywords: - "counting semaphores" - "semaphores" - "threading [.NET], cross-process synchronization" @@ -20,13 +20,13 @@ The class represents a lightweight, fast s ## Managing a limited resource -Threads enter the semaphore by calling different methods depending on the semaphore type. For a object, call the method (inherited from ). For a object, call the or method. When the call returns, the count on the semaphore is decremented. When a thread requests entry and the count is zero, the thread blocks. As threads release the semaphore by calling the or method, blocked threads can enter. No guaranteed order—such as first-in, first-out (FIFO) or last-in, first-out (LIFO)—governs which blocked thread enters the semaphore next. +Threads enter the semaphore by calling different methods depending on the semaphore type. For a object, call the method (inherited from ). For a object, call the or method. When the call returns, the count on the semaphore is decremented. When a thread requests entry and the count is zero, the thread blocks. As threads release the semaphore by calling the or method, blocked threads can enter. No guaranteed order—such as first-in, first-out (FIFO) or last-in, first-out (LIFO)—governs which blocked thread enters the semaphore next. -A thread can enter the semaphore multiple times by calling the object's method or the object's method repeatedly. To release the semaphore, call the or method the same number of times the thread entered. Alternatively, call the or overload and specify the number of entries to release. +A thread can enter the semaphore multiple times by calling the object's method or the object's method repeatedly. To release the semaphore, call the or method the same number of times the thread entered. Alternatively, call the or overload and specify the number of entries to release. ### Semaphores and thread identity -The two semaphore types don't enforce thread identity on calls to the , , , and methods. For example, a common usage scenario for semaphores involves a producer thread and a consumer thread, with one thread always incrementing the semaphore count and the other always decrementing it. +The two semaphore types don't enforce thread identity on calls to the , , , and methods. For example, a common usage scenario for semaphores involves a producer thread and a consumer thread, with one thread always incrementing the semaphore count and the other always decrementing it. Ensure that a thread doesn't release the semaphore too many times. For example, suppose a semaphore has a maximum count of two, and that thread A and thread B both enter the semaphore. If a programming error in thread B causes it to call `Release` twice, both calls succeed. The count on the semaphore is full, and when thread A eventually calls `Release`, a is thrown. @@ -37,11 +37,11 @@ The Windows operating system allows semaphores to have names. A named semaphore Create a object that represents a named system semaphore by using one of the constructors that specifies a name. > [!IMPORTANT] -> Because named semaphores are system wide, it's possible to have multiple objects that represent the same named semaphore. Each time you call a constructor or the method, a new object is created. Specifying the same name repeatedly creates multiple objects that represent the same named semaphore. +> Because named semaphores are system wide, it's possible to have multiple objects that represent the same named semaphore. Each time you call a constructor or the method, a new object is created. Specifying the same name repeatedly creates multiple objects that represent the same named semaphore. > > Be careful when you use named semaphores. Because they're system wide, another process that uses the same name can enter your semaphore unexpectedly. Malicious code executing on the same computer could use this as the basis of a denial-of-service attack. > -> Use access control security to protect a object that represents a named semaphore, preferably by using a constructor that specifies a object. You can also apply access control security using the method, but this leaves a window of vulnerability between the time the semaphore is created and the time it's protected. Protecting semaphores with access control security helps prevent malicious attacks, but doesn't solve the problem of unintentional name collisions. +> Use access control security to protect a object that represents a named semaphore, preferably by using a constructor that specifies a object. You can also apply access control security using the method, but this leaves a window of vulnerability between the time the semaphore is created and the time it's protected. Protecting semaphores with access control security helps prevent malicious attacks, but doesn't solve the problem of unintentional name collisions. ## See also diff --git a/docs/standard/threading/spinwait.md b/docs/standard/threading/spinwait.md index 37ef23dcb95fd..94b2f0cf8c717 100644 --- a/docs/standard/threading/spinwait.md +++ b/docs/standard/threading/spinwait.md @@ -2,27 +2,27 @@ description: "Learn more about: SpinWait" title: "SpinWait" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "synchronization primitives, SpinWait" ms.assetid: 36012f42-34e5-4f86-adf4-973f433ed6c6 --- # SpinWait - is a lightweight synchronization type that you can use in low-level scenarios to avoid the expensive context switches and kernel transitions that are required for kernel events. On multicore computers, when a resource is not expected to be held for long periods of time, it can be more efficient for a waiting thread to spin in user mode for a few dozen or a few hundred cycles, and then retry to acquire the resource. If the resource is available after spinning, then you have saved several thousand cycles. If the resource is still not available, then you have spent only a few cycles and can still enter a kernel-based wait. This spinning-then-waiting combination is sometimes referred to as a *two-phase wait operation*. - - is designed to be used in conjunction with the .NET types that wrap kernel events such as . can also be used by itself for basic spinning functionality in just one program. - - is more than just an empty loop. It is carefully implemented to provide correct spinning behavior for the general case, and will itself initiate context switches if it spins long enough (roughly the length of time required for a kernel transition). For example, on single-core computers, yields the time slice of the thread immediately because spinning blocks forward progress on all threads. also yields even on multi-core machines to prevent the waiting thread from blocking higher-priority threads or the garbage collector. Therefore, if you are using a in a two-phase wait operation, we recommend that you invoke the kernel wait before the itself initiates a context switch. provides the property, which you can check before every call to . When the property returns `true`, initiate your own Wait operation. For an example, see [How to: Use SpinWait to Implement a Two-Phase Wait Operation](how-to-use-spinwait-to-implement-a-two-phase-wait-operation.md). - - If you are not performing a two-phase wait operation but are just spinning until some condition is true, you can enable to perform its context switches so that it is a good citizen in the Windows operating system environment. The following basic example shows a in a lock-free stack. If you require a high-performance, thread-safe stack, consider using . - + is a lightweight synchronization type that you can use in low-level scenarios to avoid the expensive context switches and kernel transitions that are required for kernel events. On multicore computers, when a resource is not expected to be held for long periods of time, it can be more efficient for a waiting thread to spin in user mode for a few dozen or a few hundred cycles, and then retry to acquire the resource. If the resource is available after spinning, then you have saved several thousand cycles. If the resource is still not available, then you have spent only a few cycles and can still enter a kernel-based wait. This spinning-then-waiting combination is sometimes referred to as a *two-phase wait operation*. + + is designed to be used in conjunction with the .NET types that wrap kernel events such as . can also be used by itself for basic spinning functionality in just one program. + + is more than just an empty loop. It is carefully implemented to provide correct spinning behavior for the general case, and will itself initiate context switches if it spins long enough (roughly the length of time required for a kernel transition). For example, on single-core computers, yields the time slice of the thread immediately because spinning blocks forward progress on all threads. also yields even on multi-core machines to prevent the waiting thread from blocking higher-priority threads or the garbage collector. Therefore, if you are using a in a two-phase wait operation, we recommend that you invoke the kernel wait before the itself initiates a context switch. provides the property, which you can check before every call to . When the property returns `true`, initiate your own Wait operation. For an example, see [How to: Use SpinWait to Implement a Two-Phase Wait Operation](how-to-use-spinwait-to-implement-a-two-phase-wait-operation.md). + + If you are not performing a two-phase wait operation but are just spinning until some condition is true, you can enable to perform its context switches so that it is a good citizen in the Windows operating system environment. The following basic example shows a in a lock-free stack. If you require a high-performance, thread-safe stack, consider using . + [!code-csharp[CDS_SpinWait#05](../../../samples/snippets/csharp/VS_Snippets_Misc/cds_spinwait/cs/spinwait.cs#05)] - [!code-vb[CDS_SpinWait#05](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_spinwait/vb/cds_spinwait1.vb#05)] - + [!code-vb[CDS_SpinWait#05](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_spinwait/vb/cds_spinwait1.vb#05)] + ## See also -- +- - [Threading Objects and Features](threading-objects-and-features.md) diff --git a/docs/standard/threading/synchronizing-data-for-multithreading.md b/docs/standard/threading/synchronizing-data-for-multithreading.md index 31139418266c3..50ffff985257c 100644 --- a/docs/standard/threading/synchronizing-data-for-multithreading.md +++ b/docs/standard/threading/synchronizing-data-for-multithreading.md @@ -46,18 +46,18 @@ When multiple threads can make calls to the properties and methods of a single o Both Visual Basic and C# support the marking of blocks of code with a particular language keyword, the `lock` statement in C# or the `SyncLock` statement in Visual Basic. When the code is executed by a thread, an attempt is made to acquire the lock. If the lock has already been acquired by another thread, the thread blocks until the lock becomes available. When the thread exits the synchronized block of code, the lock is released, no matter how the thread exits the block. > [!NOTE] -> Beginning in C# 13, the `lock` statement recognizes if the locked object is an instance of and uses the `EnterScope` method to create a synchronized region. The `lock`, when the target isn't a `Lock` instance, and `SyncLock` statements are implemented using and , so other methods of can be used in conjunction with them within the synchronized region. +> Beginning in C# 13, the `lock` statement recognizes if the locked object is an instance of and uses the `EnterScope` method to create a synchronized region. The `lock`, when the target isn't a `Lock` instance, and `SyncLock` statements are implemented using and , so other methods of can be used in conjunction with them within the synchronized region. You can also decorate a method with a with a value of , which has the same effect as using or one of the compiler keywords to lock the entire body of the method. - can be used to break a thread out of blocking operations such as waiting for access to a synchronized region of code. **Thread.Interrupt** is also used to break threads out of operations like . + can be used to break a thread out of blocking operations such as waiting for access to a synchronized region of code. **Thread.Interrupt** is also used to break threads out of operations like . > [!IMPORTANT] > Do not lock the type — that is, `typeof(MyType)` in C#, `GetType(MyType)` in Visual Basic, or `MyType::typeid` in C++ — in order to protect `static` methods (`Shared` methods in Visual Basic). Use a private static object instead. Similarly, do not use `this` in C# (`Me` in Visual Basic) to lock instance methods. Use a private object instead. A class or instance can be locked by code other than your own, potentially causing deadlocks or performance problems. ### Compiler support - Both Visual Basic and C# support a language keyword that uses and to lock the object. Visual Basic supports the [SyncLock](../../visual-basic/language-reference/statements/synclock-statement.md) statement; C# supports the [lock](../../csharp/language-reference/statements/lock.md) statement. + Both Visual Basic and C# support a language keyword that uses and to lock the object. Visual Basic supports the [SyncLock](../../visual-basic/language-reference/statements/synclock-statement.md) statement; C# supports the [lock](../../csharp/language-reference/statements/lock.md) statement. In both cases, if an exception is thrown in the code block, the lock acquired by the **lock** or **SyncLock** is released automatically. The C# and Visual Basic compilers emit a **try**/**finally** block with **Monitor.Enter** at the beginning of the try, and **Monitor.Exit** in the **finally** block. If an exception is thrown inside the **lock** or **SyncLock** block, the **finally** handler runs to allow you to do any clean-up work. diff --git a/docs/standard/threading/the-managed-thread-pool.md b/docs/standard/threading/the-managed-thread-pool.md index 15353b99c9227..0c8a5b10f93e0 100644 --- a/docs/standard/threading/the-managed-thread-pool.md +++ b/docs/standard/threading/the-managed-thread-pool.md @@ -3,7 +3,7 @@ title: "The managed thread pool" description: Learn about the .NET thread pool that provides background worker threads ms.date: 03/13/2026 ai-usage: ai-assisted -helpviewer_keywords: +helpviewer_keywords: - "thread pooling [.NET]" - "thread pools [.NET]" - "threading [.NET], thread pool" @@ -12,76 +12,76 @@ ms.assetid: 2be05b06-a42e-4c9d-a739-96c21d673927 --- # The managed thread pool -The class provides your application with a pool of worker threads that are managed by the system, allowing you to concentrate on application tasks rather than thread management. If you have short tasks that require background processing, the managed thread pool is an easy way to take advantage of multiple threads. Use of the thread pool is significantly easier in Framework 4 and later, since you can create and objects that perform asynchronous tasks on thread pool threads. - -.NET uses thread pool threads for many purposes, including [Task Parallel Library (TPL)](../parallel-programming/task-parallel-library-tpl.md) operations, asynchronous I/O completion, [timer](timers.md) callbacks, registered wait operations, asynchronous method calls using delegates, and socket connections. +The class provides your application with a pool of worker threads that are managed by the system, allowing you to concentrate on application tasks rather than thread management. If you have short tasks that require background processing, the managed thread pool is an easy way to take advantage of multiple threads. Use of the thread pool is significantly easier in Framework 4 and later, since you can create and objects that perform asynchronous tasks on thread pool threads. + +.NET uses thread pool threads for many purposes, including [Task Parallel Library (TPL)](../parallel-programming/task-parallel-library-tpl.md) operations, asynchronous I/O completion, [timer](timers.md) callbacks, registered wait operations, asynchronous method calls using delegates, and socket connections. ## Thread pool characteristics Thread pool threads are [background](foreground-and-background-threads.md) threads. Each thread uses the default stack size, runs at the default priority, and is in the multithreaded apartment. Once a thread in the thread pool completes its task, it's returned to a queue of waiting threads. From this moment it can be reused. This reuse enables applications to avoid the cost of creating a new thread for each task. - -There is only one thread pool per process. - + +There is only one thread pool per process. + ### Exceptions in thread pool threads -Unhandled exceptions in thread pool threads terminate the process. There are three exceptions to this rule: - -- A is thrown in a thread pool thread because was called. This only applies to .NET Framework. In .NET 5 and later versions, throws a . For more information, see [SYSLIB0006: Thread.Abort is not supported](../../fundamentals/syslib-diagnostics/syslib0006.md). -- A is thrown in a thread pool thread because the application domain is being unloaded. -- The common language runtime or a host process terminates the thread. - -For more information, see [Exceptions in Managed Threads](exceptions-in-managed-threads.md). - +Unhandled exceptions in thread pool threads terminate the process. There are three exceptions to this rule: + +- A is thrown in a thread pool thread because was called. This only applies to .NET Framework. In .NET 5 and later versions, throws a . For more information, see [SYSLIB0006: Thread.Abort is not supported](../../fundamentals/syslib-diagnostics/syslib0006.md). +- A is thrown in a thread pool thread because the application domain is being unloaded. +- The common language runtime or a host process terminates the thread. + +For more information, see [Exceptions in Managed Threads](exceptions-in-managed-threads.md). + ### Maximum number of thread pool threads -The number of operations that can be queued to the thread pool is limited only by available memory. However, the thread pool limits the number of threads that can be active in the process simultaneously. If all thread pool threads are busy, additional work items are queued until threads to execute them become available. The default size of the thread pool for a process depends on several factors, such as the size of the virtual address space. A process can call the method to determine the number of threads. - -You can control the maximum number of threads by using the and methods. +The number of operations that can be queued to the thread pool is limited only by available memory. However, the thread pool limits the number of threads that can be active in the process simultaneously. If all thread pool threads are busy, additional work items are queued until threads to execute them become available. The default size of the thread pool for a process depends on several factors, such as the size of the virtual address space. A process can call the method to determine the number of threads. + +You can control the maximum number of threads by using the and methods. > [!NOTE] -> Code that hosts the common language runtime can set the size using the [`ICorThreadpool::CorSetMaxThreads`](../../framework/unmanaged-api/hosting/icorthreadpool-corsetmaxthreads-method.md) method. - +> Code that hosts the common language runtime can set the size using the [`ICorThreadpool::CorSetMaxThreads`](../../framework/unmanaged-api/hosting/icorthreadpool-corsetmaxthreads-method.md) method. + ### Thread pool minimums -The thread pool provides new worker threads or I/O completion threads on demand until it reaches a specified minimum for each category. You can use the method to obtain these minimum values. - +The thread pool provides new worker threads or I/O completion threads on demand until it reaches a specified minimum for each category. You can use the method to obtain these minimum values. + > [!NOTE] -> When demand is low, the actual number of thread pool threads can fall below the minimum values. - -When a minimum is reached, the thread pool can create additional threads or wait until some tasks complete. The thread pool creates and destroys worker threads in order to optimize throughput, which is defined as the number of tasks that complete per unit of time. Too few threads might not make optimal use of available resources, whereas too many threads could increase resource contention. - +> When demand is low, the actual number of thread pool threads can fall below the minimum values. + +When a minimum is reached, the thread pool can create additional threads or wait until some tasks complete. The thread pool creates and destroys worker threads in order to optimize throughput, which is defined as the number of tasks that complete per unit of time. Too few threads might not make optimal use of available resources, whereas too many threads could increase resource contention. + > [!CAUTION] -> You can use the method to increase the minimum number of idle threads. However, unnecessarily increasing these values can cause performance problems. If too many tasks start at the same time, all of them might appear to be slow. In most cases the thread pool will perform better with its own algorithm for allocating threads. +> You can use the method to increase the minimum number of idle threads. However, unnecessarily increasing these values can cause performance problems. If too many tasks start at the same time, all of them might appear to be slow. In most cases the thread pool will perform better with its own algorithm for allocating threads. ## Using the thread pool -The easiest way to use the thread pool is to use the [Task Parallel Library (TPL)](../parallel-programming/task-parallel-library-tpl.md). By default, TPL types like and use thread pool threads to run tasks. +The easiest way to use the thread pool is to use the [Task Parallel Library (TPL)](../parallel-programming/task-parallel-library-tpl.md). By default, TPL types like and use thread pool threads to run tasks. -You can also use the thread pool by calling from managed code (or [`ICorThreadpool::CorQueueUserWorkItem`](../../framework/unmanaged-api/hosting/icorthreadpool-corqueueuserworkitem-method.md) from unmanaged code) and passing a delegate representing the method that performs the task. +You can also use the thread pool by calling from managed code (or [`ICorThreadpool::CorQueueUserWorkItem`](../../framework/unmanaged-api/hosting/icorthreadpool-corqueueuserworkitem-method.md) from unmanaged code) and passing a delegate representing the method that performs the task. -Another way to use the thread pool is to queue work items that are related to a wait operation by using the method and passing a that, when signaled or when timed out, calls the method represented by the delegate. Thread pool threads are used to invoke callback methods. +Another way to use the thread pool is to queue work items that are related to a wait operation by using the method and passing a that, when signaled or when timed out, calls the method represented by the delegate. Thread pool threads are used to invoke callback methods. For the examples, check the referenced API pages. - + ## Skipping security checks -The thread pool also provides the and methods. Use these methods only when you are certain that the caller's stack is irrelevant to any security checks performed during the execution of the queued task. and both capture the caller's stack, which is merged into the stack of the thread pool thread when the thread begins to execute a task. If a security check is required, the entire stack must be checked. Although the check provides safety, it also has a performance cost. +The thread pool also provides the and methods. Use these methods only when you are certain that the caller's stack is irrelevant to any security checks performed during the execution of the queued task. and both capture the caller's stack, which is merged into the stack of the thread pool thread when the thread begins to execute a task. If a security check is required, the entire stack must be checked. Although the check provides safety, it also has a performance cost. ## When not to use thread pool threads -There are several scenarios in which it's appropriate to create and manage your own threads instead of using thread pool threads: - -- You require a foreground thread. -- You require a thread to have a particular priority. -- You have tasks that cause the thread to block for long periods of time. The thread pool has a maximum number of threads, so a large number of blocked thread pool threads might prevent tasks from starting. -- You need to place threads into a single-threaded apartment. All threads are in the multithreaded apartment. -- You need to have a stable identity associated with the thread, or to dedicate a thread to a task. - +There are several scenarios in which it's appropriate to create and manage your own threads instead of using thread pool threads: + +- You require a foreground thread. +- You require a thread to have a particular priority. +- You have tasks that cause the thread to block for long periods of time. The thread pool has a maximum number of threads, so a large number of blocked thread pool threads might prevent tasks from starting. +- You need to place threads into a single-threaded apartment. All threads are in the multithreaded apartment. +- You need to have a stable identity associated with the thread, or to dedicate a thread to a task. + ## See also - - -- +- - [Task Parallel Library (TPL)](../parallel-programming/task-parallel-library-tpl.md) - [How to: Return a Value from a Task](../parallel-programming/how-to-return-a-value-from-a-task.md) - [Threading Objects and Features](threading-objects-and-features.md) diff --git a/docs/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots.md b/docs/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots.md index a15307000f636..5e11c832dd0e2 100644 --- a/docs/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots.md +++ b/docs/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots.md @@ -19,7 +19,7 @@ You can use managed thread local storage (TLS) to store data that's unique to a In unmanaged C++, you use `TlsAlloc` to allocate slots dynamically and `__declspec(thread)` to declare that a variable should be allocated in thread-relative storage. Thread-relative static fields and data slots provide the managed version of this behavior. -You can use the class to create thread-local objects that are initialized lazily when the object is first consumed. For more information, see [Lazy Initialization](../../framework/performance/lazy-initialization.md). +You can use the class to create thread-local objects that are initialized lazily when the object is first consumed. For more information, see [Lazy Initialization](../../framework/performance/lazy-initialization.md). ## Uniqueness of Data in Managed TLS @@ -45,18 +45,18 @@ You can use the structure. -- To create a named data slot, use the or method. To get a reference to an existing named slot, pass its name to the method. +- To create a named data slot, use the or method. To get a reference to an existing named slot, pass its name to the method. -- To create an unnamed data slot, use the method. +- To create an unnamed data slot, use the method. - For both named and unnamed slots, use the and methods to set and retrieve the information in the slot. These are static methods that always act on the data for the thread that is currently executing them. + For both named and unnamed slots, use the and methods to set and retrieve the information in the slot. These are static methods that always act on the data for the thread that is currently executing them. - Named slots can be convenient, because you can retrieve the slot when you need it by passing its name to the method, instead of maintaining a reference to an unnamed slot. However, if another component uses the same name for its thread-relative storage and a thread executes code from both your component and the other component, the two components might corrupt each other's data. (This scenario assumes that both components are running in the same application domain, and that they are not designed to share the same data.) + Named slots can be convenient, because you can retrieve the slot when you need it by passing its name to the method, instead of maintaining a reference to an unnamed slot. However, if another component uses the same name for its thread-relative storage and a thread executes code from both your component and the other component, the two components might corrupt each other's data. (This scenario assumes that both components are running in the same application domain, and that they are not designed to share the same data.) ## See also - -- +- - - - [Threading](managed-threading-basics.md) diff --git a/docs/standard/threading/timers.md b/docs/standard/threading/timers.md index f3ba0d9e12e52..cdc27f36b6be0 100644 --- a/docs/standard/threading/timers.md +++ b/docs/standard/threading/timers.md @@ -29,7 +29,7 @@ author: "pkulikov" The class enables you to continuously call a delegate at specified time intervals. You can also use this class to schedule a single call to a delegate in a specified time interval. The delegate is executed on a thread. -When you create a object, you specify a delegate that defines the callback method, an optional state object that is passed to the callback, the amount of time to delay before the first invocation of the callback, and the time interval between callback invocations. To cancel a pending timer, call the method. +When you create a object, you specify a delegate that defines the callback method, an optional state object that is passed to the callback, the amount of time to delay before the first invocation of the callback, and the time interval between callback invocations. To cancel a pending timer, call the method. The following example creates a timer that calls the provided delegate for the first time after one second (1000 milliseconds) and then calls it every two seconds. The state object in the example is used to count how many times the delegate is called. The timer is stopped when the delegate has been called at least 10 times. [!code-csharp[System.Threading.Timer#2](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.Threading.Timer/CS/source2.cs#2)] @@ -47,11 +47,11 @@ For more information and examples, see class enables you to await individual ticks of a specified interval, performing work after calling . +The class enables you to await individual ticks of a specified interval, performing work after calling . -When you create a object, you specify a that determines the length of time between each tick of the timer. Instead of passing a callback or setting an event handler as in the previous timer classes, you perform work directly in scope, awaiting to advance the timer by the specified interval. +When you create a object, you specify a that determines the length of time between each tick of the timer. Instead of passing a callback or setting an event handler as in the previous timer classes, you perform work directly in scope, awaiting to advance the timer by the specified interval. -The method returns a [`ValueTask`](xref:System.Threading.Tasks.ValueTask`1); `true` upon successful firing of the timer, and `false` when the timer has been canceled by calling . optionally accepts a , which results in a when a cancellation has been requested. +The method returns a [`ValueTask`](xref:System.Threading.Tasks.ValueTask`1); `true` upon successful firing of the timer, and `false` when the timer has been canceled by calling . optionally accepts a , which results in a when a cancellation has been requested. For more information, see . diff --git a/docs/standard/threading/using-threads-and-threading.md b/docs/standard/threading/using-threads-and-threading.md index a475cf35c5d10..e08b9a1008d5e 100644 --- a/docs/standard/threading/using-threads-and-threading.md +++ b/docs/standard/threading/using-threads-and-threading.md @@ -4,15 +4,15 @@ description: Learn about using threads and threading in .NET, so you can write a ms.date: 03/13/2026 ai-usage: ai-assisted ms.custom: devdivchpfy22 -helpviewer_keywords: +helpviewer_keywords: - "threading [.NET], about threading" - "managed threading" ms.assetid: 9b5ec2cd-121b-4d49-b075-222cf26f2344 --- # Using threads and threading -With .NET, you can write applications that perform multiple operations at the same time. Operations with the potential of holding up other operations can execute on separate threads, a process known as *multithreading* or *free threading*. - +With .NET, you can write applications that perform multiple operations at the same time. Operations with the potential of holding up other operations can execute on separate threads, a process known as *multithreading* or *free threading*. + Applications that use multithreading are more responsive to user input because the user interface stays active as processor-intensive tasks execute on separate threads. Multithreading is also useful when you create scalable applications because you can add threads as the workload increases. > [!NOTE] @@ -20,35 +20,35 @@ Applications that use multithreading are more responsive to user input because t ## How to: Create and start a new thread -You create a new thread by creating a new instance of the class. You provide the name of the method that you want to execute on the new thread to the constructor. To start a created thread, call the method. For more information and examples, see the [Creating threads and passing data at start time](creating-threads-and-passing-data-at-start-time.md) article and the API reference. +You create a new thread by creating a new instance of the class. You provide the name of the method that you want to execute on the new thread to the constructor. To start a created thread, call the method. For more information and examples, see the [Creating threads and passing data at start time](creating-threads-and-passing-data-at-start-time.md) article and the API reference. ## How to: Stop a thread To terminate the execution of a thread, use the . It provides a unified way to stop threads cooperatively. For more information, see [Cancellation in managed threads](cancellation-in-managed-threads.md). -Sometimes it's not possible to stop a thread cooperatively because it runs third-party code not designed for cooperative cancellation. In this case, you might want to terminate its execution forcibly. In .NET Framework, you can use the method, which raises a on the target thread. For more information, see [Destroying threads](destroying-threads.md). +Sometimes it's not possible to stop a thread cooperatively because it runs third-party code not designed for cooperative cancellation. In this case, you might want to terminate its execution forcibly. In .NET Framework, you can use the method, which raises a on the target thread. For more information, see [Destroying threads](destroying-threads.md). -In .NET Core and .NET 5 and later versions, throws a at runtime. In .NET 5 and later, calling it also generates a compile-time obsoletion warning ([SYSLIB0006](../../fundamentals/syslib-diagnostics/syslib0006.md)). If you need to terminate the execution of third-party code forcibly in modern .NET implementations, run it in a separate process and use the method. +In .NET Core and .NET 5 and later versions, throws a at runtime. In .NET 5 and later, calling it also generates a compile-time obsoletion warning ([SYSLIB0006](../../fundamentals/syslib-diagnostics/syslib0006.md)). If you need to terminate the execution of third-party code forcibly in modern .NET implementations, run it in a separate process and use the method. The isn't available before .NET Framework 4. To stop a thread in older .NET Framework versions, use the thread synchronization techniques to implement the cooperative cancellation manually. For example, you can create the volatile boolean field `shouldStop` and use it to request the code executed by the thread to stop. For more information, see [volatile](../../csharp/language-reference/keywords/volatile.md) in C# Reference and . -Use the method to make the calling thread wait for the termination of the thread being stopped. +Use the method to make the calling thread wait for the termination of the thread being stopped. ## How to: Pause or interrupt a thread -You use the method to pause the current thread for a specified amount of time. You can interrupt a blocked thread by calling the method. For more information, see [Pausing and interrupting threads](pausing-and-resuming-threads.md). +You use the method to pause the current thread for a specified amount of time. You can interrupt a blocked thread by calling the method. For more information, see [Pausing and interrupting threads](pausing-and-resuming-threads.md). ## Thread properties -The following table presents some of the properties: - -|Property|Description| -|--------------|-----------| -||Returns `true` if a thread has been started and hasn't yet terminated normally or aborted.| -||Gets or sets a Boolean that indicates if a thread is a background thread. Background threads are like foreground threads. However, a background thread doesn't prevent a process from stopping. Once all foreground threads that belong to a process have stopped, the common language runtime ends the process by calling the method on background threads that are still alive. For more information, see [Foreground and Background Threads](foreground-and-background-threads.md).| -||Gets or sets the name of a thread. Most frequently used to discover individual threads when you debug.| -||Gets or sets a value that's used by the operating system to prioritize thread scheduling. For more information, see [Scheduling threads](scheduling-threads.md) and the reference.| -||Gets a value containing the current states of a thread.| +The following table presents some of the properties: + +|Property|Description| +|--------------|-----------| +||Returns `true` if a thread has been started and hasn't yet terminated normally or aborted.| +||Gets or sets a Boolean that indicates if a thread is a background thread. Background threads are like foreground threads. However, a background thread doesn't prevent a process from stopping. Once all foreground threads that belong to a process have stopped, the common language runtime ends the process by calling the method on background threads that are still alive. For more information, see [Foreground and Background Threads](foreground-and-background-threads.md).| +||Gets or sets the name of a thread. Most frequently used to discover individual threads when you debug.| +||Gets or sets a value that's used by the operating system to prioritize thread scheduling. For more information, see [Scheduling threads](scheduling-threads.md) and the reference.| +||Gets a value containing the current states of a thread.| ## See also diff --git a/docs/standard/value-tuples.md b/docs/standard/value-tuples.md index 43e4e3e19dc1f..8eae839cf9ebf 100644 --- a/docs/standard/value-tuples.md +++ b/docs/standard/value-tuples.md @@ -7,22 +7,22 @@ ms.date: 01/03/2024 A value tuple is a data structure that has a specific number and sequence of values. .NET provides the following built-in value tuple types: -- The structure represents a value tuple that has one element. -- The structure represents a value tuple that has two elements.- -- The structure represents a value tuple that has three elements. -- The structure represents a value tuple that has four elements. -- The structure represents a value tuple that has five elements. -- The structure represents a value tuple that has six elements. -- The structure represents a value tuple that has seven elements. -- The structure represents a value tuple that has eight or more elements. +- The structure represents a value tuple that has one element. +- The structure represents a value tuple that has two elements.- +- The structure represents a value tuple that has three elements. +- The structure represents a value tuple that has four elements. +- The structure represents a value tuple that has five elements. +- The structure represents a value tuple that has six elements. +- The structure represents a value tuple that has seven elements. +- The structure represents a value tuple that has eight or more elements. -The value tuple types differ from the tuple types (such as ) as follows: +The value tuple types differ from the tuple types (such as ) as follows: - They are structures (value types) rather than classes (reference types). -- Members such as and are fields rather than properties. +- Members such as and are fields rather than properties. - Their fields are mutable rather than read-only. -The value tuple types provide the runtime implementation that supports [tuples in C#](../csharp/language-reference/builtin-types/value-tuples.md) and struct tuples in F#. In addition to creating a instance by using language syntax, you can call the factory method. +The value tuple types provide the runtime implementation that supports [tuples in C#](../csharp/language-reference/builtin-types/value-tuples.md) and struct tuples in F#. In addition to creating a instance by using language syntax, you can call the factory method. ## See also diff --git a/docs/visual-basic/developing-apps/customizing-extending-my/extending-the-visual-basic-application-model.md b/docs/visual-basic/developing-apps/customizing-extending-my/extending-the-visual-basic-application-model.md index 9570d761f6987..08de2e4ada8aa 100644 --- a/docs/visual-basic/developing-apps/customizing-extending-my/extending-the-visual-basic-application-model.md +++ b/docs/visual-basic/developing-apps/customizing-extending-my/extending-the-visual-basic-application-model.md @@ -14,7 +14,7 @@ You can add functionality to the application model by overriding the `Overridabl This section visually presents the sequence of function calls in the Visual Basic Application Model. The next section describes the purpose of each function in detail. -The following graphic shows the application model call sequence in a normal Visual Basic Windows Forms application. The sequence starts when the `Sub Main` procedure calls the method. +The following graphic shows the application model call sequence in a normal Visual Basic Windows Forms application. The sequence starts when the `Sub Main` procedure calls the method. ![Diagram showing the Application Model call sequence.](./media/extending-the-visual-basic-application-model/application-model-call-sequence.gif) @@ -26,55 +26,55 @@ The Visual Basic Application Model also provides the method defines the order in which the `Application` methods run. By default, the `Sub Main` procedure for a Windows Forms application calls the method. +The method defines the order in which the `Application` methods run. By default, the `Sub Main` procedure for a Windows Forms application calls the method. -If the application is a normal application (multiple-instance application), or the first instance of a single-instance application, the method executes the `Overridable` methods in the following order: +If the application is a normal application (multiple-instance application), or the first instance of a single-instance application, the method executes the `Overridable` methods in the following order: -1. . By default, this method sets the visual styles, text display styles, and current principal for the main application thread (if the application uses Windows authentication), and calls `ShowSplashScreen` if neither `/nosplash` nor `-nosplash` is used as a command-line argument. +1. . By default, this method sets the visual styles, text display styles, and current principal for the main application thread (if the application uses Windows authentication), and calls `ShowSplashScreen` if neither `/nosplash` nor `-nosplash` is used as a command-line argument. The application startup sequence is canceled if this function returns `False`. This can be useful if there are circumstances in which the application should not run. - The method calls the following methods: + The method calls the following methods: - 1. . Determines if the application has a splash screen defined and if it does, displays the splash screen on a separate thread. + 1. . Determines if the application has a splash screen defined and if it does, displays the splash screen on a separate thread. - The method contains the code that displays the splash screen for at least the number of milliseconds specified by the property. To use this functionality, you must add the splash screen to your application using the **Project Designer** (which sets the `My.Application.MinimumSplashScreenDisplayTime` property to two seconds), or set the `My.Application.MinimumSplashScreenDisplayTime` property in a method that overrides the or method. For more information, see . + The method contains the code that displays the splash screen for at least the number of milliseconds specified by the property. To use this functionality, you must add the splash screen to your application using the **Project Designer** (which sets the `My.Application.MinimumSplashScreenDisplayTime` property to two seconds), or set the `My.Application.MinimumSplashScreenDisplayTime` property in a method that overrides the or method. For more information, see . - 2. . Allows a designer to emit code that initializes the splash screen. + 2. . Allows a designer to emit code that initializes the splash screen. - By default, this method does nothing. If you select a splash screen for your application in the Visual Basic **Project Designer**, the designer overrides the method with a method that sets the property to a new instance of the splash-screen form. + By default, this method does nothing. If you select a splash screen for your application in the Visual Basic **Project Designer**, the designer overrides the method with a method that sets the property to a new instance of the splash-screen form. -2. . Provides an extensibility point for raising the `Startup` event. The application startup sequence stops if this function returns `False`. +2. . Provides an extensibility point for raising the `Startup` event. The application startup sequence stops if this function returns `False`. By default, this method raises the event. If the event handler sets the property of the event argument to `True`, the method returns `False` to cancel the application startup. -3. . Provides the starting point for when the main application is ready to start running, after the initialization is done. +3. . Provides the starting point for when the main application is ready to start running, after the initialization is done. By default, before it enters the Windows Forms message loop, this method calls the `OnCreateMainForm` (to create the application's main form) and `HideSplashScreen` (to close the splash screen) methods: - 1. . Provides a way for a designer to emit code that initializes the main form. + 1. . Provides a way for a designer to emit code that initializes the main form. - By default, this method does nothing. However, when you select a main form for your application in the Visual Basic **Project Designer**, the designer overrides the method with a method that sets the property to a new instance of the main form. + By default, this method does nothing. However, when you select a main form for your application in the Visual Basic **Project Designer**, the designer overrides the method with a method that sets the property to a new instance of the main form. - 2. . If application has a splash screen defined and it is open, this method closes the splash screen. + 2. . If application has a splash screen defined and it is open, this method closes the splash screen. By default, this method closes the splash screen. -4. . Provides a way to customize how a single-instance application behaves when another instance of the application starts. +4. . Provides a way to customize how a single-instance application behaves when another instance of the application starts. By default, this method raises the event. -5. . Provides an extensibility point for raising the `Shutdown` event. This method does not run if an unhandled exception occurs in the main application. +5. . Provides an extensibility point for raising the `Shutdown` event. This method does not run if an unhandled exception occurs in the main application. By default, this method raises the event. -6. . Executed if an unhandled exception occurs in any of the above listed methods. +6. . Executed if an unhandled exception occurs in any of the above listed methods. By default, this method raises the event as long as a debugger is not attached and the application is handling the `UnhandledException` event. - If the application is a single-instance application, and the application is already running, the subsequent instance of the application calls the method on the original instance of the application, and then exits. + If the application is a single-instance application, and the application is already running, the subsequent instance of the application calls the method on the original instance of the application, and then exits. - The constructor calls the property to determine which text rendering engine to use for the application's forms. By default, the property returns `False`, indicating that the GDI text rendering engine be used, which is the default in Visual Basic 2005 and later versions. You can override the property to return `True`, which indicates that the GDI+ text rendering engine be used, which is the default in Visual Basic .NET 2002 and Visual Basic .NET 2003. + The constructor calls the property to determine which text rendering engine to use for the application's forms. By default, the property returns `False`, indicating that the GDI text rendering engine be used, which is the default in Visual Basic 2005 and later versions. You can override the property to return `True`, which indicates that the GDI+ text rendering engine be used, which is the default in Visual Basic .NET 2002 and Visual Basic .NET 2003. ## Configuring the Application @@ -84,10 +84,10 @@ If the application is a normal application (multiple-instance application), or t |Property|Determines|Setting in the Application pane of the Project Designer| |---|---|---| -||Whether the application runs as a single-instance or multiple-instance application.|**Make single instance application** check box| -||If the application will use visual styles that match Windows XP.|**Enable XP visual styles** check box| -||If application automatically saves application's user-settings changes when the application exits.|**Save My.Settings on Shutdown** check box| -||What causes the application to terminate, such as when the startup form closes or when the last form closes.|**Shutdown mode** list| +||Whether the application runs as a single-instance or multiple-instance application.|**Make single instance application** check box| +||If the application will use visual styles that match Windows XP.|**Enable XP visual styles** check box| +||If application automatically saves application's user-settings changes when the application exits.|**Save My.Settings on Shutdown** check box| +||What causes the application to terminate, such as when the startup form closes or when the last form closes.|**Shutdown mode** list| ## See also diff --git a/docs/visual-basic/developing-apps/programming/accessing-application-forms.md b/docs/visual-basic/developing-apps/programming/accessing-application-forms.md index c897a0469186a..d69bbaaad8da2 100644 --- a/docs/visual-basic/developing-apps/programming/accessing-application-forms.md +++ b/docs/visual-basic/developing-apps/programming/accessing-application-forms.md @@ -2,7 +2,7 @@ description: "Learn more about: Accessing Application Forms (Visual Basic)" title: "Accessing Application Forms" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "forms [Visual Basic], communicating between" - "application forms [Visual Basic], accessing" - "forms [Visual Basic], accessing one from another" @@ -12,20 +12,20 @@ ms.assetid: 9aaf5aaf-2012-4f97-89c7-6e62b9d17863 --- # Accessing Application Forms (Visual Basic) -The `My.Forms` object provides an easy way to access an instance of each Windows Form declared in the application's project. You can also use properties of the `My.Application` object to access the application's splash screen and main form, and get a list of the application's open forms. - -## Tasks +The `My.Forms` object provides an easy way to access an instance of each Windows Form declared in the application's project. You can also use properties of the `My.Application` object to access the application's splash screen and main form, and get a list of the application's open forms. + +## Tasks + + The following table lists examples showing how to access an application's forms. + +|To|See| +|---|---| +|Access one form from another form in an application.|[My.Forms Object](../../language-reference/objects/my-forms-object.md)| +|Display the titles of all the application's open forms.|| +|Update the splash screen with status information as the application starts.|| - The following table lists examples showing how to access an application's forms. - -|To|See| -|---|---| -|Access one form from another form in an application.|[My.Forms Object](../../language-reference/objects/my-forms-object.md)| -|Display the titles of all the application's open forms.|| -|Update the splash screen with status information as the application starts.|| - ## See also -- -- +- +- - [My.Forms Object](../../language-reference/objects/my-forms-object.md) diff --git a/docs/visual-basic/developing-apps/programming/accessing-user-data.md b/docs/visual-basic/developing-apps/programming/accessing-user-data.md index df9ab3b18934f..718bca47721b1 100644 --- a/docs/visual-basic/developing-apps/programming/accessing-user-data.md +++ b/docs/visual-basic/developing-apps/programming/accessing-user-data.md @@ -2,7 +2,7 @@ description: "Learn more about: Accessing User Data (Visual Basic)" title: "Accessing User Data" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "domain names [Visual Basic], retrieving" - "data [Visual Basic], accessing user data" - "My.User object [Visual Basic], tasks" @@ -15,18 +15,18 @@ ms.assetid: 32492a15-ee59-4a63-a1f1-9b24cc13140a --- # Accessing User Data (Visual Basic) -This section contains topics dealing with the `My.User` object and tasks that you can accomplish with it. - - The `My.User` object provides access to information about the logged-on user by returning an object that implements the interface. - -## Tasks - -|To|See| -|--------|---------| -|Get the user's login name|| -|Get the user's domain name, if the application uses Windows authentication|| -|Determine the user's role|| - +This section contains topics dealing with the `My.User` object and tasks that you can accomplish with it. + + The `My.User` object provides access to information about the logged-on user by returning an object that implements the interface. + +## Tasks + +|To|See| +|--------|---------| +|Get the user's login name|| +|Get the user's domain name, if the application uses Windows authentication|| +|Determine the user's role|| + ## See also - diff --git a/docs/visual-basic/developing-apps/programming/app-settings/how-to-create-property-grids-for-user-settings.md b/docs/visual-basic/developing-apps/programming/app-settings/how-to-create-property-grids-for-user-settings.md index 76574bec35469..112c19d8380be 100644 --- a/docs/visual-basic/developing-apps/programming/app-settings/how-to-create-property-grids-for-user-settings.md +++ b/docs/visual-basic/developing-apps/programming/app-settings/how-to-create-property-grids-for-user-settings.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Create Property Grids for User Settings in Visual Basic" title: "How to: Create Property Grids for User Settings" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "My.Settings object [Visual Basic], creating property grids for user settings" - "user settings [Visual Basic], creating property grids" - "property grids [Visual Basic], creating for user settings" @@ -11,41 +11,41 @@ ms.assetid: b0bc737e-50d1-43d1-a6df-268db6e6f91c --- # How to: Create Property Grids for User Settings in Visual Basic -You can create a property grid for user settings by populating a control with the user setting properties of the `My.Settings` object. - +You can create a property grid for user settings by populating a control with the user setting properties of the `My.Settings` object. + > [!NOTE] -> In order for this example to work, your application must have its user settings configured. For more information, see [Managing Application Settings (.NET)](/visualstudio/ide/managing-application-settings-dotnet). - - The `My.Settings` object exposes each setting as a property. The property name is the same as the setting name, and the property type is the same as the setting type. The setting's **Scope** determines if the property is read-only; the property for an **Application**-scope setting is read-only, while the property for a **User**-scope setting is read-write. For more information, see [My.Settings Object](../../../language-reference/objects/my-settings-object.md). - +> In order for this example to work, your application must have its user settings configured. For more information, see [Managing Application Settings (.NET)](/visualstudio/ide/managing-application-settings-dotnet). + + The `My.Settings` object exposes each setting as a property. The property name is the same as the setting name, and the property type is the same as the setting type. The setting's **Scope** determines if the property is read-only; the property for an **Application**-scope setting is read-only, while the property for a **User**-scope setting is read-write. For more information, see [My.Settings Object](../../../language-reference/objects/my-settings-object.md). + > [!NOTE] -> You cannot change or save the values of application-scope settings at run time. Application-scope settings can be changed only when creating the application (through the **Project Designer**) or by editing the application's configuration file. For more information, see [Managing Application Settings (.NET)](/visualstudio/ide/managing-application-settings-dotnet). - - This example uses a control to access the user-setting properties of the `My.Settings` object. By default, the shows all the properties of the `My.Settings` object. However, the user-setting properties have the attribute. This example sets the property of the to to display only the user-setting properties. - -### To add a user setting property grid - -1. Add the **PropertyGrid** control from the **Toolbox** to the design surface for your application, assumed here to be `Form1`. - - The default name of the property-grid control is `PropertyGrid1`. - -2. Double-click the design surface for `Form1` to open the code for the form-load event handler. - -3. Set the `My.Settings` object as the selected object for the property grid. - - [!code-vb[VbVbalrMyResources#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyResources/VB/Form1.vb#11)] - -4. Configure the property grid to show only the user settings. - - [!code-vb[VbVbalrMyResources#12](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyResources/VB/Form1.vb#12)] - +> You cannot change or save the values of application-scope settings at run time. Application-scope settings can be changed only when creating the application (through the **Project Designer**) or by editing the application's configuration file. For more information, see [Managing Application Settings (.NET)](/visualstudio/ide/managing-application-settings-dotnet). + + This example uses a control to access the user-setting properties of the `My.Settings` object. By default, the shows all the properties of the `My.Settings` object. However, the user-setting properties have the attribute. This example sets the property of the to to display only the user-setting properties. + +### To add a user setting property grid + +1. Add the **PropertyGrid** control from the **Toolbox** to the design surface for your application, assumed here to be `Form1`. + + The default name of the property-grid control is `PropertyGrid1`. + +2. Double-click the design surface for `Form1` to open the code for the form-load event handler. + +3. Set the `My.Settings` object as the selected object for the property grid. + + [!code-vb[VbVbalrMyResources#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyResources/VB/Form1.vb#11)] + +4. Configure the property grid to show only the user settings. + + [!code-vb[VbVbalrMyResources#12](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyResources/VB/Form1.vb#12)] + > [!NOTE] - > To show only the application-scope settings, use the attribute instead of . - -## Robust Programming + > To show only the application-scope settings, use the attribute instead of . + +## Robust Programming + + The application saves the user settings when the application shuts down. To save the settings immediately, call the `My.Settings.Save` method. For more information, see [How to: Persist User Settings in Visual Basic](how-to-persist-user-settings.md). - The application saves the user settings when the application shuts down. To save the settings immediately, call the `My.Settings.Save` method. For more information, see [How to: Persist User Settings in Visual Basic](how-to-persist-user-settings.md). - ## See also - [My.Settings Object](../../../language-reference/objects/my-settings-object.md) diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-computer-s-ports.md b/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-computer-s-ports.md index 151efe5453f22..4ce6acf304263 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-computer-s-ports.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-computer-s-ports.md @@ -2,44 +2,44 @@ description: "Learn more about: Accessing the Computer's Ports (Visual Basic)" title: "Accessing the Computer's Ports" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "serial ports" - "My.Computer.Ports object [Visual Basic], tasks" ms.assetid: b04a2f76-992a-4585-ab41-8bbbdbd554a1 --- # Accessing the Computer's Ports (Visual Basic) -The `My.Computer.Ports` object provides a property and a method for accessing the computer's serial ports. - -## In This Section - - [How to: Show Available Serial Ports](how-to-show-available-serial-ports.md) - Demonstrates how to show available serial ports. - - [How to: Dial Modems Attached to Serial Ports](how-to-dial-modems-attached-to-serial-ports.md) - Demonstrates how to dial a modem attached to the serial port of a computer. - - [How to: Send Strings to Serial Ports](how-to-send-strings-to-serial-ports.md) - Demonstrates how to send a string to a computer's serial port. - - [How to: Receive Strings From Serial Ports](how-to-receive-strings-from-serial-ports.md) - Demonstrates how to receive a string from a computer's serial port. - - [Port Operations in the .NET Framework](port-operations-in-the-net-framework.md) - Describes how to use the .NET Framework when performing port operations. - -## Reference - - - Describes the `My.Computer.Ports` object and its members. - - - Describes the `SerialPortNames` property, which gets a collection of the names of the serial ports on the computer. - - - Describes the `OpenSerialPort` method, which creates and opens a object. - -## Related Sections - - +The `My.Computer.Ports` object provides a property and a method for accessing the computer's serial ports. + +## In This Section + + [How to: Show Available Serial Ports](how-to-show-available-serial-ports.md) + Demonstrates how to show available serial ports. + + [How to: Dial Modems Attached to Serial Ports](how-to-dial-modems-attached-to-serial-ports.md) + Demonstrates how to dial a modem attached to the serial port of a computer. + + [How to: Send Strings to Serial Ports](how-to-send-strings-to-serial-ports.md) + Demonstrates how to send a string to a computer's serial port. + + [How to: Receive Strings From Serial Ports](how-to-receive-strings-from-serial-ports.md) + Demonstrates how to receive a string from a computer's serial port. + + [Port Operations in the .NET Framework](port-operations-in-the-net-framework.md) + Describes how to use the .NET Framework when performing port operations. + +## Reference + + + Describes the `My.Computer.Ports` object and its members. + + + Describes the `SerialPortNames` property, which gets a collection of the names of the serial ports on the computer. + + + Describes the `OpenSerialPort` method, which creates and opens a object. + +## Related Sections + + Describes the .NET Framework class. diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-keyboard.md b/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-keyboard.md index 5833a09cd6ec5..0e691883ae901 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-keyboard.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-keyboard.md @@ -2,7 +2,7 @@ description: "Learn more about: Accessing the Keyboard (Visual Basic)" title: "Accessing the Keyboard" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "keyboards [Visual Basic], accessing [Visual Basic]" - "My.Computer.Keyboard object [Visual Basic], tasks" - "keystrokes" @@ -11,22 +11,22 @@ ms.assetid: aa37d54c-5c98-4b44-b98a-c26d2a03c038 --- # Accessing the Keyboard (Visual Basic) -The `My.Computer.Keyboard` object provides properties for accessing the current state of the keyboard, such as what keys are currently pressed, and provides a method to send keystrokes to the active window. - -## Tasks +The `My.Computer.Keyboard` object provides properties for accessing the current state of the keyboard, such as what keys are currently pressed, and provides a method to send keystrokes to the active window. + +## Tasks + + This table lists tasks associated with the `My.Computer.Keyboard` object and points to topics demonstrating how to perform each task. + +|To|See| +|--------|---------| +|Determine whether CAPS LOCK is on|| +|Determine whether the SHIFT key is down|| +|Determine whether the ALT key is down|| +|Determine whether the CTRL key is down|| +|Determine whether NUM LOCK is on|| +|Determine whether SCROLL LOCK is on|| +|Start an application and send it keystrokes|[How to: Start an Application and Send it Keystrokes (Visual Basic)](how-to-start-an-application-and-send-it-keystrokes.md)| - This table lists tasks associated with the `My.Computer.Keyboard` object and points to topics demonstrating how to perform each task. - -|To|See| -|--------|---------| -|Determine whether CAPS LOCK is on|| -|Determine whether the SHIFT key is down|| -|Determine whether the ALT key is down|| -|Determine whether the CTRL key is down|| -|Determine whether NUM LOCK is on|| -|Determine whether SCROLL LOCK is on|| -|Start an application and send it keystrokes|[How to: Start an Application and Send it Keystrokes (Visual Basic)](how-to-start-an-application-and-send-it-keystrokes.md)| - ## See also - diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/getting-information-about-the-computer.md b/docs/visual-basic/developing-apps/programming/computer-resources/getting-information-about-the-computer.md index 49542c464b617..4683adca5d605 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/getting-information-about-the-computer.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/getting-information-about-the-computer.md @@ -16,12 +16,12 @@ This table lists tasks commonly accomplished through the `My.Computer.Info` obje |To|See| |---|---| -|Determine how much virtual address space is available for the computer on which the application is installed|| -|Determine the platform type of the computer on which the application is running|| -|Determine the operating system of the computer on which the application is running|| -|Determine what service packs have been installed on the computer on which the application is running|| -|Determine the installed `UICulture` on the computer on which the application is running.|| +|Determine how much virtual address space is available for the computer on which the application is installed|| +|Determine the platform type of the computer on which the application is running|| +|Determine the operating system of the computer on which the application is running|| +|Determine what service packs have been installed on the computer on which the application is running|| +|Determine the installed `UICulture` on the computer on which the application is running.|| ## See also -- +- diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value.md index 1f73d45d8ee51..43aaec2541c0f 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-create-a-registry-key-and-set-its-value.md @@ -49,7 +49,7 @@ When reading the registry from a Web application, the current user depends on th It is more secure to write data to the user folder () rather than to the local computer (). -When you create a registry value, you need to decide what to do if that value already exists. Another process, perhaps a malicious one, may have already created the value and have access to it. When you put data in the registry value, the data is available to the other process. To prevent this, use the method. It returns `Nothing` if the key does not already exist. +When you create a registry value, you need to decide what to do if that value already exists. Another process, perhaps a malicious one, may have already created the value and have access to it. When you put data in the registry value, the data is available to the other process. To prevent this, use the method. It returns `Nothing` if the key does not already exist. It is not secure to store secrets, such as passwords, in the registry as plain text, even if the registry key is protected by ACLs (Access Control Lists). @@ -74,6 +74,6 @@ To run this process, your assembly requires a privilege level granted by the -- -- +- +- - [Reading from and Writing to the Registry](reading-from-and-writing-to-the-registry.md) diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key.md index cdcda60c95283..31860bfaf0a30 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-delete-a-registry-key.md @@ -2,9 +2,9 @@ description: "Learn more about: How to: Delete a Registry Key in Visual Basic" title: "How to: Delete a Registry Key" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.DeleteSetting" -helpviewer_keywords: +helpviewer_keywords: - "GetSetting function [Visual Basic]" - "registry [Visual Basic], deleting values" - "GetAllSettings function" @@ -15,37 +15,37 @@ ms.assetid: ab9aca0e-42b0-4ff7-8ff9-845a4bfdf9f2 --- # How to: Delete a Registry Key in Visual Basic -The and methods can be used to delete registry keys. - -## Procedure - -#### To delete a registry key - -- Use the `DeleteSubKey` method to delete a registry key. This example deletes the key Software/TestApp in the CurrentUser hive. You can change this in the code to the appropriate string, or have it rely on user-supplied information. - - [!code-vb[VbResourceTasks#19](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#19)] - -## Robust Programming - - The `DeleteSubKey` method returns an empty string if the key/value pair does not exist. - - The following conditions may cause an exception: - -- The name of the key is `Nothing` (). - -- The user does not have permissions to delete registry keys (). - -- The key name exceeds the 255-character limit (). - -- The registry key is read-only (). - -## .NET Framework Security - - Registry calls fail if either sufficient run-time permissions are not granted () or if the user does not have the correct access (as determined by the ACLs) for creating or writing to settings. For example, a local application that has the code access security permission might not have operating system permission. - +The and methods can be used to delete registry keys. + +## Procedure + +#### To delete a registry key + +- Use the `DeleteSubKey` method to delete a registry key. This example deletes the key Software/TestApp in the CurrentUser hive. You can change this in the code to the appropriate string, or have it rely on user-supplied information. + + [!code-vb[VbResourceTasks#19](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#19)] + +## Robust Programming + + The `DeleteSubKey` method returns an empty string if the key/value pair does not exist. + + The following conditions may cause an exception: + +- The name of the key is `Nothing` (). + +- The user does not have permissions to delete registry keys (). + +- The key name exceeds the 255-character limit (). + +- The registry key is read-only (). + +## .NET Framework Security + + Registry calls fail if either sufficient run-time permissions are not granted () or if the user does not have the correct access (as determined by the ACLs) for creating or writing to settings. For example, a local application that has the code access security permission might not have operating system permission. + ## See also -- +- - - [Security and the Registry](security-and-the-registry.md) - [Reading from and Writing to the Registry](reading-from-and-writing-to-the-registry.md) diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-dial-modems-attached-to-serial-ports.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-dial-modems-attached-to-serial-ports.md index 2b1bf7e7094cb..63b0a7b5824a0 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-dial-modems-attached-to-serial-ports.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-dial-modems-attached-to-serial-ports.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Dial Modems Attached to Serial Ports in Visual Basic" title: "How to: Dial Modems Attached to Serial Ports" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "modems [Visual Basic], dialing" - "serial ports [Visual Basic], dialing" - "My.Computer.Ports object" @@ -10,46 +10,46 @@ ms.assetid: 3834db40-f431-45f1-b671-dc91787164b6 --- # How to: Dial Modems Attached to Serial Ports in Visual Basic -This topic describes how to use `My.Computer.Ports` to dial a modem in Visual Basic. - - Typically, the modem is connected to one of the serial ports on the computer. For your application to communicate with the modem, it must send commands to the appropriate serial port. - -### To dial a modem - -1. Determine which serial port the modem is connected to. This example assumes the modem is on COM1. - -2. Use the `My.Computer.Ports.OpenSerialPort` method to obtain a reference to the port. For more information, see . - - The `Using` block allows the application to close the serial port even if it generates an exception. All code that manipulates the serial port should appear within this block, or within a `Try...Catch...Finally` block. - - [!code-vb[VbVbalrMyComputer#28](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#28)] - -3. Set the `DtrEnable` property to indicate that the computer is ready to accept an incoming transmission from the modem. - - [!code-vb[VbVbalrMyComputer#29](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#29)] - -4. Send the dial command and the phone number to the modem through the serial port by means of the method. - - [!code-vb[VbVbalrMyComputer#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#30)] - -## Example - - [!code-vb[VbVbalrMyComputer#27](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#27)] - - This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Connectivity and Networking**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). - -## Compiling the Code - - This example requires a reference to the namespace. - -## Robust Programming - - This example assumes the modem is connected to COM1. We recommend that your code allow the user to select the desired serial port from a list of available ports. For more information, see [How to: Show Available Serial Ports](how-to-show-available-serial-ports.md). - - This example uses a `Using` block to make sure that the application closes the port even if it throws an exception. For more information, see [Using Statement](../../../language-reference/statements/using-statement.md). - - In this example, the application disconnects the serial port after it dials the modem. Realistically, you will want to transfer data to and from the modem. For more information, see [How to: Receive Strings From Serial Ports](how-to-receive-strings-from-serial-ports.md). - +This topic describes how to use `My.Computer.Ports` to dial a modem in Visual Basic. + + Typically, the modem is connected to one of the serial ports on the computer. For your application to communicate with the modem, it must send commands to the appropriate serial port. + +### To dial a modem + +1. Determine which serial port the modem is connected to. This example assumes the modem is on COM1. + +2. Use the `My.Computer.Ports.OpenSerialPort` method to obtain a reference to the port. For more information, see . + + The `Using` block allows the application to close the serial port even if it generates an exception. All code that manipulates the serial port should appear within this block, or within a `Try...Catch...Finally` block. + + [!code-vb[VbVbalrMyComputer#28](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#28)] + +3. Set the `DtrEnable` property to indicate that the computer is ready to accept an incoming transmission from the modem. + + [!code-vb[VbVbalrMyComputer#29](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#29)] + +4. Send the dial command and the phone number to the modem through the serial port by means of the method. + + [!code-vb[VbVbalrMyComputer#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#30)] + +## Example + + [!code-vb[VbVbalrMyComputer#27](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#27)] + + This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Connectivity and Networking**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). + +## Compiling the Code + + This example requires a reference to the namespace. + +## Robust Programming + + This example assumes the modem is connected to COM1. We recommend that your code allow the user to select the desired serial port from a list of available ports. For more information, see [How to: Show Available Serial Ports](how-to-show-available-serial-ports.md). + + This example uses a `Using` block to make sure that the application closes the port even if it throws an exception. For more information, see [Using Statement](../../../language-reference/statements/using-statement.md). + + In this example, the application disconnects the serial port after it dials the modem. Realistically, you will want to transfer data to and from the modem. For more information, see [How to: Receive Strings From Serial Ports](how-to-receive-strings-from-serial-ports.md). + ## See also - diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-download-a-file.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-download-a-file.md index 8e70054d8c0e8..b1cde4bc81bfd 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-download-a-file.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-download-a-file.md @@ -12,7 +12,7 @@ ms.assetid: ac479f81-c0e2-4b99-af73-217f446b73da --- # How to: Download a File in Visual Basic -The method can be used to download a remote file and store it to a specific location. If the `ShowUI` parameter is set to `True`, a dialog box is displayed showing the progress of the download and allowing users to cancel the operation. By default, existing files having the same name are not overwritten; if you want to overwrite existing files, set the `overwrite` parameter to `True`. +The method can be used to download a remote file and store it to a specific location. If the `ShowUI` parameter is set to `True`, a dialog box is displayed showing the progress of the download and allowing users to cancel the operation. By default, existing files having the same name are not overwritten; if you want to overwrite existing files, set the `overwrite` parameter to `True`. The following conditions may cause an exception: @@ -53,6 +53,6 @@ The following conditions may cause an exception: ## See also - -- +- - [How to: Upload a File](how-to-upload-a-file.md) - [How to: Parse File Paths](../drives-directories-files/how-to-parse-file-paths.md) diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-receive-strings-from-serial-ports.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-receive-strings-from-serial-ports.md index 8ed6c63f61981..4d4392c24cce5 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-receive-strings-from-serial-ports.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-receive-strings-from-serial-ports.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Receive Strings From Serial Ports in Visual Basic" title: "How to: Receive Strings From Serial Ports" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "serial ports, retrieving strings" - "strings [Visual Basic], retrieving from serial ports" - "My.Resources object" @@ -10,58 +10,58 @@ ms.assetid: 8371ce2c-e1c7-476b-a86d-9afc2614b6b7 --- # How to: Receive Strings From Serial Ports in Visual Basic -This topic describes how to use `My.Computer.Ports` to receive strings from the computer's serial ports in Visual Basic. - -### To receive strings from the serial port - -1. Initialize the return string. - - [!code-vb[VbVbalrMyComputer#38](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#38)] - -2. Determine which serial port should provide the strings. This example assumes it is `COM1`. - -3. Use the `My.Computer.Ports.OpenSerialPort` method to obtain a reference to the port. For more information, see . - - The `Try...Catch...Finally` block allows the application to close the serial port even if it generates an exception. All code that manipulates the serial port should appear within this block. - - [!code-vb[VbVbalrMyComputer#39](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#39)] - -4. Create a `Do` loop for reading lines of text until no more lines are available. - - [!code-vb[VbVbalrMyComputer#40](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#40)] - -5. Use the method to read the next available line of text from the serial port. - - [!code-vb[VbVbalrMyComputer#41](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#41)] - -6. Use an `If` statement to determine if the method returns `Nothing` (which means no more text is available). If it does return `Nothing`, exit the `Do` loop. - - [!code-vb[VbVbalrMyComputer#42](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#42)] - -7. Add an `Else` block to the `If` statement to handle the case if the string is actually read. The block appends the string from the serial port to the return string. - - [!code-vb[VbVbalrMyComputer#43](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#43)] - -8. Return the string. - - [!code-vb[VbVbalrMyComputer#44](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#44)] - -## Example - - [!code-vb[VbVbalrMyComputer#37](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#37)] - - This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Connectivity and Networking**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). - -## Compiling the Code - - This example assumes the computer is using `COM1`. - -## Robust Programming - - This example assumes the computer is using `COM1`. For more flexibility, the code should allow the user to select the desired serial port from a list of available ports. For more information, see [How to: Show Available Serial Ports](how-to-show-available-serial-ports.md). - - This example uses a `Try...Catch...Finally` block to make sure that the application closes the port and to catch any timeout exceptions. For more information, see [Try...Catch...Finally Statement](../../../language-reference/statements/try-catch-finally-statement.md). - +This topic describes how to use `My.Computer.Ports` to receive strings from the computer's serial ports in Visual Basic. + +### To receive strings from the serial port + +1. Initialize the return string. + + [!code-vb[VbVbalrMyComputer#38](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#38)] + +2. Determine which serial port should provide the strings. This example assumes it is `COM1`. + +3. Use the `My.Computer.Ports.OpenSerialPort` method to obtain a reference to the port. For more information, see . + + The `Try...Catch...Finally` block allows the application to close the serial port even if it generates an exception. All code that manipulates the serial port should appear within this block. + + [!code-vb[VbVbalrMyComputer#39](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#39)] + +4. Create a `Do` loop for reading lines of text until no more lines are available. + + [!code-vb[VbVbalrMyComputer#40](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#40)] + +5. Use the method to read the next available line of text from the serial port. + + [!code-vb[VbVbalrMyComputer#41](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#41)] + +6. Use an `If` statement to determine if the method returns `Nothing` (which means no more text is available). If it does return `Nothing`, exit the `Do` loop. + + [!code-vb[VbVbalrMyComputer#42](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#42)] + +7. Add an `Else` block to the `If` statement to handle the case if the string is actually read. The block appends the string from the serial port to the return string. + + [!code-vb[VbVbalrMyComputer#43](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#43)] + +8. Return the string. + + [!code-vb[VbVbalrMyComputer#44](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#44)] + +## Example + + [!code-vb[VbVbalrMyComputer#37](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#37)] + + This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Connectivity and Networking**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). + +## Compiling the Code + + This example assumes the computer is using `COM1`. + +## Robust Programming + + This example assumes the computer is using `COM1`. For more flexibility, the code should allow the user to select the desired serial port from a list of available ports. For more information, see [How to: Show Available Serial Ports](how-to-show-available-serial-ports.md). + + This example uses a `Try...Catch...Finally` block to make sure that the application closes the port and to catch any timeout exceptions. For more information, see [Try...Catch...Finally Statement](../../../language-reference/statements/try-catch-finally-statement.md). + ## See also - diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-send-strings-to-serial-ports.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-send-strings-to-serial-ports.md index 22b533e9836ed..fe581f74f9bc8 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-send-strings-to-serial-ports.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-send-strings-to-serial-ports.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Send Strings to Serial Ports in Visual Basic" title: "How to: Send Strings to Serial Ports" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "ports, sending strings to" - "strings [Visual Basic], sending to serial ports" - "My.Computer.Ports object" @@ -11,30 +11,30 @@ ms.assetid: 6ebf46cd-b2d0-4b2c-9a1f-be177b22ad52 --- # How to: Send Strings to Serial Ports in Visual Basic -This topic describes how to use `My.Computer.Ports` to send strings to the computer's serial ports in Visual Basic. - -## Example - - This example sends a string to the COM1 serial port. You may need to use a different serial port on your computer. - - Use the `My.Computer.Ports.OpenSerialPort` method to obtain a reference to the port. For more information, see . - - The `Using` block allows the application to close the serial port even if it generates an exception. All code that manipulates the serial port should appear within this block or within a `Try...Catch...Finally` block. - - The method sends the data to the serial port. - - [!code-vb[VbVbalrMyComputer#33](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#33)] - -## Compiling the Code - -- This example assumes the computer is using `COM1`. - -## Robust Programming - - This example assumes the computer is using `COM1`; for more flexibility, the code should allow the user to select the desired serial port from a list of available ports. For more information, see [How to: Show Available Serial Ports](how-to-show-available-serial-ports.md). - - This example uses a `Using` block to make sure that the application closes the port even if it throws an exception. For more information, see [Using Statement](../../../language-reference/statements/using-statement.md). - +This topic describes how to use `My.Computer.Ports` to send strings to the computer's serial ports in Visual Basic. + +## Example + + This example sends a string to the COM1 serial port. You may need to use a different serial port on your computer. + + Use the `My.Computer.Ports.OpenSerialPort` method to obtain a reference to the port. For more information, see . + + The `Using` block allows the application to close the serial port even if it generates an exception. All code that manipulates the serial port should appear within this block or within a `Try...Catch...Finally` block. + + The method sends the data to the serial port. + + [!code-vb[VbVbalrMyComputer#33](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class2.vb#33)] + +## Compiling the Code + +- This example assumes the computer is using `COM1`. + +## Robust Programming + + This example assumes the computer is using `COM1`; for more flexibility, the code should allow the user to select the desired serial port from a list of available ports. For more information, see [How to: Show Available Serial Ports](how-to-show-available-serial-ports.md). + + This example uses a `Using` block to make sure that the application closes the port even if it throws an exception. For more information, see [Using Statement](../../../language-reference/statements/using-statement.md). + ## See also - diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-start-an-application-and-send-it-keystrokes.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-start-an-application-and-send-it-keystrokes.md index 9f987675aa015..ecc4ff10629ae 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-start-an-application-and-send-it-keystrokes.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-start-an-application-and-send-it-keystrokes.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: start an application and send it keystrokes (Visual Basic)" title: "How to: start an Application and send it Keystrokes - Visual Basic" ms.date: 10/23/2019 -helpviewer_keywords: +helpviewer_keywords: - "keystrokes, sending" - "Shell command example [Visual Basic]" - "processes, starting and sending keystrokes" @@ -11,7 +11,7 @@ ms.assetid: f1303184-fce4-44fb-88b4-aac5f42d5d77 --- # How to: start an application and send it keystrokes (Visual Basic) -This example uses the method to start the Notepad application and then prints a sentence by sending keystrokes using the [My.Computer.Keyboard.SendKeys](xref:Microsoft.VisualBasic.Devices.Keyboard.SendKeys%2A) method. +This example uses the method to start the Notepad application and then prints a sentence by sending keystrokes using the [My.Computer.Keyboard.SendKeys](xref:Microsoft.VisualBasic.Devices.Keyboard.SendKeys%2A) method. ## Example @@ -19,14 +19,14 @@ This example uses the method t ## Robust programming -An exception is raised if an application with the requested process identifier cannot be found. - +An exception is raised if an application with the requested process identifier cannot be found. + ## .NET Framework Security The call to the `Shell` function requires full trust ( class). ## See also -- -- -- +- +- +- diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-upload-a-file.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-upload-a-file.md index 099fa12771990..a7cdb4cea4250 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-upload-a-file.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-upload-a-file.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Upload a File in Visual Basic" title: "How to: Upload a File" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "networks, uploading files" - "files [Visual Basic], uploading" - "uploading files [Visual Basic]" @@ -12,39 +12,39 @@ ms.assetid: a8b37924-c523-4fd3-b5ca-cb0074df29cd --- # How to: Upload a File in Visual Basic -The method can be used to upload a file and store it to a remote location. If the `ShowUI` parameter is set to `True`, a dialog box is displayed that shows the progress of the upload and allows users to cancel the operation. - -### To upload a file - -- Use the `UploadFile` method to upload a file, specifying the source file's location and the target directory location as a string or URI (Uniform Resource Identifier).This example uploads the file `Order.txt` to `http://www.cohowinery.com/uploads.aspx`. - - [!code-vb[VbResourceTasks#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#6)] - -### To upload a file and show the progress of the operation - -- Use the `UploadFile` method to upload a file, specifying the source file's location and the target directory location as a string or URI. This example uploads the file `Order.txt` to `http://www.cohowinery.com/uploads.aspx` without supplying a user name or password, shows the progress of the upload, and has a time-out interval of 500 milliseconds. - - [!code-vb[VbResourceTasks#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#7)] - -### To upload a file, supplying a user name and password - -- Use the `UploadFile` method to upload a file, specifying the source file's location and the target directory location as a string or URI, and specifying the user name and the password. This example uploads the file `Order.txt` to `http://www.cohowinery.com/uploads.aspx`, supplying the user name `anonymous` and a blank password. - - [!code-vb[VbResourceTasks#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#8)] - -## Robust Programming - - The following conditions may throw an exception: - -- The local file path is not valid (). - -- Authentication failed (). - -- The connection timed out (). - +The method can be used to upload a file and store it to a remote location. If the `ShowUI` parameter is set to `True`, a dialog box is displayed that shows the progress of the upload and allows users to cancel the operation. + +### To upload a file + +- Use the `UploadFile` method to upload a file, specifying the source file's location and the target directory location as a string or URI (Uniform Resource Identifier).This example uploads the file `Order.txt` to `http://www.cohowinery.com/uploads.aspx`. + + [!code-vb[VbResourceTasks#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#6)] + +### To upload a file and show the progress of the operation + +- Use the `UploadFile` method to upload a file, specifying the source file's location and the target directory location as a string or URI. This example uploads the file `Order.txt` to `http://www.cohowinery.com/uploads.aspx` without supplying a user name or password, shows the progress of the upload, and has a time-out interval of 500 milliseconds. + + [!code-vb[VbResourceTasks#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#7)] + +### To upload a file, supplying a user name and password + +- Use the `UploadFile` method to upload a file, specifying the source file's location and the target directory location as a string or URI, and specifying the user name and the password. This example uploads the file `Order.txt` to `http://www.cohowinery.com/uploads.aspx`, supplying the user name `anonymous` and a blank password. + + [!code-vb[VbResourceTasks#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#8)] + +## Robust Programming + + The following conditions may throw an exception: + +- The local file path is not valid (). + +- Authentication failed (). + +- The connection timed out (). + ## See also - -- +- - [How to: Download a File](how-to-download-a-file.md) - [How to: Parse File Paths](../drives-directories-files/how-to-parse-file-paths.md) diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/index.md b/docs/visual-basic/developing-apps/programming/computer-resources/index.md index dfec6168a74fe..e4545231e16f1 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/index.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/index.md @@ -17,7 +17,7 @@ The `My.Computer` object is one of the three central objects in `My`, providing - Clipboard () - - -- +- - - - @@ -26,26 +26,26 @@ The `My.Computer` object is one of the three central objects in `My`, providing ## In this section -[Playing Sounds](playing-sounds.md) +[Playing Sounds](playing-sounds.md) Lists tasks associated with `My.Computer.Audio`, such as playing a sound in the background. -[Storing Data to and Reading from the Clipboard](storing-data-to-and-reading-from-the-clipboard.md) +[Storing Data to and Reading from the Clipboard](storing-data-to-and-reading-from-the-clipboard.md) Lists tasks associated with `My.Computer.Clipboard`, such as reading data from or writing data to the Clipboard. -[Getting Information about the Computer](getting-information-about-the-computer.md) +[Getting Information about the Computer](getting-information-about-the-computer.md) Lists tasks associated with `My.Computer.Info`, such as determining a computer's full name or IP addresses. -[Accessing the Keyboard](accessing-the-keyboard.md) +[Accessing the Keyboard](accessing-the-keyboard.md) Lists tasks associated with `My.Computer.Keyboard`, such as determining whether CAPS LOCK is on. -[Accessing the Mouse](accessing-the-mouse.md) +[Accessing the Mouse](accessing-the-mouse.md) Lists tasks associated with `My.Computer.Mouse`, such as determining whether a mouse is present. -[Performing Network Operations](performing-network-operations.md) +[Performing Network Operations](performing-network-operations.md) Lists tasks associated with `My.Computer.Network`, such as uploading or downloading files. -[Accessing the Computer's Ports](accessing-the-computer-s-ports.md) +[Accessing the Computer's Ports](accessing-the-computer-s-ports.md) Lists tasks associated with `My.Computer.Ports`, such as showing available serial ports or sending strings to serial ports. -[Reading from and Writing to the Registry](reading-from-and-writing-to-the-registry.md) +[Reading from and Writing to the Registry](reading-from-and-writing-to-the-registry.md) Lists tasks associated with `My.Computer.Registry`, such as reading data from or writing data to registry keys. diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/performing-network-operations.md b/docs/visual-basic/developing-apps/programming/computer-resources/performing-network-operations.md index c828965aff801..dee44a07243e3 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/performing-network-operations.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/performing-network-operations.md @@ -2,39 +2,39 @@ description: "Learn more about: Performing Network Operations (Visual Basic)" title: "Performing Network Operations" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "network operations, performing" - "My.Computer.Network object, tasks" ms.assetid: 8ecc47ce-7730-49cd-b21d-3a13477eec6b --- # Performing Network Operations (Visual Basic) -The following tables list tasks associated with the `My.Computer.Network` object. - -## In This Section - - [How to: Upload a File](how-to-upload-a-file.md) - Demonstrates how to upload a file and store it to a remote location using `My.Computer.Network`. - - [How to: Download a File](how-to-download-a-file.md) - Demonstrates how to download a file from a remote location using `My.Computer.Network`. - - [How to: Check Connection Status](how-to-check-connection-status.md) - Shows how to determine whether the computer has a working network connection. - -## Reference - - - Lists methods, properties, and events for working with the network. - - - Describes the `DownloadFile` method. - - - Describes the `Ping` method. - - - Describes the `UploadFile` method. - - +The following tables list tasks associated with the `My.Computer.Network` object. + +## In This Section + + [How to: Upload a File](how-to-upload-a-file.md) + Demonstrates how to upload a file and store it to a remote location using `My.Computer.Network`. + + [How to: Download a File](how-to-download-a-file.md) + Demonstrates how to download a file from a remote location using `My.Computer.Network`. + + [How to: Check Connection Status](how-to-check-connection-status.md) + Shows how to determine whether the computer has a working network connection. + +## Reference + + + Lists methods, properties, and events for working with the network. + + + Describes the `DownloadFile` method. + + + Describes the `Ping` method. + + + Describes the `UploadFile` method. + + Describes the `IsAvailable` property. diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/playing-sounds.md b/docs/visual-basic/developing-apps/programming/computer-resources/playing-sounds.md index bf1fe9ba131a3..fd275056398df 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/playing-sounds.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/playing-sounds.md @@ -2,7 +2,7 @@ description: "Learn more about: Playing Sounds (Visual Basic)" title: "Playing Sounds" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "system sounds, playing" - "system sounds" - "playing sounds, Visual Basic" @@ -15,60 +15,60 @@ ms.assetid: f0d9e4ab-57c7-47b6-86d3-99ff07078040 --- # Playing Sounds (Visual Basic) -The `My.Computer.Audio` object provides methods for playing sounds. - -## Playing Sounds - - Background playing lets the application execute other code while the sound plays. The `My.Computer.Audio.Play` method allows the application to play only one background sound at a time; when the application plays a new background sound, it stops playing the previous background sound. You can also play a sound and wait for it to complete. - - In the following example, the `My.Computer.Audio.Play` method plays a sound. When `AudioPlayMode.WaitToComplete` is specified, `My.Computer.Audio.Play` waits until the sound completes before calling code continues. When using this example, you should ensure that the file name refers to a .wav sound file that is on your computer - - [!code-vb[VbVbalrMyComputer#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class1.vb#15)] - - In the following example, the `My.Computer.Audio.Play` method plays a sound. When using this example, you should ensure that the application resources include a .wav sound file that is named Waterfall. - - [!code-vb[VbVbalrMyComputer#16](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class1.vb#16)] - -## Playing Looping Sounds - - In the following example, the `My.Computer.Audio.Play` method plays the specified sound in the background when `PlayMode.BackgroundLoop` is specified. When using this example, you should ensure that the file name refers to a .wav sound file that is on your computer. - - [!code-vb[VbVbalrMyComputer#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class1.vb#11)] - - In the following example, the `My.Computer.Audio.Play` method plays the specified sound in the background when `PlayMode.BackgroundLoop` is specified. When using this example, you should ensure that the application resources include a .wav sound file that is named Waterfall. - - [!code-vb[VbVbalrMyComputer#12](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class1.vb#12)] - - The preceding code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Windows Forms Applications > Sound**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). - - In general, when an application plays a looping sound, it should eventually stop the sound. - -## Stopping the Playing of Sounds in the Background - - Use the `My.Computer.Audio.Stop` method to stop the application's currently playing background or looping sound. - - In general, when an application plays a looping sound, it should stop the sound at some point. - - The following example stops a sound that is playing in the background. - - [!code-vb[VbVbalrMyComputer#18](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class1.vb#18)] - - The preceding code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Windows Forms Applications > Sound**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). - -## Playing System Sounds - - Use the `My.Computer.Audio.PlaySystemSound` method to play the specified system sound. - - The `My.Computer.Audio.PlaySystemSound` method takes as a parameter one of the shared members from the class. The system sound generally denotes errors. - - The following example uses the `My.Computer.Audio.PlaySystemSound` method to play a system sound. - - [!code-vb[VbVbalrMyComputer#17](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class1.vb#17)] - +The `My.Computer.Audio` object provides methods for playing sounds. + +## Playing Sounds + + Background playing lets the application execute other code while the sound plays. The `My.Computer.Audio.Play` method allows the application to play only one background sound at a time; when the application plays a new background sound, it stops playing the previous background sound. You can also play a sound and wait for it to complete. + + In the following example, the `My.Computer.Audio.Play` method plays a sound. When `AudioPlayMode.WaitToComplete` is specified, `My.Computer.Audio.Play` waits until the sound completes before calling code continues. When using this example, you should ensure that the file name refers to a .wav sound file that is on your computer + + [!code-vb[VbVbalrMyComputer#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class1.vb#15)] + + In the following example, the `My.Computer.Audio.Play` method plays a sound. When using this example, you should ensure that the application resources include a .wav sound file that is named Waterfall. + + [!code-vb[VbVbalrMyComputer#16](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class1.vb#16)] + +## Playing Looping Sounds + + In the following example, the `My.Computer.Audio.Play` method plays the specified sound in the background when `PlayMode.BackgroundLoop` is specified. When using this example, you should ensure that the file name refers to a .wav sound file that is on your computer. + + [!code-vb[VbVbalrMyComputer#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class1.vb#11)] + + In the following example, the `My.Computer.Audio.Play` method plays the specified sound in the background when `PlayMode.BackgroundLoop` is specified. When using this example, you should ensure that the application resources include a .wav sound file that is named Waterfall. + + [!code-vb[VbVbalrMyComputer#12](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class1.vb#12)] + + The preceding code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Windows Forms Applications > Sound**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). + + In general, when an application plays a looping sound, it should eventually stop the sound. + +## Stopping the Playing of Sounds in the Background + + Use the `My.Computer.Audio.Stop` method to stop the application's currently playing background or looping sound. + + In general, when an application plays a looping sound, it should stop the sound at some point. + + The following example stops a sound that is playing in the background. + + [!code-vb[VbVbalrMyComputer#18](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class1.vb#18)] + + The preceding code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Windows Forms Applications > Sound**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). + +## Playing System Sounds + + Use the `My.Computer.Audio.PlaySystemSound` method to play the specified system sound. + + The `My.Computer.Audio.PlaySystemSound` method takes as a parameter one of the shared members from the class. The system sound generally denotes errors. + + The following example uses the `My.Computer.Audio.PlaySystemSound` method to play a system sound. + + [!code-vb[VbVbalrMyComputer#17](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyComputer/VB/Class1.vb#17)] + ## See also - -- -- -- +- +- +- - diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/port-operations-in-the-net-framework.md b/docs/visual-basic/developing-apps/programming/computer-resources/port-operations-in-the-net-framework.md index 02474dd747a48..147d638a93522 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/port-operations-in-the-net-framework.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/port-operations-in-the-net-framework.md @@ -10,7 +10,7 @@ ms.assetid: 1eba223b-7bd3-401a-b097-982bce96df1b You can access your computer's serial ports through the .NET Framework classes in the namespace. The most important class, , provides a framework for synchronous and event-driven I/O, access to pin and break states, and access to serial driver properties. It can be wrapped in a object, accessible through the property. Wrapping in a object allows the serial port to be accessed by classes that use streams. The namespace includes enumerations that simplify the control of serial ports. -The simplest way to create a object is through the method. +The simplest way to create a object is through the method. > [!NOTE] > You cannot use .NET Framework classes to directly access other types of ports, such as parallel ports, USB ports, and so on. diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/reading-from-and-writing-to-the-registry-using-the-microsoft-win32-namespace.md b/docs/visual-basic/developing-apps/programming/computer-resources/reading-from-and-writing-to-the-registry-using-the-microsoft-win32-namespace.md index 59481fef9111c..b97391e083deb 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/reading-from-and-writing-to-the-registry-using-the-microsoft-win32-namespace.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/reading-from-and-writing-to-the-registry-using-the-microsoft-win32-namespace.md @@ -2,41 +2,41 @@ description: "Learn more about: Reading from and Writing to the Registry Using the Microsoft.Win32 Namespace (Visual Basic)" title: "Reading from and Writing to the Registry Using the Microsoft.Win32 Namespace" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "registry [Visual Basic]" ms.assetid: 4a0dcce0-c27b-4199-baa8-ee4528da6a56 --- # Reading from and Writing to the Registry Using the Microsoft.Win32 Namespace (Visual Basic) Although `My.Computer.Registry` should cover your basic needs when programming against the registry, you can also use the and classes in the namespace of .NET. - -## Keys in the Registry Class - - The class supplies the base registry keys that can be used to access subkeys and their values. The base keys themselves are read-only. The following table lists and describes the seven keys exposed by the class. - -|**Key**|**Description**| -|-------------|---------------------| -||Defines the types of documents and the properties associated with those types.| -||Contains hardware configuration information that is not user-specific.| -||Contains information about the current user preferences, such as environmental variables.| -||Contains dynamic registry data, such as that used by Virtual Device Drivers.| -||Contains five subkeys (Hardware, SAM, Security, Software, and System) that hold the configuration data for the local computer.| -||Contains performance information for software components.| -||Contains information about the default user preferences.| - + +## Keys in the Registry Class + + The class supplies the base registry keys that can be used to access subkeys and their values. The base keys themselves are read-only. The following table lists and describes the seven keys exposed by the class. + +|**Key**|**Description**| +|-------------|---------------------| +||Defines the types of documents and the properties associated with those types.| +||Contains hardware configuration information that is not user-specific.| +||Contains information about the current user preferences, such as environmental variables.| +||Contains dynamic registry data, such as that used by Virtual Device Drivers.| +||Contains five subkeys (Hardware, SAM, Security, Software, and System) that hold the configuration data for the local computer.| +||Contains performance information for software components.| +||Contains information about the default user preferences.| + > [!IMPORTANT] -> It is more secure to write data to the current user () than to the local computer (). A condition that's typically referred to as "squatting" occurs when the key you are creating was previously created by another, possibly malicious, process. To prevent this from occurring, use a method, such as , that returns `Nothing` if the key does not already exist. - -## Reading a Value from the Registry - - The following code shows how to read a string from HKEY_CURRENT_USER. - - [!code-vb[VbResourceTasks#20](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#20)] - - The following code reads, increments, and then writes a string to HKEY_CURRENT_USER. - - [!code-vb[VbResourceTasks#21](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#21)] - +> It is more secure to write data to the current user () than to the local computer (). A condition that's typically referred to as "squatting" occurs when the key you are creating was previously created by another, possibly malicious, process. To prevent this from occurring, use a method, such as , that returns `Nothing` if the key does not already exist. + +## Reading a Value from the Registry + + The following code shows how to read a string from HKEY_CURRENT_USER. + + [!code-vb[VbResourceTasks#20](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#20)] + + The following code reads, increments, and then writes a string to HKEY_CURRENT_USER. + + [!code-vb[VbResourceTasks#21](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#21)] + ## See also - diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/storing-data-to-and-reading-from-the-clipboard.md b/docs/visual-basic/developing-apps/programming/computer-resources/storing-data-to-and-reading-from-the-clipboard.md index 4e90f8b437628..c54b77d68a392 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/storing-data-to-and-reading-from-the-clipboard.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/storing-data-to-and-reading-from-the-clipboard.md @@ -2,7 +2,7 @@ description: "Learn more about: Storing data to and reading from the Clipboard (Visual Basic)" title: "Storing data to and reading from the Clipboard" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "Clipboard, storing data to (My.Computer.Clipboard)" - "Clipboard, reading from (My.Computer.Clipboard)" - "Clipboard" @@ -13,65 +13,65 @@ ms.assetid: f690119a-4378-4f7d-b20e-d9377ef49496 --- # Storing data to and reading from the Clipboard (Visual Basic) -The Clipboard can be used to store data, such as text and images. Because the Clipboard is shared by all active processes, it can be used to transfer data between them. The `My.Computer.Clipboard` object allows you to easily access the Clipboard and to read from and write to it. - -## Reading from the Clipboard - - Use the method to read the text in the Clipboard. The following code reads the text and displays it in a message box. There must be text stored on the Clipboard for the example to run correctly. - - [!code-vb[VbVbcnMyClipboard#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyClipboard/VB/Class1.vb#4)] - - This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Windows Forms Applications > Clipboard**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). - - Use the method to retrieve an image from the Clipboard. This example checks to see if there is an image on the Clipboard before retrieving it and assigning it to `PictureBox1`. - - [!code-vb[VbResourceTasks#16](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#16)] - - This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Windows Forms Applications > Clipboard**.For more information, see [Code Snippets](/visualstudio/ide/code-snippets). - - Items placed on the Clipboard will persist even after the application is shut down. - -## Determining the type of file stored in the Clipboard - - Data on the Clipboard may take a number of different forms, such as text, an audio file, or an image. In order to determine what sort of file is on the Clipboard, you can use methods such as , , , and . The method can be used if you have a custom format that you want to check. - - Use the `ContainsImage` function to determine whether the data contained on the Clipboard is an image. The following code checks to see whether the data is an image and reports accordingly. - - [!code-vb[VbResourceTasks#13](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#13)] - -## Clearing the Clipboard - - The method clears the Clipboard. Because the Clipboard is shared by other processes, clearing it may have an impact on those processes. - - The following code shows how to use the `Clear` method. - - [!code-vb[VbVbcnMyClipboard#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyClipboard/VB/Class1.vb#3)] - -## Writing to the Clipboard - - Use the method to write text to the Clipboard. The following code writes the string "This is a test string" to the Clipboard. - - [!code-vb[VbVbcnMyClipboard#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyClipboard/VB/Class1.vb#1)] - - The `SetText` method can accept a format parameter that contains a type of . The following code writes the string "This is a test string" to the Clipboard as RTF text. - - [!code-vb[VbVbcnMyClipboard#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyClipboard/VB/Class1.vb#2)] - - Use the method to write data to the Clipboard. This example writes the `DataObject` `dataChunk` to the Clipboard in the custom format `specialFormat`. - - [!code-vb[VbVbcnMyClipboard#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyClipboard/VB/Class1.vb#7)] - - Use the method to write audio data to the Clipboard. This example creates the byte array `musicReader`, reads the file `cool.wav` into it, and then writes it to the Clipboard. - - [!code-vb[VbResourceTasks#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#5)] - +The Clipboard can be used to store data, such as text and images. Because the Clipboard is shared by all active processes, it can be used to transfer data between them. The `My.Computer.Clipboard` object allows you to easily access the Clipboard and to read from and write to it. + +## Reading from the Clipboard + + Use the method to read the text in the Clipboard. The following code reads the text and displays it in a message box. There must be text stored on the Clipboard for the example to run correctly. + + [!code-vb[VbVbcnMyClipboard#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyClipboard/VB/Class1.vb#4)] + + This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Windows Forms Applications > Clipboard**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). + + Use the method to retrieve an image from the Clipboard. This example checks to see if there is an image on the Clipboard before retrieving it and assigning it to `PictureBox1`. + + [!code-vb[VbResourceTasks#16](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#16)] + + This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Windows Forms Applications > Clipboard**.For more information, see [Code Snippets](/visualstudio/ide/code-snippets). + + Items placed on the Clipboard will persist even after the application is shut down. + +## Determining the type of file stored in the Clipboard + + Data on the Clipboard may take a number of different forms, such as text, an audio file, or an image. In order to determine what sort of file is on the Clipboard, you can use methods such as , , , and . The method can be used if you have a custom format that you want to check. + + Use the `ContainsImage` function to determine whether the data contained on the Clipboard is an image. The following code checks to see whether the data is an image and reports accordingly. + + [!code-vb[VbResourceTasks#13](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#13)] + +## Clearing the Clipboard + + The method clears the Clipboard. Because the Clipboard is shared by other processes, clearing it may have an impact on those processes. + + The following code shows how to use the `Clear` method. + + [!code-vb[VbVbcnMyClipboard#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyClipboard/VB/Class1.vb#3)] + +## Writing to the Clipboard + + Use the method to write text to the Clipboard. The following code writes the string "This is a test string" to the Clipboard. + + [!code-vb[VbVbcnMyClipboard#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyClipboard/VB/Class1.vb#1)] + + The `SetText` method can accept a format parameter that contains a type of . The following code writes the string "This is a test string" to the Clipboard as RTF text. + + [!code-vb[VbVbcnMyClipboard#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyClipboard/VB/Class1.vb#2)] + + Use the method to write data to the Clipboard. This example writes the `DataObject` `dataChunk` to the Clipboard in the custom format `specialFormat`. + + [!code-vb[VbVbcnMyClipboard#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyClipboard/VB/Class1.vb#7)] + + Use the method to write audio data to the Clipboard. This example creates the byte array `musicReader`, reads the file `cool.wav` into it, and then writes it to the Clipboard. + + [!code-vb[VbResourceTasks#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbResourceTasks/VB/Class1.vb#5)] + > [!IMPORTANT] -> Because the Clipboard can be accessed by other users, do not use it to store sensitive information, such as passwords or confidential data. - +> Because the Clipboard can be accessed by other users, do not use it to store sensitive information, such as passwords or confidential data. + ## See also - -- -- +- +- - [How to: Read Object Data from an XML File](../../../programming-guide/concepts/serialization/how-to-read-object-data-from-an-xml-file.md) - [How to: Write Object Data to an XML File](../../../programming-guide/concepts/serialization/how-to-write-object-data-to-an-xml-file.md) 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 090f8a47ad0b9..fb20f9d3fcf6d 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 @@ -26,7 +26,7 @@ The following tables list the classes commonly used for .NET Framework file I/O, ||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.| +||Controls the access of files and folders by defining , , and permissions.| ## Classes Used to Create Streams @@ -35,7 +35,7 @@ The following tables list the classes commonly used for .NET Framework file I/O, |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.| +||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.| @@ -48,8 +48,8 @@ The following tables list the classes commonly used for .NET Framework file I/O, |---------------|---------------------| ||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 , 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`.| diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/creating-deleting-and-moving-files-and-directories.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/creating-deleting-and-moving-files-and-directories.md index d269dd3e53984..099b27feb3ed2 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/creating-deleting-and-moving-files-and-directories.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/creating-deleting-and-moving-files-and-directories.md @@ -2,7 +2,7 @@ description: "Learn more about: Creating, Deleting, and Moving Files and Directories in Visual Basic" title: "Creating, Deleting, and Moving Files and Directories" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "examples [Visual Basic], moving files and directories" - "I/O [Visual Basic], deleting folders" - "I/O [Visual Basic], moving directories" @@ -26,97 +26,97 @@ ms.assetid: 8f814fcc-4c42-4dbb-a131-005ec445ac9e --- # Creating, Deleting, and Moving Files and Directories in Visual Basic -This section lists tasks associated with creating, deleting, moving, and renaming files and directories in Visual Basic. - -## In This Section - - [How to: Copy Files with a Specific Pattern to a Directory](how-to-copy-files-with-a-specific-pattern-to-a-directory.md) - Demonstrates how to copy files with a specific file name pattern, such as only .txt files, to a directory. - - [How to: Create a Copy of a File in the Same Directory](how-to-create-a-copy-of-a-file-in-the-same-directory.md) - Demonstrates how to create a copy of a file in the same directory. - - [How to: Create a Copy of a File in a Different Directory](how-to-create-a-copy-of-a-file-in-a-different-directory.md) - Demonstrates how to copy a file to another directory. - - [How to: Create a File](how-to-create-a-file.md) - Demonstrates how to create a file. - - [How to: Delete a File](how-to-delete-a-file.md) - Demonstrates how to delete a file. - - [How to: Find Files with a Specific Pattern](how-to-find-files-with-a-specific-pattern.md) - Demonstrates how to list only files with a specific file name pattern in a directory. - - [How to: Move a File](how-to-move-a-file.md) - Demonstrates how to move a file to a different directory. - - [How to: Rename a File](how-to-rename-a-file.md) - Demonstrates how to rename a file. - - [How to: Copy a Directory to Another Directory](how-to-copy-a-directory-to-another-directory.md) - Demonstrates how to copy a directory to another location. - - [How to: Create a Directory](how-to-create-a-directory.md) - Demonstrates how to create a directory. - - [How to: Find Subdirectories with a Specific Pattern](how-to-find-subdirectories-with-a-specific-pattern.md) - Demonstrates how to list directories with a specific pattern in their name. - - [How to: Get the Collection of Files in a Directory](how-to-get-the-collection-of-files-in-a-directory.md) - Demonstrates how to list the files in a directory. - - [How to: Retrieve the Contents of the My Documents Directory](how-to-retrieve-the-contents-of-the-my-documents-directory.md) - Demonstrates how to read from special directories. - - [How to: Parse File Paths](how-to-parse-file-paths.md) - Demonstrates how to use `My` methods to combine file paths. - -## Reference - - - Describes the `My.Computer.FileSystem` object and its members. - - - Describes the `CombinePath` method. - - - Describes the `CopyDirectory` method. - - - Describes the `CopyFile` method. - - - Describes the `CreateDirectory` method. - - - Describes the `DeleteDirectory` method. - - - Describes the `DeleteFile` method. - - - Describes the `GetParentPath` method. - - - Describes the `MoveDirectory` method. - - - Describes the `MoveFile` method. - - - Describes the `RenameDirectory` method. - - - Describes the `RenameFile` method. - - - Describes the `SpecialDirectories` object. - -## Related Sections - - [Reading from Files](reading-from-files.md) - Lists tasks associated with reading from files. - - [Writing to Files](writing-to-files.md) +This section lists tasks associated with creating, deleting, moving, and renaming files and directories in Visual Basic. + +## In This Section + + [How to: Copy Files with a Specific Pattern to a Directory](how-to-copy-files-with-a-specific-pattern-to-a-directory.md) + Demonstrates how to copy files with a specific file name pattern, such as only .txt files, to a directory. + + [How to: Create a Copy of a File in the Same Directory](how-to-create-a-copy-of-a-file-in-the-same-directory.md) + Demonstrates how to create a copy of a file in the same directory. + + [How to: Create a Copy of a File in a Different Directory](how-to-create-a-copy-of-a-file-in-a-different-directory.md) + Demonstrates how to copy a file to another directory. + + [How to: Create a File](how-to-create-a-file.md) + Demonstrates how to create a file. + + [How to: Delete a File](how-to-delete-a-file.md) + Demonstrates how to delete a file. + + [How to: Find Files with a Specific Pattern](how-to-find-files-with-a-specific-pattern.md) + Demonstrates how to list only files with a specific file name pattern in a directory. + + [How to: Move a File](how-to-move-a-file.md) + Demonstrates how to move a file to a different directory. + + [How to: Rename a File](how-to-rename-a-file.md) + Demonstrates how to rename a file. + + [How to: Copy a Directory to Another Directory](how-to-copy-a-directory-to-another-directory.md) + Demonstrates how to copy a directory to another location. + + [How to: Create a Directory](how-to-create-a-directory.md) + Demonstrates how to create a directory. + + [How to: Find Subdirectories with a Specific Pattern](how-to-find-subdirectories-with-a-specific-pattern.md) + Demonstrates how to list directories with a specific pattern in their name. + + [How to: Get the Collection of Files in a Directory](how-to-get-the-collection-of-files-in-a-directory.md) + Demonstrates how to list the files in a directory. + + [How to: Retrieve the Contents of the My Documents Directory](how-to-retrieve-the-contents-of-the-my-documents-directory.md) + Demonstrates how to read from special directories. + + [How to: Parse File Paths](how-to-parse-file-paths.md) + Demonstrates how to use `My` methods to combine file paths. + +## Reference + + + Describes the `My.Computer.FileSystem` object and its members. + + + Describes the `CombinePath` method. + + + Describes the `CopyDirectory` method. + + + Describes the `CopyFile` method. + + + Describes the `CreateDirectory` method. + + + Describes the `DeleteDirectory` method. + + + Describes the `DeleteFile` method. + + + Describes the `GetParentPath` method. + + + Describes the `MoveDirectory` method. + + + Describes the `MoveFile` method. + + + Describes the `RenameDirectory` method. + + + Describes the `RenameFile` method. + + + Describes the `SpecialDirectories` object. + +## Related Sections + + [Reading from Files](reading-from-files.md) + Lists tasks associated with reading from files. + + [Writing to Files](writing-to-files.md) Lists tasks involving writing to files. diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-append-to-text-files.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-append-to-text-files.md index 7df4e00f084c6..3196ba1c453f7 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-append-to-text-files.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-append-to-text-files.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Append to Text Files in Visual Basic" title: "How to: Append to Text Files" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "I/O [Visual Basic], appending to files" - "I/O [Visual Basic], My.Computer.FileSystem.WriteAllText method" - "I/O [Visual Basic], WriteAllText method" @@ -10,36 +10,36 @@ ms.assetid: bbbd7fb5-f169-41a9-b53f-520ea9613913 --- # How to: Append to Text Files in Visual Basic -The method can be used to append to a text file by specifying that the `append` parameter is set to `True`. - -### To append to a text file - -- Use the `WriteAllText` method, specifying the target file and string to be appended and setting the `append` parameter to `True`. - - This example writes the string `"This is a test string."` to the file named `Testfile.txt`. - - [!code-vb[VbFileIOWrite#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOWrite/VB/Class1.vb#6)] - -## Robust Programming - - The following conditions may cause an exception: - -- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). - -- The path is not valid because it is `Nothing` (). - -- `File` points to a path that does not exist ( or ). - -- The file is in use by another process, or an I/O error occurs (). - -- The path exceeds the system-defined maximum length (). - -- A file or directory name in the path contains a colon (:) or is in an invalid format (). - -- The user lacks necessary permissions to view the path (). - +The method can be used to append to a text file by specifying that the `append` parameter is set to `True`. + +### To append to a text file + +- Use the `WriteAllText` method, specifying the target file and string to be appended and setting the `append` parameter to `True`. + + This example writes the string `"This is a test string."` to the file named `Testfile.txt`. + + [!code-vb[VbFileIOWrite#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOWrite/VB/Class1.vb#6)] + +## Robust Programming + + The following conditions may cause an exception: + +- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). + +- The path is not valid because it is `Nothing` (). + +- `File` points to a path that does not exist ( or ). + +- The file is in use by another process, or an I/O error occurs (). + +- The path exceeds the system-defined maximum length (). + +- A file or directory name in the path contains a colon (:) or is in an invalid format (). + +- The user lacks necessary permissions to view the path (). + ## See also -- +- - - [Writing to Files](writing-to-files.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory.md index 09568413bae13..dd292f850e287 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-a-directory-to-another-directory.md @@ -11,7 +11,7 @@ ms.assetid: 2a370bd7-10ba-4219-afc4-4519d031eb6c --- # How to: Copy a Directory to Another Directory in Visual Basic -Use the method to copy a directory to another directory. This method copies the contents of the directory as well as the directory itself. If the target directory does not exist, it will be created. If a directory with the same name exists in the target location and `overwrite` is set to `False`, the contents of the two directories will be merged. You can specify a new name for the directory during the operation. +Use the method to copy a directory to another directory. This method copies the contents of the directory as well as the directory itself. If the target directory does not exist, it will be created. If a directory with the same name exists in the target location and `overwrite` is set to `False`, the contents of the two directories will be merged. You can specify a new name for the directory during the operation. When copying files within a directory, exceptions may be thrown that are caused by specific file, such as a file existing during a merge while `overwrite` is set to `False`. When such exceptions are thrown, they are consolidated into a single exception, whose `Data` property holds entries in which the file or directory path is the key and the specific exception message is contained in the corresponding value. @@ -59,6 +59,6 @@ The following conditions may cause an exception: ## See also -- +- - [How to: Find Subdirectories with a Specific Pattern](how-to-find-subdirectories-with-a-specific-pattern.md) - [How to: Get the Collection of Files in a Directory](how-to-get-the-collection-of-files-in-a-directory.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-files-with-a-specific-pattern-to-a-directory.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-files-with-a-specific-pattern-to-a-directory.md index bfed9a6bc9361..d8b6fca06f001 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-files-with-a-specific-pattern-to-a-directory.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-copy-files-with-a-specific-pattern-to-a-directory.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Copy Files with a Specific Pattern to a Directory in Visual Basic" title: "How to: Copy Files with a Specific Pattern to a Directory" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "My.Computer.FileSystem.CopyFile method, copying files [Visual Basic]" - "files [Visual Basic], copying" - "CopyFile method [Visual Basic], copying files in Visual Basic" @@ -11,54 +11,54 @@ ms.assetid: f205d2ad-bbe5-4d55-8a40-acda21aa82dd --- # How to: Copy Files with a Specific Pattern to a Directory in Visual Basic -The method returns a read-only collection of strings representing the path names for the files. You can use the `wildCards` parameter to specify a specific pattern. - - An empty collection is returned if no matching files are found. - - You can use the method to copy the files to a directory. - -### To copy files with a specific pattern to a directory - -1. Use the `GetFiles` method to return the list of files. This example returns all .rtf files in the specified directory. - - [!code-vb[VbFileIOMisc#36](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOMisc/VB/Class1.vb#36)] - -2. Use the `CopyFile` method to copy the files. This example copies the files to the directory named `testdirectory`. - - [!code-vb[VbVbcnMyFileSystem#88](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#88)] - -3. Close the `For` statement with a `Next` statement. - - [!code-vb[VbVbcnMyFileSystem#89](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#89)] - -## Example - - The following example, which presents the above snippets in complete form, copies all .rtf files in the specified directory to the directory named `testdirectory`. - - [!code-vb[VbFileIOMisc#37](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOMisc/VB/Class1.vb#37)] - -## .NET Framework Security - - The following conditions may cause an exception: - -- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). - -- The path is not valid because it is `Nothing` (). - -- The directory does not exist (). - -- The directory points to an existing file (). - -- The path exceeds the system-defined maximum length (). - -- A file or directory name in the path contains a colon (:) or is in an invalid format (). - -- The user lacks necessary permissions to view the path (). The user lacks necessary permissions (). - +The method returns a read-only collection of strings representing the path names for the files. You can use the `wildCards` parameter to specify a specific pattern. + + An empty collection is returned if no matching files are found. + + You can use the method to copy the files to a directory. + +### To copy files with a specific pattern to a directory + +1. Use the `GetFiles` method to return the list of files. This example returns all .rtf files in the specified directory. + + [!code-vb[VbFileIOMisc#36](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOMisc/VB/Class1.vb#36)] + +2. Use the `CopyFile` method to copy the files. This example copies the files to the directory named `testdirectory`. + + [!code-vb[VbVbcnMyFileSystem#88](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#88)] + +3. Close the `For` statement with a `Next` statement. + + [!code-vb[VbVbcnMyFileSystem#89](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#89)] + +## Example + + The following example, which presents the above snippets in complete form, copies all .rtf files in the specified directory to the directory named `testdirectory`. + + [!code-vb[VbFileIOMisc#37](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOMisc/VB/Class1.vb#37)] + +## .NET Framework Security + + The following conditions may cause an exception: + +- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). + +- The path is not valid because it is `Nothing` (). + +- The directory does not exist (). + +- The directory points to an existing file (). + +- The path exceeds the system-defined maximum length (). + +- A file or directory name in the path contains a colon (:) or is in an invalid format (). + +- The user lacks necessary permissions to view the path (). The user lacks necessary permissions (). + ## See also -- -- +- +- - [How to: Find Subdirectories with a Specific Pattern](how-to-find-subdirectories-with-a-specific-pattern.md) - [Troubleshooting: Reading from and Writing to Text Files](troubleshooting-reading-from-and-writing-to-text-files.md) - [How to: Get the Collection of Files in a Directory](how-to-get-the-collection-of-files-in-a-directory.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-copy-of-a-file-in-a-different-directory.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-copy-of-a-file-in-a-different-directory.md index b65576febfb96..6e08301d79245 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-copy-of-a-file-in-a-different-directory.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-copy-of-a-file-in-a-different-directory.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Create a Copy of a File in a Different Directory in Visual Basic" title: "How to: Create a Copy of a File in a Different Directory" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "My.Computer.FileSystem.CopyFile method, copying files [Visual Basic]" - "files [Visual Basic], copying" - "CopyFile method [Visual Basic], copying files in Visual Basic" @@ -11,50 +11,50 @@ ms.assetid: 88e2145c-d414-45a5-ad03-6f5d58ecca26 --- # How to: Create a Copy of a File in a Different Directory in Visual Basic -The `My.Computer.FileSystem.CopyFile` method allows you to copy files. Its parameters provide the ability to overwrite existing files, rename the file, show the progress of the operation, and allow the user to cancel the operation. - -### To copy a text file to another folder - -- Use the `CopyFile` method to copy a file, specifying a source file and the target directory. The `overwrite` parameter allows you to specify whether or not to overwrite existing files. The following code examples demonstrate how to use `CopyFile`. - - [!code-vb[VbFileIOMisc#24](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOMisc/VB/Class1.vb#24)] - -## Robust Programming - - The following conditions may cause an exception to be thrown: - -- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). - -- The system could not retrieve the absolute path (). - -- The path is not valid because it is `Nothing` (). - -- The source file is not valid or does not exist (). - -- The combined path points to an existing directory (). - -- The destination file exists and `overwrite` is set to `False` (). - -- The user does not have sufficient permissions to access the file (). - -- A file in the target folder with the same name is in use (). - -- A file or folder name in the path contains a colon (:) or is in an invalid format (). - -- `ShowUI` is set to `True`, `onUserCancel` is set to `ThrowException`, and the user has cancelled the operation (). - -- `ShowUI` is set to `True`, `onUserCancel` is set to `ThrowException`, and an unspecified I/O error occurs (). - -- The path exceeds the system-defined maximum length (). - -- The user does not have required permission (). - -- The user lacks necessary permissions to view the path (). - +The `My.Computer.FileSystem.CopyFile` method allows you to copy files. Its parameters provide the ability to overwrite existing files, rename the file, show the progress of the operation, and allow the user to cancel the operation. + +### To copy a text file to another folder + +- Use the `CopyFile` method to copy a file, specifying a source file and the target directory. The `overwrite` parameter allows you to specify whether or not to overwrite existing files. The following code examples demonstrate how to use `CopyFile`. + + [!code-vb[VbFileIOMisc#24](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOMisc/VB/Class1.vb#24)] + +## Robust Programming + + The following conditions may cause an exception to be thrown: + +- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). + +- The system could not retrieve the absolute path (). + +- The path is not valid because it is `Nothing` (). + +- The source file is not valid or does not exist (). + +- The combined path points to an existing directory (). + +- The destination file exists and `overwrite` is set to `False` (). + +- The user does not have sufficient permissions to access the file (). + +- A file in the target folder with the same name is in use (). + +- A file or folder name in the path contains a colon (:) or is in an invalid format (). + +- `ShowUI` is set to `True`, `onUserCancel` is set to `ThrowException`, and the user has cancelled the operation (). + +- `ShowUI` is set to `True`, `onUserCancel` is set to `ThrowException`, and an unspecified I/O error occurs (). + +- The path exceeds the system-defined maximum length (). + +- The user does not have required permission (). + +- The user lacks necessary permissions to view the path (). + ## See also - -- +- - - [How to: Copy Files with a Specific Pattern to a Directory](how-to-copy-files-with-a-specific-pattern-to-a-directory.md) - [How to: Create a Copy of a File in the Same Directory](how-to-create-a-copy-of-a-file-in-the-same-directory.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-copy-of-a-file-in-the-same-directory.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-copy-of-a-file-in-the-same-directory.md index 958ca9dac0fd1..26cac1e55469d 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-copy-of-a-file-in-the-same-directory.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-copy-of-a-file-in-the-same-directory.md @@ -2,9 +2,9 @@ description: "Learn more about: How to: Create a Copy of a File in the Same Directory in Visual Basic" title: "How to: Create a Copy of a File in the Same Directory" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "File.Copy" -helpviewer_keywords: +helpviewer_keywords: - "My.Computer.FileSystem.CopyFile method, copying files [Visual Basic]" - "files [Visual Basic], copying" - "CopyFile method [Visual Basic], copying files in Visual Basic" @@ -13,56 +13,56 @@ ms.assetid: b2fdda86-e666-42c2-9706-9527e9fa68ff --- # How to: Create a Copy of a File in the Same Directory in Visual Basic -Use the `My.Computer.FileSystem.CopyFile` method to copy files. The parameters allow you to overwrite existing files, rename the file, show the progress of the operation, and allow the user to cancel the operation. - -### To create a copy of a file in the same folder - -- Use the `CopyFile` method, supplying the target file and the location. The following example creates a copy of `test.txt` called `test2.txt`. - - [!code-vb[VbVbcnMyFileSystem#51](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#51)] - -### To create a copy of a file in the same folder, overwriting existing files - -- Use the `CopyFile` method, supplying the target file and location, and setting `overwrite` to `True`. The following example creates a copy of `test.txt` called `test2.txt` and overwrites any existing files by that name. - - [!code-vb[VbVbcnMyFileSystem#52](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#52)] - -## Robust Programming - - The following conditions may cause an exception to be thrown: - -- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). - -- The system could not retrieve the absolute path (). - -- The path is not valid because it is `Nothing` (). - -- The source file is not valid or does not exist (). - -- The combined path points to an existing directory (). - -- The destination file exists and `overwrite` is set to `False` (). - -- The user does not have sufficient permissions to access the file (). - -- A file in the target folder with the same name is in use (). - -- A file or folder name in the path contains a colon (:) or is in an invalid format (). - -- `ShowUI` is set to `True`, `onUserCancel` is set to `ThrowException`, and the user has cancelled the operation (). - -- `ShowUI` is set to `True`, `onUserCancel` is set to `ThrowException`, and an unspecified I/O error occurs (). - -- The path exceeds the system-defined maximum length (). - -- The user does not have required permission (). - -- The user lacks necessary permissions to view the path (). - +Use the `My.Computer.FileSystem.CopyFile` method to copy files. The parameters allow you to overwrite existing files, rename the file, show the progress of the operation, and allow the user to cancel the operation. + +### To create a copy of a file in the same folder + +- Use the `CopyFile` method, supplying the target file and the location. The following example creates a copy of `test.txt` called `test2.txt`. + + [!code-vb[VbVbcnMyFileSystem#51](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#51)] + +### To create a copy of a file in the same folder, overwriting existing files + +- Use the `CopyFile` method, supplying the target file and location, and setting `overwrite` to `True`. The following example creates a copy of `test.txt` called `test2.txt` and overwrites any existing files by that name. + + [!code-vb[VbVbcnMyFileSystem#52](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#52)] + +## Robust Programming + + The following conditions may cause an exception to be thrown: + +- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). + +- The system could not retrieve the absolute path (). + +- The path is not valid because it is `Nothing` (). + +- The source file is not valid or does not exist (). + +- The combined path points to an existing directory (). + +- The destination file exists and `overwrite` is set to `False` (). + +- The user does not have sufficient permissions to access the file (). + +- A file in the target folder with the same name is in use (). + +- A file or folder name in the path contains a colon (:) or is in an invalid format (). + +- `ShowUI` is set to `True`, `onUserCancel` is set to `ThrowException`, and the user has cancelled the operation (). + +- `ShowUI` is set to `True`, `onUserCancel` is set to `ThrowException`, and an unspecified I/O error occurs (). + +- The path exceeds the system-defined maximum length (). + +- The user does not have required permission (). + +- The user lacks necessary permissions to view the path (). + ## See also - -- +- - - [How to: Copy Files with a Specific Pattern to a Directory](how-to-copy-files-with-a-specific-pattern-to-a-directory.md) - [How to: Create a Copy of a File in a Different Directory](how-to-create-a-copy-of-a-file-in-a-different-directory.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-directory.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-directory.md index 74793714cf97d..e36017b5e3ac0 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-directory.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-directory.md @@ -2,42 +2,42 @@ description: "Learn more about: How to: Create a Directory in Visual Basic" title: "How to: Create a Directory" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "directories [Visual Basic], creating" - "folders [Visual Basic], creating" ms.assetid: 0351a2ca-24d8-43b5-bb39-9b99e6401cff --- # How to: Create a Directory in Visual Basic -Use the `CreateDirectory` method of the `My.Computer.FileSystem` object to create directories. - - If the directory already exists, no exception is thrown. - -### To create a directory - -- Use the `CreateDirectory` method by specifying the full path of the location where the directory should be created. This example creates the directory `NewDirectory` in `C:\Documents and Settings\All Users\Documents`. - - [!code-vb[VbVbcnMyFileSystem#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#2)] - -## Robust Programming - - The following conditions may cause an exception: - -- The directory name is malformed. For example, it contains illegal characters or is only white space (). - -- The parent directory of the directory to be created is read-only (). - -- The directory name is `Nothing` (). - -- The directory name is too long (). - -- The directory name is a colon ":" (). - -- The user does not have permission to create the directory (). - -- The user lacks permissions in a partial-trust situation (). - +Use the `CreateDirectory` method of the `My.Computer.FileSystem` object to create directories. + + If the directory already exists, no exception is thrown. + +### To create a directory + +- Use the `CreateDirectory` method by specifying the full path of the location where the directory should be created. This example creates the directory `NewDirectory` in `C:\Documents and Settings\All Users\Documents`. + + [!code-vb[VbVbcnMyFileSystem#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#2)] + +## Robust Programming + + The following conditions may cause an exception: + +- The directory name is malformed. For example, it contains illegal characters or is only white space (). + +- The parent directory of the directory to be created is read-only (). + +- The directory name is `Nothing` (). + +- The directory name is too long (). + +- The directory name is a colon ":" (). + +- The user does not have permission to create the directory (). + +- The user lacks permissions in a partial-trust situation (). + ## See also -- +- - [Creating, Deleting, and Moving Files and Directories](creating-deleting-and-moving-files-and-directories.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-file.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-file.md index a0f32aecf467e..e6a3858ab0f3f 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-file.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-create-a-file.md @@ -2,50 +2,50 @@ description: "Learn more about: How to: Create a File in Visual Basic" title: "How to: Create a File" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "text files [Visual Basic], creating" - "files [Visual Basic], creating" ms.assetid: 0253bb6d-5519-4a50-b882-b93ef5cca0d9 --- # How to: Create a File in Visual Basic -This example creates an empty text file at the specified path using the method in the class. - -## Example - - [!code-vb[VbFileIOMisc#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOMisc/VB/class2.vb#1)] - -## Compiling the Code - - Use the `file` variable to write to the file. - -## Robust Programming - - If the file already exists, it is replaced. - - The following conditions may cause an exception: - -- The path name is malformed. For example, it contains illegal characters or is only white space (). - -- The path is read-only (). - -- The path name is `Nothing` (). - -- The path name is too long (). - -- The path is invalid (). - -- The path is only a colon ":" (). - -## .NET Framework Security - - A may be thrown in partial-trust environments. - - The call to the method requires . - - An is thrown if the user does not have permission to create the file. - +This example creates an empty text file at the specified path using the method in the class. + +## Example + + [!code-vb[VbFileIOMisc#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOMisc/VB/class2.vb#1)] + +## Compiling the Code + + Use the `file` variable to write to the file. + +## Robust Programming + + If the file already exists, it is replaced. + + The following conditions may cause an exception: + +- The path name is malformed. For example, it contains illegal characters or is only white space (). + +- The path is read-only (). + +- The path name is `Nothing` (). + +- The path name is too long (). + +- The path is invalid (). + +- The path is only a colon ":" (). + +## .NET Framework Security + + A may be thrown in partial-trust environments. + + The call to the method requires . + + An is thrown if the user does not have permission to create the file. + ## See also - -- +- diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-find-files-with-a-specific-pattern.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-find-files-with-a-specific-pattern.md index f94bf04f8e825..b135a036c494c 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-find-files-with-a-specific-pattern.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-find-files-with-a-specific-pattern.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Find Files with a Specific Pattern in Visual Basic" title: "How to: Find Files with a Specific Pattern" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "files [Visual Basic], finding" - "pattern matching" - "patterns, matching" @@ -10,42 +10,42 @@ ms.assetid: 25e3b71d-b844-4293-9e4e-f06c5836b5cc --- # How to: Find Files with a Specific Pattern in Visual Basic -The method returns a read-only collection of strings representing the path names for the files. You can use the `wildCards` parameter to specify a specific pattern. If you would like to include subdirectories in the search, set the `searchType` parameter to `SearchOption.SearchAllSubDirectories`. - - An empty collection is returned if no files matching the specified pattern are found. - +The method returns a read-only collection of strings representing the path names for the files. You can use the `wildCards` parameter to specify a specific pattern. If you would like to include subdirectories in the search, set the `searchType` parameter to `SearchOption.SearchAllSubDirectories`. + + An empty collection is returned if no files matching the specified pattern are found. + > [!NOTE] -> For information about returning a file list by using the `DirectoryInfo` class of the `System.IO` namespace, see . - -### To find files with a specified pattern - -- Use the `GetFiles` method, supplying the name and path of the directory you want to search and specifying the pattern. The following example returns all files with the extension `.dll` in the directory and adds them to `ListBox1`. - - [!code-vb[VbFileIOMisc#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOMisc/VB/Class1.vb#4)] - -## .NET Framework Security - - The following conditions may cause an exception: - -- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). - -- The path is not valid because it is `Nothing` (). - -- `directory` does not exist (). - -- `directory` points to an existing file (). - -- The path exceeds the system-defined maximum length (). - -- A file or folder name in the path contains a colon (:) or is in an invalid format (). - -- The user lacks necessary permissions to view the path (). - -- The user lacks necessary permissions (). - +> For information about returning a file list by using the `DirectoryInfo` class of the `System.IO` namespace, see . + +### To find files with a specified pattern + +- Use the `GetFiles` method, supplying the name and path of the directory you want to search and specifying the pattern. The following example returns all files with the extension `.dll` in the directory and adds them to `ListBox1`. + + [!code-vb[VbFileIOMisc#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOMisc/VB/Class1.vb#4)] + +## .NET Framework Security + + The following conditions may cause an exception: + +- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). + +- The path is not valid because it is `Nothing` (). + +- `directory` does not exist (). + +- `directory` points to an existing file (). + +- The path exceeds the system-defined maximum length (). + +- A file or folder name in the path contains a colon (:) or is in an invalid format (). + +- The user lacks necessary permissions to view the path (). + +- The user lacks necessary permissions (). + ## See also -- +- - [How to: Find Subdirectories with a Specific Pattern](how-to-find-subdirectories-with-a-specific-pattern.md) - [Troubleshooting: Reading from and Writing to Text Files](troubleshooting-reading-from-and-writing-to-text-files.md) - [How to: Get the Collection of Files in a Directory](how-to-get-the-collection-of-files-in-a-directory.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-find-subdirectories-with-a-specific-pattern.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-find-subdirectories-with-a-specific-pattern.md index 82c28af6729e4..a89b8e5543313 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-find-subdirectories-with-a-specific-pattern.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-find-subdirectories-with-a-specific-pattern.md @@ -9,7 +9,7 @@ ms.assetid: c9265fd1-7483-4150-8b7f-ff642caa939d --- # How to: Find Subdirectories with a Specific Pattern in Visual Basic -The method returns a read-only collection of strings representing the path names for the subdirectories in a directory. You can use the `wildCards` parameter to specify a specific pattern. If you would like to include the contents of subdirectories in the search, set the `searchType` parameter to `SearchOption.SearchAllSubDirectories`. +The method returns a read-only collection of strings representing the path names for the subdirectories in a directory. You can use the `wildCards` parameter to specify a specific pattern. If you would like to include the contents of subdirectories in the search, set the `searchType` parameter to `SearchOption.SearchAllSubDirectories`. An empty collection is returned if no directories matching the specified pattern are found. @@ -43,5 +43,5 @@ The following conditions may cause an exception: ## See also -- +- - [How to: Find Files with a Specific Pattern](how-to-find-files-with-a-specific-pattern.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-get-the-collection-of-files-in-a-directory.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-get-the-collection-of-files-in-a-directory.md index 48d1a15e92ea4..361614991a0e3 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-get-the-collection-of-files-in-a-directory.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-get-the-collection-of-files-in-a-directory.md @@ -2,49 +2,49 @@ description: "Learn more about: How to: Get the Collection of Files in a Directory in Visual Basic" title: "How to: Get the Collection of Files in a Directory" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "folders, working with" - "files [Visual Basic], accessing" ms.assetid: 6c8ba7e8-dd37-4853-92bf-762b67c98160 --- # How to: Get the Collection of Files in a Directory in Visual Basic -The overloads of the method return a read-only collection of strings representing the names of the files within a directory: - -- Use the overload for a simple file search in a specified directory, without searching subdirectories. - -- Use the overload to specify additional options for your search. You can use the `wildCards` parameter to specify a search pattern. To include subdirectories in the search, set the `searchType` parameter to . - - An empty collection is returned if no files matching the specified pattern are found. - -### To list files in a directory - -- Use one of the method overloads, supplying the name and path of the directory to search in the `directory` parameter. The following example returns all files in the directory and adds them to `ListBox1`. - - [!code-vb[VbVbcnMyFileSystem#32](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#32)] - -## Robust Programming - - The following conditions may cause an exception: - -- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). - -- The path is not valid because it is `Nothing` (). - -- `directory` does not exist (). - -- `directory` points to an existing file (). - -- The path exceeds the system-defined maximum length (). - -- A file or directory name in the path contains a colon (:) or is in an invalid format (). - -- The user lacks necessary permissions to view the path (). - -- The user lacks necessary permissions (). - +The overloads of the method return a read-only collection of strings representing the names of the files within a directory: + +- Use the overload for a simple file search in a specified directory, without searching subdirectories. + +- Use the overload to specify additional options for your search. You can use the `wildCards` parameter to specify a search pattern. To include subdirectories in the search, set the `searchType` parameter to . + + An empty collection is returned if no files matching the specified pattern are found. + +### To list files in a directory + +- Use one of the method overloads, supplying the name and path of the directory to search in the `directory` parameter. The following example returns all files in the directory and adds them to `ListBox1`. + + [!code-vb[VbVbcnMyFileSystem#32](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#32)] + +## Robust Programming + + The following conditions may cause an exception: + +- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). + +- The path is not valid because it is `Nothing` (). + +- `directory` does not exist (). + +- `directory` points to an existing file (). + +- The path exceeds the system-defined maximum length (). + +- A file or directory name in the path contains a colon (:) or is in an invalid format (). + +- The user lacks necessary permissions to view the path (). + +- The user lacks necessary permissions (). + ## See also -- +- - [How to: Find Files with a Specific Pattern](how-to-find-files-with-a-specific-pattern.md) - [How to: Find Subdirectories with a Specific Pattern](how-to-find-subdirectories-with-a-specific-pattern.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-move-a-file.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-move-a-file.md index f9090d2629354..f36ecd2e549d1 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-move-a-file.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-move-a-file.md @@ -2,53 +2,53 @@ description: "Learn more about: How to: Move a File in Visual Basic" title: "How to: Move a File" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "files [Visual Basic], moving" ms.assetid: 53a7457b-5815-41ad-b37d-28537c1fb77a --- # How to: Move a File in Visual Basic -The `My.Computer.FileSystem.MoveFile` method can be used to move a file to another folder. If the target structure does not exist, it will be created. - -### To move a file - -- Use the `MoveFile` method to move the file, specifying the file name and location for both the source file and the target file. This example moves the file named `test.txt` from `TestDir1` to `TestDir2`. Note that the target file name is specified even though it is the same as the source file name. - - [!code-vb[VbVbcnMyFileSystem#24](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#24)] - -### To move a file and rename it - -- Use the `MoveFile` method to move the file, specifying the source file name and location, the target location, and the new name at the target location. This example moves the file named `test.txt` from `TestDir1` to `TestDir2` and renames it `nexttest.txt`. - - [!code-vb[VbVbcnMyFileSystem#25](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#25)] - -## Robust Programming - - The following conditions may cause an exception: - -- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). - -- The path is not valid because it is `Nothing` (). - -- `destinationFileName` is `Nothing` or an empty string (). - -- The source file is not valid or does not exist (). - -- The combined path points to an existing directory, the destination file exists and `overwrite` is set to `False`, a file in the target directory with the same name is in use, or the user does not have sufficient permissions to access the file (). - -- A file or directory name in the path contains a colon (:) or is in an invalid format (). - -- `showUI` is set to `True`, `onUserCancel` is set to `ThrowException`, and either the user has cancelled the operation or an unspecified I/O error occurs (). - -- The path exceeds the system-defined maximum length (). - -- The user lacks necessary permissions to view the path (). - -- The user does not have required permission (). - +The `My.Computer.FileSystem.MoveFile` method can be used to move a file to another folder. If the target structure does not exist, it will be created. + +### To move a file + +- Use the `MoveFile` method to move the file, specifying the file name and location for both the source file and the target file. This example moves the file named `test.txt` from `TestDir1` to `TestDir2`. Note that the target file name is specified even though it is the same as the source file name. + + [!code-vb[VbVbcnMyFileSystem#24](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#24)] + +### To move a file and rename it + +- Use the `MoveFile` method to move the file, specifying the source file name and location, the target location, and the new name at the target location. This example moves the file named `test.txt` from `TestDir1` to `TestDir2` and renames it `nexttest.txt`. + + [!code-vb[VbVbcnMyFileSystem#25](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#25)] + +## Robust Programming + + The following conditions may cause an exception: + +- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). + +- The path is not valid because it is `Nothing` (). + +- `destinationFileName` is `Nothing` or an empty string (). + +- The source file is not valid or does not exist (). + +- The combined path points to an existing directory, the destination file exists and `overwrite` is set to `False`, a file in the target directory with the same name is in use, or the user does not have sufficient permissions to access the file (). + +- A file or directory name in the path contains a colon (:) or is in an invalid format (). + +- `showUI` is set to `True`, `onUserCancel` is set to `ThrowException`, and either the user has cancelled the operation or an unspecified I/O error occurs (). + +- The path exceeds the system-defined maximum length (). + +- The user lacks necessary permissions to view the path (). + +- The user does not have required permission (). + ## See also -- +- - [How to: Rename a File](how-to-rename-a-file.md) - [How to: Create a Copy of a File in a Different Directory](how-to-create-a-copy-of-a-file-in-a-different-directory.md) - [How to: Parse File Paths](how-to-parse-file-paths.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-parse-file-paths.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-parse-file-paths.md index d757c97971cc2..95a841060ed3c 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-parse-file-paths.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-parse-file-paths.md @@ -2,39 +2,39 @@ description: "Learn more about: How to: Parse File Paths in Visual Basic" title: "How to: Parse File Paths" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "file names [Visual Basic], parsing [Visual Basic]" - "parsing, file paths [Visual Basic]" ms.assetid: c1bd99c9-8160-456a-b5ab-60a49139b923 --- # How to: Parse File Paths in Visual Basic -The object offers a number of useful methods when parsing file paths. - -- The method takes two paths and returns a properly formatted combined path. - -- The method returns the absolute path of the parent of the provided path. - -- The method returns a object that can be queried to determine the file's properties, such as its name and path. - - Do not make decisions about the contents of the file based on the file name extension. For example, the file Form1.vb may not be a Visual Basic source file. - -### To determine a file's name and path - -- Use the and properties of the object to determine a file's name and path. This example determines the name and path and displays them. - - [!code-vb[VbVbcnMyFileSystem#54](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#54)] - -### To combine a file's name and directory to create the full path - -- Use the `CombinePath` method, supplying the directory and name. This example takes the strings `folderPath` and `fileName` created in the previous example, combines them, and displays the result. - - [!code-vb[VbVbcnMyFileSystem#55](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#55)] - +The object offers a number of useful methods when parsing file paths. + +- The method takes two paths and returns a properly formatted combined path. + +- The method returns the absolute path of the parent of the provided path. + +- The method returns a object that can be queried to determine the file's properties, such as its name and path. + + Do not make decisions about the contents of the file based on the file name extension. For example, the file Form1.vb may not be a Visual Basic source file. + +### To determine a file's name and path + +- Use the and properties of the object to determine a file's name and path. This example determines the name and path and displays them. + + [!code-vb[VbVbcnMyFileSystem#54](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#54)] + +### To combine a file's name and directory to create the full path + +- Use the `CombinePath` method, supplying the directory and name. This example takes the strings `folderPath` and `fileName` created in the previous example, combines them, and displays the result. + + [!code-vb[VbVbcnMyFileSystem#55](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#55)] + ## See also - -- +- - -- +- - [How to: Get the Collection of Files in a Directory](how-to-get-the-collection-of-files-in-a-directory.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-binary-files.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-binary-files.md index 8140e9326542d..4b59e64c58591 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-binary-files.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-binary-files.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Read From Binary Files in Visual Basic" title: "How to: Read From Binary Files" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "binary files [Visual Basic], reading from" - "I/O [Visual Basic], reading from binary files" - "ReadAllBytes method [Visual Basic], reading from binary files" @@ -11,46 +11,46 @@ ms.assetid: d2b1269e-24b6-42e0-9414-ae708db282d8 --- # How to: Read From Binary Files in Visual Basic -The `My.Computer.FileSystem` object provides the `ReadAllBytes` method for reading from binary files. - -### To read from a binary file - -- Use the `ReadAllBytes` method, which returns the contents of a file as a byte array. This example reads from the file `C:/Documents and Settings/selfportrait.jpg`. - - [!code-vb[VbVbcnMyFileSystem#78](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#78)] - -- For large binary files, you can use the method of the object to read from the file only a specified amount at a time. You can then limit how much of the file is loaded into memory for each read operation. The following code example copies a file and allows the caller to specify how much of the file is read into memory per read operation. - - [!code-vb[VbVbcnMyFileSystem#91](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#91)] - -## Robust Programming - - The following conditions may cause an exception to be thrown: - -- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (). - -- The path is not valid because it is `Nothing` (). - -- The file does not exist (). - -- The file is in use by another process, or an I/O error occurs (). - -- The path exceeds the system-defined maximum length (). - -- A file or directory name in the path contains a colon (:) or is in an invalid format (). - -- There is not enough memory to write the string to buffer (). - -- The user lacks necessary permissions to view the path (). - - Do not make decisions about the contents of the file based on the name of the file. For example, the file Form1.vb may not be a Visual Basic source file. - - Verify all inputs before using the data in your application. The contents of the file may not be what is expected, and methods to read from the file may fail. - +The `My.Computer.FileSystem` object provides the `ReadAllBytes` method for reading from binary files. + +### To read from a binary file + +- Use the `ReadAllBytes` method, which returns the contents of a file as a byte array. This example reads from the file `C:/Documents and Settings/selfportrait.jpg`. + + [!code-vb[VbVbcnMyFileSystem#78](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#78)] + +- For large binary files, you can use the method of the object to read from the file only a specified amount at a time. You can then limit how much of the file is loaded into memory for each read operation. The following code example copies a file and allows the caller to specify how much of the file is read into memory per read operation. + + [!code-vb[VbVbcnMyFileSystem#91](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#91)] + +## Robust Programming + + The following conditions may cause an exception to be thrown: + +- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (). + +- The path is not valid because it is `Nothing` (). + +- The file does not exist (). + +- The file is in use by another process, or an I/O error occurs (). + +- The path exceeds the system-defined maximum length (). + +- A file or directory name in the path contains a colon (:) or is in an invalid format (). + +- There is not enough memory to write the string to buffer (). + +- The user lacks necessary permissions to view the path (). + + Do not make decisions about the contents of the file based on the name of the file. For example, the file Form1.vb may not be a Visual Basic source file. + + Verify all inputs before using the data in your application. The contents of the file may not be what is expected, and methods to read from the file may fail. + ## See also -- -- +- +- - [Reading from Files](reading-from-files.md) - [How to: Read From Text Files with Multiple Formats](how-to-read-from-text-files-with-multiple-formats.md) - [Storing Data to and Reading from the Clipboard](../computer-resources/storing-data-to-and-reading-from-the-clipboard.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-comma-delimited-text-files.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-comma-delimited-text-files.md index 0b2f280e3d7d7..23cb1262b9fcf 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-comma-delimited-text-files.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-comma-delimited-text-files.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: read from comma-delimited text files in Visual Basic" title: "How to: read from comma-delimited text files" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "files [Visual Basic], parsing" - "text files [Visual Basic], tasks" - "reading text files [Visual Basic], comma-delimited" @@ -11,46 +11,46 @@ ms.assetid: a8413fe4-0dba-49c8-8692-44fb67a9ec4f --- # How to: read from comma-delimited text files in Visual Basic -The `TextFieldParser` object provides a way to easily and efficiently parse structured text files, such as logs. The `TextFieldType` property defines whether it is a delimited file or one with fixed-width fields of text. - -### To parse a comma delimited text file - -1. Create a new `TextFieldParser`. The following code creates the `TextFieldParser` named `MyReader` and opens the file `test.txt`. - - [!code-vb[VbFileIORead#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#15)] - -2. Define the `TextField` type and delimiter. The following code defines the `TextFieldType` property as `Delimited` and the delimiter as ",". - - [!code-vb[VbFileIORead#16](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#16)] - -3. Loop through the fields in the file. If any lines are corrupt, report an error and continue parsing. The following code loops through the file, displaying each field in turn and reporting any fields that are formatted incorrectly. - - [!code-vb[VbFileIORead#17](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#17)] - -4. Close the `While` and `Using` blocks with `End While` and `End Using`. - - [!code-vb[VbFileIORead#18](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#18)] - -## Example - - This example reads from the file `test.txt`. - - [!code-vb[VbFileIORead#19](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#19)] - -## Robust programming - - The following conditions may cause an exception: - -- A row cannot be parsed using the specified format (). The exception message specifies the line causing the exception, while the property is assigned the text contained in the line. - -- The specified file does not exist (). - -- A partial-trust situation in which the user does not have sufficient permissions to access the file. (). - -- The path is too long (). - -- The user does not have sufficient permissions to access the file (). - +The `TextFieldParser` object provides a way to easily and efficiently parse structured text files, such as logs. The `TextFieldType` property defines whether it is a delimited file or one with fixed-width fields of text. + +### To parse a comma delimited text file + +1. Create a new `TextFieldParser`. The following code creates the `TextFieldParser` named `MyReader` and opens the file `test.txt`. + + [!code-vb[VbFileIORead#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#15)] + +2. Define the `TextField` type and delimiter. The following code defines the `TextFieldType` property as `Delimited` and the delimiter as ",". + + [!code-vb[VbFileIORead#16](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#16)] + +3. Loop through the fields in the file. If any lines are corrupt, report an error and continue parsing. The following code loops through the file, displaying each field in turn and reporting any fields that are formatted incorrectly. + + [!code-vb[VbFileIORead#17](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#17)] + +4. Close the `While` and `Using` blocks with `End While` and `End Using`. + + [!code-vb[VbFileIORead#18](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#18)] + +## Example + + This example reads from the file `test.txt`. + + [!code-vb[VbFileIORead#19](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#19)] + +## Robust programming + + The following conditions may cause an exception: + +- A row cannot be parsed using the specified format (). The exception message specifies the line causing the exception, while the property is assigned the text contained in the line. + +- The specified file does not exist (). + +- A partial-trust situation in which the user does not have sufficient permissions to access the file. (). + +- The path is too long (). + +- The user does not have sufficient permissions to access the file (). + ## See also - diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-fixed-width-text-files.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-fixed-width-text-files.md index 9cbcfec9b6ad6..7abaaa8a93c10 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-fixed-width-text-files.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-fixed-width-text-files.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: read from fixed-width text files in Visual Basic" title: "How to: read from fixed-width text Files" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "fixed-width text file" - "reading text files [Visual Basic], fixed-width" - "files [Visual Basic], parsing" @@ -12,48 +12,48 @@ ms.assetid: 99be5692-967a-4e85-993e-cd18139a5a69 --- # How to: read from fixed-width text files in Visual Basic -The `TextFieldParser` object provides a way to easily and efficiently parse structured text files, such as logs. - - The `TextFieldType` property defines whether the parsed file is a delimited file or one that has fixed-width fields of text. In a fixed-width text file, the field at the end can have a variable width. To specify that the field at the end has a variable width, define it to have a width less than or equal to zero. - -### To parse a fixed-width text file - -1. Create a new `TextFieldParser`. The following code creates the `TextFieldParser` named `Reader` and opens the file `test.log`. - - [!code-vb[VbFileIORead#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#9)] - -2. Define the `TextFieldType` property as `FixedWidth`, defining the width and format. The following code defines the columns of text; the first is 5 characters wide, the second 10, the third 11, and the fourth is of variable width. - - [!code-vb[VbFileIORead#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#10)] - -3. Loop through the fields in the file. If any lines are corrupted, report an error and continue parsing. - - [!code-vb[VbFileIORead#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#11)] - -4. Close the `While` and `Using` blocks with `End While` and `End Using`. - - [!code-vb[VbFileIORead#12](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#12)] - -## Example - - This example reads from the file `test.log`. - - [!code-vb[VbFileIORead#13](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#13)] - -## Robust programming - - The following conditions may cause an exception: - -- A row cannot be parsed using the specified format (). The exception message specifies the line causing the exception, while the property is assigned to the text contained in the line. - -- The specified file does not exist (). - -- A partial-trust situation in which the user does not have sufficient permissions to access the file. (). - -- The path is too long (). - -- The user does not have sufficient permissions to access the file (). - +The `TextFieldParser` object provides a way to easily and efficiently parse structured text files, such as logs. + + The `TextFieldType` property defines whether the parsed file is a delimited file or one that has fixed-width fields of text. In a fixed-width text file, the field at the end can have a variable width. To specify that the field at the end has a variable width, define it to have a width less than or equal to zero. + +### To parse a fixed-width text file + +1. Create a new `TextFieldParser`. The following code creates the `TextFieldParser` named `Reader` and opens the file `test.log`. + + [!code-vb[VbFileIORead#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#9)] + +2. Define the `TextFieldType` property as `FixedWidth`, defining the width and format. The following code defines the columns of text; the first is 5 characters wide, the second 10, the third 11, and the fourth is of variable width. + + [!code-vb[VbFileIORead#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#10)] + +3. Loop through the fields in the file. If any lines are corrupted, report an error and continue parsing. + + [!code-vb[VbFileIORead#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#11)] + +4. Close the `While` and `Using` blocks with `End While` and `End Using`. + + [!code-vb[VbFileIORead#12](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#12)] + +## Example + + This example reads from the file `test.log`. + + [!code-vb[VbFileIORead#13](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#13)] + +## Robust programming + + The following conditions may cause an exception: + +- A row cannot be parsed using the specified format (). The exception message specifies the line causing the exception, while the property is assigned to the text contained in the line. + +- The specified file does not exist (). + +- A partial-trust situation in which the user does not have sufficient permissions to access the file. (). + +- The path is too long (). + +- The user does not have sufficient permissions to access the file (). + ## See also - diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files-with-multiple-formats.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files-with-multiple-formats.md index 464f987ded5cb..59c105e6b0c15 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files-with-multiple-formats.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files-with-multiple-formats.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Read from text files with multiple formats in Visual Basic" title: "How to: Read from text files with multiple formats" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "TextFieldParser object, reading from a file" - "TextFieldType enumeration" - "My.Computer.FileSystem.WriteAllText method, parsing structured text files" @@ -16,7 +16,7 @@ ms.assetid: 8d185eb2-79ca-42cd-95a7-d3ff44a5a0f8 # How to: Read from text files with multiple formats in Visual Basic The object provides a way to easily and efficiently parse structured text files, such as logs. You can process a file with multiple formats by using the `PeekChars` method to determine the format of each line as you parse through the file. - + ### To parse a text file with multiple formats 1. Add a text file named *testfile.txt* to your project. Add the following content to the text file: @@ -54,9 +54,9 @@ The following is the complete example that reads from the file `testfile.txt`: ## Robust programming -The following conditions may cause an exception: - -- A row cannot be parsed using the specified format (). The exception message specifies the line causing the exception, while the property is assigned to the text contained in the line. +The following conditions may cause an exception: + +- A row cannot be parsed using the specified format (). The exception message specifies the line causing the exception, while the property is assigned to the text contained in the line. - The specified file does not exist (). - A partial-trust situation in which the user does not have sufficient permissions to access the file. (). - The path is too long (). @@ -65,11 +65,11 @@ The following conditions may cause an exception: ## See also - -- +- - -- -- -- +- +- +- - [How to: Read From Comma-Delimited Text Files](how-to-read-from-comma-delimited-text-files.md) - [How to: Read From Fixed-width Text Files](how-to-read-from-fixed-width-text-files.md) - [Parsing Text Files with the TextFieldParser Object](parsing-text-files-with-the-textfieldparser-object.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files.md index 018253646bdad..0705c4a6953e5 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files.md @@ -12,12 +12,12 @@ ms.assetid: 735fe9d7-0f7a-4185-ba02-f35e580ec4b8 --- # How to: Read From Text Files in Visual Basic -The method of the `My.Computer.FileSystem` object allows you to read from a text file. The file encoding can be specified if the contents of the file use an encoding such as ASCII or UTF-8. +The method of the `My.Computer.FileSystem` object allows you to read from a text file. The file encoding can be specified if the contents of the file use an encoding such as ASCII or UTF-8. If you are reading from a file with extended characters, you will need to specify the file encoding. > [!NOTE] -> To read a file a single line of text at a time, use the method of the `My.Computer.FileSystem` object. The `OpenTextFileReader` method returns a object. You can use the method of the `StreamReader` object to read a file one line at a time. You can test for the end of the file using the method of the `StreamReader` object. +> To read a file a single line of text at a time, use the method of the `My.Computer.FileSystem` object. The `OpenTextFileReader` method returns a object. You can use the method of the `StreamReader` object to read a file one line at a time. You can test for the end of the file using the method of the `StreamReader` object. ## To read from a text file @@ -42,7 +42,7 @@ For better error handling and file path management, you can use the following ap [!code-vb[VbFileIORead#22](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#22)] > [!NOTE] -> When specifying file paths, avoid using hardcoded absolute paths like "C:\temp\file.txt" as these can cause issues on systems where the drive letter or directory structure is different. Instead, use relative paths or construct paths using to ensure your code works across different environments. +> When specifying file paths, avoid using hardcoded absolute paths like "C:\temp\file.txt" as these can cause issues on systems where the drive letter or directory structure is different. Instead, use relative paths or construct paths using to ensure your code works across different environments. ## Robust Programming @@ -71,7 +71,7 @@ Verify all inputs before using the data in your application. The contents of the ## See also - -- +- - [Reading from Files](reading-from-files.md) - [How to: Read From Comma-Delimited Text Files](how-to-read-from-comma-delimited-text-files.md) - [How to: Read From Fixed-width Text Files](how-to-read-from-fixed-width-text-files.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-text-from-files-with-a-streamreader.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-text-from-files-with-a-streamreader.md index afe9808155c0d..a42a782dd3c77 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-text-from-files-with-a-streamreader.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-text-from-files-with-a-streamreader.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Read Text from Files with a StreamReader (Visual Basic)" title: "How to: Read Text from Files with a StreamReader" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "reading files [Visual Basic], text" - "text, reading from files" - "reading text from files [Visual Basic]" @@ -11,31 +11,31 @@ ms.assetid: 384033c6-18f9-4d59-9610-36371226558f --- # How to: Read Text from Files with a StreamReader (Visual Basic) -The `My.Computer.FileSystem` object provides methods to open a and a . These methods, `OpenTextFileWriter` and `OpenTextFileReader`, are advanced methods that do not appear in IntelliSense unless you select the **All** tab. - -### To read a line from a file with a text reader - -- Use the `OpenTextFileReader` method to open the , specifying the file. This example opens the file named `testfile.txt`, reads a line from it, and displays the line in a message box. - - [!code-vb[VbFileIORead#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#1)] - -## Robust Programming - - The file that is read must be a text file. - - Do not make decisions about the contents of the file based on the name of the file. For example, the file Form1.vb may not be a Visual Basic source file. - - Verify all inputs before using the data in your application. The contents of the file may not be what is expected, and methods to read from the file may fail. - -## .NET Framework Security - - To read from a file, your assembly requires a privilege level granted by the class. If you are running in a partial-trust context, the code might throw an exception due to insufficient privileges. For more information, see [Code Access Security Basics](/previous-versions/dotnet/framework/code-access-security/code-access-security-basics). The user also needs access to the file. For more information, see [ACL Technology Overview](/previous-versions/dotnet/netframework-4.0/ms229742(v=vs.100)). - +The `My.Computer.FileSystem` object provides methods to open a and a . These methods, `OpenTextFileWriter` and `OpenTextFileReader`, are advanced methods that do not appear in IntelliSense unless you select the **All** tab. + +### To read a line from a file with a text reader + +- Use the `OpenTextFileReader` method to open the , specifying the file. This example opens the file named `testfile.txt`, reads a line from it, and displays the line in a message box. + + [!code-vb[VbFileIORead#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIORead/VB/Class1.vb#1)] + +## Robust Programming + + The file that is read must be a text file. + + Do not make decisions about the contents of the file based on the name of the file. For example, the file Form1.vb may not be a Visual Basic source file. + + Verify all inputs before using the data in your application. The contents of the file may not be what is expected, and methods to read from the file may fail. + +## .NET Framework Security + + To read from a file, your assembly requires a privilege level granted by the class. If you are running in a partial-trust context, the code might throw an exception due to insufficient privileges. For more information, see [Code Access Security Basics](/previous-versions/dotnet/framework/code-access-security/code-access-security-basics). The user also needs access to the file. For more information, see [ACL Technology Overview](/previous-versions/dotnet/netframework-4.0/ms229742(v=vs.100)). + ## See also - - -- -- +- +- - [SaveFileDialog Component](/dotnet/desktop/winforms/controls/savefiledialog-component-windows-forms) - [Reading from Files](reading-from-files.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-rename-a-file.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-rename-a-file.md index 8310371fdbd3f..85980aa4daac0 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-rename-a-file.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-rename-a-file.md @@ -2,7 +2,7 @@ title: "How to: Rename a File" description: "Learn about how to rename a file with the Visual Basic Runtime Library or the .NET base class library." ms.date: 01/14/2025 -helpviewer_keywords: +helpviewer_keywords: - "I/O [Visual Basic], renaming files" - "files [Visual Basic], renaming" ms.assetid: 0ea7e0c8-2cb2-4bf5-a00d-7b6e3c08a3bc @@ -46,8 +46,8 @@ The following conditions might cause an exception: ## See also -- -- +- +- - [How to: Move a File](how-to-move-a-file.md) - [Creating, Deleting, and Moving Files and Directories](creating-deleting-and-moving-files-and-directories.md) - [How to: Create a Copy of a File in the Same Directory](how-to-create-a-copy-of-a-file-in-the-same-directory.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-retrieve-the-contents-of-the-my-documents-directory.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-retrieve-the-contents-of-the-my-documents-directory.md index aaa6a34307ab7..a1213feccdb0e 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-retrieve-the-contents-of-the-my-documents-directory.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-retrieve-the-contents-of-the-my-documents-directory.md @@ -2,21 +2,21 @@ description: "Learn more about: How to: Retrieve the Contents of the My Documents Directory in Visual Basic" title: "How to: Retrieve the Contents of the My Documents Directory" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "My Documents directory" ms.assetid: 26560d01-7dda-4457-8e95-21db23d71aea --- # How to: Retrieve the Contents of the My Documents Directory in Visual Basic -The object can be used to read from many of the **All Users** directories, such as **My Documents** or **Desktop**. - -### To read from the My Documents folder - -- Use the `ReadAllText` method to read the text from each file in a specific directory. The following code specifies a directory and file and then uses `ReadAllText` to read them into the string named `patients`. - - [!code-vb[VbVbcnMyFileSystem#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#15)] - +The object can be used to read from many of the **All Users** directories, such as **My Documents** or **Desktop**. + +### To read from the My Documents folder + +- Use the `ReadAllText` method to read the text from each file in a specific directory. The following code specifies a directory and file and then uses `ReadAllText` to read them into the string named `patients`. + + [!code-vb[VbVbcnMyFileSystem#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#15)] + ## See also - -- +- diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-in-the-my-documents-directory.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-in-the-my-documents-directory.md index 42c3dd9bd9a5e..d66e38cbdde87 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-in-the-my-documents-directory.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-in-the-my-documents-directory.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Write Text to Files in the My Documents Directory in Visual Basic" title: "How to: Write Text to Files in the My Documents Directory" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "files [Visual Basic], writing to" - "text, writing to files" - "examples [Visual Basic], text files" @@ -11,42 +11,42 @@ ms.assetid: 1c726124-781d-4976-9baa-ed46814ff3fe --- # How to: Write Text to Files in the My Documents Directory in Visual Basic -The `My.Computer.FileSystem.SpecialDirectories` object allows you to access special directories, such as the **MyDocuments** directory. - -## Procedure - -#### To write new text files in the My Documents directory - -1. Use the `My.Computer.FileSystem.SpecialDirectories.MyDocuments` property to supply the path. - - [!code-vb[VbFileIOWrite#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOWrite/VB/Class1.vb#1)] - -2. Use the `WriteAllText` method to write text to the specified file. - - [!code-vb[VbVbcnMyFileSystem#14](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#14)] - -## Example - - [!code-vb[VbFileIOWrite#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOWrite/VB/Class1.vb#2)] - -## Compiling the Code - - Replace `test.txt` with the name of the file you want to write to. - -## Robust Programming - - This code rethrows all the exceptions that may occur when writing text to the file. You can reduce the likelihood of exceptions by using Windows Forms controls such as the [OpenFileDialog](/dotnet/desktop/winforms/controls/openfiledialog-component-windows-forms) and the [SaveFileDialog](/dotnet/desktop/winforms/controls/savefiledialog-component-windows-forms) components that limit the user choices to valid file names. Using these controls is not foolproof, however. The file system can change between the time the user selects a file and the time that the code executes. Exception handling is therefore nearly always necessary when with working with files. - -## .NET Framework Security - - If you are running in a partial-trust context, the code might throw an exception due to insufficient privileges. For more information, see [Code Access Security Basics](/previous-versions/dotnet/framework/code-access-security/code-access-security-basics). - - This example creates a new file. If an application needs to create a file, that application needs Create permission for the folder. Permissions are set using access control lists. If the file already exists, the application needs only Write permission, a lesser privilege. Where possible, it is more secure to create the file during deployment, and only grant Read privileges to a single file, rather than to grant Create privileges for a folder. Also, it is more secure to write data to user folders than to the root folder or the **Program Files** folder. For more information, see [ACL Technology Overview](/previous-versions/dotnet/netframework-4.0/ms229742(v=vs.100)). - +The `My.Computer.FileSystem.SpecialDirectories` object allows you to access special directories, such as the **MyDocuments** directory. + +## Procedure + +#### To write new text files in the My Documents directory + +1. Use the `My.Computer.FileSystem.SpecialDirectories.MyDocuments` property to supply the path. + + [!code-vb[VbFileIOWrite#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOWrite/VB/Class1.vb#1)] + +2. Use the `WriteAllText` method to write text to the specified file. + + [!code-vb[VbVbcnMyFileSystem#14](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#14)] + +## Example + + [!code-vb[VbFileIOWrite#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOWrite/VB/Class1.vb#2)] + +## Compiling the Code + + Replace `test.txt` with the name of the file you want to write to. + +## Robust Programming + + This code rethrows all the exceptions that may occur when writing text to the file. You can reduce the likelihood of exceptions by using Windows Forms controls such as the [OpenFileDialog](/dotnet/desktop/winforms/controls/openfiledialog-component-windows-forms) and the [SaveFileDialog](/dotnet/desktop/winforms/controls/savefiledialog-component-windows-forms) components that limit the user choices to valid file names. Using these controls is not foolproof, however. The file system can change between the time the user selects a file and the time that the code executes. Exception handling is therefore nearly always necessary when with working with files. + +## .NET Framework Security + + If you are running in a partial-trust context, the code might throw an exception due to insufficient privileges. For more information, see [Code Access Security Basics](/previous-versions/dotnet/framework/code-access-security/code-access-security-basics). + + This example creates a new file. If an application needs to create a file, that application needs Create permission for the folder. Permissions are set using access control lists. If the file already exists, the application needs only Write permission, a lesser privilege. Where possible, it is more secure to create the file during deployment, and only grant Read privileges to a single file, rather than to grant Create privileges for a folder. Also, it is more secure to write data to user folders than to the root folder or the **Program Files** folder. For more information, see [ACL Technology Overview](/previous-versions/dotnet/netframework-4.0/ms229742(v=vs.100)). + ## See also -- +- - - -- +- - diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-with-a-streamwriter.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-with-a-streamwriter.md index a123156608b8a..5a16f68fb6d78 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-with-a-streamwriter.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-with-a-streamwriter.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Write Text to Files with a StreamWriter in Visual Basic" title: "How to: Write Text to Files with a StreamWriter" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "files [Visual Basic], writing to" - "text, writing to files" - "writing to files [Visual Basic], StreamWriter" @@ -10,29 +10,29 @@ ms.assetid: 99762e57-ef46-4dcc-8959-a8f79c22f067 --- # How to: Write Text to Files with a StreamWriter in Visual Basic -This example opens a object with the `My.Computer.FileSystem.OpenTextFileWriter` method and uses it to write a string to a text file with the method of the class. - -## Example - - [!code-vb[VbFileIOWrite#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOWrite/VB/Class1.vb#5)] - -## Robust Programming - - The following conditions may cause an exception: - -- The file exists and is read-only (). - -- The disk is full (). - -- The pathname is too long (). - -## .NET Framework Security - - This example creates a new file, if the file does not already exist. If an application needs to create a file, that application needs `Create` access for the folder. If the file already exists, the application needs only `Write` access, a lesser privilege. Where possible, it is more secure to create the file during deployment, and only grant `Read` access to a single file, rather than `Create` access for a folder. - +This example opens a object with the `My.Computer.FileSystem.OpenTextFileWriter` method and uses it to write a string to a text file with the method of the class. + +## Example + + [!code-vb[VbFileIOWrite#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOWrite/VB/Class1.vb#5)] + +## Robust Programming + + The following conditions may cause an exception: + +- The file exists and is read-only (). + +- The disk is full (). + +- The pathname is too long (). + +## .NET Framework Security + + This example creates a new file, if the file does not already exist. If an application needs to create a file, that application needs `Create` access for the folder. If the file already exists, the application needs only `Write` access, a lesser privilege. Where possible, it is more secure to create the file during deployment, and only grant `Read` access to a single file, rather than `Create` access for a folder. + ## See also - -- +- - [How to: Read from Text Files](how-to-read-from-text-files.md) - [Writing to Files](writing-to-files.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files.md index dce0c81d54bd4..1fe7a18ede2c1 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Write Text to Files in Visual Basic" title: "How to: Write Text to Files" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "files [Visual Basic], writing to" - "text, writing to files" - "writing to files [Visual Basic]" @@ -11,48 +11,48 @@ ms.assetid: 304956eb-530d-4df7-b48f-9b4d1f2581a0 --- # How to: Write Text to Files in Visual Basic -The method can be used to write text to files. If the specified file does not exist, it is created. - -## Procedure - -#### To write text to a file - -- Use the `WriteAllText` method to write text to a file, specifying the file and text to be written. This example writes the line `"This is new text."` to the file named `test.txt`, appending the text to any existing text in the file. - - [!code-vb[VbFileIOWrite#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOWrite/VB/Class1.vb#3)] - -#### To write a series of strings to a file - -- Loop through the string collection. Use the `WriteAllText` method to write text to a file, specifying the target file and string to be added and setting `append` to `True`. - - This example writes the names of the files in the `Documents and Settings` directory to `FileList.txt`, inserting a carriage return between each for better readability. - - [!code-vb[VbFileIOWrite#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOWrite/VB/Class1.vb#4)] - -## Robust Programming - - The following conditions may cause an exception: - -- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). - -- The path is not valid because it is `Nothing` (). - -- `File` points to a path that does not exist ( or ). - -- The file is in use by another process, or an I/O error occurs (). - -- The path exceeds the system-defined maximum length (). - -- A file or directory name in the path contains a colon (:) or is in an invalid format (). - -- The user lacks necessary permissions to view the path (). - -- The disk is full, and the call to `WriteAllText` fails (). - - If you are running in a partial-trust context, the code might throw an exception due to insufficient privileges. For more information, see [Code Access Security Basics](/previous-versions/dotnet/framework/code-access-security/code-access-security-basics). - +The method can be used to write text to files. If the specified file does not exist, it is created. + +## Procedure + +#### To write text to a file + +- Use the `WriteAllText` method to write text to a file, specifying the file and text to be written. This example writes the line `"This is new text."` to the file named `test.txt`, appending the text to any existing text in the file. + + [!code-vb[VbFileIOWrite#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOWrite/VB/Class1.vb#3)] + +#### To write a series of strings to a file + +- Loop through the string collection. Use the `WriteAllText` method to write text to a file, specifying the target file and string to be added and setting `append` to `True`. + + This example writes the names of the files in the `Documents and Settings` directory to `FileList.txt`, inserting a carriage return between each for better readability. + + [!code-vb[VbFileIOWrite#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbFileIOWrite/VB/Class1.vb#4)] + +## Robust Programming + + The following conditions may cause an exception: + +- The path is not valid for one of the following reasons: it is a zero-length string, it contains only white space, it contains invalid characters, or it is a device path (starts with \\\\.\\) (). + +- The path is not valid because it is `Nothing` (). + +- `File` points to a path that does not exist ( or ). + +- The file is in use by another process, or an I/O error occurs (). + +- The path exceeds the system-defined maximum length (). + +- A file or directory name in the path contains a colon (:) or is in an invalid format (). + +- The user lacks necessary permissions to view the path (). + +- The disk is full, and the call to `WriteAllText` fails (). + + If you are running in a partial-trust context, the code might throw an exception due to insufficient privileges. For more information, see [Code Access Security Basics](/previous-versions/dotnet/framework/code-access-security/code-access-security-basics). + ## See also - -- +- - [How to: Read from Text Files](how-to-read-from-text-files.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-to-binary-files.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-to-binary-files.md index 55dc67bec2b35..b159721faa2fd 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-to-binary-files.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-to-binary-files.md @@ -10,7 +10,7 @@ ms.assetid: 59fae125-de5b-4c96-883c-209f4a55112c --- # How to: Write to Binary Files in Visual Basic -The method writes data to a binary file. If the `append` parameter is `True`, it will append the data to the file; otherwise data in the file is overwritten. +The method writes data to a binary file. If the `append` parameter is `True`, it will append the data to the file; otherwise data in the file is overwritten. If the specified path excluding the file name is not valid, a exception will be thrown. If the path is valid but the file does not exist, the file will be created. @@ -40,5 +40,5 @@ The following conditions may create an exception: ## See also -- +- - [How to: Write Text to Files](how-to-write-text-to-files.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/parsing-text-files-with-the-textfieldparser-object.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/parsing-text-files-with-the-textfieldparser-object.md index ca504ab0f9327..9637d6c70b905 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/parsing-text-files-with-the-textfieldparser-object.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/parsing-text-files-with-the-textfieldparser-object.md @@ -2,7 +2,7 @@ description: "Learn more about: Parsing text files with the TextFieldParser object (Visual Basic)" title: "Parsing text files with the TextFieldParser object" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "TextFieldParser object, using" - "I/O [Visual Basic], parsing files" - "files [Visual Basic], parsing" @@ -10,40 +10,40 @@ ms.assetid: fc31d6e6-af0c-403f-8a00-d556b2c57567 --- # Parsing text files with the TextFieldParser object (Visual Basic) -The `TextFieldParser` object allows you to parse and process very large file that are structured as delimited-width columns of text, such as log files or legacy database information. Parsing a text file with `TextFieldParser` is similar to iterating over a text file, while the parse method to extract fields of text is similar to string manipulation methods used to tokenize delimited strings. - -## Parsing different types of text files - - Text files may have fields of various width, delimited by a character such as a comma or a tab space. Define `TextFieldType` and the delimiter, as in the following example, which uses the `SetDelimiters` method to define a tab-delimited text file: - - [!code-vb[VbVbalrTextFieldParser#21](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrTextFieldParser/VB/Class1.vb#21)] - - Other text files may have field widths that are fixed. In such cases, you need to define the `TextFieldType` as `FixedWidth` and define the widths of each field, as in the following example. This example uses the `SetFieldWidths` method to define the columns of text: the first column is 5 characters wide, the second is 10, the third is 11, and the fourth is of variable width. - - [!code-vb[VbVbalrTextFieldParser#22](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrTextFieldParser/VB/Class1.vb#22)] - - Once the format is defined, you can loop through the file, using the `ReadFields` method to process each line in turn. - - If a field does not match the specified format, a exception is thrown. When such exceptions are thrown, the `ErrorLine` and `ErrorLineNumber` properties hold the text causing the exception and the line number of that text. - -## Parsing files with multiple formats - - The `PeekChars` method of the `TextFieldParser` object can be used to check each field before reading it, allowing you to define multiple formats for the fields and react accordingly. For more information, see [How to: Read From Text Files with Multiple Formats](how-to-read-from-text-files-with-multiple-formats.md). - +The `TextFieldParser` object allows you to parse and process very large file that are structured as delimited-width columns of text, such as log files or legacy database information. Parsing a text file with `TextFieldParser` is similar to iterating over a text file, while the parse method to extract fields of text is similar to string manipulation methods used to tokenize delimited strings. + +## Parsing different types of text files + + Text files may have fields of various width, delimited by a character such as a comma or a tab space. Define `TextFieldType` and the delimiter, as in the following example, which uses the `SetDelimiters` method to define a tab-delimited text file: + + [!code-vb[VbVbalrTextFieldParser#21](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrTextFieldParser/VB/Class1.vb#21)] + + Other text files may have field widths that are fixed. In such cases, you need to define the `TextFieldType` as `FixedWidth` and define the widths of each field, as in the following example. This example uses the `SetFieldWidths` method to define the columns of text: the first column is 5 characters wide, the second is 10, the third is 11, and the fourth is of variable width. + + [!code-vb[VbVbalrTextFieldParser#22](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrTextFieldParser/VB/Class1.vb#22)] + + Once the format is defined, you can loop through the file, using the `ReadFields` method to process each line in turn. + + If a field does not match the specified format, a exception is thrown. When such exceptions are thrown, the `ErrorLine` and `ErrorLineNumber` properties hold the text causing the exception and the line number of that text. + +## Parsing files with multiple formats + + The `PeekChars` method of the `TextFieldParser` object can be used to check each field before reading it, allowing you to define multiple formats for the fields and react accordingly. For more information, see [How to: Read From Text Files with Multiple Formats](how-to-read-from-text-files-with-multiple-formats.md). + ## See also -- +- - -- -- -- -- -- -- -- -- -- -- -- -- -- +- +- +- +- +- +- +- +- +- +- +- +- +- diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/reading-from-files.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/reading-from-files.md index de8e3feba48e2..9334e0a6524fe 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/reading-from-files.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/reading-from-files.md @@ -2,7 +2,7 @@ description: "Learn more about: Reading from Files in Visual Basic" title: "Reading from Files" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "data [Visual Basic], reading from files" - "I/O [Visual Basic], reading from files" - "examples [Visual Basic], reading from files" @@ -12,55 +12,55 @@ ms.assetid: ad831a1b-7d01-4f07-a47b-799f3037df19 --- # Reading from Files in Visual Basic -This section explains how to perform tasks that are associated with reading from files. - -## In This Section - - [How to: Read from Text Files](how-to-read-from-text-files.md) - Demonstrates how to read from a text file. - - [How to: Read From Comma-Delimited Text Files](how-to-read-from-comma-delimited-text-files.md) - Demonstrates how to read from a delimited text file. - - [How to: Read From Fixed-width Text Files](how-to-read-from-fixed-width-text-files.md) - Demonstrates how to read from a fixed-width text file. - - [How to: Read From Text Files with Multiple Formats](how-to-read-from-text-files-with-multiple-formats.md) - Demonstrates how to read from a text file with multiple formats. - - [How to: Read From Binary Files](how-to-read-from-binary-files.md) - Demonstrates how to read from a binary file. - - [How to: Read Text from Files with a StreamReader](how-to-read-text-from-files-with-a-streamreader.md) - Demonstrates how to use a to read from a file. - -## Reference - - - Describes the `My.Computer.FileSystem` object and its members. - - - Describes the `ReadAllText` method. - - - Describes the `ReadAllBytes` method. - - - Describes the `OpenTextFieldParser` method. - - - Describes the `OpenTextFileReader` method. - -## Related Sections - - [Storing Data to and Reading from the Clipboard](../computer-resources/storing-data-to-and-reading-from-the-clipboard.md) - Explains how to perform tasks that are associated with `My.Computer.Clipboard`, such as reading data from or writing data to the Clipboard. - - [Parsing Text Files with the TextFieldParser Object](parsing-text-files-with-the-textfieldparser-object.md) - Provides an overview of reading text files with the `TextFieldParser` object. - - [Walkthrough: Manipulating Files and Directories in Visual Basic](walkthrough-manipulating-files-and-directories.md) - Demonstrates how to use the `My` feature with files and directories. - - [Walkthrough: Manipulating Files by Using .NET Framework Methods](walkthrough-manipulating-files-by-using-net-framework-methods.md) +This section explains how to perform tasks that are associated with reading from files. + +## In This Section + + [How to: Read from Text Files](how-to-read-from-text-files.md) + Demonstrates how to read from a text file. + + [How to: Read From Comma-Delimited Text Files](how-to-read-from-comma-delimited-text-files.md) + Demonstrates how to read from a delimited text file. + + [How to: Read From Fixed-width Text Files](how-to-read-from-fixed-width-text-files.md) + Demonstrates how to read from a fixed-width text file. + + [How to: Read From Text Files with Multiple Formats](how-to-read-from-text-files-with-multiple-formats.md) + Demonstrates how to read from a text file with multiple formats. + + [How to: Read From Binary Files](how-to-read-from-binary-files.md) + Demonstrates how to read from a binary file. + + [How to: Read Text from Files with a StreamReader](how-to-read-text-from-files-with-a-streamreader.md) + Demonstrates how to use a to read from a file. + +## Reference + + + Describes the `My.Computer.FileSystem` object and its members. + + + Describes the `ReadAllText` method. + + + Describes the `ReadAllBytes` method. + + + Describes the `OpenTextFieldParser` method. + + + Describes the `OpenTextFileReader` method. + +## Related Sections + + [Storing Data to and Reading from the Clipboard](../computer-resources/storing-data-to-and-reading-from-the-clipboard.md) + Explains how to perform tasks that are associated with `My.Computer.Clipboard`, such as reading data from or writing data to the Clipboard. + + [Parsing Text Files with the TextFieldParser Object](parsing-text-files-with-the-textfieldparser-object.md) + Provides an overview of reading text files with the `TextFieldParser` object. + + [Walkthrough: Manipulating Files and Directories in Visual Basic](walkthrough-manipulating-files-and-directories.md) + Demonstrates how to use the `My` feature with files and directories. + + [Walkthrough: Manipulating Files by Using .NET Framework Methods](walkthrough-manipulating-files-by-using-net-framework-methods.md) Demonstrates how to use .NET Framework methods with files and directories. diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/walkthrough-manipulating-files-and-directories.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/walkthrough-manipulating-files-and-directories.md index fce9cc32e7ab2..dfbe92fda1381 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/walkthrough-manipulating-files-and-directories.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/walkthrough-manipulating-files-and-directories.md @@ -2,7 +2,7 @@ description: "Learn more about: Walkthrough: Manipulating Files and Directories in Visual Basic" title: "Manipulating Files and Directories" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "files [Visual Basic], reading text" - "reading files [Visual Basic], text" - "I/O [Visual Basic], walkthroughs" @@ -19,147 +19,147 @@ ms.assetid: cae77565-9f78-4e46-8e42-eb2f9f8e1ffd --- # Walkthrough: Manipulating Files and Directories in Visual Basic -This walkthrough provides an introduction to the fundamentals of file I/O in Visual Basic. It describes how to create a small application that lists and examines text files in a directory. For each selected text file, the application provides file attributes and the first line of content. There is an option to write information to a log file. - - This walkthrough uses members of the `My.Computer.FileSystem Object`, which are available in Visual Basic. See for more information. At the end of the walkthrough, an equivalent example is provided that uses classes from the namespace. - -[!INCLUDE[note_settings_general](~/includes/note-settings-general-md.md)] - -### To create the project - -1. On the **File** menu, click **New Project**. - - The **New Project** dialog box appears. - -2. In the **Installed Templates** pane, expand **Visual Basic**, and then click **Windows**. In the **Templates** pane in the middle, click **Windows Forms Application**. - -3. In the **Name** box, type `FileExplorer` to set the project name, and then click **OK**. - - Visual Studio adds the project to **Solution Explorer**, and the Windows Forms Designer opens. - -4. Add the controls in the following table to the form, and set the corresponding values for their properties. - - |Control|Property|Value| - |-------------|--------------|-----------| - |**ListBox**|**Name**|`filesListBox`| - |**Button**|**Name**

**Text**|`browseButton`

**Browse**| - |**Button**|**Name**

**Text**|`examineButton`

**Examine**| - |**CheckBox**|**Name**

**Text**|`saveCheckBox`

**Save Results**| - |**FolderBrowserDialog**|**Name**|`FolderBrowserDialog1`| - -### To select a folder, and list files in a folder - -1. Create a `Click` event handler for `browseButton` by double-clicking the control on the form. The Code Editor opens. - -2. Add the following code to the `Click` event handler. - - [!code-vb[VbVbcnMyFileSystem#103](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#103)] - - The `FolderBrowserDialog1.ShowDialog` call opens the **Browse For Folder** dialog box. After the user clicks **OK**, the property is sent as an argument to the `ListFiles` method, which is added in the next step. - -3. Add the following `ListFiles` method. - - [!code-vb[VbVbcnMyFileSystem#104](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#104)] - - This code first clears the **ListBox**. - - The method then retrieves a collection of strings, one for each file in the directory. The `GetFiles` method accepts a search pattern argument to retrieve files that match a particular pattern. In this example, only files that have the extension .txt are returned. - - The strings that are returned by the `GetFiles` method are then added to the **ListBox**. - -4. Run the application. Click the **Browse** button. In the **Browse For Folder** dialog box, browse to a folder that contains .txt files, and then select the folder and click **OK**. - - The `ListBox` contains a list of .txt files in the selected folder. - -5. Stop running the application. - -### To obtain attributes of a file, and content from a text file - -1. Create a `Click` event handler for `examineButton` by double-clicking the control on the form. - -2. Add the following code to the `Click` event handler. - - [!code-vb[VbVbcnMyFileSystem#105](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#105)] - - The code verifies that an item is selected in the `ListBox`. It then obtains the file path entry from the `ListBox`. The method is used to check whether the file still exists. - - The file path is sent as an argument to the `GetTextForOutput` method, which is added in the next step. This method returns a string that contains file information. The file information appears in a **MessageBox**. - -3. Add the following `GetTextForOutput` method. - - [!code-vb[VbVbcnMyFileSystem#107](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#107)] - - The code uses the method to obtain file parameters. The file parameters are added to a . - - The method reads the file contents into a . The first line of the contents is obtained from the `StreamReader` and is added to the `StringBuilder`. - -4. Run the application. Click **Browse**, and browse to a folder that contains .txt files. Click **OK**. - - Select a file in the `ListBox`, and then click **Examine**. A `MessageBox` shows the file information. - -5. Stop running the application. - -### To add a log entry - -1. Add the following code to the end of the `examineButton_Click` event handler. - - [!code-vb[VbVbcnMyFileSystem#106](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#106)] - - The code sets the log file path to put the log file in the same directory as that of the selected file. The text of the log entry is set to the current date and time followed by the file information. - - The method, with the `append` argument set to `True`, is used to create the log entry. - -2. Run the application. Browse to a text file, select it in the `ListBox`, select the **Save Results** check box, and then click **Examine**. Verify that the log entry is written to the `log.txt` file. - -3. Stop running the application. - -### To use the current directory - -1. Create an event handler for `Form1_Load` by double-clicking the form. - -2. Add the following code to the event handler. - - [!code-vb[VbVbcnMyFileSystem#102](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#102)] - - This code sets the default directory of the folder browser to the current directory. - -3. Run the application. When you click **Browse** the first time, the **Browse For Folder** dialog box opens to the current directory. - -4. Stop running the application. - -### To selectively enable controls - -1. Add the following `SetEnabled` method. - - [!code-vb[VbVbcnMyFileSystem#108](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#108)] - - The `SetEnabled` method enables or disables controls depending on whether an item is selected in the `ListBox`. - -2. Create a `SelectedIndexChanged` event handler for `filesListBox` by double-clicking the `ListBox` control on the form. - -3. Add a call to `SetEnabled` in the new `filesListBox_SelectedIndexChanged` event handler. - -4. Add a call to `SetEnabled` at the end of the `browseButton_Click` event handler. - -5. Add a call to `SetEnabled` at the end of the `Form1_Load` event handler. - -6. Run the application. The **Save Results** check box and the **Examine** button are disabled if an item is not selected in the `ListBox`. - -## Full example using My.Computer.FileSystem - - Following is the complete example. - - [!code-vb[VbVbcnMyFileSystem#101](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#101)] - -## Full example using System.IO - - The following equivalent example uses classes from the namespace instead of using `My.Computer.FileSystem` objects. - - [!code-vb[VbVbcnMyFileSystem#111](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class3.vb#111)] - +This walkthrough provides an introduction to the fundamentals of file I/O in Visual Basic. It describes how to create a small application that lists and examines text files in a directory. For each selected text file, the application provides file attributes and the first line of content. There is an option to write information to a log file. + + This walkthrough uses members of the `My.Computer.FileSystem Object`, which are available in Visual Basic. See for more information. At the end of the walkthrough, an equivalent example is provided that uses classes from the namespace. + +[!INCLUDE[note_settings_general](~/includes/note-settings-general-md.md)] + +### To create the project + +1. On the **File** menu, click **New Project**. + + The **New Project** dialog box appears. + +2. In the **Installed Templates** pane, expand **Visual Basic**, and then click **Windows**. In the **Templates** pane in the middle, click **Windows Forms Application**. + +3. In the **Name** box, type `FileExplorer` to set the project name, and then click **OK**. + + Visual Studio adds the project to **Solution Explorer**, and the Windows Forms Designer opens. + +4. Add the controls in the following table to the form, and set the corresponding values for their properties. + + |Control|Property|Value| + |-------------|--------------|-----------| + |**ListBox**|**Name**|`filesListBox`| + |**Button**|**Name**

**Text**|`browseButton`

**Browse**| + |**Button**|**Name**

**Text**|`examineButton`

**Examine**| + |**CheckBox**|**Name**

**Text**|`saveCheckBox`

**Save Results**| + |**FolderBrowserDialog**|**Name**|`FolderBrowserDialog1`| + +### To select a folder, and list files in a folder + +1. Create a `Click` event handler for `browseButton` by double-clicking the control on the form. The Code Editor opens. + +2. Add the following code to the `Click` event handler. + + [!code-vb[VbVbcnMyFileSystem#103](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#103)] + + The `FolderBrowserDialog1.ShowDialog` call opens the **Browse For Folder** dialog box. After the user clicks **OK**, the property is sent as an argument to the `ListFiles` method, which is added in the next step. + +3. Add the following `ListFiles` method. + + [!code-vb[VbVbcnMyFileSystem#104](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#104)] + + This code first clears the **ListBox**. + + The method then retrieves a collection of strings, one for each file in the directory. The `GetFiles` method accepts a search pattern argument to retrieve files that match a particular pattern. In this example, only files that have the extension .txt are returned. + + The strings that are returned by the `GetFiles` method are then added to the **ListBox**. + +4. Run the application. Click the **Browse** button. In the **Browse For Folder** dialog box, browse to a folder that contains .txt files, and then select the folder and click **OK**. + + The `ListBox` contains a list of .txt files in the selected folder. + +5. Stop running the application. + +### To obtain attributes of a file, and content from a text file + +1. Create a `Click` event handler for `examineButton` by double-clicking the control on the form. + +2. Add the following code to the `Click` event handler. + + [!code-vb[VbVbcnMyFileSystem#105](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#105)] + + The code verifies that an item is selected in the `ListBox`. It then obtains the file path entry from the `ListBox`. The method is used to check whether the file still exists. + + The file path is sent as an argument to the `GetTextForOutput` method, which is added in the next step. This method returns a string that contains file information. The file information appears in a **MessageBox**. + +3. Add the following `GetTextForOutput` method. + + [!code-vb[VbVbcnMyFileSystem#107](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#107)] + + The code uses the method to obtain file parameters. The file parameters are added to a . + + The method reads the file contents into a . The first line of the contents is obtained from the `StreamReader` and is added to the `StringBuilder`. + +4. Run the application. Click **Browse**, and browse to a folder that contains .txt files. Click **OK**. + + Select a file in the `ListBox`, and then click **Examine**. A `MessageBox` shows the file information. + +5. Stop running the application. + +### To add a log entry + +1. Add the following code to the end of the `examineButton_Click` event handler. + + [!code-vb[VbVbcnMyFileSystem#106](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#106)] + + The code sets the log file path to put the log file in the same directory as that of the selected file. The text of the log entry is set to the current date and time followed by the file information. + + The method, with the `append` argument set to `True`, is used to create the log entry. + +2. Run the application. Browse to a text file, select it in the `ListBox`, select the **Save Results** check box, and then click **Examine**. Verify that the log entry is written to the `log.txt` file. + +3. Stop running the application. + +### To use the current directory + +1. Create an event handler for `Form1_Load` by double-clicking the form. + +2. Add the following code to the event handler. + + [!code-vb[VbVbcnMyFileSystem#102](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#102)] + + This code sets the default directory of the folder browser to the current directory. + +3. Run the application. When you click **Browse** the first time, the **Browse For Folder** dialog box opens to the current directory. + +4. Stop running the application. + +### To selectively enable controls + +1. Add the following `SetEnabled` method. + + [!code-vb[VbVbcnMyFileSystem#108](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#108)] + + The `SetEnabled` method enables or disables controls depending on whether an item is selected in the `ListBox`. + +2. Create a `SelectedIndexChanged` event handler for `filesListBox` by double-clicking the `ListBox` control on the form. + +3. Add a call to `SetEnabled` in the new `filesListBox_SelectedIndexChanged` event handler. + +4. Add a call to `SetEnabled` at the end of the `browseButton_Click` event handler. + +5. Add a call to `SetEnabled` at the end of the `Form1_Load` event handler. + +6. Run the application. The **Save Results** check box and the **Examine** button are disabled if an item is not selected in the `ListBox`. + +## Full example using My.Computer.FileSystem + + Following is the complete example. + + [!code-vb[VbVbcnMyFileSystem#101](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class2.vb#101)] + +## Full example using System.IO + + The following equivalent example uses classes from the namespace instead of using `My.Computer.FileSystem` objects. + + [!code-vb[VbVbcnMyFileSystem#111](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/class3.vb#111)] + ## See also - - -- +- - [Walkthrough: Manipulating Files by Using .NET Framework Methods](walkthrough-manipulating-files-by-using-net-framework-methods.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/walkthrough-manipulating-files-by-using-net-framework-methods.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/walkthrough-manipulating-files-by-using-net-framework-methods.md index ecf2a123d3270..3bfd5c6748441 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/walkthrough-manipulating-files-by-using-net-framework-methods.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/walkthrough-manipulating-files-by-using-net-framework-methods.md @@ -66,7 +66,7 @@ To add the ability to write to a file via the application, use the [!NOTE] > The Visual Studio Integrated Development Environment (IDE) will return to the Code Editor and position the insertion point within the event handler where you should add the code. -1. To write to the file, use the method of the class. Add the following code directly after `Dim fw As StreamWriter`. You do not need to worry that an exception will be thrown if the file is not found, because it will be created if it does not already exist. +1. To write to the file, use the method of the class. Add the following code directly after `Dim fw As StreamWriter`. You do not need to worry that an exception will be thrown if the file is not found, because it will be created if it does not already exist. [!code-vb[VbVbcnMyFileSystem#37](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnMyFileSystem/VB/Class1.vb#37)] diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/writing-to-files.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/writing-to-files.md index fb9d8efd5d24c..e3b51fcf1fd3f 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/writing-to-files.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/writing-to-files.md @@ -2,7 +2,7 @@ description: "Learn more about: Writing to Files in Visual Basic" title: "Writing to Files" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "I/O [Visual Basic], writing to files" - "files [Visual Basic], writing to" - "examples [Visual Basic], writing to files" @@ -12,49 +12,49 @@ ms.assetid: ac6fb453-0d6c-4ce4-93b4-1bbcd06de83e --- # Writing to Files in Visual Basic -This section explains how to perform tasks that involve writing to files. - -## In This Section - - [How to: Write Text to Files](how-to-write-text-to-files.md) - Demonstrates how to write to text files. - - [How to: Append to Text Files](how-to-append-to-text-files.md) - Demonstrates how to append text to a text file. - - [How to: Write to Binary Files](how-to-write-to-binary-files.md) - Demonstrates how to write to a binary file. - - [How to: Write Text to Files in the My Documents Directory](how-to-write-text-to-files-in-the-my-documents-directory.md) - Demonstrates how to create and write to a new text file in the **My Documents** directory. - - [How to: Write Text to Files with a StreamWriter](how-to-write-text-to-files-with-a-streamwriter.md) - Demonstrates how to write to a file with a object. - -## Reference - - - Describes the `My.Computer.FileSystem` object and its methods and properties. - - - Describes the `OpenTextFileWriter` method. - - - Describes the `WriteAllBytes` method. - - - Describes the `WriteAllText` method. - -## Related Sections - - [Reading from Files](reading-from-files.md) - Explains how to perform tasks that involve reading from files. - - [Creating, Deleting, and Moving Files and Directories](creating-deleting-and-moving-files-and-directories.md) - Explains how to perform tasks that involve creating, deleting, moving, and renaming files and directories. - - [Storing Data to and Reading from the Clipboard](../computer-resources/storing-data-to-and-reading-from-the-clipboard.md) - Explains how to perform tasks that are associated with `My.Computer.Clipboard`, such as reading data from or writing data to the Clipboard. - - [File Encodings](file-encodings.md) +This section explains how to perform tasks that involve writing to files. + +## In This Section + + [How to: Write Text to Files](how-to-write-text-to-files.md) + Demonstrates how to write to text files. + + [How to: Append to Text Files](how-to-append-to-text-files.md) + Demonstrates how to append text to a text file. + + [How to: Write to Binary Files](how-to-write-to-binary-files.md) + Demonstrates how to write to a binary file. + + [How to: Write Text to Files in the My Documents Directory](how-to-write-text-to-files-in-the-my-documents-directory.md) + Demonstrates how to create and write to a new text file in the **My Documents** directory. + + [How to: Write Text to Files with a StreamWriter](how-to-write-text-to-files-with-a-streamwriter.md) + Demonstrates how to write to a file with a object. + +## Reference + + + Describes the `My.Computer.FileSystem` object and its methods and properties. + + + Describes the `OpenTextFileWriter` method. + + + Describes the `WriteAllBytes` method. + + + Describes the `WriteAllText` method. + +## Related Sections + + [Reading from Files](reading-from-files.md) + Explains how to perform tasks that involve reading from files. + + [Creating, Deleting, and Moving Files and Directories](creating-deleting-and-moving-files-and-directories.md) + Explains how to perform tasks that involve creating, deleting, moving, and renaming files and directories. + + [Storing Data to and Reading from the Clipboard](../computer-resources/storing-data-to-and-reading-from-the-clipboard.md) + Explains how to perform tasks that are associated with `My.Computer.Clipboard`, such as reading data from or writing data to the Clipboard. + + [File Encodings](file-encodings.md) Provides an overview of file encodings. diff --git a/docs/visual-basic/developing-apps/programming/log-info/how-to-log-exceptions.md b/docs/visual-basic/developing-apps/programming/log-info/how-to-log-exceptions.md index 0d441cc469c3d..9269bd49cfbae 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/how-to-log-exceptions.md +++ b/docs/visual-basic/developing-apps/programming/log-info/how-to-log-exceptions.md @@ -2,70 +2,70 @@ description: "Learn more about: How to: Log Exceptions in Visual Basic" title: "How to: Log Exceptions" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "exceptions, logging" - "exceptions, tracking" ms.assetid: a26c60e2-ae39-444a-aebb-33eccadc0eeb --- # How to: Log Exceptions in Visual Basic -You can use the `My.Application.Log` and `My.Log` objects to log information about exceptions that occur in your application. These examples show how to use the `My.Application.Log.WriteException` method to log exceptions that you catch explicitly and exceptions that are unhandled. - - For logging tracing information, use the `My.Application.Log.WriteEntry` method. For more information, see - -### To log a handled exception - -1. Create the method that will generate the exception information. - - [!code-vb[VbVbalrMyApplicationLog#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#9)] - -2. Use a `Try...Catch` block to catch the exception. - - [!code-vb[VbVbalrMyApplicationLog#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#6)] - -3. Put the code that could generate an exception in the `Try` block. - - Uncomment the `Dim` and `MsgBox` lines to cause a exception. - - [!code-vb[VbVbalrMyApplicationLog#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#7)] - -4. In the `Catch` block, use the `My.Application.Log.WriteException` method to write the exception information. - - [!code-vb[VbVbalrMyApplicationLog#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#8)] - - The following example shows the complete code for logging a handled exception. - - [!code-vb[VbVbalrMyApplicationLog#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#10)] - -### To log an unhandled exception - -1. Have a project selected in **Solution Explorer**. On the **Project** menu, choose **Properties**. - -2. Click the **Application** tab. - -3. Click the **View Application Events** button to open the Code Editor. - - This opens the ApplicationEvents.vb file. - -4. Have the ApplicationEvents.vb file open in the Code Editor. On the **General** menu, choose **MyApplication Events**. - -5. On the **Declarations** menu, choose **UnhandledException**. - - The application raises the event before the main application runs. - -6. Add the `My.Application.Log.WriteException` method to the `UnhandledException` event handler. - - [!code-vb[VbVbalrMyApplicationLog#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/MyEventsFake.vb#4)] - - The following example shows the complete code for logging an unhandled exception. - - [!code-vb[VbVbalrMyApplicationLog#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/MyEventsFake.vb#5)] - +You can use the `My.Application.Log` and `My.Log` objects to log information about exceptions that occur in your application. These examples show how to use the `My.Application.Log.WriteException` method to log exceptions that you catch explicitly and exceptions that are unhandled. + + For logging tracing information, use the `My.Application.Log.WriteEntry` method. For more information, see + +### To log a handled exception + +1. Create the method that will generate the exception information. + + [!code-vb[VbVbalrMyApplicationLog#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#9)] + +2. Use a `Try...Catch` block to catch the exception. + + [!code-vb[VbVbalrMyApplicationLog#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#6)] + +3. Put the code that could generate an exception in the `Try` block. + + Uncomment the `Dim` and `MsgBox` lines to cause a exception. + + [!code-vb[VbVbalrMyApplicationLog#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#7)] + +4. In the `Catch` block, use the `My.Application.Log.WriteException` method to write the exception information. + + [!code-vb[VbVbalrMyApplicationLog#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#8)] + + The following example shows the complete code for logging a handled exception. + + [!code-vb[VbVbalrMyApplicationLog#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#10)] + +### To log an unhandled exception + +1. Have a project selected in **Solution Explorer**. On the **Project** menu, choose **Properties**. + +2. Click the **Application** tab. + +3. Click the **View Application Events** button to open the Code Editor. + + This opens the ApplicationEvents.vb file. + +4. Have the ApplicationEvents.vb file open in the Code Editor. On the **General** menu, choose **MyApplication Events**. + +5. On the **Declarations** menu, choose **UnhandledException**. + + The application raises the event before the main application runs. + +6. Add the `My.Application.Log.WriteException` method to the `UnhandledException` event handler. + + [!code-vb[VbVbalrMyApplicationLog#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/MyEventsFake.vb#4)] + + The following example shows the complete code for logging an unhandled exception. + + [!code-vb[VbVbalrMyApplicationLog#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/MyEventsFake.vb#5)] + ## See also - -- -- +- +- - [Working with Application Logs](working-with-application-logs.md) - [How to: Write Log Messages](how-to-write-log-messages.md) - [Walkthrough: Determining Where My.Application.Log Writes Information](walkthrough-determining-where-my-application-log-writes-information.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/how-to-log-messages-when-the-application-starts-or-shuts-down.md b/docs/visual-basic/developing-apps/programming/log-info/how-to-log-messages-when-the-application-starts-or-shuts-down.md index 1d6c6d881b0e4..298399be51c32 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/how-to-log-messages-when-the-application-starts-or-shuts-down.md +++ b/docs/visual-basic/developing-apps/programming/log-info/how-to-log-messages-when-the-application-starts-or-shuts-down.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Log Messages When the Application Starts or Shuts Down (Visual Basic)" title: "How to: Log Messages When the Application Starts or Shuts Down" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "event logs, shutdown" - "My.Application.Log object, logging" - "Startup event [Visual Basic]" @@ -13,52 +13,52 @@ ms.assetid: 67624d05-cddf-48b7-8c36-5c99baa4c621 --- # How to: Log Messages When the Application Starts or Shuts Down (Visual Basic) -You can use the `My.Application.Log` and `My.Log` objects to log information about events that occur in your application. This example shows how to use the `My.Application.Log.WriteEntry` method with the `Startup` and `Shutdown` events to write tracing information. - -### To access the application's event-handler code - -1. Have a project selected in **Solution Explorer**. On the **Project** menu, choose **Properties**. - -2. Click the **Application** tab. - -3. Click the **View Application Events** button to open the Code Editor. - - This opens the ApplicationEvents.vb file. - -### To log messages when the application starts - -1. Have the ApplicationEvents.vb file open in the Code Editor. On the **General** menu, choose **MyApplication Events**. - -2. On the **Declarations** menu, choose **Startup**. - - The application raises the event before the main application runs. - -3. Add the `My.Application.Log.WriteEntry` method to the `Startup` event handler. - - [!code-vb[VbVbalrMyApplicationLog#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/MyEventsFake.vb#1)] - -### To log messages when the application shuts down - -1. Have the ApplicationEvents.vb file open in the Code Editor. On the **General** menu, choose **MyApplication Events**. - -2. On the **Declarations** menu, choose **Shutdown**. - - The application raises the event after the main application runs, but before it shuts down. - -3. Add the `My.Application.Log.WriteEntry` method to the `Shutdown` event handler. - - [!code-vb[VbVbalrMyApplicationLog#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/MyEventsFake.vb#2)] - -## Example - - You can use the **Project Designer** to access the application events in the Code Editor. For more information, see [Application Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/application-page-project-designer-visual-basic). - - [!code-vb[VbVbalrMyApplicationLog#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/MyEventsFake.vb#3)] - +You can use the `My.Application.Log` and `My.Log` objects to log information about events that occur in your application. This example shows how to use the `My.Application.Log.WriteEntry` method with the `Startup` and `Shutdown` events to write tracing information. + +### To access the application's event-handler code + +1. Have a project selected in **Solution Explorer**. On the **Project** menu, choose **Properties**. + +2. Click the **Application** tab. + +3. Click the **View Application Events** button to open the Code Editor. + + This opens the ApplicationEvents.vb file. + +### To log messages when the application starts + +1. Have the ApplicationEvents.vb file open in the Code Editor. On the **General** menu, choose **MyApplication Events**. + +2. On the **Declarations** menu, choose **Startup**. + + The application raises the event before the main application runs. + +3. Add the `My.Application.Log.WriteEntry` method to the `Startup` event handler. + + [!code-vb[VbVbalrMyApplicationLog#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/MyEventsFake.vb#1)] + +### To log messages when the application shuts down + +1. Have the ApplicationEvents.vb file open in the Code Editor. On the **General** menu, choose **MyApplication Events**. + +2. On the **Declarations** menu, choose **Shutdown**. + + The application raises the event after the main application runs, but before it shuts down. + +3. Add the `My.Application.Log.WriteEntry` method to the `Shutdown` event handler. + + [!code-vb[VbVbalrMyApplicationLog#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/MyEventsFake.vb#2)] + +## Example + + You can use the **Project Designer** to access the application events in the Code Editor. For more information, see [Application Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/application-page-project-designer-visual-basic). + + [!code-vb[VbVbalrMyApplicationLog#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/MyEventsFake.vb#3)] + ## See also - -- -- +- +- - [Application Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/application-page-project-designer-visual-basic) - [Working with Application Logs](working-with-application-logs.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/how-to-write-event-information-to-a-text-file.md b/docs/visual-basic/developing-apps/programming/log-info/how-to-write-event-information-to-a-text-file.md index c9b3a738c1c49..babce44bf49a8 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/how-to-write-event-information-to-a-text-file.md +++ b/docs/visual-basic/developing-apps/programming/log-info/how-to-write-event-information-to-a-text-file.md @@ -53,7 +53,7 @@ You can use the `My.Application.Log` and `My.Log` objects to log information abo Change the value of the `customlocation` attribute to the log directory. > [!NOTE] - > To set the value of a listener property, use an attribute that has the same name as the property, with all letters in the name lowercase. For example, the `location` and `customlocation` attributes set the values of the and properties. + > To set the value of a listener property, use an attribute that has the same name as the property, with all letters in the name lowercase. For example, the `location` and `customlocation` attributes set the values of the and properties. ### To write event information to the file log @@ -64,7 +64,7 @@ After you configure the file log listener for an assembly, it receives all messa ## See also - -- -- +- +- - [Working with Application Logs](working-with-application-logs.md) - [How to: Log Exceptions](how-to-log-exceptions.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/how-to-write-log-messages.md b/docs/visual-basic/developing-apps/programming/log-info/how-to-write-log-messages.md index a040ed520df42..d4311e75168f3 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/how-to-write-log-messages.md +++ b/docs/visual-basic/developing-apps/programming/log-info/how-to-write-log-messages.md @@ -26,8 +26,8 @@ Make sure the data you write to the log does not include sensitive information s ## See also - -- -- +- +- - [Working with Application Logs](working-with-application-logs.md) - [How to: Log Exceptions](how-to-log-exceptions.md) - [Walkthrough: Determining Where My.Application.Log Writes Information](walkthrough-determining-where-my-application-log-writes-information.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/how-to-write-to-an-application-event-log.md b/docs/visual-basic/developing-apps/programming/log-info/how-to-write-to-an-application-event-log.md index bc30b6bafe131..b764a33206d47 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/how-to-write-to-an-application-event-log.md +++ b/docs/visual-basic/developing-apps/programming/log-info/how-to-write-to-an-application-event-log.md @@ -66,8 +66,8 @@ After you configure the event log listener for an assembly, it receives all mess ## See also - -- -- +- +- - [Working with Application Logs](working-with-application-logs.md) - [How to: Log Exceptions](how-to-log-exceptions.md) - [Walkthrough: Determining Where My.Application.Log Writes Information](walkthrough-determining-where-my-application-log-writes-information.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/troubleshooting-log-listeners.md b/docs/visual-basic/developing-apps/programming/log-info/troubleshooting-log-listeners.md index 8527401367c61..482d29bdb6a49 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/troubleshooting-log-listeners.md +++ b/docs/visual-basic/developing-apps/programming/log-info/troubleshooting-log-listeners.md @@ -2,7 +2,7 @@ description: "Learn more about: Troubleshooting: Log Listeners (Visual Basic)" title: "Troubleshooting: Log Listeners" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "event logs, troubleshooting" - "troubleshooting Visual Basic, event logs" - "troubleshooting event logs" @@ -10,30 +10,30 @@ ms.assetid: ac6eb760-3d5d-461e-aedd-40599ee22e49 --- # Troubleshooting: Log Listeners (Visual Basic) -You can use the `My.Application.Log` and `My.Log` objects to log information about events that occur in your application. - - To determine which log listeners receive those messages, see [Walkthrough: Determining Where My.Application.Log Writes Information](walkthrough-determining-where-my-application-log-writes-information.md). - - The `Log` object can use log filtering to limit the amount of information that it logs. If the filters are misconfigured, the logs might contain the wrong information. For more information about filtering, see [Walkthrough: Filtering My.Application.Log Output](walkthrough-filtering-my-application-log-output.md). - - However, if a log is configured incorrectly, you may need more information about its current configuration. You can get to this information through the log's advanced `TraceSource` property. - -### To determine the log listeners for the Log object in code - -1. Import the namespace at the beginning of the code file. For more information, see [Imports Statement (.NET Namespace and Type)](../../../language-reference/statements/imports-statement-net-namespace-and-type.md). - - [!code-vb[VbVbalrMyApplicationLog#13](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#13)] - -2. Create a function that returns a string consisting of information for each of the log's listeners. - - [!code-vb[VbVbalrMyApplicationLog#14](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#14)] - -3. Pass the collection of the log's trace listeners to the `GetListeners` function, and display the return value. - - [!code-vb[VbVbalrMyApplicationLog#19](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#19)] - - For more information, see . - +You can use the `My.Application.Log` and `My.Log` objects to log information about events that occur in your application. + + To determine which log listeners receive those messages, see [Walkthrough: Determining Where My.Application.Log Writes Information](walkthrough-determining-where-my-application-log-writes-information.md). + + The `Log` object can use log filtering to limit the amount of information that it logs. If the filters are misconfigured, the logs might contain the wrong information. For more information about filtering, see [Walkthrough: Filtering My.Application.Log Output](walkthrough-filtering-my-application-log-output.md). + + However, if a log is configured incorrectly, you may need more information about its current configuration. You can get to this information through the log's advanced `TraceSource` property. + +### To determine the log listeners for the Log object in code + +1. Import the namespace at the beginning of the code file. For more information, see [Imports Statement (.NET Namespace and Type)](../../../language-reference/statements/imports-statement-net-namespace-and-type.md). + + [!code-vb[VbVbalrMyApplicationLog#13](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#13)] + +2. Create a function that returns a string consisting of information for each of the log's listeners. + + [!code-vb[VbVbalrMyApplicationLog#14](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#14)] + +3. Pass the collection of the log's trace listeners to the `GetListeners` function, and display the return value. + + [!code-vb[VbVbalrMyApplicationLog#19](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#19)] + + For more information, see . + ## See also - diff --git a/docs/visual-basic/developing-apps/programming/log-info/walkthrough-creating-custom-log-listeners.md b/docs/visual-basic/developing-apps/programming/log-info/walkthrough-creating-custom-log-listeners.md index 3336b8b9671ff..d943581e8976d 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/walkthrough-creating-custom-log-listeners.md +++ b/docs/visual-basic/developing-apps/programming/log-info/walkthrough-creating-custom-log-listeners.md @@ -21,9 +21,9 @@ Log listeners must inherit from the clas [!code-vb[VbVbalrMyApplicationLog#16](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrMyApplicationLog/VB/Form1.vb#16)] - The and methods, required by the base class, call `MsgBox` to display their input. + The and methods, required by the base class, call `MsgBox` to display their input. - The attribute is applied to the and methods so that their attributes match the base class methods. The attribute allows the host that runs the code to determine that the code exposes host-protection synchronization. + The attribute is applied to the and methods so that their attributes match the base class methods. The attribute allows the host that runs the code to determine that the code exposes host-protection synchronization. > [!NOTE] > The attribute is effective only on unmanaged applications that host the common language runtime and that implement host protection, such as SQL Server. diff --git a/docs/visual-basic/developing-apps/programming/log-info/walkthrough-filtering-my-application-log-output.md b/docs/visual-basic/developing-apps/programming/log-info/walkthrough-filtering-my-application-log-output.md index 136c674b2f623..f11bb3485aede 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/walkthrough-filtering-my-application-log-output.md +++ b/docs/visual-basic/developing-apps/programming/log-info/walkthrough-filtering-my-application-log-output.md @@ -43,7 +43,7 @@ Each message that `My.Application.Log` writes has an associated severity level, > [!NOTE] > By default, the application flushes the log-file output when the application closes. - In the example above, the second call to the method and the call to the method produces log output, while the first and last calls to the `WriteEntry` method do not. This is because the severity levels of `WriteEntry` and `WriteException` are "Information" and "Error", both of which are allowed by the `My.Application.Log` object's default log filtering. However, events with "Start" and "Stop" severity levels are prevented from producing log output. + In the example above, the second call to the method and the call to the method produces log output, while the first and last calls to the `WriteEntry` method do not. This is because the severity levels of `WriteEntry` and `WriteException` are "Information" and "Error", both of which are allowed by the `My.Application.Log` object's default log filtering. However, events with "Start" and "Stop" severity levels are prevented from producing log output. ## Filtering for All My.Application.Log Listeners diff --git a/docs/visual-basic/developing-apps/programming/log-info/working-with-application-logs.md b/docs/visual-basic/developing-apps/programming/log-info/working-with-application-logs.md index bed5d9d0e01b1..f11a4249a40d4 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/working-with-application-logs.md +++ b/docs/visual-basic/developing-apps/programming/log-info/working-with-application-logs.md @@ -15,7 +15,7 @@ The `My.Application.Log` and `My.Log` objects make it easy to write logging and ## How Messages are Logged -First, the severity of the message is checked with the property of the log's property. By default, only messages of severity "Information" and higher are passed on to the trace listeners, specified in the log's `TraceListener` collection. Then, each listener compares the severity of the message to the listener's property. If the message's severity is high enough, the listener writes out the message. +First, the severity of the message is checked with the property of the log's property. By default, only messages of severity "Information" and higher are passed on to the trace listeners, specified in the log's `TraceListener` collection. Then, each listener compares the severity of the message to the listener's property. If the message's severity is high enough, the listener writes out the message. The following diagram shows how a message written to the `WriteEntry` method gets passed to the `WriteLine` methods of the log's trace listeners: @@ -31,7 +31,7 @@ If the assembly has no configuration file, the `My.Application.Log` and `My.Log` The debug output can be viewed in the Visual Studio **Output** window when running your application in debug mode. To open the **Output** window, click the **Debug** menu item, point to **Windows**, and then click **Output**. In the **Output** window, select **Debug** from the **Show output from** box. -By default, `My.Application.Log` writes the log file in the path for the user's application data. You can get the path from the property of the object. The format of that path is as follows: +By default, `My.Application.Log` writes the log file in the path for the user's application data. You can get the path from the property of the object. The format of that path is as follows: `BasePath`\\`CompanyName`\\`ProductName`\\`ProductVersion` diff --git a/docs/visual-basic/language-reference/constants-and-enumerations.md b/docs/visual-basic/language-reference/constants-and-enumerations.md index eb952d80f2eb6..f0f6ed3c219a0 100644 --- a/docs/visual-basic/language-reference/constants-and-enumerations.md +++ b/docs/visual-basic/language-reference/constants-and-enumerations.md @@ -3,7 +3,7 @@ description: "Learn more about: Constants and Enumerations (Visual Basic)" title: "Constants and Enumerations (Visual Basic)" titleSuffix: "" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "enumerations [Visual Basic]" - "constants [Visual Basic]" - "constants [Visual Basic], list of" @@ -11,72 +11,72 @@ ms.assetid: 309c0ad5-83e4-4f96-99ea-83cd95107417 --- # Constants and Enumerations (Visual Basic) -Visual Basic supplies a number of predefined constants and enumerations for developers. Constants store values that remain constant throughout the execution of an application. Enumerations provide a convenient way to work with sets of related constants, and to associate constant values with names. - -## Constants - -### Conditional Compilation Constants +Visual Basic supplies a number of predefined constants and enumerations for developers. Constants store values that remain constant throughout the execution of an application. Enumerations provide a convenient way to work with sets of related constants, and to associate constant values with names. - The following table lists the predefined constants available for conditional compilation. - -|**Constant**|**Description**| -|---|---| -|`CONFIG`|A string that corresponds to the current setting of the **Active Solution Configuration** box in the **Configuration Manager**.| -|`DEBUG`|A `Boolean` value that can be set in the **Project Properties** dialog box. By default, the Debug configuration for a project defines `DEBUG`. When `DEBUG` is defined, class methods generate output to the **Output** window. When it is not defined, class methods are not compiled and no Debug output is generated.| -|`TARGET`|A string representing the output type for the project or the setting of the command-line **-target** option. The possible values of `TARGET` are:

- "winexe" for a Windows application.
- "exe" for a console application.
- "library" for a class library.
- "module" for a module.
- The **-target** option may be set in the Visual Studio integrated development environment. For more information, see [-target (Visual Basic)](../reference/command-line-compiler/target.md).| -|`TRACE`|A `Boolean` value that can be set in the **Project Properties** dialog box. By default, all configurations for a project define `TRACE`. When `TRACE` is defined, class methods generate output to the **Output** window. When it is not defined, class methods are not compiled and no `Trace` output is generated.| -|`VBC_VER`|A number representing the Visual Basic version, in *major*.*minor* format.| - -### Print and Display Constants +## Constants - When you call print and display functions, you can use the following constants in your code in place of the actual values. - -|**Constant**|**Description**| -|---|---| -|`vbCrLf`|Carriage return/linefeed character combination.| -|`vbCr`|Carriage return character.| -|`vbLf`|Linefeed character.| -|`vbNewLine`|Newline character.| -|`vbNullChar`|Null character.| -|`vbNullString`|Not the same as a zero-length string (""); used for calling external procedures.| -|`vbObjectError`|Error number. User-defined error numbers should be greater than this value. For example:

`Err.Raise(Number) = vbObjectError + 1000`| -|`vbTab`|Tab character.| -|`vbBack`|Backspace character.| -|`vbFormFeed`|Not used in Microsoft Windows.| -|`vbVerticalTab`|Not useful in Microsoft Windows.| - -## Enumerations +### Conditional Compilation Constants + + The following table lists the predefined constants available for conditional compilation. + +|**Constant**|**Description**| +|---|---| +|`CONFIG`|A string that corresponds to the current setting of the **Active Solution Configuration** box in the **Configuration Manager**.| +|`DEBUG`|A `Boolean` value that can be set in the **Project Properties** dialog box. By default, the Debug configuration for a project defines `DEBUG`. When `DEBUG` is defined, class methods generate output to the **Output** window. When it is not defined, class methods are not compiled and no Debug output is generated.| +|`TARGET`|A string representing the output type for the project or the setting of the command-line **-target** option. The possible values of `TARGET` are:

- "winexe" for a Windows application.
- "exe" for a console application.
- "library" for a class library.
- "module" for a module.
- The **-target** option may be set in the Visual Studio integrated development environment. For more information, see [-target (Visual Basic)](../reference/command-line-compiler/target.md).| +|`TRACE`|A `Boolean` value that can be set in the **Project Properties** dialog box. By default, all configurations for a project define `TRACE`. When `TRACE` is defined, class methods generate output to the **Output** window. When it is not defined, class methods are not compiled and no `Trace` output is generated.| +|`VBC_VER`|A number representing the Visual Basic version, in *major*.*minor* format.| + +### Print and Display Constants + + When you call print and display functions, you can use the following constants in your code in place of the actual values. + +|**Constant**|**Description**| +|---|---| +|`vbCrLf`|Carriage return/linefeed character combination.| +|`vbCr`|Carriage return character.| +|`vbLf`|Linefeed character.| +|`vbNewLine`|Newline character.| +|`vbNullChar`|Null character.| +|`vbNullString`|Not the same as a zero-length string (""); used for calling external procedures.| +|`vbObjectError`|Error number. User-defined error numbers should be greater than this value. For example:

`Err.Raise(Number) = vbObjectError + 1000`| +|`vbTab`|Tab character.| +|`vbBack`|Backspace character.| +|`vbFormFeed`|Not used in Microsoft Windows.| +|`vbVerticalTab`|Not useful in Microsoft Windows.| + +## Enumerations + + The following table lists and describes the enumerations provided by Visual Basic. + +|Enumeration|Description| +|---|---| +||Indicates the window style to use for the invoked program when calling the function.| +||Indicates how to play sounds when calling audio methods.| +||Indicates the type of role to check when calling the method.| +||Indicates the type of procedure being invoked when calling the function.| +||Indicates how to compare strings when calling comparison functions.| +||Indicates how to display dates when calling the function.| +||Indicates how to determine and format date intervals when calling date-related functions.| +||Specifies what should be done when a directory that is to be deleted contains files or directories.| +||Indicates when payments are due when calling financial methods.| +||Indicates whether text fields are delimited or fixed-width.| +||Indicates the file attributes to use when calling file-access functions.| +||Indicates the first day of the week to use when calling date-related functions.| +||Indicates the first week of the year to use when calling date-related functions.| +||Indicates which button was pressed on a message box, returned by the function.| +||Indicates which buttons to display when calling the function.| +||Indicates how to open a file when calling file-access functions.| +||Indicates how to open a file when calling file-access functions.| +||Indicates how to open a file when calling file-access functions.| +||Specifies whether a file should be deleted permanently or placed in the Recycle Bin.| +||Specifies whether to search all or only top-level directories.| +||Indicates a `Boolean` value or whether the default should be used when calling number-formatting functions.| +||Specifies what should be done if the user clicks **Cancel** during an operation.| +||Specifies whether or not to show a progress dialog when copying, deleting, or moving files or directories.| +||Indicates the type of a variant object, returned by the function.| +||Indicates which type of conversion to perform when calling the function.| - The following table lists and describes the enumerations provided by Visual Basic. - -|Enumeration|Description| -|---|---| -||Indicates the window style to use for the invoked program when calling the function.| -||Indicates how to play sounds when calling audio methods.| -||Indicates the type of role to check when calling the method.| -||Indicates the type of procedure being invoked when calling the function.| -||Indicates how to compare strings when calling comparison functions.| -||Indicates how to display dates when calling the function.| -||Indicates how to determine and format date intervals when calling date-related functions.| -||Specifies what should be done when a directory that is to be deleted contains files or directories.| -||Indicates when payments are due when calling financial methods.| -||Indicates whether text fields are delimited or fixed-width.| -||Indicates the file attributes to use when calling file-access functions.| -||Indicates the first day of the week to use when calling date-related functions.| -||Indicates the first week of the year to use when calling date-related functions.| -||Indicates which button was pressed on a message box, returned by the function.| -||Indicates which buttons to display when calling the function.| -||Indicates how to open a file when calling file-access functions.| -||Indicates how to open a file when calling file-access functions.| -||Indicates how to open a file when calling file-access functions.| -||Specifies whether a file should be deleted permanently or placed in the Recycle Bin.| -||Specifies whether to search all or only top-level directories.| -||Indicates a `Boolean` value or whether the default should be used when calling number-formatting functions.| -||Specifies what should be done if the user clicks **Cancel** during an operation.| -||Specifies whether or not to show a progress dialog when copying, deleting, or moving files or directories.| -||Indicates the type of a variant object, returned by the function.| -||Indicates which type of conversion to perform when calling the function.| - ## See also - [Visual Basic Language Reference](index.md) diff --git a/docs/visual-basic/language-reference/data-types/char-data-type.md b/docs/visual-basic/language-reference/data-types/char-data-type.md index 2d93e5f46c3cb..50dbf697e3a5a 100644 --- a/docs/visual-basic/language-reference/data-types/char-data-type.md +++ b/docs/visual-basic/language-reference/data-types/char-data-type.md @@ -26,11 +26,11 @@ The default value of `Char` is the character with a code point of 0. The first 128 code points (0–127) of Unicode correspond to the letters and symbols on a standard U.S. keyboard. These first 128 code points are the same as those the ASCII character set defines. The second 128 code points (128–255) represent special characters, such as Latin-based alphabet letters, accents, currency symbols, and fractions. Unicode uses the remaining code points (256-65535) for a wide variety of symbols, including worldwide textual characters, diacritics, and mathematical and technical symbols. -You can use methods like and on a `Char` variable to determine its Unicode classification. +You can use methods like and on a `Char` variable to determine its Unicode classification. ## Type Conversions -Visual Basic does not convert directly between `Char` and the numeric types. You can use the or function to convert a `Char` value to an `Integer` that represents its code point. You can use the or function to convert an `Integer` value to a `Char` that has that code point. +Visual Basic does not convert directly between `Char` and the numeric types. You can use the or function to convert a `Char` value to an `Integer` that represents its code point. You can use the or function to convert an `Integer` value to a `Char` that has that code point. If the type checking switch (the [Option Strict Statement](../statements/option-strict-statement.md)) is on, you must append the literal type character to a single-character string literal to identify it as the `Char` data type. The following example illustrates this. The first assignment to the `charVar` variable generates compiler error [BC30512](../../misc/bc30512.md) because `Option Strict` is on. The second compiles successfully because the `c` literal type character identifies the literal as a `Char` value. @@ -41,10 +41,10 @@ Module CharType Public Sub Main() Dim charVar As Char - ' This statement generates compiler error BC30512 because Option Strict is On. - charVar = "Z" + ' This statement generates compiler error BC30512 because Option Strict is On. + charVar = "Z" - ' The following statement succeeds because it specifies a Char literal. + ' The following statement succeeds because it specifies a Char literal. charVar = "Z"c End Sub End Module @@ -65,10 +65,10 @@ End Module ## See also - -- -- -- -- +- +- +- +- - [Data Types](index.md) - [String Data Type](string-data-type.md) - [Type Conversion Functions](../functions/type-conversion-functions.md) diff --git a/docs/visual-basic/language-reference/data-types/date-data-type.md b/docs/visual-basic/language-reference/data-types/date-data-type.md index 374e5a743134d..0e67e2a1c2407 100644 --- a/docs/visual-basic/language-reference/data-types/date-data-type.md +++ b/docs/visual-basic/language-reference/data-types/date-data-type.md @@ -37,7 +37,7 @@ The reason for this restriction is that the meaning of your code should never ch ## Workarounds -To convert a `Date` literal to the format of your locale, or to a custom format, supply the literal to the function, specifying either a predefined or user-defined date format. The following example demonstrates this. +To convert a `Date` literal to the format of your locale, or to a custom format, supply the literal to the function, specifying either a predefined or user-defined date format. The following example demonstrates this. ```vb MsgBox("The formatted date is " & Format(#5/31/1993#, "dddd, d MMM yyyy")) @@ -63,7 +63,7 @@ If you convert a `Date` value to the `String` type, Visual Basic renders the dat ## Programming Tips -- **Interop Considerations.** If you are interfacing with components not written for the .NET Framework, for example Automation or COM objects, keep in mind that date/time types in other environments are not compatible with the Visual Basic `Date` type. If you are passing a date/time argument to such a component, declare it as `Double` instead of `Date` in your new Visual Basic code, and use the conversion methods and . +- **Interop Considerations.** If you are interfacing with components not written for the .NET Framework, for example Automation or COM objects, keep in mind that date/time types in other environments are not compatible with the Visual Basic `Date` type. If you are passing a date/time argument to such a component, declare it as `Double` instead of `Date` in your new Visual Basic code, and use the conversion methods and . - **Type Characters.** `Date` has no literal type character or identifier type character. However, the compiler treats literals enclosed within number signs (`# #`) as `Date`. diff --git a/docs/visual-basic/language-reference/data-types/decimal-data-type.md b/docs/visual-basic/language-reference/data-types/decimal-data-type.md index 58c46b0a9f224..cbf35b2dfb85b 100644 --- a/docs/visual-basic/language-reference/data-types/decimal-data-type.md +++ b/docs/visual-basic/language-reference/data-types/decimal-data-type.md @@ -96,8 +96,8 @@ For `bigDec3`, the literal type character `D` solves the problem by forcing the ## See also - -- -- +- +- - [Data Types](index.md) - [Single Data Type](single-data-type.md) - [Double Data Type](double-data-type.md) diff --git a/docs/visual-basic/language-reference/data-types/index.md b/docs/visual-basic/language-reference/data-types/index.md index 10445112d9b0c..a7f68946ca1b0 100644 --- a/docs/visual-basic/language-reference/data-types/index.md +++ b/docs/visual-basic/language-reference/data-types/index.md @@ -2,7 +2,7 @@ description: "Learn more about: Data Type Summary (Visual Basic)" title: "Data Type Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "Boolean data type [Visual Basic], supported types in Visual Basic" - "storage [Visual Basic], order of storage" - "data types [Visual Basic], Visual Basic" @@ -41,58 +41,58 @@ ms.assetid: e975cdb6-64d8-4a4a-ae27-f3b3ed198ae0 --- # Data Type Summary (Visual Basic) -The following table shows the Visual Basic data types, their supporting common language runtime types, their nominal storage allocation, and their value ranges. - -|Visual Basic type|Common language runtime type structure|Nominal storage allocation|Value range| -|-----------------------|--------------------------------------------|--------------------------------|-----------------| -|[Boolean](boolean-data-type.md)||Depends on implementing platform|`True` or `False`| -|[Byte](byte-data-type.md)||1 byte|0 through 255 (unsigned)| -|[Char](char-data-type.md) (single character)||2 bytes|0 through 65535 (unsigned)| -|[Date](date-data-type.md)||8 bytes|0:00:00 (midnight) on January 1, 0001 through 11:59:59 PM on December 31, 9999| -|[Decimal](decimal-data-type.md)||16 bytes|0 through +/-79,228,162,514,264,337,593,543,950,335 (+/-7.9...E+28) † with no decimal point; 0 through +/-7.9228162514264337593543950335 with 28 places to the right of the decimal;

smallest nonzero number is +/-0.0000000000000000000000000001 (+/-1E-28) †| -|[Double](double-data-type.md) (double-precision floating-point)||8 bytes|-1.79769313486231570E+308 through -4.94065645841246544E-324 † for negative values;

4.94065645841246544E-324 through 1.79769313486231570E+308 † for positive values| -|[Integer](integer-data-type.md)||4 bytes|-2,147,483,648 through 2,147,483,647 (signed)| -|[Long](long-data-type.md) (long integer)||8 bytes|-9,223,372,036,854,775,808 through 9,223,372,036,854,775,807 (9.2...E+18 †) (signed)| -|[Object](object-data-type.md)| (class)|4 bytes on 32-bit platform

8 bytes on 64-bit platform|Any type can be stored in a variable of type `Object`| -|[SByte](sbyte-data-type.md)||1 byte|-128 through 127 (signed)| -|[Short](short-data-type.md) (short integer)||2 bytes|-32,768 through 32,767 (signed)| -|[Single](single-data-type.md) (single-precision floating-point)||4 bytes|-3.4028235E+38 through -1.401298E-45 † for negative values;

1.401298E-45 through 3.4028235E+38 † for positive values| -|[String](string-data-type.md) (variable-length)| (class)|Depends on implementing platform|0 to approximately 2 billion Unicode characters| -|[UInteger](uinteger-data-type.md)||4 bytes|0 through 4,294,967,295 (unsigned)| -|[ULong](ulong-data-type.md)||8 bytes|0 through 18,446,744,073,709,551,615 (1.8...E+19 †) (unsigned)| -|[User-Defined](user-defined-data-type.md) (structure)|(inherits from )|Depends on implementing platform|Each member of the structure has a range determined by its data type and independent of the ranges of the other members| -|[UShort](ushort-data-type.md)||2 bytes|0 through 65,535 (unsigned)| - - † In *scientific notation*, "E" refers to a power of 10. So 3.56E+2 signifies 3.56 x 102 or 356, and 3.56E-2 signifies 3.56 / 102 or 0.0356. - +The following table shows the Visual Basic data types, their supporting common language runtime types, their nominal storage allocation, and their value ranges. + +|Visual Basic type|Common language runtime type structure|Nominal storage allocation|Value range| +|-----------------------|--------------------------------------------|--------------------------------|-----------------| +|[Boolean](boolean-data-type.md)||Depends on implementing platform|`True` or `False`| +|[Byte](byte-data-type.md)||1 byte|0 through 255 (unsigned)| +|[Char](char-data-type.md) (single character)||2 bytes|0 through 65535 (unsigned)| +|[Date](date-data-type.md)||8 bytes|0:00:00 (midnight) on January 1, 0001 through 11:59:59 PM on December 31, 9999| +|[Decimal](decimal-data-type.md)||16 bytes|0 through +/-79,228,162,514,264,337,593,543,950,335 (+/-7.9...E+28) † with no decimal point; 0 through +/-7.9228162514264337593543950335 with 28 places to the right of the decimal;

smallest nonzero number is +/-0.0000000000000000000000000001 (+/-1E-28) †| +|[Double](double-data-type.md) (double-precision floating-point)||8 bytes|-1.79769313486231570E+308 through -4.94065645841246544E-324 † for negative values;

4.94065645841246544E-324 through 1.79769313486231570E+308 † for positive values| +|[Integer](integer-data-type.md)||4 bytes|-2,147,483,648 through 2,147,483,647 (signed)| +|[Long](long-data-type.md) (long integer)||8 bytes|-9,223,372,036,854,775,808 through 9,223,372,036,854,775,807 (9.2...E+18 †) (signed)| +|[Object](object-data-type.md)| (class)|4 bytes on 32-bit platform

8 bytes on 64-bit platform|Any type can be stored in a variable of type `Object`| +|[SByte](sbyte-data-type.md)||1 byte|-128 through 127 (signed)| +|[Short](short-data-type.md) (short integer)||2 bytes|-32,768 through 32,767 (signed)| +|[Single](single-data-type.md) (single-precision floating-point)||4 bytes|-3.4028235E+38 through -1.401298E-45 † for negative values;

1.401298E-45 through 3.4028235E+38 † for positive values| +|[String](string-data-type.md) (variable-length)| (class)|Depends on implementing platform|0 to approximately 2 billion Unicode characters| +|[UInteger](uinteger-data-type.md)||4 bytes|0 through 4,294,967,295 (unsigned)| +|[ULong](ulong-data-type.md)||8 bytes|0 through 18,446,744,073,709,551,615 (1.8...E+19 †) (unsigned)| +|[User-Defined](user-defined-data-type.md) (structure)|(inherits from )|Depends on implementing platform|Each member of the structure has a range determined by its data type and independent of the ranges of the other members| +|[UShort](ushort-data-type.md)||2 bytes|0 through 65,535 (unsigned)| + + † In *scientific notation*, "E" refers to a power of 10. So 3.56E+2 signifies 3.56 x 102 or 356, and 3.56E-2 signifies 3.56 / 102 or 0.0356. + > [!NOTE] -> For strings containing text, use the function to convert from one text format to another. - - In addition to specifying a data type in a declaration statement, you can force the data type of some programming elements by using a type character. See [Type Characters](../../programming-guide/language-features/data-types/type-characters.md). - -## Memory Consumption - - When you declare an elementary data type, it is not safe to assume that its memory consumption is the same as its nominal storage allocation. This is due to the following considerations: - -- **Storage Assignment.** The common language runtime can assign storage based on the current characteristics of the platform on which your application is executing. If memory is nearly full, it might pack your declared elements as closely together as possible. In other cases it might align their memory addresses to natural hardware boundaries to optimize performance. - -- **Platform Width.** Storage assignment on a 64-bit platform is different from assignment on a 32-bit platform. - -### Composite Data Types - - The same considerations apply to each member of a composite data type, such as a structure or an array. You cannot rely on simply adding together the nominal storage allocations of the type's members. Furthermore, there are other considerations, such as the following: - -- **Overhead.** Some composite types have additional memory requirements. For example, an array uses extra memory for the array itself and also for each dimension. On a 32-bit platform, this overhead is currently 12 bytes plus 8 bytes for each dimension. On a 64-bit platform this requirement is doubled. - -- **Storage Layout.** You cannot safely assume that the order of storage in memory is the same as your order of declaration. You cannot even make assumptions about byte alignment, such as a 2-byte or 4-byte boundary. If you are defining a class or structure and you need to control the storage layout of its members, you can apply the attribute to the class or structure. - -### Object Overhead - - An `Object` referring to any elementary or composite data type uses 4 bytes in addition to the data contained in the data type. - +> For strings containing text, use the function to convert from one text format to another. + + In addition to specifying a data type in a declaration statement, you can force the data type of some programming elements by using a type character. See [Type Characters](../../programming-guide/language-features/data-types/type-characters.md). + +## Memory Consumption + + When you declare an elementary data type, it is not safe to assume that its memory consumption is the same as its nominal storage allocation. This is due to the following considerations: + +- **Storage Assignment.** The common language runtime can assign storage based on the current characteristics of the platform on which your application is executing. If memory is nearly full, it might pack your declared elements as closely together as possible. In other cases it might align their memory addresses to natural hardware boundaries to optimize performance. + +- **Platform Width.** Storage assignment on a 64-bit platform is different from assignment on a 32-bit platform. + +### Composite Data Types + + The same considerations apply to each member of a composite data type, such as a structure or an array. You cannot rely on simply adding together the nominal storage allocations of the type's members. Furthermore, there are other considerations, such as the following: + +- **Overhead.** Some composite types have additional memory requirements. For example, an array uses extra memory for the array itself and also for each dimension. On a 32-bit platform, this overhead is currently 12 bytes plus 8 bytes for each dimension. On a 64-bit platform this requirement is doubled. + +- **Storage Layout.** You cannot safely assume that the order of storage in memory is the same as your order of declaration. You cannot even make assumptions about byte alignment, such as a 2-byte or 4-byte boundary. If you are defining a class or structure and you need to control the storage layout of its members, you can apply the attribute to the class or structure. + +### Object Overhead + + An `Object` referring to any elementary or composite data type uses 4 bytes in addition to the data contained in the data type. + ## See also -- +- - - [Type Conversion Functions](../functions/type-conversion-functions.md) - [Conversion Summary](../keywords/conversion-summary.md) diff --git a/docs/visual-basic/language-reference/data-types/object-data-type.md b/docs/visual-basic/language-reference/data-types/object-data-type.md index aa9a8dac386b5..d2a6fa69f2c04 100644 --- a/docs/visual-basic/language-reference/data-types/object-data-type.md +++ b/docs/visual-basic/language-reference/data-types/object-data-type.md @@ -24,7 +24,7 @@ The default value of `Object` is `Nothing` (a null reference). ## Data Types -You can assign a variable, constant, or expression of any data type to an `Object` variable. To determine the data type an `Object` variable currently refers to, you can use the method of the class. The following example illustrates this. +You can assign a variable, constant, or expression of any data type to an `Object` variable. To determine the data type an `Object` variable currently refers to, you can use the method of the class. The following example illustrates this. ```vb Dim myObject As Object diff --git a/docs/visual-basic/language-reference/data-types/string-data-type.md b/docs/visual-basic/language-reference/data-types/string-data-type.md index 1bbc07096d744..0212f2558b796 100644 --- a/docs/visual-basic/language-reference/data-types/string-data-type.md +++ b/docs/visual-basic/language-reference/data-types/string-data-type.md @@ -2,9 +2,9 @@ description: "Learn more about: String Data Type (Visual Basic)" title: "String Data Type" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.String" -helpviewer_keywords: +helpviewer_keywords: - "strings [Visual Basic], character" - "strings [Visual Basic], fixed-length" - "string keyword [Visual Basic]" @@ -22,62 +22,62 @@ ms.assetid: 15ac03f5-cabd-42cc-a754-1df3893c25d9 --- # String Data Type (Visual Basic) -Holds sequences of unsigned 16-bit (2-byte) code points that range in value from 0 through 65535. Each *code point*, or character code, represents a single Unicode character. A string can contain from 0 to approximately two billion (2 ^ 31) Unicode characters. - -## Remarks - - Use the `String` data type to hold multiple characters without the array management overhead of `Char()`, an array of `Char` elements. - - The default value of `String` is `Nothing` (a null reference). Note that this is not the same as the empty string (value `""`). - -## Unicode Characters - - The first 128 code points (0–127) of Unicode correspond to the letters and symbols on a standard U.S. keyboard. These first 128 code points are the same as those the ASCII character set defines. The second 128 code points (128–255) represent special characters, such as Latin-based alphabet letters, accents, currency symbols, and fractions. Unicode uses the remaining code points (256-65535) for a wide variety of symbols. This includes worldwide textual characters, diacritics, and mathematical and technical symbols. - - You can use methods such as and on an individual character in a `String` variable to determine its Unicode classification. - -## Format Requirements - - You must enclose a `String` literal within quotation marks (`" "`). If you must include a quotation mark as one of the characters in the string, you use two contiguous quotation marks (`""`). The following example illustrates this. - -```vb -Dim j As String = "Joe said ""Hello"" to me." -Dim h As String = "Hello" -' The following messages all display the same thing: -' "Joe said "Hello" to me." -MsgBox(j) -MsgBox("Joe said " & """" & h & """" & " to me.") -MsgBox("Joe said """ & h & """ to me.") -``` - - Note that the contiguous quotation marks that represent a quotation mark in the string are independent of the quotation marks that begin and end the `String` literal. - -## String Manipulations - - Once you assign a string to a `String` variable, that string is *immutable*, which means you cannot change its length or contents. When you alter a string in any way, Visual Basic creates a new string and abandons the previous one. The `String` variable then points to the new string. - - You can manipulate the contents of a `String` variable by using a variety of string functions. The following example illustrates the function - -```vb -Dim S As String = "Database" -' The following statement sets S to a new string containing "Data". -S = Microsoft.VisualBasic.Left(S, 4) -``` - - A string created by another component might be padded with leading or trailing spaces. If you receive such a string, you can use the , , and functions to remove these spaces. - - For more information about string manipulations, see [Strings](../../programming-guide/language-features/strings/index.md). - -## Programming Tips - -- **Negative Numbers.** Remember that the characters held by `String` are unsigned and cannot represent negative values. In any case, you should not use `String` to hold numeric values. - -- **Interop Considerations.** If you are interfacing with components not written for the .NET Framework, for example Automation or COM objects, remember that string characters have a different data width (8 bits) in other environments. If you are passing a string argument of 8-bit characters to such a component, declare it as `Byte()`, an array of `Byte` elements, instead of `String` in your new Visual Basic code. - -- **Type Characters.** Appending the identifier type character `$` to any identifier forces it to the `String` data type. `String` has no literal type character. However, the compiler treats literals enclosed in quotation marks (`" "`) as `String`. - -- **Framework Type.** The corresponding type in the .NET Framework is the class. - +Holds sequences of unsigned 16-bit (2-byte) code points that range in value from 0 through 65535. Each *code point*, or character code, represents a single Unicode character. A string can contain from 0 to approximately two billion (2 ^ 31) Unicode characters. + +## Remarks + + Use the `String` data type to hold multiple characters without the array management overhead of `Char()`, an array of `Char` elements. + + The default value of `String` is `Nothing` (a null reference). Note that this is not the same as the empty string (value `""`). + +## Unicode Characters + + The first 128 code points (0–127) of Unicode correspond to the letters and symbols on a standard U.S. keyboard. These first 128 code points are the same as those the ASCII character set defines. The second 128 code points (128–255) represent special characters, such as Latin-based alphabet letters, accents, currency symbols, and fractions. Unicode uses the remaining code points (256-65535) for a wide variety of symbols. This includes worldwide textual characters, diacritics, and mathematical and technical symbols. + + You can use methods such as and on an individual character in a `String` variable to determine its Unicode classification. + +## Format Requirements + + You must enclose a `String` literal within quotation marks (`" "`). If you must include a quotation mark as one of the characters in the string, you use two contiguous quotation marks (`""`). The following example illustrates this. + +```vb +Dim j As String = "Joe said ""Hello"" to me." +Dim h As String = "Hello" +' The following messages all display the same thing: +' "Joe said "Hello" to me." +MsgBox(j) +MsgBox("Joe said " & """" & h & """" & " to me.") +MsgBox("Joe said """ & h & """ to me.") +``` + + Note that the contiguous quotation marks that represent a quotation mark in the string are independent of the quotation marks that begin and end the `String` literal. + +## String Manipulations + + Once you assign a string to a `String` variable, that string is *immutable*, which means you cannot change its length or contents. When you alter a string in any way, Visual Basic creates a new string and abandons the previous one. The `String` variable then points to the new string. + + You can manipulate the contents of a `String` variable by using a variety of string functions. The following example illustrates the function + +```vb +Dim S As String = "Database" +' The following statement sets S to a new string containing "Data". +S = Microsoft.VisualBasic.Left(S, 4) +``` + + A string created by another component might be padded with leading or trailing spaces. If you receive such a string, you can use the , , and functions to remove these spaces. + + For more information about string manipulations, see [Strings](../../programming-guide/language-features/strings/index.md). + +## Programming Tips + +- **Negative Numbers.** Remember that the characters held by `String` are unsigned and cannot represent negative values. In any case, you should not use `String` to hold numeric values. + +- **Interop Considerations.** If you are interfacing with components not written for the .NET Framework, for example Automation or COM objects, remember that string characters have a different data width (8 bits) in other environments. If you are passing a string argument of 8-bit characters to such a component, declare it as `Byte()`, an array of `Byte` elements, instead of `String` in your new Visual Basic code. + +- **Type Characters.** Appending the identifier type character `$` to any identifier forces it to the `String` data type. `String` has no literal type character. However, the compiler treats literals enclosed in quotation marks (`" "`) as `String`. + +- **Framework Type.** The corresponding type in the .NET Framework is the class. + ## See also - diff --git a/docs/visual-basic/language-reference/error-messages/a-double-quote-is-not-a-valid-comment-token-for-delimited-fields.md b/docs/visual-basic/language-reference/error-messages/a-double-quote-is-not-a-valid-comment-token-for-delimited-fields.md index db0d2cfa638bf..0ecdf89fdd17a 100644 --- a/docs/visual-basic/language-reference/error-messages/a-double-quote-is-not-a-valid-comment-token-for-delimited-fields.md +++ b/docs/visual-basic/language-reference/error-messages/a-double-quote-is-not-a-valid-comment-token-for-delimited-fields.md @@ -2,7 +2,7 @@ description: "Learn more about: A double quote is not a valid comment token for delimited fields where HasFieldsEnclosedInQuotes is set to True" title: "A double quote is not a valid comment token for delimited fields where HasFieldsEnclosedInQuotes is set to True" ms.date: 03/03/2026 -f1_keywords: +f1_keywords: - "vbrTextFieldParser_InvalidComment" ms.assetid: 636d4b81-00ba-4cfd-98f7-4d57036f494d ai-usage: ai-assisted @@ -18,9 +18,9 @@ A quotation mark has been supplied as a comment token for the `TextFieldParser`, ## See also -- -- -- -- +- +- +- +- - - [How to: Read From Comma-Delimited Text Files](../../developing-apps/programming/drives-directories-files/how-to-read-from-comma-delimited-text-files.md) diff --git a/docs/visual-basic/language-reference/error-messages/a-startup-form-has-not-been-specified.md b/docs/visual-basic/language-reference/error-messages/a-startup-form-has-not-been-specified.md index cb54a9829a2fb..7193edd895781 100644 --- a/docs/visual-basic/language-reference/error-messages/a-startup-form-has-not-been-specified.md +++ b/docs/visual-basic/language-reference/error-messages/a-startup-form-has-not-been-specified.md @@ -2,27 +2,27 @@ description: "Learn more about: A startup form has not been specified" title: "A startup form has not been specified" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrAppModel_NoStartupForm" ms.assetid: 8e04af49-4bef-49de-a7ec-e407e9873da7 --- # A startup form has not been specified -The application uses the class but does not specify the startup form. - - This can occur if the **Enable application framework** check box is selected in the project designer but the **Startup form** is not specified. For more information, see [Application Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/application-page-project-designer-visual-basic). - -## To correct this error - -1. Specify a startup object for the application. - - For more information, see [Application Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/application-page-project-designer-visual-basic). - -2. Override the method to set the property to the startup form. - +The application uses the class but does not specify the startup form. + + This can occur if the **Enable application framework** check box is selected in the project designer but the **Startup form** is not specified. For more information, see [Application Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/application-page-project-designer-visual-basic). + +## To correct this error + +1. Specify a startup object for the application. + + For more information, see [Application Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/application-page-project-designer-visual-basic). + +2. Override the method to set the property to the startup form. + ## See also - -- -- +- +- - [Overview of the Visual Basic Application Model](../../developing-apps/development-with-my/overview-of-the-visual-basic-application-model.md) diff --git a/docs/visual-basic/language-reference/error-messages/bad-file-name-or-number.md b/docs/visual-basic/language-reference/error-messages/bad-file-name-or-number.md index 98fac94d64916..d5d3f6fbfc68e 100644 --- a/docs/visual-basic/language-reference/error-messages/bad-file-name-or-number.md +++ b/docs/visual-basic/language-reference/error-messages/bad-file-name-or-number.md @@ -2,29 +2,29 @@ description: "Learn more about: Bad file name or number" title: "Bad file name or number" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrID52" ms.assetid: d0e96aea-7621-48f6-a78b-5d37d18aaa4e --- # Bad file name or number -An error occurred while trying to access the specified file. Among the possible causes for this error are: - -- A statement refers to a file with a file name or number that was not specified in the `FileOpen` statement or that was specified in a `FileOpen` statement but was subsequently closed. - -- A statement refers to a file with a number that is out of the range of file numbers. - -- A statement refers to a file name or number that is not valid. - -## To correct this error - -1. Make sure the file name is specified in a `FileOpen` statement. Note that if you invoked the `FileClose` statement without arguments, you may have inadvertently closed all open files. - -2. If your code is generating file numbers algorithmically, make sure the numbers are valid. - -3. Check the file names to make sure they conform to operating system conventions. - +An error occurred while trying to access the specified file. Among the possible causes for this error are: + +- A statement refers to a file with a file name or number that was not specified in the `FileOpen` statement or that was specified in a `FileOpen` statement but was subsequently closed. + +- A statement refers to a file with a number that is out of the range of file numbers. + +- A statement refers to a file name or number that is not valid. + +## To correct this error + +1. Make sure the file name is specified in a `FileOpen` statement. Note that if you invoked the `FileClose` statement without arguments, you may have inadvertently closed all open files. + +2. If your code is generating file numbers algorithmically, make sure the numbers are valid. + +3. Check the file names to make sure they conform to operating system conventions. + ## See also -- +- - [Visual Basic Naming Conventions](../../programming-guide/program-structure/naming-conventions.md) diff --git a/docs/visual-basic/language-reference/error-messages/bad-record-length.md b/docs/visual-basic/language-reference/error-messages/bad-record-length.md index 03b1c5b084ba1..b45bc79909ac8 100644 --- a/docs/visual-basic/language-reference/error-messages/bad-record-length.md +++ b/docs/visual-basic/language-reference/error-messages/bad-record-length.md @@ -2,31 +2,31 @@ description: "Learn more about: Bad record length" title: "Bad record length" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrID59" ms.assetid: 0926a3a4-177b-4452-9b33-d8a01e24cc21 --- # Bad record length -Among the possible causes of this error are: - -- The length of a record variable specified in a `FileGet`, `FileGetObject`, `FilePut` or `FilePutObject` statement differs from the length specified in the corresponding `FileOpen` statement. - -- The variable in a `FilePut` or `FilePutObject` statement is or includes a variable-length string. - -- The variable in a `FilePut` or `FilePutObject` is or includes a `Variant` type. - -## To correct this error - -1. Make sure the sum of the sizes of fixed-length variables in the user-defined type defining the record variable's type is the same as the value stated in the `FileOpen` statement's `Len` clause. - -2. If the variable in a `FilePut` or `FilePutObject` statement is or includes a variable-length string, make sure the variable-length string is at least 2 characters shorter than the record length specified in the `Len` clause of the `FileOpen` statement. - -3. If the variable in a `FilePut` or `FilePutObject` is or includes a `Variant` make sure the variable-length string is at least 4 bytes shorter than the record length specified in the `Len` clause of the `FileOpen` statement. - +Among the possible causes of this error are: + +- The length of a record variable specified in a `FileGet`, `FileGetObject`, `FilePut` or `FilePutObject` statement differs from the length specified in the corresponding `FileOpen` statement. + +- The variable in a `FilePut` or `FilePutObject` statement is or includes a variable-length string. + +- The variable in a `FilePut` or `FilePutObject` is or includes a `Variant` type. + +## To correct this error + +1. Make sure the sum of the sizes of fixed-length variables in the user-defined type defining the record variable's type is the same as the value stated in the `FileOpen` statement's `Len` clause. + +2. If the variable in a `FilePut` or `FilePutObject` statement is or includes a variable-length string, make sure the variable-length string is at least 2 characters shorter than the record length specified in the `Len` clause of the `FileOpen` statement. + +3. If the variable in a `FilePut` or `FilePutObject` is or includes a `Variant` make sure the variable-length string is at least 4 bytes shorter than the record length specified in the `Len` clause of the `FileOpen` statement. + ## See also -- -- -- -- +- +- +- +- diff --git a/docs/visual-basic/language-reference/error-messages/bc2012.md b/docs/visual-basic/language-reference/error-messages/bc2012.md index fafdcbc523af6..9e9f299bb1df6 100644 --- a/docs/visual-basic/language-reference/error-messages/bc2012.md +++ b/docs/visual-basic/language-reference/error-messages/bc2012.md @@ -23,6 +23,6 @@ The specified file cannot be opened for writing, perhaps because it has already ## See also -- -- +- +- - [Writing to Files](../../developing-apps/programming/drives-directories-files/writing-to-files.md) diff --git a/docs/visual-basic/language-reference/error-messages/bc42358.md b/docs/visual-basic/language-reference/error-messages/bc42358.md index dc9c69efe093d..c834e32472ee6 100644 --- a/docs/visual-basic/language-reference/error-messages/bc42358.md +++ b/docs/visual-basic/language-reference/error-messages/bc42358.md @@ -13,9 +13,9 @@ ms.assetid: 43342515-c3c8-4155-9263-c302afabcbc2 Because this call is not awaited, execution of the current method continues before the call is completed. Consider applying the `Await` operator to the result of the call. -The current method calls an async method that returns a or a and doesn't apply the [Await](../operators/await-operator.md) operator to the result. The call to the async method starts an asynchronous task. However, because no `Await` operator is applied, the program continues without waiting for the task to complete. In most cases, that behavior isn't expected. Usually other aspects of the calling method depend on the results of the call or, minimally, the called method is expected to complete before you return from the method that contains the call. +The current method calls an async method that returns a or a and doesn't apply the [Await](../operators/await-operator.md) operator to the result. The call to the async method starts an asynchronous task. However, because no `Await` operator is applied, the program continues without waiting for the task to complete. In most cases, that behavior isn't expected. Usually other aspects of the calling method depend on the results of the call or, minimally, the called method is expected to complete before you return from the method that contains the call. -An equally important issue is what happens with exceptions that are raised in the called async method. An exception that's raised in a method that returns a or is stored in the returned task. If you don't await the task or explicitly check for exceptions, the exception is lost. If you await the task, its exception is rethrown. +An equally important issue is what happens with exceptions that are raised in the called async method. An exception that's raised in a method that returns a or is stored in the returned task. If you don't await the task or explicitly check for exceptions, the exception is lost. If you await the task, its exception is rethrown. As a best practice, you should always await the call. diff --git a/docs/visual-basic/language-reference/error-messages/dir-function-must-first-be-called-with-a-pathname-argument.md b/docs/visual-basic/language-reference/error-messages/dir-function-must-first-be-called-with-a-pathname-argument.md index fada0ccb60665..a918edc620058 100644 --- a/docs/visual-basic/language-reference/error-messages/dir-function-must-first-be-called-with-a-pathname-argument.md +++ b/docs/visual-basic/language-reference/error-messages/dir-function-must-first-be-called-with-a-pathname-argument.md @@ -16,4 +16,4 @@ An initial call to the `Dir` function does not include the `PathName` argument. ## See also -- +- diff --git a/docs/visual-basic/language-reference/error-messages/elementname-is-obsolete-visual-basic-warning.md b/docs/visual-basic/language-reference/error-messages/elementname-is-obsolete-visual-basic-warning.md index 29220898f1eaa..9e2c5a66b8d28 100644 --- a/docs/visual-basic/language-reference/error-messages/elementname-is-obsolete-visual-basic-warning.md +++ b/docs/visual-basic/language-reference/error-messages/elementname-is-obsolete-visual-basic-warning.md @@ -13,9 +13,9 @@ ms.assetid: 729e3eb5-76ac-4c55-9fdd-78350e0de55e A statement attempts to access a programming element which has been marked with the attribute and the directive to treat it as a warning. - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - By default, this message is a warning, because the property of is `False`. For more information about hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). + By default, this message is a warning, because the property of is `False`. For more information about hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). **Error ID:** BC40008 diff --git a/docs/visual-basic/language-reference/error-messages/expression-has-the-type-typename-which-is-a-restricted-type.md b/docs/visual-basic/language-reference/error-messages/expression-has-the-type-typename-which-is-a-restricted-type.md index c084cd234dcb1..321175ffcd61f 100644 --- a/docs/visual-basic/language-reference/error-messages/expression-has-the-type-typename-which-is-a-restricted-type.md +++ b/docs/visual-basic/language-reference/error-messages/expression-has-the-type-typename-which-is-a-restricted-type.md @@ -15,7 +15,7 @@ An expression evaluates to a type that cannot be boxed by the common language ru *Boxing* refers to the processing necessary to convert a type to `Object` or, on occasion, to . The common language runtime cannot box certain structure types, for example , , and . - This expression attempts to use the restricted type to call a method inherited from or , such as or . To access this method, Visual Basic has attempted an implicit boxing conversion that causes this error. + This expression attempts to use the restricted type to call a method inherited from or , such as or . To access this method, Visual Basic has attempted an implicit boxing conversion that causes this error. **Error ID:** BC31393 diff --git a/docs/visual-basic/language-reference/error-messages/expression-is-a-value-and-therefore-cannot-be-the-target-of-an-assignment.md b/docs/visual-basic/language-reference/error-messages/expression-is-a-value-and-therefore-cannot-be-the-target-of-an-assignment.md index 14c40e17a6de1..48ed04ac3c677 100644 --- a/docs/visual-basic/language-reference/error-messages/expression-is-a-value-and-therefore-cannot-be-the-target-of-an-assignment.md +++ b/docs/visual-basic/language-reference/error-messages/expression-is-a-value-and-therefore-cannot-be-the-target-of-an-assignment.md @@ -24,7 +24,7 @@ maximum = 50 Similar examples could apply to properties and array elements. -**Indirect Access.** Indirect access through a value type can also generate this error. Consider the following code example, which attempts to set the value of by accessing it indirectly through . +**Indirect Access.** Indirect access through a value type can also generate this error. Consider the following code example, which attempts to set the value of by accessing it indirectly through . ```vb ' Assume this code runs inside Form1. @@ -34,7 +34,7 @@ exitButton.Location.X = 140 ' The preceding line is an ERROR because of no storage for Location. ``` -The last statement of the preceding example fails because it creates only a temporary allocation for the structure returned by the property. A structure is a value type, and the temporary structure is not retained after the statement runs. The problem is resolved by declaring and using a variable for , which creates a more permanent allocation for the structure. The following example shows code that can replace the last statement of the preceding example. +The last statement of the preceding example fails because it creates only a temporary allocation for the structure returned by the property. A structure is a value type, and the temporary structure is not retained after the statement runs. The problem is resolved by declaring and using a variable for , which creates a more permanent allocation for the structure. The following example shows code that can replace the last statement of the preceding example. ```vb Dim exitLocation as New System.Drawing.Point(140, exitButton.Location.Y) diff --git a/docs/visual-basic/language-reference/error-messages/expression-of-type-type-is-not-queryable.md b/docs/visual-basic/language-reference/error-messages/expression-of-type-type-is-not-queryable.md index b9ce6f15a3844..8a1604fbad761 100644 --- a/docs/visual-basic/language-reference/error-messages/expression-of-type-type-is-not-queryable.md +++ b/docs/visual-basic/language-reference/error-messages/expression-of-type-type-is-not-queryable.md @@ -27,7 +27,7 @@ Expression of type \ is not queryable. Make sure you are not missing an as 1. Add an `Import` statement for the , , or namespace to your code file. You can also import namespaces for your project by using the **References** page of the Project Designer (**My Project**). -2. Ensure that the type that you have identified as the source of your query is a queryable type. That is, a type that implements or . +2. Ensure that the type that you have identified as the source of your query is a queryable type. That is, a type that implements or . ## See also diff --git a/docs/visual-basic/language-reference/error-messages/file-already-open.md b/docs/visual-basic/language-reference/error-messages/file-already-open.md index 2b5f7a4b0c078..19dc241633571 100644 --- a/docs/visual-basic/language-reference/error-messages/file-already-open.md +++ b/docs/visual-basic/language-reference/error-messages/file-already-open.md @@ -20,4 +20,4 @@ Sometimes a file must be closed before another `FileOpen` or other operation can ## See also -- +- diff --git a/docs/visual-basic/language-reference/error-messages/file-is-too-large-to-read-into-a-byte-array.md b/docs/visual-basic/language-reference/error-messages/file-is-too-large-to-read-into-a-byte-array.md index cd12cd16e07f2..cfc8aa790e212 100644 --- a/docs/visual-basic/language-reference/error-messages/file-is-too-large-to-read-into-a-byte-array.md +++ b/docs/visual-basic/language-reference/error-messages/file-is-too-large-to-read-into-a-byte-array.md @@ -6,15 +6,15 @@ ms.assetid: 686630a6-a439-46c7-8d7b-34613ae4c5d8 --- # File is too large to read into a byte array -The size of the file you are attempting to read into a byte array exceeds 4 GB. The `My.Computer.FileSystem.ReadAllBytes` method cannot read a file that exceeds this size. - -## To correct this error - -- Use a to read the file. For more information, see [Basics of .NET Framework File I/O and the File System (Visual Basic)](../../developing-apps/programming/drives-directories-files/basics-of-net-framework-file-io-and-the-file-system.md). - +The size of the file you are attempting to read into a byte array exceeds 4 GB. The `My.Computer.FileSystem.ReadAllBytes` method cannot read a file that exceeds this size. + +## To correct this error + +- Use a to read the file. For more information, see [Basics of .NET Framework File I/O and the File System (Visual Basic)](../../developing-apps/programming/drives-directories-files/basics-of-net-framework-file-io-and-the-file-system.md). + ## See also -- +- - - [File Access with Visual Basic](../../developing-apps/programming/drives-directories-files/file-access.md) - [How to: Read Text from Files with a StreamReader](../../developing-apps/programming/drives-directories-files/how-to-read-text-from-files-with-a-streamreader.md) diff --git a/docs/visual-basic/language-reference/error-messages/first-statement-of-sub-new-must-be-explicit-call-to-mybase-new-or-myclass-new.md b/docs/visual-basic/language-reference/error-messages/first-statement-of-sub-new-must-be-explicit-call-to-mybase-new-or-myclass-new.md index 67e6e9032b21f..363fd755e490e 100644 --- a/docs/visual-basic/language-reference/error-messages/first-statement-of-sub-new-must-be-explicit-call-to-mybase-new-or-myclass-new.md +++ b/docs/visual-basic/language-reference/error-messages/first-statement-of-sub-new-must-be-explicit-call-to-mybase-new-or-myclass-new.md @@ -15,7 +15,7 @@ A class constructor does not explicitly call a base class constructor, and the i When a derived class constructor does not call a base class constructor, Visual Basic attempts to generate an implicit call to a parameterless base class constructor. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit call. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. **Error ID:** BC30920 diff --git a/docs/visual-basic/language-reference/error-messages/for-each-on-type-typename-is-ambiguous.md b/docs/visual-basic/language-reference/error-messages/for-each-on-type-typename-is-ambiguous.md index 358791f820548..2e9f68f01d7f0 100644 --- a/docs/visual-basic/language-reference/error-messages/for-each-on-type-typename-is-ambiguous.md +++ b/docs/visual-basic/language-reference/error-messages/for-each-on-type-typename-is-ambiguous.md @@ -11,15 +11,15 @@ ms.assetid: ed20d09c-913f-482e-89f8-c0a596c3ec24 --- # BC32096: 'For Each' on type '\' is ambiguous because the type implements multiple instantiations of 'System.Collections.Generic.IEnumerable(Of T)' -A `For Each` statement specifies an iterator variable that has more than one method. +A `For Each` statement specifies an iterator variable that has more than one method. - The iterator variable must be of a type that implements the or interface in one of the `Collections` namespaces of the .NET Framework. It is possible for a class to implement more than one constructed generic interface, using a different type argument for each construction. If a class that does this is used for the iterator variable, that variable has more than one method. In such a case, Visual Basic cannot choose which method to call. + The iterator variable must be of a type that implements the or interface in one of the `Collections` namespaces of the .NET Framework. It is possible for a class to implement more than one constructed generic interface, using a different type argument for each construction. If a class that does this is used for the iterator variable, that variable has more than one method. In such a case, Visual Basic cannot choose which method to call. **Error ID:** BC32096 ## To correct this error -- Use [DirectCast Operator](../operators/directcast-operator.md) or [TryCast Operator](../operators/trycast-operator.md) to cast the iterator variable type to the interface defining the method you want to use. +- Use [DirectCast Operator](../operators/directcast-operator.md) or [TryCast Operator](../operators/trycast-operator.md) to cast the iterator variable type to the interface defining the method you want to use. ## See also diff --git a/docs/visual-basic/language-reference/error-messages/input-past-end-of-file.md b/docs/visual-basic/language-reference/error-messages/input-past-end-of-file.md index f941cb32a113f..866c9d172a165 100644 --- a/docs/visual-basic/language-reference/error-messages/input-past-end-of-file.md +++ b/docs/visual-basic/language-reference/error-messages/input-past-end-of-file.md @@ -2,23 +2,23 @@ description: "Learn more about: Input past end of file" title: "Input past end of file" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrID62" ms.assetid: 65292704-6e7d-4622-9f50-eb655a59b016 --- # Input past end of file -Either an `Input` statement is reading from a file that is empty or one in which all the data is used, or you used the `EOF` function with a file opened for binary access. - -## To correct this error - -1. Use the `EOF` function immediately before the `Input` statement to detect the end of the file. - -2. If the file is opened for binary access, use `Seek` and `Loc`. - +Either an `Input` statement is reading from a file that is empty or one in which all the data is used, or you used the `EOF` function with a file opened for binary access. + +## To correct this error + +1. Use the `EOF` function immediately before the `Input` statement to detect the end of the file. + +2. If the file is opened for binary access, use `Seek` and `Loc`. + ## See also -- -- -- -- +- +- +- +- diff --git a/docs/visual-basic/language-reference/error-messages/late-bound-resolution-runtime-errors-could-occur.md b/docs/visual-basic/language-reference/error-messages/late-bound-resolution-runtime-errors-could-occur.md index 1a677bfe45713..abca52bcfecec 100644 --- a/docs/visual-basic/language-reference/error-messages/late-bound-resolution-runtime-errors-could-occur.md +++ b/docs/visual-basic/language-reference/error-messages/late-bound-resolution-runtime-errors-could-occur.md @@ -13,7 +13,7 @@ ms.assetid: 45f552c8-57c6-44c0-97d3-e510119b257a An object is assigned to a variable declared to be of the [Object Data Type](../data-types/object-data-type.md). - When you declare a variable as `Object`, the compiler must perform *late binding*, which causes extra operations at run time. It also exposes your application to potential run-time errors. For example, if you assign a to the `Object` variable and then try to access the property, the runtime throws a because the class does not expose a `NameTable` property. + When you declare a variable as `Object`, the compiler must perform *late binding*, which causes extra operations at run time. It also exposes your application to potential run-time errors. For example, if you assign a to the `Object` variable and then try to access the property, the runtime throws a because the class does not expose a `NameTable` property. If you declare the variable to be of a specific type, the compiler can perform *early binding* at compile time. This results in improved performance, controlled access to the members of the specific type, and better readability of your code. diff --git a/docs/visual-basic/language-reference/error-messages/methods-of-system-nullable-of-t-cannot-be-used-as-operands-of-the-addressof.md b/docs/visual-basic/language-reference/error-messages/methods-of-system-nullable-of-t-cannot-be-used-as-operands-of-the-addressof.md index a235a3115a523..7546600813c7d 100644 --- a/docs/visual-basic/language-reference/error-messages/methods-of-system-nullable-of-t-cannot-be-used-as-operands-of-the-addressof.md +++ b/docs/visual-basic/language-reference/error-messages/methods-of-system-nullable-of-t-cannot-be-used-as-operands-of-the-addressof.md @@ -11,15 +11,15 @@ ms.assetid: 2325668b-e2ad-40ee-a1ec-30450236c20d --- # BC32126: Methods of 'System.Nullable(Of T)' cannot be used as operands of the 'AddressOf' operator -A statement uses the `AddressOf` operator with an operand that represents a procedure of the structure. +A statement uses the `AddressOf` operator with an operand that represents a procedure of the structure. **Error ID:** BC32126 ## To correct this error -- Replace the procedure name in the `AddressOf` clause with an operand that is not a member of . +- Replace the procedure name in the `AddressOf` clause with an operand that is not a member of . -- Write a class that wraps the method of that you want to use. In the following example, the `NullableWrapper` class defines a new method named `GetValueOrDefault`. Because this new method is not a member of , it can be applied to `nullInstance`, an instance of a nullable type, to form an argument for `AddressOf`. +- Write a class that wraps the method of that you want to use. In the following example, the `NullableWrapper` class defines a new method named `GetValueOrDefault`. Because this new method is not a member of , it can be applied to `nullInstance`, an instance of a nullable type, to form an argument for `AddressOf`. ```vb Module Module1 @@ -59,7 +59,7 @@ End Module ## See also -- +- - [AddressOf Operator](../operators/addressof-operator.md) - [Nullable Value Types](../../programming-guide/language-features/data-types/nullable-value-types.md) - [Generic Types in Visual Basic](../../programming-guide/language-features/data-types/generic-types.md) diff --git a/docs/visual-basic/language-reference/error-messages/name-name-is-not-declared.md b/docs/visual-basic/language-reference/error-messages/name-name-is-not-declared.md index e41444c71615d..7082ed9627265 100644 --- a/docs/visual-basic/language-reference/error-messages/name-name-is-not-declared.md +++ b/docs/visual-basic/language-reference/error-messages/name-name-is-not-declared.md @@ -19,7 +19,7 @@ A statement refers to a programming element, but the compiler cannot find an ele 1. Check the spelling of the name in the referring statement. Visual Basic is case-insensitive, but any other variation in the spelling is regarded as a completely different name. Note that the underscore (`_`) is part of the name and therefore part of the spelling. -2. Check that you have the member access operator (`.`) between an object and its member. For example, if you have a control named `TextBox1`, to access its property you should type `TextBox1.Text`. If instead you type `TextBox1Text`, you have created a different name. +2. Check that you have the member access operator (`.`) between an object and its member. For example, if you have a control named `TextBox1`, to access its property you should type `TextBox1.Text`. If instead you type `TextBox1Text`, you have created a different name. 3. If the spelling is correct and the syntax of any object member access is correct, verify that the element has been declared. For more information, see [Declared Elements](../../programming-guide/language-features/declared-elements/index.md). @@ -29,7 +29,7 @@ A statement refers to a programming element, but the compiler cannot find an ele 6. If you are attempting to compile an SDK-style project (a project with a \*.vbproj file that begins with the line ``), and the error message refers to a type or member in the Microsoft.VisualBasic.dll assembly, configure your application to compile with a reference to the Visual Basic Runtime Library. By default, a subset of the library is embedded in your assembly in an SDK-style project. - For example, the following example fails to compile because the method cannot be found. It is not embedded in the subset of the Visual Basic Runtime included with your application. + For example, the following example fails to compile because the method cannot be found. It is not embedded in the subset of the Visual Basic Runtime included with your application. [!code-vb[BC30451](~/samples/snippets/visualbasic/language-reference/error-messages/bc30451/program1.vb?highlight=7)] diff --git a/docs/visual-basic/language-reference/error-messages/some-subkeys-cannot-be-deleted.md b/docs/visual-basic/language-reference/error-messages/some-subkeys-cannot-be-deleted.md index 0ac080a0a9ed9..c35c806597d4a 100644 --- a/docs/visual-basic/language-reference/error-messages/some-subkeys-cannot-be-deleted.md +++ b/docs/visual-basic/language-reference/error-messages/some-subkeys-cannot-be-deleted.md @@ -6,14 +6,14 @@ ms.assetid: 14562137-af43-4972-84c1-a380a90f7d6c --- # Some subkeys cannot be deleted -An attempt has been made to delete a registry key, but the operation failed because some subkeys cannot be deleted. Usually this is due to a lack of permissions. - -## To correct this error - -- Make sure you have sufficient permissions to delete the specified subkeys. - +An attempt has been made to delete a registry key, but the operation failed because some subkeys cannot be deleted. Usually this is due to a lack of permissions. + +## To correct this error + +- Make sure you have sufficient permissions to delete the specified subkeys. + ## See also - -- +- - diff --git a/docs/visual-basic/language-reference/error-messages/subscript-out-of-range.md b/docs/visual-basic/language-reference/error-messages/subscript-out-of-range.md index dffbcceb888fe..568fdbaf7b05c 100644 --- a/docs/visual-basic/language-reference/error-messages/subscript-out-of-range.md +++ b/docs/visual-basic/language-reference/error-messages/subscript-out-of-range.md @@ -2,19 +2,19 @@ description: "Learn more about: Subscript out of range (Visual Basic)" title: "Subscript out of range" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrID9" ms.assetid: d0344a65-ec02-4caf-8d3c-9977392ca353 --- # Subscript out of range (Visual Basic) -An array subscript is not valid because it falls outside the allowable range. The lowest subscript value for a dimension is always 0, and the highest subscript value is returned by the `GetUpperBound` method for that dimension. - -## To correct this error - -- Change the subscript so it falls within the valid range. - +An array subscript is not valid because it falls outside the allowable range. The lowest subscript value for a dimension is always 0, and the highest subscript value is returned by the `GetUpperBound` method for that dimension. + +## To correct this error + +- Change the subscript so it falls within the valid range. + ## See also -- +- - [Arrays](../../programming-guide/language-features/arrays/index.md) diff --git a/docs/visual-basic/language-reference/error-messages/textfieldparser-is-unable-to-complete-read-operation.md b/docs/visual-basic/language-reference/error-messages/textfieldparser-is-unable-to-complete-read-operation.md index 170a56f96afe2..b91f48c6989a5 100644 --- a/docs/visual-basic/language-reference/error-messages/textfieldparser-is-unable-to-complete-read-operation.md +++ b/docs/visual-basic/language-reference/error-messages/textfieldparser-is-unable-to-complete-read-operation.md @@ -2,21 +2,21 @@ description: "Learn more about: TextFieldParser is unable to complete the read operation because maximum buffer size has been exceeded" title: "TextFieldParser is unable to complete the read operation because maximum buffer size has been exceeded" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrTextFieldParser_BufferExceededMaxSize" ms.assetid: 36565e82-8458-4a08-86af-d9a7a2c32937 --- # TextFieldParser is unable to complete the read operation because maximum buffer size has been exceeded -The operation cannot be completed because the maximum buffer size (10,000,000 bytes) has been exceeded. - -## To correct this error - -- Make sure there are no malformed fields in the file. - +The operation cannot be completed because the maximum buffer size (10,000,000 bytes) has been exceeded. + +## To correct this error + +- Make sure there are no malformed fields in the file. + ## See also -- +- - - [How to: Read From Text Files with Multiple Formats](../../developing-apps/programming/drives-directories-files/how-to-read-from-text-files-with-multiple-formats.md) - [Parsing Text Files with the TextFieldParser Object](../../developing-apps/programming/drives-directories-files/parsing-text-files-with-the-textfieldparser-object.md) diff --git a/docs/visual-basic/language-reference/error-messages/type-of-variablename-cannot-be-inferred.md b/docs/visual-basic/language-reference/error-messages/type-of-variablename-cannot-be-inferred.md index 62842c8e72fe2..627039957348d 100644 --- a/docs/visual-basic/language-reference/error-messages/type-of-variablename-cannot-be-inferred.md +++ b/docs/visual-basic/language-reference/error-messages/type-of-variablename-cannot-be-inferred.md @@ -60,7 +60,7 @@ Dim n = 20 ## See also -- +- - [For...Next Statement](../statements/for-next-statement.md) - [Implicit and Explicit Conversions](../../programming-guide/language-features/data-types/implicit-and-explicit-conversions.md) - [Local Type Inference](../../programming-guide/language-features/variables/local-type-inference.md) diff --git a/docs/visual-basic/language-reference/functions/conversion-functions.md b/docs/visual-basic/language-reference/functions/conversion-functions.md index e7703b9d2644a..a689e5248f4c7 100644 --- a/docs/visual-basic/language-reference/functions/conversion-functions.md +++ b/docs/visual-basic/language-reference/functions/conversion-functions.md @@ -17,16 +17,16 @@ ms.assetid: 8a8fb553-a8ac-424e-8103-26eea25eaa71 # Conversion functions (Visual Basic) -- -- +- +- - [CBool Function](type-conversion-functions.md) - [CByte Function](type-conversion-functions.md) - [CChar Function](type-conversion-functions.md) - [CDate Function](type-conversion-functions.md) - [CDbl Function](type-conversion-functions.md) - [CDec Function](type-conversion-functions.md) -- -- +- +- - [CInt Function](type-conversion-functions.md) - [CLng Function](type-conversion-functions.md) - [CObj Function](type-conversion-functions.md) @@ -38,11 +38,11 @@ ms.assetid: 8a8fb553-a8ac-424e-8103-26eea25eaa71 - [CUInt Function](type-conversion-functions.md) - [CULng Function](type-conversion-functions.md) - [CUShort Function](type-conversion-functions.md) -- -- -- -- -- +- +- +- +- +- ## See also diff --git a/docs/visual-basic/language-reference/functions/math-functions.md b/docs/visual-basic/language-reference/functions/math-functions.md index 34402d553c889..82139691b216f 100644 --- a/docs/visual-basic/language-reference/functions/math-functions.md +++ b/docs/visual-basic/language-reference/functions/math-functions.md @@ -2,7 +2,7 @@ description: "Learn more about: Math Functions (Visual Basic)" title: Math functions ms.date: 01/27/2020 -helpviewer_keywords: +helpviewer_keywords: - "math functions, Visual Basic" - "arithmetic operations, math functions" - "math routines" @@ -16,54 +16,54 @@ The methods of the class provide ## Remarks The following table lists methods of the class. You can use these in a Visual Basic program: - + |.NET method|Description| |---------------------------|-----------------| -||Returns the absolute value of a number.| -||Returns the angle whose cosine is the specified number.| -||Returns the angle whose sine is the specified number.| -||Returns the angle whose tangent is the specified number.| -||Returns the angle whose tangent is the quotient of two specified numbers.| -||Returns the full product of two 32-bit numbers.| -||Returns the smallest integral value that's greater than or equal to the specified `Decimal` or `Double`.| -||Returns the cosine of the specified angle.| -||Returns the hyperbolic cosine of the specified angle.| -||Returns the quotient of two 32-bit or 64-bit signed integers, and also returns the remainder in an output parameter.| -||Returns e (the base of natural logarithms) raised to the specified power.| -||Returns the largest integer that's less than or equal to the specified `Decimal` or `Double` number.| -||Returns the remainder that results from the division of a specified number by another specified number.| -||Returns the natural (base e) logarithm of a specified number or the logarithm of a specified number in a specified base.| -||Returns the base 10 logarithm of a specified number.| -||Returns the larger of two numbers.| -||Returns the smaller of two numbers.| -||Returns a specified number raised to the specified power.| -||Returns a `Decimal` or `Double` value rounded to the nearest integral value or to a specified number of fractional digits.| -||Returns an `Integer` value indicating the sign of a number.| -||Returns the sine of the specified angle.| -||Returns the hyperbolic sine of the specified angle.| -||Returns the square root of a specified number.| -||Returns the tangent of the specified angle.| -||Returns the hyperbolic tangent of the specified angle.| -||Calculates the integral part of a specified `Decimal` or `Double` number.| +||Returns the absolute value of a number.| +||Returns the angle whose cosine is the specified number.| +||Returns the angle whose sine is the specified number.| +||Returns the angle whose tangent is the specified number.| +||Returns the angle whose tangent is the quotient of two specified numbers.| +||Returns the full product of two 32-bit numbers.| +||Returns the smallest integral value that's greater than or equal to the specified `Decimal` or `Double`.| +||Returns the cosine of the specified angle.| +||Returns the hyperbolic cosine of the specified angle.| +||Returns the quotient of two 32-bit or 64-bit signed integers, and also returns the remainder in an output parameter.| +||Returns e (the base of natural logarithms) raised to the specified power.| +||Returns the largest integer that's less than or equal to the specified `Decimal` or `Double` number.| +||Returns the remainder that results from the division of a specified number by another specified number.| +||Returns the natural (base e) logarithm of a specified number or the logarithm of a specified number in a specified base.| +||Returns the base 10 logarithm of a specified number.| +||Returns the larger of two numbers.| +||Returns the smaller of two numbers.| +||Returns a specified number raised to the specified power.| +||Returns a `Decimal` or `Double` value rounded to the nearest integral value or to a specified number of fractional digits.| +||Returns an `Integer` value indicating the sign of a number.| +||Returns the sine of the specified angle.| +||Returns the hyperbolic sine of the specified angle.| +||Returns the square root of a specified number.| +||Returns the tangent of the specified angle.| +||Returns the hyperbolic tangent of the specified angle.| +||Calculates the integral part of a specified `Decimal` or `Double` number.| The following table lists methods of the class that don't exist in .NET Framework but are added in .NET Standard or .NET Core: |.NET method|Description|Available in| |---------------------------|-----------------|-----------| -||Returns the angle whose hyperbolic cosine is the specified number.|Starting with .NET Core 2.1 and .NET Standard 2.1| -||Returns the angle whose hyperbolic sine is the specified number.|Starting with .NET Core 2.1 and .NET Standard 2.1| -||Returns the angle whose hyperbolic tangent is the specified number.|Starting with .NET Core 2.1 and .NET Standard 2.1| -||Returns the next smallest value that compares less than `x`.|Starting with .NET Core 3.0| -||Returns the next largest value that compares greater than `x`.|Starting with .NET Core 3.0| -||Returns the cube root of a specified number.|Starting with .NET Core 2.1 and .NET Standard 2.1| -||Returns `value` clamped to the inclusive range of `min` and `max`.|Starting with .NET Core 2.0 and .NET Standard 2.1| -||Returns a value with the magnitude of `x` and the sign of `y`.|Starting with .NET Core 3.0| -||Returns (x \* y) + z, rounded as one ternary operation.|Starting with .NET Core 3.0| -||Returns the base 2 integer logarithm of a specified number.|Starting with .NET Core 3.0| -||Returns the base 2 logarithm of a specified number.|Starting with .NET Core 3.0| -||Returns the larger magnitude of two double-precision floating-point numbers.|Starting with .NET Core 3.0| -||Returns the smaller magnitude of two double-precision floating-point numbers.|Starting with .NET Core 3.0| -||Returns x \* 2^n computed efficiently.|Starting with .NET Core 3.0| +||Returns the angle whose hyperbolic cosine is the specified number.|Starting with .NET Core 2.1 and .NET Standard 2.1| +||Returns the angle whose hyperbolic sine is the specified number.|Starting with .NET Core 2.1 and .NET Standard 2.1| +||Returns the angle whose hyperbolic tangent is the specified number.|Starting with .NET Core 2.1 and .NET Standard 2.1| +||Returns the next smallest value that compares less than `x`.|Starting with .NET Core 3.0| +||Returns the next largest value that compares greater than `x`.|Starting with .NET Core 3.0| +||Returns the cube root of a specified number.|Starting with .NET Core 2.1 and .NET Standard 2.1| +||Returns `value` clamped to the inclusive range of `min` and `max`.|Starting with .NET Core 2.0 and .NET Standard 2.1| +||Returns a value with the magnitude of `x` and the sign of `y`.|Starting with .NET Core 3.0| +||Returns (x \* y) + z, rounded as one ternary operation.|Starting with .NET Core 3.0| +||Returns the base 2 integer logarithm of a specified number.|Starting with .NET Core 3.0| +||Returns the base 2 logarithm of a specified number.|Starting with .NET Core 3.0| +||Returns the larger magnitude of two double-precision floating-point numbers.|Starting with .NET Core 3.0| +||Returns the smaller magnitude of two double-precision floating-point numbers.|Starting with .NET Core 3.0| +||Returns x \* 2^n computed efficiently.|Starting with .NET Core 3.0| To use these functions without qualification, import the namespace into your project by adding the following code to the top of your source file: @@ -73,7 +73,7 @@ Imports System.Math ## Example - Abs -This example uses the method of the class to compute the absolute value of a number. +This example uses the method of the class to compute the absolute value of a number. ```vb Dim x As Double = Math.Abs(50.3) @@ -83,11 +83,11 @@ Console.WriteLine(y) ' This example produces the following output: ' 50.3 ' 50.3 -``` +``` ## Example - Atan -This example uses the method of the class to calculate the value of pi. +This example uses the method of the class to calculate the value of pi. ```vb Public Function GetPi() As Double @@ -101,7 +101,7 @@ End Function ## Example - Cos -This example uses the method of the class to return the cosine of an angle. +This example uses the method of the class to return the cosine of an angle. ```vb Public Function Sec(angle As Double) As Double @@ -112,7 +112,7 @@ End Function ## Example - Exp -This example uses the method of the class to return e raised to a power. +This example uses the method of the class to return e raised to a power. ```vb Public Function Sinh(angle As Double) As Double @@ -123,7 +123,7 @@ End Function ## Example - Log -This example uses the method of the class to return the natural logarithm of a number. +This example uses the method of the class to return the natural logarithm of a number. ```vb Public Function Asinh(value As Double) As Double @@ -134,7 +134,7 @@ End Function ## Example - Round -This example uses the method of the class to round a number to the nearest integer. +This example uses the method of the class to round a number to the nearest integer. ```vb Dim myVar2 As Double = Math.Round(2.8) @@ -145,7 +145,7 @@ Console.WriteLine(myVar2) ## Example - Sign -This example uses the method of the class to determine the sign of a number. +This example uses the method of the class to determine the sign of a number. ```vb Dim mySign1 As Integer = Math.Sign(12) @@ -162,7 +162,7 @@ Console.WriteLine(mySign3) ## Example - Sin -This example uses the method of the class to return the sine of an angle. +This example uses the method of the class to return the sine of an angle. ```vb Public Function Csc(angle As Double) As Double @@ -173,7 +173,7 @@ End Function ## Example - Sqrt -This example uses the method of the class to calculate the square root of a number. +This example uses the method of the class to calculate the square root of a number. ```vb Dim mySqrt1 As Double = Math.Sqrt(4) @@ -193,7 +193,7 @@ Console.WriteLine(mySqrt4) ## Example - Tan -This example uses the method of the class to return the tangent of an angle. +This example uses the method of the class to return the tangent of an angle. ```vb Public Function Ctan(angle As Double) As Double @@ -204,8 +204,8 @@ End Function ## See also -- -- +- +- - - [Derived Math Functions](../keywords/derived-math-functions.md) - [Arithmetic Operators](../operators/arithmetic-operators.md) diff --git a/docs/visual-basic/language-reference/functions/return-values-for-the-cstr-function.md b/docs/visual-basic/language-reference/functions/return-values-for-the-cstr-function.md index e7f1988f23c6c..3584269dca365 100644 --- a/docs/visual-basic/language-reference/functions/return-values-for-the-cstr-function.md +++ b/docs/visual-basic/language-reference/functions/return-values-for-the-cstr-function.md @@ -2,7 +2,7 @@ description: "Learn more about: Return Values for the CStr Function (Visual Basic)" title: "Return Values for the CStr Function" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "times [Visual Basic], CStr Function return values" - "type conversion [Visual Basic]" - "dates [Visual Basic], CStr Function return values" @@ -15,25 +15,25 @@ ms.assetid: 3aa744e7-1419-45d5-85e3-e5abc2953673 --- # Return Values for the CStr Function (Visual Basic) -The following table describes the return values for `CStr` for different data types of `expression`. - -|If `expression` type is|`CStr` returns| -|-----------------------------|--------------------| -|[Boolean Data Type](../data-types/boolean-data-type.md)|A string containing "True" or "False".| -|[Date Data Type](../data-types/date-data-type.md)|A string containing a `Date` value (date and time) in the short date format of your system.| +The following table describes the return values for `CStr` for different data types of `expression`. + +|If `expression` type is|`CStr` returns| +|-----------------------------|--------------------| +|[Boolean Data Type](../data-types/boolean-data-type.md)|A string containing "True" or "False".| +|[Date Data Type](../data-types/date-data-type.md)|A string containing a `Date` value (date and time) in the short date format of your system.| |[Numeric Data Types](../../programming-guide/language-features/data-types/numeric-data-types.md)|A string representing the number.| |[Nothing](../../language-reference/nothing.md) | `Nothing`| - -## CStr and Date - The `Date` type always contains both date and time information. For purposes of type conversion, Visual Basic considers 1/1/0001 (January 1 of the year 1) to be a *neutral value* for the date, and 00:00:00 (midnight) to be a neutral value for the time. `CStr` does not include neutral values in the resulting string. For example, if you convert `#January 1, 0001 9:30:00#` to a string, the result is "9:30:00 AM"; the date information is suppressed. However, the date information is still present in the original `Date` value and can be recovered with functions such as . - +## CStr and Date + + The `Date` type always contains both date and time information. For purposes of type conversion, Visual Basic considers 1/1/0001 (January 1 of the year 1) to be a *neutral value* for the date, and 00:00:00 (midnight) to be a neutral value for the time. `CStr` does not include neutral values in the resulting string. For example, if you convert `#January 1, 0001 9:30:00#` to a string, the result is "9:30:00 AM"; the date information is suppressed. However, the date information is still present in the original `Date` value and can be recovered with functions such as . + > [!NOTE] -> The `CStr` function performs its conversion based on the current culture settings for the application. To get the string representation of a number in a particular culture, use the number's `ToString(IFormatProvider)` method. For example, use when converting a value of type `Double` to a `String`. - +> The `CStr` function performs its conversion based on the current culture settings for the application. To get the string representation of a number in a particular culture, use the number's `ToString(IFormatProvider)` method. For example, use when converting a value of type `Double` to a `String`. + ## See also -- +- - [Type Conversion Functions](type-conversion-functions.md) - [Boolean Data Type](../data-types/boolean-data-type.md) - [Date Data Type](../data-types/date-data-type.md) diff --git a/docs/visual-basic/language-reference/functions/string-functions.md b/docs/visual-basic/language-reference/functions/string-functions.md index 42210e5bc4155..0f9d9bc82009e 100644 --- a/docs/visual-basic/language-reference/functions/string-functions.md +++ b/docs/visual-basic/language-reference/functions/string-functions.md @@ -12,35 +12,35 @@ The following table lists the functions that Visual Basic provides in the , |Returns an `Integer` value representing the character code corresponding to a character.| -|, |Returns the character associated with the specified character code.| -||Returns a zero-based array containing a subset of a `String` array based on specified filter criteria.| -||Returns a string formatted according to instructions contained in a format `String` expression.| -||Returns an expression formatted as a currency value using the currency symbol defined in the system control panel.| -||Returns a string expression representing a date/time value.| -||Returns an expression formatted as a number.| -||Returns an expression formatted as a percentage (that is, multiplied by 100) with a trailing % character.| -||Returns an integer specifying the start position of the first occurrence of one string within another.| -||Returns the position of the first occurrence of one string within another, starting from the right side of the string.| -||Returns a string created by joining a number of substrings contained in an array.| -||Returns a string or character converted to lowercase.| -||Returns a string containing a specified number of characters from the left side of a string.| -||Returns an integer that contains the number of characters in a string.| -||Returns a left-aligned string containing the specified string adjusted to the specified length.| -||Returns a string containing a copy of a specified string with no leading spaces.| -||Returns a string containing a specified number of characters from a string.| -||Returns a string in which a specified substring has been replaced with another substring a specified number of times.| -||Returns a string containing a specified number of characters from the right side of a string.| -||Returns a right-aligned string containing the specified string adjusted to the specified length.| -||Returns a string containing a copy of a specified string with no trailing spaces.| -||Returns a string consisting of the specified number of spaces.| -||Returns a zero-based, one-dimensional array containing a specified number of substrings.| -||Returns -1, 0, or 1, based on the result of a string comparison.| -||Returns a string converted as specified.| -||Returns a string or object consisting of the specified character repeated the specified number of times.| -||Returns a string in which the character order of a specified string is reversed.| -||Returns a string containing a copy of a specified string with no leading or trailing spaces.| -||Returns a string or character containing the specified string converted to uppercase.| +|, |Returns an `Integer` value representing the character code corresponding to a character.| +|, |Returns the character associated with the specified character code.| +||Returns a zero-based array containing a subset of a `String` array based on specified filter criteria.| +||Returns a string formatted according to instructions contained in a format `String` expression.| +||Returns an expression formatted as a currency value using the currency symbol defined in the system control panel.| +||Returns a string expression representing a date/time value.| +||Returns an expression formatted as a number.| +||Returns an expression formatted as a percentage (that is, multiplied by 100) with a trailing % character.| +||Returns an integer specifying the start position of the first occurrence of one string within another.| +||Returns the position of the first occurrence of one string within another, starting from the right side of the string.| +||Returns a string created by joining a number of substrings contained in an array.| +||Returns a string or character converted to lowercase.| +||Returns a string containing a specified number of characters from the left side of a string.| +||Returns an integer that contains the number of characters in a string.| +||Returns a left-aligned string containing the specified string adjusted to the specified length.| +||Returns a string containing a copy of a specified string with no leading spaces.| +||Returns a string containing a specified number of characters from a string.| +||Returns a string in which a specified substring has been replaced with another substring a specified number of times.| +||Returns a string containing a specified number of characters from the right side of a string.| +||Returns a right-aligned string containing the specified string adjusted to the specified length.| +||Returns a string containing a copy of a specified string with no trailing spaces.| +||Returns a string consisting of the specified number of spaces.| +||Returns a zero-based, one-dimensional array containing a specified number of substrings.| +||Returns -1, 0, or 1, based on the result of a string comparison.| +||Returns a string converted as specified.| +||Returns a string or object consisting of the specified character repeated the specified number of times.| +||Returns a string in which the character order of a specified string is reversed.| +||Returns a string containing a copy of a specified string with no leading or trailing spaces.| +||Returns a string or character containing the specified string converted to uppercase.| You can use the [Option Compare](../statements/option-compare-statement.md) statement to set whether strings are compared using a case-insensitive text sort order determined by your system's locale (`Text`) or by the internal binary representations of the characters (`Binary`). The default text comparison method is `Binary`. diff --git a/docs/visual-basic/language-reference/functions/type-conversion-functions.md b/docs/visual-basic/language-reference/functions/type-conversion-functions.md index 3e64554f4732b..ce32cb40f8105 100644 --- a/docs/visual-basic/language-reference/functions/type-conversion-functions.md +++ b/docs/visual-basic/language-reference/functions/type-conversion-functions.md @@ -110,7 +110,7 @@ CUShort(expression) ## Part -`expression` +`expression` Required. Any expression of the source data type. ## Return Value Data Type @@ -178,15 +178,15 @@ Dim i3 As Integer = CInt(Math.Round(s)) ' Result: 174 If the fractional part is exactly 0.5, the integer conversion functions round it to the nearest even integer. For example, 0.5 rounds to 0, and 1.5 and 2.5 both round to 2. This is sometimes called *banker's rounding*, and its purpose is to compensate for a bias that could accumulate when adding many such numbers together. - `CInt` and `CLng` differ from the and functions, which truncate, rather than round, the fractional part of a number. Also, `Fix` and `Int` always return a value of the same data type as you pass in. + `CInt` and `CLng` differ from the and functions, which truncate, rather than round, the fractional part of a number. Also, `Fix` and `Int` always return a value of the same data type as you pass in. -- **Date/Time Conversions.** Use the function to determine if a value can be converted to a date and time. `CDate` recognizes date literals and time literals but not numeric values. To convert a Visual Basic 6.0 `Date` value to a `Date` value in Visual Basic 2005 or later versions, you can use the method. +- **Date/Time Conversions.** Use the function to determine if a value can be converted to a date and time. `CDate` recognizes date literals and time literals but not numeric values. To convert a Visual Basic 6.0 `Date` value to a `Date` value in Visual Basic 2005 or later versions, you can use the method. -- **Neutral Date/Time Values.** The [Date Data Type](../data-types/date-data-type.md) always contains both date and time information. For purposes of type conversion, Visual Basic considers 1/1/0001 (January 1 of the year 1) to be a *neutral value* for the date, and 00:00:00 (midnight) to be a neutral value for the time. If you convert a `Date` value to a string, `CStr` does not include neutral values in the resulting string. For example, if you convert `#January 1, 0001 9:30:00#` to a string, the result is "9:30:00 AM"; the date information is suppressed. However, the date information is still present in the original `Date` value and can be recovered with functions such as function. +- **Neutral Date/Time Values.** The [Date Data Type](../data-types/date-data-type.md) always contains both date and time information. For purposes of type conversion, Visual Basic considers 1/1/0001 (January 1 of the year 1) to be a *neutral value* for the date, and 00:00:00 (midnight) to be a neutral value for the time. If you convert a `Date` value to a string, `CStr` does not include neutral values in the resulting string. For example, if you convert `#January 1, 0001 9:30:00#` to a string, the result is "9:30:00 AM"; the date information is suppressed. However, the date information is still present in the original `Date` value and can be recovered with functions such as function. - **Culture Sensitivity.** The type conversion functions involving strings perform conversions based on the current culture settings for the application. For example, `CDate` recognizes date formats according to the locale setting of your system. You must provide the day, month, and year in the correct order for your locale, or the date might not be interpreted correctly. A long date format is not recognized if it contains a day-of-the-week string, such as "Wednesday". - If you need to convert to or from a string representation of a value in a format other than the one specified by your locale, you cannot use the Visual Basic type conversion functions. To do this, use the `ToString(IFormatProvider)` and `Parse(String, IFormatProvider)` methods of that value's type. For example, use when converting a string to a `Double`, and use when converting a value of type `Double` to a string. + If you need to convert to or from a string representation of a value in a format other than the one specified by your locale, you cannot use the Visual Basic type conversion functions. To do this, use the `ToString(IFormatProvider)` and `Parse(String, IFormatProvider)` methods of that value's type. For example, use when converting a string to a `Double`, and use when converting a value of type `Double` to a string. ## CType Operator @@ -212,7 +212,7 @@ The following example uses the `CChar` function to convert the first character o [!code-vb[VbVbalrFunctions#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrFunctions/VB/Class1.vb#3)] -The input argument to `CChar` must be of data type `Char` or `String`. You cannot use `CChar` to convert a number to a character, because `CChar` cannot accept a numeric data type. The following example obtains a number representing a code point (character code) and converts it to the corresponding character. It uses the function to obtain the string of digits, `CInt` to convert the string to type `Integer`, and `ChrW` to convert the number to type `Char`. +The input argument to `CChar` must be of data type `Char` or `String`. You cannot use `CChar` to convert a number to a character, because `CChar` cannot accept a numeric data type. The following example obtains a number representing a code point (character code) and converts it to the corresponding character. It uses the function to obtain the string of digits, `CInt` to convert the string to type `Integer`, and `ChrW` to convert the number to type `Char`. [!code-vb[VbVbalrFunctions#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrFunctions/VB/Class1.vb#4)] @@ -302,16 +302,16 @@ The following example uses the `CUShort` function to convert a numeric value to ## See also -- -- -- -- -- -- -- -- -- -- -- +- +- +- +- +- +- +- +- +- +- +- - [Conversion Functions](conversion-functions.md) - [Type Conversions in Visual Basic](../../programming-guide/language-features/data-types/type-conversions.md) diff --git a/docs/visual-basic/language-reference/keywords/arrays-summary.md b/docs/visual-basic/language-reference/keywords/arrays-summary.md index 18a0150f7a128..48f4c02d79735 100644 --- a/docs/visual-basic/language-reference/keywords/arrays-summary.md +++ b/docs/visual-basic/language-reference/keywords/arrays-summary.md @@ -2,21 +2,21 @@ description: "Learn more about: Arrays Summary (Visual Basic)" title: "Arrays Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "arrays [Visual Basic]" ms.assetid: 167f77d4-7cb2-4a31-9dc9-0fd0b26fda7e --- # Arrays Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Verify an array.|| -|Declare and initialize an array.|[Dim](../statements/dim-statement.md), [Private](../modifiers/private.md), [Public](../modifiers/public.md), [ReDim](../statements/redim-statement.md)| -|Find the limits of an array.|, | -|Reinitialize an array|[Erase](../statements/erase-statement.md), [ReDim](../statements/redim-statement.md)| - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Verify an array.|| +|Declare and initialize an array.|[Dim](../statements/dim-statement.md), [Private](../modifiers/private.md), [Public](../modifiers/public.md), [ReDim](../statements/redim-statement.md)| +|Find the limits of an array.|, | +|Reinitialize an array|[Erase](../statements/erase-statement.md), [ReDim](../statements/redim-statement.md)| + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/collection-object-summary.md b/docs/visual-basic/language-reference/keywords/collection-object-summary.md index 4e4071439ba77..822184c649050 100644 --- a/docs/visual-basic/language-reference/keywords/collection-object-summary.md +++ b/docs/visual-basic/language-reference/keywords/collection-object-summary.md @@ -2,22 +2,22 @@ description: "Learn more about: Collection Object Summary (Visual Basic)" title: "Collection Object Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "Collection object, summary" ms.assetid: c4586369-d817-4453-9cb0-1a272fc66737 --- # Collection Object Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Create a `Collection` object.|| -|Add an item to a collection.|| -|Remove an object from a collection.|| -|Reference an item in a collection.|| -|Return a reference to an interface.|| - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Create a `Collection` object.|| +|Add an item to a collection.|| +|Remove an object from a collection.|| +|Reference an item in a collection.|| +|Return a reference to an interface.|| + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/control-flow-summary.md b/docs/visual-basic/language-reference/keywords/control-flow-summary.md index 1644d452a0be7..35080c3364342 100644 --- a/docs/visual-basic/language-reference/keywords/control-flow-summary.md +++ b/docs/visual-basic/language-reference/keywords/control-flow-summary.md @@ -2,22 +2,22 @@ description: "Learn more about: Control Flow Summary (Visual Basic)" title: "Control Flow Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "decision structures [Visual Basic]" ms.assetid: 6885d426-fa87-4e1c-881f-f0e9ec8d98af --- # Control Flow Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Branch.|[GoTo](../statements/goto-statement.md), [On Error](../statements/on-error-statement.md)| -|Exit or pause the program.|[End](../statements/end-statement.md), [Exit](../statements/exit-statement.md), [Stop](../statements/stop-statement.md)| -|Loop.|[Do...Loop](../statements/do-loop-statement.md), [For...Next](../statements/for-next-statement.md), [For Each...Next](../statements/for-each-next-statement.md), [While...End While](../statements/while-end-while-statement.md), [With](../statements/with-end-with-statement.md)| -|Make decisions.|, [If...Then...Else](../statements/if-then-else-statement.md), [Select Case](../statements/select-case-statement.md), | -|Use procedures.|[Call](../statements/call-statement.md), [Function](../statements/function-statement.md), [Property](../statements/property-statement.md), [Sub](../statements/sub-statement.md)| - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Branch.|[GoTo](../statements/goto-statement.md), [On Error](../statements/on-error-statement.md)| +|Exit or pause the program.|[End](../statements/end-statement.md), [Exit](../statements/exit-statement.md), [Stop](../statements/stop-statement.md)| +|Loop.|[Do...Loop](../statements/do-loop-statement.md), [For...Next](../statements/for-next-statement.md), [For Each...Next](../statements/for-each-next-statement.md), [While...End While](../statements/while-end-while-statement.md), [With](../statements/with-end-with-statement.md)| +|Make decisions.|, [If...Then...Else](../statements/if-then-else-statement.md), [Select Case](../statements/select-case-statement.md), | +|Use procedures.|[Call](../statements/call-statement.md), [Function](../statements/function-statement.md), [Property](../statements/property-statement.md), [Sub](../statements/sub-statement.md)| + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/conversion-summary.md b/docs/visual-basic/language-reference/keywords/conversion-summary.md index 54a12f7ef2d75..5a5f74bf42313 100644 --- a/docs/visual-basic/language-reference/keywords/conversion-summary.md +++ b/docs/visual-basic/language-reference/keywords/conversion-summary.md @@ -2,7 +2,7 @@ description: "Learn more about: Conversion Summary (Visual Basic)" title: "Conversion Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "data type conversion [Visual Basic], keywords" - "reference, type conversions" - "conversions [Visual Basic], Visual Basic" @@ -11,22 +11,22 @@ ms.assetid: ae2c79a7-2d62-4fbe-8585-14360d11f987 --- # Conversion Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Convert ANSI value to string.|, | -|Convert string to lowercase or uppercase.|, ,| -|Convert date to serial number.|, | -|Convert decimal number to other bases.|, | -|Convert number to string.|, | -|Convert one data type to another.|[CBool](../functions/type-conversion-functions.md), [CByte](../functions/type-conversion-functions.md), [CDate](../functions/type-conversion-functions.md), [CDbl](../functions/type-conversion-functions.md), [CDec](../functions/type-conversion-functions.md), [CInt](../functions/type-conversion-functions.md), [CLng](../functions/type-conversion-functions.md), [CSng](../functions/type-conversion-functions.md), [CShort](../functions/type-conversion-functions.md), [CStr](../functions/type-conversion-functions.md), [CType](../operators/ctype-operator.md), , | -|Convert date to day, month, weekday, or year.|, , , | -|Convert time to hour, minute, or second.|, , | -|Convert string to ASCII value.|, | -|Convert string to number.|| -|Convert time to serial number.|, | - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Convert ANSI value to string.|, | +|Convert string to lowercase or uppercase.|, ,| +|Convert date to serial number.|, | +|Convert decimal number to other bases.|, | +|Convert number to string.|, | +|Convert one data type to another.|[CBool](../functions/type-conversion-functions.md), [CByte](../functions/type-conversion-functions.md), [CDate](../functions/type-conversion-functions.md), [CDbl](../functions/type-conversion-functions.md), [CDec](../functions/type-conversion-functions.md), [CInt](../functions/type-conversion-functions.md), [CLng](../functions/type-conversion-functions.md), [CSng](../functions/type-conversion-functions.md), [CShort](../functions/type-conversion-functions.md), [CStr](../functions/type-conversion-functions.md), [CType](../operators/ctype-operator.md), , | +|Convert date to day, month, weekday, or year.|, , , | +|Convert time to hour, minute, or second.|, , | +|Convert string to ASCII value.|, | +|Convert string to number.|| +|Convert time to serial number.|, | + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/data-types-summary.md b/docs/visual-basic/language-reference/keywords/data-types-summary.md index 5bdd1d39ee136..9aa2d3ea76b04 100644 --- a/docs/visual-basic/language-reference/keywords/data-types-summary.md +++ b/docs/visual-basic/language-reference/keywords/data-types-summary.md @@ -2,20 +2,20 @@ description: "Learn more about: Data Types Summary (Visual Basic)" title: "Data Types Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "data types [Visual Basic], Visual Basic" ms.assetid: 4ea2ef2a-3d4d-42d9-9f8f-173a37c96e53 --- # Data Types Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Convert between data types|[CBool](../functions/type-conversion-functions.md), [CByte](../functions/type-conversion-functions.md), [CChar](../functions/type-conversion-functions.md), [CDate](../functions/type-conversion-functions.md), [CDbl](../functions/type-conversion-functions.md), [CDec](../functions/type-conversion-functions.md), [CInt](../functions/type-conversion-functions.md), [CLng](../functions/type-conversion-functions.md), [CObj](../functions/type-conversion-functions.md), [CShort](../functions/type-conversion-functions.md), [CSng](../functions/type-conversion-functions.md), [CStr](../functions/type-conversion-functions.md), , | -|Set intrinsic data types|[Boolean](../data-types/boolean-data-type.md), [Byte](../data-types/byte-data-type.md), [Char](../data-types/char-data-type.md), [Date](../data-types/date-data-type.md), [Decimal](../data-types/decimal-data-type.md), [Double](../data-types/double-data-type.md), [Integer](../data-types/integer-data-type.md), [Long](../data-types/long-data-type.md), [Object](../data-types/object-data-type.md), [Short](../data-types/short-data-type.md), [Single](../data-types/single-data-type.md), [String](../data-types/string-data-type.md)| -|Verify data types|, , , , , , | - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Convert between data types|[CBool](../functions/type-conversion-functions.md), [CByte](../functions/type-conversion-functions.md), [CChar](../functions/type-conversion-functions.md), [CDate](../functions/type-conversion-functions.md), [CDbl](../functions/type-conversion-functions.md), [CDec](../functions/type-conversion-functions.md), [CInt](../functions/type-conversion-functions.md), [CLng](../functions/type-conversion-functions.md), [CObj](../functions/type-conversion-functions.md), [CShort](../functions/type-conversion-functions.md), [CSng](../functions/type-conversion-functions.md), [CStr](../functions/type-conversion-functions.md), , | +|Set intrinsic data types|[Boolean](../data-types/boolean-data-type.md), [Byte](../data-types/byte-data-type.md), [Char](../data-types/char-data-type.md), [Date](../data-types/date-data-type.md), [Decimal](../data-types/decimal-data-type.md), [Double](../data-types/double-data-type.md), [Integer](../data-types/integer-data-type.md), [Long](../data-types/long-data-type.md), [Object](../data-types/object-data-type.md), [Short](../data-types/short-data-type.md), [Single](../data-types/single-data-type.md), [String](../data-types/string-data-type.md)| +|Verify data types|, , , , , , | + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/dates-and-times-summary.md b/docs/visual-basic/language-reference/keywords/dates-and-times-summary.md index ee0fa63384aed..77fbf84210775 100644 --- a/docs/visual-basic/language-reference/keywords/dates-and-times-summary.md +++ b/docs/visual-basic/language-reference/keywords/dates-and-times-summary.md @@ -2,7 +2,7 @@ description: "Learn more about: Dates and Times Summary (Visual Basic)" title: "Dates and Times Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "dates [Visual Basic], Visual Basic data types" - "dates [Visual Basic], run-time library members" - "dates [Visual Basic], Visual Basic keywords" @@ -14,17 +14,17 @@ ms.assetid: 914d0563-b53c-492c-ac62-d833ce805f2f --- # Dates and Times Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Get the current date or time.|, , | -|Perform date calculations.|, , | -|Return a date.|, , , | -|Return a time.|, | -|Set the date or time.|, , , | -|Time a process.|| - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Get the current date or time.|, , | +|Perform date calculations.|, , | +|Return a date.|, , , | +|Return a time.|, | +|Set the date or time.|, , , | +|Time a process.|| + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/declarations-and-constants-summary.md b/docs/visual-basic/language-reference/keywords/declarations-and-constants-summary.md index 79aabe921db76..a5c97c1255c8d 100644 --- a/docs/visual-basic/language-reference/keywords/declarations-and-constants-summary.md +++ b/docs/visual-basic/language-reference/keywords/declarations-and-constants-summary.md @@ -2,7 +2,7 @@ description: "Learn more about: Declarations and Constants Summary (Visual Basic)" title: "Declarations and Constants Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "constants [Visual Basic]" - "declaring constants [Visual Basic], keywords" - "declarations [Visual Basic], Visual Basic language elements" @@ -10,20 +10,20 @@ ms.assetid: 79d64f3e-941d-4d39-bc5b-79f225d5be6e --- # Declarations and Constants Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Assign a value.|[Get](../statements/get-statement.md), [Property](../statements/property-statement.md)| -|Declare variables or constants.|[Const](../statements/const-statement.md), [Dim](../statements/dim-statement.md), [Private](../modifiers/private.md), [Protected](../modifiers/protected.md), [Public](../modifiers/public.md), [Shadows](../modifiers/shadows.md), [Shared](../modifiers/shared.md), [Static](../modifiers/static.md)| -|Declare a class, delegate, enumeration, module, namespace, or structure.|[Class](../statements/class-statement.md), [Delegate](../statements/delegate-statement.md), [Enum](../statements/enum-statement.md), [Module](../statements/module-statement.md), [Namespace](../statements/namespace-statement.md), [Structure](../statements/structure-statement.md)| -|Create objects.|, , [New](../operators/new-operator.md)| -|Get information about an object.|[GetType](../operators/gettype-operator.md), , , , , , , , , , , | -|Refer to the current object.|[Me](../../programming-guide/program-structure/me-my-mybase-and-myclass.md)| -|Require explicit variable declarations.|[Option Explicit](../statements/option-explicit-statement.md), [Option Strict](../statements/option-strict-statement.md)| -|Handle events.|[AddHandler](../statements/addhandler-statement.md), [Event](../statements/event-statement.md), [RaiseEvent](../statements/raiseevent-statement.md), [RemoveHandler](../statements/removehandler-statement.md)| -|Implement inheritance.|[Inherits](../statements/inherits-statement.md), [MustInherit](../modifiers/mustinherit.md), [MustOverride](../modifiers/mustoverride.md), [MyBase](../../programming-guide/language-features/objects-and-classes/inheritance-basics.md), [MyClass](../../programming-guide/language-features/objects-and-classes/inheritance-basics.md), [New](../operators/new-operator.md), [NotInheritable](../modifiers/notinheritable.md), [NotOverridable](../modifiers/notoverridable.md), [Overloads](../modifiers/overloads.md), [Overridable](../modifiers/overridable.md), [Overrides](../modifiers/overrides.md)| - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Assign a value.|[Get](../statements/get-statement.md), [Property](../statements/property-statement.md)| +|Declare variables or constants.|[Const](../statements/const-statement.md), [Dim](../statements/dim-statement.md), [Private](../modifiers/private.md), [Protected](../modifiers/protected.md), [Public](../modifiers/public.md), [Shadows](../modifiers/shadows.md), [Shared](../modifiers/shared.md), [Static](../modifiers/static.md)| +|Declare a class, delegate, enumeration, module, namespace, or structure.|[Class](../statements/class-statement.md), [Delegate](../statements/delegate-statement.md), [Enum](../statements/enum-statement.md), [Module](../statements/module-statement.md), [Namespace](../statements/namespace-statement.md), [Structure](../statements/structure-statement.md)| +|Create objects.|, , [New](../operators/new-operator.md)| +|Get information about an object.|[GetType](../operators/gettype-operator.md), , , , , , , , , , , | +|Refer to the current object.|[Me](../../programming-guide/program-structure/me-my-mybase-and-myclass.md)| +|Require explicit variable declarations.|[Option Explicit](../statements/option-explicit-statement.md), [Option Strict](../statements/option-strict-statement.md)| +|Handle events.|[AddHandler](../statements/addhandler-statement.md), [Event](../statements/event-statement.md), [RaiseEvent](../statements/raiseevent-statement.md), [RemoveHandler](../statements/removehandler-statement.md)| +|Implement inheritance.|[Inherits](../statements/inherits-statement.md), [MustInherit](../modifiers/mustinherit.md), [MustOverride](../modifiers/mustoverride.md), [MyBase](../../programming-guide/language-features/objects-and-classes/inheritance-basics.md), [MyClass](../../programming-guide/language-features/objects-and-classes/inheritance-basics.md), [New](../operators/new-operator.md), [NotInheritable](../modifiers/notinheritable.md), [NotOverridable](../modifiers/notoverridable.md), [Overloads](../modifiers/overloads.md), [Overridable](../modifiers/overridable.md), [Overrides](../modifiers/overrides.md)| + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/directories-and-files-summary.md b/docs/visual-basic/language-reference/keywords/directories-and-files-summary.md index 435d466c8cbf1..a1caf882c6ab1 100644 --- a/docs/visual-basic/language-reference/keywords/directories-and-files-summary.md +++ b/docs/visual-basic/language-reference/keywords/directories-and-files-summary.md @@ -2,7 +2,7 @@ description: "Learn more about: Directories and Files Summary (Visual Basic)" title: "Directories and Files Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "files [Visual Basic]" - "directories [Visual Basic], Visual Basic" - "files [Visual Basic], summary" @@ -10,25 +10,25 @@ ms.assetid: 588b75fd-a09b-4381-822d-19868990c170 --- # Directories and Files Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - - Using the `My` feature gives you greater productivity and performance in file I/O operations than using these members. For more information, see . - -|**Action**|**Language element**| -|----------------|--------------------------| -|Change a directory or folder.|| -|Change the drive.|| -|Copy a file.|| -|Make a directory or folder.|| -|Remove a directory or folder.|| -|Rename a file, directory, or folder.|| -|Return the current path.|| -|Return a file's date/time stamp.|| -|Return file, directory, or label attributes.|| -|Return a file's length.|| -|Return a file's name or volume label.|| -|Set attribute information for a file.|| - +Visual Basic language keywords and run-time library members are organized by purpose and use. + + Using the `My` feature gives you greater productivity and performance in file I/O operations than using these members. For more information, see . + +|**Action**|**Language element**| +|----------------|--------------------------| +|Change a directory or folder.|| +|Change the drive.|| +|Copy a file.|| +|Make a directory or folder.|| +|Remove a directory or folder.|| +|Rename a file, directory, or folder.|| +|Return the current path.|| +|Return a file's date/time stamp.|| +|Return file, directory, or label attributes.|| +|Return a file's length.|| +|Return a file's name or volume label.|| +|Set attribute information for a file.|| + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/errors-summary.md b/docs/visual-basic/language-reference/keywords/errors-summary.md index 4d966e515a2d1..d463ee01209b9 100644 --- a/docs/visual-basic/language-reference/keywords/errors-summary.md +++ b/docs/visual-basic/language-reference/keywords/errors-summary.md @@ -2,23 +2,23 @@ description: "Learn more about: Errors Summary (Visual Basic)" title: "Errors Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "errors [Visual Basic]" ms.assetid: 2557da60-c6dc-4e99-8128-fceb6f8a0736 --- # Errors Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Generate run-time errors.|, [Error](../statements/error-statement.md), | -|Get exceptions.|| -|Provide error information.|| -|Trap errors during run time.|[On Error](../statements/on-error-statement.md), [Resume](../statements/resume-statement.md), [Try...Catch...Finally](../statements/try-catch-finally-statement.md)| -|Provide line number of error.|| -|Provide system error code.|| - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Generate run-time errors.|, [Error](../statements/error-statement.md), | +|Get exceptions.|| +|Provide error information.|| +|Trap errors during run time.|[On Error](../statements/on-error-statement.md), [Resume](../statements/resume-statement.md), [Try...Catch...Finally](../statements/try-catch-finally-statement.md)| +|Provide line number of error.|| +|Provide system error code.|| + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/financial-summary.md b/docs/visual-basic/language-reference/keywords/financial-summary.md index d429da8d8ea2a..18c17c4efaca1 100644 --- a/docs/visual-basic/language-reference/keywords/financial-summary.md +++ b/docs/visual-basic/language-reference/keywords/financial-summary.md @@ -2,25 +2,25 @@ description: "Learn more about: Financial Summary (Visual Basic)" title: "Financial Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "financial functions" - "payment" ms.assetid: 474f973e-7103-42b7-aa4d-367c935e07e1 --- # Financial Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Calculate depreciation.|, , | -|Calculate future value.|| -|Calculate interest rate.|| -|Calculate internal rate of return.|, | -|Calculate number of periods.|| -|Calculate payments.|, , | -|Calculate present value.|, | - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Calculate depreciation.|, , | +|Calculate future value.|| +|Calculate interest rate.|| +|Calculate internal rate of return.|, | +|Calculate number of periods.|| +|Calculate payments.|, , | +|Calculate present value.|, | + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/information-and-interaction-summary.md b/docs/visual-basic/language-reference/keywords/information-and-interaction-summary.md index 3a74946b7d515..b45b702fd88a5 100644 --- a/docs/visual-basic/language-reference/keywords/information-and-interaction-summary.md +++ b/docs/visual-basic/language-reference/keywords/information-and-interaction-summary.md @@ -2,25 +2,25 @@ description: "Learn more about: Information and Interaction Summary (Visual Basic)" title: "Information and Interaction Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "information functions [Visual Basic]" - "interaction functions [Visual Basic]" ms.assetid: 6e698461-e944-4c0f-ae48-87429f1fe740 --- # Information and Interaction Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Run other programs.|, | -|Call a method or property.|| -|Sound a beep from computer.|| -|Provide a command-line string.|| -|Manipulate COM objects.|, | -|Retrieve color information.|, | -|Control dialog boxes|, | - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Run other programs.|, | +|Call a method or property.|| +|Sound a beep from computer.|| +|Provide a command-line string.|| +|Manipulate COM objects.|, | +|Retrieve color information.|, | +|Control dialog boxes|, | + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/input-and-output-summary.md b/docs/visual-basic/language-reference/keywords/input-and-output-summary.md index 31338612528f5..c73f438b23525 100644 --- a/docs/visual-basic/language-reference/keywords/input-and-output-summary.md +++ b/docs/visual-basic/language-reference/keywords/input-and-output-summary.md @@ -2,7 +2,7 @@ description: "Learn more about: Input and Output Summary (Visual Basic)" title: "Input and Output Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "input, Visual Basic functions" - "output, Visual Basic functions" - "I/O [Visual Basic], functions" @@ -10,23 +10,23 @@ ms.assetid: 6b0cbb88-6593-43b8-8a40-a61563bc0ce9 --- # Input and Output Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Access or create a file.|| -|Close files.|, | -|Control output appearance.|, , , , | -|Copy a file.|| -|Get information about a file.|, , , , , , , , | -|Get or provide information from/to the user by means of a control dialog box.|, | -|Manage files.|, , , | -|Read from a file.|, , , , | -|Return length of a file.|| -|Set or get file attributes.|, , | -|Set read-write position in a file.|| -|Write to a file.|, , , , | - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Access or create a file.|| +|Close files.|, | +|Control output appearance.|, , , , | +|Copy a file.|| +|Get information about a file.|, , , , , , , , | +|Get or provide information from/to the user by means of a control dialog box.|, | +|Manage files.|, , , | +|Read from a file.|, , , , | +|Return length of a file.|| +|Set or get file attributes.|, , | +|Set read-write position in a file.|| +|Write to a file.|, , , , | + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/math-summary.md b/docs/visual-basic/language-reference/keywords/math-summary.md index 2bccf6c533a94..82096e006e36a 100644 --- a/docs/visual-basic/language-reference/keywords/math-summary.md +++ b/docs/visual-basic/language-reference/keywords/math-summary.md @@ -2,7 +2,7 @@ description: "Learn more about: Math Summary (Visual Basic)" title: "Math Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "math functions, summary" - "mathematical functions" - "math functions, Visual Basic" @@ -11,17 +11,17 @@ ms.assetid: 6abf2dd7-92d2-488a-8e2b-819be9b30c3f --- # Math Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Derive trigonometric functions.|, , , | -|General calculations.|, , | -|Generate random numbers.|, | -|Get absolute value.|| -|Get the sign of an expression.|| -|Perform numeric conversions.|, | - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Derive trigonometric functions.|, , , | +|General calculations.|, , | +|Generate random numbers.|, | +|Get absolute value.|| +|Get the sign of an expression.|| +|Perform numeric conversions.|, | + ## See also - [Derived Math Functions](derived-math-functions.md) diff --git a/docs/visual-basic/language-reference/keywords/my-reference.md b/docs/visual-basic/language-reference/keywords/my-reference.md index 8c1febdc226db..52d8d47082fd1 100644 --- a/docs/visual-basic/language-reference/keywords/my-reference.md +++ b/docs/visual-basic/language-reference/keywords/my-reference.md @@ -2,28 +2,28 @@ description: "Learn more about: My Reference (Visual Basic)" title: "My Reference" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "My feature" - "My reference" ms.assetid: 6f803bd7-21ff-4569-b1fe-b00a6678b1e3 --- # My Reference (Visual Basic) -The `My` feature makes programming faster and easier by giving you intuitive access to commonly used methods, properties, and events. This table lists the objects contained in `My`, and the actions that can be performed with each. - -|**Action**|**Object**| -|----------------|----------------| -|Accessing application information and services.|The `My.Application` object consists of the following classes:

provides members that are available in all projects.

provides members available in Windows Forms applications.

provides members available in console applications.| -|Accessing the host computer and its resources, services, and data.|`My.Computer` ()| -|Accessing the forms in the current project.|[My.Forms Object](../objects/my-forms-object.md)| -|Accessing the application log.|`My.Application.Log` ()| -|Accessing the current web request.|[My.Request Object](../objects/my-request-object.md)| -|Accessing resource elements.|[My.Resources Object](../objects/my-resources-object.md)| -|Accessing the current web response.|[My.Response Object](../objects/my-response-object.md)| -|Accessing user and application level settings.|[My.Settings Object](../objects/my-settings-object.md)| -|Accessing the current user's security context.|`My.User` ()| -|Accessing XML Web services referenced by the current project.|[My.WebServices Object](../objects/my-webservices-object.md)| - +The `My` feature makes programming faster and easier by giving you intuitive access to commonly used methods, properties, and events. This table lists the objects contained in `My`, and the actions that can be performed with each. + +|**Action**|**Object**| +|----------------|----------------| +|Accessing application information and services.|The `My.Application` object consists of the following classes:

provides members that are available in all projects.

provides members available in Windows Forms applications.

provides members available in console applications.| +|Accessing the host computer and its resources, services, and data.|`My.Computer` ()| +|Accessing the forms in the current project.|[My.Forms Object](../objects/my-forms-object.md)| +|Accessing the application log.|`My.Application.Log` ()| +|Accessing the current web request.|[My.Request Object](../objects/my-request-object.md)| +|Accessing resource elements.|[My.Resources Object](../objects/my-resources-object.md)| +|Accessing the current web response.|[My.Response Object](../objects/my-response-object.md)| +|Accessing user and application level settings.|[My.Settings Object](../objects/my-settings-object.md)| +|Accessing the current user's security context.|`My.User` ()| +|Accessing XML Web services referenced by the current project.|[My.WebServices Object](../objects/my-webservices-object.md)| + ## See also - [Overview of the Visual Basic Application Model](../../developing-apps/development-with-my/overview-of-the-visual-basic-application-model.md) diff --git a/docs/visual-basic/language-reference/keywords/registry-summary.md b/docs/visual-basic/language-reference/keywords/registry-summary.md index 33de02ea527f3..e65b9958a6918 100644 --- a/docs/visual-basic/language-reference/keywords/registry-summary.md +++ b/docs/visual-basic/language-reference/keywords/registry-summary.md @@ -2,22 +2,22 @@ description: "Learn more about: Registry Summary (Visual Basic)" title: "Registry Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "registry [Visual Basic]" ms.assetid: 6e90eb8a-1a4e-4387-8a68-9287dc7875e8 --- # Registry Summary (Visual Basic) -Visual Studio language keywords and run-time library members are organized by purpose and use. - - Using the `My` feature provides you with greater productivity and performance in registry operations than these elements. For more information, see . - -|**Action**|**Language element**| -|----------------|--------------------------| -|Delete program settings.|| -|Read program settings.|, | -|Save program settings.|| - +Visual Studio language keywords and run-time library members are organized by purpose and use. + + Using the `My` feature provides you with greater productivity and performance in registry operations than these elements. For more information, see . + +|**Action**|**Language element**| +|----------------|--------------------------| +|Delete program settings.|| +|Read program settings.|, | +|Save program settings.|| + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/keywords/string-manipulation-summary.md b/docs/visual-basic/language-reference/keywords/string-manipulation-summary.md index d586da958d4a8..f8e714508b91e 100644 --- a/docs/visual-basic/language-reference/keywords/string-manipulation-summary.md +++ b/docs/visual-basic/language-reference/keywords/string-manipulation-summary.md @@ -2,7 +2,7 @@ description: "Learn more about: String Manipulation Summary (Visual Basic)" title: "String Manipulation Summary" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "string functions" - "manipulating strings [Visual Basic]" - "strings [Visual Basic], manipulating" @@ -10,24 +10,24 @@ ms.assetid: 5d3197eb-fe66-417e-9e2a-20450660c9c6 --- # String Manipulation Summary (Visual Basic) -Visual Basic language keywords and run-time library members are organized by purpose and use. - -|Action|Language element| -|------------|----------------------| -|Compare two strings.|| -|Convert strings.|| -|Reverse a string.|, | -|Convert to lowercase or uppercase.|, , | -|Create a string of repeating characters.|, | -|Find the length of a string.|| -|Format a string.|, , , , | -|Manipulate strings.|, , , , , , | -|Set string comparison rules.|[Option Compare](../statements/option-compare-statement.md)| -|Work with ASCII and ANSI values.|, , , | -|Replace a specified substring.|| -|Return a filter-based string array.|| -|Return a specified number of substrings.|, | - +Visual Basic language keywords and run-time library members are organized by purpose and use. + +|Action|Language element| +|------------|----------------------| +|Compare two strings.|| +|Convert strings.|| +|Reverse a string.|, | +|Convert to lowercase or uppercase.|, , | +|Create a string of repeating characters.|, | +|Find the length of a string.|| +|Format a string.|, , , , | +|Manipulate strings.|, , , , , , | +|Set string comparison rules.|[Option Compare](../statements/option-compare-statement.md)| +|Work with ASCII and ANSI values.|, , , | +|Replace a specified substring.|| +|Return a filter-based string array.|| +|Return a specified number of substrings.|, | + ## See also - [Keywords](index.md) diff --git a/docs/visual-basic/language-reference/modifiers/async.md b/docs/visual-basic/language-reference/modifiers/async.md index 8f256b4a08dd3..55604352e2197 100644 --- a/docs/visual-basic/language-reference/modifiers/async.md +++ b/docs/visual-basic/language-reference/modifiers/async.md @@ -44,7 +44,7 @@ The `Async` keyword is an unreserved keyword. It is a keyword when it modifies a ## Return Types -An async method is either a [Sub](../../programming-guide/language-features/procedures/sub-procedures.md) procedure, or a [Function](../../programming-guide/language-features/procedures/function-procedures.md) procedure that has a return type of or . The method cannot declare any [ByRef](byref.md) parameters. +An async method is either a [Sub](../../programming-guide/language-features/procedures/sub-procedures.md) procedure, or a [Function](../../programming-guide/language-features/procedures/function-procedures.md) procedure that has a return type of or . The method cannot declare any [ByRef](byref.md) parameters. You specify `Task(Of TResult)` for the return type of an async method if the [Return](../statements/return-statement.md) statement of the method has an operand of type TResult. You use `Task` if no meaningful value is returned when the method is completed. That is, a call to the method returns a `Task`, but when the `Task` is completed, any `Await` statement that's awaiting the `Task` doesn’t produce a result value. diff --git a/docs/visual-basic/language-reference/modifiers/in-generic-modifier.md b/docs/visual-basic/language-reference/modifiers/in-generic-modifier.md index 2dbe8ab399cb2..b4fa5e4c99cf5 100644 --- a/docs/visual-basic/language-reference/modifiers/in-generic-modifier.md +++ b/docs/visual-basic/language-reference/modifiers/in-generic-modifier.md @@ -2,9 +2,9 @@ description: "Learn more about: In (Generic Modifier) (Visual Basic)" title: "In (Generic Modifier) - Visual Basic" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.VarianceIn" -helpviewer_keywords: +helpviewer_keywords: - "contravariance, In keyword [Visual Basic]" - "In keyword [Visual Basic]" ms.assetid: 59bb13c5-fe96-42b8-8286-86293d1661c5 @@ -22,7 +22,7 @@ For more information, see [Covariance and Contravariance](../../programming-guid ## Rules You can use the `In` keyword in generic interfaces and delegates. - + A type parameter can be declared contravariant in a generic interface or delegate if it is used only as a type of method arguments and not used as a method return type. `ByRef` parameters cannot be covariant or contravariant. Covariance and contravariance are supported for reference types and not supported for value types. @@ -31,7 +31,7 @@ In Visual Basic, you cannot declare events in contravariant interfaces without s ## Behavior -An interface that has a contravariant type parameter allows its methods to accept arguments of less derived types than those specified by the interface type parameter. For example, because in .NET Framework 4, in the interface, type T is contravariant, you can assign an object of the `IComparer(Of Person)` type to an object of the `IComparer(Of Employee)` type without using any special conversion methods if `Employee` inherits from `Person`. +An interface that has a contravariant type parameter allows its methods to accept arguments of less derived types than those specified by the interface type parameter. For example, because in .NET Framework 4, in the interface, type T is contravariant, you can assign an object of the `IComparer(Of Person)` type to an object of the `IComparer(Of Employee)` type without using any special conversion methods if `Employee` inherits from `Person`. A contravariant delegate can be assigned another delegate of the same type, but with a less derived generic type parameter. diff --git a/docs/visual-basic/language-reference/modifiers/iterator.md b/docs/visual-basic/language-reference/modifiers/iterator.md index 5acf841cdaad9..8b396db495bcb 100644 --- a/docs/visual-basic/language-reference/modifiers/iterator.md +++ b/docs/visual-basic/language-reference/modifiers/iterator.md @@ -2,54 +2,54 @@ description: "Learn more about: Iterator (Visual Basic)" title: "Iterator" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.Iterator" -helpviewer_keywords: +helpviewer_keywords: - "Iterator keyword [Visual Basic]" ms.assetid: 69cb0b04-ac87-49d0-bcfe-810c0d60daff --- # Iterator (Visual Basic) -Specifies that a function or `Get` accessor is an iterator. - -## Remarks - - An *iterator* performs a custom iteration over a collection. An iterator uses the [Yield](../statements/yield-statement.md) statement to return each element in the collection one at a time. When a `Yield` statement is reached, the current location in code is retained. Execution is restarted from that location the next time that the iterator function is called. - - An iterator can be implemented as a function or as a `Get` accessor of a property definition. The `Iterator` modifier appears in the declaration of the iterator function or `Get` accessor. - - You call an iterator from client code by using a [For Each...Next Statement](../statements/for-each-next-statement.md). - - The return type of an iterator function or `Get` accessor can be , , , or . - - An iterator cannot have any `ByRef` parameters. - - An iterator cannot occur in an event, instance constructor, static constructor, or static destructor. - - An iterator can be an anonymous function. For more information, see [Iterators](../../programming-guide/concepts/iterators.md). - -## Usage - - The `Iterator` modifier can be used in these contexts: - -- [Function Statement](../statements/function-statement.md) - -- [Property Statement](../statements/property-statement.md) - +Specifies that a function or `Get` accessor is an iterator. + +## Remarks + + An *iterator* performs a custom iteration over a collection. An iterator uses the [Yield](../statements/yield-statement.md) statement to return each element in the collection one at a time. When a `Yield` statement is reached, the current location in code is retained. Execution is restarted from that location the next time that the iterator function is called. + + An iterator can be implemented as a function or as a `Get` accessor of a property definition. The `Iterator` modifier appears in the declaration of the iterator function or `Get` accessor. + + You call an iterator from client code by using a [For Each...Next Statement](../statements/for-each-next-statement.md). + + The return type of an iterator function or `Get` accessor can be , , , or . + + An iterator cannot have any `ByRef` parameters. + + An iterator cannot occur in an event, instance constructor, static constructor, or static destructor. + + An iterator can be an anonymous function. For more information, see [Iterators](../../programming-guide/concepts/iterators.md). + +## Usage + + The `Iterator` modifier can be used in these contexts: + +- [Function Statement](../statements/function-statement.md) + +- [Property Statement](../statements/property-statement.md) + ## Example 1 - The following example demonstrates an iterator function. The iterator function has a `Yield` statement that is inside a [For…Next](../statements/for-next-statement.md) loop. Each iteration of the [For Each](../statements/for-each-next-statement.md) statement body in `Main` creates a call to the `Power` iterator function. Each call to the iterator function proceeds to the next execution of the `Yield` statement, which occurs during the next iteration of the `For…Next` loop. - - [!code-vb[VbVbalrStatements#98](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class2.vb#98)] - -## Example 2 - - The following example demonstrates a `Get` accessor that is an iterator. The `Iterator` modifier is in the property declaration. - - [!code-vb[VbVbalrStatements#99](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class2.vb#99)] - - For additional examples, see [Iterators](../../programming-guide/concepts/iterators.md). - + The following example demonstrates an iterator function. The iterator function has a `Yield` statement that is inside a [For…Next](../statements/for-next-statement.md) loop. Each iteration of the [For Each](../statements/for-each-next-statement.md) statement body in `Main` creates a call to the `Power` iterator function. Each call to the iterator function proceeds to the next execution of the `Yield` statement, which occurs during the next iteration of the `For…Next` loop. + + [!code-vb[VbVbalrStatements#98](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class2.vb#98)] + +## Example 2 + + The following example demonstrates a `Get` accessor that is an iterator. The `Iterator` modifier is in the property declaration. + + [!code-vb[VbVbalrStatements#99](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class2.vb#99)] + + For additional examples, see [Iterators](../../programming-guide/concepts/iterators.md). + ## See also - diff --git a/docs/visual-basic/language-reference/modifiers/key.md b/docs/visual-basic/language-reference/modifiers/key.md index 3ec23f5e0ceaa..9154bcc282a4d 100644 --- a/docs/visual-basic/language-reference/modifiers/key.md +++ b/docs/visual-basic/language-reference/modifiers/key.md @@ -2,9 +2,9 @@ description: "Learn more about: Key (Visual Basic)" title: "Key" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.AnonymousKey" -helpviewer_keywords: +helpviewer_keywords: - "anonymous types [Visual Basic], key" - "Key [Visual Basic]" - "Key keyword [Visual Basic]" @@ -12,46 +12,46 @@ ms.assetid: 7697a928-7d14-4430-a72a-c9e96e8d6c11 --- # Key (Visual Basic) -The `Key` keyword enables you to specify behavior for properties of anonymous types. Only properties you designate as key properties participate in tests of equality between anonymous type instances, or calculation of hash code values. The values of key properties cannot be changed. - - You designate a property of an anonymous type as a key property by placing the keyword `Key` in front of its declaration in the initialization list. In the following example, `Airline` and `FlightNo` are key properties, but `Gate` is not. - - [!code-vb[VbVbalrAnonymousTypes#26](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#26)] - - When a new anonymous type is created, it inherits directly from . The compiler overrides three inherited members: , , and . The override code that is produced for and is based on key properties. If there are no key properties in the type, and are not overridden. - -## Equality - - Two anonymous type instances are equal if they are instances of the same type and if the values of their key properties are equal. In the following examples, `flight2` is equal to `flight1` from the previous example because they are instances of the same anonymous type and they have matching values for their key properties. However, `flight3` is not equal to `flight1` because it has a different value for a key property, `FlightNo`. Instance `flight4` is not the same type as `flight1` because they designate different properties as key properties. - - [!code-vb[VbVbalrAnonymousTypes#27](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#27)] - - If two instances are declared with only non-key properties, identical in name, type, order, and value, the two instances are not equal. An instance without key properties is equal only to itself. - - For more information about the conditions under which two anonymous type instances are instances of the same anonymous type, see [Anonymous Types](../../programming-guide/language-features/objects-and-classes/anonymous-types.md). - -## Hash Code Calculation - - Like , the hash function that is defined in for an anonymous type is based on the key properties of the type. The following examples show the interaction between key properties and hash code values. - - Instances of an anonymous type that have the same values for all key properties have the same hash code value, even if non-key properties do not have matching values. The following statement returns `True`. - - [!code-vb[VbVbalrAnonymousTypes#37](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#37)] - - Instances of an anonymous type that have different values for one or more key properties have different hash code values. The following statement returns `False`. - - [!code-vb[VbVbalrAnonymousTypes#38](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#38)] - - Instances of anonymous types that designate different properties as key properties are not instances of the same type. They have different hash code values even when the names and values of all properties are the same. The following statement returns `False`. - - [!code-vb[VbVbalrAnonymousTypes#39](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#39)] - -## Read-Only Values - - The values of key properties cannot be changed. For example, in `flight1` in the earlier examples, the `Airline` and `FlightNo` fields are read-only, but `Gate` can be changed. - - [!code-vb[VbVbalrAnonymousTypes#28](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#28)] - +The `Key` keyword enables you to specify behavior for properties of anonymous types. Only properties you designate as key properties participate in tests of equality between anonymous type instances, or calculation of hash code values. The values of key properties cannot be changed. + + You designate a property of an anonymous type as a key property by placing the keyword `Key` in front of its declaration in the initialization list. In the following example, `Airline` and `FlightNo` are key properties, but `Gate` is not. + + [!code-vb[VbVbalrAnonymousTypes#26](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#26)] + + When a new anonymous type is created, it inherits directly from . The compiler overrides three inherited members: , , and . The override code that is produced for and is based on key properties. If there are no key properties in the type, and are not overridden. + +## Equality + + Two anonymous type instances are equal if they are instances of the same type and if the values of their key properties are equal. In the following examples, `flight2` is equal to `flight1` from the previous example because they are instances of the same anonymous type and they have matching values for their key properties. However, `flight3` is not equal to `flight1` because it has a different value for a key property, `FlightNo`. Instance `flight4` is not the same type as `flight1` because they designate different properties as key properties. + + [!code-vb[VbVbalrAnonymousTypes#27](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#27)] + + If two instances are declared with only non-key properties, identical in name, type, order, and value, the two instances are not equal. An instance without key properties is equal only to itself. + + For more information about the conditions under which two anonymous type instances are instances of the same anonymous type, see [Anonymous Types](../../programming-guide/language-features/objects-and-classes/anonymous-types.md). + +## Hash Code Calculation + + Like , the hash function that is defined in for an anonymous type is based on the key properties of the type. The following examples show the interaction between key properties and hash code values. + + Instances of an anonymous type that have the same values for all key properties have the same hash code value, even if non-key properties do not have matching values. The following statement returns `True`. + + [!code-vb[VbVbalrAnonymousTypes#37](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#37)] + + Instances of an anonymous type that have different values for one or more key properties have different hash code values. The following statement returns `False`. + + [!code-vb[VbVbalrAnonymousTypes#38](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#38)] + + Instances of anonymous types that designate different properties as key properties are not instances of the same type. They have different hash code values even when the names and values of all properties are the same. The following statement returns `False`. + + [!code-vb[VbVbalrAnonymousTypes#39](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#39)] + +## Read-Only Values + + The values of key properties cannot be changed. For example, in `flight1` in the earlier examples, the `Airline` and `FlightNo` fields are read-only, but `Gate` can be changed. + + [!code-vb[VbVbalrAnonymousTypes#28](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#28)] + ## See also - [Anonymous Type Definition](../../programming-guide/language-features/objects-and-classes/anonymous-type-definition.md) diff --git a/docs/visual-basic/language-reference/modifiers/out-generic-modifier.md b/docs/visual-basic/language-reference/modifiers/out-generic-modifier.md index e4321e6df8aaf..1ffce776928ed 100644 --- a/docs/visual-basic/language-reference/modifiers/out-generic-modifier.md +++ b/docs/visual-basic/language-reference/modifiers/out-generic-modifier.md @@ -41,7 +41,7 @@ In Visual Basic, you cannot declare events in covariant interfaces without speci ## Behavior -An interface that has a covariant type parameter enables its methods to return more derived types than those specified by the type parameter. For example, because in .NET Framework 4, in , type T is covariant, you can assign an object of the `IEnumerable(Of String)` type to an object of the `IEnumerable(Of Object)` type without using any special conversion methods. +An interface that has a covariant type parameter enables its methods to return more derived types than those specified by the type parameter. For example, because in .NET Framework 4, in , type T is covariant, you can assign an object of the `IEnumerable(Of String)` type to an object of the `IEnumerable(Of Object)` type without using any special conversion methods. A covariant delegate can be assigned another delegate of the same type, but with a more derived generic type parameter. diff --git a/docs/visual-basic/language-reference/modifiers/shared.md b/docs/visual-basic/language-reference/modifiers/shared.md index f9f57860c1492..4f0ac5c71503a 100644 --- a/docs/visual-basic/language-reference/modifiers/shared.md +++ b/docs/visual-basic/language-reference/modifiers/shared.md @@ -31,7 +31,7 @@ Sharing does not alter the access level of a member. For example, a class member - **Accessing.** You access a shared element by qualifying it with its class or structure name, not with the variable name of a specific instance of its class or structure. You do not even have to create an instance of a class or structure to access its shared members. - The following example calls the shared procedure exposed by the structure. + The following example calls the shared procedure exposed by the structure. ```vb If Double.IsNaN(result) Then Console.WriteLine("Result is mathematically undefined.") @@ -46,7 +46,7 @@ Sharing does not alter the access level of a member. For example, a class member - **Accessing through an Instance Variable.** It is possible to access a shared element by qualifying it with the name of a variable that contains a specific instance of its class or structure. Although this usually works as expected, the compiler generates a warning message and makes the access through the class or structure name instead of the variable. - **Accessing through an Instance Expression.** If you access a shared element through an expression that returns an instance of its class or structure, the compiler makes the access through the class or structure name instead of evaluating the expression. This access produces unexpected results if you intended the expression to perform other actions as well as returning the instance. The following example illustrates this situation. - + ```vb Sub Main() ' The following line is the preferred way to access Total. @@ -87,7 +87,7 @@ The `Shared` modifier can be used in these contexts: - [Operator Statement](../statements/operator-statement.md) - [Property Statement](../statements/property-statement.md) - [Sub Statement](../statements/sub-statement.md) - + ## See also - [Shadows](shadows.md) diff --git a/docs/visual-basic/language-reference/objects/index.md b/docs/visual-basic/language-reference/objects/index.md index b9b17ddfd2501..301470c24b666 100644 --- a/docs/visual-basic/language-reference/objects/index.md +++ b/docs/visual-basic/language-reference/objects/index.md @@ -2,45 +2,45 @@ description: "Learn more about: Objects (Visual Basic)" title: "Objects" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "objects [Visual Basic]" ms.assetid: 651c73e4-dca8-402b-9c6b-e3902b3a3f4b --- # Objects (Visual Basic) -This article provides links to other articles that document the Visual Basic run-time objects and contain tables of their member procedures, properties, and events. - -## Visual Basic Run-time Objects - -| Run-time object | Description | -|---|---| -||Provides a convenient way to see a related group of items as a single object.| -||Contains information about run-time errors.| -|The `My.Application` object consists of the following classes:

provides members that are available in all projects.

provides members available in Windows Forms applications.

provides members available in console applications.|Provides data that is associated only with the current application or DLL. No system-level information can be altered with `My.Application`.

Some members are available only for Windows Forms or console applications.| -|`My.Application.Info` ()|Provides properties for getting the information about an application, such as the version number, description, loaded assemblies, and so on.| -|`My.Application.Log` ()|Provides a property and methods to write event and exception information to the application's log listeners.| -|`My.Computer` ()|Provides properties for manipulating computer components such as audio, the clock, the keyboard, the file system, and so on.| -|`My.Computer.Audio` ()|Provides methods for playing sounds.| -|`My.Computer.Clipboard` ()|Provides methods for manipulating the Clipboard.| -|`My.Computer.Clock` ()|Provides properties for accessing the current local time and Universal Coordinated Time (equivalent to Greenwich Mean Time) from the system clock.| -|`My.Computer.FileSystem` ()|Provides properties and methods for working with drives, files, and directories.| -|`My.Computer.FileSystem.SpecialDirectories` ()|Provides properties for accessing commonly referenced directories.| -|`My.Computer.Info` ()|Provides properties for getting information about the computer's memory, loaded assemblies, name, and operating system.| -|`My.Computer.Keyboard` ()|Provides properties for accessing the current state of the keyboard, such as what keys are currently pressed, and provides a method to send keystrokes to the active window.| -|`My.Computer.Mouse` ()|Provides properties for getting information about the format and configuration of the mouse that is installed on the local computer.| -|`My.Computer.Network` ()|Provides a property, an event, and methods for interacting with the network to which the computer is connected.| -|`My.Computer.Ports` ()|Provides a property and a method for accessing the computer's serial ports.| -|`My.Computer.Registry` ()|Provides properties and methods for manipulating the registry.| -|[My.Forms Object](my-forms-object.md)|Provides properties for accessing an instance of each Windows Form declared in the current project.| -|`My.Log` ()|Provides a property and methods for writing event and exception information to the application's log listeners for Web applications.| -|[My.Request Object](my-request-object.md)|Gets the object for the requested page. The `My.Request` object contains information about the current HTTP request.

The `My.Request` object is available only for ASP.NET applications.| -|[My.Resources Object](my-resources-object.md)|Provides properties and classes for accessing an application's resources.| -|[My.Response Object](my-response-object.md)|Gets the object that is associated with the . This object allows you to send HTTP response data to a client and contains information about that response.

The `My.Response` object is available only for ASP.NET applications.| -|[My.Settings Object](my-settings-object.md)|Provides properties and methods for accessing an application's settings.| -|`My.User` ()|Provides access to information about the current user.| -|[My.WebServices Object](my-webservices-object.md)|Provides properties for creating and accessing a single instance of each Web service that is referenced by the current project.| -||Provides methods and properties for parsing structured text files.| - +This article provides links to other articles that document the Visual Basic run-time objects and contain tables of their member procedures, properties, and events. + +## Visual Basic Run-time Objects + +| Run-time object | Description | +|---|---| +||Provides a convenient way to see a related group of items as a single object.| +||Contains information about run-time errors.| +|The `My.Application` object consists of the following classes:

provides members that are available in all projects.

provides members available in Windows Forms applications.

provides members available in console applications.|Provides data that is associated only with the current application or DLL. No system-level information can be altered with `My.Application`.

Some members are available only for Windows Forms or console applications.| +|`My.Application.Info` ()|Provides properties for getting the information about an application, such as the version number, description, loaded assemblies, and so on.| +|`My.Application.Log` ()|Provides a property and methods to write event and exception information to the application's log listeners.| +|`My.Computer` ()|Provides properties for manipulating computer components such as audio, the clock, the keyboard, the file system, and so on.| +|`My.Computer.Audio` ()|Provides methods for playing sounds.| +|`My.Computer.Clipboard` ()|Provides methods for manipulating the Clipboard.| +|`My.Computer.Clock` ()|Provides properties for accessing the current local time and Universal Coordinated Time (equivalent to Greenwich Mean Time) from the system clock.| +|`My.Computer.FileSystem` ()|Provides properties and methods for working with drives, files, and directories.| +|`My.Computer.FileSystem.SpecialDirectories` ()|Provides properties for accessing commonly referenced directories.| +|`My.Computer.Info` ()|Provides properties for getting information about the computer's memory, loaded assemblies, name, and operating system.| +|`My.Computer.Keyboard` ()|Provides properties for accessing the current state of the keyboard, such as what keys are currently pressed, and provides a method to send keystrokes to the active window.| +|`My.Computer.Mouse` ()|Provides properties for getting information about the format and configuration of the mouse that is installed on the local computer.| +|`My.Computer.Network` ()|Provides a property, an event, and methods for interacting with the network to which the computer is connected.| +|`My.Computer.Ports` ()|Provides a property and a method for accessing the computer's serial ports.| +|`My.Computer.Registry` ()|Provides properties and methods for manipulating the registry.| +|[My.Forms Object](my-forms-object.md)|Provides properties for accessing an instance of each Windows Form declared in the current project.| +|`My.Log` ()|Provides a property and methods for writing event and exception information to the application's log listeners for Web applications.| +|[My.Request Object](my-request-object.md)|Gets the object for the requested page. The `My.Request` object contains information about the current HTTP request.

The `My.Request` object is available only for ASP.NET applications.| +|[My.Resources Object](my-resources-object.md)|Provides properties and classes for accessing an application's resources.| +|[My.Response Object](my-response-object.md)|Gets the object that is associated with the . This object allows you to send HTTP response data to a client and contains information about that response.

The `My.Response` object is available only for ASP.NET applications.| +|[My.Settings Object](my-settings-object.md)|Provides properties and methods for accessing an application's settings.| +|`My.User` ()|Provides access to information about the current user.| +|[My.WebServices Object](my-webservices-object.md)|Provides properties for creating and accessing a single instance of each Web service that is referenced by the current project.| +||Provides methods and properties for parsing structured text files.| + ## See also - [Visual Basic Language Reference](../index.md) diff --git a/docs/visual-basic/language-reference/objects/my-computer-clipboard-object.md b/docs/visual-basic/language-reference/objects/my-computer-clipboard-object.md index e79a67d40daf6..fc32c905e4578 100644 --- a/docs/visual-basic/language-reference/objects/my-computer-clipboard-object.md +++ b/docs/visual-basic/language-reference/objects/my-computer-clipboard-object.md @@ -2,33 +2,33 @@ description: "Learn more about: My.Computer.Clipboard Object" title: "My.Computer.Clipboard Object" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "Clipboard" - "My.Computer.Clipboard object" ms.assetid: 05d4ede9-1f9a-4495-87f0-77350b8d2e5d --- # My.Computer.Clipboard Object -Provides methods for manipulating the Clipboard. - -## Remarks +Provides methods for manipulating the Clipboard. + +## Remarks + + For information about the methods and properties of the `My.Computer.Clipboard` object, see . + + For more information, see [Storing Data to and Reading from the Clipboard](../../developing-apps/programming/computer-resources/storing-data-to-and-reading-from-the-clipboard.md). - For information about the methods and properties of the `My.Computer.Clipboard` object, see . - - For more information, see [Storing Data to and Reading from the Clipboard](../../developing-apps/programming/computer-resources/storing-data-to-and-reading-from-the-clipboard.md). - > [!NOTE] -> You can also use methods of the class to manipulate the Clipboard. - -## Requirements - - **Namespace:** - - **Class:** (provides access to ) - - **Assembly:** Visual Basic Runtime Library (in Microsoft.VisualBasic.dll) - +> You can also use methods of the class to manipulate the Clipboard. + +## Requirements + + **Namespace:** + + **Class:** (provides access to ) + + **Assembly:** Visual Basic Runtime Library (in Microsoft.VisualBasic.dll) + ## See also -- +- - [My.Computer Object](my-computer-object.md) diff --git a/docs/visual-basic/language-reference/objects/my-forms-object.md b/docs/visual-basic/language-reference/objects/my-forms-object.md index 93b36ba1ca6c7..fb20f231d4d9d 100644 --- a/docs/visual-basic/language-reference/objects/my-forms-object.md +++ b/docs/visual-basic/language-reference/objects/my-forms-object.md @@ -21,7 +21,7 @@ You can access the forms provided by the `My.Forms` object by using the name of The `My.Forms` object exposes only the forms associated with the current project. It does not provide access to forms declared in referenced DLLs. To access a form that a DLL provides, you must use the qualified name of the form, written as *DllName*.*FormName*. -You can use the property to get a collection of all the application's open forms. +You can use the property to get a collection of all the application's open forms. The object and its properties are available only for Windows applications. @@ -34,7 +34,7 @@ Each property of the `My.Forms` object provides access to an instance of a form The `My.Forms` object provides access to the instance of the application's main form that was created on startup. For all other forms, the `My.Forms` object creates a new instance of the form when it is accessed and stores it. Subsequent attempts to access that property return that instance of the form. -You can dispose of a form by assigning `Nothing` to the property for that form. The property setter calls the method of the form, and then assigns `Nothing` to the stored value. If you assign any value other than `Nothing` to the property, the setter throws an exception. +You can dispose of a form by assigning `Nothing` to the property for that form. The property setter calls the method of the form, and then assigns `Nothing` to the stored value. If you assign any value other than `Nothing` to the property, the setter throws an exception. You can test whether a property of the `My.Forms` object stores an instance of the form by using the `Is` or `IsNot` operator. You can use those operators to check if the value of the property is `Nothing`. @@ -67,9 +67,9 @@ This code will work only in a Windows Application project. ## See also -- +- - -- +- - [Objects](index.md) - [Is Operator](../operators/is-operator.md) - [IsNot Operator](../operators/isnot-operator.md) diff --git a/docs/visual-basic/language-reference/objects/my-resources-object.md b/docs/visual-basic/language-reference/objects/my-resources-object.md index 101012a8249d4..e86b697b54e68 100644 --- a/docs/visual-basic/language-reference/objects/my-resources-object.md +++ b/docs/visual-basic/language-reference/objects/my-resources-object.md @@ -20,7 +20,7 @@ Provides properties and classes for accessing the application's resources. The `My.Resources` object exposes only global resources. It does not provide access to resource files associated with forms. You must access the form resources from the form. - You can access the application's culture-specific resource files from the `My.Resources` object. By default, the `My.Resources` object looks up resources from the resource file that matches the culture in the property. However, you can override this behavior and specify a particular culture to use for the resources. For more information, see [Resources in .NET apps](../../../core/extensions/resources.md). + You can access the application's culture-specific resource files from the `My.Resources` object. By default, the `My.Resources` object looks up resources from the resource file that matches the culture in the property. However, you can override this behavior and specify a particular culture to use for the resources. For more information, see [Resources in .NET apps](../../../core/extensions/resources.md). ## Properties @@ -41,7 +41,7 @@ Provides properties and classes for accessing the application's resources. | **Strings** | [String](../data-types/string-data-type.md) | | **Images** | | | **Icons** | | -| **Audio** |

The class derives from the class, so it can be used with methods that take streams, such as the method. | +| **Audio** |

The class derives from the class, so it can be used with methods that take streams, such as the method. | | **Files** | - [String](../data-types/string-data-type.md) for text files.
- for image files.
- for icon files.
- for sound files. | | **Other** | Determined by the information in the designer's **Type** column. | @@ -75,7 +75,7 @@ Provides properties and classes for accessing the application's resources. ## Example 5 - This example retrieves the French-culture version of a string resource of the application. The resource is named `Message`. To change the culture that the `My.Resources` object uses, the example uses . + This example retrieves the French-culture version of a string resource of the application. The resource is named `Message`. To change the culture that the `My.Resources` object uses, the example uses . For this example to work, the application must have a string named `Message` in its resource file, and the application should have the French-culture version of that resource file, Resources.fr-FR.resx. If the application does not have the French-culture version of the resource file, the `My.Resource` object retrieves the resource from the default-culture resource file. diff --git a/docs/visual-basic/language-reference/objects/my-user-object.md b/docs/visual-basic/language-reference/objects/my-user-object.md index 11ffc9de8d90e..c117df953eba9 100644 --- a/docs/visual-basic/language-reference/objects/my-user-object.md +++ b/docs/visual-basic/language-reference/objects/my-user-object.md @@ -2,28 +2,28 @@ description: "Learn more about: My.User Object" title: "My.User Object" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "My.User property" - "My.User object" ms.assetid: caa7462e-2149-4bdb-8850-802b80b93cbf --- # My.User Object -Provides access to information about the current user. - -## Remarks +Provides access to information about the current user. - For information about the methods and properties of the `My.User` object, see . - - For more information, see [Accessing User Data](../../developing-apps/programming/accessing-user-data.md). - -## Requirements +## Remarks + + For information about the methods and properties of the `My.User` object, see . + + For more information, see [Accessing User Data](../../developing-apps/programming/accessing-user-data.md). + +## Requirements + + **Assembly:** Visual Basic Runtime Library (in Microsoft.VisualBasic.dll) - **Assembly:** Visual Basic Runtime Library (in Microsoft.VisualBasic.dll) - ## See also - -- -- -- +- +- +- diff --git a/docs/visual-basic/language-reference/operators/await-operator.md b/docs/visual-basic/language-reference/operators/await-operator.md index d2c0c67669837..855f50eaac53e 100644 --- a/docs/visual-basic/language-reference/operators/await-operator.md +++ b/docs/visual-basic/language-reference/operators/await-operator.md @@ -18,9 +18,9 @@ The method in which `Await` is used must have an [Async](../modifiers/async.md) > [!NOTE] > The `Async` and `Await` keywords were introduced in Visual Studio 2012. For an introduction to async programming, see [Asynchronous Programming with Async and Await](../../programming-guide/concepts/async/index.md). -Typically, the task to which you apply the `Await` operator is the return value from a call to a method that implements the [Task-Based Asynchronous Pattern](https://www.microsoft.com/download/details.aspx?id=19957), that is, a or a . +Typically, the task to which you apply the `Await` operator is the return value from a call to a method that implements the [Task-Based Asynchronous Pattern](https://www.microsoft.com/download/details.aspx?id=19957), that is, a or a . -In the following code, the method returns `getContentsTask`, a `Task(Of Byte())`. The task is a promise to produce the actual byte array when the operation is complete. The `Await` operator is applied to `getContentsTask` to suspend execution in `SumPageSizesAsync` until `getContentsTask` is complete. In the meantime, control is returned to the caller of `SumPageSizesAsync`. When `getContentsTask` is finished, the `Await` expression evaluates to a byte array. +In the following code, the method returns `getContentsTask`, a `Task(Of Byte())`. The task is a promise to produce the actual byte array when the operation is complete. The `Await` operator is applied to `getContentsTask` to suspend execution in `SumPageSizesAsync` until `getContentsTask` is complete. In the meantime, control is returned to the caller of `SumPageSizesAsync`. When `getContentsTask` is finished, the `Await` expression evaluates to a byte array. ```vb Private Async Function SumPageSizesAsync() As Task @@ -57,19 +57,19 @@ An `Await` expression can occur only in the body of an immediately enclosing met ## Exceptions -Most async methods return a or . The properties of the returned task carry information about its status and history, such as whether the task is complete, whether the async method caused an exception or was canceled, and what the final result is. The `Await` operator accesses those properties. +Most async methods return a or . The properties of the returned task carry information about its status and history, such as whether the task is complete, whether the async method caused an exception or was canceled, and what the final result is. The `Await` operator accesses those properties. If you await a task-returning async method that causes an exception, the `Await` operator rethrows the exception. If you await a task-returning async method that is canceled, the `Await` operator rethrows an . -A single task that is in a faulted state can reflect multiple exceptions. For example, the task might be the result of a call to . When you await such a task, the await operation rethrows only one of the exceptions. However, you can't predict which of the exceptions is rethrown. +A single task that is in a faulted state can reflect multiple exceptions. For example, the task might be the result of a call to . When you await such a task, the await operation rethrows only one of the exceptions. However, you can't predict which of the exceptions is rethrown. For examples of error handling in async methods, see [Try...Catch...Finally Statement](../statements/try-catch-finally-statement.md). ## Example -The following Windows Forms example illustrates the use of `Await` in an async method, `WaitAsynchronouslyAsync`. Contrast the behavior of that method with the behavior of `WaitSynchronously`. Without an `Await` operator, `WaitSynchronously` runs synchronously despite the use of the `Async` modifier in its definition and a call to in its body. +The following Windows Forms example illustrates the use of `Await` in an async method, `WaitAsynchronouslyAsync`. Contrast the behavior of that method with the behavior of `WaitSynchronously`. Without an `Await` operator, `WaitSynchronously` runs synchronously despite the use of the `Async` modifier in its definition and a call to in its body. ```vb Private Async Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click diff --git a/docs/visual-basic/language-reference/operators/comparison-operators.md b/docs/visual-basic/language-reference/operators/comparison-operators.md index 74110c49f1582..f86eba4acc2b7 100644 --- a/docs/visual-basic/language-reference/operators/comparison-operators.md +++ b/docs/visual-basic/language-reference/operators/comparison-operators.md @@ -3,7 +3,7 @@ description: "Learn more about: Comparison Operators (Visual Basic)" title: "Comparison Operators in Visual Basic" titleSuffix: "" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.<>" - "vb.>=" - "vb.<=" @@ -58,31 +58,31 @@ The following are the comparison operators defined in Visual Basic. These operators compare two expressions to determine whether or not they are equal, and if not, how they differ. `Is`, `IsNot`, and `Like` are discussed in detail on separate Help pages. The relational comparison operators are discussed in detail on this page. ## Syntax - + ```vb -result = expression1 comparisonoperator expression2 -result = object1 [Is | IsNot] object2 -result = string Like pattern -``` - +result = expression1 comparisonoperator expression2 +result = object1 [Is | IsNot] object2 +result = string Like pattern +``` + ## Parts - `result` + `result` Required. A `Boolean` value representing the result of the comparison. - `expression1`, `expression2` + `expression1`, `expression2` Required. Any expression. - `comparisonoperator` + `comparisonoperator` Required. Any relational comparison operator. - `object1`, `object2` + `object1`, `object2` Required. Any reference object names. - `string` + `string` Required. Any `String` expression. - `pattern` + `pattern` Required. Any `String` expression or range of characters. ## Remarks @@ -127,7 +127,7 @@ result = string Like pattern ### Locale Dependence - When you set `Option Compare Text`, the result of a string comparison can depend on the locale in which the application is running. Two characters might compare as equal in one locale but not in another. If you are using a string comparison to make important decisions, such as whether to accept an attempt to log on, you should be alert to locale sensitivity. Consider either setting `Option Compare Binary` or calling the , which takes the locale into account. + When you set `Option Compare Text`, the result of a string comparison can depend on the locale in which the application is running. Two characters might compare as equal in one locale but not in another. If you are using a string comparison to make important decisions, such as whether to accept an attempt to log on, you should be alert to locale sensitivity. Consider either setting `Option Compare Binary` or calling the , which takes the locale into account. ## Typeless Programming with Relational Comparison Operators diff --git a/docs/visual-basic/language-reference/operators/ctype-operator.md b/docs/visual-basic/language-reference/operators/ctype-operator.md index 99f11fdfb1071..1aad1210dfb5b 100644 --- a/docs/visual-basic/language-reference/operators/ctype-operator.md +++ b/docs/visual-basic/language-reference/operators/ctype-operator.md @@ -48,13 +48,13 @@ If the data type of `expression` or `typename` is a class or structure you've de ## Conversion Keywords - A comparison of the type conversion keywords is as follows. - -|Keyword|Data types|Argument relationship|Run-time failure| -|---|---|---|---| -|`CType`|Any data types|Widening or narrowing conversion must be defined between the two data types|Throws | -|[DirectCast Operator](directcast-operator.md)|Any data types|One type must inherit from or implement the other type|Throws | -|[TryCast](trycast-operator.md)|Reference types only|One type must inherit from or implement the other type|Returns [Nothing](../nothing.md)| + A comparison of the type conversion keywords is as follows. + +|Keyword|Data types|Argument relationship|Run-time failure| +|---|---|---|---| +|`CType`|Any data types|Widening or narrowing conversion must be defined between the two data types|Throws | +|[DirectCast Operator](directcast-operator.md)|Any data types|One type must inherit from or implement the other type|Throws | +|[TryCast](trycast-operator.md)|Reference types only|One type must inherit from or implement the other type|Returns [Nothing](../nothing.md)| ## Overloading @@ -62,7 +62,7 @@ The `CType` operator can also be overloaded on a class or structure defined outs ## Converting Dynamic Objects -Type conversions of dynamic objects are performed by user-defined dynamic conversions that use the or methods. If you're working with dynamic objects, use the method to convert the dynamic object. +Type conversions of dynamic objects are performed by user-defined dynamic conversions that use the or methods. If you're working with dynamic objects, use the method to convert the dynamic object. ## Example diff --git a/docs/visual-basic/language-reference/operators/directcast-operator.md b/docs/visual-basic/language-reference/operators/directcast-operator.md index c124c2b9fa667..744ce3f303a01 100644 --- a/docs/visual-basic/language-reference/operators/directcast-operator.md +++ b/docs/visual-basic/language-reference/operators/directcast-operator.md @@ -2,47 +2,47 @@ description: "Learn more about: DirectCast Operator (Visual Basic)" title: "DirectCast Operator" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.directCast" - "directCast" -helpviewer_keywords: +helpviewer_keywords: - "DirectCast keyword [Visual Basic]" ms.assetid: 63e5a1d0-4d9e-4732-bf8f-e90c0c8784b8 --- # DirectCast Operator (Visual Basic) -Introduces a type conversion operation based on inheritance or implementation. - -## Remarks - - `DirectCast` does not use the Visual Basic run-time helper routines for conversion, so it can provide somewhat better performance than `CType` when converting to and from data type `Object`. - - You use the `DirectCast` keyword similar to the way you use the [CType Operator](ctype-operator.md) and the [TryCast Operator](trycast-operator.md) keyword. You supply an expression as the first argument and a type to convert it to as the second argument. `DirectCast` requires an inheritance or implementation relationship between the data types of the two arguments. This means that one type must inherit from or implement the other. - -## Errors and Failures - - `DirectCast` generates a compiler error if it detects that no inheritance or implementation relationship exists. But the lack of a compiler error does not guarantee a successful conversion. If the desired conversion is narrowing, it could fail at run time. If this happens, the runtime throws an error. - -## Conversion Keywords - - A comparison of the type conversion keywords is as follows. - -|Keyword|Data types|Argument relationship|Run-time failure| -|---|---|---|---| -|[CType Operator](ctype-operator.md)|Any data types|Widening or narrowing conversion must be defined between the two data types|Throws | -|`DirectCast`|Any data types|One type must inherit from or implement the other type|Throws | -|[TryCast Operator](trycast-operator.md)|Reference types only|One type must inherit from or implement the other type|Returns [Nothing](../nothing.md)| - -## Example - - The following example demonstrates two uses of `DirectCast`, one that fails at run time and one that succeeds. - - [!code-vb[VbVbalrKeywords#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrKeywords/VB/Class1.vb#1)] - - In the preceding example, the run-time type of `q` is `Double`. `CType` succeeds because `Double` can be converted to `Integer`. However, the first `DirectCast` fails at run time because the run-time type of `Double` has no inheritance relationship with `Integer`, even though a conversion exists. The second `DirectCast` succeeds because it converts from type to type , from which inherits. - +Introduces a type conversion operation based on inheritance or implementation. + +## Remarks + + `DirectCast` does not use the Visual Basic run-time helper routines for conversion, so it can provide somewhat better performance than `CType` when converting to and from data type `Object`. + + You use the `DirectCast` keyword similar to the way you use the [CType Operator](ctype-operator.md) and the [TryCast Operator](trycast-operator.md) keyword. You supply an expression as the first argument and a type to convert it to as the second argument. `DirectCast` requires an inheritance or implementation relationship between the data types of the two arguments. This means that one type must inherit from or implement the other. + +## Errors and Failures + + `DirectCast` generates a compiler error if it detects that no inheritance or implementation relationship exists. But the lack of a compiler error does not guarantee a successful conversion. If the desired conversion is narrowing, it could fail at run time. If this happens, the runtime throws an error. + +## Conversion Keywords + + A comparison of the type conversion keywords is as follows. + +|Keyword|Data types|Argument relationship|Run-time failure| +|---|---|---|---| +|[CType Operator](ctype-operator.md)|Any data types|Widening or narrowing conversion must be defined between the two data types|Throws | +|`DirectCast`|Any data types|One type must inherit from or implement the other type|Throws | +|[TryCast Operator](trycast-operator.md)|Reference types only|One type must inherit from or implement the other type|Returns [Nothing](../nothing.md)| + +## Example + + The following example demonstrates two uses of `DirectCast`, one that fails at run time and one that succeeds. + + [!code-vb[VbVbalrKeywords#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrKeywords/VB/Class1.vb#1)] + + In the preceding example, the run-time type of `q` is `Double`. `CType` succeeds because `Double` can be converted to `Integer`. However, the first `DirectCast` fails at run time because the run-time type of `Double` has no inheritance relationship with `Integer`, even though a conversion exists. The second `DirectCast` succeeds because it converts from type to type , from which inherits. + ## See also -- +- - [Widening and Narrowing Conversions](../../programming-guide/language-features/data-types/widening-and-narrowing-conversions.md) - [Implicit and Explicit Conversions](../../programming-guide/language-features/data-types/implicit-and-explicit-conversions.md) diff --git a/docs/visual-basic/language-reference/operators/gettype-operator.md b/docs/visual-basic/language-reference/operators/gettype-operator.md index 1193cf8bf75c8..e750492af2193 100644 --- a/docs/visual-basic/language-reference/operators/gettype-operator.md +++ b/docs/visual-basic/language-reference/operators/gettype-operator.md @@ -2,61 +2,61 @@ description: "Learn more about: GetType Operator (Visual Basic)" title: "GetType Operator" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.GetType" -helpviewer_keywords: +helpviewer_keywords: - "GetType operator [Visual Basic]" - "GetType keyword [Visual Basic]" ms.assetid: 4f733297-2503-4607-850c-15eba65fff90 --- # GetType Operator (Visual Basic) -Returns a object for the specified type. The object provides information about the type such as its properties, methods, and events. - -## Syntax - -```vb -GetType(typename) -``` - -## Parameters - -|Parameter|Description| -|---|---| -|`typename`|The name of the type for which you desire information.| - -## Remarks - - The `GetType` operator returns the object for the specified `typename`. You can pass the name of any defined type in `typename`. This includes the following: - -- Any Visual Basic data type, such as `Boolean` or `Date`. - -- Any .NET Framework class, structure, module, or interface, such as or . - -- Any class, structure, module, or interface defined by your application. - -- Any array defined by your application. - -- Any delegate defined by your application. - -- Any enumeration defined by Visual Basic, the .NET Framework, or your application. - - If you want to get the type object of an object variable, use the method. - - The `GetType` operator can be useful in the following circumstance: - -- You must access the metadata for a type at run time. The object supplies metadata such as type members and deployment information. You need this, for example, to reflect over an assembly. For more information, see also . - -## Example - - The following examples show the `GetType` operator in use. - - [!code-vb[VbVbalrOperators#26](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#26)] - +Returns a object for the specified type. The object provides information about the type such as its properties, methods, and events. + +## Syntax + +```vb +GetType(typename) +``` + +## Parameters + +|Parameter|Description| +|---|---| +|`typename`|The name of the type for which you desire information.| + +## Remarks + + The `GetType` operator returns the object for the specified `typename`. You can pass the name of any defined type in `typename`. This includes the following: + +- Any Visual Basic data type, such as `Boolean` or `Date`. + +- Any .NET Framework class, structure, module, or interface, such as or . + +- Any class, structure, module, or interface defined by your application. + +- Any array defined by your application. + +- Any delegate defined by your application. + +- Any enumeration defined by Visual Basic, the .NET Framework, or your application. + + If you want to get the type object of an object variable, use the method. + + The `GetType` operator can be useful in the following circumstance: + +- You must access the metadata for a type at run time. The object supplies metadata such as type members and deployment information. You need this, for example, to reflect over an assembly. For more information, see also . + +## Example + + The following examples show the `GetType` operator in use. + + [!code-vb[VbVbalrOperators#26](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#26)] + ## See also - [Operator Precedence in Visual Basic](operator-precedence.md) - [Operators Listed by Functionality](operators-listed-by-functionality.md) - [Operators and Expressions](../../programming-guide/language-features/operators-and-expressions/index.md) -- -- +- +- diff --git a/docs/visual-basic/language-reference/operators/getxmlnamespace-operator.md b/docs/visual-basic/language-reference/operators/getxmlnamespace-operator.md index 24360e531b4de..498d92e420622 100644 --- a/docs/visual-basic/language-reference/operators/getxmlnamespace-operator.md +++ b/docs/visual-basic/language-reference/operators/getxmlnamespace-operator.md @@ -37,7 +37,7 @@ GetXmlNamespace(xmlNamespacePrefix) ## Example - The following example imports `ns` as an XML namespace prefix. It then uses the prefix of the namespace to create an XML literal and access the first child node that has the qualified name `ns:phone`. It then passes that child node to the `ShowName` subroutine, which constructs a qualified name by using the `GetXmlNamespace` operator. The `ShowName` subroutine then passes the qualified name to the method to get the parent `ns:contact` node. + The following example imports `ns` as an XML namespace prefix. It then uses the prefix of the namespace to create an XML literal and access the first child node that has the qualified name `ns:phone`. It then passes that child node to the `ShowName` subroutine, which constructs a qualified name by using the `GetXmlNamespace` operator. The `ShowName` subroutine then passes the qualified name to the method to get the parent `ns:contact` node. [!code-vb[VbXMLSamples#38](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/GetXmlNamespace.vb#38)] diff --git a/docs/visual-basic/language-reference/operators/if-operator.md b/docs/visual-basic/language-reference/operators/if-operator.md index bcd6b4a7b2550..552399c5853a9 100644 --- a/docs/visual-basic/language-reference/operators/if-operator.md +++ b/docs/visual-basic/language-reference/operators/if-operator.md @@ -60,6 +60,6 @@ When the `Boolean` argument is omitted, the first argument must be a reference o ## See also -- +- - [Nullable Value Types](../../programming-guide/language-features/data-types/nullable-value-types.md) - [Nothing](../nothing.md) diff --git a/docs/visual-basic/language-reference/operators/like-operator.md b/docs/visual-basic/language-reference/operators/like-operator.md index 823c60bbe265b..bc42dcfb48ab1 100644 --- a/docs/visual-basic/language-reference/operators/like-operator.md +++ b/docs/visual-basic/language-reference/operators/like-operator.md @@ -2,10 +2,10 @@ description: "Learn more about: Like Operator (Visual Basic)" title: "Like Operator" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "Like" - "vb.Like" -helpviewer_keywords: +helpviewer_keywords: - "similar to" - "pattern matching" - "Like operator [Visual Basic]" @@ -26,98 +26,98 @@ ms.assetid: 966283ec-80e2-4294-baa8-c75baff804f9 --- # Like Operator (Visual Basic) -Compares a string against a pattern. +Compares a string against a pattern. > [!IMPORTANT] > The `Like` operator is currently not supported in .NET Core and .NET Standard projects. -## Syntax - -```vb -result = string Like pattern -``` - -## Parts - - `result` - Required. Any `Boolean` variable. The result is a `Boolean` value indicating whether or not the `string` satisfies the `pattern`. - - `string` - Required. Any `String` expression. - - `pattern` - Required. Any `String` expression conforming to the pattern-matching conventions described in "Remarks." - -## Remarks - - If the value in `string` satisfies the pattern contained in `pattern`, `result` is `True`. If the string does not satisfy the pattern, `result` is `False`. If both `string` and `pattern` are empty strings, the result is `True`. - -## Comparison Method - - The behavior of the `Like` operator depends on the [Option Compare Statement](../statements/option-compare-statement.md). The default string comparison method for each source file is `Option Compare Binary`. - -## Pattern Options - - Built-in pattern matching provides a versatile tool for string comparisons. The pattern-matching features allow you to match each character in `string` against a specific character, a wildcard character, a character list, or a character range. The following table shows the characters allowed in `pattern` and what they match. - -|Characters in `pattern`|Matches in `string`| -|-----------------------------|-------------------------| -|`?`|Any single character| -|`*`|Zero or more characters| -|`#`|Any single digit (0–9)| -|`[charlist]`|Any single character in `charlist`| -|`[!charlist]`|Any single character not in `charlist`| - -## Character Lists - - A group of one or more characters (`charlist`) enclosed in brackets (`[ ]`) can be used to match any single character in `string` and can include almost any character code, including digits. - - An exclamation point (`!`) at the beginning of `charlist` means that a match is made if any character except the characters in `charlist` is found in `string`. When used outside brackets, the exclamation point matches itself. - -## Special Characters - - To match the special characters left bracket (`[`), question mark (`?`), number sign (`#`), and asterisk (`*`), enclose them in brackets. The right bracket (`]`) cannot be used within a group to match itself, but it can be used outside a group as an individual character. - - The character sequence `[]` is considered a zero-length string (`""`). However, it cannot be part of a character list enclosed in brackets. If you want to check whether a position in `string` contains one of a group of characters or no character at all, you can use `Like` twice. For an example, see [How to: Match a String against a Pattern](../../programming-guide/language-features/operators-and-expressions/how-to-match-a-string-against-a-pattern.md). - -## Character Ranges - - By using a hyphen (`–`) to separate the lower and upper bounds of the range, `charlist` can specify a range of characters. For example, `[A–Z]` results in a match if the corresponding character position in `string` contains any character within the range `A`–`Z`, and `[!H–L]` results in a match if the corresponding character position contains any character outside the range `H`–`L`. - - When you specify a range of characters, they must appear in ascending sort order, that is, from lowest to highest. Thus, `[A–Z]` is a valid pattern, but `[Z–A]` is not. - -### Multiple Character Ranges - - To specify multiple ranges for the same character position, put them within the same brackets without delimiters. For example, `[A–CX–Z]` results in a match if the corresponding character position in `string` contains any character within either the range `A`–`C` or the range `X`–`Z`. - -### Usage of the Hyphen - - A hyphen (`–`) can appear either at the beginning (after an exclamation point, if any) or at the end of `charlist` to match itself. In any other location, the hyphen identifies a range of characters delimited by the characters on either side of the hyphen. - -## Collating Sequence - - The meaning of a specified range depends on the character ordering at run time, as determined by `Option Compare` and the locale setting of the system the code is running on. With `Option Compare Binary`, the range `[A–E]` matches `A`, `B`, `C`, `D`, and `E`. With `Option Compare Text`, `[A–E]` matches `A`, `a`, `À`, `à`, `B`, `b`, `C`, `c`, `D`, `d`, `E`, and `e`. The range does not match `Ê` or `ê` because accented characters collate after unaccented characters in the sort order. - -## Digraph Characters - - In some languages, there are alphabetic characters that represent two separate characters. For example, several languages use the character `æ` to represent the characters `a` and `e` when they appear together. The `Like` operator recognizes that the single digraph character and the two individual characters are equivalent. - - When a language that uses a digraph character is specified in the system locale settings, an occurrence of the single digraph character in either `pattern` or `string` matches the equivalent two-character sequence in the other string. Similarly, a digraph character in `pattern` enclosed in brackets (by itself, in a list, or in a range) matches the equivalent two-character sequence in `string`. - -## Overloading - - The `Like` operator can be *overloaded*, which means that a class or structure can redefine its behavior when an operand has the type of that class or structure. If your code uses this operator on such a class or structure, be sure you understand its redefined behavior. For more information, see [Operator Procedures](../../programming-guide/language-features/procedures/operator-procedures.md). - -## Example - - This example uses the `Like` operator to compare strings to various patterns. The results go into a `Boolean` variable indicating whether each string satisfies the pattern. - - [!code-vb[VbVbalrOperators#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#30)] - +## Syntax + +```vb +result = string Like pattern +``` + +## Parts + + `result` + Required. Any `Boolean` variable. The result is a `Boolean` value indicating whether or not the `string` satisfies the `pattern`. + + `string` + Required. Any `String` expression. + + `pattern` + Required. Any `String` expression conforming to the pattern-matching conventions described in "Remarks." + +## Remarks + + If the value in `string` satisfies the pattern contained in `pattern`, `result` is `True`. If the string does not satisfy the pattern, `result` is `False`. If both `string` and `pattern` are empty strings, the result is `True`. + +## Comparison Method + + The behavior of the `Like` operator depends on the [Option Compare Statement](../statements/option-compare-statement.md). The default string comparison method for each source file is `Option Compare Binary`. + +## Pattern Options + + Built-in pattern matching provides a versatile tool for string comparisons. The pattern-matching features allow you to match each character in `string` against a specific character, a wildcard character, a character list, or a character range. The following table shows the characters allowed in `pattern` and what they match. + +|Characters in `pattern`|Matches in `string`| +|-----------------------------|-------------------------| +|`?`|Any single character| +|`*`|Zero or more characters| +|`#`|Any single digit (0–9)| +|`[charlist]`|Any single character in `charlist`| +|`[!charlist]`|Any single character not in `charlist`| + +## Character Lists + + A group of one or more characters (`charlist`) enclosed in brackets (`[ ]`) can be used to match any single character in `string` and can include almost any character code, including digits. + + An exclamation point (`!`) at the beginning of `charlist` means that a match is made if any character except the characters in `charlist` is found in `string`. When used outside brackets, the exclamation point matches itself. + +## Special Characters + + To match the special characters left bracket (`[`), question mark (`?`), number sign (`#`), and asterisk (`*`), enclose them in brackets. The right bracket (`]`) cannot be used within a group to match itself, but it can be used outside a group as an individual character. + + The character sequence `[]` is considered a zero-length string (`""`). However, it cannot be part of a character list enclosed in brackets. If you want to check whether a position in `string` contains one of a group of characters or no character at all, you can use `Like` twice. For an example, see [How to: Match a String against a Pattern](../../programming-guide/language-features/operators-and-expressions/how-to-match-a-string-against-a-pattern.md). + +## Character Ranges + + By using a hyphen (`–`) to separate the lower and upper bounds of the range, `charlist` can specify a range of characters. For example, `[A–Z]` results in a match if the corresponding character position in `string` contains any character within the range `A`–`Z`, and `[!H–L]` results in a match if the corresponding character position contains any character outside the range `H`–`L`. + + When you specify a range of characters, they must appear in ascending sort order, that is, from lowest to highest. Thus, `[A–Z]` is a valid pattern, but `[Z–A]` is not. + +### Multiple Character Ranges + + To specify multiple ranges for the same character position, put them within the same brackets without delimiters. For example, `[A–CX–Z]` results in a match if the corresponding character position in `string` contains any character within either the range `A`–`C` or the range `X`–`Z`. + +### Usage of the Hyphen + + A hyphen (`–`) can appear either at the beginning (after an exclamation point, if any) or at the end of `charlist` to match itself. In any other location, the hyphen identifies a range of characters delimited by the characters on either side of the hyphen. + +## Collating Sequence + + The meaning of a specified range depends on the character ordering at run time, as determined by `Option Compare` and the locale setting of the system the code is running on. With `Option Compare Binary`, the range `[A–E]` matches `A`, `B`, `C`, `D`, and `E`. With `Option Compare Text`, `[A–E]` matches `A`, `a`, `À`, `à`, `B`, `b`, `C`, `c`, `D`, `d`, `E`, and `e`. The range does not match `Ê` or `ê` because accented characters collate after unaccented characters in the sort order. + +## Digraph Characters + + In some languages, there are alphabetic characters that represent two separate characters. For example, several languages use the character `æ` to represent the characters `a` and `e` when they appear together. The `Like` operator recognizes that the single digraph character and the two individual characters are equivalent. + + When a language that uses a digraph character is specified in the system locale settings, an occurrence of the single digraph character in either `pattern` or `string` matches the equivalent two-character sequence in the other string. Similarly, a digraph character in `pattern` enclosed in brackets (by itself, in a list, or in a range) matches the equivalent two-character sequence in `string`. + +## Overloading + + The `Like` operator can be *overloaded*, which means that a class or structure can redefine its behavior when an operand has the type of that class or structure. If your code uses this operator on such a class or structure, be sure you understand its redefined behavior. For more information, see [Operator Procedures](../../programming-guide/language-features/procedures/operator-procedures.md). + +## Example + + This example uses the `Like` operator to compare strings to various patterns. The results go into a `Boolean` variable indicating whether each string satisfies the pattern. + + [!code-vb[VbVbalrOperators#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#30)] + ## See also -- -- +- +- - [Comparison Operators](comparison-operators.md) - [Operator Precedence in Visual Basic](operator-precedence.md) - [Operators Listed by Functionality](operators-listed-by-functionality.md) diff --git a/docs/visual-basic/language-reference/operators/mod-operator.md b/docs/visual-basic/language-reference/operators/mod-operator.md index de1421cbcb1bd..cc5a74a6fa52e 100644 --- a/docs/visual-basic/language-reference/operators/mod-operator.md +++ b/docs/visual-basic/language-reference/operators/mod-operator.md @@ -113,8 +113,8 @@ The following example demonstrates the potential imprecision of floating-point o ## See also -- -- +- +- - [Arithmetic Operators](arithmetic-operators.md) - [Operator Precedence in Visual Basic](operator-precedence.md) - [Operators Listed by Functionality](operators-listed-by-functionality.md) diff --git a/docs/visual-basic/language-reference/operators/null-conditional-operators.md b/docs/visual-basic/language-reference/operators/null-conditional-operators.md index b690a0dc1bd10..8f1e645880077 100644 --- a/docs/visual-basic/language-reference/operators/null-conditional-operators.md +++ b/docs/visual-basic/language-reference/operators/null-conditional-operators.md @@ -10,7 +10,7 @@ helpviewer_keywords: --- # ?. and ?() null-conditional operators (Visual Basic) -Tests the value of the left-hand operand for null (`Nothing`) before performing a member access (`?.`) or index (`?()`) operation; returns `Nothing` if the left-hand operand evaluates to `Nothing`. Note that in expressions that ordinarily return value types, the null-conditional operator returns a . +Tests the value of the left-hand operand for null (`Nothing`) before performing a member access (`?.`) or index (`?()`) operation; returns `Nothing` if the left-hand operand evaluates to `Nothing`. Note that in expressions that ordinarily return value types, the null-conditional operator returns a . These operators help you write less code to handle null checks, especially when descending into data structures. For example: diff --git a/docs/visual-basic/language-reference/properties.md b/docs/visual-basic/language-reference/properties.md index d560797bf7c21..e8fe0bb83350b 100644 --- a/docs/visual-basic/language-reference/properties.md +++ b/docs/visual-basic/language-reference/properties.md @@ -2,29 +2,29 @@ description: "Learn more about: Properties (Visual Basic)" title: "Properties" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "properties [Visual Basic]" ms.assetid: c995caf9-8d0e-4fb8-ae02-e9e6087d7651 --- # Properties (Visual Basic) -This page lists the properties that are members of Visual Basic modules. Other properties that are members of specific Visual Basic objects are listed in [Objects](objects/index.md). - -## Visual Basic Properties - +This page lists the properties that are members of Visual Basic modules. Other properties that are members of specific Visual Basic objects are listed in [Objects](objects/index.md). + +## Visual Basic Properties + | Property | Description | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -| | Returns or sets a `String` value representing the current date according to your system. | -| | Returns a `Date` value containing the current date and time according to your system. | -| | Returns a `String` representing the runtime currently in use. | -| | Returns an `Integer` containing the build version number of the runtime currently in use. | -| | Returns an `Integer` containing the major version number of the runtime currently in use. | -| | Returns an `Integer` containing the minor version number of the runtime currently in use. | -| | Returns or sets a `Date` value containing the current time of day according to your system. | -| | Returns a `Double` value representing the number of seconds elapsed since midnight. | -| | Returns or sets a `String` value representing the current time of day according to your system. | -| | Returns or sets a `Date` value containing the current date according to your system. | - +| | Returns or sets a `String` value representing the current date according to your system. | +| | Returns a `Date` value containing the current date and time according to your system. | +| | Returns a `String` representing the runtime currently in use. | +| | Returns an `Integer` containing the build version number of the runtime currently in use. | +| | Returns an `Integer` containing the major version number of the runtime currently in use. | +| | Returns an `Integer` containing the minor version number of the runtime currently in use. | +| | Returns or sets a `Date` value containing the current time of day according to your system. | +| | Returns a `Double` value representing the number of seconds elapsed since midnight. | +| | Returns or sets a `String` value representing the current time of day according to your system. | +| | Returns or sets a `Date` value containing the current date according to your system. | + ## See also - [Visual Basic Language Reference](index.md) diff --git a/docs/visual-basic/language-reference/queries/aggregate-clause.md b/docs/visual-basic/language-reference/queries/aggregate-clause.md index b0fa82113ddde..ed44f44d0b4eb 100644 --- a/docs/visual-basic/language-reference/queries/aggregate-clause.md +++ b/docs/visual-basic/language-reference/queries/aggregate-clause.md @@ -2,11 +2,11 @@ description: "Learn more about: Aggregate Clause (Visual Basic)" title: "Aggregate Clause" ms.date: 08/28/2018 -f1_keywords: +f1_keywords: - "vb.QueryAggregateIn" - "vb.QueryAggregate" - "vb.QueryAggregateInto" -helpviewer_keywords: +helpviewer_keywords: - "Aggregate clause [Visual Basic]" - "Aggregate statement [Visual Basic]" - "queries [Visual Basic], Aggregate" @@ -14,39 +14,39 @@ ms.assetid: 1315a814-5db6-4077-b34b-b141e11cc0eb --- # Aggregate Clause (Visual Basic) -Applies one or more aggregate functions to a collection. - -## Syntax - -```vb -Aggregate element [As type] In collection _ - [, element2 [As type2] In collection2, [...]] - [ clause ] - Into expressionList -``` - -## Parts - -|Term|Definition| -|---|---| -|`element`|Required. Variable used to iterate through the elements of the collection.| -|`type`|Optional. The type of `element`. If no type is specified, the type of `element` is inferred from `collection`.| -|`collection`|Required. Refers to the collection to operate on.| -|`clause`|Optional. One or more query clauses, such as a `Where` clause, to refine the query result to apply the aggregate clause or clauses to.| -|`expressionList`|Required. One or more comma-delimited expressions that identify an aggregate function to apply to the collection. You can apply an alias to an aggregate function to specify a member name for the query result. If no alias is supplied, the name of the aggregate function is used. For examples, see the section about aggregate functions later in this topic.| - -## Remarks - - The `Aggregate` clause can be used to include aggregate functions in your queries. Aggregate functions perform checks and computations over a set of values and return a single value. You can access the computed value by using a member of the query result type. The standard aggregate functions that you can use are the `All`, `Any`, `Average`, `Count`, `LongCount`, `Max`, `Min`, and `Sum` functions. These functions are familiar to developers who are familiar with aggregates in SQL. They are described in the following section of this topic. - - The result of an aggregate function is included in the query result as a field of the query result type. You can supply an alias for the aggregate function result to specify the name of the member of the query result type that will hold the aggregate value. If no alias is supplied, the name of the aggregate function is used. - - The `Aggregate` clause can begin a query, or it can be included as an additional clause in a query. If the `Aggregate` clause begins a query, the result is a single value that is the result of the aggregate function specified in the `Into` clause. If more than one aggregate function is specified in the `Into` clause, the query returns a single type with a separate property to reference the result of each aggregate function in the `Into` clause. If the `Aggregate` clause is included as an additional clause in a query, the type returned in the query collection will have a separate property to reference the result of each aggregate function in the `Into` clause. - +Applies one or more aggregate functions to a collection. + +## Syntax + +```vb +Aggregate element [As type] In collection _ + [, element2 [As type2] In collection2, [...]] + [ clause ] + Into expressionList +``` + +## Parts + +|Term|Definition| +|---|---| +|`element`|Required. Variable used to iterate through the elements of the collection.| +|`type`|Optional. The type of `element`. If no type is specified, the type of `element` is inferred from `collection`.| +|`collection`|Required. Refers to the collection to operate on.| +|`clause`|Optional. One or more query clauses, such as a `Where` clause, to refine the query result to apply the aggregate clause or clauses to.| +|`expressionList`|Required. One or more comma-delimited expressions that identify an aggregate function to apply to the collection. You can apply an alias to an aggregate function to specify a member name for the query result. If no alias is supplied, the name of the aggregate function is used. For examples, see the section about aggregate functions later in this topic.| + +## Remarks + + The `Aggregate` clause can be used to include aggregate functions in your queries. Aggregate functions perform checks and computations over a set of values and return a single value. You can access the computed value by using a member of the query result type. The standard aggregate functions that you can use are the `All`, `Any`, `Average`, `Count`, `LongCount`, `Max`, `Min`, and `Sum` functions. These functions are familiar to developers who are familiar with aggregates in SQL. They are described in the following section of this topic. + + The result of an aggregate function is included in the query result as a field of the query result type. You can supply an alias for the aggregate function result to specify the name of the member of the query result type that will hold the aggregate value. If no alias is supplied, the name of the aggregate function is used. + + The `Aggregate` clause can begin a query, or it can be included as an additional clause in a query. If the `Aggregate` clause begins a query, the result is a single value that is the result of the aggregate function specified in the `Into` clause. If more than one aggregate function is specified in the `Into` clause, the query returns a single type with a separate property to reference the result of each aggregate function in the `Into` clause. If the `Aggregate` clause is included as an additional clause in a query, the type returned in the query collection will have a separate property to reference the result of each aggregate function in the `Into` clause. + ## Aggregate Functions -The following are the standard aggregate functions that can be used with the `Aggregate` clause. - +The following are the standard aggregate functions that can be used with the `Aggregate` clause. + ### All Returns `true` if all elements in the collection satisfy a specified condition; otherwise returns `false`. The following is an example: @@ -97,24 +97,24 @@ Computes the sum of all elements in the collection, or computes a supplied expre [!code-vb[VbSimpleQuerySamples#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/QuerySamples1.vb#15)] -## Example +## Example + +The following example shows how to use the `Aggregate` clause to apply aggregate functions to a query result. + + [!code-vb[VbSimpleQuerySamples#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/QuerySamples1.vb#4)] -The following example shows how to use the `Aggregate` clause to apply aggregate functions to a query result. - - [!code-vb[VbSimpleQuerySamples#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/QuerySamples1.vb#4)] - ## Creating User-Defined Aggregate Functions - You can include your own custom aggregate functions in a query expression by adding extension methods to the type. Your custom method can then perform a calculation or operation on the enumerable collection that has referenced your aggregate function. For more information about extension methods, see [Extension Methods](../../programming-guide/language-features/procedures/extension-methods.md). - - For example, the following example shows a custom aggregate function that calculates the median value of a collection of numbers. There are two overloads of the `Median` extension method. The first overload accepts, as input, a collection of type `IEnumerable(Of Double)`. If the `Median` aggregate function is called for a query field of type `Double`, this method will be called. The second overload of the `Median` method can be passed any generic type. The generic overload of the `Median` method takes a second parameter that references the `Func(Of T, Double)` lambda expression to project a value for a type (from a collection) as the corresponding value of type `Double`. It then delegates the calculation of the median value to the other overload of the `Median` method. For more information about lambda expressions, see [Lambda Expressions](../../programming-guide/language-features/procedures/lambda-expressions.md). - - [!code-vb[VbSimpleQuerySamples#18](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/UserDefinedAggregates.vb#18)] - - The following example shows sample queries that call the `Median` aggregate function on a collection of type `Integer`, and a collection of type `Double`. The query that calls the `Median` aggregate function on the collection of type `Double` calls the overload of the `Median` method that accepts, as input, a collection of type `Double`. The query that calls the `Median` aggregate function on the collection of type `Integer` calls the generic overload of the `Median` method. - - [!code-vb[VbSimpleQuerySamples#19](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/UserDefinedAggregates.vb#19)] - + You can include your own custom aggregate functions in a query expression by adding extension methods to the type. Your custom method can then perform a calculation or operation on the enumerable collection that has referenced your aggregate function. For more information about extension methods, see [Extension Methods](../../programming-guide/language-features/procedures/extension-methods.md). + + For example, the following example shows a custom aggregate function that calculates the median value of a collection of numbers. There are two overloads of the `Median` extension method. The first overload accepts, as input, a collection of type `IEnumerable(Of Double)`. If the `Median` aggregate function is called for a query field of type `Double`, this method will be called. The second overload of the `Median` method can be passed any generic type. The generic overload of the `Median` method takes a second parameter that references the `Func(Of T, Double)` lambda expression to project a value for a type (from a collection) as the corresponding value of type `Double`. It then delegates the calculation of the median value to the other overload of the `Median` method. For more information about lambda expressions, see [Lambda Expressions](../../programming-guide/language-features/procedures/lambda-expressions.md). + + [!code-vb[VbSimpleQuerySamples#18](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/UserDefinedAggregates.vb#18)] + + The following example shows sample queries that call the `Median` aggregate function on a collection of type `Integer`, and a collection of type `Double`. The query that calls the `Median` aggregate function on the collection of type `Double` calls the overload of the `Median` method that accepts, as input, a collection of type `Double`. The query that calls the `Median` aggregate function on the collection of type `Integer` calls the generic overload of the `Median` method. + + [!code-vb[VbSimpleQuerySamples#19](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/UserDefinedAggregates.vb#19)] + ## See also - [Introduction to LINQ in Visual Basic](../../programming-guide/language-features/linq/introduction-to-linq.md) diff --git a/docs/visual-basic/language-reference/queries/select-clause.md b/docs/visual-basic/language-reference/queries/select-clause.md index 4c8aabec991a4..52d559d0c3706 100644 --- a/docs/visual-basic/language-reference/queries/select-clause.md +++ b/docs/visual-basic/language-reference/queries/select-clause.md @@ -2,9 +2,9 @@ description: "Learn more about: Select Clause (Visual Basic)" title: "Select Clause" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.QuerySelect" -helpviewer_keywords: +helpviewer_keywords: - "Select statement [Visual Basic]" - "Select clause [Visual Basic]" - "queries [Visual Basic], Select" @@ -12,44 +12,44 @@ ms.assetid: 27a3f61c-5960-4692-9b91-4d0c4b6178fe --- # Select Clause (Visual Basic) -Defines the result of a query. - -## Syntax - -```vb -Select [ var1 = ] fieldName1 [, [ var2 = ] fieldName2 [...] ] -``` - -## Parts - - `var1` - Optional. An alias that can be used to reference the results of the column expression. - - `fieldName1` - Required. The name of the field to return in the query result. - -## Remarks - - You can use the `Select` clause to define the results to return from a query. This enables you to either define the members of a new anonymous type that is created by a query, or to target the members of a named type that is returned by a query. The `Select` clause is not required for a query. If no `Select` clause is specified, the query will return a type based on all members of the range variables identified for the current scope. For more information, see [Anonymous Types](../../programming-guide/language-features/objects-and-classes/anonymous-types.md). When a query creates a named type, it will return a result of type where `T` is the created type. - - The `Select` clause can reference any variables in the current scope. This includes range variables identified in the `From` clause (or `From` clauses). It also includes any new variables created with an alias by the `Aggregate`, `Let`, `Group By`, or `Group Join` clauses, or variables from a previous `Select` clause in the query expression. The `Select` clause can also include static values. For example, the following code example shows a query expression in which the `Select` clause defines the query result as a new anonymous type with four members: `ProductName`, `Price`, `Discount`, and `DiscountedPrice`. The `ProductName` and `Price` member values are taken from the product range variable that is defined in the `From` clause. The `DiscountedPrice` member value is calculated in the `Let` clause. The `Discount` member is a static value. - - [!code-vb[VbSimpleQuerySamples#27](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/QuerySamples1.vb#27)] - - The `Select` clause introduces a new set of range variables for subsequent query clauses, and previous range variables are no longer in scope. The last `Select` clause in a query expression determines the return value of the query. For example, the following query returns the company name and order ID for every customer order for which the total exceeds 500. The first `Select` clause identifies the range variables for the `Where` clause and the second `Select` clause. The second `Select` clause identifies the values returned by the query as a new anonymous type. - - [!code-vb[VbSimpleQuerySamples#28](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/QuerySamples1.vb#28)] - - If the `Select` clause identifies a single item to return, the query expression returns a collection of the type of that single item. If the `Select` clause identifies multiple items to return, the query expression returns a collection of a new anonymous type, based on the selected items. For example, the following two queries return collections of two different types based on the `Select` clause. The first query returns a collection of company names as strings. The second query returns a collection of `Customer` objects populated with the company names and address information. - - [!code-vb[VbSimpleQuerySamples#29](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/QuerySamples1.vb#29)] - -## Example - - The following query expression uses a `From` clause to declare a range variable `cust` for the `customers` collection. The `Select` clause selects the customer name and ID value and populates the `CompanyName` and `CustomerID` columns of the new range variable. The `For Each` statement loops over each returned object and displays the `CompanyName` and `CustomerID` columns for each record. - - [!code-vb[VbSimpleQuerySamples#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/QuerySamples1.vb#30)] - +Defines the result of a query. + +## Syntax + +```vb +Select [ var1 = ] fieldName1 [, [ var2 = ] fieldName2 [...] ] +``` + +## Parts + + `var1` + Optional. An alias that can be used to reference the results of the column expression. + + `fieldName1` + Required. The name of the field to return in the query result. + +## Remarks + + You can use the `Select` clause to define the results to return from a query. This enables you to either define the members of a new anonymous type that is created by a query, or to target the members of a named type that is returned by a query. The `Select` clause is not required for a query. If no `Select` clause is specified, the query will return a type based on all members of the range variables identified for the current scope. For more information, see [Anonymous Types](../../programming-guide/language-features/objects-and-classes/anonymous-types.md). When a query creates a named type, it will return a result of type where `T` is the created type. + + The `Select` clause can reference any variables in the current scope. This includes range variables identified in the `From` clause (or `From` clauses). It also includes any new variables created with an alias by the `Aggregate`, `Let`, `Group By`, or `Group Join` clauses, or variables from a previous `Select` clause in the query expression. The `Select` clause can also include static values. For example, the following code example shows a query expression in which the `Select` clause defines the query result as a new anonymous type with four members: `ProductName`, `Price`, `Discount`, and `DiscountedPrice`. The `ProductName` and `Price` member values are taken from the product range variable that is defined in the `From` clause. The `DiscountedPrice` member value is calculated in the `Let` clause. The `Discount` member is a static value. + + [!code-vb[VbSimpleQuerySamples#27](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/QuerySamples1.vb#27)] + + The `Select` clause introduces a new set of range variables for subsequent query clauses, and previous range variables are no longer in scope. The last `Select` clause in a query expression determines the return value of the query. For example, the following query returns the company name and order ID for every customer order for which the total exceeds 500. The first `Select` clause identifies the range variables for the `Where` clause and the second `Select` clause. The second `Select` clause identifies the values returned by the query as a new anonymous type. + + [!code-vb[VbSimpleQuerySamples#28](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/QuerySamples1.vb#28)] + + If the `Select` clause identifies a single item to return, the query expression returns a collection of the type of that single item. If the `Select` clause identifies multiple items to return, the query expression returns a collection of a new anonymous type, based on the selected items. For example, the following two queries return collections of two different types based on the `Select` clause. The first query returns a collection of company names as strings. The second query returns a collection of `Customer` objects populated with the company names and address information. + + [!code-vb[VbSimpleQuerySamples#29](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/QuerySamples1.vb#29)] + +## Example + + The following query expression uses a `From` clause to declare a range variable `cust` for the `customers` collection. The `Select` clause selects the customer name and ID value and populates the `CompanyName` and `CustomerID` columns of the new range variable. The `For Each` statement loops over each returned object and displays the `CompanyName` and `CustomerID` columns for each record. + + [!code-vb[VbSimpleQuerySamples#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbSimpleQuerySamples/VB/QuerySamples1.vb#30)] + ## See also - [Introduction to LINQ in Visual Basic](../../programming-guide/language-features/linq/introduction-to-linq.md) diff --git a/docs/visual-basic/language-reference/runtime-library-members.md b/docs/visual-basic/language-reference/runtime-library-members.md index e73e6eeee3ec2..81a866849e164 100644 --- a/docs/visual-basic/language-reference/runtime-library-members.md +++ b/docs/visual-basic/language-reference/runtime-library-members.md @@ -17,20 +17,20 @@ The `Microsoft.VisualBasic` namespace contains the classes, modules, constants, ## Microsoft.VisualBasic.Collection Class -- -- -- -- -- -- -- +- +- +- +- +- +- +- ## Microsoft.VisualBasic.ComClassAttribute Class -- -- -- -- +- +- +- +- ## Microsoft.VisualBasic.ControlChars Class @@ -408,266 +408,266 @@ The `Microsoft.VisualBasic` namespace contains the classes, modules, constants, ## Microsoft.VisualBasic.Conversion Module -- -- -- -- -- -- -- +- +- +- +- +- +- +- ## Microsoft.VisualBasic.DateAndTime Module :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: ## Microsoft.VisualBasic.ErrObject Class -- -- -- -- -- -- -- -- -- +- +- +- +- +- +- +- +- +- ## Microsoft.VisualBasic.FileSystem Module :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: ## Microsoft.VisualBasic.Financial Module -- -- -- -- -- -- -- -- -- -- -- -- -- +- +- +- +- +- +- +- +- +- +- +- +- +- ## Microsoft.VisualBasic.Globals Module -- -- -- -- +- +- +- +- ## Microsoft.VisualBasic.HideModuleNameAttribute Class @@ -677,63 +677,63 @@ The `Microsoft.VisualBasic` namespace contains the classes, modules, constants, :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::row-end::: @@ -741,204 +741,204 @@ The `Microsoft.VisualBasic` namespace contains the classes, modules, constants, :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: ## Microsoft.VisualBasic.MyGroupCollectionAttribute Class -- -- -- -- +- +- +- +- ## Microsoft.VisualBasic.Strings Module :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: :::row::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::column span=""::: - + :::column-end::: :::row-end::: ## Microsoft.VisualBasic.VBFixedArrayAttribute Class -- -- +- +- ## Microsoft.VisualBasic.VBFixedStringAttribute Class -- +- ## Microsoft.VisualBasic.VbMath Module -- -- +- +- ## Microsoft.VisualBasic Constants and Enumerations diff --git a/docs/visual-basic/language-reference/statements/class-statement.md b/docs/visual-basic/language-reference/statements/class-statement.md index f88a3db654edd..985f9b246e675 100644 --- a/docs/visual-basic/language-reference/statements/class-statement.md +++ b/docs/visual-basic/language-reference/statements/class-statement.md @@ -2,9 +2,9 @@ description: "Learn more about: Class Statement (Visual Basic)" title: "Class Statement" ms.date: 05/12/2018 -f1_keywords: +f1_keywords: - "vb.Class" -helpviewer_keywords: +helpviewer_keywords: - "class modules" - "Class statement [Visual Basic]" - "classes [Visual Basic], fields" @@ -17,95 +17,95 @@ ms.assetid: f2664f38-eb5a-4d4b-a374-1d041521fb6c --- # Class Statement (Visual Basic) -Declares the name of a class and introduces the definition of the variables, properties, events, and procedures that the class comprises. - -## Syntax - -```vb -[ ] [ accessmodifier ] [ Shadows ] [ MustInherit | NotInheritable ] [ Partial ] _ -Class name [ ( Of typelist ) ] - [ Inherits classname ] - [ Implements interfacenames ] - [ statements ] -End Class -``` - -## Parts - -|Term|Definition| -|---|---| -|`attributelist`|Optional. See [Attribute List](attribute-list.md).| -|`accessmodifier`|Optional. Can be one of the following:

- [Public](../modifiers/public.md)
- [Protected](../modifiers/protected.md)
- [Friend](../modifiers/friend.md)
- [Private](../modifiers/private.md)
- [Protected Friend](../modifiers/protected-friend.md)
- [Private Protected](../modifiers/private-protected.md)

See [Access levels in Visual Basic](../../programming-guide/language-features/declared-elements/access-levels.md).| -|`Shadows`|Optional. See [Shadows](../modifiers/shadows.md).| -|`MustInherit`|Optional. See [MustInherit](../modifiers/mustinherit.md).| -|`NotInheritable`|Optional. See [NotInheritable](../modifiers/notinheritable.md).| -|`Partial`|Optional. Indicates a partial definition of the class. See [Partial](../modifiers/partial.md).| -|`name`|Required. Name of this class. See [Declared Element Names](../../programming-guide/language-features/declared-elements/declared-element-names.md).| -|`Of`|Optional. Specifies that this is a generic class.| -|`typelist`|Required if you use the [Of](of-clause.md) keyword. List of type parameters for this class. See [Type List](type-list.md).| -|`Inherits`|Optional. Indicates that this class inherits the members of another class. See [Inherits Statement](inherits-statement.md).| -|`classname`|Required if you use the `Inherits` statement. The name of the class from which this class derives.| -|`Implements`|Optional. Indicates that this class implements the members of one or more interfaces. See [Implements Statement](implements-statement.md).| -|`interfacenames`|Required if you use the `Implements` statement. The names of the interfaces this class implements.| -|`statements`|Optional. Statements which define the members of this class.| -|`End Class`|Required. Terminates the `Class` definition.| - -## Remarks - - A `Class` statement defines a new data type. A *class* is a fundamental building block of object-oriented programming (OOP). For more information, see [Objects and Classes](../../programming-guide/language-features/objects-and-classes/index.md). - - You can use `Class` only at namespace or module level. This means the *declaration context* for a class must be a source file, namespace, class, structure, module, or interface, and cannot be a procedure or block. For more information, see [Declaration Contexts and Default Access Levels](declaration-contexts-and-default-access-levels.md). - - Each instance of a class has a lifetime independent of all other instances. This lifetime begins when it is created by a [New Operator](../operators/new-operator.md) clause or by a function such as . It ends when all variables pointing to the instance have been set to [Nothing](../nothing.md) or to instances of other classes. - - Classes default to [Friend](../modifiers/friend.md) access. You can adjust their access levels with the access modifiers. For more information, see [Access levels in Visual Basic](../../programming-guide/language-features/declared-elements/access-levels.md). - -## Rules - -- **Nesting.** You can define one class within another. The outer class is called the *containing class*, and the inner class is called a *nested class*. - -- **Inheritance.** If the class uses the [Inherits Statement](inherits-statement.md), you can specify only one base class or interface. A class cannot inherit from more than one element. - - A class cannot inherit from another class with a more restrictive access level. For example, a `Public` class cannot inherit from a `Friend` class. - - A class cannot inherit from a class nested within it. - -- **Implementation.** If the class uses the [Implements Statement](implements-statement.md), you must implement every member defined by every interface you specify in `interfacenames`. An exception to this is reimplementation of a base class member. For more information, see "Reimplementation" in [Implements](implements-clause.md). - -- **Default Property.** A class can specify at most one property as its *default property*. For more information, see [Default](../modifiers/default.md). - -## Behavior - -- **Access Level.** Within a class, you can declare each member with its own access level. Class members default to [Public](../modifiers/public.md) access, except variables and constants, which default to [Private](../modifiers/private.md) access. When a class has more restricted access than one of its members, the class access level takes precedence. - -- **Scope.** A class is in scope throughout its containing namespace, class, structure, or module. - - The scope of every class member is the entire class. - - **Lifetime.** Visual Basic does not support static classes. The functional equivalent of a static class is provided by a module. For more information, see [Module Statement](module-statement.md). - - Class members have lifetimes depending on how and where they are declared. For more information, see [Lifetime in Visual Basic](../../programming-guide/language-features/declared-elements/lifetime.md). - -- **Qualification.** Code outside a class must qualify a member's name with the name of that class. - - If code inside a nested class makes an unqualified reference to a programming element, Visual Basic searches for the element first in the nested class, then in its containing class, and so on out to the outermost containing element. - -## Classes and Modules - - These elements have many similarities, but there are some important differences as well. - -- **Terminology.** Previous versions of Visual Basic recognize two types of modules: *class modules* (.cls files) and *standard modules* (.bas files). The current version calls these *classes* and *modules*, respectively. - -- **Shared Members.** You can control whether a member of a class is a shared or instance member. - -- **Object Orientation.** Classes are object-oriented, but modules are not. You can create one or more instances of a class. For more information, see [Objects and Classes](../../programming-guide/language-features/objects-and-classes/index.md). - -## Example - - The following example uses a `Class` statement to define a class and several members. - - [!code-vb[VbVbalrStatements#62](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#62)] - +Declares the name of a class and introduces the definition of the variables, properties, events, and procedures that the class comprises. + +## Syntax + +```vb +[ ] [ accessmodifier ] [ Shadows ] [ MustInherit | NotInheritable ] [ Partial ] _ +Class name [ ( Of typelist ) ] + [ Inherits classname ] + [ Implements interfacenames ] + [ statements ] +End Class +``` + +## Parts + +|Term|Definition| +|---|---| +|`attributelist`|Optional. See [Attribute List](attribute-list.md).| +|`accessmodifier`|Optional. Can be one of the following:

- [Public](../modifiers/public.md)
- [Protected](../modifiers/protected.md)
- [Friend](../modifiers/friend.md)
- [Private](../modifiers/private.md)
- [Protected Friend](../modifiers/protected-friend.md)
- [Private Protected](../modifiers/private-protected.md)

See [Access levels in Visual Basic](../../programming-guide/language-features/declared-elements/access-levels.md).| +|`Shadows`|Optional. See [Shadows](../modifiers/shadows.md).| +|`MustInherit`|Optional. See [MustInherit](../modifiers/mustinherit.md).| +|`NotInheritable`|Optional. See [NotInheritable](../modifiers/notinheritable.md).| +|`Partial`|Optional. Indicates a partial definition of the class. See [Partial](../modifiers/partial.md).| +|`name`|Required. Name of this class. See [Declared Element Names](../../programming-guide/language-features/declared-elements/declared-element-names.md).| +|`Of`|Optional. Specifies that this is a generic class.| +|`typelist`|Required if you use the [Of](of-clause.md) keyword. List of type parameters for this class. See [Type List](type-list.md).| +|`Inherits`|Optional. Indicates that this class inherits the members of another class. See [Inherits Statement](inherits-statement.md).| +|`classname`|Required if you use the `Inherits` statement. The name of the class from which this class derives.| +|`Implements`|Optional. Indicates that this class implements the members of one or more interfaces. See [Implements Statement](implements-statement.md).| +|`interfacenames`|Required if you use the `Implements` statement. The names of the interfaces this class implements.| +|`statements`|Optional. Statements which define the members of this class.| +|`End Class`|Required. Terminates the `Class` definition.| + +## Remarks + + A `Class` statement defines a new data type. A *class* is a fundamental building block of object-oriented programming (OOP). For more information, see [Objects and Classes](../../programming-guide/language-features/objects-and-classes/index.md). + + You can use `Class` only at namespace or module level. This means the *declaration context* for a class must be a source file, namespace, class, structure, module, or interface, and cannot be a procedure or block. For more information, see [Declaration Contexts and Default Access Levels](declaration-contexts-and-default-access-levels.md). + + Each instance of a class has a lifetime independent of all other instances. This lifetime begins when it is created by a [New Operator](../operators/new-operator.md) clause or by a function such as . It ends when all variables pointing to the instance have been set to [Nothing](../nothing.md) or to instances of other classes. + + Classes default to [Friend](../modifiers/friend.md) access. You can adjust their access levels with the access modifiers. For more information, see [Access levels in Visual Basic](../../programming-guide/language-features/declared-elements/access-levels.md). + +## Rules + +- **Nesting.** You can define one class within another. The outer class is called the *containing class*, and the inner class is called a *nested class*. + +- **Inheritance.** If the class uses the [Inherits Statement](inherits-statement.md), you can specify only one base class or interface. A class cannot inherit from more than one element. + + A class cannot inherit from another class with a more restrictive access level. For example, a `Public` class cannot inherit from a `Friend` class. + + A class cannot inherit from a class nested within it. + +- **Implementation.** If the class uses the [Implements Statement](implements-statement.md), you must implement every member defined by every interface you specify in `interfacenames`. An exception to this is reimplementation of a base class member. For more information, see "Reimplementation" in [Implements](implements-clause.md). + +- **Default Property.** A class can specify at most one property as its *default property*. For more information, see [Default](../modifiers/default.md). + +## Behavior + +- **Access Level.** Within a class, you can declare each member with its own access level. Class members default to [Public](../modifiers/public.md) access, except variables and constants, which default to [Private](../modifiers/private.md) access. When a class has more restricted access than one of its members, the class access level takes precedence. + +- **Scope.** A class is in scope throughout its containing namespace, class, structure, or module. + + The scope of every class member is the entire class. + + **Lifetime.** Visual Basic does not support static classes. The functional equivalent of a static class is provided by a module. For more information, see [Module Statement](module-statement.md). + + Class members have lifetimes depending on how and where they are declared. For more information, see [Lifetime in Visual Basic](../../programming-guide/language-features/declared-elements/lifetime.md). + +- **Qualification.** Code outside a class must qualify a member's name with the name of that class. + + If code inside a nested class makes an unqualified reference to a programming element, Visual Basic searches for the element first in the nested class, then in its containing class, and so on out to the outermost containing element. + +## Classes and Modules + + These elements have many similarities, but there are some important differences as well. + +- **Terminology.** Previous versions of Visual Basic recognize two types of modules: *class modules* (.cls files) and *standard modules* (.bas files). The current version calls these *classes* and *modules*, respectively. + +- **Shared Members.** You can control whether a member of a class is a shared or instance member. + +- **Object Orientation.** Classes are object-oriented, but modules are not. You can create one or more instances of a class. For more information, see [Objects and Classes](../../programming-guide/language-features/objects-and-classes/index.md). + +## Example + + The following example uses a `Class` statement to define a class and several members. + + [!code-vb[VbVbalrStatements#62](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#62)] + ## See also - [Objects and Classes](../../programming-guide/language-features/objects-and-classes/index.md) diff --git a/docs/visual-basic/language-reference/statements/const-statement.md b/docs/visual-basic/language-reference/statements/const-statement.md index 45c718f1bd08b..9c4aedf943510 100644 --- a/docs/visual-basic/language-reference/statements/const-statement.md +++ b/docs/visual-basic/language-reference/statements/const-statement.md @@ -21,16 +21,16 @@ Const constantlist ## Parts -`attributelist` +`attributelist` Optional. List of attributes that apply to all the constants declared in this statement. See [Attribute List](attribute-list.md) in angle brackets ("`<`" and "`>`"). -`accessmodifier` +`accessmodifier` Optional. Use this to specify what code can access these constants. Can be [Public](../modifiers/public.md), [Protected](../modifiers/protected.md), [Friend](../modifiers/friend.md), [Protected Friend](../modifiers/protected-friend.md), [Private](../modifiers/private.md), or [Private Protected](../modifiers/private-protected.md). -`Shadows` +`Shadows` Optional. Use this to redeclare and hide a programming element in a base class. See [Shadows](../modifiers/shadows.md). -`constantlist` +`constantlist` Required. List of constants being declared in this statement. `constant` `[ ,` `constant` `... ]` @@ -97,12 +97,12 @@ If you define a constant with data type `Object`, the Visual Basic compiler give [!code-vb[VbVbalrStatements#87](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#87)] -The preceding example uses the method on the object returned by the [GetType Operator](../operators/gettype-operator.md), because cannot be converted to `String` using `CStr`. +The preceding example uses the method on the object returned by the [GetType Operator](../operators/gettype-operator.md), because cannot be converted to `String` using `CStr`. ## See also -- -- +- +- - [Enum Statement](enum-statement.md) - [#Const Directive](../directives/const-directive.md) - [Dim Statement](dim-statement.md) diff --git a/docs/visual-basic/language-reference/statements/declare-statement.md b/docs/visual-basic/language-reference/statements/declare-statement.md index 7ccdabf787f0b..7ca7f24ba793f 100644 --- a/docs/visual-basic/language-reference/statements/declare-statement.md +++ b/docs/visual-basic/language-reference/statements/declare-statement.md @@ -142,7 +142,7 @@ The provides an alterna ## See also -- +- - [Imports Statement (.NET Namespace and Type)](imports-statement-net-namespace-and-type.md) - [AddressOf Operator](../operators/addressof-operator.md) - [Function Statement](function-statement.md) diff --git a/docs/visual-basic/language-reference/statements/do-loop-statement.md b/docs/visual-basic/language-reference/statements/do-loop-statement.md index 7d74b1f1e525e..d63f24c651bf1 100644 --- a/docs/visual-basic/language-reference/statements/do-loop-statement.md +++ b/docs/visual-basic/language-reference/statements/do-loop-statement.md @@ -104,7 +104,7 @@ Loop [ { While | Until } condition ] ## Example 4 - The following example reads all lines in a text file. The method opens the file and returns a that reads the characters. In the `Do...Loop` condition, the method of the `StreamReader` determines whether there are any additional characters. + The following example reads all lines in a text file. The method opens the file and returns a that reads the characters. In the `Do...Loop` condition, the method of the `StreamReader` determines whether there are any additional characters. [!code-vb[VbVbalrStatements#134](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/class10.vb#134)] diff --git a/docs/visual-basic/language-reference/statements/end-statement.md b/docs/visual-basic/language-reference/statements/end-statement.md index b284b90c3cbf5..bd1ea40aba4ce 100644 --- a/docs/visual-basic/language-reference/statements/end-statement.md +++ b/docs/visual-basic/language-reference/statements/end-statement.md @@ -2,10 +2,10 @@ description: "Learn more about: End Statement" title: "End Statement" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.End" - "End" -helpviewer_keywords: +helpviewer_keywords: - "execution [Visual Basic], ending" - "files [Visual Basic], closing" - "End keyword [Visual Basic], End statements" @@ -18,42 +18,42 @@ ms.assetid: 0e64467c-0f34-4aab-9ddd-43f8b9d55d90 --- # End Statement -Terminates execution immediately. - -## Syntax - -```vb -End -``` - -## Remarks - - You can place the `End` statement anywhere in a procedure to force the entire application to stop running. `End` closes any files opened with an `Open` statement and clears all the application's variables. The application closes as soon as there are no other programs holding references to its objects and none of its code is running. - +Terminates execution immediately. + +## Syntax + +```vb +End +``` + +## Remarks + + You can place the `End` statement anywhere in a procedure to force the entire application to stop running. `End` closes any files opened with an `Open` statement and clears all the application's variables. The application closes as soon as there are no other programs holding references to its objects and none of its code is running. + > [!NOTE] -> The `End` statement stops code execution abruptly, and does not invoke the `Dispose` or `Finalize` method, or any other Visual Basic code. Object references held by other programs are invalidated. If an `End` statement is encountered within a `Try` or `Catch` block, control does not pass to the corresponding `Finally` block. - - The `Stop` statement suspends execution, but unlike `End`, it does not close any files or clear any variables, unless it is encountered in a compiled executable (.exe) file. - - Because `End` terminates your application without attending to any resources that might be open, you should try to close down cleanly before using it. For example, if your application has any forms open, you should close them before control reaches the `End` statement. - - You should use `End` sparingly, and only when you need to stop immediately. The normal ways to terminate a procedure ([Return Statement](return-statement.md) and [Exit Statement](exit-statement.md)) not only close down the procedure cleanly but also give the calling code the opportunity to close down cleanly. A console application, for example, can simply `Return` from the `Main` procedure. - +> The `End` statement stops code execution abruptly, and does not invoke the `Dispose` or `Finalize` method, or any other Visual Basic code. Object references held by other programs are invalidated. If an `End` statement is encountered within a `Try` or `Catch` block, control does not pass to the corresponding `Finally` block. + + The `Stop` statement suspends execution, but unlike `End`, it does not close any files or clear any variables, unless it is encountered in a compiled executable (.exe) file. + + Because `End` terminates your application without attending to any resources that might be open, you should try to close down cleanly before using it. For example, if your application has any forms open, you should close them before control reaches the `End` statement. + + You should use `End` sparingly, and only when you need to stop immediately. The normal ways to terminate a procedure ([Return Statement](return-statement.md) and [Exit Statement](exit-statement.md)) not only close down the procedure cleanly but also give the calling code the opportunity to close down cleanly. A console application, for example, can simply `Return` from the `Main` procedure. + > [!IMPORTANT] -> The `End` statement calls the method of the class in the namespace. requires that you have `UnmanagedCode` permission. If you do not, a error occurs. - - When followed by an additional keyword, [End \ Statement](end-keyword-statement.md) delineates the end of the definition of the appropriate procedure or block. For example, `End Function` terminates the definition of a `Function` procedure. - -## Example - - The following example uses the `End` statement to terminate code execution if the user requests it. - - [!code-vb[VbVersHelp60Controls#64](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVersHelp60Controls/VB/Form1.vb#64)] - -## Smart Device Developer Notes - - This statement is not supported. - +> The `End` statement calls the method of the class in the namespace. requires that you have `UnmanagedCode` permission. If you do not, a error occurs. + + When followed by an additional keyword, [End \ Statement](end-keyword-statement.md) delineates the end of the definition of the appropriate procedure or block. For example, `End Function` terminates the definition of a `Function` procedure. + +## Example + + The following example uses the `End` statement to terminate code execution if the user requests it. + + [!code-vb[VbVersHelp60Controls#64](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVersHelp60Controls/VB/Form1.vb#64)] + +## Smart Device Developer Notes + + This statement is not supported. + ## See also - [Stop Statement](stop-statement.md) diff --git a/docs/visual-basic/language-reference/statements/enum-statement.md b/docs/visual-basic/language-reference/statements/enum-statement.md index ae0fcfe765e5f..3558183c69cf1 100644 --- a/docs/visual-basic/language-reference/statements/enum-statement.md +++ b/docs/visual-basic/language-reference/statements/enum-statement.md @@ -175,14 +175,14 @@ The following example shows how to use a bitwise enumeration. Multiple values ca ## Example 7 -The following example iterates through an enumeration. It uses the method to retrieve an array of member names from the enumeration, and to retrieve an array of member values. +The following example iterates through an enumeration. It uses the method to retrieve an array of member names from the enumeration, and to retrieve an array of member values. [!code-vb[VbEnumsTask#51](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbEnumsTask/VB/Class1.vb#51)] ## See also - -- +- - [Const Statement](const-statement.md) - [Dim Statement](dim-statement.md) - [Implicit and Explicit Conversions](../../programming-guide/language-features/data-types/implicit-and-explicit-conversions.md) diff --git a/docs/visual-basic/language-reference/statements/error-statement.md b/docs/visual-basic/language-reference/statements/error-statement.md index 7bdb17165ed2f..ebfaba6cab64b 100644 --- a/docs/visual-basic/language-reference/statements/error-statement.md +++ b/docs/visual-basic/language-reference/statements/error-statement.md @@ -2,9 +2,9 @@ description: "Learn more about: Error Statement" title: "Error Statement" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.error" -helpviewer_keywords: +helpviewer_keywords: - "Error statement [Visual Basic], syntax" - "Error statement [Visual Basic]" - "Error keyword [Visual Basic]" @@ -14,59 +14,59 @@ ms.assetid: 85cd5c59-5224-4f02-aaf5-fcfefab17a29 --- # Error Statement -Simulates the occurrence of an error. - -## Syntax - -```vb -Error errornumber -``` - -## Parts - - `errornumber` - Required. Can be any valid error number. - -## Remarks - - The `Error` statement is supported for backward compatibility. In new code, especially when creating objects, use the `Err` object's `Raise` method to generate run-time errors. - - If `errornumber` is defined, the `Error` statement calls the error handler after the properties of the `Err` object are assigned the following default values: - -|Property|Value| -|--------------|-----------| -|`Number`|Value specified as argument to `Error` statement. Can be any valid error number.| -|`Source`|Name of the current Visual Basic project.| -|`Description`|String expression corresponding to the return value of the `Error` function for the specified `Number`, if this string exists. If the string does not exist, `Description` contains a zero-length string ("").| -|`HelpFile`|The fully qualified drive, path, and file name of the appropriate Visual Basic Help file.| -|`HelpContext`|The appropriate Visual Basic Help file context ID for the error corresponding to the `Number` property.| -|`LastDLLError`|Zero.| - - If no error handler exists, or if none is enabled, an error message is created and displayed from the `Err` object properties. - +Simulates the occurrence of an error. + +## Syntax + +```vb +Error errornumber +``` + +## Parts + + `errornumber` + Required. Can be any valid error number. + +## Remarks + + The `Error` statement is supported for backward compatibility. In new code, especially when creating objects, use the `Err` object's `Raise` method to generate run-time errors. + + If `errornumber` is defined, the `Error` statement calls the error handler after the properties of the `Err` object are assigned the following default values: + +|Property|Value| +|--------------|-----------| +|`Number`|Value specified as argument to `Error` statement. Can be any valid error number.| +|`Source`|Name of the current Visual Basic project.| +|`Description`|String expression corresponding to the return value of the `Error` function for the specified `Number`, if this string exists. If the string does not exist, `Description` contains a zero-length string ("").| +|`HelpFile`|The fully qualified drive, path, and file name of the appropriate Visual Basic Help file.| +|`HelpContext`|The appropriate Visual Basic Help file context ID for the error corresponding to the `Number` property.| +|`LastDLLError`|Zero.| + + If no error handler exists, or if none is enabled, an error message is created and displayed from the `Err` object properties. + > [!NOTE] -> Some Visual Basic host applications cannot create objects. See your host application's documentation to determine whether it can create classes and objects. - -## Example - - This example uses the `Error` statement to generate error number 11. - -```vb -On Error Resume Next ' Defer error handling. -Error 11 ' Simulate the "Division by zero" error. -``` - -## Requirements - - **Namespace:** [Microsoft.VisualBasic](../runtime-library-members.md) - - **Assembly:** Visual Basic Runtime Library (in Microsoft.VisualBasic.dll) - +> Some Visual Basic host applications cannot create objects. See your host application's documentation to determine whether it can create classes and objects. + +## Example + + This example uses the `Error` statement to generate error number 11. + +```vb +On Error Resume Next ' Defer error handling. +Error 11 ' Simulate the "Division by zero" error. +``` + +## Requirements + + **Namespace:** [Microsoft.VisualBasic](../runtime-library-members.md) + + **Assembly:** Visual Basic Runtime Library (in Microsoft.VisualBasic.dll) + ## See also -- -- -- +- +- +- - [On Error Statement](on-error-statement.md) - [Resume Statement](resume-statement.md) - [Error Messages](../error-messages/index.md) diff --git a/docs/visual-basic/language-reference/statements/for-each-next-statement.md b/docs/visual-basic/language-reference/statements/for-each-next-statement.md index f786916d539e7..c1b679d2d040d 100644 --- a/docs/visual-basic/language-reference/statements/for-each-next-statement.md +++ b/docs/visual-basic/language-reference/statements/for-each-next-statement.md @@ -123,31 +123,31 @@ You might want to avoid changing the value of `element` inside a loop. Doing thi When you're nesting loops, if a `Next` statement of an outer nesting level is encountered before the `Next` of an inner level, the compiler signals an error. However, the compiler can detect this overlapping error only if you specify `element` in every `Next` statement. -If your code depends on traversing a collection in a particular order, a `For Each`...`Next` loop isn't the best choice, unless you know the characteristics of the enumerator object the collection exposes. The order of traversal isn't determined by Visual Basic, but by the method of the enumerator object. Therefore, you might not be able to predict which element of the collection is the first to be returned in `element`, or which is the next to be returned after a given element. You might achieve more reliable results using a different loop structure, such as `For`...`Next` or `Do`...`Loop`. +If your code depends on traversing a collection in a particular order, a `For Each`...`Next` loop isn't the best choice, unless you know the characteristics of the enumerator object the collection exposes. The order of traversal isn't determined by Visual Basic, but by the method of the enumerator object. Therefore, you might not be able to predict which element of the collection is the first to be returned in `element`, or which is the next to be returned after a given element. You might achieve more reliable results using a different loop structure, such as `For`...`Next` or `Do`...`Loop`. The runtime must be able to convert the elements in `group` to `element`. The [`Option Strict`] statement controls whether both widening and narrowing conversions are allowed (`Option Strict` is off, its default value), or whether only widening conversions are allowed (`Option Strict` is on). For more information, see [Narrowing conversions](#narrowing-conversions). -The data type of `group` must be a reference type that refers to a collection or an array that's enumerable. Most commonly this means that `group` refers to an object that implements the interface of the `System.Collections` namespace or the interface of the `System.Collections.Generic` namespace. `System.Collections.IEnumerable` defines the method, which returns an enumerator object for the collection. The enumerator object implements the `System.Collections.IEnumerator` interface of the `System.Collections` namespace and exposes the property and the and methods. Visual Basic uses these to traverse the collection. +The data type of `group` must be a reference type that refers to a collection or an array that's enumerable. Most commonly this means that `group` refers to an object that implements the interface of the `System.Collections` namespace or the interface of the `System.Collections.Generic` namespace. `System.Collections.IEnumerable` defines the method, which returns an enumerator object for the collection. The enumerator object implements the `System.Collections.IEnumerator` interface of the `System.Collections` namespace and exposes the property and the and methods. Visual Basic uses these to traverse the collection. ### Narrowing Conversions When `Option Strict` is set to `On`, narrowing conversions ordinarily cause compiler errors. In a `For Each` statement, however, conversions from the elements in `group` to `element` are evaluated and performed at run time, and compiler errors caused by narrowing conversions are suppressed. -In the following example, the assignment of `m` as the initial value for `n` doesn't compile when `Option Strict` is on because the conversion of a `Long` to an `Integer` is a narrowing conversion. In the `For Each` statement, however, no compiler error is reported, even though the assignment to `number` requires the same conversion from `Long` to `Integer`. In the `For Each` statement that contains a large number, a run-time error occurs when is applied to the large number. +In the following example, the assignment of `m` as the initial value for `n` doesn't compile when `Option Strict` is on because the conversion of a `Long` to an `Integer` is a narrowing conversion. In the `For Each` statement, however, no compiler error is reported, even though the assignment to `number` requires the same conversion from `Long` to `Integer`. In the `For Each` statement that contains a large number, a run-time error occurs when is applied to the large number. :::code language="vb" source="./snippets/for-each-next-statement/vb/Program.vb"::: ### IEnumerator Calls -When execution of a `For Each`...`Next` loop starts, Visual Basic verifies that `group` refers to a valid collection object. If not, it throws an exception. Otherwise, it calls the method and the property of the enumerator object to return the first element. If `MoveNext` indicates that there is no next element, that is, if the collection is empty, the `For Each` loop stops and control passes to the statement following the `Next` statement. Otherwise, Visual Basic sets `element` to the first element and runs the statement block. +When execution of a `For Each`...`Next` loop starts, Visual Basic verifies that `group` refers to a valid collection object. If not, it throws an exception. Otherwise, it calls the method and the property of the enumerator object to return the first element. If `MoveNext` indicates that there is no next element, that is, if the collection is empty, the `For Each` loop stops and control passes to the statement following the `Next` statement. Otherwise, Visual Basic sets `element` to the first element and runs the statement block. Each time Visual Basic encounters the `Next` statement, it returns to the `For Each` statement. Again it calls `MoveNext` and `Current` to return the next element, and again it either runs the block or stops the loop depending on the result. This process continues until `MoveNext` indicates that there is no next element or an `Exit For` statement is encountered. -**Modifying the Collection.** The enumerator object returned by normally doesn't let you change the collection by adding, deleting, replacing, or reordering any elements. If you change the collection after you have initiated a `For Each`...`Next` loop, the enumerator object becomes invalid, and the next attempt to access an element causes an exception. +**Modifying the Collection.** The enumerator object returned by normally doesn't let you change the collection by adding, deleting, replacing, or reordering any elements. If you change the collection after you have initiated a `For Each`...`Next` loop, the enumerator object becomes invalid, and the next attempt to access an element causes an exception. However, this blocking of modification isn't determined by Visual Basic, but rather by the implementation of the interface. It is possible to implement `IEnumerable` in a way that allows for modification during iteration. If you are considering doing such dynamic modification, make sure that you understand the characteristics of the `IEnumerable` implementation on the collection you are using. -**Modifying Collection Elements.** The property of the enumerator object is [ReadOnly](../modifiers/readonly.md), and it returns a local copy of each collection element. This means that you cannot modify the elements themselves in a `For Each`...`Next` loop. Any modification you make affects only the local copy from `Current` and isn't reflected back into the underlying collection. However, if an element is a reference type, you can modify the members of the instance to which it points. The following example modifies the `BackColor` member of each `thisControl` element. You cannot, however, modify `thisControl` itself. +**Modifying Collection Elements.** The property of the enumerator object is [ReadOnly](../modifiers/readonly.md), and it returns a local copy of each collection element. This means that you cannot modify the elements themselves in a `For Each`...`Next` loop. Any modification you make affects only the local copy from `Current` and isn't reflected back into the underlying collection. However, if an element is a reference type, you can modify the members of the instance to which it points. The following example modifies the `BackColor` member of each `thisControl` element. You cannot, however, modify `thisControl` itself. ```vb Sub LightBlueBackground(thisForm As System.Windows.Forms.Form) @@ -159,7 +159,7 @@ End Sub The previous example can modify the `BackColor` member of each `thisControl` element, although it cannot modify `thisControl` itself. -**Traversing Arrays.** Because the class implements the interface, all arrays expose the method. This means that you can iterate through an array with a `For Each`...`Next` loop. However, you can only read the array elements. You cannot change them. +**Traversing Arrays.** Because the class implements the interface, all arrays expose the method. This means that you can iterate through an array with a `For Each`...`Next` loop. However, you can only read the array elements. You cannot change them. ## Example 1 @@ -169,11 +169,11 @@ The following example lists all the folders in the C:\ directory by using the . The `Car` class implements the interface, which requires that the method be implemented. +The following example illustrates a procedure for sorting a collection. The example sorts instances of a `Car` class that are stored in a . The `Car` class implements the interface, which requires that the method be implemented. -Each call to the method makes a single comparison that's used for sorting. User-written code in the `CompareTo` method returns a value for each comparison of the current object with another object. The value returned is less than zero if the current object is less than the other object, greater than zero if the current object is greater than the other object, and zero if they are equal. This enables you to define in code the criteria for greater than, less than, and equal. +Each call to the method makes a single comparison that's used for sorting. User-written code in the `CompareTo` method returns a value for each comparison of the current object with another object. The value returned is less than zero if the current object is less than the other object, greater than zero if the current object is greater than the other object, and zero if they are equal. This enables you to define in code the criteria for greater than, less than, and equal. -In the `ListCars` method, the `cars.Sort()` statement sorts the list. This call to the method of the causes the `CompareTo` method to be called automatically for the `Car` objects in the `List`. +In the `ListCars` method, the `cars.Sort()` statement sorts the list. This call to the method of the causes the `CompareTo` method to be called automatically for the `Car` objects in the `List`. :::code language="vb" source="./snippets/for-each-next-statement/vb/Examples.vb" id="sort"::: diff --git a/docs/visual-basic/language-reference/statements/for-next-statement.md b/docs/visual-basic/language-reference/statements/for-next-statement.md index 29aff1a6a9892..44050cf7c61f2 100644 --- a/docs/visual-basic/language-reference/statements/for-next-statement.md +++ b/docs/visual-basic/language-reference/statements/for-next-statement.md @@ -179,7 +179,7 @@ In the following example, the statement parameters use a class that has operator ## See also -- +- - [Loop Structures](../../programming-guide/language-features/control-flow/loop-structures.md) - [While...End While Statement](while-end-while-statement.md) - [Do...Loop Statement](do-loop-statement.md) diff --git a/docs/visual-basic/language-reference/statements/function-statement.md b/docs/visual-basic/language-reference/statements/function-statement.md index 20b9ddf75b7a9..a65247327562c 100644 --- a/docs/visual-basic/language-reference/statements/function-statement.md +++ b/docs/visual-basic/language-reference/statements/function-statement.md @@ -221,7 +221,7 @@ If you mark a function with the [Async](../modifiers/async.md) modifier, you can > [!NOTE] > An `Async` procedure returns to the caller when either it encounters the first awaited object that’s not yet complete, or it gets to the end of the `Async` procedure, whichever occurs first. -An `Async` function can have a return type of or . An example of an `Async` function that has a return type of is provided below. +An `Async` function can have a return type of or . An example of an `Async` function that has a return type of is provided below. An `Async` function cannot declare any [ByRef](../modifiers/byref.md) parameters. @@ -235,7 +235,7 @@ An *iterator* function performs a custom iteration over a collection, such as a You call an iterator from client code by using a [For Each…Next](for-each-next-statement.md) statement. -The return type of an iterator function can be , , , or . +The return type of an iterator function can be , , , or . For more information, see [Iterators](../../programming-guide/concepts/iterators.md). @@ -253,7 +253,7 @@ The following example invokes the function declared in the preceding example. ## Example 3 -In the following example, `DelayAsync` is an `Async` `Function` that has a return type of . `DelayAsync` has a `Return` statement that returns an integer. Therefore the function declaration of `DelayAsync` needs to have a return type of `Task(Of Integer)`. Because the return type is `Task(Of Integer)`, the evaluation of the `Await` expression in `DoSomethingAsync` produces an integer. This is demonstrated in this statement: `Dim result As Integer = Await delayTask`. +In the following example, `DelayAsync` is an `Async` `Function` that has a return type of . `DelayAsync` has a `Return` statement that returns an integer. Therefore the function declaration of `DelayAsync` needs to have a return type of `Task(Of Integer)`. Because the return type is `Task(Of Integer)`, the evaluation of the `Await` expression in `DoSomethingAsync` produces an integer. This is demonstrated in this statement: `Dim result As Integer = Await delayTask`. The `startButton_Click` procedure is an example of an `Async Sub` procedure. Because `DoSomethingAsync` is an `Async` function, the task for the call to `DoSomethingAsync` must be awaited, as the following statement demonstrates: `Await DoSomethingAsync()`. The `startButton_Click` `Sub` procedure must be defined with the `Async` modifier because it has an `Await` expression. diff --git a/docs/visual-basic/language-reference/statements/if-then-else-statement.md b/docs/visual-basic/language-reference/statements/if-then-else-statement.md index 9cb9d8d60db05..c2d471a2d111e 100644 --- a/docs/visual-basic/language-reference/statements/if-then-else-statement.md +++ b/docs/visual-basic/language-reference/statements/if-then-else-statement.md @@ -122,8 +122,8 @@ The following example illustrates the use of the single-line syntax. ## See also -- -- +- +- - [#If...Then...#Else Directives](../directives/if-then-else-directives.md) - [Select...Case Statement](select-case-statement.md) - [Nested Control Structures](../../programming-guide/language-features/control-flow/nested-control-structures.md) diff --git a/docs/visual-basic/language-reference/statements/inherits-statement.md b/docs/visual-basic/language-reference/statements/inherits-statement.md index b22c6be764d6c..386d0eab1dd6b 100644 --- a/docs/visual-basic/language-reference/statements/inherits-statement.md +++ b/docs/visual-basic/language-reference/statements/inherits-statement.md @@ -2,66 +2,66 @@ description: "Learn more about: Inherits Statement" title: "Inherits Statement" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.Inherits" - "Inherits" -helpviewer_keywords: +helpviewer_keywords: - "Inherits statement [Visual Basic]" - "Inherits statement [Visual Basic], syntax" ms.assetid: 9e6fe042-9af3-4341-8093-fc3537770cf2 --- # Inherits Statement -Causes the current class or interface to inherit the attributes, variables, properties, procedures, and events from another class or set of interfaces. - -## Syntax - -```vb -Inherits basetypenames -``` - -## Parts - -|Term|Definition| -|---|---| -|`basetypenames`|Required. The name of the class from which this class derives.

-or-

The names of the interfaces from which this interface derives. Use commas to separate multiple names.| - -## Remarks - - If used, the `Inherits` statement must be the first non-blank, non-comment line in a class or interface definition. It should immediately follow the `Class` or `Interface` statement. - - You can use `Inherits` only in a class or interface. This means the declaration context for an inheritance cannot be a source file, namespace, structure, module, procedure, or block. - -## Rules - -- **Class Inheritance.** If a class uses the `Inherits` statement, you can specify only one base class. - - A class cannot inherit from a class nested within it. - -- **Interface Inheritance.** If an interface uses the `Inherits` statement, you can specify one or more base interfaces. You can inherit from two interfaces even if they each define a member with the same name. If you do so, the implementing code must use name qualification to specify which member it is implementing. - - An interface cannot inherit from another interface with a more restrictive access level. For example, a `Public` interface cannot inherit from a `Friend` interface. - - An interface cannot inherit from an interface nested within it. - - An example of class inheritance in the .NET Framework is the class, which inherits from the class. This provides to all the predefined properties and procedures required by system exceptions, such as the property and the method. - - An example of interface inheritance in the .NET Framework is the interface, which inherits from the interface. This causes to inherit the definition of the enumerator required to traverse a collection. - +Causes the current class or interface to inherit the attributes, variables, properties, procedures, and events from another class or set of interfaces. + +## Syntax + +```vb +Inherits basetypenames +``` + +## Parts + +|Term|Definition| +|---|---| +|`basetypenames`|Required. The name of the class from which this class derives.

-or-

The names of the interfaces from which this interface derives. Use commas to separate multiple names.| + +## Remarks + + If used, the `Inherits` statement must be the first non-blank, non-comment line in a class or interface definition. It should immediately follow the `Class` or `Interface` statement. + + You can use `Inherits` only in a class or interface. This means the declaration context for an inheritance cannot be a source file, namespace, structure, module, procedure, or block. + +## Rules + +- **Class Inheritance.** If a class uses the `Inherits` statement, you can specify only one base class. + + A class cannot inherit from a class nested within it. + +- **Interface Inheritance.** If an interface uses the `Inherits` statement, you can specify one or more base interfaces. You can inherit from two interfaces even if they each define a member with the same name. If you do so, the implementing code must use name qualification to specify which member it is implementing. + + An interface cannot inherit from another interface with a more restrictive access level. For example, a `Public` interface cannot inherit from a `Friend` interface. + + An interface cannot inherit from an interface nested within it. + + An example of class inheritance in the .NET Framework is the class, which inherits from the class. This provides to all the predefined properties and procedures required by system exceptions, such as the property and the method. + + An example of interface inheritance in the .NET Framework is the interface, which inherits from the interface. This causes to inherit the definition of the enumerator required to traverse a collection. + ## Example 1 - The following example uses the `Inherits` statement to show how a class named `thisClass` can inherit all the members of a base class named `anotherClass`. - - [!code-vb[VbVbalrStatements#37](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#37)] - -## Example 2 - - The following example shows inheritance of multiple interfaces. - - [!code-vb[VbVbalrStatements#38](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#38)] - - The interface named `thisInterface` now includes all the definitions in the , , and interfaces The inherited members provide respectively for type-specific comparison of two objects, releasing allocated resources, and expressing the value of an object as a `String`. A class that implements `thisInterface` must implement every member of every base interface. - + The following example uses the `Inherits` statement to show how a class named `thisClass` can inherit all the members of a base class named `anotherClass`. + + [!code-vb[VbVbalrStatements#37](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#37)] + +## Example 2 + + The following example shows inheritance of multiple interfaces. + + [!code-vb[VbVbalrStatements#38](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#38)] + + The interface named `thisInterface` now includes all the definitions in the , , and interfaces The inherited members provide respectively for type-specific comparison of two objects, releasing allocated resources, and expressing the value of an object as a `String`. A class that implements `thisInterface` must implement every member of every base interface. + ## See also - [MustInherit](../modifiers/mustinherit.md) diff --git a/docs/visual-basic/language-reference/statements/mid-statement.md b/docs/visual-basic/language-reference/statements/mid-statement.md index 8536c8a0d6b53..311c73a5c4599 100644 --- a/docs/visual-basic/language-reference/statements/mid-statement.md +++ b/docs/visual-basic/language-reference/statements/mid-statement.md @@ -2,10 +2,10 @@ description: "Learn more about: Mid Statement" title: "Mid Statement" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.MidB" - "vb.Mid" -helpviewer_keywords: +helpviewer_keywords: - "substrings [Visual Basic], Mid statement" - "strings [Visual Basic], substrings" - "Mid statement [Visual Basic]" @@ -14,63 +14,63 @@ ms.assetid: 2b82d7a8-9646-4cb0-bec5-80abc98297bf --- # Mid Statement -Replaces a specified number of characters in a `String` variable with characters from another string. - -## Syntax - -```vb -Mid( _ - ByRef Target As String, _ - ByVal Start As Integer, _ - Optional ByVal Length As Integer _ -) = StringExpression -``` - -## Parts - - `Target` - Required. Name of the `String` variable to modify. - - `Start` - Required. `Integer` expression. Character position in `Target` where the replacement of text begins. `Start` uses a one-based index. - - `Length` - Optional. `Integer` expression. Number of characters to replace. If omitted, all of `String` is used. - - `StringExpression` - Required. `String` expression that replaces part of `Target`. - -## Exceptions - -|Exception type|Condition| -|--------------------|---------------| -||`Start` <= 0 or `Length` < 0.| - -## Remarks - - The number of characters replaced is always less than or equal to the number of characters in `Target`. - - Visual Basic has a function and a `Mid` statement. These elements both operate on a specified number of characters in a string, but the `Mid` function returns the characters while the `Mid` statement replaces the characters. For more information, see . - +Replaces a specified number of characters in a `String` variable with characters from another string. + +## Syntax + +```vb +Mid( _ + ByRef Target As String, _ + ByVal Start As Integer, _ + Optional ByVal Length As Integer _ +) = StringExpression +``` + +## Parts + + `Target` + Required. Name of the `String` variable to modify. + + `Start` + Required. `Integer` expression. Character position in `Target` where the replacement of text begins. `Start` uses a one-based index. + + `Length` + Optional. `Integer` expression. Number of characters to replace. If omitted, all of `String` is used. + + `StringExpression` + Required. `String` expression that replaces part of `Target`. + +## Exceptions + +|Exception type|Condition| +|--------------------|---------------| +||`Start` <= 0 or `Length` < 0.| + +## Remarks + + The number of characters replaced is always less than or equal to the number of characters in `Target`. + + Visual Basic has a function and a `Mid` statement. These elements both operate on a specified number of characters in a string, but the `Mid` function returns the characters while the `Mid` statement replaces the characters. For more information, see . + > [!NOTE] -> The `MidB` statement of earlier versions of Visual Basic replaces a substring in bytes, rather than characters. It is used primarily for converting strings in double-byte character set (DBCS) applications. All Visual Basic strings are in Unicode, and `MidB` is no longer supported. - -## Example - - This example uses the `Mid` statement to replace a specified number of characters in a string variable with characters from another string. - - [!code-vb[VbVbalrStrings#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class1.vb#5)] - -## Requirements - - **Namespace:** [Microsoft.VisualBasic](../runtime-library-members.md) - - **Module:** `Strings` - - **Assembly:** Visual Basic Runtime Library (in Microsoft.VisualBasic.dll) - +> The `MidB` statement of earlier versions of Visual Basic replaces a substring in bytes, rather than characters. It is used primarily for converting strings in double-byte character set (DBCS) applications. All Visual Basic strings are in Unicode, and `MidB` is no longer supported. + +## Example + + This example uses the `Mid` statement to replace a specified number of characters in a string variable with characters from another string. + + [!code-vb[VbVbalrStrings#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class1.vb#5)] + +## Requirements + + **Namespace:** [Microsoft.VisualBasic](../runtime-library-members.md) + + **Module:** `Strings` + + **Assembly:** Visual Basic Runtime Library (in Microsoft.VisualBasic.dll) + ## See also -- +- - [Strings](../../programming-guide/language-features/strings/index.md) - [Introduction to Strings in Visual Basic](../../programming-guide/language-features/strings/introduction-to-strings.md) diff --git a/docs/visual-basic/language-reference/statements/of-clause.md b/docs/visual-basic/language-reference/statements/of-clause.md index 9ce993602f9f7..09bd312102959 100644 --- a/docs/visual-basic/language-reference/statements/of-clause.md +++ b/docs/visual-basic/language-reference/statements/of-clause.md @@ -2,11 +2,11 @@ description: "Learn more about: Of Clause (Visual Basic)" title: "Of Clause" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "Of" - "vb.Of" - "vb.of" -helpviewer_keywords: +helpviewer_keywords: - "Of keyword [Visual Basic]" - "arguments [Visual Basic], data types" - "constraints, Visual Basic generic types" @@ -21,46 +21,46 @@ ms.assetid: 0db8f65c-65af-4089-ab7f-6fcfecb60444 --- # Of Clause (Visual Basic) -Introduces an `Of` clause, which identifies a *type parameter* on a *generic* class, structure, interface, delegate, or procedure. For information on generic types, see [Generic Types in Visual Basic](../../programming-guide/language-features/data-types/generic-types.md). - -## Using the Of Keyword - - The following code example uses the `Of` keyword to define the outline of a class that takes two type parameters. It *constrains* the `keyType` parameter by the interface, which means the consuming code must supply a type argument that implements . This is necessary so that the `add` procedure can call the method. For more information on constraints, see [Type List](type-list.md). - -```vb -Public Class Dictionary(Of entryType, keyType As IComparable) - Public Sub add(ByVal e As entryType, ByVal k As keyType) - Dim dk As keyType - If k.CompareTo(dk) = 0 Then - End If - End Sub - Public Function find(ByVal k As keyType) As entryType - End Function -End Class -``` - - If you complete the preceding class definition, you can construct a variety of `dictionary` classes from it. The types you supply to `entryType` and `keyType` determine what type of entry the class holds and what type of key it associates with each entry. Because of the constraint, you must supply to `keyType` a type that implements . - - The following code example creates an object that holds `String` entries and associates an `Integer` key with each one. `Integer` implements and therefore satisfies the constraint on `keyType`. - -```vb -Dim d As New dictionary(Of String, Integer) -``` - - The `Of` keyword can be used in these contexts: - - [Class Statement](class-statement.md) - - [Delegate Statement](delegate-statement.md) - - [Function Statement](function-statement.md) - - [Interface Statement](interface-statement.md) - - [Structure Statement](structure-statement.md) - - [Sub Statement](sub-statement.md) - +Introduces an `Of` clause, which identifies a *type parameter* on a *generic* class, structure, interface, delegate, or procedure. For information on generic types, see [Generic Types in Visual Basic](../../programming-guide/language-features/data-types/generic-types.md). + +## Using the Of Keyword + + The following code example uses the `Of` keyword to define the outline of a class that takes two type parameters. It *constrains* the `keyType` parameter by the interface, which means the consuming code must supply a type argument that implements . This is necessary so that the `add` procedure can call the method. For more information on constraints, see [Type List](type-list.md). + +```vb +Public Class Dictionary(Of entryType, keyType As IComparable) + Public Sub add(ByVal e As entryType, ByVal k As keyType) + Dim dk As keyType + If k.CompareTo(dk) = 0 Then + End If + End Sub + Public Function find(ByVal k As keyType) As entryType + End Function +End Class +``` + + If you complete the preceding class definition, you can construct a variety of `dictionary` classes from it. The types you supply to `entryType` and `keyType` determine what type of entry the class holds and what type of key it associates with each entry. Because of the constraint, you must supply to `keyType` a type that implements . + + The following code example creates an object that holds `String` entries and associates an `Integer` key with each one. `Integer` implements and therefore satisfies the constraint on `keyType`. + +```vb +Dim d As New dictionary(Of String, Integer) +``` + + The `Of` keyword can be used in these contexts: + + [Class Statement](class-statement.md) + + [Delegate Statement](delegate-statement.md) + + [Function Statement](function-statement.md) + + [Interface Statement](interface-statement.md) + + [Structure Statement](structure-statement.md) + + [Sub Statement](sub-statement.md) + ## See also - diff --git a/docs/visual-basic/language-reference/statements/on-error-statement.md b/docs/visual-basic/language-reference/statements/on-error-statement.md index 9157141eaf0fb..e5166efad7b69 100644 --- a/docs/visual-basic/language-reference/statements/on-error-statement.md +++ b/docs/visual-basic/language-reference/statements/on-error-statement.md @@ -2,9 +2,9 @@ description: "Learn more about: On Error Statement (Visual Basic)" title: "On Error Statement" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.OnError" -helpviewer_keywords: +helpviewer_keywords: - "Visual Basic code, control flow" - "Resume Next statement [Visual Basic]" - "errors [Visual Basic], trapping" @@ -56,30 +56,30 @@ On Error { GoTo [ line | 0 | -1 ] | Resume Next } An "enabled" error handler is one that is turned on by an `On Error` statement. An "active" error handler is an enabled handler that is in the process of handling an error. If an error occurs while an error handler is active (between the occurrence of the error and a `Resume`, `Exit Sub`, `Exit Function`, or `Exit Property` statement), the current procedure's error handler cannot handle the error. Control returns to the calling procedure. - + If the calling procedure has an enabled error handler, it is activated to handle the error. If the calling procedure's error handler is also active, control passes back through previous calling procedures until an enabled, but inactive, error handler is found. If no such error handler is found, the error is fatal at the point at which it actually occurred. - + Each time the error handler passes control back to a calling procedure, that procedure becomes the current procedure. Once an error is handled by an error handler in any procedure, execution resumes in the current procedure at the point designated by the `Resume` statement. - + > [!NOTE] > An error-handling routine is not a `Sub` procedure or a `Function` procedure. It is a section of code marked by a line label or a line number. - + ## Number Property - Error-handling routines rely on the value in the `Number` property of the `Err` object to determine the cause of the error. The routine should test or save relevant property values in the `Err` object before any other error can occur or before a procedure that might cause an error is called. The property values in the `Err` object reflect only the most recent error. The error message associated with `Err.Number` is contained in `Err.Description`. - -## Throw Statement + Error-handling routines rely on the value in the `Number` property of the `Err` object to determine the cause of the error. The routine should test or save relevant property values in the `Err` object before any other error can occur or before a procedure that might cause an error is called. The property values in the `Err` object reflect only the most recent error. The error message associated with `Err.Number` is contained in `Err.Description`. + +## Throw Statement An error that is raised with the `Err.Raise` method sets the `Exception` property to a newly created instance of the class. In order to support the raising of exceptions of derived exception types, a `Throw` statement is supported in the language. This takes a single parameter that is the exception instance to be thrown. The following example shows how these features can be used with the existing exception handling support: - [!code-vb[VbVbalrErrorHandling#17](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrErrorHandling/VB/Class1.vb#17)] - + [!code-vb[VbVbalrErrorHandling#17](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrErrorHandling/VB/Class1.vb#17)] + Notice that the `On Error GoTo` statement traps all errors, regardless of the exception class. - + ## On Error Resume Next `On Error Resume Next` causes execution to continue with the statement immediately following the statement that caused the run-time error, or with the statement immediately following the most recent call out of the procedure containing the `On Error Resume Next` statement. This statement allows execution to continue despite a run-time error. You can place the error-handling routine where the error would occur rather than transferring control to another location within the procedure. An `On Error Resume Next` statement becomes inactive when another procedure is called, so you should execute an `On Error Resume Next` statement in each called routine if you want inline error handling within that routine. - + > [!NOTE] > The `On Error Resume Next` construct may be preferable to `On Error GoTo` when handling errors generated during access to other objects. Checking `Err` after each interaction with an object removes ambiguity about which object was accessed by the code. You can be sure which object placed the error code in `Err.Number`, as well as which object originally generated the error (the object specified in `Err.Source`). @@ -122,10 +122,10 @@ On Error { GoTo [ line | 0 | -1 ] | Resume Next } ## See also -- -- -- -- +- +- +- +- - [End Statement](end-statement.md) - [Exit Statement](exit-statement.md) - [Resume Statement](resume-statement.md) diff --git a/docs/visual-basic/language-reference/statements/option-compare-statement.md b/docs/visual-basic/language-reference/statements/option-compare-statement.md index 31491b539607c..7afbb5e48a99f 100644 --- a/docs/visual-basic/language-reference/statements/option-compare-statement.md +++ b/docs/visual-basic/language-reference/statements/option-compare-statement.md @@ -2,10 +2,10 @@ description: "Learn more about: Option Compare Statement" title: "Option Compare Statement" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.Compare" - "vb.OptionCompare" -helpviewer_keywords: +helpviewer_keywords: - "case sensitivity, Option Compare statement" - "Compare keyword [Visual Basic]" - "binary comparison [Visual Basic]" @@ -22,78 +22,78 @@ ms.assetid: 54e8eeeb-3b0d-4fb9-acce-fbfbd5975f6e --- # Option Compare Statement -Declares the default comparison method to use when comparing string data. - -## Syntax - -```vb -Option Compare { Binary | Text } -``` - -## Parts - -|Term|Definition| -|---|---| -|`Binary`|Optional. Results in string comparisons based on a sort order derived from the internal binary representations of the characters.

This type of comparison is useful especially if the strings can contain characters that are not to be interpreted as text. In this case, you do not want to bias comparisons with alphabetical equivalences, such as case insensitivity.| -|`Text`|Optional. Results in string comparisons based on a case-insensitive text sort order determined by your system's locale.

This type of comparison is useful if your strings contain all text characters, and you want to compare them taking into account alphabetic equivalences such as case insensitivity and closely related letters. For example, you might want to consider `A` and `a` to be equal, and `Ä` and `ä` to come before `B` and `b`.| - -## Remarks - - If used, the `Option Compare` statement must appear in a file before any other source code statements. - - The `Option Compare` statement specifies the string comparison method (`Binary` or `Text`). The default text comparison method is `Binary`. - - A `Binary` comparison compares the numeric Unicode value of each character in each string. A `Text` comparison compares each Unicode character based on its lexical meaning in the current culture. - - In Microsoft Windows, sort order is determined by the code page. For more information, see [Code Pages](/cpp/c-runtime-library/code-pages). - - In the following example, characters in the English/European code page (ANSI 1252) are sorted by using `Option Compare Binary`, which produces a typical binary sort order. - - `A < B < E < Z < a < b < e < z < À < Ê < Ø < à < ê < ø` - - When the same characters in the same code page are sorted by using `Option Compare Text`, the following text sort order is produced. - - `(A=a) < (À = à) < (B=b) < (E=e) < (Ê = ê) < (Z=z) < (Ø = ø)` - -## When an Option Compare Statement Is Not Present - - If the source code does not contain an `Option Compare` statement, the **Option Compare** setting on the [Compile Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/compile-page-project-designer-visual-basic) is used. If you use the command-line compiler, the setting specified by the [-optioncompare](../../reference/command-line-compiler/optioncompare.md) compiler option is used. - -[!INCLUDE[note_settings_general](~/includes/note-settings-general-md.md)] - -#### To set Option Compare in the IDE - -1. In **Solution Explorer**, select a project. On the **Project** menu, click **Properties**. - -2. Click the **Compile** tab. - -3. Set the value in the **Option Compare** box. - - When you create a project, the **Option Compare** setting on the **Compile** tab is set to the **Option Compare** setting in the **Options** dialog box. To change this setting, on the **Tools** menu, click **Options**. In the **Options** dialog box, expand **Projects and Solutions**, and then click **VB Defaults**. The initial default setting in **VB Defaults** is **Binary**. - -#### To set Option Compare on the command line - -- Include the [-optioncompare](../../reference/command-line-compiler/optioncompare.md) compiler option in the **vbc** command. - +Declares the default comparison method to use when comparing string data. + +## Syntax + +```vb +Option Compare { Binary | Text } +``` + +## Parts + +|Term|Definition| +|---|---| +|`Binary`|Optional. Results in string comparisons based on a sort order derived from the internal binary representations of the characters.

This type of comparison is useful especially if the strings can contain characters that are not to be interpreted as text. In this case, you do not want to bias comparisons with alphabetical equivalences, such as case insensitivity.| +|`Text`|Optional. Results in string comparisons based on a case-insensitive text sort order determined by your system's locale.

This type of comparison is useful if your strings contain all text characters, and you want to compare them taking into account alphabetic equivalences such as case insensitivity and closely related letters. For example, you might want to consider `A` and `a` to be equal, and `Ä` and `ä` to come before `B` and `b`.| + +## Remarks + + If used, the `Option Compare` statement must appear in a file before any other source code statements. + + The `Option Compare` statement specifies the string comparison method (`Binary` or `Text`). The default text comparison method is `Binary`. + + A `Binary` comparison compares the numeric Unicode value of each character in each string. A `Text` comparison compares each Unicode character based on its lexical meaning in the current culture. + + In Microsoft Windows, sort order is determined by the code page. For more information, see [Code Pages](/cpp/c-runtime-library/code-pages). + + In the following example, characters in the English/European code page (ANSI 1252) are sorted by using `Option Compare Binary`, which produces a typical binary sort order. + + `A < B < E < Z < a < b < e < z < À < Ê < Ø < à < ê < ø` + + When the same characters in the same code page are sorted by using `Option Compare Text`, the following text sort order is produced. + + `(A=a) < (À = à) < (B=b) < (E=e) < (Ê = ê) < (Z=z) < (Ø = ø)` + +## When an Option Compare Statement Is Not Present + + If the source code does not contain an `Option Compare` statement, the **Option Compare** setting on the [Compile Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/compile-page-project-designer-visual-basic) is used. If you use the command-line compiler, the setting specified by the [-optioncompare](../../reference/command-line-compiler/optioncompare.md) compiler option is used. + +[!INCLUDE[note_settings_general](~/includes/note-settings-general-md.md)] + +#### To set Option Compare in the IDE + +1. In **Solution Explorer**, select a project. On the **Project** menu, click **Properties**. + +2. Click the **Compile** tab. + +3. Set the value in the **Option Compare** box. + + When you create a project, the **Option Compare** setting on the **Compile** tab is set to the **Option Compare** setting in the **Options** dialog box. To change this setting, on the **Tools** menu, click **Options**. In the **Options** dialog box, expand **Projects and Solutions**, and then click **VB Defaults**. The initial default setting in **VB Defaults** is **Binary**. + +#### To set Option Compare on the command line + +- Include the [-optioncompare](../../reference/command-line-compiler/optioncompare.md) compiler option in the **vbc** command. + ## Example 1 - The following example uses the `Option Compare` statement to set the binary comparison as the default string comparison method. To use this code, uncomment the `Option Compare Binary` statement, and put it at the top of the source file. - - [!code-vb[VbVbalrStatements#45](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#45)] - -## Example 2 + The following example uses the `Option Compare` statement to set the binary comparison as the default string comparison method. To use this code, uncomment the `Option Compare Binary` statement, and put it at the top of the source file. + + [!code-vb[VbVbalrStatements#45](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#45)] + +## Example 2 + + The following example uses the `Option Compare` statement to set the case-insensitive text sort order as the default string comparison method. To use this code, uncomment the `Option Compare Text` statement, and put it at the top of the source file. + + [!code-vb[VbVbalrStatements#46](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#46)] - The following example uses the `Option Compare` statement to set the case-insensitive text sort order as the default string comparison method. To use this code, uncomment the `Option Compare Text` statement, and put it at the top of the source file. - - [!code-vb[VbVbalrStatements#46](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#46)] - ## See also -- -- -- -- -- +- +- +- +- +- - [-optioncompare](../../reference/command-line-compiler/optioncompare.md) - [Comparison Operators](../operators/comparison-operators.md) - [Comparison Operators in Visual Basic](../../programming-guide/language-features/operators-and-expressions/comparison-operators.md) diff --git a/docs/visual-basic/language-reference/statements/raiseevent-statement.md b/docs/visual-basic/language-reference/statements/raiseevent-statement.md index a84f9af896120..bf3e404ecb4b6 100644 --- a/docs/visual-basic/language-reference/statements/raiseevent-statement.md +++ b/docs/visual-basic/language-reference/statements/raiseevent-statement.md @@ -2,11 +2,11 @@ description: "Learn more about: RaiseEvent Statement" title: "RaiseEvent Statement" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.RaiseEventMethod" - "vb.RaiseEvent" - "RaiseEvent" -helpviewer_keywords: +helpviewer_keywords: - "raising events [Visual Basic], RaiseEvent statement" - "RaiseEvent statement [Visual Basic]" - "event handlers, connecting events to" @@ -14,60 +14,60 @@ ms.assetid: f82e380a-1e6b-4047-bea8-c853f4d2c742 --- # RaiseEvent Statement -Triggers an event declared at module level within a class, form, or document. - -## Syntax - -```vb -RaiseEvent eventname[( argumentlist )] -``` - -## Parts - - `eventname` - Required. Name of the event to trigger. - - `argumentlist` - Optional. Comma-delimited list of variables, arrays, or expressions. The `argumentlist` argument must be enclosed by parentheses. If there are no arguments, the parentheses must be omitted. - -## Remarks - - The required `eventname` is the name of an event declared within the module. It follows Visual Basic variable naming conventions. - - If the event has not been declared within the module in which it is raised, an error occurs. The following code fragment illustrates an event declaration and a procedure in which the event is raised. - - [!code-vb[VbVbalrEvents#37](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrEvents/VB/Class1.vb#37)] - - You cannot use `RaiseEvent` to raise events that are not explicitly declared in the module. For example, all forms inherit a event from , it cannot be raised using `RaiseEvent` in a derived form. If you declare a `Click` event in the form module, it shadows the form's own event. You can still invoke the form's event by calling the method. - - By default, an event defined in Visual Basic raises its event handlers in the order that the connections are established. Because events can have `ByRef` parameters, a process that connects late may receive parameters that have been changed by an earlier event handler. After the event handlers execute, control is returned to the subroutine that raised the event. - +Triggers an event declared at module level within a class, form, or document. + +## Syntax + +```vb +RaiseEvent eventname[( argumentlist )] +``` + +## Parts + + `eventname` + Required. Name of the event to trigger. + + `argumentlist` + Optional. Comma-delimited list of variables, arrays, or expressions. The `argumentlist` argument must be enclosed by parentheses. If there are no arguments, the parentheses must be omitted. + +## Remarks + + The required `eventname` is the name of an event declared within the module. It follows Visual Basic variable naming conventions. + + If the event has not been declared within the module in which it is raised, an error occurs. The following code fragment illustrates an event declaration and a procedure in which the event is raised. + + [!code-vb[VbVbalrEvents#37](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrEvents/VB/Class1.vb#37)] + + You cannot use `RaiseEvent` to raise events that are not explicitly declared in the module. For example, all forms inherit a event from , it cannot be raised using `RaiseEvent` in a derived form. If you declare a `Click` event in the form module, it shadows the form's own event. You can still invoke the form's event by calling the method. + + By default, an event defined in Visual Basic raises its event handlers in the order that the connections are established. Because events can have `ByRef` parameters, a process that connects late may receive parameters that have been changed by an earlier event handler. After the event handlers execute, control is returned to the subroutine that raised the event. + > [!NOTE] -> Non-shared events should not be raised within the constructor of the class in which they are declared. Although such events do not cause run-time errors, they may fail to be caught by associated event handlers. Use the `Shared` modifier to create a shared event if you need to raise an event from a constructor. - +> Non-shared events should not be raised within the constructor of the class in which they are declared. Although such events do not cause run-time errors, they may fail to be caught by associated event handlers. Use the `Shared` modifier to create a shared event if you need to raise an event from a constructor. + > [!NOTE] -> You can change the default behavior of events by defining a custom event. For custom events, the `RaiseEvent` statement invokes the event's `RaiseEvent` accessor. For more information on custom events, see [Event Statement](event-statement.md). - +> You can change the default behavior of events by defining a custom event. For custom events, the `RaiseEvent` statement invokes the event's `RaiseEvent` accessor. For more information on custom events, see [Event Statement](event-statement.md). + ## Example 1 - The following example uses events to count down seconds from 10 to 0. The code illustrates several of the event-related methods, properties, and statements, including the `RaiseEvent` statement. - - The class that raises an event is the event source, and the methods that process the event are the event handlers. An event source can have multiple handlers for the events it generates. When the class raises the event, that event is raised on every class that has elected to handle events for that instance of the object. - - The example demonstrates a timer that counts down from 10 to 0 seconds and displays the progress to the console. When the countdown finishes, it displays "Done". - - Declare a `WithEvents` variable in your class to handle events from the timer: - - [!code-vb[VbVbalrEvents#14](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrEvents/VB/Class1.vb#14)] - -## Example 2 - - Add the following code to implement the event handlers and timer logic. This example shows how to use the `RaiseEvent` statement to notify event handlers when the timer updates or completes. - - [!code-vb[VbVbalrEvents#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrEvents/VB/Class1.vb#15)] - - When you run the preceding example, it starts counting down the seconds from 10 to 0, displaying the progress to the console. When the full time (10 seconds) has elapsed, it displays "Done". - + The following example uses events to count down seconds from 10 to 0. The code illustrates several of the event-related methods, properties, and statements, including the `RaiseEvent` statement. + + The class that raises an event is the event source, and the methods that process the event are the event handlers. An event source can have multiple handlers for the events it generates. When the class raises the event, that event is raised on every class that has elected to handle events for that instance of the object. + + The example demonstrates a timer that counts down from 10 to 0 seconds and displays the progress to the console. When the countdown finishes, it displays "Done". + + Declare a `WithEvents` variable in your class to handle events from the timer: + + [!code-vb[VbVbalrEvents#14](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrEvents/VB/Class1.vb#14)] + +## Example 2 + + Add the following code to implement the event handlers and timer logic. This example shows how to use the `RaiseEvent` statement to notify event handlers when the timer updates or completes. + + [!code-vb[VbVbalrEvents#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrEvents/VB/Class1.vb#15)] + + When you run the preceding example, it starts counting down the seconds from 10 to 0, displaying the progress to the console. When the full time (10 seconds) has elapsed, it displays "Done". + ## See also - [Events](../../programming-guide/language-features/events/index.md) diff --git a/docs/visual-basic/language-reference/statements/select-case-statement.md b/docs/visual-basic/language-reference/statements/select-case-statement.md index fefa92e0a058a..4252efb4fa54f 100644 --- a/docs/visual-basic/language-reference/statements/select-case-statement.md +++ b/docs/visual-basic/language-reference/statements/select-case-statement.md @@ -2,10 +2,10 @@ description: "Learn more about: Select...Case Statement (Visual Basic)" title: "Select...Case Statement" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.Select" - "vb.Case" -helpviewer_keywords: +helpviewer_keywords: - "Select statement [Visual Basic]" - "Case statement [Visual Basic]" - "Select...Case statements" @@ -25,64 +25,64 @@ ms.assetid: 68877b65-5419-4bf0-a465-20cd0e4c7d44 --- # Select...Case Statement (Visual Basic) -Runs one of several groups of statements, depending on the value of an expression. - -## Syntax - -```vb -Select [ Case ] testexpression - [ Case expressionlist - [ statements ] ] - [ Case Else - [ elsestatements ] ] -End Select -``` - -## Parts - -|Term|Definition| -|---|---| -|`testexpression`|Required. Expression. Must evaluate to one of the elementary data types (`Boolean`, `Byte`, `Char`, `Date`, `Double`, `Decimal`, `Integer`, `Long`, `Object`, `SByte`, `Short`, `Single`, `String`, `UInteger`, `ULong`, and `UShort`).| -|`expressionlist`|Required in a `Case` statement. List of expression clauses representing match values for `testexpression`. Multiple expression clauses are separated by commas. Each clause can take one of the following forms:

- *expression1* `To` *expression2*
- [ `Is` ] *comparisonoperator* *expression*
- *expression*

Use the `To` keyword to specify the boundaries of a range of match values for `testexpression`. The value of `expression1` must be less than or equal to the value of `expression2`.

Use the `Is` keyword with a comparison operator (`=`, `<>`, `<`, `<=`, `>`, or `>=`) to specify a restriction on the match values for `testexpression`. If the `Is` keyword is not supplied, it is automatically inserted before *comparisonoperator*.

The form specifying only `expression` is treated as a special case of the `Is` form where *comparisonoperator* is the equal sign (`=`). This form is evaluated as `testexpression` = `expression`.

The expressions in `expressionlist` can be of any data type, provided they are implicitly convertible to the type of `testexpression` and the appropriate `comparisonoperator` is valid for the two types it is being used with.| -|`statements`|Optional. One or more statements following `Case` that run if `testexpression` matches any clause in `expressionlist`.| -|`elsestatements`|Optional. One or more statements following `Case Else` that run if `testexpression` does not match any clause in the `expressionlist` of any of the `Case` statements.| -|`End Select`|Terminates the definition of the `Select`...`Case` construction.| - -## Remarks - - If `testexpression` matches any `Case` `expressionlist` clause, the statements following that `Case` statement run up to the next `Case`, `Case Else`, or `End Select` statement. Control then passes to the statement following `End Select`. If `testexpression` matches an `expressionlist` clause in more than one `Case` clause, only the statements following the first match run. - - The `Case Else` statement is used to introduce the `elsestatements` to run if no match is found between the `testexpression` and an `expressionlist` clause in any of the other `Case` statements. Although not required, it is a good idea to have a `Case Else` statement in your `Select Case` construction to handle unforeseen `testexpression` values. If no `Case` `expressionlist` clause matches `testexpression` and there is no `Case Else` statement, control passes to the statement following `End Select`. - - You can use multiple expressions or ranges in each `Case` clause. For example, the following line is valid. - - `Case 1 To 4, 7 To 9, 11, 13, Is > maxNumber` - +Runs one of several groups of statements, depending on the value of an expression. + +## Syntax + +```vb +Select [ Case ] testexpression + [ Case expressionlist + [ statements ] ] + [ Case Else + [ elsestatements ] ] +End Select +``` + +## Parts + +|Term|Definition| +|---|---| +|`testexpression`|Required. Expression. Must evaluate to one of the elementary data types (`Boolean`, `Byte`, `Char`, `Date`, `Double`, `Decimal`, `Integer`, `Long`, `Object`, `SByte`, `Short`, `Single`, `String`, `UInteger`, `ULong`, and `UShort`).| +|`expressionlist`|Required in a `Case` statement. List of expression clauses representing match values for `testexpression`. Multiple expression clauses are separated by commas. Each clause can take one of the following forms:

- *expression1* `To` *expression2*
- [ `Is` ] *comparisonoperator* *expression*
- *expression*

Use the `To` keyword to specify the boundaries of a range of match values for `testexpression`. The value of `expression1` must be less than or equal to the value of `expression2`.

Use the `Is` keyword with a comparison operator (`=`, `<>`, `<`, `<=`, `>`, or `>=`) to specify a restriction on the match values for `testexpression`. If the `Is` keyword is not supplied, it is automatically inserted before *comparisonoperator*.

The form specifying only `expression` is treated as a special case of the `Is` form where *comparisonoperator* is the equal sign (`=`). This form is evaluated as `testexpression` = `expression`.

The expressions in `expressionlist` can be of any data type, provided they are implicitly convertible to the type of `testexpression` and the appropriate `comparisonoperator` is valid for the two types it is being used with.| +|`statements`|Optional. One or more statements following `Case` that run if `testexpression` matches any clause in `expressionlist`.| +|`elsestatements`|Optional. One or more statements following `Case Else` that run if `testexpression` does not match any clause in the `expressionlist` of any of the `Case` statements.| +|`End Select`|Terminates the definition of the `Select`...`Case` construction.| + +## Remarks + + If `testexpression` matches any `Case` `expressionlist` clause, the statements following that `Case` statement run up to the next `Case`, `Case Else`, or `End Select` statement. Control then passes to the statement following `End Select`. If `testexpression` matches an `expressionlist` clause in more than one `Case` clause, only the statements following the first match run. + + The `Case Else` statement is used to introduce the `elsestatements` to run if no match is found between the `testexpression` and an `expressionlist` clause in any of the other `Case` statements. Although not required, it is a good idea to have a `Case Else` statement in your `Select Case` construction to handle unforeseen `testexpression` values. If no `Case` `expressionlist` clause matches `testexpression` and there is no `Case Else` statement, control passes to the statement following `End Select`. + + You can use multiple expressions or ranges in each `Case` clause. For example, the following line is valid. + + `Case 1 To 4, 7 To 9, 11, 13, Is > maxNumber` + > [!NOTE] -> The `Is` keyword used in the `Case` and `Case Else` statements is not the same as the [Is Operator](../operators/is-operator.md), which is used for object reference comparison. - - You can specify ranges and multiple expressions for character strings. In the following example, `Case` matches any string that is exactly equal to "apples", has a value between "nuts" and "soup" in alphabetical order, or contains the exact same value as the current value of `testItem`. - - `Case "apples", "nuts" To "soup", testItem` - - The setting of `Option Compare` can affect string comparisons. Under `Option Compare Text`, the strings "Apples" and "apples" compare as equal, but under `Option Compare Binary`, they do not. - +> The `Is` keyword used in the `Case` and `Case Else` statements is not the same as the [Is Operator](../operators/is-operator.md), which is used for object reference comparison. + + You can specify ranges and multiple expressions for character strings. In the following example, `Case` matches any string that is exactly equal to "apples", has a value between "nuts" and "soup" in alphabetical order, or contains the exact same value as the current value of `testItem`. + + `Case "apples", "nuts" To "soup", testItem` + + The setting of `Option Compare` can affect string comparisons. Under `Option Compare Text`, the strings "Apples" and "apples" compare as equal, but under `Option Compare Binary`, they do not. + > [!NOTE] -> A `Case` statement with multiple clauses can exhibit behavior known as *short-circuiting*. Visual Basic evaluates the clauses from left to right, and if one produces a match with `testexpression`, the remaining clauses are not evaluated. Short-circuiting can improve performance, but it can produce unexpected results if you are expecting every expression in `expressionlist` to be evaluated. For more information on short-circuiting, see [Boolean Expressions](../../programming-guide/language-features/operators-and-expressions/boolean-expressions.md). - - If the code within a `Case` or `Case Else` statement block does not need to run any more of the statements in the block, it can exit the block by using the `Exit Select` statement. This transfers control immediately to the statement following `End Select`. - - `Select Case` constructions can be nested. Each nested `Select Case` construction must have a matching `End Select` statement and must be completely contained within a single `Case` or `Case Else` statement block of the outer `Select Case` construction within which it is nested. - -## Example - - The following example uses a `Select Case` construction to write a line corresponding to the value of the variable `number`. The second `Case` statement contains the value that matches the current value of `number`, so the statement that writes "Between 6 and 8, inclusive" runs. - - [!code-vb[VbVbalrStatements#54](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#54)] - +> A `Case` statement with multiple clauses can exhibit behavior known as *short-circuiting*. Visual Basic evaluates the clauses from left to right, and if one produces a match with `testexpression`, the remaining clauses are not evaluated. Short-circuiting can improve performance, but it can produce unexpected results if you are expecting every expression in `expressionlist` to be evaluated. For more information on short-circuiting, see [Boolean Expressions](../../programming-guide/language-features/operators-and-expressions/boolean-expressions.md). + + If the code within a `Case` or `Case Else` statement block does not need to run any more of the statements in the block, it can exit the block by using the `Exit Select` statement. This transfers control immediately to the statement following `End Select`. + + `Select Case` constructions can be nested. Each nested `Select Case` construction must have a matching `End Select` statement and must be completely contained within a single `Case` or `Case Else` statement block of the outer `Select Case` construction within which it is nested. + +## Example + + The following example uses a `Select Case` construction to write a line corresponding to the value of the variable `number`. The second `Case` statement contains the value that matches the current value of `number`, so the statement that writes "Between 6 and 8, inclusive" runs. + + [!code-vb[VbVbalrStatements#54](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#54)] + ## See also -- +- - [End Statement](end-statement.md) - [If...Then...Else Statement](if-then-else-statement.md) - [Option Compare Statement](option-compare-statement.md) diff --git a/docs/visual-basic/language-reference/statements/sub-statement.md b/docs/visual-basic/language-reference/statements/sub-statement.md index 7f6d86c755a2c..3709e26dbd7f6 100644 --- a/docs/visual-basic/language-reference/statements/sub-statement.md +++ b/docs/visual-basic/language-reference/statements/sub-statement.md @@ -207,7 +207,7 @@ If you mark a procedure with the [Async](../modifiers/async.md) modifier, you ca > [!NOTE] > An `Async` procedure returns to the caller when either the first awaited object that’s not yet complete is encountered or the end of the `Async` procedure is reached, whichever occurs first. -You can also mark a [Function Statement](function-statement.md) with the `Async` modifier. An `Async` function can have a return type of or . An example later in this topic shows an `Async` function that has a return type of . +You can also mark a [Function Statement](function-statement.md) with the `Async` modifier. An `Async` function can have a return type of or . An example later in this topic shows an `Async` function that has a return type of . `Async` `Sub` procedures are primarily used for event handlers, where a value can't be returned. An `Async` `Sub` procedure can't be awaited, and the caller of an `Async` `Sub` procedure can't catch exceptions that the `Sub` procedure throws. @@ -223,7 +223,7 @@ The following example uses the `Sub` statement to define the name, parameters, a ## Example 2 -In the following example, `DelayAsync` is an `Async` `Function` that has a return type of . `DelayAsync` has a `Return` statement that returns an integer. Therefore, the function declaration of `DelayAsync` must have a return type of `Task(Of Integer)`. Because the return type is `Task(Of Integer)`, the evaluation of the `Await` expression in `DoSomethingAsync` produces an integer, as the following statement shows: `Dim result As Integer = Await delayTask`. +In the following example, `DelayAsync` is an `Async` `Function` that has a return type of . `DelayAsync` has a `Return` statement that returns an integer. Therefore, the function declaration of `DelayAsync` must have a return type of `Task(Of Integer)`. Because the return type is `Task(Of Integer)`, the evaluation of the `Await` expression in `DoSomethingAsync` produces an integer, as the following statement shows: `Dim result As Integer = Await delayTask`. The `startButton_Click` procedure is an example of an `Async Sub` procedure. Because `DoSomethingAsync` is an `Async` function, the task for the call to `DoSomethingAsync` must be awaited, as the following statement shows: `Await DoSomethingAsync()`. The `startButton_Click` `Sub` procedure must be defined with the `Async` modifier because it has an `Await` expression. diff --git a/docs/visual-basic/language-reference/statements/throw-statement.md b/docs/visual-basic/language-reference/statements/throw-statement.md index e6358d6ce0063..751f140fe1276 100644 --- a/docs/visual-basic/language-reference/statements/throw-statement.md +++ b/docs/visual-basic/language-reference/statements/throw-statement.md @@ -37,7 +37,7 @@ The `Throw` statement throws an exception that you can handle with structured ex A `Throw` statement with no expression can only be used in a `Catch` statement, in which case the statement rethrows the exception currently being handled by the `Catch` statement. -The `Throw` statement resets the call stack for the `expression` exception. If `expression` is not provided, the call stack is left unchanged. You can access the call stack for the exception through the property. +The `Throw` statement resets the call stack for the `expression` exception. If `expression` is not provided, the call stack is left unchanged. You can access the call stack for the exception through the property. ## Example diff --git a/docs/visual-basic/language-reference/statements/try-catch-finally-statement.md b/docs/visual-basic/language-reference/statements/try-catch-finally-statement.md index 3f9cd37901db9..27d5dcadc0e9d 100644 --- a/docs/visual-basic/language-reference/statements/try-catch-finally-statement.md +++ b/docs/visual-basic/language-reference/statements/try-catch-finally-statement.md @@ -101,7 +101,7 @@ If a `Try` statement does not contain at least one `Catch` block, it must contai The `Catch` block `exception` argument is an instance of the class or a class that derives from the `Exception` class. The `Exception` class instance corresponds to the error that occurred in the `Try` block. -The properties of the `Exception` object help to identify the cause and location of an exception. For example, the property lists the called methods that led to the exception, helping you find where the error occurred in the code. returns a message that describes the exception. returns a link to an associated Help file. returns the `Exception` object that caused the current exception, or it returns `Nothing` if there is no original `Exception`. +The properties of the `Exception` object help to identify the cause and location of an exception. For example, the property lists the called methods that led to the exception, helping you find where the error occurred in the code. returns a message that describes the exception. returns a link to an associated Help file. returns the `Exception` object that caused the current exception, or it returns `Nothing` if there is no original `Exception`. ## Considerations when using a `Try…Catch` statement @@ -113,7 +113,7 @@ Use a `Try…Catch` statement only to signal the occurrence of unusual or unanti - Exception handling makes a program more complex. -You do not always need a `Try…Catch` statement to check for a condition that is likely to occur. The following example checks whether a file exists before trying to open it. This reduces the need for catching an exception thrown by the method. +You do not always need a `Try…Catch` statement to check for a condition that is likely to occur. The following example checks whether a file exists before trying to open it. This reduces the need for catching an exception thrown by the method. [!code-vb[VbVbalrStatements#94](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#94)] @@ -125,7 +125,7 @@ If you mark a method with the [Async](../modifiers/async.md) modifier, you can u A task returned by an Async method may end in a faulted state, indicating that it completed due to an unhandled exception. A task may also end in a canceled state, which results in an `OperationCanceledException` being thrown out of the await expression. To catch either type of exception, place the `Await` expression that's associated with the task in a `Try` block, and catch the exception in the `Catch` block. An example is provided later in this topic. -A task can be in a faulted state because multiple exceptions were responsible for its faulting. For example, the task might be the result of a call to . When you await such a task, the caught exception is only one of the exceptions, and you can't predict which exception will be caught. An example is provided later in this topic. +A task can be in a faulted state because multiple exceptions were responsible for its faulting. For example, the task might be the result of a call to . When you await such a task, the caught exception is only one of the exceptions, and you can't predict which exception will be caught. An example is provided later in this topic. An `Await` expression can't be inside a `Catch` block or `Finally` block. @@ -187,7 +187,7 @@ Uncomment the `Throw New OperationCancelledException` line to demonstrate what h ### Handling multiple exceptions in async methods -The following example illustrates exception handling where multiple tasks can result in multiple exceptions. The `Try` block has the `Await` expression for the task that returned. The task is complete when the three tasks to which is applied are complete. +The following example illustrates exception handling where multiple tasks can result in multiple exceptions. The `Try` block has the `Await` expression for the task that returned. The task is complete when the three tasks to which is applied are complete. Each of the three tasks causes an exception. The `Catch` block iterates through the exceptions, which are found in the `Exception.InnerExceptions` property of the task that `Task.WhenAll` returned. @@ -195,7 +195,7 @@ Each of the three tasks causes an exception. The `Catch` block iterates through ## See also -- +- - - [Exit Statement](exit-statement.md) - [On Error Statement](on-error-statement.md) diff --git a/docs/visual-basic/language-reference/statements/using-statement.md b/docs/visual-basic/language-reference/statements/using-statement.md index f63190fb5ed29..433a62139c348 100644 --- a/docs/visual-basic/language-reference/statements/using-statement.md +++ b/docs/visual-basic/language-reference/statements/using-statement.md @@ -25,12 +25,12 @@ End Using ## Parts -|Term|Definition| -|---|---| -|`resourcelist`|Required if you do not supply `resourceexpression`. List of one or more system resources that this `Using` block controls, separated by commas.| -|`resourceexpression`|Required if you do not supply `resourcelist`. Reference variable or expression referring to a system resource to be controlled by this `Using` block.| -|`statements`|Optional. Block of statements that the `Using` block runs.| -|`End Using`|Required. Terminates the definition of the `Using` block and disposes of all the resources that it controls.| +|Term|Definition| +|---|---| +|`resourcelist`|Required if you do not supply `resourceexpression`. List of one or more system resources that this `Using` block controls, separated by commas.| +|`resourceexpression`|Required if you do not supply `resourcelist`. Reference variable or expression referring to a system resource to be controlled by this `Using` block.| +|`statements`|Optional. Block of statements that the `Using` block runs.| +|`End Using`|Required. Terminates the definition of the `Using` block and disposes of all the resources that it controls.| Each resource in the `resourcelist` part has the following syntax and parts: @@ -42,14 +42,14 @@ End Using ## resourcelist Parts -|Term|Definition| -|---|---| -|`resourcename`|Required. Reference variable that refers to a system resource that the `Using` block controls.| -|`New`|Required if the `Using` statement acquires the resource. If you have already acquired the resource, use the second syntax alternative.| -|`resourcetype`|Required. The class of the resource. The class must implement the interface.| -|`arglist`|Optional. List of arguments you are passing to the constructor to create an instance of `resourcetype`. See [Parameter List](parameter-list.md).| -|`resourceexpression`|Required. Variable or expression referring to a system resource satisfying the requirements of `resourcetype`. If you use the second syntax alternative, you must acquire the resource before passing control to the `Using` statement.| - +|Term|Definition| +|---|---| +|`resourcename`|Required. Reference variable that refers to a system resource that the `Using` block controls.| +|`New`|Required if the `Using` statement acquires the resource. If you have already acquired the resource, use the second syntax alternative.| +|`resourcetype`|Required. The class of the resource. The class must implement the interface.| +|`arglist`|Optional. List of arguments you are passing to the constructor to create an instance of `resourcetype`. See [Parameter List](parameter-list.md).| +|`resourceexpression`|Required. Variable or expression referring to a system resource satisfying the requirements of `resourcetype`. If you use the second syntax alternative, you must acquire the resource before passing control to the `Using` statement.| + ## Remarks Sometimes your code requires an unmanaged resource, such as a file handle, a COM wrapper, or a SQL connection. A `Using` block guarantees the disposal of one or more such resources when your code is finished with them. This makes them available for other code to use. @@ -62,7 +62,7 @@ End Using - *Usage* means accessing the resources and performing actions with them. The statements between `Using` and `End Using` represent the usage of the resources. -- *Disposal* means calling the method on the object in `resourcename`. This allows the object to cleanly terminate its resources. The `End Using` statement disposes of the resources under the `Using` block's control. +- *Disposal* means calling the method on the object in `resourcename`. This allows the object to cleanly terminate its resources. The `End Using` statement disposes of the resources under the `Using` block's control. ## Behavior @@ -72,7 +72,7 @@ End Using If you specify more than one system resource in the `Using` statement, the effect is the same as if you nested `Using` blocks one within another. - If `resourcename` is `Nothing`, no call to is made, and no exception is thrown. + If `resourcename` is `Nothing`, no call to is made, and no exception is thrown. ## Structured Exception Handling Within a Using Block @@ -87,7 +87,7 @@ Using resource As New resourceType ' Insert code to work with resource. End Using -' For the acquisition and disposal of resource, the following +' For the acquisition and disposal of resource, the following ' Try construction is equivalent to the Using block. Dim resource As New resourceType Try diff --git a/docs/visual-basic/language-reference/statements/while-end-while-statement.md b/docs/visual-basic/language-reference/statements/while-end-while-statement.md index ad962fa6603f5..ce66336a9a72a 100644 --- a/docs/visual-basic/language-reference/statements/while-end-while-statement.md +++ b/docs/visual-basic/language-reference/statements/while-end-while-statement.md @@ -78,7 +78,7 @@ End While ## Example 3 - The following example reads all lines in a text file. The method opens the file and returns a that reads the characters. In the `While` condition, the method of the `StreamReader` determines whether the file contains additional characters. + The following example reads all lines in a text file. The method opens the file and returns a that reads the characters. In the `While` condition, the method of the `StreamReader` determines whether the file contains additional characters. [!code-vb[VbVbalrStatements#173](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/class14.vb#173)] diff --git a/docs/visual-basic/language-reference/statements/with-end-with-statement.md b/docs/visual-basic/language-reference/statements/with-end-with-statement.md index 3e9f3a0908103..62c7bb0e5995f 100644 --- a/docs/visual-basic/language-reference/statements/with-end-with-statement.md +++ b/docs/visual-basic/language-reference/statements/with-end-with-statement.md @@ -86,7 +86,7 @@ The following example demonstrates how `With...End With` statements work with st ## See also -- +- - [Nested Control Structures](../../programming-guide/language-features/control-flow/nested-control-structures.md) - [Object Initializers: Named and Anonymous Types](../../programming-guide/language-features/objects-and-classes/object-initializers-named-and-anonymous-types.md) - [Anonymous Types](../../programming-guide/language-features/objects-and-classes/anonymous-types.md) diff --git a/docs/visual-basic/language-reference/statements/yield-statement.md b/docs/visual-basic/language-reference/statements/yield-statement.md index d0dacc4c8979c..597c7cef9dc7c 100644 --- a/docs/visual-basic/language-reference/statements/yield-statement.md +++ b/docs/visual-basic/language-reference/statements/yield-statement.md @@ -2,9 +2,9 @@ description: "Learn more about: Yield Statement (Visual Basic)" title: "Yield Statement" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.Yield" -helpviewer_keywords: +helpviewer_keywords: - "iterators, Yield statement [Visual Basic]" - "iterators [Visual Basic]" - "Yield statement [Visual Basic]" @@ -12,89 +12,89 @@ ms.assetid: f33126c5-d7c4-43e2-8e36-4ae3f0703d97 --- # Yield Statement (Visual Basic) -Sends the next element of a collection to a `For Each...Next` statement. - -## Syntax - -```vb -Yield expression -``` - -## Parameters - -|Term|Definition| -|---|---| -|`expression`|Required. An expression that is implicitly convertible to the type of the iterator function or `Get` accessor that contains the `Yield` statement.| - -## Remarks - - The `Yield` statement returns one element of a collection at a time. The `Yield` statement is included in an iterator function or `Get` accessor, which perform custom iterations over a collection. - - You consume an iterator function by using a [For Each...Next Statement](for-each-next-statement.md) or a LINQ query. Each iteration of the `For Each` loop calls the iterator function. When a `Yield` statement is reached in the iterator function, `expression` is returned, and the current location in code is retained. Execution is restarted from that location the next time that the iterator function is called. - - An implicit conversion must exist from the type of `expression` in the `Yield` statement to the return type of the iterator. - - You can use an `Exit Function` or `Return` statement to end the iteration. - - "Yield" is not a reserved word and has special meaning only when it is used in an `Iterator` function or `Get` accessor. - - For more information about iterator functions and `Get` accessors, see [Iterators](../../programming-guide/concepts/iterators.md). - -## Iterator Functions and Get Accessors - - The declaration of an iterator function or `Get` accessor must meet the following requirements: - -- It must include an [Iterator](../modifiers/iterator.md) modifier. - -- The return type must be , , , or . - -- It cannot have any `ByRef` parameters. - - An iterator function cannot occur in an event, instance constructor, static constructor, or static destructor. - - An iterator function can be an anonymous function. For more information, see [Iterators](../../programming-guide/concepts/iterators.md). - -## Exception Handling - - A `Yield` statement can be inside a `Try` block of a [Try...Catch...Finally Statement](try-catch-finally-statement.md). A `Try` block that has a `Yield` statement can have `Catch` blocks, and can have a `Finally` block. - - A `Yield` statement cannot be inside a `Catch` block or a `Finally` block. - - If the `For Each` body (outside of the iterator function) throws an exception, a `Catch` block in the iterator function is not executed, but a `Finally` block in the iterator function is executed. A `Catch` block inside an iterator function catches only exceptions that occur inside the iterator function. - -## Technical Implementation - - The following code returns an `IEnumerable (Of String)` from an iterator function and then iterates through the elements of the `IEnumerable (Of String)`. - -```vb -Dim elements As IEnumerable(Of String) = MyIteratorFunction() - … -For Each element As String In elements -Next -``` - - The call to `MyIteratorFunction` doesn't execute the body of the function. Instead the call returns an `IEnumerable(Of String)` into the `elements` variable. - - On an iteration of the `For Each` loop, the method is called for `elements`. This call executes the body of `MyIteratorFunction` until the next `Yield` statement is reached. The `Yield` statement returns an expression that determines not only the value of the `element` variable for consumption by the loop body but also the property of elements, which is an `IEnumerable (Of String)`. - - On each subsequent iteration of the `For Each` loop, the execution of the iterator body continues from where it left off, again stopping when it reaches a `Yield` statement. The `For Each` loop completes when the end of the iterator function or a `Return` or `Exit Function` statement is reached. - +Sends the next element of a collection to a `For Each...Next` statement. + +## Syntax + +```vb +Yield expression +``` + +## Parameters + +|Term|Definition| +|---|---| +|`expression`|Required. An expression that is implicitly convertible to the type of the iterator function or `Get` accessor that contains the `Yield` statement.| + +## Remarks + + The `Yield` statement returns one element of a collection at a time. The `Yield` statement is included in an iterator function or `Get` accessor, which perform custom iterations over a collection. + + You consume an iterator function by using a [For Each...Next Statement](for-each-next-statement.md) or a LINQ query. Each iteration of the `For Each` loop calls the iterator function. When a `Yield` statement is reached in the iterator function, `expression` is returned, and the current location in code is retained. Execution is restarted from that location the next time that the iterator function is called. + + An implicit conversion must exist from the type of `expression` in the `Yield` statement to the return type of the iterator. + + You can use an `Exit Function` or `Return` statement to end the iteration. + + "Yield" is not a reserved word and has special meaning only when it is used in an `Iterator` function or `Get` accessor. + + For more information about iterator functions and `Get` accessors, see [Iterators](../../programming-guide/concepts/iterators.md). + +## Iterator Functions and Get Accessors + + The declaration of an iterator function or `Get` accessor must meet the following requirements: + +- It must include an [Iterator](../modifiers/iterator.md) modifier. + +- The return type must be , , , or . + +- It cannot have any `ByRef` parameters. + + An iterator function cannot occur in an event, instance constructor, static constructor, or static destructor. + + An iterator function can be an anonymous function. For more information, see [Iterators](../../programming-guide/concepts/iterators.md). + +## Exception Handling + + A `Yield` statement can be inside a `Try` block of a [Try...Catch...Finally Statement](try-catch-finally-statement.md). A `Try` block that has a `Yield` statement can have `Catch` blocks, and can have a `Finally` block. + + A `Yield` statement cannot be inside a `Catch` block or a `Finally` block. + + If the `For Each` body (outside of the iterator function) throws an exception, a `Catch` block in the iterator function is not executed, but a `Finally` block in the iterator function is executed. A `Catch` block inside an iterator function catches only exceptions that occur inside the iterator function. + +## Technical Implementation + + The following code returns an `IEnumerable (Of String)` from an iterator function and then iterates through the elements of the `IEnumerable (Of String)`. + +```vb +Dim elements As IEnumerable(Of String) = MyIteratorFunction() + … +For Each element As String In elements +Next +``` + + The call to `MyIteratorFunction` doesn't execute the body of the function. Instead the call returns an `IEnumerable(Of String)` into the `elements` variable. + + On an iteration of the `For Each` loop, the method is called for `elements`. This call executes the body of `MyIteratorFunction` until the next `Yield` statement is reached. The `Yield` statement returns an expression that determines not only the value of the `element` variable for consumption by the loop body but also the property of elements, which is an `IEnumerable (Of String)`. + + On each subsequent iteration of the `For Each` loop, the execution of the iterator body continues from where it left off, again stopping when it reaches a `Yield` statement. The `For Each` loop completes when the end of the iterator function or a `Return` or `Exit Function` statement is reached. + ## Example 1 - The following example has a `Yield` statement that is inside a [For…Next](for-next-statement.md) loop. Each iteration of the [For Each](for-each-next-statement.md) statement body in `Main` creates a call to the `Power` iterator function. Each call to the iterator function proceeds to the next execution of the `Yield` statement, which occurs during the next iteration of the `For…Next` loop. - - The return type of the iterator method is , an iterator interface type. When the iterator method is called, it returns an enumerable object that contains the powers of a number. - - [!code-vb[VbVbalrStatements#98](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class2.vb#98)] - -## Example 2 - - The following example demonstrates a `Get` accessor that is an iterator. The property declaration includes an `Iterator` modifier. - - [!code-vb[VbVbalrStatements#99](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class2.vb#99)] - - For additional examples, see [Iterators](../../programming-guide/concepts/iterators.md). - + The following example has a `Yield` statement that is inside a [For…Next](for-next-statement.md) loop. Each iteration of the [For Each](for-each-next-statement.md) statement body in `Main` creates a call to the `Power` iterator function. Each call to the iterator function proceeds to the next execution of the `Yield` statement, which occurs during the next iteration of the `For…Next` loop. + + The return type of the iterator method is , an iterator interface type. When the iterator method is called, it returns an enumerable object that contains the powers of a number. + + [!code-vb[VbVbalrStatements#98](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class2.vb#98)] + +## Example 2 + + The following example demonstrates a `Get` accessor that is an iterator. The property declaration includes an `Iterator` modifier. + + [!code-vb[VbVbalrStatements#99](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class2.vb#99)] + + For additional examples, see [Iterators](../../programming-guide/concepts/iterators.md). + ## See also - [Statements](index.md) diff --git a/docs/visual-basic/language-reference/xml-axis/extension-indexer-property.md b/docs/visual-basic/language-reference/xml-axis/extension-indexer-property.md index feceb8b637d5a..a1b561e52190e 100644 --- a/docs/visual-basic/language-reference/xml-axis/extension-indexer-property.md +++ b/docs/visual-basic/language-reference/xml-axis/extension-indexer-property.md @@ -2,9 +2,9 @@ description: "Learn more about: Extension Indexer Property (Visual Basic)" title: "Extension Indexer Property" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.XmlPropertyExtensionIndexer" -helpviewer_keywords: +helpviewer_keywords: - "Visual Basic code, accessing XML" - "XML extension indexer [Visual Basic]" - "extension indexer [Visual Basic]" @@ -13,47 +13,47 @@ ms.assetid: a16a4b13-54be-432c-82b3-a87091464ada --- # Extension Indexer Property (Visual Basic) -Provides access to individual elements in a collection. - -## Syntax - -```vb -object(index) -``` - -## Parts - -|Term|Definition| -|---|---| -|`object`|Required. A queryable collection. That is, a collection that implements or .| -|(|Required. Denotes the start of the indexer property.| -|`index`|Required. An integer expression that specifies the zero-based position of an element of the collection.| -|)|Required. Denotes the end of the indexer property.| - -## Return Value - - The object from the specified location in the collection, or `Nothing` if the index is out of range. - -## Remarks - - You can use the extension indexer property to access individual elements in a collection. This indexer property is typically used on the output of XML axis properties. The XML child and XML descendent axis properties return collections of objects or an attribute value. - - The Visual Basic compiler converts extension indexer properties to calls to the `ElementAtOrDefault` method. Unlike an array indexer, the `ElementAtOrDefault` method returns `Nothing` if the index is out of range. This behavior is useful when you cannot easily determine the number of elements in a collection. - - This indexer property is like an extension property for collections that implement or : it is used only if the collection does not have an indexer or a default property. - - To access the value of the first element in a collection of or objects, you can use the XML `Value` property. For more information, see [XML Value Property](xml-value-property.md). - -## Example - - The following example shows how to use the extension indexer to access the second child node in a collection of objects. The collection is accessed by using the child axis property, which gets all child elements named `phone` in the `contact` object. - - [!code-vb[VbXMLSamples#24](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples11.vb#24)] - - This code displays the following text: - - `Second phone number: 425-555-0145` - +Provides access to individual elements in a collection. + +## Syntax + +```vb +object(index) +``` + +## Parts + +|Term|Definition| +|---|---| +|`object`|Required. A queryable collection. That is, a collection that implements or .| +|(|Required. Denotes the start of the indexer property.| +|`index`|Required. An integer expression that specifies the zero-based position of an element of the collection.| +|)|Required. Denotes the end of the indexer property.| + +## Return Value + + The object from the specified location in the collection, or `Nothing` if the index is out of range. + +## Remarks + + You can use the extension indexer property to access individual elements in a collection. This indexer property is typically used on the output of XML axis properties. The XML child and XML descendent axis properties return collections of objects or an attribute value. + + The Visual Basic compiler converts extension indexer properties to calls to the `ElementAtOrDefault` method. Unlike an array indexer, the `ElementAtOrDefault` method returns `Nothing` if the index is out of range. This behavior is useful when you cannot easily determine the number of elements in a collection. + + This indexer property is like an extension property for collections that implement or : it is used only if the collection does not have an indexer or a default property. + + To access the value of the first element in a collection of or objects, you can use the XML `Value` property. For more information, see [XML Value Property](xml-value-property.md). + +## Example + + The following example shows how to use the extension indexer to access the second child node in a collection of objects. The collection is accessed by using the child axis property, which gets all child elements named `phone` in the `contact` object. + + [!code-vb[VbXMLSamples#24](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples11.vb#24)] + + This code displays the following text: + + `Second phone number: 425-555-0145` + ## See also - diff --git a/docs/visual-basic/language-reference/xml-axis/xml-attribute-axis-property.md b/docs/visual-basic/language-reference/xml-axis/xml-attribute-axis-property.md index 8c4d552f11cc3..581144d2190c3 100644 --- a/docs/visual-basic/language-reference/xml-axis/xml-attribute-axis-property.md +++ b/docs/visual-basic/language-reference/xml-axis/xml-attribute-axis-property.md @@ -54,7 +54,7 @@ object.@ You can use an XML attribute axis property to access the value of an attribute by name from an object or from the first element in a collection of objects. You can retrieve an attribute value by name, or add a new attribute to an element by specifying a new name preceded by the @ identifier. - When you refer to an XML attribute using the @ identifier, the attribute value is returned as a string and you do not need to explicitly specify the property. + When you refer to an XML attribute using the @ identifier, the attribute value is returned as a string and you do not need to explicitly specify the property. The naming rules for XML attributes differ from the naming rules for Visual Basic identifiers. To access an XML attribute that has a name that is not a valid Visual Basic identifier, enclose the name in angle brackets (\< and >). diff --git a/docs/visual-basic/language-reference/xml-axis/xml-child-axis-property.md b/docs/visual-basic/language-reference/xml-axis/xml-child-axis-property.md index f3b3cb9c74b96..8b702f9d30bd1 100644 --- a/docs/visual-basic/language-reference/xml-axis/xml-child-axis-property.md +++ b/docs/visual-basic/language-reference/xml-axis/xml-child-axis-property.md @@ -39,7 +39,7 @@ object. You can use an XML child axis property to access child nodes by name from an or object, or from a collection of or objects. Use the XML `Value` property to access the value of the first child node in the returned collection. For more information, see [XML Value Property](xml-value-property.md). - The Visual Basic compiler converts child axis properties to calls to the method. + The Visual Basic compiler converts child axis properties to calls to the method. ## XML Namespaces diff --git a/docs/visual-basic/language-reference/xml-axis/xml-descendant-axis-property.md b/docs/visual-basic/language-reference/xml-axis/xml-descendant-axis-property.md index 3b8d0371f9ee3..bf6afbe855db5 100644 --- a/docs/visual-basic/language-reference/xml-axis/xml-descendant-axis-property.md +++ b/docs/visual-basic/language-reference/xml-axis/xml-descendant-axis-property.md @@ -50,7 +50,7 @@ A collection of objects. You can use an XML descendant axis property to access descendant nodes by name from an or object, or from a collection of or objects. Use the XML `Value` property to access the value of the first descendant node in the returned collection. For more information, see [XML Value Property](xml-value-property.md). -The Visual Basic compiler converts descendant axis properties into calls to the method. +The Visual Basic compiler converts descendant axis properties into calls to the method. ## XML Namespaces diff --git a/docs/visual-basic/language-reference/xml-axis/xml-value-property.md b/docs/visual-basic/language-reference/xml-axis/xml-value-property.md index c22529552b702..0d9b9488a2a65 100644 --- a/docs/visual-basic/language-reference/xml-axis/xml-value-property.md +++ b/docs/visual-basic/language-reference/xml-axis/xml-value-property.md @@ -23,9 +23,9 @@ object.Value ## Parts -|Term|Definition| -|---|---| -|`object`|Required. Collection of objects.| +|Term|Definition| +|---|---| +|`object`|Required. Collection of objects.| ## Return Value @@ -33,22 +33,22 @@ object.Value ## Remarks - The property makes it easy to access the value of the first element in a collection of objects. This property first checks whether the collection contains at least one object. If the collection is empty, this property returns `Nothing`. Otherwise, this property returns the value of the property of the first element in the collection. + The property makes it easy to access the value of the first element in a collection of objects. This property first checks whether the collection contains at least one object. If the collection is empty, this property returns `Nothing`. Otherwise, this property returns the value of the property of the first element in the collection. > [!NOTE] -> When you access the value of an XML attribute using the '\@' identifier, the attribute value is returned as a `String` and you do not need to explicitly specify the property. +> When you access the value of an XML attribute using the '\@' identifier, the attribute value is returned as a `String` and you do not need to explicitly specify the property. To access other elements in a collection, you can use the XML extension indexer property. For more information, see [Extension Indexer Property](extension-indexer-property.md). ## Inheritance - Most users will not have to implement , and can therefore ignore this section. + Most users will not have to implement , and can therefore ignore this section. - The property is an extension property for types that implement `IEnumerable(Of XElement)`. The binding of this extension property is like the binding of extension methods: if a type implements one of the interfaces and defines a property that has the name "Value", that property has precedence over the extension property. In other words, this property can be overridden by defining a new property in a class that implements `IEnumerable(Of XElement)`. + The property is an extension property for types that implement `IEnumerable(Of XElement)`. The binding of this extension property is like the binding of extension methods: if a type implements one of the interfaces and defines a property that has the name "Value", that property has precedence over the extension property. In other words, this property can be overridden by defining a new property in a class that implements `IEnumerable(Of XElement)`. ## Example 1 - The following example shows how to use the property to access the first node in a collection of objects. The example uses the child axis property to get the collection of all child nodes named `phone` that are in the `contact` object. + The following example shows how to use the property to access the first node in a collection of objects. The example uses the child axis property to get the collection of all child nodes named `phone` that are in the `contact` object. [!code-vb[VbXMLSamples#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples7.vb#15)] @@ -72,7 +72,7 @@ object.Value ## See also - -- +- - [XML Axis Properties](index.md) - [XML Literals](../xml-literals/index.md) - [Creating XML in Visual Basic](../../programming-guide/language-features/xml/creating-xml.md) diff --git a/docs/visual-basic/language-reference/xml-literals/xml-cdata-literal.md b/docs/visual-basic/language-reference/xml-literals/xml-cdata-literal.md index 13e80d7e1fa5b..3ff89ea525727 100644 --- a/docs/visual-basic/language-reference/xml-literals/xml-cdata-literal.md +++ b/docs/visual-basic/language-reference/xml-literals/xml-cdata-literal.md @@ -2,9 +2,9 @@ description: "Learn more about: XML CDATA Literal (Visual Basic)" title: "XML CDATA Literal" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.XmlLiteralCdata" -helpviewer_keywords: +helpviewer_keywords: - "CDATA literal [Visual Basic]" - "XML CDATA literal [Visual Basic]" - "XML literals [Visual Basic], CDATA" @@ -12,50 +12,50 @@ ms.assetid: 9eafb6a4-dd9d-4866-85e8-0654c65abc44 --- # XML CDATA Literal (Visual Basic) -A literal representing an object. - -## Syntax - -```xml - -``` - -## Parts - - `` - Required. Denotes the end of the section. - -## Return Value - - An object. - -## Remarks - - XML CDATA sections contain raw text that should be included, but not parsed, with the XML that contains it. A XML CDATA section can contain any text. This includes reserved XML characters. The XML CDATA section ends with the sequence "]]>". This implies the following points: - -- You cannot use an embedded expression in an XML CDATA literal because the embedded expression delimiters are valid XML CDATA content. - -- XML CDATA sections cannot be nested, because `content` cannot contain the value "]]>". - - You can assign an XML CDATA literal to a variable, or include it in an XML element literal. - +A literal representing an object. + +## Syntax + +```xml + +``` + +## Parts + + `` + Required. Denotes the end of the section. + +## Return Value + + An object. + +## Remarks + + XML CDATA sections contain raw text that should be included, but not parsed, with the XML that contains it. A XML CDATA section can contain any text. This includes reserved XML characters. The XML CDATA section ends with the sequence "]]>". This implies the following points: + +- You cannot use an embedded expression in an XML CDATA literal because the embedded expression delimiters are valid XML CDATA content. + +- XML CDATA sections cannot be nested, because `content` cannot contain the value "]]>". + + You can assign an XML CDATA literal to a variable, or include it in an XML element literal. + > [!NOTE] -> An XML literal can span multiple lines but does not use line continuation characters. This enables you to copy content from an XML document and paste it directly into a Visual Basic program. - - The Visual Basic compiler converts the XML CDATA literal to a call to the constructor. - -## Example - - The following example creates a CDATA section that contains the text "Can contain literal \ tags". - - [!code-vb[VbXMLSamples#23](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples11.vb#23)] - +> An XML literal can span multiple lines but does not use line continuation characters. This enables you to copy content from an XML document and paste it directly into a Visual Basic program. + + The Visual Basic compiler converts the XML CDATA literal to a call to the constructor. + +## Example + + The following example creates a CDATA section that contains the text "Can contain literal \ tags". + + [!code-vb[VbXMLSamples#23](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples11.vb#23)] + ## See also - diff --git a/docs/visual-basic/language-reference/xml-literals/xml-comment-literal.md b/docs/visual-basic/language-reference/xml-literals/xml-comment-literal.md index 409c82c7a256e..017042acf1a32 100644 --- a/docs/visual-basic/language-reference/xml-literals/xml-comment-literal.md +++ b/docs/visual-basic/language-reference/xml-literals/xml-comment-literal.md @@ -2,9 +2,9 @@ description: "Learn more about: XML Comment Literal (Visual Basic)" title: "XML Comment Literal" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.XmlLiteralComment" -helpviewer_keywords: +helpviewer_keywords: - "comment literal [Visual Basic]" - "XML comments, adding [Visual Basic]" - "XML comment literal [Visual Basic]" @@ -13,47 +13,47 @@ ms.assetid: 634c1cee-5e01-48d0-88d7-2dd55e4a9e52 --- # XML Comment Literal (Visual Basic) -A literal representing an object. - -## Syntax - -```xml - -``` - -## Parts - -|Term|Definition| -|---|---| -|``|Required. Denotes the end of the XML comment.| - -## Return Value - - An object. - -## Remarks - - XML comment literals do not contain document content; they contain information about the document. The XML comment section ends with the sequence "-->". This implies the following points: - -- You cannot use an embedded expression in an XML comment literal because the embedded expression delimiters are valid XML comment content. - -- XML comment sections cannot be nested, because `content` cannot contain the value "-->". - - You can assign an XML comment literal to a variable, or you can include it in an XML element literal. - +A literal representing an object. + +## Syntax + +```xml + +``` + +## Parts + +|Term|Definition| +|---|---| +|``|Required. Denotes the end of the XML comment.| + +## Return Value + + An object. + +## Remarks + + XML comment literals do not contain document content; they contain information about the document. The XML comment section ends with the sequence "-->". This implies the following points: + +- You cannot use an embedded expression in an XML comment literal because the embedded expression delimiters are valid XML comment content. + +- XML comment sections cannot be nested, because `content` cannot contain the value "-->". + + You can assign an XML comment literal to a variable, or you can include it in an XML element literal. + > [!NOTE] -> An XML literal can span multiple lines without using line continuation characters. This feature enables you to copy content from an XML document and paste it directly into a Visual Basic program. - - The Visual Basic compiler converts the XML comment literal to a call to the constructor. - -## Example - - The following example creates an XML comment that contains the text "This is a comment". - - [!code-vb[VbXMLSamples#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples4.vb#9)] - +> An XML literal can span multiple lines without using line continuation characters. This feature enables you to copy content from an XML document and paste it directly into a Visual Basic program. + + The Visual Basic compiler converts the XML comment literal to a call to the constructor. + +## Example + + The following example creates an XML comment that contains the text "This is a comment". + + [!code-vb[VbXMLSamples#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples4.vb#9)] + ## See also - diff --git a/docs/visual-basic/language-reference/xml-literals/xml-document-literal.md b/docs/visual-basic/language-reference/xml-literals/xml-document-literal.md index e5e6b6b602c32..5e7ea1b9450f4 100644 --- a/docs/visual-basic/language-reference/xml-literals/xml-document-literal.md +++ b/docs/visual-basic/language-reference/xml-literals/xml-document-literal.md @@ -2,9 +2,9 @@ description: "Learn more about: XML Document Literal (Visual Basic)" title: "XML Document Literal" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.XmlLiteralDocument" -helpviewer_keywords: +helpviewer_keywords: - "XML document literal [Visual Basic]" - "XML literals [Visual Basic], document" - "XML documents [Visual Basic], creating" @@ -13,47 +13,47 @@ ms.assetid: f7bbee56-0911-41de-b907-96f20450137b --- # XML Document Literal (Visual Basic) -A literal representing an object. - -## Syntax - -```xml - -[ piCommentList ] -rootElement -[ piCommentList ] -``` - -## Parts - -|Term|Definition| -|---|---| -|`encoding`|Optional. Literal text declaring which encoding the document uses.| -|`standalone`|Optional. Literal text. Must be "yes" or "no".| -|`piCommentList`|Optional. List of XML processing instructions and XML comments. Takes the following format:

`piComment [` `piComment` `... ]`

Each `piComment` can be one of the following:

- [XML Processing Instruction Literal](xml-processing-instruction-literal.md).
- [XML Comment Literal](xml-comment-literal.md).| -|`rootElement`|Required. Root element of the document. The format is one of the following:

  • [XML Element Literal](xml-element-literal.md).
  • Embedded expression of the form `<%=` `elementExp` `%>`. The `elementExp` returns one of the following:

    • An object.
    • A collection that contains one object and any number of and objects.

For more information, see [Embedded Expressions in XML](../../programming-guide/language-features/xml/embedded-expressions-in-xml.md).| - -## Return Value - - An object. - -## Remarks - - An XML document literal is identified by the XML declaration at the start of the literal. Although each XML document literal must have exactly one root XML element, it can have any number of XML processing instructions and XML comments. - - An XML document literal cannot appear in an XML element. - +A literal representing an object. + +## Syntax + +```xml + +[ piCommentList ] +rootElement +[ piCommentList ] +``` + +## Parts + +|Term|Definition| +|---|---| +|`encoding`|Optional. Literal text declaring which encoding the document uses.| +|`standalone`|Optional. Literal text. Must be "yes" or "no".| +|`piCommentList`|Optional. List of XML processing instructions and XML comments. Takes the following format:

`piComment [` `piComment` `... ]`

Each `piComment` can be one of the following:

- [XML Processing Instruction Literal](xml-processing-instruction-literal.md).
- [XML Comment Literal](xml-comment-literal.md).| +|`rootElement`|Required. Root element of the document. The format is one of the following:

  • [XML Element Literal](xml-element-literal.md).
  • Embedded expression of the form `<%=` `elementExp` `%>`. The `elementExp` returns one of the following:

    • An object.
    • A collection that contains one object and any number of and objects.

For more information, see [Embedded Expressions in XML](../../programming-guide/language-features/xml/embedded-expressions-in-xml.md).| + +## Return Value + + An object. + +## Remarks + + An XML document literal is identified by the XML declaration at the start of the literal. Although each XML document literal must have exactly one root XML element, it can have any number of XML processing instructions and XML comments. + + An XML document literal cannot appear in an XML element. + > [!NOTE] -> An XML literal can span multiple lines without using line continuation characters. This enables you to copy content from an XML document and paste it directly into a Visual Basic program. - - The Visual Basic compiler converts the XML document literal into calls to the and constructors. - -## Example - - The following example creates an XML document that has an XML declaration, a processing instruction, a comment, and an element that contains another element. - - [!code-vb[VbXMLSamples#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples13.vb#30)] - +> An XML literal can span multiple lines without using line continuation characters. This enables you to copy content from an XML document and paste it directly into a Visual Basic program. + + The Visual Basic compiler converts the XML document literal into calls to the and constructors. + +## Example + + The following example creates an XML document that has an XML declaration, a processing instruction, a comment, and an element that contains another element. + + [!code-vb[VbXMLSamples#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples13.vb#30)] + ## See also - diff --git a/docs/visual-basic/language-reference/xml-literals/xml-element-literal.md b/docs/visual-basic/language-reference/xml-literals/xml-element-literal.md index 6b72918466b29..b10ad1b6d73d7 100644 --- a/docs/visual-basic/language-reference/xml-literals/xml-element-literal.md +++ b/docs/visual-basic/language-reference/xml-literals/xml-element-literal.md @@ -104,7 +104,7 @@ You can use the XML element literal syntax to create ` enable you to add dynamic information to an XML element literal. For more information, see [Embedded Expressions in XML](../../programming-guide/language-features/xml/embedded-expressions-in-xml.md). -The Visual Basic compiler converts the XML element literal into calls to the constructor and, if it is required, the constructor. +The Visual Basic compiler converts the XML element literal into calls to the constructor and, if it is required, the constructor. ## XML Namespaces diff --git a/docs/visual-basic/language-reference/xml-literals/xml-processing-instruction-literal.md b/docs/visual-basic/language-reference/xml-literals/xml-processing-instruction-literal.md index e12a86b1e7f57..191346f13aff7 100644 --- a/docs/visual-basic/language-reference/xml-literals/xml-processing-instruction-literal.md +++ b/docs/visual-basic/language-reference/xml-literals/xml-processing-instruction-literal.md @@ -2,9 +2,9 @@ description: "Learn more about: XML Processing Instruction Literal (Visual Basic)" title: "XML Processing Instruction Literal" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.XmlLiteralProcessingInstruction" -helpviewer_keywords: +helpviewer_keywords: - "XML literals [Visual Basic], processing instruction" - "XML processing instruction literal [Visual Basic]" - "processing instruction literal [Visual Basic]" @@ -12,54 +12,54 @@ ms.assetid: cef4f7f8-0011-4f64-8602-795077ad4f15 --- # XML Processing Instruction Literal (Visual Basic) -A literal representing an object. - -## Syntax - -```xml - -``` - -## Parts - - `` - Required. Denotes the end of the processing instruction. - -## Return Value - - An object. - -## Remarks - - XML processing instruction literals indicate how applications should process an XML document. When an application loads an XML document, the application can check the XML processing instructions to determine how to process the document. The application interprets the meaning of `piName` and `piData`. - - The XML document literal uses syntax that is similar to that of the XML processing instruction. For more information, see [XML Document Literal](xml-document-literal.md). - +A literal representing an object. + +## Syntax + +```xml + +``` + +## Parts + + `` + Required. Denotes the end of the processing instruction. + +## Return Value + + An object. + +## Remarks + + XML processing instruction literals indicate how applications should process an XML document. When an application loads an XML document, the application can check the XML processing instructions to determine how to process the document. The application interprets the meaning of `piName` and `piData`. + + The XML document literal uses syntax that is similar to that of the XML processing instruction. For more information, see [XML Document Literal](xml-document-literal.md). + > [!NOTE] -> The `piName` element cannot begin with the strings "xml" or "XML", because the XML 1.0 specification reserves those identifiers. - - You can assign an XML processing instruction literal to a variable or include it in an XML document literal. - +> The `piName` element cannot begin with the strings "xml" or "XML", because the XML 1.0 specification reserves those identifiers. + + You can assign an XML processing instruction literal to a variable or include it in an XML document literal. + > [!NOTE] -> An XML literal can span multiple lines without needing line continuation characters. This enables you to copy content from an XML document and paste it directly into a Visual Basic program. - - The Visual Basic compiler converts the XML processing instruction literal to a call to the constructor. - -## Example - - The following example creates a processing instruction identifying a style-sheet for an XML document. - - [!code-vb[VbXMLSamples#28](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples13.vb#28)] - +> An XML literal can span multiple lines without needing line continuation characters. This enables you to copy content from an XML document and paste it directly into a Visual Basic program. + + The Visual Basic compiler converts the XML processing instruction literal to a call to the constructor. + +## Example + + The following example creates a processing instruction identifying a style-sheet for an XML document. + + [!code-vb[VbXMLSamples#28](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples13.vb#28)] + ## See also - diff --git a/docs/visual-basic/misc/a-delimiter-cannot-be-nothing-or-an-empty-string.md b/docs/visual-basic/misc/a-delimiter-cannot-be-nothing-or-an-empty-string.md index b8c45b9816cff..c3ca90794c095 100644 --- a/docs/visual-basic/misc/a-delimiter-cannot-be-nothing-or-an-empty-string.md +++ b/docs/visual-basic/misc/a-delimiter-cannot-be-nothing-or-an-empty-string.md @@ -2,21 +2,21 @@ description: "Learn more about: A delimiter cannot be Nothing or an empty String" title: "A delimiter cannot be Nothing or an empty String" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrTextFieldParser_DelimiterNothing" ms.assetid: 8885fcd1-c201-409d-9a32-6ff2b13c0c13 --- # A delimiter cannot be Nothing or an empty String -The `TextFieldParser` is unable to read from the file because the `Delimiters` property is set to `Nothing` or is an empty `String` (""). - -## To correct this error - -- Supply a valid value for `Delimiters`. - +The `TextFieldParser` is unable to read from the file because the `Delimiters` property is set to `Nothing` or is an empty `String` (""). + +## To correct this error + +- Supply a valid value for `Delimiters`. + ## See also -- +- - - [How to: Read From Comma-Delimited Text Files](../developing-apps/programming/drives-directories-files/how-to-read-from-comma-delimited-text-files.md) - [TextFieldParser Object](../language-reference/objects/textfieldparser-object.md) diff --git a/docs/visual-basic/misc/all-field-widths-except-the-last-element-must-be-greater-than-zero.md b/docs/visual-basic/misc/all-field-widths-except-the-last-element-must-be-greater-than-zero.md index f196f13b742ac..08b7c39c6fbca 100644 --- a/docs/visual-basic/misc/all-field-widths-except-the-last-element-must-be-greater-than-zero.md +++ b/docs/visual-basic/misc/all-field-widths-except-the-last-element-must-be-greater-than-zero.md @@ -2,23 +2,23 @@ description: "Learn more about: All field widths, except the last element, must be greater than zero" title: "All field widths, except the last element, must be greater than zero" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrTextFieldParser_FieldWidthsMustPositive" ms.assetid: 41d8c661-a749-4c89-be56-905c6e7c3c9d --- # All field widths, except the last element, must be greater than zero -All field widths, except the last element, must be greater than zero. A field width less than or equal to zero in the last element indicates the last field is of variable length. - - The operation has failed because a field width other than the last element is set to zero or less. A field width less than or equal to zero can be used as the last element to indicate that the last field is of variable length, but it cannot be used as any other element. - -## To correct this error - -- Set the field width to the correct length. - +All field widths, except the last element, must be greater than zero. A field width less than or equal to zero in the last element indicates the last field is of variable length. + + The operation has failed because a field width other than the last element is set to zero or less. A field width less than or equal to zero can be used as the last element to indicate that the last field is of variable length, but it cannot be used as any other element. + +## To correct this error + +- Set the field width to the correct length. + ## See also -- +- - - [How to: Read From Fixed-width Text Files](../developing-apps/programming/drives-directories-files/how-to-read-from-fixed-width-text-files.md) - [TextFieldParser Object](../language-reference/objects/textfieldparser-object.md) diff --git a/docs/visual-basic/misc/another-event-log-has-already-registered-a-source-with-this-name.md b/docs/visual-basic/misc/another-event-log-has-already-registered-a-source-with-this-name.md index 802d45e185ae7..5f5e4d31a0ab1 100644 --- a/docs/visual-basic/misc/another-event-log-has-already-registered-a-source-with-this-name.md +++ b/docs/visual-basic/misc/another-event-log-has-already-registered-a-source-with-this-name.md @@ -6,16 +6,16 @@ ms.assetid: e6f5cd95-bb3f-4845-84fb-ae623a9bd44e --- # Another event log has already registered a source with this name -An attempt was made to write an entry to an event log where the specified source is registered with another event log. - - You must set the property of your component instance before your component writes an entry to a log. When this happens, the system checks that the source you specified is registered with the event log to which the component is writing, and calls if needed. - -## To correct this error - -1. Remove the association of the source with the first log using the or the method. - -2. Register the source with the new log. - +An attempt was made to write an entry to an event log where the specified source is registered with another event log. + + You must set the property of your component instance before your component writes an entry to a log. When this happens, the system checks that the source you specified is registered with the event log to which the component is writing, and calls if needed. + +## To correct this error + +1. Remove the association of the source with the first log using the or the method. + +2. Register the source with the new log. + ## See also - [My.Application.Log](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) diff --git a/docs/visual-basic/misc/argument-basepath-must-be-a-path-to-a-folder.md b/docs/visual-basic/misc/argument-basepath-must-be-a-path-to-a-folder.md index 63618589e4b46..0eccd32f595e8 100644 --- a/docs/visual-basic/misc/argument-basepath-must-be-a-path-to-a-folder.md +++ b/docs/visual-basic/misc/argument-basepath-must-be-a-path-to-a-folder.md @@ -6,15 +6,15 @@ ms.assetid: b180ce60-ad57-41a6-a313-491d86d84cc7 --- # Argument BasePath must be a path to a folder -The argument `BasePath` must consist of a path to a folder. You may be parsing a string incorrectly and supplying a value that is not recognized as a valid path. - -## To correct this error - -- Check the value you are supplying for `BasePath` to make sure it is a valid path to a folder. - +The argument `BasePath` must consist of a path to a folder. You may be parsing a string incorrectly and supplying a value that is not recognized as a valid path. + +## To correct this error + +- Check the value you are supplying for `BasePath` to make sure it is a valid path to a folder. + ## See also -- -- -- +- +- +- - [How to: Parse File Paths](../developing-apps/programming/drives-directories-files/how-to-parse-file-paths.md) diff --git a/docs/visual-basic/misc/baselogname-cannot-be-nothing-or-an-empty-string.md b/docs/visual-basic/misc/baselogname-cannot-be-nothing-or-an-empty-string.md index 53a1394c5c8bc..16b6aea8b0001 100644 --- a/docs/visual-basic/misc/baselogname-cannot-be-nothing-or-an-empty-string.md +++ b/docs/visual-basic/misc/baselogname-cannot-be-nothing-or-an-empty-string.md @@ -2,22 +2,22 @@ description: "Learn more about: BaseLogName cannot be Nothing or an empty String" title: "BaseLogName cannot be Nothing or an empty String" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrApplicationLogBaseNameNull" ms.assetid: 8e7665e3-5343-45fa-bc79-64e235a0477f --- # BaseLogName cannot be Nothing or an empty String -The value of the property cannot be `Nothing` or an empty string. - - The property specifies the base name for the log files. - -## To correct this error - -- Set the property to a string that contains at least one character. - +The value of the property cannot be `Nothing` or an empty string. + + The property specifies the base name for the log files. + +## To correct this error + +- Set the property to a string that contains at least one character. + ## See also -- +- - [My.Application.Log](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) - [My.Application.Info.DirectoryPath](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) diff --git a/docs/visual-basic/misc/bc30456.md b/docs/visual-basic/misc/bc30456.md index c89413fd50f14..bb610c9aeaa19 100644 --- a/docs/visual-basic/misc/bc30456.md +++ b/docs/visual-basic/misc/bc30456.md @@ -2,28 +2,28 @@ description: "Learn more about: '' is not a member of ''" title: "'' is not a member of ''" ms.date: 10/10/2018 -f1_keywords: +f1_keywords: - "bc30456" - "vbc30456" -helpviewer_keywords: +helpviewer_keywords: - "BC30456" ms.assetid: 029f9742-858a-40c5-b771-7cdfb2c777cc --- # '\' is not a member of '\' -The member you have provided is not a member of the class. - - **Error ID:** BC30456 - -## To correct this error - -1. Check the name of the member to ensure it is accurate. - +The member you have provided is not a member of the class. + + **Error ID:** BC30456 + +## To correct this error + +1. Check the name of the member to ensure it is accurate. + 2. Use an actual member of the class. 3. If you are attempting to compile an SDK-style project (a project with a \*.vbproj file that begins with the line ``), and the error message refers to a type or member in the Microsoft.VisualBasic.dll assembly, configure your application to compile with a reference to the Visual Basic Runtime Library. By default, a subset of the library is embedded in your assembly in an SDK-style project. - For example, the following example fails to compile because the property cannot be found. It is not embedded in the subset of the Visual Basic Runtime included with your application. + For example, the following example fails to compile because the property cannot be found. It is not embedded in the subset of the Visual Basic Runtime included with your application. [!code-vb[BC30456](~/samples/snippets/visualbasic/language-reference/error-messages/bc30456/program.vb)] diff --git a/docs/visual-basic/misc/bc30532.md b/docs/visual-basic/misc/bc30532.md index bfe8f0864941e..d0483a696e84e 100644 --- a/docs/visual-basic/misc/bc30532.md +++ b/docs/visual-basic/misc/bc30532.md @@ -2,23 +2,23 @@ description: "Learn more about: Conversion from 'Date' to 'Double' requires calling the 'Date.ToOADate' method" title: "Conversion from 'Date' to 'Double' requires calling the 'Date.ToOADate' method" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc30532" - "vbc30532" -helpviewer_keywords: +helpviewer_keywords: - "BC30532" ms.assetid: 8171ce21-e4f6-4e75-b7e8-32baf78a40eb --- # Conversion from 'Date' to 'Double' requires calling the 'Date.ToOADate' method -You have attempted to cast a `Date` value to a `Double` value, which cannot be done without using the method. - - **Error ID:** BC30532 - -## To correct this error - -- Use the method to convert the value. - +You have attempted to cast a `Date` value to a `Double` value, which cannot be done without using the method. + + **Error ID:** BC30532 + +## To correct this error + +- Use the method to convert the value. + ## See also - [Type Conversions in Visual Basic](../programming-guide/language-features/data-types/type-conversions.md) diff --git a/docs/visual-basic/misc/bc30533.md b/docs/visual-basic/misc/bc30533.md index 07c9eafe06f2a..56a364ddb9240 100644 --- a/docs/visual-basic/misc/bc30533.md +++ b/docs/visual-basic/misc/bc30533.md @@ -2,23 +2,23 @@ description: "Learn more about: Conversion from 'Double' to 'Date' requires calling the 'Date.FromOADate'" title: "Conversion from 'Double' to 'Date' requires calling the 'Date.FromOADate'" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc30533" - "bc30533" -helpviewer_keywords: +helpviewer_keywords: - "BC30533" ms.assetid: afcfd115-4614-4b0b-ad09-76af8dba2ed5 --- # Conversion from 'Double' to 'Date' requires calling the 'Date.FromOADate' -You have attempted to cast a `Date` value to a `Double` value, which cannot be done without using the method. - - **Error ID:** BC30533 - -## To correct this error - -- Use the method to convert the value. - +You have attempted to cast a `Date` value to a `Double` value, which cannot be done without using the method. + + **Error ID:** BC30533 + +## To correct this error + +- Use the method to convert the value. + ## See also - [Type Conversions in Visual Basic](../programming-guide/language-features/data-types/type-conversions.md) diff --git a/docs/visual-basic/misc/bc30668.md b/docs/visual-basic/misc/bc30668.md index 2bb6d19aafd97..f34532bc0d098 100644 --- a/docs/visual-basic/misc/bc30668.md +++ b/docs/visual-basic/misc/bc30668.md @@ -2,23 +2,23 @@ description: "Learn more about: '' is obsolete: ''" title: "'' is obsolete: ''" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc30668" - "vbc30668" -helpviewer_keywords: +helpviewer_keywords: - "BC30668" ms.assetid: 25e5606c-2734-4f42-a2bc-1ad28ec1e892 --- # '\' is obsolete: '\' -A statement attempts to access a class or structure member which has been marked with the attribute and the directive to treat it as an error. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - **Error ID:** BC30668 - -## To correct this error - -1. Examine the quoted error message and take appropriate action. - +A statement attempts to access a class or structure member which has been marked with the attribute and the directive to treat it as an error. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + **Error ID:** BC30668 + +## To correct this error + +1. Examine the quoted error message and take appropriate action. + 2. Ensure that the source code reference is spelling the member name correctly. diff --git a/docs/visual-basic/misc/bc30768.md b/docs/visual-basic/misc/bc30768.md index 9e50fbdc4a8e8..4b04592a42cda 100644 --- a/docs/visual-basic/misc/bc30768.md +++ b/docs/visual-basic/misc/bc30768.md @@ -2,25 +2,25 @@ description: "Learn more about: 'Line' statements are no longer supported (Smart Device/Visual Basic Compiler Error)" title: "'Line' statements are no longer supported (Smart Device-Visual Basic Compiler Error)" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc30768" - "bc30768" -helpviewer_keywords: +helpviewer_keywords: - "BC30768" ms.assetid: e7a17c77-06bb-4d33-966e-addb4f51caaf --- # 'Line' statements are no longer supported (Smart Device/Visual Basic Compiler Error) -The `Line` statement is no longer supported. File I/O functionality is normally available as , but the targeted version of the .NET Compact Framework does not support it. - - **Error ID:** BC30768 - -## To correct this error - -- If performing file access, use the functions defined in the namespace. - -- If performing graphics, use . - +The `Line` statement is no longer supported. File I/O functionality is normally available as , but the targeted version of the .NET Compact Framework does not support it. + + **Error ID:** BC30768 + +## To correct this error + +- If performing file access, use the functions defined in the namespace. + +- If performing graphics, use . + ## See also - diff --git a/docs/visual-basic/misc/bc30911.md b/docs/visual-basic/misc/bc30911.md index f5d2052061a89..65f9efd9dbbe8 100644 --- a/docs/visual-basic/misc/bc30911.md +++ b/docs/visual-basic/misc/bc30911.md @@ -2,29 +2,29 @@ description: "Learn more about: '' accessor of '' is obsolete: '' (Visual Basic Error)" title: "'' accessor of '' is obsolete: '' (Visual Basic Error)" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc30911" - "bc30911" -helpviewer_keywords: +helpviewer_keywords: - "BC30911" ms.assetid: b690be0c-4dca-4f79-88ed-4ee3e3f1f90b --- # '\' accessor of '\' is obsolete: '\' (Visual Basic Error) -A statement attempts to read or write a property for which the corresponding procedure has been marked with the attribute and the directive to treat it as an error. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - **Error ID:** BC30911 - -## To correct this error - -1. Examine the quoted error message and take appropriate action. - -2. Ensure that the source-code reference is spelling the property name correctly. - -3. Avoid accessing the property in the way (reading or writing) that generated this message. - +A statement attempts to read or write a property for which the corresponding procedure has been marked with the attribute and the directive to treat it as an error. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + **Error ID:** BC30911 + +## To correct this error + +1. Examine the quoted error message and take appropriate action. + +2. Ensure that the source-code reference is spelling the property name correctly. + +3. Avoid accessing the property in the way (reading or writing) that generated this message. + ## See also - [Property Procedures](../programming-guide/language-features/procedures/property-procedures.md) diff --git a/docs/visual-basic/misc/bc30912.md b/docs/visual-basic/misc/bc30912.md index a004fcf661323..43e22ad1a37cc 100644 --- a/docs/visual-basic/misc/bc30912.md +++ b/docs/visual-basic/misc/bc30912.md @@ -2,27 +2,27 @@ description: "Learn more about: '' accessor of '' is obsolete (Visual Basic Error)" title: "'' accessor of '' is obsolete (Visual Basic Error)" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc30912" - "bc30912" -helpviewer_keywords: +helpviewer_keywords: - "BC30912" ms.assetid: f1fa965e-090c-49f3-ab1e-cbb2f9b2a5f0 --- # '\' accessor of '\' is obsolete (Visual Basic Error) -A statement attempts to read or write a property for which the corresponding procedure has been marked with the attribute and the directive to treat it as an error. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - **Error ID:** BC30912 - -## To correct this error - -1. Ensure that the source-code reference is spelling the property name correctly. - -2. Avoid accessing the property in the way (reading or writing) that generated this message. - +A statement attempts to read or write a property for which the corresponding procedure has been marked with the attribute and the directive to treat it as an error. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + **Error ID:** BC30912 + +## To correct this error + +1. Ensure that the source-code reference is spelling the property name correctly. + +2. Avoid accessing the property in the way (reading or writing) that generated this message. + ## See also - [Property Procedures](../programming-guide/language-features/procedures/property-procedures.md) diff --git a/docs/visual-basic/misc/bc30917.md b/docs/visual-basic/misc/bc30917.md index 29aa091cfc121..4d855e9ca6e7e 100644 --- a/docs/visual-basic/misc/bc30917.md +++ b/docs/visual-basic/misc/bc30917.md @@ -2,23 +2,23 @@ description: "Learn more about: Class '' must declare a 'Sub New' because the '' in its base class '' is marked obsolete" title: "Class '' must declare a 'Sub New' because the '' in its base class '' is marked obsolete" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc30917" - "bc30917" -helpviewer_keywords: +helpviewer_keywords: - "BC30917" ms.assetid: 764d222d-e058-40ad-a354-29b956a8027b --- # Class '\' must declare a 'Sub New' because the '\' in its base class '\' is marked obsolete -A class declaration does not include a constructor, and the base class constructor is marked with the attribute and the directive to treat it as an error. - - When a derived class does not declare a constructor, Visual Basic attempts to generate an implicit parameterless constructor that calls `MyBase.New()`. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit constructor. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - **Error ID:** BC30917 - -## To correct this error - +A class declaration does not include a constructor, and the base class constructor is marked with the attribute and the directive to treat it as an error. + + When a derived class does not declare a constructor, Visual Basic attempts to generate an implicit parameterless constructor that calls `MyBase.New()`. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit constructor. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + **Error ID:** BC30917 + +## To correct this error + - Use `Sub New` to declare a constructor in the derived class. diff --git a/docs/visual-basic/misc/bc30918.md b/docs/visual-basic/misc/bc30918.md index 65f0771db6c81..d0806a78dd16d 100644 --- a/docs/visual-basic/misc/bc30918.md +++ b/docs/visual-basic/misc/bc30918.md @@ -2,25 +2,25 @@ description: "Learn more about: Class '' must declare a 'Sub New' because the '' in its base class '' is marked obsolete: ''" title: "Class '' must declare a 'Sub New' because the '' in its base class '' is marked obsolete: ''" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc30918" - "vbc30918" -helpviewer_keywords: +helpviewer_keywords: - "BC30918" ms.assetid: 4879254c-4b03-4416-a4a3-e9f6b5d92a1a --- # Class '\' must declare a 'Sub New' because the '\' in its base class '\' is marked obsolete: '\' -A class declaration does not include a constructor, and the base class constructor is marked with the attribute and the directive to treat it as an error. - - When a derived class does not declare a constructor, Visual Basic attempts to generate an implicit parameterless constructor that calls `MyBase.New()`. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit constructor. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - **Error ID:** BC30918 - -## To correct this error - -1. Examine the quoted error message and take appropriate action. - +A class declaration does not include a constructor, and the base class constructor is marked with the attribute and the directive to treat it as an error. + + When a derived class does not declare a constructor, Visual Basic attempts to generate an implicit parameterless constructor that calls `MyBase.New()`. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit constructor. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + **Error ID:** BC30918 + +## To correct this error + +1. Examine the quoted error message and take appropriate action. + 2. Use `Sub New` to declare a constructor in the derived class. diff --git a/docs/visual-basic/misc/bc30919.md b/docs/visual-basic/misc/bc30919.md index 372ac7343dc42..fcdfd82bbc3a9 100644 --- a/docs/visual-basic/misc/bc30919.md +++ b/docs/visual-basic/misc/bc30919.md @@ -2,23 +2,23 @@ description: "Learn more about: First statement of this 'Sub New' must be an explicit call to 'MyBase.New' or 'MyClass.New' because the '' in the base class '' of '' is marked obsolete." title: "First statement of this 'Sub New' must be an explicit call to 'MyBase.New' or 'MyClass.New' because the '' in the base class '' of '' is marked obsolete." ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc30919" - "bc30919" -helpviewer_keywords: +helpviewer_keywords: - "BC30919" ms.assetid: 437e3204-8ddc-45d3-b9b4-c66d53a61a6d --- # First statement of this 'Sub New' must be an explicit call to 'MyBase.New' or 'MyClass.New' because the '\' in the base class '\' of '\' is marked obsolete. -A class constructor does not explicitly call a base class constructor, and the implicit base class constructor is marked with the attribute and the directive to treat it as an error. - - When a derived class constructor does not call a base class constructor, Visual Basic attempts to generate an implicit call to a parameterless base class constructor. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit call. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - **Error ID:** BC30919 - -## To correct this error - +A class constructor does not explicitly call a base class constructor, and the implicit base class constructor is marked with the attribute and the directive to treat it as an error. + + When a derived class constructor does not call a base class constructor, Visual Basic attempts to generate an implicit call to a parameterless base class constructor. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit call. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + **Error ID:** BC30919 + +## To correct this error + - Include a call to `MyBase.New()` or `MyClass.New()` as the first statement of the `Sub New` in the derived class. diff --git a/docs/visual-basic/misc/bc30954.md b/docs/visual-basic/misc/bc30954.md index cd6509ed6e2d9..2e1923dcabaa1 100644 --- a/docs/visual-basic/misc/bc30954.md +++ b/docs/visual-basic/misc/bc30954.md @@ -2,27 +2,27 @@ description: "Learn more about: Type arguments inferred for method '' result in the following errors :" title: "Type arguments inferred for method '' result in the following errors :" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc30954" - "vbc30954" -helpviewer_keywords: +helpviewer_keywords: - "BC30954" ms.assetid: 796592c4-70b7-45be-9322-db09e9095d7d --- # Type arguments inferred for method '\' result in the following errors :\ -A generic procedure is called without supplying any type arguments, and the inferred type arguments result in one or more constraint violations. - - Normally, when you invoke a generic type, you supply a type argument for each type parameter the generic type defines. If you do not supply any type arguments, the compiler attempts to infer the types to be passed to the type parameters. If the inferred types fail to satisfy one or more of the type parameter constraints, the compiler generates this error. - - A *constraint* on a type parameter limits what type arguments can be passed to it. For example, a type parameter might be constrained to be a class that implements the interface. For more information, see "Constraints" in [Generic Procedures in Visual Basic](../programming-guide/language-features/data-types/generic-procedures.md). - - **Error ID:** BC30954 - -## To correct this error - -- Supply type arguments to the generic procedure so that the compiler does not have to infer them. - +A generic procedure is called without supplying any type arguments, and the inferred type arguments result in one or more constraint violations. + + Normally, when you invoke a generic type, you supply a type argument for each type parameter the generic type defines. If you do not supply any type arguments, the compiler attempts to infer the types to be passed to the type parameters. If the inferred types fail to satisfy one or more of the type parameter constraints, the compiler generates this error. + + A *constraint* on a type parameter limits what type arguments can be passed to it. For example, a type parameter might be constrained to be a class that implements the interface. For more information, see "Constraints" in [Generic Procedures in Visual Basic](../programming-guide/language-features/data-types/generic-procedures.md). + + **Error ID:** BC30954 + +## To correct this error + +- Supply type arguments to the generic procedure so that the compiler does not have to infer them. + ## See also - [Generic Types in Visual Basic](../programming-guide/language-features/data-types/generic-types.md) diff --git a/docs/visual-basic/misc/bc31075.md b/docs/visual-basic/misc/bc31075.md index 2498abc99a184..ef1365aa287d5 100644 --- a/docs/visual-basic/misc/bc31075.md +++ b/docs/visual-basic/misc/bc31075.md @@ -2,21 +2,21 @@ description: "Learn more about: '' is obsolete (Visual Basic Error)" title: "'' is obsolete (Visual Basic Error)" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc31075" - "bc31075" -helpviewer_keywords: +helpviewer_keywords: - "BC31075" ms.assetid: 614d36a1-2fba-4d03-963c-1565e88b08a6 --- # '\' is obsolete (Visual Basic Error) -A statement attempts to access a programming element which has been marked with the attribute and the directive to treat it as an error. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - **Error ID:** BC31075 - -## To correct this error - +A statement attempts to access a programming element which has been marked with the attribute and the directive to treat it as an error. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + **Error ID:** BC31075 + +## To correct this error + - Ensure that the source-code reference is spelling the element name correctly. diff --git a/docs/visual-basic/misc/bc31521.md b/docs/visual-basic/misc/bc31521.md index 306c3d991a134..8797c573b5be9 100644 --- a/docs/visual-basic/misc/bc31521.md +++ b/docs/visual-basic/misc/bc31521.md @@ -2,26 +2,26 @@ description: "Learn more about: '' cannot be applied more than once to an assembly" title: "'' cannot be applied more than once to an assembly" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc31521" - "vbc31521" -helpviewer_keywords: +helpviewer_keywords: - "BC31521" ms.assetid: 7312570f-8afb-4afe-992f-b6f7796f5f26 --- # '\' cannot be applied more than once to an assembly -The specified attribute can only be applied once to an attribute. - - **Error ID:** BC31521 - -## To correct this error - -1. Remove redundant applications of this attribute. - -2. If you are using a custom attribute you developed, modify `AttributeUsageAttribute` and set the `AllowMultiple` property to `True`. - +The specified attribute can only be applied once to an attribute. + + **Error ID:** BC31521 + +## To correct this error + +1. Remove redundant applications of this attribute. + +2. If you are using a custom attribute you developed, modify `AttributeUsageAttribute` and set the `AllowMultiple` property to `True`. + ## See also - -- +- diff --git a/docs/visual-basic/misc/bc31526.md b/docs/visual-basic/misc/bc31526.md index b72f9294df379..e7f1b5e4ecdb3 100644 --- a/docs/visual-basic/misc/bc31526.md +++ b/docs/visual-basic/misc/bc31526.md @@ -2,29 +2,29 @@ description: "Learn more about: 'System.Runtime.InteropServices.DllImportAttribute' cannot be applied to a method that is generic or nested in a generic type" title: "'System.Runtime.InteropServices.DllImportAttribute' cannot be applied to a method that is generic or nested in a generic type" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc31526" - "bc31526" -helpviewer_keywords: +helpviewer_keywords: - "BC31526" ms.assetid: 6f153808-1945-4c99-85ae-8bd3b35ee5a2 --- # 'System.Runtime.InteropServices.DllImportAttribute' cannot be applied to a method that is generic or nested in a generic type -A procedure is declared with the , but either the procedure is generic or it is contained in a generic class or structure. - - The common language runtime (CLR) recognizes this attribute and its property as designating a replacement procedure defined in an unmanaged dynamic-link library (DLL) outside the .NET Framework. When code calls the procedure to which the is applied, the common language runtime calls the designated unmanaged procedure instead. - - Because unmanaged platforms outside the .NET Framework do not recognize generic types, you cannot interoperate with them using generic types. - - **Error ID:** BC31526 - -## To correct this error - -- If neither the procedure nor its container needs to be generic, then remove the `Of` clauses so that they are not generic. - -- If the procedure or its container needs to be generic, then remove the from the declaration of this procedure. - +A procedure is declared with the , but either the procedure is generic or it is contained in a generic class or structure. + + The common language runtime (CLR) recognizes this attribute and its property as designating a replacement procedure defined in an unmanaged dynamic-link library (DLL) outside the .NET Framework. When code calls the procedure to which the is applied, the common language runtime calls the designated unmanaged procedure instead. + + Because unmanaged platforms outside the .NET Framework do not recognize generic types, you cannot interoperate with them using generic types. + + **Error ID:** BC31526 + +## To correct this error + +- If neither the procedure nor its container needs to be generic, then remove the `Of` clauses so that they are not generic. + +- If the procedure or its container needs to be generic, then remove the from the declaration of this procedure. + ## See also - diff --git a/docs/visual-basic/misc/bc31529.md b/docs/visual-basic/misc/bc31529.md index 253fe51fba77f..15b5515c5ae80 100644 --- a/docs/visual-basic/misc/bc31529.md +++ b/docs/visual-basic/misc/bc31529.md @@ -2,29 +2,29 @@ description: "Learn more about: 'System.Runtime.InteropServices.DllImportAttribute' cannot be applied to instance methods" title: "'System.Runtime.InteropServices.DllImportAttribute' cannot be applied to instance methods" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc31529" - "bc31529" -helpviewer_keywords: +helpviewer_keywords: - "BC31529" ms.assetid: c8bde5d7-c6bf-4d21-bb1a-e8627d65ad29 --- # 'System.Runtime.InteropServices.DllImportAttribute' cannot be applied to instance methods -A nonshared procedure is declared with the . - - The common language runtime (CLR) recognizes this attribute and its property as designating a replacement procedure defined in an unmanaged dynamic-link library (DLL) outside the .NET Framework. When code calls the procedure to which the is applied, the common language runtime calls the designated unmanaged procedure instead. - - Because unmanaged platforms outside the .NET Framework do not support nonshared procedures the same way the .NET Framework does, you cannot interoperate with them using nonshared procedures. - - **Error ID:** BC31529 - -## To correct this error - -- If the procedure does not need to apply individually to each instance of its class or structure, then declare it as `Shared`. - -- If the procedure cannot be `Shared`, then remove the from the declaration of this procedure. - +A nonshared procedure is declared with the . + + The common language runtime (CLR) recognizes this attribute and its property as designating a replacement procedure defined in an unmanaged dynamic-link library (DLL) outside the .NET Framework. When code calls the procedure to which the is applied, the common language runtime calls the designated unmanaged procedure instead. + + Because unmanaged platforms outside the .NET Framework do not support nonshared procedures the same way the .NET Framework does, you cannot interoperate with them using nonshared procedures. + + **Error ID:** BC31529 + +## To correct this error + +- If the procedure does not need to apply individually to each instance of its class or structure, then declare it as `Shared`. + +- If the procedure cannot be `Shared`, then remove the from the declaration of this procedure. + ## See also - diff --git a/docs/visual-basic/misc/bc31530.md b/docs/visual-basic/misc/bc31530.md index 1204643621204..447fa574940ed 100644 --- a/docs/visual-basic/misc/bc31530.md +++ b/docs/visual-basic/misc/bc31530.md @@ -2,27 +2,27 @@ description: "Learn more about: 'System.Runtime.InteropServices.DllImportAttribute' cannot be applied to interface methods" title: "'System.Runtime.InteropServices.DllImportAttribute' cannot be applied to interface methods" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc31530" - "vbc31530" -helpviewer_keywords: +helpviewer_keywords: - "BC31530" ms.assetid: e63f1f7d-b7df-4637-a0f4-2783479ca1af --- # 'System.Runtime.InteropServices.DllImportAttribute' cannot be applied to interface methods -A procedure is defined inside an interface, but the procedure definition applies the . - - The common language runtime (CLR) recognizes this attribute and its property as designating a replacement procedure defined in an unmanaged dynamic-link library (DLL) outside the .NET Framework. When code calls the procedure to which the is applied, the common language runtime calls the designated unmanaged procedure instead. - - Because the definition of a procedure inside an interface does not include any implementation, it cannot interoperate with unmanaged platforms outside the .NET Framework. - - **Error ID:** BC31530 - -## To correct this error - -- Remove the from the definition of this procedure. - +A procedure is defined inside an interface, but the procedure definition applies the . + + The common language runtime (CLR) recognizes this attribute and its property as designating a replacement procedure defined in an unmanaged dynamic-link library (DLL) outside the .NET Framework. When code calls the procedure to which the is applied, the common language runtime calls the designated unmanaged procedure instead. + + Because the definition of a procedure inside an interface does not include any implementation, it cannot interoperate with unmanaged platforms outside the .NET Framework. + + **Error ID:** BC31530 + +## To correct this error + +- Remove the from the definition of this procedure. + ## See also - diff --git a/docs/visual-basic/misc/bc32115.md b/docs/visual-basic/misc/bc32115.md index 334fc0a1ec671..1c4c868c7ec3a 100644 --- a/docs/visual-basic/misc/bc32115.md +++ b/docs/visual-basic/misc/bc32115.md @@ -2,27 +2,27 @@ description: "Learn more about: 'System.Nullable' does not satisfy the 'Structure' constraint for type parameter ''" title: "'System.Nullable' does not satisfy the 'Structure' constraint for type parameter ''" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc32115" - "vbc32115" -helpviewer_keywords: +helpviewer_keywords: - "BC32115" ms.assetid: 98053645-fa76-4826-a7c1-f1bdf3511863 --- # 'System.Nullable' does not satisfy the 'Structure' constraint for type parameter '\' -A generic type is invoked passing a type argument of to a type parameter with a `Structure` constraint. - - The common language runtime (CLR) specifically disallows the structure as a type argument to itself. Even though it is a structure and would otherwise satisfy a `Structure` constraint, using it recursively could lead to awkward constructions such as `Nullable(Of Nullable(Of Nullable))`. - - **Error ID:** BC32115 - -## To correct this error - -- Either remove the `Structure` constraint from the type parameter, or change the type argument to some value type other than . - +A generic type is invoked passing a type argument of to a type parameter with a `Structure` constraint. + + The common language runtime (CLR) specifically disallows the structure as a type argument to itself. Even though it is a structure and would otherwise satisfy a `Structure` constraint, using it recursively could lead to awkward constructions such as `Nullable(Of Nullable(Of Nullable))`. + + **Error ID:** BC32115 + +## To correct this error + +- Either remove the `Structure` constraint from the type parameter, or change the type argument to some value type other than . + ## See also -- +- - [Generic Types in Visual Basic](../programming-guide/language-features/data-types/generic-types.md) - [Structure (Visual Basic)](../language-reference/statements/structure-statement.md) diff --git a/docs/visual-basic/misc/bc36010.md b/docs/visual-basic/misc/bc36010.md index 814049223fef2..e86099a02a16b 100644 --- a/docs/visual-basic/misc/bc36010.md +++ b/docs/visual-basic/misc/bc36010.md @@ -2,25 +2,25 @@ description: "Learn more about: 'Using' operand of type '' must implement System.IDisposable" title: "'Using' operand of type '' must implement System.IDisposable" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc36010" - "bc36010" -helpviewer_keywords: +helpviewer_keywords: - "BC36010" ms.assetid: ae9ed5d5-68ba-4950-bb7a-61327fa0e7d5 --- # 'Using' operand of type '\' must implement System.IDisposable -A `Using` statement specifies a resource of a type that does not implement the interface. - - The purpose of a `Using` block is to guarantee the disposal of a system resource when exiting the block. To satisfy this purpose, the resource must expose the method implemented from . - - **Error ID:** BC36010 - -## To correct this error - -- Remove the resource from the resource list of the `Using` statement, or replace it with a resource that implements . - +A `Using` statement specifies a resource of a type that does not implement the interface. + + The purpose of a `Using` block is to guarantee the disposal of a system resource when exiting the block. To satisfy this purpose, the resource must expose the method implemented from . + + **Error ID:** BC36010 + +## To correct this error + +- Remove the resource from the resource list of the `Using` statement, or replace it with a resource that implements . + ## See also - diff --git a/docs/visual-basic/misc/bc36012.md b/docs/visual-basic/misc/bc36012.md index e5b823ed50b5c..beafb4439b2d5 100644 --- a/docs/visual-basic/misc/bc36012.md +++ b/docs/visual-basic/misc/bc36012.md @@ -2,25 +2,25 @@ description: "Learn more about: 'Using' resource variable type can not be array type" title: "'Using' resource variable type can not be array type" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc36012" - "bc36012" -helpviewer_keywords: +helpviewer_keywords: - "BC36012" ms.assetid: f98c54b0-6ede-48b6-aa31-438664c219f3 --- # 'Using' resource variable type can not be array type -A `Using` statement specifies an array variable for a resource. - - The class does not implement the interface, so the `Using` block cannot call the method on an array resource. - - **Error ID:** BC36012 - -## To correct this error - -- Use a different type of system resource in the `Using` block. - +A `Using` statement specifies an array variable for a resource. + + The class does not implement the interface, so the `Using` block cannot call the method on an array resource. + + **Error ID:** BC36012 + +## To correct this error + +- Use a different type of system resource in the `Using` block. + ## See also - [Using Statement](../language-reference/statements/using-statement.md) diff --git a/docs/visual-basic/misc/bc36610.md b/docs/visual-basic/misc/bc36610.md index 4ebb8df491492..33af764e50274 100644 --- a/docs/visual-basic/misc/bc36610.md +++ b/docs/visual-basic/misc/bc36610.md @@ -2,27 +2,27 @@ description: "Learn more about: Name '' is either not declared or not in the current scope" title: "Name '' is either not declared or not in the current scope" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc36610" - "bc36610" -helpviewer_keywords: +helpviewer_keywords: - "BC36610" ms.assetid: e66a4b8a-9252-42ae-a30d-341fad4f74be --- # Name '\' is either not declared or not in the current scope -A LINQ query refers to a programming element, but the compiler cannot find an element that has that exact name. - - **Error ID:** BC36610 - -## To correct this error - -1. Check the spelling of the name in the referring statement. Visual Basic is case-insensitive, but any other variation in the spelling constitutes a different name. Note that the underscore (`_`) is part of the name and therefore part of the spelling. - -2. Verify that the programming element is in scope. If the referring statement is outside the region declaring the programming element, you might have to qualify the element name. For more information, see [Scope in Visual Basic](../programming-guide/language-features/declared-elements/scope.md). - -3. Ensure that you have the member access operator (`.`) between an object and its member. For example, if you have a control named `TextBox1`, to access its property you should type `TextBox1.Text`. If instead you type `TextBox1Text`, you have created a different name. - +A LINQ query refers to a programming element, but the compiler cannot find an element that has that exact name. + + **Error ID:** BC36610 + +## To correct this error + +1. Check the spelling of the name in the referring statement. Visual Basic is case-insensitive, but any other variation in the spelling constitutes a different name. Note that the underscore (`_`) is part of the name and therefore part of the spelling. + +2. Verify that the programming element is in scope. If the referring statement is outside the region declaring the programming element, you might have to qualify the element name. For more information, see [Scope in Visual Basic](../programming-guide/language-features/declared-elements/scope.md). + +3. Ensure that you have the member access operator (`.`) between an object and its member. For example, if you have a control named `TextBox1`, to access its property you should type `TextBox1.Text`. If instead you type `TextBox1Text`, you have created a different name. + ## See also - [Introduction to LINQ in Visual Basic](../programming-guide/language-features/linq/introduction-to-linq.md) diff --git a/docs/visual-basic/misc/bc36625.md b/docs/visual-basic/misc/bc36625.md index 4aa022b73c0e9..edeb6fff96494 100644 --- a/docs/visual-basic/misc/bc36625.md +++ b/docs/visual-basic/misc/bc36625.md @@ -2,43 +2,43 @@ description: "Learn more about: Lambda expression cannot be converted to '' because '' is not a delegate type" title: "Lambda expression cannot be converted to '' because '' is not a delegate type" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc36625" - "vbc36625" -helpviewer_keywords: +helpviewer_keywords: - "BC36625" ms.assetid: c03634d4-d831-4f8c-b6ab-566465968e4d --- # Lambda expression cannot be converted to '\' because '\' is not a delegate type -Lambda expressions can be used where delegates are valid. They can be converted to compatible delegate types, but not to any other type. For example, you can define a delegate type and assign a lambda expression to it, or send a lambda expression as the argument to a parameter. These examples are shown in the following code. - -```vb -Module Module1 - - Delegate Function FunDel(ByVal m As Integer) As Boolean - - Sub Main() - - ' Assign a lambda expression to a function delegate. - Dim negative As FunDel = Function(n As Integer) n < 0 - Console.WriteLine(negative(-3)) - - ' Send a lambda as the argument to a delegate parameter. - Dim numbers() As Integer = {3, 4, 2, 8, 1, 0, 9, 13, 42} - Dim evens = numbers.Where(Function(n) n Mod 2 = 0) - - For Each even In evens - Console.WriteLine(even) - Next - - End Sub - -End Module -``` - - **Error ID:** BC36625 - +Lambda expressions can be used where delegates are valid. They can be converted to compatible delegate types, but not to any other type. For example, you can define a delegate type and assign a lambda expression to it, or send a lambda expression as the argument to a parameter. These examples are shown in the following code. + +```vb +Module Module1 + + Delegate Function FunDel(ByVal m As Integer) As Boolean + + Sub Main() + + ' Assign a lambda expression to a function delegate. + Dim negative As FunDel = Function(n As Integer) n < 0 + Console.WriteLine(negative(-3)) + + ' Send a lambda as the argument to a delegate parameter. + Dim numbers() As Integer = {3, 4, 2, 8, 1, 0, 9, 13, 42} + Dim evens = numbers.Where(Function(n) n Mod 2 = 0) + + For Each even In evens + Console.WriteLine(even) + Next + + End Sub + +End Module +``` + + **Error ID:** BC36625 + ## See also - [Lambda Expressions](../programming-guide/language-features/procedures/lambda-expressions.md) diff --git a/docs/visual-basic/misc/bc40000.md b/docs/visual-basic/misc/bc40000.md index dab82d3619394..51f765979432a 100644 --- a/docs/visual-basic/misc/bc40000.md +++ b/docs/visual-basic/misc/bc40000.md @@ -2,25 +2,25 @@ description: "Learn more about: '' is obsolete: ''" title: "'' is obsolete: ''" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc40000" - "vbc40000" -helpviewer_keywords: +helpviewer_keywords: - "BC40000" ms.assetid: dade0f57-eca1-4dd0-b978-020678838be6 --- # '\' is obsolete: '\' -A statement attempts to access a programming element which has been marked with the attribute and the directive to treat it as a warning. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - By default, this message is a warning, because the property of is `False`. For more information about hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). - - **Error ID:** BC40000 - -## To correct this error - -1. Examine the quoted error message and take appropriate action. - +A statement attempts to access a programming element which has been marked with the attribute and the directive to treat it as a warning. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + By default, this message is a warning, because the property of is `False`. For more information about hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). + + **Error ID:** BC40000 + +## To correct this error + +1. Examine the quoted error message and take appropriate action. + 2. Ensure that the source code reference is spelling the element name correctly. diff --git a/docs/visual-basic/misc/bc40019.md b/docs/visual-basic/misc/bc40019.md index 2850711da7267..9c3730a38999e 100644 --- a/docs/visual-basic/misc/bc40019.md +++ b/docs/visual-basic/misc/bc40019.md @@ -2,31 +2,31 @@ description: "Learn more about: '' accessor of '' is obsolete: '' (Visual Basic Warning)" title: "'' accessor of '' is obsolete: '' (Visual Basic Warning)" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc40019" - "vbc40019" -helpviewer_keywords: +helpviewer_keywords: - "BC40019" ms.assetid: 57d00655-1837-4605-a5e9-1ae5b6935f51 --- # '\' accessor of '\' is obsolete: '\' (Visual Basic Warning) -A statement attempts to read or write a property for which the corresponding procedure has been marked with the attribute and the directive to treat it as a warning. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - By default, this message is a warning, because the property of is `False`. For more information on hiding warnings or treating warnings as errors, please see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). - - **Error ID:** BC40019 - -## To correct this error - -1. Examine the quoted error message and take appropriate action. - -2. Ensure that the source-code reference is spelling the property name correctly. - -3. Avoid accessing the property in the way (reading or writing) that generated this message. - +A statement attempts to read or write a property for which the corresponding procedure has been marked with the attribute and the directive to treat it as a warning. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + By default, this message is a warning, because the property of is `False`. For more information on hiding warnings or treating warnings as errors, please see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). + + **Error ID:** BC40019 + +## To correct this error + +1. Examine the quoted error message and take appropriate action. + +2. Ensure that the source-code reference is spelling the property name correctly. + +3. Avoid accessing the property in the way (reading or writing) that generated this message. + ## See also - [Property Procedures](../programming-guide/language-features/procedures/property-procedures.md) diff --git a/docs/visual-basic/misc/bc40020.md b/docs/visual-basic/misc/bc40020.md index cd1a56ddea24c..6941f06420a5f 100644 --- a/docs/visual-basic/misc/bc40020.md +++ b/docs/visual-basic/misc/bc40020.md @@ -2,29 +2,29 @@ description: "Learn more about: '' accessor of '' is obsolete (Visual Basic Warning)" title: "'' accessor of '' is obsolete (Visual Basic Warning)" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc40020" - "bc40020" -helpviewer_keywords: +helpviewer_keywords: - "BC40020" ms.assetid: 005440f4-6e82-421c-b2ce-9c5139325bac --- # '\' accessor of '\' is obsolete (Visual Basic Warning) -A statement attempts to read or write a property for which the corresponding procedure has been marked with the attribute and the directive to treat it as a warning. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - By default, this message is a warning, because the property of is `False`. For more information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). - - **Error ID:** BC40020 - -## To correct this error - -1. Ensure that the source-code reference is spelling the property name correctly. - -2. Avoid accessing the property in the way (reading or writing) that generated this message. - +A statement attempts to read or write a property for which the corresponding procedure has been marked with the attribute and the directive to treat it as a warning. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + By default, this message is a warning, because the property of is `False`. For more information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). + + **Error ID:** BC40020 + +## To correct this error + +1. Ensure that the source-code reference is spelling the property name correctly. + +2. Avoid accessing the property in the way (reading or writing) that generated this message. + ## See also - [Property Procedures](../programming-guide/language-features/procedures/property-procedures.md) diff --git a/docs/visual-basic/misc/bc41000.md b/docs/visual-basic/misc/bc41000.md index bb55a625646da..7722c22aa4f44 100644 --- a/docs/visual-basic/misc/bc41000.md +++ b/docs/visual-basic/misc/bc41000.md @@ -2,26 +2,26 @@ description: "Learn more about: Attribute '' cannot be specified more than once in this project, even with identical parameter values" title: "Attribute '' cannot be specified more than once in this project, even with identical parameter values" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc41000" - "vbc41000" -helpviewer_keywords: +helpviewer_keywords: - "BC41000" ms.assetid: 7e846177-7b89-44da-8f17-cdc8606ef148 --- # Attribute '\' cannot be specified more than once in this project, even with identical parameter values -A custom attribute is specified more than once on the same programming element, but an is applied to the custom attribute, and its property is set to `False`. controls whether the attribute is multi-use. - - By default, this message is a warning. For information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). - - **Error ID:** BC41000 - -## To correct this error - -- Remove the extra specification of the custom attribute, or set to `True` in the applied to it. - +A custom attribute is specified more than once on the same programming element, but an is applied to the custom attribute, and its property is set to `False`. controls whether the attribute is multi-use. + + By default, this message is a warning. For information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). + + **Error ID:** BC41000 + +## To correct this error + +- Remove the extra specification of the custom attribute, or set to `True` in the applied to it. + ## See also - -- +- diff --git a/docs/visual-basic/misc/bc41001.md b/docs/visual-basic/misc/bc41001.md index 873f00b25082d..5798208b9df2b 100644 --- a/docs/visual-basic/misc/bc41001.md +++ b/docs/visual-basic/misc/bc41001.md @@ -2,25 +2,25 @@ description: "Learn more about: Class '' should declare a 'Sub New' because the '' in its base class '' is marked obsolete" title: "Class '' should declare a 'Sub New' because the '' in its base class '' is marked obsolete" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc41001" - "vbc41001" -helpviewer_keywords: +helpviewer_keywords: - "BC41001" ms.assetid: b2c6b996-6d52-4963-9fee-8b6f78fc028c --- # Class '\' should declare a 'Sub New' because the '\' in its base class '\' is marked obsolete -A class declaration does not include a constructor, and the base class constructor is marked with the attribute and the directive to treat it as a warning. - - When a derived class does not declare a constructor, Visual Basic attempts to generate an implicit parameterless constructor that calls `MyBase.New()`. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit constructor. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - By default, this message is a warning, because the property of is `False`. For information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). - - **Error ID:** BC41001 - -## To correct this error - +A class declaration does not include a constructor, and the base class constructor is marked with the attribute and the directive to treat it as a warning. + + When a derived class does not declare a constructor, Visual Basic attempts to generate an implicit parameterless constructor that calls `MyBase.New()`. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit constructor. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + By default, this message is a warning, because the property of is `False`. For information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). + + **Error ID:** BC41001 + +## To correct this error + 1. Use `Sub New` to declare a constructor in the derived class. diff --git a/docs/visual-basic/misc/bc41002.md b/docs/visual-basic/misc/bc41002.md index de08587a1db6e..94e749cbdc113 100644 --- a/docs/visual-basic/misc/bc41002.md +++ b/docs/visual-basic/misc/bc41002.md @@ -2,27 +2,27 @@ description: "Learn more about: Class '' should declare a 'Sub New' because the '' in its base class '' is marked obsolete: ''" title: "Class '' should declare a 'Sub New' because the '' in its base class '' is marked obsolete: ''" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbc41002" - "bc41002" -helpviewer_keywords: +helpviewer_keywords: - "BC41002" ms.assetid: 6d034bbe-ab6a-433a-ae31-8c4a42faf7f8 --- # Class '\' should declare a 'Sub New' because the '\' in its base class '\' is marked obsolete: '\' -A class declaration does not include a constructor, and the base class constructor is marked with the attribute and the directive to treat it as a warning. - - When a derived class does not declare a constructor, Visual Basic attempts to generate an implicit parameterless constructor that calls `MyBase.New()`. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit constructor. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - By default, this message is a warning, because the property of is `False`. For information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). - - **Error ID:** BC41002 - -## To correct this error - -1. Examine the quoted error message and take appropriate action. - +A class declaration does not include a constructor, and the base class constructor is marked with the attribute and the directive to treat it as a warning. + + When a derived class does not declare a constructor, Visual Basic attempts to generate an implicit parameterless constructor that calls `MyBase.New()`. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit constructor. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + By default, this message is a warning, because the property of is `False`. For information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). + + **Error ID:** BC41002 + +## To correct this error + +1. Examine the quoted error message and take appropriate action. + 2. Use `Sub New` to declare a constructor in the derived class. diff --git a/docs/visual-basic/misc/bc41003.md b/docs/visual-basic/misc/bc41003.md index 38ec31b776de4..e94669a3ed534 100644 --- a/docs/visual-basic/misc/bc41003.md +++ b/docs/visual-basic/misc/bc41003.md @@ -2,25 +2,25 @@ description: "Learn more about: First statement of this 'Sub New' should be an explicit call to 'MyBase.New' or 'MyClass.New' because the '' in the base class '' of '' is marked obsolete." title: "First statement of this 'Sub New' should be an explicit call to 'MyBase.New' or 'MyClass.New' because the '' in the base class '' of '' is marked obsolete." ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc41003" - "vbc41003" -helpviewer_keywords: +helpviewer_keywords: - "BC41003" ms.assetid: 6d7c84db-659f-4388-85cf-38208ad607c3 --- # First statement of this 'Sub New' should be an explicit call to 'MyBase.New' or 'MyClass.New' because the '\' in the base class '\' of '\' is marked obsolete. -A class constructor does not explicitly call a base class constructor, and the implicit base class constructor is marked with the attribute and the directive to treat it as a warning. - - When a derived class constructor does not call a base class constructor, Visual Basic attempts to generate an implicit call to a parameterless base class constructor. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit call. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - By default, this message is a warning because the property of is `False`. For information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). - - **Error ID:** BC41003 - -## To correct this error - +A class constructor does not explicitly call a base class constructor, and the implicit base class constructor is marked with the attribute and the directive to treat it as a warning. + + When a derived class constructor does not call a base class constructor, Visual Basic attempts to generate an implicit call to a parameterless base class constructor. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit call. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + By default, this message is a warning because the property of is `False`. For information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). + + **Error ID:** BC41003 + +## To correct this error + - Include a call to `MyBase.New()` or `MyClass.New()` as the first statement of the `Sub New` in the derived class. diff --git a/docs/visual-basic/misc/bc41004.md b/docs/visual-basic/misc/bc41004.md index 2a2f3d8212f9a..43a3236e68a43 100644 --- a/docs/visual-basic/misc/bc41004.md +++ b/docs/visual-basic/misc/bc41004.md @@ -2,27 +2,27 @@ description: "Learn more about: First statement of this 'Sub New' should be an explicit call to 'MyBase.New' or 'MyClass.New' because the '' in the base class '' of '' is marked obsolete: ''" title: "First statement of this 'Sub New' should be an explicit call to 'MyBase.New' or 'MyClass.New' because the '' in the base class '' of '' is marked obsolete: ''" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc41004" - "vbc41004" -helpviewer_keywords: +helpviewer_keywords: - "BC41004" ms.assetid: 61185283-d43d-46ae-bfa0-6fe3e1d0982a --- # First statement of this 'Sub New' should be an explicit call to 'MyBase.New' or 'MyClass.New' because the '\' in the base class '\' of '\' is marked obsolete: '\' -A class constructor does not explicitly call a base class constructor, and the implicit base class constructor is marked with the attribute and the directive to treat it as a warning. - - When a derived class constructor does not call a base class constructor, Visual Basic attempts to generate an implicit call to a parameterless base class constructor. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit call. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. - - You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. - - By default, this message is a warning because the property of is `False`. For information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). - - **Error ID:** BC41004 - -## To correct this error - -1. Examine the quoted error message and take appropriate action. - +A class constructor does not explicitly call a base class constructor, and the implicit base class constructor is marked with the attribute and the directive to treat it as a warning. + + When a derived class constructor does not call a base class constructor, Visual Basic attempts to generate an implicit call to a parameterless base class constructor. If there is no accessible constructor in the base class that can be called without arguments, Visual Basic cannot generate an implicit call. In this case, the required constructor is marked with the attribute, so Visual Basic cannot call it. + + You can mark any programming element as being no longer in use by applying to it. If you do this, you can set the attribute's property to either `True` or `False`. If you set it to `True`, the compiler treats an attempt to use the element as an error. If you set it to `False`, or let it default to `False`, the compiler issues a warning if there is an attempt to use the element. + + By default, this message is a warning because the property of is `False`. For information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). + + **Error ID:** BC41004 + +## To correct this error + +1. Examine the quoted error message and take appropriate action. + 2. Include a call to `MyBase.New()` or `MyClass.New()` as the first statement of the `Sub New` in the derived class. diff --git a/docs/visual-basic/misc/bc41006.md b/docs/visual-basic/misc/bc41006.md index 4e24ec9d2dffa..16fbb4d5b17e7 100644 --- a/docs/visual-basic/misc/bc41006.md +++ b/docs/visual-basic/misc/bc41006.md @@ -2,29 +2,29 @@ description: "Learn more about: Type arguments inferred for method '' result in the following warnings :" title: "Type arguments inferred for method '' result in the following warnings :" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "bc41006" - "vbc41006" -helpviewer_keywords: +helpviewer_keywords: - "BC41006" ms.assetid: c789ffa9-0273-47f6-8915-78fc6a7d3d6d --- # Type arguments inferred for method '\' result in the following warnings :\ -A generic procedure is called without supplying any type arguments, and the inferred type arguments result in one or more warnings. - - Normally, when you invoke a generic type, you supply a type argument for each type parameter that the generic type defines. If you do not supply any type arguments, the compiler attempts to infer the types to be passed to the type parameters. If the inferred types cause ambiguity, or if they create a situation that could lead to unexpected results, then the compiler generates this warning. - - A *constraint* on a type parameter limits what type arguments can be passed to it. For example, a type parameter might be constrained to be a class that implements the interface. For more information, see "Constraints" in [Generic Procedures in Visual Basic](../programming-guide/language-features/data-types/generic-procedures.md). - - By default, this message is a warning. For information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). - - **Error ID:** BC41006 - -## To correct this error - -- Supply type arguments to the generic procedure so that the compiler does not have to infer them. - +A generic procedure is called without supplying any type arguments, and the inferred type arguments result in one or more warnings. + + Normally, when you invoke a generic type, you supply a type argument for each type parameter that the generic type defines. If you do not supply any type arguments, the compiler attempts to infer the types to be passed to the type parameters. If the inferred types cause ambiguity, or if they create a situation that could lead to unexpected results, then the compiler generates this warning. + + A *constraint* on a type parameter limits what type arguments can be passed to it. For example, a type parameter might be constrained to be a class that implements the interface. For more information, see "Constraints" in [Generic Procedures in Visual Basic](../programming-guide/language-features/data-types/generic-procedures.md). + + By default, this message is a warning. For information on hiding warnings or treating warnings as errors, see [Configuring Warnings in Visual Basic](/visualstudio/ide/configuring-warnings-in-visual-basic). + + **Error ID:** BC41006 + +## To correct this error + +- Supply type arguments to the generic procedure so that the compiler does not have to infer them. + ## See also - [Generic Types in Visual Basic](../programming-guide/language-features/data-types/generic-types.md) diff --git a/docs/visual-basic/misc/key-cannot-be-deleted-because-it-has-subkeys.md b/docs/visual-basic/misc/key-cannot-be-deleted-because-it-has-subkeys.md index 2b07a9b7f8623..6b5203c44e0ca 100644 --- a/docs/visual-basic/misc/key-cannot-be-deleted-because-it-has-subkeys.md +++ b/docs/visual-basic/misc/key-cannot-be-deleted-because-it-has-subkeys.md @@ -6,14 +6,14 @@ ms.assetid: 71d7f28f-42ef-4eb7-a39e-512c40b79977 --- # Key cannot be deleted because it has subkeys -The key cannot be deleted because it has subkeys. - -## To correct this error - -- Determine and delete the specified key's subkeys before attempting this operation. - +The key cannot be deleted because it has subkeys. + +## To correct this error + +- Determine and delete the specified key's subkeys before attempting this operation. + ## See also -- +- - [How to: Delete a Registry Key](../developing-apps/programming/computer-resources/how-to-delete-a-registry-key.md) - [Reading from and Writing to the Registry (Visual Basic)](../developing-apps/programming/computer-resources/reading-from-and-writing-to-the-registry.md) diff --git a/docs/visual-basic/misc/source-name-specified-in-eventlogsource-is-registered-to-another-log.md b/docs/visual-basic/misc/source-name-specified-in-eventlogsource-is-registered-to-another-log.md index a6c95d85a768e..67f7ae9bf26c4 100644 --- a/docs/visual-basic/misc/source-name-specified-in-eventlogsource-is-registered-to-another-log.md +++ b/docs/visual-basic/misc/source-name-specified-in-eventlogsource-is-registered-to-another-log.md @@ -6,14 +6,14 @@ ms.assetid: 7317e100-098b-408d-86e5-7c74cf8558c7 --- # Source name specified in EventLogSource is registered to a log other than that specified in EventLogName -The `EventLog` is attempting to refer to a source that is registered to a different log. If you are writing entries to an event log, you must specify the property. The property registers your component with the event log as a valid source of entries. A single source can be associated with (and therefore write entries to) only one event log at a time. - - By default, if you try to write an entry without first having registered your component as a valid source, the system automatically registers the source with the event log, using the value of the property as the source string. - -## To correct this error - -- Make sure the source is registered to the correct log. To do this, use the method or one of its overloads to specify a string that uniquely identifies your component to the event log. - +The `EventLog` is attempting to refer to a source that is registered to a different log. If you are writing entries to an event log, you must specify the property. The property registers your component with the event log as a valid source of entries. A single source can be associated with (and therefore write entries to) only one event log at a time. + + By default, if you try to write an entry without first having registered your component as a valid source, the system automatically registers the source with the event log, using the value of the property as the source string. + +## To correct this error + +- Make sure the source is registered to the correct log. To do this, use the method or one of its overloads to specify a string that uniquely identifies your component to the event log. + ## See also - [Administering Event Logs](/previous-versions/visualstudio/visual-studio-2008/4f69axw4(v=vs.90)) diff --git a/docs/visual-basic/misc/the-value-of-argumentname-must-be-a-positive-number.md b/docs/visual-basic/misc/the-value-of-argumentname-must-be-a-positive-number.md index 4cdfb08be724a..79ee56e991a97 100644 --- a/docs/visual-basic/misc/the-value-of-argumentname-must-be-a-positive-number.md +++ b/docs/visual-basic/misc/the-value-of-argumentname-must-be-a-positive-number.md @@ -2,22 +2,22 @@ description: "Learn more about: The value of must be a positive number" title: "The value of must be a positive number" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrApplicationLog_NegativeNumber" ms.assetid: 597c412c-499e-49d2-b656-af2d90c292a5 --- # The value of \ must be a positive number -The value of the property must be greater than zero. - - The property specifies the amount of free disk space, in bytes, necessary before messages can be written to the log file - -## To correct this error - -- Set the property to a positive number. - +The value of the property must be greater than zero. + + The property specifies the amount of free disk space, in bytes, necessary before messages can be written to the log file + +## To correct this error + +- Set the property to a positive number. + ## See also -- +- - [My.Application.Log](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) - [My.Application.Info.DirectoryPath](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) diff --git a/docs/visual-basic/misc/the-value-of-argumentname-must-be-greater-than-or-equal-to-1000.md b/docs/visual-basic/misc/the-value-of-argumentname-must-be-greater-than-or-equal-to-1000.md index 7fb5142d4a1d9..d063bd2dcefbe 100644 --- a/docs/visual-basic/misc/the-value-of-argumentname-must-be-greater-than-or-equal-to-1000.md +++ b/docs/visual-basic/misc/the-value-of-argumentname-must-be-greater-than-or-equal-to-1000.md @@ -2,22 +2,22 @@ description: "Learn more about: The value of must be greater than or equal to 1000" title: "The value of must be greater than or equal to 1000" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrApplicationLogNumberTooSmall" ms.assetid: 81aed143-1abb-41c2-9922-8e83711100e3 --- # The value of \ must be greater than or equal to 1000 -The value of the property must be greater than or equal to 1000. - - The property specifies the maximum number of bytes allowed in a log file before a new log file is created. - -## To correct this error - -- Set the property to a number greater than or equal to 1000. - +The value of the property must be greater than or equal to 1000. + + The property specifies the maximum number of bytes allowed in a log file before a new log file is created. + +## To correct this error + +- Set the property to a number greater than or equal to 1000. + ## See also -- +- - [My.Application.Log](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) - [My.Application.Info.DirectoryPath](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) diff --git a/docs/visual-basic/misc/this-operation-can-only-be-done-when-the-file-is-closed.md b/docs/visual-basic/misc/this-operation-can-only-be-done-when-the-file-is-closed.md index 1eb881d0b8409..7f80698a23ba4 100644 --- a/docs/visual-basic/misc/this-operation-can-only-be-done-when-the-file-is-closed.md +++ b/docs/visual-basic/misc/this-operation-can-only-be-done-when-the-file-is-closed.md @@ -6,14 +6,14 @@ ms.assetid: 79fe95ae-4aff-469f-beda-d5a85c91d421 --- # This operation can only be done when the File is closed -When a file is open, an attempt has been made to perform an operation that can only be performed when the file is closed. - -## To correct this error - -- Close the file and attempt the operation again. - +When a file is open, an attempt has been made to perform an operation that can only be performed when the file is closed. + +## To correct this error + +- Close the file and attempt the operation again. + ## See also - -- +- - [How to: Get Information About a File in Visual Basic](/previous-versions/visualstudio/visual-studio-2010/abtzf6f7(v=vs.100)) diff --git a/docs/visual-basic/misc/unable-to-obtain-a-stream-for-the-log.md b/docs/visual-basic/misc/unable-to-obtain-a-stream-for-the-log.md index 5a8b3295f5020..dde572664ca0d 100644 --- a/docs/visual-basic/misc/unable-to-obtain-a-stream-for-the-log.md +++ b/docs/visual-basic/misc/unable-to-obtain-a-stream-for-the-log.md @@ -2,27 +2,27 @@ description: "Learn more about: Unable to obtain a stream for the log" title: "Unable to obtain a stream for the log" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrApplicationLog_ExhaustedPossibleStreamNames" ms.assetid: 33994f52-8efb-4790-a459-033e5c1db632 --- # Unable to obtain a stream for the log -Unable to obtain a stream for the log. Potential file names based on \ are already in use. - - The class could not create a new log file because all potential log file names based on \ are already in use. - - Having too many log files may indicate an architectural problem with the application. See the documentation for the class for more information. - -## To correct this error - -1. Set the property to or to include a date-stamp in the log file name. - -2. Archive the existing logs and remove them from the computer to allow the object to create new logs. - +Unable to obtain a stream for the log. Potential file names based on \ are already in use. + + The class could not create a new log file because all potential log file names based on \ are already in use. + + Having too many log files may indicate an architectural problem with the application. See the documentation for the class for more information. + +## To correct this error + +1. Set the property to or to include a date-stamp in the log file name. + +2. Archive the existing logs and remove them from the computer to allow the object to create new logs. + ## See also - -- +- - [My.Application.Log](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) - [My.Application.Info.DirectoryPath](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) diff --git a/docs/visual-basic/misc/unable-to-write-to-log-file-because-reduce-free-disk-space-below-reservedspace.md b/docs/visual-basic/misc/unable-to-write-to-log-file-because-reduce-free-disk-space-below-reservedspace.md index fbc14ce5f9814..045cf3ea581b2 100644 --- a/docs/visual-basic/misc/unable-to-write-to-log-file-because-reduce-free-disk-space-below-reservedspace.md +++ b/docs/visual-basic/misc/unable-to-write-to-log-file-because-reduce-free-disk-space-below-reservedspace.md @@ -2,32 +2,32 @@ description: "Learn more about: Unable to write to log file because writing to it would reduce free disk space below ReservedSpace value" title: "Unable to write to log file because writing to it would reduce free disk space below ReservedSpace value" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrApplicationLog_ReservedSpaceEncroached" ms.assetid: 95832e70-4ecc-47aa-90c1-f35c4d468151 --- # Unable to write to log file because writing to it would reduce free disk space below ReservedSpace value -The class could not write to the log file because: - -- The amount of free disk space (in bytes) is less than the value of the property - - —and— - -- The value of the property was . - -## To correct this error - -1. Archive the existing logs and remove them from the computer to allow the object to create new logs. - -2. Change the value of the property to a smaller number to reserve less disk space. - -3. Set the property to to discard messages without warning if there is not enough free disk space. - +The class could not write to the log file because: + +- The amount of free disk space (in bytes) is less than the value of the property + + —and— + +- The value of the property was . + +## To correct this error + +1. Archive the existing logs and remove them from the computer to allow the object to create new logs. + +2. Change the value of the property to a smaller number to reserve less disk space. + +3. Set the property to to discard messages without warning if there is not enough free disk space. + ## See also -- -- +- +- - - [My.Application.Log](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) - [My.Application.Info.DirectoryPath](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) diff --git a/docs/visual-basic/misc/unable-to-write-to-log-file-it-would-cause-it-to-exceed-maximumsize-value.md b/docs/visual-basic/misc/unable-to-write-to-log-file-it-would-cause-it-to-exceed-maximumsize-value.md index 0f3be8f259d48..d497af795c967 100644 --- a/docs/visual-basic/misc/unable-to-write-to-log-file-it-would-cause-it-to-exceed-maximumsize-value.md +++ b/docs/visual-basic/misc/unable-to-write-to-log-file-it-would-cause-it-to-exceed-maximumsize-value.md @@ -2,32 +2,32 @@ description: "Learn more about: Unable to write to log file because writing to it would cause it to exceed MaximumSize value" title: "Unable to write to log file because writing to it would cause it to exceed MaximumSize value" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vbrApplicationLog_FileExceedsMaximumSize" ms.assetid: 61747a9c-e460-424b-a365-73cdba9dd428 --- # Unable to write to log file because writing to it would cause it to exceed MaximumSize value -The class could not write to the log file because: - -- The log file size (in bytes) is greater than the value of the property - - —and— - -- The value of the property was . - -## To correct this error - -1. Archive the existing logs and remove them from the computer to allow the object to create new logs. - -2. Change the value of the property to allow for larger logs. - -3. Set the property to to discard messages without warning if the log is too large. - +The class could not write to the log file because: + +- The log file size (in bytes) is greater than the value of the property + + —and— + +- The value of the property was . + +## To correct this error + +1. Archive the existing logs and remove them from the computer to allow the object to create new logs. + +2. Change the value of the property to allow for larger logs. + +3. Set the property to to discard messages without warning if the log is too large. + ## See also -- -- +- +- - - [My.Application.Log](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) - [My.Application.Info.DirectoryPath](xref:Microsoft.VisualBasic.ApplicationServices.ApplicationBase.Log) diff --git a/docs/visual-basic/programming-guide/com-interop/walkthrough-office-programming.md b/docs/visual-basic/programming-guide/com-interop/walkthrough-office-programming.md index 80e02902ffb3c..eb57f37cd7a79 100644 --- a/docs/visual-basic/programming-guide/com-interop/walkthrough-office-programming.md +++ b/docs/visual-basic/programming-guide/com-interop/walkthrough-office-programming.md @@ -72,7 +72,7 @@ You must have Microsoft Office Excel and Microsoft Office Word installed on your [!code-vb[csOfficeWalkthrough#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/csofficewalkthrough/vb/thisaddin.vb#4)] - - Method [Add]() has an *optional parameter* for specifying a particular template. Optional parameters enable you to omit the argument for that parameter if you want to use the parameter's default value. Because no argument is sent in the previous example, `Add` uses the default template and creates a new workbook. + - Method [Add]() has an *optional parameter* for specifying a particular template. Optional parameters enable you to omit the argument for that parameter if you want to use the parameter's default value. Because no argument is sent in the previous example, `Add` uses the default template and creates a new workbook. - The `Range` and `Offset` properties of the [Range]() object use the *indexed properties* feature. Indexed properties also enable you to use the `Value` property of the `Range` object, eliminating the need to use the `Value2` property. The `Value` property is indexed, but the index is optional. Optional arguments and indexed properties work together in the following example. @@ -96,7 +96,7 @@ You must have Microsoft Office Excel and Microsoft Office Word installed on your [!code-vb[csOfficeWalkthrough#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/csofficewalkthrough/vb/thisaddin.vb#10)] - The [PasteSpecial]() method has seven parameters, all of which are defined as optional reference parameters. Named and optional arguments enable you to designate the parameters you want to access by name and to send arguments to only those parameters. In this example, arguments are sent to indicate that a link to the workbook on the Clipboard should be created (parameter `Link`) and that the link is to be displayed in the Word document as an icon (parameter `DisplayAsIcon`). + The [PasteSpecial]() method has seven parameters, all of which are defined as optional reference parameters. Named and optional arguments enable you to designate the parameters you want to access by name and to send arguments to only those parameters. In this example, arguments are sent to indicate that a link to the workbook on the Clipboard should be created (parameter `Link`) and that the link is to be displayed in the Word document as an icon (parameter `DisplayAsIcon`). ## Run the application diff --git a/docs/visual-basic/programming-guide/concepts/async/async-return-types.md b/docs/visual-basic/programming-guide/concepts/async/async-return-types.md index 838c19d9bc3af..f6d0dce43744b 100644 --- a/docs/visual-basic/programming-guide/concepts/async/async-return-types.md +++ b/docs/visual-basic/programming-guide/concepts/async/async-return-types.md @@ -6,7 +6,7 @@ ms.assetid: 07890291-ee72-42d3-932a-fa4d312f2c60 --- # Async Return Types (Visual Basic) -Async methods have three possible return types: , , and void. In Visual Basic, the void return type is written as a [Sub](../../language-features/procedures/sub-procedures.md) procedure. For more information about async methods, see [Asynchronous Programming with Async and Await (Visual Basic)](index.md). +Async methods have three possible return types: , , and void. In Visual Basic, the void return type is written as a [Sub](../../language-features/procedures/sub-procedures.md) procedure. For more information about async methods, see [Asynchronous Programming with Async and Await (Visual Basic)](index.md). Each return type is examined in one of the following sections, and you can find a full example that uses all three types at the end of the topic. @@ -15,7 +15,7 @@ Each return type is examined in one of the following sections, and you can find ## Task(T) Return Type -The return type is used for an async method that contains a [Return](../../../language-reference/statements/return-statement.md) statement in which the operand has type `TResult`. +The return type is used for an async method that contains a [Return](../../../language-reference/statements/return-statement.md) statement in which the operand has type `TResult`. In the following example, the `TaskOfT_MethodAsync` async method contains a return statement that returns an integer. Therefore, the method declaration must specify a return type of `Task(Of Integer)`. @@ -51,10 +51,10 @@ The following code calls and awaits method `TaskOfT_MethodAsync`. The result is Dim result1 As Integer = Await TaskOfT_MethodAsync() ``` -You can better understand how this happens by separating the call to `TaskOfT_MethodAsync` from the application of `Await`, as the following code shows. A call to method `TaskOfT_MethodAsync` that isn't immediately awaited returns a `Task(Of Integer)`, as you would expect from the declaration of the method. The task is assigned to the `integerTask` variable in the example. Because `integerTask` is a , it contains a property of type `TResult`. In this case, TResult represents an integer type. When `Await` is applied to `integerTask`, the await expression evaluates to the contents of the property of `integerTask`. The value is assigned to the `result2` variable. +You can better understand how this happens by separating the call to `TaskOfT_MethodAsync` from the application of `Await`, as the following code shows. A call to method `TaskOfT_MethodAsync` that isn't immediately awaited returns a `Task(Of Integer)`, as you would expect from the declaration of the method. The task is assigned to the `integerTask` variable in the example. Because `integerTask` is a , it contains a property of type `TResult`. In this case, TResult represents an integer type. When `Await` is applied to `integerTask`, the await expression evaluates to the contents of the property of `integerTask`. The value is assigned to the `result2` variable. > [!WARNING] -> The property is a blocking property. If you try to access it before its task is finished, the thread that's currently active is blocked until the task completes and the value is available. In most cases, you should access the value by using `Await` instead of accessing the property directly. +> The property is a blocking property. If you try to access it before its task is finished, the thread that's currently active is blocked until the task completes and the value is available. In most cases, you should access the value by using `Await` instead of accessing the property directly. ```vb ' Call and await in separate statements. @@ -105,7 +105,7 @@ The following code calls and awaits method `Task_MethodAsync`. Await Task_MethodAsync() ``` -As in the previous example, you can separate the call to `Task_MethodAsync` from the application of an `Await` operator, as the following code shows. However, remember that a `Task` doesn't have a `Result` property, and that no value is produced when an await operator is applied to a `Task`. +As in the previous example, you can separate the call to `Task_MethodAsync` from the application of an `Await` operator, as the following code shows. However, remember that a `Task` doesn't have a `Result` property, and that no value is produced when an await operator is applied to a `Task`. The following code separates calling `Task_MethodAsync` from awaiting the task that `Task_MethodAsync` returns. @@ -123,7 +123,7 @@ Await simpleTask The primary use of `Sub` procedures is in event handlers, where there is no return type (referred to as a void return type in other languages). A void return also can be used to override void-returning methods or for methods that perform activities that can be categorized as "fire and forget." However, you should return a `Task` wherever possible, because a void-returning async method can't be awaited. Any caller of such a method must be able to continue to completion without waiting for the called async method to finish, and the caller must be independent of any values or exceptions that the async method generates. -The caller of a void-returning async method can't catch exceptions that are thrown from the method, and such unhandled exceptions are likely to cause your application to fail. If an exception occurs in an async method that returns a or , the exception is stored in the returned task, and rethrown when the task is awaited. Therefore, make sure that any async method that can produce an exception has a return type of or and that calls to the method are awaited. +The caller of a void-returning async method can't catch exceptions that are thrown from the method, and such unhandled exceptions are likely to cause your application to fail. If an exception occurs in an async method that returns a or , the exception is stored in the returned task, and rethrown when the task is awaited. Therefore, make sure that any async method that can produce an exception has a return type of or and that calls to the method are awaited. For more information about how to catch exceptions in async methods, see [Try...Catch...Finally Statement](../../../language-reference/statements/try-catch-finally-statement.md). @@ -294,7 +294,7 @@ The following Windows Presentation Foundation (WPF) project contains the code ex ## See also -- +- - [Walkthrough: Accessing the Web by Using Async and Await (Visual Basic)](walkthrough-accessing-the-web-by-using-async-and-await.md) - [Control Flow in Async Programs (Visual Basic)](control-flow-in-async-programs.md) - [Async](../../../language-reference/modifiers/async.md) diff --git a/docs/visual-basic/programming-guide/concepts/async/cancel-an-async-task-or-a-list-of-tasks.md b/docs/visual-basic/programming-guide/concepts/async/cancel-an-async-task-or-a-list-of-tasks.md index 87e900259a761..6682f3249d58c 100644 --- a/docs/visual-basic/programming-guide/concepts/async/cancel-an-async-task-or-a-list-of-tasks.md +++ b/docs/visual-basic/programming-guide/concepts/async/cancel-an-async-task-or-a-list-of-tasks.md @@ -52,7 +52,7 @@ Then add the following changes to the MainWindow.xaml.vb file of that project. Dim cts As CancellationTokenSource ``` -2. Add the following event handler for the **Cancel** button. The event handler uses the method to notify `cts` when the user requests cancellation. +2. Add the following event handler for the **Cancel** button. The event handler uses the method to notify `cts` when the user requests cancellation. ```vb ' ***Add an event handler for the Cancel button. @@ -73,7 +73,7 @@ Then add the following changes to the MainWindow.xaml.vb file of that project. cts = New CancellationTokenSource() ``` - - In the call to `AccessTheWebAsync`, which downloads the contents of a specified website, send the property of `cts` as an argument. The `Token` property propagates the message if cancellation is requested. Add a catch block that displays a message if the user chooses to cancel the download operation. The following code shows the changes. + - In the call to `AccessTheWebAsync`, which downloads the contents of a specified website, send the property of `cts` as an argument. The `Token` property propagates the message if cancellation is requested. Add a catch block that displays a message if the user chooses to cancel the download operation. The following code shows the changes. ```vb Try @@ -204,7 +204,7 @@ To extend the example yourself, step by step, follow the instructions in the "Do Next ``` -4. Because `AccessTheWebAsync` displays the lengths, the method doesn't need to return anything. Remove the return statement, and change the return type of the method to instead of . +4. Because `AccessTheWebAsync` displays the lengths, the method doesn't need to return anything. Remove the return statement, and change the return type of the method to instead of . ```vb Async Function AccessTheWebAsync(ct As CancellationToken) As Task diff --git a/docs/visual-basic/programming-guide/concepts/async/cancel-async-tasks-after-a-period-of-time.md b/docs/visual-basic/programming-guide/concepts/async/cancel-async-tasks-after-a-period-of-time.md index 940adec29456b..34ba041040d55 100644 --- a/docs/visual-basic/programming-guide/concepts/async/cancel-async-tasks-after-a-period-of-time.md +++ b/docs/visual-basic/programming-guide/concepts/async/cancel-async-tasks-after-a-period-of-time.md @@ -6,7 +6,7 @@ ms.assetid: a48045a3-6a99-42af-b824-af340f0b9a5d --- # Cancel Async Tasks after a Period of Time (Visual Basic) -You can cancel an asynchronous operation after a period of time by using the method if you don't want to wait for the operation to finish. This method schedules the cancellation of any associated tasks that aren’t complete within the period of time that’s designated by the `CancelAfter` expression. +You can cancel an asynchronous operation after a period of time by using the method if you don't want to wait for the operation to finish. This method schedules the cancellation of any associated tasks that aren’t complete within the period of time that’s designated by the `CancelAfter` expression. This example adds to the code that’s developed in [Cancel an Async Task or a List of Tasks (Visual Basic)](cancel-an-async-task-or-a-list-of-tasks.md) to download a list of websites and to display the length of the contents of each one. diff --git a/docs/visual-basic/programming-guide/concepts/async/cancel-remaining-async-tasks-after-one-is-complete.md b/docs/visual-basic/programming-guide/concepts/async/cancel-remaining-async-tasks-after-one-is-complete.md index e2229748c14b5..c55f07de05869 100644 --- a/docs/visual-basic/programming-guide/concepts/async/cancel-remaining-async-tasks-after-one-is-complete.md +++ b/docs/visual-basic/programming-guide/concepts/async/cancel-remaining-async-tasks-after-one-is-complete.md @@ -6,7 +6,7 @@ ms.assetid: c928b5a1-622f-4441-8baf-adca1dde197f --- # Cancel Remaining Async Tasks after One Is Complete (Visual Basic) -By using the method together with a , you can cancel all remaining tasks when one task is complete. The `WhenAny` method takes an argument that’s a collection of tasks. The method starts all the tasks and returns a single task. The single task is complete when any task in the collection is complete. +By using the method together with a , you can cancel all remaining tasks when one task is complete. The `WhenAny` method takes an argument that’s a collection of tasks. The method starts all the tasks and returns a single task. The single task is complete when any task in the collection is complete. This example demonstrates how to use a cancellation token in conjunction with `WhenAny` to hold onto the first task to finish from the collection of tasks and to cancel the remaining tasks. Each task downloads the contents of a website. The example displays the length of the contents of the first download to complete and cancels the other downloads. @@ -55,13 +55,13 @@ Async Function ProcessURLAsync(url As String, client As HttpClient, ct As Cancel End Function ``` -In `AccessTheWebAsync`, this example uses a query, the method, and the `WhenAny` method to create and start an array of tasks. The application of `WhenAny` to the array returns a single task that, when awaited, evaluates to the first task to reach completion in the array of tasks. +In `AccessTheWebAsync`, this example uses a query, the method, and the `WhenAny` method to create and start an array of tasks. The application of `WhenAny` to the array returns a single task that, when awaited, evaluates to the first task to reach completion in the array of tasks. Make the following changes in `AccessTheWebAsync`. Asterisks mark the changes in the code file. 1. Comment out or delete the loop. -2. Create a query that, when executed, produces a collection of generic tasks. Each call to `ProcessURLAsync` returns a where `TResult` is an integer. +2. Create a query that, when executed, produces a collection of generic tasks. Each call to `ProcessURLAsync` returns a where `TResult` is an integer. ```vb ' ***Create a query that, when executed, returns a collection of tasks. @@ -76,7 +76,7 @@ Make the following changes in `AccessTheWebAsync`. Asterisks mark the changes in Dim downloadTasks As Task(Of Integer)() = downloadTasksQuery.ToArray() ``` -4. Call `WhenAny` on the collection of tasks. `WhenAny` returns a `Task(Of Task(Of Integer))` or `Task>`. That is, `WhenAny` returns a task that evaluates to a single `Task(Of Integer)` or `Task` when it’s awaited. That single task is the first task in the collection to finish. The task that finished first is assigned to `finishedTask`. The type of `finishedTask` is where `TResult` is an integer because that's the return type of `ProcessURLAsync`. +4. Call `WhenAny` on the collection of tasks. `WhenAny` returns a `Task(Of Task(Of Integer))` or `Task>`. That is, `WhenAny` returns a task that evaluates to a single `Task(Of Integer)` or `Task` when it’s awaited. That single task is the first task in the collection to finish. The task that finished first is assigned to `finishedTask`. The type of `finishedTask` is where `TResult` is an integer because that's the return type of `ProcessURLAsync`. ```vb ' ***Call WhenAny and then await the result. The task that finishes @@ -84,7 +84,7 @@ Make the following changes in `AccessTheWebAsync`. Asterisks mark the changes in Dim finishedTask As Task(Of Integer) = Await Task.WhenAny(downloadTasks) ``` -5. In this example, you’re interested only in the task that finishes first. Therefore, use to cancel the remaining tasks. +5. In this example, you’re interested only in the task that finishes first. Therefore, use to cancel the remaining tasks. ```vb ' ***Cancel the rest of the downloads. You just want the first one. @@ -233,7 +233,7 @@ End Class ## See also -- +- - [Fine-Tuning Your Async Application (Visual Basic)](fine-tuning-your-async-application.md) - [Asynchronous Programming with Async and Await (Visual Basic)](index.md) - [Async Sample: Fine Tuning Your Application](https://code.msdn.microsoft.com/Async-Fine-Tuning-Your-a676abea) diff --git a/docs/visual-basic/programming-guide/concepts/async/control-flow-in-async-programs.md b/docs/visual-basic/programming-guide/concepts/async/control-flow-in-async-programs.md index 255f8fe62169c..b57fc532cd482 100644 --- a/docs/visual-basic/programming-guide/concepts/async/control-flow-in-async-programs.md +++ b/docs/visual-basic/programming-guide/concepts/async/control-flow-in-async-programs.md @@ -253,7 +253,7 @@ The first two display lines trace the path as `startButton_Click` calls `AccessT ![Steps ONE and TWO](./media/control-flow-in-async-programs/asynctrace-onetwo.png "AsyncTrace-ONETWO") -The return type of both `AccessTheWebAsync` and `client.GetStringAsync` is . For `AccessTheWebAsync`, TResult is an integer. For `GetStringAsync`, TResult is a string. For more information about async method return types, see [Async Return Types (Visual Basic)](async-return-types.md). +The return type of both `AccessTheWebAsync` and `client.GetStringAsync` is . For `AccessTheWebAsync`, TResult is an integer. For `GetStringAsync`, TResult is a string. For more information about async method return types, see [Async Return Types (Visual Basic)](async-return-types.md). A task-returning async method returns a task instance when control shifts back to the caller. Control returns from an async method to its caller either when an `Await` operator is encountered in the called method or when the called method ends. The display lines that are labeled "THREE" through "SIX" trace this part of the process. diff --git a/docs/visual-basic/programming-guide/concepts/async/fine-tuning-your-async-application.md b/docs/visual-basic/programming-guide/concepts/async/fine-tuning-your-async-application.md index 76c812f2d10e5..db4eb1f9d611c 100644 --- a/docs/visual-basic/programming-guide/concepts/async/fine-tuning-your-async-application.md +++ b/docs/visual-basic/programming-guide/concepts/async/fine-tuning-your-async-application.md @@ -6,37 +6,37 @@ ms.assetid: 4c3e7997-a95f-4fbe-a6ac-60ba042d30b9 --- # Fine-Tuning Your Async Application (Visual Basic) -You can add precision and flexibility to your async applications by using the methods and properties that the type makes available. The topics in this section show examples that use and important `Task` methods such as and . - - By using `WhenAny` and `WhenAll`, you can more easily start multiple tasks and await their completion by monitoring a single task. - -- `WhenAny` returns a task that completes when any task in a collection is complete. - - For examples that use `WhenAny`, see [Cancel Remaining Async Tasks after One Is Complete (Visual Basic)](cancel-remaining-async-tasks-after-one-is-complete.md)and [Start Multiple Async Tasks and Process Them As They Complete (Visual Basic)](start-multiple-async-tasks-and-process-them-as-they-complete.md). - -- `WhenAll` returns a task that completes when all tasks in a collection are complete. - - For more information and an example that uses `WhenAll`, see [How to: Extend the Async Walkthrough by Using Task.WhenAll (Visual Basic)](how-to-extend-the-async-walkthrough-by-using-task-whenall.md). - - This section includes the following examples. - -- [Cancel an Async Task or a List of Tasks (Visual Basic)](cancel-an-async-task-or-a-list-of-tasks.md). - -- [Cancel Async Tasks after a Period of Time (Visual Basic)](cancel-async-tasks-after-a-period-of-time.md) - -- [Cancel Remaining Async Tasks after One Is Complete (Visual Basic)](cancel-remaining-async-tasks-after-one-is-complete.md) - -- [Start Multiple Async Tasks and Process Them As They Complete (Visual Basic)](start-multiple-async-tasks-and-process-them-as-they-complete.md) - +You can add precision and flexibility to your async applications by using the methods and properties that the type makes available. The topics in this section show examples that use and important `Task` methods such as and . + + By using `WhenAny` and `WhenAll`, you can more easily start multiple tasks and await their completion by monitoring a single task. + +- `WhenAny` returns a task that completes when any task in a collection is complete. + + For examples that use `WhenAny`, see [Cancel Remaining Async Tasks after One Is Complete (Visual Basic)](cancel-remaining-async-tasks-after-one-is-complete.md)and [Start Multiple Async Tasks and Process Them As They Complete (Visual Basic)](start-multiple-async-tasks-and-process-them-as-they-complete.md). + +- `WhenAll` returns a task that completes when all tasks in a collection are complete. + + For more information and an example that uses `WhenAll`, see [How to: Extend the Async Walkthrough by Using Task.WhenAll (Visual Basic)](how-to-extend-the-async-walkthrough-by-using-task-whenall.md). + + This section includes the following examples. + +- [Cancel an Async Task or a List of Tasks (Visual Basic)](cancel-an-async-task-or-a-list-of-tasks.md). + +- [Cancel Async Tasks after a Period of Time (Visual Basic)](cancel-async-tasks-after-a-period-of-time.md) + +- [Cancel Remaining Async Tasks after One Is Complete (Visual Basic)](cancel-remaining-async-tasks-after-one-is-complete.md) + +- [Start Multiple Async Tasks and Process Them As They Complete (Visual Basic)](start-multiple-async-tasks-and-process-them-as-they-complete.md) + > [!NOTE] -> To run the examples, you must have Visual Studio 2012 or newer and the .NET Framework 4.5 or newer installed on your computer. - - The projects create a UI that contains a button that starts the process and a button that cancels it, as the following image shows. The buttons are named `startButton` and `cancelButton`. - - ![WPF window with Cancel button](./media/fine-tuning-your-async-application/cancellation-and-start-button.png "Dialog box with a Start and Stop button") - - You can download the complete Windows Presentation Foundation (WPF) projects from [Async Sample: Fine Tuning Your Application](https://code.msdn.microsoft.com/Async-Fine-Tuning-Your-a676abea). - +> To run the examples, you must have Visual Studio 2012 or newer and the .NET Framework 4.5 or newer installed on your computer. + + The projects create a UI that contains a button that starts the process and a button that cancels it, as the following image shows. The buttons are named `startButton` and `cancelButton`. + + ![WPF window with Cancel button](./media/fine-tuning-your-async-application/cancellation-and-start-button.png "Dialog box with a Start and Stop button") + + You can download the complete Windows Presentation Foundation (WPF) projects from [Async Sample: Fine Tuning Your Application](https://code.msdn.microsoft.com/Async-Fine-Tuning-Your-a676abea). + ## See also - [Asynchronous Programming with Async and Await (Visual Basic)](index.md) diff --git a/docs/visual-basic/programming-guide/concepts/async/handling-reentrancy-in-async-apps.md b/docs/visual-basic/programming-guide/concepts/async/handling-reentrancy-in-async-apps.md index e4e86c329fa71..f4a0a5a6a0925 100644 --- a/docs/visual-basic/programming-guide/concepts/async/handling-reentrancy-in-async-apps.md +++ b/docs/visual-basic/programming-guide/concepts/async/handling-reentrancy-in-async-apps.md @@ -199,7 +199,7 @@ In `AccessTheWebAsync`, make the following changes. - Add a parameter to accept the cancellation token from `StartButton_Click`. -- Use the method to download the websites because `GetAsync` accepts a argument. +- Use the method to download the websites because `GetAsync` accepts a argument. - Before calling `DisplayResults` to display the results for each downloaded website, check `ct` to verify that the current operation hasn’t been canceled. @@ -403,7 +403,7 @@ End Sub #### The AccessTheWebAsync Method -This example splits `AccessTheWebAsync` into two methods. The first method, `AccessTheWebAsync`, starts all the download tasks for a group and sets up `pendingWork` to control the display process. The method uses a Language Integrated Query (LINQ query) and to start all the download tasks at the same time. +This example splits `AccessTheWebAsync` into two methods. The first method, `AccessTheWebAsync`, starts all the download tasks for a group and sets up `pendingWork` to control the display process. The method uses a Language Integrated Query (LINQ query) and to start all the download tasks at the same time. `AccessTheWebAsync` then calls `FinishOneGroupAsync` to await the completion of each download and display its length. diff --git a/docs/visual-basic/programming-guide/concepts/async/how-to-extend-the-async-walkthrough-by-using-task-whenall.md b/docs/visual-basic/programming-guide/concepts/async/how-to-extend-the-async-walkthrough-by-using-task-whenall.md index 994d81042d1fa..ed79a3596e89a 100644 --- a/docs/visual-basic/programming-guide/concepts/async/how-to-extend-the-async-walkthrough-by-using-task-whenall.md +++ b/docs/visual-basic/programming-guide/concepts/async/how-to-extend-the-async-walkthrough-by-using-task-whenall.md @@ -6,7 +6,7 @@ ms.assetid: c06d386d-e996-4da9-bf3d-05a3b6c0a258 --- # How to: Extend the Async Walkthrough by Using Task.WhenAll (Visual Basic) -You can improve the performance of the async solution in [Walkthrough: Accessing the Web by Using Async and Await (Visual Basic)](walkthrough-accessing-the-web-by-using-async-and-await.md) by using the method. This method asynchronously awaits multiple asynchronous operations, which are represented as a collection of tasks. +You can improve the performance of the async solution in [Walkthrough: Accessing the Web by Using Async and Await (Visual Basic)](walkthrough-accessing-the-web-by-using-async-and-await.md) by using the method. This method asynchronously awaits multiple asynchronous operations, which are represented as a collection of tasks. You might have noticed in the walkthrough that the websites download at different rates. Sometimes one of the websites is very slow, which delays all the remaining downloads. When you run the asynchronous solutions that you build in the walkthrough, you can end the program easily if you don't want to wait, but a better option would be to start all the downloads at the same time and let faster downloads continue without waiting for the one that’s delayed. @@ -58,7 +58,7 @@ You apply the `Task.WhenAll` method to a collection of tasks. The application of 'Next ``` -3. Create a collection of tasks. The following code defines a [query](../linq/index.md) that, when executed by the method, creates a collection of tasks that download the contents of each website. The tasks are started when the query is evaluated. +3. Create a collection of tasks. The following code defines a [query](../linq/index.md) that, when executed by the method, creates a collection of tasks that download the contents of each website. The tasks are started when the query is evaluated. Add the following code to method `SumPageSizesAsync` after the declaration of `urlList`. @@ -84,7 +84,7 @@ You apply the `Task.WhenAll` method to a collection of tasks. The application of 'Dim lengths As Integer() = Await whenAllTask ``` -5. Finally, use the method to calculate the sum of the lengths of all the websites. Add the following line to `SumPageSizesAsync`. +5. Finally, use the method to calculate the sum of the lengths of all the websites. Add the following line to `SumPageSizesAsync`. ```vb Dim total = lengths.Sum() @@ -131,7 +131,7 @@ You apply the `Task.WhenAll` method to a collection of tasks. The application of 'Next ``` -3. Define a [query](../linq/index.md) that, when executed by the method, creates a collection of tasks that download the contents of each website. The tasks are started when the query is evaluated. +3. Define a [query](../linq/index.md) that, when executed by the method, creates a collection of tasks that download the contents of each website. The tasks are started when the query is evaluated. Add the following code to method `SumPageSizesAsync` after the declaration of `client` and `urlList`. @@ -157,7 +157,7 @@ You apply the `Task.WhenAll` method to a collection of tasks. The application of 'Dim lengths As Integer() = Await whenAllTask ``` -5. Finally, use the method to get the sum of the lengths of all the websites. Add the following line to `SumPageSizesAsync`. +5. Finally, use the method to get the sum of the lengths of all the websites. Add the following line to `SumPageSizesAsync`. ```vb Dim total = lengths.Sum() @@ -419,5 +419,5 @@ End Class ## See also -- +- - [Walkthrough: Accessing the Web by Using Async and Await (Visual Basic)](walkthrough-accessing-the-web-by-using-async-and-await.md) diff --git a/docs/visual-basic/programming-guide/concepts/async/how-to-make-multiple-web-requests-in-parallel-by-using-async-and-await.md b/docs/visual-basic/programming-guide/concepts/async/how-to-make-multiple-web-requests-in-parallel-by-using-async-and-await.md index 03963668f53f7..60cb51471b10a 100644 --- a/docs/visual-basic/programming-guide/concepts/async/how-to-make-multiple-web-requests-in-parallel-by-using-async-and-await.md +++ b/docs/visual-basic/programming-guide/concepts/async/how-to-make-multiple-web-requests-in-parallel-by-using-async-and-await.md @@ -92,9 +92,9 @@ You can download the code for this example from [Developer Code Samples](https:/ 4. Finally, define method `CreateMultipleTasksAsync`, which performs the following steps. - - The method declares an `HttpClient` object,which you need to access method in `ProcessURLAsync`. + - The method declares an `HttpClient` object,which you need to access method in `ProcessURLAsync`. - - The method creates and starts three tasks of type , where `TResult` is an integer. As each task finishes, `DisplayResults` displays the task's URL and the length of the downloaded contents. Because the tasks are running asynchronously, the order in which the results appear might differ from the order in which they were declared. + - The method creates and starts three tasks of type , where `TResult` is an integer. As each task finishes, `DisplayResults` displays the task's URL and the length of the downloaded contents. Because the tasks are running asynchronously, the order in which the results appear might differ from the order in which they were declared. - The method awaits the completion of each task. Each `Await` operator suspends execution of `CreateMultipleTasksAsync` until the awaited task is finished. The operator also retrieves the return value from the call to `ProcessURLAsync` from each completed task. diff --git a/docs/visual-basic/programming-guide/concepts/async/index.md b/docs/visual-basic/programming-guide/concepts/async/index.md index 0cbbf699d8d8a..c8e52288b498a 100644 --- a/docs/visual-basic/programming-guide/concepts/async/index.md +++ b/docs/visual-basic/programming-guide/concepts/async/index.md @@ -127,7 +127,7 @@ The previous code revisions help get everything ready for breakfast at the same > [!IMPORTANT] > The composition of an asynchronous operation followed by synchronous work is an asynchronous operation. Stated another way, if any portion of an operation is asynchronous, the entire operation is asynchronous. -In the previous updates, you learned how to use or objects to hold running tasks. You wait on each task before you use its result. The next step is to create methods that represent the combination of other work. Before you serve breakfast, you want to wait on the task that represents toasting the bread before you spread the butter and jam. +In the previous updates, you learned how to use or objects to hold running tasks. You wait on each task before you use its result. The next step is to create methods that represent the combination of other work. Before you serve breakfast, you want to wait on the task that represents toasting the bread before you spread the butter and jam. You can represent this work with the following code: @@ -141,7 +141,7 @@ Async Function MakeToastWithButterAndJamAsync(number As Integer) As Task(Of Toas End Function ``` -The `MakeToastWithButterAndJamAsync` method has the `Async` modifier in its signature that signals to the compiler that the method contains an `Await` expression and contains asynchronous operations. The method represents the task that toasts the bread, then spreads the butter and jam. The method returns a object that represents the composition of the three operations. +The `MakeToastWithButterAndJamAsync` method has the `Async` modifier in its signature that signals to the compiler that the method contains an `Await` expression and contains asynchronous operations. The method represents the task that toasts the bread, then spreads the butter and jam. The method returns a object that represents the composition of the three operations. The revised main block of code now looks like this: @@ -248,7 +248,7 @@ Before you continue to the next section, comment out the following two statement ## Efficiently apply await expressions to tasks -You can improve the series of `Await` expressions at the end of the previous code by using methods of the class. One API is the method, which returns a object that completes when all the tasks in its argument list are complete. The following code demonstrates this method: +You can improve the series of `Await` expressions at the end of the previous code by using methods of the class. One API is the method, which returns a object that completes when all the tasks in its argument list are complete. The following code demonstrates this method: ```vb Await Task.WhenAll(eggsTask, hashBrownTask, toastTask) @@ -258,7 +258,7 @@ Console.WriteLine("Toast is ready") Console.WriteLine("Breakfast is ready!") ``` -Another option is to use the method, which returns a `Task(Of Task)` object that completes when any of its arguments complete. You can wait on the returned task because you know the task is done. The following code shows how you can use the method to wait on the first task to finish and then process its result. After you process the result from the completed task, you remove the completed task from the list of tasks passed to the `WhenAny` method. +Another option is to use the method, which returns a `Task(Of Task)` object that completes when any of its arguments complete. You can wait on the returned task because you know the task is done. The following code shows how you can use the method to wait on the first task to finish and then process its result. After you process the result from the completed task, you remove the completed task from the list of tasks passed to the `WhenAny` method. :::code language="vb" source="snippets/breakfast/ConcurrentBreakfast.vb" id="ConcurrentBreakfast"::: @@ -278,7 +278,7 @@ The final code is asynchronous. It more accurately reflects how a person might c ## Async/await vs ContinueWith -The `Async` and `Await` keywords provide syntactic simplification over using directly. While `Async`/`Await` and `ContinueWith` have similar semantics for handling asynchronous operations, the compiler doesn't necessarily translate `Await` expressions directly into `ContinueWith` method calls. Instead, the compiler generates optimized state machine code that provides the same logical behavior. This transformation provides significant readability and maintainability benefits, especially when chaining multiple asynchronous operations. +The `Async` and `Await` keywords provide syntactic simplification over using directly. While `Async`/`Await` and `ContinueWith` have similar semantics for handling asynchronous operations, the compiler doesn't necessarily translate `Await` expressions directly into `ContinueWith` method calls. Instead, the compiler generates optimized state machine code that provides the same logical behavior. This transformation provides significant readability and maintainability benefits, especially when chaining multiple asynchronous operations. Consider a scenario where you need to perform multiple sequential asynchronous operations. Here's how the same logic looks when implemented by using `ContinueWith` compared to `Async`/`Await`: @@ -330,16 +330,16 @@ The same sequence of operations using `Async`/`Await` reads much more naturally: Async Function MakeBreakfastWithAsyncAwait() As Task Dim eggs = Await StartCookingEggsAsync() Console.WriteLine("Eggs ready, starting bacon...") - + Dim bacon = Await StartCookingBaconAsync() Console.WriteLine("Bacon ready, starting toast...") - + Dim toast = Await StartToastingBreadAsync() Console.WriteLine("Toast ready, applying butter...") - + Dim butteredToast = Await ApplyButterAsync(toast) Console.WriteLine("Butter applied, applying jam...") - + Dim finalToast = Await ApplyJamAsync(butteredToast) Console.WriteLine("Breakfast completed with Async/Await!") End Function diff --git a/docs/visual-basic/programming-guide/concepts/async/start-multiple-async-tasks-and-process-them-as-they-complete.md b/docs/visual-basic/programming-guide/concepts/async/start-multiple-async-tasks-and-process-them-as-they-complete.md index c9625a3bf94b5..fc5449a8ffb3b 100644 --- a/docs/visual-basic/programming-guide/concepts/async/start-multiple-async-tasks-and-process-them-as-they-complete.md +++ b/docs/visual-basic/programming-guide/concepts/async/start-multiple-async-tasks-and-process-them-as-they-complete.md @@ -6,207 +6,207 @@ ms.assetid: 57ffb748-af40-4794-bedd-bdb7fea062de --- # Start Multiple Async Tasks and Process Them As They Complete (Visual Basic) -By using , you can start multiple tasks at the same time and process them one by one as they’re completed rather than process them in the order in which they're started. - - The following example uses a query to create a collection of tasks. Each task downloads the contents of a specified website. In each iteration of a while loop, an awaited call to `WhenAny` returns the task in the collection of tasks that finishes its download first. That task is removed from the collection and processed. The loop repeats until the collection contains no more tasks. - +By using , you can start multiple tasks at the same time and process them one by one as they’re completed rather than process them in the order in which they're started. + + The following example uses a query to create a collection of tasks. Each task downloads the contents of a specified website. In each iteration of a while loop, an awaited call to `WhenAny` returns the task in the collection of tasks that finishes its download first. That task is removed from the collection and processed. The loop repeats until the collection contains no more tasks. + > [!NOTE] -> To run the examples, you must have Visual Studio 2012 or newer and the .NET Framework 4.5 or newer installed on your computer. - -## Downloading the Example - - You can download the complete Windows Presentation Foundation (WPF) project from [Async Sample: Fine Tuning Your Application](https://code.msdn.microsoft.com/Async-Fine-Tuning-Your-a676abea) and then follow these steps. - -1. Decompress the file that you downloaded, and then start Visual Studio. - -2. On the menu bar, choose **File**, **Open**, **Project/Solution**. - -3. In the **Open Project** dialog box, open the folder that holds the sample code that you decompressed, and then open the solution (.sln) file for AsyncFineTuningVB. - -4. In **Solution Explorer**, open the shortcut menu for the **ProcessTasksAsTheyFinish** project, and then choose **Set as StartUp Project**. - -5. Choose the F5 key to run the project. - - Choose the Ctrl+F5 keys to run the project without debugging it. - -6. Run the project several times to verify that the downloaded lengths don't always appear in the same order. - - If you don't want to download the project, you can review the MainWindow.xaml.vb file at the end of this topic. - -## Building the Example - - This example adds to the code that’s developed in [Cancel Remaining Async Tasks after One Is Complete (Visual Basic)](cancel-remaining-async-tasks-after-one-is-complete.md) and uses the same UI. - - To build the example yourself, step by step, follow the instructions in the "Downloading the Example" section, but choose **CancelAfterOneTask** as the **StartUp Project**. Add the changes in this topic to the `AccessTheWebAsync` method in that project. The changes are marked with asterisks. - - The **CancelAfterOneTask** project already includes a query that, when executed, creates a collection of tasks. Each call to `ProcessURLAsync` in the following code returns a where `TResult` is an integer. - -```vb -Dim downloadTasksQuery As IEnumerable(Of Task(Of Integer)) = - From url In urlList Select ProcessURLAsync(url, client, ct) -``` - - In the MainWindow.xaml.vb file of the project, make the following changes to the `AccessTheWebAsync` method. - -- Execute the query by applying instead of . - - ```vb - Dim downloadTasks As List(Of Task(Of Integer)) = downloadTasksQuery.ToList() - ``` - -- Add a while loop that performs the following steps for each task in the collection. - - 1. Awaits a call to `WhenAny` to identify the first task in the collection to finish its download. - - ```vb - Dim finishedTask As Task(Of Integer) = Await Task.WhenAny(downloadTasks) - ``` - - 2. Removes that task from the collection. - - ```vb - downloadTasks.Remove(finishedTask) - ``` - - 3. Awaits `finishedTask`, which is returned by a call to `ProcessURLAsync`. The `finishedTask` variable is a where `TReturn` is an integer. The task is already complete, but you await it to retrieve the length of the downloaded website, as the following example shows. - - ```vb - Dim length = Await finishedTask - resultsTextBox.Text &= String.Format(vbCrLf & "Length of the downloaded website: {0}" & vbCrLf, length) - ``` - - You should run the project several times to verify that the downloaded lengths don't always appear in the same order. - +> To run the examples, you must have Visual Studio 2012 or newer and the .NET Framework 4.5 or newer installed on your computer. + +## Downloading the Example + + You can download the complete Windows Presentation Foundation (WPF) project from [Async Sample: Fine Tuning Your Application](https://code.msdn.microsoft.com/Async-Fine-Tuning-Your-a676abea) and then follow these steps. + +1. Decompress the file that you downloaded, and then start Visual Studio. + +2. On the menu bar, choose **File**, **Open**, **Project/Solution**. + +3. In the **Open Project** dialog box, open the folder that holds the sample code that you decompressed, and then open the solution (.sln) file for AsyncFineTuningVB. + +4. In **Solution Explorer**, open the shortcut menu for the **ProcessTasksAsTheyFinish** project, and then choose **Set as StartUp Project**. + +5. Choose the F5 key to run the project. + + Choose the Ctrl+F5 keys to run the project without debugging it. + +6. Run the project several times to verify that the downloaded lengths don't always appear in the same order. + + If you don't want to download the project, you can review the MainWindow.xaml.vb file at the end of this topic. + +## Building the Example + + This example adds to the code that’s developed in [Cancel Remaining Async Tasks after One Is Complete (Visual Basic)](cancel-remaining-async-tasks-after-one-is-complete.md) and uses the same UI. + + To build the example yourself, step by step, follow the instructions in the "Downloading the Example" section, but choose **CancelAfterOneTask** as the **StartUp Project**. Add the changes in this topic to the `AccessTheWebAsync` method in that project. The changes are marked with asterisks. + + The **CancelAfterOneTask** project already includes a query that, when executed, creates a collection of tasks. Each call to `ProcessURLAsync` in the following code returns a where `TResult` is an integer. + +```vb +Dim downloadTasksQuery As IEnumerable(Of Task(Of Integer)) = + From url In urlList Select ProcessURLAsync(url, client, ct) +``` + + In the MainWindow.xaml.vb file of the project, make the following changes to the `AccessTheWebAsync` method. + +- Execute the query by applying instead of . + + ```vb + Dim downloadTasks As List(Of Task(Of Integer)) = downloadTasksQuery.ToList() + ``` + +- Add a while loop that performs the following steps for each task in the collection. + + 1. Awaits a call to `WhenAny` to identify the first task in the collection to finish its download. + + ```vb + Dim finishedTask As Task(Of Integer) = Await Task.WhenAny(downloadTasks) + ``` + + 2. Removes that task from the collection. + + ```vb + downloadTasks.Remove(finishedTask) + ``` + + 3. Awaits `finishedTask`, which is returned by a call to `ProcessURLAsync`. The `finishedTask` variable is a where `TReturn` is an integer. The task is already complete, but you await it to retrieve the length of the downloaded website, as the following example shows. + + ```vb + Dim length = Await finishedTask + resultsTextBox.Text &= String.Format(vbCrLf & "Length of the downloaded website: {0}" & vbCrLf, length) + ``` + + You should run the project several times to verify that the downloaded lengths don't always appear in the same order. + > [!CAUTION] -> You can use `WhenAny` in a loop, as described in the example, to solve problems that involve a small number of tasks. However, other approaches are more efficient if you have a large number of tasks to process. For more information and examples, see [Processing Tasks as they complete](https://devblogs.microsoft.com/pfxteam/processing-tasks-as-they-complete/). - -## Complete Example - - The following code is the complete text of the MainWindow.xaml.vb file for the example. Asterisks mark the elements that were added for this example. - - Notice that you must add a reference for . - - You can download the project from [Async Sample: Fine Tuning Your Application](https://code.msdn.microsoft.com/Async-Fine-Tuning-Your-a676abea). - -```vb -' Add an Imports directive and a reference for System.Net.Http. -Imports System.Net.Http - -' Add the following Imports directive for System.Threading. -Imports System.Threading - -Class MainWindow - - ' Declare a System.Threading.CancellationTokenSource. - Dim cts As CancellationTokenSource - - Private Async Sub startButton_Click(sender As Object, e As RoutedEventArgs) - - ' Instantiate the CancellationTokenSource. - cts = New CancellationTokenSource() - - resultsTextBox.Clear() - - Try - Await AccessTheWebAsync(cts.Token) - resultsTextBox.Text &= vbCrLf & "Downloads complete." - - Catch ex As OperationCanceledException - resultsTextBox.Text &= vbCrLf & "Downloads canceled." & vbCrLf - - Catch ex As Exception - resultsTextBox.Text &= vbCrLf & "Downloads failed." & vbCrLf - End Try - - ' Set the CancellationTokenSource to Nothing when the download is complete. - cts = Nothing - End Sub - - ' You can still include a Cancel button if you want to. - Private Sub cancelButton_Click(sender As Object, e As RoutedEventArgs) - - If cts IsNot Nothing Then - cts.Cancel() - End If - End Sub - - ' Provide a parameter for the CancellationToken. - ' Change the return type to Task because the method has no return statement. - Async Function AccessTheWebAsync(ct As CancellationToken) As Task - - Dim client As HttpClient = New HttpClient() - - ' Call SetUpURLList to make a list of web addresses. - Dim urlList As List(Of String) = SetUpURLList() - - ' ***Create a query that, when executed, returns a collection of tasks. - Dim downloadTasksQuery As IEnumerable(Of Task(Of Integer)) = - From url In urlList Select ProcessURLAsync(url, client, ct) - +> You can use `WhenAny` in a loop, as described in the example, to solve problems that involve a small number of tasks. However, other approaches are more efficient if you have a large number of tasks to process. For more information and examples, see [Processing Tasks as they complete](https://devblogs.microsoft.com/pfxteam/processing-tasks-as-they-complete/). + +## Complete Example + + The following code is the complete text of the MainWindow.xaml.vb file for the example. Asterisks mark the elements that were added for this example. + + Notice that you must add a reference for . + + You can download the project from [Async Sample: Fine Tuning Your Application](https://code.msdn.microsoft.com/Async-Fine-Tuning-Your-a676abea). + +```vb +' Add an Imports directive and a reference for System.Net.Http. +Imports System.Net.Http + +' Add the following Imports directive for System.Threading. +Imports System.Threading + +Class MainWindow + + ' Declare a System.Threading.CancellationTokenSource. + Dim cts As CancellationTokenSource + + Private Async Sub startButton_Click(sender As Object, e As RoutedEventArgs) + + ' Instantiate the CancellationTokenSource. + cts = New CancellationTokenSource() + + resultsTextBox.Clear() + + Try + Await AccessTheWebAsync(cts.Token) + resultsTextBox.Text &= vbCrLf & "Downloads complete." + + Catch ex As OperationCanceledException + resultsTextBox.Text &= vbCrLf & "Downloads canceled." & vbCrLf + + Catch ex As Exception + resultsTextBox.Text &= vbCrLf & "Downloads failed." & vbCrLf + End Try + + ' Set the CancellationTokenSource to Nothing when the download is complete. + cts = Nothing + End Sub + + ' You can still include a Cancel button if you want to. + Private Sub cancelButton_Click(sender As Object, e As RoutedEventArgs) + + If cts IsNot Nothing Then + cts.Cancel() + End If + End Sub + + ' Provide a parameter for the CancellationToken. + ' Change the return type to Task because the method has no return statement. + Async Function AccessTheWebAsync(ct As CancellationToken) As Task + + Dim client As HttpClient = New HttpClient() + + ' Call SetUpURLList to make a list of web addresses. + Dim urlList As List(Of String) = SetUpURLList() + + ' ***Create a query that, when executed, returns a collection of tasks. + Dim downloadTasksQuery As IEnumerable(Of Task(Of Integer)) = + From url In urlList Select ProcessURLAsync(url, client, ct) + ' ***Use ToList to execute the query and start the download tasks. - Dim downloadTasks As List(Of Task(Of Integer)) = downloadTasksQuery.ToList() - - ' ***Add a loop to process the tasks one at a time until none remain. - While downloadTasks.Count > 0 - ' ***Identify the first task that completes. - Dim finishedTask As Task(Of Integer) = Await Task.WhenAny(downloadTasks) - - ' ***Remove the selected task from the list so that you don't - ' process it more than once. - downloadTasks.Remove(finishedTask) - - ' ***Await the first completed task and display the results. - Dim length = Await finishedTask - resultsTextBox.Text &= String.Format(vbCrLf & "Length of the downloaded website: {0}" & vbCrLf, length) - End While - - End Function - - ' Bundle the processing steps for a website into one async method. - Async Function ProcessURLAsync(url As String, client As HttpClient, ct As CancellationToken) As Task(Of Integer) - + Dim downloadTasks As List(Of Task(Of Integer)) = downloadTasksQuery.ToList() + + ' ***Add a loop to process the tasks one at a time until none remain. + While downloadTasks.Count > 0 + ' ***Identify the first task that completes. + Dim finishedTask As Task(Of Integer) = Await Task.WhenAny(downloadTasks) + + ' ***Remove the selected task from the list so that you don't + ' process it more than once. + downloadTasks.Remove(finishedTask) + + ' ***Await the first completed task and display the results. + Dim length = Await finishedTask + resultsTextBox.Text &= String.Format(vbCrLf & "Length of the downloaded website: {0}" & vbCrLf, length) + End While + + End Function + + ' Bundle the processing steps for a website into one async method. + Async Function ProcessURLAsync(url As String, client As HttpClient, ct As CancellationToken) As Task(Of Integer) + ' GetAsync returns a Task(Of HttpResponseMessage). - Dim response As HttpResponseMessage = Await client.GetAsync(url, ct) - - ' Retrieve the website contents from the HttpResponseMessage. - Dim urlContents As Byte() = Await response.Content.ReadAsByteArrayAsync() - - Return urlContents.Length - End Function - - ' Add a method that creates a list of web addresses. - Private Function SetUpURLList() As List(Of String) - - Dim urls = New List(Of String) From - { - "https://msdn.microsoft.com", - "https://msdn.microsoft.com/library/hh290138.aspx", - "https://msdn.microsoft.com/library/hh290140.aspx", - "https://msdn.microsoft.com/library/dd470362.aspx", - "https://msdn.microsoft.com/library/aa578028.aspx", - "https://msdn.microsoft.com/library/ms404677.aspx", - "https://msdn.microsoft.com/library/ff730837.aspx" - } - Return urls - End Function - -End Class - -' Sample output: - -' Length of the download: 226093 -' Length of the download: 412588 -' Length of the download: 175490 -' Length of the download: 204890 -' Length of the download: 158855 -' Length of the download: 145790 -' Length of the download: 44908 -' Downloads complete. -``` - + Dim response As HttpResponseMessage = Await client.GetAsync(url, ct) + + ' Retrieve the website contents from the HttpResponseMessage. + Dim urlContents As Byte() = Await response.Content.ReadAsByteArrayAsync() + + Return urlContents.Length + End Function + + ' Add a method that creates a list of web addresses. + Private Function SetUpURLList() As List(Of String) + + Dim urls = New List(Of String) From + { + "https://msdn.microsoft.com", + "https://msdn.microsoft.com/library/hh290138.aspx", + "https://msdn.microsoft.com/library/hh290140.aspx", + "https://msdn.microsoft.com/library/dd470362.aspx", + "https://msdn.microsoft.com/library/aa578028.aspx", + "https://msdn.microsoft.com/library/ms404677.aspx", + "https://msdn.microsoft.com/library/ff730837.aspx" + } + Return urls + End Function + +End Class + +' Sample output: + +' Length of the download: 226093 +' Length of the download: 412588 +' Length of the download: 175490 +' Length of the download: 204890 +' Length of the download: 158855 +' Length of the download: 145790 +' Length of the download: 44908 +' Downloads complete. +``` + ## See also -- +- - [Fine-Tuning Your Async Application (Visual Basic)](fine-tuning-your-async-application.md) - [Asynchronous Programming with Async and Await (Visual Basic)](index.md) - [Async Sample: Fine Tuning Your Application](https://code.msdn.microsoft.com/Async-Fine-Tuning-Your-a676abea) diff --git a/docs/visual-basic/programming-guide/concepts/async/using-async-for-file-access.md b/docs/visual-basic/programming-guide/concepts/async/using-async-for-file-access.md index 7d9de88359a50..fc6e72cbe48eb 100644 --- a/docs/visual-basic/programming-guide/concepts/async/using-async-for-file-access.md +++ b/docs/visual-basic/programming-guide/concepts/async/using-async-for-file-access.md @@ -6,161 +6,161 @@ ms.assetid: c989305f-08e3-4687-95c3-948465cda202 --- # Using Async for File Access (Visual Basic) -You can use the Async feature to access files. By using the Async feature, you can call into asynchronous methods without using callbacks or splitting your code across multiple methods or lambda expressions. To make synchronous code asynchronous, you just call an asynchronous method instead of a synchronous method and add a few keywords to the code. - - You might consider the following reasons for adding asynchrony to file access calls: - -- Asynchrony makes UI applications more responsive because the UI thread that launches the operation can perform other work. If the UI thread must execute code that takes a long time (for example, more than 50 milliseconds), the UI may freeze until the I/O is complete and the UI thread can again process keyboard and mouse input and other events. - -- Asynchrony improves the scalability of ASP.NET and other server-based applications by reducing the need for threads. If the application uses a dedicated thread per response and a thousand requests are being handled simultaneously, a thousand threads are needed. Asynchronous operations often don’t need to use a thread during the wait. They use the existing I/O completion thread briefly at the end. - -- The latency of a file access operation might be very low under current conditions, but the latency may greatly increase in the future. For example, a file may be moved to a server that's across the world. - -- The added overhead of using the Async feature is small. - -- Asynchronous tasks can easily be run in parallel. - -## Running the Examples - - To run the examples in this topic, you can create a **WPF Application** or a **Windows Forms Application** and then add a **Button**. In the button's `Click` event, add a call to the first method in each example. - - In the following examples, include the following `Imports` statements. - -```vb -Imports System -Imports System.Collections.Generic -Imports System.Diagnostics -Imports System.IO -Imports System.Text -Imports System.Threading.Tasks -``` - -## Use of the FileStream Class - - The examples in this topic use the class, which has an option that causes asynchronous I/O to occur at the operating system level. By using this option, you can avoid blocking a ThreadPool thread in many cases. To enable this option, you specify the `useAsync=true` or `options=FileOptions.Asynchronous` argument in the constructor call. - - You can’t use this option with and if you open them directly by specifying a file path. However, you can use this option if you provide them a that the class opened. Note that asynchronous calls are faster in UI apps even if a ThreadPool thread is blocked, because the UI thread isn’t blocked during the wait. - -## Writing Text - - The following example writes text to a file. At each await statement, the method immediately exits. When the file I/O is complete, the method resumes at the statement that follows the await statement. Note that the async modifier is in the definition of methods that use the await statement. - -```vb -Public Async Sub ProcessWrite() - Dim filePath = "temp2.txt" - Dim text = "Hello World" & ControlChars.CrLf - - Await WriteTextAsync(filePath, text) -End Sub - -Private Async Function WriteTextAsync(filePath As String, text As String) As Task - Dim encodedText As Byte() = Encoding.Unicode.GetBytes(text) - - Using sourceStream As New FileStream(filePath, - FileMode.Append, FileAccess.Write, FileShare.None, - bufferSize:=4096, useAsync:=True) - - Await sourceStream.WriteAsync(encodedText, 0, encodedText.Length) - End Using -End Function -``` - - The original example has the statement `Await sourceStream.WriteAsync(encodedText, 0, encodedText.Length)`, which is a contraction of the following two statements: - -```vb -Dim theTask As Task = sourceStream.WriteAsync(encodedText, 0, encodedText.Length) -Await theTask -``` - - The first statement returns a task and causes file processing to start. The second statement with the await causes the method to immediately exit and return a different task. When the file processing later completes, execution returns to the statement that follows the await. For more information, see [Control Flow in Async Programs (Visual Basic)](control-flow-in-async-programs.md). - -## Reading Text - - The following example reads text from a file. The text is buffered and, in this case, placed into a . Unlike in the previous example, the evaluation of the await produces a value. The method returns a \<>, so the evaluation of the await produces an `Int32` value (`numRead`) after the operation completes. For more information, see [Async Return Types (Visual Basic)](async-return-types.md). - -```vb -Public Async Sub ProcessRead() - Dim filePath = "temp2.txt" - - If File.Exists(filePath) = False Then - Debug.WriteLine("file not found: " & filePath) - Else - Try - Dim text As String = Await ReadTextAsync(filePath) - Debug.WriteLine(text) - Catch ex As Exception - Debug.WriteLine(ex.Message) - End Try - End If -End Sub - -Private Async Function ReadTextAsync(filePath As String) As Task(Of String) - - Using sourceStream As New FileStream(filePath, - FileMode.Open, FileAccess.Read, FileShare.Read, - bufferSize:=4096, useAsync:=True) - - Dim sb As New StringBuilder - - Dim buffer As Byte() = New Byte(&H1000) {} - Dim numRead As Integer - numRead = Await sourceStream.ReadAsync(buffer, 0, buffer.Length) - While numRead <> 0 - Dim text As String = Encoding.Unicode.GetString(buffer, 0, numRead) - sb.Append(text) - - numRead = Await sourceStream.ReadAsync(buffer, 0, buffer.Length) - End While - - Return sb.ToString - End Using -End Function -``` - -## Parallel Asynchronous I/O - - The following example demonstrates parallel processing by writing 10 text files. For each file, the method returns a task that is then added to a list of tasks. The `Await Task.WhenAll(tasks)` statement exits the method and resumes within the method when file processing is complete for all of the tasks. - - The example closes all instances in a `Finally` block after the tasks are complete. If each `FileStream` was instead created in an `Imports` statement, the `FileStream` might be disposed of before the task was complete. - - Note that any performance boost is almost entirely from the parallel processing and not the asynchronous processing. The advantages of asynchrony are that it doesn’t tie up multiple threads, and that it doesn’t tie up the user interface thread. - -```vb -Public Async Sub ProcessWriteMult() - Dim folder = "tempfolder\" - Dim tasks As New List(Of Task) - Dim sourceStreams As New List(Of FileStream) - - Try - For index = 1 To 10 - Dim text = "In file " & index.ToString & ControlChars.CrLf - - Dim fileName = "thefile" & index.ToString("00") & ".txt" - Dim filePath = folder & fileName - - Dim encodedText As Byte() = Encoding.Unicode.GetBytes(text) - - Dim sourceStream As New FileStream(filePath, - FileMode.Append, FileAccess.Write, FileShare.None, - bufferSize:=4096, useAsync:=True) - - Dim theTask As Task = sourceStream.WriteAsync(encodedText, 0, encodedText.Length) - sourceStreams.Add(sourceStream) - - tasks.Add(theTask) - Next - - Await Task.WhenAll(tasks) - Finally - For Each sourceStream As FileStream In sourceStreams - sourceStream.Close() - Next - End Try -End Sub -``` - - When using the and methods, you can specify a , which you can use to cancel the operation mid-stream. For more information, see [Fine-Tuning Your Async Application (Visual Basic)](fine-tuning-your-async-application.md) and [Cancellation in Managed Threads](../../../../standard/threading/cancellation-in-managed-threads.md). - +You can use the Async feature to access files. By using the Async feature, you can call into asynchronous methods without using callbacks or splitting your code across multiple methods or lambda expressions. To make synchronous code asynchronous, you just call an asynchronous method instead of a synchronous method and add a few keywords to the code. + + You might consider the following reasons for adding asynchrony to file access calls: + +- Asynchrony makes UI applications more responsive because the UI thread that launches the operation can perform other work. If the UI thread must execute code that takes a long time (for example, more than 50 milliseconds), the UI may freeze until the I/O is complete and the UI thread can again process keyboard and mouse input and other events. + +- Asynchrony improves the scalability of ASP.NET and other server-based applications by reducing the need for threads. If the application uses a dedicated thread per response and a thousand requests are being handled simultaneously, a thousand threads are needed. Asynchronous operations often don’t need to use a thread during the wait. They use the existing I/O completion thread briefly at the end. + +- The latency of a file access operation might be very low under current conditions, but the latency may greatly increase in the future. For example, a file may be moved to a server that's across the world. + +- The added overhead of using the Async feature is small. + +- Asynchronous tasks can easily be run in parallel. + +## Running the Examples + + To run the examples in this topic, you can create a **WPF Application** or a **Windows Forms Application** and then add a **Button**. In the button's `Click` event, add a call to the first method in each example. + + In the following examples, include the following `Imports` statements. + +```vb +Imports System +Imports System.Collections.Generic +Imports System.Diagnostics +Imports System.IO +Imports System.Text +Imports System.Threading.Tasks +``` + +## Use of the FileStream Class + + The examples in this topic use the class, which has an option that causes asynchronous I/O to occur at the operating system level. By using this option, you can avoid blocking a ThreadPool thread in many cases. To enable this option, you specify the `useAsync=true` or `options=FileOptions.Asynchronous` argument in the constructor call. + + You can’t use this option with and if you open them directly by specifying a file path. However, you can use this option if you provide them a that the class opened. Note that asynchronous calls are faster in UI apps even if a ThreadPool thread is blocked, because the UI thread isn’t blocked during the wait. + +## Writing Text + + The following example writes text to a file. At each await statement, the method immediately exits. When the file I/O is complete, the method resumes at the statement that follows the await statement. Note that the async modifier is in the definition of methods that use the await statement. + +```vb +Public Async Sub ProcessWrite() + Dim filePath = "temp2.txt" + Dim text = "Hello World" & ControlChars.CrLf + + Await WriteTextAsync(filePath, text) +End Sub + +Private Async Function WriteTextAsync(filePath As String, text As String) As Task + Dim encodedText As Byte() = Encoding.Unicode.GetBytes(text) + + Using sourceStream As New FileStream(filePath, + FileMode.Append, FileAccess.Write, FileShare.None, + bufferSize:=4096, useAsync:=True) + + Await sourceStream.WriteAsync(encodedText, 0, encodedText.Length) + End Using +End Function +``` + + The original example has the statement `Await sourceStream.WriteAsync(encodedText, 0, encodedText.Length)`, which is a contraction of the following two statements: + +```vb +Dim theTask As Task = sourceStream.WriteAsync(encodedText, 0, encodedText.Length) +Await theTask +``` + + The first statement returns a task and causes file processing to start. The second statement with the await causes the method to immediately exit and return a different task. When the file processing later completes, execution returns to the statement that follows the await. For more information, see [Control Flow in Async Programs (Visual Basic)](control-flow-in-async-programs.md). + +## Reading Text + + The following example reads text from a file. The text is buffered and, in this case, placed into a . Unlike in the previous example, the evaluation of the await produces a value. The method returns a \<>, so the evaluation of the await produces an `Int32` value (`numRead`) after the operation completes. For more information, see [Async Return Types (Visual Basic)](async-return-types.md). + +```vb +Public Async Sub ProcessRead() + Dim filePath = "temp2.txt" + + If File.Exists(filePath) = False Then + Debug.WriteLine("file not found: " & filePath) + Else + Try + Dim text As String = Await ReadTextAsync(filePath) + Debug.WriteLine(text) + Catch ex As Exception + Debug.WriteLine(ex.Message) + End Try + End If +End Sub + +Private Async Function ReadTextAsync(filePath As String) As Task(Of String) + + Using sourceStream As New FileStream(filePath, + FileMode.Open, FileAccess.Read, FileShare.Read, + bufferSize:=4096, useAsync:=True) + + Dim sb As New StringBuilder + + Dim buffer As Byte() = New Byte(&H1000) {} + Dim numRead As Integer + numRead = Await sourceStream.ReadAsync(buffer, 0, buffer.Length) + While numRead <> 0 + Dim text As String = Encoding.Unicode.GetString(buffer, 0, numRead) + sb.Append(text) + + numRead = Await sourceStream.ReadAsync(buffer, 0, buffer.Length) + End While + + Return sb.ToString + End Using +End Function +``` + +## Parallel Asynchronous I/O + + The following example demonstrates parallel processing by writing 10 text files. For each file, the method returns a task that is then added to a list of tasks. The `Await Task.WhenAll(tasks)` statement exits the method and resumes within the method when file processing is complete for all of the tasks. + + The example closes all instances in a `Finally` block after the tasks are complete. If each `FileStream` was instead created in an `Imports` statement, the `FileStream` might be disposed of before the task was complete. + + Note that any performance boost is almost entirely from the parallel processing and not the asynchronous processing. The advantages of asynchrony are that it doesn’t tie up multiple threads, and that it doesn’t tie up the user interface thread. + +```vb +Public Async Sub ProcessWriteMult() + Dim folder = "tempfolder\" + Dim tasks As New List(Of Task) + Dim sourceStreams As New List(Of FileStream) + + Try + For index = 1 To 10 + Dim text = "In file " & index.ToString & ControlChars.CrLf + + Dim fileName = "thefile" & index.ToString("00") & ".txt" + Dim filePath = folder & fileName + + Dim encodedText As Byte() = Encoding.Unicode.GetBytes(text) + + Dim sourceStream As New FileStream(filePath, + FileMode.Append, FileAccess.Write, FileShare.None, + bufferSize:=4096, useAsync:=True) + + Dim theTask As Task = sourceStream.WriteAsync(encodedText, 0, encodedText.Length) + sourceStreams.Add(sourceStream) + + tasks.Add(theTask) + Next + + Await Task.WhenAll(tasks) + Finally + For Each sourceStream As FileStream In sourceStreams + sourceStream.Close() + Next + End Try +End Sub +``` + + When using the and methods, you can specify a , which you can use to cancel the operation mid-stream. For more information, see [Fine-Tuning Your Async Application (Visual Basic)](fine-tuning-your-async-application.md) and [Cancellation in Managed Threads](../../../../standard/threading/cancellation-in-managed-threads.md). + ## See also - [Asynchronous Programming with Async and Await (Visual Basic)](index.md) diff --git a/docs/visual-basic/programming-guide/concepts/async/walkthrough-accessing-the-web-by-using-async-and-await.md b/docs/visual-basic/programming-guide/concepts/async/walkthrough-accessing-the-web-by-using-async-and-await.md index cd1d48958f965..0c00464022e75 100644 --- a/docs/visual-basic/programming-guide/concepts/async/walkthrough-accessing-the-web-by-using-async-and-await.md +++ b/docs/visual-basic/programming-guide/concepts/async/walkthrough-accessing-the-web-by-using-async-and-await.md @@ -232,20 +232,20 @@ Visual Studio 2012 or later must be installed on your computer. For more informa ## Convert GetURLContents to an asynchronous method -1. To convert the synchronous solution to an asynchronous solution, the best place to start is in `GetURLContents` because the calls to the method and to the method are where the application accesses the web. The .NET Framework makes the conversion easy by supplying asynchronous versions of both methods. +1. To convert the synchronous solution to an asynchronous solution, the best place to start is in `GetURLContents` because the calls to the method and to the method are where the application accesses the web. The .NET Framework makes the conversion easy by supplying asynchronous versions of both methods. For more information about the methods that are used in `GetURLContents`, see . > [!NOTE] > As you follow the steps in this walkthrough, several compiler errors appear. You can ignore them and continue with the walkthrough. - Change the method that's called in the third line of `GetURLContents` from `GetResponse` to the asynchronous, task-based method. + Change the method that's called in the third line of `GetURLContents` from `GetResponse` to the asynchronous, task-based method. ```vb Using response As WebResponse = webReq.GetResponseAsync() ``` -2. `GetResponseAsync` returns a . In this case, the *task return variable*, `TResult`, has type . The task is a promise to produce an actual `WebResponse` object after the requested data has been downloaded and the task has run to completion. +2. `GetResponseAsync` returns a . In this case, the *task return variable*, `TResult`, has type . The task is a promise to produce an actual `WebResponse` object after the requested data has been downloaded and the task has run to completion. To retrieve the `WebResponse` value from the task, apply an [Await](../../../language-reference/operators/await-operator.md) operator to the call to `GetResponseAsync`, as the following code shows. @@ -268,7 +268,7 @@ Visual Studio 2012 or later must be installed on your computer. For more informa 3. Because you added the `Await` operator in the previous step, a compiler error occurs. The operator can be used only in methods that are marked with the [Async](../../../language-reference/modifiers/async.md) modifier. Ignore the error while you repeat the conversion steps to replace the call to `CopyTo` with a call to `CopyToAsync`. - - Change the name of the method that’s called to . + - Change the name of the method that’s called to . - The `CopyTo` or `CopyToAsync` method copies bytes to its argument, `content`, and doesn’t return a meaningful value. In the synchronous version, the call to `CopyTo` is a simple statement that doesn't return a value. The asynchronous version, `CopyToAsync`, returns a . The task functions like "Task(void)" and enables the method to be awaited. Apply `Await` or `await` to the call to `CopyToAsync`, as the following code shows. @@ -293,7 +293,7 @@ Visual Studio 2012 or later must be installed on your computer. For more informa Private Async Function GetURLContents(url As String) As Byte() ``` -5. The return type of an async method can only be , . In Visual Basic, the method must be a `Function` that returns a `Task` or a `Task(Of T)`, or the method must be a `Sub`. Typically, a `Sub` method is used only in an async event handler, where `Sub` is required. In other cases, you use `Task(T)` if the completed method has a [Return](../../../language-reference/statements/return-statement.md) statement that returns a value of type T, and you use `Task` if the completed method doesn’t return a meaningful value. +5. The return type of an async method can only be , . In Visual Basic, the method must be a `Function` that returns a `Task` or a `Task(Of T)`, or the method must be a `Sub`. Typically, a `Sub` method is used only in an async event handler, where `Sub` is required. In other cases, you use `Task(T)` if the completed method has a [Return](../../../language-reference/statements/return-statement.md) statement that returns a value of type T, and you use `Task` if the completed method doesn’t return a meaningful value. For more information, see [Async Return Types (Visual Basic)](async-return-types.md). diff --git a/docs/visual-basic/programming-guide/concepts/caller-information.md b/docs/visual-basic/programming-guide/concepts/caller-information.md index 11d59f7ab50bd..6fccc39544697 100644 --- a/docs/visual-basic/programming-guide/concepts/caller-information.md +++ b/docs/visual-basic/programming-guide/concepts/caller-information.md @@ -6,75 +6,75 @@ ms.assetid: 15d556eb-4d0c-4497-98a3-7f60abb7d6a1 --- # Caller Information (Visual Basic) -By using Caller Info attributes, you can obtain information about the caller to a method. You can obtain file path of the source code, the line number in the source code, and the member name of the caller. This information is helpful for tracing, debugging, and creating diagnostic tools. - - To obtain this information, you use attributes that are applied to optional parameters, each of which has a default value. The following table lists the Caller Info attributes that are defined in the namespace: - -|Attribute|Description|Type| -|---|---|---| -||Full path of the source file that contains the caller. This is the file path at compile time.|`String`| -||Line number in the source file at which the method is called.|`Integer`| -||Method or property name of the caller. See [Member Names](#MEMBERNAMES) later in this topic.|`String`| +By using Caller Info attributes, you can obtain information about the caller to a method. You can obtain file path of the source code, the line number in the source code, and the member name of the caller. This information is helpful for tracing, debugging, and creating diagnostic tools. + + To obtain this information, you use attributes that are applied to optional parameters, each of which has a default value. The following table lists the Caller Info attributes that are defined in the namespace: + +|Attribute|Description|Type| +|---|---|---| +||Full path of the source file that contains the caller. This is the file path at compile time.|`String`| +||Line number in the source file at which the method is called.|`Integer`| +||Method or property name of the caller. See [Member Names](#MEMBERNAMES) later in this topic.|`String`| ||Expression used by the caller for an argument. See [Caller Expressions](#CALLEREXPRESSION) later in this topic.|`String`| -## Example - - The following example shows how to use Caller Info attributes. On each call to the `TraceMessage` method, the caller information is substituted as arguments to the optional parameters. - -```vb -Private Sub DoProcessing() - TraceMessage("Something happened.") -End Sub - -Public Sub TraceMessage(message As String, - Optional memberName As String = Nothing, - Optional sourcefilePath As String = Nothing, - Optional sourceLineNumber As Integer = 0) - - System.Diagnostics.Trace.WriteLine("message: " & message) - System.Diagnostics.Trace.WriteLine("member name: " & memberName) - System.Diagnostics.Trace.WriteLine("source file path: " & sourcefilePath) - System.Diagnostics.Trace.WriteLine("source line number: " & sourceLineNumber) -End Sub - -' Sample output: -' message: Something happened. -' member name: DoProcessing -' source file path: C:\Users\username\Documents\Visual Studio 2012\Projects\CallerInfoVB\CallerInfoVB\Form1.vb -' source line number: 15 -``` - -## Remarks - - You must specify an explicit default value for each optional parameter. You can't apply Caller Info attributes to parameters that aren't specified as optional. - - The Caller Info attributes don't make a parameter optional. Instead, they affect the default value that's passed in when the argument is omitted. - - Caller Info values are emitted as literals into the Intermediate Language (IL) at compile time. Unlike the results of the property for exceptions, the results aren't affected by obfuscation. - - You can explicitly supply the optional arguments to control the caller information or to hide caller information. - -### Member Names - - You can use the `CallerMemberName` attribute to avoid specifying the member name as a `String` argument to the called method. By using this technique, you avoid the problem that **Rename Refactoring** doesn't change the `String` values. This benefit is especially useful for the following tasks: - -- Using tracing and diagnostic routines. - -- Implementing the interface when binding data. This interface allows the property of an object to notify a bound control that the property has changed, so that the control can display the updated information. Without the `CallerMemberName` attribute, you must specify the property name as a literal. - - The following chart shows the member names that are returned when you use the `CallerMemberName` attribute. - -|Calls occurs within|Member name result| -|-------------------------|------------------------| -|Method, property, or event|The name of the method, property, or event from which the call originated.| -|Constructor|The string ".ctor"| -|Static constructor|The string ".cctor"| -|Destructor|The string "Finalize"| -|User-defined operators or conversions|The generated name for the member, for example, "op_Addition".| -|Attribute constructor|The name of the member to which the attribute is applied. If the attribute is any element within a member (such as a parameter, a return value, or a generic type parameter), this result is the name of the member that's associated with that element.| -|No containing member (for example, assembly-level or attributes that are applied to types)|The default value of the optional parameter.| - -### Caller expressions +## Example + + The following example shows how to use Caller Info attributes. On each call to the `TraceMessage` method, the caller information is substituted as arguments to the optional parameters. + +```vb +Private Sub DoProcessing() + TraceMessage("Something happened.") +End Sub + +Public Sub TraceMessage(message As String, + Optional memberName As String = Nothing, + Optional sourcefilePath As String = Nothing, + Optional sourceLineNumber As Integer = 0) + + System.Diagnostics.Trace.WriteLine("message: " & message) + System.Diagnostics.Trace.WriteLine("member name: " & memberName) + System.Diagnostics.Trace.WriteLine("source file path: " & sourcefilePath) + System.Diagnostics.Trace.WriteLine("source line number: " & sourceLineNumber) +End Sub + +' Sample output: +' message: Something happened. +' member name: DoProcessing +' source file path: C:\Users\username\Documents\Visual Studio 2012\Projects\CallerInfoVB\CallerInfoVB\Form1.vb +' source line number: 15 +``` + +## Remarks + + You must specify an explicit default value for each optional parameter. You can't apply Caller Info attributes to parameters that aren't specified as optional. + + The Caller Info attributes don't make a parameter optional. Instead, they affect the default value that's passed in when the argument is omitted. + + Caller Info values are emitted as literals into the Intermediate Language (IL) at compile time. Unlike the results of the property for exceptions, the results aren't affected by obfuscation. + + You can explicitly supply the optional arguments to control the caller information or to hide caller information. + +### Member Names + + You can use the `CallerMemberName` attribute to avoid specifying the member name as a `String` argument to the called method. By using this technique, you avoid the problem that **Rename Refactoring** doesn't change the `String` values. This benefit is especially useful for the following tasks: + +- Using tracing and diagnostic routines. + +- Implementing the interface when binding data. This interface allows the property of an object to notify a bound control that the property has changed, so that the control can display the updated information. Without the `CallerMemberName` attribute, you must specify the property name as a literal. + + The following chart shows the member names that are returned when you use the `CallerMemberName` attribute. + +|Calls occurs within|Member name result| +|-------------------------|------------------------| +|Method, property, or event|The name of the method, property, or event from which the call originated.| +|Constructor|The string ".ctor"| +|Static constructor|The string ".cctor"| +|Destructor|The string "Finalize"| +|User-defined operators or conversions|The generated name for the member, for example, "op_Addition".| +|Attribute constructor|The name of the member to which the attribute is applied. If the attribute is any element within a member (such as a parameter, a return value, or a generic type parameter), this result is the name of the member that's associated with that element.| +|No containing member (for example, assembly-level or attributes that are applied to types)|The default value of the optional parameter.| + +### Caller expressions You use the when you want to capture the expression used for an argument. Diagnostic libraries may want to provide more details about the *expressions* passed as an arguments. By providing the expression that triggered the diagnostic, in addition to the parameter name, developers have more details about the condition that triggered the diagnostic. That extra information makes it easier to fix. The following method uses the to display the condition that must be `True`: diff --git a/docs/visual-basic/programming-guide/concepts/collections.md b/docs/visual-basic/programming-guide/concepts/collections.md index 9cff1f62bfb24..caa58d622a97d 100644 --- a/docs/visual-basic/programming-guide/concepts/collections.md +++ b/docs/visual-basic/programming-guide/concepts/collections.md @@ -23,7 +23,7 @@ If your collection contains elements of only one data type, you can use one of t ## Using a Simple Collection -The examples in this section use the generic class, which enables you to work with a strongly typed list of objects. +The examples in this section use the generic class, which enables you to work with a strongly typed list of objects. The following example creates a list of strings and then iterates through the strings by using a [For Each…Next](../../language-reference/statements/for-each-next-statement.md) statement. @@ -90,7 +90,7 @@ Next 'Output: chinook pink sockeye ``` -The following example removes elements from a generic list. Instead of a `For Each` statement, a [For…Next](../../language-reference/statements/for-next-statement.md) statement that iterates in descending order is used. This is because the method causes elements after a removed element to have a lower index value. +The following example removes elements from a generic list. Instead of a `For Each` statement, a [For…Next](../../language-reference/statements/for-next-statement.md) statement that iterates in descending order is used. This is because the method causes elements after a removed element to have a lower index value. ```vb Dim numbers As New List(Of Integer) From @@ -113,7 +113,7 @@ numbers.ForEach( ' Output: 0 2 4 6 8 ``` -For the type of elements in the , you can also define your own class. In the following example, the `Galaxy` class that is used by the is defined in the code. +For the type of elements in the , you can also define your own class. In the following example, the `Galaxy` class that is used by the is defined in the code. ```vb Private Sub IterateThroughList() @@ -170,11 +170,11 @@ The following table lists some of the frequently used classes of the |Represents a collection of key/value pairs that are organized based on the key.| -||Represents a list of objects that can be accessed by index. Provides methods to search, sort, and modify lists.| -||Represents a first in, first out (FIFO) collection of objects.| -||Represents a collection of key/value pairs that are sorted by key based on the associated implementation.| -||Represents a last in, first out (LIFO) collection of objects.| +||Represents a collection of key/value pairs that are organized based on the key.| +||Represents a list of objects that can be accessed by index. Provides methods to search, sort, and modify lists.| +||Represents a first in, first out (FIFO) collection of objects.| +||Represents a collection of key/value pairs that are sorted by key based on the associated implementation.| +||Represents a last in, first out (LIFO) collection of objects.| For additional information, see [Commonly Used Collection Types](../../../standard/collections/commonly-used-collection-types.md), [Selecting a Collection Class](../../../standard/collections/selecting-a-collection-class.md), and . @@ -186,7 +186,7 @@ In the .NET Framework 4 or newer, the collections in the namespace should be used instead of the corresponding types in the and namespaces whenever multiple threads are accessing the collection concurrently. For more information, see [Thread-Safe Collections](../../../standard/collections/thread-safe/index.md) and . -Some classes included in the namespace are , , , and . +Some classes included in the namespace are , , , and . @@ -225,7 +225,7 @@ For more information, see . ## Implementing a Collection of Key/Value Pairs -The generic collection enables you to access to elements in a collection by using the key of each element. Each addition to the dictionary consists of a value and its associated key. Retrieving a value by using its key is fast because the `Dictionary` class is implemented as a hash table. +The generic collection enables you to access to elements in a collection by using the key of each element. Each addition to the dictionary consists of a value and its associated key. Retrieving a value by using its key is fast because the `Dictionary` class is implemented as a hash table. The following example creates a `Dictionary` collection and iterates through the dictionary by using a `For Each` statement. @@ -291,7 +291,7 @@ Private Function BuildDictionary2() As Dictionary(Of String, Element) End Function ``` -The following example uses the method and the property of `Dictionary` to quickly find an item by key. The `Item` property enables you to access an item in the `elements` collection by using the `elements(symbol)` code in Visual Basic. +The following example uses the method and the property of `Dictionary` to quickly find an item by key. The `Item` property enables you to access an item in the `elements` collection by using the `elements(symbol)` code in Visual Basic. ```vb Private Sub FindInDictionary(ByVal symbol As String) @@ -306,7 +306,7 @@ Private Sub FindInDictionary(ByVal symbol As String) End Sub ``` -The following example instead uses the method quickly find an item by key. +The following example instead uses the method quickly find an item by key. ```vb Private Sub FindInDictionary2(ByVal symbol As String) @@ -373,11 +373,11 @@ End Class ## Sorting a Collection -The following example illustrates a procedure for sorting a collection. The example sorts instances of the `Car` class that are stored in a . The `Car` class implements the interface, which requires that the method be implemented. +The following example illustrates a procedure for sorting a collection. The example sorts instances of the `Car` class that are stored in a . The `Car` class implements the interface, which requires that the method be implemented. -Each call to the method makes a single comparison that is used for sorting. User-written code in the `CompareTo` method returns a value for each comparison of the current object with another object. The value returned is less than zero if the current object is less than the other object, greater than zero if the current object is greater than the other object, and zero if they are equal. This enables you to define in code the criteria for greater than, less than, and equal. +Each call to the method makes a single comparison that is used for sorting. User-written code in the `CompareTo` method returns a value for each comparison of the current object with another object. The value returned is less than zero if the current object is less than the other object, greater than zero if the current object is greater than the other object, and zero if they are equal. This enables you to define in code the criteria for greater than, less than, and equal. -In the `ListCars` method, the `cars.Sort()` statement sorts the list. This call to the method of the causes the `CompareTo` method to be called automatically for the `Car` objects in the `List`. +In the `ListCars` method, the `cars.Sort()` statement sorts the list. This call to the method of the causes the `CompareTo` method to be called automatically for the `Car` objects in the `List`. ```vb Public Sub ListCars() @@ -453,13 +453,13 @@ End Class ## Defining a Custom Collection -You can define a collection by implementing the or interface. For additional information, see [Enumerating a Collection](/previous-versions/dotnet/netframework-4.0/hwyysy67(v=vs.100)). +You can define a collection by implementing the or interface. For additional information, see [Enumerating a Collection](/previous-versions/dotnet/netframework-4.0/hwyysy67(v=vs.100)). Although you can define a custom collection, it is usually better to instead use the collections that are included in the .NET Framework, which are described in [Kinds of Collections](#kinds-of-collections) earlier in this topic. -The following example defines a custom collection class named `AllColors`. This class implements the interface, which requires that the method be implemented. +The following example defines a custom collection class named `AllColors`. This class implements the interface, which requires that the method be implemented. -The `GetEnumerator` method returns an instance of the `ColorEnumerator` class. `ColorEnumerator` implements the interface, which requires that the property, method, and method be implemented. +The `GetEnumerator` method returns an instance of the `ColorEnumerator` class. `ColorEnumerator` implements the interface, which requires that the property, method, and method be implemented. ```vb Public Sub ListColors() diff --git a/docs/visual-basic/programming-guide/concepts/covariance-contravariance/index.md b/docs/visual-basic/programming-guide/concepts/covariance-contravariance/index.md index 86b654203782d..a35bd6e980e30 100644 --- a/docs/visual-basic/programming-guide/concepts/covariance-contravariance/index.md +++ b/docs/visual-basic/programming-guide/concepts/covariance-contravariance/index.md @@ -96,7 +96,7 @@ A generic interface or delegate is called *variant* if its generic parameters ar |-----------|-----------------| |[Variance in Generic Interfaces (Visual Basic)](variance-in-generic-interfaces.md)|Discusses covariance and contravariance in generic interfaces and provides a list of variant generic interfaces in the .NET Framework.| |[Creating Variant Generic Interfaces (Visual Basic)](creating-variant-generic-interfaces.md)|Shows how to create custom variant interfaces.| -|[Using Variance in Interfaces for Generic Collections (Visual Basic)](using-variance-in-interfaces-for-generic-collections.md)|Shows how covariance and contravariance support in the and interfaces can help you reuse code.| +|[Using Variance in Interfaces for Generic Collections (Visual Basic)](using-variance-in-interfaces-for-generic-collections.md)|Shows how covariance and contravariance support in the and interfaces can help you reuse code.| |[Variance in Delegates (Visual Basic)](variance-in-delegates.md)|Discusses covariance and contravariance in generic and non-generic delegates and provides a list of variant generic delegates in the .NET Framework.| |[Using Variance in Delegates (Visual Basic)](using-variance-in-delegates.md)|Shows how to use covariance and contravariance support in non-generic delegates to match method signatures with delegate types.| |[Using Variance for Func and Action Generic Delegates (Visual Basic)](using-variance-for-func-and-action-generic-delegates.md)|Shows how covariance and contravariance support in the `Func` and `Action` delegates can help you reuse code.| diff --git a/docs/visual-basic/programming-guide/concepts/covariance-contravariance/using-variance-in-interfaces-for-generic-collections.md b/docs/visual-basic/programming-guide/concepts/covariance-contravariance/using-variance-in-interfaces-for-generic-collections.md index 4f5fa3b251ad9..fbb5bcfdbe562 100644 --- a/docs/visual-basic/programming-guide/concepts/covariance-contravariance/using-variance-in-interfaces-for-generic-collections.md +++ b/docs/visual-basic/programming-guide/concepts/covariance-contravariance/using-variance-in-interfaces-for-generic-collections.md @@ -9,13 +9,13 @@ ms.assetid: c867fcea-7462-4995-b9c5-542feec74036 A covariant interface allows its methods to return more derived types than those specified in the interface. A contravariant interface allows its methods to accept parameters of less derived types than those specified in the interface. -In .NET Framework 4, several existing interfaces became covariant and contravariant. These include and . This enables you to reuse methods that operate with generic collections of base types for collections of derived types. +In .NET Framework 4, several existing interfaces became covariant and contravariant. These include and . This enables you to reuse methods that operate with generic collections of base types for collections of derived types. For a list of variant interfaces in the .NET Framework, see [Variance in Generic Interfaces (Visual Basic)](variance-in-generic-interfaces.md). ## Converting Generic Collections -The following example illustrates the benefits of covariance support in the interface. The `PrintFullName` method accepts a collection of the `IEnumerable(Of Person)` type as a parameter. However, you can reuse it for a collection of the `IEnumerable(Of Person)` type because `Employee` inherits `Person`. +The following example illustrates the benefits of covariance support in the interface. The `PrintFullName` method accepts a collection of the `IEnumerable(Of Person)` type as a parameter. However, you can reuse it for a collection of the `IEnumerable(Of Person)` type because `Employee` inherits `Person`. ```vb ' Simple hierarchy of classes. @@ -49,7 +49,7 @@ End Sub ## Comparing Generic Collections -The following example illustrates the benefits of contravariance support in the interface. The `PersonComparer` class implements the `IComparer(Of Person)` interface. However, you can reuse this class to compare a sequence of objects of the `Employee` type because `Employee` inherits `Person`. +The following example illustrates the benefits of contravariance support in the interface. The `PersonComparer` class implements the `IComparer(Of Person)` interface. However, you can reuse this class to compare a sequence of objects of the `Employee` type because `Employee` inherits `Person`. ```vb ' Simple hierarchy of classes. diff --git a/docs/visual-basic/programming-guide/concepts/covariance-contravariance/variance-in-delegates.md b/docs/visual-basic/programming-guide/concepts/covariance-contravariance/variance-in-delegates.md index 884b740df5504..5eb1ea8e27a89 100644 --- a/docs/visual-basic/programming-guide/concepts/covariance-contravariance/variance-in-delegates.md +++ b/docs/visual-basic/programming-guide/concepts/covariance-contravariance/variance-in-delegates.md @@ -119,15 +119,15 @@ End Sub .NET Framework 4 introduced variance support for generic type parameters in several existing generic delegates: -- `Action` delegates from the namespace, for example, and +- `Action` delegates from the namespace, for example, and -- `Func` delegates from the namespace, for example, and +- `Func` delegates from the namespace, for example, and -- The delegate +- The delegate -- The delegate +- The delegate -- The delegate +- The delegate For more information and examples, see [Using Variance for Func and Action Generic Delegates (Visual Basic)](using-variance-for-func-and-action-generic-delegates.md). @@ -167,7 +167,7 @@ dvariant("test") ### Combining Variant Generic Delegates -You should not combine variant delegates. The method does not support variant delegate conversion and expects delegates to be of exactly the same type. This can lead to a run-time exception when you combine delegates either by using the method (in C# and Visual Basic) or by using the `+` operator (in C#), as shown in the following code example. +You should not combine variant delegates. The method does not support variant delegate conversion and expects delegates to be of exactly the same type. This can lead to a run-time exception when you combine delegates either by using the method (in C# and Visual Basic) or by using the `+` operator (in C#), as shown in the following code example. ```vb Dim actObj As Action(Of Object) = Sub(x) Console.WriteLine("object: {0}", x) diff --git a/docs/visual-basic/programming-guide/concepts/covariance-contravariance/variance-in-generic-interfaces.md b/docs/visual-basic/programming-guide/concepts/covariance-contravariance/variance-in-generic-interfaces.md index 3455fc127ba79..d614f98b2dee8 100644 --- a/docs/visual-basic/programming-guide/concepts/covariance-contravariance/variance-in-generic-interfaces.md +++ b/docs/visual-basic/programming-guide/concepts/covariance-contravariance/variance-in-generic-interfaces.md @@ -8,19 +8,19 @@ ms.assetid: cf4096d0-4bb3-45a9-9a6b-f01e29a60333 .NET Framework 4 introduced variance support for several existing generic interfaces. Variance support enables implicit conversion of classes that implement these interfaces. The following interfaces are now variant: -- (T is covariant) +- (T is covariant) -- (T is covariant) +- (T is covariant) -- (T is covariant) +- (T is covariant) -- (`TKey` and `TElement` are covariant) +- (`TKey` and `TElement` are covariant) -- (T is contravariant) +- (T is contravariant) -- (T is contravariant) +- (T is contravariant) -- (T is contravariant) +- (T is contravariant) Covariance permits a method to have a more derived return type than that defined by the generic type parameter of the interface. To illustrate the covariance feature, consider these generic interfaces: `IEnumerable(Of Object)` and `IEnumerable(Of String)`. The `IEnumerable(Of String)` interface does not inherit the `IEnumerable(Of Object)` interface. However, the `String` type does inherit the `Object` type, and in some cases you may want to assign objects of these interfaces to each other. This is shown in the following code example. @@ -29,9 +29,9 @@ Dim strings As IEnumerable(Of String) = New List(Of String) Dim objects As IEnumerable(Of Object) = strings ``` -In earlier versions of the .NET Framework, this code causes a compilation error in Visual Basic with `Option Strict On`. But now you can use `strings` instead of `objects`, as shown in the previous example, because the interface is covariant. +In earlier versions of the .NET Framework, this code causes a compilation error in Visual Basic with `Option Strict On`. But now you can use `strings` instead of `objects`, as shown in the previous example, because the interface is covariant. -Contravariance permits a method to have argument types that are less derived than that specified by the generic parameter of the interface. To illustrate contravariance, assume that you have created a `BaseComparer` class to compare instances of the `BaseClass` class. The `BaseComparer` class implements the `IEqualityComparer(Of BaseClass)` interface. Because the interface is now contravariant, you can use `BaseComparer` to compare instances of classes that inherit the `BaseClass` class. This is shown in the following code example. +Contravariance permits a method to have argument types that are less derived than that specified by the generic parameter of the interface. To illustrate contravariance, assume that you have created a `BaseComparer` class to compare instances of the `BaseClass` class. The `BaseComparer` class implements the `IEqualityComparer(Of BaseClass)` interface. Because the interface is now contravariant, you can use `BaseComparer` to compare instances of classes that inherit the `BaseClass` class. This is shown in the following code example. ```vb ' Simple hierarchy of classes. @@ -76,7 +76,7 @@ Dim integers As IEnumerable(Of Integer) = New List(Of Integer) ' Dim objects As IEnumerable(Of Object) = integers ``` -It is also important to remember that classes that implement variant interfaces are still invariant. For example, although implements the covariant interface , you cannot implicitly convert `List(Of Object)` to `List(Of String)`. This is illustrated in the following code example. +It is also important to remember that classes that implement variant interfaces are still invariant. For example, although implements the covariant interface , you cannot implicitly convert `List(Of Object)` to `List(Of String)`. This is illustrated in the following code example. ```vb ' The following statement generates a compiler error diff --git a/docs/visual-basic/programming-guide/concepts/expression-trees/how-to-execute-expression-trees.md b/docs/visual-basic/programming-guide/concepts/expression-trees/how-to-execute-expression-trees.md index 06f3cbcfd2e17..24dc78308503c 100644 --- a/docs/visual-basic/programming-guide/concepts/expression-trees/how-to-execute-expression-trees.md +++ b/docs/visual-basic/programming-guide/concepts/expression-trees/how-to-execute-expression-trees.md @@ -6,43 +6,43 @@ ms.assetid: 9dfb5ab3-f48f-417e-975f-f8f6f1cdc18d --- # How to: Execute Expression Trees (Visual Basic) -This topic shows you how to execute an expression tree. Executing an expression tree may return a value, or it may just perform an action such as calling a method. - - Only expression trees that represent lambda expressions can be executed. Expression trees that represent lambda expressions are of type or . To execute these expression trees, call the method to create an executable delegate, and then invoke the delegate. - +This topic shows you how to execute an expression tree. Executing an expression tree may return a value, or it may just perform an action such as calling a method. + + Only expression trees that represent lambda expressions can be executed. Expression trees that represent lambda expressions are of type or . To execute these expression trees, call the method to create an executable delegate, and then invoke the delegate. + > [!NOTE] -> If the type of the delegate is not known, that is, the lambda expression is of type and not , you must call the method on the delegate instead of invoking it directly. - - If an expression tree does not represent a lambda expression, you can create a new lambda expression that has the original expression tree as its body, by calling the method. Then, you can execute the lambda expression as described earlier in this section. - -## Example - - The following code example demonstrates how to execute an expression tree that represents raising a number to a power by creating a lambda expression and executing it. The result, which represents the number raised to the power, is displayed. - -```vb -' The expression tree to execute. -Dim be As BinaryExpression = Expression.Power(Expression.Constant(2.0R), Expression.Constant(3.0R)) - -' Create a lambda expression. -Dim le As Expression(Of Func(Of Double)) = Expression.Lambda(Of Func(Of Double))(be) - -' Compile the lambda expression. -Dim compiledExpression As Func(Of Double) = le.Compile() - -' Execute the lambda expression. -Dim result As Double = compiledExpression() - -' Display the result. -MsgBox(result) - -' This code produces the following output: -' 8 -``` - -## Compile the code - -- Include the System.Linq.Expressions namespace. - +> If the type of the delegate is not known, that is, the lambda expression is of type and not , you must call the method on the delegate instead of invoking it directly. + + If an expression tree does not represent a lambda expression, you can create a new lambda expression that has the original expression tree as its body, by calling the method. Then, you can execute the lambda expression as described earlier in this section. + +## Example + + The following code example demonstrates how to execute an expression tree that represents raising a number to a power by creating a lambda expression and executing it. The result, which represents the number raised to the power, is displayed. + +```vb +' The expression tree to execute. +Dim be As BinaryExpression = Expression.Power(Expression.Constant(2.0R), Expression.Constant(3.0R)) + +' Create a lambda expression. +Dim le As Expression(Of Func(Of Double)) = Expression.Lambda(Of Func(Of Double))(be) + +' Compile the lambda expression. +Dim compiledExpression As Func(Of Double) = le.Compile() + +' Execute the lambda expression. +Dim result As Double = compiledExpression() + +' Display the result. +MsgBox(result) + +' This code produces the following output: +' 8 +``` + +## Compile the code + +- Include the System.Linq.Expressions namespace. + ## See also - [Expression Trees (Visual Basic)](index.md) diff --git a/docs/visual-basic/programming-guide/concepts/expression-trees/how-to-modify-expression-trees.md b/docs/visual-basic/programming-guide/concepts/expression-trees/how-to-modify-expression-trees.md index 62226da42ae92..bdd8ecb399d8a 100644 --- a/docs/visual-basic/programming-guide/concepts/expression-trees/how-to-modify-expression-trees.md +++ b/docs/visual-basic/programming-guide/concepts/expression-trees/how-to-modify-expression-trees.md @@ -40,7 +40,7 @@ This topic shows you how to modify an expression tree. Expression trees are immu End Class ``` - This class inherits the class and is specialized to modify expressions that represent conditional `AND` operations. It changes these operations from a conditional `AND` to a conditional `OR`. To do this, the class overrides the method of the base type, because conditional `AND` expressions are represented as binary expressions. In the `VisitBinary` method, if the expression that is passed to it represents a conditional `AND` operation, the code constructs a new expression that contains the conditional `OR` operator instead of the conditional `AND` operator. If the expression that is passed to `VisitBinary` does not represent a conditional `AND` operation, the method defers to the base class implementation. The base class methods construct nodes that are like the expression trees that are passed in, but the nodes have their sub trees replaced with the expression trees that are produced recursively by the visitor. + This class inherits the class and is specialized to modify expressions that represent conditional `AND` operations. It changes these operations from a conditional `AND` to a conditional `OR`. To do this, the class overrides the method of the base type, because conditional `AND` expressions are represented as binary expressions. In the `VisitBinary` method, if the expression that is passed to it represents a conditional `AND` operation, the code constructs a new expression that contains the conditional `OR` operator instead of the conditional `AND` operator. If the expression that is passed to `VisitBinary` does not represent a conditional `AND` operation, the method defers to the base class implementation. The base class methods construct nodes that are like the expression trees that are passed in, but the nodes have their sub trees replaced with the expression trees that are produced recursively by the visitor. 4. Add an `Imports` statement to the file for the `System.Linq.Expressions` namespace. diff --git a/docs/visual-basic/programming-guide/concepts/expression-trees/how-to-use-expression-trees-to-build-dynamic-queries.md b/docs/visual-basic/programming-guide/concepts/expression-trees/how-to-use-expression-trees-to-build-dynamic-queries.md index 631dc4aa50272..21f9eca0fd416 100644 --- a/docs/visual-basic/programming-guide/concepts/expression-trees/how-to-use-expression-trees-to-build-dynamic-queries.md +++ b/docs/visual-basic/programming-guide/concepts/expression-trees/how-to-use-expression-trees-to-build-dynamic-queries.md @@ -6,7 +6,7 @@ ms.assetid: 16278787-7532-4b65-98b2-7a412406c4ee --- # Querying based on runtime state (Visual Basic) -Consider code that defines an or an [IQueryable(Of T)]() against a data source: +Consider code that defines an or an [IQueryable(Of T)]() against a data source: :::code language="vb" source="../../../../../samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/Program.vb" id="Initialize"::: @@ -28,7 +28,7 @@ The following sections describe specific techniques for querying differently in - Use runtime state from within the expression tree - Call additional LINQ methods - Vary the expression tree passed into the LINQ methods -- Construct an [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression%601) expression tree using the factory methods at +- Construct an [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression`1) expression tree using the factory methods at - Add method call nodes to an 's expression tree - Construct strings, and use the [Dynamic LINQ library](https://dynamic-linq.net/) @@ -45,9 +45,9 @@ The internal expression tree—and thus the query—haven't been modifie Generally, the [built-in LINQ methods](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs) at perform two steps: * Wrap the current expression tree in a representing the method call. -* Pass the wrapped expression tree back to the provider, either to return a value via the provider's method; or to return a translated query object via the method. +* Pass the wrapped expression tree back to the provider, either to return a value via the provider's method; or to return a translated query object via the method. -You can replace the original query with the result of an [IQueryable(Of T)](xref:System.Linq.IQueryable%601)-returning method, to get a new query. You can do this conditionally based on runtime state, as in the following example: +You can replace the original query with the result of an [IQueryable(Of T)](xref:System.Linq.IQueryable`1)-returning method, to get a new query. You can do this conditionally based on runtime state, as in the following example: :::code language="vb" source="../../../../../samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/Program.vb" id="Added_method_calls"::: @@ -65,11 +65,11 @@ You might also want to compose the various subexpressions using a third-party li In all the examples up to this point, we've known the element type at compile time—`String`—and thus the type of the query—`IQueryable(Of String)`. You may need to add components to a query of any element type, or to add different components depending on the element type. You can create expression trees from the ground up, using the factory methods at , and thus tailor the expression at run time to a specific element type. -### Constructing an [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression%601) +### Constructing an [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression`1) -When you construct an expression to pass into one of the LINQ methods, you're actually constructing an instance of [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression%601), where `TDelegate` is some delegate type such as `Func(Of String, Boolean)`, `Action`, or a custom delegate type. +When you construct an expression to pass into one of the LINQ methods, you're actually constructing an instance of [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression`1), where `TDelegate` is some delegate type such as `Func(Of String, Boolean)`, `Action`, or a custom delegate type. -[Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression%601) inherits from , which represents a complete lambda expression like the following: +[Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression`1) inherits from , which represents a complete lambda expression like the following: :::code language="vb" source="../../../../../samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/Program.vb" id="Compiler_generated"::: @@ -78,9 +78,9 @@ A has two components: * A parameter list—`(x As String)`—represented by the property. * A body—`x.StartsWith("a")`—represented by the property. -The basic steps in constructing an [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression%601) are as follows: +The basic steps in constructing an [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression`1) are as follows: -* Define objects for each of the parameters (if any) in the lambda expression, using the factory method. +* Define objects for each of the parameters (if any) in the lambda expression, using the factory method. :::code language="vb" source="../../../../../samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/Program.vb" id="Factory_method_parameter"::: @@ -88,11 +88,11 @@ The basic steps in constructing an [Expression(Of TDelegate)](xref:System.Linq.E :::code language="vb" source="../../../../../samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/Program.vb" id="Factory_method_body"::: -* Wrap the parameters and body in a compile-time-typed [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression%601), using the appropriate factory method overload: +* Wrap the parameters and body in a compile-time-typed [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression`1), using the appropriate factory method overload: :::code language="vb" source="../../../../../samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/Program.vb" id="Factory_method_lambda"::: -The following sections describe a scenario in which you might want to construct an [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression%601) to pass into a LINQ method, and provide a complete example of how to do so using the factory methods. +The following sections describe a scenario in which you might want to construct an [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression`1) to pass into a LINQ method, and provide a complete example of how to do so using the factory methods. ### Scenario @@ -114,19 +114,19 @@ While you could write one custom function for `IQueryable(Of Person)` and anothe :::code language="vb" source="../../../../../samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/Program.vb" id="Factory_methods_expression_of_tdelegate"::: -Because the `TextFilter` function takes and returns an [IQueryable(Of T)](xref:System.Linq.IQueryable%601) (and not just an ), you can add further compile-time-typed query elements after the text filter. +Because the `TextFilter` function takes and returns an [IQueryable(Of T)](xref:System.Linq.IQueryable`1) (and not just an ), you can add further compile-time-typed query elements after the text filter. :::code language="vb" source="../../../../../samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/Program.vb" id="Factory_methods_expression_of_tdelegate_usage"::: ## Add method call nodes to the 's expression tree -If you have an instead of an [IQueryable(Of T)](xref:System.Linq.IQueryable%601), you can't directly call the generic LINQ methods. One alternative is to build the inner expression tree as above, and use reflection to invoke the appropriate LINQ method while passing in the expression tree. +If you have an instead of an [IQueryable(Of T)](xref:System.Linq.IQueryable`1), you can't directly call the generic LINQ methods. One alternative is to build the inner expression tree as above, and use reflection to invoke the appropriate LINQ method while passing in the expression tree. You could also duplicate the LINQ method's functionality, by wrapping the entire tree in a that represents a call to the LINQ method: :::code language="vb" source="../../../../../samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/Program.vb" id="Factory_methods_lambdaexpression"::: -In this case you don't have a compile-time `T` generic placeholder, so you'll use the overload that doesn't require compile-time type information, and which produces a instead of an [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression%601). +In this case you don't have a compile-time `T` generic placeholder, so you'll use the overload that doesn't require compile-time type information, and which produces a instead of an [Expression(Of TDelegate)](xref:System.Linq.Expressions.Expression`1). ## The Dynamic LINQ library diff --git a/docs/visual-basic/programming-guide/concepts/expression-trees/index.md b/docs/visual-basic/programming-guide/concepts/expression-trees/index.md index 61f1a1df5ad5f..32b87448810d7 100644 --- a/docs/visual-basic/programming-guide/concepts/expression-trees/index.md +++ b/docs/visual-basic/programming-guide/concepts/expression-trees/index.md @@ -16,7 +16,7 @@ Expression trees represent code in a tree-like data structure, where each node i ## Creating Expression Trees from Lambda Expressions - When a lambda expression is assigned to a variable of type , the compiler emits code to build an expression tree that represents the lambda expression. + When a lambda expression is assigned to a variable of type , the compiler emits code to build an expression tree that represents the lambda expression. The Visual Basic compiler can generate expression trees only from expression lambdas (or single-line lambdas). It cannot parse statement lambdas (or multi-line lambdas). For more information about lambda expressions in Visual Basic, see [Lambda Expressions](../../language-features/procedures/lambda-expressions.md). @@ -115,7 +115,7 @@ Console.WriteLine(String.Format("Decomposed expression: {0} => {1} {2} {3}", ## Compiling Expression Trees - The type provides the method that compiles the code represented by an expression tree into an executable delegate. + The type provides the method that compiles the code represented by an expression tree into an executable delegate. The following code example demonstrates how to compile an expression tree and run the resulting code. diff --git a/docs/visual-basic/programming-guide/concepts/iterators.md b/docs/visual-basic/programming-guide/concepts/iterators.md index 7df1b2887452c..5109b5936579b 100644 --- a/docs/visual-basic/programming-guide/concepts/iterators.md +++ b/docs/visual-basic/programming-guide/concepts/iterators.md @@ -30,7 +30,7 @@ Private Iterator Function SomeNumbers() As System.Collections.IEnumerable End Function ``` -The return type of an iterator method or `get` accessor can be , , , or . +The return type of an iterator method or `get` accessor can be , , , or . You can use an `Exit Function` or `Return` statement to end the iteration. @@ -69,7 +69,7 @@ End Function ## Creating a Collection Class -In the following example, the `DaysOfTheWeek` class implements the interface, which requires a method. The compiler implicitly calls the `GetEnumerator` method, which returns an . +In the following example, the `DaysOfTheWeek` class implements the interface, which requires a method. The compiler implicitly calls the `GetEnumerator` method, which returns an . The `GetEnumerator` method returns each string one at a time by using the `Yield` statement, and an `Iterator` modifier is in the function declaration. @@ -287,9 +287,9 @@ If validation is instead inside the iterator function, the validation cannot be ## Using Iterators with a Generic List -In the following example, the `Stack(Of T)` generic class implements the generic interface. The `Push` method assigns values to an array of type `T`. The method returns the array values by using the `Yield` statement. +In the following example, the `Stack(Of T)` generic class implements the generic interface. The `Push` method assigns values to an array of type `T`. The method returns the array values by using the `Yield` statement. -In addition to the generic method, the non-generic method must also be implemented. This is because inherits from . The non-generic implementation defers to the generic implementation. +In addition to the generic method, the non-generic method must also be implemented. This is because inherits from . The non-generic implementation defers to the generic implementation. The example uses named iterators to support various ways of iterating through the same collection of data. These named iterators are the `TopToBottom` and `BottomToTop` properties, and the `TopN` method. @@ -412,11 +412,11 @@ Although you write an iterator as a method, the compiler translates it into a ne To see what the compiler does, you can use the Ildasm.exe tool to view the common intermediate language code that is generated for an iterator method. -When you create an iterator for a [class](../../language-reference/statements/class-statement.md) or [struct](../../language-reference/statements/structure-statement.md), you do not have to implement the whole interface. When the compiler detects the iterator, it automatically generates the `Current`, `MoveNext`, and `Dispose` methods of the or interface. +When you create an iterator for a [class](../../language-reference/statements/class-statement.md) or [struct](../../language-reference/statements/structure-statement.md), you do not have to implement the whole interface. When the compiler detects the iterator, it automatically generates the `Current`, `MoveNext`, and `Dispose` methods of the or interface. On each successive iteration of the `For Each…Next` loop (or the direct call to `IEnumerator.MoveNext`), the next iterator code body resumes after the previous `Yield` statement. It then continues to the next `Yield` statement until the end of the iterator body is reached, or until an `Exit Function` or `Return` statement is encountered. -Iterators do not support the method. To re-iterate from the start, you must obtain a new iterator. +Iterators do not support the method. To re-iterate from the start, you must obtain a new iterator. For additional information, see the [Visual Basic Language Specification](../../reference/language-specification/index.md). @@ -426,14 +426,14 @@ Iterators enable you to maintain the simplicity of a `For Each` loop when you ne - Modify the list sequence after the first `For Each` loop iteration. -- Avoid fully loading a large list before the first iteration of a `For Each` loop. An example is a paged fetch to load a batch of table rows. Another example is the method, which implements iterators within the .NET Framework. +- Avoid fully loading a large list before the first iteration of a `For Each` loop. An example is a paged fetch to load a batch of table rows. Another example is the method, which implements iterators within the .NET Framework. - Encapsulate building the list in the iterator. In the iterator method, you can build the list and then yield each result in a loop. ## See also - -- +- - [For Each...Next Statement](../../language-reference/statements/for-each-next-statement.md) - [Yield Statement](../../language-reference/statements/yield-statement.md) - [Iterator](../../language-reference/modifiers/iterator.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/aggregation-operations.md b/docs/visual-basic/programming-guide/concepts/linq/aggregation-operations.md index 6d57729a48f45..36b48f3a13121 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/aggregation-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/aggregation-operations.md @@ -6,64 +6,64 @@ ms.assetid: 0f47e92c-5dd2-4007-baf4-c5fe5dc3b4a8 --- # Aggregation Operations (Visual Basic) -An aggregation operation computes a single value from a collection of values. An example of an aggregation operation is calculating the average daily temperature from a month's worth of daily temperature values. - - The following illustration shows the results of two different aggregation operations on a sequence of numbers. The first operation sums the numbers. The second operation returns the maximum value in the sequence. - - ![Illustration that shows LINQ aggregation operations.](./media/aggregation-operations/linq-aggregation-operations.png) - - The standard query operator methods that perform aggregation operations are listed in the following section. - -## Methods - -|Method Name|Description|Visual Basic Query Expression Syntax|More Information| -|-----------------|-----------------|------------------------------------------|----------------------| -|Aggregate|Performs a custom aggregation operation on the values of a collection.|Not applicable.|

| -|Average|Calculates the average value of a collection of values.|`Aggregate … In … Into Average()`|

| -|Count|Counts the elements in a collection, optionally only those elements that satisfy a predicate function.|`Aggregate … In … Into Count()`|

| -|LongCount|Counts the elements in a large collection, optionally only those elements that satisfy a predicate function.|`Aggregate … In … Into LongCount()`|

| -|Max or MaxBy|Determines the maximum value in a collection.|`Aggregate … In … Into Max()`|


| -|Min or MinBy|Determines the minimum value in a collection.|`Aggregate … In … Into Min()`|


| -|Sum|Calculates the sum of the values in a collection.|`Aggregate … In … Into Sum()`|

| - -## Query Expression Syntax Examples - -### Average - - The following code example uses the `Aggregate Into Average` clause in Visual Basic to calculate the average temperature in an array of numbers that represent temperatures. - - [!code-vb[CsLINQAggregating#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAggregating/VB/Aggregating.vb#1)] - -### Count - - The following code example uses the `Aggregate Into Count` clause in Visual Basic to count the number of values in an array that are greater than or equal to 80. - - [!code-vb[CsLINQAggregating#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAggregating/VB/Aggregating.vb#2)] - -### LongCount - - The following code example uses the `Aggregate Into LongCount` clause to count the number of values in an array. - - [!code-vb[CsLINQAggregating#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAggregating/VB/Aggregating.vb#3)] - -### Max - - The following code example uses the `Aggregate Into Max` clause to calculate the maximum temperature in an array of numbers that represent temperatures. - - [!code-vb[CsLINQAggregating#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAggregating/VB/Aggregating.vb#4)] - -### Min - - The following code example uses the `Aggregate Into Min` clause to calculate the minimum temperature in an array of numbers that represent temperatures. - - [!code-vb[CsLINQAggregating#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAggregating/VB/Aggregating.vb#5)] - -### Sum - - The following code example uses the `Aggregate Into Sum` clause to calculate the total expense amount from an array of values that represent expenses. - - [!code-vb[CsLINQAggregating#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAggregating/VB/Aggregating.vb#6)] - +An aggregation operation computes a single value from a collection of values. An example of an aggregation operation is calculating the average daily temperature from a month's worth of daily temperature values. + + The following illustration shows the results of two different aggregation operations on a sequence of numbers. The first operation sums the numbers. The second operation returns the maximum value in the sequence. + + ![Illustration that shows LINQ aggregation operations.](./media/aggregation-operations/linq-aggregation-operations.png) + + The standard query operator methods that perform aggregation operations are listed in the following section. + +## Methods + +|Method Name|Description|Visual Basic Query Expression Syntax|More Information| +|-----------------|-----------------|------------------------------------------|----------------------| +|Aggregate|Performs a custom aggregation operation on the values of a collection.|Not applicable.|

| +|Average|Calculates the average value of a collection of values.|`Aggregate … In … Into Average()`|

| +|Count|Counts the elements in a collection, optionally only those elements that satisfy a predicate function.|`Aggregate … In … Into Count()`|

| +|LongCount|Counts the elements in a large collection, optionally only those elements that satisfy a predicate function.|`Aggregate … In … Into LongCount()`|

| +|Max or MaxBy|Determines the maximum value in a collection.|`Aggregate … In … Into Max()`|


| +|Min or MinBy|Determines the minimum value in a collection.|`Aggregate … In … Into Min()`|


| +|Sum|Calculates the sum of the values in a collection.|`Aggregate … In … Into Sum()`|

| + +## Query Expression Syntax Examples + +### Average + + The following code example uses the `Aggregate Into Average` clause in Visual Basic to calculate the average temperature in an array of numbers that represent temperatures. + + [!code-vb[CsLINQAggregating#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAggregating/VB/Aggregating.vb#1)] + +### Count + + The following code example uses the `Aggregate Into Count` clause in Visual Basic to count the number of values in an array that are greater than or equal to 80. + + [!code-vb[CsLINQAggregating#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAggregating/VB/Aggregating.vb#2)] + +### LongCount + + The following code example uses the `Aggregate Into LongCount` clause to count the number of values in an array. + + [!code-vb[CsLINQAggregating#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAggregating/VB/Aggregating.vb#3)] + +### Max + + The following code example uses the `Aggregate Into Max` clause to calculate the maximum temperature in an array of numbers that represent temperatures. + + [!code-vb[CsLINQAggregating#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAggregating/VB/Aggregating.vb#4)] + +### Min + + The following code example uses the `Aggregate Into Min` clause to calculate the minimum temperature in an array of numbers that represent temperatures. + + [!code-vb[CsLINQAggregating#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAggregating/VB/Aggregating.vb#5)] + +### Sum + + The following code example uses the `Aggregate Into Sum` clause to calculate the total expense amount from an array of values that represent expenses. + + [!code-vb[CsLINQAggregating#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAggregating/VB/Aggregating.vb#6)] + ## See also - diff --git a/docs/visual-basic/programming-guide/concepts/linq/basic-query-operations.md b/docs/visual-basic/programming-guide/concepts/linq/basic-query-operations.md index 9771435cd71dd..caf112c0b3e33 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/basic-query-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/basic-query-operations.md @@ -2,7 +2,7 @@ description: "Learn more about: Basic Query Operations (Visual Basic)" title: "Basic Query Operations" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "data sources [LINQ in Visual Basic]" - "Join clause [LINQ in Visual Basic]" - "ordering data [LINQ in Visual Basic]" @@ -19,144 +19,144 @@ ms.assetid: 1146f6d0-fcb8-4f4d-8223-c9db52620d21 --- # Basic Query Operations (Visual Basic) -This topic provides a brief introduction to Language-Integrated Query (LINQ) expressions in Visual Basic, and to some of the typical kinds of operations that you perform in a query. For more information, see the following topics: - - [Introduction to LINQ in Visual Basic](../../language-features/linq/introduction-to-linq.md) - - [Queries](../../../language-reference/queries/index.md) - - [Walkthrough: Writing Queries in Visual Basic](walkthrough-writing-queries.md) - -## Specifying the Data Source (From) - - In a LINQ query, the first step is to specify the data source that you want to query. Therefore, the `From` clause in a query always comes first. Query operators select and shape the result based on the type of the source. - - [!code-vb[VbLINQBasicOps#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#1)] - - The `From` clause specifies the data source, `customers`, and a *range variable*, `cust`. The range variable is like a loop iteration variable, except that in a query expression, no actual iteration occurs. When the query is executed, often by using a `For Each` loop, the range variable serves as a reference to each successive element in `customers`. Because the compiler can infer the type of `cust`, you do not have to specify it explicitly. For examples of queries written with and without explicit typing, see [Type Relationships in Query Operations (Visual Basic)](type-relationships-in-query-operations.md). - - For more information about how to use the `From` clause in Visual Basic, see [From Clause](../../../language-reference/queries/from-clause.md). - -## Filtering Data (Where) - - Probably the most common query operation is applying a filter in the form of a Boolean expression. The query then returns only those elements for which the expression is true. A `Where` clause is used to perform the filtering. The filter specifies which elements in the data source to include in the resulting sequence. In the following example, only those customers who have an address in London are included. - - [!code-vb[VbLINQBasicOps#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#2)] - - You can use logical operators such as `And` and `Or` to combine filter expressions in a `Where` clause. For example, to return only those customers who are from London and whose name is Devon, use the following code: - -```vb +This topic provides a brief introduction to Language-Integrated Query (LINQ) expressions in Visual Basic, and to some of the typical kinds of operations that you perform in a query. For more information, see the following topics: + + [Introduction to LINQ in Visual Basic](../../language-features/linq/introduction-to-linq.md) + + [Queries](../../../language-reference/queries/index.md) + + [Walkthrough: Writing Queries in Visual Basic](walkthrough-writing-queries.md) + +## Specifying the Data Source (From) + + In a LINQ query, the first step is to specify the data source that you want to query. Therefore, the `From` clause in a query always comes first. Query operators select and shape the result based on the type of the source. + + [!code-vb[VbLINQBasicOps#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#1)] + + The `From` clause specifies the data source, `customers`, and a *range variable*, `cust`. The range variable is like a loop iteration variable, except that in a query expression, no actual iteration occurs. When the query is executed, often by using a `For Each` loop, the range variable serves as a reference to each successive element in `customers`. Because the compiler can infer the type of `cust`, you do not have to specify it explicitly. For examples of queries written with and without explicit typing, see [Type Relationships in Query Operations (Visual Basic)](type-relationships-in-query-operations.md). + + For more information about how to use the `From` clause in Visual Basic, see [From Clause](../../../language-reference/queries/from-clause.md). + +## Filtering Data (Where) + + Probably the most common query operation is applying a filter in the form of a Boolean expression. The query then returns only those elements for which the expression is true. A `Where` clause is used to perform the filtering. The filter specifies which elements in the data source to include in the resulting sequence. In the following example, only those customers who have an address in London are included. + + [!code-vb[VbLINQBasicOps#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#2)] + + You can use logical operators such as `And` and `Or` to combine filter expressions in a `Where` clause. For example, to return only those customers who are from London and whose name is Devon, use the following code: + +```vb Where cust.City = "London" And cust.Name = "Devon" -``` - - To return customers from London or Paris, use the following code: - -```vb +``` + + To return customers from London or Paris, use the following code: + +```vb Where cust.City = "London" Or cust.City = "Paris" -``` - - For more information about how to use the `Where` clause in Visual Basic, see [Where Clause](../../../language-reference/queries/where-clause.md). - -## Ordering Data (Order By) - - It often is convenient to sort returned data into a particular order. The `Order By` clause will cause the elements in the returned sequence to be sorted on a specified field or fields. For example, the following query sorts the results based on the `Name` property. Because `Name` is a string, the returned data will be sorted alphabetically, from A to Z. - - [!code-vb[VbLINQBasicOps#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#3)] - - To order the results in reverse order, from Z to A, use the `Order By...Descending` clause. The default is `Ascending` when neither `Ascending` nor `Descending` is specified. - - For more information about how to use the `Order By` clause in Visual Basic, see [Order By Clause](../../../language-reference/queries/order-by-clause.md). - -## Selecting Data (Select) - - The `Select` clause specifies the form and content of returned elements. For example, you can specify whether your results will consist of complete `Customer` objects, just one `Customer` property, a subset of properties, a combination of properties from various data sources, or some new result type based on a computation. When the `Select` clause produces something other than a copy of the source element, the operation is called a *projection*. - - To retrieve a collection that consists of complete `Customer` objects, select the range variable itself: - - [!code-vb[VbLINQBasicOps#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#4)] - - If a `Customer` instance is a large object that has many fields, and all that you want to retrieve is the name, you can select `cust.Name`, as shown in the following example. Local type inference recognizes that this changes the result type from a collection of `Customer` objects to a collection of strings. - - [!code-vb[VbLINQBasicOps#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#5)] - - To select multiple fields from the data source, you have two choices: - -- In the `Select` clause, specify the fields you want to include in the result. The compiler will define an anonymous type that has those fields as its properties. For more information, see [Anonymous Types](../../language-features/objects-and-classes/anonymous-types.md). - - Because the returned elements in the following example are instances of an anonymous type, you cannot refer to the type by name elsewhere in your code. The compiler-designated name for the type contains characters that are not valid in normal Visual Basic code. In the following example, the elements in the collection that is returned by the query in `londonCusts4` are instances of an anonymous type - - [!code-vb[VbLINQBasicOps#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#6)] - - -or- - -- Define a named type that contains the particular fields that you want to include in the result, and create and initialize instances of the type in the `Select` clause. Use this option only if you have to use individual results outside the collection in which they are returned, or if you have to pass them as parameters in method calls. The type of `londonCusts5` in the following example is IEnumerable(Of NamePhone). - - [!code-vb[VbLINQBasicOps#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#7)] - - [!code-vb[VbLINQBasicOps#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#8)] - - For more information about how to use the `Select` clause in Visual Basic, see [Select Clause](../../../language-reference/queries/select-clause.md). - -## Joining Data (Join and Group Join) - - You can combine more than one data source in the `From` clause in several ways. For example, the following code uses two data sources and implicitly combines properties from both of them in the result. The query selects students whose last names start with a vowel. - - [!code-vb[VbLINQBasicOps#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#9)] - +``` + + For more information about how to use the `Where` clause in Visual Basic, see [Where Clause](../../../language-reference/queries/where-clause.md). + +## Ordering Data (Order By) + + It often is convenient to sort returned data into a particular order. The `Order By` clause will cause the elements in the returned sequence to be sorted on a specified field or fields. For example, the following query sorts the results based on the `Name` property. Because `Name` is a string, the returned data will be sorted alphabetically, from A to Z. + + [!code-vb[VbLINQBasicOps#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#3)] + + To order the results in reverse order, from Z to A, use the `Order By...Descending` clause. The default is `Ascending` when neither `Ascending` nor `Descending` is specified. + + For more information about how to use the `Order By` clause in Visual Basic, see [Order By Clause](../../../language-reference/queries/order-by-clause.md). + +## Selecting Data (Select) + + The `Select` clause specifies the form and content of returned elements. For example, you can specify whether your results will consist of complete `Customer` objects, just one `Customer` property, a subset of properties, a combination of properties from various data sources, or some new result type based on a computation. When the `Select` clause produces something other than a copy of the source element, the operation is called a *projection*. + + To retrieve a collection that consists of complete `Customer` objects, select the range variable itself: + + [!code-vb[VbLINQBasicOps#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#4)] + + If a `Customer` instance is a large object that has many fields, and all that you want to retrieve is the name, you can select `cust.Name`, as shown in the following example. Local type inference recognizes that this changes the result type from a collection of `Customer` objects to a collection of strings. + + [!code-vb[VbLINQBasicOps#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#5)] + + To select multiple fields from the data source, you have two choices: + +- In the `Select` clause, specify the fields you want to include in the result. The compiler will define an anonymous type that has those fields as its properties. For more information, see [Anonymous Types](../../language-features/objects-and-classes/anonymous-types.md). + + Because the returned elements in the following example are instances of an anonymous type, you cannot refer to the type by name elsewhere in your code. The compiler-designated name for the type contains characters that are not valid in normal Visual Basic code. In the following example, the elements in the collection that is returned by the query in `londonCusts4` are instances of an anonymous type + + [!code-vb[VbLINQBasicOps#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#6)] + + -or- + +- Define a named type that contains the particular fields that you want to include in the result, and create and initialize instances of the type in the `Select` clause. Use this option only if you have to use individual results outside the collection in which they are returned, or if you have to pass them as parameters in method calls. The type of `londonCusts5` in the following example is IEnumerable(Of NamePhone). + + [!code-vb[VbLINQBasicOps#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#7)] + + [!code-vb[VbLINQBasicOps#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#8)] + + For more information about how to use the `Select` clause in Visual Basic, see [Select Clause](../../../language-reference/queries/select-clause.md). + +## Joining Data (Join and Group Join) + + You can combine more than one data source in the `From` clause in several ways. For example, the following code uses two data sources and implicitly combines properties from both of them in the result. The query selects students whose last names start with a vowel. + + [!code-vb[VbLINQBasicOps#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#9)] + > [!NOTE] -> You can run this code with the list of students created in [How to: Create a List of Items](how-to-create-a-list-of-items.md). - - The `Join` keyword is equivalent to an `INNER JOIN` in SQL. It combines two collections based on matching key values between elements in the two collections. The query returns all or part of the collection elements that have matching key values. For example, the following code duplicates the action of the previous implicit join. - - [!code-vb[VbLINQBasicOps#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#10)] - - `Group Join` combines collections into a single hierarchical collection, just like a `LEFT JOIN` in SQL. For more information, see [Join Clause](../../../language-reference/queries/join-clause.md) and [Group Join Clause](../../../language-reference/queries/group-join-clause.md). - -## Grouping Data (Group By) - - You can add a `Group By` clause to group the elements in a query result according to one or more fields of the elements. For example, the following code groups students by class year. - - [!code-vb[VbLINQBasicOps#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#11)] - - If you run this code using the list of students created in [How to: Create a List of Items](how-to-create-a-list-of-items.md), the output from the `For Each` statement is: - - Year: Junior - - Tucker, Michael - - Garcia, Hugo - - Garcia, Debra - - Tucker, Lance - - Year: Senior - - Omelchenko, Svetlana - - Osada, Michiko - - Fakhouri, Fadi - - Feng, Hanying - - Adams, Terry - - Year: Freshman - - Mortensen, Sven - - Garcia, Cesar - - The variation shown in the following code orders the class years, and then orders the students within each year by last name. - - [!code-vb[VbLINQBasicOps#12](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#12)] - - For more information about `Group By`, see [Group By Clause](../../../language-reference/queries/group-by-clause.md). - +> You can run this code with the list of students created in [How to: Create a List of Items](how-to-create-a-list-of-items.md). + + The `Join` keyword is equivalent to an `INNER JOIN` in SQL. It combines two collections based on matching key values between elements in the two collections. The query returns all or part of the collection elements that have matching key values. For example, the following code duplicates the action of the previous implicit join. + + [!code-vb[VbLINQBasicOps#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#10)] + + `Group Join` combines collections into a single hierarchical collection, just like a `LEFT JOIN` in SQL. For more information, see [Join Clause](../../../language-reference/queries/join-clause.md) and [Group Join Clause](../../../language-reference/queries/group-join-clause.md). + +## Grouping Data (Group By) + + You can add a `Group By` clause to group the elements in a query result according to one or more fields of the elements. For example, the following code groups students by class year. + + [!code-vb[VbLINQBasicOps#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#11)] + + If you run this code using the list of students created in [How to: Create a List of Items](how-to-create-a-list-of-items.md), the output from the `For Each` statement is: + + Year: Junior + + Tucker, Michael + + Garcia, Hugo + + Garcia, Debra + + Tucker, Lance + + Year: Senior + + Omelchenko, Svetlana + + Osada, Michiko + + Fakhouri, Fadi + + Feng, Hanying + + Adams, Terry + + Year: Freshman + + Mortensen, Sven + + Garcia, Cesar + + The variation shown in the following code orders the class years, and then orders the students within each year by last name. + + [!code-vb[VbLINQBasicOps#12](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQBasicOps/VB/Class1.vb#12)] + + For more information about `Group By`, see [Group By Clause](../../../language-reference/queries/group-by-clause.md). + ## See also -- +- - [Getting Started with LINQ in Visual Basic](getting-started-with-linq.md) - [Queries](../../../language-reference/queries/index.md) - [Standard Query Operators Overview (Visual Basic)](standard-query-operators-overview.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/classification-of-standard-query-operators-by-manner-of-execution.md b/docs/visual-basic/programming-guide/concepts/linq/classification-of-standard-query-operators-by-manner-of-execution.md index ef66d11752b44..a174561c0a911 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/classification-of-standard-query-operators-by-manner-of-execution.md +++ b/docs/visual-basic/programming-guide/concepts/linq/classification-of-standard-query-operators-by-manner-of-execution.md @@ -16,7 +16,7 @@ The LINQ to Objects implementations of the standard query operator methods execu ### Deferred - Deferred execution means that the operation is not performed at the point in the code where the query is declared. The operation is performed only when the query variable is enumerated, for example by using a `For Each` statement. This means that the results of executing the query depend on the contents of the data source when the query is executed rather than when the query is defined. If the query variable is enumerated multiple times, the results might differ every time. Almost all the standard query operators whose return type is or execute in a deferred manner. + Deferred execution means that the operation is not performed at the point in the code where the query is declared. The operation is performed only when the query variable is enumerated, for example by using a `For Each` statement. This means that the results of executing the query depend on the contents of the data source when the query is executed rather than when the query is defined. If the query variable is enumerated multiple times, the results might differ every time. Almost all the standard query operators whose return type is or execute in a deferred manner. Query operators that use deferred execution can be additionally classified as streaming or non-streaming. @@ -37,56 +37,56 @@ The LINQ to Objects implementations of the standard query operator methods execu |Standard Query Operator|Return Type|Immediate Execution|Deferred Streaming Execution|Deferred Non-Streaming Execution| |-----------------------------|-----------------|-------------------------|----------------------------------|---------------------------------------| -||TSource|X||| -|||X||| -|||X||| -||||X|| -||Single numeric value|X||| -||||X|| -||||X|| -|||X||| -|||X||| -||||X|| -||||X|| -||TSource|X||| -||TSource|X||| -|||X||| -||||X|X| -||TSource|X||| -||TSource|X||| -|||||X| -||||X|X| -||||X|X| -||||X|X| -||TSource|X||| -||TSource|X||| -|||X||| -||Single numeric value, TSource, or TResult|X||| -||Single numeric value, TSource, or TResult|X||| -||||X|| -|||||X| -|||||X| -||||X|| -||||X|| -|||||X| -||||X|| -||||X|| -|||X||| -||TSource|X||| -||TSource|X||| -||||X|| -||||X|| -||Single numeric value|X||| -||||X|| -||||X|| -|||||X| -|||||X| -||TSource array|X||| -|||X||| -|||X||| -|||X||| -||||X|| -||||X|| +||TSource|X||| +|||X||| +|||X||| +||||X|| +||Single numeric value|X||| +||||X|| +||||X|| +|||X||| +|||X||| +||||X|| +||||X|| +||TSource|X||| +||TSource|X||| +|||X||| +||||X|X| +||TSource|X||| +||TSource|X||| +|||||X| +||||X|X| +||||X|X| +||||X|X| +||TSource|X||| +||TSource|X||| +|||X||| +||Single numeric value, TSource, or TResult|X||| +||Single numeric value, TSource, or TResult|X||| +||||X|| +|||||X| +|||||X| +||||X|| +||||X|| +|||||X| +||||X|| +||||X|| +|||X||| +||TSource|X||| +||TSource|X||| +||||X|| +||||X|| +||Single numeric value|X||| +||||X|| +||||X|| +|||||X| +|||||X| +||TSource array|X||| +|||X||| +|||X||| +|||X||| +||||X|| +||||X|| ## See also diff --git a/docs/visual-basic/programming-guide/concepts/linq/concatenation-operations.md b/docs/visual-basic/programming-guide/concepts/linq/concatenation-operations.md index ec48cff1fe29f..5434c108a9494 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/concatenation-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/concatenation-operations.md @@ -6,20 +6,20 @@ ms.assetid: 4021e019-a8f7-477b-879e-07dd7f44feb9 --- # Concatenation Operations (Visual Basic) -Concatenation refers to the operation of appending one sequence to another. - - The following illustration depicts a concatenation operation on two sequences of characters. - - ![Graphic showing concatenation of two sequences.](./media/concatenation-operations/concatenation-two-sequences.png) - - The standard query operator methods that perform concatenation are listed in the following section. - -## Methods - -|Method Name|Description|Visual Basic Query Expression Syntax|More Information| -|-----------------|-----------------|------------------------------------------|----------------------| -|Concat|Concatenates two sequences to form one sequence.|Not applicable.|

| - +Concatenation refers to the operation of appending one sequence to another. + + The following illustration depicts a concatenation operation on two sequences of characters. + + ![Graphic showing concatenation of two sequences.](./media/concatenation-operations/concatenation-two-sequences.png) + + The standard query operator methods that perform concatenation are listed in the following section. + +## Methods + +|Method Name|Description|Visual Basic Query Expression Syntax|More Information| +|-----------------|-----------------|------------------------------------------|----------------------| +|Concat|Concatenates two sequences to form one sequence.|Not applicable.|

| + ## See also - diff --git a/docs/visual-basic/programming-guide/concepts/linq/converting-data-types.md b/docs/visual-basic/programming-guide/concepts/linq/converting-data-types.md index 24a4068400425..f51fdaf83d6ef 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/converting-data-types.md +++ b/docs/visual-basic/programming-guide/concepts/linq/converting-data-types.md @@ -10,11 +10,11 @@ Conversion methods change the type of input objects. Conversion operations in LINQ queries are useful in a variety of applications. The following are some examples: -- The method can be used to hide a type's custom implementation of a standard query operator. +- The method can be used to hide a type's custom implementation of a standard query operator. -- The method can be used to enable non-parameterized collections for LINQ querying. +- The method can be used to enable non-parameterized collections for LINQ querying. -- The , , , and methods can be used to force immediate query execution instead of deferring it until the query is enumerated. +- The , , , and methods can be used to force immediate query execution instead of deferring it until the query is enumerated. ## Methods @@ -24,14 +24,14 @@ The conversion methods in this table whose names start with "As" change the stat |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|AsEnumerable|Returns the input typed as .|Not applicable.|| -|AsQueryable|Converts a (generic) to a (generic) .|Not applicable.|| -|Cast|Casts the elements of a collection to a specified type.|`From … As …`|

| -|OfType|Filters values, depending on their ability to be cast to a specified type.|Not applicable.|

| -|ToArray|Converts a collection to an array. This method forces query execution.|Not applicable.|| -|ToDictionary|Puts elements into a based on a key selector function. This method forces query execution.|Not applicable.|| -|ToList|Converts a collection to a . This method forces query execution.|Not applicable.|| -|ToLookup|Puts elements into a (a one-to-many dictionary) based on a key selector function. This method forces query execution.|Not applicable.|| +|AsEnumerable|Returns the input typed as .|Not applicable.|| +|AsQueryable|Converts a (generic) to a (generic) .|Not applicable.|| +|Cast|Casts the elements of a collection to a specified type.|`From … As …`|

| +|OfType|Filters values, depending on their ability to be cast to a specified type.|Not applicable.|

| +|ToArray|Converts a collection to an array. This method forces query execution.|Not applicable.|| +|ToDictionary|Puts elements into a based on a key selector function. This method forces query execution.|Not applicable.|| +|ToList|Converts a collection to a . This method forces query execution.|Not applicable.|| +|ToLookup|Puts elements into a (a one-to-many dictionary) based on a key selector function. This method forces query execution.|Not applicable.|| ## Query Expression Syntax Example diff --git a/docs/visual-basic/programming-guide/concepts/linq/element-operations.md b/docs/visual-basic/programming-guide/concepts/linq/element-operations.md index 31ba667054aa3..782d9e97543f8 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/element-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/element-operations.md @@ -6,23 +6,23 @@ ms.assetid: 5fcb0631-dce5-45ff-8abb-353cae21e14f --- # Element Operations (Visual Basic) -Element operations return a single, specific element from a sequence. - - The standard query operator methods that perform element operations are listed in the following section. - -## Methods - -|Method Name|Description|Visual Basic Query Expression Syntax|More Information| -|-----------------|-----------------|------------------------------------------|----------------------| -|ElementAt|Returns the element at a specified index in a collection.|Not applicable.|

| -|ElementAtOrDefault|Returns the element at a specified index in a collection or a default value if the index is out of range.|Not applicable.|

| -|First|Returns the first element of a collection, or the first element that satisfies a condition.|Not applicable.|

| -|FirstOrDefault|Returns the first element of a collection, or the first element that satisfies a condition. Returns a default value if no such element exists.|Not applicable.|



| -|Last|Returns the last element of a collection, or the last element that satisfies a condition.|Not applicable.|

| -|LastOrDefault|Returns the last element of a collection, or the last element that satisfies a condition. Returns a default value if no such element exists.|Not applicable.|

| -|Single|Returns the only element of a collection, or the only element that satisfies a condition.|Not applicable.|

| -|SingleOrDefault|Returns the only element of a collection, or the only element that satisfies a condition. Returns a default value if no such element exists or the collection does not contain exactly one element.|Not applicable.|

| - +Element operations return a single, specific element from a sequence. + + The standard query operator methods that perform element operations are listed in the following section. + +## Methods + +|Method Name|Description|Visual Basic Query Expression Syntax|More Information| +|-----------------|-----------------|------------------------------------------|----------------------| +|ElementAt|Returns the element at a specified index in a collection.|Not applicable.|

| +|ElementAtOrDefault|Returns the element at a specified index in a collection or a default value if the index is out of range.|Not applicable.|

| +|First|Returns the first element of a collection, or the first element that satisfies a condition.|Not applicable.|

| +|FirstOrDefault|Returns the first element of a collection, or the first element that satisfies a condition. Returns a default value if no such element exists.|Not applicable.|



| +|Last|Returns the last element of a collection, or the last element that satisfies a condition.|Not applicable.|

| +|LastOrDefault|Returns the last element of a collection, or the last element that satisfies a condition. Returns a default value if no such element exists.|Not applicable.|

| +|Single|Returns the only element of a collection, or the only element that satisfies a condition.|Not applicable.|

| +|SingleOrDefault|Returns the only element of a collection, or the only element that satisfies a condition. Returns a default value if no such element exists or the collection does not contain exactly one element.|Not applicable.|

| + ## See also - diff --git a/docs/visual-basic/programming-guide/concepts/linq/enabling-a-data-source-for-linq-querying.md b/docs/visual-basic/programming-guide/concepts/linq/enabling-a-data-source-for-linq-querying.md index 6240459b27aad..0e95961530b34 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/enabling-a-data-source-for-linq-querying.md +++ b/docs/visual-basic/programming-guide/concepts/linq/enabling-a-data-source-for-linq-querying.md @@ -8,11 +8,11 @@ ms.assetid: c412f0cf-ff0e-4993-ab3d-1b49e23f00f8 There are various ways to extend LINQ to enable any data source to be queried in the LINQ pattern. The data source might be a data structure, a Web service, a file system, or a database, to name some. The LINQ pattern makes it easy for clients to query a data source for which LINQ querying is enabled, because the syntax and pattern of the query does not change. The ways in which LINQ can be extended to these data sources include the following: -- Implementing the interface in a type to enable LINQ to Objects querying of that type. +- Implementing the interface in a type to enable LINQ to Objects querying of that type. -- Creating standard query operator methods such as and that extend a type, to enable custom LINQ querying of that type. +- Creating standard query operator methods such as and that extend a type, to enable custom LINQ querying of that type. -- Creating a provider for your data source that implements the interface. A provider that implements this interface receives LINQ queries in the form of expression trees, which it can execute in a custom way, for example remotely. +- Creating a provider for your data source that implements the interface. A provider that implements this interface receives LINQ queries in the form of expression trees, which it can execute in a custom way, for example remotely. - Creating a provider for your data source that takes advantage of an existing LINQ technology. Such a provider would enable not only querying, but also insert, update, and delete operations and mapping for user-defined types. @@ -22,15 +22,15 @@ This topic discusses these options. ### In-Memory Data - There are two ways you can enable LINQ querying of in-memory data. If the data is of a type that implements , you can query the data by using LINQ to Objects. If it does not make sense to enable enumeration of your type by implementing the interface, you can define LINQ standard query operator methods in that type or create LINQ standard query operator methods that extend the type. Custom implementations of the standard query operators should use deferred execution to return the results. + There are two ways you can enable LINQ querying of in-memory data. If the data is of a type that implements , you can query the data by using LINQ to Objects. If it does not make sense to enable enumeration of your type by implementing the interface, you can define LINQ standard query operator methods in that type or create LINQ standard query operator methods that extend the type. Custom implementations of the standard query operators should use deferred execution to return the results. ### Remote Data - The best option for enabling LINQ querying of a remote data source is to implement the interface. However, this differs from extending a provider such as [!INCLUDE[vbtecdlinq](~/includes/vbtecdlinq-md.md)] for a data source. No provider models for extending existing LINQ technologies, such as [!INCLUDE[vbtecdlinq](~/includes/vbtecdlinq-md.md)], to other types of data source are available in Visual Studio 2008. + The best option for enabling LINQ querying of a remote data source is to implement the interface. However, this differs from extending a provider such as [!INCLUDE[vbtecdlinq](~/includes/vbtecdlinq-md.md)] for a data source. No provider models for extending existing LINQ technologies, such as [!INCLUDE[vbtecdlinq](~/includes/vbtecdlinq-md.md)], to other types of data source are available in Visual Studio 2008. ## IQueryable LINQ Providers - LINQ providers that implement can vary widely in their complexity. This section discusses the different levels of complexity. + LINQ providers that implement can vary widely in their complexity. This section discusses the different levels of complexity. A less complex `IQueryable` provider might interface with a single method of a Web service. This type of provider is very specific because it expects specific information in the queries that it handles. It has a closed type system, perhaps exposing a single result type. Most of the execution of the query occurs locally, for example by using the implementations of the standard query operators. A less complex provider might examine only one method call expression in the expression tree that represents the query, and let the remaining logic of the query be handled elsewhere. @@ -40,8 +40,8 @@ This topic discusses these options. ## See also -- -- +- +- - - [Standard Query Operators Overview (Visual Basic)](standard-query-operators-overview.md) - [LINQ to Objects (Visual Basic)](linq-to-objects.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/equality-operations.md b/docs/visual-basic/programming-guide/concepts/linq/equality-operations.md index e59ae6f764515..4c1534a8d97f6 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/equality-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/equality-operations.md @@ -6,14 +6,14 @@ ms.assetid: 1f2fcf87-6f52-4830-b9af-861f9ad999dc --- # Equality Operations (Visual Basic) -Two sequences whose corresponding elements are equal and which have the same number of elements are considered equal. - -## Methods - -|Method Name|Description|Visual Basic Query Expression Syntax|More Information| -|-----------------|-----------------|------------------------------------------|----------------------| -|SequenceEqual|Determines whether two sequences are equal by comparing elements in a pair-wise manner.|Not applicable.|

| - +Two sequences whose corresponding elements are equal and which have the same number of elements are considered equal. + +## Methods + +|Method Name|Description|Visual Basic Query Expression Syntax|More Information| +|-----------------|-----------------|------------------------------------------|----------------------| +|SequenceEqual|Determines whether two sequences are equal by comparing elements in a pair-wise manner.|Not applicable.|

| + ## See also - diff --git a/docs/visual-basic/programming-guide/concepts/linq/features-that-support-linq.md b/docs/visual-basic/programming-guide/concepts/linq/features-that-support-linq.md index 475ce95a748e6..9a9a2806f4343 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/features-that-support-linq.md +++ b/docs/visual-basic/programming-guide/concepts/linq/features-that-support-linq.md @@ -2,99 +2,99 @@ description: "Learn more about: Visual Basic Features That Support LINQ" title: "Features That Support LINQ" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "Visual Basic, LINQ features" - "LINQ [Visual Basic], features supporting LINQ" ms.assetid: c821bb50-b6f6-4cf9-8aba-2717e465bd3a --- # Visual Basic Features That Support LINQ -The name Language-Integrated Query (LINQ) refers to technology in Visual Basic that supports query syntax and other language constructs directly in the language. With LINQ, you do not have to learn a new language to query against an external data source. You can query against data in relational databases, XML stores, or objects by using Visual Basic. This integration of query capabilities into the language enables compile-time checking for syntax errors and type safety. This integration also ensures that you already know most of what you have to know to write rich, varied queries in Visual Basic. - - The following sections describe the language constructs that support LINQ in enough detail to enable you to get started in reading the introductory documentation, code examples, and sample applications. You can also click the links to find more detailed explanations of how the language features come together to enable language-integrated query. A good place to start is [Walkthrough: Writing Queries in Visual Basic](walkthrough-writing-queries.md). - -## Query Expressions - - Query expressions in Visual Basic can be expressed in a declarative syntax similar to that of SQL or XQuery. At compile time, query syntax is converted into method calls to a LINQ provider's implementation of the standard query operator extension methods. Applications control which standard query operators are in scope by specifying the appropriate namespace with an `Imports` statement. Syntax for a Visual Basic query expression looks like this: - - [!code-vb[VbLINQVbFeatures#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#1)] - - For more information, see [Introduction to LINQ in Visual Basic](../../language-features/linq/introduction-to-linq.md). - -## Implicitly Typed Variables - - Instead of explicitly specifying a type when you declare and initialize a variable, you can enable the compiler to infer and assign the type. This is referred to as *local type inference*. - - Variables whose types are inferred are strongly typed, just like variables whose type you specify explicitly. Local type inference works only when you are defining a local variable inside a method body. For more information, see [Option Infer Statement](../../../language-reference/statements/option-infer-statement.md) and [Local Type Inference](../../language-features/variables/local-type-inference.md). - - The following example illustrates local type inference. To use this example, you must set `Option Infer` to `On`. - - [!code-vb[VbLINQVbFeatures#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#2)] - - Local type inference also makes it possible to create anonymous types, which are described later in this section and are necessary for LINQ queries. - - In the following LINQ example, type inference occurs if `Option Infer` is either `On` or `Off`. A compile-time error occurs if `Option Infer` is `Off` and `Option Strict` is `On`. - - [!code-vb[VbLINQVbFeatures#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#3)] - -## Object Initializers - - Object initializers are used in query expressions when you have to create an anonymous type to hold the results of a query. They also can be used to initialize objects of named types outside of queries. By using an object initializer, you can initialize an object in a single line without explicitly calling a constructor. Assuming that you have a class named `Customer` that has public `Name` and `Phone` properties, along with other properties, an object initializer can be used in this manner: - - [!code-vb[VbLINQVbFeatures#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#4)] - - For more information, see [Object Initializers: Named and Anonymous Types](../../language-features/objects-and-classes/object-initializers-named-and-anonymous-types.md). - -## Anonymous Types - - Anonymous types provide a convenient way to temporarily group a set of properties into an element that you want to include in a query result. This enables you to choose any combination of available fields in the query, in any order, without defining a named data type for the element. - - An *anonymous type* is constructed dynamically by the compiler. The name of the type is assigned by the compiler, and it might change with each new compilation. Therefore, the name cannot be used directly. Anonymous types are initialized in the following way: - - [!code-vb[VbLINQVbFeatures#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#5)] - - For more information, see [Anonymous Types](../../language-features/objects-and-classes/anonymous-types.md). - -## Extension Methods - - Extension methods enable you to add methods to a data type or interface from outside the definition. This feature enables you to, in effect, add new methods to an existing type without actually modifying the type. The standard query operators are themselves a set of extension methods that provide LINQ query functionality for any type that implements . Other extensions to include , , and . - - The following extension method adds a print method to the class. - - [!code-vb[VbLINQVbFeatures#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#6)] - - The method is called like an ordinary instance method of : - - [!code-vb[VbLINQVbFeatures#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#7)] - - For more information, see [Extension Methods](../../language-features/procedures/extension-methods.md). - -## Lambda Expressions - - A lambda expression is a function without a name that calculates and returns a single value. Unlike named functions, a lambda expression can be defined and executed at the same time. The following example displays 4. - - [!code-vb[VbLINQVbFeatures#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#8)] - - You can assign the lambda expression definition to a variable name and then use the name to call the function. The following example also displays 4. - - [!code-vb[VbLINQVbFeatures#12](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#12)] - - In LINQ, lambda expressions underlie many of the standard query operators. The compiler creates lambda expressions to capture the calculations that are defined in fundamental query methods such as `Where`, `Select`, `Order By`, `Take While`, and others. - - For example, the following code defines a query that returns all senior students from a list of students. - - [!code-vb[VbLINQVbFeatures#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#9)] - - The query definition is compiled into code that is similar to the following example, which uses two lambda expressions to specify the arguments for `Where` and `Select`. - - [!code-vb[VbLINQVbFeatures#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#10)] - - Either version can be run by using a `For Each` loop: - - [!code-vb[VbLINQVbFeatures#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#11)] - - For more information, see [Lambda Expressions](../../language-features/procedures/lambda-expressions.md). - +The name Language-Integrated Query (LINQ) refers to technology in Visual Basic that supports query syntax and other language constructs directly in the language. With LINQ, you do not have to learn a new language to query against an external data source. You can query against data in relational databases, XML stores, or objects by using Visual Basic. This integration of query capabilities into the language enables compile-time checking for syntax errors and type safety. This integration also ensures that you already know most of what you have to know to write rich, varied queries in Visual Basic. + + The following sections describe the language constructs that support LINQ in enough detail to enable you to get started in reading the introductory documentation, code examples, and sample applications. You can also click the links to find more detailed explanations of how the language features come together to enable language-integrated query. A good place to start is [Walkthrough: Writing Queries in Visual Basic](walkthrough-writing-queries.md). + +## Query Expressions + + Query expressions in Visual Basic can be expressed in a declarative syntax similar to that of SQL or XQuery. At compile time, query syntax is converted into method calls to a LINQ provider's implementation of the standard query operator extension methods. Applications control which standard query operators are in scope by specifying the appropriate namespace with an `Imports` statement. Syntax for a Visual Basic query expression looks like this: + + [!code-vb[VbLINQVbFeatures#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#1)] + + For more information, see [Introduction to LINQ in Visual Basic](../../language-features/linq/introduction-to-linq.md). + +## Implicitly Typed Variables + + Instead of explicitly specifying a type when you declare and initialize a variable, you can enable the compiler to infer and assign the type. This is referred to as *local type inference*. + + Variables whose types are inferred are strongly typed, just like variables whose type you specify explicitly. Local type inference works only when you are defining a local variable inside a method body. For more information, see [Option Infer Statement](../../../language-reference/statements/option-infer-statement.md) and [Local Type Inference](../../language-features/variables/local-type-inference.md). + + The following example illustrates local type inference. To use this example, you must set `Option Infer` to `On`. + + [!code-vb[VbLINQVbFeatures#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#2)] + + Local type inference also makes it possible to create anonymous types, which are described later in this section and are necessary for LINQ queries. + + In the following LINQ example, type inference occurs if `Option Infer` is either `On` or `Off`. A compile-time error occurs if `Option Infer` is `Off` and `Option Strict` is `On`. + + [!code-vb[VbLINQVbFeatures#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#3)] + +## Object Initializers + + Object initializers are used in query expressions when you have to create an anonymous type to hold the results of a query. They also can be used to initialize objects of named types outside of queries. By using an object initializer, you can initialize an object in a single line without explicitly calling a constructor. Assuming that you have a class named `Customer` that has public `Name` and `Phone` properties, along with other properties, an object initializer can be used in this manner: + + [!code-vb[VbLINQVbFeatures#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#4)] + + For more information, see [Object Initializers: Named and Anonymous Types](../../language-features/objects-and-classes/object-initializers-named-and-anonymous-types.md). + +## Anonymous Types + + Anonymous types provide a convenient way to temporarily group a set of properties into an element that you want to include in a query result. This enables you to choose any combination of available fields in the query, in any order, without defining a named data type for the element. + + An *anonymous type* is constructed dynamically by the compiler. The name of the type is assigned by the compiler, and it might change with each new compilation. Therefore, the name cannot be used directly. Anonymous types are initialized in the following way: + + [!code-vb[VbLINQVbFeatures#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#5)] + + For more information, see [Anonymous Types](../../language-features/objects-and-classes/anonymous-types.md). + +## Extension Methods + + Extension methods enable you to add methods to a data type or interface from outside the definition. This feature enables you to, in effect, add new methods to an existing type without actually modifying the type. The standard query operators are themselves a set of extension methods that provide LINQ query functionality for any type that implements . Other extensions to include , , and . + + The following extension method adds a print method to the class. + + [!code-vb[VbLINQVbFeatures#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#6)] + + The method is called like an ordinary instance method of : + + [!code-vb[VbLINQVbFeatures#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#7)] + + For more information, see [Extension Methods](../../language-features/procedures/extension-methods.md). + +## Lambda Expressions + + A lambda expression is a function without a name that calculates and returns a single value. Unlike named functions, a lambda expression can be defined and executed at the same time. The following example displays 4. + + [!code-vb[VbLINQVbFeatures#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#8)] + + You can assign the lambda expression definition to a variable name and then use the name to call the function. The following example also displays 4. + + [!code-vb[VbLINQVbFeatures#12](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#12)] + + In LINQ, lambda expressions underlie many of the standard query operators. The compiler creates lambda expressions to capture the calculations that are defined in fundamental query methods such as `Where`, `Select`, `Order By`, `Take While`, and others. + + For example, the following code defines a query that returns all senior students from a list of students. + + [!code-vb[VbLINQVbFeatures#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#9)] + + The query definition is compiled into code that is similar to the following example, which uses two lambda expressions to specify the arguments for `Where` and `Select`. + + [!code-vb[VbLINQVbFeatures#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#10)] + + Either version can be run by using a `For Each` loop: + + [!code-vb[VbLINQVbFeatures#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQVbFeatures/VB/Class1.vb#11)] + + For more information, see [Lambda Expressions](../../language-features/procedures/lambda-expressions.md). + ## See also - [Language-Integrated Query (LINQ) (Visual Basic)](index.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/filtering-data.md b/docs/visual-basic/programming-guide/concepts/linq/filtering-data.md index ed7b4d43d51b4..4c512a627e5ec 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/filtering-data.md +++ b/docs/visual-basic/programming-guide/concepts/linq/filtering-data.md @@ -18,8 +18,8 @@ The standard query operator methods that perform selection are listed in the fol |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|OfType|Selects values, depending on their ability to be cast to a specified type.|Not applicable.|

| -|Where|Selects values that are based on a predicate function.|`Where`|

| +|OfType|Selects values, depending on their ability to be cast to a specified type.|Not applicable.|

| +|Where|Selects values that are based on a predicate function.|`Where`|

| ## Query Expression Syntax Example diff --git a/docs/visual-basic/programming-guide/concepts/linq/generation-operations.md b/docs/visual-basic/programming-guide/concepts/linq/generation-operations.md index 031fb77a57cee..5d0212fd5f3e8 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/generation-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/generation-operations.md @@ -6,19 +6,19 @@ ms.assetid: 22b8e380-8eb0-4c93-b4ff-7ac21caf27d5 --- # Generation Operations (Visual Basic) -Generation refers to creating a new sequence of values. - - The standard query operator methods that perform generation are listed in the following section. - -## Methods - -|Method Name|Description|Visual Basic Query Expression Syntax|More Information| -|-----------------|-----------------|------------------------------------------|----------------------| -|DefaultIfEmpty|Replaces an empty collection with a default valued singleton collection.|Not applicable.|

| -|Empty|Returns an empty collection.|Not applicable.|| -|Range|Generates a collection that contains a sequence of numbers.|Not applicable.|| -|Repeat|Generates a collection that contains one repeated value.|Not applicable.|| - +Generation refers to creating a new sequence of values. + + The standard query operator methods that perform generation are listed in the following section. + +## Methods + +|Method Name|Description|Visual Basic Query Expression Syntax|More Information| +|-----------------|-----------------|------------------------------------------|----------------------| +|DefaultIfEmpty|Replaces an empty collection with a default valued singleton collection.|Not applicable.|

| +|Empty|Returns an empty collection.|Not applicable.|| +|Range|Generates a collection that contains a sequence of numbers.|Not applicable.|| +|Repeat|Generates a collection that contains one repeated value.|Not applicable.|| + ## See also - diff --git a/docs/visual-basic/programming-guide/concepts/linq/grouping-data.md b/docs/visual-basic/programming-guide/concepts/linq/grouping-data.md index 130dfd56ae17d..44886e621e7f6 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/grouping-data.md +++ b/docs/visual-basic/programming-guide/concepts/linq/grouping-data.md @@ -6,60 +6,60 @@ ms.assetid: 8f3a0871-6958-4aef-8f6f-493e189fd57d --- # Grouping Data (Visual Basic) -Grouping refers to the operation of putting data into groups so that the elements in each group share a common attribute. - - The following illustration shows the results of grouping a sequence of characters. The key for each group is the character. - - ![Diagram that shows a LINQ Grouping operation.](./media/grouping-data/linq-group-operation.png) - - The standard query operator methods that group data elements are listed in the following section. - -## Methods - -|Method Name|Description|Visual Basic Query Expression Syntax|More Information| -|-----------------|-----------------|------------------------------------------|----------------------| -|GroupBy|Groups elements that share a common attribute. Each group is represented by an object.|`Group … By … Into …`|

| -|ToLookup|Inserts elements into a (a one-to-many dictionary) based on a key selector function.|Not applicable.|| - -## Query Expression Syntax Example - - The following code example uses the `Group By` clause to group integers in a list according to whether they are even or odd. - -```vb -Dim numbers As New System.Collections.Generic.List(Of Integer)( - New Integer() {35, 44, 200, 84, 3987, 4, 199, 329, 446, 208}) - +Grouping refers to the operation of putting data into groups so that the elements in each group share a common attribute. + + The following illustration shows the results of grouping a sequence of characters. The key for each group is the character. + + ![Diagram that shows a LINQ Grouping operation.](./media/grouping-data/linq-group-operation.png) + + The standard query operator methods that group data elements are listed in the following section. + +## Methods + +|Method Name|Description|Visual Basic Query Expression Syntax|More Information| +|-----------------|-----------------|------------------------------------------|----------------------| +|GroupBy|Groups elements that share a common attribute. Each group is represented by an object.|`Group … By … Into …`|

| +|ToLookup|Inserts elements into a (a one-to-many dictionary) based on a key selector function.|Not applicable.|| + +## Query Expression Syntax Example + + The following code example uses the `Group By` clause to group integers in a list according to whether they are even or odd. + +```vb +Dim numbers As New System.Collections.Generic.List(Of Integer)( + New Integer() {35, 44, 200, 84, 3987, 4, 199, 329, 446, 208}) + Dim query = From number In numbers - Group By Remainder = (number Mod 2) Into Group - -Dim sb As New System.Text.StringBuilder() -For Each group In query - sb.AppendLine(If(group.Remainder = 0, vbCrLf & "Even numbers:", vbCrLf & "Odd numbers:")) - For Each num In group.Group - sb.AppendLine(num) - Next -Next - -' Display the results. -MsgBox(sb.ToString()) - -' This code produces the following output: - -' Odd numbers: -' 35 -' 3987 -' 199 -' 329 - -' Even numbers: -' 44 -' 200 -' 84 -' 4 -' 446 -' 208 -``` - + Group By Remainder = (number Mod 2) Into Group + +Dim sb As New System.Text.StringBuilder() +For Each group In query + sb.AppendLine(If(group.Remainder = 0, vbCrLf & "Even numbers:", vbCrLf & "Odd numbers:")) + For Each num In group.Group + sb.AppendLine(num) + Next +Next + +' Display the results. +MsgBox(sb.ToString()) + +' This code produces the following output: + +' Odd numbers: +' 35 +' 3987 +' 199 +' 329 + +' Even numbers: +' 44 +' 200 +' 84 +' 4 +' 446 +' 208 +``` + ## See also - diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-add-custom-methods-for-linq-queries.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-add-custom-methods-for-linq-queries.md index 9d44c8c9ec61a..ec80580b319a5 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-add-custom-methods-for-linq-queries.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-add-custom-methods-for-linq-queries.md @@ -6,19 +6,19 @@ ms.assetid: 099b2e2a-83cd-45c6-aa4d-01b398b5faaf --- # How to: Add custom methods for LINQ queries (Visual Basic) -You extend the set of methods that you use for LINQ queries by adding extension methods to the interface. For example, in addition to the standard average or maximum operations, you create a custom aggregate method to compute a single value from a sequence of values. You also create a method that works as a custom filter or a specific data transform for a sequence of values and returns a new sequence. Examples of such methods are , , and . +You extend the set of methods that you use for LINQ queries by adding extension methods to the interface. For example, in addition to the standard average or maximum operations, you create a custom aggregate method to compute a single value from a sequence of values. You also create a method that works as a custom filter or a specific data transform for a sequence of values and returns a new sequence. Examples of such methods are , , and . -When you extend the interface, you can apply your custom methods to any enumerable collection. For more information, see [Extension Methods](../../language-features/procedures/extension-methods.md). +When you extend the interface, you can apply your custom methods to any enumerable collection. For more information, see [Extension Methods](../../language-features/procedures/extension-methods.md). ## Adding an aggregate method -An aggregate method computes a single value from a set of values. LINQ provides several aggregate methods, including , , and . You can create your own aggregate method by adding an extension method to the interface. +An aggregate method computes a single value from a set of values. LINQ provides several aggregate methods, including , , and . You can create your own aggregate method by adding an extension method to the interface. The following code example shows how to create an extension method called `Median` to compute a median for a sequence of numbers of type `double`. :::code language="vb" source="./snippets/LinqExtension.vb" ::: -You call this extension method for any enumerable collection in the same way you call other aggregate methods from the interface. +You call this extension method for any enumerable collection in the same way you call other aggregate methods from the interface. > [!NOTE] > In Visual Basic, you can either use a method call or standard query syntax for the `Aggregate` or `Group By` clause. For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md) and [Group By Clause](../../../language-reference/queries/group-by-clause.md). @@ -45,29 +45,29 @@ You can now call the `Median` overloads for both `integer` and `double` types, a You can also create an overload that accepts a sequence of generic objects. This overload takes a delegate as a parameter and uses it to convert a sequence of objects of a generic type to a specific type. -The following code shows an overload of the `Median` method that takes the delegate as a parameter. This delegate takes an object of generic type `T` and returns an object of type `double`. +The following code shows an overload of the `Median` method that takes the delegate as a parameter. This delegate takes an object of generic type `T` and returns an object of type `double`. :::code language="vb" source="./snippets/OtherExtensions.vb" ID="GenericOverload"::: You can now call the `Median` method for a sequence of objects of any type. If the type does not have its own method overload, you have to pass a delegate parameter. In Visual Basic, you can use a lambda expression for this purpose. Also, if you use the `Aggregate` or `Group By` clause instead of the method call, you can pass any value or expression that is in the scope this clause. -The following example code shows how to call the `Median` method for an array of integers and an array of strings. For strings, the median for the lengths of strings in the array is calculated. The example shows how to pass the delegate parameter to the `Median` method for each case. +The following example code shows how to call the `Median` method for an array of integers and an array of strings. For strings, the median for the lengths of strings in the array is calculated. The example shows how to pass the delegate parameter to the `Median` method for each case. :::code language="vb" source="./snippets/Program.vb" ID="GenericUsage"::: ## Adding a method that returns a collection -You can extend the interface with a custom query method that returns a sequence of values. In this case, the method must return a collection of type . Such methods can be used to apply filters or data transforms to a sequence of values. +You can extend the interface with a custom query method that returns a sequence of values. In this case, the method must return a collection of type . Such methods can be used to apply filters or data transforms to a sequence of values. The following example shows how to create an extension method named `AlternateElements` that returns every other element in a collection, starting from the first element. :::code language="vb" source="./snippets/OtherExtensions.vb" ID="SequenceElement"::: -You can call this extension method for any enumerable collection just as you would call other methods from the interface, as shown in the following code: +You can call this extension method for any enumerable collection just as you would call other methods from the interface, as shown in the following code: :::code language="vb" source="./snippets/Program.vb" ID="SequenceUsage"::: ## See also -- +- - [Extension Methods](../../language-features/procedures/extension-methods.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-compute-column-values-in-a-csv-text-file-linq.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-compute-column-values-in-a-csv-text-file-linq.md index ec8d193bb73fc..9fa60149a9362 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-compute-column-values-in-a-csv-text-file-linq.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-compute-column-values-in-a-csv-text-file-linq.md @@ -136,7 +136,7 @@ End Class ' Exam #4 Average: 76.92 High Score: 94 Low Score: 39 ``` -The query works by using the method to convert each line of text into an array. Each array element represents a column. Finally, the text in each column is converted to its numeric representation. If your file is a tab-separated file, just update the argument in the `Split` method to `\t`. +The query works by using the method to convert each line of text into an array. Each array element represents a column. Finally, the text in each column is converted to its numeric representation. If your file is a tab-separated file, just update the argument in the `Split` method to `\t`. ## Compile the code diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-count-occurrences-of-a-word-in-a-string-linq.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-count-occurrences-of-a-word-in-a-string-linq.md index 3e5105d7dce9a..c4cbe0f554d2f 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-count-occurrences-of-a-word-in-a-string-linq.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-count-occurrences-of-a-word-in-a-string-linq.md @@ -6,7 +6,7 @@ ms.assetid: bc367e46-f7cc-45f9-936f-754e661b7bb9 --- # How to: Count Occurrences of a Word in a String (LINQ) (Visual Basic) -This example shows how to use a LINQ query to count the occurrences of a specified word in a string. Note that to perform the count, first the method is called to create an array of words. There is a performance cost to the method. If the only operation on the string is to count the words, you should consider using the or methods instead. However, if performance is not a critical issue, or you have already split the sentence in order to perform other types of queries over it, then it makes sense to use LINQ to count the words or phrases as well. +This example shows how to use a LINQ query to count the occurrences of a specified word in a string. Note that to perform the count, first the method is called to create an array of words. There is a performance cost to the method. If the only operation on the string is to count the words, you should consider using the or methods instead. However, if performance is not a critical issue, or you have already split the sentence in order to perform other types of queries over it, then it makes sense to use LINQ to count the words or phrases as well. ## Example diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-find-the-set-difference-between-two-lists-linq.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-find-the-set-difference-between-two-lists-linq.md index 88fdd3789a845..825c77ab8d12c 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-find-the-set-difference-between-two-lists-linq.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-find-the-set-difference-between-two-lists-linq.md @@ -6,53 +6,53 @@ ms.assetid: b5b25474-10a8-4df6-aab5-75621bb6b68e --- # How to: Find the Set Difference Between Two Lists (LINQ) (Visual Basic) -This example shows how to use LINQ to compare two lists of strings and output those lines that are in names1.txt but not in names2.txt. - -### To create the data files - -1. Copy names1.txt and names2.txt to your solution folder as shown in [How to: Combine and Compare String Collections (LINQ) (Visual Basic)](how-to-combine-and-compare-string-collections-linq.md). - -## Example - -```vb -Class CompareLists - - Shared Sub Main() - - ' Create the IEnumerable data sources. - Dim names1 As String() = System.IO.File.ReadAllLines("../../../names1.txt") - Dim names2 As String() = System.IO.File.ReadAllLines("../../../names2.txt") - - ' Create the query. Note that method syntax must be used here. - Dim differenceQuery = names1.Except(names2) - Console.WriteLine("The following lines are in names1.txt but not names2.txt") - - ' Execute the query. - For Each name As String In differenceQuery - Console.WriteLine(name) - Next - - ' Keep console window open in debug mode. - Console.WriteLine("Press any key to exit.") - Console.ReadKey() - End Sub -End Class -' Output: -' The following lines are in names1.txt but not names2.txt -' Potra, Cristina -' Noriega, Fabricio -' Aw, Kam Foo -' Toyoshima, Tim -' Guy, Wey Yuan -' Garcia, Debra -``` - - Some types of query operations in Visual Basic, such as , , , and , can only be expressed in method-based syntax. - -## Compile the code +This example shows how to use LINQ to compare two lists of strings and output those lines that are in names1.txt but not in names2.txt. + +### To create the data files + +1. Copy names1.txt and names2.txt to your solution folder as shown in [How to: Combine and Compare String Collections (LINQ) (Visual Basic)](how-to-combine-and-compare-string-collections-linq.md). + +## Example + +```vb +Class CompareLists + + Shared Sub Main() + + ' Create the IEnumerable data sources. + Dim names1 As String() = System.IO.File.ReadAllLines("../../../names1.txt") + Dim names2 As String() = System.IO.File.ReadAllLines("../../../names2.txt") + + ' Create the query. Note that method syntax must be used here. + Dim differenceQuery = names1.Except(names2) + Console.WriteLine("The following lines are in names1.txt but not names2.txt") + + ' Execute the query. + For Each name As String In differenceQuery + Console.WriteLine(name) + Next + + ' Keep console window open in debug mode. + Console.WriteLine("Press any key to exit.") + Console.ReadKey() + End Sub +End Class +' Output: +' The following lines are in names1.txt but not names2.txt +' Potra, Cristina +' Noriega, Fabricio +' Aw, Kam Foo +' Toyoshima, Tim +' Guy, Wey Yuan +' Garcia, Debra +``` + + Some types of query operations in Visual Basic, such as , , , and , can only be expressed in method-based syntax. + +## Compile the code Create a Visual Basic console application project, with an `Imports` statement for the System.Linq namespace. - + ## See also - [LINQ and Strings (Visual Basic)](linq-and-strings.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-group-files-by-extension-linq.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-group-files-by-extension-linq.md index 0f5f277a25894..689e4074385de 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-group-files-by-extension-linq.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-group-files-by-extension-linq.md @@ -6,94 +6,94 @@ ms.assetid: 904dc6d7-7162-4655-a7f4-5785d669bc5a --- # How to: Group Files by Extension (LINQ) (Visual Basic) -This example shows how LINQ can be used to perform advanced grouping and sorting operations on lists of files or folders. It also shows how to page output in the console window by using the and methods. - -## Example - - The following query shows how to group the contents of a specified directory tree by the file name extension. - -```vb -Module GroupByExtension - Public Sub Main() - - ' Root folder to query, along with all subfolders. - Dim startFolder As String = "C:\program files\Microsoft Visual Studio 9.0\VB\" - - ' Used in WriteLine() to skip over startfolder in output lines. - Dim rootLength As Integer = startFolder.Length - - 'Take a snapshot of the folder contents - Dim dir As New System.IO.DirectoryInfo(startFolder) - Dim fileList = dir.GetFiles("*.*", System.IO.SearchOption.AllDirectories) - - ' Create the query. - Dim queryGroupByExt = From file In fileList _ - Group By file.Extension.ToLower() Into fileGroup = Group _ - Order By ToLower _ - Select fileGroup - - ' Execute the query. By storing the result we can - ' page the display with good performance. - Dim groupByExtList = queryGroupByExt.ToList() - +This example shows how LINQ can be used to perform advanced grouping and sorting operations on lists of files or folders. It also shows how to page output in the console window by using the and methods. + +## Example + + The following query shows how to group the contents of a specified directory tree by the file name extension. + +```vb +Module GroupByExtension + Public Sub Main() + + ' Root folder to query, along with all subfolders. + Dim startFolder As String = "C:\program files\Microsoft Visual Studio 9.0\VB\" + + ' Used in WriteLine() to skip over startfolder in output lines. + Dim rootLength As Integer = startFolder.Length + + 'Take a snapshot of the folder contents + Dim dir As New System.IO.DirectoryInfo(startFolder) + Dim fileList = dir.GetFiles("*.*", System.IO.SearchOption.AllDirectories) + + ' Create the query. + Dim queryGroupByExt = From file In fileList _ + Group By file.Extension.ToLower() Into fileGroup = Group _ + Order By ToLower _ + Select fileGroup + + ' Execute the query. By storing the result we can + ' page the display with good performance. + Dim groupByExtList = queryGroupByExt.ToList() + ' Display one group at a time. If the number of - ' entries is greater than the number of lines - ' in the console window, then page the output. - Dim trimLength = startFolder.Length - PageOutput(groupByExtList, trimLength) - - End Sub - - ' Pages console display for large query results. No more than one group per page. - ' This sub specifically works with group queries of FileInfo objects - ' but can be modified for any type. - Sub PageOutput(ByVal groupQuery, ByVal charsToSkip) - - ' "3" = 1 line for extension key + 1 for "Press any key" + 1 for input cursor. - Dim numLines As Integer = Console.WindowHeight - 3 - ' Flag to indicate whether there are more results to display - Dim goAgain As Boolean = True - - For Each fg As IEnumerable(Of System.IO.FileInfo) In groupQuery - ' Start a new extension at the top of a page. - Dim currentLine As Integer = 0 - - Do While (currentLine < fg.Count()) - Console.Clear() - Console.WriteLine(fg(0).Extension) - - ' Get the next page of results - ' No more than one filename per page - Dim resultPage = From file In fg _ - Skip currentLine Take numLines - - ' Execute the query. Trim the display output. - For Each line In resultPage - Console.WriteLine(vbTab & line.FullName.Substring(charsToSkip)) - Next - - ' Advance the current position - currentLine = numLines + currentLine - - ' Give the user a chance to break out of the loop - Console.WriteLine("Press any key for next page or the 'End' key to exit.") - Dim key As ConsoleKey = Console.ReadKey().Key - If key = ConsoleKey.End Then - goAgain = False - Exit For - End If - Loop - Next - End Sub -End Module -``` - - The output from this program can be long, depending on the details of the local file system and what the `startFolder` is set to. To enable viewing of all results, this example shows how to page through results. The same techniques can be applied to Windows and Web applications. Notice that because the code pages the items in a group, a nested `For Each` loop is required. There is also some additional logic to compute the current position in the list, and to enable the user to stop paging and exit the program. In this particular case, the paging query is run against the cached results from the original query. In other contexts, such as LINQ to SQL, such caching is not required. - -## Compile the code + ' entries is greater than the number of lines + ' in the console window, then page the output. + Dim trimLength = startFolder.Length + PageOutput(groupByExtList, trimLength) + + End Sub + + ' Pages console display for large query results. No more than one group per page. + ' This sub specifically works with group queries of FileInfo objects + ' but can be modified for any type. + Sub PageOutput(ByVal groupQuery, ByVal charsToSkip) + + ' "3" = 1 line for extension key + 1 for "Press any key" + 1 for input cursor. + Dim numLines As Integer = Console.WindowHeight - 3 + ' Flag to indicate whether there are more results to display + Dim goAgain As Boolean = True + + For Each fg As IEnumerable(Of System.IO.FileInfo) In groupQuery + ' Start a new extension at the top of a page. + Dim currentLine As Integer = 0 + + Do While (currentLine < fg.Count()) + Console.Clear() + Console.WriteLine(fg(0).Extension) + + ' Get the next page of results + ' No more than one filename per page + Dim resultPage = From file In fg _ + Skip currentLine Take numLines + + ' Execute the query. Trim the display output. + For Each line In resultPage + Console.WriteLine(vbTab & line.FullName.Substring(charsToSkip)) + Next + + ' Advance the current position + currentLine = numLines + currentLine + + ' Give the user a chance to break out of the loop + Console.WriteLine("Press any key for next page or the 'End' key to exit.") + Dim key As ConsoleKey = Console.ReadKey().Key + If key = ConsoleKey.End Then + goAgain = False + Exit For + End If + Loop + Next + End Sub +End Module +``` + + The output from this program can be long, depending on the details of the local file system and what the `startFolder` is set to. To enable viewing of all results, this example shows how to page through results. The same techniques can be applied to Windows and Web applications. Notice that because the code pages the items in a group, a nested `For Each` loop is required. There is also some additional logic to compute the current position in the list, and to enable the user to stop paging and exit the program. In this particular case, the paging query is run against the cached results from the original query. In other contexts, such as LINQ to SQL, such caching is not required. + +## Compile the code Create a Visual Basic console application project, with an `Imports` statement for the System.Linq namespace. - + ## See also - [LINQ to Objects (Visual Basic)](linq-to-objects.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md index 5fd6a42b546f7..49021999db1f1 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md @@ -15,11 +15,11 @@ Dim query = From student As Student In arrList By specifying the type of the range variable, you are casting each item in the to a `Student`. -The use of an explicitly typed range variable in a query expression is equivalent to calling the method. throws an exception if the specified cast cannot be performed. and are the two Standard Query Operator methods that operate on non-generic types. In Visual Basic, you must explicitly call the method on the data source to ensure a specific range variable type. For more information, see [Type Relationships in Query Operations (Visual Basic)](type-relationships-in-query-operations.md). +The use of an explicitly typed range variable in a query expression is equivalent to calling the method. throws an exception if the specified cast cannot be performed. and are the two Standard Query Operator methods that operate on non-generic types. In Visual Basic, you must explicitly call the method on the data source to ensure a specific range variable type. For more information, see [Type Relationships in Query Operations (Visual Basic)](type-relationships-in-query-operations.md). ## Example -The following example shows a simple query over an . Note that this example uses object initializers when the code calls the method, but this is not a requirement. +The following example shows a simple query over an . Note that this example uses object initializers when the code calls the method, but this is not a requirement. ```vb Imports System.Collections diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-an-assembly-s-metadata-with-reflection-linq.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-an-assembly-s-metadata-with-reflection-linq.md index 94d0fe9916dc3..32129ae253ee9 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-an-assembly-s-metadata-with-reflection-linq.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-an-assembly-s-metadata-with-reflection-linq.md @@ -6,43 +6,43 @@ ms.assetid: 53caa336-ab83-4181-b0f6-5c87c5f9e4ee --- # How to: Query An Assembly's Metadata with Reflection (LINQ) (Visual Basic) -The following example shows how LINQ can be used with reflection to retrieve specific metadata about methods that match a specified search criterion. In this case, the query will find the names of all the methods in the assembly that return enumerable types such as arrays. - -## Example - +The following example shows how LINQ can be used with reflection to retrieve specific metadata about methods that match a specified search criterion. In this case, the query will find the names of all the methods in the assembly that return enumerable types such as arrays. + +## Example + ```vb Imports System.Linq -Imports System.Reflection +Imports System.Reflection -Module Module1 - Sub Main() +Module Module1 + Sub Main() Dim asmbly As Assembly = - Assembly.Load("System.Core, Version=3.5.0.0, Culture=neutral, PublicKeyToken= b77a5c561934e089") - + Assembly.Load("System.Core, Version=3.5.0.0, Culture=neutral, PublicKeyToken= b77a5c561934e089") + Dim pubTypesQuery = From type In asmbly.GetTypes() Where type.IsPublic From method In type.GetMethods() Where method.ReturnType.IsArray = True Let name = method.ToString() Let typeName = type.ToString() - Group name By typeName Into methodNames = Group - - Console.WriteLine("Getting ready to iterate") - For Each item In pubTypesQuery - Console.WriteLine(item.methodNames) - - For Each type In item.methodNames - Console.WriteLine(" " & type) - Next - Next - Console.WriteLine("Press any key to exit... ") - Console.ReadKey() - End Sub -End Module -``` - -The example uses the method to return an array of types in the specified assembly. The [Where Clause](../../../language-reference/queries/where-clause.md) filter is applied so that only public types are returned. For each public type, a subquery is generated by using the array that is returned from the call. These results are filtered to return only those methods whose return type is an array or else a type that implements . Finally, these results are grouped by using the type name as a key. - + Group name By typeName Into methodNames = Group + + Console.WriteLine("Getting ready to iterate") + For Each item In pubTypesQuery + Console.WriteLine(item.methodNames) + + For Each type In item.methodNames + Console.WriteLine(" " & type) + Next + Next + Console.WriteLine("Press any key to exit... ") + Console.ReadKey() + End Sub +End Module +``` + +The example uses the method to return an array of types in the specified assembly. The [Where Clause](../../../language-reference/queries/where-clause.md) filter is applied so that only public types are returned. For each public type, a subquery is generated by using the array that is returned from the call. These results are filtered to return only those methods whose return type is an array or else a type that implements . Finally, these results are grouped by using the type name as a key. + ## See also - [LINQ to Objects (Visual Basic)](linq-to-objects.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-characters-in-a-string-linq.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-characters-in-a-string-linq.md index c8a765976f49e..e725d8712e09f 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-characters-in-a-string-linq.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-characters-in-a-string-linq.md @@ -6,7 +6,7 @@ ms.assetid: 499ebbe0-746c-4235-9dba-ce722c12b50e --- # How to: Query for Characters in a String (LINQ) (Visual Basic) -Because the class implements the generic interface, any string can be queried as a sequence of characters. However, this is not a common use of LINQ. For complex pattern matching operations, use the class. +Because the class implements the generic interface, any string can be queried as a sequence of characters. However, this is not a common use of LINQ. For complex pattern matching operations, use the class. ## Example diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-sentences-that-contain-a-specified-set-of-words.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-sentences-that-contain-a-specified-set-of-words.md index d92acf4d9b9c7..cf8ff60381072 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-sentences-that-contain-a-specified-set-of-words.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-sentences-that-contain-a-specified-set-of-words.md @@ -54,9 +54,9 @@ End Class ' Historically, the world of data and the world of objects have not been well integrated ``` -The query works by first splitting the text into sentences, and then splitting the sentences into an array of strings that hold each word. For each of these arrays, the method removes all duplicate words, and then the query performs an operation on the word array and the `wordsToMatch` array. If the count of the intersection is the same as the count of the `wordsToMatch` array, all words were found in the words and the original sentence is returned. +The query works by first splitting the text into sentences, and then splitting the sentences into an array of strings that hold each word. For each of these arrays, the method removes all duplicate words, and then the query performs an operation on the word array and the `wordsToMatch` array. If the count of the intersection is the same as the count of the `wordsToMatch` array, all words were found in the words and the original sentence is returned. -In the call to , the punctuation marks are used as separators in order to remove them from the string. If you did not do this, for example you could have a string "Historically," that would not match "Historically" in the `wordsToMatch` array. You may have to use additional separators, depending on the types of punctuation found in the source text. +In the call to , the punctuation marks are used as separators in order to remove them from the string. If you did not do this, for example you could have a string "Historically," that would not match "Historically" in the `wordsToMatch` array. You may have to use additional separators, depending on the types of punctuation found in the source text. ## Compile the code diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-the-largest-file-or-files-in-a-directory-tree.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-the-largest-file-or-files-in-a-directory-tree.md index 0c76bb66bea3a..4a327b4cf92af 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-the-largest-file-or-files-in-a-directory-tree.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-the-largest-file-or-files-in-a-directory-tree.md @@ -6,118 +6,118 @@ ms.assetid: 8c1c9f0c-95dd-4222-9be2-9ec026a13e81 --- # How to: Query for the Largest File or Files in a Directory Tree (LINQ) (Visual Basic) -This example shows five queries related to file size in bytes: - -- How to retrieve the size in bytes of the largest file. - -- How to retrieve the size in bytes of the smallest file. - -- How to retrieve the object largest or smallest file from one or more folders under a specified root folder. - -- How to retrieve a sequence such as the 10 largest files. - -- How to order files into groups based on their file size in bytes, ignoring files that are less than a specified size. - -## Example - - The following example contains five separate queries that show how to query and group files, depending on their file size in bytes. You can easily modify these examples to base the query on some other property of the object. - -```vb -Module QueryBySize - Sub Main() - - ' Change the drive\path if necessary - Dim root As String = "C:\Program Files\Microsoft Visual Studio 9.0" - - 'Take a snapshot of the folder contents - Dim dir As New System.IO.DirectoryInfo(root) - Dim fileList = dir.GetFiles("*.*", System.IO.SearchOption.AllDirectories) - - ' Return the size of the largest file - Dim maxSize = Aggregate aFile In fileList Into Max(GetFileLength(aFile)) - - 'Dim maxSize = fileLengths.Max - Console.WriteLine("The length of the largest file under {0} is {1}", _ - root, maxSize) - - ' Return the FileInfo object of the largest file - ' by sorting and selecting from the beginning of the list - Dim filesByLengDesc = From file In fileList _ - Let filelength = GetFileLength(file) _ - Where filelength > 0 _ - Order By filelength Descending _ - Select file - - Dim longestFile = filesByLengDesc.First - - Console.WriteLine("The largest file under {0} is {1} with a length of {2} bytes", _ - root, longestFile.FullName, longestFile.Length) - - Dim smallestFile = filesByLengDesc.Last - - Console.WriteLine("The smallest file under {0} is {1} with a length of {2} bytes", _ - root, smallestFile.FullName, smallestFile.Length) - - ' Return the FileInfos for the 10 largest files - ' Based on a previous query, but nothing is executed - ' until the For Each statement below. - Dim tenLargest = From file In filesByLengDesc Take 10 - - Console.WriteLine("The 10 largest files under {0} are:", root) - - For Each fi As System.IO.FileInfo In tenLargest - Console.WriteLine("{0}: {1} bytes", fi.FullName, fi.Length) - Next - - ' Group files according to their size, - ' leaving out the ones under 200K - Dim sizeGroups = From file As System.IO.FileInfo In fileList _ - Where file.Length > 0 _ - Let groupLength = file.Length / 100000 _ - Group file By groupLength Into fileGroup = Group _ - Where groupLength >= 2 _ - Order By groupLength Descending - - For Each group In sizeGroups - Console.WriteLine(group.groupLength + "00000") - - For Each item As System.IO.FileInfo In group.fileGroup - Console.WriteLine(" {0}: {1}", item.Name, item.Length) - Next - Next - - ' Keep the console window open in debug mode - Console.WriteLine("Press any key to exit.") - Console.ReadKey() - - End Sub - - ' This method is used to catch the possible exception - ' that can be raised when accessing the FileInfo.Length property. - ' In this particular case, it is safe to ignore the exception. - Function GetFileLength(ByVal fi As System.IO.FileInfo) As Long - Dim retval As Long - Try - retval = fi.Length - Catch ex As FileNotFoundException - ' If a file is no longer present, +This example shows five queries related to file size in bytes: + +- How to retrieve the size in bytes of the largest file. + +- How to retrieve the size in bytes of the smallest file. + +- How to retrieve the object largest or smallest file from one or more folders under a specified root folder. + +- How to retrieve a sequence such as the 10 largest files. + +- How to order files into groups based on their file size in bytes, ignoring files that are less than a specified size. + +## Example + + The following example contains five separate queries that show how to query and group files, depending on their file size in bytes. You can easily modify these examples to base the query on some other property of the object. + +```vb +Module QueryBySize + Sub Main() + + ' Change the drive\path if necessary + Dim root As String = "C:\Program Files\Microsoft Visual Studio 9.0" + + 'Take a snapshot of the folder contents + Dim dir As New System.IO.DirectoryInfo(root) + Dim fileList = dir.GetFiles("*.*", System.IO.SearchOption.AllDirectories) + + ' Return the size of the largest file + Dim maxSize = Aggregate aFile In fileList Into Max(GetFileLength(aFile)) + + 'Dim maxSize = fileLengths.Max + Console.WriteLine("The length of the largest file under {0} is {1}", _ + root, maxSize) + + ' Return the FileInfo object of the largest file + ' by sorting and selecting from the beginning of the list + Dim filesByLengDesc = From file In fileList _ + Let filelength = GetFileLength(file) _ + Where filelength > 0 _ + Order By filelength Descending _ + Select file + + Dim longestFile = filesByLengDesc.First + + Console.WriteLine("The largest file under {0} is {1} with a length of {2} bytes", _ + root, longestFile.FullName, longestFile.Length) + + Dim smallestFile = filesByLengDesc.Last + + Console.WriteLine("The smallest file under {0} is {1} with a length of {2} bytes", _ + root, smallestFile.FullName, smallestFile.Length) + + ' Return the FileInfos for the 10 largest files + ' Based on a previous query, but nothing is executed + ' until the For Each statement below. + Dim tenLargest = From file In filesByLengDesc Take 10 + + Console.WriteLine("The 10 largest files under {0} are:", root) + + For Each fi As System.IO.FileInfo In tenLargest + Console.WriteLine("{0}: {1} bytes", fi.FullName, fi.Length) + Next + + ' Group files according to their size, + ' leaving out the ones under 200K + Dim sizeGroups = From file As System.IO.FileInfo In fileList _ + Where file.Length > 0 _ + Let groupLength = file.Length / 100000 _ + Group file By groupLength Into fileGroup = Group _ + Where groupLength >= 2 _ + Order By groupLength Descending + + For Each group In sizeGroups + Console.WriteLine(group.groupLength + "00000") + + For Each item As System.IO.FileInfo In group.fileGroup + Console.WriteLine(" {0}: {1}", item.Name, item.Length) + Next + Next + + ' Keep the console window open in debug mode + Console.WriteLine("Press any key to exit.") + Console.ReadKey() + + End Sub + + ' This method is used to catch the possible exception + ' that can be raised when accessing the FileInfo.Length property. + ' In this particular case, it is safe to ignore the exception. + Function GetFileLength(ByVal fi As System.IO.FileInfo) As Long + Dim retval As Long + Try + retval = fi.Length + Catch ex As FileNotFoundException + ' If a file is no longer present, ' just return zero bytes. - retval = 0 - End Try - - Return retval - End Function -End Module -``` - - To return one or more complete objects, the query first must examine each one in the data source, and then sort them by the value of their Length property. Then it can return the single one or the sequence with the greatest lengths. Use to return the first element in a list. Use to return the first n number of elements. Specify a descending sort order to put the smallest elements at the start of the list. - - The query calls out to a separate method to obtain the file size in bytes in order to consume the possible exception that will be raised in the case where a file was deleted on another thread in the time period since the object was created in the call to `GetFiles`. Even through the object has already been created, the exception can occur because a object will try to refresh its property by using the most current size in bytes the first time the property is accessed. By putting this operation in a try-catch block outside the query, we follow the rule of avoiding operations in queries that can cause side-effects. In general, great care must be taken when consuming exceptions, to make sure that an application is not left in an unknown state. - -## Compile the code + retval = 0 + End Try + + Return retval + End Function +End Module +``` + + To return one or more complete objects, the query first must examine each one in the data source, and then sort them by the value of their Length property. Then it can return the single one or the sequence with the greatest lengths. Use to return the first element in a list. Use to return the first n number of elements. Specify a descending sort order to put the smallest elements at the start of the list. + + The query calls out to a separate method to obtain the file size in bytes in order to consume the possible exception that will be raised in the case where a file was deleted on another thread in the time period since the object was created in the call to `GetFiles`. Even through the object has already been created, the exception can occur because a object will try to refresh its property by using the most current size in bytes the first time the property is accessed. By putting this operation in a try-catch block outside the query, we follow the rule of avoiding operations in queries that can cause side-effects. In general, great care must be taken when consuming exceptions, to make sure that an application is not left in an unknown state. + +## Compile the code Create a Visual Basic console application project, with an `Imports` statement for the System.Linq namespace. - + ## See also - [LINQ to Objects (Visual Basic)](linq-to-objects.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-the-total-number-of-bytes-in-a-set-of-folders.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-the-total-number-of-bytes-in-a-set-of-folders.md index ba78661fdcc93..32725ed991cf8 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-the-total-number-of-bytes-in-a-set-of-folders.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-for-the-total-number-of-bytes-in-a-set-of-folders.md @@ -6,72 +6,72 @@ ms.assetid: bfe85ed2-44dc-4ef1-aac7-241622b80a69 --- # How to: Query for the Total Number of Bytes in a Set of Folders (LINQ) (Visual Basic) -This example shows how to retrieve the total number of bytes used by all the files in a specified folder and all its subfolders. - -## Example - - The method adds the values of all the items selected in the `select` clause. You can easily modify this query to retrieve the biggest or smallest file in the specified directory tree by calling the or method instead of . - -```vb -Module QueryTotalBytes - Sub Main() - - ' Change the drive\path if necessary. - Dim root As String = "C:\Program Files\Microsoft Visual Studio 9.0\VB" - - 'Take a snapshot of the folder contents. - ' This method assumes that the application has discovery permissions - ' for all folders under the specified path. - Dim fileList = My.Computer.FileSystem.GetFiles _ - (root, FileIO.SearchOption.SearchAllSubDirectories, "*.*") - - Dim fileQuery = From file In fileList _ - Select GetFileLength(file) - - ' Force execution and cache the results to avoid multiple trips to the file system. - Dim fileLengths = fileQuery.ToArray() - - ' Find the largest file - Dim maxSize = Aggregate aFile In fileLengths Into Max() - - ' Find the total number of bytes - Dim totalBytes = Aggregate aFile In fileLengths Into Sum() - - Console.WriteLine("The largest file is " & maxSize & " bytes") - Console.WriteLine("There are " & totalBytes & " total bytes in " & _ - fileList.Count & " files under " & root) - - ' Keep the console window open in debug mode - Console.WriteLine("Press any key to exit.") - Console.ReadKey() - End Sub - - ' This method is used to catch the possible exception - ' that can be raised when accessing the FileInfo.Length property. - Function GetFileLength(ByVal filename As String) As Long - Dim retval As Long - Try - Dim fi As New System.IO.FileInfo(filename) - retval = fi.Length - Catch ex As System.IO.FileNotFoundException - ' If a file is no longer present, +This example shows how to retrieve the total number of bytes used by all the files in a specified folder and all its subfolders. + +## Example + + The method adds the values of all the items selected in the `select` clause. You can easily modify this query to retrieve the biggest or smallest file in the specified directory tree by calling the or method instead of . + +```vb +Module QueryTotalBytes + Sub Main() + + ' Change the drive\path if necessary. + Dim root As String = "C:\Program Files\Microsoft Visual Studio 9.0\VB" + + 'Take a snapshot of the folder contents. + ' This method assumes that the application has discovery permissions + ' for all folders under the specified path. + Dim fileList = My.Computer.FileSystem.GetFiles _ + (root, FileIO.SearchOption.SearchAllSubDirectories, "*.*") + + Dim fileQuery = From file In fileList _ + Select GetFileLength(file) + + ' Force execution and cache the results to avoid multiple trips to the file system. + Dim fileLengths = fileQuery.ToArray() + + ' Find the largest file + Dim maxSize = Aggregate aFile In fileLengths Into Max() + + ' Find the total number of bytes + Dim totalBytes = Aggregate aFile In fileLengths Into Sum() + + Console.WriteLine("The largest file is " & maxSize & " bytes") + Console.WriteLine("There are " & totalBytes & " total bytes in " & _ + fileList.Count & " files under " & root) + + ' Keep the console window open in debug mode + Console.WriteLine("Press any key to exit.") + Console.ReadKey() + End Sub + + ' This method is used to catch the possible exception + ' that can be raised when accessing the FileInfo.Length property. + Function GetFileLength(ByVal filename As String) As Long + Dim retval As Long + Try + Dim fi As New System.IO.FileInfo(filename) + retval = fi.Length + Catch ex As System.IO.FileNotFoundException + ' If a file is no longer present, ' just return zero bytes. - retval = 0 - End Try - - Return retval - End Function -End Module -``` - - If you only have to count the number of bytes in a specified directory tree, you can do this more efficiently without creating a LINQ query, which incurs the overhead of creating the list collection as a data source. The usefulness of the LINQ approach increases as the query becomes more complex, or when you have to run multiple queries against the same data source. - - The query calls out to a separate method to obtain the file length. It does this in order to consume the possible exception that will be raised if the file was deleted on another thread after the object was created in the call to `GetFiles`. Even though the object has already been created, the exception can occur because a object will try to refresh its property with the most current length the first time the property is accessed. By putting this operation in a try-catch block outside the query, the code follows the rule of avoiding operations in queries that can cause side-effects. In general, great care must be taken when you consume exceptions to make sure that an application is not left in an unknown state. - -## Compile the code + retval = 0 + End Try + + Return retval + End Function +End Module +``` + + If you only have to count the number of bytes in a specified directory tree, you can do this more efficiently without creating a LINQ query, which incurs the overhead of creating the list collection as a data source. The usefulness of the LINQ approach increases as the query becomes more complex, or when you have to run multiple queries against the same data source. + + The query calls out to a separate method to obtain the file length. It does this in order to consume the possible exception that will be raised if the file was deleted on another thread after the object was created in the call to `GetFiles`. Even though the object has already been created, the exception can occur because a object will try to refresh its property with the most current length the first time the property is accessed. By putting this operation in a try-catch block outside the query, the code follows the rule of avoiding operations in queries that can cause side-effects. In general, great care must be taken when you consume exceptions to make sure that an application is not left in an unknown state. + +## Compile the code Create a Visual Basic console application project, with an `Imports` statement for the System.Linq namespace. - + ## See also - [LINQ to Objects (Visual Basic)](linq-to-objects.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-reorder-the-fields-of-a-delimited-file.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-reorder-the-fields-of-a-delimited-file.md index 37dcc5fcc2cd6..a9546f11d5b47 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-reorder-the-fields-of-a-delimited-file.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-reorder-the-fields-of-a-delimited-file.md @@ -6,7 +6,7 @@ ms.assetid: c451c7db-663b-4daf-b8ba-a2093095d672 --- # How to: Reorder the Fields of a Delimited File (LINQ) (Visual Basic) -A comma-separated value (CSV) file is a text file that is often used to store spreadsheet data or other tabular data that is represented by rows and columns. By using the method to separate the fields, it is very easy to query and manipulate CSV files by using LINQ. In fact, the same technique can be used to reorder the parts of any structured line of text; it is not limited to CSV files. +A comma-separated value (CSV) file is a text file that is often used to store spreadsheet data or other tabular data that is represented by rows and columns. By using the method to separate the fields, it is very easy to query and manipulate CSV files by using LINQ. In fact, the same technique can be used to reorder the parts of any structured line of text; it is not limited to CSV files. In the following example, assume that the three columns represent students' "last name," "first name", and "ID." The fields are in alphabetical order based on the students' last names. The query produces a new sequence in which the ID column appears first, followed by a second column that combines the student's first name and last name. The lines are reordered according to the ID field. The results are saved into a new file and the original data is not modified. diff --git a/docs/visual-basic/programming-guide/concepts/linq/introduction-to-linq.md b/docs/visual-basic/programming-guide/concepts/linq/introduction-to-linq.md index 744d71b2a5abf..387ae48ccefd8 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/introduction-to-linq.md +++ b/docs/visual-basic/programming-guide/concepts/linq/introduction-to-linq.md @@ -7,30 +7,30 @@ ms.assetid: c6339c12-9b2d-433e-961c-0d2b7f0091c2 --- # Introduction to LINQ (Visual Basic) -Language-Integrated Query (LINQ) is an innovation introduced in the .NET Framework version 3.5 that bridges the gap between the world of objects and the world of data. - - Traditionally, queries against data are expressed as simple strings without type checking at compile time or IntelliSense support. Furthermore, you have to learn a different query language for each type of data source: SQL databases, XML documents, various Web services, and so on. LINQ makes a *query* a first-class language construct in Visual Basic. You write queries against strongly typed collections of objects by using language keywords and familiar operators. - - You can write LINQ queries in Visual Basic for SQL Server databases, XML documents, ADO.NET Datasets, and any collection of objects that supports or the generic interface. LINQ support is also provided by third parties for many Web services and other database implementations. - - You can use LINQ queries in new projects, or alongside non-LINQ queries in existing projects. The only requirement is that the project target .NET Framework 3.5 or later. - - The following illustration from Visual Studio shows a partially-completed LINQ query against a SQL Server database in both C# and Visual Basic with full type checking and IntelliSense support. - - ![Diagram that shows a LINQ query with Intellisense.](./media/introduction-to-linq/linq-query-intellisense.png) - -## Next Steps - - To learn more details about LINQ, start by becoming familiar with some basic concepts in the Getting Started section [Getting Started with LINQ in Visual Basic](getting-started-with-linq.md), and then read the documentation for the LINQ technology in which you are interested: - -- SQL Server databases: [LINQ to SQL](../../../../framework/data/adonet/sql/linq/index.md) - -- XML documents: [LINQ to XML (Visual Basic)](../../../../standard/linq/linq-xml-overview.md) - -- ADO.NET Datasets: [LINQ to DataSet](../../../../framework/data/adonet/linq-to-dataset.md) - -- .NET collections, files, strings and so on: [LINQ to Objects (Visual Basic)](linq-to-objects.md) - +Language-Integrated Query (LINQ) is an innovation introduced in the .NET Framework version 3.5 that bridges the gap between the world of objects and the world of data. + + Traditionally, queries against data are expressed as simple strings without type checking at compile time or IntelliSense support. Furthermore, you have to learn a different query language for each type of data source: SQL databases, XML documents, various Web services, and so on. LINQ makes a *query* a first-class language construct in Visual Basic. You write queries against strongly typed collections of objects by using language keywords and familiar operators. + + You can write LINQ queries in Visual Basic for SQL Server databases, XML documents, ADO.NET Datasets, and any collection of objects that supports or the generic interface. LINQ support is also provided by third parties for many Web services and other database implementations. + + You can use LINQ queries in new projects, or alongside non-LINQ queries in existing projects. The only requirement is that the project target .NET Framework 3.5 or later. + + The following illustration from Visual Studio shows a partially-completed LINQ query against a SQL Server database in both C# and Visual Basic with full type checking and IntelliSense support. + + ![Diagram that shows a LINQ query with Intellisense.](./media/introduction-to-linq/linq-query-intellisense.png) + +## Next Steps + + To learn more details about LINQ, start by becoming familiar with some basic concepts in the Getting Started section [Getting Started with LINQ in Visual Basic](getting-started-with-linq.md), and then read the documentation for the LINQ technology in which you are interested: + +- SQL Server databases: [LINQ to SQL](../../../../framework/data/adonet/sql/linq/index.md) + +- XML documents: [LINQ to XML (Visual Basic)](../../../../standard/linq/linq-xml-overview.md) + +- ADO.NET Datasets: [LINQ to DataSet](../../../../framework/data/adonet/linq-to-dataset.md) + +- .NET collections, files, strings and so on: [LINQ to Objects (Visual Basic)](linq-to-objects.md) + ## See also - [Language-Integrated Query (LINQ) (Visual Basic)](index.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/join-operations.md b/docs/visual-basic/programming-guide/concepts/linq/join-operations.md index 2355e3ffcb534..ce7c423f558f3 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/join-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/join-operations.md @@ -6,23 +6,23 @@ ms.assetid: 39ab4854-ac84-4738-9d0b-3cb79be84db4 --- # Join Operations (Visual Basic) -A *join* of two data sources is the association of objects in one data source with objects that share a common attribute in another data source. - - Joining is an important operation in queries that target data sources whose relationships to each other cannot be followed directly. In object-oriented programming, this could mean a correlation between objects that is not modeled, such as the backwards direction of a one-way relationship. An example of a one-way relationship is a Customer class that has a property of type City, but the City class does not have a property that is a collection of Customer objects. If you have a list of City objects and you want to find all the customers in each city, you could use a join operation to find them. - - The join methods provided in the LINQ framework are and . These methods perform equijoins, or joins that match two data sources based on equality of their keys. (For comparison, Transact-SQL supports join operators other than 'equals', for example the 'less than' operator.) In relational database terms, implements an inner join, a type of join in which only those objects that have a match in the other data set are returned. The method has no direct equivalent in relational database terms, but it implements a superset of inner joins and left outer joins. A left outer join is a join that returns each element of the first (left) data source, even if it has no correlated elements in the other data source. - - The following illustration shows a conceptual view of two sets and the elements within those sets that are included in either an inner join or a left outer join. - - ![Two overlapping circles showing inner/outer.](./media/join-operations/join-method-overlapping-circles.png) - -## Methods - -|Method Name|Description|Visual Basic Query Expression Syntax|More Information| -|-----------------|-----------------|------------------------------------------|----------------------| -|Join|Joins two sequences based on key selector functions and extracts pairs of values.|`From x In …, y In … Where x.a = y.a`

-or-

`Join … [As …]In … On …`|

| -|GroupJoin|Joins two sequences based on key selector functions and groups the resulting matches for each element.|`Group Join … In … On …`|

| - +A *join* of two data sources is the association of objects in one data source with objects that share a common attribute in another data source. + + Joining is an important operation in queries that target data sources whose relationships to each other cannot be followed directly. In object-oriented programming, this could mean a correlation between objects that is not modeled, such as the backwards direction of a one-way relationship. An example of a one-way relationship is a Customer class that has a property of type City, but the City class does not have a property that is a collection of Customer objects. If you have a list of City objects and you want to find all the customers in each city, you could use a join operation to find them. + + The join methods provided in the LINQ framework are and . These methods perform equijoins, or joins that match two data sources based on equality of their keys. (For comparison, Transact-SQL supports join operators other than 'equals', for example the 'less than' operator.) In relational database terms, implements an inner join, a type of join in which only those objects that have a match in the other data set are returned. The method has no direct equivalent in relational database terms, but it implements a superset of inner joins and left outer joins. A left outer join is a join that returns each element of the first (left) data source, even if it has no correlated elements in the other data source. + + The following illustration shows a conceptual view of two sets and the elements within those sets that are included in either an inner join or a left outer join. + + ![Two overlapping circles showing inner/outer.](./media/join-operations/join-method-overlapping-circles.png) + +## Methods + +|Method Name|Description|Visual Basic Query Expression Syntax|More Information| +|-----------------|-----------------|------------------------------------------|----------------------| +|Join|Joins two sequences based on key selector functions and extracts pairs of values.|`From x In …, y In … Where x.a = y.a`

-or-

`Join … [As …]In … On …`|

| +|GroupJoin|Joins two sequences based on key selector functions and groups the resulting matches for each element.|`Group Join … In … On …`|

| + ## See also - diff --git a/docs/visual-basic/programming-guide/concepts/linq/linq-and-strings.md b/docs/visual-basic/programming-guide/concepts/linq/linq-and-strings.md index b5b531039a3dd..d908aa1676fab 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/linq-and-strings.md +++ b/docs/visual-basic/programming-guide/concepts/linq/linq-and-strings.md @@ -6,57 +6,57 @@ ms.assetid: 75ddb201-d97a-4f98-8cdf-4ad51714529a --- # LINQ and Strings (Visual Basic) -LINQ can be used to query and transform strings and collections of strings. It can be especially useful with semi-structured data in text files. LINQ queries can be combined with traditional string functions and regular expressions. For example, you can use the or method to create an array of strings that you can then query or modify by using LINQ. You can use the method in the `where` clause of a LINQ query. And you can use LINQ to query or modify the results returned by a regular expression. - - You can also use the techniques described in this section to transform semi-structured text data to XML. For more information, see [How to: Generate XML from CSV Files](../../../../standard/linq/generate-xml-csv-files.md). - - The examples in this section fall into two categories: - -## Querying a Block of Text - - You can query, analyze, and modify text blocks by splitting them into a queryable array of smaller strings by using the method or the method. You can split the source text into words, sentences, paragraphs, pages, or any other criteria, and then perform additional splits if they are required in your query. - - [How to: Count Occurrences of a Word in a String (LINQ) (Visual Basic)](how-to-count-occurrences-of-a-word-in-a-string-linq.md) - Shows how to use LINQ for simple querying over text. - +LINQ can be used to query and transform strings and collections of strings. It can be especially useful with semi-structured data in text files. LINQ queries can be combined with traditional string functions and regular expressions. For example, you can use the or method to create an array of strings that you can then query or modify by using LINQ. You can use the method in the `where` clause of a LINQ query. And you can use LINQ to query or modify the results returned by a regular expression. + + You can also use the techniques described in this section to transform semi-structured text data to XML. For more information, see [How to: Generate XML from CSV Files](../../../../standard/linq/generate-xml-csv-files.md). + + The examples in this section fall into two categories: + +## Querying a Block of Text + + You can query, analyze, and modify text blocks by splitting them into a queryable array of smaller strings by using the method or the method. You can split the source text into words, sentences, paragraphs, pages, or any other criteria, and then perform additional splits if they are required in your query. + + [How to: Count Occurrences of a Word in a String (LINQ) (Visual Basic)](how-to-count-occurrences-of-a-word-in-a-string-linq.md) + Shows how to use LINQ for simple querying over text. + [How to: Query for Sentences that Contain a Specified Set of Words (LINQ) (Visual Basic)](how-to-query-for-sentences-that-contain-a-specified-set-of-words.md) - Shows how to split text files on arbitrary boundaries and how to perform queries against each part. - - [How to: Query for Characters in a String (LINQ) (Visual Basic)](how-to-query-for-characters-in-a-string-linq.md) - Demonstrates that a string is a queryable type. - - [How to combine LINQ queries with regular expressions (Visual Basic)](how-to-combine-linq-queries-with-regular-expressions.md) - Shows how to use regular expressions in LINQ queries for complex pattern matching on filtered query results. - -## Querying Semi-Structured Data in Text Format - - Many different types of text files consist of a series of lines, often with similar formatting, such as tab- or comma-delimited files or fixed-length lines. After you read such a text file into memory, you can use LINQ to query and/or modify the lines. LINQ queries also simplify the task of combining data from multiple sources. - - [How to: Find the Set Difference Between Two Lists (LINQ) (Visual Basic)](how-to-find-the-set-difference-between-two-lists-linq.md) - Shows how to find all the strings that are present in one list but not the other. - - [How to: Sort or Filter Text Data by Any Word or Field (LINQ) (Visual Basic)](how-to-sort-or-filter-text-data-by-any-word-or-field-linq.md) - Shows how to sort text lines based on any word or field. - - [How to: Reorder the Fields of a Delimited File (LINQ) (Visual Basic)](how-to-reorder-the-fields-of-a-delimited-file.md) - Shows how to reorder fields in a line in a .csv file. - - [How to: Combine and Compare String Collections (LINQ) (Visual Basic)](how-to-combine-and-compare-string-collections-linq.md) - Shows how to combine string lists in various ways. - - [How to: Populate Object Collections from Multiple Sources (LINQ) (Visual Basic)](how-to-populate-object-collections-from-multiple-sources-linq.md) - Shows how to create object collections by using multiple text files as data sources. - - [How to: Join Content from Dissimilar Files (LINQ) (Visual Basic)](how-to-join-content-from-dissimilar-files-linq.md) - Shows how to combine strings in two lists into a single string by using a matching key. - - [How to: Split a File Into Many Files by Using Groups (LINQ) (Visual Basic)](how-to-split-a-file-into-many-files-by-using-groups-linq.md) - Shows how to create new files by using a single file as a data source. - - [How to: Compute Column Values in a CSV Text File (LINQ) (Visual Basic)](how-to-compute-column-values-in-a-csv-text-file-linq.md) - Shows how to perform mathematical computations on text data in .csv files. - + Shows how to split text files on arbitrary boundaries and how to perform queries against each part. + + [How to: Query for Characters in a String (LINQ) (Visual Basic)](how-to-query-for-characters-in-a-string-linq.md) + Demonstrates that a string is a queryable type. + + [How to combine LINQ queries with regular expressions (Visual Basic)](how-to-combine-linq-queries-with-regular-expressions.md) + Shows how to use regular expressions in LINQ queries for complex pattern matching on filtered query results. + +## Querying Semi-Structured Data in Text Format + + Many different types of text files consist of a series of lines, often with similar formatting, such as tab- or comma-delimited files or fixed-length lines. After you read such a text file into memory, you can use LINQ to query and/or modify the lines. LINQ queries also simplify the task of combining data from multiple sources. + + [How to: Find the Set Difference Between Two Lists (LINQ) (Visual Basic)](how-to-find-the-set-difference-between-two-lists-linq.md) + Shows how to find all the strings that are present in one list but not the other. + + [How to: Sort or Filter Text Data by Any Word or Field (LINQ) (Visual Basic)](how-to-sort-or-filter-text-data-by-any-word-or-field-linq.md) + Shows how to sort text lines based on any word or field. + + [How to: Reorder the Fields of a Delimited File (LINQ) (Visual Basic)](how-to-reorder-the-fields-of-a-delimited-file.md) + Shows how to reorder fields in a line in a .csv file. + + [How to: Combine and Compare String Collections (LINQ) (Visual Basic)](how-to-combine-and-compare-string-collections-linq.md) + Shows how to combine string lists in various ways. + + [How to: Populate Object Collections from Multiple Sources (LINQ) (Visual Basic)](how-to-populate-object-collections-from-multiple-sources-linq.md) + Shows how to create object collections by using multiple text files as data sources. + + [How to: Join Content from Dissimilar Files (LINQ) (Visual Basic)](how-to-join-content-from-dissimilar-files-linq.md) + Shows how to combine strings in two lists into a single string by using a matching key. + + [How to: Split a File Into Many Files by Using Groups (LINQ) (Visual Basic)](how-to-split-a-file-into-many-files-by-using-groups-linq.md) + Shows how to create new files by using a single file as a data source. + + [How to: Compute Column Values in a CSV Text File (LINQ) (Visual Basic)](how-to-compute-column-values-in-a-csv-text-file-linq.md) + Shows how to perform mathematical computations on text data in .csv files. + ## See also - [Language-Integrated Query (LINQ) (Visual Basic)](index.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/linq-to-objects.md b/docs/visual-basic/programming-guide/concepts/linq/linq-to-objects.md index 1b52427085203..4f62a48131fe4 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/linq-to-objects.md +++ b/docs/visual-basic/programming-guide/concepts/linq/linq-to-objects.md @@ -6,38 +6,38 @@ ms.assetid: dd4c30bc-1c9b-4781-a482-b5eada38deb2 --- # LINQ to Objects (Visual Basic) -The term "LINQ to Objects" refers to the use of LINQ queries with any or collection directly, without the use of an intermediate LINQ provider or API such as [LINQ to SQL](../../../../framework/data/adonet/sql/linq/index.md) or [LINQ to XML](../../../../standard/linq/linq-xml-overview.md). You can use LINQ to query any enumerable collections such as , , or . The collection may be user-defined or may be returned by a .NET Framework API. - - In a basic sense, LINQ to Objects represents a new approach to collections. In the old way, you had to write complex `For Each` loops that specified how to retrieve data from a collection. In the LINQ approach, you write declarative code that describes what you want to retrieve. - - In addition, LINQ queries offer three main advantages over traditional `For Each` loops: - -1. They are more concise and readable, especially when filtering multiple conditions. - -2. They provide powerful filtering, ordering, and grouping capabilities with a minimum of application code. - -3. They can be ported to other data sources with little or no modification. - - In general, the more complex the operation you want to perform on the data, the more benefit you will realize by using LINQ instead of traditional iteration techniques. - - The purpose of this section is to demonstrate the LINQ approach with some select examples. It is not intended to be exhaustive. - -## In This Section - - [LINQ and Strings (Visual Basic)](linq-and-strings.md) - Explains how LINQ can be used to query and transform strings and collections of strings. Also includes links to topics that demonstrate these principles. - - [LINQ and Reflection (Visual Basic)](linq-and-reflection.md) - Links to a sample that demonstrates how LINQ uses reflection. - - [LINQ and File Directories (Visual Basic)](linq-and-file-directories.md) - Explains how LINQ can be used to interact with file systems. Also includes links to topics that demonstrate these concepts. - - [How to: Query an ArrayList with LINQ (Visual Basic)](how-to-query-an-arraylist-with-linq.md) - Demonstrates how to query an ArrayList in C#. - - [How to: Add Custom Methods for LINQ Queries (Visual Basic)](how-to-add-custom-methods-for-linq-queries.md) - Explains how to extend the set of methods that you can use for LINQ queries by adding extension methods to the interface. - - [Language-Integrated Query (LINQ) (Visual Basic)](index.md) +The term "LINQ to Objects" refers to the use of LINQ queries with any or collection directly, without the use of an intermediate LINQ provider or API such as [LINQ to SQL](../../../../framework/data/adonet/sql/linq/index.md) or [LINQ to XML](../../../../standard/linq/linq-xml-overview.md). You can use LINQ to query any enumerable collections such as , , or . The collection may be user-defined or may be returned by a .NET Framework API. + + In a basic sense, LINQ to Objects represents a new approach to collections. In the old way, you had to write complex `For Each` loops that specified how to retrieve data from a collection. In the LINQ approach, you write declarative code that describes what you want to retrieve. + + In addition, LINQ queries offer three main advantages over traditional `For Each` loops: + +1. They are more concise and readable, especially when filtering multiple conditions. + +2. They provide powerful filtering, ordering, and grouping capabilities with a minimum of application code. + +3. They can be ported to other data sources with little or no modification. + + In general, the more complex the operation you want to perform on the data, the more benefit you will realize by using LINQ instead of traditional iteration techniques. + + The purpose of this section is to demonstrate the LINQ approach with some select examples. It is not intended to be exhaustive. + +## In This Section + + [LINQ and Strings (Visual Basic)](linq-and-strings.md) + Explains how LINQ can be used to query and transform strings and collections of strings. Also includes links to topics that demonstrate these principles. + + [LINQ and Reflection (Visual Basic)](linq-and-reflection.md) + Links to a sample that demonstrates how LINQ uses reflection. + + [LINQ and File Directories (Visual Basic)](linq-and-file-directories.md) + Explains how LINQ can be used to interact with file systems. Also includes links to topics that demonstrate these concepts. + + [How to: Query an ArrayList with LINQ (Visual Basic)](how-to-query-an-arraylist-with-linq.md) + Demonstrates how to query an ArrayList in C#. + + [How to: Add Custom Methods for LINQ Queries (Visual Basic)](how-to-add-custom-methods-for-linq-queries.md) + Explains how to extend the set of methods that you can use for LINQ queries by adding extension methods to the interface. + + [Language-Integrated Query (LINQ) (Visual Basic)](index.md) Provides links to topics that explain LINQ and provide examples of code that perform queries. diff --git a/docs/visual-basic/programming-guide/concepts/linq/partitioning-data.md b/docs/visual-basic/programming-guide/concepts/linq/partitioning-data.md index 15eb6b097d1f2..b2359a79ac178 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/partitioning-data.md +++ b/docs/visual-basic/programming-guide/concepts/linq/partitioning-data.md @@ -6,50 +6,50 @@ ms.assetid: 69c59379-b66e-422c-b324-5b5c07760ef7 --- # Partitioning Data (Visual Basic) -Partitioning in LINQ refers to the operation of dividing an input sequence into two sections, without rearranging the elements, and then returning one of the sections. - - The following illustration shows the results of three different partitioning operations on a sequence of characters. The first operation returns the first three elements in the sequence. The second operation skips the first three elements and returns the remaining elements. The third operation skips the first two elements in the sequence and returns the next three elements. - - ![Illustration that shows three LINQ partitioning operations.](./media/partitioning-data/linq-partitioning-operations.png) - - The standard query operator methods that partition sequences are listed in the following section. - -## Operators - -|Operator Name|Description|Visual Basic Query Expression Syntax|More Information| -|-------------------|-----------------|------------------------------------------|----------------------| -|Skip|Skips elements up to a specified position in a sequence.|`Skip`|

| -|SkipWhile|Skips elements based on a predicate function until an element does not satisfy the condition.|`Skip While`|

| -|Take|Takes elements up to a specified position in a sequence.|`Take`|

| -|TakeWhile|Takes elements based on a predicate function until an element does not satisfy the condition.|`Take While`|

| -| Chunk | Splits the elements of a sequence into chunks of a specified maximum size. | |
| - -## Query Expression Syntax Examples - -### Skip - - The following code example uses the `Skip` clause in Visual Basic to skip over the first four strings in an array of strings before returning the remaining strings in the array. - - [!code-vb[CsLINQPartitioning#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQPartitioning/VB/Partitioning.vb#1)] - -### SkipWhile - - The following code example uses the `Skip While` clause in Visual Basic to skip over the strings in an array while the first letter of the string is "a". The remaining strings in the array are returned. - - [!code-vb[CsLINQPartitioning#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQPartitioning/VB/Partitioning.vb#2)] - -### Take - - The following code example uses the `Take` clause in Visual Basic to return the first two strings in an array of strings. - - [!code-vb[CsLINQPartitioning#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQPartitioning/VB/Partitioning.vb#3)] - -### TakeWhile - - The following code example uses the `Take While` clause in Visual Basic to return strings from an array while the length of the string is five or less. - - [!code-vb[CsLINQPartitioning#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQPartitioning/VB/Partitioning.vb#4)] - +Partitioning in LINQ refers to the operation of dividing an input sequence into two sections, without rearranging the elements, and then returning one of the sections. + + The following illustration shows the results of three different partitioning operations on a sequence of characters. The first operation returns the first three elements in the sequence. The second operation skips the first three elements and returns the remaining elements. The third operation skips the first two elements in the sequence and returns the next three elements. + + ![Illustration that shows three LINQ partitioning operations.](./media/partitioning-data/linq-partitioning-operations.png) + + The standard query operator methods that partition sequences are listed in the following section. + +## Operators + +|Operator Name|Description|Visual Basic Query Expression Syntax|More Information| +|-------------------|-----------------|------------------------------------------|----------------------| +|Skip|Skips elements up to a specified position in a sequence.|`Skip`|

| +|SkipWhile|Skips elements based on a predicate function until an element does not satisfy the condition.|`Skip While`|

| +|Take|Takes elements up to a specified position in a sequence.|`Take`|

| +|TakeWhile|Takes elements based on a predicate function until an element does not satisfy the condition.|`Take While`|

| +| Chunk | Splits the elements of a sequence into chunks of a specified maximum size. | |
| + +## Query Expression Syntax Examples + +### Skip + + The following code example uses the `Skip` clause in Visual Basic to skip over the first four strings in an array of strings before returning the remaining strings in the array. + + [!code-vb[CsLINQPartitioning#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQPartitioning/VB/Partitioning.vb#1)] + +### SkipWhile + + The following code example uses the `Skip While` clause in Visual Basic to skip over the strings in an array while the first letter of the string is "a". The remaining strings in the array are returned. + + [!code-vb[CsLINQPartitioning#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQPartitioning/VB/Partitioning.vb#2)] + +### Take + + The following code example uses the `Take` clause in Visual Basic to return the first two strings in an array of strings. + + [!code-vb[CsLINQPartitioning#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQPartitioning/VB/Partitioning.vb#3)] + +### TakeWhile + + The following code example uses the `Take While` clause in Visual Basic to return strings from an array while the length of the string is five or less. + + [!code-vb[CsLINQPartitioning#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQPartitioning/VB/Partitioning.vb#4)] + ## See also - diff --git a/docs/visual-basic/programming-guide/concepts/linq/projection-operations.md b/docs/visual-basic/programming-guide/concepts/linq/projection-operations.md index 66dfdc88e21e9..12da277651679 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/projection-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/projection-operations.md @@ -14,9 +14,9 @@ The standard query operator methods that perform projection are listed in the fo |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|Select|Projects values that are based on a transform function.|`Select`|

| -|SelectMany|Projects sequences of values that are based on a transform function and then flattens them into one sequence.|Use multiple `From` clauses|

| -| Zip | Produces a sequence of tuples with elements from 2-3 specified sequences. | Not applicable. |
| +|Select|Projects values that are based on a transform function.|`Select`|

| +|SelectMany|Projects sequences of values that are based on a transform function and then flattens them into one sequence.|Use multiple `From` clauses|

| +| Zip | Produces a sequence of tuples with elements from 2-3 specified sequences. | Not applicable. |
| ## Query Expression Syntax Examples @@ -93,7 +93,7 @@ This illustration depicts how `SelectMany()` concatenates the intermediate seque ### Code Example -The following example compares the behavior of `Select()` and `SelectMany()`. The code creates a "bouquet" of flowers by taking the items from each list of flower names in the source collection. In this example, the "single value" that the transform function uses is itself a collection of values. This requires the extra `For Each` loop in order to enumerate each string in each sub-sequence. +The following example compares the behavior of `Select()` and `SelectMany()`. The code creates a "bouquet" of flowers by taking the items from each list of flower names in the source collection. In this example, the "single value" that the transform function uses is itself a collection of values. This requires the extra `For Each` loop in order to enumerate each string in each sub-sequence. ```vb Class Bouquet diff --git a/docs/visual-basic/programming-guide/concepts/linq/quantifier-operations.md b/docs/visual-basic/programming-guide/concepts/linq/quantifier-operations.md index 5bb8a4f813b55..7e9fba8b939a3 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/quantifier-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/quantifier-operations.md @@ -6,34 +6,34 @@ ms.assetid: ae1a2b73-503c-4f4b-a3fd-31b5adbee67c --- # Quantifier Operations (Visual Basic) -Quantifier operations return a value that indicates whether some or all of the elements in a sequence satisfy a condition. - +Quantifier operations return a value that indicates whether some or all of the elements in a sequence satisfy a condition. + The following illustration depicts two different quantifier operations on two different source sequences. The first operation asks if any of the elements are the character 'A'. The second operation asks if all the elements are the character 'A'. Both methods return `true` in this example. - - ![LINQ Quantifier Operations](./media/quantifier-operations/linq-quantifier-operations.png) - - The standard query operator methods that perform quantifier operations are listed in the following section. - -## Methods - -|Method Name|Description|Visual Basic Query Expression Syntax|More Information| -|-----------------|-----------------|------------------------------------------|----------------------| -|All|Determines whether all the elements in a sequence satisfy a condition.|`Aggregate … In … Into All(…)`|

| -|Any|Determines whether any elements in a sequence satisfy a condition.|`Aggregate … In … Into Any()`|

| -|Contains|Determines whether a sequence contains a specified element.|Not applicable.|

| - -## Query Expression Syntax Examples - - These examples use the `Aggregate` clause in Visual Basic as part of the filtering condition in a LINQ query. - - The following example uses the `Aggregate` clause and the extension method to return from a collection those people whose pets are all older than a specified age. - - [!code-vb[CsLINQAnyAll#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAnyAll/VB/AnyAll.vb#1)] - - The next example uses the `Aggregate` clause and the extension method to return from a collection those people who have at least one pet that is older than a specified age. - - [!code-vb[CsLINQAnyAll#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAnyAll/VB/AnyAll.vb#2)] - + + ![LINQ Quantifier Operations](./media/quantifier-operations/linq-quantifier-operations.png) + + The standard query operator methods that perform quantifier operations are listed in the following section. + +## Methods + +|Method Name|Description|Visual Basic Query Expression Syntax|More Information| +|-----------------|-----------------|------------------------------------------|----------------------| +|All|Determines whether all the elements in a sequence satisfy a condition.|`Aggregate … In … Into All(…)`|

| +|Any|Determines whether any elements in a sequence satisfy a condition.|`Aggregate … In … Into Any()`|

| +|Contains|Determines whether a sequence contains a specified element.|Not applicable.|

| + +## Query Expression Syntax Examples + + These examples use the `Aggregate` clause in Visual Basic as part of the filtering condition in a LINQ query. + + The following example uses the `Aggregate` clause and the extension method to return from a collection those people whose pets are all older than a specified age. + + [!code-vb[CsLINQAnyAll#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAnyAll/VB/AnyAll.vb#1)] + + The next example uses the `Aggregate` clause and the extension method to return from a collection those people who have at least one pet that is older than a specified age. + + [!code-vb[CsLINQAnyAll#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/CsLINQAnyAll/VB/AnyAll.vb#2)] + ## See also - diff --git a/docs/visual-basic/programming-guide/concepts/linq/query-expression-syntax-for-standard-query-operators.md b/docs/visual-basic/programming-guide/concepts/linq/query-expression-syntax-for-standard-query-operators.md index b0ef6d4c216f1..757f3da33eb67 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/query-expression-syntax-for-standard-query-operators.md +++ b/docs/visual-basic/programming-guide/concepts/linq/query-expression-syntax-for-standard-query-operators.md @@ -6,39 +6,39 @@ ms.assetid: eb978d86-d3b5-497b-95ce-a054bea8f510 --- # Query Expression Syntax for Standard Query Operators (Visual Basic) -Some of the more frequently used standard query operators have dedicated Visual Basic language keyword syntax that enables them to be called as part of a *query expression*. A query expression is a different, more readable form of expressing a query than its *method-based* equivalent. Query expression clauses are translated into calls to the query methods at compile time. - -## Query Expression Syntax Table +Some of the more frequently used standard query operators have dedicated Visual Basic language keyword syntax that enables them to be called as part of a *query expression*. A query expression is a different, more readable form of expressing a query than its *method-based* equivalent. Query expression clauses are translated into calls to the query methods at compile time. + +## Query Expression Syntax Table + + The following table lists the standard query operators that have equivalent query expression clauses. + +|Method|Visual Basic Query Expression Syntax| +|------------|------------------------------------------| +||`Aggregate … In … Into All(…)`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| +||`Aggregate … In … Into Any()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| +||`Aggregate … In … Into Average()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| +||`From … As …`

(For more information, see [From Clause](../../../language-reference/queries/from-clause.md).)| +||`Aggregate … In … Into Count()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| +||`Distinct`

(For more information, see [Distinct Clause](../../../language-reference/queries/distinct-clause.md).)| +||`Group … By … Into …`

(For more information, see [Group By Clause](../../../language-reference/queries/group-by-clause.md).)| +||`Group Join … In … On …`

(For more information, see [Group Join Clause](../../../language-reference/queries/group-join-clause.md).)| +||`From x In …, y In … Where x.a = b.a`

-or-

`Join … [As …]In … On …`

(For more information, see [Join Clause](../../../language-reference/queries/join-clause.md).)| +||`Aggregate … In … Into LongCount()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| +||`Aggregate … In … Into Max()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| +||`Aggregate … In … Into Min()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| +||`Order By`

(For more information, see [Order By Clause](../../../language-reference/queries/order-by-clause.md).)| +||`Order By … Descending`

(For more information, see [Order By Clause](../../../language-reference/queries/order-by-clause.md).)| +||`Select`

(For more information, see [Select Clause](../../../language-reference/queries/select-clause.md).)| +||Multiple `From` clauses

(For more information, see [From Clause](../../../language-reference/queries/from-clause.md).)| +||`Skip`

(For more information, see [Skip Clause](../../../language-reference/queries/skip-clause.md).)| +||`Skip While`

(For more information, see [Skip While Clause](../../../language-reference/queries/skip-while-clause.md).)| +||`Aggregate … In … Into Sum()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| +||`Take`

(For more information, see [Take Clause](../../../language-reference/queries/take-clause.md).)| +||`Take While`

(For more information, see [Take While Clause](../../../language-reference/queries/take-while-clause.md).)| +||`Order By …, …`

(For more information, see [Order By Clause](../../../language-reference/queries/order-by-clause.md).)| +||`Order By …, … Descending`

(For more information, see [Order By Clause](../../../language-reference/queries/order-by-clause.md).)| +||`Where`

(For more information, see [Where Clause](../../../language-reference/queries/where-clause.md).)| - The following table lists the standard query operators that have equivalent query expression clauses. - -|Method|Visual Basic Query Expression Syntax| -|------------|------------------------------------------| -||`Aggregate … In … Into All(…)`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| -||`Aggregate … In … Into Any()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| -||`Aggregate … In … Into Average()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| -||`From … As …`

(For more information, see [From Clause](../../../language-reference/queries/from-clause.md).)| -||`Aggregate … In … Into Count()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| -||`Distinct`

(For more information, see [Distinct Clause](../../../language-reference/queries/distinct-clause.md).)| -||`Group … By … Into …`

(For more information, see [Group By Clause](../../../language-reference/queries/group-by-clause.md).)| -||`Group Join … In … On …`

(For more information, see [Group Join Clause](../../../language-reference/queries/group-join-clause.md).)| -||`From x In …, y In … Where x.a = b.a`

-or-

`Join … [As …]In … On …`

(For more information, see [Join Clause](../../../language-reference/queries/join-clause.md).)| -||`Aggregate … In … Into LongCount()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| -||`Aggregate … In … Into Max()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| -||`Aggregate … In … Into Min()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| -||`Order By`

(For more information, see [Order By Clause](../../../language-reference/queries/order-by-clause.md).)| -||`Order By … Descending`

(For more information, see [Order By Clause](../../../language-reference/queries/order-by-clause.md).)| -||`Select`

(For more information, see [Select Clause](../../../language-reference/queries/select-clause.md).)| -||Multiple `From` clauses

(For more information, see [From Clause](../../../language-reference/queries/from-clause.md).)| -||`Skip`

(For more information, see [Skip Clause](../../../language-reference/queries/skip-clause.md).)| -||`Skip While`

(For more information, see [Skip While Clause](../../../language-reference/queries/skip-while-clause.md).)| -||`Aggregate … In … Into Sum()`

(For more information, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md).)| -||`Take`

(For more information, see [Take Clause](../../../language-reference/queries/take-clause.md).)| -||`Take While`

(For more information, see [Take While Clause](../../../language-reference/queries/take-while-clause.md).)| -||`Order By …, …`

(For more information, see [Order By Clause](../../../language-reference/queries/order-by-clause.md).)| -||`Order By …, … Descending`

(For more information, see [Order By Clause](../../../language-reference/queries/order-by-clause.md).)| -||`Where`

(For more information, see [Where Clause](../../../language-reference/queries/where-clause.md).)| - ## See also - diff --git a/docs/visual-basic/programming-guide/concepts/linq/set-operations.md b/docs/visual-basic/programming-guide/concepts/linq/set-operations.md index 695104099d8b4..2801e2058bfc9 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/set-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/set-operations.md @@ -14,28 +14,28 @@ The standard query operator methods that perform set operations are listed in th |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -| Distinct or DistinctBy |Removes duplicate values from a collection.|`Distinct`|


| -| Except or ExceptBy |Returns the set difference, which means the elements of one collection that do not appear in a second collection.|Not applicable.|


| -| Intersect or IntersectBy |Returns the set intersection, which means elements that appear in each of two collections.|Not applicable.|


| -| Union or UnionBy |Returns the set union, which means unique elements that appear in either of two collections.|Not applicable.|


| +| Distinct or DistinctBy |Removes duplicate values from a collection.|`Distinct`|


| +| Except or ExceptBy |Returns the set difference, which means the elements of one collection that do not appear in a second collection.|Not applicable.|


| +| Intersect or IntersectBy |Returns the set intersection, which means elements that appear in each of two collections.|Not applicable.|


| +| Union or UnionBy |Returns the set union, which means unique elements that appear in either of two collections.|Not applicable.|


| ## Comparison of Set Operations ### Distinct -The following illustration depicts the behavior of the method on a sequence of characters. The returned sequence contains the unique elements from the input sequence. +The following illustration depicts the behavior of the method on a sequence of characters. The returned sequence contains the unique elements from the input sequence. ![Graphic showing the behavior of Distinct().](./media/set-operations/distinct-method-behavior.png) ### Except -The following illustration depicts the behavior of . The returned sequence contains only the elements from the first input sequence that are not in the second input sequence. +The following illustration depicts the behavior of . The returned sequence contains only the elements from the first input sequence that are not in the second input sequence. ![Graphic showing the action of Except().](./media/set-operations/except-behavior-graphic.png "Shows the behavior of Except.") ### Intersect -The following illustration depicts the behavior of . The returned sequence contains the elements that are common to both of the input sequences. +The following illustration depicts the behavior of . The returned sequence contains the elements that are common to both of the input sequences. ![Graphic showing the intersection of two sequences.](./media/set-operations/intersection-two-sequences.png) diff --git a/docs/visual-basic/programming-guide/concepts/linq/sorting-data.md b/docs/visual-basic/programming-guide/concepts/linq/sorting-data.md index 202d6d8685f5e..622a26958a070 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/sorting-data.md +++ b/docs/visual-basic/programming-guide/concepts/linq/sorting-data.md @@ -18,11 +18,11 @@ The standard query operator methods that sort data are listed in the following s |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|OrderBy|Sorts values in ascending order.|`Order By`|

| -|OrderByDescending|Sorts values in descending order.|`Order By … Descending`|

| -|ThenBy|Performs a secondary sort in ascending order.|`Order By …, …`|

| -|ThenByDescending|Performs a secondary sort in descending order.|`Order By …, … Descending`|

| -|Reverse|Reverses the order of the elements in a collection.|Not applicable.|

| +|OrderBy|Sorts values in ascending order.|`Order By`|

| +|OrderByDescending|Sorts values in descending order.|`Order By … Descending`|

| +|ThenBy|Performs a secondary sort in ascending order.|`Order By …, …`|

| +|ThenByDescending|Performs a secondary sort in descending order.|`Order By …, … Descending`|

| +|Reverse|Reverses the order of the elements in a collection.|Not applicable.|

| ## Query Expression Syntax Examples diff --git a/docs/visual-basic/programming-guide/concepts/linq/standard-query-operators-overview.md b/docs/visual-basic/programming-guide/concepts/linq/standard-query-operators-overview.md index 22a0aa7b55230..7cc23300ae8e8 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/standard-query-operators-overview.md +++ b/docs/visual-basic/programming-guide/concepts/linq/standard-query-operators-overview.md @@ -6,17 +6,17 @@ ms.assetid: 302bd39e-2ec1-495b-94bf-37d370d6f05f --- # Standard Query Operators Overview (Visual Basic) -The *standard query operators* are the methods that form the LINQ pattern. Most of these methods operate on sequences, where a sequence is an object whose type implements the interface or the interface. The standard query operators provide query capabilities including filtering, projection, aggregation, sorting and more. +The *standard query operators* are the methods that form the LINQ pattern. Most of these methods operate on sequences, where a sequence is an object whose type implements the interface or the interface. The standard query operators provide query capabilities including filtering, projection, aggregation, sorting and more. -There are two sets of LINQ standard query operators, one that operates on objects of type and the other that operates on objects of type . The methods that make up each set are static members of the and classes, respectively. They are defined as *extension methods* of the type that they operate on. This means that they can be called by using either static method syntax or instance method syntax. +There are two sets of LINQ standard query operators, one that operates on objects of type and the other that operates on objects of type . The methods that make up each set are static members of the and classes, respectively. They are defined as *extension methods* of the type that they operate on. This means that they can be called by using either static method syntax or instance method syntax. -In addition, several standard query operator methods operate on types other than those based on or . The type defines two such methods that both operate on objects of type . These methods, and , let you enable a non-parameterized, or non-generic, collection to be queried in the LINQ pattern. They do this by creating a strongly typed collection of objects. The class defines two similar methods, and , that operate on objects of type . +In addition, several standard query operator methods operate on types other than those based on or . The type defines two such methods that both operate on objects of type . These methods, and , let you enable a non-parameterized, or non-generic, collection to be queried in the LINQ pattern. They do this by creating a strongly typed collection of objects. The class defines two similar methods, and , that operate on objects of type . -The standard query operators differ in the timing of their execution, depending on whether they return a singleton value or a sequence of values. Those methods that return a singleton value (for example, and ) execute immediately. Methods that return a sequence defer the query execution and return an enumerable object. +The standard query operators differ in the timing of their execution, depending on whether they return a singleton value or a sequence of values. Those methods that return a singleton value (for example, and ) execute immediately. Methods that return a sequence defer the query execution and return an enumerable object. -In the case of the methods that operate on in-memory collections, that is, those methods that extend , the returned enumerable object captures the arguments that were passed to the method. When that object is enumerated, the logic of the query operator is employed and the query results are returned. +In the case of the methods that operate on in-memory collections, that is, those methods that extend , the returned enumerable object captures the arguments that were passed to the method. When that object is enumerated, the logic of the query operator is employed and the query results are returned. -In contrast, methods that extend do not implement any querying behavior, but build an expression tree that represents the query to be performed. The query processing is handled by the source object. +In contrast, methods that extend do not implement any querying behavior, but build an expression tree that represents the query to be performed. The query processing is handled by the source object. Calls to query methods can be chained together in one query, which enables queries to become arbitrarily complex. @@ -65,7 +65,7 @@ Some of the more frequently used standard query operators have dedicated C# and ## Extending the Standard Query Operators -You can augment the set of standard query operators by creating domain-specific methods that are appropriate for your target domain or technology. You can also replace the standard query operators with your own implementations that provide additional services such as remote evaluation, query translation, and optimization. See for an example. +You can augment the set of standard query operators by creating domain-specific methods that are appropriate for your target domain or technology. You can also replace the standard query operators with your own implementations that provide additional services such as remote evaluation, query translation, and optimization. See for an example. ## Related Sections diff --git a/docs/visual-basic/programming-guide/concepts/linq/type-relationships-in-query-operations.md b/docs/visual-basic/programming-guide/concepts/linq/type-relationships-in-query-operations.md index 3c6f9b268d129..01f7aab653349 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/type-relationships-in-query-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/type-relationships-in-query-operations.md @@ -30,7 +30,7 @@ Visual Basic makes strong typing convenient by implementing local type inference However, even if you use local type inference in a query, the same type relationships are present among the variables in the data source, the query variable, and the query execution loop. It is useful to have a basic understanding of these type relationships when you are writing LINQ queries, or working with the samples and code examples in the documentation. -You may need to specify an explicit type for a range variable that does not match the type returned from the data source. You can specify the type of the range variable by using an `As` clause. However, this results in an error if the conversion is a [narrowing conversion](../../language-features/data-types/widening-and-narrowing-conversions.md) and `Option Strict` is set to `On`. Therefore, we recommend that you perform the conversion on the values retrieved from the data source. You can convert the values from the data source to the explicit range variable type by using the method. You can also cast the values selected in the `Select` clause to an explicit type that is different from the type of the range variable. These points are illustrated in the following code. +You may need to specify an explicit type for a range variable that does not match the type returned from the data source. You can specify the type of the range variable by using an `As` clause. However, this results in an error if the conversion is a [narrowing conversion](../../language-features/data-types/widening-and-narrowing-conversions.md) and `Option Strict` is set to `On`. Therefore, we recommend that you perform the conversion on the values retrieved from the data source. You can convert the values from the data source to the explicit range variable type by using the method. You can also cast the values selected in the `Select` clause to an explicit type that is different from the type of the range variable. These points are illustrated in the following code. [!code-vb[VbLINQTypeRels#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQTypeRels/VB/Class1.vb#4)] diff --git a/docs/visual-basic/programming-guide/concepts/linq/writing-your-first-linq-query.md b/docs/visual-basic/programming-guide/concepts/linq/writing-your-first-linq-query.md index 1e7c98621d69d..cbe3f0fd7b7c8 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/writing-your-first-linq-query.md +++ b/docs/visual-basic/programming-guide/concepts/linq/writing-your-first-linq-query.md @@ -39,15 +39,15 @@ A *query* is an expression that retrieves data from a data source. Queries are e ## The Data Source - Because the data source in the previous example is an array, it implicitly supports the generic interface. It is this fact that enables you to use an array as a data source for a LINQ query. Types that support or a derived interface such as the generic are called *queryable types*. + Because the data source in the previous example is an array, it implicitly supports the generic interface. It is this fact that enables you to use an array as a data source for a LINQ query. Types that support or a derived interface such as the generic are called *queryable types*. - As an implicitly queryable type, the array requires no modification or special treatment to serve as a LINQ data source. The same is true for any collection type that supports , including the generic , , and other classes in the .NET Framework class library. + As an implicitly queryable type, the array requires no modification or special treatment to serve as a LINQ data source. The same is true for any collection type that supports , including the generic , , and other classes in the .NET Framework class library. - If the source data does not already implement , a LINQ provider is needed to implement the functionality of the *standard query operators* for that data source. For example, LINQ to XML handles the work of loading an XML document into a queryable type, as shown in the following example. For more information about standard query operators, see [Standard Query Operators Overview (Visual Basic)](standard-query-operators-overview.md). + If the source data does not already implement , a LINQ provider is needed to implement the functionality of the *standard query operators* for that data source. For example, LINQ to XML handles the work of loading an XML document into a queryable type, as shown in the following example. For more information about standard query operators, see [Standard Query Operators Overview (Visual Basic)](standard-query-operators-overview.md). [!code-vb[VbLINQFirstQuery#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbLINQFirstQuery/VB/Class1.vb#2)] - With [!INCLUDE[vbtecdlinq](~/includes/vbtecdlinq-md.md)], you first create an object-relational mapping at design time, either manually or by using the [LINQ to SQL Tools in Visual Studio](/visualstudio/data-tools/linq-to-sql-tools-in-visual-studio2) in Visual Studio. You write your queries against the objects, and at run-time [!INCLUDE[vbtecdlinq](~/includes/vbtecdlinq-md.md)] handles the communication with the database. In the following example, `customers` represents a specific table in the database, and supports generic . + With [!INCLUDE[vbtecdlinq](~/includes/vbtecdlinq-md.md)], you first create an object-relational mapping at design time, either manually or by using the [LINQ to SQL Tools in Visual Studio](/visualstudio/data-tools/linq-to-sql-tools-in-visual-studio2) in Visual Studio. You write your queries against the objects, and at run-time [!INCLUDE[vbtecdlinq](~/includes/vbtecdlinq-md.md)] handles the communication with the database. In the following example, `customers` represents a specific table in the database, and supports generic . ```vb ' Create a data source from a SQL table. @@ -55,7 +55,7 @@ Dim db As New DataContext("C:\Northwind\Northwnd.mdf") Dim customers As Table(Of Customer) = db.GetTable(Of Customer) ``` - For more information about how to create specific types of data sources, see the documentation for the various LINQ providers. (For a list of these providers, see [LINQ (Language-Integrated Query)](index.md).) The basic rule is simple: a LINQ data source is any object that supports the generic interface, or an interface that inherits from it. + For more information about how to create specific types of data sources, see the documentation for the various LINQ providers. (For a list of these providers, see [LINQ (Language-Integrated Query)](index.md).) The basic rule is simple: a LINQ data source is any object that supports the generic interface, or an interface that inherits from it. > [!NOTE] > Types such as that support the non-generic interface can also be used as LINQ data sources. For an example that uses an , see [How to: Query an ArrayList with LINQ (Visual Basic)](how-to-query-an-arraylist-with-linq.md). @@ -118,7 +118,7 @@ Dim customers As Table(Of Customer) = db.GetTable(Of Customer) Using `ToList` or `ToArray` to force immediate execution is especially useful in scenarios in which you want to execute the query immediately and cache the results in a single collection object. For more information about these methods, see [Converting Data Types](converting-data-types.md). - You can also cause a query to be executed by using an `IEnumerable` method such as the method. + You can also cause a query to be executed by using an `IEnumerable` method such as the method. ## See also diff --git a/docs/visual-basic/programming-guide/language-features/arrays/array-dimensions.md b/docs/visual-basic/programming-guide/language-features/arrays/array-dimensions.md index 8d324445f1f97..b8ba47d07e4e4 100644 --- a/docs/visual-basic/programming-guide/language-features/arrays/array-dimensions.md +++ b/docs/visual-basic/programming-guide/language-features/arrays/array-dimensions.md @@ -16,7 +16,7 @@ ms.assetid: 385e911b-18c1-4e98-9924-c6d279101dd9 A *dimension* is a direction in which you can vary the specification of an array's elements. An array that holds the sales total for each day of the month has one dimension (the day of the month). An array that holds the sales total by department for each day of the month has two dimensions (the department number and the day of the month). The number of dimensions an array has is called its *rank*. > [!NOTE] -> You can use the property to determine how many dimensions an array has. +> You can use the property to determine how many dimensions an array has. ## Working with Dimensions @@ -86,7 +86,7 @@ Dim salesAmounts(4, 11, 30) As Double Note that, because each index varies from 0 to its maximum, each dimension of `salesAmounts` is declared as one less than the required length for that dimension. Note also that the size of the array increases with each new dimension. The three sizes in the preceding examples are 31, 372, and 1,860 elements respectively. > [!NOTE] -> You can create an array without using the `Dim` statement or the `New` clause. For example, you can call the method, or another component can pass your code an array created in this manner. Such an array can have a lower bound other than 0. You can always test for the lower bound of a dimension by using the method or the `LBound` function. +> You can create an array without using the `Dim` statement or the `New` clause. For example, you can call the method, or another component can pass your code an array created in this manner. Such an array can have a lower bound other than 0. You can always test for the lower bound of a dimension by using the method or the `LBound` function. ## See also diff --git a/docs/visual-basic/programming-guide/language-features/arrays/how-to-sort-an-array.md b/docs/visual-basic/programming-guide/language-features/arrays/how-to-sort-an-array.md index fe3c632aa4408..25741828555a3 100644 --- a/docs/visual-basic/programming-guide/language-features/arrays/how-to-sort-an-array.md +++ b/docs/visual-basic/programming-guide/language-features/arrays/how-to-sort-an-array.md @@ -2,9 +2,9 @@ description: "Learn more about: How to: sort an array in Visual Basic" title: "How to: Sort An Array" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "Array.Sort" -helpviewer_keywords: +helpviewer_keywords: - "arrays [Visual Basic], sorting" - "examples [Visual Basic], arrays" ms.assetid: 9289aeaa-9626-4698-94a7-1d1fd3702b87 @@ -16,7 +16,7 @@ This article shows an example of how to sort an array of strings in Visual Basic ## Example This example declares an array of `String` objects named `zooAnimals`, populates it, and then sorts it alphabetically: - + ```vb Private Sub SortAnimals() Dim zooAnimals(2) As String @@ -37,7 +37,7 @@ The following conditions may cause an exception: ## See also -- +- - [Arrays](index.md) - [Troubleshooting Arrays](troubleshooting-arrays.md) - [Collections](../../concepts/collections.md) diff --git a/docs/visual-basic/programming-guide/language-features/arrays/index.md b/docs/visual-basic/programming-guide/language-features/arrays/index.md index d9a17bcdfbdf5..320ef22388480 100644 --- a/docs/visual-basic/programming-guide/language-features/arrays/index.md +++ b/docs/visual-basic/programming-guide/language-features/arrays/index.md @@ -126,13 +126,13 @@ For additional examples, see [How to: Initialize an Array Variable in Visual Bas ## Iterating through an array -When you iterate through an array, you access each element in the array from the lowest index to the highest or from the highest to the lowest. Typically, use either the [For...Next Statement](../../../language-reference/statements/for-next-statement.md) or the [For Each...Next Statement](../../../language-reference/statements/for-each-next-statement.md) to iterate through the elements of an array. When you don't know the upper bounds of the array, you can call the method to get the highest value of the index. Although the lowest index value is almost always 0, you can call the method to get the lowest value of the index. +When you iterate through an array, you access each element in the array from the lowest index to the highest or from the highest to the lowest. Typically, use either the [For...Next Statement](../../../language-reference/statements/for-next-statement.md) or the [For Each...Next Statement](../../../language-reference/statements/for-each-next-statement.md) to iterate through the elements of an array. When you don't know the upper bounds of the array, you can call the method to get the highest value of the index. Although the lowest index value is almost always 0, you can call the method to get the lowest value of the index. The following example iterates through a one-dimensional array by using the [`For...Next`](../../../language-reference/statements/for-next-statement.md) statement. [!code-vb[iterate-one-dimensional-array](~/samples/snippets/visualbasic/programming-guide/language-features/arrays/iterate1d.vb)] -The following example iterates through a multidimensional array by using a [`For...Next`](../../../language-reference/statements/for-next-statement.md) statement. The method has a parameter that specifies the dimension. `GetUpperBound(0)` returns the highest index of the first dimension, and `GetUpperBound(1)` returns the highest index of the second dimension. +The following example iterates through a multidimensional array by using a [`For...Next`](../../../language-reference/statements/for-next-statement.md) statement. The method has a parameter that specifies the dimension. `GetUpperBound(0)` returns the highest index of the first dimension, and `GetUpperBound(1)` returns the highest index of the second dimension. [!code-vb[iterate-two-dimensional-array](~/samples/snippets/visualbasic/programming-guide/language-features/arrays/iterate2d.vb)] @@ -149,7 +149,7 @@ The size of an array is the product of the lengths of all its dimensions. It rep > [!NOTE] > This discussion of array size does not apply to jagged arrays. For information on jagged arrays and determining the size of a jagged array, see the [Jagged arrays](#jagged-arrays) section. -You can find the size of an array by using the property. You can find the length of each dimension of a multidimensional array by using the method. +You can find the size of an array by using the property. You can find the length of each dimension of a multidimensional array by using the method. You can resize an array variable by assigning a new array object to it or by using the [`ReDim`](../../../language-reference/statements/redim-statement.md) statement. The following example uses the `ReDim` statement to change a 100-element array to a 51-element array. @@ -168,7 +168,7 @@ There are several things to keep in mind when dealing with the size of an array. Every array has a data type, which differs from the data type of its elements. There is no single data type for all arrays. Instead, the data type of an array is determined by the number of dimensions, or *rank*, of the array, and the data type of the elements in the array. Two array variables are of the same data type only when they have the same rank and their elements have the same data type. The lengths of the dimensions of an array do not influence the array data type. -Every array inherits from the class, and you can declare a variable to be of type `Array`, but you cannot create an array of type `Array`. For example, although the following code declares the `arr` variable to be of type `Array` and calls the method to instantiate the array, the array's type proves to be Object[]. +Every array inherits from the class, and you can declare a variable to be of type `Array`, but you cannot create an array of type `Array`. For example, although the following code declares the `arr` variable to be of type `Array` and calls the method to instantiate the array, the array's type proves to be Object[]. [!code-vb[array-class](~/samples/snippets/visualbasic/programming-guide/language-features/arrays/array-class.vb)] @@ -176,10 +176,10 @@ Also, the [ReDim Statement](../../../language-reference/statements/redim-stateme You can find out the data type of either an array or its elements in several ways. -- You can call the method on the variable to get a object that represents the run-time type of the variable. The object holds extensive information in its properties and methods. -- You can pass the variable to the function to get a `String` with the name of run-time type. +- You can call the method on the variable to get a object that represents the run-time type of the variable. The object holds extensive information in its properties and methods. +- You can pass the variable to the function to get a `String` with the name of run-time type. -The following example calls the both the `GetType` method and the `TypeName` function to determine the type of an array. The array type is `Byte(,)`. Note that the property also indicates that the base type of the byte array is the class. +The following example calls the both the `GetType` method and the `TypeName` function to determine the type of an array. The array type is `Byte(,)`. Note that the property also indicates that the base type of the byte array is the class. [!code-vb[array-type](~/samples/snippets/visualbasic/programming-guide/language-features/arrays/array-type.vb)] @@ -209,7 +209,7 @@ The previous example assigns values to the jagged array on an element-by-element [!code-vb[jagged-array-initialization](~/samples/snippets/visualbasic/programming-guide/language-features/arrays/jagged-assign.vb)] -A jagged array is a one-dimensional array whose elements contain arrays. Therefore, the property and the `Array.GetLength(0)` method return the number of elements in the one-dimensional array, and `Array.GetLength(1)` throws an because a jagged array is not multidimensional. You determine the number of elements in each subarray by retrieving the value of each subarray's property. The following example illustrates how to determine the number of elements in a jagged array. +A jagged array is a one-dimensional array whose elements contain arrays. Therefore, the property and the `Array.GetLength(0)` method return the number of elements in the one-dimensional array, and `Array.GetLength(1)` throws an because a jagged array is not multidimensional. You determine the number of elements in each subarray by retrieving the value of each subarray's property. The following example illustrates how to determine the number of elements in a jagged array. [!code-vb[jagged-array-size](~/samples/snippets/visualbasic/programming-guide/language-features/arrays/jagged-length.vb)] @@ -229,7 +229,7 @@ Dim arrZ(-1) As String You might need to create a zero-length array under the following circumstances: -- Without risking a exception, your code must access members of the class, such as or , or call a Visual Basic function such as . +- Without risking a exception, your code must access members of the class, such as or , or call a Visual Basic function such as . - You want to keep your code simple by not having to check for `Nothing` as a special case. @@ -240,15 +240,15 @@ You might need to create a zero-length array under the following circumstances: In some cases, you may need to split a single array into multiple arrays. This involves identifying the point or points at which the array is to be split, and then spitting the array into two or more separate arrays. > [!NOTE] -> This section does not discuss splitting a single string into a string array based on some delimiter. For information on splitting a string, see the method. +> This section does not discuss splitting a single string into a string array based on some delimiter. For information on splitting a string, see the method. The most common criteria for splitting an array are: -- The number of elements in the array. For example, you might want to split an array of more than a specified number of elements into a number of approximately equal parts. For this purpose, you can use the value returned by either the or method. +- The number of elements in the array. For example, you might want to split an array of more than a specified number of elements into a number of approximately equal parts. For this purpose, you can use the value returned by either the or method. -- The value of an element, which serves as a delimiter that indicates where the array should be split. You can search for a specific value by calling the and methods. +- The value of an element, which serves as a delimiter that indicates where the array should be split. You can search for a specific value by calling the and methods. -Once you've determined the index or indexes at which the array should be split, you can then create the individual arrays by calling the method. +Once you've determined the index or indexes at which the array should be split, you can then create the individual arrays by calling the method. The following example splits an array into two arrays of approximately equal size. (If the total number of array elements is odd, the first array has one more element than the second.) @@ -260,10 +260,10 @@ The following example splits a string array into two arrays based on the presenc ## Joining arrays -You can also combine a number of arrays into a single larger array. To do this, you also use the method. +You can also combine a number of arrays into a single larger array. To do this, you also use the method. > [!NOTE] -> This section does not discuss joining a string array into a single string. For information on joining a string array, see the method. +> This section does not discuss joining a string array into a single string. For information on joining a string array, see the method. Before copying the elements of each array into the new array, you must first ensure that you have initialized the array so that it is large enough to accommodate the new array. You can do this in one of two ways: diff --git a/docs/visual-basic/programming-guide/language-features/arrays/troubleshooting-arrays.md b/docs/visual-basic/programming-guide/language-features/arrays/troubleshooting-arrays.md index dab586deabcb3..4cd7aec86ef11 100644 --- a/docs/visual-basic/programming-guide/language-features/arrays/troubleshooting-arrays.md +++ b/docs/visual-basic/programming-guide/language-features/arrays/troubleshooting-arrays.md @@ -2,7 +2,7 @@ description: "Learn more about: Troubleshooting Arrays (Visual Basic)" title: "Troubleshooting Arrays" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "troubleshooting arrays" - "arrays [Visual Basic], initialization errors" - "troubleshooting Visual Basic, arrays" @@ -13,50 +13,50 @@ ms.assetid: f4e971c7-c0a4-4ed7-a77a-8d71039f266f --- # Troubleshooting Arrays (Visual Basic) -This page lists some common problems that can occur when working with arrays. - -## Compilation Errors Declaring and Initializing an Array - - Compilation errors can arise from misunderstanding of the rules for declaring, creating, and initializing arrays. The most common causes of errors are the following: - -- Supplying a [New Operator](../../../language-reference/operators/new-operator.md) clause after specifying dimension lengths in the array variable declaration. The following code lines show invalid declarations of this type. - - `Dim INVALIDsingleDimByteArray(2) As Byte = New Byte()` - - `Dim INVALIDtwoDimShortArray(1, 1) As Short = New Short(,)` - - `Dim INVALIDjaggedByteArray(1)() As Byte = New Byte()()` - -- Specifying dimension lengths for more than the top-level array of a jagged array. The following code line shows an invalid declaration of this type. - - `Dim INVALIDjaggedByteArray(1)(1) As Byte` - -- Omitting the `New` keyword when specifying the element values. The following code line shows an invalid declaration of this type. - - `Dim INVALIDoneDimShortArray() As Short = Short() {0, 1, 2, 3}` - -- Supplying a `New` clause without braces (`{}`). The following code lines show invalid declarations of this type. - - `Dim INVALIDsingleDimByteArray() As Byte = New Byte()` - - `Dim INVALIDsingleDimByteArray() As Byte = New Byte(2)` - - `Dim INVALIDtwoDimShortArray(,) As Short = New Short(,)` - - `Dim INVALIDtwoDimShortArray(,) As Short = New Short(1, 1)` - -## Accessing an Array Out of Bounds - - The process of initializing an array assigns an upper bound and a lower bound to each dimension. Every access to an element of the array must specify a valid index, or subscript, for every dimension. If any index is below its lower bound or above its upper bound, an exception results. The compiler cannot detect such an error, so an error occurs at run time. - -### Determining Bounds - - If another component passes an array to your code, for example as a procedure argument, you do not know the size of that array or the lengths of its dimensions. You should always determine the upper bound for every dimension of an array before you attempt to access any elements. If the array has been created by some means other than a Visual Basic `New` clause, the lower bound might be something other than 0, and it is safest to determine that lower bound as well. - -### Specifying the Dimension - - When determining the bounds of a multidimensional array, take care how you specify the dimension. The `dimension` parameters of the and methods are 0-based, while the `Rank` parameters of the Visual Basic and functions are 1-based. - +This page lists some common problems that can occur when working with arrays. + +## Compilation Errors Declaring and Initializing an Array + + Compilation errors can arise from misunderstanding of the rules for declaring, creating, and initializing arrays. The most common causes of errors are the following: + +- Supplying a [New Operator](../../../language-reference/operators/new-operator.md) clause after specifying dimension lengths in the array variable declaration. The following code lines show invalid declarations of this type. + + `Dim INVALIDsingleDimByteArray(2) As Byte = New Byte()` + + `Dim INVALIDtwoDimShortArray(1, 1) As Short = New Short(,)` + + `Dim INVALIDjaggedByteArray(1)() As Byte = New Byte()()` + +- Specifying dimension lengths for more than the top-level array of a jagged array. The following code line shows an invalid declaration of this type. + + `Dim INVALIDjaggedByteArray(1)(1) As Byte` + +- Omitting the `New` keyword when specifying the element values. The following code line shows an invalid declaration of this type. + + `Dim INVALIDoneDimShortArray() As Short = Short() {0, 1, 2, 3}` + +- Supplying a `New` clause without braces (`{}`). The following code lines show invalid declarations of this type. + + `Dim INVALIDsingleDimByteArray() As Byte = New Byte()` + + `Dim INVALIDsingleDimByteArray() As Byte = New Byte(2)` + + `Dim INVALIDtwoDimShortArray(,) As Short = New Short(,)` + + `Dim INVALIDtwoDimShortArray(,) As Short = New Short(1, 1)` + +## Accessing an Array Out of Bounds + + The process of initializing an array assigns an upper bound and a lower bound to each dimension. Every access to an element of the array must specify a valid index, or subscript, for every dimension. If any index is below its lower bound or above its upper bound, an exception results. The compiler cannot detect such an error, so an error occurs at run time. + +### Determining Bounds + + If another component passes an array to your code, for example as a procedure argument, you do not know the size of that array or the lengths of its dimensions. You should always determine the upper bound for every dimension of an array before you attempt to access any elements. If the array has been created by some means other than a Visual Basic `New` clause, the lower bound might be something other than 0, and it is safest to determine that lower bound as well. + +### Specifying the Dimension + + When determining the bounds of a multidimensional array, take care how you specify the dimension. The `dimension` parameters of the and methods are 0-based, while the `Rank` parameters of the Visual Basic and functions are 1-based. + ## See also - [Arrays](index.md) diff --git a/docs/visual-basic/programming-guide/language-features/collection-initializers/how-to-create-an-add-extension-method-used-by-a-collection-initializer.md b/docs/visual-basic/programming-guide/language-features/collection-initializers/how-to-create-an-add-extension-method-used-by-a-collection-initializer.md index 5d94624964fd9..5ae443f7ee99b 100644 --- a/docs/visual-basic/programming-guide/language-features/collection-initializers/how-to-create-an-add-extension-method-used-by-a-collection-initializer.md +++ b/docs/visual-basic/programming-guide/language-features/collection-initializers/how-to-create-an-add-extension-method-used-by-a-collection-initializer.md @@ -2,26 +2,26 @@ description: "Learn more about: How to: Create an Add Extension Method Used by a Collection Initializer (Visual Basic)" title: "How to: Create an Add Extension Method Used by a Collection Initializer" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "collection initializers [Visual Basic]" ms.assetid: f64b52c7-8b11-4410-93a6-cb3aeebcc772 --- # How to: Create an Add Extension Method Used by a Collection Initializer (Visual Basic) -When you use a collection initializer to create a collection, the Visual Basic compiler searches for an `Add` method of the collection type for which the parameters for the `Add` method match the types of the values in the collection initializer. This `Add` method is used to populate the collection with the values from the collection initializer. - - If no matching `Add` method exists and you cannot modify the code for the collection, you can add an extension method called `Add` that takes the parameters that are required by the collection initializer. This is typically what you need to do when you use collection initializers for generic collections. - -## Example - - The following example shows how to add an extension method to the generic type so that a collection initializer can be used to add objects of type `Employee`. The extension method enables you to use the shortened collection initializer syntax. - - [!code-vb[VbVbalrCollectionInitializersHowTo1#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrCollectionInitializersHowTo1/VB/Module1.vb#1)] - - [!code-vb[VbVbalrCollectionInitializersHowTo1#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrCollectionInitializersHowTo1/VB/Module1.vb#2)] - - [!code-vb[VbVbalrCollectionInitializersHowTo1#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrCollectionInitializersHowTo1/VB/Module1.vb#3)] - +When you use a collection initializer to create a collection, the Visual Basic compiler searches for an `Add` method of the collection type for which the parameters for the `Add` method match the types of the values in the collection initializer. This `Add` method is used to populate the collection with the values from the collection initializer. + + If no matching `Add` method exists and you cannot modify the code for the collection, you can add an extension method called `Add` that takes the parameters that are required by the collection initializer. This is typically what you need to do when you use collection initializers for generic collections. + +## Example + + The following example shows how to add an extension method to the generic type so that a collection initializer can be used to add objects of type `Employee`. The extension method enables you to use the shortened collection initializer syntax. + + [!code-vb[VbVbalrCollectionInitializersHowTo1#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrCollectionInitializersHowTo1/VB/Module1.vb#1)] + + [!code-vb[VbVbalrCollectionInitializersHowTo1#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrCollectionInitializersHowTo1/VB/Module1.vb#2)] + + [!code-vb[VbVbalrCollectionInitializersHowTo1#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrCollectionInitializersHowTo1/VB/Module1.vb#3)] + ## See also - [Collection Initializers](index.md) diff --git a/docs/visual-basic/programming-guide/language-features/collection-initializers/index.md b/docs/visual-basic/programming-guide/language-features/collection-initializers/index.md index b67aaf76ca3e0..dc8422ff1245c 100644 --- a/docs/visual-basic/programming-guide/language-features/collection-initializers/index.md +++ b/docs/visual-basic/programming-guide/language-features/collection-initializers/index.md @@ -28,7 +28,7 @@ A collection initializer consists of a list of comma-separated values that are e [!code-vb[VbVbalrCollectionInitializers#2](../../../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrCollectionInitializers/VB/Module1.vb#2)] -When you create a collection, such as a or a , you must supply the collection type before the collection initializer, as shown in the following code. +When you create a collection, such as a or a , you must supply the collection type before the collection initializer, as shown in the following code. [!code-vb[VbVbalrCollectionInitializers#13](../../../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrCollectionInitializers/VB/Module1.vb#13)] @@ -37,7 +37,7 @@ When you create a collection, such as a by using a collection initializer, each string value in the collection initializer is passed to the method. If you want to create a collection by using a collection initializer, the specified type must be valid collection type. Examples of valid collection types include classes that implement the interface or inherit the class. The specified type must also expose an `Add` method that meets the following criteria. +When you create a collection by using a collection initializer, each value that is supplied in the collection initializer is passed to the appropriate `Add` method of the collection. For example, if you create a by using a collection initializer, each string value in the collection initializer is passed to the method. If you want to create a collection by using a collection initializer, the specified type must be valid collection type. Examples of valid collection types include classes that implement the interface or inherit the class. The specified type must also expose an `Add` method that meets the following criteria. - The `Add` method must be available from the scope in which the collection initializer is being called. The `Add` method does not have to be public if you are using the collection initializer in a scenario where non-public methods of the collection can be accessed. @@ -59,7 +59,7 @@ If the collection has an `Add` method that has parameters that match the constru You can nest values within a collection initializer to identify a specific overload of an `Add` method for the collection that is being created. The values passed to the `Add` method must be separated by commas and enclosed in braces (`{}`), like you would do in an array literal or collection initializer. -When you create a collection by using nested values, each element of the nested value list is passed as an argument to the `Add` method that matches the element types. For example, the following code example creates a in which the keys are of type `Integer` and the values are of type `String`. Each of the nested value lists is matched to the method for the `Dictionary`. +When you create a collection by using nested values, each element of the nested value list is passed as an argument to the `Add` method that matches the element types. For example, the following code example creates a in which the keys are of type `Integer` and the values are of type `String`. Each of the nested value lists is matched to the method for the `Dictionary`. [!code-vb[VbVbalrCollectionInitializers#5](../../../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrCollectionInitializers/VB/Module1.vb#5)] diff --git a/docs/visual-basic/programming-guide/language-features/constants-enums/how-to-determine-the-string-associated-with-an-enumeration-value.md b/docs/visual-basic/programming-guide/language-features/constants-enums/how-to-determine-the-string-associated-with-an-enumeration-value.md index 607cb4be05539..42ad6bcda4005 100644 --- a/docs/visual-basic/programming-guide/language-features/constants-enums/how-to-determine-the-string-associated-with-an-enumeration-value.md +++ b/docs/visual-basic/programming-guide/language-features/constants-enums/how-to-determine-the-string-associated-with-an-enumeration-value.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Determine the String Associated with an Enumeration Value (Visual Basic)" title: "How to: Determine the String Associated with an Enumeration Value" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "enumerations [Visual Basic]" - "strings [Visual Basic], enumeration values" - "values [Visual Basic], enumeration members" @@ -10,18 +10,18 @@ ms.assetid: 9253e7c8-579c-49a2-8f26-392b20ea99eb --- # How to: Determine the String Associated with an Enumeration Value (Visual Basic) -The and methods allow you to determine the strings and values associated with enumeration members. - -### To determine the string associated with an enumeration - -- Use the method to retrieve the strings associated with the enumeration members. This example declares an enumeration, `flavorEnum`, then uses the method to display the strings associated with each member. - - [!code-vb[VbEnumsTask#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbEnumsTask/VB/Class2.vb#2)] - +The and methods allow you to determine the strings and values associated with enumeration members. + +### To determine the string associated with an enumeration + +- Use the method to retrieve the strings associated with the enumeration members. This example declares an enumeration, `flavorEnum`, then uses the method to display the strings associated with each member. + + [!code-vb[VbEnumsTask#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbEnumsTask/VB/Class2.vb#2)] + ## See also -- -- +- +- - - [How to: Declare an Enumeration](how-to-declare-enumerations.md) - [How to: Refer to an Enumeration Member](how-to-refer-to-an-enumeration-member.md) diff --git a/docs/visual-basic/programming-guide/language-features/constants-enums/how-to-iterate-through-an-enumeration.md b/docs/visual-basic/programming-guide/language-features/constants-enums/how-to-iterate-through-an-enumeration.md index 8fcbff2f19114..780bdd8968357 100644 --- a/docs/visual-basic/programming-guide/language-features/constants-enums/how-to-iterate-through-an-enumeration.md +++ b/docs/visual-basic/programming-guide/language-features/constants-enums/how-to-iterate-through-an-enumeration.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Iterate Through An Enumeration in Visual Basic" title: "How to: Iterate Through An Enumeration" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "arrays [Visual Basic], iterating" - "enumerations [Visual Basic], iterating" - "ListBox control [Windows Forms], populating from an enumeration" @@ -10,14 +10,14 @@ ms.assetid: e5aa10eb-cfcd-4a3b-8e76-f06b8f2002be --- # How to: Iterate Through An Enumeration in Visual Basic -Enumerations provide a convenient way to work with sets of related constants, and to associate constant values with names. To iterate through an enumeration, you can move it into an array using the method. You could also iterate through an enumeration using a `For...Each` statement, using the or method to extract the string or numeric value. - -### To iterate through an enumeration - -- Declare an array and convert the enumeration to it with the method before passing the array as you would any other variable. The following example displays each member of the enumeration as it iterates through the enumeration. - - [!code-vb[VbEnumsTask#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbEnumsTask/VB/Class2.vb#7)] - +Enumerations provide a convenient way to work with sets of related constants, and to associate constant values with names. To iterate through an enumeration, you can move it into an array using the method. You could also iterate through an enumeration using a `For...Each` statement, using the or method to extract the string or numeric value. + +### To iterate through an enumeration + +- Declare an array and convert the enumeration to it with the method before passing the array as you would any other variable. The following example displays each member of the enumeration as it iterates through the enumeration. + + [!code-vb[VbEnumsTask#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbEnumsTask/VB/Class2.vb#7)] + ## See also - [Enumerations Overview](enumerations-overview.md) diff --git a/docs/visual-basic/programming-guide/language-features/control-flow/walkthrough-implementing-ienumerable-of-t.md b/docs/visual-basic/programming-guide/language-features/control-flow/walkthrough-implementing-ienumerable-of-t.md index 79a7f55f799c3..2711998f4b214 100644 --- a/docs/visual-basic/programming-guide/language-features/control-flow/walkthrough-implementing-ienumerable-of-t.md +++ b/docs/visual-basic/programming-guide/language-features/control-flow/walkthrough-implementing-ienumerable-of-t.md @@ -2,7 +2,7 @@ description: "Learn more about: Walkthrough: Implementing IEnumerable(Of T) in Visual Basic" title: "Implementing IEnumerable" ms.date: 07/31/2018 -helpviewer_keywords: +helpviewer_keywords: - "control flow [Visual Basic]" - "enumerable interfaces" - "loop structures [Visual Basic], optimizing performance" @@ -11,18 +11,18 @@ ms.assetid: c60d7589-51f2-4463-a2d5-22506bbc1554 --- # Walkthrough: Implementing IEnumerable(Of T) in Visual Basic -The interface is implemented by classes that can return a sequence of values one item at a time. The advantage of returning data one item at a time is that you do not have to load the complete set of data into memory to work with it. You only have to use sufficient memory to load a single item from the data. Classes that implement the `IEnumerable(T)` interface can be used with `For Each` loops or LINQ queries. - - For example, consider an application that must read a large text file and return each line from the file that matches particular search criteria. The application uses a LINQ query to return lines from the file that match the specified criteria. To query the contents of the file by using a LINQ query, the application could load the contents of the file into an array or a collection. However, loading the whole file into an array or collection would consume far more memory than is required. The LINQ query could instead query the file contents by using an enumerable class, returning only values that match the search criteria. Queries that return only a few matching values would consume far less memory. - - You can create a class that implements the interface to expose source data as enumerable data. Your class that implements the `IEnumerable(T)` interface will require another class that implements the interface to iterate through the source data. These two classes enable you to return items of data sequentially as a specific type. - - In this walkthrough, you will create a class that implements the `IEnumerable(Of String)` interface and a class that implements the `IEnumerator(Of String)` interface to read a text file one line at a time. - -[!INCLUDE[note_settings_general](~/includes/note-settings-general-md.md)] - -## Creating the Enumerable Class - +The interface is implemented by classes that can return a sequence of values one item at a time. The advantage of returning data one item at a time is that you do not have to load the complete set of data into memory to work with it. You only have to use sufficient memory to load a single item from the data. Classes that implement the `IEnumerable(T)` interface can be used with `For Each` loops or LINQ queries. + + For example, consider an application that must read a large text file and return each line from the file that matches particular search criteria. The application uses a LINQ query to return lines from the file that match the specified criteria. To query the contents of the file by using a LINQ query, the application could load the contents of the file into an array or a collection. However, loading the whole file into an array or collection would consume far more memory than is required. The LINQ query could instead query the file contents by using an enumerable class, returning only values that match the search criteria. Queries that return only a few matching values would consume far less memory. + + You can create a class that implements the interface to expose source data as enumerable data. Your class that implements the `IEnumerable(T)` interface will require another class that implements the interface to iterate through the source data. These two classes enable you to return items of data sequentially as a specific type. + + In this walkthrough, you will create a class that implements the `IEnumerable(Of String)` interface and a class that implements the `IEnumerator(Of String)` interface to read a text file one line at a time. + +[!INCLUDE[note_settings_general](~/includes/note-settings-general-md.md)] + +## Creating the Enumerable Class + **Create the enumerable class project** 1. In Visual Basic, on the **File** menu, point to **New** and then click **Project**. @@ -33,8 +33,8 @@ The interface is implemented b 1. Right-click the StreamReaderEnumerable project, point to **Add**, and then click **New Item**. Select the **Class** template. In the **Name** box, type `StreamReaderEnumerator.vb` and click **OK**. - The first class in this project is the enumerable class and will implement the `IEnumerable(Of String)` interface. This generic interface implements the interface and guarantees that consumers of this class can access values typed as `String`. - + The first class in this project is the enumerable class and will implement the `IEnumerable(Of String)` interface. This generic interface implements the interface and guarantees that consumers of this class can access values typed as `String`. + **Add the code to implement IEnumerable** 1. Open the StreamReaderEnumerable.vb file. @@ -44,15 +44,15 @@ The interface is implemented b [!code-vb[VbVbalrIteratorWalkthrough#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIteratorWalkthrough/VB/StreamReaderIterator.vb#1)] Visual Basic automatically populates the class with the members that are required by the `IEnumerable(Of String)` interface. - + 3. This enumerable class will read lines from a text file one line at a time. Add the following code to the class to expose a public constructor that takes a file path as an input parameter. [!code-vb[VbVbalrIteratorWalkthrough#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIteratorWalkthrough/VB/StreamReaderIterator.vb#2)] -4. Your implementation of the method of the `IEnumerable(Of String)` interface will return a new instance of the `StreamReaderEnumerator` class. The implementation of the `GetEnumerator` method of the `IEnumerable` interface can be made `Private`, because you have to expose only members of the `IEnumerable(Of String)` interface. Replace the code that Visual Basic generated for the `GetEnumerator` methods with the following code. +4. Your implementation of the method of the `IEnumerable(Of String)` interface will return a new instance of the `StreamReaderEnumerator` class. The implementation of the `GetEnumerator` method of the `IEnumerable` interface can be made `Private`, because you have to expose only members of the `IEnumerable(Of String)` interface. Replace the code that Visual Basic generated for the `GetEnumerator` methods with the following code. + + [!code-vb[VbVbalrIteratorWalkthrough#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIteratorWalkthrough/VB/StreamReaderIterator.vb#3)] - [!code-vb[VbVbalrIteratorWalkthrough#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIteratorWalkthrough/VB/StreamReaderIterator.vb#3)] - **Add the code to implement IEnumerator** 1. Open the StreamReaderEnumerator.vb file. @@ -82,13 +82,13 @@ The interface is implemented b 7. The `Dispose` method of the `IEnumerator` interface guarantees that all unmanaged resources are released before the iterator is destroyed. The file handle that is used by the `StreamReader` object is an unmanaged resource and must be closed before the iterator instance is destroyed. Replace the code that Visual Basic generated for the `Dispose` method with the following code. [!code-vb[VbVbalrIteratorWalkthrough#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIteratorWalkthrough/VB/StreamReaderIterator.vb#9)] - + ## Using the Sample Iterator - You can use an enumerable class in your code together with control structures that require an object that implements `IEnumerable`, such as a `For Next` loop or a LINQ query. The following example shows the `StreamReaderEnumerable` in a LINQ query. - - [!code-vb[VbVbalrIteratorWalkthrough#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIteratorWalkthrough/VB/Module1.vb#10)] - + You can use an enumerable class in your code together with control structures that require an object that implements `IEnumerable`, such as a `For Next` loop or a LINQ query. The following example shows the `StreamReaderEnumerable` in a LINQ query. + + [!code-vb[VbVbalrIteratorWalkthrough#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIteratorWalkthrough/VB/Module1.vb#10)] + ## See also - [Introduction to LINQ in Visual Basic](../linq/introduction-to-linq.md) diff --git a/docs/visual-basic/programming-guide/language-features/data-types/conversions-between-strings-and-other-types.md b/docs/visual-basic/programming-guide/language-features/data-types/conversions-between-strings-and-other-types.md index 3fca37499d6eb..acdc7415ae129 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/conversions-between-strings-and-other-types.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/conversions-between-strings-and-other-types.md @@ -2,7 +2,7 @@ description: "Learn more about: Conversions Between Strings and Other Types (Visual Basic)" title: "Conversions Between Strings and Other Types" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "data type conversion [Visual Basic], string" - "conversions [Visual Basic], type" - "string conversion [Visual Basic]" @@ -13,31 +13,31 @@ ms.assetid: c3a99596-f09a-44a5-81dd-1b89a094f1df --- # Conversions Between Strings and Other Types (Visual Basic) -You can convert a numeric, `Boolean`, or date/time value to a `String`. You can also convert in the reverse direction — from a string value to numeric, `Boolean`, or `Date` — provided the contents of the string can be interpreted as a valid value of the destination data type. If they cannot, a run-time error occurs. - - The conversions for all these assignments, in either direction, are narrowing conversions. You should use the type conversion keywords (`CBool`, `CByte`, `CDate`, `CDbl`, `CDec`, `CInt`, `CLng`, `CSByte`, `CShort`, `CSng`, `CStr`, `CUInt`, `CULng`, `CUShort`, and `CType`). The and functions give you additional control over conversions between strings and numbers. - - If you have defined a class or structure, you can define type conversion operators between `String` and the type of your class or structure. For more information, see [How to: Define a Conversion Operator](../procedures/how-to-define-a-conversion-operator.md). - -## Conversion of Numbers to Strings - - You can use the `Format` function to convert a number to a formatted string, which can include not only the appropriate digits but also formatting symbols such as a currency sign (such as `$`), thousands separators or *digit grouping symbols* (such as `,`), and a decimal separator (such as `.`). `Format` automatically uses the appropriate symbols according to the **Regional Options** settings specified in the Windows **Control Panel**. - - Note that the concatenation (`&`) operator can convert a number to a string implicitly, as the following example shows. - -```vb -' The following statement converts count to a String value. -Str = "The total count is " & count -``` - -## Conversion of Strings to Numbers - - You can use the `Val` function to explicitly convert the digits in a string to a number. `Val` reads the string until it encounters a character other than a digit, space, tab, line feed, or period. The sequences "&O" and "&H" alter the base of the number system and terminate the scanning. Until it stops reading, `Val` converts all appropriate characters to a numeric value. For example, the following statement returns the value `141.825`. - - `Val(" 14 1.825 miles")` - - When Visual Basic converts a string to a numeric value, it uses the **Regional Options** settings specified in the Windows **Control Panel** to interpret the thousands separator, decimal separator, and currency symbol. This means that a conversion might succeed under one setting but not another. For example, `"$14.20"` is acceptable in the English (United States) locale but not in any French locale. - +You can convert a numeric, `Boolean`, or date/time value to a `String`. You can also convert in the reverse direction — from a string value to numeric, `Boolean`, or `Date` — provided the contents of the string can be interpreted as a valid value of the destination data type. If they cannot, a run-time error occurs. + + The conversions for all these assignments, in either direction, are narrowing conversions. You should use the type conversion keywords (`CBool`, `CByte`, `CDate`, `CDbl`, `CDec`, `CInt`, `CLng`, `CSByte`, `CShort`, `CSng`, `CStr`, `CUInt`, `CULng`, `CUShort`, and `CType`). The and functions give you additional control over conversions between strings and numbers. + + If you have defined a class or structure, you can define type conversion operators between `String` and the type of your class or structure. For more information, see [How to: Define a Conversion Operator](../procedures/how-to-define-a-conversion-operator.md). + +## Conversion of Numbers to Strings + + You can use the `Format` function to convert a number to a formatted string, which can include not only the appropriate digits but also formatting symbols such as a currency sign (such as `$`), thousands separators or *digit grouping symbols* (such as `,`), and a decimal separator (such as `.`). `Format` automatically uses the appropriate symbols according to the **Regional Options** settings specified in the Windows **Control Panel**. + + Note that the concatenation (`&`) operator can convert a number to a string implicitly, as the following example shows. + +```vb +' The following statement converts count to a String value. +Str = "The total count is " & count +``` + +## Conversion of Strings to Numbers + + You can use the `Val` function to explicitly convert the digits in a string to a number. `Val` reads the string until it encounters a character other than a digit, space, tab, line feed, or period. The sequences "&O" and "&H" alter the base of the number system and terminate the scanning. Until it stops reading, `Val` converts all appropriate characters to a numeric value. For example, the following statement returns the value `141.825`. + + `Val(" 14 1.825 miles")` + + When Visual Basic converts a string to a numeric value, it uses the **Regional Options** settings specified in the Windows **Control Panel** to interpret the thousands separator, decimal separator, and currency symbol. This means that a conversion might succeed under one setting but not another. For example, `"$14.20"` is acceptable in the English (United States) locale but not in any French locale. + ## See also - [Type Conversions in Visual Basic](type-conversions.md) diff --git a/docs/visual-basic/programming-guide/language-features/data-types/efficient-use-of-data-types.md b/docs/visual-basic/programming-guide/language-features/data-types/efficient-use-of-data-types.md index d202ca12ea5da..ba161cbac3190 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/efficient-use-of-data-types.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/efficient-use-of-data-types.md @@ -2,7 +2,7 @@ description: "Learn more about: Efficient Use of Data Types (Visual Basic)" title: "Efficient Use of Data Types" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "performance, data type efficiency" - "data types [Visual Basic], weak typing" - "AscW function [Visual Basic], preferred to Asc" @@ -50,10 +50,10 @@ Protected s As String ## See also -- -- -- -- +- +- +- +- - [Data Types](index.md) - [Numeric Data Types](numeric-data-types.md) - [Variable Declaration](../variables/variable-declaration.md) diff --git a/docs/visual-basic/programming-guide/language-features/data-types/generic-procedures.md b/docs/visual-basic/programming-guide/language-features/data-types/generic-procedures.md index e02376cf6beaf..6f313a84eeb30 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/generic-procedures.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/generic-procedures.md @@ -2,7 +2,7 @@ description: "Learn more about: Generic Procedures in Visual Basic" title: "Generic Procedures" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "generic methods [Visual Basic], type inference" - "generics [Visual Basic], type inference" - "procedures [Visual Basic], generic" @@ -16,21 +16,21 @@ ms.assetid: 95577b28-137f-4d5c-a149-919c828600e5 --- # Generic Procedures in Visual Basic -A *generic procedure*, also called a *generic method*, is a procedure defined with at least one type parameter. This allows the calling code to tailor the data types to its requirements each time it calls the procedure. - - A procedure is not generic simply by virtue of being defined inside a generic class or a generic structure. To be generic, the procedure must take at least one type parameter, in addition to any normal parameters it might take. A generic class or structure can contain nongeneric procedures, and a nongeneric class, structure, or module can contain generic procedures. - - A generic procedure can use its type parameters in its normal parameter list, in its return type if it has one, and in its procedure code. - -## Type Inference - - You can call a generic procedure without supplying any type arguments at all. If you call it this way, the compiler attempts to determine the appropriate data types to pass to the procedure's type arguments. This is called *type inference*. The following code shows a call in which the compiler infers that it should pass type `String` to the type parameter `t`. - - [!code-vb[VbVbalrDataTypes#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#15)] - - If the compiler cannot infer the type arguments from the context of your call, it reports an error. One possible cause of such an error is an array rank mismatch. For example, suppose you define a normal parameter as an array of a type parameter. If you call the generic procedure supplying an array of a different rank (number of dimensions), the mismatch causes type inference to fail. The following code shows a call in which a two-dimensional array is passed to a procedure that expects a one-dimensional array. - -```vb +A *generic procedure*, also called a *generic method*, is a procedure defined with at least one type parameter. This allows the calling code to tailor the data types to its requirements each time it calls the procedure. + + A procedure is not generic simply by virtue of being defined inside a generic class or a generic structure. To be generic, the procedure must take at least one type parameter, in addition to any normal parameters it might take. A generic class or structure can contain nongeneric procedures, and a nongeneric class, structure, or module can contain generic procedures. + + A generic procedure can use its type parameters in its normal parameter list, in its return type if it has one, and in its procedure code. + +## Type Inference + + You can call a generic procedure without supplying any type arguments at all. If you call it this way, the compiler attempts to determine the appropriate data types to pass to the procedure's type arguments. This is called *type inference*. The following code shows a call in which the compiler infers that it should pass type `String` to the type parameter `t`. + + [!code-vb[VbVbalrDataTypes#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#15)] + + If the compiler cannot infer the type arguments from the context of your call, it reports an error. One possible cause of such an error is an array rank mismatch. For example, suppose you define a normal parameter as an array of a type parameter. If you call the generic procedure supplying an array of a different rank (number of dimensions), the mismatch causes type inference to fail. The following code shows a call in which a two-dimensional array is passed to a procedure that expects a one-dimensional array. + +```vb Public Sub demoSub(Of t)(ByVal arg() As t) End Sub @@ -39,31 +39,31 @@ Public Sub callDemoSub() demoSub(twoDimensions) End Sub ``` - - You can invoke type inference only by omitting all the type arguments. If you supply one type argument, you must supply them all. - - Type inference is supported only for generic procedures. You cannot invoke type inference on generic classes, structures, interfaces, or delegates. - -## Example - -### Description - - The following example defines a generic `Function` procedure to find a particular element in an array. It defines one type parameter and uses it to construct the two parameters in the parameter list. - -### Code - - [!code-vb[VbVbalrDataTypes#14](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#14)] - -### Comments - - The preceding example requires the ability to compare `searchValue` against each element of `searchArray`. To guarantee this ability, it constrains the type parameter `T` to implement the interface. The code uses the method instead of the `=` operator, because there is no guarantee that a type argument supplied for `T` supports the `=` operator. - - You can test the `findElement` procedure with the following code. - - [!code-vb[VbVbalrDataTypes#13](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#13)] - - The preceding calls to `MsgBox` display "0", "1", and "-1" respectively. - + + You can invoke type inference only by omitting all the type arguments. If you supply one type argument, you must supply them all. + + Type inference is supported only for generic procedures. You cannot invoke type inference on generic classes, structures, interfaces, or delegates. + +## Example + +### Description + + The following example defines a generic `Function` procedure to find a particular element in an array. It defines one type parameter and uses it to construct the two parameters in the parameter list. + +### Code + + [!code-vb[VbVbalrDataTypes#14](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#14)] + +### Comments + + The preceding example requires the ability to compare `searchValue` against each element of `searchArray`. To guarantee this ability, it constrains the type parameter `T` to implement the interface. The code uses the method instead of the `=` operator, because there is no guarantee that a type argument supplied for `T` supports the `=` operator. + + You can test the `findElement` procedure with the following code. + + [!code-vb[VbVbalrDataTypes#13](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#13)] + + The preceding calls to `MsgBox` display "0", "1", and "-1" respectively. + ## See also - [Generic Types in Visual Basic](generic-types.md) diff --git a/docs/visual-basic/programming-guide/language-features/data-types/generic-types.md b/docs/visual-basic/programming-guide/language-features/data-types/generic-types.md index a7b626d0e9c74..c353c4cdfed6c 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/generic-types.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/generic-types.md @@ -2,7 +2,7 @@ description: "Learn more about: Generic Types in Visual Basic (Visual Basic)" title: "Generic Types" ms.date: 01/31/2025 -helpviewer_keywords: +helpviewer_keywords: - "generic interfaces" - "data type arguments [Visual Basic], defining" - "generic delegates" @@ -47,7 +47,7 @@ An analogy is a screwdriver set with removable heads. You inspect the screw and When you define a generic type, you parameterize it with one or more data types. Type parameters allow code to tailor the data types to its requirements. Your code can declare several different programming elements from the generic element, each one acting on a different set of data types. But the declared elements all perform the identical logic, no matter what data types they're using. -For example, you might want to create and use a queue class that operates on a specific data type such as `String`. You can declare such a class from , as the following example shows. +For example, you might want to create and use a queue class that operates on a specific data type such as `String`. You can declare such a class from , as the following example shows. :::code language="visual-basic" source="~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb" id="Snippet1"::: @@ -88,7 +88,7 @@ A generic type has the following advantages over these alternatives: - **Type Safety.** Generic types enforce compile-time type checking. Types based on `Object` accept any data type, and you must write code to check whether an input data type is acceptable. With generic types, the compiler can catch type mismatches before run time. - **Performance.** Generic types don't have to *box* and *unbox* data, because each one is specialized for one data type. Operations based on `Object` must box input data types to convert them to `Object` and unbox data destined for output. Boxing and unboxing reduce performance. - Types based on `Object` are also late-bound, which means that accessing their members requires extra code at run time. Type conversions also reduce performance. + Types based on `Object` are also late-bound, which means that accessing their members requires extra code at run time. Type conversions also reduce performance. - **Code Consolidation.** The code in a generic type has to be defined only once. A set of type-specific versions of a type must replicate the same code in each version, with the only difference being the specific data type for that version. With generic types, the type-specific versions are all generated from the original generic type. - **Code Reuse.** Code that doesn't depend on a particular data type can be reused with various data types if it's generic. You can often reuse it even with a data type that you didn't originally predict. - **IDE Support.** When you use a constructed type declared from a generic type, the integrated development environment (IDE) can give you more support while you're developing your code. For example, IntelliSense can show you the type-specific options for an argument to a constructor or method. @@ -117,7 +117,7 @@ Your constraint can specify the following requirements in any combination: C# code can declare that a type argument must be an [*unmanaged type*](../../../../csharp/programming-guide/generics/constraints-on-type-parameters.md#unmanaged-constraint). Visual Basic enforces this constraint for Visual Basic code that uses a generic type or method that was defined with this constraint (in C#). However, you can't declare an `unmanaged` constraint on a type parameter in Visual Basic. -If you need to impose more than one requirement, you use a comma-separated *constraint list* inside braces (`{ }`). To require an accessible constructor, you include the [New Operator](../../../language-reference/operators/new-operator.md) keyword in the list. To require a reference type, you include the `Class` keyword; to require a value type, you include the `Structure` keyword. +If you need to impose more than one requirement, you use a comma-separated *constraint list* inside braces (`{ }`). To require an accessible constructor, you include the [New Operator](../../../language-reference/operators/new-operator.md) keyword in the list. To require a reference type, you include the `Class` keyword; to require a value type, you include the `Structure` keyword. For more information on constraints, see [Type List](../../../language-reference/statements/type-list.md). diff --git a/docs/visual-basic/programming-guide/language-features/data-types/how-to-use-a-generic-class.md b/docs/visual-basic/programming-guide/language-features/data-types/how-to-use-a-generic-class.md index a96095997a0b9..f2e8bdd885c90 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/how-to-use-a-generic-class.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/how-to-use-a-generic-class.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Use a Generic Class (Visual Basic)" title: "How to: Use a Generic Class" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "type parameters [Visual Basic], defining" - "data type arguments [Visual Basic], defining" - "arguments [Visual Basic], data types" @@ -25,22 +25,22 @@ ms.assetid: 242dd2a6-86c4-4ce7-83f2-f2661803f752 --- # How to: Use a Generic Class (Visual Basic) -A class that takes *type parameters* is called a *generic class*. If you are using a generic class, you can generate a *constructed class* from it by supplying a *type argument* for each of these parameters. You can then declare a variable of the constructed class type, and you can create an instance of the constructed class and assign it to that variable. - - In addition to classes, you can also define and use generic structures, interfaces, procedures, and delegates. - - The following procedure takes a generic class defined in the .NET Framework and creates an instance from it. - -### To use a class that takes a type parameter - -1. At the beginning of your source file, include an [Imports Statement (.NET Namespace and Type)](../../../language-reference/statements/imports-statement-net-namespace-and-type.md) to import the namespace. This allows you to refer to the class without having to fully qualify it to differentiate it from other queue classes such as . - -2. Create the object in the normal way, but add `(Of type)` immediately after the class name. - - The following example uses the same class () to create two queue objects that hold items of different data types. It adds items to the end of each queue and then removes and displays items from the front of each queue. - - [!code-vb[VbVbalrDataTypes#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#9)] - +A class that takes *type parameters* is called a *generic class*. If you are using a generic class, you can generate a *constructed class* from it by supplying a *type argument* for each of these parameters. You can then declare a variable of the constructed class type, and you can create an instance of the constructed class and assign it to that variable. + + In addition to classes, you can also define and use generic structures, interfaces, procedures, and delegates. + + The following procedure takes a generic class defined in the .NET Framework and creates an instance from it. + +### To use a class that takes a type parameter + +1. At the beginning of your source file, include an [Imports Statement (.NET Namespace and Type)](../../../language-reference/statements/imports-statement-net-namespace-and-type.md) to import the namespace. This allows you to refer to the class without having to fully qualify it to differentiate it from other queue classes such as . + +2. Create the object in the normal way, but add `(Of type)` immediately after the class name. + + The following example uses the same class () to create two queue objects that hold items of different data types. It adds items to the end of each queue and then removes and displays items from the front of each queue. + + [!code-vb[VbVbalrDataTypes#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#9)] + ## See also - [Data Types](index.md) diff --git a/docs/visual-basic/programming-guide/language-features/data-types/nullable-value-types.md b/docs/visual-basic/programming-guide/language-features/data-types/nullable-value-types.md index 8a6a75813e394..1a484aa2d8624 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/nullable-value-types.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/nullable-value-types.md @@ -2,9 +2,9 @@ description: "Learn more about: Nullable Value Types (Visual Basic)" title: "Nullable Value Types" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.Nullable" -helpviewer_keywords: +helpviewer_keywords: - "nullable types [Visual Basic]" - "? [Visual Basic]" - "types [Visual Basic], nullable" @@ -16,7 +16,7 @@ ms.assetid: 9ac3b602-6f96-4e6d-96f7-cd4e81c468a6 Sometimes you work with a value type that does not have a defined value in certain circumstances. For example, a field in a database might have to distinguish between having an assigned value that is meaningful and not having an assigned value. Value types can be extended to take either their normal values or a null value. Such an extension is called a *nullable type*. -Each nullable value type is constructed from the generic structure. Consider a database that tracks work-related activities. The following example constructs a nullable `Boolean` type and declares a variable of that type. You can write the declaration in three ways: +Each nullable value type is constructed from the generic structure. Consider a database that tracks work-related activities. The following example constructs a nullable `Boolean` type and declares a variable of that type. You can write the declaration in three ways: [!code-vb[VbVbalrNullableValue#1](../../../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrNullableValue/VB/Class1.vb#1)] @@ -28,11 +28,11 @@ You cannot construct a nullable type on a reference type such as an array, a `St ## Using a Nullable Type Variable -The most important members of a nullable value type are its and properties. For a variable of a nullable value type, tells you whether the variable contains a defined value. If is `True`, you can read the value from . Note that both and are `ReadOnly` properties. +The most important members of a nullable value type are its and properties. For a variable of a nullable value type, tells you whether the variable contains a defined value. If is `True`, you can read the value from . Note that both and are `ReadOnly` properties. ### Default Values -When you declare a variable with a nullable value type, its property has a default value of `False`. This means that by default the variable has no defined value, instead of the default value of its underlying value type. In the following example, the variable `numberOfChildren` initially has no defined value, even though the default value of the `Integer` type is 0. +When you declare a variable with a nullable value type, its property has a default value of `False`. This means that by default the variable has no defined value, instead of the default value of its underlying value type. In the following example, the variable `numberOfChildren` initially has no defined value, even though the default value of the `Integer` type is 0. [!code-vb[VbVbalrNullableValue#2](../../../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrNullableValue/VB/Class1.vb#2)] @@ -49,11 +49,11 @@ If a variable or property of a nullable value type contains a defined value, you [!code-vb[VbVbalrNullableValue#4](../../../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrNullableValue/VB/Class1.vb#4)] > [!NOTE] -> Although you can assign `Nothing` to a variable of a nullable value type, you cannot test it for `Nothing` by using the equal sign. Comparison that uses the equal sign, `someVar = Nothing`, always evaluates to `Nothing`. You can test the variable's property for `False`, or test by using the `Is` or `IsNot` operator. +> Although you can assign `Nothing` to a variable of a nullable value type, you cannot test it for `Nothing` by using the equal sign. Comparison that uses the equal sign, `someVar = Nothing`, always evaluates to `Nothing`. You can test the variable's property for `False`, or test by using the `Is` or `IsNot` operator. ### Retrieving Values -To retrieve the value of a variable of a nullable value type, you should first test its property to confirm that it has a value. If you try to read the value when is `False`, Visual Basic throws an exception. The following example shows the recommended way to read the variable `numberOfChildren` of the previous examples. +To retrieve the value of a variable of a nullable value type, you should first test its property to confirm that it has a value. If you try to read the value when is `False`, Visual Basic throws an exception. The following example shows the recommended way to read the variable `numberOfChildren` of the previous examples. [!code-vb[VbVbalrNullableValue#5](../../../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrNullableValue/VB/Class1.vb#5)] @@ -103,7 +103,7 @@ A database is one of the most important places to use nullable value types. Not ## See also - -- +- - [Data Types](index.md) - [Value Types and Reference Types](value-types-and-reference-types.md) - [Troubleshooting Data Types](troubleshooting-data-types.md) diff --git a/docs/visual-basic/programming-guide/language-features/data-types/structures-and-classes.md b/docs/visual-basic/programming-guide/language-features/data-types/structures-and-classes.md index eff5176b544d9..85dbf8a761da6 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/structures-and-classes.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/structures-and-classes.md @@ -2,7 +2,7 @@ description: "Learn more about: Structures and Classes (Visual Basic)" title: "Structures and Classes" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "classes [Visual Basic], vs. structures" - "structures [Visual Basic]" - "classes [Visual Basic]" @@ -13,78 +13,78 @@ ms.assetid: a221e74a-ffcf-4bdc-a0f6-a088a9bf26cc --- # Structures and Classes (Visual Basic) -Visual Basic unifies the syntax for structures and classes, with the result that both entities support most of the same features. However, there are also important differences between structures and classes. - - Classes have the advantage of being reference types — passing a reference is more efficient than passing a structure variable with all its data. On the other hand, structures do not require allocation of memory on the global heap. - - Because you cannot inherit from a structure, structures should be used only for objects that do not need to be extended. Use structures when the object you wish to create has a small instance size, and take into account the performance characteristics of classes versus structures. - -## Similarities - - Structures and classes are similar in the following respects: - -- Both are *container* types, meaning that they contain other types as members. - +Visual Basic unifies the syntax for structures and classes, with the result that both entities support most of the same features. However, there are also important differences between structures and classes. + + Classes have the advantage of being reference types — passing a reference is more efficient than passing a structure variable with all its data. On the other hand, structures do not require allocation of memory on the global heap. + + Because you cannot inherit from a structure, structures should be used only for objects that do not need to be extended. Use structures when the object you wish to create has a small instance size, and take into account the performance characteristics of classes versus structures. + +## Similarities + + Structures and classes are similar in the following respects: + +- Both are *container* types, meaning that they contain other types as members. + - Both have members, which can include constructors, methods, properties, fields, constants, enumerations, events, and event handlers. - -- Members of both can have individualized access levels. For example, one member can be declared `Public` and another `Private`. - -- Both can implement interfaces. - -- Both can have shared constructors, with or without parameters. - -- Both can expose a *default property*, provided that property takes at least one parameter. - -- Both can declare and raise events, and both can declare delegates. - -## Differences - - Structures and classes differ in the following particulars: - -- Structures are *value types*; classes are *reference types*. A variable of a structure type contains the structure's data, rather than containing a reference to the data as a class type does. - -- Structures use stack allocation; classes use heap allocation. - -- All structure elements are `Public` by default; class variables and constants are `Private` by default, while other class members are `Public` by default. This behavior for class members provides compatibility with the Visual Basic 6.0 system of defaults. - -- A structure must have at least one nonshared variable or nonshared, noncustom event element; a class can be completely empty. - -- Structure elements cannot be declared as `Protected`; class members can. - -- A structure procedure can handle events only if it is a [Shared](../../../language-reference/modifiers/shared.md)`Sub` procedure, and only by means of the [AddHandler Statement](../../../language-reference/statements/addhandler-statement.md); any class procedure can handle events, using either the [Handles](../../../language-reference/statements/handles-clause.md) keyword or the `AddHandler` statement. For more information, see [Events](../events/index.md). - -- Structure variable declarations cannot specify initializers or initial sizes for arrays; class variable declarations can. - -- Structures implicitly inherit from the class and cannot inherit from any other type; classes can inherit from any class or classes other than . - -- Structures are not inheritable; classes are. - -- Structures are never terminated, so the common language runtime (CLR) never calls the method on any structure; classes are terminated by the garbage collector (GC), which calls on a class when it detects there are no active references remaining. - -- A structure does not require a constructor; a class does. - -- Structures can have nonshared constructors only if they take parameters; classes can have them with or without parameters. - - Every structure has an implicit public constructor without parameters. This constructor initializes all the structure's data elements to their default values. You cannot redefine this behavior. - -## Instances and Variables - - Because structures are value types, each structure variable is permanently bound to an individual structure instance. But classes are reference types, and an object variable can refer to various class instances at different times. This distinction affects your usage of structures and classes in the following ways: - -- **Initialization.** A structure variable implicitly includes an initialization of the elements using the structure's parameterless constructor. Therefore, `Dim s As struct1` is equivalent to `Dim s As struct1 = New struct1()`. - -- **Assigning Variables.** When you assign one structure variable to another, or pass a structure instance to a procedure argument, the current values of all the variable elements are copied to the new structure. When you assign one object variable to another, or pass an object variable to a procedure, only the reference pointer is copied. - -- **Assigning Nothing.** You can assign the value [Nothing](../../../language-reference/nothing.md) to a structure variable, but the instance continues to be associated with the variable. You can still call its methods and access its data elements, although variable elements are reinitialized by the assignment. - - In contrast, if you set an object variable to `Nothing`, you dissociate it from any class instance, and you cannot access any members through the variable until you assign another instance to it. - -- **Multiple Instances.** An object variable can have different class instances assigned to it at different times, and several object variables can refer to the same class instance at the same time. Changes you make to the values of class members affect those members when accessed through another variable pointing to the same instance. - - Structure elements, however, are isolated within their own instance. Changes to their values are not reflected in any other structure variables, even in other instances of the same `Structure` declaration. - -- **Equality.** Equality testing of two structures must be performed with an element-by-element test. Two object variables can be compared using the method. indicates whether the two variables point to the same instance. - + +- Members of both can have individualized access levels. For example, one member can be declared `Public` and another `Private`. + +- Both can implement interfaces. + +- Both can have shared constructors, with or without parameters. + +- Both can expose a *default property*, provided that property takes at least one parameter. + +- Both can declare and raise events, and both can declare delegates. + +## Differences + + Structures and classes differ in the following particulars: + +- Structures are *value types*; classes are *reference types*. A variable of a structure type contains the structure's data, rather than containing a reference to the data as a class type does. + +- Structures use stack allocation; classes use heap allocation. + +- All structure elements are `Public` by default; class variables and constants are `Private` by default, while other class members are `Public` by default. This behavior for class members provides compatibility with the Visual Basic 6.0 system of defaults. + +- A structure must have at least one nonshared variable or nonshared, noncustom event element; a class can be completely empty. + +- Structure elements cannot be declared as `Protected`; class members can. + +- A structure procedure can handle events only if it is a [Shared](../../../language-reference/modifiers/shared.md)`Sub` procedure, and only by means of the [AddHandler Statement](../../../language-reference/statements/addhandler-statement.md); any class procedure can handle events, using either the [Handles](../../../language-reference/statements/handles-clause.md) keyword or the `AddHandler` statement. For more information, see [Events](../events/index.md). + +- Structure variable declarations cannot specify initializers or initial sizes for arrays; class variable declarations can. + +- Structures implicitly inherit from the class and cannot inherit from any other type; classes can inherit from any class or classes other than . + +- Structures are not inheritable; classes are. + +- Structures are never terminated, so the common language runtime (CLR) never calls the method on any structure; classes are terminated by the garbage collector (GC), which calls on a class when it detects there are no active references remaining. + +- A structure does not require a constructor; a class does. + +- Structures can have nonshared constructors only if they take parameters; classes can have them with or without parameters. + + Every structure has an implicit public constructor without parameters. This constructor initializes all the structure's data elements to their default values. You cannot redefine this behavior. + +## Instances and Variables + + Because structures are value types, each structure variable is permanently bound to an individual structure instance. But classes are reference types, and an object variable can refer to various class instances at different times. This distinction affects your usage of structures and classes in the following ways: + +- **Initialization.** A structure variable implicitly includes an initialization of the elements using the structure's parameterless constructor. Therefore, `Dim s As struct1` is equivalent to `Dim s As struct1 = New struct1()`. + +- **Assigning Variables.** When you assign one structure variable to another, or pass a structure instance to a procedure argument, the current values of all the variable elements are copied to the new structure. When you assign one object variable to another, or pass an object variable to a procedure, only the reference pointer is copied. + +- **Assigning Nothing.** You can assign the value [Nothing](../../../language-reference/nothing.md) to a structure variable, but the instance continues to be associated with the variable. You can still call its methods and access its data elements, although variable elements are reinitialized by the assignment. + + In contrast, if you set an object variable to `Nothing`, you dissociate it from any class instance, and you cannot access any members through the variable until you assign another instance to it. + +- **Multiple Instances.** An object variable can have different class instances assigned to it at different times, and several object variables can refer to the same class instance at the same time. Changes you make to the values of class members affect those members when accessed through another variable pointing to the same instance. + + Structure elements, however, are isolated within their own instance. Changes to their values are not reflected in any other structure variables, even in other instances of the same `Structure` declaration. + +- **Equality.** Equality testing of two structures must be performed with an element-by-element test. Two object variables can be compared using the method. indicates whether the two variables point to the same instance. + ## See also - [Data Types](index.md) diff --git a/docs/visual-basic/programming-guide/language-features/data-types/troubleshooting-data-types.md b/docs/visual-basic/programming-guide/language-features/data-types/troubleshooting-data-types.md index a2739e6d5315f..595f7e592ee50 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/troubleshooting-data-types.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/troubleshooting-data-types.md @@ -33,13 +33,13 @@ Because of this imprecision, you cannot rely on exact results when you operate o | To compare floating-point quantities | |---| -|1. Calculate the absolute value of their difference by using the method of the class in the namespace.
2. Determine an acceptable maximum difference, such that you can consider the two quantities to be equal for practical purposes if their difference is no larger.
3. Compare the absolute value of the difference to the acceptable difference.| +|1. Calculate the absolute value of their difference by using the method of the class in the namespace.
2. Determine an acceptable maximum difference, such that you can consider the two quantities to be equal for practical purposes if their difference is no larger.
3. Compare the absolute value of the difference to the acceptable difference.| The following example demonstrates both incorrect and correct comparison of two `Double` values. [!code-vb[VbVbalrDataTypes#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#10)] -The previous example uses the method of the structure so that it can specify better precision than the `CStr` keyword uses. The default is 15 digits, but the "G17" format extends it to 17 digits. +The previous example uses the method of the structure so that it can specify better precision than the `CStr` keyword uses. The default is 15 digits, but the "G17" format extends it to 17 digits. ## Mod Operator Does Not Return Accurate Result @@ -55,7 +55,7 @@ The following example demonstrates the potential imprecision of floating-point o [!code-vb[VbVbalrDataTypes#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#11)] -The previous example uses the method of the structure so that it can specify better precision than the `CStr` keyword uses. The default is 15 digits, but the "G17" format extends it to 17 digits. +The previous example uses the method of the structure so that it can specify better precision than the `CStr` keyword uses. The default is 15 digits, but the "G17" format extends it to 17 digits. Because `zeroPointTwo` is `Double`, its value for 0.2 is an infinitely repeating binary fraction with a stored value of 0.20000000000000001. Dividing 2.0 by this quantity yields 9.9999999999999995 with a remainder of 0.19999999999999991. @@ -75,7 +75,7 @@ When you use the `CType` or `CBool` conversion keywords to convert numeric data ### Conversion in the Framework -The method of the class in the namespace converts `True` to +1. +The method of the class in the namespace converts `True` to +1. If you must convert a `Boolean` value to a numeric data type, be careful about which conversion method you use. @@ -112,7 +112,7 @@ If you must convert from `String` to another data type, the safest procedure is ### Character Arrays -A single `Char` and an array of `Char` elements both widen to `String`. However, `String` does not widen to `Char()`. To convert a `String` value to a `Char` array, you can use the method of the class. +A single `Char` and an array of `Char` elements both widen to `String`. However, `String` does not widen to `Char()`. To convert a `String` value to a `Char` array, you can use the method of the class. ### Meaningless Values diff --git a/docs/visual-basic/programming-guide/language-features/data-types/tuples.md b/docs/visual-basic/programming-guide/language-features/data-types/tuples.md index dbf590a58ee5c..c91dcbd07d15f 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/tuples.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/tuples.md @@ -77,7 +77,7 @@ When field name inference fails, Visual Basic does not generate a compiler error ## Tuples versus structures -A Visual Basic tuple is a value type that is an instance of one of the **System.ValueTuple** generic types. For example, the `holiday` tuple defined in the previous example is an instance of the structure. It is designed to be a lightweight container for data. Since the tuple aims to make it easy to create an object with multiple data items, it lacks some of the features that a custom structure might have. These include: +A Visual Basic tuple is a value type that is an instance of one of the **System.ValueTuple** generic types. For example, the `holiday` tuple defined in the previous example is an instance of the structure. It is designed to be a lightweight container for data. Since the tuple aims to make it easy to create an object with multiple data items, it lacks some of the features that a custom structure might have. These include: - Custom members. You cannot define your own properties, methods, or events for a tuple. diff --git a/docs/visual-basic/programming-guide/language-features/data-types/value-types-and-reference-types.md b/docs/visual-basic/programming-guide/language-features/data-types/value-types-and-reference-types.md index 5f21c253b1fdb..59aab3093a525 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/value-types-and-reference-types.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/value-types-and-reference-types.md @@ -2,7 +2,7 @@ description: "Learn more about: Value Types and Reference Types" title: "Value Types and Reference Types" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "reference data types [Visual Basic]" - "reference types [Visual Basic]" - "value types [Visual Basic]" @@ -15,63 +15,63 @@ ms.assetid: fc82ce15-5a40-4c5c-a1e1-a556830e7391 # Value Types and Reference Types There are two kinds of types in Visual Basic: reference types and value types. Variables of reference types store references to their data (objects), while variables of value types directly contain their data. With reference types, two variables can reference the same object; therefore, operations on one variable can affect the object referenced by the other variable. With value types, each variable has its own copy of the data, and it is not possible for operations on one variable to affect the other (except in the case of the [ByRef modifier on parameters](../../../language-reference/modifiers/byref.md)). - -## Value Types - - A data type is a *value type* if it holds the data within its own memory allocation. Value types include the following: - -- All numeric data types - -- `Boolean`, `Char`, and `Date` - -- All structures, even if their members are reference types - -- Enumerations, since their underlying type is always `SByte`, `Short`, `Integer`, `Long`, `Byte`, `UShort`, `UInteger`, or `ULong` - - Every structure is a value type, even if it contains reference type members. For this reason, value types such as `Char` and `Integer` are implemented by .NET Framework structures. - - You can declare a value type by using the reserved keyword, for example, `Decimal`. You can also use the `New` keyword to initialize a value type. This is especially useful if the type has a constructor that takes parameters. An example of this is the constructor, which builds a new `Decimal` value from the supplied parts. - -## Reference Types - - A *reference type* stores a reference to its data. Reference types include the following: - -- `String` - -- All arrays, even if their elements are value types - -- Class types, such as - -- Delegates - - A class is a *reference type*. Note that every array is a reference type, even if its members are value types. - - Since every reference type represents an underlying .NET Framework class, you must use the [New Operator](../../../language-reference/operators/new-operator.md) keyword when you initialize it. The following statement initializes an array. - -```vb -Dim totals() As Single = New Single(8) {} -``` - -## Elements That Are Not Types - - The following programming elements do not qualify as types, because you cannot specify any of them as a data type for a declared element: - -- Namespaces - -- Modules - -- Events - -- Properties and procedures - -- Variables, constants, and fields - -## Working with the Object Data Type - - You can assign either a reference type or a value type to a variable of the `Object` data type. An `Object` variable always holds a reference to the data, never the data itself. However, if you assign a value type to an `Object` variable, it behaves as if it holds its own data. For more information, see [Object Data Type](../../../language-reference/data-types/object-data-type.md). - - You can find out whether an `Object` variable is acting as a reference type or a value type by passing it to the method in the class of the namespace. returns `True` if the content of the `Object` variable represents a reference type. - + +## Value Types + + A data type is a *value type* if it holds the data within its own memory allocation. Value types include the following: + +- All numeric data types + +- `Boolean`, `Char`, and `Date` + +- All structures, even if their members are reference types + +- Enumerations, since their underlying type is always `SByte`, `Short`, `Integer`, `Long`, `Byte`, `UShort`, `UInteger`, or `ULong` + + Every structure is a value type, even if it contains reference type members. For this reason, value types such as `Char` and `Integer` are implemented by .NET Framework structures. + + You can declare a value type by using the reserved keyword, for example, `Decimal`. You can also use the `New` keyword to initialize a value type. This is especially useful if the type has a constructor that takes parameters. An example of this is the constructor, which builds a new `Decimal` value from the supplied parts. + +## Reference Types + + A *reference type* stores a reference to its data. Reference types include the following: + +- `String` + +- All arrays, even if their elements are value types + +- Class types, such as + +- Delegates + + A class is a *reference type*. Note that every array is a reference type, even if its members are value types. + + Since every reference type represents an underlying .NET Framework class, you must use the [New Operator](../../../language-reference/operators/new-operator.md) keyword when you initialize it. The following statement initializes an array. + +```vb +Dim totals() As Single = New Single(8) {} +``` + +## Elements That Are Not Types + + The following programming elements do not qualify as types, because you cannot specify any of them as a data type for a declared element: + +- Namespaces + +- Modules + +- Events + +- Properties and procedures + +- Variables, constants, and fields + +## Working with the Object Data Type + + You can assign either a reference type or a value type to a variable of the `Object` data type. An `Object` variable always holds a reference to the data, never the data itself. However, if you assign a value type to an `Object` variable, it behaves as if it holds its own data. For more information, see [Object Data Type](../../../language-reference/data-types/object-data-type.md). + + You can find out whether an `Object` variable is acting as a reference type or a value type by passing it to the method in the class of the namespace. returns `True` if the content of the `Object` variable represents a reference type. + ## See also - [Nullable Value Types](nullable-value-types.md) diff --git a/docs/visual-basic/programming-guide/language-features/early-late-binding/calling-a-property-or-method-using-a-string-name.md b/docs/visual-basic/programming-guide/language-features/early-late-binding/calling-a-property-or-method-using-a-string-name.md index 06d7262e766f8..0ffcddec1d29b 100644 --- a/docs/visual-basic/programming-guide/language-features/early-late-binding/calling-a-property-or-method-using-a-string-name.md +++ b/docs/visual-basic/programming-guide/language-features/early-late-binding/calling-a-property-or-method-using-a-string-name.md @@ -2,7 +2,7 @@ description: "Learn more about: Calling a Property or Method Using a String Name (Visual Basic)" title: "Calling a Property or Method Using a String Name" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "passing operators [Visual Basic]" - "strings [Visual Basic], passing new operators as" - "objects [Visual Basic], setting properties" @@ -16,34 +16,34 @@ ms.assetid: 79a7b8b4-b8c7-4ad8-aca8-12a9a2b32f03 --- # Calling a Property or Method Using a String Name (Visual Basic) -In most cases, you can discover the properties and methods of an object at design time, and write code to handle them. However, in some cases you may not know about an object's properties and methods in advance, or you may just want the flexibility of enabling an end user to specify properties or execute methods at run time. - -## CallByName Function - - Consider, for example, a client application that evaluates expressions entered by the user by passing an operator to a COM component. Suppose you are constantly adding new functions to the component that require new operators. When you use standard object access techniques, you must recompile and redistribute the client application before it could use the new operators. To avoid this, you can use the `CallByName` function to pass the new operators as strings, without changing the application. - - The `CallByName` function lets you use a string to specify a property or method at run time. The signature for the `CallByName` function looks like this: - - *Result* = `CallByName`(*Object*, *ProcedureName*, *CallType*, *Arguments*()) - - The first argument, *Object*, takes the name of the object you want to act upon. The *ProcedureName* argument takes a string that contains the name of the method or property procedure to be invoked. The *CallType* argument takes a constant that represents the type of procedure to invoke: a method (`Microsoft.VisualBasic.CallType.Method`), a property read (`Microsoft.VisualBasic.CallType.Get`), or a property set (`Microsoft.VisualBasic.CallType.Set`). The *Arguments* argument, which is optional, takes an array of type `Object` that contains any arguments to the procedure. - - You can use `CallByName` with classes in your current solution, but it is most often used to access COM objects or objects from .NET Framework assemblies. - - Suppose you add a reference to an assembly that contains a class named `MathClass`, which has a new function named `SquareRoot`, as shown in the following code: - - [!code-vb[VbVbalrOOP#53](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#53)] - - Your application could use text box controls to control which method will be called and its arguments. For example, if `TextBox1` contains the expression to be evaluated, and `TextBox2` is used to enter the name of the function, you can use the following code to invoke the `SquareRoot` function on the expression in `TextBox1`: - - [!code-vb[VbVbalrOOP#54](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#54)] - - If you enter "64" in `TextBox1`, "SquareRoot" in `TextBox2`, and then call the `CallMath` procedure, the square root of the number in `TextBox1` is evaluated. The code in the example invokes the `SquareRoot` function (which takes a string that contains the expression to be evaluated as a required argument) and returns "8" in `TextBox1` (the square root of 64). Of course, if the user enters an invalid string in `TextBox2`, if the string contains the name of a property instead of a method, or if the method had an additional required argument, a run-time error occurs. You have to add robust error-handling code when you use `CallByName` to anticipate these or any other errors. - +In most cases, you can discover the properties and methods of an object at design time, and write code to handle them. However, in some cases you may not know about an object's properties and methods in advance, or you may just want the flexibility of enabling an end user to specify properties or execute methods at run time. + +## CallByName Function + + Consider, for example, a client application that evaluates expressions entered by the user by passing an operator to a COM component. Suppose you are constantly adding new functions to the component that require new operators. When you use standard object access techniques, you must recompile and redistribute the client application before it could use the new operators. To avoid this, you can use the `CallByName` function to pass the new operators as strings, without changing the application. + + The `CallByName` function lets you use a string to specify a property or method at run time. The signature for the `CallByName` function looks like this: + + *Result* = `CallByName`(*Object*, *ProcedureName*, *CallType*, *Arguments*()) + + The first argument, *Object*, takes the name of the object you want to act upon. The *ProcedureName* argument takes a string that contains the name of the method or property procedure to be invoked. The *CallType* argument takes a constant that represents the type of procedure to invoke: a method (`Microsoft.VisualBasic.CallType.Method`), a property read (`Microsoft.VisualBasic.CallType.Get`), or a property set (`Microsoft.VisualBasic.CallType.Set`). The *Arguments* argument, which is optional, takes an array of type `Object` that contains any arguments to the procedure. + + You can use `CallByName` with classes in your current solution, but it is most often used to access COM objects or objects from .NET Framework assemblies. + + Suppose you add a reference to an assembly that contains a class named `MathClass`, which has a new function named `SquareRoot`, as shown in the following code: + + [!code-vb[VbVbalrOOP#53](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#53)] + + Your application could use text box controls to control which method will be called and its arguments. For example, if `TextBox1` contains the expression to be evaluated, and `TextBox2` is used to enter the name of the function, you can use the following code to invoke the `SquareRoot` function on the expression in `TextBox1`: + + [!code-vb[VbVbalrOOP#54](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#54)] + + If you enter "64" in `TextBox1`, "SquareRoot" in `TextBox2`, and then call the `CallMath` procedure, the square root of the number in `TextBox1` is evaluated. The code in the example invokes the `SquareRoot` function (which takes a string that contains the expression to be evaluated as a required argument) and returns "8" in `TextBox1` (the square root of 64). Of course, if the user enters an invalid string in `TextBox2`, if the string contains the name of a property instead of a method, or if the method had an additional required argument, a run-time error occurs. You have to add robust error-handling code when you use `CallByName` to anticipate these or any other errors. + > [!NOTE] -> While the `CallByName` function may be useful in some cases, you must weigh its usefulness against the performance implications — using `CallByName` to invoke a procedure is slightly slower than a late-bound call. If you are invoking a function that is called repeatedly, such as inside a loop, `CallByName` can have a severe effect on performance. - +> While the `CallByName` function may be useful in some cases, you must weigh its usefulness against the performance implications — using `CallByName` to invoke a procedure is slightly slower than a late-bound call. If you are invoking a function that is called repeatedly, such as inside a loop, `CallByName` can have a severe effect on performance. + ## See also -- +- - [Determining Object Type](determining-object-type.md) diff --git a/docs/visual-basic/programming-guide/language-features/early-late-binding/determining-object-type.md b/docs/visual-basic/programming-guide/language-features/early-late-binding/determining-object-type.md index 538f023fb4ee2..5b17194ea6dad 100644 --- a/docs/visual-basic/programming-guide/language-features/early-late-binding/determining-object-type.md +++ b/docs/visual-basic/programming-guide/language-features/early-late-binding/determining-object-type.md @@ -2,7 +2,7 @@ description: "Learn more about: Determining Object Type (Visual Basic)" title: "Determining Object Type" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "classes [Visual Basic], discovering which an object belongs to" - "types [Visual Basic], determining Visual Basic object types" - "object variables [Visual Basic], testing values" @@ -13,37 +13,37 @@ ms.assetid: d95e7ad1-cd63-41d6-9a28-d7a1380d49c1 --- # Determining Object Type (Visual Basic) -Generic object variables (that is, variables you declare as `Object`) can hold objects from any class. When using variables of type `Object`, you may need to take different actions based on the class of the object; for example, some objects might not support a particular property or method. Visual Basic provides two means of determining which type of object is stored in an object variable: the `TypeName` function and the `TypeOf...Is` operator. - -## TypeName and TypeOf…Is - - The `TypeName` function returns a string and is the best choice when you need to store or display the class name of an object, as shown in the following code fragment: - - [!code-vb[VbVbalrOOP#92](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#92)] - - The `TypeOf...Is` operator is the best choice for testing an object's type, because it is much faster than an equivalent string comparison using `TypeName`. The following code fragment uses `TypeOf...Is` within an `If...Then...Else` statement: - - [!code-vb[VbVbalrOOP#93](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#93)] - - A word of caution is due here. The `TypeOf...Is` operator returns `True` if an object is of a specific type, or is derived from a specific type. Almost everything you do with Visual Basic involves objects, which include some elements not normally thought of as objects, such as strings and integers. These objects are derived from and inherit methods from . When passed an `Integer` and evaluated with `Object`, the `TypeOf...Is` operator returns `True`. The following example reports that the parameter `InParam` is both an `Object` and an `Integer`: - - [!code-vb[VbVbalrOOP#94](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#94)] - - The following example uses both `TypeOf...Is` and `TypeName` to determine the type of object passed to it in the `Ctrl` argument. The `TestObject` procedure calls `ShowType` with three different kinds of controls. - -#### To run the example - -1. Create a new Windows Application project and add a control, a control, and a control to the form. - -2. From the button on your form, call the `TestObject` procedure. - -3. Add the following code to your form: - - [!code-vb[VbVbalrOOP#95](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#95)] - +Generic object variables (that is, variables you declare as `Object`) can hold objects from any class. When using variables of type `Object`, you may need to take different actions based on the class of the object; for example, some objects might not support a particular property or method. Visual Basic provides two means of determining which type of object is stored in an object variable: the `TypeName` function and the `TypeOf...Is` operator. + +## TypeName and TypeOf…Is + + The `TypeName` function returns a string and is the best choice when you need to store or display the class name of an object, as shown in the following code fragment: + + [!code-vb[VbVbalrOOP#92](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#92)] + + The `TypeOf...Is` operator is the best choice for testing an object's type, because it is much faster than an equivalent string comparison using `TypeName`. The following code fragment uses `TypeOf...Is` within an `If...Then...Else` statement: + + [!code-vb[VbVbalrOOP#93](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#93)] + + A word of caution is due here. The `TypeOf...Is` operator returns `True` if an object is of a specific type, or is derived from a specific type. Almost everything you do with Visual Basic involves objects, which include some elements not normally thought of as objects, such as strings and integers. These objects are derived from and inherit methods from . When passed an `Integer` and evaluated with `Object`, the `TypeOf...Is` operator returns `True`. The following example reports that the parameter `InParam` is both an `Object` and an `Integer`: + + [!code-vb[VbVbalrOOP#94](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#94)] + + The following example uses both `TypeOf...Is` and `TypeName` to determine the type of object passed to it in the `Ctrl` argument. The `TestObject` procedure calls `ShowType` with three different kinds of controls. + +#### To run the example + +1. Create a new Windows Application project and add a control, a control, and a control to the form. + +2. From the button on your form, call the `TestObject` procedure. + +3. Add the following code to your form: + + [!code-vb[VbVbalrOOP#95](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#95)] + ## See also -- +- - [Calling a Property or Method Using a String Name](calling-a-property-or-method-using-a-string-name.md) - [Object Data Type](../../../language-reference/data-types/object-data-type.md) - [If...Then...Else Statement](../../../language-reference/statements/if-then-else-statement.md) diff --git a/docs/visual-basic/programming-guide/language-features/early-late-binding/index.md b/docs/visual-basic/programming-guide/language-features/early-late-binding/index.md index 468e09904a40a..5820794f21edb 100644 --- a/docs/visual-basic/programming-guide/language-features/early-late-binding/index.md +++ b/docs/visual-basic/programming-guide/language-features/early-late-binding/index.md @@ -2,7 +2,7 @@ description: "Learn more about: Early and Late Binding (Visual Basic)" title: "Early and Late Binding" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "early binding [Visual Basic]" - "objects [Visual Basic], late-bound" - "objects [Visual Basic], early-bound" @@ -17,25 +17,25 @@ ms.assetid: d6ff7f1e-b94f-4205-ab8d-5cfa91758724 --- # Early and Late Binding (Visual Basic) -The Visual Basic compiler performs a process called `binding` when an object is assigned to an object variable. An object is *early bound* when it is assigned to a variable declared to be of a specific object type. Early bound objects allow the compiler to allocate memory and perform other optimizations before an application executes. For example, the following code fragment declares a variable to be of type : - - [!code-vb[VbVbalrOOP#90](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#90)] - - Because is a specific object type, the instance assigned to `FS` is early bound. - - By contrast, an object is *late bound* when it is assigned to a variable declared to be of type `Object`. Objects of this type can hold references to any object, but lack many of the advantages of early-bound objects. For example, the following code fragment declares an object variable to hold an object returned by the `CreateObject` function: - - [!code-vb[VbVbalrOOP#91](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/LateBinding.vb#91)] - -## Advantages of Early Binding - - You should use early-bound objects whenever possible, because they allow the compiler to make important optimizations that yield more efficient applications. Early-bound objects are significantly faster than late-bound objects and make your code easier to read and maintain by stating exactly what kind of objects are being used. Another advantage to early binding is that it enables useful features such as automatic code completion and Dynamic Help because the Visual Studio integrated development environment (IDE) can determine exactly what type of object you are working with as you edit the code. Early binding reduces the number and severity of run-time errors because it allows the compiler to report errors when a program is compiled. - +The Visual Basic compiler performs a process called `binding` when an object is assigned to an object variable. An object is *early bound* when it is assigned to a variable declared to be of a specific object type. Early bound objects allow the compiler to allocate memory and perform other optimizations before an application executes. For example, the following code fragment declares a variable to be of type : + + [!code-vb[VbVbalrOOP#90](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/OOP.vb#90)] + + Because is a specific object type, the instance assigned to `FS` is early bound. + + By contrast, an object is *late bound* when it is assigned to a variable declared to be of type `Object`. Objects of this type can hold references to any object, but lack many of the advantages of early-bound objects. For example, the following code fragment declares an object variable to hold an object returned by the `CreateObject` function: + + [!code-vb[VbVbalrOOP#91](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOOP/VB/LateBinding.vb#91)] + +## Advantages of Early Binding + + You should use early-bound objects whenever possible, because they allow the compiler to make important optimizations that yield more efficient applications. Early-bound objects are significantly faster than late-bound objects and make your code easier to read and maintain by stating exactly what kind of objects are being used. Another advantage to early binding is that it enables useful features such as automatic code completion and Dynamic Help because the Visual Studio integrated development environment (IDE) can determine exactly what type of object you are working with as you edit the code. Early binding reduces the number and severity of run-time errors because it allows the compiler to report errors when a program is compiled. + > [!NOTE] -> Late binding can only be used to access type members that are declared as `Public`. Accessing members declared as `Friend` or `Protected Friend` results in a run-time error. - +> Late binding can only be used to access type members that are declared as `Public`. Accessing members declared as `Friend` or `Protected Friend` results in a run-time error. + ## See also -- +- - [Object Lifetime: How Objects Are Created and Destroyed](../objects-and-classes/object-lifetime-how-objects-are-created-and-destroyed.md) - [Object Data Type](../../../language-reference/data-types/object-data-type.md) diff --git a/docs/visual-basic/programming-guide/language-features/early-late-binding/walkthrough-creating-and-using-dynamic-objects.md b/docs/visual-basic/programming-guide/language-features/early-late-binding/walkthrough-creating-and-using-dynamic-objects.md index 459454ff32fe7..fbc449d9542f6 100644 --- a/docs/visual-basic/programming-guide/language-features/early-late-binding/walkthrough-creating-and-using-dynamic-objects.md +++ b/docs/visual-basic/programming-guide/language-features/early-late-binding/walkthrough-creating-and-using-dynamic-objects.md @@ -76,11 +76,11 @@ The first walkthrough defines a custom dynamic object that searches the contents [!code-vb[VbDynamicWalkthrough#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/vbdynamicwalkthrough/vb/readonlyfile.vb#5)] -1. After the `GetPropertyValue` method, add the following code to override the method of the class. The method is called when a member of a dynamic class is requested and no arguments are specified. The `binder` argument contains information about the referenced member, and the `result` argument references the result returned for the specified member. The method returns a Boolean value that returns `true` if the requested member exists; otherwise it returns `false`. +1. After the `GetPropertyValue` method, add the following code to override the method of the class. The method is called when a member of a dynamic class is requested and no arguments are specified. The `binder` argument contains information about the referenced member, and the `result` argument references the result returned for the specified member. The method returns a Boolean value that returns `true` if the requested member exists; otherwise it returns `false`. [!code-vb[VbDynamicWalkthrough#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/vbdynamicwalkthrough/vb/readonlyfile.vb#6)] -1. After the `TryGetMember` method, add the following code to override the method of the class. The method is called when a member of a dynamic class is requested with arguments. The `binder` argument contains information about the referenced member, and the `result` argument references the result returned for the specified member. The `args` argument contains an array of the arguments that are passed to the member. The method returns a Boolean value that returns `true` if the requested member exists; otherwise it returns `false`. +1. After the `TryGetMember` method, add the following code to override the method of the class. The method is called when a member of a dynamic class is requested with arguments. The `binder` argument contains information about the referenced member, and the `result` argument references the result returned for the specified member. The `args` argument contains an array of the arguments that are passed to the member. The method returns a Boolean value that returns `true` if the requested member exists; otherwise it returns `false`. The custom version of the `TryInvokeMember` method expects the first argument to be a value from the `StringSearchOption` enum that you defined in a previous step. The `TryInvokeMember` method expects the second argument to be a Boolean value. If one or both arguments are valid values, they are passed to the `GetPropertyValue` method to retrieve the results. diff --git a/docs/visual-basic/programming-guide/language-features/events/how-to-declare-custom-events-to-avoid-blocking.md b/docs/visual-basic/programming-guide/language-features/events/how-to-declare-custom-events-to-avoid-blocking.md index 625a07388a944..9c6bbf62071c7 100644 --- a/docs/visual-basic/programming-guide/language-features/events/how-to-declare-custom-events-to-avoid-blocking.md +++ b/docs/visual-basic/programming-guide/language-features/events/how-to-declare-custom-events-to-avoid-blocking.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Declare Custom Events To Avoid Blocking (Visual Basic)" title: "How to: Declare Custom Events To Avoid Blocking" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "declaring events [Visual Basic], custom" - "events [Visual Basic], custom" - "custom events [Visual Basic]" @@ -10,23 +10,23 @@ ms.assetid: 998b6a90-67c5-4d2c-8b11-366d3e355505 --- # How to: Declare Custom Events To Avoid Blocking (Visual Basic) -There are several circumstances when it is important that one event handler not block subsequent event handlers. Custom events allow the event to call its event handlers asynchronously. - - By default, the backing-store field for an event declaration is a multicast delegate that serially combines all the event handlers. This means that if one handler takes a long time to complete, it blocks the other handlers until it completes. (Well-behaved event handlers should never perform lengthy or potentially blocking operations.) - - Instead of using the default implementation of events that Visual Basic provides, you can use a custom event to execute the event handlers asynchronously. - -## Example - - In this example, the `AddHandler` accessor adds the delegate for each handler of the `Click` event to an stored in the `EventHandlerList` field. - - When code raises the `Click` event, the `RaiseEvent` accessor invokes all the event handler delegates asynchronously using the method. That method invokes each handler on a worker thread and returns immediately, so handlers cannot block one another. - - [!code-vb[VbVbalrEvents#27](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrEvents/VB/Class1.vb#27)] - +There are several circumstances when it is important that one event handler not block subsequent event handlers. Custom events allow the event to call its event handlers asynchronously. + + By default, the backing-store field for an event declaration is a multicast delegate that serially combines all the event handlers. This means that if one handler takes a long time to complete, it blocks the other handlers until it completes. (Well-behaved event handlers should never perform lengthy or potentially blocking operations.) + + Instead of using the default implementation of events that Visual Basic provides, you can use a custom event to execute the event handlers asynchronously. + +## Example + + In this example, the `AddHandler` accessor adds the delegate for each handler of the `Click` event to an stored in the `EventHandlerList` field. + + When code raises the `Click` event, the `RaiseEvent` accessor invokes all the event handler delegates asynchronously using the method. That method invokes each handler on a worker thread and returns immediately, so handlers cannot block one another. + + [!code-vb[VbVbalrEvents#27](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrEvents/VB/Class1.vb#27)] + ## See also - -- +- - [Events](index.md) - [How to: Declare Custom Events To Conserve Memory](how-to-declare-custom-events-to-conserve-memory.md) diff --git a/docs/visual-basic/programming-guide/language-features/events/walkthrough-declaring-and-raising-events.md b/docs/visual-basic/programming-guide/language-features/events/walkthrough-declaring-and-raising-events.md index 75b4bac5ed242..572e8462d0868 100644 --- a/docs/visual-basic/programming-guide/language-features/events/walkthrough-declaring-and-raising-events.md +++ b/docs/visual-basic/programming-guide/language-features/events/walkthrough-declaring-and-raising-events.md @@ -2,7 +2,7 @@ description: "Learn more about: Walkthrough: Declaring and Raising Events (Visual Basic)" title: "Declaring and Raising Events" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "declarations [Visual Basic], events" - "events [Visual Basic], walkthroughs" - "declaring events [Visual Basic], walkthroughs" @@ -13,66 +13,66 @@ ms.assetid: 8ffb3be8-097d-4d3c-b71e-04555ebda2a2 --- # Walkthrough: Declaring and Raising Events (Visual Basic) -This walkthrough demonstrates how to declare and raise events for a class named `Widget`. After you complete the steps, you might want to read the companion topic, [Walkthrough: Handling Events](walkthrough-handling-events.md), which shows how to use events from `Widget` objects to provide status information in an application. - -## The Widget Class - - Assume for the moment that you have a `Widget` class. Your `Widget` class has a method that can take a long time to execute, and you want your application to be able to put up some kind of completion indicator. - - Of course, you could make the `Widget` object show a percent-complete dialog box, but then you would be stuck with that dialog box in every project in which you used the `Widget` class. A good principle of object design is to let the application that uses an object handle the user interface—unless the whole purpose of the object is to manage a form or dialog box. - - The purpose of `Widget` is to perform other tasks, so it is better to add a `PercentDone` event and let the procedure that calls `Widget`'s methods handle that event and display status updates. The `PercentDone` event can also provide a mechanism for canceling the task. - -#### To build the code example for this topic - -1. Open a new Visual Basic Windows Application project and create a form named `Form1`. - -2. Add two buttons and a label to `Form1`. - -3. Name the objects as shown in the following table. - - |Object|Property|Setting| - |------------|--------------|-------------| - |`Button1`|`Text`|Start Task| - |`Button2`|`Text`|Cancel| - |`Label`|`(Name)`, `Text`|lblPercentDone, 0| - -4. On the **Project** menu, choose **Add Class** to add a class named `Widget.vb` to the project. - -#### To declare an event for the Widget class - -- Use the `Event` keyword to declare an event in the `Widget` class. Note that an event can have `ByVal` and `ByRef` arguments, as `Widget`'s `PercentDone` event demonstrates: - - [!code-vb[VbVbcnWalkthroughDeclaringAndRaisingEvents#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnWalkthroughDeclaringAndRaisingEvents/VB/Widget.vb#1)] - - When the calling object receives a `PercentDone` event, the `Percent` argument contains the percentage of the task that is complete. The `Cancel` argument can be set to `True` to cancel the method that raised the event. - +This walkthrough demonstrates how to declare and raise events for a class named `Widget`. After you complete the steps, you might want to read the companion topic, [Walkthrough: Handling Events](walkthrough-handling-events.md), which shows how to use events from `Widget` objects to provide status information in an application. + +## The Widget Class + + Assume for the moment that you have a `Widget` class. Your `Widget` class has a method that can take a long time to execute, and you want your application to be able to put up some kind of completion indicator. + + Of course, you could make the `Widget` object show a percent-complete dialog box, but then you would be stuck with that dialog box in every project in which you used the `Widget` class. A good principle of object design is to let the application that uses an object handle the user interface—unless the whole purpose of the object is to manage a form or dialog box. + + The purpose of `Widget` is to perform other tasks, so it is better to add a `PercentDone` event and let the procedure that calls `Widget`'s methods handle that event and display status updates. The `PercentDone` event can also provide a mechanism for canceling the task. + +#### To build the code example for this topic + +1. Open a new Visual Basic Windows Application project and create a form named `Form1`. + +2. Add two buttons and a label to `Form1`. + +3. Name the objects as shown in the following table. + + |Object|Property|Setting| + |------------|--------------|-------------| + |`Button1`|`Text`|Start Task| + |`Button2`|`Text`|Cancel| + |`Label`|`(Name)`, `Text`|lblPercentDone, 0| + +4. On the **Project** menu, choose **Add Class** to add a class named `Widget.vb` to the project. + +#### To declare an event for the Widget class + +- Use the `Event` keyword to declare an event in the `Widget` class. Note that an event can have `ByVal` and `ByRef` arguments, as `Widget`'s `PercentDone` event demonstrates: + + [!code-vb[VbVbcnWalkthroughDeclaringAndRaisingEvents#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnWalkthroughDeclaringAndRaisingEvents/VB/Widget.vb#1)] + + When the calling object receives a `PercentDone` event, the `Percent` argument contains the percentage of the task that is complete. The `Cancel` argument can be set to `True` to cancel the method that raised the event. + > [!NOTE] -> You can declare event arguments just as you do arguments of procedures, with the following exceptions: Events cannot have `Optional` or `ParamArray` arguments, and events do not have return values. - - The `PercentDone` event is raised by the `LongTask` method of the `Widget` class. `LongTask` takes two arguments: the length of time the method pretends to be doing work, and the minimum time interval before `LongTask` pauses to raise the `PercentDone` event. - -#### To raise the PercentDone event - -1. To simplify access to the `Timer` property used by this class, add an `Imports` statement to the top of the declarations section of your class module, above the `Class Widget` statement. - - [!code-vb[VbVbcnWalkthroughDeclaringAndRaisingEvents#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnWalkthroughDeclaringAndRaisingEvents/VB/Widget.vb#2)] - -2. Add the following code to the `Widget` class: - - [!code-vb[VbVbcnWalkthroughDeclaringAndRaisingEvents#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnWalkthroughDeclaringAndRaisingEvents/VB/Widget.vb#3)] - - When your application calls the `LongTask` method, the `Widget` class raises the `PercentDone` event every `MinimumInterval` seconds. When the event returns, `LongTask` checks to see if the `Cancel` argument was set to `True`. - - A few disclaimers are necessary here. For simplicity, the `LongTask` procedure assumes you know in advance how long the task will take. This is almost never the case. Dividing tasks into chunks of even size can be difficult, and often what matters most to users is simply the amount of time that passes before they get an indication that something is happening. - - You may have spotted another flaw in this sample. The `Timer` property returns the number of seconds that have passed since midnight; therefore, the application gets stuck if it is started just before midnight. A more careful approach to measuring time would take boundary conditions such as this into consideration, or avoid them altogether, using properties such as `Now`. - - Now that the `Widget` class can raise events, you can move to the next walkthrough. [Walkthrough: Handling Events](walkthrough-handling-events.md) demonstrates how to use `WithEvents` to associate an event handler with the `PercentDone` event. - +> You can declare event arguments just as you do arguments of procedures, with the following exceptions: Events cannot have `Optional` or `ParamArray` arguments, and events do not have return values. + + The `PercentDone` event is raised by the `LongTask` method of the `Widget` class. `LongTask` takes two arguments: the length of time the method pretends to be doing work, and the minimum time interval before `LongTask` pauses to raise the `PercentDone` event. + +#### To raise the PercentDone event + +1. To simplify access to the `Timer` property used by this class, add an `Imports` statement to the top of the declarations section of your class module, above the `Class Widget` statement. + + [!code-vb[VbVbcnWalkthroughDeclaringAndRaisingEvents#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnWalkthroughDeclaringAndRaisingEvents/VB/Widget.vb#2)] + +2. Add the following code to the `Widget` class: + + [!code-vb[VbVbcnWalkthroughDeclaringAndRaisingEvents#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnWalkthroughDeclaringAndRaisingEvents/VB/Widget.vb#3)] + + When your application calls the `LongTask` method, the `Widget` class raises the `PercentDone` event every `MinimumInterval` seconds. When the event returns, `LongTask` checks to see if the `Cancel` argument was set to `True`. + + A few disclaimers are necessary here. For simplicity, the `LongTask` procedure assumes you know in advance how long the task will take. This is almost never the case. Dividing tasks into chunks of even size can be difficult, and often what matters most to users is simply the amount of time that passes before they get an indication that something is happening. + + You may have spotted another flaw in this sample. The `Timer` property returns the number of seconds that have passed since midnight; therefore, the application gets stuck if it is started just before midnight. A more careful approach to measuring time would take boundary conditions such as this into consideration, or avoid them altogether, using properties such as `Now`. + + Now that the `Widget` class can raise events, you can move to the next walkthrough. [Walkthrough: Handling Events](walkthrough-handling-events.md) demonstrates how to use `WithEvents` to associate an event handler with the `PercentDone` event. + ## See also -- -- +- +- - [Walkthrough: Handling Events](walkthrough-handling-events.md) - [Events](index.md) diff --git a/docs/visual-basic/programming-guide/language-features/linq/how-to-call-a-stored-procedure-by-using-linq.md b/docs/visual-basic/programming-guide/language-features/linq/how-to-call-a-stored-procedure-by-using-linq.md index 970991a13f08e..f2cdbf1083031 100644 --- a/docs/visual-basic/programming-guide/language-features/linq/how-to-call-a-stored-procedure-by-using-linq.md +++ b/docs/visual-basic/programming-guide/language-features/linq/how-to-call-a-stored-procedure-by-using-linq.md @@ -55,7 +55,7 @@ The examples in this article use the Northwind sample database. To obtain the da 3. When you added stored procedures to the O/R Designer, the designer added a object for your project. This object contains the code that you must have to access those procedures. The object for the project is named based on the name of the .dbml file. For this project, the object is named `northwindDataContext`. - You can create an instance of the in your code and call the stored procedure methods specified by the O/R Designer. To bind to the object, you may have to force the query to execute immediately by calling the method on the results of the stored procedure. + You can create an instance of the in your code and call the stored procedure methods specified by the O/R Designer. To bind to the object, you may have to force the query to execute immediately by calling the method on the results of the stored procedure. Add the following code to the `Load` event to call either of the stored procedures exposed as methods for your data context. diff --git a/docs/visual-basic/programming-guide/language-features/linq/how-to-modify-data-in-a-database-by-using-linq.md b/docs/visual-basic/programming-guide/language-features/linq/how-to-modify-data-in-a-database-by-using-linq.md index 7ddf83db4da9a..ff0c2458fee7f 100644 --- a/docs/visual-basic/programming-guide/language-features/linq/how-to-modify-data-in-a-database-by-using-linq.md +++ b/docs/visual-basic/programming-guide/language-features/linq/how-to-modify-data-in-a-database-by-using-linq.md @@ -58,7 +58,7 @@ The examples in this article use the Northwind sample database. To obtain the da 2. When you added tables to the O/R Designer, the designer added a object to your project. This object contains code that you can use to access the Customers table. It also contains code that defines a local Customer object and a Customers collection for the table. The object for your project is named based on the name of your .dbml file. For this project, the object is named `northwindDataContext`. - You can create an instance of the object in your code and query and modify the Customers collection specified by the O/R Designer. Changes that you make to the Customers collection are not reflected in the database until you submit them by calling the method of the object. + You can create an instance of the object in your code and query and modify the Customers collection specified by the O/R Designer. Changes that you make to the Customers collection are not reflected in the database until you submit them by calling the method of the object. Double-click the Windows Form, Form1, to add code to the event to query the Customers table that is exposed as a property of your . Add the following code: diff --git a/docs/visual-basic/programming-guide/language-features/linq/introduction-to-linq.md b/docs/visual-basic/programming-guide/language-features/linq/introduction-to-linq.md index a38d0e8fe1a8b..8614f89227420 100644 --- a/docs/visual-basic/programming-guide/language-features/linq/introduction-to-linq.md +++ b/docs/visual-basic/programming-guide/language-features/linq/introduction-to-linq.md @@ -2,7 +2,7 @@ description: "Learn more about: Introduction to LINQ in Visual Basic" title: "Intro to LINQ" ms.date: 08/28/2018 -helpviewer_keywords: +helpviewer_keywords: - "queries [LINQ in Visual Basic], about LINQ in Visual Basic queries" - "query execution [LINQ in Visual Basic]" - "range variables [Visual Basic]" @@ -16,60 +16,60 @@ ms.assetid: 3047d86e-0d49-40e2-928b-dc02e46c7984 --- # Introduction to LINQ in Visual Basic -Language-Integrated Query (LINQ) adds query capabilities to Visual Basic and provides simple and powerful capabilities when you work with all kinds of data. Rather than sending a query to a database to be processed, or working with different query syntax for each type of data that you are searching, LINQ introduces queries as part of the Visual Basic language. It uses a unified syntax regardless of the type of data. - - LINQ enables you to query data from a SQL Server database, XML, in-memory arrays and collections, ADO.NET datasets, or any other remote or local data source that supports LINQ. You can do all this with common Visual Basic language elements. Because your queries are written in the Visual Basic language, your query results are returned as strongly typed objects. These objects support IntelliSense, which enables you to write code faster and catch errors in your queries at compile time instead of at run time. LINQ queries can be used as the source of additional queries to refine results. They can also be bound to controls so that users can easily view and modify your query results. - - For example, the following code example shows a LINQ query that returns a list of customers from a collection and groups them based on their location. - - [!code-vb[VbVbalrIntroToLINQ#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#1)] - -## Running the examples - - To run the examples in the introduction and in the [Structure of a LINQ Query](#structure-of-a-linq-query) section, include the following code, which returns lists of customers and orders. - - [!code-vb[VbVbalrIntroToLINQ#31](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#31)] - -## LINQ providers - - A *LINQ provider* maps your Visual Basic LINQ queries to the data source being queried. When you write a LINQ query, the provider takes that query and translates it into commands that the data source will be able to execute. The provider also converts data from the source to the objects that make up your query result. Finally, it converts objects to data when you send updates to the data source. - - Visual Basic includes the following LINQ providers. - -|Provider|Description| -|---|---| -|LINQ to Objects|The LINQ to Objects provider enables you to query in-memory collections and arrays. If an object supports either the or interface, the LINQ to Objects provider enables you to query it.

You can enable the LINQ to Objects provider by importing the namespace, which is imported by default for all Visual Basic projects.

For more information about the LINQ to Objects provider, see [LINQ to Objects](../../concepts/linq/linq-to-objects.md).| -|LINQ to SQL|The LINQ to SQL provider enables you to query and modify data in a SQL Server database. This makes it easy to map the object model for an application to the tables and objects in a database.

Visual Basic makes it easier to work with LINQ to SQL by including the Object Relational Designer (O/R Designer). This designer is used to create an object model in an application that maps to objects in a database. The O/R Designer also provides functionality to map stored procedures and functions to the object, which manages communication with the database and stores state for optimistic concurrency checks.

For more information about the LINQ to SQL provider, see [LINQ to SQL](../../../../framework/data/adonet/sql/linq/index.md). For more information about the Object Relational Designer, see [LINQ to SQL Tools in Visual Studio](/visualstudio/data-tools/linq-to-sql-tools-in-visual-studio2).| -|LINQ to XML|The LINQ to XML provider enables you to query and modify XML. You can modify in-memory XML, or you can load XML from and save XML to a file.

Additionally, the LINQ to XML provider enables XML literals and XML axis properties that enable you to write XML directly in your Visual Basic code. For more information, see [XML](../xml/index.md).| -|LINQ to DataSet|The LINQ to DataSet provider enables you to query and update data in an ADO.NET dataset. You can add the power of LINQ to applications that use datasets in order to simplify and extend your capabilities for querying, aggregating, and updating the data in your dataset.

For more information, see [LINQ to DataSet](../../../../framework/data/adonet/linq-to-dataset.md).| - -## Structure of a LINQ query - - A LINQ query, often referred to as a *query expression*, consists of a combination of query clauses that identify the data sources and iteration variables for the query. A query expression can also include instructions for sorting, filtering, grouping, and joining, or calculations to apply to the source data. Query expression syntax resembles the syntax of SQL; therefore, you may find much of the syntax familiar. - - A query expression starts with a `From` clause. This clause identifies the source data for a query and the variables that are used to refer to each element of the source data individually. These variables are named *range variables* or *iteration variables*. The `From` clause is required for a query, except for `Aggregate` queries, where the `From` clause is optional. After the scope and source of the query are identified in the `From` or `Aggregate` clauses, you can include any combination of query clauses to refine the query. For details about query clauses, see Visual Basic LINQ Query Operators later in this topic. For example, the following query identifies a source collection of customer data as the `customers` variable, and an iteration variable named `cust`. - - [!code-vb[VbVbalrIntroToLINQ#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#2)] - - This example is a valid query by itself; however, the query becomes far more powerful when you add more query clauses to refine the result. For example, you can add a `Where` clause to filter the result by one or more values. Query expressions are a single line of code; you can just append additional query clauses to the end of the query. You can break up a query across multiple lines of text to improve readability by using the underscore (\_) line-continuation character. The following code example shows an example of a query that includes a `Where` clause. - - [!code-vb[VbVbalrIntroToLINQ#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#3)] - - Another powerful query clause is the `Select` clause, which enables you to return only selected fields from the data source. LINQ queries return enumerable collections of strongly typed objects. A query can return a collection of anonymous types or named types. You can use the `Select` clause to return only a single field from the data source. When you do this, the type of the collection returned is the type of that single field. You can also use the `Select` clause to return multiple fields from the data source. When you do this, the type of the collection returned is a new anonymous type. You can also match the fields returned by the query to the fields of a specified named type. The following code example shows a query expression that returns a collection of anonymous types that have members populated with data from the selected fields from the data source. - - [!code-vb[VbVbalrIntroToLINQ#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#4)] - - LINQ queries can also be used to combine multiple sources of data and return a single result. This can be done with one or more `From` clauses, or by using the `Join` or `Group Join` query clauses. The following code example shows a query expression that combines customer and order data and returns a collection of anonymous types containing customer and order data. - - [!code-vb[VbVbalrIntroToLINQ#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#5)] - - You can use the `Group Join` clause to create a hierarchical query result that contains a collection of customer objects. Each customer object has a property that contains a collection of all orders for that customer. The following code example shows a query expression that combines customer and order data as a hierarchical result and returns a collection of anonymous types. The query returns a type that includes a `CustomerOrders` property that contains a collection of order data for the customer. It also includes an `OrderTotal` property that contains the sum of the totals for all the orders for that customer. (This query is equivalent to a LEFT OUTER JOIN.) - - [!code-vb[VbVbalrIntroToLINQ#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#6)] - - There are several additional LINQ query operators that you can use to create powerful query expressions. The next section of this topic discusses the various query clauses that you can include in a query expression. For details about Visual Basic query clauses, see [Queries](../../../language-reference/queries/index.md). - -## Visual Basic LINQ query operators +Language-Integrated Query (LINQ) adds query capabilities to Visual Basic and provides simple and powerful capabilities when you work with all kinds of data. Rather than sending a query to a database to be processed, or working with different query syntax for each type of data that you are searching, LINQ introduces queries as part of the Visual Basic language. It uses a unified syntax regardless of the type of data. + + LINQ enables you to query data from a SQL Server database, XML, in-memory arrays and collections, ADO.NET datasets, or any other remote or local data source that supports LINQ. You can do all this with common Visual Basic language elements. Because your queries are written in the Visual Basic language, your query results are returned as strongly typed objects. These objects support IntelliSense, which enables you to write code faster and catch errors in your queries at compile time instead of at run time. LINQ queries can be used as the source of additional queries to refine results. They can also be bound to controls so that users can easily view and modify your query results. + + For example, the following code example shows a LINQ query that returns a list of customers from a collection and groups them based on their location. + + [!code-vb[VbVbalrIntroToLINQ#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#1)] + +## Running the examples + + To run the examples in the introduction and in the [Structure of a LINQ Query](#structure-of-a-linq-query) section, include the following code, which returns lists of customers and orders. + + [!code-vb[VbVbalrIntroToLINQ#31](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#31)] + +## LINQ providers + + A *LINQ provider* maps your Visual Basic LINQ queries to the data source being queried. When you write a LINQ query, the provider takes that query and translates it into commands that the data source will be able to execute. The provider also converts data from the source to the objects that make up your query result. Finally, it converts objects to data when you send updates to the data source. + + Visual Basic includes the following LINQ providers. + +|Provider|Description| +|---|---| +|LINQ to Objects|The LINQ to Objects provider enables you to query in-memory collections and arrays. If an object supports either the or interface, the LINQ to Objects provider enables you to query it.

You can enable the LINQ to Objects provider by importing the namespace, which is imported by default for all Visual Basic projects.

For more information about the LINQ to Objects provider, see [LINQ to Objects](../../concepts/linq/linq-to-objects.md).| +|LINQ to SQL|The LINQ to SQL provider enables you to query and modify data in a SQL Server database. This makes it easy to map the object model for an application to the tables and objects in a database.

Visual Basic makes it easier to work with LINQ to SQL by including the Object Relational Designer (O/R Designer). This designer is used to create an object model in an application that maps to objects in a database. The O/R Designer also provides functionality to map stored procedures and functions to the object, which manages communication with the database and stores state for optimistic concurrency checks.

For more information about the LINQ to SQL provider, see [LINQ to SQL](../../../../framework/data/adonet/sql/linq/index.md). For more information about the Object Relational Designer, see [LINQ to SQL Tools in Visual Studio](/visualstudio/data-tools/linq-to-sql-tools-in-visual-studio2).| +|LINQ to XML|The LINQ to XML provider enables you to query and modify XML. You can modify in-memory XML, or you can load XML from and save XML to a file.

Additionally, the LINQ to XML provider enables XML literals and XML axis properties that enable you to write XML directly in your Visual Basic code. For more information, see [XML](../xml/index.md).| +|LINQ to DataSet|The LINQ to DataSet provider enables you to query and update data in an ADO.NET dataset. You can add the power of LINQ to applications that use datasets in order to simplify and extend your capabilities for querying, aggregating, and updating the data in your dataset.

For more information, see [LINQ to DataSet](../../../../framework/data/adonet/linq-to-dataset.md).| + +## Structure of a LINQ query + + A LINQ query, often referred to as a *query expression*, consists of a combination of query clauses that identify the data sources and iteration variables for the query. A query expression can also include instructions for sorting, filtering, grouping, and joining, or calculations to apply to the source data. Query expression syntax resembles the syntax of SQL; therefore, you may find much of the syntax familiar. + + A query expression starts with a `From` clause. This clause identifies the source data for a query and the variables that are used to refer to each element of the source data individually. These variables are named *range variables* or *iteration variables*. The `From` clause is required for a query, except for `Aggregate` queries, where the `From` clause is optional. After the scope and source of the query are identified in the `From` or `Aggregate` clauses, you can include any combination of query clauses to refine the query. For details about query clauses, see Visual Basic LINQ Query Operators later in this topic. For example, the following query identifies a source collection of customer data as the `customers` variable, and an iteration variable named `cust`. + + [!code-vb[VbVbalrIntroToLINQ#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#2)] + + This example is a valid query by itself; however, the query becomes far more powerful when you add more query clauses to refine the result. For example, you can add a `Where` clause to filter the result by one or more values. Query expressions are a single line of code; you can just append additional query clauses to the end of the query. You can break up a query across multiple lines of text to improve readability by using the underscore (\_) line-continuation character. The following code example shows an example of a query that includes a `Where` clause. + + [!code-vb[VbVbalrIntroToLINQ#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#3)] + + Another powerful query clause is the `Select` clause, which enables you to return only selected fields from the data source. LINQ queries return enumerable collections of strongly typed objects. A query can return a collection of anonymous types or named types. You can use the `Select` clause to return only a single field from the data source. When you do this, the type of the collection returned is the type of that single field. You can also use the `Select` clause to return multiple fields from the data source. When you do this, the type of the collection returned is a new anonymous type. You can also match the fields returned by the query to the fields of a specified named type. The following code example shows a query expression that returns a collection of anonymous types that have members populated with data from the selected fields from the data source. + + [!code-vb[VbVbalrIntroToLINQ#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#4)] + + LINQ queries can also be used to combine multiple sources of data and return a single result. This can be done with one or more `From` clauses, or by using the `Join` or `Group Join` query clauses. The following code example shows a query expression that combines customer and order data and returns a collection of anonymous types containing customer and order data. + + [!code-vb[VbVbalrIntroToLINQ#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#5)] + + You can use the `Group Join` clause to create a hierarchical query result that contains a collection of customer objects. Each customer object has a property that contains a collection of all orders for that customer. The following code example shows a query expression that combines customer and order data as a hierarchical result and returns a collection of anonymous types. The query returns a type that includes a `CustomerOrders` property that contains a collection of order data for the customer. It also includes an `OrderTotal` property that contains the sum of the totals for all the orders for that customer. (This query is equivalent to a LEFT OUTER JOIN.) + + [!code-vb[VbVbalrIntroToLINQ#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/class2.vb#6)] + + There are several additional LINQ query operators that you can use to create powerful query expressions. The next section of this topic discusses the various query clauses that you can include in a query expression. For details about Visual Basic query clauses, see [Queries](../../../language-reference/queries/index.md). + +## Visual Basic LINQ query operators The classes in the namespace and the other namespaces that support LINQ queries include methods that you can call to create and refine queries based on the needs of your application. Visual Basic includes keywords for the following common query clauses. For details about Visual Basic query clauses, see [Queries](../../../language-reference/queries/index.md). @@ -162,93 +162,93 @@ Optional. A [`Take` clause](../../../language-reference/queries/take-clause.md) Optional. A [`Take While` clause](../../../language-reference/queries/take-while-clause.md) includes elements in a collection as long as a specified condition is `true` and bypasses the remaining elements. For example: [!code-vb[VbVbalrIntroToLINQ#21](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/Class1.vb#21)] - -## Use additional LINQ query features - -You can use additional LINQ query features by calling members of the enumerable and queryable types provided by LINQ. You can use these additional capabilities by calling a particular query operator on the result of a query expression. For example, the following example uses the method to combine the results of two queries into one query result. It uses the method to return the query result as a generic list. - - [!code-vb[VbVbalrIntroToLINQ#22](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/Class1.vb#22)] - - For details about additional LINQ capabilities, see [Standard Query Operators Overview](../../concepts/linq/standard-query-operators-overview.md). - -## Connect to a database by using LINQ to SQL - - In Visual Basic, you identify the SQL Server database objects, such as tables, views, and stored procedures, that you want to access by using a LINQ to SQL file. A LINQ to SQL file has an extension of .dbml. - - When you have a valid connection to a SQL Server database, you can add a **LINQ to SQL Classes** item template to your project. This will display the Object Relational Designer (O/R designer). The O/R Designer enables you to drag the items that you want to access in your code from the **Server Explorer**/**Database Explorer** onto the designer surface. The LINQ to SQL file adds a object to your project. This object includes properties and collections for the tables and views that you want access to, and methods for the stored procedures that you want to call. After you have saved your changes to the LINQ to SQL (.dbml) file, you can access these objects in your code by referencing the object that is defined by the O/R Designer. The object for your project is named based on the name of your LINQ to SQL file. For example, a LINQ to SQL file that is named Northwind.dbml will create a object named `NorthwindDataContext`. - - For examples with step-by-step instructions, see [How to: Query a Database](how-to-query-a-database-by-using-linq.md) and [How to: Call a Stored Procedure](how-to-call-a-stored-procedure-by-using-linq.md). - -## Visual Basic features that support LINQ - - Visual Basic includes other notable features that make the use of LINQ simple and reduce the amount of code that you must write to perform LINQ queries. These include the following: - -- **Anonymous types**, which enable you to create a new type based on a query result. - -- **Implicitly typed variables**, which enable you to defer specifying a type and let the compiler infer the type based on the query result. - -- **Extension methods**, which enable you to extend an existing type with your own methods without modifying the type itself. - - For details, see [Visual Basic Features That Support LINQ](../../concepts/linq/features-that-support-linq.md). - + +## Use additional LINQ query features + +You can use additional LINQ query features by calling members of the enumerable and queryable types provided by LINQ. You can use these additional capabilities by calling a particular query operator on the result of a query expression. For example, the following example uses the method to combine the results of two queries into one query result. It uses the method to return the query result as a generic list. + + [!code-vb[VbVbalrIntroToLINQ#22](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrIntroToLINQ/VB/Class1.vb#22)] + + For details about additional LINQ capabilities, see [Standard Query Operators Overview](../../concepts/linq/standard-query-operators-overview.md). + +## Connect to a database by using LINQ to SQL + + In Visual Basic, you identify the SQL Server database objects, such as tables, views, and stored procedures, that you want to access by using a LINQ to SQL file. A LINQ to SQL file has an extension of .dbml. + + When you have a valid connection to a SQL Server database, you can add a **LINQ to SQL Classes** item template to your project. This will display the Object Relational Designer (O/R designer). The O/R Designer enables you to drag the items that you want to access in your code from the **Server Explorer**/**Database Explorer** onto the designer surface. The LINQ to SQL file adds a object to your project. This object includes properties and collections for the tables and views that you want access to, and methods for the stored procedures that you want to call. After you have saved your changes to the LINQ to SQL (.dbml) file, you can access these objects in your code by referencing the object that is defined by the O/R Designer. The object for your project is named based on the name of your LINQ to SQL file. For example, a LINQ to SQL file that is named Northwind.dbml will create a object named `NorthwindDataContext`. + + For examples with step-by-step instructions, see [How to: Query a Database](how-to-query-a-database-by-using-linq.md) and [How to: Call a Stored Procedure](how-to-call-a-stored-procedure-by-using-linq.md). + +## Visual Basic features that support LINQ + + Visual Basic includes other notable features that make the use of LINQ simple and reduce the amount of code that you must write to perform LINQ queries. These include the following: + +- **Anonymous types**, which enable you to create a new type based on a query result. + +- **Implicitly typed variables**, which enable you to defer specifying a type and let the compiler infer the type based on the query result. + +- **Extension methods**, which enable you to extend an existing type with your own methods without modifying the type itself. + + For details, see [Visual Basic Features That Support LINQ](../../concepts/linq/features-that-support-linq.md). + ## Deferred and immediate query execution - Query execution is separate from creating a query. After a query is created, its execution is triggered by a separate mechanism. A query can be executed as soon as it is defined (*immediate execution*), or the definition can be stored and the query can be executed later (*deferred execution*). - - By default, when you create a query, the query itself does not execute immediately. Instead, the query definition is stored in the variable that is used to reference the query result. When the query result variable is accessed later in code, such as in a `For…Next` loop, the query is executed. This process is referred to as *deferred execution*. - - Queries can also be executed when they are defined, which is referred to as *immediate execution*. You can trigger immediate execution by applying a method that requires access to individual elements of the query result. This can be the result of including an aggregate function, such as `Count`, `Sum`, `Average`, `Min`, or `Max`. For more information about aggregate functions, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md). - - Using the `ToList` or `ToArray` methods will also force immediate execution. This can be useful when you want to execute the query immediately and cache the results. For more information about these methods, see [Converting Data Types](../../concepts/linq/converting-data-types.md). - - For more information about query execution, see [Writing Your First LINQ Query](../../concepts/linq/writing-your-first-linq-query.md). - -## XML in Visual Basic - - The XML features in Visual Basic include XML literals and XML axis properties, which enable you easily to create, access, query, and modify XML in your code. XML literals enable you to write XML directly in your code. The Visual Basic compiler treats the XML as a first-class data object. - - The following code example shows how to create an XML element, access its sub-elements and attributes, and query the contents of the element by using LINQ. - - [!code-vb[VbXmlSamples#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples3.vb#8)] - - For more information, see [XML](../xml/index.md). - -## Related resources - -|Topic|Description| -|---|---| -|[XML](../xml/index.md)|Describes the XML features in Visual Basic that can be queried and that enable you to include XML as first-class data objects in your Visual Basic code.| -|[Queries](../../../language-reference/queries/index.md)|Provides reference information about the query clauses that are available in Visual Basic.| -|[LINQ (Language-Integrated Query)](../../concepts/linq/index.md)|Includes general information, programming guidance, and samples for LINQ.| -|[LINQ to SQL](../../../../framework/data/adonet/sql/linq/index.md)|Includes general information, programming guidance, and samples for LINQ to SQL.| -|[LINQ to Objects](../../concepts/linq/linq-to-objects.md)|Includes general information, programming guidance, and samples for LINQ to Objects.| -|[LINQ to ADO.NET (Portal Page)](../../concepts/linq/linq-to-adonet-portal-page.md)|Includes links to general information, programming guidance, and samples for LINQ to ADO.NET.| -|[LINQ to XML](../../../../standard/linq/linq-xml-overview.md)|Includes general information, programming guidance, and samples for LINQ to XML.| - + Query execution is separate from creating a query. After a query is created, its execution is triggered by a separate mechanism. A query can be executed as soon as it is defined (*immediate execution*), or the definition can be stored and the query can be executed later (*deferred execution*). + + By default, when you create a query, the query itself does not execute immediately. Instead, the query definition is stored in the variable that is used to reference the query result. When the query result variable is accessed later in code, such as in a `For…Next` loop, the query is executed. This process is referred to as *deferred execution*. + + Queries can also be executed when they are defined, which is referred to as *immediate execution*. You can trigger immediate execution by applying a method that requires access to individual elements of the query result. This can be the result of including an aggregate function, such as `Count`, `Sum`, `Average`, `Min`, or `Max`. For more information about aggregate functions, see [Aggregate Clause](../../../language-reference/queries/aggregate-clause.md). + + Using the `ToList` or `ToArray` methods will also force immediate execution. This can be useful when you want to execute the query immediately and cache the results. For more information about these methods, see [Converting Data Types](../../concepts/linq/converting-data-types.md). + + For more information about query execution, see [Writing Your First LINQ Query](../../concepts/linq/writing-your-first-linq-query.md). + +## XML in Visual Basic + + The XML features in Visual Basic include XML literals and XML axis properties, which enable you easily to create, access, query, and modify XML in your code. XML literals enable you to write XML directly in your code. The Visual Basic compiler treats the XML as a first-class data object. + + The following code example shows how to create an XML element, access its sub-elements and attributes, and query the contents of the element by using LINQ. + + [!code-vb[VbXmlSamples#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples3.vb#8)] + + For more information, see [XML](../xml/index.md). + +## Related resources + +|Topic|Description| +|---|---| +|[XML](../xml/index.md)|Describes the XML features in Visual Basic that can be queried and that enable you to include XML as first-class data objects in your Visual Basic code.| +|[Queries](../../../language-reference/queries/index.md)|Provides reference information about the query clauses that are available in Visual Basic.| +|[LINQ (Language-Integrated Query)](../../concepts/linq/index.md)|Includes general information, programming guidance, and samples for LINQ.| +|[LINQ to SQL](../../../../framework/data/adonet/sql/linq/index.md)|Includes general information, programming guidance, and samples for LINQ to SQL.| +|[LINQ to Objects](../../concepts/linq/linq-to-objects.md)|Includes general information, programming guidance, and samples for LINQ to Objects.| +|[LINQ to ADO.NET (Portal Page)](../../concepts/linq/linq-to-adonet-portal-page.md)|Includes links to general information, programming guidance, and samples for LINQ to ADO.NET.| +|[LINQ to XML](../../../../standard/linq/linq-xml-overview.md)|Includes general information, programming guidance, and samples for LINQ to XML.| + ## How to and walkthrough topics - [How to: Query a Database](how-to-query-a-database-by-using-linq.md) - - [How to: Call a Stored Procedure](how-to-call-a-stored-procedure-by-using-linq.md) - - [How to: Modify Data in a Database](how-to-modify-data-in-a-database-by-using-linq.md) - - [How to: Combine Data with Joins](how-to-combine-data-with-linq-by-using-joins.md) - - [How to: Sort Query Results](how-to-sort-query-results-by-using-linq.md) - - [How to: Filter Query Results](how-to-filter-query-results-by-using-linq.md) - - [How to: Count, Sum, or Average Data](how-to-count-sum-or-average-data-by-using-linq.md) - - [How to: Find the Minimum or Maximum Value in a Query Result](how-to-find-the-minimum-or-maximum-value-in-a-query-result.md) - - [How to: Assign stored procedures to perform updates, inserts, and deletes (O/R Designer)](/visualstudio/data-tools/how-to-assign-stored-procedures-to-perform-updates-inserts-and-deletes-o-r-designer) - -## Featured book chapters - - [Chapter 17: LINQ](/previous-versions/visualstudio/visual-studio-2008/ff652502(v=orm.10)) in [Programming Visual Basic 2008](/previous-versions/visualstudio/visual-studio-2008/ff652504(v=orm.10)) - + [How to: Query a Database](how-to-query-a-database-by-using-linq.md) + + [How to: Call a Stored Procedure](how-to-call-a-stored-procedure-by-using-linq.md) + + [How to: Modify Data in a Database](how-to-modify-data-in-a-database-by-using-linq.md) + + [How to: Combine Data with Joins](how-to-combine-data-with-linq-by-using-joins.md) + + [How to: Sort Query Results](how-to-sort-query-results-by-using-linq.md) + + [How to: Filter Query Results](how-to-filter-query-results-by-using-linq.md) + + [How to: Count, Sum, or Average Data](how-to-count-sum-or-average-data-by-using-linq.md) + + [How to: Find the Minimum or Maximum Value in a Query Result](how-to-find-the-minimum-or-maximum-value-in-a-query-result.md) + + [How to: Assign stored procedures to perform updates, inserts, and deletes (O/R Designer)](/visualstudio/data-tools/how-to-assign-stored-procedures-to-perform-updates-inserts-and-deletes-o-r-designer) + +## Featured book chapters + + [Chapter 17: LINQ](/previous-versions/visualstudio/visual-studio-2008/ff652502(v=orm.10)) in [Programming Visual Basic 2008](/previous-versions/visualstudio/visual-studio-2008/ff652504(v=orm.10)) + ## See also - [LINQ (Language-Integrated Query)](../../concepts/linq/index.md) diff --git a/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-type-definition.md b/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-type-definition.md index 1a0e051b6b097..6b3171c0b486a 100644 --- a/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-type-definition.md +++ b/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-type-definition.md @@ -49,7 +49,7 @@ End Class In addition, anonymous type definitions contain a parameterless constructor. Constructors that require parameters are not permitted. -If an anonymous type declaration contains at least one key property, the type definition overrides three members inherited from : , , and . If no key properties are declared, only is overridden. The overrides provide the following functionality: +If an anonymous type declaration contains at least one key property, the type definition overrides three members inherited from : , , and . If no key properties are declared, only is overridden. The overrides provide the following functionality: - `Equals` returns `True` if two anonymous type instances are the same instance, or if they meet the following conditions: @@ -73,7 +73,7 @@ If an anonymous type declaration contains at least one key property, the type de Explicitly named properties of an anonymous type cannot conflict with these generated methods. That is, you cannot use `.Equals`, `.GetHashCode`, or `.ToString` to name a property. -Anonymous type definitions that include at least one key property also implement the interface, where `T` is the type of the anonymous type. +Anonymous type definitions that include at least one key property also implement the interface, where `T` is the type of the anonymous type. > [!NOTE] > Anonymous type declarations create the same anonymous type only if they occur in the same assembly, their properties have the same names and the same inferred types, the properties are declared in the same order, and the same properties are marked as key properties. diff --git a/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-types.md b/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-types.md index e371dd8973737..e7edc531eef7e 100644 --- a/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-types.md +++ b/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-types.md @@ -2,9 +2,9 @@ description: "Learn more about: Anonymous Types (Visual Basic)" title: "Anonymous Types" ms.date: 07/20/2015 -f1_keywords: +f1_keywords: - "vb.AnonymousType" -helpviewer_keywords: +helpviewer_keywords: - "anonymous types [Visual Basic], about anonymous types" - "anonymous types [Visual Basic]" - "types [Visual Basic], anonymous" @@ -12,123 +12,123 @@ ms.assetid: 7b87532c-4b3e-4398-8503-6ea9d67574a4 --- # Anonymous Types (Visual Basic) -Visual Basic supports anonymous types, which enable you to create objects without writing a class definition for the data type. Instead, the compiler generates a class for you. The class has no usable name, inherits directly from , and contains the properties you specify in declaring the object. Because the name of the data type is not specified, it is referred to as an *anonymous type*. - - The following example declares and creates variable `product` as an instance of an anonymous type that has two properties, `Name` and `Price`. - - [!code-vb[VbVbalrAnonymousTypes#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#1)] - - A *query expression* uses anonymous types to combine columns of data selected by a query. You cannot define the type of the result in advance, because you cannot predict the columns a particular query might select. Anonymous types enable you to write a query that selects any number of columns, in any order. The compiler creates a data type that matches the specified properties and the specified order. - - In the following examples, `products` is a list of product objects, each of which has many properties. Variable `namePriceQuery` holds the definition of a query that, when it is executed, returns a collection of instances of an anonymous type that has two properties, `Name` and `Price`. - - [!code-vb[VbVbalrAnonymousTypes#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#2)] - - Variable `nameQuantityQuery` holds the definition of a query that, when it is executed, returns a collection of instances of an anonymous type that has two properties, `Name` and `OnHand`. - - [!code-vb[VbVbalrAnonymousTypes#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#3)] - - For more information about the code created by the compiler for an anonymous type, see [Anonymous Type Definition](anonymous-type-definition.md). - +Visual Basic supports anonymous types, which enable you to create objects without writing a class definition for the data type. Instead, the compiler generates a class for you. The class has no usable name, inherits directly from , and contains the properties you specify in declaring the object. Because the name of the data type is not specified, it is referred to as an *anonymous type*. + + The following example declares and creates variable `product` as an instance of an anonymous type that has two properties, `Name` and `Price`. + + [!code-vb[VbVbalrAnonymousTypes#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#1)] + + A *query expression* uses anonymous types to combine columns of data selected by a query. You cannot define the type of the result in advance, because you cannot predict the columns a particular query might select. Anonymous types enable you to write a query that selects any number of columns, in any order. The compiler creates a data type that matches the specified properties and the specified order. + + In the following examples, `products` is a list of product objects, each of which has many properties. Variable `namePriceQuery` holds the definition of a query that, when it is executed, returns a collection of instances of an anonymous type that has two properties, `Name` and `Price`. + + [!code-vb[VbVbalrAnonymousTypes#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#2)] + + Variable `nameQuantityQuery` holds the definition of a query that, when it is executed, returns a collection of instances of an anonymous type that has two properties, `Name` and `OnHand`. + + [!code-vb[VbVbalrAnonymousTypes#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#3)] + + For more information about the code created by the compiler for an anonymous type, see [Anonymous Type Definition](anonymous-type-definition.md). + > [!CAUTION] -> The name of the anonymous type is compiler generated and may vary from compilation to compilation. Your code should not use or rely on the name of an anonymous type because the name might change when a project is recompiled. - -## Declaring an Anonymous Type - - The declaration of an instance of an anonymous type uses an initializer list to specify the properties of the type. You can specify only properties when you declare an anonymous type, not other class elements such as methods or events. In the following example, `product1` is an instance of an anonymous type that has two properties: `Name` and `Price`. - - [!code-vb[VbVbalrAnonymousTypes#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#4)] - - If you designate properties as key properties, you can use them to compare two anonymous type instances for equality. However, the values of key properties cannot be changed. See the Key Properties section later in this topic for more information. - - Notice that declaring an instance of an anonymous type is like declaring an instance of a named type by using an object initializer: - - [!code-vb[VbVbalrAnonymousTypes#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#5)] - - For more information about other ways to specify anonymous type properties, see [How to: Infer Property Names and Types in Anonymous Type Declarations](how-to-infer-property-names-and-types-in-anonymous-type-declarations.md). - -## Key Properties - - Key properties differ from non-key properties in several fundamental ways: - -- Only the values of key properties are compared in order to determine whether two instances are equal. - -- The values of key properties are read-only and cannot be changed. - -- Only key property values are included in the compiler-generated hash code algorithm for an anonymous type. - -### Equality - - Instances of anonymous types can be equal only if they are instances of the same anonymous type. The compiler treats two instances as instances of the same type if they meet the following conditions: - -- They are declared in the same assembly. - -- Their properties have the same names, the same inferred types, and are declared in the same order. Name comparisons are not case-sensitive. - -- The same properties in each are marked as key properties. - -- At least one property in each declaration is a key property. - - An instance of an anonymous types that has no key properties is equal only to itself. - - [!code-vb[VbVbalrAnonymousTypes#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#6)] - - Two instances of the same anonymous type are equal if the values of their key properties are equal. The following examples illustrate how equality is tested. - - [!code-vb[VbVbalrAnonymousTypes#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#7)] - -### Read-Only Values - - The values of key properties cannot be changed. For example, in `prod8` in the previous example, the `Name` and `Price` fields are `read-only`, but `OnHand` can be changed. - - [!code-vb[VbVbalrAnonymousTypes#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#8)] - -## Anonymous Types from Query Expressions - - Query expressions do not always require the creation of anonymous types. When possible, they use an existing type to hold the column data. This occurs when the query returns either whole records from the data source, or only one field from each record. In the following code examples, `customers` is a collection of objects of a `Customer` class. The class has many properties, and you can include one or more of them in the query result, in any order. In the first two examples, no anonymous types are required because the queries select elements of named types: - -- `custs1` contains a collection of strings, because `cust.Name` is a string. - - [!code-vb[VbVbalrAnonymousTypes#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#30)] - -- `custs2` contains a collection of `Customer` objects, because each element of `customers` is a `Customer` object, and the whole element is selected by the query. - - [!code-vb[VbVbalrAnonymousTypes#31](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#31)] - - However, appropriate named types are not always available. You might want to select customer names and addresses for one purpose, customer ID numbers and locations for another, and customer names, addresses, and order histories for a third. Anonymous types enable you to select any combination of properties, in any order, without first declaring a new named type to hold the result. Instead, the compiler creates an anonymous type for each compilation of properties. The following query selects only the customer's name and ID number from each `Customer` object in `customers`. Therefore, the compiler creates an anonymous type that contains only those two properties. - - [!code-vb[VbVbalrAnonymousTYpes#32](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#32)] - - Both the names and the data types of the properties in the anonymous type are taken from the arguments to `Select`, `cust.Name` and `cust.ID`. The properties in an anonymous type that is created by a query are always key properties. When `custs3` is executed in the following `For Each` loop, the result is a collection of instances of an anonymous type with two key properties, `Name` and `ID`. - - [!code-vb[VbVbalrAnonymousTypes#33](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#33)] - - The elements in the collection represented by `custs3` are strongly typed, and you can use IntelliSense to navigate through the available properties and to verify their types. - - For more information, see [Introduction to LINQ in Visual Basic](../linq/introduction-to-linq.md). - -## Deciding Whether to Use Anonymous Types - - Before you create an object as an instance of an anonymous class, consider whether that is the best option. For example, if you want to create a temporary object to contain related data, and you have no need for other fields and methods that a complete class might contain, an anonymous type is a good solution. Anonymous types are also convenient if you want a different selection of properties for each declaration, or if you want to change the order of the properties. However, if your project includes several objects that have the same properties, in a fixed order, you can declare them more easily by using a named type with a class constructor. For example, with an appropriate constructor, it is easier to declare several instances of a `Product` class than it is to declare several instances of an anonymous type. - - [!code-vb[VbVbalrAnonymousTypes#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#9)] - - Another advantage of named types is that the compiler can catch an accidental mistyping of a property name. In the previous examples, `firstProd2`, `secondProd2`, and `thirdProd2` are intended to be instances of the same anonymous type. However, if you were to accidentally declare `thirdProd2` in one of the following ways, its type would be different from that of `firstProd2` and `secondProd2`. - - [!code-vb[VbVbalrAnonymousTypes#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#10)] - - More importantly, there are limitations on the use of anonymous types that do not apply to instances of named types. `firstProd2`, `secondProd2`, and `thirdProd2` are instances of the same anonymous type. However, the name for the shared anonymous type is not available and cannot appear where a type name is expected in your code. For example, an anonymous type cannot be used to define a method signature, to declare another variable or field, or in any type declaration. As a result, anonymous types are not appropriate when you have to share information across methods. - -## An Anonymous Type Definition - - In response to the declaration of an instance of an anonymous type, the compiler creates a new class definition that contains the specified properties. - - If the anonymous type contains at least one key property, the definition overrides three members inherited from : , , and . The code produced for testing equality and determining the hash code value considers only the key properties. If the anonymous type contains no key properties, only is overridden. Explicitly named properties of an anonymous type cannot conflict with these generated methods. That is, you cannot use `.Equals`, `.GetHashCode`, or `.ToString` to name a property. - - Anonymous type definitions that have at least one key property also implement the interface, where `T` is the type of the anonymous type. - - For more information about the code created by the compiler and the functionality of the overridden methods, see [Anonymous Type Definition](anonymous-type-definition.md). - +> The name of the anonymous type is compiler generated and may vary from compilation to compilation. Your code should not use or rely on the name of an anonymous type because the name might change when a project is recompiled. + +## Declaring an Anonymous Type + + The declaration of an instance of an anonymous type uses an initializer list to specify the properties of the type. You can specify only properties when you declare an anonymous type, not other class elements such as methods or events. In the following example, `product1` is an instance of an anonymous type that has two properties: `Name` and `Price`. + + [!code-vb[VbVbalrAnonymousTypes#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#4)] + + If you designate properties as key properties, you can use them to compare two anonymous type instances for equality. However, the values of key properties cannot be changed. See the Key Properties section later in this topic for more information. + + Notice that declaring an instance of an anonymous type is like declaring an instance of a named type by using an object initializer: + + [!code-vb[VbVbalrAnonymousTypes#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#5)] + + For more information about other ways to specify anonymous type properties, see [How to: Infer Property Names and Types in Anonymous Type Declarations](how-to-infer-property-names-and-types-in-anonymous-type-declarations.md). + +## Key Properties + + Key properties differ from non-key properties in several fundamental ways: + +- Only the values of key properties are compared in order to determine whether two instances are equal. + +- The values of key properties are read-only and cannot be changed. + +- Only key property values are included in the compiler-generated hash code algorithm for an anonymous type. + +### Equality + + Instances of anonymous types can be equal only if they are instances of the same anonymous type. The compiler treats two instances as instances of the same type if they meet the following conditions: + +- They are declared in the same assembly. + +- Their properties have the same names, the same inferred types, and are declared in the same order. Name comparisons are not case-sensitive. + +- The same properties in each are marked as key properties. + +- At least one property in each declaration is a key property. + + An instance of an anonymous types that has no key properties is equal only to itself. + + [!code-vb[VbVbalrAnonymousTypes#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#6)] + + Two instances of the same anonymous type are equal if the values of their key properties are equal. The following examples illustrate how equality is tested. + + [!code-vb[VbVbalrAnonymousTypes#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#7)] + +### Read-Only Values + + The values of key properties cannot be changed. For example, in `prod8` in the previous example, the `Name` and `Price` fields are `read-only`, but `OnHand` can be changed. + + [!code-vb[VbVbalrAnonymousTypes#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#8)] + +## Anonymous Types from Query Expressions + + Query expressions do not always require the creation of anonymous types. When possible, they use an existing type to hold the column data. This occurs when the query returns either whole records from the data source, or only one field from each record. In the following code examples, `customers` is a collection of objects of a `Customer` class. The class has many properties, and you can include one or more of them in the query result, in any order. In the first two examples, no anonymous types are required because the queries select elements of named types: + +- `custs1` contains a collection of strings, because `cust.Name` is a string. + + [!code-vb[VbVbalrAnonymousTypes#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#30)] + +- `custs2` contains a collection of `Customer` objects, because each element of `customers` is a `Customer` object, and the whole element is selected by the query. + + [!code-vb[VbVbalrAnonymousTypes#31](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#31)] + + However, appropriate named types are not always available. You might want to select customer names and addresses for one purpose, customer ID numbers and locations for another, and customer names, addresses, and order histories for a third. Anonymous types enable you to select any combination of properties, in any order, without first declaring a new named type to hold the result. Instead, the compiler creates an anonymous type for each compilation of properties. The following query selects only the customer's name and ID number from each `Customer` object in `customers`. Therefore, the compiler creates an anonymous type that contains only those two properties. + + [!code-vb[VbVbalrAnonymousTYpes#32](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#32)] + + Both the names and the data types of the properties in the anonymous type are taken from the arguments to `Select`, `cust.Name` and `cust.ID`. The properties in an anonymous type that is created by a query are always key properties. When `custs3` is executed in the following `For Each` loop, the result is a collection of instances of an anonymous type with two key properties, `Name` and `ID`. + + [!code-vb[VbVbalrAnonymousTypes#33](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class2.vb#33)] + + The elements in the collection represented by `custs3` are strongly typed, and you can use IntelliSense to navigate through the available properties and to verify their types. + + For more information, see [Introduction to LINQ in Visual Basic](../linq/introduction-to-linq.md). + +## Deciding Whether to Use Anonymous Types + + Before you create an object as an instance of an anonymous class, consider whether that is the best option. For example, if you want to create a temporary object to contain related data, and you have no need for other fields and methods that a complete class might contain, an anonymous type is a good solution. Anonymous types are also convenient if you want a different selection of properties for each declaration, or if you want to change the order of the properties. However, if your project includes several objects that have the same properties, in a fixed order, you can declare them more easily by using a named type with a class constructor. For example, with an appropriate constructor, it is easier to declare several instances of a `Product` class than it is to declare several instances of an anonymous type. + + [!code-vb[VbVbalrAnonymousTypes#9](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#9)] + + Another advantage of named types is that the compiler can catch an accidental mistyping of a property name. In the previous examples, `firstProd2`, `secondProd2`, and `thirdProd2` are intended to be instances of the same anonymous type. However, if you were to accidentally declare `thirdProd2` in one of the following ways, its type would be different from that of `firstProd2` and `secondProd2`. + + [!code-vb[VbVbalrAnonymousTypes#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#10)] + + More importantly, there are limitations on the use of anonymous types that do not apply to instances of named types. `firstProd2`, `secondProd2`, and `thirdProd2` are instances of the same anonymous type. However, the name for the shared anonymous type is not available and cannot appear where a type name is expected in your code. For example, an anonymous type cannot be used to define a method signature, to declare another variable or field, or in any type declaration. As a result, anonymous types are not appropriate when you have to share information across methods. + +## An Anonymous Type Definition + + In response to the declaration of an instance of an anonymous type, the compiler creates a new class definition that contains the specified properties. + + If the anonymous type contains at least one key property, the definition overrides three members inherited from : , , and . The code produced for testing equality and determining the hash code value considers only the key properties. If the anonymous type contains no key properties, only is overridden. Explicitly named properties of an anonymous type cannot conflict with these generated methods. That is, you cannot use `.Equals`, `.GetHashCode`, or `.ToString` to name a property. + + Anonymous type definitions that have at least one key property also implement the interface, where `T` is the type of the anonymous type. + + For more information about the code created by the compiler and the functionality of the overridden methods, see [Anonymous Type Definition](anonymous-type-definition.md). + ## See also - [Object Initializers: Named and Anonymous Types](object-initializers-named-and-anonymous-types.md) diff --git a/docs/visual-basic/programming-guide/language-features/objects-and-classes/how-to-infer-property-names-and-types-in-anonymous-type-declarations.md b/docs/visual-basic/programming-guide/language-features/objects-and-classes/how-to-infer-property-names-and-types-in-anonymous-type-declarations.md index 5af1734b8a28e..83ea672d9b6d2 100644 --- a/docs/visual-basic/programming-guide/language-features/objects-and-classes/how-to-infer-property-names-and-types-in-anonymous-type-declarations.md +++ b/docs/visual-basic/programming-guide/language-features/objects-and-classes/how-to-infer-property-names-and-types-in-anonymous-type-declarations.md @@ -45,7 +45,7 @@ Anonymous types can also infer property names and types from other sources. The Dim anon1 = New With {Key sc.SomeFunction()} ``` - The variable `anon2` in the following code is an anonymous type that has one property, a character named `First`. This code will display a letter "E," the letter that is returned by function . + The variable `anon2` in the following code is an anonymous type that has one property, a character named `First`. This code will display a letter "E," the letter that is returned by function . [!code-vb[VbVbalrAnonymousTypes#13](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrAnonymousTypes/VB/Class1.vb#13)] diff --git a/docs/visual-basic/programming-guide/language-features/objects-and-classes/index.md b/docs/visual-basic/programming-guide/language-features/objects-and-classes/index.md index 893e02b333e62..57f18909edf37 100644 --- a/docs/visual-basic/programming-guide/language-features/objects-and-classes/index.md +++ b/docs/visual-basic/programming-guide/language-features/objects-and-classes/index.md @@ -64,7 +64,7 @@ An object is an element of an application, representing an *instance* of a class ### Member Access -You access a member of an object by specifying, in order, the name of the object variable, a period (`.`), and the name of the member. The following example sets the property of a object. +You access a member of an object by specifying, in order, the name of the object variable, a period (`.`), and the name of the member. The following example sets the property of a object. ```vb warningLabel.Text = "Data not saved" @@ -76,7 +76,7 @@ IntelliSense lists members of a class when you invoke its List Members option, f ### Fields and properties -*Fields* and *properties* represent information stored in an object. You retrieve and set their values with assignment statements the same way you retrieve and set local variables in a procedure. The following example retrieves the property and sets the property of a object. +*Fields* and *properties* represent information stored in an object. You retrieve and set their values with assignment statements the same way you retrieve and set local variables in a procedure. The following example retrieves the property and sets the property of a object. ```vb Dim warningWidth As Integer = warningLabel.Width @@ -112,9 +112,9 @@ Use fields when: ### Methods -A *method* is an action that an object can perform. For example, is a method of the object that adds a new entry to a combo box. +A *method* is an action that an object can perform. For example, is a method of the object that adds a new entry to a combo box. -The following example demonstrates the method of a object. +The following example demonstrates the method of a object. ```vb Dim safetyTimer As New System.Windows.Forms.Timer @@ -192,7 +192,7 @@ Public Sub ExamineTimeZone() End Sub ``` -In the preceding example, the first [Dim Statement](../../../language-reference/statements/dim-statement.md) declares an object variable of type and assigns to it a object returned by the property. +In the preceding example, the first [Dim Statement](../../../language-reference/statements/dim-statement.md) declares an object variable of type and assigns to it a object returned by the property. ## Relationships among objects @@ -245,11 +245,11 @@ Be sure the compiler can access the class from which you intend to derive your n ### Containment relationship -Another way that objects can be related is a *containment relationship*. Container objects logically encapsulate other objects. For example, the object logically contains a object, which it returns through its property. Note that the container object does not physically contain any other object. +Another way that objects can be related is a *containment relationship*. Container objects logically encapsulate other objects. For example, the object logically contains a object, which it returns through its property. Note that the container object does not physically contain any other object. #### Collections -One particular type of object containment is represented by *collections*. Collections are groups of similar objects that can be enumerated. Visual Basic supports a specific syntax in the [For Each...Next Statement](../../../language-reference/statements/for-each-next-statement.md) that allows you to iterate through the items of a collection. Additionally, collections often allow you to use an to retrieve elements by their index or by associating them with a unique string. Collections can be easier to use than arrays because they allow you to add or remove items without using indexes. Because of their ease of use, collections are often used to store forms and controls. +One particular type of object containment is represented by *collections*. Collections are groups of similar objects that can be enumerated. Visual Basic supports a specific syntax in the [For Each...Next Statement](../../../language-reference/statements/for-each-next-statement.md) that allows you to iterate through the items of a collection. Additionally, collections often allow you to use an to retrieve elements by their index or by associating them with a unique string. Collections can be easier to use than arrays because they allow you to add or remove items without using indexes. Because of their ease of use, collections are often used to store forms and controls. ## Related topics diff --git a/docs/visual-basic/programming-guide/language-features/objects-and-classes/object-lifetime-how-objects-are-created-and-destroyed.md b/docs/visual-basic/programming-guide/language-features/objects-and-classes/object-lifetime-how-objects-are-created-and-destroyed.md index a138906fc1a4c..120a70a712c98 100644 --- a/docs/visual-basic/programming-guide/language-features/objects-and-classes/object-lifetime-how-objects-are-created-and-destroyed.md +++ b/docs/visual-basic/programming-guide/language-features/objects-and-classes/object-lifetime-how-objects-are-created-and-destroyed.md @@ -59,7 +59,7 @@ Before releasing objects, the CLR automatically calls the `Finalize` method for The `Finalize` destructor is a protected method that can be called only from the class it belongs to, or from derived classes. The system calls `Finalize` automatically when an object is destroyed, so you should not explicitly call `Finalize` from outside of a derived class's `Finalize` implementation. -Unlike `Class_Terminate`, which executes as soon as an object is set to nothing, there is usually a delay between when an object loses scope and when Visual Basic calls the `Finalize` destructor. Visual Basic .NET allows for a second kind of destructor, , which can be explicitly called at any time to immediately release resources. +Unlike `Class_Terminate`, which executes as soon as an object is set to nothing, there is usually a delay between when an object loses scope and when Visual Basic calls the `Finalize` destructor. Visual Basic .NET allows for a second kind of destructor, , which can be explicitly called at any time to immediately release resources. > [!NOTE] > A `Finalize` destructor should not throw exceptions, because they cannot be handled by the application and can cause the application to terminate. @@ -72,7 +72,7 @@ When an instance of a derived class is created, the `Sub New` constructor of the ![Screenshot showing class hierarchy constructors and inheritance.](./media/object-lifetime-how-objects-are-created-and-destroyed/subnew-constructor-inheritance.gif) -When an object is no longer needed, the CLR calls the method for that object before freeing its memory. The method is called a `destructor` because it performs cleanup tasks, such as saving state information, closing files and connections to databases, and other tasks that must be done before releasing the object. +When an object is no longer needed, the CLR calls the method for that object before freeing its memory. The method is called a `destructor` because it performs cleanup tasks, such as saving state information, closing files and connections to databases, and other tasks that must be done before releasing the object. ![Screenshot showing the Finalize method destructor.](./media/object-lifetime-how-objects-are-created-and-destroyed/finalize-method-destructor.gif) @@ -80,7 +80,7 @@ When an object is no longer needed, the CLR calls the interface. has one method, , which clients should call when they finish using an object. You can use the method to immediately release resources and perform tasks such as closing files and database connections. Unlike the `Finalize` destructor, the method is not called automatically. Clients of a class must explicitly call when you want to immediately release resources. +To supplement garbage collection, your classes can provide a mechanism to actively manage system resources if they implement the interface. has one method, , which clients should call when they finish using an object. You can use the method to immediately release resources and perform tasks such as closing files and database connections. Unlike the `Finalize` destructor, the method is not called automatically. Clients of a class must explicitly call when you want to immediately release resources. ### Implementing IDisposable @@ -92,7 +92,7 @@ A class that implements the interface should include t Protected disposed As Boolean = False ``` -- An overload of the that frees the class's resources. This method should be called by the and `Finalize` methods of the base class: +- An overload of the that frees the class's resources. This method should be called by the and `Finalize` methods of the base class: ```vb Protected Overridable Sub Dispose(ByVal disposing As Boolean) @@ -106,7 +106,7 @@ A class that implements the interface should include t End Sub ``` -- An implementation of that contains only the following code: +- An implementation of that contains only the following code: ```vb Public Sub Dispose() Implements IDisposable.Dispose @@ -140,7 +140,7 @@ Protected Overrides Sub Dispose(ByVal disposing As Boolean) End Sub ``` -A derived class should not override the base class's and `Finalize` methods. When those methods are called from an instance of the derived class, the base class's implementation of those methods call the derived class's override of the `Dispose(disposing)` method. +A derived class should not override the base class's and `Finalize` methods. When those methods are called from an instance of the derived class, the base class's implementation of those methods call the derived class's override of the `Dispose(disposing)` method. ## Garbage Collection and the Finalize Destructor @@ -148,11 +148,11 @@ The .NET Framework uses the *reference-tracing garbage collection* system to per The CLR periodically destroys objects when the system determines that such objects are no longer needed. Objects are released more quickly when system resources are in short supply, and less frequently otherwise. The delay between when an object loses scope and when the CLR releases it means that, unlike with objects in Visual Basic 6.0 and earlier versions, you cannot determine exactly when the object will be destroyed. In such a situation, objects are said to have *non-deterministic lifetime*. In most cases, non-deterministic lifetime does not change how you write applications, as long as you remember that the `Finalize` destructor may not immediately execute when an object loses scope. -Another difference between the garbage-collection systems involves the use of `Nothing`. To take advantage of reference counting in Visual Basic 6.0 and earlier versions, programmers sometimes assigned `Nothing` to object variables to release the references those variables held. If the variable held the last reference to the object, the object's resources were released immediately. In later versions of Visual Basic, while there may be cases in which this procedure is still valuable, performing it never causes the referenced object to release its resources immediately. To release resources immediately, use the object's method, if available. The only time you should set a variable to `Nothing` is when its lifetime is long relative to the time the garbage collector takes to detect orphaned objects. +Another difference between the garbage-collection systems involves the use of `Nothing`. To take advantage of reference counting in Visual Basic 6.0 and earlier versions, programmers sometimes assigned `Nothing` to object variables to release the references those variables held. If the variable held the last reference to the object, the object's resources were released immediately. In later versions of Visual Basic, while there may be cases in which this procedure is still valuable, performing it never causes the referenced object to release its resources immediately. To release resources immediately, use the object's method, if available. The only time you should set a variable to `Nothing` is when its lifetime is long relative to the time the garbage collector takes to detect orphaned objects. ## See also -- +- - [Initialization and Termination of Components](/previous-versions/visualstudio/visual-studio-2013/ws9dc6t6(v=vs.120)) - [New Operator](../../../language-reference/operators/new-operator.md) - [Cleaning Up Unmanaged Resources](../../../../standard/garbage-collection/unmanaged.md) diff --git a/docs/visual-basic/programming-guide/language-features/operators-and-expressions/arithmetic-operators.md b/docs/visual-basic/programming-guide/language-features/operators-and-expressions/arithmetic-operators.md index 830772fa01716..c2a9a15380905 100644 --- a/docs/visual-basic/programming-guide/language-features/operators-and-expressions/arithmetic-operators.md +++ b/docs/visual-basic/programming-guide/language-features/operators-and-expressions/arithmetic-operators.md @@ -2,7 +2,7 @@ description: "Learn more about: Arithmetic Operators in Visual Basic" title: "Arithmetic Operators" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "type safety" - "operators [Visual Basic], bitwise" - "operators [Visual Basic], bit-shift" @@ -17,84 +17,84 @@ ms.assetid: 325dac7a-ea4f-41d5-8b48-f6e904211569 --- # Arithmetic Operators in Visual Basic -Arithmetic operators are used to perform many of the familiar arithmetic operations that involve the calculation of numeric values represented by literals, variables, other expressions, function and property calls, and constants. Also classified with arithmetic operators are the bit-shift operators, which act at the level of the individual bits of the operands and shift their bit patterns to the left or right. - -## Arithmetic Operations - - You can add two values in an expression together with the [+ Operator](../../../language-reference/operators/addition-operator.md), or subtract one from another with the [- Operator (Visual Basic)](../../../language-reference/operators/subtraction-operator.md), as the following example demonstrates. - - [!code-vb[VbVbalrOperators#57](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#57)] - - Negation also uses the [- Operator (Visual Basic)](../../../language-reference/operators/subtraction-operator.md), but with only one operand, as the following example demonstrates. - - [!code-vb[VbVbalrOperators#58](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#58)] - - Multiplication and division use the [* Operator](../../../language-reference/operators/multiplication-operator.md) and [/ Operator (Visual Basic)](../../../language-reference/operators/floating-point-division-operator.md), respectively, as the following example demonstrates. - - [!code-vb[VbVbalrOperators#59](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#59)] - - Exponentiation uses the [^ Operator](../../../language-reference/operators/exponentiation-operator.md), as the following example demonstrates. - - [!code-vb[VbVbalrOperators#60](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#60)] - - Integer division is carried out using the [\ Operator (Visual Basic)](../../../language-reference/operators/integer-division-operator.md). Integer division returns the quotient, that is, the integer that represents the number of times the divisor can divide into the dividend without consideration of any remainder. Both the divisor and the dividend must be integral types (`SByte`, `Byte`, `Short`, `UShort`, `Integer`, `UInteger`, `Long`, and `ULong`) for this operator. All other types must be converted to an integral type first. The following example demonstrates integer division. - - [!code-vb[VbVbalrOperators#61](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#61)] - - Modulus arithmetic is performed using the [Mod Operator](../../../language-reference/operators/mod-operator.md). This operator returns the remainder after dividing the divisor into the dividend an integral number of times. If both divisor and dividend are integral types, the returned value is integral. If divisor and dividend are floating-point types, the returned value is also floating-point. The following example demonstrates this behavior. - - [!code-vb[VbVbalrOperators#62](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#62)] - - [!code-vb[VbVbalrOperators#63](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#63)] - -### Attempted Division by Zero - - Division by zero has different results depending on the data types involved. In integral divisions (`SByte`, `Byte`, `Short`, `UShort`, `Integer`, `UInteger`, `Long`, `ULong`), the .NET Framework throws a exception. In division operations on the `Decimal` or `Single` data type, the .NET Framework also throws a exception. - - In floating-point divisions involving the `Double` data type, no exception is thrown, and the result is the class member representing , , or , depending on the dividend. The following table summarizes the various results of attempting to divide a `Double` value by zero. - -|Dividend data type|Divisor data type|Dividend value|Result| -|---|---|---|---| -|`Double`|`Double`|0| (not a mathematically defined number)| -|`Double`|`Double`|> 0|| -|`Double`|`Double`|\< 0|| - - When you catch a exception, you can use its members to help you handle it. For example, the property holds the message text for the exception. For more information, see [Try...Catch...Finally Statement](../../../language-reference/statements/try-catch-finally-statement.md). - -## Bit-Shift Operations - - A bit-shift operation performs an arithmetic shift on a bit pattern. The pattern is contained in the operand on the left, while the operand on the right specifies the number of positions to shift the pattern. You can shift the pattern to the right with the [>> Operator](../../../language-reference/operators/right-shift-operator.md) or to the left with the [<< Operator](../../../language-reference/operators/left-shift-operator.md). - - The data type of the pattern operand must be `SByte`, `Byte`, `Short`, `UShort`, `Integer`, `UInteger`, `Long`, or `ULong`. The data type of the shift amount operand must be `Integer` or must widen to `Integer`. - - Arithmetic shifts are not circular, which means the bits shifted off one end of the result are not reintroduced at the other end. The bit positions vacated by a shift are set as follows: - -- 0 for an arithmetic left shift - -- 0 for an arithmetic right shift of a positive number - -- 0 for an arithmetic right shift of an unsigned data type (`Byte`, `UShort`, `UInteger`, `ULong`) - -- 1 for an arithmetic right shift of a negative number (`SByte`, `Short`, `Integer`, or `Long`) - - The following example shifts an `Integer` value both left and right. - - [!code-vb[VbVbalrOperators#64](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#64)] - - Arithmetic shifts never generate overflow exceptions. - -## Bitwise Operations - - In addition to being logical operators, `Not`, `Or`, `And`, and `Xor` also perform bitwise arithmetic when used on numeric values. For more information, see "Bitwise Operations" in [Logical and Bitwise Operators in Visual Basic](logical-and-bitwise-operators.md). - -## Type Safety - - Operands should normally be of the same type. For example, if you are doing addition with an `Integer` variable, you should add it to another `Integer` variable, and you should assign the result to a variable of type `Integer` as well. - - One way to ensure good type-safe coding practice is to use the [Option Strict Statement](../../../language-reference/statements/option-strict-statement.md). If you set `Option Strict On`, Visual Basic automatically performs *type-safe* conversions. For example, if you try to add an `Integer` variable to a `Double` variable and assign the value to a `Double` variable, the operation proceeds normally, because an `Integer` value can be converted to `Double` without loss of data. Type-unsafe conversions, on the other hand, cause a compiler error with `Option Strict On`. For example, if you try to add an `Integer` variable to a `Double` variable and assign the value to an `Integer` variable, a compiler error results, because a `Double` variable cannot be implicitly converted to type `Integer`. - - If you set `Option Strict Off`, however, Visual Basic allows implicit narrowing conversions to take place, although they can result in the unexpected loss of data or precision. For this reason, we recommend that you use `Option Strict On` when writing production code. For more information, see [Widening and Narrowing Conversions](../data-types/widening-and-narrowing-conversions.md). - +Arithmetic operators are used to perform many of the familiar arithmetic operations that involve the calculation of numeric values represented by literals, variables, other expressions, function and property calls, and constants. Also classified with arithmetic operators are the bit-shift operators, which act at the level of the individual bits of the operands and shift their bit patterns to the left or right. + +## Arithmetic Operations + + You can add two values in an expression together with the [+ Operator](../../../language-reference/operators/addition-operator.md), or subtract one from another with the [- Operator (Visual Basic)](../../../language-reference/operators/subtraction-operator.md), as the following example demonstrates. + + [!code-vb[VbVbalrOperators#57](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#57)] + + Negation also uses the [- Operator (Visual Basic)](../../../language-reference/operators/subtraction-operator.md), but with only one operand, as the following example demonstrates. + + [!code-vb[VbVbalrOperators#58](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#58)] + + Multiplication and division use the [* Operator](../../../language-reference/operators/multiplication-operator.md) and [/ Operator (Visual Basic)](../../../language-reference/operators/floating-point-division-operator.md), respectively, as the following example demonstrates. + + [!code-vb[VbVbalrOperators#59](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#59)] + + Exponentiation uses the [^ Operator](../../../language-reference/operators/exponentiation-operator.md), as the following example demonstrates. + + [!code-vb[VbVbalrOperators#60](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#60)] + + Integer division is carried out using the [\ Operator (Visual Basic)](../../../language-reference/operators/integer-division-operator.md). Integer division returns the quotient, that is, the integer that represents the number of times the divisor can divide into the dividend without consideration of any remainder. Both the divisor and the dividend must be integral types (`SByte`, `Byte`, `Short`, `UShort`, `Integer`, `UInteger`, `Long`, and `ULong`) for this operator. All other types must be converted to an integral type first. The following example demonstrates integer division. + + [!code-vb[VbVbalrOperators#61](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#61)] + + Modulus arithmetic is performed using the [Mod Operator](../../../language-reference/operators/mod-operator.md). This operator returns the remainder after dividing the divisor into the dividend an integral number of times. If both divisor and dividend are integral types, the returned value is integral. If divisor and dividend are floating-point types, the returned value is also floating-point. The following example demonstrates this behavior. + + [!code-vb[VbVbalrOperators#62](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#62)] + + [!code-vb[VbVbalrOperators#63](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#63)] + +### Attempted Division by Zero + + Division by zero has different results depending on the data types involved. In integral divisions (`SByte`, `Byte`, `Short`, `UShort`, `Integer`, `UInteger`, `Long`, `ULong`), the .NET Framework throws a exception. In division operations on the `Decimal` or `Single` data type, the .NET Framework also throws a exception. + + In floating-point divisions involving the `Double` data type, no exception is thrown, and the result is the class member representing , , or , depending on the dividend. The following table summarizes the various results of attempting to divide a `Double` value by zero. + +|Dividend data type|Divisor data type|Dividend value|Result| +|---|---|---|---| +|`Double`|`Double`|0| (not a mathematically defined number)| +|`Double`|`Double`|> 0|| +|`Double`|`Double`|\< 0|| + + When you catch a exception, you can use its members to help you handle it. For example, the property holds the message text for the exception. For more information, see [Try...Catch...Finally Statement](../../../language-reference/statements/try-catch-finally-statement.md). + +## Bit-Shift Operations + + A bit-shift operation performs an arithmetic shift on a bit pattern. The pattern is contained in the operand on the left, while the operand on the right specifies the number of positions to shift the pattern. You can shift the pattern to the right with the [>> Operator](../../../language-reference/operators/right-shift-operator.md) or to the left with the [<< Operator](../../../language-reference/operators/left-shift-operator.md). + + The data type of the pattern operand must be `SByte`, `Byte`, `Short`, `UShort`, `Integer`, `UInteger`, `Long`, or `ULong`. The data type of the shift amount operand must be `Integer` or must widen to `Integer`. + + Arithmetic shifts are not circular, which means the bits shifted off one end of the result are not reintroduced at the other end. The bit positions vacated by a shift are set as follows: + +- 0 for an arithmetic left shift + +- 0 for an arithmetic right shift of a positive number + +- 0 for an arithmetic right shift of an unsigned data type (`Byte`, `UShort`, `UInteger`, `ULong`) + +- 1 for an arithmetic right shift of a negative number (`SByte`, `Short`, `Integer`, or `Long`) + + The following example shifts an `Integer` value both left and right. + + [!code-vb[VbVbalrOperators#64](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrOperators/VB/Class1.vb#64)] + + Arithmetic shifts never generate overflow exceptions. + +## Bitwise Operations + + In addition to being logical operators, `Not`, `Or`, `And`, and `Xor` also perform bitwise arithmetic when used on numeric values. For more information, see "Bitwise Operations" in [Logical and Bitwise Operators in Visual Basic](logical-and-bitwise-operators.md). + +## Type Safety + + Operands should normally be of the same type. For example, if you are doing addition with an `Integer` variable, you should add it to another `Integer` variable, and you should assign the result to a variable of type `Integer` as well. + + One way to ensure good type-safe coding practice is to use the [Option Strict Statement](../../../language-reference/statements/option-strict-statement.md). If you set `Option Strict On`, Visual Basic automatically performs *type-safe* conversions. For example, if you try to add an `Integer` variable to a `Double` variable and assign the value to a `Double` variable, the operation proceeds normally, because an `Integer` value can be converted to `Double` without loss of data. Type-unsafe conversions, on the other hand, cause a compiler error with `Option Strict On`. For example, if you try to add an `Integer` variable to a `Double` variable and assign the value to an `Integer` variable, a compiler error results, because a `Double` variable cannot be implicitly converted to type `Integer`. + + If you set `Option Strict Off`, however, Visual Basic allows implicit narrowing conversions to take place, although they can result in the unexpected loss of data or precision. For this reason, we recommend that you use `Option Strict On` when writing production code. For more information, see [Widening and Narrowing Conversions](../data-types/widening-and-narrowing-conversions.md). + ## See also - [Arithmetic Operators](../../../language-reference/operators/arithmetic-operators.md) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/function-procedures.md b/docs/visual-basic/programming-guide/language-features/procedures/function-procedures.md index 22d4579c12498..aa65bc6c44bb1 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/function-procedures.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/function-procedures.md @@ -87,7 +87,7 @@ The syntax for a call to a `Function` procedure is as follows. `If ((` *functionname* `[(` *argumentlist* `)] / 3) <=` *expression* `) Then` -When you call a `Function` procedure, you do not have to use its return value. If you do not, all the actions of the function are performed, but the return value is ignored. is often called in this manner. +When you call a `Function` procedure, you do not have to use its return value. If you do not, all the actions of the function are performed, but the return value is ignored. is often called in this manner. ### Illustration of declaration and call diff --git a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-procedure-that-does-not-return-a-value.md b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-procedure-that-does-not-return-a-value.md index e23de4b4314d4..bd0fc835612cf 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-procedure-that-does-not-return-a-value.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-procedure-that-does-not-return-a-value.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Call a Procedure that Does Not Return a Value (Visual Basic)" title: "How to: Call a Procedure that Does Not Return a Value" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "procedure calls [Visual Basic], returning values" - "Visual Basic code, procedures" - "procedures [Visual Basic], calling" @@ -10,23 +10,23 @@ ms.assetid: 259b49a3-a3c1-4254-ba8c-73cdc4127703 --- # How to: Call a Procedure that Does Not Return a Value (Visual Basic) -A `Sub` procedure does not return a value to the calling code. You call it explicitly with a stand-alone calling statement. You cannot call it by simply using its name within an expression. - -### To call a Sub procedure - -1. Specify the name of the `Sub` procedure. - -2. Follow the procedure name with parentheses to enclose the argument list. If there are no arguments, you can optionally omit the parentheses. However, using the parentheses makes your code easier to read. - -3. Place the arguments in the argument list within the parentheses, separated by commas. Be sure you supply the arguments in the same order that the `Sub` procedure defines the corresponding parameters. - - The following example calls the Visual Basic function to activate an application window. takes the window title as its sole argument. It does not return a value to the calling code. If a Notepad process is not running, the example throws an . The `Shell` procedure assumes the applications are in the paths specified. - - [!code-vb[VbVbalrCatRef#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrCatRef/VB/Class1.vb#11)] - +A `Sub` procedure does not return a value to the calling code. You call it explicitly with a stand-alone calling statement. You cannot call it by simply using its name within an expression. + +### To call a Sub procedure + +1. Specify the name of the `Sub` procedure. + +2. Follow the procedure name with parentheses to enclose the argument list. If there are no arguments, you can optionally omit the parentheses. However, using the parentheses makes your code easier to read. + +3. Place the arguments in the argument list within the parentheses, separated by commas. Be sure you supply the arguments in the same order that the `Sub` procedure defines the corresponding parameters. + + The following example calls the Visual Basic function to activate an application window. takes the window title as its sole argument. It does not return a value to the calling code. If a Notepad process is not running, the example throws an . The `Shell` procedure assumes the applications are in the paths specified. + + [!code-vb[VbVbalrCatRef#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrCatRef/VB/Class1.vb#11)] + ## See also -- +- - - [Procedures](./index.md) - [Sub Procedures](./sub-procedures.md) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-procedure-that-returns-a-value.md b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-procedure-that-returns-a-value.md index 1051cdddeca16..794cab87f3855 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-procedure-that-returns-a-value.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-procedure-that-returns-a-value.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Call a Procedure That Returns a Value (Visual Basic)" title: "How to: Call a Procedure That Returns a Value" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "procedure calls [Visual Basic], returning values" - "Visual Basic code, procedures" - "procedures [Visual Basic], calling" @@ -11,36 +11,36 @@ ms.assetid: a445127b-0f5f-465a-98fb-3e514b93d115 --- # How to: Call a Procedure That Returns a Value (Visual Basic) -A `Function` procedure returns a value to the calling code. You call it by including its name and arguments either on the right side of an assignment statement or in an expression. - -### To call a Function procedure within an expression - -1. Use the `Function` procedure name the same way you would use a variable. You can use a `Function` procedure call anywhere you can use a variable or constant in an expression. - -2. Follow the procedure name with parentheses to enclose the argument list. If there are no arguments, you can optionally omit the parentheses. However, using the parentheses makes your code easier to read. - -3. Place the arguments in the argument list within the parentheses, separated by commas. Be sure you supply the arguments in the same order that the `Function` procedure defines the corresponding parameters. - - Alternatively, you can pass one or more arguments by name. For more information, see [Passing Arguments by Position and by Name](./passing-arguments-by-position-and-by-name.md). - -4. The value returned from the procedure participates in the expression just as the value of a variable or constant would. - -### To call a Function procedure in an assignment statement - -1. Use the `Function` procedure name following the equal (`=`) sign in the assignment statement. - -2. Follow the procedure name with parentheses to enclose the argument list. If there are no arguments, you can optionally omit the parentheses. However, using the parentheses makes your code easier to read. - -3. Place the arguments in the argument list within the parentheses, separated by commas. Be sure you supply the arguments in the same order that the `Function` procedure defines the corresponding parameters, unless you are passing them by name. - -4. The value returned from the procedure is stored in the variable or property on the left side of the assignment statement. - -## Example - - The following example calls the Visual Basic to retrieve the value of an operating system environment variable. The first line calls `Environ` within an expression, and the second line calls it in an assignment statement. `Environ` takes the variable name as its sole argument. It returns the variable's value to the calling code. - - [!code-vb[VbVbcnProcedures#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#7)] - +A `Function` procedure returns a value to the calling code. You call it by including its name and arguments either on the right side of an assignment statement or in an expression. + +### To call a Function procedure within an expression + +1. Use the `Function` procedure name the same way you would use a variable. You can use a `Function` procedure call anywhere you can use a variable or constant in an expression. + +2. Follow the procedure name with parentheses to enclose the argument list. If there are no arguments, you can optionally omit the parentheses. However, using the parentheses makes your code easier to read. + +3. Place the arguments in the argument list within the parentheses, separated by commas. Be sure you supply the arguments in the same order that the `Function` procedure defines the corresponding parameters. + + Alternatively, you can pass one or more arguments by name. For more information, see [Passing Arguments by Position and by Name](./passing-arguments-by-position-and-by-name.md). + +4. The value returned from the procedure participates in the expression just as the value of a variable or constant would. + +### To call a Function procedure in an assignment statement + +1. Use the `Function` procedure name following the equal (`=`) sign in the assignment statement. + +2. Follow the procedure name with parentheses to enclose the argument list. If there are no arguments, you can optionally omit the parentheses. However, using the parentheses makes your code easier to read. + +3. Place the arguments in the argument list within the parentheses, separated by commas. Be sure you supply the arguments in the same order that the `Function` procedure defines the corresponding parameters, unless you are passing them by name. + +4. The value returned from the procedure is stored in the variable or property on the left side of the assignment statement. + +## Example + + The following example calls the Visual Basic to retrieve the value of an operating system environment variable. The first line calls `Environ` within an expression, and the second line calls it in an assignment statement. `Environ` takes the variable name as its sole argument. It returns the variable's value to the calling code. + + [!code-vb[VbVbcnProcedures#7](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#7)] + ## See also - [Function Procedures](./function-procedures.md) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-property-procedure.md b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-property-procedure.md index 4c7d4361c3d71..fe1e62a7fe8ff 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-property-procedure.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/how-to-call-a-property-procedure.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Call a Property Procedure (Visual Basic)" title: "How to: Call a Property Procedure" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "Visual Basic code, procedures" - "Visual Basic code, properties" - "procedures [Visual Basic], calling" @@ -12,42 +12,42 @@ ms.assetid: 96bc4d74-d9c3-4b7a-954d-58ac8553cd94 --- # How to: Call a Property Procedure (Visual Basic) -You call a property procedure by storing a value in the property or retrieving its value. You access a property the same way you access a variable. - - The property's `Set` procedure stores a value, and its `Get` procedure retrieves the value. However, you do not explicitly call these procedures by name. You use the property in an assignment statement or an expression, just as you would store or retrieve the value of a variable. Visual Basic makes the calls to the property's procedures. - -### To call a property's Get procedure - -1. Use the property name in an expression the same way you would use a variable name. You can use a property anywhere you can use a variable or a constant. - - -or- - - Use the property name following the equal (`=`) sign in an assignment statement. - - The following example reads the value of the property, implicitly calling its `Get` procedure. - - [!code-vb[VbVbalrDateProperties#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDateProperties/VB/Module1.vb#4)] - -2. If the property takes arguments, follow the property name with parentheses to enclose the argument list. If there are no arguments, you can optionally omit the parentheses. - -3. Place the arguments in the argument list within the parentheses, separated by commas. Be sure you supply the arguments in the same order that the property defines the corresponding parameters. - - The value of the property participates in the expression just as a variable or constant would, or it is stored in the variable or property on the left side of the assignment statement. - -### To call a property's Set procedure - -1. Use the property name on the left side of an assignment statement. - - The following example sets the value of the property, implicitly calling the `Set` procedure. - - [!code-vb[VbVbcnProcedures#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#11)] - -2. If the property takes arguments, follow the property name with parentheses to enclose the argument list. If there are no arguments, you can optionally omit the parentheses. - -3. Place the arguments in the argument list within the parentheses, separated by commas. Be sure you supply the arguments in the same order that the property defines the corresponding parameters. - - The value generated on the right side of the assignment statement is stored in the property. - +You call a property procedure by storing a value in the property or retrieving its value. You access a property the same way you access a variable. + + The property's `Set` procedure stores a value, and its `Get` procedure retrieves the value. However, you do not explicitly call these procedures by name. You use the property in an assignment statement or an expression, just as you would store or retrieve the value of a variable. Visual Basic makes the calls to the property's procedures. + +### To call a property's Get procedure + +1. Use the property name in an expression the same way you would use a variable name. You can use a property anywhere you can use a variable or a constant. + + -or- + + Use the property name following the equal (`=`) sign in an assignment statement. + + The following example reads the value of the property, implicitly calling its `Get` procedure. + + [!code-vb[VbVbalrDateProperties#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDateProperties/VB/Module1.vb#4)] + +2. If the property takes arguments, follow the property name with parentheses to enclose the argument list. If there are no arguments, you can optionally omit the parentheses. + +3. Place the arguments in the argument list within the parentheses, separated by commas. Be sure you supply the arguments in the same order that the property defines the corresponding parameters. + + The value of the property participates in the expression just as a variable or constant would, or it is stored in the variable or property on the left side of the assignment statement. + +### To call a property's Set procedure + +1. Use the property name on the left side of an assignment statement. + + The following example sets the value of the property, implicitly calling the `Set` procedure. + + [!code-vb[VbVbcnProcedures#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#11)] + +2. If the property takes arguments, follow the property name with parentheses to enclose the argument list. If there are no arguments, you can optionally omit the parentheses. + +3. Place the arguments in the argument list within the parentheses, separated by commas. Be sure you supply the arguments in the same order that the property defines the corresponding parameters. + + The value generated on the right side of the assignment statement is stored in the property. + ## See also - [Property Procedures](./property-procedures.md) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/how-to-create-a-lambda-expression.md b/docs/visual-basic/programming-guide/language-features/procedures/how-to-create-a-lambda-expression.md index bbf3c195cd298..7e0bd906fbde3 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/how-to-create-a-lambda-expression.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/how-to-create-a-lambda-expression.md @@ -2,105 +2,105 @@ description: "Learn more about: How to: Create a Lambda Expression (Visual Basic)" title: "How to: Create a Lambda Expression" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "lambda expressions [Visual Basic]" - "expressions [Visual Basic], lambda" ms.assetid: 3279bd5c-80f7-410a-a7ba-f7085ed36aa5 --- # How to: Create a Lambda Expression (Visual Basic) -A *lambda expression* is a function or subroutine that does not have a name. A lambda expression can be used wherever a delegate type is valid. - -### To create a single-line lambda expression function - -1. In any situation where a delegate type could be used, type the keyword `Function`, as in the following example: - - `Dim add1 =` `Function` - -2. In parentheses, directly after `Function`, type the parameters of the function. Notice that you do not specify a name after `Function`. - - `Dim add1 = Function` `(num As Integer)` - -3. Following the parameter list, type a single expression as the body of the function. The value that the expression evaluates to is the value returned by the function. You do not use an `As` clause to specify the return type. - - [!code-vb[VbVbalrLambdas#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#1)] - - You call the lambda expression by passing in an integer argument. - - [!code-vb[VbVbalrLambdas#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#2)] - -4. Alternatively, the same result is accomplished by the following example: - - [!code-vb[VbVbalrLambdas#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#3)] - -### To create a single-line lambda expression subroutine - -1. In any situation where a delegate type could be used, type the keyword `Sub`, as shown in the following example. - - `Dim add1 =` `Sub` - -2. In parentheses, directly after `Sub`, type the parameters of the subroutine. Notice that you do not specify a name after `Sub`. - - `Dim add1 = Sub` `(msg As String)` - -3. Following the parameter list, type a single statement as the body of the subroutine. - - [!code-vb[VbVbalrLambdas#17](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#17)] - - You call the lambda expression by passing in a string argument. - - [!code-vb[VbVbalrLambdas#18](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#18)] - -### To create a multiline lambda expression function - -1. In any situation where a delegate type could be used, type the keyword `Function`, as shown in the following example. - - `Dim add1 =` `Function` - -2. In parentheses, directly after `Function`, type the parameters of the function. Notice that you do not specify a name after `Function`. - - `Dim add1 = Function` `(index As Integer)` - -3. Press ENTER. The `End Function` statement is automatically added. - -4. Within the body of the function, add the following code to create an expression and return the value. You do not use an `As` clause to specify the return type. - - [!code-vb[VbVbalrLambdas#19](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#19)] - - You call the lambda expression by passing in an integer argument. - - [!code-vb[VbVbalrLambdas#20](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#20)] - -### To create a multiline lambda expression subroutine - -1. In any situation where a delegate type could be used, type the keyword `Sub`, as shown in the following example: - - `Dim add1 =` `Sub` - -2. In parentheses, directly after `Sub`, type the parameters of the subroutine. Notice that you do not specify a name after `Sub`. - - `Dim add1 = Sub` `(msg As String)` - -3. Press ENTER. The `End Sub` statement is automatically added. - -4. Within the body of the function, add the following code to execute when the subroutine is invoked. - - [!code-vb[VbVbalrLambdas#21](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#21)] - - You call the lambda expression by passing in a string argument. - - [!code-vb[VbVbalrLambdas#22](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#22)] - -## Example - - A common use of lambda expressions is to define a function that can be passed in as the argument for a parameter whose type is `Delegate`. In the following example, the method returns an array of the processes running on the local computer. The method from the class requires a `Boolean` delegate as its argument. The lambda expression in the example is used for that purpose. It returns `True` for each process that has only one thread, and those are selected in `filteredList`. - - [!code-vb[VbVbalrLambdas#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class4.vb#10)] - - The previous example is equivalent to the following code, which is written in Language-Integrated Query (LINQ) syntax: - - [!code-vb[VbVbalrLambdas#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class5.vb#11)] - +A *lambda expression* is a function or subroutine that does not have a name. A lambda expression can be used wherever a delegate type is valid. + +### To create a single-line lambda expression function + +1. In any situation where a delegate type could be used, type the keyword `Function`, as in the following example: + + `Dim add1 =` `Function` + +2. In parentheses, directly after `Function`, type the parameters of the function. Notice that you do not specify a name after `Function`. + + `Dim add1 = Function` `(num As Integer)` + +3. Following the parameter list, type a single expression as the body of the function. The value that the expression evaluates to is the value returned by the function. You do not use an `As` clause to specify the return type. + + [!code-vb[VbVbalrLambdas#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#1)] + + You call the lambda expression by passing in an integer argument. + + [!code-vb[VbVbalrLambdas#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#2)] + +4. Alternatively, the same result is accomplished by the following example: + + [!code-vb[VbVbalrLambdas#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#3)] + +### To create a single-line lambda expression subroutine + +1. In any situation where a delegate type could be used, type the keyword `Sub`, as shown in the following example. + + `Dim add1 =` `Sub` + +2. In parentheses, directly after `Sub`, type the parameters of the subroutine. Notice that you do not specify a name after `Sub`. + + `Dim add1 = Sub` `(msg As String)` + +3. Following the parameter list, type a single statement as the body of the subroutine. + + [!code-vb[VbVbalrLambdas#17](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#17)] + + You call the lambda expression by passing in a string argument. + + [!code-vb[VbVbalrLambdas#18](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#18)] + +### To create a multiline lambda expression function + +1. In any situation where a delegate type could be used, type the keyword `Function`, as shown in the following example. + + `Dim add1 =` `Function` + +2. In parentheses, directly after `Function`, type the parameters of the function. Notice that you do not specify a name after `Function`. + + `Dim add1 = Function` `(index As Integer)` + +3. Press ENTER. The `End Function` statement is automatically added. + +4. Within the body of the function, add the following code to create an expression and return the value. You do not use an `As` clause to specify the return type. + + [!code-vb[VbVbalrLambdas#19](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#19)] + + You call the lambda expression by passing in an integer argument. + + [!code-vb[VbVbalrLambdas#20](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#20)] + +### To create a multiline lambda expression subroutine + +1. In any situation where a delegate type could be used, type the keyword `Sub`, as shown in the following example: + + `Dim add1 =` `Sub` + +2. In parentheses, directly after `Sub`, type the parameters of the subroutine. Notice that you do not specify a name after `Sub`. + + `Dim add1 = Sub` `(msg As String)` + +3. Press ENTER. The `End Sub` statement is automatically added. + +4. Within the body of the function, add the following code to execute when the subroutine is invoked. + + [!code-vb[VbVbalrLambdas#21](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#21)] + + You call the lambda expression by passing in a string argument. + + [!code-vb[VbVbalrLambdas#22](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class1.vb#22)] + +## Example + + A common use of lambda expressions is to define a function that can be passed in as the argument for a parameter whose type is `Delegate`. In the following example, the method returns an array of the processes running on the local computer. The method from the class requires a `Boolean` delegate as its argument. The lambda expression in the example is used for that purpose. It returns `True` for each process that has only one thread, and those are selected in `filteredList`. + + [!code-vb[VbVbalrLambdas#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class4.vb#10)] + + The previous example is equivalent to the following code, which is written in Language-Integrated Query (LINQ) syntax: + + [!code-vb[VbVbalrLambdas#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrLambdas/VB/Class5.vb#11)] + ## See also - diff --git a/docs/visual-basic/programming-guide/language-features/procedures/how-to-declare-and-call-a-default-property.md b/docs/visual-basic/programming-guide/language-features/procedures/how-to-declare-and-call-a-default-property.md index a7e77f43b71c1..622f2adc4b497 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/how-to-declare-and-call-a-default-property.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/how-to-declare-and-call-a-default-property.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Declare and Call a Default Property in Visual Basic" title: "How to: Declare and Call a Default Property" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "defaults [Visual Basic], properties" - "properties [Visual Basic], default" - "procedures [Visual Basic], defining" @@ -14,72 +14,72 @@ ms.assetid: 68b4026e-09ef-4613-808e-f6287494ff63 --- # How to: Declare and Call a Default Property in Visual Basic -A *default property* is a class or structure property that your code can access without specifying it. When calling code names a class or structure but not a property, and the context allows access to a property, Visual Basic resolves the access to that class or structure's default property if one exists. - - A class or structure can have at most one default property. However, you can overload a default property and have more than one version of it. - - For more information, see [Default](../../../language-reference/modifiers/default.md). - -### To declare a default property - -1. Declare the property in the normal way. Do not specify the `Shared` or `Private` keyword. - -2. Include the `Default` keyword in the property declaration. - -3. Specify at least one parameter for the property. You cannot define a default property that does not take at least one argument. - - [!code-vb[VbVbcnProcedures#17](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#17)] - -### To call a default property - -1. Declare a variable of the containing class or structure type. - - [!code-vb[VbVbcnProcedures#16](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#16)] - -2. Use the variable name alone in an expression where you would normally include the property name. - - [!code-vb[VbVbcnProcedures#21](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#21)] - -3. Follow the variable name with an argument list in parentheses. A default property must take at least one argument. - - [!code-vb[VbVbcnProcedures#20](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#20)] - -4. To retrieve the default property value, use the variable name, with an argument list, in an expression or following the equal (`=`) sign in an assignment statement. - - [!code-vb[VbVbcnProcedures#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#15)] - -5. To set the default property value, use the variable name, with an argument list, on the left side of an assignment statement. - - [!code-vb[VbVbcnProcedures#14](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#14)] - -6. You can always specify the default property name together with the variable name, just as you would do to access any other property. - - [!code-vb[VbVbcnProcedures#19](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#19)] - +A *default property* is a class or structure property that your code can access without specifying it. When calling code names a class or structure but not a property, and the context allows access to a property, Visual Basic resolves the access to that class or structure's default property if one exists. + + A class or structure can have at most one default property. However, you can overload a default property and have more than one version of it. + + For more information, see [Default](../../../language-reference/modifiers/default.md). + +### To declare a default property + +1. Declare the property in the normal way. Do not specify the `Shared` or `Private` keyword. + +2. Include the `Default` keyword in the property declaration. + +3. Specify at least one parameter for the property. You cannot define a default property that does not take at least one argument. + + [!code-vb[VbVbcnProcedures#17](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#17)] + +### To call a default property + +1. Declare a variable of the containing class or structure type. + + [!code-vb[VbVbcnProcedures#16](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#16)] + +2. Use the variable name alone in an expression where you would normally include the property name. + + [!code-vb[VbVbcnProcedures#21](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#21)] + +3. Follow the variable name with an argument list in parentheses. A default property must take at least one argument. + + [!code-vb[VbVbcnProcedures#20](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#20)] + +4. To retrieve the default property value, use the variable name, with an argument list, in an expression or following the equal (`=`) sign in an assignment statement. + + [!code-vb[VbVbcnProcedures#15](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#15)] + +5. To set the default property value, use the variable name, with an argument list, on the left side of an assignment statement. + + [!code-vb[VbVbcnProcedures#14](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#14)] + +6. You can always specify the default property name together with the variable name, just as you would do to access any other property. + + [!code-vb[VbVbcnProcedures#19](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#19)] + ## Example 1 - The following example declares a default property on a class. - - [!code-vb[VbVbcnProcedures#12](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#12)] - -## Example 2 - - The following example demonstrates how to call the default property `myProperty` on class `class1`. The three assignment statements store values in `myProperty`, and the call reads the values. - - [!code-vb[VbVbcnProcedures#13](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#13)] - - The most common use of a default property is the property on various collection classes. - -## Robust Programming - - Default properties can result in a small reduction in source code-characters, but they can make your code more difficult to read. If the calling code is not familiar with your class or structure, when it makes a reference to the class or structure name it cannot be certain whether that reference accesses the class or structure itself, or a default property. This can lead to compiler errors or subtle run-time logic errors. - - You can somewhat reduce the chance of default property errors by always using the [Option Strict Statement](../../../language-reference/statements/option-strict-statement.md) to set compiler type checking to `On`. - - If you are planning to use a predefined class or structure in your code, you must determine whether it has a default property, and if so, what its name is. - - Because of these disadvantages, you should consider not defining default properties. For code readability, you should also consider always referring to all properties explicitly, even default properties. - + The following example declares a default property on a class. + + [!code-vb[VbVbcnProcedures#12](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#12)] + +## Example 2 + + The following example demonstrates how to call the default property `myProperty` on class `class1`. The three assignment statements store values in `myProperty`, and the call reads the values. + + [!code-vb[VbVbcnProcedures#13](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#13)] + + The most common use of a default property is the property on various collection classes. + +## Robust Programming + + Default properties can result in a small reduction in source code-characters, but they can make your code more difficult to read. If the calling code is not familiar with your class or structure, when it makes a reference to the class or structure name it cannot be certain whether that reference accesses the class or structure itself, or a default property. This can lead to compiler errors or subtle run-time logic errors. + + You can somewhat reduce the chance of default property errors by always using the [Option Strict Statement](../../../language-reference/statements/option-strict-statement.md) to set compiler type checking to `On`. + + If you are planning to use a predefined class or structure in your code, you must determine whether it has a default property, and if so, what its name is. + + Because of these disadvantages, you should consider not defining default properties. For code readability, you should also consider always referring to all properties explicitly, even default properties. + ## See also - [Property Procedures](./property-procedures.md) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/how-to-pass-arguments-to-a-procedure.md b/docs/visual-basic/programming-guide/language-features/procedures/how-to-pass-arguments-to-a-procedure.md index deab747a348d3..227dcf12e7de5 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/how-to-pass-arguments-to-a-procedure.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/how-to-pass-arguments-to-a-procedure.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Pass Arguments to a Procedure (Visual Basic)" title: "How to: Pass Arguments to a Procedure" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "arguments [Visual Basic], passing to procedures" - "procedures [Visual Basic], arguments" - "procedures [Visual Basic], parameters" @@ -15,32 +15,32 @@ ms.assetid: 08723588-3890-4ddc-8249-79e049e0f241 --- # How to: Pass Arguments to a Procedure (Visual Basic) -When you call a procedure, you follow the procedure name with an argument list in parentheses. You supply an argument corresponding to every required parameter the procedure defines, and you can optionally supply arguments to the `Optional` parameters. If you do not supply an `Optional` parameter in the call, you must include a comma to mark its place in the argument list if you are supplying any subsequent arguments. - - If you intend to pass an argument of a data type different from that of its corresponding parameter, such as `Byte` to `String`, you can set the type-checking switch ([Option Strict Statement](../../../language-reference/statements/option-strict-statement.md)) to `Off`. If `Option Strict` is `On`, you must use either widening conversions or explicit conversion keywords. For more information, see [Widening and Narrowing Conversions](../data-types/widening-and-narrowing-conversions.md) and [Type Conversion Functions](../../../language-reference/functions/type-conversion-functions.md). - - For more information, see [Procedure Parameters and Arguments](./procedure-parameters-and-arguments.md). - -### To pass one or more arguments to a procedure - -1. In the calling statement, follow the procedure name with parentheses. - -2. Inside the parentheses, put an argument list. Include an argument for each required parameter the procedure defines, and separate the arguments with commas. - -3. Make sure each argument is a valid expression that evaluates to a data type convertible to the type the procedure defines for the corresponding parameter. - -4. If a parameter is defined as [Optional](../../../language-reference/modifiers/optional.md), you can either include it in the argument list or omit it. If you omit it, the procedure uses the default value defined for that parameter. - -5. If you omit an argument for an `Optional` parameter and there is another parameter after it in the parameter list, you can mark the place of the omitted argument by an extra comma in the argument list. - - The following example calls the Visual Basic function. - - [!code-vb[VbVbcnProcedures#34](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#34)] - - The preceding example supplies the required first argument, which is the message string to be displayed. It omits an argument for the optional second parameter, which specifies the buttons to be displayed on the message box. Because the call does not supply a value, `MsgBox` uses the default value, `MsgBoxStyle.OKOnly`, which displays only an **OK** button. - - The second comma in the argument list marks the place of the omitted second argument, and the last string is passed to the optional third parameter of `MsgBox`, which is the text to be displayed in the title bar. - +When you call a procedure, you follow the procedure name with an argument list in parentheses. You supply an argument corresponding to every required parameter the procedure defines, and you can optionally supply arguments to the `Optional` parameters. If you do not supply an `Optional` parameter in the call, you must include a comma to mark its place in the argument list if you are supplying any subsequent arguments. + + If you intend to pass an argument of a data type different from that of its corresponding parameter, such as `Byte` to `String`, you can set the type-checking switch ([Option Strict Statement](../../../language-reference/statements/option-strict-statement.md)) to `Off`. If `Option Strict` is `On`, you must use either widening conversions or explicit conversion keywords. For more information, see [Widening and Narrowing Conversions](../data-types/widening-and-narrowing-conversions.md) and [Type Conversion Functions](../../../language-reference/functions/type-conversion-functions.md). + + For more information, see [Procedure Parameters and Arguments](./procedure-parameters-and-arguments.md). + +### To pass one or more arguments to a procedure + +1. In the calling statement, follow the procedure name with parentheses. + +2. Inside the parentheses, put an argument list. Include an argument for each required parameter the procedure defines, and separate the arguments with commas. + +3. Make sure each argument is a valid expression that evaluates to a data type convertible to the type the procedure defines for the corresponding parameter. + +4. If a parameter is defined as [Optional](../../../language-reference/modifiers/optional.md), you can either include it in the argument list or omit it. If you omit it, the procedure uses the default value defined for that parameter. + +5. If you omit an argument for an `Optional` parameter and there is another parameter after it in the parameter list, you can mark the place of the omitted argument by an extra comma in the argument list. + + The following example calls the Visual Basic function. + + [!code-vb[VbVbcnProcedures#34](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#34)] + + The preceding example supplies the required first argument, which is the message string to be displayed. It omits an argument for the optional second parameter, which specifies the buttons to be displayed on the message box. Because the call does not supply a value, `MsgBox` uses the default value, `MsgBoxStyle.OKOnly`, which displays only an **OK** button. + + The second comma in the argument list marks the place of the omitted second argument, and the last string is passed to the optional third parameter of `MsgBox`, which is the text to be displayed in the title bar. + ## See also - [Sub Procedures](./sub-procedures.md) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/how-to-put-a-value-in-a-property.md b/docs/visual-basic/programming-guide/language-features/procedures/how-to-put-a-value-in-a-property.md index 0efdbfde2f63a..91860f69334e9 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/how-to-put-a-value-in-a-property.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/how-to-put-a-value-in-a-property.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Put a Value in a Property (Visual Basic)" title: "How to: Put a Value in a Property" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "property values [Visual Basic]" - "Visual Basic code, procedures" - "values [Visual Basic], properties" @@ -12,27 +12,27 @@ ms.assetid: c39401e5-b5fc-4439-8f31-ed640f7ce6ed --- # How to: Put a Value in a Property (Visual Basic) -You store a value in a property by putting the property name on the left side of an assignment statement. - - The property's `Set` procedure stores a value, but you do not explicitly call it by name. You use the property just as you would use a variable. Visual Basic makes the calls to the property's procedures. - -### To store a value in a property - -1. Use the property name on the left side of an assignment statement. - - The following example sets the value of the Visual Basic `TimeOfDay` property to noon, implicitly calling its `Set` procedure. - - [!code-vb[VbVbcnProcedures#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#11)] - -2. If the property takes arguments, follow the property name with parentheses to enclose the argument list. If there are no arguments, you can optionally omit the parentheses. - -3. Place the arguments in the argument list within the parentheses, separated by commas. Be sure you supply the arguments in the same order that the property defines the corresponding parameters. - -4. The value generated on the right side of the assignment statement is stored in the property. - +You store a value in a property by putting the property name on the left side of an assignment statement. + + The property's `Set` procedure stores a value, but you do not explicitly call it by name. You use the property just as you would use a variable. Visual Basic makes the calls to the property's procedures. + +### To store a value in a property + +1. Use the property name on the left side of an assignment statement. + + The following example sets the value of the Visual Basic `TimeOfDay` property to noon, implicitly calling its `Set` procedure. + + [!code-vb[VbVbcnProcedures#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#11)] + +2. If the property takes arguments, follow the property name with parentheses to enclose the argument list. If there are no arguments, you can optionally omit the parentheses. + +3. Place the arguments in the argument list within the parentheses, separated by commas. Be sure you supply the arguments in the same order that the property defines the corresponding parameters. + +4. The value generated on the right side of the assignment statement is stored in the property. + ## See also -- +- - [Property Procedures](./property-procedures.md) - [Procedure Parameters and Arguments](./procedure-parameters-and-arguments.md) - [Property Statement](../../../language-reference/statements/property-statement.md) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/how-to-use-a-class-that-defines-operators.md b/docs/visual-basic/programming-guide/language-features/procedures/how-to-use-a-class-that-defines-operators.md index c35f452a53437..c49797b76e2aa 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/how-to-use-a-class-that-defines-operators.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/how-to-use-a-class-that-defines-operators.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Use a Class that Defines Operators (Visual Basic)" title: "How to: Use a Class that Defines Operators" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "operator procedures [Visual Basic], calling" - "procedures [Visual Basic], operator" - "procedures [Visual Basic], calling" @@ -15,28 +15,28 @@ ms.assetid: 7ccce94a-6ca0-47d1-9f3f-13385d34f5d5 --- # How to: Use a Class that Defines Operators (Visual Basic) -If you are using a class or structure that defines its own operators, you can access those operators from Visual Basic. - - Defining an operator on a class or structure is also called *overloading* the operator. - -## Example - - The following example accesses the SQL structure , which defines the conversion operators ([CType Function](../../../language-reference/operators/ctype-operator.md)) in both directions between a SQL string and a Visual Basic string. Use `CType(`*SQL string expression*, `String)` to convert a SQL string to a Visual Basic string, and `CType(`*Visual Basic string expression*, `)` to convert in the other direction. - - [!code-vb[VbVbcnProcedures#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#30)] - - [!code-vb[VbVbcnProcedures#31](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#31)] - - The structure defines a conversion operator ([CType Function](../../../language-reference/operators/ctype-operator.md)) from `String` to and another from to `String`. The statement that assigns `title` to `jobTitle` makes use of the first operator, and the function call uses the second. - -## Compile the code - - Be sure the class or structure you are using defines the operator you want to use. Do not assume that the class or structure has defined every operator available for overloading. For a list of available operators, see [Operator Statement](../../../language-reference/statements/operator-statement.md). - - Include the appropriate `Imports` statement for the SQL string at the beginning of your source file (in this case ). - - Your project must have references to System.Data and System.XML. - +If you are using a class or structure that defines its own operators, you can access those operators from Visual Basic. + + Defining an operator on a class or structure is also called *overloading* the operator. + +## Example + + The following example accesses the SQL structure , which defines the conversion operators ([CType Function](../../../language-reference/operators/ctype-operator.md)) in both directions between a SQL string and a Visual Basic string. Use `CType(`*SQL string expression*, `String)` to convert a SQL string to a Visual Basic string, and `CType(`*Visual Basic string expression*, `)` to convert in the other direction. + + [!code-vb[VbVbcnProcedures#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#30)] + + [!code-vb[VbVbcnProcedures#31](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#31)] + + The structure defines a conversion operator ([CType Function](../../../language-reference/operators/ctype-operator.md)) from `String` to and another from to `String`. The statement that assigns `title` to `jobTitle` makes use of the first operator, and the function call uses the second. + +## Compile the code + + Be sure the class or structure you are using defines the operator you want to use. Do not assume that the class or structure has defined every operator available for overloading. For a list of available operators, see [Operator Statement](../../../language-reference/statements/operator-statement.md). + + Include the appropriate `Imports` statement for the SQL string at the beginning of your source file (in this case ). + + Your project must have references to System.Data and System.XML. + ## See also - [Operator Procedures](./operator-procedures.md) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/parameter-arrays.md b/docs/visual-basic/programming-guide/language-features/procedures/parameter-arrays.md index dc70ec9ab8ffb..47fd02003d16a 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/parameter-arrays.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/parameter-arrays.md @@ -2,7 +2,7 @@ description: "Learn more about: Parameter Arrays (Visual Basic)" title: "Parameter Arrays" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "parameter arrays [Visual Basic], about parameter arrays" - "ParamArray keyword [Visual Basic], parameter arrays" - "Visual Basic code, procedures" @@ -14,50 +14,50 @@ ms.assetid: c43edfae-9114-4096-9ebc-8c5c957a1067 --- # Parameter Arrays (Visual Basic) -Usually, you cannot call a procedure with more arguments than the procedure declaration specifies. When you need an indefinite number of arguments, you can declare a *parameter array*, which allows a procedure to accept an array of values for a parameter. You do not have to know the number of elements in the parameter array when you define the procedure. The array size is determined individually by each call to the procedure. - -## Declaring a ParamArray - - You use the [ParamArray](../../../language-reference/modifiers/paramarray.md) keyword to denote a parameter array in the parameter list. The following rules apply: - -- A procedure can define only one parameter array, and it must be the last parameter in the procedure definition. - -- The parameter array must be passed by value. It is good programming practice to explicitly include the [ByVal](../../../language-reference/modifiers/byval.md) keyword in the procedure definition. - -- The parameter array is automatically optional. Its default value is an empty one-dimensional array of the parameter array's element type. - -- All parameters preceding the parameter array must be required. The parameter array must be the only optional parameter. - -## Calling a ParamArray - - When you call a procedure that defines a parameter array, you can supply the argument in any one of the following ways: - +Usually, you cannot call a procedure with more arguments than the procedure declaration specifies. When you need an indefinite number of arguments, you can declare a *parameter array*, which allows a procedure to accept an array of values for a parameter. You do not have to know the number of elements in the parameter array when you define the procedure. The array size is determined individually by each call to the procedure. + +## Declaring a ParamArray + + You use the [ParamArray](../../../language-reference/modifiers/paramarray.md) keyword to denote a parameter array in the parameter list. The following rules apply: + +- A procedure can define only one parameter array, and it must be the last parameter in the procedure definition. + +- The parameter array must be passed by value. It is good programming practice to explicitly include the [ByVal](../../../language-reference/modifiers/byval.md) keyword in the procedure definition. + +- The parameter array is automatically optional. Its default value is an empty one-dimensional array of the parameter array's element type. + +- All parameters preceding the parameter array must be required. The parameter array must be the only optional parameter. + +## Calling a ParamArray + + When you call a procedure that defines a parameter array, you can supply the argument in any one of the following ways: + - Nothing — that is, you can omit the [ParamArray](../../../language-reference/modifiers/paramarray.md) argument. In this case, an empty array is passed to the procedure. If you explicitly pass the [Nothing](../../../language-reference/nothing.md) keyword, a null array is passed to the procedure and may result in a NullReferenceException if the called procedure does not check for this condition. - -- A list of an arbitrary number of arguments, separated by commas. The data type of each argument must be implicitly convertible to the `ParamArray` element type. - -- An array with the same element type as the parameter array's element type. - - In all cases, the code within the procedure treats the parameter array as a one-dimensional array with elements of the same data type as the `ParamArray` data type. - + +- A list of an arbitrary number of arguments, separated by commas. The data type of each argument must be implicitly convertible to the `ParamArray` element type. + +- An array with the same element type as the parameter array's element type. + + In all cases, the code within the procedure treats the parameter array as a one-dimensional array with elements of the same data type as the `ParamArray` data type. + > [!IMPORTANT] -> Whenever you deal with an array which can be indefinitely large, there is a risk of overrunning some internal capacity of your application. If you accept a parameter array, you should test for the size of the array that the calling code passed to it. Take appropriate steps if it is too large for your application. For more information, see [Arrays](../arrays/index.md). - -## Example - - The following example defines and calls the function `calcSum`. The `ParamArray` modifier for the parameter `args` enables the function to accept a variable number of arguments. - - [!code-vb[VbVbalrStatements#26](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#26)] - - The following example defines a procedure with a parameter array, and outputs the values of all the array elements passed to the parameter array. - - [!code-vb[VbVbcnProcedures#48](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#48)] - - [!code-vb[VbVbcnProcedures#49](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#49)] - +> Whenever you deal with an array which can be indefinitely large, there is a risk of overrunning some internal capacity of your application. If you accept a parameter array, you should test for the size of the array that the calling code passed to it. Take appropriate steps if it is too large for your application. For more information, see [Arrays](../arrays/index.md). + +## Example + + The following example defines and calls the function `calcSum`. The `ParamArray` modifier for the parameter `args` enables the function to accept a variable number of arguments. + + [!code-vb[VbVbalrStatements#26](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStatements/VB/Class1.vb#26)] + + The following example defines a procedure with a parameter array, and outputs the values of all the array elements passed to the parameter array. + + [!code-vb[VbVbcnProcedures#48](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#48)] + + [!code-vb[VbVbcnProcedures#49](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#49)] + ## See also -- +- - [Procedures](./index.md) - [Procedure Parameters and Arguments](./procedure-parameters-and-arguments.md) - [Passing Arguments by Value and by Reference](./passing-arguments-by-value-and-by-reference.md) diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md b/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md index 3567e027fe4a9..8d2e8bd0721bb 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md @@ -2,83 +2,83 @@ description: "Learn more about: How Culture Affects Strings in Visual Basic" title: "How Culture Affects Strings" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "locale [Visual Basic], effect on strings" - "strings [Visual Basic], locale dependence" ms.assetid: c4664444-ee0d-47bf-bef1-eaa3c54bdd7f --- # How Culture Affects Strings in Visual Basic -This Help page discusses how Visual Basic uses culture information to perform string conversions and comparisons. - -## When to Use Culture-Specific Strings - - Typically, you should use culture-specific strings for all data presented to and read from users, and use culture-invariant strings for your application's internal data. - - For example, if your application asks users to enter a date as a string, it should expect users to format the strings according to their culture, and the application should convert the string appropriately. If your application then presents that date in its user interface, it should present it in the user's culture. - - However, if the application uploads the date to a central server, it should format the string according to one specific culture, to prevent confusion between potentially different date formats. - -## Culture-Sensitive Functions - - All of the Visual Basic string-conversion functions (except for the `Str` and `Val` functions) use the application's culture information to make sure that the conversions and comparisons are appropriate for the culture of the application's user. - - The key to successfully using string-conversion functions in applications that run on computers with different culture settings is to understand which functions use a specific culture setting, and which use the current culture setting. Notice that the application's culture settings are, by default, inherited from the culture settings of the operating system. For more information, see , , , , , , , and [Type Conversion Functions](../../../language-reference/functions/type-conversion-functions.md). - - The `Str` (converts numbers to strings) and `Val` (converts strings to numbers) functions do not use the application's culture information when converting between strings and numbers. Instead, they recognize only the period (.) as a valid decimal separator. The culturally-aware analogues of these functions are: - -- **Conversions that use the current culture.** The `CStr` and `Format` functions convert a number to a string, and the `CDbl` and `CInt` functions convert a string to a number. - -- **Conversions that use a specific culture.** Each number object has a `ToString(IFormatProvider)` method that converts a number to a string, and a `Parse(String, IFormatProvider)` method that converts a string to a number. For example, the `Double` type provides the and methods. - - For more information, see and . - -## Using a Specific Culture - - Imagine that you are developing an application that sends a date (formatted as a string) to a Web service. In this case, your application must use a specific culture for the string conversion. To illustrate why, consider the result of using the date's method: If your application uses that method to format the date July 4, 2005, it returns "7/4/2005 12:00:00 AM" when run with the United States English (en-US) culture, but it returns "04.07.2005 00:00:00" when run with the German (de-DE) culture. - - When you need to perform a string conversion in a specific culture format, you should use the `CultureInfo` class that is built into the .NET Framework. You can create a new `CultureInfo` object for a specific culture by passing the culture's name to the constructor. The supported culture names are listed in the class Help page. - - Alternatively, you can get an instance of the *invariant culture* from the property. The invariant culture is based on the English culture, but there are some differences. For example, the invariant culture specifies a 24-hour clock instead of a 12-hour clock. - - To convert a date to the culture's string, pass the object to the date object's method. For example, the following code displays "07/04/2005 00:00:00", regardless of the application's culture settings. - - [!code-vb[VbVbalrConcepts#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrConcepts/VB/Class1.vb#1)] - +This Help page discusses how Visual Basic uses culture information to perform string conversions and comparisons. + +## When to Use Culture-Specific Strings + + Typically, you should use culture-specific strings for all data presented to and read from users, and use culture-invariant strings for your application's internal data. + + For example, if your application asks users to enter a date as a string, it should expect users to format the strings according to their culture, and the application should convert the string appropriately. If your application then presents that date in its user interface, it should present it in the user's culture. + + However, if the application uploads the date to a central server, it should format the string according to one specific culture, to prevent confusion between potentially different date formats. + +## Culture-Sensitive Functions + + All of the Visual Basic string-conversion functions (except for the `Str` and `Val` functions) use the application's culture information to make sure that the conversions and comparisons are appropriate for the culture of the application's user. + + The key to successfully using string-conversion functions in applications that run on computers with different culture settings is to understand which functions use a specific culture setting, and which use the current culture setting. Notice that the application's culture settings are, by default, inherited from the culture settings of the operating system. For more information, see , , , , , , , and [Type Conversion Functions](../../../language-reference/functions/type-conversion-functions.md). + + The `Str` (converts numbers to strings) and `Val` (converts strings to numbers) functions do not use the application's culture information when converting between strings and numbers. Instead, they recognize only the period (.) as a valid decimal separator. The culturally-aware analogues of these functions are: + +- **Conversions that use the current culture.** The `CStr` and `Format` functions convert a number to a string, and the `CDbl` and `CInt` functions convert a string to a number. + +- **Conversions that use a specific culture.** Each number object has a `ToString(IFormatProvider)` method that converts a number to a string, and a `Parse(String, IFormatProvider)` method that converts a string to a number. For example, the `Double` type provides the and methods. + + For more information, see and . + +## Using a Specific Culture + + Imagine that you are developing an application that sends a date (formatted as a string) to a Web service. In this case, your application must use a specific culture for the string conversion. To illustrate why, consider the result of using the date's method: If your application uses that method to format the date July 4, 2005, it returns "7/4/2005 12:00:00 AM" when run with the United States English (en-US) culture, but it returns "04.07.2005 00:00:00" when run with the German (de-DE) culture. + + When you need to perform a string conversion in a specific culture format, you should use the `CultureInfo` class that is built into the .NET Framework. You can create a new `CultureInfo` object for a specific culture by passing the culture's name to the constructor. The supported culture names are listed in the class Help page. + + Alternatively, you can get an instance of the *invariant culture* from the property. The invariant culture is based on the English culture, but there are some differences. For example, the invariant culture specifies a 24-hour clock instead of a 12-hour clock. + + To convert a date to the culture's string, pass the object to the date object's method. For example, the following code displays "07/04/2005 00:00:00", regardless of the application's culture settings. + + [!code-vb[VbVbalrConcepts#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrConcepts/VB/Class1.vb#1)] + > [!NOTE] -> Date literals are always interpreted according to the English culture. - -## Comparing Strings - - There are two important situations where string comparisons are needed: - -- **Sorting data for display to the user.** Use operations based on the current culture so the strings sort appropriately. - -- **Determining if two application-internal strings exactly match (typically for security purposes).** Use operations that disregard the current culture. - - You can perform both types of comparisons with the Visual Basic function. Specify the optional `Compare` argument to control the type of comparison: `Text` for most input and output `Binary` for determining exact matches. - - The `StrComp` function returns an integer that indicates the relationship between the two compared strings based on the sorting order. A positive value for the result indicates that the first string is greater than the second string. A negative result indicates the first string is smaller, and zero indicates equality between the strings. - - [!code-vb[VbVbalrStrings#22](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class1.vb#22)] - - You can also use the .NET Framework partner of the `StrComp` function, the method. This is a static, overloaded method of the base string class. The following example illustrates how this method is used: - - [!code-vb[VbVbalrStrings#48](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class2.vb#48)] - - For finer control over how the comparisons are performed, you can use additional overloads of the method. With the method, you can use the `comparisonType` argument to specify which type of comparison to use. - -|Value for `comparisonType` argument|Type of comparison|When to use| -|---|---|---| -|`Ordinal`|Comparison based on strings' component bytes.|Use this value when comparing: case-sensitive identifiers, security-related settings, or other non-linguistic identifiers where the bytes must match exactly.| -|`OrdinalIgnoreCase`|Comparison based on strings' component bytes.

`OrdinalIgnoreCase` uses the invariant culture information to determine when two characters differ only in capitalization.|Use this value when comparing: case-insensitive identifiers, security-related settings, and data stored in Windows.| -|`CurrentCulture` or `CurrentCultureIgnoreCase`|Comparison based on the strings' interpretation in the current culture.|Use these values when comparing: data that is displayed to the user, most user input, and other data that requires linguistic interpretation.| -|`InvariantCulture` or `InvariantCultureIgnoreCase`|Comparison based on the strings' interpretation in the invariant culture.

This is different than the `Ordinal` and `OrdinalIgnoreCase`, because the invariant culture treats characters outside its accepted range as equivalent invariant characters.|Use these values only when comparing persisting data or displaying linguistically-relevant data that requires a fixed sort order.| - -### Security Considerations - - If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass `Ordinal` or `OrdinalIgnoreCase` for the `comparisonType` argument. - +> Date literals are always interpreted according to the English culture. + +## Comparing Strings + + There are two important situations where string comparisons are needed: + +- **Sorting data for display to the user.** Use operations based on the current culture so the strings sort appropriately. + +- **Determining if two application-internal strings exactly match (typically for security purposes).** Use operations that disregard the current culture. + + You can perform both types of comparisons with the Visual Basic function. Specify the optional `Compare` argument to control the type of comparison: `Text` for most input and output `Binary` for determining exact matches. + + The `StrComp` function returns an integer that indicates the relationship between the two compared strings based on the sorting order. A positive value for the result indicates that the first string is greater than the second string. A negative result indicates the first string is smaller, and zero indicates equality between the strings. + + [!code-vb[VbVbalrStrings#22](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class1.vb#22)] + + You can also use the .NET Framework partner of the `StrComp` function, the method. This is a static, overloaded method of the base string class. The following example illustrates how this method is used: + + [!code-vb[VbVbalrStrings#48](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class2.vb#48)] + + For finer control over how the comparisons are performed, you can use additional overloads of the method. With the method, you can use the `comparisonType` argument to specify which type of comparison to use. + +|Value for `comparisonType` argument|Type of comparison|When to use| +|---|---|---| +|`Ordinal`|Comparison based on strings' component bytes.|Use this value when comparing: case-sensitive identifiers, security-related settings, or other non-linguistic identifiers where the bytes must match exactly.| +|`OrdinalIgnoreCase`|Comparison based on strings' component bytes.

`OrdinalIgnoreCase` uses the invariant culture information to determine when two characters differ only in capitalization.|Use this value when comparing: case-insensitive identifiers, security-related settings, and data stored in Windows.| +|`CurrentCulture` or `CurrentCultureIgnoreCase`|Comparison based on the strings' interpretation in the current culture.|Use these values when comparing: data that is displayed to the user, most user input, and other data that requires linguistic interpretation.| +|`InvariantCulture` or `InvariantCultureIgnoreCase`|Comparison based on the strings' interpretation in the invariant culture.

This is different than the `Ordinal` and `OrdinalIgnoreCase`, because the invariant culture treats characters outside its accepted range as equivalent invariant characters.|Use these values only when comparing persisting data or displaying linguistically-relevant data that requires a fixed sort order.| + +### Security Considerations + + If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass `Ordinal` or `OrdinalIgnoreCase` for the `comparisonType` argument. + ## See also - diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-to-access-characters-in-strings.md b/docs/visual-basic/programming-guide/language-features/strings/how-to-access-characters-in-strings.md index 35ea076a051c2..d8d6b96acb83f 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-to-access-characters-in-strings.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-to-access-characters-in-strings.md @@ -2,32 +2,32 @@ description: "Learn more about: How to: Access Characters in Strings in Visual Basic" title: "How to: Access Characters in Strings" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "strings [Visual Basic], accessing characters" - "characters [Visual Basic], accessing in strings" ms.assetid: 02c5206c-ffab-494d-b648-3b2ea358dc34 --- # How to: Access Characters in Strings in Visual Basic -This example demonstrates how to use the property to access the character at the specified location in a string. - -## Example - - Sometimes it is useful to have data about the characters in your string and the positions of those characters within your string. You can think of a string as an array of characters (`Char` instances); you can retrieve a particular character by referencing the index of that character through the property. - - [!code-vb[VbVbalrStrings#49](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class2.vb#49)] - - The `index` parameter of the property is zero-based. - -## Robust Programming - - The property returns the character at the specified position. However, some Unicode characters can be represented by more than one character. For more information on how to work with Unicode characters, see [How to: Convert a String to an Array of Characters](how-to-convert-a-string-to-an-array-of-characters.md). - - The property throws an exception if the `index` parameter is greater than or equal to the length of the string, or if it is less than zero - +This example demonstrates how to use the property to access the character at the specified location in a string. + +## Example + + Sometimes it is useful to have data about the characters in your string and the positions of those characters within your string. You can think of a string as an array of characters (`Char` instances); you can retrieve a particular character by referencing the index of that character through the property. + + [!code-vb[VbVbalrStrings#49](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class2.vb#49)] + + The `index` parameter of the property is zero-based. + +## Robust Programming + + The property returns the character at the specified position. However, some Unicode characters can be represented by more than one character. For more information on how to work with Unicode characters, see [How to: Convert a String to an Array of Characters](how-to-convert-a-string-to-an-array-of-characters.md). + + The property throws an exception if the `index` parameter is greater than or equal to the length of the string, or if it is less than zero + ## See also -- +- - [How to: Convert a String to an Array of Characters](how-to-convert-a-string-to-an-array-of-characters.md) - [Converting Between Strings and Other Data Types in Visual Basic](converting-between-strings-and-other-data-types.md) - [Strings](index.md) diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-a-string-to-an-array-of-characters.md b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-a-string-to-an-array-of-characters.md index 8d4b43054eac7..602656b3750f5 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-a-string-to-an-array-of-characters.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-a-string-to-an-array-of-characters.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Convert a String to an Array of Characters in Visual Basic" title: "How to: Convert a String to an Array of Characters" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "character arrays [Visual Basic], converting strings" - "arrays [Visual Basic], converting strings to" - "examples [Visual Basic], string conversion" @@ -12,23 +12,23 @@ ms.assetid: 1b54b686-ab29-413b-adce-6bd5422376eb --- # How to: Convert a String to an Array of Characters in Visual Basic -Sometimes it is useful to have data about the characters in your string and the positions of those characters within your string, such as when you are parsing a string. This example shows how you can get an array of the characters in a string by calling the string's method. - +Sometimes it is useful to have data about the characters in your string and the positions of those characters within your string, such as when you are parsing a string. This example shows how you can get an array of the characters in a string by calling the string's method. + ## Example 1 - This example demonstrates how to split a string into a `Char` array, and how to split a string into a `String` array of its Unicode text characters. The reason for this distinction is that Unicode text characters can be composed of two or more `Char` characters (such as a surrogate pair or a combining character sequence). For more information, see and [The Unicode Standard](https://www.unicode.org/standard/standard.html). - - [!code-vb[VbVbalrStrings#75](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class4.vb#75)] - -## Example 2 + This example demonstrates how to split a string into a `Char` array, and how to split a string into a `String` array of its Unicode text characters. The reason for this distinction is that Unicode text characters can be composed of two or more `Char` characters (such as a surrogate pair or a combining character sequence). For more information, see and [The Unicode Standard](https://www.unicode.org/standard/standard.html). + + [!code-vb[VbVbalrStrings#75](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class4.vb#75)] + +## Example 2 + + It is more difficult to split a string into its Unicode text characters, but this is necessary if you need information about the visual representation of a string. This example uses the method to get information about the Unicode text characters that make up a string. + + [!code-vb[VbVbalrStrings#76](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class4.vb#76)] - It is more difficult to split a string into its Unicode text characters, but this is necessary if you need information about the visual representation of a string. This example uses the method to get information about the Unicode text characters that make up a string. - - [!code-vb[VbVbalrStrings#76](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class4.vb#76)] - ## See also -- +- - - [How to: Access Characters in Strings](how-to-access-characters-in-strings.md) - [Converting Between Strings and Other Data Types in Visual Basic](converting-between-strings-and-other-data-types.md) diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-an-array-of-bytes-into-a-string.md b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-an-array-of-bytes-into-a-string.md index ff23526aeff65..8aeb75efdc440 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-an-array-of-bytes-into-a-string.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-an-array-of-bytes-into-a-string.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Convert an Array of Bytes into a String in Visual Basic" title: "How to: Convert an Array of Bytes into a String" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "string conversion [Visual Basic], arrays" - "byte arrays [Visual Basic], converting to strings" - "examples [Visual Basic], strings" @@ -11,32 +11,32 @@ ms.assetid: d0dc8317-9ab3-4324-99f7-3f5788c0e72a --- # How to: Convert an Array of Bytes into a String in Visual Basic -This topic shows how to convert the bytes from a byte array into a string. - -## Example - - This example uses the method of the encoding class to convert all the bytes from a byte array into a string. - - [!code-vb[VbVbalrStrings#72](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class2.vb#72)] - - You can choose from several encoding options to convert a byte array into a string: - -- : Gets an encoding for the ASCII (7-bit) character set. - -- : Gets an encoding for the UTF-16 format using the big-endian byte order. - -- : Gets an encoding for the system's current ANSI code page. - -- : Gets an encoding for the UTF-16 format using the little-endian byte order. - -- : Gets an encoding for the UTF-32 format using the little-endian byte order. - -- : Gets an encoding for the UTF-7 format. - -- : Gets an encoding for the UTF-8 format. - +This topic shows how to convert the bytes from a byte array into a string. + +## Example + + This example uses the method of the encoding class to convert all the bytes from a byte array into a string. + + [!code-vb[VbVbalrStrings#72](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class2.vb#72)] + + You can choose from several encoding options to convert a byte array into a string: + +- : Gets an encoding for the ASCII (7-bit) character set. + +- : Gets an encoding for the UTF-16 format using the big-endian byte order. + +- : Gets an encoding for the system's current ANSI code page. + +- : Gets an encoding for the UTF-16 format using the little-endian byte order. + +- : Gets an encoding for the UTF-32 format using the little-endian byte order. + +- : Gets an encoding for the UTF-7 format. + +- : Gets an encoding for the UTF-8 format. + ## See also - -- +- - [How to: Convert Strings into an Array of Bytes in Visual Basic](how-to-convert-strings-into-an-array-of-bytes.md) diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-hexadecimal-strings-to-numbers.md b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-hexadecimal-strings-to-numbers.md index efd402f5e650d..b400572586820 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-hexadecimal-strings-to-numbers.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-hexadecimal-strings-to-numbers.md @@ -12,7 +12,7 @@ ms.assetid: 76675807-eadb-4c08-bd50-e6c6ff4b8ced --- # How to: Convert Hexadecimal Strings to Numbers (Visual Basic) -This example converts a hexadecimal string to an integer using the method. +This example converts a hexadecimal string to an integer using the method. ## To convert a hexadecimal string to a number @@ -31,5 +31,5 @@ This example converts a hexadecimal string to an integer using the -- +- +- diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-strings-into-an-array-of-bytes.md b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-strings-into-an-array-of-bytes.md index 3edd7bb7a4ecb..e49e539aeb569 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-strings-into-an-array-of-bytes.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-strings-into-an-array-of-bytes.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Convert Strings into an Array of Bytes in Visual Basic" title: "How to: Convert Strings into an Array of Bytes" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "string conversion [Visual Basic], arrays" - "arrays [Visual Basic], converting strings to" - "byte arrays" @@ -12,32 +12,32 @@ ms.assetid: f477d35c-a3fc-4a30-b1d4-cd0d353aae1d --- # How to: Convert Strings into an Array of Bytes in Visual Basic -This topic shows how to convert a string into an array of bytes. - -## Example - - This example uses the method of the encoding class to convert a string into an array of bytes. - - [!code-vb[VbVbalrStrings#74](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class2.vb#74)] - - You can choose from several encoding options to convert a string into a byte array: - -- : Gets an encoding for the ASCII (7-bit) character set. - -- : Gets an encoding for the UTF-16 format using the big-endian byte order. - -- : Gets an encoding for the system's current ANSI code page. - -- : Gets an encoding for the UTF-16 format using the little-endian byte order. - -- : Gets an encoding for the UTF-32 format using the little-endian byte order. - -- : Gets an encoding for the UTF-7 format. - -- : Gets an encoding for the UTF-8 format. - +This topic shows how to convert a string into an array of bytes. + +## Example + + This example uses the method of the encoding class to convert a string into an array of bytes. + + [!code-vb[VbVbalrStrings#74](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class2.vb#74)] + + You can choose from several encoding options to convert a string into a byte array: + +- : Gets an encoding for the ASCII (7-bit) character set. + +- : Gets an encoding for the UTF-16 format using the big-endian byte order. + +- : Gets an encoding for the system's current ANSI code page. + +- : Gets an encoding for the UTF-16 format using the little-endian byte order. + +- : Gets an encoding for the UTF-32 format using the little-endian byte order. + +- : Gets an encoding for the UTF-7 format. + +- : Gets an encoding for the UTF-8 format. + ## See also - -- +- - [How to: Convert an Array of Bytes into a String in Visual Basic](how-to-convert-an-array-of-bytes-into-a-string.md) diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-to-search-within-a-string.md b/docs/visual-basic/programming-guide/language-features/strings/how-to-search-within-a-string.md index 6cd36bd31736c..41e023fee7a14 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-to-search-within-a-string.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-to-search-within-a-string.md @@ -14,23 +14,23 @@ This article shows an example of how to search within a string in Visual Basic. ## Example -This example calls the method on a object to report the index of the first occurrence of a substring: +This example calls the method on a object to report the index of the first occurrence of a substring: [!code-vb[VbVbalrStrings#71](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class2.vb#71)] ## Robust programming -The method returns the location of the first character of the first occurrence of the substring. The index is 0-based, which means the first character of a string has an index of 0. +The method returns the location of the first character of the first occurrence of the substring. The index is 0-based, which means the first character of a string has an index of 0. -If does not find the substring, it returns -1. +If does not find the substring, it returns -1. -The method is case-sensitive and uses the current culture. +The method is case-sensitive and uses the current culture. For optimal error control, you might want to enclose the string search in the `Try` block of a [Try...Catch...Finally Statement](../../../language-reference/statements/try-catch-finally-statement.md) construction. ## See also -- +- - [Try...Catch...Finally Statement](../../../language-reference/statements/try-catch-finally-statement.md) - [Introduction to Strings in Visual Basic](introduction-to-strings.md) - [Strings](index.md) diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-to-validate-file-names-and-paths.md b/docs/visual-basic/programming-guide/language-features/strings/how-to-validate-file-names-and-paths.md index 1be2fb42729ad..f2ce5e85e5ff1 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-to-validate-file-names-and-paths.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-to-validate-file-names-and-paths.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Validate File Names and Paths in Visual Basic" title: "How to: Validate File Names and Paths" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "file names [Visual Basic], validating" - "strings [Visual Basic], validating" - "Boolean values [Visual Basic]" @@ -11,15 +11,15 @@ ms.assetid: f673462d-57b7-4120-b13a-6a7592f7ab2c --- # How to: Validate File Names and Paths in Visual Basic -This example returns a `Boolean` value that indicates whether a string represents a file name or path. The validation checks if the name contains characters that are not allowed by the file system. - -## Example +This example returns a `Boolean` value that indicates whether a string represents a file name or path. The validation checks if the name contains characters that are not allowed by the file system. + +## Example + + [!code-vb[VbVbcnRegEx#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnRegEx/VB/Class1.vb#4)] + + This example does not check if the name has incorrectly placed colons, or directories with no name, or if the length of the name exceeds the system-defined maximum length. It also does not check if the application has permission to access the file-system resource with the specified name. - [!code-vb[VbVbcnRegEx#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnRegEx/VB/Class1.vb#4)] - - This example does not check if the name has incorrectly placed colons, or directories with no name, or if the length of the name exceeds the system-defined maximum length. It also does not check if the application has permission to access the file-system resource with the specified name. - ## See also -- +- - [Validating Strings in Visual Basic](validating-strings.md) diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-to-validate-strings-that-represent-dates-or-times.md b/docs/visual-basic/programming-guide/language-features/strings/how-to-validate-strings-that-represent-dates-or-times.md index 6f1f4140c8b7f..ce4927ebaf144 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-to-validate-strings-that-represent-dates-or-times.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-to-validate-strings-that-represent-dates-or-times.md @@ -2,29 +2,29 @@ description: "Learn more about: How to: Validate Strings That Represent Dates or Times (Visual Basic)" title: "How to: Validate Strings That Represent Dates or Times" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "strings [Visual Basic], validating" - "String data type [Visual Basic], validation" ms.assetid: ae7d4b29-3436-4032-bdbf-4650eb1c8e19 --- # How to: Validate Strings That Represent Dates or Times (Visual Basic) -The following code example sets a `Boolean` value that indicates whether a string represents a valid date or time. - -## Example +The following code example sets a `Boolean` value that indicates whether a string represents a valid date or time. - [!code-vb[VbVbcnRegEx#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnRegEx/VB/Class1.vb#2)] - -## Compile the code +## Example - Replace `("01/01/03")` and `"9:30 PM"` with the date and time you want to validate. You can replace the string with another hard-coded string, with a `String` variable, or with a method that returns a string, such as `InputBox`. - -## Robust Programming + [!code-vb[VbVbcnRegEx#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnRegEx/VB/Class1.vb#2)] + +## Compile the code + + Replace `("01/01/03")` and `"9:30 PM"` with the date and time you want to validate. You can replace the string with another hard-coded string, with a `String` variable, or with a method that returns a string, such as `InputBox`. + +## Robust Programming + + Use this method to validate the string before trying to convert the `String` to a `DateTime` variable. By checking the date or time first, you can avoid generating an exception at run time. - Use this method to validate the string before trying to convert the `String` to a `DateTime` variable. By checking the date or time first, you can avoid generating an exception at run time. - ## See also -- -- +- +- - [Validating Strings in Visual Basic](validating-strings.md) diff --git a/docs/visual-basic/programming-guide/language-features/strings/interpolated-strings.md b/docs/visual-basic/programming-guide/language-features/strings/interpolated-strings.md index a2561699805e3..2a74681fcd56d 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/interpolated-strings.md +++ b/docs/visual-basic/programming-guide/language-features/strings/interpolated-strings.md @@ -63,7 +63,7 @@ There are three implicit type conversions from an interpolated string: 3. Conversion of an interpolated string to a variable that represents a composite format string. Inspecting the composite format string and how it renders as a result string might, for example, help you protect against an injection attack if you were building a query. A also includes: - A overload that produces a result string for the . - - An method that produces a string for the . + - An method that produces a string for the . - A method that produces a result string for a specified culture. All occurrences of double curly braces ("{{" and "}}") remain as double curly braces until you format. All contained interpolation expressions are converted to {0}, {1}, and so on. diff --git a/docs/visual-basic/programming-guide/language-features/strings/types-of-string-manipulation-methods.md b/docs/visual-basic/programming-guide/language-features/strings/types-of-string-manipulation-methods.md index fb0a8f5df48e5..ee796d97c7f8c 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/types-of-string-manipulation-methods.md +++ b/docs/visual-basic/programming-guide/language-features/strings/types-of-string-manipulation-methods.md @@ -31,7 +31,7 @@ There are several different ways to analyze and manipulate your strings. Some of [!code-vb[VbVbalrStrings#45](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class2.vb#45)] - In the preceding example, the method is a shared method that accepts two instances of `String` as arguments. + In the preceding example, the method is a shared method that accepts two instances of `String` as arguments. #### Instance Methods @@ -39,7 +39,7 @@ There are several different ways to analyze and manipulate your strings. Some of [!code-vb[VbVbalrStrings#46](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrStrings/VB/Class2.vb#46)] - In this example, the method is a method of the instance of `String` (that is, `aString`). It performs an operation on `aString` and assigns that value to `bString`. + In this example, the method is a method of the instance of `String` (that is, `aString`). It performs an operation on `aString` and assigns that value to `bString`. For more information, see the documentation for the class. diff --git a/docs/visual-basic/programming-guide/language-features/strings/using-regular-expressions-with-the-maskedtextbox-control.md b/docs/visual-basic/programming-guide/language-features/strings/using-regular-expressions-with-the-maskedtextbox-control.md index 48ce699ae0b88..aa6088ce97fa9 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/using-regular-expressions-with-the-maskedtextbox-control.md +++ b/docs/visual-basic/programming-guide/language-features/strings/using-regular-expressions-with-the-maskedtextbox-control.md @@ -2,60 +2,60 @@ description: "Learn more about: Using Regular Expressions with the MaskedTextBox Control in Visual Basic" title: "Using Regular Expressions with the MaskedTextBox Control" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "strings [Visual Basic], regular expressions" - "strings [Visual Basic], masked edit" ms.assetid: 2a048fb0-7053-487d-b2c5-ffa5e22ed6f9 --- # Using Regular Expressions with the MaskedTextBox Control in Visual Basic -This example demonstrates how to convert simple regular expressions to work with the control. - -## Description of the Masking Language - - The standard masking language is based on the one used by the `Masked Edit` control in Visual Basic 6.0 and should be familiar to users migrating from that platform. - - The property of the control specifies what input mask to use. The mask must be a string composed of one or more of the masking elements from the following table. - -|Masking element|Description|Regular expression element| -|---------------------|-----------------|--------------------------------| -|0|Any single digit between 0 and 9. Entry required.|\d| -|9|Digit or space. Entry optional.|[ \d]?| -|#|Digit or space. Entry optional. If this position is left blank in the mask, it will be rendered as a space. Plus (+) and minus (-) signs are allowed.|[ \d+-]?| -|L|ASCII letter. Entry required.|[a-zA-Z]| -|?|ASCII letter. Entry optional.|[a-zA-Z]?| -|&|Character. Entry required.|[\p{Ll}\p{Lu}\p{Lt}\p{Lm}\p{Lo}]| -|C|Character. Entry optional.|[\p{Ll}\p{Lu}\p{Lt}\p{Lm}\p{Lo}]?| -|A|Alphanumeric. Entry optional.|\W| -|.|Culture-appropriate decimal placeholder.|Not available.| -|,|Culture-appropriate thousands placeholder.|Not available.| -|:|Culture-appropriate time separator.|Not available.| -|/|Culture-appropriate date separator.|Not available.| -|$|Culture-appropriate currency symbol.|Not available.| -|\<|Converts all characters that follow to lowercase.|Not available.| -|>|Converts all characters that follow to uppercase.|Not available.| -|||Undoes a previous shift up or shift down.|Not available.| -|\|Escapes a mask character, turning it into a literal. "\\\\" is the escape sequence for a backslash.|\| -|All other characters.|Literals. All non-mask elements will appear as themselves within .|All other characters.| - - The decimal (.), thousandths (,), time (:), date (/), and currency ($) symbols default to displaying those symbols as defined by the application's culture. You can force them to display symbols for another culture by using the property. - -## Regular Expressions and Masks - - Although you can use regular expressions and masks to validate user input, they are not completely equivalent. Regular expressions can express more complex patterns than masks, but masks can express the same information more succinctly and in a culturally relevant format. - - The following table compares four regular expressions and the equivalent mask for each. - -|Regular Expression|Mask|Notes| -|------------------------|----------|-----------| -|`\d{2}/\d{2}/\d{4}`|`00/00/0000`|The `/` character in the mask is a logical date separator, and it will appear to the user as the date separator appropriate to the application's current culture.| -|`\d{2}-[A-Z][a-z]{2}-\d{4}`|`00->L control. + +## Description of the Masking Language + + The standard masking language is based on the one used by the `Masked Edit` control in Visual Basic 6.0 and should be familiar to users migrating from that platform. + + The property of the control specifies what input mask to use. The mask must be a string composed of one or more of the masking elements from the following table. + +|Masking element|Description|Regular expression element| +|---------------------|-----------------|--------------------------------| +|0|Any single digit between 0 and 9. Entry required.|\d| +|9|Digit or space. Entry optional.|[ \d]?| +|#|Digit or space. Entry optional. If this position is left blank in the mask, it will be rendered as a space. Plus (+) and minus (-) signs are allowed.|[ \d+-]?| +|L|ASCII letter. Entry required.|[a-zA-Z]| +|?|ASCII letter. Entry optional.|[a-zA-Z]?| +|&|Character. Entry required.|[\p{Ll}\p{Lu}\p{Lt}\p{Lm}\p{Lo}]| +|C|Character. Entry optional.|[\p{Ll}\p{Lu}\p{Lt}\p{Lm}\p{Lo}]?| +|A|Alphanumeric. Entry optional.|\W| +|.|Culture-appropriate decimal placeholder.|Not available.| +|,|Culture-appropriate thousands placeholder.|Not available.| +|:|Culture-appropriate time separator.|Not available.| +|/|Culture-appropriate date separator.|Not available.| +|$|Culture-appropriate currency symbol.|Not available.| +|\<|Converts all characters that follow to lowercase.|Not available.| +|>|Converts all characters that follow to uppercase.|Not available.| +|||Undoes a previous shift up or shift down.|Not available.| +|\|Escapes a mask character, turning it into a literal. "\\\\" is the escape sequence for a backslash.|\| +|All other characters.|Literals. All non-mask elements will appear as themselves within .|All other characters.| + + The decimal (.), thousandths (,), time (:), date (/), and currency ($) symbols default to displaying those symbols as defined by the application's culture. You can force them to display symbols for another culture by using the property. + +## Regular Expressions and Masks + + Although you can use regular expressions and masks to validate user input, they are not completely equivalent. Regular expressions can express more complex patterns than masks, but masks can express the same information more succinctly and in a culturally relevant format. + + The following table compares four regular expressions and the equivalent mask for each. + +|Regular Expression|Mask|Notes| +|------------------------|----------|-----------| +|`\d{2}/\d{2}/\d{4}`|`00/00/0000`|The `/` character in the mask is a logical date separator, and it will appear to the user as the date separator appropriate to the application's current culture.| +|`\d{2}-[A-Z][a-z]{2}-\d{4}`|`00->L +- - - [Validating Strings in Visual Basic](validating-strings.md) - [MaskedTextBox Control](/dotnet/desktop/winforms/controls/maskedtextbox-control-windows-forms) diff --git a/docs/visual-basic/programming-guide/language-features/strings/zero-based-vs-one-based-string-access.md b/docs/visual-basic/programming-guide/language-features/strings/zero-based-vs-one-based-string-access.md index 49a805810a09c..df5a1f2bf9093 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/zero-based-vs-one-based-string-access.md +++ b/docs/visual-basic/programming-guide/language-features/strings/zero-based-vs-one-based-string-access.md @@ -2,26 +2,26 @@ description: "Learn more about: Zero-based vs. One-based String Access in Visual Basic" title: "Zero-based vs. One-based String Access" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "strings [Visual Basic], indexing" ms.assetid: 0ed39f35-d68e-421d-ae14-460a5c0373b8 --- # Zero-based vs. One-based String Access in Visual Basic -This topic compares how Visual Basic and the .NET Framework provide access to the characters in a string. The .NET Framework always provides zero-based access to the characters in a string, whereas Visual Basic provides zero-based and one-based access, depending on the function. - -## One-Based +This topic compares how Visual Basic and the .NET Framework provide access to the characters in a string. The .NET Framework always provides zero-based access to the characters in a string, whereas Visual Basic provides zero-based and one-based access, depending on the function. - For an example of a one-based Visual Basic function, consider the `Mid` function. It takes an argument that indicates the character position at which the substring will start, starting with position 1. The .NET Framework method takes an index of the character in the string at which the substring is to start, starting with position 0. Thus, if you have a string "ABCDE", the individual characters are numbered 1,2,3,4,5 for use with the `Mid` function, but 0,1,2,3,4 for use with the method. - -## Zero-Based +## One-Based + + For an example of a one-based Visual Basic function, consider the `Mid` function. It takes an argument that indicates the character position at which the substring will start, starting with position 1. The .NET Framework method takes an index of the character in the string at which the substring is to start, starting with position 0. Thus, if you have a string "ABCDE", the individual characters are numbered 1,2,3,4,5 for use with the `Mid` function, but 0,1,2,3,4 for use with the method. + +## Zero-Based + + For an example of a zero-based Visual Basic function, consider the `Split` function. It splits a string and returns an array containing the substrings. The .NET Framework method also splits a string and returns an array containing the substrings. Because the `Split` function and method return .NET Framework arrays, they must be zero-based. - For an example of a zero-based Visual Basic function, consider the `Split` function. It splits a string and returns an array containing the substrings. The .NET Framework method also splits a string and returns an array containing the substrings. Because the `Split` function and method return .NET Framework arrays, they must be zero-based. - ## See also -- -- -- -- +- +- +- +- - [Introduction to Strings in Visual Basic](introduction-to-strings.md) diff --git a/docs/visual-basic/programming-guide/language-features/variables/how-to-access-members-of-an-object.md b/docs/visual-basic/programming-guide/language-features/variables/how-to-access-members-of-an-object.md index 79f73d20a8396..487cf2fed0eee 100644 --- a/docs/visual-basic/programming-guide/language-features/variables/how-to-access-members-of-an-object.md +++ b/docs/visual-basic/programming-guide/language-features/variables/how-to-access-members-of-an-object.md @@ -9,7 +9,7 @@ ms.assetid: a0072514-6a79-4dd6-8d03-ca8c13e61ddc --- # How to: Access Members of an Object (Visual Basic) -When you have an object variable that refers to an object, you often want to work with the members of that object, such as its methods, properties, fields, and events. For example, once you have created a new object, you might want to set its property or call its method. +When you have an object variable that refers to an object, you often want to work with the members of that object, such as its methods, properties, fields, and events. For example, once you have created a new object, you might want to set its property or call its method. ## Accessing Members diff --git a/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-what-type-an-object-variable-refers-to.md b/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-what-type-an-object-variable-refers-to.md index cc2fd746a1917..e40f0475d2047 100644 --- a/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-what-type-an-object-variable-refers-to.md +++ b/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-what-type-an-object-variable-refers-to.md @@ -10,18 +10,18 @@ ms.assetid: 6f6a138d-58a4-40d1-9f4e-0a3c598eaf81 --- # How to: Determine What Type an Object Variable Refers To (Visual Basic) -An object variable contains a pointer to data that is stored elsewhere. The type of that data can change during run time. At any moment, you can use the method to determine the current run-time type, or the [TypeOf Operator](../../../language-reference/operators/typeof-operator.md) to find out if the current run-time type is compatible with a specified type. +An object variable contains a pointer to data that is stored elsewhere. The type of that data can change during run time. At any moment, you can use the method to determine the current run-time type, or the [TypeOf Operator](../../../language-reference/operators/typeof-operator.md) to find out if the current run-time type is compatible with a specified type. ### To determine the exact type an object variable currently refers to -1. On the object variable, call the method to retrieve a object. +1. On the object variable, call the method to retrieve a object. ```vb Dim myObject As Object myObject.GetType() ``` -2. On the class, call the shared method to retrieve the enumeration value for the object's type. +2. On the class, call the shared method to retrieve the enumeration value for the object's type. ```vb Dim myObject As Object @@ -51,9 +51,9 @@ Note that the specified type cannot be a variable or expression. It must be the ## See also -- +- - -- +- - - [Object Variables](object-variables.md) - [Object Variable Values](object-variable-values.md) diff --git a/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-whether-two-objects-are-related.md b/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-whether-two-objects-are-related.md index 604cfb73d7c66..2be1e3773b06b 100644 --- a/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-whether-two-objects-are-related.md +++ b/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-whether-two-objects-are-related.md @@ -10,17 +10,17 @@ ms.assetid: da002e3f-6616-4bad-a229-f842d06652bb --- # How to: Determine Whether Two Objects Are Related (Visual Basic) -You can compare two objects to determine the relationship, if any, between the classes from which they are created. The method of the class returns `True` if the specified class inherits from the current class, or if the current type is an interface supported by the specified class. +You can compare two objects to determine the relationship, if any, between the classes from which they are created. The method of the class returns `True` if the specified class inherits from the current class, or if the current type is an interface supported by the specified class. ### To determine if one object inherits from another object's class or interface -1. On the object you think might be of the base type, invoke the method. +1. On the object you think might be of the base type, invoke the method. -2. On the object returned by , invoke the method. +2. On the object returned by , invoke the method. -3. In the argument list for , specify the object you think might be of the derived type. +3. In the argument list for , specify the object you think might be of the derived type. - returns `True` if its argument type inherits from the object type. + returns `True` if its argument type inherits from the object type. ## Example @@ -42,13 +42,13 @@ Public Class testTheseClasses End Class ``` -Note the unexpected placement of the two object variables in the call to . The supposed base type is used to generate the class, and the supposed derived type is passed as an argument to the method. +Note the unexpected placement of the two object variables in the call to . The supposed base type is used to generate the class, and the supposed derived type is passed as an argument to the method. ## See also -- +- - -- +- - [Object Data Type](../../../language-reference/data-types/object-data-type.md) - [Object Variables](object-variables.md) - [Object Variable Values](object-variable-values.md) diff --git a/docs/visual-basic/programming-guide/language-features/variables/object-variable-values.md b/docs/visual-basic/programming-guide/language-features/variables/object-variable-values.md index d8a44be73cf01..695266094b7e1 100644 --- a/docs/visual-basic/programming-guide/language-features/variables/object-variable-values.md +++ b/docs/visual-basic/programming-guide/language-features/variables/object-variable-values.md @@ -2,7 +2,7 @@ description: "Learn more about: Object Variable Values (Visual Basic)" title: "Object Variable Values" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "object variables [Visual Basic], values" - "values [Visual Basic], of object variables" - "data types [Visual Basic], object variable" @@ -11,60 +11,60 @@ ms.assetid: 31555704-58a3-49f1-9a0a-6421f605664f --- # Object Variable Values (Visual Basic) -A variable of the [Object Data Type](../../../language-reference/data-types/object-data-type.md) can refer to data of any type. The value you store in an `Object` variable is kept elsewhere in memory, while the variable itself holds a pointer to the data. - -## Object Classifier Functions - - Visual Basic supplies functions that return information about what an `Object` variable refers to, as shown in the following table. - -|Function|Returns True if the Object variable refers to| -|--------------|---------------------------------------------------| -||An array of values, rather than a single value| -||A [Date Data Type](../../../language-reference/data-types/date-data-type.md) value, or a string that can be interpreted as a date and time value| -||An object of type , which represents missing or nonexistent data| -||An exception object, which derives from | -||[Nothing](../../../language-reference/nothing.md), that is, no object is currently assigned to the variable| -||A number, or a string that can be interpreted as a number| -||A reference type (such as a string, array, delegate, or class type)| - - You can use these functions to avoid submitting an invalid value to an operation or a procedure. - -## TypeOf Operator - - You can also use the [TypeOf Operator](../../../language-reference/operators/typeof-operator.md) to determine whether an object variable currently refers to a specific data type. The `TypeOf`...`Is` expression evaluates to `True` if the run-time type of the operand is derived from or implements the specified type. - - The following example uses `TypeOf` on object variables referring to value and reference types. - -```vb -' The following statement puts a value type (Integer) in an Object variable. -Dim num As Object = 10 -' The following statement puts a reference type (Form) in an Object variable. -Dim frm As Object = New Form() -If TypeOf num Is Long Then Debug.WriteLine("num is Long") -If TypeOf num Is Integer Then Debug.WriteLine("num is Integer") -If TypeOf num Is Short Then Debug.WriteLine("num is Short") -If TypeOf num Is Object Then Debug.WriteLine("num is Object") -If TypeOf frm Is Form Then Debug.WriteLine("frm is Form") -If TypeOf frm Is Label Then Debug.WriteLine("frm is Label") -If TypeOf frm Is Object Then Debug.WriteLine("frm is Object") -``` - - The preceding example writes the following lines to the **Debug** window: - - `num is Integer` - - `num is Object` - - `frm is Form` - - `frm is Object` - - The object variable `num` refers to data of type `Integer`, and `frm` refers to an object of class . - -## Object Arrays - - You can declare and use an array of `Object` variables. This is useful when you need to handle a variety of data types and object classes. All the elements in an array must have the same declared data type. Declaring this data type as `Object` allows you to store objects and class instances alongside other data types in the array. - +A variable of the [Object Data Type](../../../language-reference/data-types/object-data-type.md) can refer to data of any type. The value you store in an `Object` variable is kept elsewhere in memory, while the variable itself holds a pointer to the data. + +## Object Classifier Functions + + Visual Basic supplies functions that return information about what an `Object` variable refers to, as shown in the following table. + +|Function|Returns True if the Object variable refers to| +|--------------|---------------------------------------------------| +||An array of values, rather than a single value| +||A [Date Data Type](../../../language-reference/data-types/date-data-type.md) value, or a string that can be interpreted as a date and time value| +||An object of type , which represents missing or nonexistent data| +||An exception object, which derives from | +||[Nothing](../../../language-reference/nothing.md), that is, no object is currently assigned to the variable| +||A number, or a string that can be interpreted as a number| +||A reference type (such as a string, array, delegate, or class type)| + + You can use these functions to avoid submitting an invalid value to an operation or a procedure. + +## TypeOf Operator + + You can also use the [TypeOf Operator](../../../language-reference/operators/typeof-operator.md) to determine whether an object variable currently refers to a specific data type. The `TypeOf`...`Is` expression evaluates to `True` if the run-time type of the operand is derived from or implements the specified type. + + The following example uses `TypeOf` on object variables referring to value and reference types. + +```vb +' The following statement puts a value type (Integer) in an Object variable. +Dim num As Object = 10 +' The following statement puts a reference type (Form) in an Object variable. +Dim frm As Object = New Form() +If TypeOf num Is Long Then Debug.WriteLine("num is Long") +If TypeOf num Is Integer Then Debug.WriteLine("num is Integer") +If TypeOf num Is Short Then Debug.WriteLine("num is Short") +If TypeOf num Is Object Then Debug.WriteLine("num is Object") +If TypeOf frm Is Form Then Debug.WriteLine("frm is Form") +If TypeOf frm Is Label Then Debug.WriteLine("frm is Label") +If TypeOf frm Is Object Then Debug.WriteLine("frm is Object") +``` + + The preceding example writes the following lines to the **Debug** window: + + `num is Integer` + + `num is Object` + + `frm is Form` + + `frm is Object` + + The object variable `num` refers to data of type `Integer`, and `frm` refers to an object of class . + +## Object Arrays + + You can declare and use an array of `Object` variables. This is useful when you need to handle a variety of data types and object classes. All the elements in an array must have the same declared data type. Declaring this data type as `Object` allows you to store objects and class instances alongside other data types in the array. + ## See also - [Object Variables](object-variables.md) diff --git a/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-attributes.md b/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-attributes.md index 891f1d0b5531f..72be3a72e4b43 100644 --- a/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-attributes.md +++ b/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-attributes.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Access XML Attributes (Visual Basic)" title: "How to: Access XML Attributes" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "attribute axis property [Visual Basic]" - "XML attribute axis property [Visual Basic]" - "XML axis [Visual Basic], attribute" @@ -11,15 +11,15 @@ ms.assetid: 66cd704f-990c-4f8d-9b49-2b6aa76ca8fd --- # How to: Access XML Attributes (Visual Basic) -This example shows how to use an attribute axis property to access XML attributes in an XML element by name. In particular, it uses the `type` attribute axis property to access the attribute named `type` in the `phone` object. - -## Example +This example shows how to use an attribute axis property to access XML attributes in an XML element by name. In particular, it uses the `type` attribute axis property to access the attribute named `type` in the `phone` object. + +## Example + + [!code-vb[VbXMLSamples#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples5.vb#11)] - [!code-vb[VbXMLSamples#11](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples5.vb#11)] - ## See also -- +- - [XML Attribute Axis Property](../../../language-reference/xml-axis/xml-attribute-axis-property.md) - [Accessing XML in Visual Basic](accessing-xml.md) - [XML](index.md) diff --git a/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-child-elements.md b/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-child-elements.md index d23e6bcd8bf38..4715404975d01 100644 --- a/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-child-elements.md +++ b/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-child-elements.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Access XML Child Elements (Visual Basic)" title: "How to: Access XML Child Elements" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "XML axis [Visual Basic], child" - "child axis property [Visual Basic]" - "XML child axis property [Visual Basic]" @@ -11,21 +11,21 @@ ms.assetid: 6689eb36-c471-469f-a82d-099ab8197b25 --- # How to: Access XML Child Elements (Visual Basic) -This example shows how to use a child axis property to access all XML child elements that have a specified name in an XML element. In particular, it uses the property to get the value of the first element in the collection that the `name` child axis property returns. The `name` child axis property gets all child elements named `phone` in the `contact` object. This example also uses the `phone` child axis property to access all child elements named `phone` that are contained in the `contact` object. - -## Example +This example shows how to use a child axis property to access all XML child elements that have a specified name in an XML element. In particular, it uses the property to get the value of the first element in the collection that the `name` child axis property returns. The `name` child axis property gets all child elements named `phone` in the `contact` object. This example also uses the `phone` child axis property to access all child elements named `phone` that are contained in the `contact` object. - [!code-vb[VbXMLSamples#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples4.vb#10)] - -## Compile the code +## Example + + [!code-vb[VbXMLSamples#10](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples4.vb#10)] + +## Compile the code + + This example requires: + +- A reference to the namespace. - This example requires: - -- A reference to the namespace. - ## See also -- +- - [XML Child Axis Property](../../../language-reference/xml-axis/xml-child-axis-property.md) - [XML Value Property](../../../language-reference/xml-axis/xml-value-property.md) - [Accessing XML in Visual Basic](accessing-xml.md) diff --git a/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-descendant-elements.md b/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-descendant-elements.md index c823f847c673d..ece22829ccca1 100644 --- a/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-descendant-elements.md +++ b/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-descendant-elements.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Access XML Descendant Elements (Visual Basic)" title: "How to: Access XML Descendant Elements" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "XML descendent axis property [Visual Basic]" - "XML axis [Visual Basic], descendent" - "descendent axis property [Visual Basic]" @@ -11,21 +11,21 @@ ms.assetid: aabfa258-4112-4e7e-bab9-403f96072ef7 --- # How to: Access XML Descendant Elements (Visual Basic) -This example shows how to use a descendant axis property to access all XML elements that have a specified name and that are contained under an XML element. In particular, it uses the `Value` property to get the value of the first element in the collection that the `name` descendant axis property returns. The `name` descendant axis property gets all elements named `name` that are contained in the `contacts` object. This example also uses the `phone` descendant axis property to access all descendants named `phone` that are contained in the `contacts` object. - -## Example +This example shows how to use a descendant axis property to access all XML elements that have a specified name and that are contained under an XML element. In particular, it uses the `Value` property to get the value of the first element in the collection that the `name` descendant axis property returns. The `name` descendant axis property gets all elements named `name` that are contained in the `contacts` object. This example also uses the `phone` descendant axis property to access all descendants named `phone` that are contained in the `contacts` object. - [!code-vb[VbXMLSamples#31](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples13.vb#31)] - -## Compile the code +## Example + + [!code-vb[VbXMLSamples#31](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples13.vb#31)] + +## Compile the code + + This example requires: + +- A reference to the namespace. - This example requires: - -- A reference to the namespace. - ## See also -- +- - [XML Descendant Axis Property](../../../language-reference/xml-axis/xml-descendant-axis-property.md) - [XML Value Property](../../../language-reference/xml-axis/xml-value-property.md) - [Accessing XML in Visual Basic](accessing-xml.md) diff --git a/docs/visual-basic/programming-guide/language-features/xml/how-to-declare-and-use-xml-namespace-prefixes.md b/docs/visual-basic/programming-guide/language-features/xml/how-to-declare-and-use-xml-namespace-prefixes.md index 83d1af402c72f..ca36217138157 100644 --- a/docs/visual-basic/programming-guide/language-features/xml/how-to-declare-and-use-xml-namespace-prefixes.md +++ b/docs/visual-basic/programming-guide/language-features/xml/how-to-declare-and-use-xml-namespace-prefixes.md @@ -2,28 +2,28 @@ description: "Learn more about: How to: Declare and Use XML Namespace Prefixes (Visual Basic)" title: "How to: Declare and Use XML Namespace Prefixes" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "LINQ to XML [Visual Basic], XML namespace prefixes" - "XML namespace prefixes [Visual Basic]" ms.assetid: 4292e1d9-eb8f-49d6-a3aa-f05a5fbe24d1 --- # How to: Declare and Use XML Namespace Prefixes (Visual Basic) -This example shows how to import the XML namespace prefix `ns` and use it in an XML literal and XML axis properties. - -## Example +This example shows how to import the XML namespace prefix `ns` and use it in an XML literal and XML axis properties. - [!code-vb[VbXMLSamples#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples3.vb#8)] - -## Compile the code +## Example + + [!code-vb[VbXMLSamples#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples3.vb#8)] + +## Compile the code + + This example requires: + +- A reference to the namespace. - This example requires: - -- A reference to the namespace. - ## See also -- +- - [Imports Statement (XML Namespace)](../../../language-reference/statements/imports-statement-xml-namespace.md) - [XML Attribute Axis Property](../../../language-reference/xml-axis/xml-attribute-axis-property.md) - [XML Value Property](../../../language-reference/xml-axis/xml-value-property.md) diff --git a/docs/visual-basic/programming-guide/language-features/xml/how-to-load-xml-from-a-file-string-or-stream.md b/docs/visual-basic/programming-guide/language-features/xml/how-to-load-xml-from-a-file-string-or-stream.md index e1c72cb0db3be..5dd2aa6e1516d 100644 --- a/docs/visual-basic/programming-guide/language-features/xml/how-to-load-xml-from-a-file-string-or-stream.md +++ b/docs/visual-basic/programming-guide/language-features/xml/how-to-load-xml-from-a-file-string-or-stream.md @@ -31,19 +31,19 @@ The following code example shows the use of the or object from a stream, you can use the `Load` method or the method. +To populate an XML literal such as an or object from a stream, you can use the `Load` method or the method. -The following code example shows the use of the method to populate an object with XML from an XML stream. +The following code example shows the use of the method to populate an object with XML from an XML stream. [!code-vb[VbXMLSamples#46](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXMLSamples/VB/XMLSamples15.vb#46)] ## See also -- -- -- -- -- +- +- +- +- +- - [XML Literals](../../../language-reference/xml-literals/index.md) - [XML](index.md) - [Manipulating XML in Visual Basic](manipulating-xml.md) diff --git a/docs/visual-basic/programming-guide/language-features/xml/how-to-modify-xml-literals.md b/docs/visual-basic/programming-guide/language-features/xml/how-to-modify-xml-literals.md index c03679304e0ba..2538f64c06a91 100644 --- a/docs/visual-basic/programming-guide/language-features/xml/how-to-modify-xml-literals.md +++ b/docs/visual-basic/programming-guide/language-features/xml/how-to-modify-xml-literals.md @@ -64,7 +64,7 @@ Visual Basic provides convenient ways to modify XML literals. You can add or del ### To add an attribute to an XML literal -1. To add an attribute to an XML literal, first obtain a reference to the XML literal. You can then add an attribute by adding a new XML attribute axis property. You can also add a new object to the XML literal by using the method. The following example shows both options. +1. To add an attribute to an XML literal, first obtain a reference to the XML literal. You can then add an attribute by adding a new XML attribute axis property. You can also add a new object to the XML literal by using the method. The following example shows both options. [!code-vb[VbXmlSamples2#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXmlSamples2/VB/Module2.vb#5)] @@ -110,9 +110,9 @@ Visual Basic provides convenient ways to modify XML literals. You can add or del ### To add an element to an XML literal -1. To add an element to an XML literal, first obtain a reference to the XML literal. You can then add a new object as the last sub-element of the element by using the method. You can add a new object as the first sub-element by using the method. +1. To add an element to an XML literal, first obtain a reference to the XML literal. You can then add a new object as the last sub-element of the element by using the method. You can add a new object as the first sub-element by using the method. - To add a new element in a specific location relative to other sub-elements, first obtain a reference to an adjacent sub-element. You can then add the new object before the adjacent sub-element by using the method. You can also add the new object after the adjacent sub-element by using the method. + To add a new element in a specific location relative to other sub-elements, first obtain a reference to an adjacent sub-element. You can then add the new object before the adjacent sub-element by using the method. You can also add the new object after the adjacent sub-element by using the method. The following example shows examples of each of these techniques. @@ -206,15 +206,15 @@ Visual Basic provides convenient ways to modify XML literals. You can add or del ``` - To remove all elements or attributes from an XML literal, obtain a reference to the XML literal and call the method. + To remove all elements or attributes from an XML literal, obtain a reference to the XML literal and call the method. ### To modify an XML literal -1. To change the name of an XML element, first obtain a reference to the element. You can then create a new object that has a new name and pass the new object to the method of the existing object. +1. To change the name of an XML element, first obtain a reference to the element. You can then create a new object that has a new name and pass the new object to the method of the existing object. - If the element that you are replacing has sub-elements that must be preserved, set the value of the new object to the property of the existing element. This will set the value of the new element to the inner XML of the existing element. Otherwise, you can set the value of the new element to the `Value` property of the existing element. + If the element that you are replacing has sub-elements that must be preserved, set the value of the new object to the property of the existing element. This will set the value of the new element to the inner XML of the existing element. Otherwise, you can set the value of the new element to the `Value` property of the existing element. - The following code example replaces all `` elements with an `` element. The content of the `` element is preserved in the new `` element by using the property of the `` object. + The following code example replaces all `` elements with an `` element. The content of the `` element is preserved in the new `` element by using the property of the `` object. [!code-vb[VbXmlSamples2#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbXmlSamples2/VB/Module2.vb#8)] diff --git a/docs/visual-basic/programming-guide/language-features/xml/how-to-transform-xml-by-using-linq.md b/docs/visual-basic/programming-guide/language-features/xml/how-to-transform-xml-by-using-linq.md index 152765392a407..97ed14ce01407 100644 --- a/docs/visual-basic/programming-guide/language-features/xml/how-to-transform-xml-by-using-linq.md +++ b/docs/visual-basic/programming-guide/language-features/xml/how-to-transform-xml-by-using-linq.md @@ -57,7 +57,7 @@ The example in this topic transforms content from an XML source document to HTML 3. After the code to create the source XML document, add the following code to retrieve all the `` elements from the object and transform them into an HTML document. The list of `` elements is created by using a LINQ query that returns a collection of objects that contain the transformed HTML. You can use embedded expressions to put the values from the source document in the new XML format. - The resulting HTML document is written to a file by using the method. + The resulting HTML document is written to a file by using the method. ```vb Dim htmlOutput = @@ -80,7 +80,7 @@ The example in this topic transforms content from an XML source document to HTML 4. After `Sub Main` of `Module1`, add a new method (`Sub`) to transform a `` node into the specified HTML format. This method is called by the code in the previous step and is used to preserve the format of the `` elements. - This method replaces sub-elements of the `` element with HTML. The `ReplaceWith` method is used to preserve the location of the sub-elements. The transformed content of the `` element is included in an HTML paragraph (\

) element. The property is used to retrieve the transformed content of the `` element. This ensures that sub-elements are included in the transformed content. + This method replaces sub-elements of the `` element with HTML. The `ReplaceWith` method is used to preserve the location of the sub-elements. The transformed content of the `` element is included in an HTML paragraph (\

) element. The property is used to retrieve the transformed content of the `` element. This ensures that sub-elements are included in the transformed content. Add the following code after `Sub Main` of `Module1`. diff --git a/docs/visual-basic/programming-guide/program-structure/main-procedure.md b/docs/visual-basic/programming-guide/program-structure/main-procedure.md index 90be2022da8b1..b429fe21d1f35 100644 --- a/docs/visual-basic/programming-guide/program-structure/main-procedure.md +++ b/docs/visual-basic/programming-guide/program-structure/main-procedure.md @@ -105,12 +105,12 @@ Every Visual Basic application must contain a procedure called `Main`. This proc End Sub End Module ``` - + ## See also -- -- -- +- +- +- - [Structure of a Visual Basic Program](structure-of-a-visual-basic-program.md) - [-main](../../reference/command-line-compiler/main.md) - [Shared](../../language-reference/modifiers/shared.md) diff --git a/docs/visual-basic/programming-guide/program-structure/naming-conventions.md b/docs/visual-basic/programming-guide/program-structure/naming-conventions.md index 20ddcf03d3474..a4314719ca784 100644 --- a/docs/visual-basic/programming-guide/program-structure/naming-conventions.md +++ b/docs/visual-basic/programming-guide/program-structure/naming-conventions.md @@ -2,7 +2,7 @@ description: "Learn more about: Visual Basic Naming Conventions" title: "Naming Conventions" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "names [Visual Basic], Visual Basic rules" - "naming conventions" - "naming conventions [Visual Basic], Visual Basic" @@ -14,28 +14,28 @@ ms.assetid: 164949a4-2a7c-4736-9d82-9c3078e2e56c --- # Visual Basic Naming Conventions -When you name an element in your Visual Basic application, the first character of that name must be an alphabetic character or an underscore. Note, however, that names beginning with an underscore are not compliant with the [Language Independence and Language-Independent Components](../../../standard/language-independence.md) (CLS). - - The following suggestions apply to naming. - -- Begin each separate word in a name with a capital letter, as in `FindLastRecord` and `RedrawMyForm`. - -- Begin function and method names with a verb, as in `InitNameArray` or `CloseDialog`. - -- Begin class, structure, module, and property names with a noun, as in `EmployeeName` or `CarAccessory`. - -- Begin interface names with the prefix "I", followed by a noun or a noun phrase, like `IComponent`, or with an adjective describing the interface's behavior, like `IPersistable`. Do not use the underscore, and use abbreviations sparingly, because abbreviations can cause confusion. - -- Begin event handler names with a noun describing the type of event followed by the "`EventHandler`" suffix, as in "`MouseEventHandler`". - -- In names of event argument classes, include the "`EventArgs`" suffix. - -- If an event has a concept of "before" or "after," use a suffix in present or past tense, as in "`ControlAdd`" or "`ControlAdded`". - -- For long or frequently used terms, use abbreviations to keep name lengths reasonable, for example, "HTML", instead of "Hypertext Markup Language". In general, variable names greater than 32 characters are difficult to read on a monitor set to a low resolution. Also, make sure your abbreviations are consistent throughout the entire application. Randomly switching in a project between "HTML" and "Hypertext Markup Language" can lead to confusion. - -- Avoid using names in an inner scope that are the same as names in an outer scope. Errors can result if the wrong variable is accessed. If a conflict occurs between a variable and the keyword of the same name, you must identify the keyword by preceding it with the appropriate type library. For example, if you have a variable called `Date`, you can use the intrinsic `Date` function only by calling . - +When you name an element in your Visual Basic application, the first character of that name must be an alphabetic character or an underscore. Note, however, that names beginning with an underscore are not compliant with the [Language Independence and Language-Independent Components](../../../standard/language-independence.md) (CLS). + + The following suggestions apply to naming. + +- Begin each separate word in a name with a capital letter, as in `FindLastRecord` and `RedrawMyForm`. + +- Begin function and method names with a verb, as in `InitNameArray` or `CloseDialog`. + +- Begin class, structure, module, and property names with a noun, as in `EmployeeName` or `CarAccessory`. + +- Begin interface names with the prefix "I", followed by a noun or a noun phrase, like `IComponent`, or with an adjective describing the interface's behavior, like `IPersistable`. Do not use the underscore, and use abbreviations sparingly, because abbreviations can cause confusion. + +- Begin event handler names with a noun describing the type of event followed by the "`EventHandler`" suffix, as in "`MouseEventHandler`". + +- In names of event argument classes, include the "`EventArgs`" suffix. + +- If an event has a concept of "before" or "after," use a suffix in present or past tense, as in "`ControlAdd`" or "`ControlAdded`". + +- For long or frequently used terms, use abbreviations to keep name lengths reasonable, for example, "HTML", instead of "Hypertext Markup Language". In general, variable names greater than 32 characters are difficult to read on a monitor set to a low resolution. Also, make sure your abbreviations are consistent throughout the entire application. Randomly switching in a project between "HTML" and "Hypertext Markup Language" can lead to confusion. + +- Avoid using names in an inner scope that are the same as names in an outer scope. Errors can result if the wrong variable is accessed. If a conflict occurs between a variable and the keyword of the same name, you must identify the keyword by preceding it with the appropriate type library. For example, if you have a variable called `Date`, you can use the intrinsic `Date` function only by calling . + ## See also - [Keywords as Element Names in Code](keywords-as-element-names-in-code.md) diff --git a/docs/visual-basic/reference/command-line-compiler/resource.md b/docs/visual-basic/reference/command-line-compiler/resource.md index 37701171246c3..19c2010d8d29d 100644 --- a/docs/visual-basic/reference/command-line-compiler/resource.md +++ b/docs/visual-basic/reference/command-line-compiler/resource.md @@ -2,7 +2,7 @@ description: "Learn more about: -resource (Visual Basic)" title: "-resource" ms.date: 03/13/2018 -helpviewer_keywords: +helpviewer_keywords: - "/resource compiler option [Visual Basic]" - "-resource compiler option [Visual Basic]" - "/res compiler option [Visual Basic]" @@ -13,45 +13,45 @@ ms.assetid: eee2f227-91f2-4f2b-a9d6-1c51c5320858 --- # -resource (Visual Basic) -Embeds a managed resource in an assembly. - -## Syntax - -```console --resource:filename[,identifier[,public|private]] +Embeds a managed resource in an assembly. + +## Syntax + +```console +-resource:filename[,identifier[,public|private]] ``` -or +or ```console --res:filename[,identifier[,public|private]] -``` - -## Arguments - -|Term|Definition| -|---|---| -|`filename`|Required. The name of the resource file to embed in the output file. By default, `filename` is public in the assembly. Enclose the file name in quotation marks (" ") if it contains a space.| -|`identifier`|Optional. The logical name for the resource; the name used to load it. The default is the name of the file. Optionally, you can specify whether the resource is public or private in the assembly manifest, as with the following: `-res:filename.res, myname.res, public`| - -## Remarks - - Use `-linkresource` to link a resource to an assembly without placing the resource file in the output file. - - If `filename` is a .NET Framework resource file created, for example, by the [Resgen.exe (Resource File Generator)](../../../framework/tools/resgen-exe-resource-file-generator.md) or in the development environment, it can be accessed with members in the namespace (see for more information). To access all other resources at run time, use one of the following methods: , , or . - - The short form of `-resource` is `-res`. - - For information about how to set `-resource` in the Visual Studio IDE, see [Managing Application Resources (.NET)](/visualstudio/ide/managing-application-resources-dotnet). - -## Example - - The following code compiles `In.vb` and attaches resource file `Rf.resource`. - +-res:filename[,identifier[,public|private]] +``` + +## Arguments + +|Term|Definition| +|---|---| +|`filename`|Required. The name of the resource file to embed in the output file. By default, `filename` is public in the assembly. Enclose the file name in quotation marks (" ") if it contains a space.| +|`identifier`|Optional. The logical name for the resource; the name used to load it. The default is the name of the file. Optionally, you can specify whether the resource is public or private in the assembly manifest, as with the following: `-res:filename.res, myname.res, public`| + +## Remarks + + Use `-linkresource` to link a resource to an assembly without placing the resource file in the output file. + + If `filename` is a .NET Framework resource file created, for example, by the [Resgen.exe (Resource File Generator)](../../../framework/tools/resgen-exe-resource-file-generator.md) or in the development environment, it can be accessed with members in the namespace (see for more information). To access all other resources at run time, use one of the following methods: , , or . + + The short form of `-resource` is `-res`. + + For information about how to set `-resource` in the Visual Studio IDE, see [Managing Application Resources (.NET)](/visualstudio/ide/managing-application-resources-dotnet). + +## Example + + The following code compiles `In.vb` and attaches resource file `Rf.resource`. + ```console -vbc -res:rf.resource in.vb -``` - +vbc -res:rf.resource in.vb +``` + ## See also - [Visual Basic Command-Line Compiler](index.md) diff --git a/docs/visual-basic/reference/command-line-compiler/rootnamespace.md b/docs/visual-basic/reference/command-line-compiler/rootnamespace.md index 11b72c43004ac..69a84b204b4d9 100644 --- a/docs/visual-basic/reference/command-line-compiler/rootnamespace.md +++ b/docs/visual-basic/reference/command-line-compiler/rootnamespace.md @@ -29,7 +29,7 @@ Specifies a namespace for all type declarations. ## Remarks - If you use the Visual Studio executable file (Devenv.exe) to compile a project created in the Visual Studio integrated development environment, use `-rootnamespace` to specify the value of the property. See [Devenv Command Line Switches](/visualstudio/ide/reference/devenv-command-line-switches) for more information. + If you use the Visual Studio executable file (Devenv.exe) to compile a project created in the Visual Studio integrated development environment, use `-rootnamespace` to specify the value of the property. See [Devenv Command Line Switches](/visualstudio/ide/reference/devenv-command-line-switches) for more information. Use the IL Disassembler tool (`Ildasm.exe`) to view the namespace names in your output file. diff --git a/docs/visual-basic/whats-new/index.md b/docs/visual-basic/whats-new/index.md index 56c36ec3e6128..e6808ea169ce1 100644 --- a/docs/visual-basic/whats-new/index.md +++ b/docs/visual-basic/whats-new/index.md @@ -180,7 +180,7 @@ Tuples are a lightweight data structure that you most commonly use to return mul - Define one or more `ByRef` parameters, in addition to returning a value from the method. -Visual Basic's support for tuples lets you quickly define a tuple, optionally assign semantic names to its values, and quickly retrieve its values. The following example wraps a call to the method and returns a tuple. +Visual Basic's support for tuples lets you quickly define a tuple, optionally assign semantic names to its values, and quickly retrieve its values. The following example wraps a call to the method and returns a tuple. :::code language="vb" source="../../../samples/snippets/visualbasic/programming-guide/language-features/data-types/tuples/tuple-returns.vb" id="ParseIntegerReturnsTuple":::