应该“使用” C# 中的指令位于命名空间内部还是外部？

Question

我一直在一些 C# 代码上运行 StyleCop ，并且它不断报告我的 using< /code> 指令应该位于命名空间内。

将 using 指令放在命名空间内部而不是外部是否有技术原因？

Answer 1

两者之间实际上存在（微妙的）差异。假设您在 File1.cs 中有以下代码：

// File1.cs
using System;
namespace Outer.Inner
{
    class Foo
    {
        static void Bar()
        {
            double d = Math.PI;
        }
    }
}

现在假设有人将另一个文件 (File2.cs) 添加到项目中，如下所示：

// File2.cs
namespace Outer
{
    class Math
    {
    }
}

编译器在查看这些 之前先搜索 Outer，然后使用 指令位于命名空间之外，因此它会查找 Outer.Math 而不是 System.Math。不幸的是（或许幸运的是？），Outer.Math 没有 PI 成员，因此 File1 现在已损坏。

如果您将 using 放入命名空间声明中，情况会发生变化，如下所示：

// File1b.cs
namespace Outer.Inner
{
    using System;
    class Foo
    {
        static void Bar()
        {
            double d = Math.PI;
        }
    }
}

现在，编译器在搜索 Outer 之前搜索 System，找到 System .数学，一切都很好。

有些人会认为，对于用户定义的类来说，Math 可能是一个不好的名字，因为 System 中已经有一个这样的名称；这里的要点是存在差异，它会影响代码的可维护性。

值得注意的是，如果 Foo 位于命名空间 Outer 中，而不是 Outer.Inner 中，会发生什么情况。在这种情况下，无论 using 位于何处，在 File2 中添加 Outer.Math 都会破坏 File1。这意味着编译器在查看任何 using 指令之前会先搜索最内层的封闭命名空间。

Answer 2

该线程已经有一些很好的答案，但我觉得我可以通过这个附加答案带来更多细节。

首先，请记住带有句点的命名空间声明，例如：

namespace MyCorp.TheProduct.SomeModule.Utilities
{
    ...
}

完全等同于：

namespace MyCorp
{
    namespace TheProduct
    {
        namespace SomeModule
        {
            namespace Utilities
            {
                ...
            }
        }
    }
}

如果您愿意，您可以将 using 指令放在所有这些级别上。 （当然，我们希望只在一个地方使用 using ，但根据该语言，这是合法的。）

解析隐含类型的规则可以这样宽松地表述：< strong>首先在最里面的“范围”中搜索匹配项，如果没有找到任何内容，则转到下一个范围并在那里搜索，依此类推，直到找到匹配项。如果在某一级别找到多个匹配项，并且其中一种类型来自当前程序集，则选择该类型并发出编译器警告。否则，放弃（编译时错误）。

现在，让我们通过两个主要约定的具体示例来明确说明这意味着什么。

(1) 在外部使用：

using System;
using System.Collections.Generic;
using System.Linq;
//using MyCorp.TheProduct;  <-- uncommenting this would change nothing
using MyCorp.TheProduct.OtherModule;
using MyCorp.TheProduct.OtherModule.Integration;
using ThirdParty;

namespace MyCorp.TheProduct.SomeModule.Utilities
{
    class C
    {
        Ambiguous a;
    }
}

在上述情况下，要找出 Ambigously 是什么类型，请按照以下顺序进行搜索：

1. C 内部的嵌套类型code> （包括继承的嵌套类型）
2. 当前命名空间中的类型 MyCorp.TheProduct.SomeModule.Utilities
3. 命名空间中的类型 MyCorp.TheProduct.SomeModule
4. 中的类型MyCorp.TheProduct
5. MyCorp 中的类型
6. null 命名空间（全局命名空间）中
7. 的类型 System、System.Collections.Generic、System.Linq、MyCorp.TheProduct.OtherModule、 MyCorp.TheProduct.OtherModule.Integration 和 ThirdParty

另一个约定：

(2) 内部使用：

namespace MyCorp.TheProduct.SomeModule.Utilities
{
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using MyCorp.TheProduct;                           // MyCorp can be left out; this using is NOT redundant
    using MyCorp.TheProduct.OtherModule;               // MyCorp.TheProduct can be left out
    using MyCorp.TheProduct.OtherModule.Integration;   // MyCorp.TheProduct can be left out
    using ThirdParty;

    class C
    {
        Ambiguous a;
    }
}

现在，搜索类型 Ambigitude 按以下顺序进行：

1. C 内的嵌套类型（包括继承的嵌套类型）
2. 当前命名空间中的类型 MyCorp.TheProduct.SomeModule.Utilities
3. 中的类型系统、System.Collections.Generic、System.Linq、MyCorp.TheProduct、MyCorp.TheProduct 命名空间中的.OtherModule、MyCorp.TheProduct.OtherModule.Integration 和 ThirdParty
4. 类型MyCorp.TheProduct.SomeModule
5. MyCorp 中的类型
6. null 命名空间（全局命名空间）中的类型

（请注意，MyCorp.TheProduct 是“3.”的一部分，因此不需要在“4.”和“5.”之间。）

结束语

无论将 using 放在名称空间声明内部还是外部，总有可能以后有人将具有相同名称的新类型添加到具有更高优先级的命名空间之一。

此外，如果嵌套命名空间与类型具有相同的名称，则可能会导致问题。

将使用从一个位置移动到另一个位置总是很危险的，因为搜索层次结构会发生变化，并且可能会找到另一种类型。因此，选择一种约定并坚持下去，这样您就不必移动使用。

默认情况下，Visual Studio 的模板将 usings 放置在命名空间之外（例如，如果您让 VS 在新文件中生成新类）。

在外部使用 using 的一个（微小）优点是，您可以将 using 指令用于全局属性，例如 [assemble: ComVisible(false)] 而不是 <代码>[程序集：System.Runtime.InteropServices.ComVisible(false)]。

---

受其他线程启发的添加：假设在上面的示例中，命名空间MyCorp.TheProduct.System发生了存在，即使我们的文件中没有使用它。然后在外面使用，它不会改变任何东西。但是使用 usings inside 时，您必须使用 global 别名，如下所示：

namespace MyCorp.TheProduct.SomeModule.Utilities
{
    using global::System;  // avoids 'MyCorp.TheProduct.System' which also exists
    using global::System.Collections.Generic;
    // etc.
}

---

更新有关文件范围的命名空间声明

自 C# 10.0（从2021），您可以避免缩进并使用（约定 1，外部使用）：

using System;
using System.Collections.Generic;
using System.Linq;
using MyCorp.TheProduct.OtherModule;
using MyCorp.TheProduct.OtherModule.Integration;
using ThirdParty;

namespace MyCorp.TheProduct.SomeModule.Utilities;

class C
{
    Ambiguous a;
}

或（约定 2，内部使用）：

namespace MyCorp.TheProduct.SomeModule.Utilities;

using System;
using System.Collections.Generic;
using System.Linq;
using MyCorp.TheProduct;
using MyCorp.TheProduct.OtherModule;
using MyCorp.TheProduct.OtherModule.Integration;
using ThirdParty;

class C
{
    Ambiguous a;
}

但与之前的注意事项相同。

Answer 3

将其放入命名空间内会使声明成为该文件的该命名空间的本地声明（如果文件中有多个命名空间），但如果每个文件只有一个命名空间，那么无论它们是在外部还是外部，都没有太大区别在命名空间内。

using ThisNamespace.IsImported.InAllNamespaces.Here;

namespace Namespace1
{ 
   using ThisNamespace.IsImported.InNamespace1.AndNamespace2;

   namespace Namespace2
   { 
      using ThisNamespace.IsImported.InJustNamespace2;
   }       
}

namespace Namespace3
{ 
   using ThisNamespace.IsImported.InJustNamespace3;
}

Answer 4

根据 Hanselman - 使用指令和程序集加载... 和其他此类文章，技术上有没有区别。

我的偏好是将它们放在名称空间之外。

Answer 5

根据 StyleCop 文档：

SA1200：UsingDirectivesMustBePlacedWithinNamespace

原因
C# using 指令放置在命名空间元素之外。

规则说明
当 using 指令或 using-alias 指令放置在命名空间元素之外时，就会违反此规则，除非该文件不包含任何命名空间元素。

例如，以下代码将导致两次违反此规则。

using System;
using Guid = System.Guid;

namespace Microsoft.Sample
{
    public class Program
    {
    }
}

但是，以下代码不会导致违反此规则：

namespace Microsoft.Sample
{
    using System;
    using Guid = System.Guid;

    public class Program
    {
    }
}

此代码将干净地编译，没有任何编译器错误。但是，尚不清楚正在分配哪个版本的 Guid 类型。如果将 using 指令移动到命名空间内部，如下所示，将会发生编译器错误：

namespace Microsoft.Sample
{
    using Guid = System.Guid;
    public class Guid
    {
        public Guid(string s)
        {
        }
    }

    public class Program
    {
        public static void Main(string[] args)
        {
            Guid g = new Guid("hello");
        }
    }
}

代码因以下编译器错误而失败，该错误出现在包含 Guid g = new Guid("hello");< 的行上/code>

CS0576：命名空间“Microsoft.Sample”包含与别名“Guid”冲突的定义

该代码创建 System.Guid 类型的别名（称为 Guid），并创建自己的类型（称为 Guid）并具有匹配的构造函数接口。随后，代码创建 Guid 类型的实例。要创建此实例，编译器必须在 Guid 的两个不同定义之间进行选择。当 using-alias 指令放置在命名空间元素之外时，编译器将选择本地命名空间内定义的 Guid 的本地定义，并完全忽略命名空间之外定义的 using-alias 指令。不幸的是，在阅读代码时这一点并不明显。

然而，当 using-alias 指令位于命名空间中时，编译器必须在同一命名空间中定义的两个不同的、冲突的 Guid 类型之间进行选择。这两种类型都提供了匹配的构造函数。编译器无法做出决定，因此它会标记编译器错误。

将 using-alias 指令放在命名空间之外是一种不好的做法，因为在这种情况下可能会导致混乱，在这种情况下，实际使用的类型版本并不明显。这可能会导致难以诊断的错误。

将 using-alias 指令放置在命名空间元素中可以消除这种错误来源。

2. 多个命名空间

将多个命名空间元素放置在一个文件中通常是一个坏主意，但是如果这样做，最好将所有 using 指令放置在每个命名空间元素中，而不是全局放置在文件顶部。这将严格限制命名空间，并且还有助于避免上述行为。

需要注意的是，当使用放置在命名空间之外的 using 指令编写代码时，在命名空间内移动这些指令时应小心，以确保这不会改变代码的语义。如上所述，将 using-alias 指令放置在命名空间元素内允许编译器以将指令放置在命名空间之外时不会发生的方式在冲突类型之间进行选择。

如何纠正违规行为
要修复违反此规则的问题，请移动命名空间元素内的所有 using 指令和 using-alias 指令。

Answer 6

当您希望使用别名时，在命名空间内放置 using 语句会出现问题。该别名无法从早期的 using 语句中受益，并且必须是完全限定的。

考虑：

namespace MyNamespace
{
    using System;
    using MyAlias = System.DateTime;

    class MyClass
    {
    }
}

与：

using System;

namespace MyNamespace
{
    using MyAlias = DateTime;

    class MyClass
    {
    }
}

如果您有一个冗长的别名，如下所示（这就是我发现问题的方式），这可能会特别明显：

using MyAlias = Tuple<Expression<Func<DateTime, object>>, Expression<Func<TimeSpan, object>>>;

在命名空间内使用 using 语句，它突然变成

using MyAlias = System.Tuple<System.Linq.Expressions.Expression<System.Func<System.DateTime, object>>, System.Linq.Expressions.Expression<System.Func<System.TimeSpan, object>>>;

：漂亮的。

Answer 7

我遇到的一个问题（其他答案中没有涵盖）：

假设您有这些命名空间：

• Something.Other
• Parent.Something.Other

当您使用 using Something.Other outside 命名空间Parent，它引用第一个（Something.Other）。

但是，如果您在该命名空间声明中使用它，它会引用第二个命名空间 (Parent.Something.Other)！

有一个简单的解决方案：添加“global::”前缀：文档

namespace Parent
{
   using global::Something.Other;
   // etc
}

Answer 8

我认为其他答案没有涵盖的另一个微妙之处是当您有一个具有相同名称的类和命名空间时。

当您在命名空间内进行导入时，它将找到该类。如果导入位于命名空间之外，则导入将被忽略，并且类和命名空间必须是完全限定的。

//file1.cs
namespace Foo
{
    class Foo
    {
    }
}

//file2.cs
namespace ConsoleApp3
{
    using Foo;
    class Program
    {
        static void Main(string[] args)
        {
            //This will allow you to use the class
            Foo test = new Foo();
        }
    }
}

//file3.cs
using Foo; //Unused and redundant    
namespace Bar
{
    class Bar
    {
        Bar()
        {
            Foo.Foo test = new Foo.Foo();
            Foo test = new Foo(); //will give you an error that a namespace is being used like a class.
        }
    }
}

Answer 9

正如 Jeppe Stig Nielsen 所说，这个帖子已经有了很好的答案，但我认为这个相当明显的微妙之处也值得一提。

在命名空间内指定的 using 指令可以缩短代码，因为它们不需要像在外部指定时那样完全限定。

以下示例之所以有效，是因为类型 Foo 和 Bar 都位于同一全局命名空间 Outer 中。

假设代码文件 Foo.cs:

namespace Outer.Inner
{
    class Foo { }
}

和 Bar.cs:

namespace Outer
{
    using Outer.Inner;

    class Bar
    {
        public Foo foo;
    }
}

可能会省略 using 指令中的外部命名空间，简而言之：

namespace Outer
{
    using Inner;

    class Bar
    {
        public Foo foo;
    }
}

Answer 10

尚未提及：

将 using 指令放入命名空间声明内部是众所周知的最佳编程实践的应用在尽可能小的范围内声明所有内容。

如果最佳编程实践是您的第二天性，那么您会自动执行类似的操作。

这可能是将您的 using 指令放入名称空间声明中的最佳理由，无论其他地方提到的（边界）技术（边界）优点如何；就这么简单。

---

已经提到过，但也许更好地说明了：

将 using 指令放置在命名空间内可以避免不必要的重复，并使我们的声明更加简洁。

这是不必要的简洁：

using Com.Acme.Products.Traps.RoadRunnerTraps;
namespace Com.Acme.Products.Traps {

这是甜蜜且切题的：

namespace Com.Acme.Products.Traps { 
using RoadRunnerTraps;

Answer 11

答案中讨论了技术原因，我认为最终取决于个人喜好，因为差异并没有那么大，而且两者都需要权衡。 Visual Studio 用于创建 .cs 文件的默认模板使用命名空间之外的 using 指令，例如，

可以通过添加来调整 stylecop 以检查命名空间之外的 using 指令项目文件根目录中的 stylecop.json 文件包含以下内容：

{
  "$schema": "https://raw.githubusercontent.com/DotNetAnalyzers/StyleCopAnalyzers/master/StyleCop.Analyzers/StyleCop.Analyzers/Settings/stylecop.schema.json",
    "orderingRules": {
      "usingDirectivesPlacement": "outsideNamespace"
    }
  }
}

您可以在解决方案级别创建此配置文件，并将其作为“现有链接文件”添加到您的项目中，以便在所有项目之间共享配置你的项目也是如此。

Answer 12

通常，外部 using 指令（例如 System 和 Microsoft 命名空间）应放置在 namespace 指令的外部。它们是默认值，应在所有情况下应用除非另有说明。这应该包括您自己组织的任何不属于当前项目的内部库，或者引用同一项目中其他主命名空间的 using 指令。任何引用当前项目和命名空间中其他模块的 using 指令都应放置在 namespace 指令内部。这有两个特定的功能：

• 它提供本地模块和“其他”模块（意味着其他所有模块）之间的视觉区别。
• 它限制了本地指令的应用范围，使其优先优于全局指令。

后一个原因很重要。这意味着引入不明确的参考问题会更困难，而这种问题可以通过不比重构代码更重要的更改来引入。也就是说，您将一种方法从一个文件移动到另一个文件，然后突然出现一个以前不存在的错误。通俗地说，“heisenbug”——历史上极难追踪。

Answer 13

这取决于。
根据 StyleCop 的说法，里面。
据微软称，外部。

（只是想要一个真正简短的答案，我阅读了整个线程，但并不是每个人都有时间这样做）

Answer 14

虽然大多数答案倾向于将 using 指令放置在 namespace 声明中，但有趣的是，微软在 C# 编码约定 另有说明：

将 using 指令放在命名空间声明之外

当 using 指令位于命名空间声明之外时，
导入的命名空间是其完全限定名称。这样就更清楚了。
当 using 指令位于命名空间内时，它可以是
相对于该名称空间或其完全限定名称。那是
模棱两可。

然而，在这篇文章中，他们规定相反：

Using 语句应该位于命名空间声明内。

Answer 15

如果源解决方案中使用的默认（即“引用”）应该位于命名空间之外，并且“新添加的引用”< /strong> 是一个很好的做法，您应该将其放在名称空间内。这是为了区分正在添加的引用。