Атрибуты (C#)Attributes (C#)

Атрибуты предоставляют мощное средство для связывания метаданных или декларативной информации с кодом (сборки, типы, методы, свойства и т. д.).Attributes provide a powerful method of associating metadata, or declarative information, with code (assemblies, types, methods, properties, and so forth). Связав атрибут связан с сущностью программы, вы можете проверять этот атрибут во время выполнения, используя технику отражения.After an attribute is associated with a program entity, the attribute can be queried at run time by using a technique called reflection. Подробнее см. в разделе Отражение (C#).For more information, see Reflection (C#).

Атрибуты имеют следующие свойства.Attributes have the following properties:

  • Атрибуты добавляют в программу метаданные.Attributes add metadata to your program. Метаданные — это сведения о типах, определенных в программе.Metadata is information about the types defined in a program. Все сборки .NET содержат некоторый набор метаданных, описывающих типы и члены типов, определенные в этой сборке.All .NET assemblies contain a specified set of metadata that describes the types and type members defined in the assembly. Вы можете добавить пользовательские атрибуты, чтобы указать любую дополнительную информацию.You can add custom attributes to specify any additional information that is required. Подробнее см. в разделе Создание настраиваемых атрибутов (C#).For more information, see, Creating Custom Attributes (C#).
  • Вы можете применить один или несколько атрибутов ко всей сборке, к модулю или к более мелким элементам программы, например к классам и свойствам.You can apply one or more attributes to entire assemblies, modules, or smaller program elements such as classes and properties.
  • Атрибуты могут принимать аргументы, так же как методы и свойства.Attributes can accept arguments in the same way as methods and properties.
  • Программа может проверить собственные метаданные или метаданные в других программах, используя отражение.Your program can examine its own metadata or the metadata in other programs by using reflection. Дополнительные сведения см. в разделе Обращение к атрибутам с помощью отражения (C#).For more information, see Accessing Attributes by Using Reflection (C#).

Использование атрибутовUsing attributes

Атрибуты можно использовать почти в любых объявлениях, но для каждого атрибута можно ограничить типы объявлений, в которых он является допустимым.Attributes can be placed on most any declaration, though a specific attribute might restrict the types of declarations on which it is valid. Чтобы указать атрибут на C#, поместите имя атрибута в квадратных скобках ([]) над объявлением сущности, к которой он применяется.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.

В этом примере атрибут SerializableAttribute используется для применения определенной характеристики к классу: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.
}

Метод с атрибутом DllImportAttribute объявляется следующим образом:A method with the attribute DllImportAttribute is declared like the following example:

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

В объявлении можно разместить несколько атрибутов, как показано в следующем примере: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) { }

Некоторые атрибуты можно указать для одной сущности более одного раза.Some attributes can be specified more than once for a given entity. Пример такого многократно используемого атрибута — ConditionalAttribute:An example of such a multiuse attribute is ConditionalAttribute:

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

Примечание

По соглашению все имена атрибутов заканчиваются словом Attribute, чтобы отличать их от других элементов библиотек .NET.By convention, all attribute names end with the word "Attribute" to distinguish them from other items in the .NET libraries. Но при использовании атрибута в коде этот суффикс можно не указывать.However, you do not need to specify the attribute suffix when using attributes in code. Например, обращение [DllImport] эквивалентно [DllImportAttribute], хотя в библиотеке классов .NET Framework этот атрибут имеет имя DllImportAttribute.For example, [DllImport] is equivalent to [DllImportAttribute], but DllImportAttribute is the attribute's actual name in the .NET Framework Class Library.

Параметры атрибутовAttribute parameters

Многие атрибуты имеют параметры, которые могут быть позиционными, неименованными или именованными.Many attributes have parameters, which can be positional, unnamed, or named. Позиционные параметры должны указываться в определенном порядке и не могут опускаться.Any positional parameters must be specified in a certain order and cannot be omitted. Именованные параметры являются необязательными и могут указываться в любом порядке.Named parameters are optional and can be specified in any order. Сначала указываются позиционные параметры.Positional parameters are specified first. Например, эти три атрибута являются эквивалентными:For example, these three attributes are equivalent:

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

Первый параметр (имя библиотеки DLL) является позиционным и всегда располагается первым, остальные параметры являются именованными.The first parameter, the DLL name, is positional and always comes first; the others are named. В этом примере оба именованных параметра имеют значение по умолчанию (false), и мы можем их опустить.In this case, both named parameters default to false, so they can be omitted. Позиционные параметры соответствуют параметрам конструктора атрибутов.Positional parameters correspond to the parameters of the attribute constructor. Именованные (или необязательные) параметры соответствуют свойствам или полям атрибута.Named or optional parameters correspond to either properties or fields of the attribute. Сведения о значениях параметров по умолчанию указываются в документации по каждому отдельному атрибуту.Refer to the individual attribute's documentation for information on default parameter values.

Целевые объекты атрибутовAttribute targets

Целевой объект атрибута — это сущность, к которой применяется атрибут.The target of an attribute is the entity which the attribute applies to. Например, атрибут можно применить к классу, отдельному методу или ко всей сборке.For example, an attribute may apply to a class, a particular method, or an entire assembly. По умолчанию атрибут применяется к тому элементу, который следует за ним.By default, an attribute applies to the element that follows it. Но у вас есть возможность явным образом указать, например, что атрибут применяется к методу, параметру или возвращаемому значению.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.

Чтобы явным образом определить целевой объект атрибута, используйте следующий синтаксис:To explicitly identify an attribute target, use the following syntax:

[target : attribute-list]

Возможные значения target перечислены в следующей таблице.The list of possible target values is shown in the following table.

Целевое значениеTarget value ПрименениеApplies to
assembly Вся сборкаEntire assembly
module Модуль текущей сборкиCurrent assembly module
field Поле в классе или структуреField in a class or a struct
event событиеEvent
method Метод либо методы доступа к свойствам get и setMethod or get and set property accessors
param Параметры метода или параметры метода доступа setMethod parameters or set property accessor parameters
property Свойство.Property
return Возвращаемое значение метода, индексатора свойства или метода доступа к свойствам getReturn value of a method, property indexer, or get property accessor
type Структура, класс, интерфейс, перечисление или делегатStruct, class, interface, enum, or delegate

Следует указать целевое значение field, чтобы применить атрибут к резервной переменной, созданной для автоматически реализуемого свойства.You would specify the field target value to apply an attribute to the backing field created for an auto-implemented property.

Следующий пример демонстрирует, как применить атрибуты к сборкам и модулям.The following example shows how to apply attributes to assemblies and modules. Дополнительные сведения см. в разделе Общие атрибуты (C#).For more information, see Common Attributes (C#).

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

В следующем примере показано, как применять атрибуты к методам, параметрам и возвращаемым значениям методов в 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; }

Примечание

Вне зависимости от целевых объектов, для которых действует атрибут ValidatedContract, необходимо задать целевой объект для return, даже если атрибут ValidatedContract назначен только возвращаемым значениям.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. Другими словами, компилятор не будет использовать сведения AttributeUsage для разрешения конфликтов между неоднозначными целевыми объектами атрибута.In other words, the compiler will not use AttributeUsage information to resolve ambiguous attribute targets. Подробнее см. в разделе AttributeUsage (C#).For more information, see AttributeUsage (C#).

Популярные методы применения атрибутовCommon uses for attributes

В следующем списке перечислены несколько распространенных применений для атрибутов.The following list includes a few of the common uses of attributes in code:

  • Указание для методов в веб-службах атрибута WebMethod, который обозначает, что метод должен вызываться по протоколу SOAP.Marking methods using the WebMethod attribute in Web services to indicate that the method should be callable over the SOAP protocol. Дополнительные сведения можно найти по адресу: WebMethodAttribute.For more information, see WebMethodAttribute.
  • Описание способов упаковки параметров методов при взаимодействии с машинным кодом.Describing how to marshal method parameters when interoperating with native code. Дополнительные сведения можно найти по адресу: MarshalAsAttribute.For more information, see MarshalAsAttribute.
  • Описание свойств COM для классов, методов и интерфейсов.Describing the COM properties for classes, methods, and interfaces.
  • Вызов неуправляемого кода с помощью класса DllImportAttribute.Calling unmanaged code using the DllImportAttribute class.
  • Указание для сборки таких параметров, как заголовок, версия, описание или товарный знак.Describing your assembly in terms of title, version, description, or trademark.
  • Указание членов класса, которые будут сериализованы при сохранении класса.Describing which members of a class to serialize for persistence.
  • Описание правил сопоставления членов класса с XML-узлами при XML-сериализации.Describing how to map between class members and XML nodes for XML serialization.
  • Описание требований безопасности для методов.Describing the security requirements for methods.
  • Указание характеристик, используемых для обеспечения безопасности.Specifying characteristics used to enforce security.
  • Управление оптимизацией для JIT-компилятора, сохраняя при этом простоту отладки кода.Controlling optimizations by the just-in-time (JIT) compiler so the code remains easy to debug.
  • Получение сведений об объекте, вызывающем метод.Obtaining information about the caller to a method.

Дополнительные сведения можно найти в разделеFor more information, see:

См. такжеSee also