diff --git a/.openpublishing.redirection.csharp.json b/.openpublishing.redirection.csharp.json index b3feedae1279f..854d17b31097d 100644 --- a/.openpublishing.redirection.csharp.json +++ b/.openpublishing.redirection.csharp.json @@ -590,6 +590,30 @@ "source_path_from_root": "/docs/csharp/language-reference/compiler-messages/cs7000.md", "redirect_url": "/dotnet/csharp/language-reference/compiler-messages/using-directive-errors" }, + { + "source_path_from_root": "/docs/csharp/language-reference/compiler-messages/cs8124.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-messages/tuple-errors" + }, + { + "source_path_from_root": "/docs/csharp/language-reference/compiler-messages/cs8125.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-messages/tuple-errors" + }, + { + "source_path_from_root": "/docs/csharp/language-reference/compiler-messages/cs8127.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-messages/tuple-errors" + }, + { + "source_path_from_root": "/docs/csharp/language-reference/compiler-messages/cs8139.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-messages/tuple-errors" + }, + { + "source_path_from_root": "/docs/csharp/language-reference/compiler-messages/cs8140.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-messages/tuple-errors" + }, + { + "source_path_from_root": "/docs/csharp/language-reference/compiler-messages/cs8141.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-messages/tuple-errors" + }, { "source_path_from_root": "/docs/csharp/language-reference/compiler-messages/cs8145.md", "redirect_url": "/dotnet/csharp/language-reference/compiler-messages/property-declaration-errors" @@ -638,6 +662,10 @@ "source_path_from_root": "/docs/csharp/language-reference/compiler-messages/cs8178.md", "redirect_url": "/dotnet/csharp/language-reference/compiler-messages/async-await-errors" }, + { + "source_path_from_root": "/docs/csharp/language-reference/compiler-messages/cs8210.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-messages/tuple-errors" + }, { "source_path_from_root": "/docs/csharp/language-reference/compiler-messages/cs8373.md", "redirect_url": "/dotnet/csharp/language-reference/compiler-messages/ref-modifiers-errors" diff --git a/docs/csharp/language-reference/compiler-messages/cs8124.md b/docs/csharp/language-reference/compiler-messages/cs8124.md deleted file mode 100644 index 3b745c8740486..0000000000000 --- a/docs/csharp/language-reference/compiler-messages/cs8124.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -description: "Compiler Error CS8124" -title: "Compiler Error CS8124" -ms.date: 9/30/2022 -f1_keywords: - - "CS8124" -helpviewer_keywords: - - "CS8124" ---- -# Compiler Error CS8124 - -Tuple must contain at least two elements. - -## Example - - The following sample generates CS8124: - -```csharp -// CS8124.cs (4,20) - -class C -{ - void M(int x, () y, (int a) z) { } -} -``` - -## To correct this error - -A valid tuple declaration contains two or more elements, ensuring tuple declarations have two or more elements corrects this error: - -```csharp -class C -{ - void M(int x, (int, int) y, (int a, int b) z) { } -} -``` diff --git a/docs/csharp/language-reference/compiler-messages/cs8125.md b/docs/csharp/language-reference/compiler-messages/cs8125.md deleted file mode 100644 index 6d7a2a7cb44c6..0000000000000 --- a/docs/csharp/language-reference/compiler-messages/cs8125.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -description: "Compiler Error CS8125" -title: "Compiler Error CS8125" -ms.date: 9/30/2022 -f1_keywords: - - "CS8125" -helpviewer_keywords: - - "CS8125" ---- -# Compiler Error CS8125 - -Tuple element name is only allowed at position. - -## Example - - The following sample generates CS8125: - -```csharp -// CS8125.cs (2,15) - -public class C -{ - public void Method() - { - var tuple3 = (Item2: 2, Item1: 1); - } -} -``` - -## To correct this error - -If tuple element names `Item1`, `Item2`, etc. are used, ensuring the correct order corrects this error: - -```csharp - public void Method() - { - var tuple3 = (Item1: 2, Item2: 1); - } -``` diff --git a/docs/csharp/language-reference/compiler-messages/cs8127.md b/docs/csharp/language-reference/compiler-messages/cs8127.md deleted file mode 100644 index 036fa67654075..0000000000000 --- a/docs/csharp/language-reference/compiler-messages/cs8127.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -description: "Compiler Error CS8127" -title: "Compiler Error CS8127" -ms.date: 9/30/2022 -f1_keywords: - - "CS8127" -helpviewer_keywords: - - "CS8127" ---- -# Compiler Error CS8127 - -Tuple element names must be unique. - -## Example - - The following sample generates CS8127: - -```csharp -// CS8127.cs (7,0) - -internal struct NewStruct -{ - public int a; - public int b; - - public static implicit operator (int a, int a)(NewStruct value) - { - return (value.a, value.b); - } -} -``` - -## To correct this error - -Ensuring the names of elements within a tuple declaration are unique corrects this error: - -```csharp - public static implicit operator (int a, int b)(NewStruct value) - { - return (value.a, value.b); - } -``` diff --git a/docs/csharp/language-reference/compiler-messages/cs8139.md b/docs/csharp/language-reference/compiler-messages/cs8139.md deleted file mode 100644 index d7c863eee3804..0000000000000 --- a/docs/csharp/language-reference/compiler-messages/cs8139.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -description: "Compiler Error CS8139" -title: "Compiler Error CS8139" -ms.date: 9/30/2022 -f1_keywords: - - "CS8139" -helpviewer_keywords: - - "CS8139" ---- -# Compiler Error CS8139 - -cannot change tuple element names when overriding inherited member - -## Example - - The following sample generates CS8139: - -```csharp -// CS8139.cs (9,38) - -public class Base -{ - public virtual (object a, object b) M((object c, object d) x) { return x; } -} - -class C : Base -{ - public override (object, object) M((object c, object d) y) { return y; } -} -``` - -## To correct this error - -Ensuring the tuple element names in the overriding member match those in the virtual member corrects this error: - -```csharp -class C : Base -{ - public override (object a, object b) M((object c, object d) y) { return y; } -} -``` diff --git a/docs/csharp/language-reference/compiler-messages/cs8140.md b/docs/csharp/language-reference/compiler-messages/cs8140.md deleted file mode 100644 index 4628539900de7..0000000000000 --- a/docs/csharp/language-reference/compiler-messages/cs8140.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -description: "Compiler Error CS8140" -title: "Compiler Error CS8140" -ms.date: 9/30/2022 -f1_keywords: - - "CS8140" -helpviewer_keywords: - - "CS8140" ---- -# Compiler Error CS8140 - -is already listed in the interface list on type with different tuple element names, as. - -## Example - - The following sample generates CS8140: - -```csharp -// CS8140.cs (11,7) - -interface I -{ - T GetValue(); -} - -interface I2 : I<(int c, int d)> -{ -} - -class C : I<(int a, int b)>, I2 -{ - public (int c, int d) GetValue() - { - return (1, 2); - } -} -``` - -## To correct this error - -Renaming the tuple element names to match the interface declaration corrects this error: - -```csharp -interface I -{ - T GetValue(); -} - -interface I2 : I<(int c, int d)> -{ -} - -class C : I<(int c, int d)>, I2 -{ - public (int c, int d) GetValue() - { - return (1, 2); - } -} -``` diff --git a/docs/csharp/language-reference/compiler-messages/cs8141.md b/docs/csharp/language-reference/compiler-messages/cs8141.md deleted file mode 100644 index 8e99744d298ac..0000000000000 --- a/docs/csharp/language-reference/compiler-messages/cs8141.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -description: "Compiler Error CS8141" -title: "Compiler Error CS8141" -ms.date: 9/30/2022 -f1_keywords: - - "CS8141" -helpviewer_keywords: - - "CS8141" ---- -# Compiler Error CS8141 - -The tuple element names in the signature of method must match the tuple element names of interface method (including on the return type). - -## Example - -The following sample generates CS8141: - -```csharp -// CS8141.cs (10,27) -using System.Collections; - -public interface IGrabber -{ - T GetOne(); -} - -class SomeGrabber : IGrabber<(int, int)> -{ - public (int a, int b) GetOne() - { - return (1, 2); - } -} -``` - -## To correct this error - -Changing the signature of the `GetOne` method to return an unnamed tuple, matching the unnamed tuple in the interface, will correct this error: - -```csharp - public (int, int) GetOne() - { - return (1, 2); - } -``` diff --git a/docs/csharp/language-reference/compiler-messages/cs8210.md b/docs/csharp/language-reference/compiler-messages/cs8210.md deleted file mode 100644 index 1969a7e5e8e53..0000000000000 --- a/docs/csharp/language-reference/compiler-messages/cs8210.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -description: "Compiler Error CS8210" -title: "Compiler Error CS8210" -ms.date: 10/26/2022 -f1_keywords: - - "CS8210" -helpviewer_keywords: - - "CS8210" ---- -# Compiler Error CS8210 - -A tuple may not contain a value of type 'void'. - -## Example - - The following sample generates CS8210: - -```csharp -// CS8210.cs -void Method() -{ -} - -void Test() -{ - var x = ("something", Method()); -} -``` - -Your method returns `void`, so that method doesn't return a value. You can't use a method that returns `void` for a data member of a tuple. - -## See also - -- [Tuple](../builtin-types/value-tuples.md) -- [Void](../builtin-types/void.md) diff --git a/docs/csharp/language-reference/compiler-messages/tuple-errors.md b/docs/csharp/language-reference/compiler-messages/tuple-errors.md new file mode 100644 index 0000000000000..54b58e2bd7772 --- /dev/null +++ b/docs/csharp/language-reference/compiler-messages/tuple-errors.md @@ -0,0 +1,148 @@ +--- +title: "Resolve errors and warnings related to tuples" +description: "This article helps you diagnose and correct compiler errors and warnings related to tuple declarations, element names, metadata, conversions, equality, type inference, and pattern matching." +f1_keywords: + - "CS8123" + - "CS8124" + - "CS8125" + - "CS8126" + - "CS8127" + - "CS8128" + - "CS8135" + - "CS8137" + - "CS8138" + - "CS8139" + - "CS8140" + - "CS8141" + - "CS8142" + - "CS8179" + - "CS8182" + - "CS8210" + - "CS8307" + - "CS8383" + - "CS8384" + - "CS8516" + - "CS8522" +helpviewer_keywords: + - "CS8123" + - "CS8124" + - "CS8125" + - "CS8126" + - "CS8127" + - "CS8128" + - "CS8135" + - "CS8137" + - "CS8138" + - "CS8139" + - "CS8140" + - "CS8141" + - "CS8142" + - "CS8179" + - "CS8182" + - "CS8210" + - "CS8307" + - "CS8383" + - "CS8384" + - "CS8516" + - "CS8522" +ms.date: 08/17/2026 +ai-usage: ai-assisted +--- + +# Resolve errors and warnings for tuples + +This article covers the following compiler errors and warnings: + + + +- [**CS8123**](#tuple-element-names): *The tuple element name 'name' is ignored because a different name or no name is specified by the target type 'type'.* +- [**CS8124**](#tuple-structure-and-literals): *Tuple must contain at least two elements.* +- [**CS8125**](#tuple-element-names): *Tuple element name 'name' is only allowed at position N.* +- [**CS8126**](#tuple-element-names): *Tuple element name 'name' is disallowed at any position.* +- [**CS8127**](#tuple-element-names): *Tuple element names must be unique.* +- [**CS8128**](#valuetuple-infrastructure): *Member 'member' was not found on type 'type' from assembly 'assembly'.* +- [**CS8135**](#tuple-structure-and-literals): *Tuple with 'count' elements cannot be converted to type 'type'.* +- [**CS8137**](#tuple-metadata): *Cannot define a class or member that utilizes tuples because the compiler required type 'type' cannot be found. Are you missing a reference?* +- [**CS8138**](#tuple-metadata): *Cannot reference 'System.Runtime.CompilerServices.TupleElementNamesAttribute' explicitly. Use the tuple syntax to define tuple names.* +- [**CS8139**](#tuple-element-names-in-type-hierarchy): *'member': cannot change tuple element names when overriding inherited member 'base member'.* +- [**CS8140**](#tuple-element-names-in-type-hierarchy): *'interface' is already listed in the interface list on type 'type' with different tuple element names, as 'alias'.* +- [**CS8141**](#tuple-element-names-in-type-hierarchy): *The tuple element names in the signature of method 'method' must match the tuple element names of interface method 'interface method' (including on the return type).* +- [**CS8142**](#tuple-element-names-in-type-hierarchy): *Both partial member declarations, 'member' and 'other partial', must use the same tuple element names.* +- [**CS8179**](#valuetuple-infrastructure): *Predefined type 'type' is not defined or imported.* +- [**CS8182**](#valuetuple-infrastructure): *Predefined type 'type' must be a struct.* +- [**CS8210**](#tuple-structure-and-literals): *A tuple may not contain a value of type 'void'.* +- [**CS8307**](#tuple-type-inference): *The first operand of an 'as' operator may not be a tuple literal without a natural type.* +- [**CS8383**](#tuple-equality): *The tuple element name 'name' is ignored because a different name or no name is specified on the other side of the tuple == or != operator.* +- [**CS8384**](#tuple-equality): *Tuple types used as operands of an == or != operator must have matching cardinalities. But this operator has tuple types of cardinality 'left' on the left and 'right' on the right.* +- [**CS8516**](#pattern-matching-with-tuples): *The name 'name' does not identify tuple element 'element'.* +- [**CS8522**](#pattern-matching-with-tuples): *Element names are not permitted when pattern-matching via 'System.Runtime.CompilerServices.ITuple'.* + +## Tuple element names + +- **CS8123**: *The tuple element name 'name' is ignored because a different name or no name is specified by the target type 'type'.* +- **CS8125**: *Tuple element name 'name' is only allowed at position N.* +- **CS8126**: *Tuple element name 'name' is disallowed at any position.* +- **CS8127**: *Tuple element names must be unique.* + +The compiler warns when tuple element names conflict with the target type or constraints. The compiler ignores names in tuple literals during type conversion. If the target type expects different names or no names, rename the tuple literal to match the target type or change the target type (**CS8123**). `ItemN` names are reserved for their specific positions (`Item1` at position 1, `Item2` at position 2, and so on). Reorder elements or use custom names (**CS8125**). Names like `Rest`, `ToString`, `GetHashCode`, and `Equals` are reserved for `ValueTuple` infrastructure and can't be used as element names. Choose a different name (**CS8126**). Ensure all element names within a tuple are distinct. Rename any duplicates (**CS8127**). + +## Tuple element names in type hierarchy + +- **CS8139**: *'member': cannot change tuple element names when overriding inherited member 'base member'.* +- **CS8140**: *'interface' is already listed in the interface list on type 'type' with different tuple element names, as 'alias'.* +- **CS8141**: *The tuple element names in the signature of method 'method' must match the tuple element names of interface method 'interface method' (including on the return type).* +- **CS8142**: *Both partial member declarations, 'member' and 'other partial', must use the same tuple element names.* + +Tuple element names are part of method signatures and must be consistent across inheritance, interface implementation, and partial declarations. Match tuple element names in overriding methods to the base member (**CS8139**). Align element names across all base types and interface implementations so that all inheritance paths to the same generic interface use matching element names (**CS8140**). Match element names in interface implementations to the interface declaration, for both parameters and return types (**CS8141**). Update one partial declaration to match the other exactly (**CS8142**). + +## Tuple metadata + +- **CS8137**: *Cannot define a class or member that utilizes tuples because the compiler required type 'type' cannot be found. Are you missing a reference?* +- **CS8138**: *Cannot reference 'System.Runtime.CompilerServices.TupleElementNamesAttribute' explicitly. Use the tuple syntax to define tuple names.* + +When a type signature includes named tuples, the compiler must reference to store element names in metadata. Ensure your project references a .NET runtime that provides , or add the `System.Runtime` NuGet package for older frameworks (**CS8137**). Use tuple literal syntax with element names—for example, `(int x, string y)`—instead of explicitly referencing the attribute. The compiler generates the metadata automatically (**CS8138**). + +## ValueTuple infrastructure + +- **CS8128**: *Member 'member' was not found on type 'type' from assembly 'assembly'.* +- **CS8179**: *Predefined type 'type' is not defined or imported.* +- **CS8182**: *Predefined type 'type' must be a struct.* + +These errors occur when the compiler can't find or validate required types that underlie tuple syntax. Add the `System.ValueTuple` NuGet package for frameworks that don't include it built-in (for example, older .NET Framework versions) (**CS8179**). Verify that `ValueTuple` types are structs, not classes. If a custom class shadows system types, remove or rename it (**CS8182**). If a specific member (`Item1`, `Item2`, `Rest`) is missing from the predefined `ValueTuple` type, verify that your project references the correct runtime or NuGet package version (**CS8128**). + +## Tuple structure and literals + +- **CS8124**: *Tuple must contain at least two elements.* +- **CS8135**: *Tuple with 'count' elements cannot be converted to type 'type'.* +- **CS8210**: *A tuple may not contain a value of type 'void'.* + +These errors relate to tuple expression formation. Tuples require at least two elements; convert single-element or zero-element tuples to two or more elements (**CS8124**). Ensure tuple literals have the same element count as the destination type (**CS8135**). Remove `void`-returning method calls from tuple elements; tuples can only contain values, not `void` results (**CS8210**). + +## Tuple type inference + +- **CS8307**: *The first operand of an 'as' operator may not be a tuple literal without a natural type.* + +**CS8307** occurs when a tuple literal without explicit element types is used as the left operand of an `as` operator. Assign the literal to a typed variable first, then apply `as` to the variable, or annotate the tuple with an explicit type before using `as` (**CS8307**). + +## Tuple equality + +- **CS8383**: *The tuple element name 'name' is ignored because a different name or no name is specified on the other side of the tuple == or != operator.* +- **CS8384**: *Tuple types used as operands of an == or != operator must have matching cardinalities. But this operator has tuple types of cardinality 'left' on the left and 'right' on the right.* + +**CS8383** is a warning when `==` or `!=` operands have different or absent element names. Names don't affect equality semantics (comparison is positional), but mismatches often indicate naming inconsistency. Align element names on both sides or use unnamed tuples (**CS8383**). **CS8384** occurs when `==` or `!=` operands have different numbers of elements. Adjust tuple literals or types so both operands have the same element count (**CS8384**). + +## Pattern matching with tuples + +- **CS8516**: *The name 'name' does not identify tuple element 'element'.* +- **CS8522**: *Element names are not permitted when pattern-matching via 'System.Runtime.CompilerServices.ITuple'.* + +**CS8516** occurs when a tuple pattern uses a property name that doesn't match any element of the tuple type. Verify the element names of the tuple type and correct the pattern property name. **CS8522** occurs when a positional pattern uses named subpatterns against a type that implements but isn't a known tuple type. Remove element names from the pattern and match positionally. + +## See also + +- [Value tuples](../builtin-types/value-tuples.md) +- [Deconstruction](../../fundamentals/functional/deconstruct.md) +- [Pattern matching](../../fundamentals/functional/pattern-matching.md) +- [Void](../builtin-types/void.md) diff --git a/docs/csharp/language-reference/toc.yml b/docs/csharp/language-reference/toc.yml index 6d25c0e978bc3..78596fdc0de3a 100644 --- a/docs/csharp/language-reference/toc.yml +++ b/docs/csharp/language-reference/toc.yml @@ -518,6 +518,13 @@ items: displayName: > CS0017, CS0028, CS0402, CS1555, CS1556, CS1557, CS1558, CS1559, CS2017, CS5001, CS7022, CS8801, CS8802, CS8803, CS8805, CS8899, CS8937 + - name: Tuple declarations + href: ./compiler-messages/tuple-errors.md + displayName: > + tuples, tuple element names, tuple metadata, tuple conversions, tuple equality, tuple pattern matching, + CS8123, CS8124, CS8125, CS8126, CS8127, CS8128, CS8135, CS8137, CS8138, CS8139, + CS8140, CS8141, CS8142, CS8179, CS8182, CS8210, CS8307, CS8383, CS8384, CS8516, + CS8522 - name: Record declarations href: ./compiler-messages/record-declaration-errors.md displayName: > @@ -1555,12 +1562,6 @@ items: href: ./compiler-messages/cs7003.md - name: CS8070 href: ./compiler-messages/cs8070.md - - name: CS8124 - href: ./compiler-messages/cs8124.md - - name: CS8125 - href: ./compiler-messages/cs8125.md - - name: CS8127 - href: ./compiler-messages/cs8127.md - name: CS8129 href: ./compiler-messages/cs8129.md - name: CS8130 @@ -1569,12 +1570,6 @@ items: href: ./compiler-messages/cs8131.md - name: CS8132 href: ./compiler-messages/cs8132.md - - name: CS8139 - href: ./compiler-messages/cs8139.md - - name: CS8140 - href: ./compiler-messages/cs8140.md - - name: CS8141 - href: ./compiler-messages/cs8141.md - name: CS8146 href: ./compiler-messages/cs8146.md - name: CS8147 @@ -1615,8 +1610,6 @@ items: href: ./compiler-messages/cs8173.md - name: CS8174 href: ./compiler-messages/cs8174.md - - name: CS8210 - href: ./compiler-messages/cs8210.md - name: CS8333 href: ./compiler-messages/cs8333.md - name: CS8334 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 b99526fdabc49..05951a75304c0 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 @@ -160,17 +160,9 @@ f1_keywords: - "CS8113" # C# 7.0 diagnostics - "CS8115" - - "CS8123" - - "CS8126" - - "CS8128" - "CS8134" - - "CS8135" - "CS8136" - - "CS8137" - - "CS8138" - - "CS8179" - "CS8180" - - "CS8182" - "CS8183" - "CS8184" - "CS8185" @@ -190,7 +182,6 @@ f1_keywords: - "CS8300" - "CS8301" - "CS8305" - - "CS8307" - "CS8308" - "CS8309" - "CS8310" @@ -214,8 +205,6 @@ f1_keywords: # C# 7.3 diagnostics - "CS8378" - "CS8381" - - "CS8383" - - "CS8384" # Coming in C# 15 - "CS9343" # misc - "CS9347"