Namespaces and Assemblies

Analogy categoryAnalogies

Namespaces and assemblies solve two different problems that beginners often conflate. A namespace is a logical, purely compile-time grouping mechanism that prevents naming collisions and organizes related types under a hierarchical name like System.Collections.Generic. An assembly is a physical, deployable unit — a .dll or .exe file — containing compiled IL code, type metadata, and a manifest, and it's the unit the .NET runtime actually loads, versions, and resolves dependencies against. A single assembly can contain many namespaces, and a single namespace's types can be spread across multiple assemblies (System.Collections.Generic types, for instance, live in more than one core assembly).

🏏

Cricket analogy: A namespace is like organizing players by role (Batsmen, Bowlers, AllRounders) on a team sheet, purely organizational, while an assembly is like the actual squad bus (.dll) deployed to the stadium, carrying players from multiple role groups.

Declaring and using namespaces

C# 10 introduced file-scoped namespace declarations (namespace MyApp.Orders; with no braces) which have become the idiomatic style, replacing the older block-scoped form for files that contain only one namespace. The using directive imports a namespace so its types can be referenced without full qualification, and C# 10's global using directives (often centralized in a GlobalUsings.cs file) let you declare a using once for an entire project rather than repeating it at the top of every file.

🏏

Cricket analogy: A file-scoped namespace is like a scorecard header stating 'Match: India vs Australia' once instead of repeating it on every page; a using directive is like referencing 'Kohli' instead of repeating his full title each time; global usings are like a broadcast standard applied across every match in a series.

csharp

// GlobalUsings.cs — applies project-wide (C# 10+)
global using System;
global using System.Collections.Generic;
global using System.Linq;

// OrderRepository.cs
namespace Contoso.Orders.Data; // file-scoped namespace, C# 10+

public sealed class OrderRepository
{
    private readonly List<Order> _orders = new();

    public void Add(Order order) => _orders.Add(order);

    public IEnumerable<Order> ForCustomer(int customerId) =>
        _orders.Where(o => o.CustomerId == customerId);
}

// Fully qualified name avoids ambiguity when two namespaces
// define a type with the same short name:
// var log = new Contoso.Diagnostics.Logger();
// var log2 = new Contoso.Orders.Logger();

Assemblies, metadata, and versioning

Every compiled C# project produces an assembly containing IL, a manifest describing its identity (name, version, culture, optionally a strong-name public key), and metadata describing every type, member, and attribute it defines — this metadata is what enables reflection to inspect a type at runtime without needing its source. Assemblies reference other assemblies by name and version, and the .NET runtime's assembly resolution process (driven by the project's dependency graph and runtimeconfig.json in modern .NET) determines which actual DLL gets loaded at run time.

🏏

Cricket analogy: An assembly is like a player's full registration file, skills (IL), an official ID card (manifest with name/version), and a stats sheet (metadata) scouts can inspect (reflection) without watching him play; the transfer system (assembly resolution) determines which club's registered version takes the field.

Internal visibility and assembly boundaries

The internal access modifier is scoped to the assembly, not the namespace — an internal type or member is visible anywhere within the same assembly, even across different namespaces, but invisible to other assemblies entirely (unless exposed via InternalsVisibleTo, commonly used to let a test assembly see internal members of the assembly it tests). This is a frequent point of confusion: namespaces provide no access control on their own; only access modifiers combined with assembly boundaries do.

🏏

Cricket analogy: The internal modifier is like a team's internal training drills visible to every player regardless of which sub-squad (namespace) they're in, but invisible to rival teams entirely, unless the team explicitly grants a scouting partner (InternalsVisibleTo) access to watch practice.

Java ties packages (its namespace equivalent) directly to physical directory structure and, historically, to classpath-based visibility; C# namespaces have no required relationship to file or folder layout at all — a file can declare any namespace regardless of its location on disk, though most teams mirror namespace to folder structure by convention for readability.

Two assemblies can each define a type with the identical fully-qualified name (same namespace and type name) — this is legal and does happen with versioned or vendored dependencies — and can cause baffling 'type exists in two places' compiler errors that require an extern alias to resolve, since assembly identity, not just namespace, ultimately determines type identity to the runtime.

Namespaces are a compile-time, logical grouping that prevents naming collisions; they have no runtime existence.
Assemblies (.dll/.exe) are the physical units the .NET runtime loads, versions, and resolves dependencies against.
File-scoped namespace declarations (C# 10+) are the modern, less-indented style for single-namespace files.
global using directives centralize common imports project-wide instead of repeating them per file.
internal visibility is scoped to the containing assembly, not to the namespace.
InternalsVisibleTo lets a designated assembly (e.g. a test project) access another assembly's internal members.

Practice what you learned

1. What is the key distinction between a namespace and an assembly?

2. What is the scope of the `internal` access modifier?

3. What does a file-scoped namespace declaration look like in C# 10+?

4. What is the purpose of InternalsVisibleTo?

5. Can two different assemblies define types with the exact same fully-qualified name?

Was this page helpful?

NuGet Packages

Related Study Notes in Programming

Browse all study notes

Programming

Apache Spark Study Notes

Programming · 30 topics

Programming

Apache Flink Study Notes

Programming · 30 topics

Programming

Hadoop Study Notes

Programming · 30 topics

Programming

Snowflake Study Notes

Programming · 30 topics

Programming

Apache Airflow Study Notes

Programming · 30 topics

Programming

dbt (Data Build Tool) Study Notes

Programming · 30 topics

Topics covered

#CStudyNotes#Programming#NamespacesAndAssemblies#Namespaces#Assemblies#Declaring#Metadata#StudyNotes#SkillVeris#ExamPrep

Namespaces and Assemblies