`using` 指示詞

發行項
11/24/2024

using 指示詞可讓您使用命名空間中定義的型別，而不需指定該型別的完整命名空間。在其基本格式中，using 指示詞會從單一命名空間匯入所有型別，如下列範例所示：

using System.Text;

您可以將兩個修飾詞套用至 using 指示詞：

global 修飾詞的效果與將相同的 using 指示詞新增至專案中的每個來源檔案相同。
static 修飾詞會從單一型別匯入 static 成員和巢狀型別，而不是匯入命名空間中的所有型別。

您可以合併這兩個修飾詞，將靜態成員從類型彙入專案中的所有原始程序檔。

您也可以使用 using alias指示詞，為命名空間或類型建立別名。

using Project = PC.MyCompany.Project;

您可以在 global上使用修飾詞。

注意

using 關鍵字也用來建立 using 陳述式，協助確保能夠正確處理 IDisposable 物件 (例如檔案和字型)。如需有關 using 陳述式的詳細資訊，請參閱 using 陳述式。

沒有 using 修飾詞的 global 指示詞的範圍是其出現的檔案。

指示 global using 詞必須出現在所有命名空間和類型宣告之前。所有全域 using 指示詞都必須出現在原始程序檔中，才能顯示任何非全域 using 指示詞。

其他 using 指示詞可能會出現：

位於原始程式碼檔的開頭，在任何命名空間或型別宣告之前。
在任何封鎖範圍命名空間中，但在該命名空間中宣告的任何命名空間或類型之前。

否則，會產生編譯程序錯誤。

建立 using 指示詞，以在命名空間中使用類型，而無需指定命名空間。 using 指示詞不會授予您任何命名空間的存取權，此存取權巢狀於您指定的命名空間。命名空間有兩種類型：使用者定義和系統定義。使用者定義的命名空間是在程式碼中定義的命名空間。如需系統定義的命名空間清單，請參閱 .NET API 瀏覽器。

`global`修飾詞

將 global 修飾詞新增至 using 指令，表示使用會被套用至編輯中的所有檔案（通常是專案）：

global using <fully-qualified-namespace>;

其中 ，完整命名空間 是命名空間的完整名稱，其類型可以參考而不指定命名空間。

global using 指示詞可以出現在任何原始程式碼檔案的開頭。單一檔案中的所有 global using 指示詞都必須在之前出現：

不含 using 修飾詞的所有 global 指示詞。
檔案中的所有命名空間和型別宣告。

您可以將指示詞新增 global using 至任何原始程序檔。一般而言，您想要將它們保留在單一位置。不論是在單一檔案中還是檔案之間，global using 指示詞的順序並不重要。

global修飾詞可以與 static 修飾詞結合。 global修飾詞可以套用至using alias指示詞。在這兩種情況下，指示詞的範圍均為目前編譯中的所有檔案。下列範例會使用專案中所有檔案中 System.Math 宣告的所有方法：

global using static System.Math;

您也可以透過新增 <Using> 項目將命名空間全域包含至專案檔，例如 <Using Include="My.Awesome.Namespace" />。如需詳細資訊，請參閱<Using> 項目。

如果您在不同位置重複 global using 指示詞，分析器會發出診斷。如果您為已參考 using 指示詞的命名空間或型using別新增global指示詞，這些相同的分析器也會通知您。您可能會發現，將它們放在專案中的一個檔案中，以更輕鬆地管理您的 global 使用方式。

重要

.NET 6 的 C# 範本會使用最上層陳述式。如果您已經升級至 .NET 6，您的應用程式可能與本文中的程式碼不相符。如需詳細資訊，請參閱新 C# 範本會產生最上層陳述式一文

.NET 6 SDK 也針對使用下列 SDK 的專案新增了一組隱含global using 指示詞：

Microsoft.NET.Sdk
Microsoft.NET.Sdk.Web
Microsoft.NET.Sdk.Worker

這些隱含 global using 指示詞包含該專案類型最常見的命名空間。

如需詳細資訊，請參閱有關隱含 using 指示詞的文章

`static`修飾詞

using static 指示詞命名一種類型，讓您不需指定型別名稱，即可存取其靜態成員和巢狀型別。其語法如下：

using static <fully-qualified-type-name>;

<fully-qualified-type-name> 不需要指定類型名稱，即可參考其靜態成員和巢狀型別類型的名稱。如果您未提供完整型別名稱 (完整命名空間名稱及型別名稱)，C# 會產生編譯器錯誤 CS0246：「找不到型別或命名空間名稱 'type/namespace' (您是否遺漏 using 指示詞或組件參考?)」。

using static 指示詞會套用至任何具有靜態成員 (或巢狀型別) 的類型，即使該類型同時具有執行個體成員也一樣。不過，執行個體成員只能透過類型執行個體叫用。

您可以存取類型的靜態成員，而不需以類型名稱限定存取：

using static System.Console;
using static System.Math;
class Program
{
    static void Main()
    {
        WriteLine(Sqrt(3*3 + 4*4));
    }
}

一般而言，當您呼叫靜態成員時，您會提供類型名稱及成員名稱。重複輸入相同的類型名稱來叫用類型的成員，可能會導致冗長且難以理解的程式碼。例如，Circle 類別的下列定義參考了 Math 類別的許多成員。

using System;

public class Circle
{
   public Circle(double radius)
   {
      Radius = radius;
   }

   public double Radius { get; set; }

   public double Diameter
   {
      get { return 2 * Radius; }
   }

   public double Circumference
   {
      get { return 2 * Radius * Math.PI; }
   }

   public double Area
   {
      get { return Math.PI * Math.Pow(Radius, 2); }
   }
}

Math 指示詞可避免每次參考成員時都必須明確參考 using static 類別，因此所產生的程式碼會更簡潔：

using System;
using static System.Math;

public class Circle
{
   public Circle(double radius)
   {
      Radius = radius;
   }

   public double Radius { get; set; }

   public double Diameter
   {
      get { return 2 * Radius; }
   }

   public double Circumference
   {
      get { return 2 * Radius * PI; }
   }

   public double Area
   {
      get { return PI * Pow(Radius, 2); }
   }
}

using static 只會匯入指定的類型中宣告的可存取靜態成員和巢狀類型。不會匯入繼承的成員。您可以用 using static 指示詞從任何具名型別匯入，包括 Visual Basic 模組。如果 F# 最上層函式出現在中繼資料中，作為具名類型的靜態成員，其名稱是有效的 C# 識別項，則可以匯入 F# 函式。

using static 讓您在可供擴充方法查閱使用的指定類型中宣告擴充方法。不過，擴充方法的名稱不會匯入程式碼中未限定參考的範圍。

在相同編譯單位或命名空間中透過不同 using static 指示詞從不同的類型匯入、具有相同名稱的方法會形成方法群組。這些方法群組內的多載解析會遵循一般的 C# 規則。

下列範例使用 using static 指示詞來提供 Console、Math 和 String 類別的靜態成員，而不需要指定其類型名稱。

using System;
using static System.Console;
using static System.Math;
using static System.String;

class Program
{
   static void Main()
   {
      Write("Enter a circle's radius: ");
      var input = ReadLine();
      if (!IsNullOrEmpty(input) && double.TryParse(input, out var radius)) {
         var c = new Circle(radius);

         string s = "\nInformation about the circle:\n";
         s = s + Format("   Radius: {0:N2}\n", c.Radius);
         s = s + Format("   Diameter: {0:N2}\n", c.Diameter);
         s = s + Format("   Circumference: {0:N2}\n", c.Circumference);
         s = s + Format("   Area: {0:N2}\n", c.Area);
         WriteLine(s);
      }
      else {
         WriteLine("Invalid input...");
      }
   }
}

public class Circle
{
   public Circle(double radius)
   {
      Radius = radius;
   }

   public double Radius { get; set; }

   public double Diameter
   {
      get { return 2 * Radius; }
   }

   public double Circumference
   {
      get { return 2 * Radius * PI; }
   }

   public double Area
   {
      get { return PI * Pow(Radius, 2); }
   }
}
// The example displays the following output:
//       Enter a circle's radius: 12.45
//
//       Information about the circle:
//          Radius: 12.45
//          Diameter: 24.90
//          Circumference: 78.23
//          Area: 486.95

在此範例中 using static ，指示詞也可以套用至型別 Double 。新增該指示詞可不需要指定類型名稱，即可呼叫 TryParse(String, Double) 方法。不過, 使用沒有型別名稱的 TryParse 會建立較難讀取的程式碼，因為您必須檢查 using static 指示詞，以判斷呼叫了哪一個數字型別的 TryParse 方法。

using static 也適用於 enum 型別。藉由在列舉中新增 using static，使用列舉成員不再需要型別。

using static Color;

enum Color
{
    Red,
    Green,
    Blue
}

class Program
{
    public static void Main()
    {
        Color color = Green;
    }
}

別名`using`

建立 using 別名指示詞，讓您更輕鬆地將識別碼限定在命名空間或類型。在任何 using 指示詞中，必須使用完整的命名空間或類型，不論 using 指示詞是否在其前面。 using 指示詞的宣告中不可使用任何 using 別名。例如，下列範例會產生編譯器錯誤：

using s = System.Text;
using s.RegularExpressions; // Generates a compiler error.

下列範例示範如何定義和使用命名空間的 using 別名：

namespace PC
{
    // Define an alias for the nested namespace.
    using Project = PC.MyCompany.Project;
    class A
    {
        void M()
        {
            // Use the alias
            var mc = new Project.MyClass();
        }
    }
    namespace MyCompany
    {
        namespace Project
        {
            public class MyClass { }
        }
    }
}

using alias 指示詞的右邊不能有開放式泛型型別。例如，您無法為 List<T> 建立 using alias，但是可以為 List<int> 建立。

下列範例示範如何定義類別的 using 指示詞和 using 別名：

using System;

// Using alias directive for a class.
using AliasToMyClass = NameSpace1.MyClass;

// Using alias directive for a generic class.
using UsingAlias = NameSpace2.MyClass<int>;

namespace NameSpace1
{
    public class MyClass
    {
        public override string ToString()
        {
            return "You are in NameSpace1.MyClass.";
        }
    }
}

namespace NameSpace2
{
    class MyClass<T>
    {
        public override string ToString()
        {
            return "You are in NameSpace2.MyClass.";
        }
    }
}

namespace NameSpace3
{
    class MainClass
    {
        static void Main()
        {
            var instance1 = new AliasToMyClass();
            Console.WriteLine(instance1);

            var instance2 = new UsingAlias();
            Console.WriteLine(instance2);
        }
    }
}
// Output:
//    You are in NameSpace1.MyClass.
//    You are in NameSpace2.MyClass.

從 C# 12 開始，您可以為先前受限制的型別建立別名，包括 Tuple 型別、指標型別和其他不安全的型別。如需已更新規則的詳細資訊，請參閱功能規格。

限定別名成員

命名空間別名限定符可 :: 明確存取全域命名空間或其他使用可能由其他實體隱藏的別名。

global::可確保令牌後面的::命名空間查閱相對於全域命名空間。否則，令牌必須解析為using別名，且後面的 :: 令牌必須解析為該別名命名空間中的類型。下列範例顯示這兩種形式：

using S = System.Net.Sockets;

class A
{
    public static int x;
}

class C
{
    public void F(int A, object S)
    {
        // Use global::A.x instead of A.x
        global::A.x += A;

        // Using ::, S must resolve to a namespace alias:
        S::Socket s = S as S::Socket;

        // In this form, if S were a class, it would be a compile-time error:
        S.Socket s1 = S as S.Socket;
    }
}

C# 語言規格

如需詳細資訊，請參閱 C# 語言規格的 Using 指示詞。語言規格是 C# 語法及用法的限定來源。

如需有關修飾符的全域使用的詳細資訊，請參閱全域使用功能規範。

共用方式為

`using` 指示詞

`global`修飾詞

`static`修飾詞

別名`using`

限定別名成員

C# 語言規格

另請參閱

其他資源

共用方式為

using 指示詞

global修飾詞

static修飾詞

別名using

限定別名成員

C# 語言規格

另請參閱

其他資源

`using` 指示詞

`global`修飾詞

`static`修飾詞

別名`using`