CA1036: переопределяйте методы в сравнимых типах
| Свойство | Значение |
|---|---|
| Идентификатор правила | CA1036 |
| Заголовок | Переопределите методы в сопоставимых типах |
| Категория | Проектирование |
| Исправление является критическим или не критическим | Не критическое |
| Включен по умолчанию в .NET 9 | No |
Причина
Тип реализует интерфейс System.IComparable. Он не переопределяет System.Object.Equals и не перегружает языковые операторы "равно", "не равно", "меньше" и "больше". Правило не сообщает о нарушении, если тип наследует только реализацию интерфейса.
По умолчанию это правило проверяет только видимые извне типы, но это поведение можно настроить.
Описание правила
Типы, определяющие пользовательский порядок сортировки, реализуют интерфейс IComparable. Метод CompareTo возвращает целочисленное значение, указывающее правильный порядок сортировки для двух экземпляров типа. Это правило обнаруживает типы, которые задают порядок сортировки. Установка порядка сортировки подразумевает, что обычные значения "равно", "не равно", "меньше" и "больше" не применяются. Когда вы предоставляете реализацию IComparable, обычно также необходимо переопределять Equals, чтобы возвращались значения, соответствующие CompareTo. Если вы переопределяете Equals и пишете код на языке, поддерживающем перегрузки операторов, следует также предоставить операторы, которые соответствуют Equals.
Устранение нарушений
Чтобы устранить нарушение этого правила, переопределите метод Equals. Если ваш язык программирования поддерживает перегрузку операторов, укажите следующие операторы:
op_Equalityop_Inequalityop_LessThanop_GreaterThan
// In C#, implement these operators.
public static bool operator ==(SampleClass? one, SampleClass? other) { }
public static bool operator !=(SampleClass? one, SampleClass? other) { }
public static bool operator <(SampleClass? one, SampleClass? other) { }
public static bool operator >(SampleClass? one, SampleClass? other) { }
' In Visual Basic, implement these operators.
Public Shared Operator =(one As SampleClass, other As SampleClass) As Boolean
...
End Operator
Public Shared Operator <>(one As SampleClass, other As SampleClass) As Boolean
...
End Operator
Public Shared Operator <(one As SampleClass, other As SampleClass) As Boolean
...
End Operator
Public Shared Operator >(one As SampleClass, other As SampleClass) As Boolean
...
End Operator
Когда лучше отключить предупреждения
Это безопасно для подавления предупреждения от правила CA1036, если нарушение вызвано отсутствием операторов и языком программирования не поддерживает перегрузку оператора. Если определить, что реализация операторов не имеет смысла в контексте приложения, это также безопасно, чтобы отключить предупреждение от этого правила, если он запускается на операторах равенства, отличных от op_Equality. Однако при переопределении Object.Equalsнеобходимо всегда переопределить op_Equality и == оператор.
Отключение предупреждений
Если вы просто хотите отключить одно нарушение, добавьте директивы препроцессора в исходный файл, чтобы отключить и повторно включить правило.
#pragma warning disable CA1036
// The code that's violating the rule is on this line.
#pragma warning restore CA1036
Чтобы отключить правило для файла, папки или проекта, задайте его серьезность none в файле конфигурации.
[*.{cs,vb}]
dotnet_diagnostic.CA1036.severity = none
Дополнительные сведения см. в разделе Практическое руководство. Скрытие предупреждений анализа кода.
Настройка кода для анализа
Используйте следующий параметр, чтобы выбрать части базы кода для применения этого правила.
Этот параметр можно настроить только для этого правила, для всех правил, к которым он применяется, или для всех правил в этой категории (конструкторе), к которым она применяется. Дополнительные сведения см. в статье Параметры конфигурации правила качества кода.
Включение определенных контактных зон API
Вы можете настроить, для каких частей базы кода следует выполнять это правило в зависимости от их доступности. Например, чтобы указать, что правило должно выполняться только для закрытой контактной зоны API, добавьте следующую пару "ключ-значение" в файл EDITORCONFIG в своем проекте:
dotnet_code_quality.CAXXXX.api_surface = private, internal
Примеры
Следующий код содержит тип, который правильно реализует IComparable. В комментариях к коду определены методы, которые соответствуют различным правилам, связанным с Equals и интерфейсом IComparable.
// Valid ratings are between A and C.
// A is the highest rating; it is greater than any other valid rating.
// C is the lowest rating; it is less than any other valid rating.
public class RatingInformation : IComparable, IComparable<RatingInformation>
{
public string Rating { get; private set; }
public RatingInformation(string rating)
{
ArgumentNullException.ThrowIfNull(rating);
string v = rating.ToUpper(CultureInfo.InvariantCulture);
if (v.Length != 1 ||
string.Compare(v, "C", StringComparison.Ordinal) > 0 ||
string.Compare(v, "A", StringComparison.Ordinal) < 0)
{
throw new ArgumentException("Invalid rating value was specified.", nameof(rating));
}
Rating = v;
}
public int CompareTo(object? obj)
{
if (obj == null)
{
return 1;
}
if (obj is RatingInformation other)
{
return CompareTo(other);
}
throw new ArgumentException("A RatingInformation object is required for comparison.", nameof(obj));
}
public int CompareTo(RatingInformation? other)
{
if (other is null)
{
return 1;
}
// Ratings compare opposite to normal string order,
// so reverse the value returned by String.CompareTo.
return -string.Compare(Rating, other.Rating, StringComparison.OrdinalIgnoreCase);
}
public static int Compare(RatingInformation left, RatingInformation right)
{
if (object.ReferenceEquals(left, right))
{
return 0;
}
if (left is null)
{
return -1;
}
return left.CompareTo(right);
}
// Omitting Equals violates rule: OverrideMethodsOnComparableTypes.
public override bool Equals(object? obj)
{
if (obj is RatingInformation other)
{
return CompareTo(other) == 0;
}
return false;
}
// Omitting getHashCode violates rule: OverrideGetHashCodeOnOverridingEquals.
public override int GetHashCode()
{
char[] c = Rating.ToCharArray();
return (int)c[0];
}
// Omitting any of the following operator overloads
// violates rule: OverrideMethodsOnComparableTypes.
public static bool operator ==(RatingInformation left, RatingInformation right)
{
if (left is null)
{
return right is null;
}
return left.Equals(right);
}
public static bool operator !=(RatingInformation left, RatingInformation right)
{
return !(left == right);
}
public static bool operator <(RatingInformation left, RatingInformation right)
{
return (Compare(left, right) < 0);
}
public static bool operator >(RatingInformation left, RatingInformation right)
{
return (Compare(left, right) > 0);
}
}
Imports System.Globalization
Public Class RatingInformation
Implements IComparable
Implements IComparable(Of RatingInformation)
Public Sub New(rating As String)
ArgumentNullException.ThrowIfNull(rating)
Dim v As String = rating.ToUpper(CultureInfo.InvariantCulture)
If (v.Length <> 1 Or
String.Compare(v, "C", StringComparison.Ordinal) > 0 Or
String.Compare(v, "A", StringComparison.Ordinal) < 0) Then
Throw New ArgumentException("Invalid rating value was specified.", NameOf(rating))
End If
Me.Rating = v
End Sub
Public ReadOnly Property Rating As String
Public Function CompareTo(obj As Object) As Integer Implements IComparable.CompareTo
If (obj Is Nothing) Then Return 1
If (TypeOf obj IsNot RatingInformation) Then Return 0
Dim other As RatingInformation = DirectCast(obj, RatingInformation)
Return CompareTo(other)
End Function
Public Function CompareTo(other As RatingInformation) As Integer Implements IComparable(Of RatingInformation).CompareTo
If (other Is Nothing) Then Return 1
' Ratings compare opposite To normal String order,
' so reverse the value returned by String.CompareTo.
Return -String.Compare(Rating, other.Rating, StringComparison.OrdinalIgnoreCase)
End Function
Public Shared Operator =(one As RatingInformation, other As RatingInformation) As Boolean
If (one Is Nothing) Then Return (other Is Nothing)
If (other Is Nothing) Then Return False
Return (one.Rating = other.Rating)
End Operator
Public Shared Operator <>(one As RatingInformation, other As RatingInformation) As Boolean
If (one Is Nothing) Then Return (other IsNot Nothing)
If (other Is Nothing) Then Return True
Return (one.Rating <> other.Rating)
End Operator
Public Shared Operator <(one As RatingInformation, other As RatingInformation) As Boolean
If (one Is Nothing) Then Return (other IsNot Nothing)
If (other Is Nothing) Then Return False
Return (one.Rating < other.Rating)
End Operator
Public Shared Operator >(one As RatingInformation, other As RatingInformation) As Boolean
If (one Is Nothing) Then Return False
If (other Is Nothing) Then Return True
Return (one.Rating > other.Rating)
End Operator
Public Overrides Function Equals(obj As Object) As Boolean
If ReferenceEquals(Me, obj) Then
Return True
End If
If obj Is Nothing Then
Return False
End If
Throw New NotImplementedException()
End Function
Public Overrides Function GetHashCode() As Integer
Throw New NotImplementedException()
End Function
End Class
Следующий код приложения проверяет поведение реализации IComparable, показанной ранее.
public class TestCompare
{
public static void Main1036(params string[] args)
{
if (args.Length < 2)
{
return;
}
RatingInformation r1 = new(args[0]);
RatingInformation r2 = new(args[1]);
string answer;
if (r1.CompareTo(r2) > 0)
answer = "greater than";
else if (r1.CompareTo(r2) < 0)
answer = "less than";
else
answer = "equal to";
Console.WriteLine("{0} is {1} {2}", r1.Rating, answer, r2.Rating);
}
}
Public Class TestCompare
Public Shared Sub Main1036(ByVal args As String())
If (args.Length < 2) Then
Return
End If
Dim r1 As New RatingInformation(args(0))
Dim r2 As New RatingInformation(args(1))
Dim answer As String
If (r1.CompareTo(r2) > 0) Then
answer = "greater than"
ElseIf (r1.CompareTo(r2) < 0) Then
answer = "less than"
Else
answer = "equal to"
End If
Console.WriteLine("{0} is {1} {2}", r1.Rating, answer, r2.Rating)
End Sub
End Class
