CSharp.Refactor

CSharp.Refactor

The C# little-sister of FSharp.Refactor

Functional refactoring suggestions for C#, implemented in F# on Roslyn. The rules care about correctness, measured performance and clear idiomatic C# — and deliberately not about naming, layout or conventions.

• light bulb quick fixes in your editor (Visual Studio, VS Code, Rider, anything that hosts Roslyn analyzers)
• a command-line tool that applies them in bulk, build-verified

Suggestions are Info severity: they mark an opportunity, not a defect, and never gate your build.

---

Using it

The tool is fully offline: AI has been used to make it, but it doesn't use AI.

Quick start

Nothing to configure — the tool reads your project, reports what it would change, and only edits when you tell it to:

dotnet tool install --global csharp-refactor

csharp-refactor Your.csproj --dry-run --api-changes

That prints every fix it would make, with file and position, and writes nothing. When the list looks right, drop the flag to apply them:

csharp-refactor Your.csproj --api-changes

If you don't want change public methods / API, drop --api-changes:

csharp-refactor Your.fsproj

It refuses a compilation that does not already build, recompiles in memory after every pass, and builds the project for real at the end, putting the fixes back if that fails.

For light bulbs while you type, see VS Code / Ionide and Visual Studio IDE-plugin instructions below.

For agentic scenarios the dotnet tool supports MCP.

Using the tool:

Point it at whatever you have — the kind is read off the path:

Editor and CI setup

The analyzers ship as CSharp.Refactor.Analyzers, an ordinary Roslyn analyzer package. Reference it from the project you want analysed and every host — dotnet build, Visual Studio, VS Code's C# extension, Rider — loads it by itself:

<PackageReference Include="CSharp.Refactor.Analyzers" Version="*" PrivateAssets="all" />

The package is a development dependency: it only produces hints and quick fixes, and nothing from it reaches your compiled output or your bin.

Visual Studio 2022 / 2026

Install the CSharp.Refactor extension: every C# project opened in the IDE gets the suggestions and Ctrl+. fixes, with no project change and no effect on builds. Its Tools > CSharp.Refactor menu runs the csharp-refactor tool on the open solution (apply or dry run, with or without --api-changes), writes the SARIF report, opens the notes page and the .editorconfig block — the VS Code extension's commands, in Visual Studio. Or use the package reference above; both work, and a project with both sees each finding once.

VS Code

Install the CSharp.Refactor extension. It bundles the analyzers and, with your consent, wires them into every C# project on the machine through MSBuild's user ImportBefore hook (one props file under your profile, undone by a command). Or use the package reference.

CI

The analyzers run inside the compiler, so a build can write the findings as SARIF with no extra tool:

dotnet build -p:ErrorLog=findings.sarif

The tool's own report carries more — fixes as suggested changes, context snippets, stable fingerprints — and pairs with --dry-run for a lint gate:

      - run: dotnet tool install --global csharp-refactor

• run: csharp-refactor src/Your.csproj --dry-run --report findings.sarif
• uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: findings.sarif category: csharp-refactor

A dry run exits 0 whether or not it found anything; --fail-on-findings makes it exit 3 when a finding survives the filters, and --baseline turns that into a ratchet: findings already in an earlier report are neither reported nor fixed, only new ones surface.

Applying fixes from the command line

csharp-refactor Your.csproj [--dry-run] [--codes CR0090,CR0103] [--categories correctness,performance] [--api-changes]

Projects are loaded through MSBuildWorkspace — SDK-style projects of any target, net48 included, in every framework flavour they list. A legacy project ( with explicit items) is read from its project file when the .NET Framework build host does not answer: compile items, defines, HintPath references that exist, the targeting pack's assemblies and project references. Without the build tree (a reference a custom .targets adds, a sibling bin) some types stay unresolved; the run says how many, the typed rules stand down where a type is unknown, the in-memory check holds the error count, and the final build runs through Visual Studio's MSBuild.exe where a baseline build succeeds — otherwise the run is verified in memory only, and says so. An executable another project of the solution references (its tests) is not a leaf: its public shape stays unless --api-changes says otherwise, and every dependent of a changed project is built too. A C# script (.csx) is a compilation of its own: the file parsed as a script, the running runtime as its references, #r resolved against the script's directory, the runtime and the NuGet cache (#r "nuget: Name, Version"), #load read by the compiler for context (a loaded file is edited when it is swept as a target of its own, and a directory sweeps every loose script). Nothing builds a script, so the run is verified in memory: the error count may not grow, and a script host's globals (Args) count as errors on both sides.

Code under #if LOCAL_BUILD

Code behind a preprocessor symbol nothing defines is not in the parse tree at all: the tool neither analyses it nor sees what a fix elsewhere does to it, and the verification build compiles without it too. A repository that keeps, say, a local-development path under #if LOCAL_BUILD names the symbol for the run:

csharp-refactor Your.sln --define LOCAL_BUILD        # or --define:LOCAL_BUILD, -d:LOCAL_BUILD

csharp-refactor Your.sln --define "LOCAL_BUILD;CI" # several at once

or once for every run, in .editorconfig (csharp_refactor.defines = LOCAL_BUILD, below). The run uses both, and says at the start which symbols are active and where each came from. The symbols are added to what each project defines, exactly as dotnet build would see them with DefineConstants set in the environment: the SDK's DEBUG/TRACE, the target framework's NET8_0_OR_GREATER and the project's own $(DefineConstants);FOO all stay. (-p:DefineConstants=LOCAL_BUILD would not do: a global property replaces every one of them.) Every MSBuild the run starts — the workspace's design-time build, restores, the verification builds — gets them that way, and the loaded C# projects, legacy projects and .csx scripts get them in their parse options as well, so a project that assigns DefineConstants outright is still analysed with them. A script whose #r cannot be resolved while another #r sits under #if LOCAL_BUILD gets the hint to pass --define LOCAL_BUILD.

Configuration

Rules are configured the way every Roslyn analyzer is, in .editorconfig, nearest section winning:

[*.cs]

dotnet_diagnostic.CR0103.severity = none # off dotnet_diagnostic.CR0006.severity = suggestion # a default-off rule, on csharp_refactor.CR0006.then_at_least = 30 # a rule's knob

csharp_refactor.public_api = false # nothing links to this assembly csharp_refactor.api_changes = true # --api-changes as a standing decision csharp_refactor.suppressions = no-correctness # all | no-correctness | none csharp_refactor.skip_microsoft_duplicates = true # the Microsoft analyzers run here: skip what they already report csharp_refactor.ignore_paths = generated;external/imported csharp_refactor.defines = LOCAL_BUILD # like --define on every run

csharp_refactor.defines is a run-level key: it is read once per run, from the .editorconfig nearest the target (the walk stops at root = true), and adds to --define, never replacing it.

csharp-refactor --create-config writes the block for you, every value at this build's default, so it changes nothing until you edit a line. Each rule's knobs follow its severity line, at their defaults; a knob whose default is not one value (CR0023's measured floor, a rule's wrap_column, which falls back to the file's max_line_length) is written commented out.

A generated f