Атрибуты (C# и Visual Basic)
Атрибуты обеспечивают эффективный способ связывания метаданных или декларативной информации с кодом (сборками, типами, методами, свойствами и т. д.). Атрибут, связанный с сущностью программы, может быть запрошен во время выполнения с помощью метода, называемого отражением.. Дополнительные сведения см. в разделе Отражение (C# и Visual Basic).
Атрибуты имеют следующие параметры.
Атрибуты добавляют в программу метаданные. Метаданные представляют собой сведения о типах, определенных в программе. Все сборки .NET содержат заданный набор метаданных, описывающих типы и члены типов, определенных в сборке. Для задания необходимых дополнительных сведений можно добавить атрибуты. Дополнительные сведения см. в разделе Создание настраиваемых атрибутов (C# и Visual Basic).
Один или несколько атрибутов могут применяться к сборкам, модулям или более мелким программным элементам, таким как классы и свойства.
Атрибуты могут принимать аргументы точно так же, как методы и свойства.
Программа может проверить собственные метаданные или метаданные в других программах с помощью отражения. Дополнительные сведения см. в разделе Обращение к атрибутам с помощью отражения (C# и Visual Basic).
Использование атрибутов
Атрибуты могут быть размещены в большинстве объявлений, хотя определенный атрибут может ограничить типы объявлений, в которых он допустим. В C# атрибут задается путем размещения его имени, заключенного в квадратные скобки ([]), перед объявлением сущности, к которой он относится. В Visual Basic атрибуты заключаются в угловые скобки (< >). Их необходимо помещать непосредственно перед элементом, к которому они относятся, на той же строке.
В этом примере для применения определенных характеристик к классу используется атрибут SerializableAttribute.
<System.Serializable()> Public Class SampleClass
' Objects of this type can be serialized.
End Class
[System.Serializable]
public class SampleClass
{
// Objects of this type can be serialized.
}
Объявление метода с атрибутом DllImportAttribute выглядит следующим образом.
Imports System.Runtime.InteropServices
...
<System.Runtime.InteropServices.DllImport("user32.dll")>
Sub SampleMethod()
End Sub
using System.Runtime.InteropServices;
...
[System.Runtime.InteropServices.DllImport("user32.dll")]
extern static void SampleMethod();
Объявление может содержать несколько атрибутов.
Imports System.Runtime.InteropServices
...
Sub MethodA(<[In](), Out()> ByVal x As Double)
End Sub
Sub MethodB(<Out(), [In]()> ByVal x As Double)
End Sub
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")>
Sub TraceMethod()
End Sub
[Conditional("DEBUG"), Conditional("TEST1")]
void TraceMethod()
{
// ...
}
Примечание
Чтобы отличать атрибуты от других элементов платформы .NET Framework, используется соглашение, по которому все имена атрибутов заканчиваются словом "Attribute" ("атрибут").Однако нет необходимости указывать суффикс атрибута при его использовании в коде.Например, [DllImport] эквивалентен [DllImportAttribute], однако DllImportAttribute является фактическим именем атрибута в платформе .NET Framework.
Параметры атрибутов
Многие атрибуты имеют параметры, которые могут быть позиционными, неименованными или именованными. Именованные параметры следует указывать в определенном порядке, их нельзя опустить; именованные параметры являются необязательными и могут быть указаны в любой последовательности. Сначала указываются позиционные параметры. Например, следующие три атрибута являются эквивалентными.
[DllImport("user32.dll")]
[DllImport("user32.dll", SetLastError=false, ExactSpelling=false)]
[DllImport("user32.dll", ExactSpelling=false, SetLastError=false)]
<DllImport("user32.dll")>
<DllImport("user32.dll", SetLastError:=False, ExactSpelling:=False)>
<DllImport("user32.dll", ExactSpelling:=False, SetLastError:=False)>
Первый параметр — имя библиотеки DLL — является позиционным и всегда стоит на первом месте; остальные являются именованными. В этом случае оба именованных параметра по умолчанию имеют значение "false" и могут быть пропущены. Сведения о заданных по умолчанию значениях параметров см. в документации по отдельному атрибуту.
Целевые объекты атрибутов
Целевым объектом атрибута является сущность, к которой относится атрибут. Например, атрибут может относиться к классу, отдельному методу или целой сборке. По умолчанию атрибут относится к тому элементу, перед которым он указан. Однако можно явным образом определить, к чему относится атрибут, — например, к методу, его параметру или возвращаемому значению.
Для явного задания целевого объекта атрибута используется следующий синтаксис.
[target : attribute-list]
<target : attribute-list>
Список возможных значений target приведен в следующей таблице.
C# |
Visual Basic |
Применение |
|---|---|---|
assembly |
Assembly |
Целая сборка |
module |
Module |
Модуль текущей сборки (отличается от модуля Visual Basic) |
field |
Не поддерживаются |
Поле в классе или в структуре |
event |
Не поддерживаются |
Событие |
method |
Не поддерживаются |
Метод или метод доступа к свойствам get или set |
param |
Не поддерживаются |
Параметры методов или параметры методов доступа к свойствам set |
property |
Не поддерживаются |
Свойство |
return |
Не поддерживаются |
Возвращаемое значение метода, индексатор свойств или метод доступа к свойствам get |
type |
Не поддерживаются |
Структура, класс, интерфейс, перечисление или делегат |
В следующем примере показано применение атрибутов к сборкам и модулям. Дополнительные сведения см. в разделе Общие атрибуты (C# и Visual Basic).
Imports System.Reflection
<Assembly: AssemblyTitleAttribute("Production assembly 4"),
Module: CLSCompliant(True)>
using System;
using System.Reflection;
[assembly: AssemblyTitleAttribute("Production assembly 4")]
[module: CLSCompliant(true)]
В следующем примере показано, как применять атрибуты к методам, параметрам методов и возвращаемым значениям методов в C#.
// default: applies to method
[SomeAttr]
int Method1() { return 0; }
// applies to method
[method: SomeAttr]
int Method2() { return 0; }
// applies to return value
[return: SomeAttr]
int Method3() { return 0; }
Примечание
Независимо от целевых объектов, для которых определен атрибут SomeAttr, необходимо задать целевой объект return, даже если атрибут SomeAttr определен как относящийся только к возвращаемым значениям.Другими словами, компилятор не будет использовать информацию AttributeUsage для разрешения неоднозначных целевых объектов атрибута.Дополнительные сведения см. в разделе AttributeUsage (C# и Visual Basic).
Общие случаи использования атрибутов
Следующий список содержит несколько общих случаев использования атрибутов в коде:
Пометка метода веб-службы с помощью атрибута WebMethod для указания на возможность вызова метода с помощью протокола SOAP. Дополнительные сведения см. в разделе WebMethodAttribute.
Описание способов упаковки параметров методов при взаимодействии с машинным кодом. Дополнительные сведения см. в разделе MarshalAsAttribute.
Описание свойств COM для классов, методов и интерфейсов.
Вызов неуправляемого кода с помощью класса DllImportAttribute.
Описание сборки с помощью заголовка, версии, описания или торгового знака.
Указание того, какие члены класса должны быть сериализованы при сохранении.
Описание порядка сопоставления членов класса и XML-узлов при XML-сериализации.
Описание требований безопасности к методам.
Указание характеристик, используемых для обеспечения безопасности.
Управление оптимизацией с помощью JIT-компилятора для того, чтобы отладка кода оставалась простой.
Связанные разделы
Дополнительные сведения см. в следующих разделах.
Обращение к атрибутам с помощью отражения (C# и Visual Basic)
Практическое руководство. Создание объединения C/C++ с помощью атрибутов (C# и Visual Basic)
См. также
Ссылки
Основные понятия
Руководство по программированию на C#
Расширение метаданных с помощью атрибутов