CSharpier

SyntaxFinder is a tool used to scan C# code files using SyntaxWalkers to analyze developer preferences and code patterns. It is primarily used for research and data collection, such as:

• Determining if developers prefer spaces or tabs.
• Determining if developers prefer always using braces or no braces.
• Identifying if developers add empty lines into object initializers.
• Finding files that contain specific types of SyntaxNodes.
• Printing examples of how specific types of Syntax were formatted.

CSharpier is an opinionated code formatter for C# and XML. It works by parsing your code and re-printing it according to its own internal rules. The printing process is based on a port of Prettier but has evolved specifically for C# and XML.

CSharpier follows the Prettier 'Option Philosophy', meaning it provides a minimal set of configuration options to ensure consistent formatting across projects. Requests for new formatting options are generally considered out of scope.

Beyond manual CLI usage, CSharpier can be integrated into your development workflow in several ways:

• Editor Integration: Configure your editor to format code automatically on save.
• Pre-commit Hooks: Use CSharpier to ensure code is formatted before commits are finalized.
• Build Process: Integrate formatting as part of your MSBuild process.
• Programmatic Usage: Call CSharpier via its API within your own applications.
• CI/CD: Use CSharpier in your continuous integration pipelines to enforce formatting standards across the codebase.

When performing a formatting action, CSharpier follows a specific resolution order to determine which version of the tool to use. It attempts to find the most relevant version in this priority:

1. MSBuild version: It first looks for a version defined within the .csproj file.
2. Local dotnet tool: It checks for a local version installed via dotnet tools (e.g., via a tool manifest).
3. Global version: It falls back to a globally installed version of CSharpier.

Ensuring the correct version is used is critical for consistent formatting (for example, ensuring specific rules like adding blank lines between methods are applied correctly).

The CSharpier extension supports several formatting triggers and contexts:

• Automatic Warming: Existing open documents are warmed up for formatting.
• Edit-based Formatting: Formatting can be triggered by edits made to the document.
• Run on Save: The extension supports 'run on save' functionality (specifically in VS Code).
• Unsaved Documents: Unsaved documents can be formatted (primarily applicable to VS Code).
• Language Filtering: Formatting actions are only shown/available for C# files.

The extension requires the dotnet CLI to function. It uses the following resolution logic to find the dotnet executable:

1. Uses the path specified in dotnet.dotnetPath if set.
2. Uses the paths specified in omnisharp.dotNetCliPaths if set.
3. Attempts to run dotnet --info to check if it is on the system PATH.
4. On non-Windows systems, it attempts to run sh -c "dotnet --info" to check the PATH.

The Rider plugin does not include the formatter itself; it uses the dotnet tool CSharpier. The plugin determines which version of CSharpier to use by following this priority:

1. It looks for a dotnet manifest file in your project to use a local, project-specific version.
2. If no manifest is found, it looks for a globally installed version of CSharpier on your system.

If the CSharpier extension is unable to format files, you can enable debug logging to capture more information about the failure. The process varies by editor:

Visual Studio

1. Navigate to Tools - Options - CSharpier.
2. Set Log Debug Messages to true.

VSCode

1. Navigate to File - Preferences - Settings - Extensions - CSharpier.
2. Check Enable debug logs.
3. Restart VSCode.

Rider

1. Execute the action Debug Log Settings.
2. Add an entry for #com.intellij.csharpier.CSharpierLogger.
3. Restart Rider.

Ignoring code in XML follows a similar pattern to C#. Use XML comments to wrap the elements you wish to exclude from formatting.

• Single element: Use <!-- csharpier-ignore --> before the element.
• Ranged elements: Use <!-- csharpier-ignore-start --> and <!-- csharpier-ignore-end --> to wrap a block of XML.

<Root>
  <Child>
    <!-- csharpier-ignore -->
    <Element   />
    
    <!-- csharpier-ignore-start -->
    <Element   />
    <Element   SomeAttribute = "yeah"   />
    <!-- csharpier-ignore-end -->
  </Child>
</Root>

CSharpier can be configured using several file types. The configuration file is resolved based on the location of the file being formatted: it looks for a .csharpierrc file (JSON or YAML) or a .csharpierrc.json/.csharpierrc.yaml file at or above the target file. If none are found, it falls back to an .editorconfig file, respecting standard editorconfig inheritance.

Supported configuration files:

• .csharpierrc (JSON or YAML)
• .csharpierrc.json (JSON)
• .csharpierrc.yaml (YAML)
• .editorconfig (INI)