9. Namespaces

C# programs are organized using namespaces. Namespaces are used both as an “internal” organization system for a program, and as an “external” organization system—a way of presenting program elements that are exposed to other programs.

Using directives (§‎9.3) are provided to facilitate the use of namespaces.

9.1 Compilation units

A compilation-unit defines the overall structure of a source file. A compilation unit consists of zero or more using-directives followed by zero or more global-attributes followed by zero or more namespace-member-declarations.

compilation-unit:
using-directives_opt  global-attributes_opt    namespace-member-declarations_opt

A C# program consists of one or more compilation units, each contained in a separate source file. When a C# program is compiled, all of the compilation units are processed together. Thus, compilation units can depend on each other, possibly in a circular fashion.

The using-directives of a compilation unit affect the global-attributes and namespace-member-declarations of that compilation unit, but have no effect on other compilation units.

The global-attributes (§‎17) of a compilation unit permit the specification of attributes for the target assembly and module. Assemblies and modules act as physical containers for types. An assembly may consist of several physically separate modules.

The namespace-member-declarations of each compilation unit of a program contribute members to a single declaration space called the global namespace. For example:

File A.cs:

class A {}

File B.cs:

class B {}

The two compilation units contribute to the single global namespace, in this case declaring two classes with the fully qualified names A and B. Because the two compilation units contribute to the same declaration space, it would have been an error if each contained a declaration of a member with the same name.

9.2 Namespace declarations

A namespace-declaration consists of the keyword namespace, followed by a namespace name and body, optionally followed by a semicolon.

namespace-declaration:
namespace   qualified-identifier   namespace-body   ;_opt

qualified-identifier:
identifier
qualified-identifier   .   identifier

namespace-body:
{   using-directives_opt   namespace-member-declarations_opt   }

A namespace-declaration may occur as a top-level declaration in a compilation-unit or as a member declaration within another namespace-declaration. When a namespace-declaration occurs as a top-level declaration in a compilation-unit, the namespace becomes a member of the global namespace. When a namespace-declaration occurs within another namespace-declaration, the inner namespace becomes a member of the outer namespace. In either case, the name of a namespace must be unique within the containing namespace.

Namespaces are implicitly public and the declaration of a namespace cannot include any access modifiers.

Within a namespace-body, the optional using-directives import the names of other namespaces and types, allowing them to be referenced directly instead of through qualified names. The optional namespace-member-declarations contribute members to the declaration space of the namespace. Note that all using-directives must appear before any member declarations.

The qualified-identifier of a namespace-declaration may be a single identifier or a sequence of identifiers separated by “.” tokens. The latter form permits a program to define a nested namespace without lexically nesting several namespace declarations. For example,

namespace N1.N2
{
   class A {}

   class B {}
}

is semantically equivalent to

namespace N1
{
   namespace N2
   {
      class A {}

      class B {}
   }
}

Namespaces are open-ended, and two namespace declarations with the same fully qualified name contribute to the same declaration space (§‎3.3). In the example

namespace N1.N2
{
   class A {}
}

namespace N1.N2
{
   class B {}
}

the two namespace declarations above contribute to the same declaration space, in this case declaring two classes with the fully qualified names N1.N2.A and N1.N2.B. Because the two declarations contribute to the same declaration space, it would have been an error if each contained a declaration of a member with the same name.

9.3 Using directives

Using directives facilitate the use of namespaces and types defined in other namespaces. Using directives impact the name resolution process of namespace-or-type-names (§‎3.8) and simple-names (§‎7.5.2), but unlike declarations, using directives do not contribute new members to the underlying declaration spaces of the compilation units or namespaces within which they are used.

using-directives:
using-directive
using-directives   using-directive

using-directive:
using-alias-directive
using-namespace-directive

A using-alias-directive (§‎9.3.1) introduces an alias for a namespace or type.

A using-namespace-directive (§‎9.3.2) imports the type members of a namespace.

The scope of a using-directive extends over the namespace-member-declarations of its immediately containing compilation unit or namespace body. The scope of a using-directive specifically does not include its peer using-directives. Thus, peer using-directives do not affect each other, and the order in which they are written is insignificant.

9.3.1 Using alias directives

A using-alias-directive introduces an identifier that serves as an alias for a namespace or type within the immediately enclosing compilation unit or namespace body.

using-alias-directive:
using   identifier   =   namespace-or-type-name   ;

Within member declarations in a compilation unit or namespace body that contains a using-alias-directive, the identifier introduced by the using-alias-directive can be used to reference the given namespace or type. For example:

namespace N1.N2
{
   class A {}
}

namespace N3
{
   using A = N1.N2.A;

   class B: A {}
}

Above, within member declarations in the N3 namespace, A is an alias for N1.N2.A, and thus class N3.B derives from class N1.N2.A. The same effect can be obtained by creating an alias R for N1.N2 and then referencing R.A:

namespace N3
{
   using R = N1.N2;

   class B: R.A {}
}

The identifier of a using-alias-directive must be unique within the declaration space of the compilation unit or namespace that immediately contains the using-alias-directive. For example:

namespace N3
{
   class A {}
}

namespace N3
{
   using A = N1.N2.A;      // Error, A already exists
}

Above, N3 already contains a member A, so it is a compile-time error for a using-alias-directive to use that identifier. Likewise, it is a compile-time error for two or more using-alias-directives in the same compilation unit or namespace body to declare aliases by the same name.

A using-alias-directive makes an alias available within a particular compilation unit or namespace body, but it does not contribute any new members to the underlying declaration space. In other words, a using-alias-directive is not transitive but rather affects only the compilation unit or namespace body in which it occurs. In the example

namespace N3
{
   using R = N1.N2;
}

namespace N3
{
   class B: R.A {}         // Error, R unknown
}

the scope of the using-alias-directive that introduces R only extends to member declarations in the namespace body in which it is contained, so R is unknown in the second namespace declaration. However, placing the using-alias-directive in the containing compilation unit causes the alias to become available within both namespace declarations:

using R = N1.N2;

namespace N3
{
   class B: R.A {}
}

namespace N3
{
   class C: R.A {}
}

Just like regular members, names introduced by using-alias-directives are hidden by similarly named members in nested scopes. In the example

using R = N1.N2;

namespace N3
{
   class R {}

   class B: R.A {}      // Error, R has no member A
}

the reference to R.A in the declaration of B causes a compile-time error because R refers to N3.R, not N1.N2.

The order in which using-alias-directives are written has no significance, and resolution of the namespace-or-type-name referenced by a using-alias-directive is not affected by the using-alias-directive itself or by other using-directives in the immediately containing compilation unit or namespace body. In other words, the namespace-or-type-name of a using-alias-directive is resolved as if the immediately containing compilation unit or namespace body had no using-directives. In the example

namespace N1.N2 {}

namespace N3
{
   using R1 = N1;       // OK

   using R2 = N1.N2;    // OK

   using R3 = R1.N2;    // Error, R1 unknown
}

the last using-alias-directive results in a compile-time error because it is not affected by the first using-alias-directive.

A using-alias-directive can create an alias for any namespace or type, including the namespace within which it appears and any namespace or type nested within that namespace.

Accessing a namespace or type through an alias yields exactly the same result as accessing that namespace or type through its declared name. For example, given

namespace N1.N2
{
   class A {}
}

namespace N3
{
   using R1 = N1;
   using R2 = N1.N2;

   class B
   {
      N1.N2.A a;        // refers to N1.N2.A
      R1.N2.A b;        // refers to N1.N2.A
      R2.A c;           // refers to N1.N2.A
   }
}

the names N1.N2.A, R1.N2.A, and R2.A are equivalent and all refer to the class whose fully qualified name is N1.N2.A.

9.3.2 Using namespace directives

A using-namespace-directive imports the types contained in a namespace into the immediately enclosing compilation unit or namespace body, enabling the identifier of each type to be used without qualification.

using-namespace-directive:
using   namespace-name   ;

Within member declarations in a compilation unit or namespace body that contains a using-namespace-directive, the types contained in the given namespace can be referenced directly. For example:

namespace N1.N2
{
   class A {}
}

namespace N3
{
   using N1.N2;

   class B: A {}
}

Above, within member declarations in the N3 namespace, the type members of N1.N2 are directly available, and thus class N3.B derives from class N1.N2.A.

A using-namespace-directive imports the types contained in the given namespace, but specifically does not import nested namespaces. In the example

namespace N1.N2
{
   class A {}
}

namespace N3
{
   using N1;

   class B: N2.A {}     // Error, N2 unknown
}

the using-namespace-directive imports the types contained in N1, but not the namespaces nested in N1. Thus, the reference to N2.A in the declaration of B results in a compile-time error because no members named N2 are in scope.

Unlike a using-alias-directive, a using-namespace-directive may import types whose identifiers are already defined within the enclosing compilation unit or namespace body. In effect, names imported by a using-namespace-directive are hidden by similarly named members in the enclosing compilation unit or namespace body. For example:

namespace N1.N2
{
   class A {}

   class B {}
}

namespace N3
{
   using N1.N2;

   class A {}
}

Here, within member declarations in the N3 namespace, A refers to N3.A rather than N1.N2.A.

When more than one namespace imported by using-namespace-directives in the same compilation unit or namespace body contain types by the same name, references to that name are considered ambiguous. In the example

namespace N1
{
   class A {}
}

namespace N2
{
   class A {}
}

namespace N3
{
   using N1;

   using N2;

   class B: A {}           // Error, A is ambiguous
}

both N1 and N2 contain a member A, and because N3 imports both, referencing A in N3 is a compile-time error. In this situation, the conflict can be resolved either through qualification of references to A, or by introducing a using-alias-directive that picks a particular A. For example:

namespace N3
{
   using N1;

   using N2;

   using A = N1.A;

   class B: A {}           // A means N1.A
}

Like a using-alias-directive, a using-namespace-directive does not contribute any new members to the underlying declaration space of the compilation unit or namespace, but rather affects only the compilation unit or namespace body in which it appears.

The namespace-name referenced by a using-namespace-directive is resolved in the same way as the namespace-or-type-name referenced by a using-alias-directive. Thus, using-namespace-directives in the same compilation unit or namespace body do not affect each other and can be written in any order.

9.4 Namespace members

A namespace-member-declaration is either a namespace-declaration (§‎9.2) or a type-declaration (§‎9.5).

namespace-member-declarations:
namespace-member-declaration
namespace-member-declarations   namespace-member-declaration

namespace-member-declaration:
namespace-declaration
type-declaration

A compilation unit or a namespace body can contain namespace-member-declarations, and such declarations contribute new members to the underlying declaration space of the containing compilation unit or namespace body.

9.5 Type declarations

A type-declaration is a class-declaration (§‎10.1), a struct-declaration (§‎11.1), an interface-declaration (§‎13.1), an enum-declaration (§‎14.1), or a delegate-declaration (§‎15.1).

type-declaration:
class-declaration
struct-declaration
interface-declaration
enum-declaration
delegate-declaration

A type-declaration can occur as a top-level declaration in a compilation unit or as a member declaration within a namespace, class, or struct.

When a type declaration for a type T occurs as a top-level declaration in a compilation unit, the fully qualified name of the newly declared type is simply T. When a type declaration for a type T occurs within a namespace, class, or struct, the fully qualified name of the newly declared type is N.T, where N is the fully qualified name of the containing namespace, class, or struct.

A type declared within a class or struct is called a nested type (§‎10.2.6).

The permitted access modifiers and the default access for a type declaration depend on the context in which the declaration takes place (§‎3.5.1):

·         Types declared in compilation units or namespaces can have public or internal access. The default is internal access.

·         Types declared in classes can have public, protected internal, protected, internal, or private access. The default is private access.

·         Types declared in structs can have public, internal, or private access. The default is private access.