Stosowanie atrybutów

Użyj następującego procesu, aby zastosować atrybut do elementu kodu.

Zdefiniuj nowy atrybut lub użyj istniejącego atrybutu .NET.
Zastosuj atrybut do elementu kodu, umieszczając go bezpośrednio przed elementem.

Każdy język ma własną składnię atrybutów. W językach C++ i C# atrybut jest otoczony nawiasami kwadratowymi i oddzielony od elementu białym znakiem, który może zawierać podział wiersza. W Visual Basic atrybut jest otoczony nawiasami kątowymi i musi znajdować się w tym samym wierszu logicznym; znak kontynuacji wiersza może być używany, jeśli wymagany jest podział wiersza.
Określ parametry pozycyjne i nazwane parametry atrybutu.

Parametry pozycyjne są wymagane i muszą znajdować się przed dowolnymi nazwanych parametrami; odpowiadają parametrom jednego z konstruktorów atrybutu. Nazwane parametry są opcjonalne i odpowiadają właściwościom odczytu/zapisu atrybutu. W języku C++i C#określ name=value dla każdego opcjonalnego parametru, gdzie name jest nazwą właściwości. W Visual Basic określ name:=value.

Atrybut jest emitowany do metadanych podczas kompilowania kodu i jest dostępny dla środowiska uruchomieniowego języka wspólnego oraz dowolnego niestandardowego narzędzia lub aplikacji za pośrednictwem usług odbicia środowiska uruchomieniowego.

Zgodnie z konwencją wszystkie nazwy atrybutów kończą się ciągiem "Attribute". Jednak kilka języków przeznaczonych dla środowiska uruchomieniowego, takich jak Visual Basic i C#, nie wymaga określenia pełnej nazwy atrybutu. Jeśli na przykład chcesz zainicjować System.ObsoleteAttribute, wystarczy, że odwołasz się do niego jako Obsolete.

Prawidłowe argumenty atrybutów

Po przekazaniu argumentów do atrybutu użyj jednego z następujących rodzajów wyrażeń:

Wyrażenia stałe (literały, const/Const wartości oraz wartości typu enumeracyjnego).
Wyrażenia typów (typeof w języku C#, GetType w Visual Basic).
Wyrażenia nazw (nameof w języku C#, NameOf w Visual Basic), które generują ciągi znaków w czasie kompilacji.
Wyrażenia tworzenia tablicy typu parametru atrybutu, które używają tylko poprzednich wyrażeń jako wartości elementów.

Następujące typy są prawidłowe jako typy parametrów atrybutów:

Proste typy (słowo kluczowe C# / Visual Basic słowo kluczowe / typ środowiska uruchomieniowego .NET):

C#	Visual Basic	typ środowiska uruchomieniowego .NET
`bool`	`Boolean`	Boolean
`byte`	`Byte`	Byte
`char`	`Char`	Char
`double`	`Double`	Double
`float`	`Single`	Single
`int`	`Integer`	Int32
`long`	`Long`	Int64
`short`	`Short`	Int16
`string`	`String`	String

object (w języku C#, gdy wartość jest jednym z prawidłowych typów argumentu atrybutu lub jednowymiarową tablicą takich typów).
Type.
Typy wyliczenia, które są dostępne w miejscu użycia.
Tablice jednowymiarowe dowolnego z powyższych typów.

Uwaga / Notatka

Typy sbyte, ushort, uint, ulong, decimal, nint i nuint nie są prawidłowymi typami parametrów atrybutów, chociaż obsługują stałe literałowe.

W poniższych przykładach przedstawiono prawidłowe argumenty atrybutów:

[MyAttr(true)]                            // bool literal
[MyAttr(42)]                              // int literal
[MyAttr("hello")]                         // string literal
[MyAttr(MyEnum.Value)]                    // enum value
[MyAttr(typeof(string))]                  // typeof expression
[MyAttr(nameof(MyClass))]                 // nameof expression (string constant)
[MyAttr(new int[] { 1, 2, 3 })]          // array of constants
[MyAttr(new string[] { "a", "b" })]      // array of strings

<MyAttr(True)>                            ' Boolean literal
<MyAttr(42)>                              ' Integer literal
<MyAttr("hello")>                         ' String literal
<MyAttr(MyEnum.Value)>                    ' Enum value
<MyAttr(GetType(String))>                 ' GetType expression
<MyAttr(NameOf(MyClass))>                 ' NameOf expression (string constant)
<MyAttr(New Integer() {1, 2, 3})>         ' Array of constants

W poniższych przykładach przedstawiono argumenty, które powodują błąd kompilatora:

string value = "test";
[MyAttr(value)]        // Error CS0182: not a constant expression
[MyAttr(GetValue())]   // Error CS0182: method calls aren't allowed

Stosowanie atrybutu do metody

W poniższym przykładzie kodu pokazano, jak używać elementu System.ObsoleteAttribute, który oznacza kod jako przestarzały. Ciąg "Will be removed in next version" jest przekazywany do atrybutu. Ten atrybut powoduje ostrzeżenie kompilatora, które wyświetla przekazany ciąg po wywołaniu kodu, który opisuje atrybut.

public class Example
{
    // Specify attributes between square brackets in C#.
    // This attribute is applied only to the Add method.
    [Obsolete("Will be removed in next version.")]
    public static int Add(int a, int b)
    {
        return (a + b);
    }
}

class Test
{
    public static void Main()
    {
        // This generates a compile-time warning.
        int i = Example.Add(2, 2);
    }
}

Public Class Example
    ' Specify attributes between square brackets in C#.
    ' This attribute is applied only to the Add method.
    <Obsolete("Will be removed in next version.")>
    Public Shared Function Add(a As Integer, b As Integer) As Integer
        Return a + b
    End Function
End Class

Class Test
    Public Shared Sub Main()
        ' This generates a compile-time warning.
        Dim i As Integer = Example.Add(2, 2)
    End Sub
End Class