diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index d52915dd3b97b..6fc9294cfb7a2 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -12,7 +12,7 @@ | Azure.Core.Expressions.DataFactory | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Core.Expressions.DataFactory/1.0.0) | [docs](/dotnet/api/overview/azure/Core.Expressions.DataFactory-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Expressions.DataFactory_1.0.0/sdk/core/Azure.Core.Expressions.DataFactory/) | | Calling Server | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.CallingServer/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Communication.CallingServer-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallingServer_1.0.0-beta.3/sdk/communication/Azure.Communication.CallingServer/) | | Code Transparency | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Security.CodeTransparency/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Security.CodeTransparency-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.CodeTransparency_1.0.0-beta.2/sdk/confidentialledger/Azure.Security.CodeTransparency/) | -| Communication Call Automation | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.3.0)
NuGet [1.4.0-beta.1](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.4.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.CallAutomation-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.3.0/sdk/communication/Azure.Communication.CallAutomation/)
GitHub [1.4.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.4.0-beta.1/sdk/communication/Azure.Communication.CallAutomation/) | +| Communication Call Automation | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.3.0)
NuGet [1.4.0-beta.2](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.4.0-beta.2) | [docs](/dotnet/api/overview/azure/Communication.CallAutomation-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.3.0/sdk/communication/Azure.Communication.CallAutomation/)
GitHub [1.4.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.4.0-beta.2/sdk/communication/Azure.Communication.CallAutomation/) | | Communication Chat | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Communication.Chat/1.3.1) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.3.1/sdk/communication/Azure.Communication.Chat/) | | Communication Common | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.Common/1.3.0)
NuGet [2.0.0-beta.1](https://www.nuget.org/packages/Azure.Communication.Common/2.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.Common-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_1.3.0/sdk/communication/Azure.Communication.Common/)
GitHub [2.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_2.0.0-beta.1/sdk/communication/Azure.Communication.Common/) | | Communication Email | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Email/1.0.1)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.Communication.Email/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/Communication.Email-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Email_1.0.1/sdk/communication/Azure.Communication.Email/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Email_1.1.0-beta.2/sdk/communication/Azure.Communication.Email/) | @@ -496,7 +496,7 @@ | Functions extension for Notification Hubs | NuGet [1.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.NotificationHubs/1.3.0) | | GitHub [1.3.0](https://github.com/Azure/azure-webjobs-sdk-extensions) | | Functions extension for RabbitMQ | NuGet [2.0.3](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.RabbitMQ/2.0.3) | | GitHub [2.0.3](https://github.com/Azure/azure-functions-rabbitmq-extension/tree/v0.2.2029-beta) | | Functions extension for script abstractions | NuGet [1.0.4-preview](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Script.Abstractions/1.0.4-preview) | | | -| Functions extension for SendGrid | NuGet [3.0.3](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.SendGrid/3.0.3) | | GitHub [3.0.3](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/v3.0.0/src/WebJobs.Extensions.SendGrid) | +| Functions extension for SendGrid | NuGet [3.1.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.SendGrid/3.1.0) | | GitHub [3.1.0](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/v3.0.0/src/WebJobs.Extensions.SendGrid) | | Functions extension for Sources | NuGet [3.0.41](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Sources/3.0.41) | | GitHub [3.0.41](https://github.com/Azure/azure-webjobs-sdk) | | Functions extension for Storage Timers | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Timers.Storage/1.0.0) | | | | Functions extension for Twilio | NuGet [3.0.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Twilio/3.0.2) | | GitHub [3.0.2](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/v3.0.0/src/WebJobs.Extensions.Twilio) | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index c575cc9beb87f..01119636288fa 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -12,7 +12,7 @@ | Azure.Core.Expressions.DataFactory | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Core.Expressions.DataFactory/1.0.0) | [docs](/dotnet/api/overview/azure/Core.Expressions.DataFactory-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Expressions.DataFactory_1.0.0/sdk/core/Azure.Core.Expressions.DataFactory/) | | Calling Server | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.CallingServer/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Communication.CallingServer-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallingServer_1.0.0-beta.3/sdk/communication/Azure.Communication.CallingServer/) | | Code Transparency | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Security.CodeTransparency/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Security.CodeTransparency-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.CodeTransparency_1.0.0-beta.2/sdk/confidentialledger/Azure.Security.CodeTransparency/) | -| Communication Call Automation | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.3.0)
NuGet [1.4.0-beta.1](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.4.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.CallAutomation-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.3.0/sdk/communication/Azure.Communication.CallAutomation/)
GitHub [1.4.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.4.0-beta.1/sdk/communication/Azure.Communication.CallAutomation/) | +| Communication Call Automation | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.3.0)
NuGet [1.4.0-beta.2](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.4.0-beta.2) | [docs](/dotnet/api/overview/azure/Communication.CallAutomation-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.3.0/sdk/communication/Azure.Communication.CallAutomation/)
GitHub [1.4.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.4.0-beta.2/sdk/communication/Azure.Communication.CallAutomation/) | | Communication Chat | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Communication.Chat/1.3.1) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.3.1/sdk/communication/Azure.Communication.Chat/) | | Communication Common | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.Common/1.3.0)
NuGet [2.0.0-beta.1](https://www.nuget.org/packages/Azure.Communication.Common/2.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.Common-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_1.3.0/sdk/communication/Azure.Communication.Common/)
GitHub [2.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_2.0.0-beta.1/sdk/communication/Azure.Communication.Common/) | | Communication Email | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Email/1.0.1)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.Communication.Email/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/Communication.Email-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Email_1.0.1/sdk/communication/Azure.Communication.Email/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Email_1.1.0-beta.2/sdk/communication/Azure.Communication.Email/) | diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 91ded5b8daec0..3cfb3b62328eb 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -2,7 +2,8 @@ title: Breaking changes in .NET 10 titleSuffix: "" description: Navigate to the breaking changes in .NET 10. -ms.date: 12/19/2024 +ms.date: 01/30/2025 +ai-usage: ai-assisted no-loc: [Blazor, Razor, Kestrel] --- # Breaking changes in .NET 10 @@ -17,6 +18,30 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af ## Core .NET libraries -| Title | Type of change | Introduced version | -|------------------------------------------------------------------------------------------|---------------------|--------------------| -| [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md) | Source incompatible | Preview 1 | +| Title | Type of change | Introduced version | +|----------------------------------------------------------------------------------------------------------------------------|---------------------|--------------------| +| [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md) | Source incompatible | Preview 1 | +| [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md) | Behavioral change | Preview 1 | +| [C# 14 overload resolution with span parameters](core-libraries/10.0/csharp-overload-resolution.md) | Behavioral change | Preview 1 | +| [Consistent shift behavior in generic math](core-libraries/10.0/generic-math.md) | Behavioral change | Preview 1 | +| [LDAP DirectoryControl parsing is now more stringent](core-libraries/10.0/ldap-directorycontrol-parsing.md) | Behavioral change | Preview 1 | +| [MacCatalyst version normalization](core-libraries/10.0/maccatalyst-version-normalization.md) | Behavioral change | Preview 1 | + +## Globalization + +| Title | Type of change | Introduced version | +|-------------------------------------------------------------------------------------------------------|-------------------|--------------------| +| [Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE](globalization/10.0/version-override.md) | Behavioral change | Preview 1 | + +## Cryptography + +| Title | Type of change | Introduced version | +|--------------------------------------------------------------------------------------------------------|-------------------|--------------------| +| [X500DistinguishedName validation is stricter](cryptography/10.0/x500distinguishedname-validation.md) | Behavioral change | Preview 1 | + +## Windows Forms + +| Title | Type of change | Introduced version | +|-------------------------------------------------------------------------------------------------------------------|---------------------|--------------------| +| [Renamed parameter in HtmlElement.InsertAdjacentElement](windows-forms/10.0/insertadjacentelement-orientation.md) | Source incompatible | Preview 1 | +| [TreeView checkbox image truncation](windows-forms/10.0/treeview-text-location.md) | Behavioral change | Preview 1 | diff --git a/docs/core/compatibility/core-libraries/10.0/activity-sampling.md b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md new file mode 100644 index 0000000000000..04c63c8246214 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/activity-sampling.md @@ -0,0 +1,61 @@ +--- +title: "Breaking change: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior changes" +description: Learn about the .NET 10.0 breaking change in core .NET libraries where ActivitySource.CreateActivity and ActivitySource.StartActivity behavior is modified. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- +# ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change + +The and APIs only return an when there's a registered listener that decides the instance should be created. This is generally known as sampling. + +The enum defines the possible sampling decisions. + +When creating an `Activity` without a parent, `ActivitySamplingResult` drives whether the `Activity` is created and then how the `Recorded` and `IsAllDataRequested` properties are set: + +|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested| +|---|---|---|---| +|None|No||| +|PropagationData|Yes|False|False| +|AllData|Yes|False|True| +|AllDataAndRecorded|Yes|True|True| + +It is also possible to create an `Activity` with a parent. The parent could be in the same process, or it could be a remote parent propagated to the current process. + +## Previous behavior + +Previously, when creating an `Activity` as `PropagationData` with a parent marked as `Recorded`, the `Recorded` and `IsAllDataRequested` properties were set as follows: + +|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested| +|---|---|---|---| +|PropagationData|Yes|True|False| + +## New behavior + +Starting in .NET 10, when you create an `Activity` as `PropagationData` with a parent marked as `Recorded`, the `Recorded` and `IsAllDataRequested` properties are set as follows: + +|ActivitySamplingResult|Activity created|Activity.Recorded|Activity.IsAllDataRequested| +|---|---|---|---| +|PropagationData|Yes|False|False| + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +The previous behavior did not follow the OpenTelemetry specification. + +## Recommended action + +If you've implemented `ActivityListener.Sample` directly AND use `ActivitySamplingResult.PropagationData`, verify that you're not reliant on the flawed behavior. To restore the previous behavior, you can set `Activity.ActivityTraceFlags` to `Recorded` after the `CreateActivity` or `StartActivity` call. + +If you use OpenTelemetry .NET and have customized the sampler, verify your sampler configuration. The default OpenTelemetry .NET configuration uses a parent-based algorithm that isn't impacted. + +## Affected APIs + +- +- diff --git a/docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md b/docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md new file mode 100644 index 0000000000000..5033409d99d93 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md @@ -0,0 +1,51 @@ +--- +title: "Breaking change: C# 14 overload resolution with span parameters" +description: Learn about the .NET 10 breaking change in core .NET libraries where overloads with span parameters are applicable in more scenarios. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- +# C# 14 overload resolution with span parameters + +C# 14, which ships with .NET 10, introduces new [built-in span conversions and type inference rules](https://github.com/dotnet/csharplang/issues/7905). Those changes make overloads with span parameters applicable in more scenarios. + +## Previous behavior + +In C# 13 and earlier, an extension method taking a `ReadOnlySpan` or `Span` receiver was not applicable to a value of type `T[]`. Therefore, only non-span extension methods like the ones from the `System.Linq.Enumerable` class were usually bound inside Expression lambdas. + +## New behavior + +In C# 14 and later, methods with `ReadOnlySpan` or `Span` parameters can participate in type inference or be used as extension methods in more scenarios. This makes span-based methods like the ones from the `System.MemoryExtensions` class bind in more scenarios, including inside Expression lambdas where they will cause run-time exceptions when compiled with interpretation. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +The C# language feature allows simplified API design and usage (for example, one extension method can apply to both spans and arrays). + +## Recommended action + +If you need to continue using Expression interpretation, make sure the non-span overloads are bound, for example, by casting arguments to the exact types the method signature takes or calling the extension methods as explicit static invocations: + +```csharp +using System; +using System.Collections.Generic; +using System.Linq; +using System.Linq.Expressions; + +M((array, num) => array.Contains(num)); // fails, binds to MemoryExtensions.Contains +M((array, num) => ((IEnumerable)array).Contains(num)); // ok, binds to Enumerable.Contains +M((array, num) => array.AsEnumerable().Contains(num)); // ok, binds to Enumerable.Contains +M((array, num) => Enumerable.Contains(array, num)); // ok, binds to Enumerable.Contains + +void M(Expression> e) => e.Compile(preferInterpretation: true); +``` + +## Affected APIs + +- diff --git a/docs/core/compatibility/core-libraries/10.0/generic-math.md b/docs/core/compatibility/core-libraries/10.0/generic-math.md new file mode 100644 index 0000000000000..7d418a0d0678c --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/generic-math.md @@ -0,0 +1,39 @@ +--- +title: "Breaking change: Consistent shift behavior in generic math" +description: Learn about the .NET 10 breaking change in core .NET libraries where shift operations in generic math now have consistent behavior. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- +# Consistent shift behavior in generic math + +Shift operations in generic math now have consistent behavior across all built-in integer types. + +## Previous behavior + +The behavior when utilizing generic math to perform a shift on a `T` could differ based on the type. In some cases, it appropriately masked the shift amount by `sizeof(T) - 1`. And in other cases, there was no masking. This meant that "overshifting" (such as shifting a `byte` by 8) could result in different answers than expected. + +## New behavior + +The implementations were updated to mask the shift amount, as appropriate, to ensure consistent behavior across all built-in integer types and with the behavior documented by the interface. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +The behavior differed from the designed behavior due to a difference in how masking works for small integer types in C#. + +## Recommended action + +Update any code that relies on the previous inconsistent behavior to ensure it works with the new consistent behavior. + +## Affected APIs + +- `operator <<` +- `operator >>` +- `operator >>>` for `byte`, `char`, `sbyte`, `short`, and `ushort` when used via generic math, which requires a `T` constrained to `where T : IShiftOperators` or a similar interface. diff --git a/docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md b/docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md new file mode 100644 index 0000000000000..ba4bf5d6e8030 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/ldap-directorycontrol-parsing.md @@ -0,0 +1,63 @@ +--- +title: "Breaking change: LDAP DirectoryControl parsing is now more stringent" +description: Learn about the .NET 10 breaking change in core .NET libraries where LDAP DirectoryControl parsing is now more stringent. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- + +# LDAP DirectoryControl parsing is now more stringent + +Previously, .NET used to parse the objects it received over the network and to generate the byte arrays it sent. used the OS-specific BER parsing functionality. This parsing functionality is now implemented in managed code. + +## Previous behavior + +As a result of using , the parsing of objects was fairly loose: + +- The ASN.1 tags of each value weren't checked. +- Trailing data after the end of the parsed DirectoryControl was ignored, as was trailing data within an ASN.1 SEQUENCE. +- On Linux, OCTET STRING lengths that extended beyond the end of their parent sequence returned data outside the parent sequence. +- On earlier versions of Windows, a zero-length OCTET STRING returned `null` rather than an empty string. +- When reading the contents of a as a UTF8-encoded string, an invalid UTF8 sequence did not throw an exception. +- When passing an invalid UTF8 string to the constructor of [VlvRequestControl](xref:System.DirectoryServices.Protocols.VlvRequestControl), no exception was thrown. + +While not a breaking change, Windows always encoded ASN.1 tags with a four-byte length while Linux only used as many bytes for the tag length as it needed. Both representations were valid, but this behavioral difference between platforms is now gone; the Linux behavior now also appears on Windows. + +## New behavior + +The DirectoryControl parsing is much more stringent, and is now consistent across platforms and versions: + +- ASN.1 tags are now checked. +- Trailing data is no longer permitted. +- The length of `OCTET STRING`s and `SEQUENCE`s is now checked. +- Zero-length `OCTET STRING`s now always return an empty string. +- If the server sends an invalid UTF8 byte sequence, the parsing logic now throws an exception rather than silently substituting the invalid characters with a known value. + +We also validate errors more thoroughly when calling the constructor. Passing a string which cannot be encoded as a UTF8 value now throws an . + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change was made for RFC and specification compliance. In the various RFCs and sections of MS-ADTS, the controlValue is specified as the BER encoding of an ASN.1 structure with wording similar to the following (from [RFC2891, section 1.2](https://datatracker.ietf.org/doc/html/rfc2891#section-1.2)): + +> The controlType is set to "1.2.840.113556.1.4.474". The criticality is FALSE (MAY be absent). The controlValue is an OCTET STRING, whose value is the BER encoding of a value of the following SEQUENCE: + +This precludes trailing data. It also rules out BER encodings of ASN.1 structures with differing ASN.1 tags, and of invalid BER encodings (such as OCTET STRINGs which are longer than their containing SEQUENCE.) + +For the constructor, throwing the exception early means that users can trust that only the values they explicitly specify are sent to the server. There are no circumstances where they can accidentally send `EF BF BD` to the server because they've passed a string that can't be encoded to valid UTF8 bytes. + +## Recommended action + +Servers should comply with the RFCs and specifications. Make sure to handle an when calling the constructor. + +## Affected APIs + +- +- +- diff --git a/docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization.md b/docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization.md new file mode 100644 index 0000000000000..bd0bc72aed39a --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/maccatalyst-version-normalization.md @@ -0,0 +1,40 @@ +--- +title: "Breaking change: MacCatalyst version normalization" +description: Learn about the .NET 10 breaking change in core .NET libraries where MacCatalyst version components are normalized. +ms.date: 01/01/2025 +ai-usage: ai-assisted +--- + +# MacCatalyst version normalization + +This update ensures that MacCatalyst version components retrieved from the OS are always normalized to three components: major, minor, and build. The build component is set to `0` if undefined (`-1`), ensuring consistent behavior between iOS and MacCatalyst versions for version checks. + +## Previous behavior + +The build component in `Version` was not previously normalized, which led to incorrect version checks on MacCatalyst when only two components (major and minor) were provided. This resulted in invalid version checks. + +## New behavior + +The MacCatalyst build component is now normalized to `0`, ensuring consistent version checks. The revision component is always set to `-1`, as it is not specified on MacCatalyst or iOS. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This changed was made to prevent incorrect version checks and align MacCatalyst versioning with iOS, ensuring consistent version components. + +## Recommended action + +Use versions of up to three components (major, minor, and build) on MacCatalyst. + +## Affected APIs + +- +- +- diff --git a/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md b/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md index 2a5e9c98f4344..391fcf47ee01c 100644 --- a/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md +++ b/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md @@ -3,6 +3,7 @@ title: "Breaking change: .NET 10 obsoletions with custom IDs" titleSuffix: "" description: Learn about the APIs that have been marked as obsolete in .NET 10 with a custom diagnostic ID. ms.date: 01/14/2025 +ai-usage: ai-assisted --- # API obsoletions with non-default diagnostic IDs (.NET 10) @@ -16,11 +17,13 @@ The following table lists the custom diagnostic IDs and their corresponding warn | Diagnostic ID | Description | Severity | |---------------|-------------|----------| +| [SYSLIB0058](../../../../fundamentals/syslib-diagnostics/syslib0058.md) | The `KeyExchangeAlgorithm`, `KeyExchangeStrength`, `CipherAlgorithm`, `CipherAlgorithmStrength`, `HashAlgorithm`, and `HashStrength` properties of are obsolete. Use instead. | Warning | | [SYSLIB0059](../../../../fundamentals/syslib-diagnostics/syslib0059.md) | callbacks aren't run before the process exits. Use instead. | Warning | +| [SYSLIB0060](../../../../fundamentals/syslib-diagnostics/syslib0060.md) | constructors are obsolete. Use instead. | Warning | ## Version introduced -.NET 9 +.NET 10 ## Type of breaking change @@ -34,10 +37,27 @@ These obsoletions can affect [source compatibility](../../categories.md#source-c ## Affected APIs +### SYSLIB0058 + +- +- +- +- +- +- +- +- +- + ### SYSLIB0059 - +### SYSLIB0060 + +- +- + ## See also - [API obsoletions with non-default diagnostic IDs (.NET 9)](../9.0/obsolete-apis-with-custom-diagnostics.md) diff --git a/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md b/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md new file mode 100644 index 0000000000000..150dd22b4fcdb --- /dev/null +++ b/docs/core/compatibility/cryptography/10.0/x500distinguishedname-validation.md @@ -0,0 +1,59 @@ +--- +title: "Breaking change: X500DistinguishedName validation is stricter" +description: Learn about the .NET 10 breaking change in cryptography where X500DistinguishedName validation is stricter. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- +# X500DistinguishedName validation is stricter + +Starting in .NET 10, the constructor that accepts a string-encoded distinguished name might reject previously accepted invalid input or encode it differently on non-Windows systems. This aligns with encoding specifications and Windows behavior. + +## Previous behavior + +Previous versions of .NET on non-Windows systems permitted incorrect distinguished names or encoded them in a way not permitted by X.520 encoding rules. The flag forced components to use a UTF8String even if it wasn't a valid representation. + +## New behavior + +Starting in .NET 10, components that violate encoding rules throw a on non-Windows systems, matching Windows behavior. The flag only UTF-8 encodes components when permissible. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +Different X.500 components have specific encoding rules. For example, `id-at-telephoneNumber` must be encoded as an ASN.1 . The exclamation point character is invalid for a PrintableString. Consider the following code: + +```csharp +new X500DistinguishedName("Phone=!!"); +``` + +This code threw an exception on Windows but was encoded as a UTF8String on non-Windows. Similarly, using forced UTF8String encoding even when not permitted: + +```csharp +new X500DistinguishedName("Phone=000-555-1234", X500DistinguishedNameFlags.ForceUTF8Encoding); +``` + +This change ensures encoding aligns with specifications and Windows behavior. + +## Recommended action + +Generally, no action is needed unless compatibility with incorrect encoding is required. Use to create instances with desired encoding: + +```csharp +using System.Formats.Asn1; +using System.Security.Cryptography.X509Certificates; + +X500DistinguishedNameBuilder builder = new(); +builder.Add("2.5.4.20", "000-555-1234", UniversalTagNumber.UTF8String); +X500DistinguishedName dn = builder.Build(); +``` + +## Affected APIs + +- +- diff --git a/docs/core/compatibility/globalization/10.0/version-override.md b/docs/core/compatibility/globalization/10.0/version-override.md new file mode 100644 index 0000000000000..fc1cc13e80a3b --- /dev/null +++ b/docs/core/compatibility/globalization/10.0/version-override.md @@ -0,0 +1,38 @@ +--- +title: "Breaking change: Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE" +description: Learn about the .NET 10 breaking change in globalization where the environment variable CLR_ICU_VERSION_OVERRIDE was renamed to DOTNET_ICU_VERSION_OVERRIDE. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- + +# Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE + +.NET previously supported a configuration-switch environment variable called `CLR_ICU_VERSION_OVERRIDE`, which allowed users to specify the preferred ICU library version for apps running on Linux. In .NET 10, this environment variable has been renamed to `DOTNET_ICU_VERSION_OVERRIDE` to align with the naming convention of other configuration switch environment variables in .NET. + +## Previous behavior + +The `CLR_ICU_VERSION_OVERRIDE` environment variable was used to specify the preferred ICU version to be loaded in the application. + +## New behavior + +The `DOTNET_ICU_VERSION_OVERRIDE` environment variable is used to specify the preferred ICU version to be loaded in the application. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change ensures the environment variable is consistent with the naming convention used for all [.NET environment variables](../../../tools/dotnet-environment-variables.md). + +## Recommended action + +If you have a .NET 10 app that previously used the `CLR_ICU_VERSION_OVERRIDE` environment variable, use `DOTNET_ICU_VERSION_OVERRIDE` instead. + +## Affected APIs + +N/A diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 3a923d1625876..d512dd2bc91aa 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -12,6 +12,30 @@ items: items: - name: API obsoletions with non-default diagnostic IDs href: core-libraries/10.0/obsolete-apis.md + - name: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change + href: core-libraries/10.0/activity-sampling.md + - name: C# 14 overload resolution with span parameters + href: core-libraries/10.0/csharp-overload-resolution.md + - name: Consistent shift behavior in generic math + href: core-libraries/10.0/generic-math.md + - name: LDAP DirectoryControl parsing is now more stringent + href: core-libraries/10.0/ldap-directorycontrol-parsing.md + - name: MacCatalyst version normalization + href: core-libraries/10.0/maccatalyst-version-normalization.md + - name: Cryptography + items: + - name: X500DistinguishedName validation is stricter + href: cryptography/10.0/x500distinguishedname-validation.md + - name: Globalization + items: + - name: Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE + href: globalization/10.0/version-override.md + - name: Windows Forms + items: + - name: Renamed parameter in HtmlElement.InsertAdjacentElement + href: windows-forms/10.0/insertadjacentelement-orientation.md + - name: TreeView checkbox image truncation + href: windows-forms/10.0/treeview-text-location.md - name: .NET 9 items: - name: Overview @@ -1312,6 +1336,16 @@ items: items: - name: API obsoletions with non-default diagnostic IDs href: core-libraries/10.0/obsolete-apis.md + - name: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change + href: core-libraries/10.0/activity-sampling.md + - name: C# 14 overload resolution with span parameters + href: core-libraries/10.0/csharp-overload-resolution.md + - name: Consistent shift behavior in generic math + href: core-libraries/10.0/generic-math.md + - name: LDAP DirectoryControl parsing is now more stringent + href: core-libraries/10.0/ldap-directorycontrol-parsing.md + - name: MacCatalyst version normalization + href: core-libraries/10.0/maccatalyst-version-normalization.md - name: .NET 9 items: - name: Adding a ZipArchiveEntry sets header general-purpose bit flags @@ -1546,6 +1580,10 @@ items: href: corefx.md - name: Cryptography items: + - name: .NET 10 + items: + - name: X500DistinguishedName validation is stricter + href: cryptography/10.0/x500distinguishedname-validation.md - name: .NET 9 items: - name: SafeEvpPKeyHandle.DuplicateHandle up-refs the handle @@ -1674,6 +1712,10 @@ items: href: extensions/6.0/service-provider-disposed.md - name: Globalization items: + - name: .NET 10 + items: + - name: Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE + href: globalization/10.0/version-override.md - name: .NET 8 items: - name: Date and time converters honor culture argument @@ -2046,6 +2088,12 @@ items: href: wcf-client/6.0/duplex-synchronization-context.md - name: Windows Forms items: + - name: .NET 10 + items: + - name: Renamed parameter in HtmlElement.InsertAdjacentElement + href: windows-forms/10.0/insertadjacentelement-orientation.md + - name: TreeView checkbox image truncation + href: windows-forms/10.0/treeview-text-location.md - name: .NET 9 items: - name: BindingSource.SortDescriptions doesn't return null diff --git a/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md b/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md new file mode 100644 index 0000000000000..afb741bde02eb --- /dev/null +++ b/docs/core/compatibility/windows-forms/10.0/insertadjacentelement-orientation.md @@ -0,0 +1,54 @@ +--- +title: "Breaking change: Renamed parameter in HtmlElement.InsertAdjacentElement" +description: Learn about the .NET 10 Preview 1 breaking change in Windows Forms where the parameter `orient` was renamed to `orientation`. +ms.date: 01/30/2025 +ai-usage: ai-assisted +--- + +# Renamed parameter in HtmlElement.InsertAdjacentElement + + parameter `orient` was renamed to `orientation`. + +## Previous behavior + +Calls to included the `orient` parameter: + +```csharp +element.InsertAdjacentElement(orient: HtmlElementInsertionOrientation.AfterEnd, newElement); +``` + +## New behavior + +The new parameter name is `orientation`. + +```csharp +element.InsertAdjacentElement(orientation: HtmlElementInsertionOrientation.AfterEnd, newElement); +``` + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change can affect [source compatibility](../../categories.md#source-compatibility). + +## Reason for change + +The parameter name was changed to provide a more descriptive name. + +## Recommended action + +Edit any calls with a named argument to use the new parameter name or remove the parameter name: + +```csharp +element.InsertAdjacentElement(orientation: HtmlElementInsertionOrientation.AfterEnd, newElement); +``` + +```csharp +element.InsertAdjacentElement(HtmlElementInsertionOrientation.AfterEnd, newElement); +``` + +## Affected APIs + +- diff --git a/docs/core/compatibility/windows-forms/10.0/treeview-text-location.md b/docs/core/compatibility/windows-forms/10.0/treeview-text-location.md new file mode 100644 index 0000000000000..01307f712a5b8 --- /dev/null +++ b/docs/core/compatibility/windows-forms/10.0/treeview-text-location.md @@ -0,0 +1,52 @@ +--- +title: "Breaking change: TreeView checkbox image truncation" +description: Learn about the .NET 10 breaking change in Windows Forms where the TreeView checkbox image is truncated under certain conditions. +ms.date: 01/30/2025 +--- +# TreeView checkbox image truncation + +The in the control allows users to customize the DrawMode and add checkboxes. However, the checkbox image will be truncated due to the position of the TreeNode text drawing. To avoid affecting normal, common use, you can use an AppContext switch setting to avoid checkbox truncation in these specific situations. + +The checkbox image is truncated when all of the following conditions are met: + +- `CheckBoxes` is set to `true` +- `DrawMode` is set to `OwnerDrawText` +- `DrawDefault` is set to `true` in the `OnDrawNode` event + +## Previous behavior + +In previous versions, when the TreeView control had `CheckBoxes` set to `true`, `DrawMode` set to `OwnerDrawText`, and `DrawDefault` set to `true` in the `OnDrawNode` event, the TreeNode checkbox images were shown truncated on the right border. + +## New behavior + +By setting the switch `"System.Windows.Forms.TreeView.MoveTreeViewTextLocationOnePixel": true` in the project's runtime config file, the TreeNode checkboxes are displayed completely when the TreeView has `CheckBoxes` set to `true`, `DrawMode` set to `OwnerDrawText`, and `DrawDefault` set to `true` in the `OnDrawNode` event. + +## Version introduced + +.NET 10 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change ensures that the checkbox of the node in the TreeView control can be fully displayed. + +## Recommended action + +Manually add `"System.Windows.Forms.TreeView.MoveTreeViewTextLocationOnePixel": true` to the project's *runtimeconfig.json* file to enable the switch. + +```json +{ + "runtimeOptions": { + "configProperties": { + "System.Windows.Forms.TreeView.MoveTreeViewTextLocationOnePixel": true + } + } +} +``` + +## Affected APIs + +- diff --git a/docs/fundamentals/networking/overview.md b/docs/fundamentals/networking/overview.md index afd6919075198..bda00173ea874 100644 --- a/docs/fundamentals/networking/overview.md +++ b/docs/fundamentals/networking/overview.md @@ -26,7 +26,7 @@ The type is used as a representat :::code language="csharp" source="snippets/misc/Program.Uri.cs" id="canonicaluri"::: -The `Uri` class automatically performs validation and canonicalization per [RCF 3986](https://datatracker.ietf.org/doc/html/rfc3986). These validation and canonicalization rules are used to ensure that a URI is well-formed and that the URI is in a canonical form. +The `Uri` class automatically performs validation and canonicalization per [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). These validation and canonicalization rules are used to ensure that a URI is well-formed and that the URI is in a canonical form. ## See also diff --git a/docs/fundamentals/networking/telemetry/overview.md b/docs/fundamentals/networking/telemetry/overview.md index 46a447c5392f5..a9954fac4f73d 100644 --- a/docs/fundamentals/networking/telemetry/overview.md +++ b/docs/fundamentals/networking/telemetry/overview.md @@ -14,6 +14,3 @@ The .NET networking stack is instrumented at various layers. .NET gives you the - **[Distributed tracing](tracing.md)**: `HttpClient` is instrumented to emit [distributed tracing](../../../core/diagnostics/distributed-tracing.md) activities (also known as spans). - **[Networking events](events.md)**: Events provide debug and trace information with accurate timestamps. - **[Networking event counters](event-counters.md)**: All networking components are instrumented to publish real-time performance metrics using the EventCounters API. - -> [!TIP] -> If you're looking for information on tracking HTTP operations across different services, see the [distributed tracing documentation](../../../core/diagnostics/distributed-tracing.md). diff --git a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md index b7ca9e2eef5c1..fac18796d6033 100644 --- a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md +++ b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md @@ -1,8 +1,8 @@ --- title: Obsolete features in .NET 5+ -titleSuffix: "" description: Learn about APIs that are marked as obsolete in .NET 5 and later versions that produce SYSLIB compiler warnings. ms.date: 01/14/2025 +ai-usage: ai-assisted --- # Obsolete features in .NET 5+ @@ -80,6 +80,7 @@ The following table provides an index to the `SYSLIB0XXX` obsoletions in .NET 5+ | [SYSLIB0057](syslib0057.md) | Warning | `X509Certificate2` and `X509Certificate` constructors for binary and file content are obsolete. | | SYSLIB0058 | Warning | The `KeyExchangeAlgorithm`, `KeyExchangeStrength`, `CipherAlgorithm`, `CipherAlgorithmStrength`, `HashAlgorithm`, and `HashStrength` properties of are obsolete. Use instead. | | [SYSLIB0059](syslib0059.md) | Warning | callbacks aren't run before the process exits. Use instead. | +| [SYSLIB0060](syslib0060.md) | Warning | Constructors on are obsolete. Use instead. | ## Suppress warnings diff --git a/docs/fundamentals/syslib-diagnostics/syslib0058.md b/docs/fundamentals/syslib-diagnostics/syslib0058.md new file mode 100644 index 0000000000000..efb7a660f80c3 --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0058.md @@ -0,0 +1,58 @@ +--- +title: SYSLIB0058 warning - Certain SslStream properties are obsolete +description: Learn about the obsoletion of ExchangeAlgorithmType, CipherAlgorithmType, and HashAlgorithmType enums that generates compile-time warning SYSLIB0058. +ms.date: 01/01/2025 +ai-usage: ai-assisted +f1_keywords: + - SYSLIB0058 +--- +# SYSLIB0058: Certain SslStream properties are obsolete + +The following properties of are obsolete, starting in .NET 10: + +- +- +- +- +- +- + +, , and enums are obsolete since they were only used by the class. + +## Reason for obsoletion + +The obsoleted enum types were outdated and missing members for covering new algorithms. Since the same information is available via , the outdated properties were removed to clarify which one should be used for logging/auditing purposes. + +## Workaround + +Use instead. + +## Suppress a warning + +If you must use the obsolete API, you can suppress the warning in code or in your project file. + +To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning. + +```csharp +// Disable the warning. +#pragma warning disable SYSLIB0058 + +// Code that uses obsolete API. +// ... + +// Re-enable the warning. +#pragma warning restore SYSLIB0058 +``` + +To suppress all the `SYSLIB0058` warnings in your project, add a `` property to your project file. + +```xml + + + ... + $(NoWarn);SYSLIB0058 + + +``` + +For more information, see [Suppress warnings](obsoletions-overview.md#suppress-warnings). diff --git a/docs/fundamentals/syslib-diagnostics/syslib0060.md b/docs/fundamentals/syslib-diagnostics/syslib0060.md new file mode 100644 index 0000000000000..eba580531f6ff --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0060.md @@ -0,0 +1,64 @@ +--- +title: SYSLIB0060 warning - Rfc2898DeriveBytes constructors are obsolete +description: Learn about the obsoletion of Rfc2898DeriveBytes constructors. Use of these constructors generates compile-time warning SYSLIB0060. +ms.date: 01/30/2025 +ai-usage: ai-assisted +f1_keywords: + - SYSLIB0060 +--- +# SYSLIB0060: Rfc2898DeriveBytes constructors are obsolete + +Starting in .NET 10, all of the constructors on are obsolete. Calling these constructors in code generates warning `SYSLIB0060` at compile time. + +## Reason for obsoletion + +The instance-based implementation of PBKDF2, which provides, offers a non-standard usage by "streaming" bytes back by allowing successive calls to `GetBytes`. This is not the intended use of PBKDF2; the algorithm should be used as a one-shot. The one-shot functionality exists as the static method and should be used instead of instantiating . + +## Workaround + +Change instances of and calls to `GetBytes` to use the one-shot static method instead. + +For example, change: + +```csharp +using System.Security.Cryptography; + +Rfc2898DeriveBytes kdf = new Rfc2898DeriveBytes(password, salt, iterations, hashAlgorithm); +byte[] derivedKey = kdf.GetBytes(64); +``` + +to + +```csharp +byte[] derivedKey = Rfc2898DeriveBytes.Pbkdf2(password, salt, iterations, hashAlgorithm, 64); +``` + +## Suppress a warning + +If you must use the obsolete API, you can suppress the warning in code or in your project file. + +To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning. + +```csharp +// Disable the warning. +#pragma warning disable SYSLIB0060 + +// Code that uses obsolete API. +// ... + +// Re-enable the warning. +#pragma warning restore SYSLIB0060 +``` + +To suppress all the `SYSLIB0060` warnings in your project, add a `` property to your project file. + +```xml + + + ... + $(NoWarn);SYSLIB0060 + + +``` + +For more information, see [Suppress warnings](obsoletions-overview.md#suppress-warnings). diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index bbf8858b1f20e..de24d0465b7f0 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -1822,8 +1822,12 @@ items: href: ../../fundamentals/syslib-diagnostics/syslib0056.md - name: SYSLIB0057 href: ../../fundamentals/syslib-diagnostics/syslib0057.md + - name: SYSLIB0058 + href: ../../fundamentals/syslib-diagnostics/syslib0058.md - name: SYSLIB0059 href: ../../fundamentals/syslib-diagnostics/syslib0059.md + - name: SYSLIB0060 + href: ../../fundamentals/syslib-diagnostics/syslib0060.md - name: Experimental features items: - name: Overview diff --git a/docs/visual-basic/programming-guide/language-features/data-types/generic-types.md b/docs/visual-basic/programming-guide/language-features/data-types/generic-types.md index 5da15590b0db7..a7b626d0e9c74 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/generic-types.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/generic-types.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Generic Types in Visual Basic (Visual Basic)" title: "Generic Types" -ms.date: 07/20/2015 +ms.date: 01/31/2025 helpviewer_keywords: - "generic interfaces" - "data type arguments [Visual Basic], defining" @@ -36,120 +36,107 @@ helpviewer_keywords: - "data type parameters [Visual Basic], defining" - "type arguments [Visual Basic], defining" - "arguments [Visual Basic], type" -ms.assetid: 89f771d9-ecbb-4737-88b8-116b63c6cf4d --- -# Generic Types in Visual Basic (Visual Basic) - -A *generic type* is a single programming element that adapts to perform the same functionality for a variety of data types. When you define a generic class or procedure, you do not have to define a separate version for each data type for which you might want to perform that functionality. - - An analogy is a screwdriver set with removable heads. You inspect the screw you need to turn and select the correct head for that screw (slotted, crossed, starred). Once you insert the correct head in the screwdriver handle, you perform the exact same function with the screwdriver, namely turning the screw. - - ![Diagram of a screwdriver set with different heads.](./media/generic-types/generic-screwdriver-set.gif) - - When you define a generic type, you parameterize it with one or more data types. This allows the using code to tailor the data types to its requirements. Your code can declare several different programming elements from the generic element, each one acting on a different set of data types. But the declared elements all perform the identical logic, no matter what data types they are using. - - For example, you might want to create and use a queue class that operates on a specific data type such as `String`. You can declare such a class from , as the following example shows. - - [!code-vb[VbVbalrDataTypes#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#1)] - - You can now use `stringQ` to work exclusively with `String` values. Because `stringQ` is specific for `String` instead of being generalized for `Object` values, you do not have late binding or type conversion. This saves execution time and reduces run-time errors. - - For more information on using a generic type, see [How to: Use a Generic Class](how-to-use-a-generic-class.md). - -## Example of a Generic Class - - The following example shows a skeleton definition of a generic class. - - [!code-vb[VbVbalrDataTypes#2](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#2)] - - In the preceding skeleton, `t` is a *type parameter*, that is, a placeholder for a data type that you supply when you declare the class. Elsewhere in your code, you can declare various versions of `classHolder` by supplying various data types for `t`. The following example shows two such declarations. - - [!code-vb[VbVbalrDataTypes#3](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#3)] - - The preceding statements declare *constructed classes*, in which a specific type replaces the type parameter. This replacement is propagated throughout the code within the constructed class. The following example shows what the `processNewItem` procedure looks like in `integerClass`. - - [!code-vb[VbVbalrDataTypes#4](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#4)] - - For a more complete example, see [How to: Define a Class That Can Provide Identical Functionality on Different Data Types](how-to-define-a-class-that-can-provide-identical-functionality.md). - -## Eligible Programming Elements - - You can define and use generic classes, structures, interfaces, procedures, and delegates. Note that the .NET Framework defines several generic classes, structures, and interfaces that represent commonly used generic elements. The namespace provides dictionaries, lists, queues, and stacks. Before defining your own generic element, see if it is already available in . - - Procedures are not types, but you can define and use generic procedures. See [Generic Procedures in Visual Basic](generic-procedures.md). - -## Advantages of Generic Types - - A generic type serves as a basis for declaring several different programming elements, each of which operates on a specific data type. The alternatives to a generic type are: - -1. A single type operating on the `Object` data type. - -2. A set of *type-specific* versions of the type, each version individually coded and operating on one specific data type such as `String`, `Integer`, or a user-defined type such as `customer`. - - A generic type has the following advantages over these alternatives: - -- **Type Safety.** Generic types enforce compile-time type checking. Types based on `Object` accept any data type, and you must write code to check whether an input data type is acceptable. With generic types, the compiler can catch type mismatches before run time. - -- **Performance.** Generic types do not have to *box* and *unbox* data, because each one is specialized for one data type. Operations based on `Object` must box input data types to convert them to `Object` and unbox data destined for output. Boxing and unboxing reduce performance. - - Types based on `Object` are also late-bound, which means that accessing their members requires extra code at run time. This also reduces performance. - -- **Code Consolidation.** The code in a generic type has to be defined only once. A set of type-specific versions of a type must replicate the same code in each version, with the only difference being the specific data type for that version. With generic types, the type-specific versions are all generated from the original generic type. - -- **Code Reuse.** Code that does not depend on a particular data type can be reused with various data types if it is generic. You can often reuse it even with a data type that you did not originally predict. - -- **IDE Support.** When you use a constructed type declared from a generic type, the integrated development environment (IDE) can give you more support while you are developing your code. For example, IntelliSense can show you the type-specific options for an argument to a constructor or method. - -- **Generic Algorithms.** Abstract algorithms that are type-independent are good candidates for generic types. For example, a generic procedure that sorts items using the interface can be used with any data type that implements . - -## Constraints - - Although the code in a generic type definition should be as type-independent as possible, you might need to require a certain capability of any data type supplied to your generic type. For example, if you want to compare two items for the purpose of sorting or collating, their data type must implement the interface. You can enforce this requirement by adding a *constraint* to the type parameter. - -### Example of a Constraint - - The following example shows a skeleton definition of a class with a constraint that requires the type argument to implement . - - [!code-vb[VbVbalrDataTypes#5](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#5)] - - If subsequent code attempts to construct a class from `itemManager` supplying a type that does not implement , the compiler signals an error. - -### Types of Constraints - - Your constraint can specify the following requirements in any combination: - -- The type argument must implement one or more interfaces - -- The type argument must be of the type of, or inherit from, at most one class - -- The type argument must expose a parameterless constructor accessible to the code that creates objects from it - -- The type argument must be a *reference type*, or it must be a *value type* - - If you need to impose more than one requirement, you use a comma-separated *constraint list* inside braces (`{ }`). To require an accessible constructor, you include the [New Operator](../../../language-reference/operators/new-operator.md) keyword in the list. To require a reference type, you include the `Class` keyword; to require a value type, you include the `Structure` keyword. - - For more information on constraints, see [Type List](../../../language-reference/statements/type-list.md). - -### Example of Multiple Constraints - - The following example shows a skeleton definition of a generic class with a constraint list on the type parameter. In the code that creates an instance of this class, the type argument must implement both the and interfaces, be a reference type, and expose an accessible parameterless constructor. - - [!code-vb[VbVbalrDataTypes#6](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb#6)] - -## Important Terms - - Generic types introduce and use the following terms: - -- *Generic Type*. A definition of a class, structure, interface, procedure, or delegate for which you supply at least one data type when you declare it. - -- *Type Parameter*. In a generic type definition, a placeholder for a data type you supply when you declare the type. - -- *Type Argument*. A specific data type that replaces a type parameter when you declare a constructed type from a generic type. - -- *Constraint*. A condition on a type parameter that restricts the type argument you can supply for it. A constraint can require that the type argument must implement a particular interface, be or inherit from a particular class, have an accessible parameterless constructor, or be a reference type or a value type. You can combine these constraints, but you can specify at most one class. - -- *Constructed Type*. A class, structure, interface, procedure, or delegate declared from a generic type by supplying type arguments for its type parameters. - +# Generic types in Visual Basic (Visual Basic) + +A *generic type* is a single programming element that adapts to perform the same functionality for multiple data types. When you define a generic class or procedure, you don't have to define a separate version for each data type for which you might want to perform that functionality. + +An analogy is a screwdriver set with removable heads. You inspect the screw and select the correct head for that screw (slotted, crossed, starred). Once you insert the correct head in the screwdriver handle, you perform the exact same function with the screwdriver, namely turning the screw. + +:::image type="content" source="./media/generic-types/generic-screwdriver-set.gif" alt-text="Diagram of a screwdriver set with different heads."::: + +When you define a generic type, you parameterize it with one or more data types. Type parameters allow code to tailor the data types to its requirements. Your code can declare several different programming elements from the generic element, each one acting on a different set of data types. But the declared elements all perform the identical logic, no matter what data types they're using. + +For example, you might want to create and use a queue class that operates on a specific data type such as `String`. You can declare such a class from , as the following example shows. + +:::code language="visual-basic" source="~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb" id="Snippet1"::: + +You can now use `stringQ` to work exclusively with `String` values. Because `stringQ` is specific for `String` instead of being generalized for `Object` values, you don't have late binding or type conversion. Generic types save execution time and reduce run-time errors. + +For more information on using a generic type, see [How to: Use a Generic Class](how-to-use-a-generic-class.md). + +## Example of a generic class + +The following example shows a skeleton definition of a generic class. + +:::code language="visual-basic" source="~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb" id="Snippet2"::: + +In the preceding skeleton, `t` is a *type parameter*, that is, a placeholder for a data type that you supply when you declare the class. Elsewhere in your code, you can declare various versions of `classHolder` by supplying various data types for `t`. The following example shows two such declarations. + +:::code language="visual-basic" source="~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb" id="Snippet3"::: + +The preceding statements declare *constructed classes*, in which a specific type replaces the type parameter. This replacement is propagated throughout the code within the constructed class. The following example shows what the `processNewItem` procedure looks like in `integerClass`. + +:::code language="visual-basic" source="~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb" id="Snippet4"::: + +For a more complete example, see [How to: Define a Class That Can Provide Identical Functionality on Different Data Types](how-to-define-a-class-that-can-provide-identical-functionality.md). + +## Eligible programming elements + +You can define and use generic classes, structures, interfaces, procedures, and delegates. .NET defines several generic classes, structures, and interfaces that represent commonly used generic elements. The namespace provides dictionaries, lists, queues, and stacks. Before defining your own generic element, see if it's already available in . + +Procedures aren't types, but you can define and use generic procedures. See [Generic Procedures in Visual Basic](generic-procedures.md). + +## Advantages of generic types + +A generic type serves as a basis for declaring several different programming elements, each of which operates on a specific data type. The alternatives to a generic type are: + +1. A single type operating on the `Object` data type. +2. A set of *type-specific* versions of the type. Each version is individually coded and operating on one specific data type such as `String`, `Integer`, or a user-defined type such as `customer`. + +A generic type has the following advantages over these alternatives: + +- **Type Safety.** Generic types enforce compile-time type checking. Types based on `Object` accept any data type, and you must write code to check whether an input data type is acceptable. With generic types, the compiler can catch type mismatches before run time. +- **Performance.** Generic types don't have to *box* and *unbox* data, because each one is specialized for one data type. Operations based on `Object` must box input data types to convert them to `Object` and unbox data destined for output. Boxing and unboxing reduce performance. + Types based on `Object` are also late-bound, which means that accessing their members requires extra code at run time. Type conversions also reduce performance. +- **Code Consolidation.** The code in a generic type has to be defined only once. A set of type-specific versions of a type must replicate the same code in each version, with the only difference being the specific data type for that version. With generic types, the type-specific versions are all generated from the original generic type. +- **Code Reuse.** Code that doesn't depend on a particular data type can be reused with various data types if it's generic. You can often reuse it even with a data type that you didn't originally predict. +- **IDE Support.** When you use a constructed type declared from a generic type, the integrated development environment (IDE) can give you more support while you're developing your code. For example, IntelliSense can show you the type-specific options for an argument to a constructor or method. +- **Generic Algorithms.** Abstract algorithms that are type-independent are good candidates for generic types. For example, a generic procedure that sorts items using the interface can be used with any data type that implements . + +## Constraints + +Although the code in a generic type definition should be as type-independent as possible, you might need to require a certain capability of any data type supplied to your generic type. For example, if you want to compare two items to sort or collate, their data type must implement the interface. You can enforce this requirement by adding a *constraint* to the type parameter. + +### Example of a constraint + +The following example shows a skeleton definition of a class with a constraint that requires the type argument to implement . + +:::code language="visual-basic" source="~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb" id="Snippet5"::: + +If subsequent code attempts to construct a class from `itemManager` supplying a type that doesn't implement , the compiler signals an error. + +### Types of constraints + +Your constraint can specify the following requirements in any combination: + +- The type argument must implement one or more interfaces +- The type argument must be of the type of, or inherit from, at most one class +- The type argument must expose a parameterless constructor accessible to the code that creates objects from it +- The type argument must be a *reference type*, or it must be a *value type* + +C# code can declare that a type argument must be an [*unmanaged type*](../../../../csharp/programming-guide/generics/constraints-on-type-parameters.md#unmanaged-constraint). Visual Basic enforces this constraint for Visual Basic code that uses a generic type or method that was defined with this constraint (in C#). However, you can't declare an `unmanaged` constraint on a type parameter in Visual Basic. + +If you need to impose more than one requirement, you use a comma-separated *constraint list* inside braces (`{ }`). To require an accessible constructor, you include the [New Operator](../../../language-reference/operators/new-operator.md) keyword in the list. To require a reference type, you include the `Class` keyword; to require a value type, you include the `Structure` keyword. + +For more information on constraints, see [Type List](../../../language-reference/statements/type-list.md). + +### Example of multiple constraints + +The following example shows a skeleton definition of a generic class with a constraint list on the type parameter. In the code that creates an instance of this class, the type argument must implement both the and interfaces, be a reference type, and expose an accessible parameterless constructor. + +:::code language="visual-basic" source="~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrDataTypes/VB/Class1.vb" id="Snippet6"::: + +## Important terms + +Generic types introduce and use the following terms: + +- *Generic Type*. A definition of a class, structure, interface, procedure, or delegate for which you supply at least one data type when you declare it. +- *Type Parameter*. In a generic type definition, a placeholder for a data type you supply when you declare the type. +- *Type Argument*. A specific data type that replaces a type parameter when you declare a constructed type from a generic type. +- *Constraint*. A condition on a type parameter that restricts the type argument you can supply for it. A constraint can require that the type argument implement a particular interface, inherit from a particular class, have an accessible parameterless constructor, or be a reference type or a value type. You can combine these constraints, but you can specify at most one base class. +- *Constructed Type*. A class, structure, interface, procedure, or delegate declared from a generic type by supplying type arguments for its type parameters. + ## See also - [Data Types](index.md) diff --git a/docs/visual-basic/programming-guide/language-features/procedures/overload-resolution.md b/docs/visual-basic/programming-guide/language-features/procedures/overload-resolution.md index e4630b8365b4e..cc7c0abea8b0b 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/overload-resolution.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/overload-resolution.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Overload Resolution (Visual Basic)" title: "Overload Resolution" -ms.date: 07/20/2015 +ms.date: 01/31/2025 helpviewer_keywords: - "Visual Basic code, procedures" - "overload resolution" @@ -10,51 +10,45 @@ helpviewer_keywords: - "procedure overloading [Visual Basic], overload resolution" - "signatures [Visual Basic], procedure" - "overloads [Visual Basic], resolution" -ms.assetid: 766115d1-4352-45fb-859f-6063e0de0ec0 --- -# Overload Resolution (Visual Basic) +# Overload resolution (Visual Basic) -When the Visual Basic compiler encounters a call to a procedure that is defined in several overloaded versions, the compiler must decide which of the overloads to call. It does this by performing the following steps: - -1. **Accessibility.** It eliminates any overload with an access level that prevents the calling code from calling it. - -2. **Number of Parameters.** It eliminates any overload that defines a different number of parameters than are supplied in the call. - -3. **Parameter Data Types.** The compiler gives instance methods preference over extension methods. If any instance method is found that requires only widening conversions to match the procedure call, all extension methods are dropped and the compiler continues with only the instance method candidates. If no such instance method is found, it continues with both instance and extension methods. - - In this step, it eliminates any overload for which the data types of the calling arguments cannot be converted to the parameter types defined in the overload. - -4. **Narrowing Conversions.** It eliminates any overload that requires a narrowing conversion from the calling argument types to the defined parameter types. This is true whether the type checking switch ([Option Strict Statement](../../../language-reference/statements/option-strict-statement.md)) is `On` or `Off`. - -5. **Least Widening.** The compiler considers the remaining overloads in pairs. For each pair, it compares the data types of the defined parameters. If the types in one of the overloads all widen to the corresponding types in the other, the compiler eliminates the latter. That is, it retains the overload that requires the least amount of widening. - -6. **Single Candidate.** It continues considering overloads in pairs until only one overload remains, and it resolves the call to that overload. If the compiler cannot reduce the overloads to a single candidate, it generates an error. - - The following illustration shows the process that determines which of a set of overloaded versions to call. - - ![Flow diagram of overload resolution process](./media/overload-resolution/determine-overloaded-version.gif "Resolving among overloaded versions") - - The following example illustrates this overload resolution process. - - [!code-vb[VbVbcnProcedures#62](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#62)] - - [!code-vb[VbVbcnProcedures#63](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb#63)] - - In the first call, the compiler eliminates the first overload because the type of the first argument (`Short`) narrows to the type of the corresponding parameter (`Byte`). It then eliminates the third overload because each argument type in the second overload (`Short` and `Single`) widens to the corresponding type in the third overload (`Integer` and `Single`). The second overload requires less widening, so the compiler uses it for the call. - - In the second call, the compiler cannot eliminate any of the overloads on the basis of narrowing. It eliminates the third overload for the same reason as in the first call, because it can call the second overload with less widening of the argument types. However, the compiler cannot resolve between the first and second overloads. Each has one defined parameter type that widens to the corresponding type in the other (`Byte` to `Short`, but `Single` to `Double`). The compiler therefore generates an overload resolution error. - -## Overloaded Optional and ParamArray Arguments +The Visual Basic compiler must decide which overload to call when a procedure is defined in several overloaded versions. It decides by performing the following steps: + +1. **Accessibility.** It eliminates any overload with an access level that prevents the calling code from calling it. +1. **Number of Parameters.** It eliminates any overload that defines a different number of parameters than are supplied in the call. +1. **Parameter Data Types.** The compiler gives instance methods preference over extension methods. If any instance method is found that requires only widening conversions to match the procedure call, all extension methods are dropped. The compiler continues with only the instance method candidates. If no such instance method is found, it continues with both instance and extension methods. + In this step, it eliminates any overload for which the data types of the calling arguments can't be converted to the parameter types defined in the overload. +1. **Narrowing Conversions.** It eliminates any overload that requires a narrowing conversion from the calling argument types to the defined parameter types. This step takes place whether the type checking switch ([Option Strict Statement](../../../language-reference/statements/option-strict-statement.md)) is `On` or `Off`. +1. **Least Widening.** The compiler considers the remaining overloads in pairs. For each pair, it compares the data types of the defined parameters. If the types in one of the overloads all widen to the corresponding types in the other, the compiler eliminates the latter. That is, it retains the overload that requires the least amount of widening. +1. **Overload Resolution Priority.** The compiler removes any overload that has a lower than the highest value on any candidate overloads. Any overload without this attribute is assigned the default value of zero. +1. **Single Candidate.** It continues considering overloads in pairs until only one overload remains, and it resolves the call to that overload. If the compiler can't reduce the overloads to a single candidate, it generates an error. + +The following illustration shows the process that determines which of a set of overloaded versions to call. + +:::image type="content" source="./media/overload-resolution/determine-overloaded-version.gif" alt-text="Flow diagram of overload resolution process"::: + +The following example illustrates this overload resolution process. + +:::code language="visual-basic" source="~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb" id="Snippet62"::: + +:::code language="visual-basic" source="~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbcnProcedures/VB/Class1.vb" id="Snippet63"::: + +In the first call, the compiler eliminates the first overload because the type of the first argument (`Short`) narrows to the type of the corresponding parameter (`Byte`). It then eliminates the third overload because each argument type in the second overload (`Short` and `Single`) widens to the corresponding type in the third overload (`Integer` and `Single`). The second overload requires less widening, so the compiler uses it for the call. + +In the second call, the compiler can't eliminate any of the overloads based on narrowing. It eliminates the third overload for the same reason as in the first call, because it can call the second overload with less widening of the argument types. However, the compiler can't resolve between the first and second overloads. Each has one defined parameter type that widens to the corresponding type in the other (`Byte` to `Short`, but `Single` to `Double`). The compiler therefore generates an overload resolution error. + +## Overloaded `Optional` and `ParamArray` arguments + +If two overloads of a procedure have identical signatures except that the last parameter is declared [Optional](../../../language-reference/modifiers/optional.md) in one and [ParamArray](../../../language-reference/modifiers/paramarray.md) in the other, the compiler resolves a call to that procedure as follows: + +|If the call supplies the last argument as|The compiler resolves the call to the overload declaring the last argument as| +|---|---| +|No value (argument omitted)|`Optional`| +|A single value|`Optional`| +|Two or more values in a comma-separated list|`ParamArray`| +|An array of any length (including an empty array)|`ParamArray`| - If two overloads of a procedure have identical signatures except that the last parameter is declared [Optional](../../../language-reference/modifiers/optional.md) in one and [ParamArray](../../../language-reference/modifiers/paramarray.md) in the other, the compiler resolves a call to that procedure as follows: - -|If the call supplies the last argument as|The compiler resolves the call to the overload declaring the last argument as| -|---|---| -|No value (argument omitted)|`Optional`| -|A single value|`Optional`| -|Two or more values in a comma-separated list|`ParamArray`| -|An array of any length (including an empty array)|`ParamArray`| - ## See also - [Optional Parameters](./optional-parameters.md)