Zum Inhalt springen

Using platform profiles

Browse platform profiles, pin a version, apply updates, and include platform refs in your own profiles.

Updated on 2026-09-01

Platform profiles are curator-managed rule profiles published by the CodeCharter team. They provide versioned, ready-to-use rule sets you can reference directly from your CI pipeline without managing individual rules yourself.

What platform profiles are and who maintains them

Platform profiles are published and maintained centrally by the CodeCharter team. You cannot edit them, but you can pin any published version and reference it in your .codecharter/config.yml. Each profile has an immutable slug in the codecharter/ namespace, for example codecharter/csharp-all, the umbrella profile that includes the full C# rule set.

Profiles: adoption tiers and add-ons

The platform rule set is organised as three nested adoption tiers plus a few focused add-on profiles, so you can start small and ratchet up:

Slug Display name Coverage
codecharter/recommended Recommended Start here: a small, high-signal set of real correctness hazards plus the naming and encapsulation rules nearly every C# team already follows
codecharter/standard Standard Recommended plus the mainstream naming, async, complexity, and API-design rules
codecharter/strict Strict Standard plus the more demanding metric, design, and style rules
codecharter/aspnetcore ASP.NET Core Add-on: ASP.NET Core controller, action, and routing conventions
codecharter/documentation Documentation Add-on: XML documentation-comment coverage
codecharter/conventions Method & Role Conventions Opt-in: role- and verb-based naming and method-shape conventions (a deliberate house style)
codecharter/csharp-all C# All Rules Umbrella: every built-in rule

The tiers nest: recommended ⊂ standard ⊂ strict. The add-ons combine with any tier — pick a tier, then add codecharter/aspnetcore for web projects or codecharter/documentation for libraries. codecharter/conventions is an opinion-heavy house style and is not part of the tiers; enable it only if you want those conventions. codecharter/csharp-all remains the umbrella that contains every rule.

The exact rule list of each profile is shown on its detail page under Platform profiles in the portal. You reference any profile in your .codecharter/config.yml the same way:

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

Browsing profiles

Navigate to Platform profiles in the sidebar (/platform-rules) to see all available platform profiles. Each card shows the profile slug, the display name, the latest published version, and the number of rules it contains. The Details button opens the profile page with two tabs: Current version lists the rules included in the latest version, and Version history lists all versions with their publish date, rule count, and status.

Pinning a platform profile version

To use a platform profile in your CI, copy the ready-made CI snippet and add it to your .codecharter/config.yml:

  1. Click Copy CI snippet on the profile card. The copied snippet already contains the profile's slug and latest version.
  2. Paste the snippet into your .codecharter/config.yml:
# .codecharter/config.yml
version: 1
profiles: ["codecharter/csharp-all@1.0.0"]
  1. Run codecharter update locally to refresh the lockfile. By default the command targets the hosted portal and authenticates with your installed license. For a self-hosted portal, pass --portal-url; an API key with the read:rules scope (create one on the portal's API keys page) can optionally be passed via --api-key:
codecharter update --portal-url https://<your-portal> --api-key <your-api-key>
  1. Commit .codecharter/config.yml and .codecharter/codecharter.lock.json together in a PR.

Place .codecharter/config.yml in your repository so that codecharter analyze picks it up. In CI, codecharter restore then downloads the profile based on the lockfile without querying the portal for version resolution. restore needs no API key -- it authenticates with your installed license. When the cache is missing, codecharter analyze runs an implicit restore automatically.

Updates: when and how to update

Platform profiles follow semantic versioning. When the curator publishes a new version, nothing happens automatically in your CI -- your lockfile is frozen. To move to a new version:

  1. Change the version in .codecharter/config.yml to the desired new version.
  2. Run codecharter update locally.
  3. Review the diff of new rules and merge the PR.

Patch releases (x.y.Z) are non-breaking. Minor releases (x.Y.0) may add rules that were not checked before. Major releases (X.0.0) may include breaking changes, for example removed or renamed rules.

Yanked versions

When the CodeCharter team retracts a version as defective (yank), the CLI prints a warning on the next codecharter update run:

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

The warning does not block the command, and your build remains functional. We recommend updating to a non-yanked version promptly.

Besides retracting defective versions manually, the CodeCharter team also withdraws versions whose pinned rules the current engine can no longer evaluate — otherwise part of the rule set would be silently skipped there. Both cases behave the same for you:

  • @latest and other floating specs pass over withdrawn versions and resolve to a release whose rules all actually run.
  • An exact pin on a withdrawn version keeps working and still restores byte-for-byte; codecharter update tells you it was withdrawn and why, so you can choose when to move up.

Including platform refs in your own profiles

You can use a platform profile as the foundation for your own profile. Open your profile in the editor and find the Platform profile dependencies section. Click Add platform profile… to open a picker where you reference a platform profile at a pinned version. The dependency then appears as a row showing its slug and pinned version.

To adjust individual rules from a platform profile, use your .codecharter/config.yml: the overrides section changes a rule's severity, and the ignore section switches a rule off entirely. Rules are addressed by their slug, which is unique across profiles:

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

This lets you adopt platform standards as a baseline and add project-specific rules on top. See Configuration file for the full set of sections.

Further reading