Format

dotnet format

Trigger On

• the repo uses dotnet format
• you need a CI-safe formatting check for .NET
• the repo wants .editorconfig-driven style enforcement

Value

• produce a concrete project delta: code, docs, config, tests, CI, or review artifact
• reduce ambiguity through explicit planning, verification, and final validation skills
• leave reusable project context so future tasks are faster and safer

Do Not Use For

• repositories that intentionally use CSharpier as the only formatter
• analyzer strategy with no formatting command change

Inputs

• the nearest AGENTS.md
• the solution or project path
• the current .editorconfig

Quick Start

1. Read the nearest AGENTS.md and confirm scope and constraints. 2. Run this skill's Workflow through the Ralph Loop until outcomes are acceptable. 3. Return the Required Result Format with concrete artifacts and verification evidence.

Workflow

1. Prefer the SDK-provided dotnet format command instead of inventing custom format scripts. 2. Start with verify mode in CI: dotnet format TARGET --verify-no-changes. 3. Use narrower subcommands only when the repo needs them:

• whitespace
• style
• analyzers

4. Keep .editorconfig as the source of truth for style preferences. 5. If the repo also uses CSharpier, document which tool owns which file types or rules.

Bootstrap When Missing

If dotnet format is requested but not available yet:

1. Detect current state:

• dotnet --info
• dotnet format --version

2. Treat dotnet format as SDK-provided, not as a separate repo-local tool by default. 3. If the command is missing, install or upgrade to a supported .NET SDK, then recheck dotnet format --version. 4. Add explicit local and CI commands to AGENTS.md, usually:

• dotnet format TARGET --verify-no-changes

5. Run the chosen command once and return status: configured or status: improved. 6. If the repo intentionally uses only CSharpier for formatting ownership, return status: not_applicable.

Deliver

• explicit dotnet format commands for local and CI runs
• formatting that follows .editorconfig

Validate

• formatting is reproducible on CI
• no overlapping formatter ownership is left ambiguous

Ralph Loop

Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.

1. Plan first (mandatory):

• analyze current state
• define target outcome, constraints, and risks
• write a detailed execution plan
• list final validation skills to run at the end, with order and reason

2. Execute one planned step and produce a concrete delta. 3. Review the result and capture findings with actionable next fixes. 4. Apply fixes in small batches and rerun the relevant checks or review steps. 5. Update the plan after each iteration. 6. Repeat until outcomes are acceptable or only explicit exceptions remain. 7. If a dependency is missing, bootstrap it or return status: not_applicable with explicit reason and fallback path.

Required Result Format

• status: complete | clean | improved | configured | not_applicable | blocked
• plan: concise plan and current iteration step
• actions_taken: concrete changes made
• validation_skills: final skills run, or skipped with reasons
• verification: commands, checks, or review evidence summary
• remaining: top unresolved items or none

For setup-only requests with no execution, return status: configured and exact next commands.

Load References

• references/format.md
• references/dotnet-format.md
• references/commands.md
• references/config.md

Example Requests

• "Add dotnet format to this repo."
• "Make formatting fail CI if files drift."
• "Explain when to use dotnet format versus CSharpier."

dotnet format CLI Commands

Use this reference for all dotnet format command patterns, options, and CI integration.

Basic Commands

# Format entire solution
dotnet format MySolution.sln

# Format specific project
dotnet format MyProject.csproj

# Format current directory (finds solution or project automatically)
dotnet format

Verification Mode (CI)

# Fail if any files would change (CI gate)
dotnet format --verify-no-changes

# Verify with specific target
dotnet format MySolution.sln --verify-no-changes

# Verify with diagnostics output
dotnet format --verify-no-changes --verbosity diagnostic

Subcommands

# Format whitespace only (indentation, line endings)
dotnet format whitespace MySolution.sln

# Format code style only (editorconfig style rules)
dotnet format style MySolution.sln

# Apply analyzer code fixes
dotnet format analyzers MySolution.sln

Subcommand Verification

# Verify whitespace only
dotnet format whitespace MySolution.sln --verify-no-changes

# Verify style only
dotnet format style MySolution.sln --verify-no-changes

# Verify analyzers only
dotnet format analyzers MySolution.sln --verify-no-changes

Filtering Options

# Include only specific files (glob pattern)
dotnet format --include "src/**/*.cs"

# Exclude specific files (glob pattern)
dotnet format --exclude "**/*.Designer.cs"

# Combine include and exclude
dotnet format --include "src/**/*.cs" --exclude "**/Generated/**"

# Multiple includes
dotnet format --include "src/**/*.cs" --include "tests/**/*.cs"

Diagnostic Options

# Apply fixes for specific diagnostic IDs
dotnet format analyzers --diagnostics IDE0005

# Apply fixes for multiple diagnostics
dotnet format analyzers --diagnostics IDE0005 IDE0051 IDE0052

# Apply fixes for specific severity
dotnet format analyzers --severity error
dotnet format analyzers --severity warn
dotnet format analyzers --severity info

Verbosity Options

# Quiet output
dotnet format --verbosity quiet

# Minimal output
dotnet format --verbosity minimal

# Normal output (default)
dotnet format --verbosity normal

# Detailed output
dotnet format --verbosity detailed

# Diagnostic output (most verbose)
dotnet format --verbosity diagnostic

Report Generation

# Generate JSON report
dotnet format --report format-report.json

# Generate report with verification
dotnet format --verify-no-changes --report format-report.json

Binary Log Support

# Use existing binary log for analysis
dotnet format --binarylog build.binlog

No Restore Option

# Skip restore (use when already restored)
dotnet format --no-restore

CI Workflow Examples

GitHub Actions

- name: Verify formatting
  run: dotnet format --verify-no-changes --verbosity diagnostic

Azure DevOps

- script: dotnet format --verify-no-changes --verbosity diagnostic
  displayName: 'Verify code formatting'

Pre-commit Hook

#!/bin/bash
dotnet format --verify-no-changes
if [ $? -ne 0 ]; then
  echo "Code formatting issues detected. Run 'dotnet format' to fix."
  exit 1
fi

Common Patterns

# Full verification pipeline
dotnet format whitespace --verify-no-changes && \
dotnet format style --verify-no-changes && \
dotnet format analyzers --verify-no-changes

# Fix all formatting issues
dotnet format

# Fix and report
dotnet format --report format-changes.json

# Targeted analyzer fixes
dotnet format analyzers --diagnostics IDE0005 --severity warn

Exit Codes

Sources

• dotnet format command
• Code style rule options

.editorconfig Settings for dotnet format

Use this reference for .editorconfig configuration that controls dotnet format behavior.

File Structure

repo-root/
  .editorconfig          # Root config, source of truth
  src/
    .editorconfig        # Optional: subtree overrides
  tests/
    .editorconfig        # Optional: relaxed rules for tests

Root .editorconfig Template

# Root EditorConfig
root = true

# All files
[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

# C# files
[*.cs]
indent_size = 4

# XML files
[*.{xml,csproj,props,targets}]
indent_size = 2

# JSON files
[*.json]
indent_size = 2

# YAML files
[*.{yml,yaml}]
indent_size = 2

C# Code Style Options

Using Directives

[*.cs]
# Sort System.* usings first
dotnet_sort_system_directives_first = true

# Place usings outside namespace
csharp_using_directive_placement = outside_namespace:warning

Namespace Declarations

[*.cs]
# File-scoped namespaces (C# 10+)
csharp_style_namespace_declarations = file_scoped:warning

# Block-scoped namespaces (traditional)
# csharp_style_namespace_declarations = block_scoped:warning

Expression-bodied Members

[*.cs]
# Methods
csharp_style_expression_bodied_methods = when_on_single_line:suggestion

# Constructors
csharp_style_expression_bodied_constructors = false:suggestion

# Properties
csharp_style_expression_bodied_properties = true:suggestion

# Accessors
csharp_style_expression_bodied_accessors = true:suggestion

# Lambdas
csharp_style_expression_bodied_lambdas = true:suggestion

# Local functions
csharp_style_expression_bodied_local_functions = when_on_single_line:suggestion

Pattern Matching

[*.cs]
# Prefer pattern matching over is/as
csharp_style_pattern_matching_over_is_with_cast_check = true:suggestion
csharp_style_pattern_matching_over_as_with_null_check = true:suggestion

# Prefer not pattern
csharp_style_prefer_not_pattern = true:suggestion

# Prefer extended property pattern
csharp_style_prefer_extended_property_pattern = true:suggestion

Null Checking

[*.cs]
# Prefer null-coalescing
csharp_style_coalesce_expression = true:suggestion

# Prefer null-conditional
csharp_style_conditional_delegate_call = true:suggestion

# Prefer throw expression
csharp_style_throw_expression = true:suggestion

# Prefer null-propagation
dotnet_style_null_propagation = true:suggestion

var Preferences

[*.cs]
# Use var when type is apparent
csharp_style_var_for_built_in_types = true:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion
csharp_style_var_elsewhere = true:suggestion

Braces

[*.cs]
# Prefer braces
csharp_prefer_braces = true:warning

# Allow single-line (when_multiline)
# csharp_prefer_braces = when_multiline:suggestion

New Line Preferences

[*.cs]
# New line before open brace
csharp_new_line_before_open_brace = all

# New line before else
csharp_new_line_before_else = true

# New line before catch
csharp_new_line_before_catch = true

# New line before finally
csharp_new_line_before_finally = true

# New line before members in object initializers
csharp_new_line_before_members_in_object_initializers = true

# New line before members in anonymous types
csharp_new_line_before_members_in_anonymous_types = true

# New line between query expression clauses
csharp_new_line_between_query_expression_clauses = true

Indentation Preferences

[*.cs]
# Indent case contents
csharp_indent_case_contents = true

# Indent switch labels
csharp_indent_switch_labels = true

# Indent block contents
csharp_indent_block_contents = true

# Indent braces
csharp_indent_braces = false

# Indent case contents when block
csharp_indent_case_contents_when_block = false

Spacing Preferences

[*.cs]
# Space after cast
csharp_space_after_cast = false

# Space after keywords in control flow
csharp_space_after_keywords_in_control_flow_statements = true

# Space between method declaration parameter list parentheses
csharp_space_between_method_declaration_parameter_list_parentheses = false

# Space between method call parameter list parentheses
csharp_space_between_method_call_parameter_list_parentheses = false

# Space before colon in inheritance clause
csharp_space_before_colon_in_inheritance_clause = true

# Space after colon in inheritance clause
csharp_space_after_colon_in_inheritance_clause = true

# Space around binary operators
csharp_space_around_binary_operators = before_and_after

Naming Conventions

[*.cs]
# PascalCase for public members
dotnet_naming_rule.public_members_should_be_pascal_case.severity = warning
dotnet_naming_rule.public_members_should_be_pascal_case.symbols = public_symbols
dotnet_naming_rule.public_members_should_be_pascal_case.style = pascal_case_style

dotnet_naming_symbols.public_symbols.applicable_kinds = property,method,field,event,delegate
dotnet_naming_symbols.public_symbols.applicable_accessibilities = public

dotnet_naming_style.pascal_case_style.capitalization = pascal_case

# camelCase for private fields
dotnet_naming_rule.private_fields_should_be_camel_case.severity = warning
dotnet_naming_rule.private_fields_should_be_camel_case.symbols = private_fields
dotnet_naming_rule.private_fields_should_be_camel_case.style = camel_case_style

dotnet_naming_symbols.private_fields.applicable_kinds = field
dotnet_naming_symbols.private_fields.applicable_accessibilities = private

dotnet_naming_style.camel_case_style.capitalization = camel_case

# _camelCase for private fields with underscore prefix
dotnet_naming_rule.private_fields_should_be_underscore_camel.severity = warning
dotnet_naming_rule.private_fields_should_be_underscore_camel.symbols = private_fields_underscore
dotnet_naming_rule.private_fields_should_be_underscore_camel.style = underscore_camel_style

dotnet_naming_symbols.private_fields_underscore.applicable_kinds = field
dotnet_naming_symbols.private_fields_underscore.applicable_accessibilities = private

dotnet_naming_style.underscore_camel_style.capitalization = camel_case
dotnet_naming_style.underscore_camel_style.required_prefix = _

# Interfaces should begin with I
dotnet_naming_rule.interface_should_begin_with_i.severity = warning
dotnet_naming_rule.interface_should_begin_with_i.symbols = interface_symbols
dotnet_naming_rule.interface_should_begin_with_i.style = interface_style

dotnet_naming_symbols.interface_symbols.applicable_kinds = interface
dotnet_naming_symbols.interface_symbols.applicable_accessibilities = *

dotnet_naming_style.interface_style.capitalization = pascal_case
dotnet_naming_style.interface_style.required_prefix = I

Analyzer Severity Configuration

[*.cs]
# IDE0005: Remove unnecessary usings
dotnet_diagnostic.IDE0005.severity = warning

# IDE0051: Remove unused private members
dotnet_diagnostic.IDE0051.severity = warning

# IDE0052: Remove unread private members
dotnet_diagnostic.IDE0052.severity = warning

# IDE0055: Fix formatting
dotnet_diagnostic.IDE0055.severity = warning

# IDE0060: Remove unused parameter
dotnet_diagnostic.IDE0060.severity = suggestion

# IDE0161: Convert to file-scoped namespace
dotnet_diagnostic.IDE0161.severity = warning

# CA1848: Use LoggerMessage delegates
dotnet_diagnostic.CA1848.severity = suggestion

# CA2007: Consider calling ConfigureAwait
dotnet_diagnostic.CA2007.severity = none

Test Project Relaxations

# tests/.editorconfig
[*.cs]
# Allow more flexibility in test naming
dotnet_naming_rule.public_members_should_be_pascal_case.severity = suggestion

# Relax unused parameter warnings for test methods
dotnet_diagnostic.IDE0060.severity = none

# Allow async void for test setup/teardown
dotnet_diagnostic.VSTHRD100.severity = none

Generated Code Exclusions

# Exclude generated files
[*.Designer.cs]
generated_code = true

[*.g.cs]
generated_code = true

[**/obj/**/*.cs]
generated_code = true

Severity Levels

Verification

# Verify editorconfig is applied
dotnet format --verify-no-changes --verbosity diagnostic

# Check specific style rules
dotnet format style --verify-no-changes

# Check specific analyzer rules
dotnet format analyzers --verify-no-changes

Sources

• EditorConfig settings
• .NET code style rule options
• Naming rules
• Configuration files for code analysis

dotnet format

Open/Free Status

• first-party .NET tooling
• free to use with the .NET SDK

Install

Usually no extra install is needed beyond the .NET SDK because dotnet format is an SDK command.

If the repo intentionally pins an older standalone tool, follow the repo's existing tool manifest instead of inventing a new installation path.

Verify First

Before changing install guidance, verify that the command already works:

dotnet format -h

Common Commands

dotnet format MySolution.sln
dotnet format MySolution.sln --verify-no-changes
dotnet format whitespace MySolution.sln --verify-no-changes
dotnet format style MySolution.sln --verify-no-changes
dotnet format analyzers MySolution.sln --verify-no-changes

CI Fit

• use --verify-no-changes as the default gate
• keep .editorconfig in repo and versioned
• do not pair dotnet format and CSharpier without explicit ownership

When Not To Use

• when the repo intentionally standardized on CSharpier as the sole formatter for C# and XML
• when the target is not an SDK-style .NET solution or project

Sources

• dotnet format command