Atrybuty (C#)Attributes (C#)

Atrybuty zapewniają zaawansowaną metodę kojarzenia metadanych lub deklaracyjne informacje z kodem (zestawy, typy, metody, właściwości i tak dalej).Attributes provide a powerful method of associating metadata, or declarative information, with code (assemblies, types, methods, properties, and so forth). Gdy atrybut jest skojarzony z jednostką programu, atrybut może być badany w czasie wykonywania przy użyciu techniki o nazwie odbicie.After an attribute is associated with a program entity, the attribute can be queried at run time by using a technique called reflection. Aby uzyskać więcej informacji, zobacz odbicie (C#).For more information, see Reflection (C#).

Atrybuty mają następujące właściwości:Attributes have the following properties:

  • Atrybuty dodają metadane do programu.Attributes add metadata to your program. Metadane są informacjami o typach zdefiniowanych w programie.Metadata is information about the types defined in a program. Wszystkie zestawy .NET zawierają określony zestaw metadanych opisujący typy i elementy członkowskie typu zdefiniowane w zestawie.All .NET assemblies contain a specified set of metadata that describes the types and type members defined in the assembly. Można dodać atrybuty niestandardowe, aby określić wszelkie dodatkowe informacje, które są wymagane.You can add custom attributes to specify any additional information that is required. Aby uzyskać więcej informacji, zobacz temat Tworzenie atrybutów niestandardowychC#().For more information, see, Creating Custom Attributes (C#).
  • Można zastosować jeden lub więcej atrybutów do całych zestawów, modułów lub mniejszych elementów programu, takich jak klasy i właściwości.You can apply one or more attributes to entire assemblies, modules, or smaller program elements such as classes and properties.
  • Atrybuty mogą akceptować argumenty w taki sam sposób jak metody i właściwości.Attributes can accept arguments in the same way as methods and properties.
  • Program może przeanalizować własne metadane lub metadane w innych programach przy użyciu odbicia.Your program can examine its own metadata or the metadata in other programs by using reflection. Aby uzyskać więcej informacji, zobacz Uzyskiwanie dostępu do atrybutówC#przy użyciu odbicia ().For more information, see Accessing Attributes by Using Reflection (C#).

Używanie atrybutówUsing attributes

Atrybuty mogą być umieszczane w większości każdej deklaracji, chociaż określony atrybut może ograniczyć typy deklaracji, na których jest on prawidłowy.Attributes can be placed on most any declaration, though a specific attribute might restrict the types of declarations on which it is valid. W C#programie należy określić atrybut, umieszczając nazwę atrybutu ujętą w nawiasy kwadratowe ([]) powyżej deklaracji jednostki, do której ma zastosowanie.In C#, you specify an attribute by placing the name of the attribute enclosed in square brackets ([]) above the declaration of the entity to which it applies.

W tym przykładzie atrybut SerializableAttribute jest używany do zastosowania konkretnej cechy klasy:In this example, the SerializableAttribute attribute is used to apply a specific characteristic to a class:

[Serializable]
public class SampleClass
{
    // Objects of this type can be serialized.
}

Metoda z atrybutem DllImportAttribute jest zadeklarowana jak w poniższym przykładzie:A method with the attribute DllImportAttribute is declared like the following example:

[System.Runtime.InteropServices.DllImport("user32.dll")]
extern static void SampleMethod();

Więcej niż jeden atrybut może być umieszczony w deklaracji, jak pokazano w poniższym przykładzie:More than one attribute can be placed on a declaration as the following example shows:

using System.Runtime.InteropServices;
void MethodA([In][Out] ref double x) { }
void MethodB([Out][In] ref double x) { }
void MethodC([In, Out] ref double x) { }

Niektóre atrybuty można określić więcej niż raz dla danej jednostki.Some attributes can be specified more than once for a given entity. Przykładem takiego atrybutu Multiuse jest ConditionalAttribute:An example of such a multiuse attribute is ConditionalAttribute:

[Conditional("DEBUG"), Conditional("TEST1")]
void TraceMethod()
{
    // ...
}

Uwaga

Według Konwencji wszystkie nazwy atrybutów kończą się słowem "Attribute", aby odróżnić je od innych elementów w bibliotekach platformy .NET.By convention, all attribute names end with the word "Attribute" to distinguish them from other items in the .NET libraries. Nie trzeba jednak określać sufiksu atrybutu podczas używania atrybutów w kodzie.However, you do not need to specify the attribute suffix when using attributes in code. Na przykład [DllImport] jest równoważne [DllImportAttribute], ale DllImportAttribute jest rzeczywistą nazwą atrybutu w bibliotece klas .NET Framework.For example, [DllImport] is equivalent to [DllImportAttribute], but DllImportAttribute is the attribute's actual name in the .NET Framework Class Library.

Parametry atrybutuAttribute parameters

Wiele atrybutów ma parametry, które mogą mieć położenie, nienazwane lub nazwane.Many attributes have parameters, which can be positional, unnamed, or named. Wszystkie parametry pozycyjne muszą być określone w określonej kolejności i nie mogą być pominięte.Any positional parameters must be specified in a certain order and cannot be omitted. Parametry nazwane są opcjonalne i można je określić w dowolnej kolejności.Named parameters are optional and can be specified in any order. Parametry pozycyjne są określone jako pierwsze.Positional parameters are specified first. Na przykład te trzy atrybuty są równoważne:For example, these three attributes are equivalent:

[DllImport("user32.dll")]
[DllImport("user32.dll", SetLastError=false, ExactSpelling=false)]
[DllImport("user32.dll", ExactSpelling=false, SetLastError=false)]

Pierwszy parametr, nazwa biblioteki DLL, jest położeniem i zawsze jest pierwszy. inne osoby mają nazwę.The first parameter, the DLL name, is positional and always comes first; the others are named. W tym przypadku oba nazwane parametry domyślnie mają wartość false, więc można je pominąć.In this case, both named parameters default to false, so they can be omitted. Parametry pozycyjne odpowiadają parametrom konstruktora atrybutu.Positional parameters correspond to the parameters of the attribute constructor. Parametry nazwane lub opcjonalne odpowiadają właściwościom lub polom atrybutu.Named or optional parameters correspond to either properties or fields of the attribute. Informacje dotyczące domyślnych wartości parametrów można znaleźć w dokumentacji poszczególnych atrybutów.Refer to the individual attribute's documentation for information on default parameter values.

Docelowe atrybutyAttribute targets

Obiektem docelowym atrybutu jest jednostka, do której odnosi się ten atrybut.The target of an attribute is the entity which the attribute applies to. Na przykład, atrybut może dotyczyć klasy, konkretnej metody lub całego zestawu.For example, an attribute may apply to a class, a particular method, or an entire assembly. Domyślnie atrybut ma zastosowanie do elementu, który następuje po nim.By default, an attribute applies to the element that follows it. Ale można również jawnie określić, na przykład, czy atrybut jest stosowany do metody lub do jego parametru lub do jego wartości zwracanej.But you can also explicitly identify, for example, whether an attribute is applied to a method, or to its parameter, or to its return value.

Aby jawnie zidentyfikować obiekt docelowy atrybutu, należy użyć następującej składni:To explicitly identify an attribute target, use the following syntax:

[target : attribute-list]

Lista możliwych wartości target przedstawiono w poniższej tabeli.The list of possible target values is shown in the following table.

Wartość docelowaTarget value Informacje zawarte w tym artykule dotycząApplies to
assembly Cały zestawEntire assembly
module Bieżący moduł zestawuCurrent assembly module
field Pole w klasie lub strukturzeField in a class or a struct
event ZdarzenieEvent
method Metody dostępu do właściwości metod lub get i setMethod or get and set property accessors
param Parametry metody lub set parametry dostępu do właściwościMethod parameters or set property accessor parameters
property WłaściwośćProperty
return Wartość zwracana metody, indeksatora właściwości lub właściwości getReturn value of a method, property indexer, or get property accessor
type Struct, Class, Interface, enum lub DelegateStruct, class, interface, enum, or delegate

Należy określić wartość docelową field, aby zastosować atrybut do pola zapasowego utworzonego dla właściwości, która jest implementowana.You would specify the field target value to apply an attribute to the backing field created for an auto-implemented property.

Poniższy przykład pokazuje, jak zastosować atrybuty do zestawów i modułów.The following example shows how to apply attributes to assemblies and modules. Aby uzyskać więcej informacji, zobacz Common AttributesC#().For more information, see Common Attributes (C#).

using System;
using System.Reflection;
[assembly: AssemblyTitleAttribute("Production assembly 4")]
[module: CLSCompliant(true)]

Poniższy przykład pokazuje, jak zastosować atrybuty do metod, parametrów metody i wartości zwracanych metody w C#.The following example shows how to apply attributes to methods, method parameters, and method return values in C#.

// default: applies to method
[ValidatedContract]
int Method1() { return 0; }

// applies to method
[method: ValidatedContract]
int Method2() { return 0; }

// applies to return value
[return: ValidatedContract]
int Method3() { return 0; }

Uwaga

Niezależnie od obiektów docelowych, w których ValidatedContract jest zdefiniowany jako prawidłowy, należy określić element docelowy return, nawet jeśli ValidatedContract zostały zdefiniowane do zastosowania tylko do wartości zwracanych.Regardless of the targets on which ValidatedContract is defined to be valid, the return target has to be specified, even if ValidatedContract were defined to apply only to return values. Innymi słowy kompilator nie będzie używać AttributeUsage informacji do rozwiązywania niejednoznacznych obiektów docelowych atrybutu.In other words, the compiler will not use AttributeUsage information to resolve ambiguous attribute targets. Aby uzyskać więcej informacji, zobacz AttributeUsageC#().For more information, see AttributeUsage (C#).

Typowe zastosowania atrybutówCommon uses for attributes

Poniższa lista zawiera kilka typowych zastosowania atrybutów w kodzie:The following list includes a few of the common uses of attributes in code:

  • Oznaczanie metod przy użyciu atrybutu WebMethod w usługach sieci Web, aby wskazać, że metoda powinna być wywoływana za pośrednictwem protokołu SOAP.Marking methods using the WebMethod attribute in Web services to indicate that the method should be callable over the SOAP protocol. Aby uzyskać więcej informacji, zobacz WebMethodAttribute.For more information, see WebMethodAttribute.
  • Opis sposobu organizowania parametrów metody podczas współdziałania z kodem natywnym.Describing how to marshal method parameters when interoperating with native code. Aby uzyskać więcej informacji, zobacz MarshalAsAttribute.For more information, see MarshalAsAttribute.
  • Opisywanie właściwości modelu COM dla klas, metod i interfejsów.Describing the COM properties for classes, methods, and interfaces.
  • Wywoływanie kodu niezarządzanego za pomocą klasy DllImportAttribute.Calling unmanaged code using the DllImportAttribute class.
  • Opisywanie zestawu pod względem tytułu, wersji, opisu lub znaku towarowego.Describing your assembly in terms of title, version, description, or trademark.
  • Opisywanie elementów członkowskich klasy do serializacji dla trwałości.Describing which members of a class to serialize for persistence.
  • Opis sposobu mapowania między elementami członkowskimi klasy i węzłami XML na potrzeby serializacji XML.Describing how to map between class members and XML nodes for XML serialization.
  • Opisywanie wymagań dotyczących zabezpieczeń dla metod.Describing the security requirements for methods.
  • Określanie charakterystyki służącej do wymuszania zabezpieczeń.Specifying characteristics used to enforce security.
  • Kontrolowanie optymalizacji przez kompilator just-in-Time (JIT), dzięki czemu kod pozostaje łatwy do debugowania.Controlling optimizations by the just-in-time (JIT) compiler so the code remains easy to debug.
  • Uzyskiwanie informacji o wywołującym do metody.Obtaining information about the caller to a method.

Aby uzyskać więcej informacji, zobacz:For more information, see:

Zobacz takżeSee also