Skip to content

Commit 05bcf1b

Browse files
ghogenghogen
committed
Merge branch 'master' of github.com:MicrosoftDocs/visualstudio-docs-pr into msbuild
2 parents 73d98b6 + 4a551f3 commit 05bcf1b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+1019
-215
lines changed

‎docs/code-quality/ca1066.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: 'CA1066: Implement IEquatable when overriding Equals'
3+
ms.date: 04/23/2020
4+
ms.topic: reference
5+
f1_keywords:
6+
- CA1066
7+
helpviewer_keywords:
8+
- CA1066
9+
ms.assetid: 4e1bade4-4ca2-4219-abc3-c7b2d741e157
10+
author: mavasani
11+
ms.author: mavasani
12+
manager: jillfra
13+
ms.workload:
14+
- multiple
15+
---
16+
# CA1066: Implement IEquatable when overriding Equals
17+
18+
|||
19+
|-|-|
20+
|TypeName|EquatableAnalyzer|
21+
|CheckId|CA1066|
22+
|Category|Microsoft.Design|
23+
|Breaking change|Non-breaking|
24+
25+
## Cause
26+
27+
A value type (struct) overrides <xref:System.Object.Equals%2A> method, but does not implement <xref:System.IEquatable%601>.
28+
29+
## Rule description
30+
31+
A value type overriding <xref:System.Object.Equals%2A> method indicates that it supports comparing two instances of the type for value equality. Consider implementing the <xref:System.IEquatable%601> interface to support strongly typed tests for equality. This ensures that callers performing equality checks invoke the strongly typed <xref:System.IEquatable%601.Equals%2A?displayProperty=fullName> method and avoid boxing the argument, improving performance. For more information, see [here](/dotnet/api/system.iequatable-1#notes-to-implementers).
32+
33+
Your <xref:System.IEquatable%601.Equals%2A?displayProperty=fullName> implementation should return results that are consistent with <xref:System.Object.Equals%2A>.
34+
35+
## How to fix violations
36+
37+
To fix a violation, implement <xref:System.IEquatable%601> and update <xref:System.Object.Equals%2A> override to invoke this implemented method. For example, the following two code snippets show a violation of the rule and how to fix it:
38+
39+
```csharp
40+
public struct S
41+
{
42+
private readonly int _value;
43+
public S(int f)
44+
{
45+
_value = f;
46+
}
47+
48+
public override int GetHashCode()
49+
=> _value.GetHashCode();
50+
51+
public override bool Equals(object other)
52+
=> other is S otherS && _value == otherS._value;
53+
}
54+
```
55+
56+
```csharp
57+
using System;
58+
59+
public struct S : IEquatable<S>
60+
{
61+
private readonly int _value;
62+
public S(int f)
63+
{
64+
_value = f;
65+
}
66+
67+
public override int GetHashCode()
68+
=> _value.GetHashCode();
69+
70+
public override bool Equals(object other)
71+
=> other is S otherS && Equals(otherS);
72+
73+
public bool Equals(S other)
74+
=> _value == other._value;
75+
}
76+
```
77+
78+
## When to suppress warnings
79+
80+
It is fine to suppress violations from this rule if the design and performance benefits from implementing the interface are not critical.
81+
82+
## Related rules
83+
84+
- [CA1067: Override Equals when implementing IEquatable](ca1067.md)
85+
86+
## See also
87+
88+
- [Design Warnings](../code-quality/design-warnings.md)

‎docs/code-quality/ca1067.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: 'CA1067: Override Equals when implementing IEquatable'
3+
ms.date: 04/23/2020
4+
ms.topic: reference
5+
f1_keywords:
6+
- CA1067
7+
helpviewer_keywords:
8+
- CA1067
9+
ms.assetid: 4e1bade4-4ca2-4219-abc3-c7b2d741e157
10+
author: mavasani
11+
ms.author: mavasani
12+
manager: jillfra
13+
ms.workload:
14+
- multiple
15+
---
16+
# CA1067: Override Equals when implementing IEquatable
17+
18+
|||
19+
|-|-|
20+
|TypeName|EquatableAnalyzer|
21+
|CheckId|CA1067|
22+
|Category|Microsoft.Design|
23+
|Breaking change|Non-breaking|
24+
25+
## Cause
26+
27+
A type implements <xref:System.IEquatable%601>, but does not override <xref:System.Object.Equals%2A> method.
28+
29+
## Rule description
30+
31+
A type implementing <xref:System.IEquatable%601> interface indicates that it supports comparing two instances of the type for equality. You should also override the base class implementations of <xref:System.Object.Equals%2A> and <xref:System.Object.GetHashCode> methods so that their behavior is consistent with that of the <xref:System.IEquatable%601.Equals%2A?displayProperty=fullName> implementation. See [here](/dotnet/api/system.iequatable-1#notes-to-implementers) for more details.
32+
33+
Your <xref:System.Object.Equals%2A> implementation should return results that are consistent with <xref:System.IEquatable%601.Equals%2A?displayProperty=fullName> implementation.
34+
35+
## How to fix violations
36+
37+
To fix a violation, override <xref:System.Object.Equals%2A> and implement it by invoking the <xref:System.IEquatable%601.Equals%2A?displayProperty=fullName> implementation. For example, the following two code snippets show a violation of the rule and how to fix it:
38+
39+
```csharp
40+
using System;
41+
42+
public struct S : IEquatable<S>
43+
{
44+
private readonly int _value;
45+
public S(int f)
46+
{
47+
_value = f;
48+
}
49+
50+
public bool Equals(S other)
51+
=> _value == other._value;
52+
}
53+
```
54+
55+
```csharp
56+
using System;
57+
58+
public struct S : IEquatable<S>
59+
{
60+
private readonly int _value;
61+
public S(int f)
62+
{
63+
_value = f;
64+
}
65+
66+
public bool Equals(S other)
67+
=> _value == other._value;
68+
69+
public override bool Equals(object obj)
70+
=> obj is S objS && Equals(objS);
71+
72+
public override int GetHashCode()
73+
=> _value.GetHashCode();
74+
}
75+
```
76+
77+
## When to suppress warnings
78+
79+
Do not suppress violations of this rule.
80+
81+
## Related rules
82+
83+
- [CA1066: Implement IEquatable when overriding Equals](ca1066.md)
84+
85+
## See also
86+
87+
- [Design Warnings](../code-quality/design-warnings.md)

‎docs/code-quality/ca1508.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: "CA1508: Avoid dead conditional code"
3+
ms.date: 04/23/2020
4+
ms.topic: reference
5+
f1_keywords:
6+
- "CA1508"
7+
- "AvoidDeadConditionalCode"
8+
helpviewer_keywords:
9+
- "CA1508"
10+
- "AvoidDeadConditionalCode"
11+
author: mavasani
12+
ms.author: mavasani
13+
manager: jillfra
14+
ms.workload:
15+
- "multiple"
16+
---
17+
# CA1508: Avoid dead conditional code
18+
19+
|||
20+
|-|-|
21+
|TypeName|AvoidDeadConditionalCode|
22+
|CheckId|CA1508|
23+
|Category|Microsoft.Maintainability|
24+
|Breaking change|Non-Breaking|
25+
26+
## Cause
27+
28+
A method has conditional code that always evaluates to `true` or `false` at runtime. This leads to dead code in the `false` branch of the condition.
29+
30+
## Rule description
31+
32+
Methods can have conditional code, such as if statements, binary expressions (`==`, `!=`, `<`, `>`), null checks, etc. For example, consider the following code:
33+
34+
```csharp
35+
public void M(int i, int j)
36+
{
37+
if (i != 0)
38+
{
39+
return;
40+
}
41+
42+
if (j != 0)
43+
{
44+
return;
45+
}
46+
47+
// Below condition will always evaluate to 'false' as 'i' and 'j' are both '0' here.
48+
if (i != j)
49+
{
50+
// Code in this 'if' branch is dead code.
51+
// It can either be removed or refactored.
52+
...
53+
}
54+
}
55+
```
56+
57+
C# and VB compilers perform analysis of conditional checks involving compile-time _constant values_ that always evaluate to `true` or `false`. This analyzer performs data flow analysis of non-constant variables to determine redundant conditional checks involving _non-constant values_. In the preceding code, the analyzer determines that `i` and `j` are both `0` for all code paths that reach `i != j` check. Hence, this check will always evaluate to `false` at runtime. The code inside the if statement is dead code and can be removed or refactored. Similarly, the analyzer tracks nullness of variables and reports redundant null checks.
58+
59+
> [!NOTE]
60+
> Rule CA1508 is not available in legacy analysis. It was first introduced in [FxCop analyzers](https://www.nuget.org/packages/Microsoft.CodeAnalysis.FxCopAnalyzers).
61+
> Note that this analyzer performs an expensive dataflow analysis of non-constant values. This can increase the overall compile time on certain code bases. Hence, this rule is disabled by default in the analyzer package. Users can enable this rule in editorconfig and perform a one-off analysis and code cleanup. For more information on enabling the rule in editorconfig, see [here](https://docs.microsoft.com/visualstudio/code-quality/use-roslyn-analyzers#rule-severity).
62+
63+
## When to suppress warnings
64+
65+
It's safe to suppress a violation of this rule if you're not concerned about the maintainability of your code. It is also fine to suppress violations that are identified to be false positives. These are possible in the presence of concurrent code that can execute from multiple threads.
66+
67+
## See also
68+
69+
- [Maintainability warnings](../code-quality/maintainability-warnings.md)

‎docs/code-quality/ca1826.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: "CA1826: Use property instead of Linq Enumerable method"
3+
ms.date: 04/24/2020
4+
ms.topic: reference
5+
f1_keywords:
6+
- "DoNotUseEnumerableMethodsOnIndexableCollectionsInsteadUseTheCollectionDirectlyAnalyzer"
7+
- "CA1826"
8+
helpviewer_keywords:
9+
- "DoNotUseEnumerableMethodsOnIndexableCollectionsInsteadUseTheCollectionDirectlyAnalyzer"
10+
- "CA1826"
11+
author: mavasani
12+
ms.author: mavasani
13+
manager: jillfra
14+
ms.workload:
15+
- "multiple"
16+
---
17+
# CA1826: Use property instead of Linq Enumerable method
18+
19+
|||
20+
|-|-|
21+
|TypeName|DoNotUseEnumerableMethodsOnIndexableCollectionsInsteadUseTheCollectionDirectlyAnalyzer|
22+
|CheckId|CA1826|
23+
|Category|Microsoft.Performance|
24+
|Breaking change|Non-breaking|
25+
26+
## Cause
27+
28+
The <xref:System.Linq.Enumerable> LINQ method was used on a type that supports an equivalent, more efficient property.
29+
30+
## Rule description
31+
32+
This rule flags the <xref:System.Linq.Enumerable> LINQ method calls on collections of types that have equivalent, but more efficient properties to fetch the same data.
33+
34+
This rule analyzes the following collection types:
35+
36+
- A type that implements <xref:System.Collections.Generic.IReadOnlyList%601>, but not <xref:System.Collections.Generic.IList%601>
37+
38+
This rule flags calls to following methods on these collection types:
39+
40+
- <xref:System.Linq.Enumerable.Count%2A?displayProperty=fullName> method
41+
- <xref:System.Linq.Enumerable.First%2A?displayProperty=fullName> method
42+
- <xref:System.Linq.Enumerable.FirstOrDefault%2A?displayProperty=fullName> method
43+
- <xref:System.Linq.Enumerable.Last%2A?displayProperty=fullName> method
44+
- <xref:System.Linq.Enumerable.LastOrDefault%2A?displayProperty=fullName> method
45+
46+
The analyzed collection types and/or methods may be extended in future to cover more cases.
47+
48+
> [!NOTE]
49+
> Rule CA1826 is not available in legacy analysis. It was first introduced in [FxCop analyzers](https://www.nuget.org/packages/Microsoft.CodeAnalysis.FxCopAnalyzers) version 2.9.6.
50+
51+
## How to fix violations
52+
53+
To fix a violation, replace the <xref:System.Linq.Enumerable> method calls with property access. For example, the following two code snippets show a violation of the rule and how to fix it:
54+
55+
```csharp
56+
using System;
57+
using System.Collections.Generic;
58+
using System.Linq;
59+
60+
class C
61+
{
62+
public void M(IReadOnlyList<string> list)
63+
{
64+
Console.Write(list.First());
65+
Console.Write(list.Last());
66+
Console.Write(list.Count());
67+
}
68+
}
69+
```
70+
71+
72+
```csharp
73+
using System;
74+
using System.Collections.Generic;
75+
76+
class C
77+
{
78+
public void M(IReadOnlyList<string> list)
79+
{
80+
Console.Write(list[0]);
81+
Console.Write(list[list.Count - 1]);
82+
Console.Write(list.Count);
83+
}
84+
}
85+
```
86+
87+
> [!TIP]
88+
> A code fix is available for this rule in Visual Studio. To use it, position the cursor on the violation and press **Ctrl**+**.** (period). Choose **Use indexer** from the list of options that's presented.
89+
>
90+
> ![Code fix for CA1826 - Use indexer](media/ca1826-codefix.png)
91+
92+
## When to suppress warnings
93+
94+
It's safe to suppress a violation of this rule if you're not concerned about the performance impact from specific <xref:System.Linq.Enumerable> method calls.
95+
96+
## Related rules
97+
98+
- [CA1827: Do not use Count/LongCount when Any can be used](ca1827.md)
99+
- [CA1828: Do not use CountAsync/LongCountAsync when AnyAsync can be used](ca1828.md)
100+
- [CA1829: Use Length/Count property instead of Enumerable.Count method](ca1829.md)
101+
102+
## See also
103+
104+
- [Performance warnings](../code-quality/performance-warnings.md)

0 commit comments

Comments
 (0)