Introduction

Converting a C# codebase to file-scoped namespaces in Visual Studio 2022 is mostly a workflow and tooling problem, not a manual editing task. The safest approach is to set style rules first, run a solution-wide code fix, and isolate the migration in a dedicated commit. Done well, this reduces indentation noise and keeps future files consistent. Because this refactor touches many files, migration sequencing matters as much as syntax conversion itself.

What File-Scoped Namespace Changes

Block-scoped style wraps every type in braces. File-scoped style uses one namespace statement ending with a semicolon. This feature was introduced in C# 10 alongside .NET 6.

1// block-scoped (traditional)
2namespace Company.Project.Services
3{
4    public class EmailService
5    {
6        public void Send() { }
7    }
8}

1// file-scoped (C# 10+)
2namespace Company.Project.Services;
3
4public class EmailService
5{
6    public void Send() { }
7}

For one-namespace-per-file code, semantics remain equivalent while reducing indentation depth by one level. Every type declaration in the file loses a tab or four spaces of leading whitespace. In a large codebase this removes thousands of lines of pure indentation noise from diffs.

Configure .editorconfig First

Set namespace declaration preference at repository root so IDE and CLI tools agree.

[*.cs]
csharp_style_namespace_declarations = file_scoped:warning

Start with warning instead of error. This lets you migrate incrementally and avoid blocking unrelated pull requests.

If your repository has generated files, exclude them in separate sections.

[*.Designer.cs]
csharp_style_namespace_declarations = block_scoped:none

Run Solution-Wide Conversion in Visual Studio 2022

In Visual Studio:

1. Open any file with block-scoped namespace.
2. Place cursor on namespace declaration.
3. Open quick actions menu.
4. Choose convert to file-scoped namespace.
5. Choose fix all in solution.

This uses Roslyn refactoring logic and is safer than regex-based replacements.

After conversion, rebuild immediately to catch edge files that need manual attention.

Command-Line Option with dotnet format

For teams that prefer scripted formatting in CI, use dotnet format with style diagnostics.

1# Fix all IDE0161 diagnostics (namespace style) across the solution
2dotnet format --diagnostics IDE0161
3
4# Preview changes without writing them
5dotnet format --diagnostics IDE0161 --verify-no-changes
6
7# Target a specific project instead of the whole solution
8dotnet format ./src/MyProject/MyProject.csproj --diagnostics IDE0161

Run it in a clean branch and keep the migration commit separate from feature work. A focused diff is easier to review and revert if needed. The dotnet format approach is especially useful for CI pipelines where you want automated enforcement without opening Visual Studio.

Handle Edge Cases Explicitly

Some files require manual checks:

• files containing multiple namespaces
• generated code committed from tooling
• source files with preprocessor directives near namespace declarations
• partial types split across unusual file layouts

For multi-namespace files, split content into separate files before applying file-scoped style. File-scoped syntax assumes one namespace declaration per file.

Migration Strategy for Active Teams

Namespace refactors touch many files and can create merge friction. A predictable rollout plan helps:

• schedule migration during low branch churn
• announce a temporary rebase window
• merge migration quickly after branch freeze
• ask long-lived branches to rebase right away

Avoid mixing logical changes with formatting migration. If both happen together, code review signal drops and conflict resolution gets harder.

Enforce for New Code

After migration is complete, tighten severity to prevent regressions.

[*.cs]
csharp_style_namespace_declarations = file_scoped:error

Then add style checks in CI. This stops reintroduction of block-scoped namespaces in new pull requests.

A typical CI step looks like this:

# Fail the build if any file violates namespace style
dotnet format --verify-no-changes --diagnostics IDE0161

This returns a non-zero exit code when any file still uses block-scoped namespaces, so your pipeline catches regressions before they merge.

Verify with a Quick Sanity Checklist

Before closing migration:

1. Run full solution build.
2. Run test suite.
3. Check generated file exclusions still work.
4. Confirm no files with multiple namespaces remain.
5. Confirm CI style checks pass.

This keeps migration quality high and avoids hidden breakage from formatting side effects.

Rollback and Partial Rollout Options

If a subset of projects has tooling incompatibility, you can adopt file-scoped style per project instead of whole solution. Use project-specific .editorconfig sections until all tools are upgraded.

For rollback, keeping migration in one commit makes revert simple:

git revert <migration-commit-sha>

Clean commit boundaries make style experiments low-risk.

Common Pitfalls

• No .editorconfig before converting: Running the conversion without an .editorconfig leads to inconsistent behavior across developers and IDE settings. Each developer's local preferences may disagree on namespace style, causing back-and-forth reformatting.
• Mixing namespace conversion with functional refactors: That increases review noise and hides real logic changes. Keep formatting migration in a standalone commit so reviewers can skip it confidently.
• Forgetting generated or special files: Generators overwrite their output on every run. If you convert generated files to file-scoped, the generator rewrites them back to block-scoped on the next build, causing repeated churn.
• Premature error enforcement: Switching to file_scoped:error before finishing migration blocks unrelated pull requests that happen to touch unconverted files.
• Not rebuilding after conversion: The Roslyn refactoring is reliable, but edge cases involving partial classes or conditional compilation can introduce subtle issues. Always rebuild and run tests immediately after the bulk conversion.

Summary

• Set namespace style in .editorconfig before changing files.
• Use Visual Studio fix-all or Roslyn tooling, not manual text replacement.
• Isolate migration in a dedicated commit to simplify review and rollback.
• Handle edge cases like multi-namespace and generated files explicitly.
• Enforce file-scoped style in CI only after migration is complete.