From c16dba3202e1fe5d3be05ed31b41c6d9685047a2 Mon Sep 17 00:00:00 2001 From: Andrew Casey Date: Fri, 20 Oct 2023 18:29:20 -0700 Subject: [PATCH 01/20] Document that WebHost.CreateDefaultBuilder will use port 5000 ...rather than port 8080, like newer hosts. Fixes https://github.com/dotnet/aspnetcore/issues/51125 --- docs/core/compatibility/containers/8.0/aspnet-port.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/core/compatibility/containers/8.0/aspnet-port.md b/docs/core/compatibility/containers/8.0/aspnet-port.md index 2c6bcc18f7997..7bca16aa64013 100644 --- a/docs/core/compatibility/containers/8.0/aspnet-port.md +++ b/docs/core/compatibility/containers/8.0/aspnet-port.md @@ -9,6 +9,8 @@ The default ASP.NET Core port configured in .NET container images has been updat We also added the new `ASPNETCORE_HTTP_PORTS` environment variable as a simpler alternative to `ASPNETCORE_URLS`. The new variable expects a semicolon delimited list of ports numbers, while the older variable expects a more complicated syntax. +Apps build using the older [`WebHost.CreateDefaultBuilder`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.webhost.createdefaultbuilder) API won't respect the new `ASPNETCORE_HTTP_PORTS` environment variable and will therefore switch to using a default port of 5000, now that `ASPNETCORE_URLS` is no longer set automatically. + ## Previous behavior Prior to .NET 8, you could run a container expecting port 80 to be the default port and be able to access the running app. @@ -56,7 +58,7 @@ $ docker kill 74d866bdaa8a5a09e4a347bba17ced321d77a2524a0853294a123640bcc7f21d Mapping port `80` with `ASPNETCORE_HTTP_PORTS` set to port `80`: ```bash -$ docker run --rm -d -p 8000:80 -e ASPNETCORE_HTTP_PORTS=80 mcr.microsoft.com/dotnet/samples:aspnetapp +$ docker run --rm -d -p 8000:80 -e ASPNETCORE_HTTP_PORTS=80 mcr.microsoft.com/dotnet/samples:aspnetapp 3cc86b4b3ea1a7303d83171c132b0645d4adf61d80131152936b01661ae82a09 $ curl http://localhost:8000/Environment {"runtimeVersion":".NET 8.0.0-rc.1.23419.4","osVersion":"Alpine Linux v3.18","osArchitecture":"Arm64","user":"root","processorCount":4,"totalAvailableMemoryBytes":4123820032,"memoryLimit":0,"memoryUsage":95383552,"hostName":"3cc86b4b3ea1"} @@ -85,6 +87,8 @@ There are two ways to respond to this breaking change: - Recommended: Explicitly set the `ASPNETCORE_HTTP_PORTS`, `ASPNETCORE_HTTPS_PORTS`, and `ASPNETCORE_URLS` environment variables to the desired port. Example: `docker run --rm -it -p 9999:80 -e ASPNETCORE_HTTP_PORTS=80 ` - Update existing commands and configuration that rely on the expected default port of port 80 to reference port 8080 instead. Example: `docker run --rm -it -p 9999:8080 ` +Apps build using the older [`WebHost.CreateDefaultBuilder`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.webhost.createdefaultbuilder) will need to either set `ASPNETCORE_URLS` (not `ASPNETCORE_HTTP_PORTS`) or update the expected default port of port 80 to reference port 5000 instead. + ## Affected APIs None. From bf3b82977ec25fa4f85de2f1006157f97208cabb Mon Sep 17 00:00:00 2001 From: Andrew Casey Date: Mon, 23 Oct 2023 13:24:13 -0700 Subject: [PATCH 02/20] Use xref for doc links Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/containers/8.0/aspnet-port.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/compatibility/containers/8.0/aspnet-port.md b/docs/core/compatibility/containers/8.0/aspnet-port.md index 7bca16aa64013..ff8ae4f58fb06 100644 --- a/docs/core/compatibility/containers/8.0/aspnet-port.md +++ b/docs/core/compatibility/containers/8.0/aspnet-port.md @@ -9,7 +9,7 @@ The default ASP.NET Core port configured in .NET container images has been updat We also added the new `ASPNETCORE_HTTP_PORTS` environment variable as a simpler alternative to `ASPNETCORE_URLS`. The new variable expects a semicolon delimited list of ports numbers, while the older variable expects a more complicated syntax. -Apps build using the older [`WebHost.CreateDefaultBuilder`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.webhost.createdefaultbuilder) API won't respect the new `ASPNETCORE_HTTP_PORTS` environment variable and will therefore switch to using a default port of 5000, now that `ASPNETCORE_URLS` is no longer set automatically. +Apps build using the older [`WebHost.CreateDefaultBuilder`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.webhost.createdefaultbuilder) API won't respect the new `ASPNETCORE_HTTP_PORTS` environment variable and will therefore switch to using a default port of 5000, which is not accessible outside the container, now that `ASPNETCORE_URLS` is no longer set automatically. ## Previous behavior @@ -87,7 +87,7 @@ There are two ways to respond to this breaking change: - Recommended: Explicitly set the `ASPNETCORE_HTTP_PORTS`, `ASPNETCORE_HTTPS_PORTS`, and `ASPNETCORE_URLS` environment variables to the desired port. Example: `docker run --rm -it -p 9999:80 -e ASPNETCORE_HTTP_PORTS=80 ` - Update existing commands and configuration that rely on the expected default port of port 80 to reference port 8080 instead. Example: `docker run --rm -it -p 9999:8080 ` -Apps build using the older [`WebHost.CreateDefaultBuilder`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.webhost.createdefaultbuilder) will need to either set `ASPNETCORE_URLS` (not `ASPNETCORE_HTTP_PORTS`) or update the expected default port of port 80 to reference port 5000 instead. +If your app was built using the older method, either set `ASPNETCORE_URLS` (not `ASPNETCORE_HTTP_PORTS`) or update the expected default port of port 80 to reference port 5000 instead. ## Affected APIs From dbb451e1a1cbcabd13a9ebcc34d709a7a4265891 Mon Sep 17 00:00:00 2001 From: Andrew Casey Date: Mon, 23 Oct 2023 13:26:46 -0700 Subject: [PATCH 03/20] Use --- docs/core/compatibility/containers/8.0/aspnet-port.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/containers/8.0/aspnet-port.md b/docs/core/compatibility/containers/8.0/aspnet-port.md index ff8ae4f58fb06..1a71716598abc 100644 --- a/docs/core/compatibility/containers/8.0/aspnet-port.md +++ b/docs/core/compatibility/containers/8.0/aspnet-port.md @@ -9,7 +9,7 @@ The default ASP.NET Core port configured in .NET container images has been updat We also added the new `ASPNETCORE_HTTP_PORTS` environment variable as a simpler alternative to `ASPNETCORE_URLS`. The new variable expects a semicolon delimited list of ports numbers, while the older variable expects a more complicated syntax. -Apps build using the older [`WebHost.CreateDefaultBuilder`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.webhost.createdefaultbuilder) API won't respect the new `ASPNETCORE_HTTP_PORTS` environment variable and will therefore switch to using a default port of 5000, which is not accessible outside the container, now that `ASPNETCORE_URLS` is no longer set automatically. +Apps built using the older API won't respect the new `ASPNETCORE_HTTP_PORTS` environment variable. And now that `ASPNETCORE_URLS` is no longer set automatically, they'll switch to use a default port of 5000. ## Previous behavior From 7ab47bf08baf737cea1e6e0a29a9995f1b30d2a2 Mon Sep 17 00:00:00 2001 From: Andrew Casey Date: Wed, 25 Oct 2023 16:18:59 -0700 Subject: [PATCH 04/20] Be more explicit about localhost --- docs/core/compatibility/containers/8.0/aspnet-port.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/compatibility/containers/8.0/aspnet-port.md b/docs/core/compatibility/containers/8.0/aspnet-port.md index 1a71716598abc..ddc837e1f3efe 100644 --- a/docs/core/compatibility/containers/8.0/aspnet-port.md +++ b/docs/core/compatibility/containers/8.0/aspnet-port.md @@ -9,7 +9,7 @@ The default ASP.NET Core port configured in .NET container images has been updat We also added the new `ASPNETCORE_HTTP_PORTS` environment variable as a simpler alternative to `ASPNETCORE_URLS`. The new variable expects a semicolon delimited list of ports numbers, while the older variable expects a more complicated syntax. -Apps built using the older API won't respect the new `ASPNETCORE_HTTP_PORTS` environment variable. And now that `ASPNETCORE_URLS` is no longer set automatically, they'll switch to use a default port of 5000. +Apps built using the older API won't respect the new `ASPNETCORE_HTTP_PORTS` environment variable. And now that `ASPNETCORE_URLS` is no longer set automatically, they'll switch to use a default URL of `http://localhost:5000`, rather than `http://*:80`, as formerly. ## Previous behavior @@ -87,7 +87,7 @@ There are two ways to respond to this breaking change: - Recommended: Explicitly set the `ASPNETCORE_HTTP_PORTS`, `ASPNETCORE_HTTPS_PORTS`, and `ASPNETCORE_URLS` environment variables to the desired port. Example: `docker run --rm -it -p 9999:80 -e ASPNETCORE_HTTP_PORTS=80 ` - Update existing commands and configuration that rely on the expected default port of port 80 to reference port 8080 instead. Example: `docker run --rm -it -p 9999:8080 ` -If your app was built using the older method, either set `ASPNETCORE_URLS` (not `ASPNETCORE_HTTP_PORTS`) or update the expected default port of port 80 to reference port 5000 instead. +If your app was built using the older method, set `ASPNETCORE_URLS` (not `ASPNETCORE_HTTP_PORTS`). Example: `docker run --rm -it -p 9999:80 -e ASPNETCORE_URLS=http://*:80 ` ## Affected APIs From e3557d868725fec6142c85502e7b2917dda97d9e Mon Sep 17 00:00:00 2001 From: Theano Petersen <20667102+v-thepet@users.noreply.github.com> Date: Thu, 2 Nov 2023 06:04:41 -0700 Subject: [PATCH 05/20] Fixes (?) GitHub issue #30189 - Question about note on Creating and Throwing exceptions page (#37822) * Update creating-and-throwing-exceptions.md * Update creating-and-throwing-exceptions.md --- .../exceptions/creating-and-throwing-exceptions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/csharp/fundamentals/exceptions/creating-and-throwing-exceptions.md b/docs/csharp/fundamentals/exceptions/creating-and-throwing-exceptions.md index 848cc1e9aa719..8f5ed99204671 100644 --- a/docs/csharp/fundamentals/exceptions/creating-and-throwing-exceptions.md +++ b/docs/csharp/fundamentals/exceptions/creating-and-throwing-exceptions.md @@ -1,7 +1,7 @@ --- title: "Creating and Throwing Exceptions" description: Learn about creating and throwing exceptions. Exceptions are used to indicate that an error has occurred while running a program. -ms.date: 09/28/2023 +ms.date: 10/31/2023 helpviewer_keywords: - "catching exceptions [C#]" - "throwing exceptions [C#]" @@ -26,8 +26,8 @@ Programmers should throw exceptions when one or more of the following conditions :::code language="csharp" source="snippets/exceptions/Program.cs" ID="InvalidArg"::: -> [!NOTE] -> The example above is for illustrative purposes. Index validating via exceptions is in most cases bad practice. Exceptions should be reserved to guard against exceptional program conditions, not for argument checking as above. + > [!NOTE] + > The preceding example shows how to use the `InnerException` property. It's intentionally simplified. In practice, you should check that an index is in range before using it. You could use this technique of wrapping an exception when a member of a parameter throws an exception you couldn't anticipate before calling the member. Exceptions contain a property named . This string contains the name of the methods on the current call stack, together with the file name and line number where the exception was thrown for each method. A object is created automatically by the common language runtime (CLR) from the point of the `throw` statement, so that exceptions must be thrown from the point where the stack trace should begin. From 04d983c73ddb6388c93e4f323a37e062ae56d9f0 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 2 Nov 2023 09:10:03 -0400 Subject: [PATCH 06/20] What's new article (#37832) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Bot 🤖 generated "What's new article" * Update docs/whats-new/dotnet-docs-mod1.md --------- Co-authored-by: IEvangelist Co-authored-by: David Pine --- docs/whats-new/dotnet-docs-mod1.md | 176 ++++++++++++++++++----------- docs/whats-new/index.yml | 6 +- docs/whats-new/toc.yml | 4 +- 3 files changed, 117 insertions(+), 69 deletions(-) diff --git a/docs/whats-new/dotnet-docs-mod1.md b/docs/whats-new/dotnet-docs-mod1.md index 584decb25625b..3b0876d337623 100644 --- a/docs/whats-new/dotnet-docs-mod1.md +++ b/docs/whats-new/dotnet-docs-mod1.md @@ -1,102 +1,150 @@ --- -title: ".NET docs: What's new for July 2023" -description: "What's new in the .NET docs for July 2023." -ms.custom: July-2023 -ms.date: 08/01/2023 +title: ".NET docs: What's new for October 2023" +description: "What's new in the .NET docs for October 2023." +ms.custom: October-2023 +ms.date: 11/01/2023 --- -# .NET docs: What's new for July 2023 +# .NET docs: What's new for October 2023 -Welcome to what's new in the .NET docs for July 2023. This article lists some of the major changes to docs during this period. +Welcome to what's new in the .NET docs for October 2023. This article lists some of the major changes to docs during this period. ## .NET breaking changes ### New articles -- [Tool manifests in root folder](../core/compatibility/sdk/7.0/manifest-search.md) -- [Empty keys added to dictionary by configuration binder](../core/compatibility/extensions/8.0/dictionary-configuration-binding.md) -- [Containers default to use the 'latest' tag](../core/compatibility/sdk/8.0/default-image-tag.md) -- [SDK no longer calls ResolvePackageDependencies](../core/compatibility/sdk/7.0/resolvepackagedependencies.md) -- [New 'app' user in Linux images](../core/compatibility/containers/8.0/app-user.md) -- [Default ASP.NET Core port changed to 8080](../core/compatibility/containers/8.0/aspnet-port.md) -- [Debian container images upgraded to Debian 12](../core/compatibility/containers/8.0/debian-version.md) -- ['libintl' package removed from Alpine images](../core/compatibility/containers/8.0/libintl-package.md) -- [Multi-platform container tags are Linux-only](../core/compatibility/containers/8.0/multi-platform-tags.md) +- [ManagementDateTimeConverter.ToDateTime returns a local time](../core/compatibility/extensions/8.0/dmtf-todatetime.md) +- [--arch option doesn't imply self-contained](../core/compatibility/sdk/8.0/arch-option.md) + +## .NET Framework + +### Updated articles + +- [WCF Web HTTP Programming Model Overview](../framework/wcf/feature-details/wcf-web-http-programming-model-overview.md) - Fix broken links ## .NET fundamentals +### New articles + +- [Reflection versus source generation in System.Text.Json](../standard/serialization/system-text-json/reflection-vs-source-generation.md) +- [Compile-time options validation source generation](../core/extensions/options-validation-generator.md) +- [How to read JSON as .NET objects (deserialize)](../standard/serialization/system-text-json/deserialization.md) +- [Include fields](../standard/serialization/system-text-json/fields.md) +- [Populate initialized properties](../standard/serialization/system-text-json/populate-properties.md) +- [Build resilient HTTP apps: Key development patterns](../core/resilience/http-resilience.md) +- [Introduction to resilient app development](../core/resilience/index.md) + ### Updated articles -- [What's new in .NET 8](../core/whats-new/dotnet-8.md) - Update What's new in .NET 8 for Preview 6 -- [Tutorial: Create a template package](../core/tutorials/cli-templates-create-template-package.md) - Update cli-templates-create-template-package.md +- [How to use source generation in System.Text.Json](../standard/serialization/system-text-json/source-generation.md) - Remaining STJ work for .NET 8 +- [Logging in C# and .NET](../core/extensions/logging.md) - Update logging docs +- [Dispose Pattern](../standard/design-guidelines/dispose-pattern.md) - Add note that material may be out of date +- [Tutorial: Create an item template](../core/tutorials/cli-templates-create-item-template.md) - Update template articles +- [Tutorial: Create a template package](../core/tutorials/cli-templates-create-template-package.md) - Update template articles + +## .NET security + +### Updated articles + +- [Cross-Platform Cryptography in .NET](../standard/security/cross-platform-cryptography.md) - Overhaul cross platform cryptography guide ## .NET tools and diagnostics ### New articles -- [CA1865-CA1867: Use 'string.Method(char)' instead of 'string.Method(string)' for string with single char](../fundamentals/code-analysis/quality-rules/ca1865-ca1867.md) -- [Null check can be simplified (IDE0029, IDE0030, and IDE0270)](../fundamentals/code-analysis/style-rules/ide0029-ide0030-ide0270.md) -- [CA1868: Unnecessary call to 'Contains' for sets](../fundamentals/code-analysis/quality-rules/ca1868.md) -- [Nullable directive is redundant (IDE0240)](../fundamentals/code-analysis/style-rules/ide0240.md) -- [Nullable directive is unnecessary (IDE0241)](../fundamentals/code-analysis/style-rules/ide0241.md) -- [Struct can be made 'readonly' (IDE0250)](../fundamentals/code-analysis/style-rules/ide0250.md) -- [Member can be made 'readonly' (IDE0251)](../fundamentals/code-analysis/style-rules/ide0251.md) -- [Convert to top-level statements (IDE0210)](../fundamentals/code-analysis/style-rules/ide0210.md) -- [Convert to 'Program.Main' style program (IDE0211)](../fundamentals/code-analysis/style-rules/ide0211.md) -- [Add explicit cast in foreach loop (IDE0220)](../fundamentals/code-analysis/style-rules/ide0220.md) -- [Use UTF-8 string literal (IDE0230)](../fundamentals/code-analysis/style-rules/ide0230.md) -- [Simplify LINQ expression (IDE0120)](../fundamentals/code-analysis/style-rules/ide0120.md) -- [Remove unnecessary lambda expression (IDE0200)](../fundamentals/code-analysis/style-rules/ide0200.md) -- [CA1864: Prefer the 'IDictionary.TryAdd(TKey, TValue)' method](../fundamentals/code-analysis/quality-rules/ca1864.md) -- [dotnet new details](../core/tools/dotnet-new-details.md) - -## Azure SDK for .NET +- [SYSLIB1034: JsonSourceGenerator encountered a [JsonStringEnumConverter] annotation](../fundamentals/syslib-diagnostics/syslib1034.md) +- [SYSLIB1039: JsonSourceGenerator encountered a `JsonDerivedTypeAttribute` annotation with `JsonSourceGenerationMode.Serialization` enabled](../fundamentals/syslib-diagnostics/syslib1039.md) +- [SYSLIB diagnostics for System.Text.Json source generation](../fundamentals/syslib-diagnostics/syslib1220-1229.md) +- [SYSLIB diagnostics for options validation source generation](../fundamentals/syslib-diagnostics/syslib1201-1219.md) +- [Exception summarization](../core/diagnostics/diagnostic-exception-summary.md) +- [.NET app health checks in C\#](../core/diagnostics/diagnostic-health-checks.md) +- [Resource monitoring](../core/diagnostics/diagnostic-resource-monitoring.md) +- [NETSDK1202: workload is out of support and will not receive security updates in the future](../core/tools/sdk-errors/netsdk1202.md) +- [SYSLIB0049](../fundamentals/syslib-diagnostics/syslib0049.md) +- [CA1514: Avoid redundant length argument](../fundamentals/code-analysis/quality-rules/ca1514.md) +- [ASP.NET Core Metrics](../core/diagnostics/built-in-metrics-aspnetcore.md) +- [System.Net Metrics](../core/diagnostics/built-in-metrics-system-net.md) +- [Built-in Metrics in .NET](../core/diagnostics/built-in-metrics.md) + +## Advanced .NET programming + +### Updated articles + +- [Best Practices for Implementing the Event-based Asynchronous Pattern](../standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md) - Replace `` with `*` + +## C# language ### New articles -- [Unit testing and mocking with the Azure SDK for .NET](../azure/sdk/unit-testing-mocking.md) +- [Errors and warnings associated with reference parameters, variables, and returns](../csharp/language-reference/compiler-messages/ref-modifiers-errors.md) +- [Compiler Error CS8795](../csharp/language-reference/compiler-messages/cs8795.md) +- [Compiler Error CS8817](../csharp/language-reference/compiler-messages/cs8817.md) ### Updated articles -- [Dependency injection with the Azure SDK for .NET](../azure/sdk/dependency-injection.md) - Update Azure SDK DI doc for additional app builders +- [Method Parameters](../csharp/language-reference/keywords/method-parameters.md) - Add coverage of the `ref readonly` modifier to the C# language reference. -## C# language +## DevOps and testing in .NET + +### New articles + +- [Cross-compilation](../core/deploying/native-aot/cross-compile.md) + +## F# language + +### Updated articles + +- [Query expressions](../fsharp/language-reference/query-expressions.md) - Bulk update html codeblock to markdown format + +## Microsoft Orleans ### New articles -- [Resolve errors and warnings with inline array declarations](../csharp/language-reference/compiler-messages/inline-array-errors.md) +- [Azure Cosmos DB for NoSQL grain persistence](../orleans/grains/grain-persistence/azure-cosmos-db.md) ### Updated articles -- [Common C# code conventions](../csharp/fundamentals/coding-style/coding-conventions.md) - Update coding guidelines -- [C# identifier naming rules and conventions](../csharp/fundamentals/coding-style/identifier-names.md) - Update coding guidelines +- [Deploy and scale an Orleans app on Azure](../orleans/quickstarts/deploy-scale-orleans-on-azure.md) - Orleans | Add Azure Cosmos DB to Orleans quickstart ## Community contributors The following people contributed to the .NET docs during this period. Thank you! Learn how to contribute by following the links under "Get involved" in the [what's new landing page](index.yml). -- [pkulikov](https://github.com/pkulikov) - Petr Kulikov ![7 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-7-green) -- [ErykKorzeniowski](https://github.com/ErykKorzeniowski) - ![5 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-5-green) -- imehdi7 - ![3 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-3-green) -- [smoothdeveloper](https://github.com/smoothdeveloper) - Gauthier Segay ![2 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-2-green) -- [aleksvujic](https://github.com/aleksvujic) - Aleks Vujić ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [andrewreeman](https://github.com/andrewreeman) - Andrew Reeman ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [Applesauce314](https://github.com/Applesauce314) - Andrew Moskevitz ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [BartoszKlonowski](https://github.com/BartoszKlonowski) - Bartosz Klonowski ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [CollinAlpert](https://github.com/CollinAlpert) - Collin Alpert ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [ericmutta](https://github.com/ericmutta) - Eric Mutta ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [frenzibyte](https://github.com/frenzibyte) - Salman Ahmed ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [jamesh1999](https://github.com/jamesh1999) - James Hogge ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [jjanuszkiewicz](https://github.com/jjanuszkiewicz) - Jakub Januszkiewicz ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [jwreford99](https://github.com/jwreford99) - Julian Wreford ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [lmorvan](https://github.com/lmorvan) - Loïc Morvan ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [MaxBQb](https://github.com/MaxBQb) - MaxBQb ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [Rageking8](https://github.com/Rageking8) - ![16 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-16-green) +- [BartoszKlonowski](https://github.com/BartoszKlonowski) - Bartosz Klonowski ![8 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-8-green) +- [JiuLing-zhang](https://github.com/JiuLing-zhang) - 九零 ![2 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-2-green) +- [alexravenna](https://github.com/alexravenna) - Alex Ravenna ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [AptiviCEO](https://github.com/AptiviCEO) - Aptivi CEO ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [ar1k](https://github.com/ar1k) - Aleksandr Ananin ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [Arclight3](https://github.com/Arclight3) - Iustin ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [BruceTheBrick](https://github.com/BruceTheBrick) - ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [david-acker](https://github.com/david-acker) - David Acker ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [dawedawe](https://github.com/dawedawe) - dawe ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [DreadedTuba](https://github.com/DreadedTuba) - ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [fincentxyz](https://github.com/fincentxyz) - fincent ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [gfoidl](https://github.com/gfoidl) - Günther Foidl ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [Happypig375](https://github.com/Happypig375) - Hadrian Tang ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [jgscherber](https://github.com/jgscherber) - Jacob Scherber ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [jjolidon](https://github.com/jjolidon) - ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [jmangel](https://github.com/jmangel) - ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [KUTlime](https://github.com/KUTlime) - Radek Zahradník ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [kyanha](https://github.com/kyanha) - Kyle H ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [mavaddat](https://github.com/mavaddat) - Mavaddat Javid ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) - [mpidash](https://github.com/mpidash) - Mario Pistrich ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [mrahhal](https://github.com/mrahhal) - Mohammad Rahhal ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [ousiax](https://github.com/ousiax) - John Hsu ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [Sljcom](https://github.com/Sljcom) - ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [softwaretirol](https://github.com/softwaretirol) - ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [Varorbc](https://github.com/Varorbc) - Varorbc ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [Youssef1313](https://github.com/Youssef1313) - Youssef Victor ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [zacharylayne](https://github.com/zacharylayne) - ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) -- [zzfima](https://github.com/zzfima) - Efim Zabarsky ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [nnpcYvIVl](https://github.com/nnpcYvIVl) - ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [owre](https://github.com/owre) - Pontus Öwre ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [postmeback](https://github.com/postmeback) - Arka Poddar ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [Raienryuu](https://github.com/Raienryuu) - Piotr ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [roboz0r](https://github.com/roboz0r) - ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [sa-es-ir](https://github.com/sa-es-ir) - Saeed Esmaeelinejad ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [Sergey-Vlasov](https://github.com/Sergey-Vlasov) - Sergey Vlasov ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [sliekens](https://github.com/sliekens) - Steven ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [smoothdeveloper](https://github.com/smoothdeveloper) - Gauthier Segay ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [stesmi](https://github.com/stesmi) - Stefan Smietanowski ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [sungam3r](https://github.com/sungam3r) - Ivan Maximov ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [SusheelThapa](https://github.com/SusheelThapa) - Susheel Thapa ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [Tchial0](https://github.com/Tchial0) - Chialo Armando ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [timdeschryver](https://github.com/timdeschryver) - Tim Deschryver ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [tmds](https://github.com/tmds) - Tom Deseyn ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [tokayy](https://github.com/tokayy) - ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) +- [tsemer](https://github.com/tsemer) - ![1 pull requests.](https://img.shields.io/badge/Merged%20Pull%20Requests-1-green) diff --git a/docs/whats-new/index.yml b/docs/whats-new/index.yml index c1767d2f7cd58..2cff1a024c69d 100644 --- a/docs/whats-new/index.yml +++ b/docs/whats-new/index.yml @@ -5,7 +5,7 @@ summary: Welcome to what's new in .NET docs. Use this page to quickly find the l metadata: title: .NET documentation what's new? description: Learn about new and updated content in .NET docs. - ms.date: 10/01/2023 + ms.date: 11/01/2023 ms.topic: landing-page landingContent: - title: .NET release updates @@ -18,12 +18,12 @@ landingContent: linkLists: - linkListType: whats-new links: + - text: October 2023 + url: dotnet-docs-mod1.md - text: September 2023 url: dotnet-docs-mod0.md - text: August 2023 url: dotnet-docs-mod2.md - - text: July 2023 - url: dotnet-docs-mod1.md - title: Find language updates linkLists: - linkListType: whats-new diff --git a/docs/whats-new/toc.yml b/docs/whats-new/toc.yml index 4a6c7ef4ba2d5..671f7eb309c9b 100644 --- a/docs/whats-new/toc.yml +++ b/docs/whats-new/toc.yml @@ -8,9 +8,9 @@ items: - name: Latest documentation updates expanded: true items: + - name: October 2023 + href: dotnet-docs-mod1.md - name: September 2023 href: dotnet-docs-mod0.md - name: August 2023 href: dotnet-docs-mod2.md - - name: July 2023 - href: dotnet-docs-mod1.md From 7c1bf155f13e383762a258a5329ee0af15eb4e23 Mon Sep 17 00:00:00 2001 From: Tim Sherer <28902327+TimShererWithAquent@users.noreply.github.com> Date: Thu, 2 Nov 2023 13:22:33 +0000 Subject: [PATCH 07/20] Add text per issue 26569. (#37850) --- docs/visual-basic/language-reference/nothing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/visual-basic/language-reference/nothing.md b/docs/visual-basic/language-reference/nothing.md index 550a15f6e62ca..0efc72e87e616 100644 --- a/docs/visual-basic/language-reference/nothing.md +++ b/docs/visual-basic/language-reference/nothing.md @@ -33,9 +33,9 @@ If a variable is of a reference type, assigning `Nothing` to the variable sets i [!code-vb[VbVbalrKeywords#8](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrKeywords/VB/class3.vb#8)] -When checking whether a reference (or nullable value type) variable is `null`, do not use `= Nothing` or `<> Nothing`. Always use `Is Nothing` or `IsNot Nothing`. +To check whether a reference (or nullable value type) variable is `null`, always use `Is Nothing` or `IsNot Nothing`. Don't use `= Nothing` or `<> Nothing`. -For strings in Visual Basic, the empty string equals `Nothing`. Therefore, `"" = Nothing` is true. +For strings in Visual Basic, the empty string equals `Nothing`. Therefore, `"" = Nothing` is true. This fact makes it especially important that you choose the correct comparison when you work with strings. Although `myString = Nothing` and `myString <> Nothing` indicate whether a non-empty value is set, we strongly recommend using `String.IsNullOrEmpty(myString)` for this purpose. Use `Is Nothing` and `IsNot Nothing` to determine whether any value, including an empty string, was set. The following example shows comparisons that use the `Is` and `IsNot` operators: From 7742b9e95e7975b2d2646924eeed5914497fac92 Mon Sep 17 00:00:00 2001 From: Tim Sherer <28902327+TimShererWithAquent@users.noreply.github.com> Date: Thu, 2 Nov 2023 13:23:18 +0000 Subject: [PATCH 08/20] Update summary description - issue 27060. (#37853) --- docs/csharp/language-reference/xmldoc/recommended-tags.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/csharp/language-reference/xmldoc/recommended-tags.md b/docs/csharp/language-reference/xmldoc/recommended-tags.md index 24a2f0a68a38b..d59cba967f163 100644 --- a/docs/csharp/language-reference/xmldoc/recommended-tags.md +++ b/docs/csharp/language-reference/xmldoc/recommended-tags.md @@ -164,7 +164,7 @@ If you want angle brackets to appear in the text of a documentation comment, use description ``` -The `` tag should be used to describe a type or a type member. Use [\](#remarks) to add supplemental information to a type description. Use the [cref attribute](#cref-attribute) to enable documentation tools such as [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) to create internal hyperlinks to documentation pages for code elements. The text for the `` tag is the only source of information about the type in IntelliSense, and is also displayed in the Object Browser window. +The `` tag should be used to describe a type or a type member. Use [\](#remarks) to add supplemental information to a type description. Use the [cref attribute](#cref-attribute) to enable documentation tools such as [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) to create internal hyperlinks to documentation pages for code elements. The text for the `` tag is a source of information about the type in IntelliSense, and is also displayed in the Object Browser window. ### \ @@ -174,7 +174,7 @@ description ``` -The `` tag is used to add information about a type or a type member, supplementing the information specified with [\](#summary). This information is displayed in the Object Browser window. This tag may include more lengthy explanations. You may find that using `CDATA` sections for markdown make writing it more convenient. Tools such as [docfx](https://dotnet.github.io/docfx/) process the markdown text in `CDATA` sections. +The `` tag is used to add information about a type or a type member, supplementing the information specified with [\](#summary). This information is displayed in the Object Browser window. The text for the `` tag is a source of information about the type in IntelliSense. This tag may include more lengthy explanations. You may find that using `CDATA` sections for markdown make writing it more convenient. Tools such as [docfx](https://dotnet.github.io/docfx/) process the markdown text in `CDATA` sections. ## Document members From 4d8692e9d48f4d8c689d98faf4b54b05e7131ac9 Mon Sep 17 00:00:00 2001 From: Theano Petersen <20667102+v-thepet@users.noreply.github.com> Date: Thu, 2 Nov 2023 06:26:33 -0700 Subject: [PATCH 09/20] Update formatting.md (#37860) --- docs/fsharp/style-guide/formatting.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/fsharp/style-guide/formatting.md b/docs/fsharp/style-guide/formatting.md index 425fbb4dddbd5..e1493d959fbcb 100644 --- a/docs/fsharp/style-guide/formatting.md +++ b/docs/fsharp/style-guide/formatting.md @@ -1,7 +1,7 @@ --- title: F# code formatting guidelines description: Learn guidelines for formatting F# code. -ms.date: 09/19/2021 +ms.date: 11/01/2023 --- # F# code formatting guidelines @@ -1300,6 +1300,14 @@ let comparer = { } ``` +Empty type definitions may be formatted on one line: + +```fsharp +type AnEmptyType = class end +``` + +Regardless of the chosen page width, `= class end` should always be on the same line. + ### Formatting index/slice expressions Index expressions shouldn't contain any spaces around the opening and closing brackets. From a05883d27092b2732b89c1d42e6fe3ddf113de92 Mon Sep 17 00:00:00 2001 From: Tim Deschryver <28659384+timdeschryver@users.noreply.github.com> Date: Thu, 2 Nov 2023 14:27:37 +0100 Subject: [PATCH 10/20] update string declarations using NRT (#37865) --- .../csharp/programming-guide/strings/snippets/Declarations.cs | 4 ++-- .../programming-guide/strings/snippets/StringCharacters.cs | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/csharp/programming-guide/strings/snippets/Declarations.cs b/docs/csharp/programming-guide/strings/snippets/Declarations.cs index 102d44f964909..eab9af09e3a1d 100644 --- a/docs/csharp/programming-guide/strings/snippets/Declarations.cs +++ b/docs/csharp/programming-guide/strings/snippets/Declarations.cs @@ -1,4 +1,4 @@ -namespace StringExamples; +namespace StringExamples; using System; @@ -11,7 +11,7 @@ public static void DeclareStrings() string message1; // Initialize to null. - string message2 = null; + string? message2 = null; // Initialize as an empty string. // Use the Empty constant instead of the literal "". diff --git a/docs/csharp/programming-guide/strings/snippets/StringCharacters.cs b/docs/csharp/programming-guide/strings/snippets/StringCharacters.cs index 36fca6283a458..6cf15fc5bc8b9 100644 --- a/docs/csharp/programming-guide/strings/snippets/StringCharacters.cs +++ b/docs/csharp/programming-guide/strings/snippets/StringCharacters.cs @@ -54,7 +54,7 @@ public static void BuildStrings() { // string str = "hello"; - string nullStr = null; + string? nullStr = null; string emptyStr = String.Empty; string tempStr = str + nullStr; From 4df60d18be23ef6c98fe0fad5c4952e021c46c14 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 2 Nov 2023 07:50:54 -0700 Subject: [PATCH 11/20] add article to toc (#37857) --- docs/navigate/devops-testing/toc.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/navigate/devops-testing/toc.yml b/docs/navigate/devops-testing/toc.yml index 8db9700aad0fb..43840734a60f7 100644 --- a/docs/navigate/devops-testing/toc.yml +++ b/docs/navigate/devops-testing/toc.yml @@ -333,6 +333,8 @@ items: href: ../../core/deploying/native-aot/diagnostics.md - name: Native code interop href: ../../core/deploying/native-aot/interop.md + - name: Cross-compilation + href: ../../core/deploying/native-aot/cross-compile.md - name: Intro to AOT warnings href: ../../core/deploying/native-aot/fixing-warnings.md - name: AOT warnings From f36ed2ddaafc13cbf7c8e979592d6101fc290b56 Mon Sep 17 00:00:00 2001 From: Azure SDK Bot <53356347+azure-sdk@users.noreply.github.com> Date: Thu, 2 Nov 2023 08:22:24 -0700 Subject: [PATCH 12/20] Update package index with latest published versions (#37872) --- docs/azure/includes/dotnet-all.md | 12 ++++++------ docs/azure/includes/dotnet-new.md | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index ea3bd0ca9d1c4..e435f95f44f87 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -128,7 +128,7 @@ | Resource Management - Bot Service | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.BotService/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.BotService/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.BotService-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.BotService_1.0.1/sdk/botservice/Azure.ResourceManager.BotService/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.BotService_1.1.0-beta.1/sdk/botservice/Azure.ResourceManager.BotService/) | | Resource Management - Change Analysis | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.ChangeAnalysis/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ChangeAnalysis/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ChangeAnalysis-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ChangeAnalysis_1.0.1/sdk/changeanalysis/Azure.ResourceManager.ChangeAnalysis/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ChangeAnalysis_1.1.0-beta.1/sdk/changeanalysis/Azure.ResourceManager.ChangeAnalysis/) | | Resource Management - Chaos | NuGet [1.0.0-beta.5](https://www.nuget.org/packages/Azure.ResourceManager.Chaos/1.0.0-beta.5) | [docs](/dotnet/api/overview/azure/ResourceManager.Chaos-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Chaos_1.0.0-beta.5/sdk/chaos/Azure.ResourceManager.Chaos/) | -| Resource Management - Cognitive Search | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Search-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.1.0/sdk/search/Azure.ResourceManager.Search/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.2.0-beta.1/sdk/search/Azure.ResourceManager.Search/) | +| Resource Management - Cognitive Search | NuGet [1.2.0](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.2.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Search-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.2.0/sdk/search/Azure.ResourceManager.Search/) | | Resource Management - Cognitive Services | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.CognitiveServices/1.3.0) | [docs](/dotnet/api/overview/azure/ResourceManager.CognitiveServices-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.CognitiveServices_1.3.0/sdk/cognitiveservices/Azure.ResourceManager.CognitiveServices/) | | Resource Management - Communication | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Communication/1.1.0)
NuGet [1.2.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.Communication/1.2.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Communication-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Communication_1.1.0/sdk/communication/Azure.ResourceManager.Communication/)
GitHub [1.2.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Communication_1.2.0-beta.2/sdk/communication/Azure.ResourceManager.Communication/) | | Resource Management - Compute | NuGet [1.2.0](https://www.nuget.org/packages/Azure.ResourceManager.Compute/1.2.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Compute-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute_1.2.0/sdk/compute/Azure.ResourceManager.Compute/) | @@ -256,7 +256,7 @@ | Resource Management - Service Fabric | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.ServiceFabric/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ServiceFabric/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ServiceFabric-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceFabric_1.0.1/sdk/servicefabric/Azure.ResourceManager.ServiceFabric/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceFabric_1.1.0-beta.1/sdk/servicefabric/Azure.ResourceManager.ServiceFabric/) | | Resource Management - Service Fabric Managed Clusters | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.ServiceFabricManagedClusters/1.0.1)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ServiceFabricManagedClusters/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.ServiceFabricManagedClusters-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceFabricManagedClusters_1.0.1/sdk/servicefabricmanagedclusters/Azure.ResourceManager.ServiceFabricManagedClusters/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceFabricManagedClusters_1.1.0-beta.2/sdk/servicefabricmanagedclusters/Azure.ResourceManager.ServiceFabricManagedClusters/) | | Resource Management - Service Linker | NuGet [1.0.2](https://www.nuget.org/packages/Azure.ResourceManager.ServiceLinker/1.0.2)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ServiceLinker/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ServiceLinker-readme) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceLinker_1.0.2/sdk/servicelinker/Azure.ResourceManager.ServiceLinker/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceLinker_1.1.0-beta.1/sdk/servicelinker/Azure.ResourceManager.ServiceLinker/) | -| Resource Management - Service Networking | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ServiceNetworking/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.ServiceNetworking-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceNetworking_1.0.0-beta.2/sdk/servicenetworking/Azure.ResourceManager.ServiceNetworking/) | +| Resource Management - Service Networking | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.ServiceNetworking/1.0.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ServiceNetworking-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceNetworking_1.0.0/sdk/servicenetworking/Azure.ResourceManager.ServiceNetworking/) | | Resource Management - SignalR | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.SignalR/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.SignalR/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.SignalR-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SignalR_1.0.1/sdk/signalr/Azure.ResourceManager.SignalR/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SignalR_1.1.0-beta.1/sdk/signalr/Azure.ResourceManager.SignalR/) | | Resource Management - Site Recovery | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.RecoveryServicesSiteRecovery/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.RecoveryServicesSiteRecovery-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.RecoveryServicesSiteRecovery_1.1.0/sdk/recoveryservices-siterecovery/Azure.ResourceManager.RecoveryServicesSiteRecovery/) | | Resource Management - Sphere | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Sphere/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Sphere-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sphere_1.0.0-beta.1/sdk/sphere/Azure.ResourceManager.Sphere/) | @@ -369,8 +369,8 @@ | Search - Common | NuGet [10.1.0](https://www.nuget.org/packages/Microsoft.Azure.Search.Common/10.1.0) | | GitHub [10.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Search.Common_10.1.0/sdk/search/Microsoft.Azure.Search.Common/) | | Search - Data | NuGet [10.1.0](https://www.nuget.org/packages/Microsoft.Azure.Search.Data/10.1.0) | | GitHub [10.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Search.Data_10.1.0/sdk/search/Microsoft.Azure.Search.Data/) | | Search - Service | NuGet [10.1.0](https://www.nuget.org/packages/Microsoft.Azure.Search.Service/10.1.0) | | GitHub [10.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Search.Service_10.1.0/sdk/search/Microsoft.Azure.Search.Service/) | -| Speech | NuGet [1.32.1](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech/1.32.1) | | | -| Speech Remote Conversation | NuGet [1.32.1](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech.Remoteconversation/1.32.1) | | | +| Speech | NuGet [1.33.0](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech/1.33.0) | | | +| Speech Remote Conversation | NuGet [1.33.0](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech.Remoteconversation/1.33.0) | | | | Speech Xamarin iOS | NuGet [1.25.0](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech.Xamarin.iOS/1.25.0) | | | | Spell Check | NuGet [4.1.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Language.SpellCheck/4.1.0-preview.1) | | GitHub [4.1.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Language.SpellCheck_4.1.0-preview.1/sdk/cognitiveservices/Language.SpellCheck) | | Spring Cloud Client | NuGet [2.0.0-preview.3](https://www.nuget.org/packages/Microsoft.Azure.SpringCloud.Client/2.0.0-preview.3) | | | @@ -395,14 +395,14 @@ | Cosmos DB - Direct | NuGet [3.31.5](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Direct/3.31.5) | | GitHub [3.31.5](https://github.com/Azure/azure-cosmos-dotnet-v3) | | Cosmos DB - Encryption | NuGet [2.0.3](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Encryption/2.0.3) | | GitHub [2.0.3](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/releases/encryption/1.0.0-preview4/Microsoft.Azure.Cosmos.Encryption) | | Cosmos DB - Encryption | NuGet [1.0.0-preview06](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Encryption.Custom/1.0.0-preview06) | | | -| Extensions - Caching Cosmos | NuGet [1.5.0](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Cosmos/1.5.0) | | GitHub [1.5.0](https://github.com/Azure/Microsoft.Extensions.Caching.Cosmos/tree/v1.0.0-preview4) | +| Extensions - Caching Cosmos | NuGet [1.6.0](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Cosmos/1.6.0) | | GitHub [1.6.0](https://github.com/Azure/Microsoft.Extensions.Caching.Cosmos/tree/v1.0.0-preview4) | | Functions - Extensions | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Extensions/1.1.0) | | GitHub [1.1.0](https://github.com/Azure/azure-functions-dotnet-extensions) | | Functions extension for Application Insights | NuGet [1.0.0-preview4](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.ApplicationInsights/1.0.0-preview4) | | | | Functions extension for Authentication Events | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/1.0.0-beta.3) | | | | Functions extension for Azure Mobile Apps | NuGet [3.0.0-beta8](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.MobileApps/3.0.0-beta8) | | GitHub [3.0.0-beta8](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/v3.0.0-beta8/src/WebJobs.Extensions.MobileApps) | | Functions extension for Azure SQL and SQL Server | NuGet [3.0.461](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Sql/3.0.461) | | | | Functions extension for Blob Storage | NuGet [5.2.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs/5.2.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs-readme) | | -| Functions extension for Cosmos DB | NuGet [4.4.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.CosmosDB/4.4.0) | | GitHub [4.4.0](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/cosmos-v3.0.7/src/WebJobs.Extensions.CosmosDB) | +| Functions extension for Cosmos DB | NuGet [4.4.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.CosmosDB/4.4.1) | | GitHub [4.4.1](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/cosmos-v3.0.7/src/WebJobs.Extensions.CosmosDB) | | Functions extension for DocumentDB | NuGet [1.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.DocumentDB/1.3.0) | | GitHub [1.3.0](https://github.com/Azure/azure-webjobs-sdk-extensions) | | Functions extension for Durable Task Framework | NuGet [2.12.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.DurableTask/2.12.0)
NuGet [2.13.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.DurableTask/2.13.0-preview.1) | [docs](https://learn.microsoft.com/dotnet/api/overview/azure/functions) | GitHub [2.12.0](https://github.com/Azure/azure-functions-durable-extension/tree/v2.2.2/src/WebJobs.Extensions.DurableTask) | | Functions extension for Durable Task Framework - isolated worker | NuGet [1.0.4](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.DurableTask/1.0.4)
NuGet [1.1.0-preview.2](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.DurableTask/1.1.0-preview.2) | | | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index bc0b072537c12..6e45dff616aef 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -130,7 +130,7 @@ | Resource Management - Bot Service | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.BotService/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.BotService/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.BotService-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.BotService_1.0.1/sdk/botservice/Azure.ResourceManager.BotService/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.BotService_1.1.0-beta.1/sdk/botservice/Azure.ResourceManager.BotService/) | | Resource Management - Change Analysis | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.ChangeAnalysis/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ChangeAnalysis/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ChangeAnalysis-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ChangeAnalysis_1.0.1/sdk/changeanalysis/Azure.ResourceManager.ChangeAnalysis/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ChangeAnalysis_1.1.0-beta.1/sdk/changeanalysis/Azure.ResourceManager.ChangeAnalysis/) | | Resource Management - Chaos | NuGet [1.0.0-beta.5](https://www.nuget.org/packages/Azure.ResourceManager.Chaos/1.0.0-beta.5) | [docs](/dotnet/api/overview/azure/ResourceManager.Chaos-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Chaos_1.0.0-beta.5/sdk/chaos/Azure.ResourceManager.Chaos/) | -| Resource Management - Cognitive Search | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Search-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.1.0/sdk/search/Azure.ResourceManager.Search/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.2.0-beta.1/sdk/search/Azure.ResourceManager.Search/) | +| Resource Management - Cognitive Search | NuGet [1.2.0](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.2.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Search-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.2.0/sdk/search/Azure.ResourceManager.Search/) | | Resource Management - Cognitive Services | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.CognitiveServices/1.3.0) | [docs](/dotnet/api/overview/azure/ResourceManager.CognitiveServices-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.CognitiveServices_1.3.0/sdk/cognitiveservices/Azure.ResourceManager.CognitiveServices/) | | Resource Management - Communication | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Communication/1.1.0)
NuGet [1.2.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.Communication/1.2.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Communication-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Communication_1.1.0/sdk/communication/Azure.ResourceManager.Communication/)
GitHub [1.2.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Communication_1.2.0-beta.2/sdk/communication/Azure.ResourceManager.Communication/) | | Resource Management - Compute | NuGet [1.2.0](https://www.nuget.org/packages/Azure.ResourceManager.Compute/1.2.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Compute-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute_1.2.0/sdk/compute/Azure.ResourceManager.Compute/) | @@ -259,7 +259,7 @@ | Resource Management - Service Fabric | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.ServiceFabric/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ServiceFabric/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ServiceFabric-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceFabric_1.0.1/sdk/servicefabric/Azure.ResourceManager.ServiceFabric/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceFabric_1.1.0-beta.1/sdk/servicefabric/Azure.ResourceManager.ServiceFabric/) | | Resource Management - Service Fabric Managed Clusters | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.ServiceFabricManagedClusters/1.0.1)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ServiceFabricManagedClusters/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.ServiceFabricManagedClusters-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceFabricManagedClusters_1.0.1/sdk/servicefabricmanagedclusters/Azure.ResourceManager.ServiceFabricManagedClusters/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceFabricManagedClusters_1.1.0-beta.2/sdk/servicefabricmanagedclusters/Azure.ResourceManager.ServiceFabricManagedClusters/) | | Resource Management - Service Linker | NuGet [1.0.2](https://www.nuget.org/packages/Azure.ResourceManager.ServiceLinker/1.0.2)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ServiceLinker/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ServiceLinker-readme) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceLinker_1.0.2/sdk/servicelinker/Azure.ResourceManager.ServiceLinker/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceLinker_1.1.0-beta.1/sdk/servicelinker/Azure.ResourceManager.ServiceLinker/) | -| Resource Management - Service Networking | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ServiceNetworking/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.ServiceNetworking-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceNetworking_1.0.0-beta.2/sdk/servicenetworking/Azure.ResourceManager.ServiceNetworking/) | +| Resource Management - Service Networking | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.ServiceNetworking/1.0.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ServiceNetworking-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ServiceNetworking_1.0.0/sdk/servicenetworking/Azure.ResourceManager.ServiceNetworking/) | | Resource Management - SignalR | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.SignalR/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.SignalR/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.SignalR-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SignalR_1.0.1/sdk/signalr/Azure.ResourceManager.SignalR/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SignalR_1.1.0-beta.1/sdk/signalr/Azure.ResourceManager.SignalR/) | | Resource Management - Site Recovery | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.RecoveryServicesSiteRecovery/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.RecoveryServicesSiteRecovery-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.RecoveryServicesSiteRecovery_1.1.0/sdk/recoveryservices-siterecovery/Azure.ResourceManager.RecoveryServicesSiteRecovery/) | | Resource Management - Sphere | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Sphere/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Sphere-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sphere_1.0.0-beta.1/sdk/sphere/Azure.ResourceManager.Sphere/) | From bd47affc00c598aeeb062e614bdcf1d396f085e3 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Thu, 2 Nov 2023 15:50:40 -0400 Subject: [PATCH 13/20] Add latest errors codes (#37855) * Add latest errors codes Several diagnostics have been added for the C# 12 features since their initial release. Add them. Fixes #37737 * fix warnings * cross reference to remove duplicates Fix warnings, make sure all C# 12 errors go somewhere. * final edits Add other undocumented errors for data tracking. Make error formatting consistent. * build warning * build warning --- .../array-declaration-errors.md | 149 +++++--- .../compiler-messages/constructor-errors.md | 177 +++++----- .../feature-version-errors.md | 73 ++-- .../compiler-messages/inline-array-errors.md | 74 +++- .../lambda-expression-errors.md | 50 ++- .../pattern-matching-warnings.md | 34 +- .../compiler-messages/ref-modifiers-errors.md | 325 +++++++++--------- .../source-generator-errors.md | 35 +- .../compiler-messages/toc.yml | 26 +- .../using-directive-errors.md | 55 +-- ...n-t-have-specifics-on-this-csharp-error.md | 61 ++++ 11 files changed, 639 insertions(+), 420 deletions(-) diff --git a/docs/csharp/language-reference/compiler-messages/array-declaration-errors.md b/docs/csharp/language-reference/compiler-messages/array-declaration-errors.md index 5660de29e92e9..fe439f9db24dd 100644 --- a/docs/csharp/language-reference/compiler-messages/array-declaration-errors.md +++ b/docs/csharp/language-reference/compiler-messages/array-declaration-errors.md @@ -25,6 +25,14 @@ f1_keywords: - "CS3016" - "CS9174" - "CS9176" + - "CS9185" + - "CS9186" + - "CS9187" + - "CS9188" + - "CS9203" + - "CS9208" + - "CS9209" + - "CS9210" helpviewer_keywords: - "CS0022" - "CS0178" @@ -49,7 +57,15 @@ helpviewer_keywords: - "CS3016" - "CS9174" - "CS9176" -ms.date: 08/29/2023 + - "CS9185" + - "CS9186" + - "CS9187" + - "CS9188" + - "CS9203" + - "CS9208" + - "CS9209" + - "CS9210" +ms.date: 11/02/2023 --- # Resolve errors and warnings in array and collection declarations and initialization expressions @@ -58,32 +74,40 @@ This article covers the following compiler errors: -- [**CS0022**](#invalid-array-element-access) - *Wrong number of indices inside [], expected 'number'* -- [**CS0178**](#invalid-array-rank) - *Invalid rank specifier: expected '`,`' or '`]`'* -- [**CS0248**](#invalid-array-length) - *Cannot create an array with a negative size* -- [**CS0270**](#invalid-array-length) - *Array size cannot be specified in a variable declaration (try initializing with a '`new`' expression)* -- [**CS0611**](#invalid-element-type) - *Array elements cannot be of type* -- [**CS0623**](#invalid-array-initializer) - *Array initializers can only be used in a variable or field initializer. Try using a new expression instead.* -- [**CS0650**](#invalid-array-rank) - *Bad array declarator: To declare a managed array the rank specifier precedes the variable's identifier. To declare a fixed size buffer field, use the fixed keyword before the field type.* -- [**CS0719**](#invalid-element-type) - *Array elements cannot be of static type* -- [**CS0747**](#invalid-collection-initializer) - *Invalid initializer member declarator.* -- [**CS0820**](#invalid-element-type) - *Cannot assign array initializer to an implicitly typed local* -- [**CS0826**](#invalid-element-type) - *No best type found for implicitly typed array.* -- [**CS0846**](#invalid-array-initializer) - *A nested array initializer is expected* -- [**CS1552**](#invalid-array-rank) - *Array type specifier, `[]`, must appear before parameter name* -- [**CS1586**](#invalid-array-length) - *Array creation must have array size or array initializer* -- [**CS1920**](#invalid-collection-initializer) - *Element initializer cannot be empty.* -- [**CS1921**](#invalid-collection-initializer) - *The best overloaded method match has wrong signature for the initializer element. The initializable `Add` must be an accessible instance method.* -- [**CS1925**](#invalid-array-initializer) - *Cannot initialize object of type 'type' with a collection initializer.* -- [**CS1954**](#invalid-collection-initializer) - *The best overloaded method match for the collection initializer element cannot be used. Collection initializer '`Add`' methods cannot have `ref` or `out` parameters.* -- [**CS9174**](#invalid-collection-initializer) - *Cannot initialize type with a collection literal because the type is not constructible.* -- [**CS9176**](#invalid-collection-initializer) - *There is no target type for the collection literal.* +- [**CS0022**](#invalid-array-element-access): *Wrong number of indices inside [], expected 'number'* +- [**CS0178**](#invalid-array-rank): *Invalid rank specifier: expected '`,`' or '`]`'* +- [**CS0248**](#invalid-array-length): *Cannot create an array with a negative size* +- [**CS0270**](#invalid-array-length): *Array size cannot be specified in a variable declaration (try initializing with a '`new`' expression)* +- [**CS0611**](#invalid-element-type): *Array elements cannot be of type* +- [**CS0623**](#invalid-array-initializer): *Array initializers can only be used in a variable or field initializer. Try using a new expression instead.* +- [**CS0650**](#invalid-array-rank): *Bad array declarator: To declare a managed array the rank specifier precedes the variable's identifier. To declare a fixed size buffer field, use the fixed keyword before the field type.* +- [**CS0719**](#invalid-element-type): *Array elements cannot be of static type* +- [**CS0747**](#invalid-collection-initializer): *Invalid initializer member declarator.* +- [**CS0820**](#invalid-element-type): *Cannot assign array initializer to an implicitly typed local* +- [**CS0826**](#invalid-element-type): *No best type found for implicitly typed array.* +- [**CS0846**](#invalid-array-initializer): *A nested array initializer is expected* +- [**CS1552**](#invalid-array-rank): *Array type specifier, `[]`, must appear before parameter name* +- [**CS1586**](#invalid-array-length): *Array creation must have array size or array initializer* +- [**CS1920**](#invalid-collection-initializer): *Element initializer cannot be empty.* +- [**CS1921**](#invalid-collection-initializer): *The best overloaded method match has wrong signature for the initializer element. The initializable `Add` must be an accessible instance method.* +- [**CS1925**](#invalid-array-initializer): *Cannot initialize object of type 'type' with a collection initializer.* +- [**CS1954**](#invalid-collection-initializer): *The best overloaded method match for the collection initializer element cannot be used. Collection initializer '`Add`' methods cannot have `ref` or `out` parameters.* +- [**CS9174**](#invalid-collection-initializer): *Cannot initialize type with a collection literal because the type is not constructible.* +- [**CS9176**](#invalid-collection-initializer): *There is no target type for the collection literal.* +- [**CS9185**](#invalid-collection-builder): *The CollectionBuilderAttribute builder type must be a non-generic class or struct.* +- [**CS9186**](#invalid-collection-builder): *The CollectionBuilderAttribute method name is invalid.* +- [**CS9187**](#invalid-collection-builder): *Could not find an accessible method with the expected signature: a static method with a single parameter of type `ReadOnlySpan`; and correct return type* +- [**CS9188**](#invalid-collection-builder): *Type has a CollectionBuilderAttribute but no element type.* +- [**CS9203**](#invalid-collection-initializer): *A collection expression of this type cannot be used in this context because it may be exposed outside of the current scope.* +- [**CS9210**](#invalid-collection-initializer): *This version of cannot be used with collection expressions.* In addition, the following warnings are covered in this article: -- [**CS3007**](#common-language-specification-warnings) - *Overloaded method 'method' differing only by unnamed array types is not CLS-compliant* -- [**CS3016**](#common-language-specification-warnings) - *Arrays as attribute arguments is not CLS-compliant* -- [**CS0251**](#invalid-array-element-access) - *Indexing an array with a negative index (array indices always start at zero)* +- [**CS3007**](#common-language-specification-warnings): *Overloaded method 'method' differing only by unnamed array types is not CLS-compliant* +- [**CS3016**](#common-language-specification-warnings): *Arrays as attribute arguments is not CLS-compliant* +- [**CS0251**](#invalid-array-element-access): *Indexing an array with a negative index (array indices always start at zero)* +- [**CS9208**](#invalid-collection-initializer): *Collection expression may incur unexpected heap allocations. Consider explicitly creating an array, then converting to the final type to make the allocation explicit.* +- [**CS9209**](#invalid-collection-initializer): *Collection expression may incur unexpected heap allocations due to use of '`..`' spreads. Consider explicitly creating an array, then converting to the final type to make the allocation explicit.* You can learn more about arrays, collection initializers and collection expressions in the following articles: @@ -93,33 +117,46 @@ You can learn more about arrays, collection initializers and collection expressi ## Invalid collection initializer -- **CS0747** - *Invalid initializer member declarator.* -- **CS1920** - *Element initializer cannot be empty.* -- **CS1921** - *The best overloaded method match has wrong signature for the initializer element. The initializable `Add` must be an accessible instance method.* -- **CS1954** - *The best overloaded method match for the collection initializer element cannot be used. Collection initializer '`Add`' methods cannot have `ref` or `out` parameters.* -- **CS9174** - *Cannot initialize type with a collection literal because the type is not constructible.* -- **CS9176** - *There is no target type for the collection literal.* +The following errors indicate that the code generated by the compiler for a collection initializer is invalid: -These errors all indicate that the code generated by the compiler for a collection initializer is invalid. Check the following: +- **CS0747**: *Invalid initializer member declarator.* +- **CS1920**: *Element initializer cannot be empty.* +- **CS1921**: *The best overloaded method match has wrong signature for the initializer element. The initializable `Add` must be an accessible instance method.* +- **CS1954**: *The best overloaded method match for the collection initializer element cannot be used. Collection initializer '`Add`' methods cannot have `ref` or `out` parameters.* +- **CS9174**: *Cannot initialize type with a collection literal because the type is not constructible.* +- **CS9176**: *There is no target type for the collection literal.* +- **CS9203**: *A collection expression of this type cannot be used in this context because it may be exposed outside of the current scope.* +- **CS9210**: *This version of cannot be used with collection expressions.* + +The compiler might also generate the following warning: + +- **CS9208**: *Collection expression may incur unexpected heap allocations. Consider explicitly creating an array, then converting to the final type to make the allocation explicit.* +- **CS9209**: *Collection expression may incur unexpected heap allocations due to use of '`..`' spreads. Consider explicitly creating an array, then converting to the final type to make the allocation explicit.* + +The errors all indicate that the code generated by the compiler for a collection initializer is invalid. Check the following: - A collection initializer contains a sequence of elements. You can't mix setting properties on the collection instance with adding elements in the same initializer. - A collection initializer that includes braces (`{` and `}`) can't be empty. - A conforming `Add` method must be accessible and take one parameter that is the same type as the collection elements. The parameter can't include the `ref` or `out` modifier. - Overload resolution must pick one `Add` method as a better match. There can't be multiple matching methods that are equally good. - Collection expressions can initialize explicitly typed variables of a collection type. If the variable isn't a collection or array type, or is implicitly typed (using `var`), a collection initializer can't be used. +- A `ref struct` type, like can't be initialized with a collection expression that may violate ref safety. +- A collection expression can't correctly initialize an using the current version. Use a different version of the runtime, or change the initialization expression. + +The warnings indicates that the collection expression, including any [spread elements](../operators/collection-expressions.md#spread-element) might allocate memory. Creating different storage and converting might be more efficient. ## Invalid array initializer -- **CS0623** - *Array initializers can only be used in a variable or field initializer. Try using a new expression instead.* -- **CS0846** - *A nested array initializer is expected* -- **CS1925** - *Cannot initialize object of type 'type' with a collection initializer.* +- **CS0623**: *Array initializers can only be used in a variable or field initializer. Try using a new expression instead.* +- **CS0846**: *A nested array initializer is expected* +- **CS1925**: *Cannot initialize object of type 'type' with a collection initializer.* These errors indicate that you've created an invalid initializer. The likely cause is unbalanced braces `{` and `}` around one or more elements or child arrays. Ensure that the initializing expression matches the number of arrays in a jagged array initialization, and that the braces are balanced. ## Invalid array element access -- **CS0022** - *Wrong number of indices inside [], expected 'number'* -- **CS0251** - *Indexing an array with a negative index (array indices always start at zero)* +- **CS0022**: *Wrong number of indices inside [], expected 'number'* +- **CS0251**: *Indexing an array with a negative index (array indices always start at zero)* You access an element of an array by specifying the index for each axis declared in the array. The indices are between `[` and `]` after the array name. There are two rules for the array indices: @@ -128,9 +165,9 @@ You access an element of an array by specifying the index for each axis declared ## Invalid array rank -- **CS0178** - *Invalid rank specifier: expected '`,`' or '`]`'* -- **CS0650** - *Bad array declarator: To declare a managed array the rank specifier precedes the variable's identifier. To declare a fixed size buffer field, use the fixed keyword before the field type.* -- **CS1552** - *Array type specifier, `[]`, must appear before parameter name* +- **CS0178**: *Invalid rank specifier: expected '`,`' or '`]`'* +- **CS0650**: *Bad array declarator: To declare a managed array the rank specifier precedes the variable's identifier. To declare a fixed size buffer field, use the fixed keyword before the field type.* +- **CS1552**: *Array type specifier, `[]`, must appear before parameter name* An array declaration consists of the following tokens, in order: @@ -152,9 +189,9 @@ For more information, see the C# specification ([C# Language Specification](~/_c ## Invalid array length -- **CS0248** - *Cannot create an array with a negative size* -- **CS0270** - *Array size cannot be specified in a variable declaration (try initializing with a 'new' expression* -- **CS1586** - *Array creation must have array size or array initializer* +- **CS0248**: *Cannot create an array with a negative size* +- **CS0270**: *Array size cannot be specified in a variable declaration (try initializing with a 'new' expression* +- **CS1586**: *Array creation must have array size or array initializer* The length of each dimension of an array must be specified as part of the array initialization, not its declaration. The length of each dimension must be positive. You can specify the length either by using a `new` expression to allocate the array, or using an array initializer to assign all the elements. The following example shows both mechanisms: @@ -162,10 +199,10 @@ The length of each dimension of an array must be specified as part of the array ## Invalid element type -- **CS0611** - *Array elements cannot be of type 'type'* -- **CS0719** - *Array elements cannot be of static type* -- **CS0820** - *Cannot assign array initializer to an implicitly typed local* -- **CS0826** - *No best type found for implicitly typed array.* +- **CS0611**: *Array elements cannot be of type 'type'* +- **CS0719**: *Array elements cannot be of static type* +- **CS0820**: *Cannot assign array initializer to an implicitly typed local* +- **CS0826**: *No best type found for implicitly typed array.* There are some types that cannot be used as the type of an array. These types include and . The type of an array can't be a `static` class, because instances of a `static` class can't be created. @@ -179,10 +216,26 @@ You can ensure the best common type using any of the following techniques: - Give all array elements the same type. - Provide explicit casts on those elements that might be causing the problem. +## Invalid collection builder + +The following errors indicate errors in your collection builder type: + +- **CS9185**: *The `CollectionBuilderAttribute` builder type must be a non-generic class or struct.* +- **CS9186**: *The `CollectionBuilderAttribute` method name is invalid.* +- **CS9187**: *Could not find an accessible method with the expected signature: a static method with a single parameter of type `ReadOnlySpan`; and correct return type.* +- **CS9188**: *Type has a `CollectionBuilderAttribute` but no element type.* + +These errors indicate that your collection builder type needs modification. Remember the following rules: + +- The collection type must have an iteration type. In other words, you can [`foreach`](~/_csharpstandard/standard/statements.md#1395-the-foreach-statement) the type as a collection. +- The collection builder type can't be a generic type. +- The method name specified on the must be a valid method name. For example, it can't be finalizer, or other name that contains invalid identifier characters. +- The collection builder method must be an accessible static method. It must return the collection type, and it must take a parameter of `ReadOnlySpan` where `T` matches the element type of the collection. + ## Common language specification warnings -- **CS3007** - *Overloaded method 'method' differing only by unnamed array types is not CLS-compliant* -- **CS3016** - *Arrays as attribute arguments is not CLS-compliant* +- **CS3007**: *Overloaded method 'method' differing only by unnamed array types is not CLS-compliant* +- **CS3016**: *Arrays as attribute arguments is not CLS-compliant* CS3007 occurs if you have an overloaded method that takes a jagged array and the only difference between the method signatures is the element type of the array. To avoid this error, consider using a rectangular array rather than a jagged array or, if CLS Compliance isn't needed, remove the attribute. For more information on CLS Compliance, see [Language independence and language-independent components](../../../standard/language-independence.md). diff --git a/docs/csharp/language-reference/compiler-messages/constructor-errors.md b/docs/csharp/language-reference/compiler-messages/constructor-errors.md index 2753cf762b61e..e7c75402d3f9e 100644 --- a/docs/csharp/language-reference/compiler-messages/constructor-errors.md +++ b/docs/csharp/language-reference/compiler-messages/constructor-errors.md @@ -41,6 +41,9 @@ f1_keywords: - "CS9120" # ERR_RefReturnPrimaryConstructorParameter - Cannot return primary constructor parameter '{0}' by reference. - "CS9121" # ERR_StructLayoutCyclePrimaryConstructorParameter - Struct primary constructor parameter '{0}' of type '{1}' causes a cycle in the struct layout - "CS9122" # ERR_UnexpectedParameterList - Unexpected parameter list. Test: Interfaces can't have primary constructors. + - "CS9124" + - "CS9136" + - "CS9179" helpviewer_keywords: - "CS0514" - "CS0515" @@ -81,7 +84,10 @@ helpviewer_keywords: - "CS9120" - "CS9121" - "CS9122" -ms.date: 05/08/2023 + - "CS9124" + - "CS9136" + - "CS9179" +ms.date: 11/02/2023 --- # Resolve errors and warnings in constructor declarations @@ -90,54 +96,57 @@ This article covers the following compiler errors: -- [**CS0514**](#static-constructors) - *static constructor cannot have an explicit 'this' or 'base' constructor call.* -- [**CS0515**](#static-constructors) - *access modifiers are not allowed on static constructors.* -- [**CS0516**](#constructor-calls-with-base-and-this) - *Constructor 'constructor' can not call itself.* -- [**CS0517**](#constructor-declarations) - *'class' has no base class and cannot call a base constructor.* -- [**CS0522**](#constructor-calls-with-base-and-this) - *structs cannot call base class constructors.* -- [**CS0526**](#constructor-declarations) - *Interfaces cannot contain constructors.* -- [**CS0568**](#constructors-in-struct-types) - *Structs cannot contain explicit parameterless constructors.* -- [**CS0710**](#constructor-declarations) - *Static classes cannot have instance constructors.* -- [**CS0768**](#constructor-calls-with-base-and-this) - *Constructor cannot call itself through another constructor.* -- [**CS8054**](#constructor-declarations) - *Enums cannot contain explicit parameterless constructors.* -- [**CS8091**](#constructor-declarations) - *cannot be extern and have a constructor initializer.* -- [**CS8862**](#primary-constructor-syntax) - *A constructor declared in a type with parameter list must have 'this' constructor initializer.* -- [**CS8358**](#constructor-declarations) - *Cannot use attribute constructor because it has 'in' parameters.* -- [**CS8867**](#records-and-copy-constructors) - *No accessible copy constructor found in base type '{0}'.* -- [**CS8868**](#records-and-copy-constructors) - *A copy constructor in a record must call a copy constructor of the base, or a parameterless object constructor if the record inherits from object.* -- [**CS8878**](#records-and-copy-constructors) - *A copy constructor '{0}' must be public or protected because the record is not sealed.* -- [**CS8910**](#records-and-copy-constructors) - *The primary constructor conflicts with the synthesized copy constructor.* -- [**CS8958**](#constructors-in-struct-types) - *The parameterless struct constructor must be 'public'.* -- [**CS8982**](#constructors-in-struct-types) - *A constructor declared in a 'struct' with parameter list must have a 'this' initializer that calls the primary constructor or an explicitly declared constructor.* -- [**CS8983**](#constructors-in-struct-types) - *A 'struct' with field initializers must include an explicitly declared constructor.* -- [**CS9105**](#primary-constructor-syntax) - *Cannot use primary constructor parameter in this context.* -- [**CS9106**](#primary-constructor-syntax) - *Identifier is ambiguous between type and parameter in this context.* +- [**CS0514**](#static-constructors): *static constructor cannot have an explicit 'this' or 'base' constructor call.* +- [**CS0515**](#static-constructors): *access modifiers are not allowed on static constructors.* +- [**CS0516**](#constructor-calls-with-base-and-this): *Constructor 'constructor' can not call itself.* +- [**CS0517**](#constructor-declaration): *'class' has no base class and cannot call a base constructor.* +- [**CS0522**](#constructor-calls-with-base-and-this): *structs cannot call base class constructors.* +- [**CS0526**](#constructor-declaration): *Interfaces cannot contain constructors.* +- [**CS0568**](#constructors-in-struct-types): *Structs cannot contain explicit parameterless constructors.* +- [**CS0710**](#constructor-declaration): *Static classes cannot have instance constructors.* +- [**CS0768**](#constructor-calls-with-base-and-this): *Constructor cannot call itself through another constructor.* +- [**CS8054**](#constructor-declaration): *Enums cannot contain explicit parameterless constructors.* +- [**CS8091**](#constructor-declaration): *cannot be extern and have a constructor initializer.* +- [**CS8862**](#primary-constructor-declaration): *A constructor declared in a type with parameter list must have 'this' constructor initializer.* +- [**CS8358**](#constructor-declaration): *Cannot use attribute constructor because it has 'in' parameters.* +- [**CS8867**](#records-and-copy-constructors): *No accessible copy constructor found in base type '{0}'.* +- [**CS8868**](#records-and-copy-constructors): *A copy constructor in a record must call a copy constructor of the base, or a parameterless object constructor if the record inherits from object.* +- [**CS8878**](#records-and-copy-constructors): *A copy constructor '{0}' must be public or protected because the record is not sealed.* +- [**CS8910**](#records-and-copy-constructors): *The primary constructor conflicts with the synthesized copy constructor.* +- [**CS8958**](#constructors-in-struct-types): *The parameterless struct constructor must be 'public'.* +- [**CS8982**](#constructors-in-struct-types): *A constructor declared in a 'struct' with parameter list must have a 'this' initializer that calls the primary constructor or an explicitly declared constructor.* +- [**CS8983**](#constructors-in-struct-types): *A 'struct' with field initializers must include an explicitly declared constructor.* +- [**CS9105**](#primary-constructor-declaration): *Cannot use primary constructor parameter in this context.* +- [**CS9106**](#primary-constructor-declaration): *Identifier is ambiguous between type and parameter in this context.* class as well.* -- [**CS9108**](#primary-constructor-syntax) - *Cannot use parameter that has ref-like type inside an anonymous method, lambda expression, query expression, or local function.* -- [**CS9109**](#primary-constructor-syntax) - *Cannot use `ref`, `out`, or `in` primary constructor parameter inside an instance member.* -- [**CS9110**](#primary-constructor-syntax) - *Cannot use primary constructor parameter that has ref-like type inside an instance member.* -- [**CS9111**](#primary-constructor-syntax) - *Anonymous methods, lambda expressions, query expressions, and local functions inside an instance member of a struct cannot access primary constructor parameter.* -- [**CS9112**](#primary-constructor-syntax) - *Anonymous methods, lambda expressions, query expressions, and local functions inside a struct cannot access primary constructor parameter also used inside an instance member.* -- [**CS9114**](#primary-constructor-syntax) - *A primary constructor parameter of a readonly type cannot be assigned to (except in init-only setter of the type or a variable initializer).* -- [**CS9115**](#primary-constructor-syntax) - *A primary constructor parameter of a readonly type cannot be returned by writable reference.* -- [**CS9116**](#primary-constructor-syntax) - *A primary constructor parameter of a readonly type cannot be used as a ref or out value (except in init-only setter of the type or a variable initializer).* -- [**CS9117**](#primary-constructor-syntax) - *Members of primary constructor parameter of a readonly type cannot be modified (except in init-only setter of the type or a variable initializer).* -- [**CS9118**](#primary-constructor-syntax) - *Members of primary constructor parameter of a readonly type cannot be returned by writable reference.* -- [**CS9119**](#primary-constructor-syntax) - *Members of primary constructor parameter of a readonly type cannot be used as a `ref` or `out` value (except in init-only setter of the type or a variable initializer).* -- [**CS9120**](#primary-constructor-syntax) - *Cannot return primary constructor parameter by reference.* -- [**CS9121**](#primary-constructor-syntax) - *Struct primary constructor parameter of type causes a cycle in the struct layout.* -- [**CS9122**](#primary-constructor-syntax) - *Unexpected parameter list.* +- [**CS9108**](#primary-constructor-declaration): *Cannot use parameter that has ref-like type inside an anonymous method, lambda expression, query expression, or local function.* +- [**CS9109**](#primary-constructor-declaration): *Cannot use `ref`, `out`, or `in` primary constructor parameter inside an instance member.* +- [**CS9110**](#primary-constructor-declaration): *Cannot use primary constructor parameter that has ref-like type inside an instance member.* +- [**CS9111**](#primary-constructor-declaration): *Anonymous methods, lambda expressions, query expressions, and local functions inside an instance member of a struct cannot access primary constructor parameter.* +- [**CS9112**](#primary-constructor-declaration): *Anonymous methods, lambda expressions, query expressions, and local functions inside a struct cannot access primary constructor parameter also used inside an instance member.* +- [**CS9114**](#primary-constructor-declaration): *A primary constructor parameter of a readonly type cannot be assigned to (except in init-only setter of the type or a variable initializer).* +- [**CS9115**](#primary-constructor-declaration): *A primary constructor parameter of a readonly type cannot be returned by writable reference.* +- [**CS9116**](#primary-constructor-declaration): *A primary constructor parameter of a readonly type cannot be used as a ref or out value (except in init-only setter of the type or a variable initializer).* +- [**CS9117**](#primary-constructor-declaration): *Members of primary constructor parameter of a readonly type cannot be modified (except in init-only setter of the type or a variable initializer).* +- [**CS9118**](#primary-constructor-declaration): *Members of primary constructor parameter of a readonly type cannot be returned by writable reference.* +- [**CS9119**](#primary-constructor-declaration): *Members of primary constructor parameter of a readonly type cannot be used as a `ref` or `out` value (except in init-only setter of the type or a variable initializer).* +- [**CS9120**](#primary-constructor-declaration): *Cannot return primary constructor parameter by reference.* +- [**CS9121**](#primary-constructor-declaration): *Struct primary constructor parameter of type causes a cycle in the struct layout.* +- [**CS9122**](#primary-constructor-declaration): *Unexpected parameter list.* +- [**CS9136**](#primary-constructor-declaration): *Cannot use primary constructor parameter of type inside an instance member.* In addition, the following warnings are covered in this article: -- [**CS0824**](#constructor-declarations) - *Constructor 'name' is marked external.* -- [**CS9107**](#primary-constructor-syntax) - *Parameter is captured into the state of the enclosing type and its value is also passed to the base constructor. The value might be captured by the base class as well.* -- [**CS9113**](#primary-constructor-syntax) - *Parameter is unread.* +- [**CS0824**](#constructor-declaration): *Constructor 'name' is marked external.* +- [**CS9107**](#primary-constructor-declaration): *Parameter is captured into the state of the enclosing type and its value is also passed to the base constructor. The value might be captured by the base class as well.* +- [**CS9113**](#primary-constructor-declaration): *Parameter is unread.* +- [**CS9124**](#primary-constructor-declaration): *Parameter is captured into the state of the enclosing type and its value is also used to initialize a field, property, or event.* +- [**CS9179**](#primary-constructor-declaration): *Primary constructor parameter is shadowed by a member from base* ## Static constructors -- **CS0514** - *Static constructor cannot have an explicit 'this' or 'base' constructor call.* -- **CS0515** - *Access modifiers are not allowed on static constructors.* +- **CS0514**: *Static constructor cannot have an explicit 'this' or 'base' constructor call.* +- **CS0515**: *Access modifiers are not allowed on static constructors.* You can write at most one static constructor for a type. The declaration of a static constructor must obey the following rules: @@ -145,13 +154,13 @@ You can write at most one static constructor for a type. The declaration of a st - The static constructor must be a parameterless constructor. - The static constructor must not call `base()` or `this()`. If the base class includes a static constructor, the runtime calls it automatically. -## Constructor declarations +## Constructor declaration -- **CS0526** - *Interfaces cannot contain constructors.* -- **CS0710** - *Static classes cannot have instance constructors.* -- **CS8054** - *Enums cannot contain explicit parameterless constructors.* -- **CS8358** - *Cannot use attribute constructor because it has 'in' parameters.* -- **CS8091** - *A constructor cannot be extern and have a constructor initializer.* +- **CS0526**: *Interfaces cannot contain constructors.* +- **CS0710**: *Static classes cannot have instance constructors.* +- **CS8054**: *Enums cannot contain explicit parameterless constructors.* +- **CS8358**: *Cannot use attribute constructor because it has 'in' parameters.* +- **CS8091**: *A constructor cannot be extern and have a constructor initializer.* Constructors are allowed only in `class` and `struct` types, including `record class` and `record struct` types. You can't define them in `enum` or `interface` types. Furthermore, [attribute](../attributes/general.md) class types can't declare `in` parameters. Instead, pass parameters by value. @@ -159,16 +168,16 @@ You can declare `extern` constructors, however you can't use `base()` or `this() In addition, the following warnings can be generated for constructor declarations: -- **CS0824** - *Constructor is marked external.* +- **CS0824**: *Constructor is marked external.* When a constructor is marked `extern`, the compiler can't guarantee the constructor exists. Therefore, the compiler generates this warning. ## Constructors in struct types -- **CS0568** - *Structs cannot contain explicit parameterless constructors.* -- **CS8958** - *The parameterless struct constructor must be 'public'.* -- **CS8982** - *A constructor declared in a 'struct' with parameter list must have a 'this' initializer that calls the primary constructor or an explicitly declared constructor.* -- **CS8983** - *A 'struct' with field initializers must include an explicitly declared constructor.* +- **CS0568**: *Structs cannot contain explicit parameterless constructors.* +- **CS8958**: *The parameterless struct constructor must be 'public'.* +- **CS8982**: *A constructor declared in a 'struct' with parameter list must have a 'this' initializer that calls the primary constructor or an explicitly declared constructor.* +- **CS8983**: *A 'struct' with field initializers must include an explicitly declared constructor.* Recent features in C# remove earlier restrictions to `struct` types. **CS0568** is generated when you declare a parameterless constructor and you're using C# 9 or earlier. Once you're using C# 10, you can declare an explicit parameterless constructor. That explicit parameterless constructor must be `public`. If your `struct` declares any [field initializers](../../programming-guide/classes-and-structs/fields.md), you must also declare an explicit constructor. This constructor can be a parameterless constructor with an empty body. @@ -176,10 +185,10 @@ When a `struct` type declares a primary constructor, including `record struct` t ## Constructor calls with `base` and `this` -- **CS0516** - *Constructor can not call itself.* -- **CS0517** - *Class has no base class and cannot call a base constructor.* -- **CS0522** - *Structs cannot call base class constructors.* -- **CS0768** - *Constructor cannot call itself through another constructor.* +- **CS0516**: *Constructor can not call itself.* +- **CS0517**: *Class has no base class and cannot call a base constructor.* +- **CS0522**: *Structs cannot call base class constructors.* +- **CS0768**: *Constructor cannot call itself through another constructor.* You can use `base()` and `this()` to have one constructor call another in the same type or the base type. Calling constructors can minimize duplicated constructor logic. You must follow these rules when calling another constructor using `this()` or `base()`: @@ -210,10 +219,10 @@ You can use `base()` and `this()` to have one constructor call another in the sa ## Records and copy constructors -- **CS8867** - *No accessible copy constructor found in base type.* -- **CS8868** - *A copy constructor in a record must call a copy constructor of the base, or a parameterless object constructor if the record inherits from object.* -- **CS8878** - *A copy constructor must be public or protected because the record is not sealed.* -- **CS8910** - *The primary constructor conflicts with the synthesized copy constructor.* +- **CS8867**: *No accessible copy constructor found in base type.* +- **CS8868**: *A copy constructor in a record must call a copy constructor of the base, or a parameterless object constructor if the record inherits from object.* +- **CS8878**: *A copy constructor must be public or protected because the record is not sealed.* +- **CS8910**: *The primary constructor conflicts with the synthesized copy constructor.* Adding the `record` modifier to a `struct` or `class` type creates a [record](../builtin-types/record.md). Records include a compiler-synthesized [copy constructor](../builtin-types/record.md#nondestructive-mutation). You can write an explicit copy constructor yourself, but it must adhere to the following rules: @@ -221,27 +230,29 @@ Adding the `record` modifier to a `struct` or `class` type creates a [record](.. - Copy constructors must call the `base()` copy constructor unless the base class is . - Furthermore, the base type must have a copy constructor. `record` types always have a copy constructor. -## Primary constructor syntax +## Primary constructor declaration The compiler emits the following errors when a primary constructor violates one or more rules on primary constructors for classes and structs: -- **CS8862** - *A constructor declared in a type with parameter list must have 'this' constructor initializer.* -- **CS9105** - *Cannot use primary constructor parameter in this context.* -- **CS9106** - *Identifier is ambiguous between type and parameter in this context.* -- **CS9108** - *Cannot use parameter that has ref-like type inside an anonymous method, lambda expression, query expression, or local function.* -- **CS9109** - *Cannot use `ref`, `out`, or `in` primary constructor parameter inside an instance member.* -- **CS9110** - *Cannot use primary constructor parameter that has ref-like type inside an instance member.* -- **CS9111** - *Anonymous methods, lambda expressions, query expressions, and local functions inside an instance member of a struct cannot access primary constructor parameter.* -- **CS9112** - *Anonymous methods, lambda expressions, query expressions, and local functions inside a struct cannot access primary constructor parameter also used inside an instance member.* -- **CS9114** - *A primary constructor parameter of a readonly type cannot be assigned to (except in init-only setter of the type or a variable initializer).* -- **CS9115** - *A primary constructor parameter of a readonly type cannot be returned by writable reference.* -- **CS9116** - *A primary constructor parameter of a readonly type cannot be used as a `ref` or `out` value (except in init-only setter of the type or a variable initializer).* -- **CS9117** - *Members of primary constructor parameter of a readonly type cannot be modified (except in init-only setter of the type or a variable initializer).* -- **CS9118** - *Members of primary constructor parameter of a readonly type cannot be returned by writable reference.* -- **CS9119** - *Members of primary constructor parameter of a readonly type cannot be used as a `ref` or `out` value (except in init-only setter of the type or a variable initializer).* -- **CS9120** - *Cannot return primary constructor parameter by reference.* -- **CS9121** - *Struct primary constructor parameter of type causes a cycle in the struct layout.* -- **CS9122** - *Unexpected parameter list.* +- **CS8862**: *A constructor declared in a type with parameter list must have 'this' constructor initializer.* +- **CS9105**: *Cannot use primary constructor parameter in this context.* +- **CS9106**: *Identifier is ambiguous between type and parameter in this context.* +- **CS9108**: *Cannot use parameter that has ref-like type inside an anonymous method, lambda expression, query expression, or local function.* +- **CS9109**: *Cannot use `ref`, `out`, or `in` primary constructor parameter inside an instance member.* +- **CS9110**: *Cannot use primary constructor parameter that has ref-like type inside an instance member.* +- **CS9111**: *Anonymous methods, lambda expressions, query expressions, and local functions inside an instance member of a struct cannot access primary constructor parameter.* +- **CS9112**: *Anonymous methods, lambda expressions, query expressions, and local functions inside a struct cannot access primary constructor parameter also used inside an instance member.* +- **CS9114**: *A primary constructor parameter of a readonly type cannot be assigned to (except in init-only setter of the type or a variable initializer).* +- **CS9115**: *A primary constructor parameter of a readonly type cannot be returned by writable reference.* +- **CS9116**: *A primary constructor parameter of a readonly type cannot be used as a `ref` or `out` value (except in init-only setter of the type or a variable initializer).* +- **CS9117**: *Members of primary constructor parameter of a readonly type cannot be modified (except in init-only setter of the type or a variable initializer).* +- **CS9118**: *Members of primary constructor parameter of a readonly type cannot be returned by writable reference.* +- **CS9119**: *Members of primary constructor parameter of a readonly type cannot be used as a `ref` or `out` value (except in init-only setter of the type or a variable initializer).* +- **CS9120**: *Cannot return primary constructor parameter by reference.* +- **CS9121**: *Struct primary constructor parameter of type causes a cycle in the struct layout.* +- **CS9122**: *Unexpected parameter list.* +- **CS9124**: *Parameter is captured into the state of the enclosing type and its value is also used to initialize a field, property, or event.* +- **CS9136**: *Cannot use primary constructor parameter of type inside an instance member.* Primary constructor parameters are in scope in the body of that type. The compiler can synthesize a field that stores the parameter for use in members or in field initializers. Because a primary constructor parameter may be copied to a field, the following restrictions apply: @@ -264,7 +275,9 @@ Readonly only struct types have the following extra restrictions on primary cons In all these cases, the restrictions on primary constructor parameters are consistent with restrictions on data fields in those types. The restrictions are because a primary constructor parameter may be transformed into a synthesized field in the type. Therefore primary constructor parameters must follow the rules that apply to that synthesized field. -The two warnings provide guidance on captured primary constructor parameters. +The warnings provide guidance on captured or shadowed primary constructor parameters. -- **CS9107** - *Parameter is captured into the state of the enclosing type and its value is also passed to the base constructor. The value might be captured by the base class as well.* This warning indicates that your code may be allocated two copies of a primary constructor parameter. Because the parameter is passed to the base class, the base class likely uses it. Because the derived class accesses it, it may have a second copy of the same parameter. That extra storage may not be intended. -- **CS9113** - *Parameter is unread.* This warning indicates that your class never references the primary constructor, even to pass it to the base primary constructor. It likely isn't needed. +- **CS9107**: *Parameter is captured into the state of the enclosing type and its value is also passed to the base constructor. The value might be captured by the base class as well.* This warning indicates that your code may be allocated two copies of a primary constructor parameter. Because the parameter is passed to the base class, the base class likely uses it. Because the derived class accesses it, it may have a second copy of the same parameter. That extra storage may not be intended. +- **CS9113**: *Parameter is unread.* This warning indicates that your class never references the primary constructor, even to pass it to the base primary constructor. It likely isn't needed. +- **CS9124**: *Parameter is captured into the state of the enclosing type and its value is also used to initialize a field, property, or event.* This warning indicates that the constructor parameter of a nested type is also captured by the enclosing type. The parameter is likely stored twice. +- **CS9179**: *Primary constructor parameter is shadowed by a member from base* diff --git a/docs/csharp/language-reference/compiler-messages/feature-version-errors.md b/docs/csharp/language-reference/compiler-messages/feature-version-errors.md index f3747d6ec9a57..1b984961f84de 100644 --- a/docs/csharp/language-reference/compiler-messages/feature-version-errors.md +++ b/docs/csharp/language-reference/compiler-messages/feature-version-errors.md @@ -43,11 +43,14 @@ f1_keywords: - "CS9017" # WRN_UseDefViolationFieldUnsupportedVersion Use of possibly unassigned field - "CS8967" # ERR_NewlinesAreNotAllowedInsideANonVerbatimInterpolatedString Newlines inside a non-verbatim interpolated string are not supported in C# - "CS9064" + - "CS9103" - "CS9171" - "CS8058" - "CS8305" - "CS9204" - "CS9194" + - "CS9202" + - "CS9211" helpviewer_keywords: - "CS0171" - "CS0188" @@ -90,12 +93,15 @@ helpviewer_keywords: - "CS9017" - "CS8967" - "CS9064" + - "CS9103" - "CS9171" - "CS8058" - "CS8305" - "CS9204" - "CS9194" -ms.date: 10/26/2023 + - "CS9202" + - "CS9211" +ms.date: 11/02/2023 --- # Resolve warnings related to language features and versions @@ -104,41 +110,44 @@ This article covers the following compiler warnings: -- **CS8022, CS8023, CS8024, CS8025, CS8026, CS8059, CS8107, CS8302, CS8320, CS8370, CS8400, CS8773, CS8936, CS9058** - *Feature is not available. Use newer language version.* -- **CS8058** - *Feature is experimental.* -- **CS8192** - *Provided language version is unsupported or invalid* -- **CS8303** - *Specified language version cannot have leading zeroes* -- **CS8304** - *Compiler version is less than language version* -- **CS1738** - *Named argument specifications must appear after all fixed arguments have been specified.* -- **CS8306** - *Tuple element name is inferred.* -- **CS8314** - *An expression of type cannot be handled by a pattern of type* -- **CS8371** - *Field-targeted attributes on auto-properties are not supported in language version* -- **CS8401** - *To use `@$` instead of `$@` for an interpolated verbatim string, use newer language version.* -- **CS8511** - *An expression of type cannot be handled by a pattern of type.* -- **CS8627** - *A nullable type parameter must be known to be a value type or non-nullable reference type* -- **CS8630** - *Invalid nullable options. Use newer language version* -- **CS8652** - *The modifier is not valid for this item.* -- **CS8704** - *Type does not implement interface member. It cannot implicitly implement a non-public member.* -- **CS8706** - *Type cannot implement interface member because a feature is not available in this version.* -- **CS8904** - *Invalid variance: The type parameter must be valid.* -- **CS8912** - *Inheriting from a record with a sealed 'Object.ToString' is not supported.* -- **CS8957** - *Conditional expression is not valid in language version because a common type was not found between types.* -- **CS8967** - *Newlines inside a non-verbatim interpolated string are not supported in C#* -- **CS9014** - *Error: Use of possibly unassigned property. Upgrade to auto-default the property.* -- **CS9015** - *Error: Use of possibly unassigned field. Upgrade to auto-default the field.* -- **CS9016** - *Warning: Use of possibly unassigned property. Upgrade to auto-default the property.* -- **CS9017** - *Warning: Use of possibly unassigned field. Upgrade to auto-default the field.* -- **CS9064** - *Target runtime doesn't support ref fields.* -- **CS9171** - *Target runtime doesn't support inline array types.* -- **CS9194** - *Argument may not be passed with the `ref` keyword. To pass `ref` arguments to `in` parameters, upgrade to language version 12 or greater.* +- **CS8022, CS8023, CS8024, CS8025, CS8026, CS8059, CS8107, CS8302, CS8320, CS8370, CS8400, CS8773, CS8936, CS9058**: *Feature is not available. Use newer language version.* +- **CS8058**: *Feature is experimental.* +- **CS8192**: *Provided language version is unsupported or invalid* +- **CS8303**: *Specified language version cannot have leading zeroes* +- **CS8304**: *Compiler version is less than language version* +- **CS1738**: *Named argument specifications must appear after all fixed arguments have been specified.* +- **CS8306**: *Tuple element name is inferred.* +- **CS8314**: *An expression of type cannot be handled by a pattern of type* +- **CS8371**: *Field-targeted attributes on auto-properties are not supported in language version* +- **CS8401**: *To use `@$` instead of `$@` for an interpolated verbatim string, use newer language version.* +- **CS8511**: *An expression of type cannot be handled by a pattern of type.* +- **CS8627**: *A nullable type parameter must be known to be a value type or non-nullable reference type* +- **CS8630**: *Invalid nullable options. Use newer language version* +- **CS8652**: *The modifier is not valid for this item.* +- **CS8704**: *Type does not implement interface member. It cannot implicitly implement a non-public member.* +- **CS8706**: *Type cannot implement interface member because a feature is not available in this version.* +- **CS8904**: *Invalid variance: The type parameter must be valid.* +- **CS8912**: *Inheriting from a record with a sealed 'Object.ToString' is not supported.* +- **CS8957**: *Conditional expression is not valid in language version because a common type was not found between types.* +- **CS8967**: *Newlines inside a non-verbatim interpolated string are not supported in C#* +- **CS9014**: *Error: Use of possibly unassigned property. Upgrade to auto-default the property.* +- **CS9015**: *Error: Use of possibly unassigned field. Upgrade to auto-default the field.* +- **CS9016**: *Warning: Use of possibly unassigned property. Upgrade to auto-default the property.* +- **CS9017**: *Warning: Use of possibly unassigned field. Upgrade to auto-default the field.* +- **CS9064**: *Target runtime doesn't support ref fields.* +- **CS9103**: *Definition in a module with an unrecognized RefSafetyRulesAttribute version, expecting '11'.* +- **CS9171**: *Target runtime doesn't support inline array types.* +- **CS9194**: *Argument may not be passed with the `ref` keyword. To pass `ref` arguments to `in` parameters, upgrade to language version 12 or greater.* +- **CS9202**: *Feature is not available in C# 12.0. Please use newer language version* +- **CS9211**: *The diagnosticId argument to the 'Experimental' attribute must be a valid identifier.* In addition, the following errors and warnings relate to struct initialization changes in recent versions: - [**CS0171**, **CS8881**](#breaking-changes-on-struct-initialization): *Backing field for automatically implemented property 'name' must be fully assigned before control is returned to the caller.* - [**CS0188**, **CS8885**](#breaking-changes-on-struct-initialization): *The 'this' object cannot be used before all of its fields are assigned to* - [**CS0843**, **CS8880**](#breaking-changes-on-struct-initialization): *Backing field for automatically implemented property 'name' must be fully assigned before control is returned to the caller* -- [**CS8305**](#enable-experimental-features) - *Feature is for evaluation purposes only and is subject to change or removal in future updates.* -- [**CS9204**](#enable-experimental-features) - *Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.* +- [**CS8305**](#enable-experimental-features): *Feature is for evaluation purposes only and is subject to change or removal in future updates.* +- [**CS9204**](#enable-experimental-features): *Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.* The cause behind all these errors and warnings is that the compiler installed supports a newer version of C# than the version your project has selected. The C# compiler can conform to any previous version. You can validate syntax against an earlier version of C#, or because your project must support older libraries or runtimes. @@ -171,6 +180,8 @@ The diagnostics for experimental features can be disabled to use the experimenta > [!WARNING] > Experimental features are subject to changes. The APIs may change, or they may be removed in future updates. Including experimental features is a way for library authors to get feedback on ideas and concepts for future development. Use extreme caution when using any feature marked as experimental. +You can also declare your own experimental features using the . The compiler emits *CS9211* if the identifier used for the experimental feature is not a valid identifier. + ## Breaking changes on struct initialization All these errors and warnings help ensure that `struct` types are properly initialized before their fields are accessed. In earlier versions of C#, you must explicitly assign all fields in a struct in any constructor. The parameterless constructor initializes all fields to their default value. In later versions, all constructors initialize all fields. Either the field is explicitly set, set in a field initializer, or set to its default value. @@ -179,7 +190,7 @@ All these errors and warnings help ensure that `struct` types are properly initi - **CS0188**, **CS8885**: *The 'this' object cannot be used before all of its fields are assigned to* - **CS0843**, **CS8880**: *Backing field for automatically implemented property 'name' must be fully assigned before control is returned to the caller* -You can address this error by upgrading your language version to C# 11, when all fields are initialized by every `struct` constructor. If that's not a possible option, you must explicitly call the default constructor, as shown in the following example: +You can address this error by upgrading your language version to C# 11, every `struct` constructor initializes all fields. If that's not a possible option, you must explicitly call the default constructor, as shown in the following example: ```csharp struct S diff --git a/docs/csharp/language-reference/compiler-messages/inline-array-errors.md b/docs/csharp/language-reference/compiler-messages/inline-array-errors.md index f45a570350d66..b1382b08d7499 100644 --- a/docs/csharp/language-reference/compiler-messages/inline-array-errors.md +++ b/docs/csharp/language-reference/compiler-messages/inline-array-errors.md @@ -10,6 +10,12 @@ f1_keywords: - "CS9169" - "CS9172" - "CS9173" + - "CS9180" + - "CS9181" + - "CS9182" + - "CS9183" + - "CS9184" + - "CS9189" helpviewer_keywords: - "CS9164" - "CS9165" @@ -19,45 +25,68 @@ helpviewer_keywords: - "CS9169" - "CS9172" - "CS9173" -ms.date: 07/11/2023 + - "CS9180" + - "CS9181" + - "CS9182" + - "CS9183" + - "CS9184" + - "CS9189" +ms.date: 11/02/2023 --- # Resolve errors and warnings with inline array declarations -This article covers the following compiler errors: +This article covers the following compiler errors and warnings: -- [**CS9164**](#conversions-to-span) - *Cannot convert expression to `Span` because it is not an assignable variable* -- [**CS9165**](#conversions-to-span) - *Cannot convert expression to `ReadOnlySpan` because it may not be passed or returned by reference* -- [**CS9166**](#element-access) - *Index is outside the bounds of the inline array* -- [**CS9167**](#inline-array-declaration) - *Inline array length must be greater than 0.* -- [**CS9168**](#inline-array-declaration) - *Inline array struct must not have explicit layout.* -- [**CS9169**](#inline-array-declaration) - *Inline array struct must declare one and only one instance field which must not be a ref field.* -- [**CS9172**](#element-access) - *Elements of an inline array type can be accessed only with a single argument implicitly convertible to `int`, `System.Index`, or `System.Range`.* -- [**CS9173**](#element-access) - *An inline array access may not have a named argument specifier* +- [**CS9164**](#conversions-to-span): *Cannot convert expression to `Span` because it is not an assignable variable* +- [**CS9165**](#conversions-to-span): *Cannot convert expression to `ReadOnlySpan` because it may not be passed or returned by reference* +- [**CS9166**](#element-access): *Index is outside the bounds of the inline array* +- [**CS9167**](#inline-array-declaration): *Inline array length must be greater than 0.* +- [**CS9168**](#inline-array-declaration): *Inline array struct must not have explicit layout.* +- [**CS9169**](#inline-array-declaration): *Inline array struct must declare one and only one instance field which must not be a ref field.* +- [**CS9172**](#element-access): *Elements of an inline array type can be accessed only with a single argument implicitly convertible to `int`, `System.Index`, or `System.Range`.* +- [**CS9173**](#element-access): *An inline array access may not have a named argument specifier* +- [**CS9180**](#inline-array-declaration): *Inline array element field cannot be declared as required, readonly, volatile, or as a fixed size buffer.* +- [**CS9181**](#element-access): *Inline array indexer will not be used for element access expression.* +- [**CS9182**](#conversions-to-span): *Inline array 'Slice' method will not be used for element access expression.* +- [**CS9183**](#conversions-to-span): *Inline array conversion operator will not be used for conversion from expression of the declaring type.* +- [**CS9184**](#inline-array-declaration): *'Inline arrays' language feature is not supported for inline array types with element field which is either a '`ref`' field, or has type that is not valid as a type argument.* +- [**CS9189**](#element-access): *`foreach` statement on an inline array of type is not supported* ## Inline array declaration You declare inline arrays as a `struct` type with a single field, and an attribute that specifies the length of the array. The compiler generates the following errors for invalid inline array declarations: -- **CS9167** - *Inline array length must be greater than 0.* -- **CS9168** - *Inline array struct must not have explicit layout.* -- **CS9169** - *Inline array struct must declare one and only one instance field which must not be a ref field.* +- **CS9167**: *Inline array length must be greater than 0.* +- **CS9168**: *Inline array struct must not have explicit layout.* +- **CS9169**: *Inline array struct must declare one and only one instance field which must not be a ref field.* +- **CS9180**: *Inline array element field cannot be declared as required, readonly, volatile, or as a fixed size buffer.* +- **CS9184**: *'Inline arrays' language feature is not supported for inline array types with element field which is either a '`ref`' field, or has type that is not valid as a type argument.* To fix these arrays, ensure the following are true: - The argument to the is a positive integer. - The enclosing `struct` doesn't specify any explicit layout. - The enclosing `struct` has a single instance field, and that instance field is not a `ref` field. +- The single instance field is not a fixed size buffer. +- The single instance field doesn't include the `required`, `volatile`, or `readonly` modifiers. ## Element access -You access elements of an inline array in the same way as any array. The following errors may be generated from incorrect element access: +You access elements of an inline array in the same way as any array. The compiler emits the following errors from incorrect element access: -- **CS9166** - *Index is outside the bounds of the inline array* -- **CS9172** - *Elements of an inline array type can be accessed only with a single argument implicitly convertible to `int`, `System.Index`, or `System.Range`.* -- **CS9173** - *An inline array access may not have a named argument specifier* +- **CS9166**: *Index is outside the bounds of the inline array* +- **CS9172**: *Elements of an inline array type can be accessed only with a single argument implicitly convertible to `int`, `System.Index`, or `System.Range`.* +- **CS9173**: *An inline array access may not have a named argument specifier* +- **CS9189**: *`foreach` statement on an inline array of type is not supported* + +In addition, the compiler issues the following warning when you declare an [indexer](../../indexers.md): + +- **CS9181**: *Inline array indexer will not be used for element access expression.* + +The generated code for an inline buffer accesses the buffer memory directly, bypassing any declared indexers. Inline arrays can't be used with the `foreach` statement. The argument to the indexer must be: @@ -69,10 +98,17 @@ The argument to the indexer must be: You often use or to work with inline arrays. The compiler generates the following errors for invalid conversions: -- **CS9164** - *Cannot convert expression to `Span` because it is not an assignable variable* -- **CS9165** - *Cannot convert expression to `ReadOnlySpan` because it may not be passed or returned by reference* +- **CS9164**: *Cannot convert expression to `Span` because it is not an assignable variable* +- **CS9165**: *Cannot convert expression to `ReadOnlySpan` because it may not be passed or returned by reference* + +The compiler generates code that directly accesses the memory for an inline buffer. Therefore, some members aren't ever called. The compiler generates the following warnings if you write one of the members that aren't ever called: + +- **CS9182**: *Inline array 'Slice' method will not be used for element access expression.* +- **CS9183**: *Inline array conversion operator will not be used for conversion from expression of the declaring type.* An inline array can be implicitly converted to a `Span` or `ReadOnlySpan` to pass an inline array to methods. The compiler enforces restrictions on those conversions: - The inline array must be writable in order to convert an inline array to a `Span`. If the array is readonly, you can't convert it to a writable `Span`. You can use `ReadOnlySpan` instead. - The *safe context* of the inline array must be at least as wide as the *safe context* of the `Span` or `ReadOnlySpan` for the conversion to succeed. You must either limit the context of the span, or expand the scope of the inline array. + +In addition, the compiler never generates calls to a `Slice` method in an inline buffer. Conversion operators to convert an inline buffer to a `Span` or `ReadOnlySpan` aren't called. The compiler generates code to create a or directly from the memory buffer. diff --git a/docs/csharp/language-reference/compiler-messages/lambda-expression-errors.md b/docs/csharp/language-reference/compiler-messages/lambda-expression-errors.md index 4a9d5d8b7f968..e612fc51b03fc 100644 --- a/docs/csharp/language-reference/compiler-messages/lambda-expression-errors.md +++ b/docs/csharp/language-reference/compiler-messages/lambda-expression-errors.md @@ -18,7 +18,6 @@ f1_keywords: - "CS9098" # ERR_ImplicitlyTypedDefaultParameter: Implicitly typed lambda parameter '{0}' cannot have a default value. - "CS9099" # WRN_OptionalParamValueMismatch: The default parameter value does not match in the target delegate type. - "CS9100" # WRN_ParamsArrayInLambdaOnly: Parameter has params modifier in lambda but not in target delegate type. - - "CS9108" helpviewer_keywords: - "CS0748" - "CS0835" @@ -36,7 +35,6 @@ helpviewer_keywords: - "CS9098" - "CS9099" - "CS9100" - - "CS9108" ms.date: 05/04/2023 --- # Errors and warnings when using lambda expressions and anonymous functions @@ -46,26 +44,25 @@ There are several *errors* related to declaring and using lambda expressions: -- [**CS0748**](#lambda-expression-parameters-and-returns) - *Inconsistent lambda parameter usage; parameter types must be all explicit or all implicit.* -- [**CS1621**](#syntax-limitations-in-lambda-expressions) - *The yield statement cannot be used inside an anonymous method or lambda expression.* -- [**CS1628**](#syntax-limitations-in-lambda-expressions) - *Cannot use `in` `ref` or `out` parameter inside an anonymous method, lambda expression, or query expression.* -- [**CS1632**](#syntax-limitations-in-lambda-expressions) - *Control cannot leave the body of an anonymous method or lambda expression.* -- [**CS1673**](#syntax-limitations-in-lambda-expressions) - *Anonymous methods, lambda expressions, and query expressions inside structs cannot access instance members of 'this'.* -- [**CS1686**](#syntax-limitations-in-lambda-expressions) - *Local variable or its members cannot have their address taken and be used inside an anonymous method or lambda expression.* -- [**CS1706**](#syntax-limitations-in-lambda-expressions) - *Expression cannot contain anonymous methods or lambda expressions.* -- [**CS8030**](#syntax-limitations-in-lambda-expressions) - *Anonymous function converted to a void returning delegate cannot return a value.* -- [**CS8175**](#syntax-limitations-in-lambda-expressions) - *Cannot use ref local inside an anonymous method, lambda expression, or query expression.* -- [**CS8916**](#lambda-expression-parameters-and-returns) - *Attributes on lambda expressions require a parenthesized parameter list.* -- [**CS8971**](#syntax-limitations-in-lambda-expressions) - *InterpolatedStringHandlerArgument has no effect when applied to lambda parameters and will be ignored at the call site.* -- [**CS8975**](#lambda-expression-parameters-and-returns) - *The contextual keyword `var` cannot be used as an explicit lambda return type.* -- [**CS9098**](#lambda-expression-parameters-and-returns) - *Implicitly typed lambda parameter '...' cannot have a default value.* -- [**CS9108**](#syntax-limitations-in-lambda-expressions) - *Cannot use a parameter that has ref-like type inside an anonymous method, lambda expression, query expression, or local function* +- [**CS0748**](#lambda-expression-parameters-and-returns): *Inconsistent lambda parameter usage; parameter types must be all explicit or all implicit.* +- [**CS1621**](#syntax-limitations-in-lambda-expressions): *The yield statement cannot be used inside an anonymous method or lambda expression.* +- [**CS1628**](#syntax-limitations-in-lambda-expressions): *Cannot use `in` `ref` or `out` parameter inside an anonymous method, lambda expression, or query expression.* +- [**CS1632**](#syntax-limitations-in-lambda-expressions): *Control cannot leave the body of an anonymous method or lambda expression.* +- [**CS1673**](#syntax-limitations-in-lambda-expressions): *Anonymous methods, lambda expressions, and query expressions inside structs cannot access instance members of 'this'.* +- [**CS1686**](#syntax-limitations-in-lambda-expressions): *Local variable or its members cannot have their address taken and be used inside an anonymous method or lambda expression.* +- [**CS1706**](#syntax-limitations-in-lambda-expressions): *Expression cannot contain anonymous methods or lambda expressions.* +- [**CS8030**](#syntax-limitations-in-lambda-expressions): *Anonymous function converted to a void returning delegate cannot return a value.* +- [**CS8175**](#syntax-limitations-in-lambda-expressions): *Cannot use ref local inside an anonymous method, lambda expression, or query expression.* +- [**CS8916**](#lambda-expression-parameters-and-returns): *Attributes on lambda expressions require a parenthesized parameter list.* +- [**CS8971**](#syntax-limitations-in-lambda-expressions): *InterpolatedStringHandlerArgument has no effect when applied to lambda parameters and will be ignored at the call site.* +- [**CS8975**](#lambda-expression-parameters-and-returns): *The contextual keyword `var` cannot be used as an explicit lambda return type.* +- [**CS9098**](#lambda-expression-parameters-and-returns): *Implicitly typed lambda parameter '...' cannot have a default value.* In addition, there are several *warnings* related to declaring and using lambda expressions: -- [**CS8971**](#syntax-limitations-in-lambda-expressions) - *InterpolatedStringHandlerArgument has no effect when applied to lambda parameters and will be ignored at the call site.* -- [**CS9099**](#lambda-expression-delegate-type) - *The default parameter value does not match in the target delegate type.* -- [**CS9100**](#lambda-expression-delegate-type) - *Parameter has params modifier in lambda but not in target delegate type.* +- [**CS8971**](#syntax-limitations-in-lambda-expressions): *InterpolatedStringHandlerArgument has no effect when applied to lambda parameters and will be ignored at the call site.* +- [**CS9099**](#lambda-expression-delegate-type): *The default parameter value does not match in the target delegate type.* +- [**CS9100**](#lambda-expression-delegate-type): *Parameter has params modifier in lambda but not in target delegate type.* ## Syntax limitations in lambda expressions @@ -77,7 +74,6 @@ Some C# syntax is prohibited in lambda expressions and anonymous methods. Using - **CS1673**: *Anonymous methods, lambda expressions, and query expressions inside structs cannot access instance members of `this`.* - **CS1686**: *Local variable or its members cannot have their address taken and be used inside an anonymous method or lambda expression.* - **CS8175**: *Cannot use ref local inside an anonymous method, lambda expression, or query expression.* -- **CS9108**: *Cannot use a parameter that has ref-like type inside an anonymous method, lambda expression, query expression, or local function* All the following constructs are disallowed in lambda expressions: @@ -92,17 +88,17 @@ You can't use any of these constructs in a lambda expression or an anonymous met In addition, interpolated string handler types are ignored when applied to a lambda parameter. If you use one, you see the following warning: -- **CS8971** - *InterpolatedStringHandlerArgument has no effect when applied to lambda parameters and will be ignored at the call site.* +- **CS8971**: *InterpolatedStringHandlerArgument has no effect when applied to lambda parameters and will be ignored at the call site.* ## Lambda expression parameters and returns These errors indicate a problem with a parameter declaration: -- **CS0748** - *Inconsistent lambda parameter usage; parameter types must be all explicit or all implicit.* -- **CS9098** - *Implicitly typed lambda parameter '...' cannot have a default value.* -- **CS8030** - *Anonymous function converted to a void returning delegate cannot return a value.* -- **CS8916** - *Attributes on lambda expressions require a parenthesized parameter list.* -- **CS8975** - *The contextual keyword 'var' cannot be used as an explicit lambda return type.* +- **CS0748**: *Inconsistent lambda parameter usage; parameter types must be all explicit or all implicit.* +- **CS9098**: *Implicitly typed lambda parameter '...' cannot have a default value.* +- **CS8030**: *Anonymous function converted to a void returning delegate cannot return a value.* +- **CS8916**: *Attributes on lambda expressions require a parenthesized parameter list.* +- **CS8975**: *The contextual keyword 'var' cannot be used as an explicit lambda return type.* Lambda expression parameters must follow these rules: @@ -117,7 +113,7 @@ Return types of lambda expression must follow these rules: ## Lambda expression delegate type -- [**CS9099**](#lambda-expression-delegate-type) - Warning: *The default parameter value does not match in the target delegate type.* +- [**CS9099**](#lambda-expression-delegate-type): Warning: *The default parameter value does not match in the target delegate type.* When you declare a default value or add the `params` modifier with a lambda expression parameter, the delegate type isn't one of the `Func` or `Action` types. Rather, it's a custom type that includes the default parameter value or `params` modifier. The following code generates warnings because it assigns a lambda expression that has a default parameter to an `Action` type: diff --git a/docs/csharp/language-reference/compiler-messages/pattern-matching-warnings.md b/docs/csharp/language-reference/compiler-messages/pattern-matching-warnings.md index 50659a4003e71..bbb3d9717edb7 100644 --- a/docs/csharp/language-reference/compiler-messages/pattern-matching-warnings.md +++ b/docs/csharp/language-reference/compiler-messages/pattern-matching-warnings.md @@ -1,17 +1,39 @@ --- -title: Pattern matching warnings +title: Pattern matching errors and warnings description: There are several pattern matching warnings. Learn how to address these warnings. f1_keywords: - "CS8509" # WRN_SwitchNotAllPossibleValues: The switch expression does not handle all possible values of its input type (it is not exhaustive). For example, the pattern '...' is not covered. + - "CS9134" + - "CS9135" helpviewer_keywords: - "CS8509" -ms.date: 11/10/2022 + - "CS9134" + - "CS9135" +ms.date: 11/02/2022 --- -# Pattern matching warnings +# Pattern matching errors and warnings -There are several pattern matching warnings. Learn how to address these warnings. +The compiler generates the following errors for invalid pattern match expressions: -- **CS8509** - *The switch expression does not handle all possible values of its input type (it is not exhaustive). For example, the pattern '...' is not covered.* +- **CS9134**: *A switch expression arm does not begin with a 'case' keyword.* +- **CS9135**: *A constant value of type is expected* + +The compiler generates the following warnings for incomplete pattern matching expressions: + +- **CS8509**: *The switch expression does not handle all possible values of its input type (it is not exhaustive). For example, the pattern '...' is not covered.* + +The compiler generates CS9134 to help you convert a switch statement to a switch expression. The `case` keyword isn't used in a switch expression. If you have the `case` keyword in a switch expression, it must be removed: + +```csharp +var answer = x switch +{ + // CS9134: remove the keyword "case" from each switch arm: + case 0 => false, + case 1 => true, +} +``` + +The compiler generates CS9135 when the pattern isn't a constant value. You can't create pattern matching expressions to match against a variable. The following code snippets generate CS8509: @@ -21,6 +43,6 @@ To address this warning, add switch arms that cover all possible input values. F :::code language="csharp" source="./snippets/pattern-matching-warnings/Switch.cs" id="SwitchAllPossibleValues"::: -The `_` pattern matches all remaining values. It's often used to match invalid values, as shown in the preceding example. +The `_` pattern matches all remaining values. One scenario for the `_` pattern is matching invalid values, as shown in the preceding example. For more information, see [Switch](../statements/selection-statements.md#the-switch-statement). diff --git a/docs/csharp/language-reference/compiler-messages/ref-modifiers-errors.md b/docs/csharp/language-reference/compiler-messages/ref-modifiers-errors.md index ae88e2d739abc..6c08cc1804561 100644 --- a/docs/csharp/language-reference/compiler-messages/ref-modifiers-errors.md +++ b/docs/csharp/language-reference/compiler-messages/ref-modifiers-errors.md @@ -2,7 +2,6 @@ title: Errors and warnings associated with reference parameter modifiers description: The compiler issues these errors and warnings when you use the reference parameter modifiers incorrectly. They indicate a mismatch between the modifier on the parameter, the argument, or the use of the parameter in the method. f1_keywords: - - "CS9190" - "CS0192" - "CS0199" - "CS0206" @@ -42,14 +41,6 @@ f1_keywords: - "CS9077" - "CS9078" - "CS9079" - - "CS9096" - - "CS9109" - - "CS9110" - - "CS9116" - - "CS9119" - - "CS9130" - - "CS9190" - - "CS9199" - "CS9085" - "CS9086" - "CS9087" @@ -59,8 +50,12 @@ f1_keywords: - "CS9093" - "CS9094" - "CS9095" + - "CS9096" - "CS9097" - - "CS9184" + - "CS9101" + - "CS9102" + - "CS9104" + - "CS9190" - "CS9191" - "CS9192" - "CS9193" @@ -68,10 +63,10 @@ f1_keywords: - "CS9196" - "CS9197" - "CS9198" + - "CS9199" - "CS9200" - "CS9201" helpviewer_keywords: - - "CS9190" - "CS0192" - "CS0199" - "CS0206" @@ -111,14 +106,6 @@ helpviewer_keywords: - "CS9077" - "CS9078" - "CS9079" - - "CS9096" - - "CS9109" - - "CS9110" - - "CS9116" - - "CS9119" - - "CS9130" - - "CS9190" - - "CS9199" - "CS9085" - "CS9086" - "CS9087" @@ -128,8 +115,12 @@ helpviewer_keywords: - "CS9093" - "CS9094" - "CS9095" + - "CS9096" - "CS9097" - - "CS9184" + - "CS9101" + - "CS9102" + - "CS9104" + - "CS9190" - "CS9191" - "CS9192" - "CS9193" @@ -137,9 +128,10 @@ helpviewer_keywords: - "CS9196" - "CS9197" - "CS9198" + - "CS9199" - "CS9200" - "CS9201" -ms.date: 10/24/2023 +ms.date: 11/02/2023 --- # Errors and warnings associated with reference parameters, variables, and returns @@ -148,84 +140,81 @@ The following errors can be generated when you're working with reference variabl -- [**CS0192**](#writable-reference-variables-require-a-writable-referent) - *A `readonly` field cannot be used as a `ref` or `out` value (except in a constructor)* -- [**CS0199**](#writable-reference-variables-require-a-writable-referent) - *A `static readonly` field cannot be used as a `ref` or `out` value (except in a static constructor)* -- [**CS0206**](#reference-variables-require-a-referent) - *A non ref-returning property or indexer may not be used as an `out` or `ref` value* -- [**CS0631**](#reference-variable-restrictions) - *`ref` and `out` are not valid in this context* -- [**CS0767**](#reference-variable-restrictions) - *Cannot inherit interface with the specified type parameters because it causes method to contain overloads which differ only on `ref` and `out`* -- [**CS1510**](#reference-variables-require-a-referent) - *A `ref` or `out` value must be an assignable variable* -- [**CS1605**](#writable-reference-variables-require-a-writable-referent) - *Cannot use variable as a `ref` or `out` value because it is read-only* -- [**CS1623**](#reference-variable-restrictions) - *Iterators cannot have `ref`, `in` or `out` parameters* -- [**CS1649**](#writable-reference-variables-require-a-writable-referent) - *Members of a `readonly` field cannot be used as a `ref` or `out` value (except in a constructor)* -- [**CS1651**](#writable-reference-variables-require-a-writable-referent) - *Fields of a static readonly field cannot be used as a `ref` or `out` value (except in a static constructor)* -- [**CS1655**](#writable-reference-variables-require-a-writable-referent) - *Cannot use fields of type as a `ref` or `out` value* -- [**CS1657**](#writable-reference-variables-require-a-writable-referent) - *Cannot use variable as a `ref` or `out` value* -- [**CS1741**](#reference-variable-restrictions) - *A `ref` or `out` parameter cannot have a default value* -- [**CS1939**](#reference-variable-restrictions) - *Cannot pass the range variable as an `out` or `ref` parameter* -- [**CS1988**](#reference-variable-restrictions) - *Async methods cannot have `ref`, `in` or `out` parameters* -- [**CS7084**](#reference-variable-restrictions) - *A Windows Runtime event may not be passed as an `out` or `ref` parameter.* -- [**CS8166**](#ref-safety-violations) - *Cannot return a parameter by reference because it is not a `ref` parameter* -- [**CS8167**](#ref-safety-violations) - *Cannot return by reference a member of parameter because it is not a `ref` or `out` parameter* -- [**CS8168**](#ref-safety-violations) - *Cannot return local by reference because it is not a ref local* -- [**CS8169**](#ref-safety-violations) - *Cannot return a member of local variable by reference because it is not a ref local* -- [**CS8325**](#reference-variable-restrictions) - *'`await`' cannot be used in an expression containing a `ref` conditional operator* -- [**CS8326**](#reference-variable-restrictions) - *Both conditional operator values must be ref values or neither may be a ref value* -- [**CS8327**](#reference-variable-restrictions) - *The expression must be of correct type to match the alternative ref value* -- [**CS8329**](#writable-reference-variables-require-a-writable-referent) - *Cannot use variable as a `ref` or `out` value because it is a readonly variable* -- [**CS8330**](#writable-reference-variables-require-a-writable-referent) - *Members of variable cannot be used as a `ref` or `out` value because it is a readonly variable* -- [**CS8331**](#writable-reference-variables-require-a-writable-referent) - *Cannot assign to variable or use it as the right hand side of a `ref` assignment because it is a readonly variable* -- [**CS8332**](#writable-reference-variables-require-a-writable-referent) - *Cannot assign to a member of variable or use it as the right hand side of a `ref` assignment because it is a readonly variable* -- [**CS8337**](#reference-variable-restrictions) - *The first parameter of a '`ref`' extension method must be a value type or a generic type constrained to struct.* -- [**CS8338**](#reference-variable-restrictions) - *The first '`in`' or '`ref readonly`' parameter of the extension method must be a concrete (non-generic) value type.* -- [**CS8345**](#ref-safety-violations) - *Field or auto-implemented property cannot be of type unless it is an instance member of a `ref struct`.* -- [**CS8351**](#ref-safety-violations) - *Branches of a `ref` conditional operator cannot refer to variables with incompatible declaration scopes* -- [**CS8373**](#incorrect-syntax) - *The left-hand side of a `ref` assignment must be a ref variable.* -- [**CS8374**](#ref-safety-violations) - *Cannot ref-assign source has a narrower escape scope than destination.* -- [**CS8388**](#incorrect-syntax) - *An `out` variable cannot be declared as a ref local* -- [**CS8977**](#reference-variable-restrictions) - *Cannot use '`ref`', '`in`', or '`out`' in the signature of a method attributed with 'UnmanagedCallersOnly'.* -- [**CS9072**](#reference-variable-restrictions) - *A deconstruction variable cannot be declared as a ref local* -- [**CS9077**](#ref-safety-violations) - *Cannot return a parameter by reference through a `ref` parameter; it can only be returned in a return statement* -- [**CS9078**](#ref-safety-violations) - *Cannot return by reference a member of parameter through a `ref` parameter; it can only be returned in a return statement* -- [**CS9079**](#ref-safety-violations) - *Cannot ref-assign because source can only escape the current method through a return statement.* -- [**CS9096**](#ref-safety-violations) - *Cannot ref-assign because source has a wider value escape scope than destination allowing assignment through source of values with narrower escapes scopes than destination.* -- [**CS9109**](#ref-safety-violations) - *Cannot use `ref`, `out`, or `in` primary constructor parameter inside an instance member* -- [**CS9110**](#ref-safety-violations) - *Cannot use primary constructor parameter that has ref-like type inside an instance member* -- [**CS9116**](#writable-reference-variables-require-a-writable-referent) - *A primary constructor parameter of a readonly type cannot be used as a `ref` or `out` value (except in init-only setter of the type or a variable initializer)* -- [**CS9119**](#writable-reference-variables-require-a-writable-referent) - *Members of primary constructor parameter of a readonly type cannot be used as a `ref` or `out` value (except in init-only setter of the type or a variable initializer)* -- [**CS9130**](#incorrect-syntax) - *Using alias cannot be a '`ref`' type.* -- [**CS9190**](#incorrect-syntax) - *`readonly` modifier must be specified after `ref`.* -- [**CS9199**](#reference-variable-restrictions) - *A `ref readonly` parameter cannot have the Out attribute.* +- [**CS0192**](#writable-reference-variables-require-a-writable-referent): *A `readonly` field cannot be used as a `ref` or `out` value (except in a constructor)* +- [**CS0199**](#writable-reference-variables-require-a-writable-referent): *A `static readonly` field cannot be used as a `ref` or `out` value (except in a static constructor)* +- [**CS0206**](#reference-variables-require-a-referent): *A non ref-returning property or indexer may not be used as an `out` or `ref` value* +- [**CS0631**](#reference-variable-restrictions): *`ref` and `out` are not valid in this context* +- [**CS0767**](#reference-variable-restrictions): *Cannot inherit interface with the specified type parameters because it causes method to contain overloads which differ only on `ref` and `out`* +- [**CS1510**](#reference-variables-require-a-referent): *A `ref` or `out` value must be an assignable variable* +- [**CS1605**](#writable-reference-variables-require-a-writable-referent): *Cannot use variable as a `ref` or `out` value because it is read-only* +- [**CS1623**](#reference-variable-restrictions): *Iterators cannot have `ref`, `in` or `out` parameters* +- [**CS1649**](#writable-reference-variables-require-a-writable-referent): *Members of a `readonly` field cannot be used as a `ref` or `out` value (except in a constructor)* +- [**CS1651**](#writable-reference-variables-require-a-writable-referent): *Fields of a static readonly field cannot be used as a `ref` or `out` value (except in a static constructor)* +- [**CS1655**](#writable-reference-variables-require-a-writable-referent): *Cannot use fields of type as a `ref` or `out` value* +- [**CS1657**](#writable-reference-variables-require-a-writable-referent): *Cannot use variable as a `ref` or `out` value* +- [**CS1741**](#reference-variable-restrictions): *A `ref` or `out` parameter cannot have a default value* +- [**CS1939**](#reference-variable-restrictions): *Cannot pass the range variable as an `out` or `ref` parameter* +- [**CS1988**](#reference-variable-restrictions): *Async methods cannot have `ref`, `in` or `out` parameters* +- [**CS7084**](#reference-variable-restrictions): *A Windows Runtime event may not be passed as an `out` or `ref` parameter.* +- [**CS8166**](#ref-safety-violations): *Cannot return a parameter by reference because it is not a `ref` parameter* +- [**CS8167**](#ref-safety-violations): *Cannot return by reference a member of parameter because it is not a `ref` or `out` parameter* +- [**CS8168**](#ref-safety-violations): *Cannot return local by reference because it is not a ref local* +- [**CS8169**](#ref-safety-violations): *Cannot return a member of local variable by reference because it is not a ref local* +- [**CS8325**](#reference-variable-restrictions): *'`await`' cannot be used in an expression containing a `ref` conditional operator* +- [**CS8326**](#reference-variable-restrictions): *Both conditional operator values must be ref values or neither may be a ref value* +- [**CS8327**](#reference-variable-restrictions): *The expression must be of correct type to match the alternative ref value* +- [**CS8329**](#writable-reference-variables-require-a-writable-referent): *Cannot use variable as a `ref` or `out` value because it is a readonly variable* +- [**CS8330**](#writable-reference-variables-require-a-writable-referent): *Members of variable cannot be used as a `ref` or `out` value because it is a readonly variable* +- [**CS8331**](#writable-reference-variables-require-a-writable-referent): *Cannot assign to variable or use it as the right hand side of a `ref` assignment because it is a readonly variable* +- [**CS8332**](#writable-reference-variables-require-a-writable-referent): *Cannot assign to a member of variable or use it as the right hand side of a `ref` assignment because it is a readonly variable* +- [**CS8337**](#reference-variable-restrictions): *The first parameter of a '`ref`' extension method must be a value type or a generic type constrained to struct.* +- [**CS8338**](#reference-variable-restrictions): *The first '`in`' or '`ref readonly`' parameter of the extension method must be a concrete (non-generic) value type.* +- [**CS8345**](#ref-safety-violations): *Field or auto-implemented property cannot be of type unless it is an instance member of a `ref struct`.* +- [**CS8351**](#ref-safety-violations): *Branches of a `ref` conditional operator cannot refer to variables with incompatible declaration scopes* +- [**CS8373**](#incorrect-syntax): *The left-hand side of a `ref` assignment must be a ref variable.* +- [**CS8374**](#ref-safety-violations): *Cannot ref-assign source has a narrower escape scope than destination.* +- [**CS8388**](#incorrect-syntax): *An `out` variable cannot be declared as a ref local* +- [**CS8977**](#reference-variable-restrictions): *Cannot use '`ref`', '`in`', or '`out`' in the signature of a method attributed with 'UnmanagedCallersOnly'.* +- [**CS9072**](#reference-variable-restrictions): *A deconstruction variable cannot be declared as a ref local* +- [**CS9077**](#ref-safety-violations): *Cannot return a parameter by reference through a `ref` parameter; it can only be returned in a return statement* +- [**CS9078**](#ref-safety-violations): *Cannot return by reference a member of parameter through a `ref` parameter; it can only be returned in a return statement* +- [**CS9079**](#ref-safety-violations): *Cannot ref-assign because source can only escape the current method through a return statement.* +- [**CS9096**](#ref-safety-violations): *Cannot ref-assign because source has a wider value escape scope than destination allowing assignment through source of values with narrower escapes scopes than destination.* +- [**CS9101**](#unscoped-ref-restrictions): *UnscopedRefAttribute can only be applied to struct instance methods and properties, and cannot be applied to constructors or init-only members.* +- [**CS9102**](#unscoped-ref-restrictions): *UnscopedRefAttribute cannot be applied to an interface implementation.* +- [**CS9104**](#reference-variable-restrictions): *A using statement resource of type cannot be used in async methods or async lambda expressions.* +- [**CS9190**](#incorrect-syntax): *`readonly` modifier must be specified after `ref`.* +- [**CS9199**](#reference-variable-restrictions): *A `ref readonly` parameter cannot have the Out attribute.* The following warnings are generated when reference variables are used incorrectly: -- [**CS9085**](#ref-safety-violations) - *This ref-assigns variable but destination has a narrower escape scope than source.* -- [**CS9086**](#ref-safety-violations) - *The branches of the `ref` conditional operator refer to variables with incompatible declaration scopes* -- [**CS9087**](#ref-safety-violations) - *This returns a parameter by reference but it is not a `ref` parameter* -- [**CS9089**](#ref-safety-violations) - *This returns by reference a member of parameter that is not a `ref` or `out` parameter* -- [**CS9091**](#ref-safety-violations) - *This returns local by reference but it is not a ref local* -- [**CS9092**](#ref-safety-violations) - *This returns a member of local by reference but it is not a ref local* -- [**CS9093**](#ref-safety-violations) - *This ref-assigns but source can only escape the current method through a return statement.* -- [**CS9094**](#ref-safety-violations) - *This returns a parameter by reference through a `ref` parameter; but it can only safely be returned in a return statement* -- [**CS9095**](#ref-safety-violations) - *This returns by reference a member of parameter through a `ref` parameter; but it can only safely be returned in a return statement* -- [**CS9097**](#ref-safety-violations) - *This ref-assigns but source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* -- [**CS9184**](#reference-variable-restrictions) - *'Inline arrays' language feature is not supported for inline array types with element field which is either a '`ref`' field, or has type that is not valid as a type argument.* -- [**CS9191**](#reference-variables-require-a-referent) - *The `ref` modifier for argument corresponding to `in` parameter is equivalent to `in`. Consider using `in` instead.* -- [**CS9192**](#reference-variables-require-a-referent) - *Argument should be passed with `ref` or `in` keyword.* -- [**CS9193**](#reference-variables-require-a-referent) - *Argument should be a variable because it is passed to a `ref readonly` parameter* -- [**CS9195**](#reference-variables-require-a-referent) - *Argument should be passed with the `in` keyword* -- [**CS9196**](#reference-variable-restrictions) - *Reference kind modifier of parameter doesn't match the corresponding parameter in overridden or implemented member.* -- [**CS9197**](#reference-variable-restrictions) - *Reference kind modifier of parameter doesn't match the corresponding parameter in hidden member.* -- [**CS9198**](#reference-variable-restrictions) - *Reference kind modifier of parameter doesn't match the corresponding parameter in target.* -- [**CS9200**](#reference-variable-restrictions) - *A default value is specified for `ref readonly` parameter, but `ref readonly` should be used only for references. Consider declaring the parameter as `in`.* -- [**CS9201**](#reference-variable-restrictions) - *Ref field should be ref-assigned before use.* +- [**CS9085**](#ref-safety-violations): *This ref-assigns variable but destination has a narrower escape scope than source.* +- [**CS9086**](#ref-safety-violations): *The branches of the `ref` conditional operator refer to variables with incompatible declaration scopes* +- [**CS9087**](#ref-safety-violations): *This returns a parameter by reference but it is not a `ref` parameter* +- [**CS9089**](#ref-safety-violations): *This returns by reference a member of parameter that is not a `ref` or `out` parameter* +- [**CS9091**](#ref-safety-violations): *This returns local by reference but it is not a ref local* +- [**CS9092**](#ref-safety-violations): *This returns a member of local by reference but it is not a ref local* +- [**CS9093**](#ref-safety-violations): *This ref-assigns but source can only escape the current method through a return statement.* +- [**CS9094**](#ref-safety-violations): *This returns a parameter by reference through a `ref` parameter; but it can only safely be returned in a return statement* +- [**CS9095**](#ref-safety-violations): *This returns by reference a member of parameter through a `ref` parameter; but it can only safely be returned in a return statement* +- [**CS9097**](#ref-safety-violations): *This ref-assigns but source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* +- [**CS9191**](#reference-variables-require-a-referent): *The `ref` modifier for argument corresponding to `in` parameter is equivalent to `in`. Consider using `in` instead.* +- [**CS9192**](#reference-variables-require-a-referent): *Argument should be passed with `ref` or `in` keyword.* +- [**CS9193**](#reference-variables-require-a-referent): *Argument should be a variable because it is passed to a `ref readonly` parameter* +- [**CS9195**](#reference-variables-require-a-referent): *Argument should be passed with the `in` keyword* +- [**CS9196**](#reference-variable-restrictions): *Reference kind modifier of parameter doesn't match the corresponding parameter in overridden or implemented member.* +- [**CS9197**](#reference-variable-restrictions): *Reference kind modifier of parameter doesn't match the corresponding parameter in hidden member.* +- [**CS9198**](#reference-variable-restrictions): *Reference kind modifier of parameter doesn't match the corresponding parameter in target.* +- [**CS9200**](#reference-variable-restrictions): *A default value is specified for `ref readonly` parameter, but `ref readonly` should be used only for references. Consider declaring the parameter as `in`.* +- [**CS9201**](#reference-variable-restrictions): *Ref field should be ref-assigned before use.* These errors and warnings follow these themes: -- ***[Incorrect syntax](#incorrect-syntax)*** - The syntax of your declaration or usage is invalid. -- ***[Language constructs where `ref` variables aren't valid](#reference-variable-restrictions)*** - Some C# idioms don't allow variables. Usually this is because ref safety analysis can't be performed reliably. -- ***[Value expression used where a reference variable is needed](#reference-variables-require-a-referent)*** - The expression used as a reference variable must be a variable, not a value expression. -- ***[Writable reference variables referring to readonly variables](#writable-reference-variables-require-a-writable-referent)*** - A reference to a readonly variable can't be passed by writable reference. -- ***[violations of ref safety](#ref-safety-violations)*** - A reference variable can't refer to a variable that has a narrower context. That would mean the reference variable could refer to invalid memory. +- ***[Incorrect syntax](#incorrect-syntax)***: The syntax of your declaration or usage is invalid. +- ***[Language constructs where `ref` variables aren't valid](#reference-variable-restrictions)***: Some C# idioms don't allow variables. Usually this is because ref safety analysis can't be performed reliably. +- ***[Value expression used where a reference variable is needed](#reference-variables-require-a-referent)***: The expression used as a reference variable must be a variable, not a value expression. +- ***[Writable reference variables referring to readonly variables](#writable-reference-variables-require-a-writable-referent)***: A reference to a readonly variable can't be passed by writable reference. +- ***[violations of ref safety](#ref-safety-violations)***: A reference variable can't refer to a variable that has a narrower context. That would mean the reference variable could refer to invalid memory. This article uses the term *reference variable* as a general term for a parameter declared with one of the `in`, `ref readonly`, `ref`, or `out` modifiers, or a `ref` local variable, a `ref` field in a `ref struct`, or a `ref` return. A reference variable refers to another variable, called the *referent*. @@ -233,46 +222,44 @@ This article uses the term *reference variable* as a general term for a paramete These errors indicate that you're using incorrect syntax regarding reference variables: -- **CS8373** - *The left-hand side of a `ref` assignment must be a ref variable.* -- **CS8388** - *An `out` variable cannot be declared as a ref local.* -- **CS9130** - *Using alias cannot be a '`ref`' type.* -- **CS9190** - *`readonly` modifier must be specified after `ref`.* +- **CS8373**: *The left-hand side of a `ref` assignment must be a ref variable.* +- **CS8388**: *An `out` variable cannot be declared as a ref local.* +- **CS9190**: *`readonly` modifier must be specified after `ref`.* You can correct the error with one of these changes: - The left operand of an `= ref` operator must be a reference variable. For more information on the correct syntax, see [reference variables](../statements/declarations.md#reference-variables). - The parameter modifier `ref readonly` must be in that order. `readonly ref` is not a legal parameter modifier. Switch the order of the words. - A local variable can't be declared as `out`. To declare a local reference variable, use `ref`. -- A `using` alias can't be a `ref` type. You must remove that alias. ## Reference variable restrictions The following errors indicate that a reference variable can't be used where you have one: -- **CS0631** - *`ref` and `out` are not valid in this context* -- **CS0767** - *Cannot inherit interface with the specified type parameters because it causes method to contain overloads which differ only on `ref` and `out`* -- **CS1623** - *Iterators cannot have `ref`, `in` or `out` parameters* -- **CS1741** - *A `ref` or `out` parameter cannot have a default value* -- **CS1939** - *Cannot pass the range variable as an `out` or `ref` parameter* -- **CS1988** - *Async methods cannot have `ref`, `in` or `out` parameters* -- **CS7084** - *A Windows Runtime event may not be passed as an `out` or `ref` parameter.* -- **CS8325** - *'await' cannot be used in an expression containing a `ref` conditional operator* -- **CS8326** - *Both conditional operator values must be ref values or neither may be a ref value* -- **CS8327** - *The expression must be of correct type to match the alternative ref value* -- **CS8337** - *The first parameter of a '`ref`' extension method must be a value type or a generic type constrained to struct.* -- **CS8338** - *The first '`in`' or '`ref readonly`' parameter of the extension method must be a concrete (non-generic) value type.* -- **CS8977** - *Cannot use '`ref`', '`in`', or '`out`' in the signature of a method attributed with 'UnmanagedCallersOnly'.* -- **CS9072** - *A deconstruction variable cannot be declared as a ref local* -- **CS9199** - *A `ref readonly` parameter cannot have the Out attribute.* +- **CS0631**: *`ref` and `out` are not valid in this context* +- **CS0767**: *Cannot inherit interface with the specified type parameters because it causes method to contain overloads which differ only on `ref` and `out`* +- **CS1623**: *Iterators cannot have `ref`, `in` or `out` parameters* +- **CS1741**: *A `ref` or `out` parameter cannot have a default value* +- **CS1939**: *Cannot pass the range variable as an `out` or `ref` parameter* +- **CS1988**: *Async methods cannot have `ref`, `in` or `out` parameters* +- **CS7084**: *A Windows Runtime event may not be passed as an `out` or `ref` parameter.* +- **CS8325**: *'await' cannot be used in an expression containing a `ref` conditional operator* +- **CS8326**: *Both conditional operator values must be ref values or neither may be a ref value* +- **CS8327**: *The expression must be of correct type to match the alternative ref value* +- **CS8337**: *The first parameter of a '`ref`' extension method must be a value type or a generic type constrained to struct.* +- **CS8338**: *The first '`in`' or '`ref readonly`' parameter of the extension method must be a concrete (non-generic) value type.* +- **CS8977**: *Cannot use '`ref`', '`in`', or '`out`' in the signature of a method attributed with 'UnmanagedCallersOnly'.* +- **CS9072**: *A deconstruction variable cannot be declared as a ref local* +- **CS9104**: *A `using` statement resource of type cannot be used in async methods or async lambda expressions.* +- **CS9199**: *A `ref readonly` parameter cannot have the Out attribute.* The following warnings indicate that a reference variable shouldn't be used, and might be unsafe: -- **CS9184** - *'Inline arrays' language feature is not supported for inline array types with element field which is either a '`ref`' field, or has type that is not valid as a type argument.* -- **CS9196** - *Reference kind modifier of parameter doesn't match the corresponding parameter in overridden or implemented member.* -- **CS9197** - *Reference kind modifier of parameter doesn't match the corresponding parameter in hidden member.* -- **CS9198** - *Reference kind modifier of parameter doesn't match the corresponding parameter in target.* -- **CS9200** - *A default value is specified for `ref readonly` parameter, but `ref readonly` should be used only for references. Consider declaring the parameter as `in`.* -- **CS9201** - *Ref field should be ref-assigned before use.* +- **CS9196**: *Reference kind modifier of parameter doesn't match the corresponding parameter in overridden or implemented member.* +- **CS9197**: *Reference kind modifier of parameter doesn't match the corresponding parameter in hidden member.* +- **CS9198**: *Reference kind modifier of parameter doesn't match the corresponding parameter in target.* +- **CS9200**: *A default value is specified for `ref readonly` parameter, but `ref readonly` should be used only for references. Consider declaring the parameter as `in`.* +- **CS9201**: *Ref field should be ref-assigned before use.* To fix the error, remove the reference variable where it isn't allowed: @@ -281,6 +268,7 @@ To fix the error, remove the reference variable where it isn't allowed: - Remove the `ref` modifier from the first parameter of a [extension method](../../programming-guide/classes-and-structs/extension-methods.md) where that type isn't a value type or a generic type constrained as a value type. - Either both or neither [conditional operator expressions] must be `ref` variables. Either remove `ref` from one expression, or add it to the other. If it's a `ref` conditional expression, both expressions must be the same type. - `ref` and `out` parameters can't have [default values](../../programming-guide/classes-and-structs/named-and-optional-arguments.md). Either remove the `ref` or `out` modifier, or remove the default value. +- You can't put reference variables in a `using` statement in `async` methods lambda expressions. - The range variable in a [LINQ query expression](../../linq/query-expression-basics.md) can't be passed by reference. - You can't deconstruct an object into reference variables. Replace the reference variables with value variables. - You can't implement multiple interfaces where method overloads differ only on `ref` and `out`. For example, one interface declares `void M(ref int i)` and another interface declares `void M(out int i)`. A class can't implement both interfaces because the methods aren't distinguishable. You can only implement one of those interfaces. @@ -288,39 +276,46 @@ To fix the error, remove the reference variable where it isn't allowed: - A Windows runtime event can't be passed as a reference variable. - A `ref readonly` parameter can't have the applied to it in remoting API. +## `unscoped ref` restrictions + +The `unscoped` qualifier on `ref` parameters isn't allowed in some locations: + +- **CS9101**: *UnscopedRefAttribute can only be applied to struct instance methods and properties, and cannot be applied to constructors or or init-only members.* +- **CS9102**: *UnscopedRefAttribute cannot be applied to an interface implementation.* + +You must remove the `unscoped` modifier on the parameter declaration that caused the error. + ## Reference variables require a referent You must supply a variable as an argument to a reference parameter, reference return, or ref local assignment: -- **CS0206** - *A non ref-returning property or indexer may not be used as an `out` or `ref` value* -- **CS1510** - *A `ref` or `out` value must be an assignable variable* +- **CS0206**: *A non ref-returning property or indexer may not be used as an `out` or `ref` value* +- **CS1510**: *A `ref` or `out` value must be an assignable variable* Warnings: -- **CS9191** - *The `ref` modifier for argument corresponding to `in` parameter is equivalent to `in`. Consider using `in` instead.* -- **CS9192** - *Argument should be passed with `ref` or `in` keyword.* -- **CS9193** - *Argument should be a variable because it is passed to a `ref readonly` parameter* -- **CS9195** - *Argument should be passed with the `in` keyword* +- **CS9191**: *The `ref` modifier for argument corresponding to `in` parameter is equivalent to `in`. Consider using `in` instead.* +- **CS9192**: *Argument should be passed with `ref` or `in` keyword.* +- **CS9193**: *Argument should be a variable because it is passed to a `ref readonly` parameter* +- **CS9195**: *Argument should be passed with the `in` keyword* -When the compiler emits one of these errors, you've used an expression that calculates a value where a variable must be used. You must store the result of that expression in a variable to use it. For example, properties and indexers return values, not variables. You must store the result in a variable and pass a reference to that variable. +The compiler emits these errors when you use an expression that calculates a value where a variable must be used. You must store the result of that expression in a variable to use it. For example, properties and indexers return values, not variables. You must store the result in a variable and pass a reference to that variable. ## Writable reference variables require a writable referent -A writable reference variable requires that the referent also be writable. The following errors indicate that the variable isn't writable: - -- **CS0192** - *A `readonly` field cannot be used as a `ref` or `out` value (except in a constructor)* -- **CS0199** - *A `static readonly` field cannot be used as a `ref` or `out` value (except in a static constructor)* -- **CS1605** - *Cannot use variable as a `ref` or `out` value because it is read-only* -- **CS1649** - *Members of a `readonly` field cannot be used as a `ref` or `out` value (except in a constructor)* -- **CS1651** - *Fields of a `static readonly` field cannot be used as a `ref` or `out` value (except in a static constructor)* -- **CS1655** - *Cannot use fields of type as a `ref` or `out` value* -- **CS1657** - *Cannot use variable as a `ref` or `out` value* -- **CS8329** - *Cannot use variable as a `ref` or `out` value because it is a readonly variable* -- **CS8330** - *Members of variable cannot be used as a `ref` or `out` value because it is a readonly variable* -- **CS8331** - *Cannot assign to variable or use it as the right hand side of a `ref` assignment because it is a readonly variable* -- **CS8332** - *Cannot assign to a member of variable or use it as the right hand side of a `ref` assignment because it is a readonly variable* -- **CS9116** - *A primary constructor parameter of a `readonly` type cannot be used as a `ref` or `out` value (except in init-only setter of the type or a variable initializer)* -- **CS9119** - *Members of primary constructor parameter of a readonly type cannot be used as a `ref` or `out` value (except in init-only setter of the type or a variable initializer)* +A writable reference variable requires that the referent also is writable. The following errors indicate that the variable isn't writable: + +- **CS0192**: *A `readonly` field cannot be used as a `ref` or `out` value (except in a constructor)* +- **CS0199**: *A `static readonly` field cannot be used as a `ref` or `out` value (except in a static constructor)* +- **CS1605**: *Cannot use variable as a `ref` or `out` value because it is read-only* +- **CS1649**: *Members of a `readonly` field cannot be used as a `ref` or `out` value (except in a constructor)* +- **CS1651**: *Fields of a `static readonly` field cannot be used as a `ref` or `out` value (except in a static constructor)* +- **CS1655**: *Cannot use fields of type as a `ref` or `out` value* +- **CS1657**: *Cannot use variable as a `ref` or `out` value* +- **CS8329**: *Cannot use variable as a `ref` or `out` value because it is a readonly variable* +- **CS8330**: *Members of variable cannot be used as a `ref` or `out` value because it is a readonly variable* +- **CS8331**: *Cannot assign to variable or use it as the right hand side of a `ref` assignment because it is a readonly variable* +- **CS8332**: *Cannot assign to a member of variable or use it as the right hand side of a `ref` assignment because it is a readonly variable* Examples of variables that aren't writable include: @@ -334,33 +329,31 @@ You must copy the value and pass a reference to the copy. ## Ref safety violations -The compiler tracks the safe context of referents and reference variables. The compiler issues errors, or warnings in unsafe code, when a reference variable refers to a referent variable that's no longer valid. The reference variable can't refer to a variable that has been reclaimed while the reference variable is still valid. - -- **CS8166** - *Cannot return a parameter by reference because it is not a `ref` parameter* -- **CS8167** - *Cannot return by reference a member of parameter because it is not a `ref` or `out` parameter* -- **CS8168** - *Cannot return local by reference because it is not a ref local* -- **CS8169** - *Cannot return a member of local variable by reference because it is not a ref local* -- **CS8345** - *Field or auto-implemented property cannot be of type unless it is an instance member of a `ref struct`.* -- **CS8351** - *Branches of a `ref` conditional operator cannot refer to variables with incompatible declaration scopes* -- **CS8374** - *Cannot ref-assign source has a narrower escape scope than destination.* -- **CS9077** - *Cannot return a parameter by reference through a `ref` parameter; it can only be returned in a return statement* -- **CS9078** - *Cannot return by reference a member of parameter through a `ref` parameter; it can only be returned in a return statement* -- **CS9079** - *Cannot ref-assign source to destination because source can only escape the current method through a return statement.* -- **CS9096** - *Cannot ref-assign source to destination because source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* -- **CS9109** - *Cannot use `ref`, `out`, or `in` primary constructor parameter inside an instance member* -- **CS9110** - *Cannot use primary constructor parameter that has ref-like type inside an instance member* +The compiler tracks the safe context of referents and reference variables. The compiler issues errors, or warnings in unsafe code, when a reference variable refers to a referent variable that's no longer valid. The referent must have a safe context that is at least as wide as the ref safe context of The reference variable. Violating these safety checks means the reference variable accesses random memory instead of the referent variable. + +- **CS8166**: *Cannot return a parameter by reference because it is not a `ref` parameter* +- **CS8167**: *Cannot return by reference a member of parameter because it is not a `ref` or `out` parameter* +- **CS8168**: *Cannot return local by reference because it is not a ref local* +- **CS8169**: *Cannot return a member of local variable by reference because it is not a ref local* +- **CS8345**: *Field or auto-implemented property cannot be of type unless it is an instance member of a `ref struct`.* +- **CS8351**: *Branches of a `ref` conditional operator cannot refer to variables with incompatible declaration scopes* +- **CS8374**: *Cannot ref-assign source has a narrower escape scope than destination.* +- **CS9077**: *Cannot return a parameter by reference through a `ref` parameter; it can only be returned in a return statement* +- **CS9078**: *Cannot return by reference a member of parameter through a `ref` parameter; it can only be returned in a return statement* +- **CS9079**: *Cannot ref-assign source to destination because source can only escape the current method through a return statement.* +- **CS9096**: *Cannot ref-assign source to destination because source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* Warnings: -- **CS9085** - *This ref-assigns source to destination but source has a narrower escape scope than destination.* -- **CS9086** - *The branches of the ref conditional operator refer to variables with incompatible declaration scopes* -- **CS9087** - *This returns a parameter by reference but it is not a `ref` parameter* -- **CS9089** - *This returns by reference a member of parameter that is not a `ref` or `out` parameter* -- **CS9091** - *This returns local by reference but it is not a ref local* -- **CS9092** - *This returns a member of local by reference but it is not a ref local* -- **CS9093** - *This ref-assigns source to destination but source can only escape the current method through a return statement.* -- **CS9094** - *This returns a parameter by reference through a `ref` parameter; but it can only safely be returned in a return statement* -- **CS9095** - *This returns by reference a member of parameter through a `ref` parameter; but it can only safely be returned in a return statement* -- **CS9097** - *This ref-assigns source to destination but source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* +- **CS9085**: *This ref-assigns source to destination but source has a narrower escape scope than destination.* +- **CS9086**: *The branches of the ref conditional operator refer to variables with incompatible declaration scopes* +- **CS9087**: *This returns a parameter by reference but it is not a `ref` parameter* +- **CS9089**: *This returns by reference a member of parameter that is not a `ref` or `out` parameter* +- **CS9091**: *This returns local by reference but it is not a ref local* +- **CS9092**: *This returns a member of local by reference but it is not a ref local* +- **CS9093**: *This ref-assigns source to destination but source can only escape the current method through a return statement.* +- **CS9094**: *This returns a parameter by reference through a `ref` parameter; but it can only safely be returned in a return statement* +- **CS9095**: *This returns by reference a member of parameter through a `ref` parameter; but it can only safely be returned in a return statement* +- **CS9097**: *This ref-assigns source to destination but source has a wider value escape scope than destination allowing assignment through destination of values with narrower escapes scopes than source.* The compiler uses static analysis to determine if the referent is valid at all points where the reference variable can be used. You need to refactor code so that the referent remains valid at all locations where the reference variable might refer to it. For details on the rules for ref safety, see the C# standard on [ref safe contexts](~/_csharpstandard/standard/variables.md#972-ref-safe-contexts). diff --git a/docs/csharp/language-reference/compiler-messages/source-generator-errors.md b/docs/csharp/language-reference/compiler-messages/source-generator-errors.md index 24f0ed9b8ca3b..cb20061e8ea8b 100644 --- a/docs/csharp/language-reference/compiler-messages/source-generator-errors.md +++ b/docs/csharp/language-reference/compiler-messages/source-generator-errors.md @@ -1,6 +1,6 @@ --- title: Errors and warnings associated with source generators and interceptors -description: You may see these errors and warnings when code is compiled with source generators and interceptors. They indicate some condition where the compiler can't run the source generator, or the generate code isn't compilable. +description: You might see these errors and warnings when code is compiled with source generators and interceptors. They indicate some condition where the compiler can't run the source generator, or the generate code isn't compilable. f1_keywords: - "CS9137" - "CS9138" @@ -27,6 +27,10 @@ f1_keywords: - "CS9159" - "CS9160" - "CS9161" + - "CS9177" + - "CS9178" + - "CS9206" + - "CS9207" helpviewer_keywords: - "CS9137" - "CS9138" @@ -53,11 +57,15 @@ helpviewer_keywords: - "CS9159" - "CS9160" - "CS9161" -ms.date: 06/28/2023 + - "CS9177" + - "CS9178" + - "CS9206" + - "CS9207" +ms.date: 11/02/2023 --- # Errors and warnings associated with source generators and interceptors -The following errors may be generated when source generators or interceptors are loaded during a compilation: +The following errors are generated when source generators or interceptors are loaded during a compilation: - [**CS9137**](#interceptors-are-experimental): *The 'interceptors' experimental feature is not enabled. Add `InterceptorsPreview` to your project.* - [**CS9138**](#other-failures): *Method cannot be used as an interceptor because it or its containing type has type parameters.* @@ -81,8 +89,12 @@ The following errors may be generated when source generators or interceptors are - [**CS9157**](#incorrect-mapping): *Line and character numbers provided to `InterceptsLocationAttribute` must be positive.* - [**CS9160**](#other-failures): *A nameof operator cannot be intercepted.* - [**CS9161**](#other-failures): *An interceptor cannot be marked with `UnmanagedCallersOnlyAttribute`.* +- [**CS9177**](#signature-mismatch): *Interceptor must be non-generic or have matching arity.* +- [**CS9178**](#signature-mismatch): *Method must be non-generic to match* +- [**CS9206**](#other-failures): *An interceptor cannot be declared in the global namespace.* +- [**CS9207**](#other-failures): *Cannot intercept because method is not an invocation of an ordinary member method.* -The following warnings may be generated when source generators or interceptors are loaded during a compilation: +The following warnings are generated when source generators or interceptors are loaded during a compilation: - [**CS9154**](#signature-mismatch): *Intercepting a call to `M` with interceptor `V`, but the signatures do not match.* - [**CS9158**](#signature-mismatch): *Nullability of reference types in return type doesn't match interceptable method.* @@ -92,13 +104,13 @@ These errors and warnings follow these themes: ## Interceptors are experimental -This error indicates you haven't enabled the experimental feature. +This error indicates you must enable the experimental feature. - **CS9137**: *The 'interceptors' experimental feature is not enabled. Add `InterceptorsPreview` to your project.* -In C# 12, interceptors are experimental. Interceptors may be subject to breaking changes or removal in a future release. Therefore, it is not recommended for production or released applications. +In C# 12, interceptors are experimental. Interceptors are subject to breaking changes or removal in a future release. Therefore, it is not recommended for production or released applications. -In order to use interceptors, you'll need to set the `InterceptorsPreview` element in your project file. Without this flag, interceptors are disabled, even when other C# 12 features are enabled. +In order to use interceptors, you must set the `InterceptorsPreview` element in your project file. Without this flag, interceptors are disabled, even when other C# 12 features are enabled. ## Signature mismatch @@ -109,6 +121,8 @@ The following errors indicate a mismatch between the interceptor method and the - **CS9149**: *Interceptor must not have a `this` parameter because method does not have a `this` parameter.* - **CS9155**: *Cannot intercept call with `M` because it is not accessible within `V`.* - **CS9156**: *Cannot intercept call to `M` with `V` because of a difference in 'scoped' modifiers or `[UnscopedRef]` attributes.* +- **CS9177**]: *Interceptor must be non-generic or have matching arity.* +- **CS9178**: *Method must be non-generic to match* In addition, the following warnings indicate a mismatch in the signatures of the interceptor and the interceptable method: @@ -121,10 +135,11 @@ The interceptor method must be compatible with the interceptable method. You mus - Instance methods can intercept instance methods, not static methods. Similarly, static methods can only intercept static methods, not instance methods. - The method signatures for the interceptor and the interceptable method must match: They must have the same parameters with the same modifiers in the same order. The return types must also match. - The ref safe contexts must match. In other words, corresponding `ref` parameters must be either `scoped` or not `scoped`. +- They methods must both be non-generic, or both must have the same number of type parameters. ## Incorrect mapping -Interceptors require a source mapping that maps the interceptable method and the interceptor method. The following error indicate an issue with the mapping: +Interceptors require a source mapping that maps the interceptable method and the interceptor method. The following errors indicate an issue with the mapping: - **CS9139**: *Cannot intercept: compilation does not contain a file with path.* - **CS9140**: *Cannot intercept: compilation does not contain a file with path. Did you mean to use a different path?* @@ -149,11 +164,15 @@ These errors indicate other limitations for interceptors: - **CS9153**: *The indicated call is intercepted multiple times.* - **CS9160**: *A nameof operator cannot be intercepted.* - **CS9161**: *An interceptor cannot be marked with `UnmanagedCallersOnlyAttribute`.* +- **CS9206**: *An interceptor cannot be declared in the global namespace.* +- **CS9207**: *Cannot intercept because method is not an invocation of an ordinary member method.* These errors indicate that your interceptor method violates one of the rules for interceptors: - Interceptors can't be generic methods, or members of generic classes. - Interceptors must be ordinary members. They can't be operators, instance or static constructors, or finalizers. +- Interceptable methods must be ordinary members. They can't be operators, instance or static constructors, or finalizers, nor delegate invocations. - Interceptable methods that are never invoked can't be intercepted. - Interceptable methods can be intercepted at most once. - Interceptors can't be methods limited to unmanaged callers. +- Interceptors must be contained in a namespace. diff --git a/docs/csharp/language-reference/compiler-messages/toc.yml b/docs/csharp/language-reference/compiler-messages/toc.yml index 740fb24b4b2ba..5bd1b63288047 100644 --- a/docs/csharp/language-reference/compiler-messages/toc.yml +++ b/docs/csharp/language-reference/compiler-messages/toc.yml @@ -1872,17 +1872,24 @@ items: displayName: > CS0171, CS0188, CS0843, CS8904, CS1738, CS8022, CS8023, CS8024, CS8025, CS8026, CS8058, CS8059, CS8107, CS8192, CS8302, CS8303, CS8304, CS8305, CS8306, CS8314, CS8320, CS8370, CS8371, CS8400, CS8401, CS8511, CS8627, CS8630, CS8652, CS8703, - CS8704, CS8706, CS8773, CS8912, CS8936, CS8957, CS8967, CS9014, CS9015, CS9016, CS9017, CS9058, CS9064, CS9194, CS9204 + CS8704, CS8706, CS8773, CS8912, CS8936, CS8957, CS8967, CS9014, CS9015, CS9016, CS9017, CS9058, CS9064, CS9103, CS9171, + CS9194, CS9202, CS9204 - name: Constructor declarations href: constructor-errors.md displayName: > Primary constructors, CS0514, CS0515, CS0516, CS0517, CS0522, CS0526, CS0568, CS0710, CS0768, CS0824, CS8054, CS8091, CS8358, CS8862, CS8867, CS8868, CS8878, CS8910, CS8958, CS8982, CS8983, CS9105, CS9106, CS9107, CS9108, CS9109, CS9110, CS9111, CS9112, CS9113, - CS9114, CS9115, CS9116, CS9117, CS9118, CS9119, CS9120, CS9121, CS9122 + CS9114, CS9115, CS9116, CS9117, CS9118, CS9119, CS9120, CS9121, CS9122, CS9124, CS9136, CS9179 - name: Reference parameters href: ref-modifiers-errors.md - displayName: CS9190, CS9191, CS9192, CS9193, CS9195, CS9196, CS9197, CS9198, CS9199, CS9200 + displayName: > + ref safety, + CS0192, CS0199, CS0206, CS0631, CS0767, CS1510, CS1605, CS1623, CS1649, CS1651, CS1655, CS1657, CS1741, CS1939, CS1988, + CS7084, CS8166, CS8167, CS8168, CS8169. CS8325, CS8326, CS8327, CS8329, CS8330, CS8331, CS8332, CS8337, CS8338, CS8345, + CS8351, CS8373, CS8374, CS8388, CS8977, CS9072, CS9077, CS9078, CS9079, CS9085, CS9086, CS9087, CS9089, CS9091, CS9092, + CS9093, CS9094, CS9095, CS9096, CS9097, CS9101, CS9102, CS9104, CS9190, CS9191, CS9192, CS9193, CS9195, CS9196, CS9197, + CS9198, CS9199, CS9200, CS9201 - name: Nullable warnings href: nullable-warnings.md displayName: > @@ -1892,20 +1899,21 @@ items: CS8776, CS8775, CS8777, CS8819, CS8824, CS8825, CS8847 - name: Pattern matching warnings href: pattern-matching-warnings.md - displayName: CS8509 + displayName: CS8509, CS9134, CS9135 - name: Array declarations href: array-declaration-errors.md displayName: > CS0022, CS0178, CS0248, CS0251, CS0270, CS0611, CS0623, CS0650, CS0719, CS0747, CS0820, CS0826, CS0846, CS1552, CS1586, - CS1920, CS1921, CS1925, CS1954, CS3007, CS3016, CS9174, CS9176 + CS1920, CS1921, CS1925, CS1954, CS3007, CS3016, CS9174, CS9176, CS9185, CS9186, CS9187, CS9188, CS9203, CS9208, CS9209, + CS9210 - name: Inline arrays href: inline-array-errors.md - displayName: CS9164, CS9165, CS9166, CS9167, CS9168, CS9169, CS9172, CS9173 + displayName: CS9164, CS9165, CS9166, CS9167, CS9168, CS9169, CS9172, CS9173, CS9180, CS9181, CS9182, CS9183, CS9184 - name: Lambda expressions href: lambda-expression-errors.md displayName: > CS0748, CS1621, CS1628, CS1632, CS1673, CS1686, CS1706, CS1989, CS8030, CS8175, CS8916, CS8971, CS8972, CS8975, CS9098, - CS9099, CS9100, CS9108 + CS9099, CS9100 - name: Restrictions on expression trees href: expression-tree-restrictions.md displayName: > @@ -1916,12 +1924,12 @@ items: href: using-directive-errors.md displayName: > CS0105, CS0138, CS0431, CS0432, CS0440, CS0576, CS0687, CS1529, CS1537, CS7000, CS7007, CS8019, CS8083, CS8085, CS8914, - CS8915, CS8933, CS9055, CS9130, CS9131, CS9132, CS9133 + CS8915, CS8933, CS9055, CS9130, CS9131, CS9132, CS9133, CS9162, CS9163 - name: Source generators href: source-generator-errors.md displayName: > CS9137, CS9138, CS9139, CS9140, CS9141, CS9142, CS9143, CS9144, CS9145, CS9146, CS9147, CS9148, CS9149, CS9150, CS9151, - CS9152, CS9153, CS9154, CS9155, CS9156, CS9157, CS9158, CS9159, CS9160, CS9161 + CS9152, CS9153, CS9154, CS9155, CS9156, CS9157, CS9158, CS9159, CS9160, CS9161, CS9177, CS9178, CS9206, CS9207 - name: Warning waves href: warning-waves.md displayName: > diff --git a/docs/csharp/language-reference/compiler-messages/using-directive-errors.md b/docs/csharp/language-reference/compiler-messages/using-directive-errors.md index 99ff2e3d1930c..9dcaef6fe12bb 100644 --- a/docs/csharp/language-reference/compiler-messages/using-directive-errors.md +++ b/docs/csharp/language-reference/compiler-messages/using-directive-errors.md @@ -1,7 +1,7 @@ --- title: "Resolve compiler errors and warnings related to using directives and using alias directives" description: "These errors and warnings indicate problems with using directives and using directive aliases. This information helps diagnose and fix those issues." -ms.date: 04/25/2023 +ms.date: 11/02/2023 f1_keywords: - "CS0105" - "CS0138" @@ -25,6 +25,8 @@ f1_keywords: - "CS9131" - "CS9132" - "CS9133" + - "CS9162" + - "CS9163" helpviewer_keywords: - "CS0105" - "CS0138" @@ -48,6 +50,8 @@ helpviewer_keywords: - "CS9131" - "CS9132" - "CS9133" + - "CS9162" + - "CS9163" --- # Resolve warnings related using namespaces @@ -56,31 +60,32 @@ This article covers the following compiler errors: -- [**CS0138**](#using-static-directive) - *Error: A using namespace directive can only be applied to namespaces; 'type' is a type not a namespace.* -- [**CS0431**](#alias-qualifier) - *Error: Cannot use alias 'identifier' with `::` since the alias references a type. Use `.` instead*. -- [**CS0432**](#alias-qualifier) - *Error: Alias 'identifier' not found.* -- [**CS0576**](#alias-name-conflicts) - *Error: Namespace 'namespace' contains a definition conflicting with alias 'identifier'.* -- [**CS0687**](#alias-qualifier) - *Error: The namespace alias qualifier `::` always resolves to a type or namespace so is illegal here. Consider using `.` instead.* -- [**CS1529**](#using-directive) - *Error: A using clause must precede all other elements defined in the namespace except extern alias declarations.* -- [**CS1537**](#alias-name-conflicts) - *Error: The using alias 'alias' appeared previously in this namespace.* -- [**CS7000**](#alias-qualifier) - *Error: Unexpected use of an aliased name.* -- [**CS7007**](#using-static-directive) - *Error: A `using static` directive can only be applied to types. Consider a `using namespace` directive instead* -- [**CS8083**](#alias-qualifier) - *Error: An alias-qualified name is not an expression.* -- [**CS8085**](#restrictions-on-using-aliases) - *Error: A 'using static' directive cannot be used to declare an alias.* -- [**CS8914**](#global-using-directive) - *Error: A global using directive cannot be used in a namespace declaration.* -- [**CS8915**](#global-using-directive) - *Error: A global using directive must precede all non-global using directives.* -- [**CS9055**](#global-using-directive) - *Error: A file-local type cannot be used in a 'global using static' directive.* -- [**CS9130**](#restrictions-on-using-aliases) - *Error: Using alias cannot be a `ref` type.* -- [**CS9131**](#restrictions-on-using-aliases) - *Error: Only a using alias can be `unsafe`.* -- [**CS9132**](#restrictions-on-using-aliases) - *Error: Using alias cannot be a nullable reference type.* -- [**CS9133**](#using-static-directive) - *Error: `static` modifier must precede `unsafe` modifier.* +- [**CS0138**](#using-static-directive): *Error: A using namespace directive can only be applied to namespaces; 'type' is a type not a namespace.* +- [**CS0431**](#alias-qualifier): *Error: Cannot use alias 'identifier' with `::` since the alias references a type. Use `.` instead*. +- [**CS0432**](#alias-qualifier): *Error: Alias 'identifier' not found.* +- [**CS0576**](#alias-name-conflicts): *Error: Namespace 'namespace' contains a definition conflicting with alias 'identifier'.* +- [**CS0687**](#alias-qualifier): *Error: The namespace alias qualifier `::` always resolves to a type or namespace so is illegal here. Consider using `.` instead.* +- [**CS1529**](#using-directive): *Error: A using clause must precede all other elements defined in the namespace except extern alias declarations.* +- [**CS1537**](#alias-name-conflicts): *Error: The using alias 'alias' appeared previously in this namespace.* +- [**CS7000**](#alias-qualifier): *Error: Unexpected use of an aliased name.* +- [**CS7007**](#using-static-directive): *Error: A `using static` directive can only be applied to types. Consider a `using namespace` directive instead* +- [**CS8083**](#alias-qualifier): *Error: An alias-qualified name is not an expression.* +- [**CS8085**](#restrictions-on-using-aliases): *Error: A 'using static' directive cannot be used to declare an alias.* +- [**CS8914**](#global-using-directive): *Error: A global using directive cannot be used in a namespace declaration.* +- [**CS8915**](#global-using-directive): *Error: A global using directive must precede all non-global using directives.* +- [**CS9055**](#global-using-directive): *Error: A file-local type cannot be used in a 'global using static' directive.* +- [**CS9130**](#restrictions-on-using-aliases): *Error: Using alias cannot be a `ref` type.* +- [**CS9131**](#restrictions-on-using-aliases): *Error: Only a using alias can be `unsafe`.* +- [**CS9132**](#restrictions-on-using-aliases): *Error: Using alias cannot be a nullable reference type.* +- [**CS9133**](#using-static-directive): *Error: `static` modifier must precede `unsafe` modifier.* +- [**CS9162**](#using-static-directive): *Type is not valid for 'using static'. Only a class, struct, interface, enum, delegate, or namespace can be used.* And the following compiler warnings: -- [**CS0105**](#using-directive) - *Warning: The using directive for 'namespace' appeared previously in this namespace.* -- [**CS0440**](#alias-qualifier) - *Warning: Defining an alias named `global` is ill-advised since `global::` always references the global namespace and not an alias.* -- [**CS8019**](#using-directive) - *Info: Unnecessary using directive.* -- [**CS8933**](#using-directive) - *Info: The using directive appeared previously as global using.* +- [**CS0105**](#using-directive): *Warning: The using directive for 'namespace' appeared previously in this namespace.* +- [**CS0440**](#alias-qualifier): *Warning: Defining an alias named `global` is ill-advised since `global::` always references the global namespace and not an alias.* +- [**CS8019**](#using-directive): *Info: Unnecessary using directive.* +- [**CS8933**](#using-directive): *Info: The using directive appeared previously as global using.* These errors and warnings indicate you're `using` directive isn't formed correctly. The following sections cover these errors and how to correct them. @@ -101,7 +106,7 @@ To fix this issue, move any `using` declarations to the top of the file or the t :::code language="csharp" source="./snippets/UsingDirectives/MyClass.cs" id="UsingExample"::: -The compiler produces warning **CS8933**, **CS0105** or diagnostic **CS8019** for a `using` directive that's duplicated in a `using` or `global using` directive. You can remove any duplicates. +The compiler produces warning **CS8933**, **CS0105** or diagnostic **CS8019** for a duplicate `using` directive from a `using` or `global using` directive. You can remove any duplicates. Incorrectly combining a `using` directive with the `static`, `global`, or `unsafe` modifiers on a `using` directive are covered later in this article. @@ -123,6 +128,8 @@ The compiler generates **CS7007** if you include the `static` modifier importing using static System; // CS7007 ``` +The compiler emits CS9162 if the symbol isn't one of the proper types. + If you combine the `static` modifier with the `unsafe` modifier in a `using` directive, the `static` modifier must come first: :::code language="csharp" source="./snippets/UsingDirectives/Program.cs" id="UsingUnsafeStatic"::: diff --git a/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md b/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md index 28e5675586d4e..05e7df90df0c2 100644 --- a/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md +++ b/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md @@ -515,6 +515,63 @@ f1_keywords: - "CS8901" - "CS8902" - "CS8903" + - "CS8905" + - "CS8906" + - "CS8907" + - "CS8908" + - "CS8909" + - "CS8911" + # C# 10 errors start here: + - "CS8913" + - "CS8917" + - "CS8918" + - "CS8919" + - "CS8920" + - "CS8921" + - "CS8922" + - "CS8923" + - "CS8924" + - "CS8925" + - "CS8926" + - "CS8928" + - "CS8929" + - "CS8930" + - "CS8931" + - "CS8932" + - "CS8934" + - "CS8935" + - "CS8937" + - "CS8938" + - "CS8939" + - "CS8940" + - "CS8941" + - "CS8942" + - "CS8943" + - "CS8944" + - "CS8945" + - "CS8946" + - "CS8947" + - "CS8948" + - "CS8949" + - "CS8950" + - "CS8951" + - "CS8953" + - "CS8954" + - "CS8955" + - "CS8956" + - "CS8959" + - "CS8960" + - "CS8961" + - "CS8962" + - "CS8963" + - "CS8965" + - "CS8966" + - "CS8968" + - "CS8970" + - "CS8973" + - "CS8974" + - "CS8976" + # C# 11 errors start here - "CS8978" - "CS8979" - "CS8980" @@ -616,6 +673,10 @@ f1_keywords: - "CS9095" - "CS9096" - "CS9097" + # C# 12 errors begin here + - "CS9123" + - "CS9125" + - "CS9205" helpviewer_keywords: - "errors [C#], additional information" ms.assetid: 48320e4a-6e17-45a6-9966-88c6ec89bd2f From 96f77157ff58e47910fb45b75cc644a128515312 Mon Sep 17 00:00:00 2001 From: David Pine Date: Thu, 2 Nov 2023 15:37:13 -0500 Subject: [PATCH 14/20] Remove all references to `AutoClient` and add redirect. (#37876) * Remove all references to AutoClient, and add redirect * Fix warnings... --- .openpublishing.redirection.fundamentals.json | 4 + .../networking/http/http-autoclient.md | 158 ------------------ .../networking/http/httpclient.md | 3 +- docs/fundamentals/toc.yml | 3 - docs/whats-new/dotnet-docs-mod0.md | 1 - 5 files changed, 5 insertions(+), 164 deletions(-) delete mode 100644 docs/fundamentals/networking/http/http-autoclient.md diff --git a/.openpublishing.redirection.fundamentals.json b/.openpublishing.redirection.fundamentals.json index a5d1312a14d85..1516b2a94b208 100644 --- a/.openpublishing.redirection.fundamentals.json +++ b/.openpublishing.redirection.fundamentals.json @@ -519,6 +519,10 @@ { "source_path_from_root": "/docs/fundamentals/tools-and-productivity.md", "redirect_url": "/dotnet/toc/tools-diagnostics/index" + }, + { + "source_path_from_root": "/docs/fundamentals/networking/http/http-autoclient.md", + "redirect_url": "/dotnet/fundamentals/networking/http/http-overview" } ] } diff --git a/docs/fundamentals/networking/http/http-autoclient.md b/docs/fundamentals/networking/http/http-autoclient.md deleted file mode 100644 index fb9d78d0a38eb..0000000000000 --- a/docs/fundamentals/networking/http/http-autoclient.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: Use the REST API HTTP client generator -description: Learn how to generate HttpClient-dependent code implementations of AutoClient decorated interfaces. -author: IEvangelist -ms.author: dapine -ms.date: 09/29/2023 ---- - -# Use the REST API HTTP client generator - -> [!NOTE] -> This API is experimental. It might change in subsequent versions of the library, and backwards compatibility is not guaranteed. - -The is a great way to consume REST APIs, but it's not without its challenges. One of the challenges is the amount of boilerplate code you need to write to consume the API. In this article, you learn how to use the [Microsoft.Extensions.Http.AutoClient](https://www.nuget.org/packages/Microsoft.Extensions.Http.AutoClient) NuGet package to decorate an interface and generate an HTTP client dependency. The AutoClient's underlying source generator generates the implementation of your interface, along with extension methods to register it into the dependency injection container. Additionally, the AutoClient generates telemetry for each HTTP request, which is sent with . - -## Use the `AutoClientAttribute` - -The is responsible for triggering the AutoClient generator to emit the corresponding implementation of the decorated interface. It accepts the `httpClientName` of the to be retrieved from the . Consider the following interface definition: - -:::code source="snippets/autoclient/IProductClient.cs"::: - -> [!TIP] -> The interface name must start with an `I`. The name is stripped of the leading `I`, and used as the for telemetry's . If the name ends in `Api` or `Client`, those are excluded. For example, if the interface is named `IProductClient`, the dependency name is `Product`. - -To override the calculated dependency name, use the `customDependencyName` parameter of the . - -:::code source="snippets/autoclient/IWidgetClient.cs"::: - -> [!NOTE] -> Both preceding code examples result in a compilation warning, as the interface doesn't define any HTTP methods. The warning is emitted by the AutoClient generator, and it's a reminder that the emitted implementations are be useless. - -## Define HTTP methods with verb attributes - -An empty interface isn't a useful abstraction. To define HTTP methods, you must use the HTTP verb attributes. Each HTTP method returns a where `T` is any of the following types: - -| Return type | Description | -|--|--| -| `Task` | The raw content of the response is returned as a string. | -| `Task` | When `T` is any serializable type, the response content is deserialized from JSON and returned. | -| `Task` | If you need the itself, as returned from , use this type. | - -When the content type of the HTTP response isn't `application/json` and the method's return type isn't `Task`, an exception is thrown. - -### HTTP verb attributes - -An HTTP method is defined using one of the following attributes: - -- -- -- -- -- -- -- - -Each attribute requires a `path` argument that routes to the underlying REST API, and it should be relative to the . The `path` can't contain query string parameters, instead the is used. From the perspective of telemetry, the `path` is used as the . - -HTTP methods decorated with any of the verb attributes must have a parameter and it should be the last parameter defined. The `CancellationToken` parameter is used to cancel the HTTP request. - -:::code source="snippets/autoclient/IUserClient.cs"::: - -The preceding code: - -- Defines an HTTP method using the . -- The `path` is `/api/users`. -- The method returns a where `T` is `User[]`. -- The method accepts an optional parameter that is assigned to `default` when an argument isn't provided. - -### Route parameters - -The URL may contain route parameters, for example, `"/api/users/{userId}"`. To define a route parameter the method must also accept a parameter with the same name, in this case, `userId`: - -:::code source="snippets/autoclient/IRouteParameterUserClient.cs"::: - -In the preceding code: - -- The `GetUserAsync` method has a route parameter named `userId`. -- The `userId` parameter is used in the `path` of the request, replacing the `{userId}` placeholder. - -### Telemetry request name - -The method name is used as the . If the method name includes the `Async` suffix, it's removed. For example, a method named `GetUsersAsync` is calculated as `"GetUsers"`. - -To override the name, use the `RequestName` property of each attribute of the [HTTP verb attributes](#http-verb-attributes). - -:::code source="snippets/autoclient/IRequestNameUserClient.cs"::: - -## HTTP payloads - -To send an HTTP payload with your request, use the on a method's parameter. If you don't pass any parameter to it, it treats the content type as JSON, serializing your parameter before sending. Otherwise, you define an explicit - and use it within the . - -:::code source="snippets/autoclient/IPayloadUserClient.cs"::: - -## HTTP headers - -There are two ways of sending headers with your HTTP request. One of them is best suited for headers that never change value (static headers). The other way is headers that change based on the parameters of your methods. - -### Static headers - -To define a static header, use the on your interface definition. Pass the header name and value to its constructor. - -You can also use more than one together and in methods as well. When the `StaticHeader` attribute is used on a method, that HTTP header is sent for that method only, whereas the interface-level `StaticHeader` attribute is sent for all methods. - -:::code source="snippets/autoclient/IStaticHeaderUserClient.cs"::: - -### Parameter headers - -Use the to define parameter-based headers, where you can receive the value for a header from the attributes of your method. Pass the header name to its constructor. - -The parameter may be of any type. When the header type is anything other than a `string`, the `.ToString()` method is called on the value of the parameter. - -:::code source="snippets/autoclient/IParameterHeaderUserClient.cs"::: - -## Query parameters - -Query parameters are defined using the on a method's parameter. All types are valid, and the query value relies on the `.ToString()` method to get the value of the parameter when not a `string` type. - -The is assigned from the name of the parameter. - -:::code source="snippets/autoclient/IQueryUserClient.cs"::: - -The `GetUsersAsync` method generates an HTTP request with a URL formatted as `/api/users?search={search}`. This format is used as the for telemetry. - -If you need to change the query key, you may call the `key` parameter-based constructor, . - -:::code source="snippets/autoclient/ICustomQueryUserClient.cs"::: - -The `GetUsersAsync` method generates an HTTP request with a URL formatted like `/api/users?customQueryKey={customQueryKey}`, as the key name was overridden to `customQueryKey`. - -## Dependency injection hooks - -Along with the interface's implementation, extension methods are generated to register the client in the dependency injection container. The name of the generated extension method is the same as your interface name, replacing the leading `I` with `Add`. - -For example, consider the following interface definition: - -:::code source="snippets/autoclient/ICompleteUserClient.cs"::: - -While the generator emits the implementation of the `ICompleteUserClient` interface, it also generates the `AddCompleteUserClient` extension method on the `IServiceCollection`. Consider the following example _Program.cs_ code: - -:::code source="snippets/autoclient/Program.cs" id="program"::: - -In the preceding example code: - -- The is used to create a . -- The is retrieved from the property, to call the extension method. - - The `AddHttpClient` extension method is called with the name of the to be registered, and a delegate to configure the instance. -- The `AddCompleteUserClient` extension method is called to register the `ICompleteUserClient` interface and its implementation. - -You can consume the client by injecting it into your service's constructor: - -:::code source="snippets/autoclient/UserService.cs"::: - -For more information, see [.NET dependency injection](../../../core/extensions/dependency-injection.md). - -The application is expected to output the following: - -:::code source="snippets/autoclient/Program.cs" id="output"::: diff --git a/docs/fundamentals/networking/http/httpclient.md b/docs/fundamentals/networking/http/httpclient.md index 85e44f4cf685e..7adc47611539c 100644 --- a/docs/fundamentals/networking/http/httpclient.md +++ b/docs/fundamentals/networking/http/httpclient.md @@ -3,7 +3,7 @@ title: Make HTTP requests with the HttpClient description: Learn how to make HTTP requests and handle responses with the HttpClient in .NET. author: IEvangelist ms.author: dapine -ms.date: 05/19/2023 +ms.date: 11/02/2023 --- # Make HTTP requests with the HttpClient class @@ -377,5 +377,4 @@ For more information about configuring a proxy, see: - [Guidelines for using HttpClient](httpclient-guidelines.md) - [IHttpClientFactory with .NET](../../../core/extensions/httpclient-factory.md) - [Use HTTP/3 with HttpClient](../../../core/extensions/httpclient-http3.md) -- [REST API HTTP client generator](http-autoclient.md) - [Test web APIs with the HttpRepl](/aspnet/core/web-api/http-repl) diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index 8e8eb967aaa76..bd910082243a6 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -853,9 +853,6 @@ items: - name: HTTP/3 with .NET href: ../core/extensions/httpclient-http3.md displayName: networking,http,http3,http/3,http3 with .net,http/3 with .net - - name: REST API HTTP client generator - href: networking/http/http-autoclient.md - displayName: networking,http,httpclient,auto,autoclient,auto-client,source generation,source generator,httpclient source generation,httpclient source generator - name: Rate limit an HTTP handler href: ../core/extensions/http-ratelimiter.md displayName: networking,http,rate limit,rate limiting,rate limit http,rate limiting http,rate limit http handler,rate limiting http handler diff --git a/docs/whats-new/dotnet-docs-mod0.md b/docs/whats-new/dotnet-docs-mod0.md index 7c36de95c1865..a2326b0dde2ae 100644 --- a/docs/whats-new/dotnet-docs-mod0.md +++ b/docs/whats-new/dotnet-docs-mod0.md @@ -38,7 +38,6 @@ Welcome to what's new in the .NET docs for September 2023. This article lists so - [.NET runtime tiered compilation events](../fundamentals/diagnostics/runtime-tiered-compilation-events.md) - [Runtime configuration options for WPF](../core/runtime-config/wpf.md) - [Customize SNI in HTTP requests](../core/extensions/httpclient-sni.md) -- [Use the REST API HTTP client generator](../fundamentals/networking/http/http-autoclient.md) ### Updated articles From 3a77d38c0c5dc1139ae9e64a730626d7277961b1 Mon Sep 17 00:00:00 2001 From: David Pine Date: Thu, 2 Nov 2023 15:45:06 -0500 Subject: [PATCH 15/20] Added missing metrics for .NET extensions. (#37875) * Added missing metrics for .NET extensions * Apply suggestions from code review Co-authored-by: Tom Dykstra * Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Apply suggestions from code review --------- Co-authored-by: Tom Dykstra Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .../built-in-metrics-aspnetcore.md | 84 +++++++++--- .../built-in-metrics-diagnostics.md | 126 ++++++++++++++++++ .../built-in-metrics-system-net.md | 4 +- docs/core/diagnostics/built-in-metrics.md | 7 +- .../diagnostics/diagnostic-health-checks.md | 8 +- .../diagnostic-resource-monitoring.md | 8 +- docs/navigate/tools-diagnostics/toc.yml | 8 +- 7 files changed, 213 insertions(+), 32 deletions(-) create mode 100644 docs/core/diagnostics/built-in-metrics-diagnostics.md diff --git a/docs/core/diagnostics/built-in-metrics-aspnetcore.md b/docs/core/diagnostics/built-in-metrics-aspnetcore.md index 23c2f89e7ea0d..bcab619514f3a 100644 --- a/docs/core/diagnostics/built-in-metrics-aspnetcore.md +++ b/docs/core/diagnostics/built-in-metrics-aspnetcore.md @@ -1,41 +1,81 @@ --- -title: ASP.NET Core Metrics +title: ASP.NET Core metrics description: Review the metrics available for ASP.NET Core ms.topic: reference -ms.date: 10/16/2023 +ms.date: 11/02/2023 --- -# ASP.NET Core Metrics +# ASP.NET Core metrics This article describes the metrics built-in for ASP.NET Core produced using the API. For a listing of metrics based on the older [EventCounters](event-counters.md) API, see [here](available-counters.md). +- [Meter: `Microsoft.AspNetCore.HeaderParsing`](#meter-microsoftaspnetcoreheaderparsing) + - [Instrument: `aspnetcore.header_parsing.parse_errors`](#instrument-aspnetcoreheader_parsingparse_errors) + - [Instrument: `aspnetcore.header_parsing.cache_accesses`](#instrument-aspnetcoreheader_parsingcache_accesses) - [Meter: `Microsoft.AspNetCore.Hosting`](#meter-microsoftaspnetcorehosting) - * [Instrument: `http.server.request.duration`](#instrument-httpserverrequestduration) - * [Instrument: `http.server.active_requests`](#instrument-httpserveractive_requests) + - [Instrument: `http.server.request.duration`](#instrument-httpserverrequestduration) + - [Instrument: `http.server.active_requests`](#instrument-httpserveractive_requests) - [Meter: `Microsoft.AspNetCore.Routing`](#meter-microsoftaspnetcorerouting) - * [Instrument: `aspnetcore.routing.match_attempts`](#instrument-aspnetcoreroutingmatch_attempts) + - [Instrument: `aspnetcore.routing.match_attempts`](#instrument-aspnetcoreroutingmatch_attempts) - [Meter: `Microsoft.AspNetCore.Diagnostics`](#meter-microsoftaspnetcorediagnostics) - * [Instrument: `aspnetcore.diagnostics.exceptions`](#instrument-aspnetcorediagnosticsexceptions) + - [Instrument: `aspnetcore.diagnostics.exceptions`](#instrument-aspnetcorediagnosticsexceptions) - [Meter: `Microsoft.AspNetCore.RateLimiting`](#meter-microsoftaspnetcoreratelimiting) - * [Instrument: `aspnetcore.rate_limiting.active_request_leases`](#instrument-aspnetcorerate_limitingactive_request_leases) - * [Instrument: `aspnetcore.rate_limiting.request_lease.duration`](#instrument-aspnetcorerate_limitingrequest_leaseduration) - * [Instrument: `aspnetcore.rate_limiting.queued_requests`](#instrument-aspnetcorerate_limitingqueued_requests) - * [Instrument: `aspnetcore.rate_limiting.request.time_in_queue`](#instrument-aspnetcorerate_limitingrequesttime_in_queue) - * [Instrument: `aspnetcore.rate_limiting.requests`](#instrument-aspnetcorerate_limitingrequests) + - [Instrument: `aspnetcore.rate_limiting.active_request_leases`](#instrument-aspnetcorerate_limitingactive_request_leases) + - [Instrument: `aspnetcore.rate_limiting.request_lease.duration`](#instrument-aspnetcorerate_limitingrequest_leaseduration) + - [Instrument: `aspnetcore.rate_limiting.queued_requests`](#instrument-aspnetcorerate_limitingqueued_requests) + - [Instrument: `aspnetcore.rate_limiting.request.time_in_queue`](#instrument-aspnetcorerate_limitingrequesttime_in_queue) + - [Instrument: `aspnetcore.rate_limiting.requests`](#instrument-aspnetcorerate_limitingrequests) - [Meter: `Microsoft.AspNetCore.Server.Kestrel`](#meter-microsoftaspnetcoreserverkestrel) - * [Instrument: `kestrel.active_connections`](#instrument-kestrelactive_connections) - * [Instrument: `kestrel.connection.duration`](#instrument-kestrelconnectionduration) - * [Instrument: `kestrel.rejected_connections`](#instrument-kestrelrejected_connections) - * [Instrument: `kestrel.queued_connections`](#instrument-kestrelqueued_connections) - * [Instrument: `kestrel.queued_requests`](#instrument-kestrelqueued_requests) - * [Instrument: `kestrel.upgraded_connections`](#instrument-kestrelupgraded_connections) - * [Instrument: `kestrel.tls_handshake.duration`](#instrument-kestreltls_handshakeduration) - * [Instrument: `kestrel.active_tls_handshakes`](#instrument-kestrelactive_tls_handshakes) + - [Instrument: `kestrel.active_connections`](#instrument-kestrelactive_connections) + - [Instrument: `kestrel.connection.duration`](#instrument-kestrelconnectionduration) + - [Instrument: `kestrel.rejected_connections`](#instrument-kestrelrejected_connections) + - [Instrument: `kestrel.queued_connections`](#instrument-kestrelqueued_connections) + - [Instrument: `kestrel.queued_requests`](#instrument-kestrelqueued_requests) + - [Instrument: `kestrel.upgraded_connections`](#instrument-kestrelupgraded_connections) + - [Instrument: `kestrel.tls_handshake.duration`](#instrument-kestreltls_handshakeduration) + - [Instrument: `kestrel.active_tls_handshakes`](#instrument-kestrelactive_tls_handshakes) - [Meter: `Microsoft.AspNetCore.Http.Connections`](#meter-microsoftaspnetcorehttpconnections) - * [Instrument: `signalr.server.connection.duration`](#instrument-signalrserverconnectionduration) - * [Instrument: `signalr.server.active_connections`](#instrument-signalrserveractive_connections) + - [Instrument: `signalr.server.connection.duration`](#instrument-signalrserverconnectionduration) + - [Instrument: `signalr.server.active_connections`](#instrument-signalrserveractive_connections) + +## Meter: `Microsoft.AspNetCore.HeaderParsing` + +### Instrument: `aspnetcore.header_parsing.parse_errors` + +| Name | Instrument Type | Unit (UCUM) | Description | +|--|--|--|--| +| `aspnetcore.header_parsing.parse_errors` | Counter | `{parse_error}` | Number of errors that occurred when parsing HTTP request headers. | + +| Attribute | Type | Description | Examples | Presence | +|--|--|--|--|--| +| `aspnetcore.header_parsing.header.name` | string | The header name. | `Content-Type` | Always | +| `error.type` | string | The error message. | `Unable to parse media type value.` | Always | + +Available starting in: .NET 8.0. + +### Instrument: `aspnetcore.header_parsing.cache_accesses` + +The metric is emitted only for HTTP request header parsers that support caching. + +| Name | Instrument Type | Unit (UCUM) | Description | +| ---- | --------------- | ----------- | ----------- | +| `aspnetcore.header_parsing.cache_accesses` | Counter | `{cache_access}` | Number of times a cache storing parsed header values was accessed. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.header_parsing.header.name` | string | The header name. | `Content-Type` | Always | +| `aspnetcore.header_parsing.cache_access.type` | string | A value indicating whether the header's value was found in the cache or not. | `Hit`; `Miss` | Always | + +`aspnetcore.header_parsing.cache_access.type` is one of the following: + +| Value | Description | +|---|---| +| `Hit` | The header's value was found in the cache. | +| `Miss` | The header's value wasn't found in the cache. | + +Available starting in: .NET 8.0. ## Meter: `Microsoft.AspNetCore.Hosting` diff --git a/docs/core/diagnostics/built-in-metrics-diagnostics.md b/docs/core/diagnostics/built-in-metrics-diagnostics.md new file mode 100644 index 0000000000000..f8a86199d46a8 --- /dev/null +++ b/docs/core/diagnostics/built-in-metrics-diagnostics.md @@ -0,0 +1,126 @@ +--- +title: .NET extensions metrics +description: Review the metrics available for diagnostic .NET extensions libraries. +ms.topic: reference +ms.date: 11/02/2023 +--- + +# .NET extensions metrics + +This article describes the built-in metrics for diagnostic .NET extensions libraries that are produced using the + API. For a listing of metrics based on the older [EventCounters](event-counters.md) API, see [Available counters](available-counters.md). + +- [Meter: `Microsoft.Extensions.Diagnostics.HealthChecks`](#meter-microsoftextensionsdiagnosticshealthchecks) + - [Instrument: `dotnet.health_check.reports`](#instrument-dotnethealth_checkreports) + - [Instrument: `dotnet.health_check.unhealthy_checks`](#instrument-dotnethealth_checkunhealthy_checks) +- [Meter: `Microsoft.Extensions.Diagnostics.ResourceMonitoring`](#meter-microsoftextensionsdiagnosticsresourcemonitoring) + - [Instrument: `process.cpu.utilization`](#instrument-processcpuutilization) + - [Instrument: `dotnet.process.memory.virtual.utilization`](#instrument-dotnetprocessmemoryvirtualutilization) + - [Instrument: `system.network.connections`](#instrument-systemnetworkconnections) + +## Meter: `Microsoft.Extensions.Diagnostics.HealthChecks` + +### Instrument: `dotnet.health_check.reports` + +| Name | Instrument Type | Unit (UCUM) | Description | +| ---- | --------------- | ----------- | ----------- | +| `dotnet.health_check.reports` | Counter | `{report}` | Number of times a health report reported the health status of an application. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `dotnet.health_check.status` | string | The health status of an application. | `Healthy`; `Unhealthy` | Always | + +`dotnet.health_check.status` is one of the following: + +| Value | Description | +|---|---| +| `Degraded` | An application was in degraded state. | +| `Healthy` | An application was healthy. | +| `Unhealthy` | An application was unhealthy. | + +Available starting in: .NET 8.0. + +### Instrument: `dotnet.health_check.unhealthy_checks` + +| Name | Instrument Type | Unit (UCUM) | Description | +| ---- | --------------- | ----------- | ----------- | +| `dotnet.health_check.unhealthy_checks` | Counter | `{unhealthy_check}` | Number of times a health check reported the health status of an application as `Degraded` or `Unhealthy`. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `dotnet.health_check.name` | string | The name of the health check. | `ApplicationLifecycle` | Always | +| `dotnet.health_check.status` | string | The health status of an application. | `Healthy`; `Unhealthy` | Always | + +`dotnet.health_check.status` is one of the following: + +| Value | Description | +|---|---| +| `Degraded` | An application was in degraded state. | +| `Healthy` | An application was healthy. | +| `Unhealthy` | An application was unhealthy. | + +Available starting in: .NET 8.0. + +## Meter: `Microsoft.Extensions.Diagnostics.ResourceMonitoring` + +> [!NOTE] +> Metrics emitted by the `Microsoft.Extensions.Diagnostics.ResourceMonitoring` meter are in experimental stage. This means that there could be breaking changes to them. + +### Instrument: `process.cpu.utilization` + +The instrument is available only on Linux. + +| Name | Instrument Type | Unit (UCUM) | Description | +| ---- | --------------- | ----------- | ----------- | +| `process.cpu.utilization` | ObservableGauge | `1` | The CPU consumption of the running application in range `[0, 1]`. | + +Available starting in: .NET 8.0. + +### Instrument: `dotnet.process.memory.virtual.utilization` + +The instrument is available only on Linux. + +| Name | Instrument Type | Unit (UCUM) | Description | +| ---- | --------------- | ----------- | ----------- | +| `dotnet.process.memory.virtual.utilization` | ObservableGauge | `1` | The memory consumption of the running application in range `[0, 1]`. | + +Available starting in: .NET 8.0. + +### Instrument: `system.network.connections` + +The instrument is available only on Windows. + +| Name | Instrument Type | Unit (UCUM) | Description | +| ---- | --------------- | ----------- | ----------- | +| `system.network.connections` | ObservableUpDownCounter | `{connection}` | Number of network connections by state. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.type` | string | OSI network layer or non-OSI equivalent. | `ipv4`; `ipv6` | Always | +| `system.network.state` | string | The state of a network connection. | `close`; `listen` | Always | + +`network.type` is one of the following: + +| Value | Description | +|---|---| +| `ipv4` | IPv4 | +| `ipv6` | IPv6 | + +`system.network.state` is one of the following: + +| Value | Description | +|---|---| +| `close` | A connection is closed. | +| `close_wait` | A connection is in the close wait state. | +| `closing` | A connection is closing. | +| `delete` | A connection is in the delete TCB state. | +| `established` | A connection is established. | +| `fin_wait_1` | A connection is waiting for a FIN packet 1. | +| `fin_wait_2` | A connection is waiting for a FIN packet 2. | +| `last_ack` | A connection is in the last ACK state. | +| `listen` | A connection is in the listen state. | +| `syn_recv` | A connection has received a SYN packet. | +| `syn_sent` | A connection has sent a SYN packet. | +| `time_wait` | A connection is in the time wait state. | + +Available starting in: .NET 8.0. diff --git a/docs/core/diagnostics/built-in-metrics-system-net.md b/docs/core/diagnostics/built-in-metrics-system-net.md index f25b7fb448f67..ff01d0cbace75 100644 --- a/docs/core/diagnostics/built-in-metrics-system-net.md +++ b/docs/core/diagnostics/built-in-metrics-system-net.md @@ -1,11 +1,11 @@ --- -title: System.Net Metrics +title: System.Net metrics description: Review the metrics available for System.Net ms.topic: reference ms.date: 9/21/2023 --- -# System.Net Metrics +# System.Net metrics This article describes the networking metrics built-in for produced using the API. For a listing of metrics based on the alternate [EventCounters](event-counters.md) API, see [Well-known EventCounters in .NET](available-counters.md). diff --git a/docs/core/diagnostics/built-in-metrics.md b/docs/core/diagnostics/built-in-metrics.md index 88126da3da619..228f3c097bae7 100644 --- a/docs/core/diagnostics/built-in-metrics.md +++ b/docs/core/diagnostics/built-in-metrics.md @@ -1,15 +1,16 @@ --- -title: Built-in Metrics in .NET +title: Built-in metrics in .NET description: Review the metrics built-in for the .NET runtime and libraries. ms.topic: reference -ms.date: 9/21/2023 +ms.date: 11/02/2023 --- -# Built-in Metrics in .NET +# Built-in metrics in .NET This is a reference for [metrics](metrics.md) built-in for .NET, produced using the API. For metrics produced by [alternative metric APIs](compare-metric-apis.md) see the [EventCounters reference](available-counters.md) and [Windows Performance Counter reference](../../framework/debug-trace-profile/performance-counters.md). +- [.NET extensions metrics](built-in-metrics-diagnostics.md) - [ASP.NET Core Metrics](built-in-metrics-aspnetcore.md) - [System.Net Metrics](built-in-metrics-system-net.md) diff --git a/docs/core/diagnostics/diagnostic-health-checks.md b/docs/core/diagnostics/diagnostic-health-checks.md index c0ff5911608da..715761ec4bf10 100644 --- a/docs/core/diagnostics/diagnostic-health-checks.md +++ b/docs/core/diagnostics/diagnostic-health-checks.md @@ -1,7 +1,7 @@ --- title: App health checks in C# description: Learn how to use resource utilization and application lifetime health checks in .NET app development. -ms.date: 10/30/2023 +ms.date: 11/02/2023 --- # .NET app health checks in C\# @@ -14,6 +14,8 @@ The following heath check status results are possible: - - +In addition, health checks often report various diagnostic metrics. For more information, see [Diagnostic Metrics: `Microsoft.Extensions.Diagnostics.HealthChecks`](built-in-metrics-diagnostics.md#meter-microsoftextensionsdiagnosticshealthchecks). + ## Resource utilization health checks To perform health checks on the resource utilization of your .NET apps, add a package reference to [Microsoft.Extensions.Diagnostics.HealthChecks.ResourceUtilization](https://www.nuget.org/packages/Microsoft.Extensions.Diagnostics.HealthChecks.ResourceUtilization). On an instance, chain a call from to . The following example demonstrates how to use the `AddResourceUtilizationHealthCheck` extension method to add a resource utilization health check to an `IServiceCollection` instance: @@ -80,3 +82,7 @@ The app outputs logs in the following order, reporting the health check status a 1. `StoppedAsync`: Unhealthy In other words, this provider ensures that the application instance only receives traffic when it's ready. If you're developing web apps with ASP.NET Core, there's health checks middleware available. For more information, [Health checks in ASP.NET Core](/aspnet/core/host-and-deploy/health-checks). + +## See also + +- [.NET extensions metrics](built-in-metrics-diagnostics.md) diff --git a/docs/core/diagnostics/diagnostic-resource-monitoring.md b/docs/core/diagnostics/diagnostic-resource-monitoring.md index 1141220de6f20..33c629591b1fd 100644 --- a/docs/core/diagnostics/diagnostic-resource-monitoring.md +++ b/docs/core/diagnostics/diagnostic-resource-monitoring.md @@ -1,7 +1,7 @@ --- title: Diagnostic resource monitoring description: Learn how to use the diagnostic resource monitoring library in .NET. -ms.date: 10/30/2023 +ms.date: 11/02/2023 --- # Resource monitoring @@ -10,6 +10,8 @@ Resource monitoring involves the continuous measurement of resource utilization The interface furnishes methods for retrieving real-time information concerning process resource utilization. This interface supports the retrieval of data related to CPU and memory usage and is currently compatible with both Windows and Linux platforms. All resource monitoring diagnostic information is published to OpenTelemetry by default, so there's no need to manually publish this yourself. +In addition, the resource monitoring library reports various diagnostic metrics. For more information, see [Diagnostic Metrics: `Microsoft.Extensions.Diagnostics.ResourceMonitoring`](built-in-metrics-diagnostics.md#meter-microsoftextensionsdiagnosticsresourcemonitoring). + ## Example resource monitoring usage The following example demonstrates how to use the `IResourceMonitor` interface to retrieve information about the current process's CPU and memory usage. @@ -64,3 +66,7 @@ In addition to resource monitoring, apps that exist within a Kubernetes cluster The library communicates the apps current health to a Kubernetes hosting environment. If a process reports as being unhealthy, Kubernetes doesn't send it any traffic, providing the process time to recover or terminate. To add support for Kubernetes probes, add a package reference to [Microsoft.Extensions.Diagnostics.Probes](https://www.nuget.org/packages/Microsoft.Extensions.Diagnostics.Probes). On an instance, call . + +## See also + +- [.NET extensions metrics](built-in-metrics-diagnostics.md) diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 6098b6230add6..4d1c91f91f45e 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -343,13 +343,15 @@ items: displayName: exception summarization,exception summary,exception summarizer,ExceptionSummary - name: Collection href: ../../core/diagnostics/metrics-collection.md - - name: Built-in Metrics + - name: Built-in metrics items: - name: Overview href: ../../core/diagnostics/built-in-metrics.md - - name: ASP.NET Core Metrics + - name: .NET extensions metrics + href: ../../core/diagnostics/built-in-metrics-diagnostics.md + - name: ASP.NET Core metrics href: ../../core/diagnostics/built-in-metrics-aspnetcore.md - - name: System.Net Metrics + - name: System.Net metrics href: ../../core/diagnostics/built-in-metrics-system-net.md - name: EventCounters items: From fb2ab5d13efce5728d9b6b55f87247b734051d75 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 2 Nov 2023 16:01:17 -0700 Subject: [PATCH 16/20] Miscellany (#37879) --- .../signalr-differences.md | 2 +- docs/core/extensions/package-and-deploy-resources.md | 10 +++++----- docs/fundamentals/syslib-diagnostics/syslib0049.md | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/architecture/porting-existing-aspnet-apps/signalr-differences.md b/docs/architecture/porting-existing-aspnet-apps/signalr-differences.md index 25e2aedb21904..5ea022855dac4 100644 --- a/docs/architecture/porting-existing-aspnet-apps/signalr-differences.md +++ b/docs/architecture/porting-existing-aspnet-apps/signalr-differences.md @@ -13,7 +13,7 @@ ASP.NET Core SignalR is incompatible with clients or servers using ASP.NET Signa ## Feature differences -- ASP.NET SignalR automatically attempts to reconnect dropped connections; this behavior is opt-in for ASP.NET Core SignalR clients +- ASP.NET SignalR automatically attempts to reconnect dropped connections; this behavior is opt-in for ASP.NET Core SignalR clients. - Both frameworks support JSON; ASP.NET Core SignalR also supports a binary protocol based on MessagePack, and custom protocols can be created. - The Forever Frame transport, supported by ASP.NET SignalR, isn't supported in ASP.NET Core SignalR. - ASP.NET Core SignalR must be configured by adding `services.AddSignalR()` and `app.UseEndpoints` in _Program.cs_. diff --git a/docs/core/extensions/package-and-deploy-resources.md b/docs/core/extensions/package-and-deploy-resources.md index 946e3cb4d87ae..420224a1fc54e 100644 --- a/docs/core/extensions/package-and-deploy-resources.md +++ b/docs/core/extensions/package-and-deploy-resources.md @@ -1,5 +1,5 @@ --- -title: "Package and deploy resources in .NET Apps" +title: "Package and deploy resources in .NET apps" description: Package and deploy resources in .NET apps using a main assembly (hub) and satellite assemblies (spokes). A spoke contains localized resources but no code. ms.date: 03/13/2023 dev_langs: @@ -29,7 +29,7 @@ helpviewer_keywords: ms.assetid: b224d7c0-35f8-4e82-a705-dd76795e8d16 --- -# Package and deploy resources in .NET Apps +# Package and deploy resources in .NET apps Applications rely on the .NET Framework Resource Manager, represented by the class, to retrieve localized resources. The Resource Manager assumes that a hub and spoke model is used to package and deploy resources. The hub is the main assembly that contains the nonlocalizable executable code and the resources for a single culture, called the neutral or default culture. The default culture is the fallback culture for the application; it is the culture whose resources are used if localized resources cannot be found. Each spoke connects to a satellite assembly that contains the resources for a single culture, but does not contain any code. @@ -39,7 +39,7 @@ There are several advantages to this model: - You can update and change an application's satellite assemblies without recompiling the application. - An application needs to load only those satellite assemblies that contain the resources needed for a particular culture. This can significantly reduce the use of system resources. - However, there are also disadvantages to this model: +However, there are also disadvantages to this model: - You must manage multiple sets of resources. - The initial cost of testing an application increases, because you must test several configurations. Note that in the long term it will be easier and less expensive to test one core application with several satellites, than to test and maintain several parallel international versions. @@ -57,7 +57,7 @@ For more information, see [Create resource files](create-resource-files.md) and ## The resource fallback process -The hub and spoke model for packaging and deploying resources uses a fallback process to locate appropriate resources. If an application requests a localized resource that is unavailable, the common language runtime searches the hierarchy of cultures for an appropriate fallback resource that most closely matches the user's application's request, and throws an exception only as a last resort. At each level of the hierarchy, if an appropriate resource is found, the runtime uses it. If the resource is not found, the search continues at the next level. +The hub and spoke model for packaging and deploying resources uses a fallback process to locate appropriate resources. If an application requests a localized resource that's unavailable, the common language runtime searches the hierarchy of cultures for an appropriate fallback resource that most closely matches the user's application's request, and throws an exception only as a last resort. At each level of the hierarchy, if an appropriate resource is found, the runtime uses it. If the resource is not found, the search continues at the next level. To improve lookup performance, apply the attribute to your main assembly, and pass it the name of the neutral language that will work with your main assembly. @@ -103,7 +103,7 @@ For example, suppose the application requests a resource localized for Spanish ( #### Optimize the .NET Framework resource fallback process -Under the following conditions, you can optimize the process by which the runtime searches for resources in satellite assemblies +Under the following conditions, you can optimize the process by which the runtime searches for resources in satellite assemblies: - Satellite assemblies are deployed in the same location as the code assembly. If the code assembly is installed in the [Global Assembly Cache](../../framework/app-domains/gac.md), satellite assemblies are also installed in the global assembly cache. If the code assembly is installed in a directory, satellite assemblies are installed in culture-specific folders of that directory. diff --git a/docs/fundamentals/syslib-diagnostics/syslib0049.md b/docs/fundamentals/syslib-diagnostics/syslib0049.md index e8d168e483d27..354f980d02448 100644 --- a/docs/fundamentals/syslib-diagnostics/syslib0049.md +++ b/docs/fundamentals/syslib-diagnostics/syslib0049.md @@ -1,9 +1,9 @@ --- -title: SYSLIB0049 warning - -description: Learn about the obsoletion of the RSA.EncryptValue and RSA.DecryptValue methods that generates compile-time warning SYSLIB0049. +title: SYSLIB0049 warning - JsonSerializerOptions.AddContext is obsolete +description: Learn about the obsoletion of the JsonSerializerOptions.AddContext method that generates compile-time warning SYSLIB0049. ms.date: 10/09/2023 --- -# SYSLIB0049 +# SYSLIB0049: JsonSerializerOptions.AddContext is obsolete The method is obsolete, starting in .NET 8. Calling it in code generates warning `SYSLIB0049` at compile time. From 474c5971fddf23f1ed53bd5bb11695c5cfbf2820 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 2 Nov 2023 16:24:49 -0700 Subject: [PATCH 17/20] Revert "Update summary description - issue 27060. (#37853)" (#37870) This reverts commit 7742b9e95e7975b2d2646924eeed5914497fac92. --- docs/csharp/language-reference/xmldoc/recommended-tags.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/csharp/language-reference/xmldoc/recommended-tags.md b/docs/csharp/language-reference/xmldoc/recommended-tags.md index d59cba967f163..24a2f0a68a38b 100644 --- a/docs/csharp/language-reference/xmldoc/recommended-tags.md +++ b/docs/csharp/language-reference/xmldoc/recommended-tags.md @@ -164,7 +164,7 @@ If you want angle brackets to appear in the text of a documentation comment, use description ``` -The `` tag should be used to describe a type or a type member. Use [\](#remarks) to add supplemental information to a type description. Use the [cref attribute](#cref-attribute) to enable documentation tools such as [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) to create internal hyperlinks to documentation pages for code elements. The text for the `` tag is a source of information about the type in IntelliSense, and is also displayed in the Object Browser window. +The `` tag should be used to describe a type or a type member. Use [\](#remarks) to add supplemental information to a type description. Use the [cref attribute](#cref-attribute) to enable documentation tools such as [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) to create internal hyperlinks to documentation pages for code elements. The text for the `` tag is the only source of information about the type in IntelliSense, and is also displayed in the Object Browser window. ### \ @@ -174,7 +174,7 @@ description ``` -The `` tag is used to add information about a type or a type member, supplementing the information specified with [\](#summary). This information is displayed in the Object Browser window. The text for the `` tag is a source of information about the type in IntelliSense. This tag may include more lengthy explanations. You may find that using `CDATA` sections for markdown make writing it more convenient. Tools such as [docfx](https://dotnet.github.io/docfx/) process the markdown text in `CDATA` sections. +The `` tag is used to add information about a type or a type member, supplementing the information specified with [\](#summary). This information is displayed in the Object Browser window. This tag may include more lengthy explanations. You may find that using `CDATA` sections for markdown make writing it more convenient. Tools such as [docfx](https://dotnet.github.io/docfx/) process the markdown text in `CDATA` sections. ## Document members From 8087020c96d5aa7c6a53a8d4ab80f0493480cd8e Mon Sep 17 00:00:00 2001 From: Benjamin Petit Date: Fri, 3 Nov 2023 00:38:28 +0100 Subject: [PATCH 18/20] Add small section to describe keyed DI (#37868) * Add small section to describe keyed DI * Update docs/core/extensions/dependency-injection.md * Update dependency-injection.md --------- Co-authored-by: David Pine --- docs/core/extensions/dependency-injection.md | 28 ++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/core/extensions/dependency-injection.md b/docs/core/extensions/dependency-injection.md index 815cdbcf4fce2..061b813336170 100644 --- a/docs/core/extensions/dependency-injection.md +++ b/docs/core/extensions/dependency-injection.md @@ -408,6 +408,34 @@ In the preceding code, while the app is running, the background service: From the sample source code, you can see how implementations of can benefit from scoped service lifetimes. +## Keyed services + +.NET also supports service registrations and lookups based on a key, meaning it's possible to register multiple services with a different key, and use this key for the lookup. + +For example, let's consider you have different implementation of the interface `IMessageWriter`: `MemoryMessageWriter` and `QueueMessageWriter`. + +You can register these services using the overload of the service registration methods (seen earlier) that supports a key as a parameter: + +```csharp +services.AddSingleton("memory"); +services.AddSingleton("queue"); +``` + +The `key` isn't limited to `string`, it can be any `object` you want, as long as the type correctly implements `Equals`. + +In the constructor of the class that uses `IMessageWriter`, you add the to specify the key of the service to resolve: + +```csharp +public class ExampleService +{ + public ExampleService( + [FromKeyedServices("queue")] IMessageWriter writer) + { + // Omitted for brevity... + } +} +``` + ## See also - [Use dependency injection in .NET](dependency-injection-usage.md) From 50258b57cbc60fbd65657bcb09fc6bf7f2a5650d Mon Sep 17 00:00:00 2001 From: Immo Landwerth Date: Thu, 2 Nov 2023 17:30:55 -0700 Subject: [PATCH 19/20] Add topic for diagnostic IDs (#37877) * Add topic for diagnostic IDs * Fix indentation * Apply review feedback * Link diagnostic ID topic from C# style guide --- .../coding-style/coding-conventions.md | 4 ++ .../roslyn-sdk/choosing-diagnostic-ids.md | 39 +++++++++++++++++++ docs/csharp/toc.yml | 2 + 3 files changed, 45 insertions(+) create mode 100644 docs/csharp/roslyn-sdk/choosing-diagnostic-ids.md diff --git a/docs/csharp/fundamentals/coding-style/coding-conventions.md b/docs/csharp/fundamentals/coding-style/coding-conventions.md index 50caf08491277..0d9a0bdaba9a6 100644 --- a/docs/csharp/fundamentals/coding-style/coding-conventions.md +++ b/docs/csharp/fundamentals/coding-style/coding-conventions.md @@ -33,6 +33,10 @@ These tools make it easier for your team to adopt your preferred guidelines. Vis Code analysis produces warnings and diagnostics when the enabled rules are violated. You configure the rules you want applied to your project. Then, each CI build notifies developers when they violate any of the rules. +### Diagnostic IDs + +- [Choose appropriate diagnostic IDs](../../roslyn-sdk/choosing-diagnostic-ids.md) when building your own analyzers + ## Language guidelines The following sections describe practices that the .NET docs team follows to prepare code examples and samples. In general, follow these practices: diff --git a/docs/csharp/roslyn-sdk/choosing-diagnostic-ids.md b/docs/csharp/roslyn-sdk/choosing-diagnostic-ids.md new file mode 100644 index 0000000000000..e6e7fed4fc38d --- /dev/null +++ b/docs/csharp/roslyn-sdk/choosing-diagnostic-ids.md @@ -0,0 +1,39 @@ +--- +title: Choosing diagnostic IDs +description: This overview provides an understanding of how to choose a diagnostic ID +ms.date: 11/2/2023 +--- + +# Choose diagnostic IDs + +A diagnostic ID is the string associated with a given diagnostic, such as a +compiler error or a diagnostic that is produced by an analyzer. + +The IDs are surfaced from various APIs, such as: + +* +* +* + +Diagnostic IDs are also used as identifiers in source, for example, from +[#pragma warning disable] or [.editorconfig] files. + +## Considerations + +* Diagnostic IDs should be unique +* Diagnostic IDs must be legal identifiers in C# +* Diagnostic IDs should be less than 15 characters long +* Diagnostic IDs should be of the form `` + - The prefix is specific to your project + - The number represents the specific diagnostic + +> [!NOTE] +> It's a source breaking change to change diagnostic IDs, as existing +> suppressions would be ignored if the ID changed. + +Don't limit your prefix to two-characters (such as `CSXXX`and `CAXXXX`). +Instead, use a longer prefix to avoid conflicts. For example, the `System.*` +diagnostics use `SYSLIB` as their prefix. + +[#pragma warning disable]: ../language-reference/preprocessor-directives.md#pragma-warning +[.editorconfig]: ../../fundamentals/code-analysis/code-style-rule-options.md diff --git a/docs/csharp/toc.yml b/docs/csharp/toc.yml index f73e55883fe42..2b576933f5598 100644 --- a/docs/csharp/toc.yml +++ b/docs/csharp/toc.yml @@ -505,6 +505,8 @@ items: href: roslyn-sdk/syntax-visualizer.md - name: Source Generators href: roslyn-sdk/source-generators-overview.md + - name: Choose diagnostic IDs + href: roslyn-sdk/choosing-diagnostic-ids.md - name: Quick starts items: - name: Syntax analysis From b3331a417ec22734a83f7139bd22ebd35f091af4 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 2 Nov 2023 20:24:03 -0700 Subject: [PATCH 20/20] cbor breaking change (#37881) --- docs/core/compatibility/8.0.md | 21 +++-- .../extensions/8.0/cbor-datetime.md | 94 +++++++++++++++++++ docs/core/compatibility/toc.yml | 4 + 3 files changed, 109 insertions(+), 10 deletions(-) create mode 100644 docs/core/compatibility/extensions/8.0/cbor-datetime.md diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md index ccfcc9818f226..6ade2b75d867d 100644 --- a/docs/core/compatibility/8.0.md +++ b/docs/core/compatibility/8.0.md @@ -78,16 +78,17 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff ## Extensions -| Title | Type of change | Introduced | -|-----------------------------------------------------------------------------------------------------------------------------------|-------------------|------------| -| [ActivatorUtilities.CreateInstance behaves consistently](extensions/8.0/activatorutilities-createinstance-behavior.md) | Behavioral change | Preview 1 | -| [ActivatorUtilities.CreateInstance requires non-null provider](extensions/8.0/activatorutilities-createinstance-null-provider.md) | Behavioral change | Preview 1 | -| [ConfigurationBinder throws for mismatched value](extensions/8.0/configurationbinder-exceptions.md) | Behavioral change | Preview 1 | -| [ConfigurationManager package no longer references System.Security.Permissions](extensions/8.0/configurationmanager-package.md) | Source incompatible | Preview 3 | -| [DirectoryServices package no longer references System.Security.Permissions](extensions/8.0/directoryservices-package.md) | Source incompatible | Preview 3 | -| [Empty keys added to dictionary by configuration binder](extensions/8.0/dictionary-configuration-binding.md) | Behavioral change | Preview 5 | -| [HostApplicationBuilderSettings.Args respected by HostApplicationBuilder ctor](extensions/8.0/hostapplicationbuilder-ctor.md) | Behavioral change | Preview 2 | -| [ManagementDateTimeConverter.ToDateTime returns a local time](extensions/8.0/dmtf-todatetime.md) | Behavioral change | RC 1 | +| Title | Type of change | +|-----------------------------------------------------------------------------------------------------------------------------------|-------------------| +| [ActivatorUtilities.CreateInstance behaves consistently](extensions/8.0/activatorutilities-createinstance-behavior.md) | Behavioral change | +| [ActivatorUtilities.CreateInstance requires non-null provider](extensions/8.0/activatorutilities-createinstance-null-provider.md) | Behavioral change | +| [ConfigurationBinder throws for mismatched value](extensions/8.0/configurationbinder-exceptions.md) | Behavioral change | +| [ConfigurationManager package no longer references System.Security.Permissions](extensions/8.0/configurationmanager-package.md) | Source incompatible | +| [DirectoryServices package no longer references System.Security.Permissions](extensions/8.0/directoryservices-package.md) | Source incompatible | +| [Empty keys added to dictionary by configuration binder](extensions/8.0/dictionary-configuration-binding.md) | Behavioral change | +| [HostApplicationBuilderSettings.Args respected by HostApplicationBuilder ctor](extensions/8.0/hostapplicationbuilder-ctor.md) | Behavioral change | +| [ManagementDateTimeConverter.ToDateTime returns a local time](extensions/8.0/dmtf-todatetime.md) | Behavioral change | +| [System.Formats.Cbor DateTimeOffset formatting change](extensions/8.0/cbor-datetime.md) | Behavioral change | ## Globalization diff --git a/docs/core/compatibility/extensions/8.0/cbor-datetime.md b/docs/core/compatibility/extensions/8.0/cbor-datetime.md new file mode 100644 index 0000000000000..6cf3c73d07168 --- /dev/null +++ b/docs/core/compatibility/extensions/8.0/cbor-datetime.md @@ -0,0 +1,94 @@ +--- +title: "Breaking change: System.Formats.Cbor DateTimeOffset formatting change" +description: Learn about the .NET 8 breaking change in .NET extensions where System.Formats.Cbor always formats and parses DateTimeOffset values using the invariant culture. +ms.date: 11/02/2023 +--- +# System.Formats.Cbor DateTimeOffset formatting change + +Since it was released in .NET 5, the System.Formats.Cbor NuGet package included built-in methods for serializing and deserializing DateTimeOffset values according to RFC 7049. Unfortunately, the implementations didn't use invariant culture when formatting and parsing DateTimeOffset values. This resulted in inconsistent or even incorrect date encodings on machines with cultures that use non-Gregorian calendars. + +The behavior has been changed so that invariant culture is always used when parsing and formatting DateTimeOffset values. This change might break your code if you relied on the previous behavior. Also, it might be impossible to read date values that were encoded with earlier versions of the System.Formats.Cbor NuGet package. + +## Version introduced + +.NET 8 + +## Previous behavior + +Consider this code that parses a DateTimeOffset value from a string and then encodes it using CBOR: + +```csharp +// Install a culture with a non-Gregorian calendar +var culture = new CultureInfo("he-IL"); +culture.DateTimeFormat.Calendar = new HebrewCalendar(); +Thread.CurrentThread.CurrentCulture = culture; + +DateTimeOffset value = DateTimeOffset.Parse("2020-04-09T14:31:21.3535941+01:00", CultureInfo.InvariantCulture); + +var writer = new CborWriter(); +writer.WriteDateTimeOffset(value); +byte[] cborEncoding = writer.Encode(); + +Console.WriteLine(Convert.ToHexString(cborEncoding)); +``` + +Previously, this code produced the following CBOR encoding: + +`C07828D7AAD7A922D7A42DD796272DD79822D7955431343A33313A32312E333533353934312B30313A3030` + +This encoding corresponds to `0(תש\"פ-ז'-ט\"וT14:31:21.3535941+01:00)` in CBOR diagnostic notation, which is an invalid date representation per RFC 7049. + +## New behavior + +Starting in .NET 8, the same code produces the following CBOR encoding: + +`C07821323032302D30342D30395431343A33313A32312E333533353934312B30313A3030` + +This encoding corresponds to `0("2020-04-09T14:31:21.3535941+01:00")` in CBOR diagnostic notation. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +The previous behavior produced invalid date encodings per RFC 7049. + +## Recommended action + +You might have to be able to read CBOR date encodings that were persisted using earlier versions of System.Formats.Cbor if you don't upgrade to the latest version of the System.Formats.Cbor NuGet package. + +Alternatively, you can change your code to use the following extension method: + +```csharp +public static class CborReaderExtensions +{ + private const string Rfc3339FormatString = "yyyy-MM-ddTHH:mm:ss.FFFFFFFK"; + + public static DateTimeOffset ReadDateTimeOffsetReplacement(this CborReader reader, CultureInfo? cultureInfo = null) + { + CborTag tag = reader.PeekTag(); + if (tag != CborTag.DateTimeString) + { + throw new InvalidOperationException($"Expected CborTag {(int)CborTag.DateTimeString}"); + } + + reader.ReadTag(); + string dateString = reader.ReadTextString(); + return DateTimeOffset.ParseExact(dateString, Rfc3339FormatString, cultureInfo, DateTimeStyles. RoundtripKind); + } +} +``` + +Use this extension method to read a CBOR date encoding as follows: + +```csharp +var reader = new CborReader(cborEncoding); +DateTimeOffset date = reader.ReadDateTimeOffsetReplacement(culture); +Console.WriteLine(date.ToString(CultureInfo.InvariantCulture)); +``` + +## Affected APIs + +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 48ce60e6cf94a..e0d1b08e0b4c7 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -102,6 +102,8 @@ items: href: extensions/8.0/hostapplicationbuilder-ctor.md - name: ManagementDateTimeConverter.ToDateTime returns a local time href: extensions/8.0/dmtf-todatetime.md + - name: System.Formats.Cbor DateTimeOffset formatting change + href: extensions/8.0/cbor-datetime.md - name: Globalization items: - name: Date and time converters honor culture argument @@ -1354,6 +1356,8 @@ items: href: extensions/8.0/hostapplicationbuilder-ctor.md - name: ManagementDateTimeConverter.ToDateTime returns a local time href: extensions/8.0/dmtf-todatetime.md + - name: System.Formats.Cbor DateTimeOffset formatting change + href: extensions/8.0/cbor-datetime.md - name: .NET 7 items: - name: Binding config to dictionary extends values