diff --git a/docfx.json b/docfx.json index 4fc0d7e67544a..f410b428132bf 100644 --- a/docfx.json +++ b/docfx.json @@ -535,6 +535,8 @@ "_csharplang/proposals/csharp-9.0/target-typed-conditional-expression.md" : "Target-typed conditional expression", "_csharplang/proposals/csharp-9.0/target-typed-new.md" : "Target-typed new expressions", "_csharplang/proposals/csharp-9.0/top-level-statements.md" : "Top-level statements", + "_csharplang/proposals/csharp-9.0/unconstrained-type-parameter-annotations.md" : "Unconstrained type parameter annotations", + "_vblang/spec/introduction.md": "Introduction", "_vblang/spec/lexical-grammar.md": "Lexical grammar", diff --git a/docs/core/compatibility/3.1-5.0.md b/docs/core/compatibility/3.1-5.0.md index eabc866044bfb..437b0994caae8 100644 --- a/docs/core/compatibility/3.1-5.0.md +++ b/docs/core/compatibility/3.1-5.0.md @@ -338,11 +338,16 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v ## Cryptography +- [Default FeedbackSize value for instances created by TripleDES.Create changed](#default-feedbacksize-value-for-instances-created-by-tripledescreate-changed) - [Instantiating default implementations of cryptographic abstractions is not supported](#instantiating-default-implementations-of-cryptographic-abstractions-is-not-supported) - [Default TLS cipher suites for .NET on Linux](#default-tls-cipher-suites-for-net-on-linux) - [System.Security.Cryptography APIs not supported on Blazor WebAssembly](#systemsecuritycryptography-apis-not-supported-on-blazor-webassembly) - [System.Security.Cryptography.Oid is functionally init-only](#systemsecuritycryptographyoid-is-functionally-init-only) +[!INCLUDE [tripledes-default-feedback-size-change](../../../includes/core-changes/cryptography/5.0/tripledes-default-feedback-size-change.md)] + +*** + [!INCLUDE [instantiating-default-implementations-of-cryptographic-abstractions-not-supported](../../../includes/core-changes/cryptography/5.0/instantiating-default-implementations-of-cryptographic-abstractions-not-supported.md)] *** diff --git a/docs/core/compatibility/cryptography.md b/docs/core/compatibility/cryptography.md index 26f10e7a2546a..e4350efc2d871 100644 --- a/docs/core/compatibility/cryptography.md +++ b/docs/core/compatibility/cryptography.md @@ -9,6 +9,7 @@ The following breaking changes are documented on this page: | Breaking change | Version introduced | | - | :-: | +| [Default FeedbackSize value for instances created by TripleDES.Create changed](#default-feedbacksize-value-for-instances-created-by-tripledescreate-changed) | 5.0 | | [Instantiating default implementations of cryptographic abstractions is not supported](#instantiating-default-implementations-of-cryptographic-abstractions-is-not-supported) | 5.0 | | [Default TLS cipher suites for .NET on Linux](#default-tls-cipher-suites-for-net-on-linux) | 5.0 | | [System.Security.Cryptography APIs not supported on Blazor WebAssembly](#systemsecuritycryptography-apis-not-supported-on-blazor-webassembly) | 5.0 | @@ -22,6 +23,10 @@ The following breaking changes are documented on this page: ## .NET 5.0 +[!INCLUDE [tripledes-default-feedback-size-change](../../../includes/core-changes/cryptography/5.0/tripledes-default-feedback-size-change.md)] + +*** + [!INCLUDE [instantiating-default-implementations-of-cryptographic-abstractions-not-supported](../../../includes/core-changes/cryptography/5.0/instantiating-default-implementations-of-cryptographic-abstractions-not-supported.md)] *** diff --git a/docs/core/extensions/console-log-formatter.md b/docs/core/extensions/console-log-formatter.md new file mode 100644 index 0000000000000..bed1aa4804a5f --- /dev/null +++ b/docs/core/extensions/console-log-formatter.md @@ -0,0 +1,154 @@ +--- +title: Console log formatting +description: Learn how to use available console log formatting, or implement custom log formatting for your .NET applications. +author: IEvangelist +ms.author: dapine +ms.date: 10/22/2020 +--- + +# Console log formatting + +In .NET 5, support for custom formatting was added to console logs in the `Microsoft.Extensions.Logging.Console` namespace. There are three predefined formatting options available: [`Simple`](#simple), [`Systemd`](#systemd), and [`Json`](#json). + +> [!IMPORTANT] +> Previously, the enum allowed for selecting the desired log format, either human readable which was the `Default`, or single line which is also known as `Systemd`. However, these were **not** customizable, and are now deprecated. + +In this article, you will learn about console log formatters. The sample source code demonstrates how to: + +- Register a new formatter +- Select a registered formatter to use + - Either through code, or [configuration](configuration.md) +- Implement a custom formatter + - Update configuration via + - Enable custom color formatting + +## Register formatter + +The [`Console` logging provider](logging-providers.md#console) has several predefined formatters, and exposes the ability to author your own custom formatter. To register any of the available formatters, use the corresponding `Add{Type}Console` extension method: + +| Available types | Method to register type | +|--|--| +| | | +| | | +| | | + +### Simple + +To use the `Simple` console formatter, register it with `AddSimpleConsole`: + +:::code language="csharp" source="snippets/logging/console-formatter-simple/Program.cs" highlight="11-16"::: + +In the preceding sample source code, the formatter was registered. It provides logs with the ability to not only wrap information such as time and log level in each log message, but also allows for ANSI color embedding and indentation of messages. + +### Systemd + +The console logger: + +- Uses the "Syslog" log level format and severities +- Does **not** format messages with colors +- Always logs messages in a single line + +This is commonly useful for containers, which often make use of `Systemd` console logging. With .NET 5, the `Simple` console logger also enables a compact version that logs in a single line, and also allows for disabling colors as shown in an earlier sample. + +:::code language="csharp" source="snippets/logging/console-formatter-systemd/Program.cs" highlight="11-15"::: + +### Json + +To write logs in a JSON format, the `Json` console formatter is used. The sample source code shows how an ASP.NET Core app might register it. Using the `webapp` template, create a new ASP.NET Core app with the [dotnet new](../tools/dotnet-new.md) command: + +```dotnetcli +dotnet new webapp -o Console.ExampleFormatters.Json +``` + +When running the app, using the template code, you get the default log format below: + +``` +info: Microsoft.Hosting.Lifetime[0] + Now listening on: https://localhost:5001 +``` + +By default, the `Simple` console log formatter is selected with default configuration. You change this by calling `AddJsonConsole` in the *Program.cs*: + +:::code language="csharp" source="snippets/logging/console-formatter-json/Program.cs" highlight="17-26"::: + +Run the app again, with the above change, the log message is now formatted as JSON: + +:::code language="json" source="snippets/logging/console-formatter-json/example-output.json"::: + +> [!TIP] +> The `Json` console formatter, by default, logs each message in a single line. In order to make it more readable while configuring the formatter, set to `true`. + +## Set formatter with configuration + +The previous samples have shown how to register a formatter programmatically. Alternatively, this can be done with [configuration](configuration.md). Consider the previous web application sample source code, if you update the *appsettings.json* file rather than calling `ConfigureLogging` in the *Program.cs* file, you could get the same outcome. The updated `appsettings.json` file would configure the formatter as follows: + +:::code language="json" source="snippets/logging/console-formatter-json/appsettings.json" highlight="14-23"::: + +The two key values that need to be set are `"FormatterName"` and `"FormatterOptions"`. If a formatter with the value set for `"FormatterName"` is already registered, that formatter is selected, and its properties can be configured as long as they are provided as a key inside the `"FormatterOptions"` node. The predefined formatter names are reserved under : + +- +- +- + +## Implement a custom formatter + +To implement a custom formatter, you need to: + +- Create a subclass of , this represents your custom formatter +- Register your custom formatter with + - + - + +Create an extension method to handle this for you: + +:::code language="csharp" source="snippets/logging/console-formatter-custom/ConsoleLoggerExtensions.cs" highlight="11-12"::: + +The `CustomOptions` are defined as follows: + +:::code language="csharp" source="snippets/logging/console-formatter-custom/CustomOptions.cs"::: + +In the preceding code, the options are a subclass of . + +The `AddConsoleFormatter` API: + +- Registers a subclass of `ConsoleFormatter` +- Handles configuration: + - Uses a change token to synchronize updates, based on the [options pattern](options.md), and the [IOptionsMonitor](xref:Microsoft.Extensions.Options.IOptionsMonitor%601) interface + +:::code language="csharp" source="snippets/logging/console-formatter-custom/Program.cs" highlight="11-12"::: + +Define a `CustomerFormatter` subclass of `ConsoleFormatter`: + +:::code language="csharp" source="snippets/logging/console-formatter-custom/CustomFormatter.cs" highlight="24-45"::: + +The preceding `CustomFormatter.Write` API dictates what text gets wrapped around each log message. A standard `ConsoleFormatter` should be able to wrap around scopes, time stamps, and severity level of logs at a minimum. Additionally, you can encode ANSI colors in the log messages, and provide desired indentations as well. The implementation of the `CustomFormatter.Write` lacks these capabilities. + +For inspiration on further customizing formatting, see the existing implementations in the `Microsoft.Extensions.Logging.Console` namespace: + +- [SimpleConsoleFormatter](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.Extensions.Logging.Console/src/SimpleConsoleFormatter.cs). +- [SystemdConsoleFormatter](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.Extensions.Logging.Console/src/SystemdConsoleFormatter.cs) +- [JsonConsoleFormatter](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.Extensions.Logging.Console/src/JsonConsoleFormatter.cs) + +## Implement custom color formatting + +In order to properly enable color capabilities in your custom logging formatter, you can extend the as it has a property that can be useful for enabling colors in logs. + +Create a `CustomColorOptions` that derives from `SimpleConsoleFormatterOptions`: + +:::code language="csharp" source="snippets/logging/console-formatter-custom/CustomColorOptions.cs" highlight="5"::: + +Next, write some extension methods in a `TextWriterExtensions` class that allow for conveniently embedding ANSI coded colors within formatted log messages: + +:::code language="csharp" source="snippets/logging/console-formatter-custom/TextWriterExtensions.cs"::: + +A custom color formatter that handles applying custom colors could be defined as follows: + +:::code language="csharp" source="snippets/logging/console-formatter-custom/CustomColorFormatter.cs" highlight="15-18,52-65"::: + +When you run the application, the logs will show the `CustomPrefix` message in the color green when `FormatterOptions.ColorBehavior` is `Enabled`. + +## See also + +- [Logging in .NET](logging.md) +- [Implement a custom logging provider in .NET](custom-logging-provider.md) +- [High-performance logging in .NET](high-performance-logging.md) diff --git a/docs/core/extensions/dependency-injection-usage.md b/docs/core/extensions/dependency-injection-usage.md index 96281ac2d3c7a..cc60d3ce8bd9f 100644 --- a/docs/core/extensions/dependency-injection-usage.md +++ b/docs/core/extensions/dependency-injection-usage.md @@ -5,6 +5,7 @@ author: IEvangelist ms.author: dapine ms.date: 09/23/2020 ms.topic: tutorial +no-loc: [Transient, Scoped, Singleton, Example] --- # Tutorial: Use dependency injection in .NET @@ -22,8 +23,7 @@ In this tutorial, you learn how to: ## Prerequisites -- [.NET Core 3.1 SDK](https://dotnet.microsoft.com/download/dotnet-core) or a later version. -- An Integrated Development Environment (IDE), [Visual Studio, Visual Studio Code, or Visual Studio for Mac](https://visualstudio.microsoft.com) are all valid choices. +- [.NET Core 3.1 SDK](https://dotnet.microsoft.com/download/dotnet-core) or later. - Familiarity with creating new .NET applications and installing NuGet packages. ## Create a new console application @@ -62,25 +62,25 @@ Add the following default implementation for the various operations: :::code language="csharp" source="snippets/configuration/console-di/DefaultOperation.cs"::: -The `DefaultOperation` implements all of the named/marker interfaces and initializes the `OperationId` property to the last four characters of a new globally unique identifier (GUID). +The `DefaultOperation` implements all of the named marker interfaces and initializes the `OperationId` property to the last four characters of a new globally unique identifier (GUID). ## Add service that requires DI -Add the following operation logger object, which acts as a service to your console application: +Add the following operation logger object, which acts as a service to the console app: *OperationLogger.cs* :::code language="csharp" source="snippets/configuration/console-di/OperationLogger.cs"::: -The `OperationLogger` defines a constructor that requires each of the aforementioned marker interfaces, that is; `ITransientOperation`, `IScopedOperation`, and `ISingletonOperation`. The object exposes a single method that allows the consumer to log the operations with a given `scope` parameter. When invoked, the `LogOperations` method will log each operation's unique identifier with the scope string and message. +The `OperationLogger` defines a constructor that requires each of the aforementioned marker interfaces, that is; `ITransientOperation`, `IScopedOperation`, and `ISingletonOperation`. The object exposes a single method that allows the consumer to log the operations with a given `scope` parameter. When invoked, the `LogOperations` method logs each operation's unique identifier with the scope string and message. ## Register services for DI -Finally, update the *Program.cs* file to match following: +Update *Program.cs* with the following code: :::code language="csharp" source="snippets/configuration/console-di/Program.cs" range="1-18,35-60" highlight="22-26"::: -The application: +The app: - Creates an instance with the [default binder settings](generic-host.md#default-builder-settings). - Configures services and adds them with their corresponding service lifetime. @@ -89,7 +89,7 @@ The application: ## Conclusion -The application produces output similar to the following example: +The app displays output similar to the following example: ```console Scope 1-Call 1 .GetRequiredService(): ITransientOperation [ 80f4...Always different ] @@ -109,13 +109,13 @@ Scope 2-Call 2 .GetRequiredService(): IScopedOperation [ 2bd Scope 2-Call 2 .GetRequiredService(): ISingletonOperation [ 1586...Always the same ] ``` -From the application output, you can see that: +From the app output, you can see that: -- Transient operations are always different, meaning a new instance is created with every retrieval of the service. +- Transient operations are always different, a new instance is created with every retrieval of the service. - Scoped operations change only with a new scope, but are the same instance within a scope. -- Singleton operations are always the same, meaning a new instance is only created once. +- Singleton operations are always the same, a new instance is only created once. -## Next steps +## See also -> [!div class="nextstepaction"] -> [Dependency injection guidelines](dependency-injection-guidelines.md) +* [Dependency injection guidelines](dependency-injection-guidelines.md) +* [Dependency injection in ASP.NET Core](/aspnet/core/fundamentals/dependency-injection) diff --git a/docs/core/extensions/dependency-injection.md b/docs/core/extensions/dependency-injection.md index 752c72e2ec82a..a59784dd79469 100644 --- a/docs/core/extensions/dependency-injection.md +++ b/docs/core/extensions/dependency-injection.md @@ -168,7 +168,7 @@ In apps that process requests, scoped services are disposed at the end of the re When using Entity Framework Core, the extension method registers `DbContext` types with a scoped lifetime by default. > [!NOTE] -> Do ***not*** resolve a scoped service from a singleton. It may cause the service to have incorrect state when processing subsequent requests. It's fine to: +> Do ***not*** resolve a scoped service from a singleton and be careful not to do so indirectly, for example, through a transient service. It may cause the service to have incorrect state when processing subsequent requests. It's fine to: > > - Resolve a singleton service from a scoped or transient service. > - Resolve a scoped service from another scoped or transient service. @@ -286,6 +286,7 @@ Scoped services are disposed by the container that created them. If a scoped ser - [Use dependency injection in .NET](dependency-injection-usage.md) - [Dependency injection guidelines](dependency-injection-guidelines.md) +- [Dependency injection in ASP.NET Core](/aspnet/core/fundamentals/dependency-injection) - [NDC Conference Patterns for DI app development](https://www.youtube.com/watch?v=x-C-CNBVTaY) - [Explicit dependencies principle](../../architecture/modern-web-apps-azure/architectural-principles.md#explicit-dependencies) - [Inversion of control containers and the dependency injection pattern (Martin Fowler)](https://www.martinfowler.com/articles/injection.html) diff --git a/docs/core/extensions/logging.md b/docs/core/extensions/logging.md index 24a28c7a33ab9..78b12af8ab135 100644 --- a/docs/core/extensions/logging.md +++ b/docs/core/extensions/logging.md @@ -525,5 +525,6 @@ class Program - [Logging providers in .NET](logging-providers.md) - [Implement a custom logging provider in .NET](custom-logging-provider.md) +- [Console log formatting](console-log-formatter.md) - [High-performance logging in .NET](high-performance-logging.md) - Logging bugs should be created in the [github.com/dotnet/extensions](https://github.com/dotnet/extensions/issues) repo diff --git a/docs/core/extensions/snippets/logging/console-formatter-custom/ConsoleLoggerExtensions.cs b/docs/core/extensions/snippets/logging/console-formatter-custom/ConsoleLoggerExtensions.cs new file mode 100644 index 0000000000000..e60193b3f2616 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-custom/ConsoleLoggerExtensions.cs @@ -0,0 +1,14 @@ +using Microsoft.Extensions.Logging; +using System; + +namespace Console.ExampleFormatters.Custom +{ + public static class ConsoleLoggerExtensions + { + public static ILoggingBuilder AddCustomFormatter( + this ILoggingBuilder builder, + Action configure) => + builder.AddConsole(options => options.FormatterName = "customName") + .AddConsoleFormatter(configure); + } +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-custom/CustomColorFormatter.cs b/docs/core/extensions/snippets/logging/console-formatter-custom/CustomColorFormatter.cs new file mode 100644 index 0000000000000..b12e22cc21280 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-custom/CustomColorFormatter.cs @@ -0,0 +1,69 @@ +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging.Abstractions; +using Microsoft.Extensions.Logging.Console; +using Microsoft.Extensions.Options; +using System; +using System.IO; + +namespace Console.ExampleFormatters.Custom +{ + public sealed class CustomColorFormatter : ConsoleFormatter, IDisposable + { + private readonly IDisposable _optionsReloadToken; + private CustomColorOptions _formatterOptions; + + private bool ConsoleColorFormattingEnabled => + _formatterOptions.ColorBehavior == LoggerColorBehavior.Enabled || + _formatterOptions.ColorBehavior == LoggerColorBehavior.Default && + System.Console.IsOutputRedirected == false; + + public CustomColorFormatter(IOptionsMonitor options) + // Case insensitive + : base("customName") => + (_optionsReloadToken, _formatterOptions) = + (options.OnChange(ReloadLoggerOptions), options.CurrentValue); + + private void ReloadLoggerOptions(CustomColorOptions options) => + _formatterOptions = options; + + public override void Write( + in LogEntry logEntry, + IExternalScopeProvider scopeProvider, + TextWriter textWriter) + { + if (logEntry.Exception is null) + { + return; + } + + string message = + logEntry.Formatter( + logEntry.State, logEntry.Exception); + + if (message == null) + { + return; + } + + CustomLogicGoesHere(textWriter); + textWriter.WriteLine(message); + } + + private void CustomLogicGoesHere(TextWriter textWriter) + { + if (ConsoleColorFormattingEnabled) + { + textWriter.WriteWithColor( + _formatterOptions.CustomPrefix, + ConsoleColor.Black, + ConsoleColor.Green); + } + else + { + textWriter.Write(_formatterOptions.CustomPrefix); + } + } + + public void Dispose() => _optionsReloadToken?.Dispose(); + } +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-custom/CustomColorOptions.cs b/docs/core/extensions/snippets/logging/console-formatter-custom/CustomColorOptions.cs new file mode 100644 index 0000000000000..1f2213893f684 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-custom/CustomColorOptions.cs @@ -0,0 +1,9 @@ +using Microsoft.Extensions.Logging.Console; + +namespace Console.ExampleFormatters.Custom +{ + public class CustomColorOptions : SimpleConsoleFormatterOptions + { + public string CustomPrefix { get; set; } + } +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-custom/CustomFormatter.cs b/docs/core/extensions/snippets/logging/console-formatter-custom/CustomFormatter.cs new file mode 100644 index 0000000000000..f105838d4891d --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-custom/CustomFormatter.cs @@ -0,0 +1,54 @@ +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging.Abstractions; +using Microsoft.Extensions.Logging.Console; +using Microsoft.Extensions.Options; +using System; +using System.IO; + +namespace Console.ExampleFormatters.Custom +{ + public sealed class CustomFormatter : ConsoleFormatter, IDisposable + { + private readonly IDisposable _optionsReloadToken; + private CustomOptions _formatterOptions; + + public CustomFormatter(IOptionsMonitor options) + // Case insensitive + : base("customName") => + (_optionsReloadToken, _formatterOptions) = + (options.OnChange(ReloadLoggerOptions), options.CurrentValue); + + private void ReloadLoggerOptions(CustomOptions options) => + _formatterOptions = options; + + public override void Write( + in LogEntry logEntry, + IExternalScopeProvider scopeProvider, + TextWriter textWriter) + { + if (logEntry.Exception is null) + { + return; + } + + string message = + logEntry.Formatter( + logEntry.State, logEntry.Exception); + + if (message == null) + { + return; + } + + CustomLogicGoesHere(textWriter); + textWriter.WriteLine(message); + } + + private void CustomLogicGoesHere(TextWriter textWriter) + { + textWriter.Write(_formatterOptions.CustomPrefix); + } + + public void Dispose() => _optionsReloadToken?.Dispose(); + } +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-custom/CustomOptions.cs b/docs/core/extensions/snippets/logging/console-formatter-custom/CustomOptions.cs new file mode 100644 index 0000000000000..33d491986d576 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-custom/CustomOptions.cs @@ -0,0 +1,9 @@ +using Microsoft.Extensions.Logging.Console; + +namespace Console.ExampleFormatters.Custom +{ + public class CustomOptions : ConsoleFormatterOptions + { + public string CustomPrefix { get; set; } + } +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-custom/Program.cs b/docs/core/extensions/snippets/logging/console-formatter-custom/Program.cs new file mode 100644 index 0000000000000..b0fef32abae49 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-custom/Program.cs @@ -0,0 +1,22 @@ +using Microsoft.Extensions.Logging; + +namespace Console.ExampleFormatters.Custom +{ + class Program + { + static void Main() + { + using ILoggerFactory loggerFactory = + LoggerFactory.Create(builder => + builder.AddCustomFormatter(options => + options.CustomPrefix = " ~~~~~ ")); + + ILogger logger = loggerFactory.CreateLogger(); + using (logger.BeginScope("TODO: Add logic to enable scopes")) + { + logger.LogInformation("Hello World!"); + logger.LogInformation("TODO: Add logic to enable timestamp and log level info."); + } + } + } +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-custom/TextWriterExtensions.cs b/docs/core/extensions/snippets/logging/console-formatter-custom/TextWriterExtensions.cs new file mode 100644 index 0000000000000..60f0e00a61278 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-custom/TextWriterExtensions.cs @@ -0,0 +1,87 @@ +using System; +using System.IO; + +namespace Console.ExampleFormatters.Custom +{ + public static class TextWriterExtensions + { + const string DefaultForegroundColor = "\x1B[39m\x1B[22m"; + const string DefaultBackgroundColor = "\x1B[49m"; + + public static void WriteWithColor( + this TextWriter textWriter, + string message, + ConsoleColor? background, + ConsoleColor? foreground) + { + // Order: + // 1. background color + // 2. foreground color + // 3. message + // 4. reset foreground color + // 5. reset background color + + (bool writeBackgroundColor, string backgroundColor) = + (background.HasValue, GetBackgroundColorEscapeCode(background.Value)); + (bool writeForegroundColor, string foregroundColor) = + (foreground.HasValue, GetForegroundColorEscapeCode(foreground.Value)); + + if (writeBackgroundColor) + { + textWriter.Write(backgroundColor); + } + if (writeForegroundColor) + { + textWriter.Write(foregroundColor); + } + + textWriter.WriteLine(message); + + if (writeForegroundColor) + { + textWriter.Write(DefaultForegroundColor); + } + if (writeBackgroundColor) + { + textWriter.Write(DefaultBackgroundColor); + } + } + + static string GetForegroundColorEscapeCode(ConsoleColor color) => + color switch + { + ConsoleColor.Black => "\x1B[30m", + ConsoleColor.DarkRed => "\x1B[31m", + ConsoleColor.DarkGreen => "\x1B[32m", + ConsoleColor.DarkYellow => "\x1B[33m", + ConsoleColor.DarkBlue => "\x1B[34m", + ConsoleColor.DarkMagenta => "\x1B[35m", + ConsoleColor.DarkCyan => "\x1B[36m", + ConsoleColor.Gray => "\x1B[37m", + ConsoleColor.Red => "\x1B[1m\x1B[31m", + ConsoleColor.Green => "\x1B[1m\x1B[32m", + ConsoleColor.Yellow => "\x1B[1m\x1B[33m", + ConsoleColor.Blue => "\x1B[1m\x1B[34m", + ConsoleColor.Magenta => "\x1B[1m\x1B[35m", + ConsoleColor.Cyan => "\x1B[1m\x1B[36m", + ConsoleColor.White => "\x1B[1m\x1B[37m", + + _ => DefaultForegroundColor + }; + + static string GetBackgroundColorEscapeCode(ConsoleColor color) => + color switch + { + ConsoleColor.Black => "\x1B[40m", + ConsoleColor.DarkRed => "\x1B[41m", + ConsoleColor.DarkGreen => "\x1B[42m", + ConsoleColor.DarkYellow => "\x1B[43m", + ConsoleColor.DarkBlue => "\x1B[44m", + ConsoleColor.DarkMagenta => "\x1B[45m", + ConsoleColor.DarkCyan => "\x1B[46m", + ConsoleColor.Gray => "\x1B[47m", + + _ => DefaultBackgroundColor + }; + } +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-custom/console-formatter-custom.csproj b/docs/core/extensions/snippets/logging/console-formatter-custom/console-formatter-custom.csproj new file mode 100644 index 0000000000000..6e38e3c303f8d --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-custom/console-formatter-custom.csproj @@ -0,0 +1,13 @@ + + + + Exe + net5.0 + Console.ExampleFormatters.Custom + + + + + + + diff --git a/docs/core/extensions/snippets/logging/console-formatter-json/Program.cs b/docs/core/extensions/snippets/logging/console-formatter-json/Program.cs new file mode 100644 index 0000000000000..9d8de3e8e7385 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-json/Program.cs @@ -0,0 +1,28 @@ +using System.Text.Json; +using System.Threading.Tasks; +using Microsoft.AspNetCore.Hosting; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; + +namespace Console.ExampleFormatters.Json +{ + class Program + { + static Task Main(string[] args) => + CreateHostBuilder(args).Build().RunAsync(); + + static IHostBuilder CreateHostBuilder(string[] args) => + Host.CreateDefaultBuilder(args) + .ConfigureWebHostDefaults(builder => builder.UseStartup()) + .ConfigureLogging(builder => + builder.AddJsonConsole(options => + { + options.IncludeScopes = false; + options.TimestampFormat = "hh:mm:ss "; + options.JsonWriterOptions = new JsonWriterOptions + { + Indented = true + }; + })); + } +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-json/Properties/launchSettings.json b/docs/core/extensions/snippets/logging/console-formatter-json/Properties/launchSettings.json new file mode 100644 index 0000000000000..bf164a203e5ac --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-json/Properties/launchSettings.json @@ -0,0 +1,27 @@ +{ + "iisSettings": { + "windowsAuthentication": false, + "anonymousAuthentication": true, + "iisExpress": { + "applicationUrl": "http://localhost:59449/", + "sslPort": 44370 + } + }, + "profiles": { + "IIS Express": { + "commandName": "IISExpress", + "launchBrowser": true, + "environmentVariables": { + "ASPNETCORE_ENVIRONMENT": "Development" + } + }, + "console-formatter-json": { + "commandName": "Project", + "launchBrowser": true, + "environmentVariables": { + "ASPNETCORE_ENVIRONMENT": "Development" + }, + "applicationUrl": "https://localhost:5001;http://localhost:5000" + } + } +} \ No newline at end of file diff --git a/docs/core/extensions/snippets/logging/console-formatter-json/Startup.cs b/docs/core/extensions/snippets/logging/console-formatter-json/Startup.cs new file mode 100644 index 0000000000000..889116603ead1 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-json/Startup.cs @@ -0,0 +1,52 @@ +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Hosting; +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; + +namespace Console.ExampleFormatters.Json +{ + public class Startup + { + public Startup(IConfiguration configuration) + { + Configuration = configuration; + } + + public IConfiguration Configuration { get; } + + // This method gets called by the runtime. Use this method to add services to the container. + public void ConfigureServices(IServiceCollection services) + { + services.AddControllersWithViews(); + } + + // This method gets called by the runtime. Use this method to configure the HTTP request pipeline. + public void Configure(IApplicationBuilder app, IWebHostEnvironment env) + { + if (env.IsDevelopment()) + { + app.UseDeveloperExceptionPage(); + } + else + { + app.UseExceptionHandler("/Home/Error"); + // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts. + app.UseHsts(); + } + app.UseHttpsRedirection(); + app.UseStaticFiles(); + + app.UseRouting(); + + app.UseAuthorization(); + + app.UseEndpoints(endpoints => + { + endpoints.MapControllerRoute( + name: "default", + pattern: "{controller=Home}/{action=Index}/{id?}"); + }); + } + } +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-json/appsettings.json b/docs/core/extensions/snippets/logging/console-formatter-json/appsettings.json new file mode 100644 index 0000000000000..ecbfacc4d3460 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-json/appsettings.json @@ -0,0 +1,27 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + }, + "Console": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + }, + "FormatterName": "json", + "FormatterOptions": { + "SingleLine": true, + "IncludeScopes": true, + "TimestampFormat": "HH:mm:ss ", + "UseUtcTimestamp": true, + "JsonWriterOptions": { + "Indented": true + } + } + } + }, + "AllowedHosts": "*" +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-json/console-formatter-json.csproj b/docs/core/extensions/snippets/logging/console-formatter-json/console-formatter-json.csproj new file mode 100644 index 0000000000000..57947a23960d8 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-json/console-formatter-json.csproj @@ -0,0 +1,13 @@ + + + + Exe + net5.0 + Console.ExampleFormatters.Json + + + + + + + diff --git a/docs/core/extensions/snippets/logging/console-formatter-json/example-output.json b/docs/core/extensions/snippets/logging/console-formatter-json/example-output.json new file mode 100644 index 0000000000000..6414fca7f0e99 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-json/example-output.json @@ -0,0 +1,12 @@ +{ + "Timestamp": "09:08:33 ", + "EventId": 0, + "LogLevel": "Information", + "Category": "Microsoft.Hosting.Lifetime", + "Message": "Now listening on: https://localhost:5001", + "State": { + "Message": "Now listening on: https://localhost:5001", + "address": "https://localhost:5001", + "{OriginalFormat}": "Now listening on: {address}" + } +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-simple/Program.cs b/docs/core/extensions/snippets/logging/console-formatter-simple/Program.cs new file mode 100644 index 0000000000000..c03595cbaa47f --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-simple/Program.cs @@ -0,0 +1,27 @@ +using Microsoft.Extensions.Logging; + +namespace Console.ExampleFormatters.Simple +{ + class Program + { + static void Main() + { + using ILoggerFactory loggerFactory = + LoggerFactory.Create(builder => + builder.AddSimpleConsole(options => + { + options.IncludeScopes = true; + options.SingleLine = true; + options.TimestampFormat = "hh:mm:ss "; + })); + + ILogger logger = loggerFactory.CreateLogger(); + using (logger.BeginScope("[scope is enabled]")) + { + logger.LogInformation("Hello World!"); + logger.LogInformation("Logs contain timestamp and log level."); + logger.LogInformation("Each log message is fit in a single line."); + } + } + } +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-simple/console-formatter-simple.csproj b/docs/core/extensions/snippets/logging/console-formatter-simple/console-formatter-simple.csproj new file mode 100644 index 0000000000000..387194f795f6d --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-simple/console-formatter-simple.csproj @@ -0,0 +1,14 @@ + + + + Exe + net5.0 + Console.ExampleFormatters.Simple + + + + + + + + diff --git a/docs/core/extensions/snippets/logging/console-formatter-systemd/Program.cs b/docs/core/extensions/snippets/logging/console-formatter-systemd/Program.cs new file mode 100644 index 0000000000000..7d29bf39e4775 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-systemd/Program.cs @@ -0,0 +1,27 @@ +using Microsoft.Extensions.Logging; + +namespace Console.ExampleFormatters.Systemd +{ + class Program + { + static void Main() + { + using ILoggerFactory loggerFactory = + LoggerFactory.Create(builder => + builder.AddSystemdConsole(options => + { + options.IncludeScopes = true; + options.TimestampFormat = "hh:mm:ss "; + })); + + ILogger logger = loggerFactory.CreateLogger(); + using (logger.BeginScope("[scope is enabled]")) + { + logger.LogInformation("Hello World!"); + logger.LogInformation("Logs contain timestamp and log level."); + logger.LogInformation("Systemd console logs never provide color options."); + logger.LogInformation("Systemd console logs always appear in a single line."); + } + } + } +} diff --git a/docs/core/extensions/snippets/logging/console-formatter-systemd/console-formatter-systemd.csproj b/docs/core/extensions/snippets/logging/console-formatter-systemd/console-formatter-systemd.csproj new file mode 100644 index 0000000000000..08431434fe220 --- /dev/null +++ b/docs/core/extensions/snippets/logging/console-formatter-systemd/console-formatter-systemd.csproj @@ -0,0 +1,13 @@ + + + + Exe + net5.0 + Console.ExampleFormatters.Systemd + + + + + + + diff --git a/docs/core/porting/index.md b/docs/core/porting/index.md index 2237e9335cd9d..fc094b7260d49 100644 --- a/docs/core/porting/index.md +++ b/docs/core/porting/index.md @@ -107,5 +107,10 @@ We recommend you use the following process when porting your project to .NET Cor > [!div class="nextstepaction"] > [Analyze dependencies](third-party-deps.md) -> [Package NuGet Package](../deploying/creating-nuget-packages.md) -> [ASP.NET to ASP.NET Core Migration](/aspnet/core/migration/proper-to-2x) +> [Package a NuGet package](../deploying/creating-nuget-packages.md) + +## See also + +- [ASP.NET to ASP.NET Core migration](/aspnet/core/migration/proper-to-2x) +- [Migrate WPF apps to .NET Core](/dotnet/desktop/wpf/migration/convert-project-from-net-framework) +- [Migrate Windows Forms apps to .NET Core](winforms.md) diff --git a/docs/csharp/language-reference/proposals/toc.yml b/docs/csharp/language-reference/proposals/toc.yml index cefcdbfdd005d..379a4f2cf5813 100644 --- a/docs/csharp/language-reference/proposals/toc.yml +++ b/docs/csharp/language-reference/proposals/toc.yml @@ -116,3 +116,5 @@ href: ../../../../_csharplang/proposals/csharp-9.0/function-pointers.md - name: Surpress emitting localsinit flag href: ../../../../_csharplang/proposals/csharp-9.0/skip-localsinit.md + - name: Unconstrained type parameter annotations + href: ../../../../_csharplang/proposals/csharp-9.0/unconstrained-type-parameter-annotations.md diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index feead8f85ce2c..de6c78de9dbf8 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -1560,6 +1560,8 @@ items: href: ../core/extensions/custom-logging-provider.md - name: High-performance logging href: ../core/extensions/high-performance-logging.md + - name: Console log formatting + href: ../core/extensions/console-log-formatter.md - name: HostBuilder (generic host) href: ../core/extensions/generic-host.md - name: Data access diff --git a/docs/standard/asynchronous-programming-patterns/asynchronous-programming-using-delegates.md b/docs/standard/asynchronous-programming-patterns/asynchronous-programming-using-delegates.md index 5ea88a19673ec..dc907d2bfa57a 100644 --- a/docs/standard/asynchronous-programming-patterns/asynchronous-programming-using-delegates.md +++ b/docs/standard/asynchronous-programming-patterns/asynchronous-programming-using-delegates.md @@ -9,11 +9,12 @@ helpviewer_keywords: - "calling synchronous methods in asynchronous manner" - "EndInvoke method" - "calling asynchronous methods" - - "delegates [.NET Framework], asynchronous" + - "delegates [.NET], asynchronous" - "synchronous calling in asynchronous manner" ms.assetid: 38a345ca-6963-4436-9608-5c9defef9c64 --- # Asynchronous Programming Using Delegates + Delegates enable you to call a synchronous method in an asynchronous manner. When you call a delegate synchronously, the `Invoke` method calls the target method directly on the current thread. If the `BeginInvoke` method is called, the common language runtime (CLR) queues the request and returns immediately to the caller. The target method is called asynchronously on a thread from the thread pool. The original thread, which submitted the request, is free to continue executing in parallel with the target method. If a callback method has been specified in the call to the `BeginInvoke` method, the callback method is called when the target method ends. In the callback method, the `EndInvoke` method obtains the return value and any input/output or output-only parameters. If no callback method is specified when calling `BeginInvoke`, `EndInvoke` can be called from the thread that called `BeginInvoke`. > [!IMPORTANT] @@ -25,7 +26,7 @@ Delegates enable you to call a synchronous method in an asynchronous manner. Whe ## Related Sections [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md) - Describes asynchronous programming with the .NET Framework. + Describes asynchronous programming in .NET. ## See also 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 8830afa57f5ce..473fb297e427e 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 @@ -6,26 +6,30 @@ helpviewer_keywords: - "Event-based Asynchronous Pattern" - "ProgressChangedEventArgs class" - "BackgroundWorker component" - - "events [.NET Framework], asynchronous" + - "events [.NET], asynchronous" - "AsyncOperationManager class" - - "threading [.NET Framework], asynchronous features" + - "threading [.NET], asynchronous features" - "AsyncOperation class" - "AsyncCompletedEventArgs class" ms.assetid: 4acd2094-4f46-4eff-9190-92d0d9ff47db --- # Best Practices for Implementing the Event-based Asynchronous Pattern + The Event-based Asynchronous Pattern provides you with an effective way to expose asynchronous behavior in classes, with familiar event and delegate semantics. To implement Event-based Asynchronous Pattern, you need to follow some specific behavioral requirements. The following sections describe requirements and guidelines you should consider when you implement a class that follows the Event-based Asynchronous Pattern. For an overview, see [Implementing the Event-based Asynchronous Pattern](implementing-the-event-based-asynchronous-pattern.md). -## Required Behavioral Guarantees +## Required Behavioral Guarantees + If you implement the Event-based Asynchronous Pattern, you must provide a number of guarantees to ensure that your class will behave properly and clients of your class can rely on such behavior. -### Completion +### Completion + Always invoke the MethodName**Completed** event handler when you have successful completion, an error, or a cancellation. Applications should never encounter a situation where they remain idle and completion never occurs. One exception to this rule is if the asynchronous operation itself is designed so that it never completes. -### Completed Event and EventArgs - For each separate MethodName**Async** method, apply the following design requirements: +### Completed Event and EventArgs + +For each separate MethodName**Async** method, apply the following design requirements: - Define a MethodName**Completed** event on the same class as the method. @@ -111,7 +115,8 @@ private void Form1_MethodNameCompleted(object sender, MethodNameCompletedEventAr - Catch any exceptions that occur in the asynchronous operation and set the value of the property to that exception. -### Threading and Contexts +### 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. diff --git a/docs/standard/asynchronous-programming-patterns/calling-asynchronous-methods-using-iasyncresult.md b/docs/standard/asynchronous-programming-patterns/calling-asynchronous-methods-using-iasyncresult.md index 8f1ef0ca5e128..89281360826ab 100644 --- a/docs/standard/asynchronous-programming-patterns/calling-asynchronous-methods-using-iasyncresult.md +++ b/docs/standard/asynchronous-programming-patterns/calling-asynchronous-methods-using-iasyncresult.md @@ -13,7 +13,8 @@ helpviewer_keywords: ms.assetid: 07fba116-045b-473c-a0b7-acdbeb49861f --- # Calling Asynchronous Methods Using IAsyncResult -Types in the .NET Framework and third-party class libraries can provide methods that allow an application to continue executing while performing asynchronous operations in threads other than the main application thread. The following sections describe and provide code examples that demonstrate the different ways you can call asynchronous methods that use the design pattern. + +Types in the .NET libraries and third-party class libraries can provide methods that allow an application to continue executing while performing asynchronous operations in threads other than the main application thread. The following sections describe and provide code examples that demonstrate the different ways you can call asynchronous methods that use the design pattern. - [Blocking Application Execution by Ending an Async Operation](blocking-application-execution-by-ending-an-async-operation.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 67aa9ecfac7bc..255b788480abe 100644 --- a/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md +++ b/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md @@ -16,15 +16,15 @@ helpviewer_keywords: - "WaitHandle class, code examples" - "asynchronous programming, status polling" - "polling asynchronous operation status" - - "delegates [.NET Framework], asynchronous" + - "delegates [.NET], asynchronous" - "synchronous calling in asynchronous manner" - "waiting for asynchronous calls" - - "status information [.NET Framework], asynchronous operations" + - "status information [.NET], asynchronous operations" ms.assetid: 41972034-92ed-450a-9664-ab93fcc6f1fb --- # Calling Synchronous Methods Asynchronously -The .NET Framework enables you to call any method asynchronously. To do this you define a delegate with the same signature as the method you want to call; the common language runtime automatically defines `BeginInvoke` and `EndInvoke` methods for this delegate, with the appropriate signatures. +.NET enables you to call any method asynchronously. To do this, you define a delegate with the same signature as the method you want to call. The common language runtime automatically defines `BeginInvoke` and `EndInvoke` methods for this delegate, with the appropriate signatures. > [!NOTE] > Asynchronous delegate calls, specifically the `BeginInvoke` and `EndInvoke` methods, are not supported in the .NET Compact Framework. 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 2ef3897016768..903c5f9d73ce5 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 @@ -9,17 +9,18 @@ helpviewer_keywords: - "Event-based Asynchronous Pattern" - "ProgressChangedEventArgs class" - "BackgroundWorker component" - - "events [.NET Framework], asynchronous" + - "events [.NET], asynchronous" - "Asynchronous Pattern" - "AsyncOperationManager class" - - "threading [.NET Framework], asynchronous features" - - "components [.NET Framework], asynchronous" + - "threading [.NET], asynchronous features" + - "components [.NET], asynchronous" - "AsyncOperation class" - "threading [Windows Forms], asynchronous features" - "AsyncCompletedEventArgs class" ms.assetid: 61f676b5-936f-40f6-83ce-f22805ec9c2f --- # 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 Overview](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. 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 e5cb6b56b540f..6c0871f0dd57a 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 @@ -4,19 +4,20 @@ description: Learn to consume the Task-based Asynchronous Pattern (TAP) when wor ms.date: "03/30/2017" ms.technology: dotnet-standard helpviewer_keywords: - - ".NET Framework, and TAP" - - "asynchronous design patterns, .NET Framework" - - "TAP, .NET Framework support for" - - "Task-based Asynchronous Pattern, .NET Framework support for" - - ".NET Framework, asynchronous design patterns" + - ".NET and TAP" + - "asynchronous design patterns, .NET" + - "TAP, .NET support for" + - "Task-based Asynchronous Pattern, .NET support for" + - ".NET, asynchronous design patterns" 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 - Starting with the .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. For more information about C# and Visual Basic language support in the .NET Framework 4.5, see the C# and Visual Basic language specifications. + +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. @@ -57,7 +58,8 @@ await someTask.ConfigureAwait(continueOnCapturedContext:false); ``` ## Canceling an Asynchronous Operation - Starting with the .NET Framework 4, TAP methods that support cancellation provide at least one overload that accepts a cancellation token ( object). + +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: @@ -529,7 +531,7 @@ public async void btnDownload_Click(object sender, RoutedEventArgs e) ``` ## Building Task-based Combinators - Because a task is able to completely represent an asynchronous operation and provide synchronous and asynchronous capabilities for joining with the operation, retrieving its results, and so on, you can build useful libraries of combinators that compose tasks to build larger patterns. As discussed in the previous section, the .NET Framework includes several built-in combinators, but you can also build your own. The following sections provide several examples of potential combinator methods and types. + Because a task is able to completely represent an asynchronous operation and provide synchronous and asynchronous capabilities for joining with the operation, retrieving its results, and so on, you can build useful libraries of combinators that compose tasks to build larger patterns. As discussed in the previous section, .NET includes several built-in combinators, but you can also build your own. The following sections provide several examples of potential combinator methods and types. ### RetryOnFault In many situations, you may want to retry an operation if a previous attempt fails. For synchronous code, you might build a helper method such as `RetryOnFault` in the following example to accomplish this: @@ -826,7 +828,7 @@ private static void Produce(int data) ``` > [!NOTE] -> The namespace is available in the .NET Framework 4.5 through **NuGet**. To install the assembly that contains the namespace, open your project in Visual Studio, choose **Manage NuGet Packages** from the Project menu, and search online for the Microsoft.Tpl.Dataflow package. +> The namespace is available as a NuGet package. To install the assembly that contains the namespace, open your project in Visual Studio, choose **Manage NuGet Packages** from the Project menu, and search online for the `System.Threading.Tasks.Dataflow` package. ## See also diff --git a/docs/standard/asynchronous-programming-patterns/deciding-when-to-implement-the-event-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/deciding-when-to-implement-the-event-based-asynchronous-pattern.md index 1de3e239b3c6b..4a9c11e478b50 100644 --- a/docs/standard/asynchronous-programming-patterns/deciding-when-to-implement-the-event-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/deciding-when-to-implement-the-event-based-asynchronous-pattern.md @@ -6,16 +6,16 @@ helpviewer_keywords: - "Event-based Asynchronous Pattern" - "ProgressChangedEventArgs class" - "BackgroundWorker component" - - "events [.NET Framework], asynchronous" + - "events [.NET], asynchronous" - "AsyncOperationManager class" - - "threading [.NET Framework], asynchronous features" + - "threading [.NET], asynchronous features" - "AsyncOperation class" - "AsyncCompletedEventArgs class" ms.assetid: a00046aa-785d-4f7f-a8e5-d06475ea50da --- # Deciding When to Implement the Event-based Asynchronous Pattern -The Event-based Asynchronous Pattern provides a pattern for exposing the asynchronous behavior of a class. With the introduction of this pattern, the .NET Framework defines two patterns for exposing asynchronous behavior: the Asynchronous Pattern based on the interface, and the event-based pattern. This topic describes when it is appropriate for you to implement both patterns. +The Event-based Asynchronous Pattern provides a pattern for exposing the asynchronous behavior of a class. With the introduction of this pattern, .NET defines two patterns for exposing asynchronous behavior: the Asynchronous Pattern based on the interface, and the event-based pattern. This article describes when it's appropriate for you to implement both patterns. For more information about asynchronous programming with the interface, see [Asynchronous Programming Model (APM)](asynchronous-programming-model-apm.md). diff --git a/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md b/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md index 808e2368c712c..18aeb62dae58c 100644 --- a/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md +++ b/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md @@ -14,7 +14,7 @@ ms.assetid: c6baed9f-2a25-4728-9a9a-53b7b14840cf There are a number of ways to expose asynchronous features to client code. The Event-based Asynchronous Pattern prescribes one way for classes to present asynchronous behavior. > [!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). +> Starting with .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). ## In This Section 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 8adb2abbbda98..6efb8ee77c51a 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 @@ -10,10 +10,10 @@ helpviewer_keywords: - "Event-based Asynchronous Pattern" - "ProgressChangedEventArgs class" - "BackgroundWorker component" - - "events [.NET Framework], asynchronous" + - "events [.NET], asynchronous" - "Asynchronous Pattern" - "AsyncOperationManager class" - - "threading [.NET Framework], asynchronous features" + - "threading [.NET], asynchronous features" - "AsyncOperation class" - "AsyncCompletedEventArgs class" ms.assetid: 792aa8da-918b-458e-b154-9836b97735f3 diff --git a/docs/standard/asynchronous-programming-patterns/how-to-implement-a-client-of-the-event-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/how-to-implement-a-client-of-the-event-based-asynchronous-pattern.md index 158b85a7e1d18..1a3a2e729d2d9 100644 --- a/docs/standard/asynchronous-programming-patterns/how-to-implement-a-client-of-the-event-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/how-to-implement-a-client-of-the-event-based-asynchronous-pattern.md @@ -9,11 +9,11 @@ helpviewer_keywords: - "Event-based Asynchronous Pattern" - "ProgressChangedEventArgs class" - "BackgroundWorker component" - - "events [.NET Framework], asynchronous" + - "events [.NET], asynchronous" - "Asynchronous Pattern" - "AsyncOperationManager class" - - "threading [.NET Framework], asynchronous features" - - "components [.NET Framework], asynchronous" + - "threading [.NET], asynchronous features" + - "components [.NET], asynchronous" - "AsyncOperation class" - "threading [Windows Forms], asynchronous features" - "AsyncCompletedEventArgs class" diff --git a/docs/standard/asynchronous-programming-patterns/how-to-use-components-that-support-the-event-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/how-to-use-components-that-support-the-event-based-asynchronous-pattern.md index 9a0ea31481753..dc2bc1281ca3e 100644 --- a/docs/standard/asynchronous-programming-patterns/how-to-use-components-that-support-the-event-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/how-to-use-components-that-support-the-event-based-asynchronous-pattern.md @@ -9,11 +9,11 @@ helpviewer_keywords: - "Event-based Asynchronous Pattern" - "ProgressChangedEventArgs class" - "BackgroundWorker component" - - "events [.NET Framework], asynchronous" + - "events [.NET], asynchronous" - "Asynchronous Pattern" - "AsyncOperationManager class" - - "threading [.NET Framework], asynchronous features" - - "components [.NET Framework], asynchronous" + - "threading [.NET], asynchronous features" + - "components [.NET], asynchronous" - "AsyncOperation class" - "threading [Windows Forms], asynchronous features" - "AsyncCompletedEventArgs class" 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 60d49ff9a94b6..873154dbd6e9a 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 @@ -10,11 +10,11 @@ helpviewer_keywords: - "Event-based Asynchronous Pattern" - "ProgressChangedEventArgs class" - "BackgroundWorker component" - - "events [.NET Framework], asynchronous" + - "events [.NET], asynchronous" - "Asynchronous Pattern" - "AsyncOperationManager class" - - "threading [.NET Framework], asynchronous features" - - "components [.NET Framework], asynchronous" + - "threading [.NET], asynchronous features" + - "components [.NET], asynchronous" - "AsyncOperation class" - "AsyncCompletedEventArgs class" ms.assetid: 43402d19-8d30-426d-8785-1a4478233bfa @@ -207,7 +207,7 @@ Invoke that event handler on the appropriate thread as described in [Best Practi ## Handling Out and Ref Parameters in Methods -Although the use of `out` and `ref` is, in general, discouraged in the .NET Framework, here are the rules to follow when they are present: +Although the use of `out` and `ref` is, in general, discouraged in .NET, here are the rules to follow when they are present: Given a synchronous method *MethodName*: 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 754e80a70d8f1..51b5bcf257bb3 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 @@ -6,11 +6,10 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - ".NET Framework, and TAP" - - "asynchronous design patterns, .NET Framework" - - "TAP, .NET Framework support for" - - "Task-based Asynchronous Pattern, .NET Framework support for" - - ".NET Framework, asynchronous design patterns" + - "asynchronous design patterns, .NET" + - "TAP, .NET support for" + - "Task-based Asynchronous Pattern, .NET support for" + - ".NET, asynchronous design patterns" ms.assetid: fab6bd41-91bd-44ad-86f9-d8319988aa78 --- # Implementing the Task-based Asynchronous Pattern @@ -28,7 +27,7 @@ You may implement the TAP pattern manually for better control over implementatio [!code-vb[Conceptual.TAP_Patterns#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap_patterns/vb/patterns1.vb#1)] ### Hybrid approach - You may find it useful to implement the TAP pattern manually but to delegate the core logic for the implementation to the compiler. For example, you may want to use the hybrid approach when you want to verify arguments outside a compiler-generated asynchronous method so that exceptions can escape to the method’s direct caller rather than being exposed through the object: + You may find it useful to implement the TAP pattern manually but to delegate the core logic for the implementation to the compiler. For example, you may want to use the hybrid approach when you want to verify arguments outside a compiler-generated asynchronous method so that exceptions can escape to the method's direct caller rather than being exposed through the object: [!code-csharp[Conceptual.TAP_Patterns#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap_patterns/cs/patterns1.cs#2)] [!code-vb[Conceptual.TAP_Patterns#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap_patterns/vb/patterns1.vb#2)] @@ -43,9 +42,9 @@ The class is ide You can generate compute-bound tasks in the following ways: -- In the .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.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 the .NET Framework 4.5 and later versions (including .NET Core and .NET Standard), use the static method as a shortcut to . You may use to easily launch a compute-bound task that targets the thread pool. In the .NET Framework 4.5 and later versions, 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(…)`. - Use the constructors of the `Task` type or the `Start` method if you want to generate and schedule the task separately. Public methods must only return tasks that have already been started. @@ -76,7 +75,7 @@ Let's say that you want to create a task that will complete after a specified pe [!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)] -Starting with the .NET Framework 4.5, 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)] diff --git a/docs/standard/asynchronous-programming-patterns/index.md b/docs/standard/asynchronous-programming-patterns/index.md index 22c8b1ef1e807..457bb9ae2b82a 100644 --- a/docs/standard/asynchronous-programming-patterns/index.md +++ b/docs/standard/asynchronous-programming-patterns/index.md @@ -5,16 +5,16 @@ ms.date: "10/16/2018" ms.technology: dotnet-standard helpviewer_keywords: - "asynchronous design patterns, .NET" - - ".NET Framework, asynchronous design patterns" + - ".NET, asynchronous design patterns" ms.assetid: 4ece5c0b-f8fe-4114-9862-ac02cfe5a5d7 --- # Asynchronous programming patterns .NET provides three patterns for performing asynchronous operations: -- **Task-based Asynchronous Pattern (TAP)**, which uses a single method to represent the initiation and completion of an asynchronous operation. TAP was introduced in the .NET Framework 4. **It's the recommended approach to asynchronous programming in .NET.** The [async](../../csharp/language-reference/keywords/async.md) and [await](../../csharp/language-reference/operators/await.md) keywords in C# and the [Async](../../visual-basic/language-reference/modifiers/async.md) and [Await](../../visual-basic/language-reference/operators/await-operator.md) operators in Visual Basic add language support for TAP. For more information, see [Task-based Asynchronous Pattern (TAP)](task-based-asynchronous-pattern-tap.md). +- **Task-based Asynchronous Pattern (TAP)**, which uses a single method to represent the initiation and completion of an asynchronous operation. TAP was introduced in .NET Framework 4. **It's the recommended approach to asynchronous programming in .NET.** The [async](../../csharp/language-reference/keywords/async.md) and [await](../../csharp/language-reference/operators/await.md) keywords in C# and the [Async](../../visual-basic/language-reference/modifiers/async.md) and [Await](../../visual-basic/language-reference/operators/await-operator.md) operators in Visual Basic add language support for TAP. For more information, see [Task-based Asynchronous Pattern (TAP)](task-based-asynchronous-pattern-tap.md). -- **Event-based Asynchronous Pattern (EAP)**, which is the event-based legacy model for providing asynchronous behavior. It requires a method that has the `Async` suffix and one or more events, event handler delegate types, and `EventArg`-derived types. EAP was introduced in the .NET Framework 2.0. It's no longer recommended for new development. For more information, see [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md). +- **Event-based Asynchronous Pattern (EAP)**, which is the event-based legacy model for providing asynchronous behavior. It requires a method that has the `Async` suffix and one or more events, event handler delegate types, and `EventArg`-derived types. EAP was introduced in .NET Framework 2.0. It's no longer recommended for new development. For more information, see [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md). - **Asynchronous Programming Model (APM)** pattern (also called the pattern), which is the legacy model that uses the interface to provide asynchronous behavior. In this pattern, synchronous operations require `Begin` and `End` methods (for example, `BeginWrite` and `EndWrite` to implement an asynchronous write operation). This pattern is no longer recommended for new development. For more information, see [Asynchronous Programming Model (APM)](asynchronous-programming-model-apm.md). 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 110e9c386b4db..568e350da51be 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 @@ -6,30 +6,24 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - ".NET Framework, and TAP" - - "asynchronous design patterns, .NET Framework" - - "TAP, .NET Framework support for" - - "Task-based Asynchronous Pattern, .NET Framework support for" - - ".NET Framework, asynchronous design patterns" + - "asynchronous design patterns, .NET" + - "TAP, .NET support for" + - "Task-based Asynchronous Pattern, .NET support for" + - ".NET, asynchronous design patterns" ms.assetid: f120a5d9-933b-4d1d-acb6-f034a57c3749 --- # Interop with Other Asynchronous Patterns and Types -The .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. The .NET Framework 2.0 added the [Event-based Asynchronous Pattern (EAP)](event-based-asynchronous-pattern-eap.md). Starting with the .NET Framework 4, the [Task-based Asynchronous Pattern (TAP)](task-based-asynchronous-pattern-tap.md) supersedes both APM and EAP, but provides the ability to easily build migration routines from the earlier patterns. - - In this topic: - -- [Tasks and APM](#APM) ([from APM to TAP](#ApmToTap) or [from TAP to APM](#TapToApm)) - -- [Tasks and EAP](#EAP) - -- [Tasks and wait handles](#WaitHandles) ([from wait handles to TAP](#WHToTap) or [from TAP to wait handles](#TapToWH)) - - -## Tasks and the Asynchronous Programming Model (APM) + +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 - Because the [Asynchronous Programming Model (APM)](asynchronous-programming-model-apm.md) pattern is very structured, it is quite easy to build a wrapper to expose an APM implementation as a TAP implementation. In fact, the .NET Framework, starting with .NET Framework 4, includes helper routines in the form of method overloads to provide this translation. + 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: @@ -50,7 +44,6 @@ The .NET Framework 1.0 introduced the pattern, otherw [!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 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. @@ -74,31 +67,27 @@ The .NET Framework 1.0 introduced the pattern, otherw [!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) 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-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: + 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: 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 32a7d8780af21..e7abb99ed15a5 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 @@ -8,7 +8,7 @@ dev_langs: helpviewer_keywords: - "asynchronous programming, status polling" - "polling asynchronous operation status" - - "status information [.NET Framework], asynchronous operations" + - "status information [.NET], asynchronous operations" ms.assetid: b541af31-dacb-4e20-8847-1b1ff7c35363 --- # Polling for the Status of an Asynchronous Operation 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 4ea2f2afc2820..871deb08e486d 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 @@ -6,12 +6,11 @@ ms.technology: dotnet-standard dev_langs: - "csharp" - "vb" -helpviewer_keywords: - - ".NET Framework, and TAP" - - "asynchronous design patterns, .NET Framework" - - "TAP, .NET Framework support for" - - "Task-based Asynchronous Pattern, .NET Framework support for" - - ".NET Framework, asynchronous design patterns" +helpviewer_keywords: + - "asynchronous design patterns, .NET" + - "TAP, .NET support for" + - "Task-based Asynchronous Pattern, .NET support for" + - ".NET, asynchronous design patterns" ms.assetid: 8cef1fcf-6f9f-417c-b21f-3fd8bac75007 --- # Task-based asynchronous pattern @@ -89,7 +88,7 @@ TAP uses a single method to represent the initiation and completion of an asynch 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 - The .NET Framework 4.5 provides a single implementation: . The class is declared as follows: +.NET provides the class, which implements . The class is declared as follows: ```csharp public class Progress : IProgress @@ -97,18 +96,9 @@ public class Progress : IProgress public Progress(); public Progress(Action handler); protected virtual void OnReport(T value); - public event EventHandler ProgressChanged; + public event EventHandler? ProgressChanged; } -``` - -```vb -Public Class Progress(Of T) : Inherits IProgress(Of T) - Public Sub New() - Public Sub New(handler As Action(Of T)) - Protected Overridable Sub OnReport(value As T) - Public Event ProgressChanged As EventHandler(Of T> -End Class -``` +``` 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. diff --git a/docs/standard/attributes/applying-attributes.md b/docs/standard/attributes/applying-attributes.md index 4e30a15800521..8bd1d3c2f635b 100644 --- a/docs/standard/attributes/applying-attributes.md +++ b/docs/standard/attributes/applying-attributes.md @@ -7,8 +7,8 @@ dev_langs: - "vb" - "cpp" helpviewer_keywords: - - "assemblies [.NET Framework], attributes" - - "attributes [.NET Framework], applying" + - "assemblies [.NET], attributes" + - "attributes [.NET], applying" ms.assetid: dd7604eb-9fa3-4b60-b2dd-b47739fa3148 --- # Apply attributes diff --git a/docs/standard/attributes/index.md b/docs/standard/attributes/index.md index 1a6108b6b815c..541e8f60ef5be 100644 --- a/docs/standard/attributes/index.md +++ b/docs/standard/attributes/index.md @@ -27,7 +27,7 @@ The common language runtime allows you to add keyword-like descriptive declarati |[Applying Attributes](applying-attributes.md)|Describes how to apply an attribute to an element of your code.| |[Writing Custom Attributes](writing-custom-attributes.md)|Describes how to design custom attribute classes.| |[Retrieving Information Stored in Attributes](retrieving-information-stored-in-attributes.md)|Describes how to retrieve custom attributes for code that is loaded into the execution context.| -|[Metadata and Self-Describing Components](../metadata-and-self-describing-components.md)|Provides an overview of metadata and describes how it is implemented in a .NET Framework portable executable (PE) file.| +|[Metadata and Self-Describing Components](../metadata-and-self-describing-components.md)|Provides an overview of metadata and describes how it is implemented in a .NET portable executable (PE) file.| |[How to: Load Assemblies into the Reflection-Only Context](../../framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context.md)|Explains how to retrieve custom attribute information in the reflection-only context.| ## Reference diff --git a/docs/standard/attributes/retrieving-information-stored-in-attributes.md b/docs/standard/attributes/retrieving-information-stored-in-attributes.md index 4a707678b7b10..4cd1074b2a0b0 100644 --- a/docs/standard/attributes/retrieving-information-stored-in-attributes.md +++ b/docs/standard/attributes/retrieving-information-stored-in-attributes.md @@ -10,7 +10,7 @@ dev_langs: helpviewer_keywords: - "retrieving attributes" - "multiple attribute instances" - - "attributes [.NET Framework], retrieving" + - "attributes [.NET], retrieving" ms.assetid: 37dfe4e3-7da0-48b6-a3d9-398981524e1c --- # Retrieving Information Stored in Attributes diff --git a/docs/standard/attributes/writing-custom-attributes.md b/docs/standard/attributes/writing-custom-attributes.md index b79f35720c24e..ee187c1271216 100644 --- a/docs/standard/attributes/writing-custom-attributes.md +++ b/docs/standard/attributes/writing-custom-attributes.md @@ -10,7 +10,7 @@ dev_langs: helpviewer_keywords: - "multiple attribute instances" - "AttributeTargets enumeration" - - "attributes [.NET Framework], custom" + - "attributes [.NET], custom" - "AllowMultiple property" - "custom attributes" - "AttributeUsageAttribute class, custom attributes" 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 c731d0ca9851a..35d7faf401f11 100644 --- a/docs/standard/base-types/alternation-constructs-in-regular-expressions.md +++ b/docs/standard/base-types/alternation-constructs-in-regular-expressions.md @@ -13,7 +13,7 @@ helpviewer_keywords: - "alternation constructs" - "optional matching patterns" - "constructs, alternation" - - ".NET Framework regular expressions, alternation constructs" + - ".NET regular expressions, alternation constructs" ms.assetid: 071e22e9-fbb0-4ecf-add1-8d2424f9f2d1 --- # Alternation Constructs in Regular Expressions diff --git a/docs/standard/base-types/anchors-in-regular-expressions.md b/docs/standard/base-types/anchors-in-regular-expressions.md index 4a0cd85ae7ea6..257ca5294f267 100644 --- a/docs/standard/base-types/anchors-in-regular-expressions.md +++ b/docs/standard/base-types/anchors-in-regular-expressions.md @@ -13,8 +13,8 @@ helpviewer_keywords: - "anchors, in regular expressions" - "metacharacters, atomic zero-width assertions" - "metacharacters, anchors" - - ".NET Framework regular expressions, anchors" - - ".NET Framework regular expressions, atomic zero-width assertions" + - ".NET regular expressions, anchors" + - ".NET regular expressions, atomic zero-width assertions" ms.assetid: 336391f6-2614-499b-8b1b-07a6837108a7 --- # Anchors in Regular Expressions 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 3fcaf76866028..c78767e41a4a5 100644 --- a/docs/standard/base-types/backreference-constructs-in-regular-expressions.md +++ b/docs/standard/base-types/backreference-constructs-in-regular-expressions.md @@ -9,7 +9,7 @@ dev_langs: helpviewer_keywords: - "backreferences" - "constructs, backreference" - - ".NET Framework regular expressions, backreference constructs" + - ".NET regular expressions, backreference constructs" - "regular expressions, backreference constructs" ms.assetid: 567a4b8d-0e79-49dc-8df9-f4b1aa376a2a --- diff --git a/docs/standard/base-types/backtracking-in-regular-expressions.md b/docs/standard/base-types/backtracking-in-regular-expressions.md index 30066035b4be7..4a8286ef9870e 100644 --- a/docs/standard/base-types/backtracking-in-regular-expressions.md +++ b/docs/standard/base-types/backtracking-in-regular-expressions.md @@ -7,14 +7,14 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - ".NET Framework regular expressions, backtracking" + - ".NET regular expressions, backtracking" - "alternative matching patterns" - "optional matching patterns" - "searching with regular expressions, backtracking" - "pattern-matching with regular expressions, backtracking" - "backtracking" - - "regular expressions [.NET Framework], backtracking" - - "strings [.NET Framework], regular expressions" + - "regular expressions [.NET], backtracking" + - "strings [.NET], regular expressions" - "parsing text with regular expressions, backtracking" ms.assetid: 34df1152-0b22-4a1c-a76c-3c28c47b70d8 --- diff --git a/docs/standard/base-types/basic-manipulations.md b/docs/standard/base-types/basic-manipulations.md index 4b6c1cc703d4a..a65165585ec50 100644 --- a/docs/standard/base-types/basic-manipulations.md +++ b/docs/standard/base-types/basic-manipulations.md @@ -7,7 +7,7 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "strings [.NET Framework], examples" + - "strings [.NET], examples" ms.assetid: 121d1eae-251b-44c0-8818-57da04b8215e --- # How to: Perform Basic String Manipulations in .NET diff --git a/docs/standard/base-types/basic-string-operations.md b/docs/standard/base-types/basic-string-operations.md index a1a12201cb356..8d615575290bb 100644 --- a/docs/standard/base-types/basic-string-operations.md +++ b/docs/standard/base-types/basic-string-operations.md @@ -4,7 +4,7 @@ description: Learn about the basic operations that you can perform on strings. ms.date: "03/30/2017" ms.technology: dotnet-standard helpviewer_keywords: - - "strings [.NET Framework], basic string operations" + - "strings [.NET], basic string operations" - "custom strings" ms.assetid: 8133d357-90b5-4b62-9927-43323d99b6b6 ms.custom: seadec18 diff --git a/docs/standard/base-types/best-practices-strings.md b/docs/standard/base-types/best-practices-strings.md index 1a4b212eec0f5..0ff522249f7d6 100644 --- a/docs/standard/base-types/best-practices-strings.md +++ b/docs/standard/base-types/best-practices-strings.md @@ -7,16 +7,16 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "strings [.NET Framework],searching" + - "strings [.NET],searching" - "best practices,string comparison and sorting" - - "strings [.NET Framework],best practices" - - "strings [.NET Framework],basic string operations" + - "strings [.NET],best practices" + - "strings [.NET],basic string operations" - "sorting strings" - - "strings [.NET Framework],sorting" - - "string comparison [.NET Framework],best practices" + - "strings [.NET],sorting" + - "string comparison [.NET],best practices" - "string sorting" - "comparing strings" - - "strings [.NET Framework],comparing" + - "strings [.NET],comparing" ms.assetid: b9f0bf53-e2de-4116-8ce9-d4f91a1df4f7 --- # Best Practices for Using Strings in .NET diff --git a/docs/standard/base-types/changing-case.md b/docs/standard/base-types/changing-case.md index 82a8304602eed..e0336a9e439c7 100644 --- a/docs/standard/base-types/changing-case.md +++ b/docs/standard/base-types/changing-case.md @@ -7,7 +7,7 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "strings [.NET Framework], case" + - "strings [.NET], case" - "case sensitivity" - "ToUpper method" - "ToLower method" 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 acfef1ec4ace2..c9792515ed15d 100644 --- a/docs/standard/base-types/character-classes-in-regular-expressions.md +++ b/docs/standard/base-types/character-classes-in-regular-expressions.md @@ -10,7 +10,7 @@ helpviewer_keywords: - "character classes" - "regular expressions, character classes" - "characters, matching syntax" - - ".NET Framework regular expressions, character classes" + - ".NET regular expressions, character classes" ms.assetid: 0f8bffab-ee0d-4e0e-9a96-2b4a252bb7e4 --- # Character classes in regular expressions @@ -42,7 +42,7 @@ A character class defines a set of characters, any one of which can occur in an .NET supports character class subtraction expressions, which enables you to define a set of characters as the result of excluding one character class from another character class. For more information, see [Character Class Subtraction](#CharacterClassSubtraction). > [!NOTE] -> Character classes that match characters by category, such as [\w](#WordCharacter) to match word characters or [\p{}](#CategoryOrBlock) to match a Unicode category, rely on the class to provide information about character categories. Starting with the .NET Framework 4.6.2, character categories are based on [The Unicode Standard, Version 8.0.0](https://www.unicode.org/versions/Unicode8.0.0/). In the .NET Framework 4 through the .NET Framework 4.6.1, they are based on [The Unicode Standard, Version 6.3.0](https://www.unicode.org/versions/Unicode6.3.0/). +> Character classes that match characters by category, such as [\w](#WordCharacter) to match word characters or [\p{}](#CategoryOrBlock) to match a Unicode category, rely on the class to provide information about character categories. In .NET Framework 4.6.2 and later versions, character categories are based on [The Unicode Standard, Version 8.0.0](https://www.unicode.org/versions/Unicode8.0.0/). ## Positive character group: [ ] diff --git a/docs/standard/base-types/character-escapes-in-regular-expressions.md b/docs/standard/base-types/character-escapes-in-regular-expressions.md index d167641173202..71c6bfc41cd99 100644 --- a/docs/standard/base-types/character-escapes-in-regular-expressions.md +++ b/docs/standard/base-types/character-escapes-in-regular-expressions.md @@ -12,7 +12,7 @@ helpviewer_keywords: - "characters, escapes" - "regular expressions, character escapes" - "escape characters" - - ".NET Framework regular expressions, character escapes" + - ".NET regular expressions, character escapes" - "constructs, character escapes" ms.assetid: f49cc9cc-db7d-4058-8b8a-422bc08b29b0 --- diff --git a/docs/standard/base-types/common-type-system.md b/docs/standard/base-types/common-type-system.md index d3485c728d04c..c2fe9d1859aa6 100644 --- a/docs/standard/base-types/common-type-system.md +++ b/docs/standard/base-types/common-type-system.md @@ -9,11 +9,11 @@ dev_langs: helpviewer_keywords: - "type system" - "common type system" - - "assemblies [.NET Framework], types" + - "assemblies [.NET], types" - "reference types" - "value types" - "cross-language interoperability" - - "namespaces [.NET Framework], types" + - "namespaces [.NET], types" - "types, about types" ms.assetid: 53c57c96-83e1-4ee3-9543-9ac832671a89 --- diff --git a/docs/standard/base-types/comparing.md b/docs/standard/base-types/comparing.md index 295cd28408693..0391ebc73f059 100644 --- a/docs/standard/base-types/comparing.md +++ b/docs/standard/base-types/comparing.md @@ -13,7 +13,7 @@ helpviewer_keywords: - "CompareTo method" - "IndexOf method" - "Compare method" - - "strings [.NET Framework], comparing" + - "strings [.NET], comparing" - "CompareOrdinal method" - "EndsWith method" - "Equals method" 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 815d635ef248a..e0885825c6703 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 @@ -5,8 +5,8 @@ ms.technology: dotnet-standard helpviewer_keywords: - "parsing text with regular expressions, compilation" - "searching with regular expressions, compilation" - - ".NET Framework regular expressions, engines" - - ".NET Framework regular expressions, compilation" + - ".NET regular expressions, engines" + - ".NET regular expressions, compilation" - "regular expressions, compilation" - "compilation, regular expressions" - "pattern-matching with regular expressions, compilation" diff --git a/docs/standard/base-types/composite-formatting.md b/docs/standard/base-types/composite-formatting.md index bb04302865968..0e2a9e1d5cd0b 100644 --- a/docs/standard/base-types/composite-formatting.md +++ b/docs/standard/base-types/composite-formatting.md @@ -8,11 +8,11 @@ dev_langs: - "vb" helpviewer_keywords: - "parameter specifiers" - - "strings [.NET Framework], alignment" + - "strings [.NET], alignment" - "format specifiers, composite formatting" - - "strings [.NET Framework], composite" + - "strings [.NET], composite" - "composite formatting" - - "objects [.NET Framework], formatting multiple objects" + - "objects [.NET], formatting multiple objects" ms.assetid: 87b7d528-73f6-43c6-b71a-f23043039a49 --- # Composite formatting @@ -78,7 +78,7 @@ The composite formatting feature is supported by methods such as the following: ### Format String Component The optional *formatString* component is a format string that is appropriate for the type of object being formatted. Specify a standard or custom numeric format string if the corresponding object is a numeric value, a standard or custom date and time format string if the corresponding object is a object, or an [enumeration format string](enumeration-format-strings.md) if the corresponding object is an enumeration value. If *formatString* is not specified, the general ("G") format specifier for a numeric, date and time, or enumeration type is used. The colon is required if *formatString* is specified. - The following table lists types or categories of types in the .NET Framework class library that support a predefined set of format strings, and provides links to the topics that list the supported format strings. Note that string formatting is an extensible mechanism that makes it possible to define new format strings for all existing types as well as to define a set of format strings supported by an application-defined type. For more information, see the and interface topics. + The following table lists types or categories of types in the .NET class library that support a predefined set of format strings, and provides links to the topics that list the supported format strings. Note that string formatting is an extensible mechanism that makes it possible to define new format strings for all existing types as well as to define a set of format strings supported by an application-defined type. For more information, see the and interface topics. |Type or type category|See| |---------------------------|---------| diff --git a/docs/standard/base-types/conversion-tables.md b/docs/standard/base-types/conversion-tables.md index 5901765a1c679..02ab4a3d7a41d 100644 --- a/docs/standard/base-types/conversion-tables.md +++ b/docs/standard/base-types/conversion-tables.md @@ -9,8 +9,8 @@ helpviewer_keywords: - "converting types, narrowing conversions" - "converting types, widening conversions" - "base types, converting" - - "tables [.NET Framework], type conversions" - - "data types [.NET Framework], converting" + - "tables [.NET], type conversions" + - "data types [.NET], converting" ms.assetid: 0ea65c59-85eb-4a52-94ca-c36d3bd13058 --- # Type Conversion Tables in .NET diff --git a/docs/standard/base-types/creating-new.md b/docs/standard/base-types/creating-new.md index fee710696ecee..54aaa7563e18f 100644 --- a/docs/standard/base-types/creating-new.md +++ b/docs/standard/base-types/creating-new.md @@ -11,12 +11,13 @@ helpviewer_keywords: - "Join method" - "Format method" - "Concat method" - - "strings [.NET Framework], creating" + - "strings [.NET], creating" - "Insert method" ms.assetid: 06fdf123-2fac-4459-8904-eb48ab908a30 --- # Creating New Strings in .NET -The .NET Framework allows strings to be created using simple assignment, and also overloads a class constructor to support string creation using a number of different parameters. The .NET Framework also provides several methods in the class that create new string objects by combining several strings, arrays of strings, or objects. + +.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. ## Creating Strings Using Assignment The easiest way to create a new object is simply to assign a string literal to a object. 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 d01b6a73bf499..fb84ccd032280 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 @@ -8,12 +8,12 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "formatting [.NET Framework], dates" + - "formatting [.NET], dates" - "custom DateTime format string" - "format specifiers, custom date and time" - "format strings" - "custom date and time format strings" - - "formatting [.NET Framework], time" + - "formatting [.NET], time" - "date and time strings" ms.assetid: 98b374e3-0cc2-4c78-ab44-efb671d71984 --- diff --git a/docs/standard/base-types/custom-numeric-format-strings.md b/docs/standard/base-types/custom-numeric-format-strings.md index 76fb57aa744d0..151fc52351c05 100644 --- a/docs/standard/base-types/custom-numeric-format-strings.md +++ b/docs/standard/base-types/custom-numeric-format-strings.md @@ -8,13 +8,13 @@ dev_langs: - "vb" - "cpp" helpviewer_keywords: - - "numeric format strings [.NET Framework]" - - "formatting [.NET Framework], numbers" + - "numeric format strings [.NET]" + - "formatting [.NET], numbers" - "format strings" - "custom numeric format strings" - - "numbers [.NET Framework], formatting" + - "numbers [.NET], formatting" - "format specifiers, numeric" - - "formatting numbers [.NET Framework]" + - "formatting numbers [.NET]" - "format specifiers, custom numeric format strings" ms.assetid: 6f74fd32-6c6b-48ed-8241-3c2b86dea5f4 --- diff --git a/docs/standard/base-types/custom-timespan-format-strings.md b/docs/standard/base-types/custom-timespan-format-strings.md index f40042f0ce548..564f08e91658a 100644 --- a/docs/standard/base-types/custom-timespan-format-strings.md +++ b/docs/standard/base-types/custom-timespan-format-strings.md @@ -9,9 +9,9 @@ dev_langs: helpviewer_keywords: - "format specifiers, custom time interval" - "format strings" - - "formatting [.NET Framework], time interval" + - "formatting [.NET], time interval" - "custom time interval format strings" - - "formatting [.NET Framework], time" + - "formatting [.NET], time" - "custom TimeSpan format strings" ms.assetid: a63ebf55-7269-416b-b4f5-286f6c03bf0e --- 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 6702ca94c49ca..46318c184ce74 100644 --- a/docs/standard/base-types/details-of-regular-expression-behavior.md +++ b/docs/standard/base-types/details-of-regular-expression-behavior.md @@ -7,12 +7,12 @@ dev_langs: - "vb" helpviewer_keywords: - "regular expressions, behavior" - - ".NET Framework regular expressions, behavior" + - ".NET regular expressions, behavior" ms.assetid: 0ee1a6b8-caac-41d2-917f-d35570021b10 --- # Details of regular expression behavior -The .NET Framework regular expression engine is a backtracking regular expression matcher that incorporates a traditional Nondeterministic Finite Automaton (NFA) engine such as that used by Perl, Python, Emacs, and Tcl. This distinguishes it from faster, but more limited, pure regular expression Deterministic Finite Automaton (DFA) engines such as those found in awk, egrep, or lex. This also distinguishes it from standardized, but slower, POSIX NFAs. The following section describes the three types of regular expression engines, and explains why regular expressions in the .NET Framework are implemented by using a traditional NFA engine. +The .NET regular expression engine is a backtracking regular expression matcher that incorporates a traditional Nondeterministic Finite Automaton (NFA) engine such as that used by Perl, Python, Emacs, and Tcl. This distinguishes it from faster, but more limited, pure regular expression Deterministic Finite Automaton (DFA) engines such as those found in awk, egrep, or lex. This also distinguishes it from standardized, but slower, POSIX NFAs. The following section describes the three types of regular expression engines, and explains why regular expressions in .NET are implemented by using a traditional NFA engine. ## Benefits of the NFA engine @@ -27,11 +27,11 @@ The .NET Framework regular expression engine is a backtracking regular expressio > [!NOTE] > For information about the performance penalty caused by excessive backtracking and ways to craft a regular expression to work around them, see [Backtracking](backtracking-in-regular-expressions.md). -## .NET Framework engine capabilities +## .NET engine capabilities - To take advantage of the benefits of a traditional NFA engine, the .NET Framework regular expression engine includes a complete set of constructs to enable programmers to steer the backtracking engine. These constructs can be used to find matches faster or to favor specific expansions over others. + To take advantage of the benefits of a traditional NFA engine, the .NET regular expression engine includes a complete set of constructs to enable programmers to steer the backtracking engine. These constructs can be used to find matches faster or to favor specific expansions over others. - Other features of the .NET Framework regular expression engine include the following: + Other features of the .NET regular expression engine include the following: - Lazy quantifiers: `??`, `*?`, `+?`, `{`*n*`,`*m*`}?`. These constructs tell the backtracking engine to search the minimum number of repetitions first. In contrast, ordinary greedy quantifiers try to match the maximum number of repetitions first. The following example illustrates the difference between the two. A regular expression matches a sentence that ends in a number, and a capturing group is intended to extract that number. The regular expression `.+(\d+)\.` includes the greedy quantifier `.+`, which causes the regular expression engine to capture only the last digit of the number. In contrast, the regular expression `.+?(\d+)\.` includes the lazy quantifier `.+?`, which causes the regular expression engine to capture the entire number. @@ -143,7 +143,7 @@ The .NET Framework regular expression engine is a backtracking regular expressio |[Backtracking](backtracking-in-regular-expressions.md)|Provides information about how regular expression backtracking branches to find alternative matches.| |[Compilation and Reuse](compilation-and-reuse-in-regular-expressions.md)|Provides information about compiling and reusing regular expressions to increase performance.| |[Thread Safety](thread-safety-in-regular-expressions.md)|Provides information about regular expression thread safety and explains when you should synchronize access to regular expression objects.| -|[.NET Framework Regular Expressions](regular-expressions.md)|Provides an overview of the programming language aspect of regular expressions.| +|[.NET Regular Expressions](regular-expressions.md)|Provides an overview of the programming language aspect of regular expressions.| |[The Regular Expression Object Model](the-regular-expression-object-model.md)|Provides information and code examples illustrating how to use the regular expression classes.| |[Regular Expression Language - Quick Reference](regular-expression-language-quick-reference.md)|Provides information about the set of characters, operators, and constructs that you can use to define regular expressions.| diff --git a/docs/standard/base-types/enumeration-format-strings.md b/docs/standard/base-types/enumeration-format-strings.md index 1c0f5880232f1..fda0c1d19e809 100644 --- a/docs/standard/base-types/enumeration-format-strings.md +++ b/docs/standard/base-types/enumeration-format-strings.md @@ -9,7 +9,7 @@ dev_langs: helpviewer_keywords: - "format specifiers, enumeration format strings" - "enumeration format strings" - - "formatting [.NET Framework], enumeration" + - "formatting [.NET], enumeration" ms.assetid: dd1ff672-1052-42cf-8666-4924fb6cd1a1 --- # Enumeration format strings diff --git a/docs/standard/base-types/formatting-types.md b/docs/standard/base-types/formatting-types.md index 1b9dfaa1bece4..838bdd9621193 100644 --- a/docs/standard/base-types/formatting-types.md +++ b/docs/standard/base-types/formatting-types.md @@ -7,24 +7,24 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "data formatting [.NET Framework]" - - "dates [.NET Framework], formatting" - - "date formatting [.NET Framework]" - - "number formatting [.NET Framework]" + - "data formatting [.NET]" + - "dates [.NET], formatting" + - "date formatting [.NET]" + - "number formatting [.NET]" - "ToString method" - - "custom cultural settings [.NET Framework]" - - "numbers [.NET Framework], formatting" - - "formatting strings [.NET Framework]" - - "time [.NET Framework], formatting" - - "currency [.NET Framework], formatting" - - "types [.NET Framework], formatting" - - "format specifiers [.NET Framework]" - - "times [.NET Framework], formatting" - - "culture [.NET Framework], formatting" - - "formatting [.NET Framework], types supported" - - "base types [.NET Framework], formatting" - - "custom formatting [.NET Framework]" - - "strings [.NET Framework], formatting" + - "custom cultural settings [.NET]" + - "numbers [.NET], formatting" + - "formatting strings [.NET]" + - "time [.NET], formatting" + - "currency [.NET], formatting" + - "types [.NET], formatting" + - "format specifiers [.NET]" + - "times [.NET], formatting" + - "culture [.NET], formatting" + - "formatting [.NET], types supported" + - "base types [.NET], formatting" + - "custom formatting [.NET]" + - "strings [.NET], formatting" ms.assetid: 0d1364da-5b30-4d42-8e6b-03378343343f --- # Format types in .NET 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 2eb95f722af33..456a676c2b226 100644 --- a/docs/standard/base-types/grouping-constructs-in-regular-expressions.md +++ b/docs/standard/base-types/grouping-constructs-in-regular-expressions.md @@ -10,7 +10,7 @@ helpviewer_keywords: - "lookbehinds" - "regular expressions, grouping constructs" - "lookaheads" - - ".NET Framework regular expressions, grouping constructs" + - ".NET regular expressions, grouping constructs" - "constructs, grouping" - "grouping constructs" ms.assetid: 0fc18634-f590-4062-8d5c-f0b71abe405b 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 ade55edda6fdb..28282bd8c67f8 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 @@ -6,18 +6,19 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "numeric format strings [.NET Framework]" - - "formatting [.NET Framework], numbers" - - "number formatting [.NET Framework]" + - "numeric format strings [.NET]" + - "formatting [.NET], numbers" + - "number formatting [.NET]" - "custom numeric format strings" - - "numbers [.NET Framework], custom numeric format strings" + - "numbers [.NET], custom numeric format strings" - "displaying date and time data" - - "format providers [.NET Framework]" + - "format providers [.NET]" - "custom format strings" ms.assetid: a281bfbf-6596-45ed-a2d6-3782d535ada2 --- # How to: Define and Use Custom Numeric Format Providers -The .NET Framework gives you extensive control over the string representation of numeric values. It supports the following features for customizing the format of numeric values: + +.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). @@ -25,9 +26,9 @@ The .NET Framework gives you extensive control over the string representation of - 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. The .NET Framework 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. + 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. -### To define a custom format provider +## Define a custom format provider 1. Define a class that implements the and interfaces. @@ -49,13 +50,14 @@ The .NET Framework gives you extensive control over the string representation of 4. Return the string representation of the `arg` parameter. -### To use a custom numeric formatting object +## 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 +## 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). [!code-csharp[Formatting.HowTo.NumericValue#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.NumericValue/cs/Telephone1.cs#1)] 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 8b619ceb31ce0..fcba8a5a299be 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 @@ -6,9 +6,9 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "formatting [.NET Framework], dates" - - "dates [.NET Framework], formatting" - - "calendars [.NET Framework], displaying dates" + - "formatting [.NET], dates" + - "dates [.NET], formatting" + - "calendars [.NET], displaying dates" - "displaying date and time data" ms.assetid: ed324eff-4aff-4a76-b6c0-04e6c0d8f5a9 --- 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 1f306706c5b29..b68ffbed02c40 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 @@ -9,9 +9,9 @@ dev_langs: helpviewer_keywords: - "DateTime.ToString method" - "displaying date and time data" - - "time [.NET Framework], milliseconds" - - "dates [.NET Framework], milliseconds" - - "milliseconds [.NET Framework]" + - "time [.NET], milliseconds" + - "dates [.NET], milliseconds" + - "milliseconds [.NET]" ms.assetid: ae1a0610-90b9-4877-8eb6-4e30bc5e00cf --- # How to: Display Milliseconds in Date and Time Values 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 af2bef24b30bf..86c3a1059a5c5 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 @@ -9,8 +9,8 @@ helpviewer_keywords: - "searching with regular expressions, examples" - "parsing text with regular expressions, examples" - "regular expressions, examples" - - ".NET Framework regular expressions, examples" - - "regular expressions [.NET Framework], examples" + - ".NET regular expressions, examples" + - "regular expressions [.NET], examples" - "pattern-matching with regular expressions, examples" ms.assetid: ab7f62b3-6d2c-4efb-8ac6-28600df5fd5c --- 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 6fc2d4ae0ffcc..5002e139f6e40 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 @@ -7,27 +7,28 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "formatting [.NET Framework], dates" + - "formatting [.NET], dates" - "DateTime.DayOfWeek property" - "DateTime.ToString method" - - "dates [.NET Framework], retrieving week information" + - "dates [.NET], retrieving week information" - "DateTimeOffset.DayOfWeek property" - - "dates [.NET Framework], day of week" + - "dates [.NET], day of week" - "Weekday function" - - "day of week [.NET Framework]" + - "day of week [.NET]" - "extracting day of week" - "weekday names" - "WeekdayName function" - - "numbers [.NET Framework], day of week" - - "formatting [.NET Framework], time" + - "numbers [.NET], day of week" + - "formatting [.NET], time" - "DateTimeOffset.ToString method" - "full weekday names" ms.assetid: 1c9bef76-5634-46cf-b91c-9b9eb72091d7 --- # How to: Extract the Day of the Week from a Specific Date -The .NET Framework 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 topic 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 topic shows how to perform these formatting operations. -### To extract a number indicating the day of the week from a specific date +## Extract a number indicating the day of the week 1. If you are working with the string representation of a date, convert it to a or a value by using the static or method. @@ -40,7 +41,7 @@ The .NET Framework makes it easy to determine the ordinal day of the week for a [!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)] -### To extract the abbreviated weekday name from a specific date +## Extract the abbreviated weekday name 1. If you are working with the string representation of a date, convert it to a or a value by using the static or method. @@ -56,7 +57,7 @@ The .NET Framework makes it easy to determine the ordinal day of the week for a [!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)] -### To extract the full weekday name from a specific date +## Extract the full weekday name 1. If you are working with the string representation of a date, convert it to a or a value by using the static or method. @@ -78,7 +79,7 @@ The .NET Framework makes it easy to determine the ordinal day of the week for a [!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 may provide functionality that duplicates or supplements the functionality provided by the .NET Framework. For example, Visual Basic includes two such functions: + Individual languages may 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. 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 15ac440ead163..a18c9c09dd2f9 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 @@ -7,10 +7,10 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "numeric format strings [.NET Framework]" - - "formatting [.NET Framework], numbers" - - "number formatting [.NET Framework]" - - "numbers [.NET Framework], format strings" + - "numeric format strings [.NET]" + - "formatting [.NET], numbers" + - "number formatting [.NET]" + - "numbers [.NET], format strings" ms.assetid: 0b2c2cb5-c580-4891-8d81-cb632f5ec384 --- 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 eb0215406fc98..45a560327a930 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 @@ -7,10 +7,10 @@ dev_langs: - "vb" helpviewer_keywords: - "round-trip date and time values" - - "dates [.NET Framework], round-trip values" - - "time zones [.NET Framework], round-trip date and time values" - - "time [.NET Framework], round-trip values" - - "formatting strings [.NET Framework], round-trip values" + - "dates [.NET], round-trip values" + - "time zones [.NET], round-trip date and time values" + - "time [.NET], round-trip values" + - "formatting strings [.NET], round-trip values" ms.assetid: b609b277-edc6-4c74-b03e-ea73324ecbdb --- # How to: Round-trip Date and Time Values 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 03ce15404ae30..3c62446566014 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 @@ -10,8 +10,8 @@ helpviewer_keywords: - "regular expressions, examples" - "cleaning input" - "user input, examples" - - ".NET Framework regular expressions, examples" - - "regular expressions [.NET Framework], examples" + - ".NET regular expressions, examples" + - "regular expressions [.NET], examples" - "Regex.Replace method" - "stripping invalid characters" - "Replace method" 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 096414891c0f7..ab6f4e83544cf 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 @@ -10,13 +10,13 @@ helpviewer_keywords: - "regular expressions, examples" - "user input, examples" - "Regex.IsMatch method" - - "regular expressions [.NET Framework], examples" + - "regular expressions [.NET], examples" - "examples [Visual Basic], strings" - "IsValidEmail" - "validation, email strings" - "input, checking" - - "strings [.NET Framework], examples [Visual Basic]" - - "email [.NET Framework], validating" + - "strings [.NET], examples [Visual Basic]" + - "email [.NET], validating" - "IsMatch method" ms.assetid: 7536af08-4e86-4953-98a1-a8298623df92 --- @@ -78,5 +78,5 @@ In this example, the regular expression pattern `^[^@\s]+@[^@\s]+\.[^@\s]+$` is ## See also -- [.NET Framework Regular Expressions](regular-expressions.md) +- [.NET Regular Expressions](regular-expressions.md) - [How far should one take e-mail address validation?](https://softwareengineering.stackexchange.com/questions/78353/how-far-should-one-take-e-mail-address-validation#78363) 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 a5b59bba49364..7c1bbdf3f75f1 100644 --- a/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md +++ b/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md @@ -7,7 +7,7 @@ dev_langs: - "vb" helpviewer_keywords: - "constructs, miscellaneous" - - ".NET Framework regular expressions, miscellaneous constructs" + - ".NET regular expressions, miscellaneous constructs" - "regular expressions, miscellaneous constructs" ms.assetid: 7d10d11f-680f-4721-b047-fb136316b4cd --- diff --git a/docs/standard/base-types/padding.md b/docs/standard/base-types/padding.md index 1ab967eded106..108e89411e0ee 100644 --- a/docs/standard/base-types/padding.md +++ b/docs/standard/base-types/padding.md @@ -8,7 +8,7 @@ dev_langs: - "vb" - "cpp" helpviewer_keywords: - - "strings [.NET Framework], padding" + - "strings [.NET], padding" - "white space" - "PadRight method" - "PadLeft method" diff --git a/docs/standard/base-types/parsing-datetime.md b/docs/standard/base-types/parsing-datetime.md index 191c086c472fd..c33a72a4b4633 100644 --- a/docs/standard/base-types/parsing-datetime.md +++ b/docs/standard/base-types/parsing-datetime.md @@ -10,7 +10,7 @@ helpviewer_keywords: - "parsing strings, date and time strings" - "date and time strings" - "ParseExact method" - - "enumerations [.NET Framework], parsing strings" + - "enumerations [.NET], parsing strings" - "base types, parsing strings" - "DateTime object" - "time strings" diff --git a/docs/standard/base-types/parsing-numeric.md b/docs/standard/base-types/parsing-numeric.md index 52c19d9dc3e16..daa7e21d01703 100644 --- a/docs/standard/base-types/parsing-numeric.md +++ b/docs/standard/base-types/parsing-numeric.md @@ -9,7 +9,7 @@ dev_langs: helpviewer_keywords: - "parsing strings, numeric strings" - "numeric strings" - - "enumerations [.NET Framework], parsing strings" + - "enumerations [.NET], parsing strings" - "base types, parsing strings" ms.assetid: e39324ee-72e5-42d4-a80d-bf3ee7fc6c59 --- diff --git a/docs/standard/base-types/parsing-other.md b/docs/standard/base-types/parsing-other.md index 67e5411cf52a1..a01d32710f218 100644 --- a/docs/standard/base-types/parsing-other.md +++ b/docs/standard/base-types/parsing-other.md @@ -8,7 +8,7 @@ dev_langs: - "cpp" helpviewer_keywords: - "Char data type, parsing strings" - - "enumerations [.NET Framework], parsing strings" + - "enumerations [.NET], parsing strings" - "base types, parsing strings" - "parsing strings, other strings" - "Boolean data type, parsing strings" diff --git a/docs/standard/base-types/quantifiers-in-regular-expressions.md b/docs/standard/base-types/quantifiers-in-regular-expressions.md index dc831fbc62271..236c0030ebb68 100644 --- a/docs/standard/base-types/quantifiers-in-regular-expressions.md +++ b/docs/standard/base-types/quantifiers-in-regular-expressions.md @@ -11,7 +11,7 @@ helpviewer_keywords: - "metacharacters, quantifiers" - "minimal matching quantifiers" - "quantifiers in regular expressions" - - ".NET Framework regular expressions, quantifiers" + - ".NET regular expressions, quantifiers" - "quantifiers" - "lazy quantifiers" ms.assetid: 36b81212-6511-49ed-a8f1-ff080415312f 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 d2a8e347f38a4..bb81e84401405 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 @@ -9,8 +9,8 @@ helpviewer_keywords: - "searching with regular expressions, examples" - "parsing text with regular expressions, examples" - "regular expressions, examples" - - ".NET Framework regular expressions, examples" - - "regular expressions [.NET Framework], examples" + - ".NET regular expressions, examples" + - "regular expressions [.NET], examples" - "pattern-matching with regular expressions, examples" ms.assetid: 5fcc75a5-09d7-45ae-a4c0-9ad6085ac83d --- 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 7daf831a14949..926b957a32912 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 @@ -10,8 +10,8 @@ helpviewer_keywords: - "searching with regular expressions, examples" - "parsing text with regular expressions, examples" - "regular expressions, examples" - - ".NET Framework regular expressions, examples" - - "regular expressions [.NET Framework], examples" + - ".NET regular expressions, examples" + - "regular expressions [.NET], examples" - "pattern-matching with regular expressions, examples" ms.assetid: fae2c15b-7adf-4b15-b118-58eb3906994f --- 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 6215127f13cc4..d776fe840b150 100644 --- a/docs/standard/base-types/regular-expression-language-quick-reference.md +++ b/docs/standard/base-types/regular-expression-language-quick-reference.md @@ -11,9 +11,9 @@ helpviewer_keywords: - "searching with regular expressions, language elements" - "pattern-matching with regular expressions, language elements" - "regular expressions, language elements" - - "regular expressions [.NET Framework]" + - "regular expressions [.NET]" - "cheat sheet" - - ".NET Framework regular expressions, language elements" + - ".NET regular expressions, language elements" ms.assetid: 930653a6-95d2-4697-9d5a-52d11bb6fd4c --- # Regular Expression Language - Quick Reference diff --git a/docs/standard/base-types/regular-expression-options.md b/docs/standard/base-types/regular-expression-options.md index 907f6de49996b..968938ff0d7f2 100644 --- a/docs/standard/base-types/regular-expression-options.md +++ b/docs/standard/base-types/regular-expression-options.md @@ -9,7 +9,7 @@ dev_langs: helpviewer_keywords: - "regular expressions, options" - "constructs, options" - - ".NET Framework regular expressions, options" + - ".NET regular expressions, options" - "inline option constructs" - "options parameter" ms.assetid: c82dc689-7e82-4767-a18d-cd24ce5f05e9 diff --git a/docs/standard/base-types/regular-expressions.md b/docs/standard/base-types/regular-expressions.md index 4461c65d01fa3..82a9f3ec14769 100644 --- a/docs/standard/base-types/regular-expressions.md +++ b/docs/standard/base-types/regular-expressions.md @@ -13,13 +13,13 @@ helpviewer_keywords: - "pattern-matching with regular expressions" - "searching with regular expressions" - "parsing text with regular expressions" - - "regular expressions [.NET Framework], about regular expressions" - - "regular expressions [.NET Framework]" - - ".NET Framework regular expressions, about" - - "characters [.NET Framework], regular expressions" + - "regular expressions [.NET], about regular expressions" + - "regular expressions [.NET]" + - ".NET regular expressions, about" + - "characters [.NET], regular expressions" - "parsing text with regular expressions, overview" - - ".NET Framework regular expressions" - - "strings [.NET Framework], regular expressions" + - ".NET regular expressions" + - "strings [.NET], regular expressions" ms.assetid: 521b3f6d-f869-42e1-93e5-158c54a6895d --- # .NET regular expressions 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 bc2a18ed434c0..a10f84824d69f 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 @@ -7,12 +7,12 @@ dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "formatting [.NET Framework], dates" + - "formatting [.NET], dates" - "custom DateTime format string" - "format specifiers, custom date and time" - "format strings" - "custom date and time format strings" - - "formatting [.NET Framework], time" + - "formatting [.NET], time" - "date and time strings" ms.assetid: bb79761a-ca08-44ee-b142-b06b3e2fc22b --- diff --git a/docs/standard/base-types/standard-numeric-format-strings.md b/docs/standard/base-types/standard-numeric-format-strings.md index 35de16963f46f..1216e491acaf2 100644 --- a/docs/standard/base-types/standard-numeric-format-strings.md +++ b/docs/standard/base-types/standard-numeric-format-strings.md @@ -8,14 +8,14 @@ dev_langs: - "vb" - "cpp" helpviewer_keywords: - - "numeric format strings [.NET Framework]" - - "formatting [.NET Framework], numbers" + - "numeric format strings [.NET]" + - "formatting [.NET], numbers" - "standard format strings, numeric" - "format strings" - - "numbers [.NET Framework], formatting" + - "numbers [.NET], formatting" - "format specifiers, numeric" - "standard numeric format strings" - - "formatting numbers [.NET Framework]" + - "formatting numbers [.NET]" - "format specifiers, standard numeric format strings" --- # Standard numeric format strings @@ -27,7 +27,7 @@ Standard numeric format strings are used to format common numeric types. A stand - `xx` is an optional integer called the *precision specifier*. The precision specifier ranges from 0 to 99 and affects the number of digits in the result. Note that 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 the .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 ). + - **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 ). - **On .NET Core 2.1 and later**, the runtime selects the result with an even least significant digit (that is, using ). > [!NOTE] @@ -48,7 +48,7 @@ Standard numeric format strings are supported by: |Format specifier|Name|Description|Examples| |----------------------|----------|-----------------|--------------| -|"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| diff --git a/docs/standard/base-types/standard-timespan-format-strings.md b/docs/standard/base-types/standard-timespan-format-strings.md index 735049f559e33..8f21cb23b5306 100644 --- a/docs/standard/base-types/standard-timespan-format-strings.md +++ b/docs/standard/base-types/standard-timespan-format-strings.md @@ -12,11 +12,11 @@ helpviewer_keywords: - "standard time interval format strings" - "standard format strings, time intervals" - "format specifiers, time intervals" - - "time intervals [.NET Framework], formatting" - - "time [.NET Framework], formatting" - - "formatting [.NET Framework], time" + - "time intervals [.NET], formatting" + - "time [.NET], formatting" + - "formatting [.NET], time" - "standard TimeSpan format strings" - - "formatting [.NET Framework], time intervals" + - "formatting [.NET], time intervals" ms.assetid: 9f6c95eb-63ae-4dcc-9c32-f81985c75794 --- # Standard TimeSpan format strings @@ -57,7 +57,7 @@ The following table lists the standard time interval format specifiers. |*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 is common to all previous versions of the .NET Framework before the .NET Framework 4. "c" is the default format string; the method formats a time interval value by using the "c" format string. + 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. diff --git a/docs/standard/base-types/stringbuilder.md b/docs/standard/base-types/stringbuilder.md index c57258bc99883..f8bd7b5438dfc 100644 --- a/docs/standard/base-types/stringbuilder.md +++ b/docs/standard/base-types/stringbuilder.md @@ -9,13 +9,13 @@ dev_langs: - "cpp" helpviewer_keywords: - "Remove method" - - "strings [.NET Framework], capacities" + - "strings [.NET], capacities" - "StringBuilder object" - "Replace method" - "AppendFormat method" - "Append method" - "Insert method" - - "strings [.NET Framework], StringBuilder object" + - "strings [.NET], StringBuilder object" ms.assetid: 5c14867c-9a99-45bc-ae7f-2686700d377a --- # Using the StringBuilder Class in .NET diff --git a/docs/standard/base-types/substitutions-in-regular-expressions.md b/docs/standard/base-types/substitutions-in-regular-expressions.md index d3974ef7da8fb..2a2f9078b072e 100644 --- a/docs/standard/base-types/substitutions-in-regular-expressions.md +++ b/docs/standard/base-types/substitutions-in-regular-expressions.md @@ -10,15 +10,16 @@ helpviewer_keywords: - "regular expressions, substitutions" - "replacement patterns" - "metacharacters, substitutions" - - ".NET Framework regular expressions, substitutions" + - ".NET regular expressions, substitutions" - "constructs, substitutions" - "substitutions" 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. - The .NET Framework defines the substitution elements listed in the following table. + .NET defines the substitution elements listed in the following table. |Substitution|Description| |------------------|-----------------| 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 205ca5fca00a8..6b2cee159a0e7 100644 --- a/docs/standard/base-types/the-regular-expression-object-model.md +++ b/docs/standard/base-types/the-regular-expression-object-model.md @@ -11,28 +11,28 @@ helpviewer_keywords: - "Regex class" - "Match class" - "pattern-matching with regular expressions, backreferences" - - ".NET Framework regular expressions, classes" + - ".NET regular expressions, classes" - "CaptureCollection class" - "Group class" - - "characters [.NET Framework], backreferences" + - "characters [.NET], backreferences" - "substrings" - - ".NET Framework regular expressions, backreferences" + - ".NET regular expressions, backreferences" - "searching with regular expressions, classes" - "backreferences" - "Capture class" - "repeating groups of characters" - "MatchCollection class" - "parsing text with regular expressions, backreferences" - - "regular expressions [.NET Framework]" - - "characters [.NET Framework], regular expressions" - - "classes [.NET Framework], regular expression" - - "regular expressions [.NET Framework], classes" - - "characters [.NET Framework], metacharacters" + - "regular expressions [.NET]" + - "characters [.NET], regular expressions" + - "classes [.NET], regular expression" + - "regular expressions [.NET], classes" + - "characters [.NET], metacharacters" - "metacharacters, regular expression classes" - "metacharacters, backreferences" - "parsing text with regular expressions, classes" - - "regular expressions [.NET Framework], backreferences" - - "strings [.NET Framework], regular expressions" + - "regular expressions [.NET], backreferences" + - "strings [.NET], regular expressions" - "pattern-matching with regular expressions, classes" - "GroupCollection class" ms.assetid: 49a21470-64ca-4b5a-a889-8e24e3c0af7e diff --git a/docs/standard/base-types/thread-safety-in-regular-expressions.md b/docs/standard/base-types/thread-safety-in-regular-expressions.md index 9baf58fb6a8e5..88910975d8bef 100644 --- a/docs/standard/base-types/thread-safety-in-regular-expressions.md +++ b/docs/standard/base-types/thread-safety-in-regular-expressions.md @@ -3,7 +3,7 @@ title: "Thread Safety in Regular Expressions" ms.date: "03/30/2017" ms.technology: dotnet-standard helpviewer_keywords: - - ".NET Framework regular expressions, threads" + - ".NET regular expressions, threads" - "regular expressions, threads" - "searching with regular expressions, threads" - "parsing text with regular expressions, threads" diff --git a/docs/standard/base-types/trimming.md b/docs/standard/base-types/trimming.md index f5b8028544db3..2dc7bc483ba6a 100644 --- a/docs/standard/base-types/trimming.md +++ b/docs/standard/base-types/trimming.md @@ -8,7 +8,7 @@ dev_langs: - "vb" - "cpp" helpviewer_keywords: - - "strings [.NET Framework], removing characters" + - "strings [.NET], removing characters" - "Remove method" - "TrimEnd method" - "Trim method" diff --git a/docs/standard/collections/commonly-used-collection-types.md b/docs/standard/collections/commonly-used-collection-types.md index 2dd7e2e37048d..607ee9deae0d6 100644 --- a/docs/standard/collections/commonly-used-collection-types.md +++ b/docs/standard/collections/commonly-used-collection-types.md @@ -4,9 +4,9 @@ description: Learn about commonly used collection types in .NET, such as hash ta ms.date: "03/30/2017" ms.technology: dotnet-standard helpviewer_keywords: - - "collections [.NET Framework], generic" - - "objects [.NET Framework], grouping in collections" - - "generics [.NET Framework], collections" + - "collections [.NET], generic" + - "objects [.NET], grouping in collections" + - "generics [.NET], collections" - "IList interface, grouping data in collections" - "IDictionary interface, grouping data in collections" - "grouping data in collections, generic collection types" @@ -29,10 +29,10 @@ Collection types are the common variations of data collections, such as hash tab |Title|Description| |-----------|-----------------| -|[Collections and Data Structures](index.md)|Discusses the various collection types available in the .NET Framework, including stacks, queues, lists, arrays, and dictionaries.| +|[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 the .NET Framework. Provides links to feature documentation for C#, Visual Basic, and Visual C++, and to supporting technologies such as reflection.| +|[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 30a966081388d..b6fa3e4ad1ee5 100644 --- a/docs/standard/collections/comparisons-and-sorts-within-collections.md +++ b/docs/standard/collections/comparisons-and-sorts-within-collections.md @@ -11,7 +11,7 @@ helpviewer_keywords: - "IComparable.CompareTo method" - "Collections classes" - "Equals method" - - "collections [.NET Framework], comparisons" + - "collections [.NET], comparisons" ms.assetid: 5e4d3b45-97f0-423c-a65f-c492ed40e73b --- # Comparisons and sorts within collections diff --git a/docs/standard/collections/hashtable-and-dictionary-collection-types.md b/docs/standard/collections/hashtable-and-dictionary-collection-types.md index 23ccd39d05619..886c6ac6a22af 100644 --- a/docs/standard/collections/hashtable-and-dictionary-collection-types.md +++ b/docs/standard/collections/hashtable-and-dictionary-collection-types.md @@ -8,7 +8,7 @@ helpviewer_keywords: - "hash tables" - "grouping data in collections, Hashtable collection type" - "hash function" - - "collections [.NET Framework], Hashtable collection type" + - "collections [.NET], Hashtable collection type" ms.assetid: bfc20837-3d02-4fc7-8a8f-c5215b6b7913 --- # Hashtable and Dictionary Collection Types diff --git a/docs/standard/collections/index.md b/docs/standard/collections/index.md index 01b27d83b760f..a7c89ef0e99b2 100644 --- a/docs/standard/collections/index.md +++ b/docs/standard/collections/index.md @@ -5,11 +5,11 @@ ms.date: 04/30/2020 ms.technology: dotnet-standard helpviewer_keywords: - "grouping data in collections" - - "objects [.NET Framework], grouping in collections" + - "objects [.NET], grouping in collections" - "Array class, grouping data in collections" - - "threading [.NET Framework], safety" + - "threading [.NET], safety" - "Collections classes" - - "collections [.NET Framework]" + - "collections [.NET]" ms.assetid: 60cc581f-1db5-445b-ba04-a173396bf872 --- @@ -17,9 +17,9 @@ ms.assetid: 60cc581f-1db5-445b-ba04-a173396bf872 Similar data can often be handled more efficiently when stored and manipulated as a collection. You can use the class or the classes in the , , , and namespaces to add, remove, and modify either individual elements or a range of elements in a collection. -There are two main types of collections; generic collections and non-generic collections. Generic collections were added in the .NET Framework 2.0 and provide collections that are type-safe at compile time. Because of this, generic collections typically offer better performance. Generic collections accept a type parameter when they are constructed and do not require that you cast to and from the type when you add or remove items from the collection. In addition, most generic collections are supported in Windows Store apps. Non-generic collections store items as , require casting, and most are not supported for Windows Store app development. However, you may see non-generic collections in older code. +There are two main types of collections; generic collections and non-generic collections. Generic collections are type-safe at compile time. Because of this, generic collections typically offer better performance. Generic collections accept a type parameter when they are constructed and do not require that you cast to and from the type when you add or remove items from the collection. In addition, most generic collections are supported in Windows Store apps. Non-generic collections store items as , require casting, and most are not supported for Windows Store app development. However, you may see non-generic collections in older code. -Starting with the .NET Framework 4, the collections in the namespace provide efficient thread-safe operations for accessing collection items from multiple threads. The immutable collection classes in the namespace ([NuGet package](https://www.nuget.org/packages/System.Collections.Immutable)) are inherently thread-safe because operations are performed on a copy of the original collection and the original collection cannot be modified. +Starting with .NET Framework 4, the collections in the namespace provide efficient thread-safe operations for accessing collection items from multiple threads. The immutable collection classes in the namespace ([NuGet package](https://www.nuget.org/packages/System.Collections.Immutable)) are inherently thread-safe because operations are performed on a copy of the original collection and the original collection cannot be modified. ## Common collection features @@ -28,7 +28,7 @@ All collections provide methods for adding, removing, or finding items in the co - **The ability to enumerate the collection** - .NET Framework 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/keywords/foreach-in.md) 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 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/programming-guide/concepts/linq/linq-to-objects.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md), [Introduction to LINQ Queries (C#)](../../csharp/programming-guide/concepts/linq/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/keywords/foreach-in.md) 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 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/programming-guide/concepts/linq/linq-to-objects.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md), [Introduction to LINQ Queries (C#)](../../csharp/programming-guide/concepts/linq/introduction-to-linq-queries.md), and [Basic Query Operations (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/basic-query-operations.md). - **The ability to copy the collection contents to an array** diff --git a/docs/standard/collections/selecting-a-collection-class.md b/docs/standard/collections/selecting-a-collection-class.md index e8f858723684b..a86381a4359d9 100644 --- a/docs/standard/collections/selecting-a-collection-class.md +++ b/docs/standard/collections/selecting-a-collection-class.md @@ -6,7 +6,7 @@ ms.technology: dotnet-standard helpviewer_keywords: - "last-in-first-out collections" - "first-in-first-out collections" - - "collections [.NET Framework], selecting collection class" + - "collections [.NET], selecting collection class" - "indexed collections" - "Collections classes" - "grouping data in collections, selecting collection class" diff --git a/docs/standard/collections/sorted-collection-types.md b/docs/standard/collections/sorted-collection-types.md index 678252a3cf7f6..9545fa2b76e46 100644 --- a/docs/standard/collections/sorted-collection-types.md +++ b/docs/standard/collections/sorted-collection-types.md @@ -7,7 +7,7 @@ helpviewer_keywords: - "SortedList class, grouping data in collections" - "grouping data in collections, SortedList collection type" - "SortedList collection type" - - "collections [.NET Framework], SortedList collection type" + - "collections [.NET], SortedList collection type" ms.assetid: 3db965b2-36a6-4b12-b76e-7f074ff7275a --- @@ -40,7 +40,7 @@ For sorted lists or dictionaries that must be accessible concurrently from multi > [!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. -Starting with the .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 diff --git a/docs/standard/collections/when-to-use-generic-collections.md b/docs/standard/collections/when-to-use-generic-collections.md index 910306081d128..5d80e562a12f0 100644 --- a/docs/standard/collections/when-to-use-generic-collections.md +++ b/docs/standard/collections/when-to-use-generic-collections.md @@ -3,8 +3,8 @@ title: "When to Use Generic Collections" ms.date: 04/30/2020 ms.technology: dotnet-standard helpviewer_keywords: - - "collections [.NET Framework], generic" - - "generic collections [.NET Framework]" + - "collections [.NET], generic" + - "generic collections [.NET]" ms.assetid: e7b868b1-11fe-4ac5-bed3-de68aca47739 --- diff --git a/includes/core-changes/cryptography/5.0/tripledes-default-feedback-size-change.md b/includes/core-changes/cryptography/5.0/tripledes-default-feedback-size-change.md new file mode 100644 index 0000000000000..281aa7315286a --- /dev/null +++ b/includes/core-changes/cryptography/5.0/tripledes-default-feedback-size-change.md @@ -0,0 +1,56 @@ +### Default FeedbackSize value for instances created by TripleDES.Create changed + +The default value for the property on the instance returned from has changed from 64 to 8 to make migration from .NET Framework easier. This property, unless used directly in caller code, is used only when the property is . + +Support for the mode was first added to .NET for the 5.0 RC1 release, so only .NET 5.0 RC1 and .NET 5.0 RC2 applications should be impacted by this change. + +#### Change description + +In .NET Core and previous pre-release versions of .NET 5.0, `TripleDES.Create().FeedbackSize` has a default value of 64. Starting in the RTM version of .NET 5.0, `TripleDES.Create().FeedbackSize` has a default value of 8. + +#### Reason for change + +In .NET Framework, the base class defaults the value of to 64, but the class overwrites the default to 8. When the property was introduced to .NET Core in version 2.0, this same behavior was preserved. However, in .NET Framework, returns an instance of , so the default value from the algorithm factory is 8. For .NET Core and .NET 5+, the algorithm factory returns a non-public implementation, which, until now, had a default value of 64. + +Changing the implementation class' value to 8 allows for applications written for .NET Framework that specified the cipher mode as but didn't explicitly assign the property, to continue to function on .NET 5. + +#### Version introduced + +5.0 RTM + +#### Recommended action + +Applications that encrypt or decrypt data in the RC1 or RC2 versions of .NET 5.0 do so with CFB64, when the following conditions are met: + +- With a instance from . +- Using the default value for . +- With the property set to . + +To maintain this behavior, assign the property to `64`. + +Not all `TripleDES` implementations use the same default for . We recommend that if you use the cipher mode on instances, you should always explicitly assign the property value. + +```csharp +TripleDES cipher = TripleDES.Create(); +cipher.Mode = CipherMode.CFB; +// Explicitly set the FeedbackSize for CFB to control between CFB8 and CFB64. +cipher.FeedbackSize = 8; +``` + +#### Category + +- Cryptography + +#### Affected APIs + +- +- + +