Zum Inhalt springen

Plattform-Profile nutzen

Plattform-Profile durchsuchen, eine Version pinnen, Updates einspielen und Plattform-Refs in eigenen Profilen verwenden.

Aktualisiert am 2026-09-01

Plattform-Profile sind vom CodeCharter-Team kuratierte Regelprofile. Sie bieten versionierte, einsatzbereite Regelsets, die ihr direkt in eurer CI-Pipeline referenzieren könnt, ohne einzelne Regeln selbst pflegen zu müssen.

Was Plattform-Profile sind und wer sie pflegt

Plattform-Profile werden zentral vom CodeCharter-Team veröffentlicht und gewartet. Ihr könnt sie nicht bearbeiten, aber ihr könnt jede veröffentlichte Version pinnen und in eurer .codecharter/config.yml referenzieren. Jedes Profil hat einen unveränderlichen Slug im Namensraum codecharter/, zum Beispiel codecharter/csharp-all, das Dachprofil mit dem vollständigen C#-Regelset.

Profile: Adoptionsstufen und Add-ons

Der Plattform-Regelsatz ist als drei ineinander verschachtelte Adoptionsstufen plus einige fokussierte Add-on-Profile organisiert, sodass ihr klein anfangen und schrittweise hochziehen könnt:

Slug Anzeigename Abdeckung
codecharter/recommended Recommended Einstieg: ein kleiner, signalstarker Satz aus echten Korrektheitsrisiken sowie den Namens- und Kapselungsregeln, denen praktisch jedes C#-Team ohnehin folgt
codecharter/standard Standard Recommended plus die gängigen Regeln zu Naming, Async, Komplexität und API-Design
codecharter/strict Strict Standard plus die anspruchsvolleren Metrik-, Design- und Stilregeln
codecharter/aspnetcore ASP.NET Core Add-on: ASP.NET-Core-Controller, Actions und Routing-Konventionen
codecharter/documentation Documentation Add-on: Abdeckung mit XML-Dokumentationskommentaren
codecharter/conventions Method & Role Conventions Opt-in: rollen- und verbbasierte Namens- und Methodenform-Konventionen (ein bewusster Hausstil)
codecharter/csharp-all C# All Rules Dachprofil: alle eingebauten Regeln

Die Stufen verschachteln sich: recommended ⊂ standard ⊂ strict. Die Add-ons kombiniert ihr mit jeder Stufe: Wählt eine Stufe und ergänzt codecharter/aspnetcore für Web-Projekte oder codecharter/documentation für Bibliotheken. codecharter/conventions ist ein meinungsstarker Hausstil und nicht Teil der Stufen; aktiviert es nur, wenn ihr diese Konventionen wünscht. codecharter/csharp-all bleibt das Dachprofil mit allen Regeln.

Die genaue Regelliste jedes Profils seht ihr auf seiner Detailseite unter Plattform-Profile im Portal. Jedes Profil referenziert ihr in eurer .codecharter/config.yml auf dieselbe Weise:

# .codecharter/config.yml
version: 1
profiles: ["codecharter/recommended@1.0.0"]

Profile durchsuchen

Öffnet Plattform-Profile in der Seitenleiste (/platform-rules), um alle verfügbaren Plattform-Profile zu sehen. Jede Karte zeigt den Profil-Slug, den Anzeigenamen, die zuletzt veröffentlichte Version und die Anzahl der enthaltenen Regeln. Der Button Details öffnet die Profilseite mit zwei Tabs: Aktuelle Version listet die Regeln der neuesten Version, Versionsverlauf zeigt alle Versionen mit Veröffentlichungsdatum, Regelanzahl und Status.

Eine Plattform-Profil-Version pinnen

Um ein Plattform-Profil in eurer CI zu verwenden, kopiert ihr das fertige CI-Snippet und tragt es in eure .codecharter/config.yml ein:

  1. Klickt auf CI-Snippet kopieren auf der Profilkarte. Das kopierte Snippet enthält bereits den Slug und die neueste Version des Profils.
  2. Fügt das Snippet in eure .codecharter/config.yml ein:
# .codecharter/config.yml
version: 1
profiles: ["codecharter/csharp-all@1.0.0"]
  1. Führt lokal codecharter update aus, um das Lockfile zu aktualisieren. Der Befehl verwendet standardmäßig das gehostete Portal und authentifiziert sich mit eurer installierten Lizenz. Für ein selbst gehostetes Portal übergebt ihr --portal-url; ein API-Key mit dem Scope read:rules (anlegbar auf der Seite API-Keys im Portal) lässt sich optional per --api-key übergeben:
codecharter update --portal-url https://<portal-url> --api-key <api-key>
  1. Committet .codecharter/config.yml und .codecharter/codecharter.lock.json zusammen in einem PR.

Legt die .codecharter/config.yml in euer Repository, damit codecharter analyze sie findet. In der CI lädt codecharter restore das Profil dann anhand des Lockfiles herunter, ohne das Portal für eine Versionsauflösung abzufragen. restore braucht keinen API-Key, es authentifiziert sich mit eurer installierten Lizenz. Fehlt der Cache, führt codecharter analyze automatisch ein implizites Restore aus.

Updates: wann und wie ihr aktualisiert

Plattform-Profile folgen semantischer Versionierung. Wenn der Kurator eine neue Version veröffentlicht, passiert in eurer CI nichts automatisch: Euer Lockfile ist eingefroren. Um auf eine neue Version zu wechseln:

  1. Ändert die Version in .codecharter/config.yml auf die gewünschte neue Version.
  2. Führt codecharter update lokal aus.
  3. Prüft den Diff der neuen Regeln und mergt den PR.

Patch-Releases (x.y.Z) sind nicht brechend. Minor-Releases (x.Y.0) können neue Regeln enthalten, die vorher nicht geprüft wurden. Major-Releases (X.0.0) können brechende Änderungen umfassen, zum Beispiel entfernte oder umbenannte Regeln.

Yank: was passiert, wenn eine Version zurückgezogen wird

Wenn das CodeCharter-Team eine Version als fehlerhaft zurückzieht (Yank), zeigt die CLI beim nächsten codecharter update eine Warnung:

warning: Profile <slug>@<version> was yanked. Reason: <reason>. Consider running `codecharter update` to move to the next version.

Die Warnung blockiert den Befehl nicht und euer Build bleibt funktionsfähig. Wir empfehlen dennoch, zeitnah auf eine nicht-yanked Version zu wechseln.

Neben dem manuellen Zurückziehen fehlerhafter Versionen zieht das CodeCharter-Team auch Versionen zurück, deren gepinnte Regeln die aktuelle Engine nicht mehr auswerten kann, denn sonst würde ein Teil des Regelsets stillschweigend übersprungen. Für euch verhalten sich beide Fälle gleich:

  • @latest und andere Float-Angaben überspringen zurückgezogene Versionen und lösen auf ein Release auf, dessen Regeln vollständig laufen.
  • Ein exakter Pin auf eine zurückgezogene Version funktioniert weiterhin und restauriert byte-identisch; codecharter update nennt euch dabei den Grund des Rückzugs, damit ihr den Wechsel selbst planen könnt.

Plattform-Refs in eigenen Profilen einbinden

Ihr könnt ein Plattform-Profil als Basis für euer eigenes Profil verwenden. Öffnet euer Profil im Editor und geht zum Bereich Plattform-Profilabhängigkeiten. Über Plattform-Profil hinzufügen… öffnet sich eine Auswahl, in der ihr ein Plattform-Profil mit einer exakten Version referenziert. Die Abhängigkeit erscheint danach als Zeile mit Slug und gepinnter Version.

Einzelne Regeln eines Plattform-Profils passt ihr über eure .codecharter/config.yml an: Der Abschnitt overrides ändert die Severity einer Regel, der Abschnitt ignore schaltet sie vollständig ab. Regeln werden über ihren Slug adressiert, der über alle Profile hinweg eindeutig ist:

# .codecharter/config.yml
version: 1
overrides:
  <rule-slug>:
    severity: warning
ignore:
  - rule: <other-rule-slug>

So könnt ihr Plattform-Standards als Grundlage nehmen und projektspezifische Regeln ergänzend hinzufügen. Den vollständigen Satz an Abschnitten findet ihr unter Konfigurationsdatei.