[Everyday C#] - Program structure: namespaces + preprocessor directives

[BillWagner]

Fixes #51990
Fixes #34836

Plan: PR 1 — Program structure: namespaces + preprocessor directives

TL;DR: This PR restructures the Program structure section of C# Fundamentals by (1) revising the overview index.md to emphasize file-scoped namespaces and global usings as the default style, (2) moving the namespaces article from types/namespaces.md to program-structure/namespaces.md with a major revision to cover file-scoped namespaces (C# 10), global usings (C# 10), static using (C# 6), and type/namespace aliases, (3) creating a new fundamentals-level preprocessor-directives.md covering #if, #region, #nullable, and #pragma warning, and (4) creating a new organizing-programs.md article about assemblies, namespaces, and types as organizational tools (addressing #34836). All code snippets use latest .NET, file-based app style where natural, and the full "Everyday C#" feature set. The PR follows concept → example → concept → example structure per the project conventions.

Steps

1. Revise docs/csharp/fundamentals/program-structure/index.md

   • Update frontmatter: set ms.date to current date, add ai-usage: ai-assisted
   • Rewrite to lead with a motivating example showing a modern C# program with file-scoped namespaces, global usings, and top-level statements as the default style
   • Distinguish the three application styles: file-based apps (C# 14), project-based apps with top-level statements, and Main-style project-based apps
   • Update the "Related Sections" links: change the Namespaces link from ../types/namespaces.md to namespaces.md (since it moves into this directory)
   • Replace or modernize existing snippet references; consider whether existing snippets/structure/ and snippets/toplevel-structure/ need updating to latest .NET target and everyday C# features

2. Move + revise fundamentals/types/namespaces.md → fundamentals/program-structure/namespaces.md

   • Delete docs/csharp/fundamentals/types/namespaces.md
   • Create new docs/csharp/fundamentals/program-structure/namespaces.md with heavily revised content covering:
     • File-scoped namespaces (C# 10) as the default, recommended style
     • Global using directives (C# 10) including implicit usings from the SDK
     • Static using (C# 6) for importing static members
     • Type and namespace aliases (subset) via using alias directive
     • extern alias (brief mention only)
     • How namespaces organize code and the . delimiter convention
     • Link to SDK section for implicit usings detail
   • Follow concept → example → concept → example structure
   • Target 1000–2000 words (5–10 minute read)

3. Move + modernize namespace snippets from types/snippets/namespaces/ → program-structure/snippets/namespaces/

   • Move all files from docs/csharp/fundamentals/types/snippets/namespaces/ to docs/csharp/fundamentals/program-structure/snippets/namespaces/
   • Rename snippet region IDs from legacy numeric (Snippet1, Snippet22, Snippet23, Snippet6) to CamelCase names (e.g., FullyQualifiedName, UsingDirective, ConsoleShorthand, DeclareNamespace, FileScopedNamespace)
   • Modernize code: update .csproj target from net8.0 to latest .NET, use top-level statements or file-based style where appropriate, use everyday C# features (nullable enable, collection expressions if natural)
   • Add new snippet files for global usings, static using, and alias examples
   • Delete the old types/snippets/namespaces/ directory

4. Create new docs/csharp/fundamentals/program-structure/preprocessor-directives.md

   • This is a fundamentals-level article (not the language-reference exhaustive docs at language-reference/preprocessor-directives.md)
   • Cover only the four directives most relevant to everyday development:
     • #if / #elif / #else / #endif — conditional compilation (with DEBUG, RELEASE, target framework symbols)
     • #region / #endregion — code organization
     • #nullable enable/disable/restore — controlling nullable analysis scope
     • #pragma warning disable/restore — suppressing specific warnings
   • Brief mention of #! and #: for file-based apps (C# 14) with cross-reference to the overview and language reference
   • Link to the full language-reference/preprocessor-directives.md for complete reference
   • Create snippet project at program-structure/snippets/preprocessor-directives/
   • Add ai-usage: ai-assisted to frontmatter

5. Create new docs/csharp/fundamentals/program-structure/organizing-programs.md

   • Addresses dotnet/docs#34836
   • Content: assemblies, namespaces, and types as organizational tools
   • Cover how the organizational hierarchy works: solution → projects → assemblies → namespaces → types
   • Explain naming conventions and how folder structure typically mirrors namespace structure
   • Show practical examples of organizing a small multi-project solution
   • Create snippet project at program-structure/snippets/organizing-programs/
   • Add ai-usage: ai-assisted to frontmatter

6. Update docs/csharp/toc.yml

   • In the Program structure section (currently lines 38–43), add entries for:
     • Namespaces and using directives → fundamentals/program-structure/namespaces.md (after Top-level statements)
     • Preprocessor directives → fundamentals/program-structure/preprocessor-directives.md
     • Organizing programs → fundamentals/program-structure/organizing-programs.md
   • In the Type system section (line 50), remove the Namespaces entry pointing to fundamentals/types/namespaces.md

7. Add redirect for old namespaces path in .openpublishing.redirection.csharp.json

   • Add new entry: source "/docs/csharp/fundamentals/types/namespaces.md" → redirect /dotnet/csharp/fundamentals/program-structure/namespaces

8. Update existing redirect targets in .openpublishing.redirection.csharp.json

   • Update 4 entries that currently point to /dotnet/csharp/fundamentals/types/namespaces to point to /dotnet/csharp/fundamentals/program-structure/namespaces:
     • Line 2857: source /docs/csharp/namespaces-and-assemblies.md
     • Line 4538: source /docs/csharp/programming-guide/namespaces/how-to-use-the-my-namespace.md
     • Line 4542: source /docs/csharp/programming-guide/namespaces/index.md
     • Line 4546: source /docs/csharp/programming-guide/namespaces/using-namespaces.md

9. Update cross-references in 5 other articles that link to the old namespaces path:

   • docs/csharp/fundamentals/program-structure/index.md (line 66): change ../types/namespaces.md → namespaces.md
   • docs/csharp/language-reference/keywords/namespace.md (line 105): change ../../fundamentals/types/namespaces.md → ../../fundamentals/program-structure/namespaces.md
   • docs/csharp/language-reference/keywords/using-directive.md (line 190): change ../../fundamentals/types/namespaces.md → ../../fundamentals/program-structure/namespaces.md
   • docs/csharp/misc/cs0101.md (line 15): change ../fundamentals/types/namespaces.md → ../fundamentals/program-structure/namespaces.md
   • docs/csharp/misc/cs1527.md (line 42): change ../fundamentals/types/namespaces.md → ../fundamentals/program-structure/namespaces.md

10. Snippet conventions for all new/revised articles:

    • Each article's snippets go in program-structure/snippets/{article-name}/ (omitting csharp/vb subfolder since these articles are under docs/csharp/)
    • All .csproj files target latest .NET with <Nullable>enable</Nullable>
    • Region IDs use CamelCase (e.g., <FileScopedNamespace>, <GlobalUsing>, <ConditionalCompilation>)
    • Prefer file-based apps for small standalone examples
    • All code uses everyday C# features: file-scoped namespaces, var, collection expressions, nullable reference types, string interpolation

---

Internal previews

📄 File	🔗 Preview link
docs/csharp/fundamentals/program-structure/index.md	General structure of a C# program
docs/csharp/fundamentals/program-structure/namespaces.md	"Namespaces and using directives"
docs/csharp/fundamentals/program-structure/preprocessor-directives.md	Preprocessor directives
docs/csharp/fundamentals/program-structure/program-organization.md	docs/csharp/fundamentals/program-structure/program-organization
docs/csharp/fundamentals/program-structure/top-level-statements.md	Top-level statements - programs without Main methods
docs/csharp/language-reference/keywords/namespace.md	"The namespace keyword"
docs/csharp/language-reference/keywords/using-directive.md	The using directive
docs/csharp/misc/cs0101.md	docs/csharp/misc/cs0101
docs/csharp/misc/cs1527.md	Compiler Error CS1527
docs/csharp/toc.yml	Taken from https://github.com/dotnet/roslyn/wiki/Samples-and-Walkthroughs

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated 3 comments.

[adegeo]

Submitting my thoughts per our discussion.

[adegeo]

According to our discussion, we might want to delete this statement

[adegeo]

This article weaves between namespaces and using directives. It would probably make more sense to fully explain namespaces and then move on to how using directives help you use namespaces.

[adegeo]

This example may want to elaborate on namespaces. The type is Console in the System namespace. The type is List<T> in the System.Collections.Generic namespace. Using some real-world analogy might be useful. Like how a street address 15452 55th ave ne gets you to a specific house. 15451 can be a house on any street, but you navigate to it based on 55th ave ne. Similarly Task is a type and you access it through the namespace System.Threading.Tasks. But maybe there's a better analogy that's not specific to a locale.