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

Атрибуты предоставляют мощное средство для связывания метаданных или декларативной информации с кодом (сборки, типы, методы, свойства и т. д.). Связав атрибут связан с сущностью программы, вы можете проверять этот атрибут во время выполнения, используя технику отражения. Подробнее см. в разделе Отражение (C#).

Атрибуты имеют следующие свойства.

  • Атрибуты добавляют в программу метаданные. Метаданные — это сведения о типах, определенных в программе. Все сборки .NET содержат некоторый набор метаданных, описывающих типы и члены типов, определенные в этой сборке. Вы можете добавить пользовательские атрибуты, чтобы указать любую дополнительную информацию. Подробнее см. в разделе Создание настраиваемых атрибутов (C#).
  • Вы можете применить один или несколько атрибутов ко всей сборке, к модулю или к более мелким элементам программы, например к классам и свойствам.
  • Атрибуты могут принимать аргументы, так же как методы и свойства.
  • Программа может проверить собственные метаданные или метаданные в других программах, используя отражение. Дополнительные сведения см. в разделе Обращение к атрибутам с помощью отражения (C#).

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

Атрибуты можно использовать почти в любых объявлениях, но для каждого атрибута можно ограничить типы объявлений, в которых он является допустимым. Чтобы указать атрибут на C#, поместите имя атрибута в квадратных скобках ([]) над объявлением сущности, к которой он применяется.

В этом примере атрибут SerializableAttribute используется для применения определенной характеристики к классу:

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

Метод с атрибутом DllImportAttribute объявляется следующим образом:

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

В объявлении можно разместить несколько атрибутов, как показано в следующем примере:

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) { }

Некоторые атрибуты можно указать для одной сущности более одного раза. Пример такого многократно используемого атрибута — ConditionalAttribute:

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

Примечание

По соглашению все имена атрибутов заканчиваются словом Attribute, чтобы отличать их от других элементов библиотек .NET. Но при использовании атрибута в коде этот суффикс можно не указывать. Например, обращение [DllImport] эквивалентно [DllImportAttribute], хотя в библиотеке классов .NET этот атрибут имеет имя DllImportAttribute.

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

Многие атрибуты имеют параметры, которые могут быть позиционными, неименованными или именованными. Позиционные параметры должны указываться в определенном порядке и не могут опускаться. Именованные параметры являются необязательными и могут указываться в любом порядке. Сначала указываются позиционные параметры. Например, эти три атрибута являются эквивалентными:

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

Первый параметр (имя библиотеки DLL) является позиционным и всегда располагается первым, остальные параметры являются именованными. В этом примере оба именованных параметра имеют значение по умолчанию (false), и мы можем их опустить. Позиционные параметры соответствуют параметрам конструктора атрибутов. Именованные (или необязательные) параметры соответствуют свойствам или полям атрибута. Сведения о значениях параметров по умолчанию указываются в документации по каждому отдельному атрибуту.

Дополнительные сведения о разрешенных типах параметров см. в разделе Атрибуты в спецификации языка C#.

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

Целевой объект атрибута — это сущность, к которой применяется атрибут. Например, атрибут можно применить к классу, отдельному методу или ко всей сборке. По умолчанию атрибут применяется к тому элементу, который следует за ним. Но у вас есть возможность явным образом указать, например, что атрибут применяется к методу, параметру или возвращаемому значению.

Чтобы явным образом определить целевой объект атрибута, используйте следующий синтаксис:

[target : attribute-list]

Возможные значения target перечислены в следующей таблице.

Целевое значение Применение
assembly Вся сборка
module Модуль текущей сборки
field Поле в классе или структуре
event событие
method Метод либо методы доступа к свойствам get и set
param Параметры метода или параметры метода доступа set
property Свойство.
return Возвращаемое значение метода, индексатора свойства или метода доступа к свойствам get
type Структура, класс, интерфейс, перечисление или делегат

Следует указать целевое значение field, чтобы применить атрибут к резервной переменной, созданной для field.

Следующий пример демонстрирует, как применить атрибуты к сборкам и модулям. Дополнительные сведения см. в разделе Общие атрибуты (C#).

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

В следующем примере показано, как применять атрибуты к методам, параметрам и возвращаемым значениям методов в C#.

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

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

// applies to parameter
int Method3([ValidatedContract] string contract) { return 0; }

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

Примечание

Вне зависимости от целевых объектов, для которых действует атрибут ValidatedContract, необходимо задать целевой объект для return, даже если атрибут ValidatedContract назначен только возвращаемым значениям. Другими словами, компилятор не будет использовать сведения AttributeUsage для разрешения конфликтов между неоднозначными целевыми объектами атрибута. Подробнее см. в разделе AttributeUsage (C#).

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

В следующем списке перечислены несколько распространенных применений для атрибутов.

  • Указание для методов в веб-службах атрибута WebMethod, который обозначает, что метод должен вызываться по протоколу SOAP. Для получения дополнительной информации см. WebMethodAttribute.
  • Описание способов упаковки параметров методов при взаимодействии с машинным кодом. Для получения дополнительной информации см. MarshalAsAttribute.
  • Описание свойств COM для классов, методов и интерфейсов.
  • Вызов неуправляемого кода с помощью класса DllImportAttribute.
  • Указание для сборки таких параметров, как заголовок, версия, описание или товарный знак.
  • Указание членов класса, которые будут сериализованы при сохранении класса.
  • Описание правил сопоставления членов класса с XML-узлами при XML-сериализации.
  • Описание требований безопасности для методов.
  • Указание характеристик, используемых для обеспечения безопасности.
  • Управление оптимизацией для JIT-компилятора, сохраняя при этом простоту отладки кода.
  • Получение сведений об объекте, вызывающем метод.

Дополнительные сведения можно найти в разделе

См. также