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

Статья
02/20/2013

В этом разделе описаны атрибуты, наиболее часто используемые в программах на языках C# и Visual Basic.

Глобальные атрибуты
Атрибут Obsolete
Атрибут Conditional
Информационные атрибуты вызывающего объекта
Атрибуты в Visual Basic

Глобальные атрибуты

Большинство атрибутов применяется к определенным элементам языка, таким как классы или методы; однако, некоторые атрибуты являются глобальными и могут применяться ко всей сборке или методу.Например, атрибут AssemblyVersionAttribute можно использовать для встраивания сведений о версии в сборку, например вот так:

[assembly: AssemblyVersion("1.0.0.0")]

<Assembly: AssemblyVersion("1.0.0.0")>

Глобальные атрибуты отображаются в исходном коде после любых директив using (Imports в Visual Basic) верхнего уровня и перед всеми объявлениями типов, модулей и пространств имен.Глобальные атрибуты могут присутствовать в нескольких файлах исходного кода, но файлы должны быть скомпилированы за один проход компиляции.В проектах Visual Basic глобальные атрибуты обычно помещаются в файл AssemblyInfo.vb, который автоматически создается в проектах Visual Basic.В проектах C# они помещаются в файл AssemblyInfo.cs.

Атрибуты сборок — это значения, которые содержат информацию о сборке.Эти атрибуты можно разделить на следующие категории:

Атрибуты удостоверения сборки.
Информационные атрибуты.
Атрибуты манифеста сборки.
Атрибуты строгого имени.

Атрибуты удостоверения сборки.

Удостоверение сборки определяют три атрибута (по возможности имеющие строгие имена), а именно: имя, версия, язык и региональные параметры.Эти атрибуты формируют полное имя сборки и являются обязательными при ссылке на сборку в коде.Версию, язык и региональные параметры сборки можно задать с помощью атрибутов.Однако значение имени задается компилятором Visual Studio IDE в Диалоговое окно "Сведения о сборке", или компоновщиком сборки (Al.exe) во время создания сборки на основе файла, содержащегося в манифесте сборки.Атрибут AssemblyFlagsAttribute определяет возможность совместного существования нескольких копий сборки.

В приведенной ниже таблице содержатся атрибуты удостоверения.

Атрибут	Назначение
AssemblyName	Полностью описывает удостоверение сборки.
AssemblyVersionAttribute	Указывает версию сборки.
AssemblyCultureAttribute	Определяет, какие язык и региональные параметры поддерживает сборка.
AssemblyFlagsAttribute	Определяет, поддерживает ли сборка одновременное выполнение на том же компьютере, в том же процессе или в том же домене приложения.

Информационные атрибуты

Информационные атрибуты могут использоваться для присвоения сборке дополнительной информации о компании или продукте.В следующей таблице представлены информационные атрибуты, определенные в пространстве имен System.Reflection.

Атрибут	Назначение
AssemblyProductAttribute	Определяет пользовательский атрибут имени продукта для манифеста сборки.
AssemblyTrademarkAttribute	Определяет пользовательский атрибут товарного знака для манифеста сборки.
AssemblyInformationalVersionAttribute	Определяет пользовательский атрибут версии для манифеста сборки.
AssemblyCompanyAttribute	Определяет пользовательский атрибут имени компании для манифеста сборки.
AssemblyCopyrightAttribute	Определяет пользовательский атрибут авторских прав для манифеста сборки.
AssemblyFileVersionAttribute	Указывает, что компилятор должен использовать определенный номер версии для ресурса версии файла Win32.
CLSCompliantAttribute	Указывает, является ли сборка совместимой со спецификацией CLS.

Атрибуты манифеста сборки.

Атрибуты манифеста сборки можно использовать для предоставления сведений в манифесте сборки.К ним относятся заголовок, описание, псевдоним по умолчанию и конфигурация.В следующей таблице представлены атрибуты манифеста, определенные в пространстве имен System.Reflection.

Атрибут	Назначение
AssemblyTitleAttribute	Определяет пользовательский атрибут названия сборки для манифеста сборки.
AssemblyDescriptionAttribute	Определяет пользовательский атрибут описания сборки для манифеста сборки.
AssemblyConfigurationAttribute	Определяет пользовательский атрибут, который описывает конфигурацию сборки (например коммерческой или отладочной сборки) для манифеста сборки.
AssemblyDefaultAliasAttribute	Определяет понятный псевдоним по умолчанию для манифеста сборки.

Атрибуты строгого имени.

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

Такой способ по-прежнему поддерживается, но предпочтительнее использовать страницу подписи в конструкторе проектов.Дополнительные сведения см. в разделах Страница "Подписывание" в конструкторе проектов и Практическое руководство. Подписывание сборки (Visual Studio).

Атрибут Obsolete

Атрибутом Obsolete отмечается нерекомендуемая для использования сущность программы.Каждый случай использования сущности, отмеченной устаревшей, будет приводить к генерированию предупреждения или ошибки в зависимости от настроек этого атрибута.Например:

    <System.Obsolete("use class B")> 
    Class A
        Sub Method()
        End Sub
    End Class

    Class B
        <System.Obsolete("use NewMethod", True)> 
        Sub OldMethod()
        End Sub

        Sub NewMethod()
        End Sub
    End Class

[System.Obsolete("use class B")]
class A
{
    public void Method() { }
}
class B
{
    [System.Obsolete("use NewMethod", true)]
    public void OldMethod() { }
    public void NewMethod() { }
}

В этом примере атрибут Obsolete применяется к классу A и к методу B.OldMethod.Так как второй аргумент конструктора атрибута, примененный к методу B.OldMethod, имеет значение true, то использование этого метода будет приводить к ошибке компилятора, а использование класса A будет приводить только к генерированию предупреждения.Вызов метода B.NewMethod, однако, не будет приводить к генерированию предупреждения или ошибки.

Строка, передаваемая конструктору атрибута в качестве первого аргумента, будет отображаться как часть предупреждения или ошибки.Например, при использовании с предыдущими определениями следующий код генерирует два предупреждения и одну ошибку:

' Generates 2 warnings:
' Dim a As New A
' Generate no errors or warnings:

Dim b As New B
b.NewMethod()

' Generates an error, terminating compilation:
' b.OldMethod()

// Generates 2 warnings:
// A a = new A();

// Generate no errors or warnings:
B b = new B();
b.NewMethod();

// Generates an error, terminating compilation:
// b.OldMethod();

Для класса A генерируется два предупреждения: одно из-за объявления ссылки на класс и второе из-за конструктора класса.

Атрибут Obsolete может использоваться без аргументов, но рекомендуется включать пояснение, почему соответствующий элемент является устаревшим и что следует использовать взамен.

Атрибут Obsolete является атрибутом однократного использования и может быть применен к любой сущности, допускающей использование атрибутов.Obsolete — это псевдоним для команды ObsoleteAttribute.

Атрибут Conditional

Атрибут Conditional делает выполнение метода зависимым от идентификатора предварительной обработки.Атрибут Conditional является псевдонимом для ConditionalAttribute и может применяться к методу или классу атрибутов.

В данном примере атрибут Conditional применяется к методу для включения и отключения отображения диагностической информации для конкретной программы:


#Const TRACE_ON = True
Imports System
Imports System.Diagnostics
Module TestConditionalAttribute
    Public Class Trace
        <Conditional("TRACE_ON")> 
        Public Shared Sub Msg(ByVal msg As String)
            Console.WriteLine(msg)
        End Sub

    End Class

    Sub Main()
        Trace.Msg("Now in Main...")
        Console.WriteLine("Done.")
    End Sub
End Module

#define TRACE_ON
using System;
using System.Diagnostics;

public class Trace
{
    [Conditional("TRACE_ON")]
    public static void Msg(string msg)
    {
        Console.WriteLine(msg);
    }
}

public class ProgramClass
{
    static void Main()
    {
        Trace.Msg("Now in Main...");
        Console.WriteLine("Done.");
    }
}

Если идентификатор TRACE_ON не задан, выходные данные трассировки не отображаются.

Атрибут Conditional часто используется с идентификатором DEBUG для разрешения функций трассировки и ведения журнала в построениях отладки, но не в построениях выпуска:

<Conditional("DEBUG")> 
Shared Sub DebugMethod()

End Sub

[Conditional("DEBUG")]
static void DebugMethod()
{
}

Если вызывается метод, помеченный как условный, то наличие или отсутствие заданного символа предварительной обработки определяет, включен этот вызов или опущен.Если символ указан, то вызов включается; в противном случае вызов опускается.Использование атрибута Conditional представляет собой более понятную, элегантную и менее подверженную ошибкам альтернативу вложению методов в блоки #if…#endif, как показано ниже:

#If DEBUG Then
    Sub ConditionalMethod()
    End Sub
#End If

#if DEBUG
    void ConditionalMethod()
    {
    }
#endif

Условный метод должен быть методом в объявлении класса или структуры и не должен возвращать значений.

Использование нескольких идентификаторов

Если метод имеет несколько атрибутов Conditional, вызов этого метода включается, если задан хотя бы один из условных символов (т. е. символы логически связаны оператором OR).В данном примере наличие A или B ведет к вызову метода:

<Conditional("A"), Conditional("B")> 
Shared Sub DoIfAorB()

End Sub

[Conditional("A"), Conditional("B")]
static void DoIfAorB()
{
    // ...
}

Для получения эффекта логического связывания символов оператором AND можно задать последовательные условные методы.Например, второй метод, приведенный ниже, выполняется только тогда, когда заданы и A, и B:

<Conditional("A")> 
Shared Sub DoIfA()
    DoIfAandB()
End Sub

<Conditional("B")> 
Shared Sub DoIfAandB()
    ' Code to execute when both A and B are defined...
End Sub

[Conditional("A")]
static void DoIfA()
{
    DoIfAandB();
}

[Conditional("B")]
static void DoIfAandB()
{
    // Code to execute when both A and B are defined...
}

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

Атрибут Conditional можно применить к определению класса атрибутов.В данном примере особый атрибут Documentation только добавляет сведения в метаданные, если задано значение DEBUG.

<Conditional("DEBUG")> 
Public Class Documentation
    Inherits System.Attribute
    Private text As String
    Sub New(ByVal doc_text As String)
        text = doc_text
    End Sub
End Class

Class SampleClass
    ' This attribute will only be included if DEBUG is defined.
    <Documentation("This method displays an integer.")> 
    Shared Sub DoWork(ByVal i As Integer)
        System.Console.WriteLine(i)
    End Sub
End Class

[Conditional("DEBUG")]
public class Documentation : System.Attribute
{
    string text;

    public Documentation(string text)
    {
        this.text = text;
    }
}

class SampleClass
{
    // This attribute will only be included if DEBUG is defined.
    [Documentation("This method displays an integer.")]
    static void DoWork(int i)
    {
        System.Console.WriteLine(i.ToString());
    }
}

Информационные атрибуты вызывающего объекта

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

Для получения сведений о вызывающем объекте члена, используются атрибуты, которые применены к необязательным параметрам.Каждый необязательный параметр указывает значение по умолчанию.В следующей таблице перечислены информационные атрибуты вызывающего объекта, которые определены в пространстве имен System.Runtime.CompilerServices:

Атрибут	Описание	Тип
CallerFilePathAttribute	Полный путь исходного файла, содержащего вызывающий объект.Это путь во время компиляции.	String
CallerLineNumberAttribute	Номер строки в исходном файле, из которого вызывается метод.	Integer
CallerMemberNameAttribute	Имя метода или имя свойства вызывающего объекта.Дополнительные сведения см. в разделе Сведения о вызывающем (C# и Visual Basic).	String

Дополнительные сведения об информационных атрибутах вызывающего объекта: см. в разделе Сведения о вызывающем (C# и Visual Basic).

Атрибуты в Visual Basic

В следующей таблице перечислены атрибуты, относящиеся только к Visual Basic.

Атрибут	Назначение
ComClassAttribute	Указывает компилятору на то, что класс должен быть представлен другим приложениям в виде COM-объекта.
HideModuleNameAttribute	Обеспечивает доступ к членам модуля с использованием только квалификации, необходимой для модуля.
VBFixedStringAttribute	Определяет размер строки заданной длины в структуре для использования с функциями ввода и вывода из файлов.
VBFixedArrayAttribute	Определяет фиксированный размер массива в структуре для использования с функциями ввода и вывода из файлов.

COMClassAttribute

Используйте атрибут COMClassAttribute, чтобы упростить процесс создания COM-компонентов для Visual Basic.COM-объекты существенно отличаются от сборок .NET Framework. Без атрибута COMClassAttribute необходимо выполнить несколько шагов для создания COM-объекта из Visual Basic.Для классов, помеченных атрибутом COMClassAttribute, большую часть этих операций компилятор выполняет автоматически.

HideModuleNameAttribute

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

VBFixedStringAttribute

Используйте атрибут VBFixedStringAttribute для принудительного создания строки фиксированной длины в Visual Basic.По умолчанию строки имеют переменную длину. Этот атрибут особенно полезен при сохранении строк в файлы.Это демонстрируется в следующем коде:

Structure Worker
    ' The runtime uses VBFixedString to determine 
    ' if the field should be written out as a fixed size.
    <VBFixedString(10)> Public LastName As String
    <VBFixedString(7)> Public Title As String
    <VBFixedString(2)> Public Rank As String
End Structure

VBFixedArrayAttribute

Используйте атрибут VBFixedArrayAttribute, чтобы объявить массивы фиксированного размера.Подобно строкам, массивы в Visual Basic по умолчанию имеют переменный размер.Этот атрибут полезен при сериализации или записи данных в файлы.

См. также

Поделиться через