Общие атрибуты (C#)Common Attributes (C#)

В этом разделе описываются атрибуты, которые чаще всего используются в программах C#.This topic describes the attributes that are most commonly used in C# programs.

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

Большинство атрибутов применяется к определенным элементам языка, таким как классы или методы. Тем не менее некоторые атрибуты являются глобальными — они применяются ко всей сборке или модулю.Most attributes are applied to specific language elements such as classes or methods; however, some attributes are global—they apply to an entire assembly or module. Например, атрибут AssemblyVersionAttribute можно использовать для встраивания сведений о версии в сборку, например следующим образом:For example, the AssemblyVersionAttribute attribute can be used to embed version information into an assembly, like this:

[assembly: AssemblyVersion("1.0.0.0")]  

Глобальные атрибуты отображаются в исходном коде после любых директив using верхнего уровня и перед всеми объявлениями типов, модулей или пространств имен.Global attributes appear in the source code after any top-level using directives and before any type, module, or namespace declarations. Глобальные атрибуты могут содержаться в нескольких исходных файлах, однако эти файлы должны быть скомпилированы за один проход компиляции.Global attributes can appear in multiple source files, but the files must be compiled in a single compilation pass. В проектах C# глобальные атрибуты помещаются в файл AssemblyInfo.cs.In C# projects, global attributes are put in the AssemblyInfo.cs file.

Атрибуты сборки — это значения, которые предоставляют сведения о сборке.Assembly attributes are values that provide information about an assembly. Они делятся на следующие категории:They fall into the following categories:

  • Атрибуты удостоверения сборкиAssembly identity attributes

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

  • Атрибуты манифеста сборкиAssembly manifest attributes

Атрибуты удостоверения сборкиAssembly Identity Attributes

Три атрибута (со строгим именем, если оно применимо) определяют удостоверение сборки: имя, версию, язык и региональные параметры.Three attributes (with a strong name, if applicable) determine the identity of an assembly: name, version, and culture. Эти атрибуты формируют полное имя сборки и являются обязательными при ссылке на нее в коде.These attributes form the full name of the assembly and are required when you reference it in code. Атрибуты можно использовать для задания версии сборки и языка и региональных параметров.You can set an assembly's version and culture using attributes. Однако значение имени задается компилятором, в интегрированной среде разработки Visual Studio, в диалоговом окне сведений о сборке или в компоновщике сборок (Al.exe) при создании сборки на основе файла, содержащего манифест сборки.However, the name value is set by the compiler, the Visual Studio IDE in the Assembly Information Dialog Box, or the Assembly Linker (Al.exe) when the assembly is created, based on the file that contains the assembly manifest. Атрибут AssemblyFlagsAttribute указывает, могут ли сосуществовать несколько копий сборки.The AssemblyFlagsAttribute attribute specifies whether multiple copies of the assembly can coexist.

В следующей таблице приведены атрибуты удостоверения.The following table shows the identity attributes.

АтрибутAttribute ЦельPurpose
AssemblyName Полностью описывает удостоверение сборки.Fully describes the identity of an assembly.
AssemblyVersionAttribute Задает версию сборки.Specifies the version of an assembly.
AssemblyCultureAttribute Указывает, какой язык и региональные параметры поддерживает сборка.Specifies which culture the assembly supports.
AssemblyFlagsAttribute Указывает, поддерживает ли сборка параллельное выполнение на одном компьютере, в одном процессе или в одном домене приложения.Specifies whether an assembly supports side-by-side execution on the same computer, in the same process, or in the same application domain.

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

Информационные атрибуты можно использовать для предоставления дополнительных сведений о компании или продукте в сборке.You can use informational attributes to provide additional company or product information for an assembly. В следующей таблице показаны информационные атрибуты, определенные в пространстве имен System.Reflection.The following table shows the informational attributes defined in the System.Reflection namespace.

АтрибутAttribute ЦельPurpose
AssemblyProductAttribute Определяет настраиваемый атрибут, задающий имя продукта для манифеста сборки.Defines a custom attribute that specifies a product name for an assembly manifest.
AssemblyTrademarkAttribute Определяет настраиваемый атрибут, задающий товарный знак для манифеста сборки.Defines a custom attribute that specifies a trademark for an assembly manifest.
AssemblyInformationalVersionAttribute Определяет настраиваемый атрибут, задающий информационную версию для манифеста сборки.Defines a custom attribute that specifies an informational version for an assembly manifest.
AssemblyCompanyAttribute Определяет настраиваемый атрибут, задающий название организации для манифеста сборки.Defines a custom attribute that specifies a company name for an assembly manifest.
AssemblyCopyrightAttribute Определяет настраиваемый атрибут, задающий уведомление об авторских правах для манифеста сборки.Defines a custom attribute that specifies a copyright for an assembly manifest.
AssemblyFileVersionAttribute Дает компилятору указание использовать определенный номер версии для ресурса версии файла Win32.Instructs the compiler to use a specific version number for the Win32 file version resource.
CLSCompliantAttribute Указывает, соответствует ли сборка спецификации CLS.Indicates whether the assembly is compliant with the Common Language Specification (CLS).

Атрибуты манифеста сборкиAssembly Manifest Attributes

Атрибуты манифеста сборки можно использовать для предоставления сведений в манифесте сборки.You can use assembly manifest attributes to provide information in the assembly manifest. К ним относится заголовок, описание, псевдоним по умолчанию и конфигурация.This includes title, description, default alias, and configuration. В следующей таблице показаны атрибуты манифеста сборки, определенные в пространстве имен System.Reflection.The following table shows the assembly manifest attributes defined in the System.Reflection namespace.

АтрибутAttribute ЦельPurpose
AssemblyTitleAttribute Определяет настраиваемый атрибут, задающий название сборки для манифеста сборки.Defines a custom attribute that specifies an assembly title for an assembly manifest.
AssemblyDescriptionAttribute Определяет настраиваемый атрибут, задающий описание сборки для манифеста сборки.Defines a custom attribute that specifies an assembly description for an assembly manifest.
AssemblyConfigurationAttribute Определяет настраиваемый атрибут, задающий конфигурацию сборки для манифеста сборки.Defines a custom attribute that specifies an assembly configuration (such as retail or debug) for an assembly manifest.
AssemblyDefaultAliasAttribute Определяет понятный псевдоним по умолчанию для манифеста сборки.Defines a friendly default alias for an assembly manifest

Атрибут ObsoleteObsolete Attribute

Атрибут Obsolete помечает сущность программы как нерекомендуемую для использования.The Obsolete attribute marks a program entity as one that is no longer recommended for use. Каждый случай использования сущности, помеченной как устаревшая, будет приводить к созданию предупреждения или сообщения об ошибке в зависимости от настройки атрибута.Each use of an entity marked obsolete will subsequently generate a warning or an error, depending on how the attribute is configured. Например:For example:

[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.In this example the Obsolete attribute is applied to class A and to method B.OldMethod. Поскольку для второго аргумента конструктора атрибутов, примененного к B.OldMethod, задано значение true, этот метод будет вызывать ошибку компилятора, тогда как при использовании класса A будет просто создаваться предупреждение.Because the second argument of the attribute constructor applied to B.OldMethod is set to true, this method will cause a compiler error, whereas using class A will just produce a warning. При этом вызов B.NewMethod не создает предупреждений или ошибок.Calling B.NewMethod, however, produces no warning or error.

Строка, предоставленная в качестве первого аргумента конструктору атрибута, будет отображаться как часть предупреждения или ошибки.The string provided as the first argument to attribute constructor will be displayed as part of the warning or error. Например, при использовании с предыдущими определениями следующий код создает два предупреждения и одну ошибку:For example, when you use it with the previous definitions, the following code generates two warnings and one error:

// 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: одно для объявления ссылки на класс, а второе — для конструктора класса.Two warnings for class A are generated: one for the declaration of the class reference, and one for the class constructor.

Атрибут Obsolete может использоваться без аргументов, однако рекомендуется включать пояснение о том, почему соответствующий элемент является устаревшим и что следует использовать вместо него.The Obsolete attribute can be used without arguments, but including an explanation of why the item is obsolete and what to use instead is recommended.

Атрибут Obsolete является атрибутом однократного использования и может применяться к любой сущности, допускающей использование атрибутов.The Obsolete attribute is a single-use attribute and can be applied to any entity that allows attributes. Obsolete является псевдонимом для ObsoleteAttribute.Obsolete is an alias for ObsoleteAttribute.

Атрибут ConditionalConditional Attribute

Атрибут Conditional определяет зависимость выполнения метода от идентификатора предварительной обработки.The Conditional attribute makes the execution of a method dependent on a preprocessing identifier. Атрибут Conditional является псевдонимом для ConditionalAttribute и может применяться к методу или классу атрибута.The Conditional attribute is an alias for ConditionalAttribute, and can be applied to a method or an attribute class.

В этом примере атрибут Conditional применяется к методу для включения и отключения отображения диагностической информации для конкретной программы:In this example, Conditional is applied to a method to enable or disable the display of program-specific diagnostic information:

#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 не определен, выходные данные трассировки не отображаются.If the TRACE_ON identifier is not defined, no trace output will be displayed.

Атрибут Conditional часто используется с идентификатором DEBUG для включения функций трассировки и ведения журнала для отладочных сборок (но не сборок выпуска) следующим образом:The Conditional attribute is often used with the DEBUG identifier to enable trace and logging features for debug builds but not in release builds, like this:

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

Когда вызывается метод, помеченный как условный, наличие или отсутствие заданного символа предварительной обработки определяет, включается ли вызов или пропускается.When a method marked as conditional is called, the presence or absence of the specified preprocessing symbol determines whether the call is included or omitted. Если этот символ определен, вызов включается; в противном случае вызов пропускается.If the symbol is defined, the call is included; otherwise, the call is omitted. Использование атрибута Conditional — это более понятная, элегантная и менее подверженная ошибкам альтернатива вложению методов в блоки #if…#endif, например следующим образом:Using Conditional is a cleaner, more elegant, and less error-prone alternative to enclosing methods inside #if…#endif blocks, like this:

#if DEBUG  
    void ConditionalMethod()  
    {  
    }  
#endif  

Условный метод должен быть методом в объявлении класса или структуры и не должен возвращать значение.A conditional method must be a method in a class or struct declaration and must not have a return value.

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

Если метод содержит несколько атрибутов Conditional, вызов метода включается, если определен хотя бы один из условных символов (другими словами, символы логически связаны с помощью оператора ИЛИ).If a method has multiple Conditional attributes, a call to the method is included if at least one of the conditional symbols is defined (in other words, the symbols are logically linked together by using the OR operator). В этом примере наличие A или B приведет к вызову метода:In this example, the presence of either A or B will result in a method call:

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

Для получения эффекта логического связывания символов с помощью оператора И можно определить последовательные условные методы.To achieve the effect of logically linking symbols by using the AND operator, you can define serial conditional methods. Например, второй метод ниже будет выполняться, только если определены A и B:For example, the second method below will execute only if both A and B are defined:

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

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

Атрибут Conditional также может применяться к определению класса атрибута.The Conditional attribute can also be applied to an attribute class definition. В этом примере настраиваемый атрибут Documentation добавит сведения в метаданные, только если задано значение DEBUG.In this example, the custom attribute Documentation will only add information to the metadata if DEBUG is defined.

[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());  
    }  
}  

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

С помощью информационных атрибутов вызывающего объекта можно получить сведения о вызывающем объекте метода.By using Caller Info attributes, you can obtain information about the caller to a method. Можно получить путь к файлу исходного кода, номер строки в исходном коде и имя вызывающего объекта.You can obtain the file path of the source code, the line number in the source code, and the member name of the caller.

Для получения этих сведений используются атрибуты, которые применяются к необязательным параметрам.To obtain member caller information, you use attributes that are applied to optional parameters. Каждый необязательный параметр задает значение по умолчанию.Each optional parameter specifies a default value. В следующей таблице перечислены информационные атрибуты вызывающего объекта, которые определены в пространстве имен System.Runtime.CompilerServices:The following table lists the Caller Info attributes that are defined in the System.Runtime.CompilerServices namespace:

АтрибутAttribute ОПИСАНИЕDescription ТипType
CallerFilePathAttribute Полный путь исходного файла, содержащего вызывающий объект.Full path of the source file that contains the caller. Это путь во время компиляции.This is the path at compile time. String
CallerLineNumberAttribute Номер строки в исходном файле, из которого вызывается метод.Line number in the source file from which the method is called. Integer
CallerMemberNameAttribute Имя свойства или метода вызывающего объекта.Method name or property name of the caller. Дополнительные сведения см. в разделе Сведения о вызывающем объекте (C#).For more information, see Caller Information (C#). String

Дополнительные сведения об информационных атрибутах вызывающего объекта см. в разделе Сведения о вызывающем объекте (C#).For more information about the Caller Info attributes, see Caller Information (C#).

См. такжеSee also