Skip to content

ATC220.md

Latest commit

 

History

History
168 lines (118 loc) · 5.79 KB

ATC220.md

File metadata and controls

168 lines (118 loc) · 5.79 KB

🌐 ATC220: Use global usings for all namespaces

📂 Category

Style

⚠️ Severity

Warning

📖 Description

All using directives should be defined as global usings in GlobalUsings.cs for maximum consistency and minimal boilerplate across the codebase. This ensures every namespace import is centralized in one location.

📋 Rules

  1. All namespaces: Any using directive should be moved to GlobalUsings.cs
  2. Applies to: Regular using directives only
  3. Does NOT apply to:
    • Static using directives (using static System.Console)
    • Using aliases (using Constants = Domain.Constants)
    • Using directives already in GlobalUsings.cs
    • Generated code files

💡 Motivation

Centralizing all namespace imports in GlobalUsings.cs provides several benefits:

  • Maximum boilerplate reduction: Eliminates ALL repetitive using statements across files
  • Ultimate consistency: Every file has access to the same namespaces
  • Single source of truth: All namespace imports managed in one place
  • Cleanest files: Individual files only need using aliases if required
  • Easiest maintenance: Changes to namespace imports only need to be made once

This is the most aggressive global usings policy, suitable for projects where you want absolutely minimal boilerplate.

🔀 ATC220 and ATC221: Working Together

Both ATC220 and ATC221 enforce global usings, but they differ in scope:

Aspect ATC220 (Strict) ATC221 (Lenient)
Policy Non-common namespaces (by default) Only System/Microsoft/Atc
Flags Third-party and custom using directives Only common framework usings
Third-party libs Must be in GlobalUsings.cs Can stay in individual files
Best for Catching all remaining non-common usings Centralizing common framework usings

Automatic Mutual Exclusivity

By default, both rules can be enabled simultaneously without producing duplicate warnings. ATC220 automatically excludes namespaces that ATC221 handles (System, Microsoft, Atc), so each using directive triggers at most one warning.

Scenario ATC220 fires on ATC221 fires on
Both enabled (default) Third-party/custom namespaces System/Microsoft/Atc
Only ATC220 (exclude_common_namespaces = false) Everything n/a
Only ATC221 n/a System/Microsoft/Atc

Configuration Examples

# Both enabled (default) - no overlap, each rule covers its own scope
dotnet_diagnostic.ATC220.severity = warning
dotnet_diagnostic.ATC221.severity = warning

# Use ATC220 for ALL namespaces (disable ATC221 and the exclusion)
dotnet_diagnostic.ATC220.severity = warning
dotnet_diagnostic.ATC220.exclude_common_namespaces = false
dotnet_diagnostic.ATC221.severity = none

# Use only ATC221 for common namespaces
dotnet_diagnostic.ATC220.severity = none
dotnet_diagnostic.ATC221.severity = warning

📝 Examples

Scenario 1: All namespaces should be in GlobalUsings.cs

// non-compliant - ANY namespace should be in GlobalUsings.cs
using System;
using Xunit;
using MyCompany.Utilities;

public class Sample
{
}

// compliant - GlobalUsings.cs contains all usings
public class Sample
{
}

Scenario 2: Aliases are allowed locally

// compliant - using aliases can remain in individual files
using Constants = Domain.Constants;

public class Sample
{
}

⚙️ Configuration

Configure in .editorconfig:

[*.cs]
# Exclude common namespaces handled by ATC221 (default: true)
# Set to false if you want ATC220 to flag ALL namespaces (use with ATC221 disabled)
dotnet_diagnostic.ATC220.exclude_common_namespaces = true
Option Default Description
exclude_common_namespaces true When true, skips namespaces matching ATC221's configured prefixes (System, Microsoft, Atc) to avoid duplicate diagnostics

When exclude_common_namespaces is true (default), ATC220 reads ATC221's namespace_prefixes setting to determine which namespaces to skip. If you customize ATC221's prefixes, ATC220 automatically respects that.

🔧 Code Fix

A code fix is available that automatically moves the using directive to GlobalUsings.cs.

How to apply:

  1. Position cursor on the using directive
  2. Click the lightbulb (💡) or press Ctrl+. (Windows/Linux) or Cmd+. (Mac)
  3. Select "Move to GlobalUsings.cs"

GlobalUsings.cs Ordering Rule

The code fix ensures proper ordering in GlobalUsings.cs:

  1. System namespaces first - All System.* namespaces are placed at the top, sorted alphabetically
  2. All other namespaces - Everything else follows, sorted alphabetically

Example ordering:

global using System;
global using System.Collections.Generic;
global using System.Linq;
global using System.Text;
global using Atc.Data;
global using Atc.Utilities;
global using Microsoft.Extensions.Logging;
global using Newtonsoft.Json;
global using Xunit;

This ensures consistency and makes it easy to locate specific namespace imports.

🔗 Related Rules

Global Usings Policy

Other Style Rules