Атрибуты (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()
{
    // ...
}

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

Многие атрибуты имеют параметры, которые могут быть позиционными, неименованными или именованными. Любые позиционные параметры следует указывать в определенном порядке, их нельзя опустить; именованные параметры являются необязательными и могут быть указаны в любой последовательности. Сначала указываются позиционные параметры. Например, следующие три атрибута являются эквивалентными.

[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).

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; }

Общие случаи использования атрибутов

Следующий список содержит несколько общих случаев использования атрибутов в коде:

• Пометка метода веб-службы с помощью атрибута WebMethod для указания на возможность вызова метода с помощью протокола SOAP. Дополнительные сведения см. в разделе WebMethodAttribute.

• Описание способов упаковки параметров методов при взаимодействии с машинным кодом. Дополнительные сведения см. в разделе MarshalAsAttribute.

• Описание свойств COM для классов, методов и интерфейсов.

• Вызов неуправляемого кода с помощью класса DllImportAttribute.

• Описание сборки с помощью заголовка, версии, описания или торгового знака.

• Указание того, какие члены класса должны быть сериализованы при сохранении.

• Описание порядка сопоставления членов класса и XML-узлов при XML-сериализации.

• Описание требований безопасности к методам.

• Указание характеристик, используемых для обеспечения безопасности.

• Управление оптимизацией с помощью JIT-компилятора для того, чтобы отладка кода оставалась простой.

• Получение сведений методом о вызывающем объекте.

Связанные разделы

Дополнительные сведения см. в следующих разделах.

• Создание настраиваемых атрибутов (C# и Visual Basic)

• Обращение к атрибутам с помощью отражения (C# и Visual Basic)

• Практическое руководство. Создание объединения C/C++ с помощью атрибутов (C# и Visual Basic)

• Общие атрибуты (C# и Visual Basic)

• Сведения о вызывающем (C# и Visual Basic)

См. также

Ссылки

Отражение (C# и Visual Basic)

Основные понятия

Руководство по программированию на C#

Другие ресурсы

Руководство по программированию на Visual Basic

Расширение метаданных с помощью атрибутов