23 個屬性

23.1 一般規定

大部分的 C# 語言可讓程式設計人員指定程式中所定義實體的宣告式資訊。 例如,在類別中,方法的存取範圍是使用 method_modifier、public、 protectedinternal和 private來裝飾。

C# 可讓程式設計師發明新的宣告式資訊,稱為 屬性s。 程序設計人員接著可以將屬性附加至各種程序實體,並在運行時間環境中擷取屬性資訊。

注意:例如,框架可能會定義一個 HelpAttribute 屬性,可以放置在某些程式元素(如類別和方法)上,以提供這些程式元素與其文件的對應。 結尾註記

屬性是透過屬性類別的宣告來定義 (§23.2),屬性類別可以有位置和具名參數 (§23.2.3)。 屬性會使用屬性規格附加至 C# 程式中的實體 (§23.3),而且可以在執行階段擷取為屬性實例 (§23.4) 。

23.2 屬性類別

23.2.1 一般規定

衍生自抽象類的類別 System.Attribute,無論是直接或間接,都是 屬性類別。 屬性類別的宣告會定義可在程序實體上放置的新屬性類型。 依照慣例,屬性類別會以的後綴 Attribute命名。 屬性的使用可能會包含或省略此後綴。

屬性類別可以是通用的。 當 attribute_name 參考泛型屬性類別時,每個型別參數都受到與運算元類型參數相同的 typeof 限制(§12.8.18);例如 dynamic,具有元素名稱的元組型別、可空的參考型別 nint、以及 nuint 不允許作為型別參數。 (此外,周圍宣告的型別參數不得用作型別參數;詳見 §8.5。)

Example:

public class Attr<T> : Attribute { } // OK – generic attribute class

[Attr<int>]                           // OK
public class C1 { }

結束範例

23.2.2 屬性用法

屬性 AttributeUsageAttribute (§23.5.2) 可用來描述如何使用屬性類別。

AttributeUsageAttribute 有一個位置參數(§23.2.3),使屬性類別能指定可用於哪些程式實體。

範例:以下範例定義了一個名為 SimpleAttribute 屬性類別的類別,該類別只能放置在 class_declarations和 interface_declarations上,並展示了該 Simple 屬性的多種用途。

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Interface)]
public class SimpleAttribute : Attribute
{ 
    ... 
}

[Simple] class Class1 {...}
[Simple] interface Interface1 {...}

雖然這個屬性是以名稱 SimpleAttribute定義,但使用這個屬性時, Attribute 可能會省略後綴,導致簡短名稱 Simple。 因此,上述範例在語意上相當於下列內容

[SimpleAttribute] class Class1 {...}
[SimpleAttribute] interface Interface1 {...}

結束範例

AttributeUsageAttribute 有一個命名參數(§23.2.3),稱為 AllowMultiple,該參數表示該屬性是否能為同一實體指定多次。 如果 AllowMultiple 屬性類別為 true,則該屬性類別是 多用途屬性類別,而且可以在實體上指定多次。 如果 AllowMultiple 屬性類別為 false 或未指定,則該屬性類別為單一 使用屬性類別,而且最多可以在實體上指定一次。

注意:對於一般屬性類別,重重性由未綁定的通用屬性類別定義決定,而非由個別封閉構造決定。 因此,當 AllowMultiple 為假或未指定時,僅在型別參數上不同的兩個屬性應用程式,不會同時出現在同一實體上。 結尾註記

範例:以下範例定義了一個名為 AuthorAttribute 多重用途的屬性類別,並展示一個類別宣告,該屬性有兩種用途 Author :

[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
public class AuthorAttribute : Attribute
{
    public string Name { get; }
    public AuthorAttribute(string name) => Name = name;
}

[Author("Brian Kernighan"), Author("Dennis Ritchie")]
class Class1 
{
    ...
}

結束範例

AttributeUsageAttribute 有一個命名參數(§23.2.3),稱為 Inherited,該參數表示該屬性在指定於基底類別時,是否也會被從該基底類別衍生的類別繼承。 如果 Inherited 屬性類別為 true,則會繼承該屬性。 如果 Inherited 屬性類別為 false,則不會繼承該屬性。 如果未指定,則其預設值為 true。

屬性類別 X 沒有 AttributeUsageAttribute 附加屬性,如 中所示

class X : Attribute { ... }

相當於下列專案:

[AttributeUsage(
   AttributeTargets.All,
   AllowMultiple = false,
   Inherited = true)
]
class X : Attribute { ... }

23.2.3 位置和命名參數

屬性類別可以有 位置參數s和 具名參數s。 屬性類別的每個公用實例建構函式都會定義該屬性類別的有效位置參數序列。 每個非靜態公開讀寫欄位,以及屬性類別的非靜態公開讀寫或讀取初始化屬性,都會定義該屬性類別的命名參數。 為了讓屬性定義命名參數,該屬性必須同時擁有公共的 get accessor 和 public set 或初始化的 accessor。

範例:以下範例定義了一個名為 HelpAttribute 的屬性類別,其有一個位置參數 url,以及一個命名參數 Topic。 雖然它是非靜態且公開的,但此特性 Url 並未定義命名參數,因為它不是讀寫或讀取初始化。 也會顯示此屬性的兩種用法:

[AttributeUsage(AttributeTargets.Class)]
public class HelpAttribute : Attribute
{
    public HelpAttribute(string url) // url is a positional parameter
    { 
        ...
    }

    // Topic is a named parameter
    public string Topic
    { 
        get;
        set;
    }

    public string Url { get; }
}

[Help("http://www.mycompany.com/xxx/Class1.htm")]
class Class1
{
}

[Help("http://www.mycompany.com/xxx/Misc.htm", Topic ="Class2")]
class Class2
{
}

結束範例

23.2.4 屬性參數類型

屬性類別的位置參數和具名參數類型僅限於 屬性參數類型s,它們為:

  • 下列其中一種類型:bool、byte、、char、doublefloatint、、longsbyteshortstring、uint、 。 ulongushort
  • object 類型。
  • System.Type 類型。
  • 列舉類型。
  • 上述類型的單維陣列。
  • 沒有其中一種類型的建構函式自變數或公用欄位,不得做為屬性規格中的位置或具名參數。

23.3 屬性規範

將先前定義的屬性套用至程式實體稱為 屬性規格。 屬性是針對程式實體指定的其他宣告式資訊片段。 屬性可在全域範圍(以指定包含組件或模組的屬性)以及對type_declarations(§14.8)、class_member_declarations(§15.3)、interface_member_declarations(§19.4)、struct_member_declarations(§16.3)、enum_member_declarations(§20.2)、accessor_declarations(§15.7.3)、event_accessor_declarations(§15.8)來指定)、local_function_declarations(§13.6.4)、parameter_lists 元素(§15.6.2)、type_parameter_lists 元素(§15.2.3)、lambda_expressions(§12.22.1),以及explicit_anonymous_function_parameters與implicit_anonymous_function_parameters元素(§12.22.1)。

屬性在 屬性區段s 中指定。 屬性區段是由一對方括弧所組成,以逗號分隔的清單括住一或多個屬性。 在這類清單中指定屬性的順序,以及附加至相同程序實體之區段的順序並不重要。 例如,屬性規格 [A][B]、 [B][A]、 [A, B]和 [B, A] 是相等的。

global_attributes
    : global_attribute_section+
    ;

global_attribute_section
    : '[' global_attribute_target_specifier attribute_list ']'
    ;

global_attribute_target_specifier
    : global_attribute_target ':'
    ;

global_attribute_target
    : identifier
    ;

attributes
    : attribute_section+
    ;

attribute_section
    : '[' attribute_target_specifier? attribute_list ']'
    ;

attribute_target_specifier
    : attribute_target ':'
    ;

attribute_target
    : identifier
    | keyword
    ;

attribute_list
    : attribute (',' attribute)* ','?
    ;

attribute
    : attribute_name attribute_arguments?
    ;

attribute_name
    : type_name
    ;

attribute_arguments
    : '(' ')'
    | '(' positional_argument_list (',' named_argument_list)? ')'
    | '(' named_argument_list ')'
    ;

positional_argument_list
    : positional_argument (',' positional_argument)*
    ;

positional_argument
    : argument_name? attribute_argument_expression
    ;

named_argument_list
    : named_argument (','  named_argument)*
    ;

named_argument
    : identifier '=' attribute_argument_expression
    ;

attribute_argument_expression
    : non_assignment_expression
    ;

針對生產global_attribute_target,且在下列文字中,標識符的拼字應該等於 assembly 或 module,其中相等是指在6.4.3 中定義的。 針對生產 attribute_target,且在下列文字中, 標識符 應具有不等於 assembly 或 module的拼字,使用與上述相同的相等定義。

屬性是由 attribute_name 和位置及具名自變數的選擇性清單所組成。 具名自變數之前的位置自變數(如果有的話)。 位置自變數是由 attribute_argument_expression所組成;具名自變數是由名稱所組成,後面接著等號,後面接著 attribute_argument_expression,一起受到與簡單指派相同的規則約束。 具名自變數的順序並不重要。

注意:為了方便起見, global_attribute_section 和 attribute_section允許後置逗號,就像 array_initializer 中允許的逗號一樣(§17.7)。 結尾註記

attribute_name會識別屬性類別。

當屬性置於全域層級時, 需要global_attribute_target_specifier 。 當global_attribute_target等於:

  • assembly — 目標為包含的組件
  • module — 目標為包含模組

不允許其他global_attribute_target值。

標準化attribute_target名稱為 event、field、method、、paramproperty、、return、 type和 typevar。 這些目標名稱只能用於下列內容:

  • event ——一個事件。
  • field ——一片田野。 類似欄位的事件(亦即沒有存取子的一個事件)(15.8.2)和自動實作的屬性(~15.7.4)也可以具有具有這個目標的屬性。
  • method — 建構子;終結者;方法;地方功能;操作員;屬性取得、設定與初始化存取器;索引器取得、設定及初始化存取器;事件新增與移除存取器;以及 lambda 表達式。 類似欄位的事件(也就是沒有存取子的一個事件)也可以有具有這個目標的屬性。
  • param — 屬性設定與初始化存取器、索引器設定與初始化存取器、事件新增與移除存取者,以及建構子、方法、本地函式與運算子中的參數。
  • property — 一個性質 和一個索引器。
  • return — 一個代理、方法、本地函式、運算子、屬性 get accessor、indexer get accessor 以及 lambda 運算式。
  • type — 一個代理、類別、結構體、枚舉和介面。
  • typevar — 一個型別參數。

某些內容允許在多個目標上指定屬性。 程式可以藉由包含 attribute_target_specifier來明確指定目標。 如果沒有attribute_target_specifier會套用預設值,但attribute_target_specifier可用來確認或覆寫預設值。 內容會解析如下:

  • 對於委派宣告上的屬性,默認目標為委派。 否則, 當attribute_target 等於:
    • type — 目標是代表
    • return — 目標為回傳值
  • 對於方法宣告上的屬性,默認目標為方法。 否則, 當attribute_target 等於:
    • method — 目標即為方法
    • return — 目標為回傳值
  • 對於本地函式宣告的屬性,預設目標是本地函式。 否則, 當attribute_target 等於:
    • method — 目標為局部函數
    • return — 目標為回傳值
  • 對於運算符宣告上的屬性,默認目標為運算符。 否則, 當attribute_target 等於:
    • method — 目標為運算元
    • return — 目標為回傳值
  • 對於屬性或索引器宣告之 get 存取子宣告上的屬性,預設目標為相關聯的方法。 否則, 當attribute_target 等於:
    • method — 目標為相關方法
    • return — 目標為回傳值
  • 對於屬性或索引器宣告的設定或初始值存取器上的屬性,預設目標是相關的方法。 否則, 當attribute_target 等於:
    • method — 目標為相關方法
    • param — 目標是唯一的隱含參數
  • 對於自動實作屬性宣告上的屬性,默認目標為 屬性。 否則, 當attribute_target 等於:
    • field — 目標是該屬性由編譯器產生的後盾欄位
  • 對於在省略 event_accessor_declarations 預設目標的事件宣告上指定的屬性為事件宣告。 否則, 當attribute_target 等於:
    • event — 目標為事件宣告
    • field — 目標為場
    • method — 目標即為方法
  • 如果事件宣告未省略 event_accessor_declarations 預設目標就是 方法。
    • method — 目標為相關方法
    • param — 目標是唯一的參數
  • 對於 lambda_expression 上的屬性,預設目標是方法。 否則, 當attribute_target 等於:
    • method — 目標即為方法
    • return — 目標為回傳值

在所有其他內容中,允許包含 attribute_target_specifier ,但不需要。

範例:類別宣告可以包含或省略指定符 type:

[type: Author("Brian Kernighan")]
class Class1 {}

[Author("Dennis Ritchie")]
class Class2 {}

舉完一個例子。

實作可以接受其他 attribute_target,其用途是定義實作。 無法辨識這類 attribute_target 的實作應該發出警告,並忽略包含 attribute_section。

依照慣例,屬性類別會以的後綴 Attribute命名。 attribute_name可以包含或省略此後綴。 具體來說, attribute_name 解析方式如下:

  • 如果 attribute_name 最右邊的識別碼是逐字識別碼(§6.4.3),則該 attribute_name 會解析為 type_name (§7.7)。 如果結果不是衍生自 System.Attribute的類型,就會發生編譯時期錯誤。
  • 否則為
    • attribute_name以type_name方式解決(第7.7條),但任何錯誤都會被排除。 如果此解析成功,併產生衍生自 System.Attribute 的類型,則類型是此步驟的結果。
    • Attribute字元會附加在attribute_name中最右側的識別碼上,產生的標記串會被解析為type_name(§7.7),但錯誤會被抑制。 如果此解析成功,併產生衍生自 System.Attribute 的類型,則類型是此步驟的結果。

如果上述兩個步驟中只有一個步驟會產生衍生自 System.Attribute的類型,則該類型就是attribute_name的結果。 否則會發生編譯時期錯誤。

範例:若一個屬性類別同時帶有或不帶此後綴,則存在歧義,並產生編譯時錯誤。 如果attribute_name拼字,使其最右邊的標識碼是逐字標識碼(~6.4.3),則只會比對沒有後綴的屬性,因此能夠解析這類模棱兩可。 範例

[AttributeUsage(AttributeTargets.All)]
public class Example : Attribute
{}

[AttributeUsage(AttributeTargets.All)]
public class ExampleAttribute : Attribute
{}

[Example]               // Error: ambiguity
class Class1 {}

[ExampleAttribute]      // Refers to ExampleAttribute
class Class2 {}

[@Example]              // Refers to Example
class Class3 {}

[@ExampleAttribute]     // Refers to ExampleAttribute
class Class4 {}

顯示兩個名為 Example 和 ExampleAttribute的屬性類別。 屬性 [Example] 模棱兩可,因為它可以參考 Example 或 ExampleAttribute。 使用逐字標識碼可讓在這類罕見情況下指定確切意圖。 屬性 [ExampleAttribute] 並不模棱兩可(不過,如果有名為 ExampleAttributeAttribute的屬性名稱的話,它就會模棱兩可!)。 如果移除類別 Example 的宣告,則這兩個屬性都會參考名為 ExampleAttribute的屬性類別,如下所示:

[AttributeUsage(AttributeTargets.All)]
public class ExampleAttribute : Attribute
{}

[Example]            // Refers to ExampleAttribute
class Class1 {}

[ExampleAttribute]   // Refers to ExampleAttribute
class Class2 {}

[@Example]           // Error: no attribute named “Example”
class Class3 {}

結束範例

在同一個實體上多次使用單一使用屬性類別是編譯時期錯誤。

範例:範例

[AttributeUsage(AttributeTargets.Class)]
public class HelpStringAttribute : Attribute
{
    public HelpStringAttribute(string value)
    {
        Value = value;
    }

    public string Value { get; }
}
[HelpString("Description of Class1")]
[HelpString("Another description of Class1")]   // multiple uses not allowed
public class Class1 {}

會導致編譯時期錯誤,因為它嘗試使用 HelpStringAttribute,這是單一使用屬性類別,在的 Class1宣告上多次。

結束範例

如果下列所有語句都成立,表達式 E 就是 attribute_argument_expression :

  • 的 E 類型是屬性參數類型 (§23.2.4)。
  • 在編譯階段,的值 E 可以解析為下列其中一項:

Example:

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Field)]
public class TestAttribute : Attribute
{
    public int P1 { get; set; }

    public Type P2 { get; set; }

    public object P3 { get; set; }
}

[Test(P1 = 1234, P3 = new int[]{1, 3, 5}, P2 = typeof(float))]
class MyClass {}

class C<T> {
    [Test(P2 = typeof(T))] // Error – T not a closed type.
    int x1;

    [Test(P2 = typeof(C<T>))] // Error – C<;T>; not a closed type.
    int x2;

    [Test(P2 = typeof(C<int>))] // Ok
    int x3;

    [Test(P2 = typeof(C<>))] // Ok
    int x4;
}

結束範例

在多個元件中宣告的類型屬性是由以未指定的順序結合其每個元件的屬性來決定。 如果相同的屬性放在多個元件上,它相當於在型別上多次指定該屬性。

範例:兩部分:

[Attr1, Attr2("hello")]
partial class A {}

[Attr3, Attr2("goodbye")]
partial class A {}

相當於下列單一宣告:

[Attr1, Attr2("hello"), Attr3, Attr2("goodbye")]
class A {}

結束範例

型別參數的屬性會以相同方式結合。

23.4 屬性實例

23.4.1 一般規定

屬性實例是一個實例,表示運行時間的屬性。 屬性是使用屬性類別、位置自變數和具名自變數來定義。 屬性實例是使用位置和具名自變數初始化之屬性類別的實例。

擷取屬性實例牽涉到編譯時間和運行時間處理,如下列子集所述。

23.4.2 屬性的編譯

使用屬性類別、positional_argument_list、T

  • 請遵循編譯時間處理步驟,以編譯。 這些步驟會導致編譯時期錯誤,或判斷可在運行時間叫用的實例建構CT函式。
  • 如果沒有 C 公用輔助功能,則會發生編譯時期錯誤。
  • Arg:
    • 讓我們Name成為 。
    • Name應識別非靜態讀寫公共欄位或公共非靜態讀寫或讀取初始化屬性。T 如果沒有 T 這類欄位或屬性,則會發生編譯時期錯誤。
  • 如果 positional_argument_listP 內的任何值或 named_argument_listN 內的其中一個值是類型 System.String ,且值格式不正確,如 Unicode 標準所定義,則編譯的值是否等於擷取的執行階段值 (§23.4.3) ,則會實作定義。

    注意:舉例來說,包含高代理 UTF-16 碼單元且後面沒有緊接低代碼單元的字串,則不是良構。 結尾註記

  • 將下列資訊(針對屬性的運行時間具現化)儲存在編譯程式所產生的元件輸出中,因為編譯包含 屬性的程式:屬性類別T、上的實例建構CT函式、P和相關聯的程序實體N,並在編譯階段完全解析值。

23.4.3 屬性實例的執行階段擷取

使用 §23.4.2 中定義的術語,可以在執行階段使用下列步驟從元件T擷取以 、 C、 P和 N相關聯E的屬性實例A:

  • 請遵循運行時間處理步驟,以使用編譯時期所決定的實例建構函式和值,執行new T(P)。 這些步驟會導致例外狀況,或產生的O實例T。
  • 針對中的每個Arg,依序排列:
    • 讓我們Name成為 。 若 Name 無法識別非靜態的公開讀寫欄位或非靜態的公開讀寫或讀取初始化屬性, O則會拋出例外。
    • 讓我們Value評估結果。
    • 如果 Name 識別上的 O欄位,請將此欄位設定為 Value。
    • 否則,Name 會識別 上的 O屬性。 將此屬性設定為 Value。
    • 結果是 O,屬性類別 T 的實例,已使用 positional_argument_listP 和 named_argument_listN 初始化。

注意:儲存 T、 C、 P( N 並將其與 E) A 關聯的格式,以及指定 E 與檢索 T、 C、 P、 N 的 A 機制(因此屬性實例在執行時如何取得)超出本規範範圍。 結尾註記

23.5 保留屬性

23.5.1 一般規定

許多屬性會以某種方式影響語言。 這些屬性可以包括:

  • System.AttributeUsageAttribute (§23.5.2),用來描述屬性類別的使用方式。
  • System.Diagnostics.ConditionalAttribute (§23.5.3),是一個多用途屬性類別,用於定義條件方法與條件屬性類別。 這個屬性會藉由測試條件式編譯符號來指出條件。
  • System.ObsoleteAttribute (§23.5.4),用來標記成員為過時。
  • System.Runtime.CompilerServices.AsyncMethodBuilderAttribute (§23.5.5),用於建立非同步方法的任務建置器。
  • System.Runtime.CompilerServices.CallerLineNumberAttribute (§23.5.6.2)、 System.Runtime.CompilerServices.CallerFilePathAttribute (§23.5.6.3)、 System.Runtime.CompilerServices.CallerMemberNameAttribute (§23.5.6.4)及 System.Runtime.CompilerServices.CallerArgumentExpressionAttribute (§23.5.6.5)用於提供呼叫上下文的資訊給可選參數。
  • System.Runtime.CompilerServices.EnumeratorCancellationAttribute (§23.5.10),用於指定非同步迭代器中消去標記的參數。
  • System.Runtime.CompilerServices.ModuleInitializerAttribute (§23.5.11),用於標記方法為模組初始化器。
  • System.Runtime.CompilerServices.InterpolatedStringHandlerAttribute 以及 System.Runtime.CompilerServices.InterpolatedStringHandlerArgumentAttribute,分別用於宣告一個自訂插值字串表達式處理器(§23.5.11.1)以及呼叫其其中一個建構子。
  • System.Diagnostics.CodeAnalysis.UnscopedRefAttribute(§23.5.8),允許原本隱含作用範圍的參考被視為未被作用範圍限制。
  • System.Diagnostics.CodeAnalysis.SetsRequiredMembersAttribute (§23.5.12.1)及 System.Runtime.CompilerServices.RequiredMemberAttribute (§23.5.12.2),用於必需成員情境(§15.7.1)。
  • System.Runtime.CompilerServices.CollectionBuilderAttribute (§23.5.13),該典禮指定集合類型具有集合-建立方法。
  • System.Runtime.CompilerServices.InlineArrayAttribute (§23.5.14),將結構型別標記為內嵌陣列型別(§16.6)。
  • System.Runtime.CompilerServices.OverloadResolutionPriorityAttribute (§23.5.15),規定成員在超載解決時的優先權。

可為 Null 的靜態分析屬性 (§23.5.7) 可以改善針對 Null 可能性和 Null 狀態所產生的警告正確性 (§8.9.5) 。

執行環境可能會提供影響 C# 程式執行的其他實作定義屬性。

23.5.2 AttributeUsage 屬性

屬性 AttributeUsageAttribute 可用來描述可以使用屬性類別的方式。

以 屬性裝飾的 AttributeUsageAttribute 類別應該直接或間接衍生自 System.Attribute。 否則,會發生編譯時期錯誤。

注意:關於使用此屬性的範例,請參見 §23.2.2。 結尾註記

23.5.3 條件屬性

23.5.3.1 一般規定

屬性 ConditionalAttribute 允許定義 條件方法s、 條件局部函數s及 條件屬性類別es。

23.5.3.2 條件方法

以 ConditionalAttribute 裝飾的方法為條件方法。 因此,每個條件方法都與其 ConditionalAttributes 中宣告的條件編譯符號相關聯。

Example:

class Eg
{
    [Conditional("ALPHA")]
    [Conditional("BETA")]
    public static void M()
    {
        // ...
    }
}

Eg.M宣告為與兩個條件式編譯符號ALPHA和 BETA相關聯的條件式方法。

結束範例

如果在呼叫點定義一或多個相關聯的條件式編譯符號,則會包含條件式方法的呼叫,否則會省略呼叫。

條件式方法受限於下列限制:

  • 條件式方法應該是class_declaration或struct_declaration中的方法。 若 ConditionalAttribute 在介面宣告中指定了某方法,則會發生編譯時錯誤。
  • 條件方法不得是屬性、索引器或事件的存取者。
  • 條件式方法的傳回型 void別應為 。
  • 條件式方法不得以 override 修飾詞標示。 不過,條件式方法可以使用 修飾詞來標記 virtual 。 此類方法的覆寫是隱含條件的,不應明確標記為 ConditionalAttribute。
  • 條件式方法不得為介面方法的實作。 否則,會發生編譯時期錯誤。
  • 條件式方法的參數不得為輸出參數。

注意:包含 AttributeUsageAttribute (§23.2.2) 的 AttributeTargets.Method 屬性通常可套用於屬性、索引器及事件的存取者。 上述限制禁止此種使用 ConditionalAttribute。 結尾註記

此外,如果從條件式方法建立委派,就會發生編譯時期錯誤。

範例:範例

#define DEBUG
using System;
using System.Diagnostics;

class Class1
{
    [Conditional("DEBUG")]
    public static void M()
    {
        Console.WriteLine("Executed Class1.M");
    }
}

class Class2
{
    public static void Test()
    {
        Class1.M();
    }
}

Class1.M宣告為條件式方法。 Class2的方法 Test 稱為此方法。 由於已定義條件式編譯符號 DEBUG ,如果 Class2.Test 呼叫 ,則會呼叫 M。 如果未定義符號 DEBUG ,則 Class2.Test 不會呼叫 Class1.M。

結束範例

請務必瞭解,條件式方法的包含或排除是由呼叫點的條件式編譯符號所控制。

範例:以下程式碼

// File Class1.cs:
using System;
using System.Diagnostics;
class Class1
{
    [Conditional("DEBUG")]
    public static void F()
    {
        Console.WriteLine("Executed Class1.F");
    }
}

// File Class2.cs:
#define DEBUG
class Class2
{
    public static void G()
    {
        Class1.F(); // F is called
    }
}

// File Class3.cs:
#undef DEBUG
class Class3
{
    public static void H()
    {
        Class1.F(); // F is not called
    }
}

類別 Class2 和 Class3 每個都包含條件式方法 Class1.F的呼叫,這是根據是否 DEBUG 定義的條件式方法。 由於此符號定義於 的內容Class2中,但不包含 Class3中的 F 呼叫Class2,同時省略 中的 F 呼叫Class3。

結束範例

在繼承鏈結中使用條件式方法可能會造成混淆。 透過 base的形式 base.M呼叫條件式方法,會受限於一般條件式方法呼叫規則。

範例:以下程式碼

// File Class1.cs
using System;
using System.Diagnostics;
class Class1
{
    [Conditional("DEBUG")]
    public virtual void M() => Console.WriteLine("Class1.M executed");
}

// File Class2.cs
class Class2 : Class1
{
    public override void M()
    {
        Console.WriteLine("Class2.M executed");
        base.M(); // base.M is not called!
    }
}

// File Class3.cs
#define DEBUG
class Class3
{
    public static void Main()
    {
        Class2 c = new Class2();
        c.M(); // M is called
    }
}

Class2 包含對其基類中定義的 的 M 呼叫。 省略此呼叫,因為基底方法會根據未定義的符號 DEBUG存在來設定條件。 因此,方法只會寫入主控台 “ ”Class2.M executed 明智地使用 pp_declaration可以消除此類問題。

結束範例

23.5.3.3 條件局部函數

靜態局部函數可以條件方式設計,與條件方法相同(§23.5.3.2)。

若非靜態的本地函式被設定為條件函式,則會發生編譯時錯誤。

23.5.3.4 條件屬性類別

以ConditionalAttribute一個或多個點綴的屬性類別(§23.2)稱為條件屬性類別。 因此,條件屬性類別與其 ConditionalAttributes 中宣告的條件編譯符號相關聯。

Example:

[Conditional("ALPHA")]
[Conditional("BETA")]
public class TestAttribute : Attribute {}

TestAttribute宣告為與條件式編譯符號ALPHA和 BETA相關聯的條件屬性類別。

結束範例

如果在規範點定義了條件屬性的一個或多個關聯的條件編譯符號,則包括條件屬性的屬性規範 (§23.3),否則省略屬性規範。

請務必注意,條件屬性類別的屬性規格包含或排除是由規格點的條件式編譯符號所控制。

範例:在本範例中

// File Test.cs:
using System;
using System.Diagnostics;
[Conditional("DEBUG")]
public class TestAttribute : Attribute {}

// File Class1.cs:
#define DEBUG
[Test] // TestAttribute is specified
class Class1 {}

// File Class2.cs:
#undef DEBUG
[Test] // TestAttribute is not specified
class Class2 {}

類別 Class1 和 Class2 都是以 屬性 Test裝飾,這是根據是否 DEBUG 定義的條件式。 由於這個符號是在的內容Class1中定義,但不是 Class2,因此會包含 上的Test屬性Class1規格,同時省略上的 Test 屬性規格Class2。

結束範例

23.5.4 過時屬性

屬性 ObsoleteAttribute 是用來標記不應該再使用的型別和型別成員。

若程式使用以 裝飾為 ObsoleteAttribute的型別或成員,編譯器應發出警告或錯誤。 具體來說,如果未提供錯誤參數,或提供錯誤參數且具有 值 false,編譯程式應該發出警告。 如果指定 error 參數並且其值為 true,編譯器應該發出錯誤。

範例:以下程式碼

[Obsolete("This class is obsolete; use class B instead")]
class A
{
    public void F() {}
}

class B
{
    public void F() {}
}

class Test
{
    static void Main()
    {
        A a = new A(); // Warning
        a.F();
    }
}

該類別 A 以 裝飾為 ObsoleteAttribute。 每次使用 A 時 Main ,都會產生包含指定訊息的警告:「這個類別已過時;請改用 類別 B 」。

結束範例

23.5.5 AsyncMethodBuilder 屬性

此屬性將建構器與任務類型(§15.14.1)關聯,或選擇非同步函式的建構器(§15.14.5)。

23.5.6 來電者資訊屬性

23.5.6.1 一般規定

基於記錄和報告等用途,函式成員有時有助於取得呼叫程式代碼的特定編譯時間資訊。 呼叫端資訊屬性提供透明傳遞這類資訊的方式。

當選擇性參數以其中一個呼叫端資訊屬性加上批注時,省略呼叫中的對應自變數不一定會導致替代預設參數值。 相反地,如果呼叫內容的相關指定資訊可供使用,該資訊將會當做自變數值傳遞。

Example:

public void Log(
    [CallerLineNumber] int line = -1,
    [CallerFilePath] string path = null,
    [CallerMemberName] string name = null
)
{
    Console.WriteLine((line < 0) ? "No line" : "Line "+ line);
    Console.WriteLine((path == null) ? "No file path" : path);
    Console.WriteLine((name == null) ? "No member name" : name);
}

沒有自變數的呼叫 Log() 會列印呼叫的行號和檔案路徑,以及呼叫發生所在的成員名稱。

結束範例

呼叫端資訊屬性可以發生在任何位置的選擇性參數上,包括委派宣告中。 不過,特定呼叫端資訊屬性會限制他們可以屬性的參數類型,因此一律會有從替代值到參數類型的隱含轉換。

在部分方法或部分索引器宣告的定義部分與實作部分的參數上,使用相同的呼叫者資訊屬性是錯誤的。 只會套用定義元件中的呼叫端資訊屬性,而只會忽略實作元件中發生的呼叫端資訊屬性。

呼叫端資訊不會影響多載解析。 由於屬性化選擇性參數仍會從呼叫端的原始碼中省略,多載解析會以忽略其他省略的選擇性參數(~12.6.4)的方式忽略這些參數。

只有在原始碼中明確叫用函式時,才會取代呼叫端資訊。 隱含調用,例如隱含父建構函式呼叫沒有來源位置,而且不會取代呼叫端資訊。 此外,動態系結的呼叫將不會取代呼叫端資訊。 在這種情況下,當省略呼叫端資訊屬性化參數時,會改用參數的指定預設值。

其中一個例外狀況是查詢表達式。 這些會被視為語法擴充,如果呼叫擴充以省略具有呼叫端資訊屬性的選擇性參數,則會取代呼叫端資訊。 使用的位置是從中產生呼叫的查詢子句位置。

若在特定參數上指定多個呼叫者資訊屬性,則依以下順序CallerLineNumberAttribute辨識:, CallerFilePathAttribute, CallerMemberNameAttributeCallerArgumentExpressionAttribute 請考慮下列參數宣告:

[CallerMemberName, CallerFilePath, CallerLineNumber] object p = ...

CallerLineNumberAttribute 優先,其他三個屬性則被忽略。 若CallerLineNumberAttribute省CallerFilePathAttribute略,則CallerMemberNameAttributeCallerArgumentExpressionAttribute優先,且將被忽略。 這些屬性的語彙順序無關緊要。

23.5.6.2 CallerLineNumber 屬性

當從常數值CallerLineNumberAttribute到參數類型的標準隱含轉換(~10.4.2)時,選擇性參數允許屬性int.MaxValue。 這可確保任何不負數的行號可以傳遞至該值,而不會發生錯誤。

如果原始碼中某個位置的函式調用會省略具有 CallerLineNumberAttribute的選擇性參數,則表示該位置行號的數值常值會當做調用的自變數,而不是預設參數值。

如果調用跨越多行,選擇的行是實作相依的。

行號可能會受到 #line 指示詞的影響(~6.5.8)。

23.5.6.3 CallerFilePath 屬性

當從標準隱含轉換 (~10.4.2CallerFilePathAttribute

若從原始碼中某位置調用函式時省略了帶有 CallerFilePathAttribute的可選參數,則會使用代表該位置檔案路徑的 UTF-16 字串字串字面作為調用參數,而非預設參數值。

檔案路徑的格式與實作相依。

檔案路徑可能會受到 #line 指示詞的影響(~6.5.8)。

23.5.6.4 CallerMemberName 屬性

當從標準隱含轉換 (~10.4.2CallerMemberNameAttribute

如果從函式成員體內某處或套用到該函式成員本身、其回傳類型、參數或原始碼中屬性參數的函式調用,遺漏了帶有 CallerMemberNameAttribute的可選參數,則會使用代表該成員名稱的 UTF-16 字串字串作為調用參數,而非預設參數值。

注意:若函式調用頂層語句,字串即為實作名稱的表示(§7.1.3)。 結尾註記

對於在泛型方法內發生的調用,只會使用方法名稱本身,而不使用類型參數清單。

對於在明確介面成員實作內發生的調用,只會使用方法名稱本身,而沒有上述介面限定性。

對於在屬性或事件存取子內發生的調用,所使用的成員名稱是屬性或事件本身的成員名稱。

對於在索引子存取子內發生的調用,使用的成員名稱是由索引子成員 (IndexerNameAttribute) 所提供的成員名稱,如果有的話,或預設名稱Item。

針對在欄位或事件初始化表達式內發生的調用,所使用的成員名稱是正在初始化的欄位或事件名稱。

對於實例建構函式宣告內發生的調用,靜態建構函式、完成項和運算符所使用的成員名稱是實作相依的。

對於發生在本地函式或匿名函式中的調用,會使用呼叫該函式的成員方法名稱。

範例:請考慮以下情況:

class Program
{
    static void Main()
    {
        F1();
        Action anonymousFunction = () => F2();
        anonymousFunction();

        void F1([CallerMemberName] string? name = null)
        {
            Console.WriteLine($"F1 MemberName: |{name}|");
            F2();
        }

        static void F2([CallerMemberName] string? name = null)
        {
            Console.WriteLine($"F2 MemberName: |{name}|");
        }
    }
}

產生輸出

F1 MemberName: |Main|
F2 MemberName: |Main|
F2 MemberName: |Main|

此屬性提供呼叫函數成員的名稱,對於局部函數 F1 而言,該函數為方法 Main。 即使 F2 被 呼叫 F1,但局部函數 並非 函數成員,因此該調用 F2 的報告呼叫者也是 Main。 同樣地,當 F2 被指派給 anonymousFunction的匿名函式呼叫時,報告的呼叫者就是 Main呼叫該匿名函式的方法。 結束範例

23.5.6.5 CallerArgumentExpression 屬性

屬性 CallerArgumentExpressionAttribute 被套用到 目標參數,並可能導致將兄弟參數參數的原始碼文字擷取為字串,此處稱為 捕獲字串。

目標參數應有 default_argument。 如果由屬性命名的兄弟參數是擴充方法的第一個參數,則擴充方法調用會捕捉接收者表達式的原始文字。 若使用靜態方法語法呼叫該方法,則會擷取該參數對應參數的原始文本。

請考慮以下方法宣告:

using System;
using System.Runtime.CompilerServices;
#nullable enable
class Test
{
    public static void M(int val = 0, [CallerArgumentExpression("val")] string? text = null)
    {
        Console.WriteLine($"val = {val}, text = <{text}>");
    }
}

其中目標參數為text,兄弟參數為 val,其對應參數的原始碼文字可在呼叫時擷取textM。

屬性建構子取一個型別 string為 的參數。 那條線

  • 應包含兄弟參數的名稱;否則,該屬性會被忽略。
  • 應省略帶有該前綴的參數名稱中的前導 @ 。

一個 parameter_list 可能包含多個目標參數。

從目標參數的類型應有標準的隱含轉換(§10.4.2)。string

注意:此不包含使用者定義的轉換。string 實務上,參數類型為 string、 object、 dynamic,或由 string實作的介面。 dynamic參數類型本身不會使呼叫動態綁定;呼叫者資訊替換動態綁定呼叫受 §23.5.6.1 規範。 結尾註記

若針對目標參數傳遞明確參數,則不會擷取任何字串,該參數取用該參數的值。 否則,對應兄弟參數的參數文字會依照以下規則轉換成捕獲的字串:

  • 選擇兄弟參數所提供的來源表達式或 variable_reference 。 對於屬性參數,會選擇其表達式;對於擴展方法接收器,會選擇其接收表達式。 任何參數名稱及參數傳遞模式關鍵字(ref, in, 或 out) 均被排除。
  • 任何最外層的 parenthesized_expression (§12.8.5)都會被其包含的表達式替換,反覆直到結果不再是 parenthesized_expression。 屬於 tuple_literal (§12.8.6)的括號不會被刪除。
  • 捕獲的字串從所得表達式或 variable_reference 的第一個符號的第一個字元開始,直到最後一個符號的最後一個字元結束。 前置與後置的空白區塊、行終止符、註解及預處理器指令在這些邊界之外則被排除。
  • 所有在這些邊界內的原始文字都會被逐字保留,包括空白、行終止符、註解、預處理器指令、 Unicode_Escape_Sequences 以及 @ 識別碼上的前綴。

捕獲的字串接著作為對應目標參數的參數傳遞。 然而,若省略兄弟參數的參數,目標參數會取其 default_argument 值。

範例:給定上述宣告 M ,考慮以下對 的 M呼叫:

Test.M();
Test.M(123);
Test.M(123, null);
Test.M(123, "xyz");
Test.M(  1  +      2 );
Test.M(( ( (123) + 0) ) );
int local = 10;
Test.M(l\u006fcal /*...*/ + // xxx
  5);

產出為

val = 0, text = <>
val = 123, text = <123>
val = 123, text = <>
val = 123, text = <xyz>
val = 3, text = <1  +      2>
val = 123, text = <(123) + 0>
val = 15, text = <l\u006fcal /*...*/ + // xxx
  5>

結束範例

範例:一個可選的目標參數可以透過命名第一個參數來捕捉擴充方法的接收器。 以下 value兩種召喚形式捕獲:

using System;
using System.Runtime.CompilerServices;

int value = 5;
value.Show();
Extensions.Show(value);

static class Extensions
{
    public static void Show(this int value,
        [CallerArgumentExpression("value")] string text = "")
    {
        Console.WriteLine(text);
    }
}

輸出為:

value
value

結束範例

範例:邊界註解與分組括號被排除,但元組括號與標記間的原始文字(包括指令)則保留。 參數名稱與傳遞模式關鍵字不包含在擷取的文字中:

using System;
using System.Runtime.CompilerServices;

Capture(value: /*outer*/ ( /*before*/ 1 /*inside*/ + 2 /*after*/ ) /*outer*/);
Capture(((1, 2)));
int value = 5;
CaptureRef(ref value);
CaptureIn(in value);
CaptureOut(out value);
Capture(1 +
#if true
2
#endif
);

static void Capture<T>(T value,
    [CallerArgumentExpression("value")] string text = "")
    => Console.WriteLine(text);

static void CaptureRef(ref int value,
    [CallerArgumentExpression("value")] string text = "")
    => Console.WriteLine(text);

static void CaptureIn(in int value,
    [CallerArgumentExpression("value")] string text = "")
    => Console.WriteLine(text);

static void CaptureOut(out int value,
    [CallerArgumentExpression("value")] string text = "")
{
    value = 0;
    Console.WriteLine(text);
}

輸出為:

1 /*inside*/ + 2
(1, 2)
value
value
value
1 +
#if true
2

閉包 #endif 位於最後一個表達式標記之外,因此被排除。

結束範例

23.5.7 程式碼分析屬性

23.5.7.1 一般規定

此子句中的屬性用於提供額外資訊,以支援能進行可空性和空狀態診斷的編譯器(§8.9.5)。 編譯器不需執行任何空狀態診斷。 這些屬性的存在或不存在不會影響語言或程序的行為。 不提供空狀態診斷的編譯器應讀取並忽略這些屬性的存在。 提供空狀態診斷的編譯器應針對其用來通知其診斷的任何這些屬性使用本子句中定義的含義。

程式代碼分析屬性會在命名空間 System.Diagnostics.CodeAnalysis中宣告。

屬性 意義
AllowNullAttribute (§23.5.7.2) 不可為 Null 的自變數可能是 Null。
DisallowNullAttribute (第23.5.7.3節) 可為 Null 的自變數絕不應為 Null。
MaybeNullAttribute (第23.5.7.6條) 不可為 Null 的傳回值可能是 Null。
NotNullAttribute (第23.5.7.10條) 可為 Null 的傳回值永遠不會是 Null。
MaybeNullWhenAttribute (§23.5.7.7) 當方法傳回指定的 bool 值時,不可為 Null 的引數可能是 null。
NotNullWhenAttribute (§23.5.7.12) 當方法回傳指定的 bool 值時,可空參數不會是空。
NotNullIfNotNullAttribute (§23.5.7.11) 若指定參數的參數參數非空,則該回傳值不為空值。
MemberNotNullAttribute (第23.5.7.8條) 當方法回傳時,列出的成員不會是空的。
MemberNotNullWhenAttribute (§23.5.7.9) 當方法回傳指定 bool 值時,列出的成員不會是空的。
DoesNotReturnAttribute (第23.5.7.4節) 這個方法永遠不會傳回。
DoesNotReturnIfAttribute (§23.5.7.5) 如果關聯的 bool 參數具有指定的值,這個方法永遠不會傳回 。

§23.5.7 中的以下子條款為有條件規範性。

23.5.7.2 AllowNull 屬性

指定即使對應的類型不允許 Null 值,還是允許 Null 值做為輸入。

範例:考慮以下讀寫屬性,因為它有合理的預設值,因此從未回傳 null 。 不過,用戶可以將 null 提供給 set 存取子,將 屬性設定為該預設值。

#nullable enable
public class X
{
    [AllowNull]
    public string ScreenName
    {
        get => _screenName;
        set => _screenName = value ?? GenerateRandomScreenName();
    }
    private string _screenName = GenerateRandomScreenName();
    private static string GenerateRandomScreenName() => ...;
}

假設下列使用該屬性的 set 存取子

var v = new X();
v.ScreenName = null;   // may warn without attribute AllowNull

如果沒有 屬性,編譯程式可能會產生警告,因為不可為 Null 的型別屬性似乎設定為 Null 值。 屬性的存在會隱藏該警告。 結束範例

23.5.7.3 DisallowNull 屬性

指定即使對應的類型允許 Null 值,也不允許做為輸入。

範例:考慮以下屬性,其中 null 是預設值,但客戶端只能設定為非 null 值。

#nullable enable
public class X
{
    [DisallowNull]
    public string? ReviewComment
    {
        get => _comment;
        set => _comment = value ?? throw new ArgumentNullException(nameof(value),
           "Cannot set to null");
    }
    private string? _comment = default;
}

get 存取子可能會傳回 null的預設值,因此編譯程式可能會警告它必須在存取之前加以檢查。 此外,它警告呼叫者,即使可能是空,呼叫者不應明確設定為空。 結束範例

23.5.7.4 DoesNotReturn 屬性

指定指定的方法永遠不會傳回。

範例:請考慮以下情況:

public class X
{
    [DoesNotReturn]
    private void FailFast() =>
        throw new InvalidOperationException();

    public void SetState(object? containedField)
    {
        if ((!isInitialized) || (containedField == null))
        {
            FailFast();
        }
        // null check not needed.
        _field = containedField;
    }

    private bool isInitialized = false;
    private object _field;
}

屬性的存在可透過多種方式協助編譯程式。 首先,編譯器可以在有路徑讓方法退出且不拋出例外時發出警告。 其次,編譯程式可以在呼叫該方法之後,抑制程式碼中的任何可空警告,直到找到適當的 catch 子句為止。 第三,不可達程式碼不會影響任何空狀態。

屬性不會根據此屬性的存在而變更可觸達性 (~13.2) 或明確的指派 (\9.4) 分析。 它只會用來影響可為 Null 的警告。 結束範例

23.5.7.5 DoesNotReturnIf 屬性

指定當相關聯的 bool 參數具有指定的值時,指定的方法永遠不會傳回 。

範例:請考慮以下情況:

#nullable enable
public class X
{
    private void ThrowIfNull([DoesNotReturnIf(true)] bool isNull, string paramName)
    {
        if (isNull)
        {
            throw new ArgumentException(paramName,
                $"argument for {paramName} cannot be null");
        }
    }

    public void SetFieldState(object containedField)
    {
        ThrowIfNull(containedField == null, nameof(containedField));
        // unreachable code when "isInitialized" is false:
        _field = containedField;
    }

    private bool isInitialized = false;
    private object _field = default!;
}

結束範例

23.5.7.6 MaybeNull 屬性

指定不可為 Null 的傳回值可以是 Null。

範例:考慮以下通用方法:

#nullable enable
[return: MaybeNull]
public T Find<T>(IEnumerable<T> sequence, Func<T, bool> predicate) { ... }

若沒有該屬性,編譯器可能會產生警告,若方法能回傳 null。 屬性的存在會隱藏該警告。 結束範例

23.5.7.7 MaybeNullWhen 屬性

指定當方法傳回指定的null值時,可能是bool不可為 Null 的自變數。 這與(§23.5.7.6)類似MaybeNullAttribute,但包含指定回傳值的參數。

23.5.7.8 MemberNotNull 屬性

指定該成員在方法回傳時不會是 null 。

範例:輔助方法可能包含 MemberNotNull 屬性,以列出該方法中指派給非空值的任何欄位。 分析建構子以判斷所有不可空參考欄位是否已被初始化的編譯器,可能會利用此屬性來發現這些輔助方法設定了哪些欄位。 請考慮下列範例:

#nullable enable
public class Container
{
    private string _uniqueIdentifier; // must be initialized.
    private string? _optionalMessage;

    public Container()
    {
        Helper();
    }

    public Container(string message)
    {
        Helper();
        _optionalMessage = message;
    }

    [MemberNotNull(nameof(_uniqueIdentifier))]
    private void Helper()
    {
        _uniqueIdentifier = DateTime.Now.Ticks.ToString();
    }
}

多個欄位名稱可作為屬性建構子的參數。 結束範例

23.5.7.9 MemberNotNullWhen 屬性

指定當方法回傳指定null值時,所列成員不會被列入bool。

舉例:這個屬性類似 MemberNotNull 於 (§23.5.7.8),但那是一個 MemberNotNullWhen 參數 bool 。 MemberNotNullWhen 設計用於輔助方法回傳 A bool 並表示是否初始化欄位的情況。 結束範例

23.5.7.10 NotNull 屬性

指定如果方法傳回 (而不是擲回),則永遠不會 null 有可為 Null 的值。

範例:請考慮以下情況:

#nullable enable
public static void ThrowWhenNull([NotNull] object? value,
  string valueExpression = "") =>
    _ = value ?? throw new ArgumentNullException(valueExpression);

public static void LogMessage(string? message)
{
    ThrowWhenNull(message, nameof(message));
    Console.WriteLine(message.Length);
}

當啟用可空引用型別時,方法 ThrowWhenNull 會無警告地編譯。 當該方法傳回時, value 自變數保證不是 null。 然而,使用空參考是可以 ThrowWhenNull 接受的。 結束範例

23.5.7.11 NotNullIfNotNull 屬性

指定若該參數的參數參數不是null,則該回傳值不null為 。

範例:回傳值的空狀態可能依賴於一個或多個參數的空狀態。 為了協助編譯器分析,當某方法總是回傳非空值且某些參數並非 null空值時,該方法可裝飾為 NotNullIfNotNullAttribute。 請考慮下列 方法:

#nullable enable
string GetTopLevelDomainFromFullUrl(string url) { ... }

若 url 參數不 null成立, null 則不返回。 啟用可為 Null 的參考時,該簽章會正確運作,前提是 API 永遠不會接受 Null 自變數。 不過,如果自變數可以是 Null,則傳回值也可以是 Null。 若要正確表示該合約,請標註此方法,如下所示:

#nullable enable
[return: NotNullIfNotNull("url")]
string? GetTopLevelDomainFromFullUrl(string? url) { ... }

結束範例

23.5.7.12 NotNullWhen 屬性

指定當方法回傳指定null值時,可空的參數不會是bool。

範例:當參數為null空字串時,函式庫方法String.IsNullOrEmpty(String)會回傳true。 這是一種空檢查(null-check):呼叫者不需要對參數進行空檢查,若方法回傳 false。 要讓這種方法能被 nullable aware ,請將參數型別設為可空參考型別,並用 NotNullWhenAttribute: 來裝飾:

#nullable enable
bool IsNullOrEmpty([NotNullWhen(false)] string? value) { ... }

結束範例

23.5.8 UnscopedRef 屬性

有數種情況中,參考文獻被視為隱含範圍(§9.7.3);也就是說,參考不可逃脫方法。 例如:

  • this 對於結構體實例方法。
  • 參考參數,這些參數指向 ref 結構型別。
  • 我們的參數。

此屬性用於裁判應被允許逃脫的情況。

此屬性可套用於任意 ref ,且 ref-safe-context 會比預設寬一級。 例如:

UnscopedRef 被應用於 原始參考安全上下文 新 ref-safe-context
實例成員 函數成員 僅能回傳
in / ref 參數 僅能回傳 呼叫者上下文
out 參數 函數成員 僅能回傳

當將此屬性套用到結構的實例方法時,會修改隱含 this 參數;也就是說,作為 this 同類型的無註解 ref 參數。

一個以 為 UnscopedRefAttribute 註解的實例方法或屬性,其 的 ref-safe-context this 設為 呼叫者上下文。

標註為 的 UnscopedRefAttribute 成員不得實作介面。

這是個錯誤,不能用 UnscopedRefAttribute 在

  • 一個未被宣告在 struct上的成員。
  • static一個成員、init成員或構造子。struct
  • 一個標記為 scoped的參數。
  • 一個參數,由值傳遞。
  • 一個透過參考傳遞且未隱含作用域的參數。

更多資訊請參見 §9.7.3 。

23.5.9 ScopedRef 屬性

這個名稱 System.Runtime.CompilerServices.ScopedRefAttribute 保留給編譯器使用。 當參數 scoped 的註解與預設狀態不同時,編譯器會對該參數發出此屬性,以便將 scoped 修飾符(§9.7.3)編碼成元資料。 這個屬性在原始碼中是不被允許的。

23.5.10 EnumeratorCancellation 屬性

指定代表非同步反覆運算器的參數 CancellationToken (§15.15)。 此參數的引數應與傳遞給 IAsyncEnumerable<T>.GetAsyncEnumerator(CancellationToken)的引數結合。 此組合令牌應由 (IAsyncEnumerator<T>.MoveNextAsync()) 輪詢。 這些代幣應合併為一個代幣,就像 和 CancellationToken.CreateLinkedTokenSource 其Token屬性一樣。 如果取消兩個來源權杖中的任何一個,則會取消合併的權杖。 組合權杖會被視為該方法主體中非同步反覆運算器方法 (§15.15) 的引數。

如果屬性套用至多個參數,則 EnumeratorCancellationAttribute 為錯誤。 在下列情況下,編譯器可能會產生警告:

  • EnumeratorCancellationAttribute 應用於非型態 CancellationToken的參數,
  • 或若 EnumeratorCancellationAttribute 應用於非非同步迭代器方法的參數(§15.15),
  • 或若 EnumeratorCancellationAttribute 套用於方法上的參數,回傳非同步列舉介面(§15.15.2),而非非同步列舉介面(§15.15.3)。

當沒有任何屬性具備此參數時,迭代器將無法存取該CancellationToken參數。GetAsyncEnumerator

範例:此方法 GetStringsAsync() 是一個非同步迭代器。 在執行任何工作以擷取下一個值之前,它會檢查取消權杖,以判斷是否應該取消反覆專案。 如果要求取消,則不會採取進一步的動作。

public static async Task ExampleCombination()
{
    var sourceOne = new CancellationTokenSource();
    var sourceTwo = new CancellationTokenSource();
    await using (IAsyncEnumerator<string> enumerator =
        GetStringsAsync(sourceOne.Token).GetAsyncEnumerator(sourceTwo.Token))
    {
        while (await enumerator.MoveNextAsync())
        {
            string number = enumerator.Current;
            if (number == "8") sourceOne.Cancel();
            if (number == "5") sourceTwo.Cancel();
            Console.WriteLine(number);
        }
    }
}

static async IAsyncEnumerable<string> GetStringsAsync(
  [EnumeratorCancellation] CancellationToken token)
{
    for (int i = 0; i < 10; i++)
    {
        if (token.IsCancellationRequested) yield break;
        await Task.Delay(1000, token);
        yield return i.ToString();
    }
}

結束範例

23.5.11 ModuleInitializer 屬性

屬性 ModuleInitializerAttribute 用來標記方法為 模組初始化器。 此類方法在包含模組初始化時被呼叫。 一個模組可能有多個初始化器,這些初始化器會依實作定義的順序呼叫。

模組初始化器中允許使用哪些程式碼沒有限制。

模組初始化器應具備以下特性:

  • method_modifierstatic。
  • 沒有 parameter_list。
  • return_typevoid的 。
  • 沒有 type_parameter_list。
  • 不會被 class_declaration 內申報,並擁有 type_parameter_list。
  • 可以從包含模組中可達(即具有存取修飾符 internal 或 public)。
  • 不要成為地方性的活動。

23.5.11.1 自訂插值字串表達式處理器

23.5.11.1.1 宣告自訂處理器

請考慮以下程式,它實作了一個簡單的訊息記錄器:

using System;
public class Logger
{
    public void LogMessage(string msg)
    {
        Console.WriteLine(msg);
    }
}
public class Program
{
    static void Main()
    {
        var logger = new Logger();
        int val = 255;
        logger.LogMessage($"val = {{{val,4:X}}}; 2 * val = {2 * val}.");
    }
}

產出的產品如下:

val = {  FF}; 2 * val = 510.

在呼叫 LogMessage時,插值字串表達式參數的目標是 msg參數 ,其型別 string為 。 如 §12.8.3 所述,編譯器可在預設插值字串處理器可用且上下文支援時使用。 以下範例展示了如何使用自訂處理器。

為了為上述程式提供客製化處理,需要 一個客製化插值字串表達式處理器 。 以下是新增自訂處理器的訊息記錄器,展示了一種可能的實作方式:

using System;
using System.Text;
using System.Runtime.CompilerServices;

[InterpolatedStringHandler]
public ref struct LogInterpolatedStringHandler
{
    StringBuilder builder; // Storage for the built-up string
    public LogInterpolatedStringHandler(int literalLength, int formattedCount)
    {
        builder = new StringBuilder(literalLength);
    }
    public void AppendLiteral(string s)
    {
        builder.Append(s);
    }
    public void AppendFormatted<T>(T t)
    {
        builder.Append(t?.ToString());
    }
    public void AppendFormatted<T>(T t, string format) where T : IFormattable
    {
        builder.Append(t?.ToString(format, null));
    }
    public void AppendFormatted<T>(T t, int alignment)
    {
        builder.Append(String.Format("{0," + alignment + "}", t));
    }
    public void AppendFormatted<T>(T t, int alignment, string format)
        where T : IFormattable
    {
        builder.Append(String.Format("{0" + "," + alignment + ":" + format + "}", t));
    }
    public override string ToString() => builder.ToString();
}

public class Logger
{
    public void LogMessage(string msg)
    {
        Console.WriteLine(msg);
    }
    public void LogMessage(LogInterpolatedStringHandler builder)
    {
        Console.WriteLine(builder.ToString());
    }
}

public class Program
{
    static void Main()
    {
        var logger = new Logger();
        int val = 255;
        logger.LogMessage($"val = {{{val,4:X}}}; 2 * val = {2 * val}.");
    }
}

產出的產品如下:

val = {  FF}; 2 * val = 510.

具有 屬性 InterpolatedStringHandlerAttribute 的型別稱為 適用插值字串處理型態。

隱含插值字串處理器轉換(§10.2.5)到類別或結構型別 T 的綁定方式如下。 屬性的存在決定轉換的適用性;建構子與附加方法驗證會在超載解析選擇轉換後執行。

建構子參數列表包含:

  • 兩個 int 常數:文字段長度之和與 interpolated_string_handler_expression 中插值次數(§12.8.3)。 字面長度是在解碼脫脫後計算的,包括替換 {{ 和 }} 用單大括號。 對於 $"val = {{{val,4:X}}}; 2 * val = {2 * val}.",這兩個值分別為 21 和 2。
  • 由 依指定順序指定的 InterpolatedStringHandlerArgumentAttribute任何額外參數(§23.5.11.1.3)。
  • 一個型bool為 的最後out論點。

建構子綁定基於 T 此參數清單及一般物件建立規則(§12.8.17.2),包括超載解析、可存取性及最終驗證。 若此約束失敗,包括因含糊不清,則重新嘗試結合,且不包含最終 out bool 參數。 若兩次嘗試皆未選擇有效的建構子,則為編譯時錯誤。

範例:接受 out bool 該參數的建構子之間的歧義,並不阻止選擇沒有該參數的建構子:

Handler handler = $"";

[System.Runtime.CompilerServices.InterpolatedStringHandler]
struct Handler
{
    public Handler(int literalLength, int formattedCount) =>
        Console.WriteLine("ungated");
    public Handler(int literalLength, int formattedCount,
        out bool enabled, int optional = 0) { enabled = true; }
    public Handler(int literalLength, int formattedCount,
        out bool enabled, long optional = 0) { enabled = true; }
}

結束範例

新增方法僅解析 interpolated_string_handler_expression中存在的元件:

  • 對於每個非空的文字段,會用一個型別string為 的值參數來解析 的AppendLiteral呼叫。
  • 對每個插值,都會解析一個調用。AppendFormatted 它的第一個參數是插值的 表達式,以值傳遞。 若存在 interpolation_minimum_width ,其常數值會以命名參數 alignment提供。 若存在格式指定符,其文本會以命名參數 format提供。

成員查詢與超載解析使用透過 (§12.8.10.2) 的常規規則進行調用T。 每個選擇的附加方法都應是可存取的實例方法;不考慮延伸方法。 可選參數、一般推論及參數轉換照常適用。 每個選擇的附加方法都必須以值回傳或voidbool,且所有選擇的附加方法都回傳相同類型。 缺少、模糊或無效的必要方法即為編譯時錯誤。

注意:不需要未使用的附加過載或 ToString 覆寫。 附加方法不必是公開或通用的,也不需要特定的通用限制。 處理器不一定需要產生字串。 結尾註記

成功綁定轉換的評估過程如下:

  1. 先前評估過的接收器與參數值或儲存位置,依 據 §23.5.11.1.3 的規定保留。 包含表達式的早期組件會先被評估,並保留其一般的評估順序。
  2. 選取的建構子會以字面長度、插值次數、轉發參數及 out bool 參數(若選擇)來呼叫。 其結果儲存在型為 T的臨時中。
  3. 若 out bool 選取參數且其值為 false,則不會執行附加呼叫,也不會評估插值表達式。
  4. 否則,元件會依詞彙順序處理,涵蓋整個 interpolated_string_handler_expression。 每個文字區段都會被解碼並提供給所選 AppendLiteral 的方法。 每個插值表達式都會被計算、轉換,並以其對齊與格式參數一同提供給所選 AppendFormatted 方法。 若 append 方法回傳 false,所有後續的 append 呼叫與插值表達式皆被跳過。
  5. 轉換結果即為建構處理程序,包括附加呼叫所造成的任何變更。

當建構阻礙處理或附加方法返回 false時,周圍的調用(若有的話)仍然會發生。 後來的普通論證仍以正常順序評估。 沒有默示的處理者。

處理器轉換並不隱含 ToString 呼叫或要求處理器產生字串。 處理者過載與字串過載之間的偏好,詳見 §12.6.4.5。

範例:處理器可以使用非通用、非公開、布ol回傳附加方法而不覆蓋 ToString。 也可以透過引用傳遞,無需明確 ref 的論元:

class Program
{
    static int Hole() { Console.WriteLine("hole"); return 1; }
    static void Write(ref Handler handler, params int[] values) =>
        Console.WriteLine("body:" + values.Length);

    static void Main()
    {
        Write(($"prefix{Hole()}" + ($"{Hole()}"!)), 1, 2);
        Write($"{Hole(),4:X}", new[] { 1 });
    }
}

[System.Runtime.CompilerServices.InterpolatedStringHandler]
struct Handler
{
    internal Handler(int literalLength, int formattedCount) =>
        Console.WriteLine($"construct:{literalLength}:{formattedCount}");
    internal bool AppendLiteral(string text)
    {
        Console.WriteLine("literal:" + text);
        return false;
    }
    internal bool AppendFormatted(int value, int alignment = 0, string format = null)
    {
        Console.WriteLine($"formatted:{value}:{alignment}:{format}");
        return false;
    }
}

第一個字面附詞會壓制第一個召喚中的兩個孔洞。 第二次呼叫評估其第一個孔洞,並以名稱傳遞對齊與格式。 兩個召喚都執行 Write。

結束範例

23.5.11.1.2 禁止自訂處理器

若建構子解析選擇帶有 out bool 參數的建構子,則在建構後會測試該參數的值。 如果是, true元件處理開始。 若為 false,則 處理程序被 抑制:不評估插值表達式,也不會呼叫附加方法。 此測試與每次布爾回傳附加呼叫後的短路測試是分開的。

public LogInterpolatedStringHandler(int literalLength, int formattedCount,
    out bool processString)
{
    if (some_condition)
    {
        processString = false;
        return;
    }
    else
    {
        processString = true;
        // continue construction
    }
}

注意:插值表達式可能包含副作用,例如來自 ++、 --、 指派及方法呼叫。 建構子抑制跳過所有此類表達式。 假附加結果只會跳過剩餘的表達式。 定指派解釋了這些條件路徑(§9.4.4.23)。 結尾註記

23.5.11.1.3 傳遞資訊給/從自訂處理器

傳遞其他資訊給自訂處理器,並接收回傳資訊,是很有用的。 這是透過屬性 InterpolatedStringHandlerArgument來完成的。 請考慮以下對訊息記錄程式的新超載:

public class Logger
{
    // …
    public void LogMessage(bool flag, int count,
        [InterpolatedStringHandlerArgument("count","flag","")]
        LogInterpolatedStringHandler builder)
    {
        // …
    }
}

public ref struct LogInterpolatedStringHandler
{
    // …
    public LogInterpolatedStringHandler(int literalLength, int formattedCount,
        int count, bool flag, Logger logger)
    {
        // …
    }
}

InterpolatedStringHandlerArgumentAttribute 套用到處理器參數。 其參數指定一個有序的參數名稱清單,要轉發給處理器建構子。 空白清單不會轉發任何東西。 空字串表示包含呼叫的接收者。

每個非空名稱應識別包含成員的另一個參數。 未知名稱、處理者參數自身名稱,或對無法接收的請求(包括靜態方法的請求)屬於編譯時錯誤。 如果指定參數在處理者參數之後宣告,宣告可能會產生警告;這並不使該聲明無效。

在使用處理器轉換時,每個轉發的參數在詞彙上都必須出現在呼叫參數清單中的 interpolated_string_handler_expression 之前。 轉發的參數不能被遺漏,只能由參數的預設值來提供。 這些要求取決於呼叫站點順序,而非宣告順序;因此,命名參數可以讓警告宣告變得可用。 當索引器接收器是member_initializer中的initializer_target時,請求轉發索引器接收器屬於編譯時錯誤。

建構器超載解析使用包含成員的參數類型,並替換其型別參數參數,而非原始參數表達式。 轉發的參數保留其參數傳遞模式。 執行時,已評估的接收器及已轉換的參數值或評估過的儲存位置會被處理程序建構與包含調用重複使用,保留參考語意。 構造子還需對這些保留值進行額外轉換;原始表達式不再被評估或綁定。

注意:特別地,轉發的 lambda 並不會獨立綁定到建構子的不同代理類型。 處理器建構子參數類型不會對包含調用的通用推論做出貢獻。 對建構子參數的可空分析不會將變更流回原始接收器或參數欄位。 結尾註記

23.5.12 必要成員屬性

23.5.12.1 SetsRequiredMembers 屬性

此屬性表示其裝飾的建構子已設定當前型別的所有必要成員,因此呼叫者無需自行設定任何必要成員。 然而,編譯器並未驗證建構子是否真的初始化了所有所需的成員。

Example:

public class Person
{
    public Person() { }

    [SetsRequiredMembers]
    public Person(string firstName, string lastName) =>
        (FirstName, LastName) = (firstName, lastName);

    public required string FirstName { get; init; }
    public required string LastName { get; init; }

    public int? Age { get; set; }
}

public class Student : Person
{
    public Student() : base()
    {
    }

    [SetsRequiredMembers]
    public Student(string firstName, string lastName) :
        base(firstName, lastName)
    {
    }

    public double GPA { get; set; }
}

public class Test
{
    public static void M()
    {
        var p1 = new Student(); // error: doesn't set required members
        var p2 = new Student("Jane", "Williams"); // OK
    }
}

結束範例

注意:由於衍生型建構子 Student(string, string) 與具有此屬性的基底建構子 Person(string, string)鏈式,衍生型態建構子也必須具備該屬性(§15.11.1)。 結尾註記

23.5.12.2 RequiredMember 屬性

此屬性表示目前型別有一個或多個必需成員(§15.7.1),或是該型別的特定成員是必需的。 然而,明確使用此屬性是錯誤的。 相反地,修飾符 required 的存在會使該類型或成員被視為裝飾了這個屬性。

23.5.13 CollectionBuilder 屬性

此屬性指定集合類型具有集合建立方法(§15.17.1)。

建構子會取一個建構型別及要調用的方法名稱來建構該集合型別的實例。

屬性可以套用到類別、結構體、ref 結構體或介面上。 該屬性不會被繼承,但它可以套用到基底類別或抽象類別。

建構者類型應為非通用類別或結構體。

23.5.14 InlineArray 屬性

此屬性用來將非記錄結構體識別為內列陣列類型。 欲了解更多資訊及使用範例,請參見 第16.6節。

23.5.15 OverloadResolutionPriority 屬性

屬性 OverloadResolutionPriority 用於在超載解析時指定成員的優先順序,作為 int 建構子的參數。 此屬性的缺失等價於其存在且參數為 0。 數字越大,優先順序越高。 所有優先權低於最高超載優先權的超載,都會從適用的配對集合中移除。

函式庫作者可能會使用此屬性,確保優先選擇新的、更好的超載而非現有的,以減少記憶體配置。 此屬性會告知編譯器應優先處理哪種過載。

範例:請考慮以下情況:

class Program
{
    static void Main()
    {
        var c = new C();
        int[] arr = [1, 2, 3];
        c.M(arr);   // Prints "Span"
    }
}
class C
{
    [OverloadResolutionPriority(1)]
    public void M(params ReadOnlySpan<int> s) => Console.WriteLine("Span");
    public void M(params int[] a) => Console.WriteLine("Array");
}

第二種方法隱含優先權為零,若無明確屬性,則會呼叫第二個超載。 然而,當屬性存在時,會被召喚出第一個屬性。

此屬性的某些使用可能會使成員無法被呼叫,具體如下:

class Program
{
    static void Main()
    {
        var c = new C();
        c.M1(1); // Calls C3.M1(long), not M1(int)
        c.M2(1); // Calls C3.M2(int, string), not M2(int)
        c.M3("abc"); // Calls C3.M3(object), not M3(string)
    }
}
class C
{
    public void M1(int i) { }
    [OverloadResolutionPriority(1)]
    public void M1(long l) { }

    [Conditional("DEBUG")]
    public void M2(int i) { }
    [OverloadResolutionPriority(1), Conditional("DEBUG")]
    public void M2(int i, [CallerArgumentExpression(nameof(i))] string s = "") { }

    public void M3(string s) { }
    [OverloadResolutionPriority(1)]
    public void M3(object o) { }
}

結束範例

23.6 互通屬性

若要與其他語言互操作,您可以使用索引屬性來實作索引器。 如果索引器沒有 IndexerNameAttribute裝飾 ,則預設使用該名稱 Item 。 IndexerNameAttribute 讓開發者能覆寫此預設值並指定不同名稱。

範例:預設索引器的名稱為 Item。 這可以覆寫,如下所示:

[System.Runtime.CompilerServices.IndexerName("TheItem")]
public int this[int index]
{
    get { ... }
    set { ... }
}

現在,索引器的名稱是 TheItem。

結束範例