CA1200: Verwenden Sie keine cref-Tags mit einem Präfix.
| Eigenschaft | Wert |
|---|---|
| Regel-ID | CA1200 |
| Titel | Verwenden Sie keine cref-Tags mit einem Präfix. |
| Kategorie | Dokumentation |
| Fix führt oder führt nicht zur Unterbrechung | Nicht unterbrechend |
| Standardmäßig in .NET 8 aktiviert | Nein |
Ursache
Das cref-Tag in einem XML-Dokumentationskommentar verwendet ein Präfix.
Regelbeschreibung
Das cref-Attribut in einem XML-Dokumentationstag steht für „Code reference“ (Codeverweis). Es gibt an, dass der innere Text des Tags ein Codeelement ist, wie z.B. ein Typ, eine Methode oder Eigenschaft. Verwenden Sie keine cref-Tags mit Präfixen, da diese verhindern, dass der Compiler Referenzen überprüfen kann. Außerdem wird dadurch verhindert, dass die integrierte Entwicklungsumgebung (IDE) von Visual Studio diese Symbolverweise beim Refactoring findet und aktualisiert. Es wird empfohlen, dass Sie die vollständige Syntax ohne Präfixe verwenden, um auf Symbolnamen in den-Tags in-Tags zu verweisen.
Behandeln von Verstößen
Um einen Verstoß gegen diese Regel zu beheben, entfernen Sie das Präfix aus demcref-Tag. Die folgenden beiden Codeausschnitte zeigen z. B. einen Verstoß gegen die Regel und wie dieser korrigiert werden kann:
// Violates CA1200
/// <summary>
/// Type <see cref="T:C" /> contains method <see cref="F:C.F" />
/// </summary>
class C
{
public void F() { }
}
// Does not violate CA1200
/// <summary>
/// Type <see cref="C" /> contains method <see cref="F" />
/// </summary>
class C
{
public void F() { }
}
Wann sollten Warnungen unterdrückt werden?
Es ist ungefährlich, diese Warnung zu unterdrücken, wenn die Codereferenz ein Präfix verwenden muss, weil der referenzierte Typ vom Compiler nicht gefunden werden kann. Wenn z. B. eine Codereferenz auf ein spezielles Attribut im vollständigen Framework verweist, die Datei aber gegen das portable Framework kompiliert, können Sie diese Warnung unterdrücken.
Unterdrücken einer Warnung
Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.
#pragma warning disable CA1200
// The code that's violating the rule is on this line.
#pragma warning restore CA1200
Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad in der Konfigurationsdatei auf none fest.
[*.{cs,vb}]
dotnet_diagnostic.CA1200.severity = none
Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.
