Атрибуты C++ для модели COM и .NETC++ Attributes for COM and .NET

Корпорация Майкрософт определяет набор атрибутов C++, упрощающих программирование COM и .NET Framework разработку среды CLR.Microsoft defines a set of C++ attributes that simplify COM programming and .NET Framework common language runtime development. При включении атрибутов в исходные файлы компилятор работает с библиотеками DLL поставщика для вставки кода или изменения кода в созданных объектных файлах.When you include attributes in your source files, the compiler works with provider DLLs to insert code or modify the code in the generated object files. Эти атрибуты помогают в создании IDL-файлов, интерфейсов, библиотек типов и других элементов COM.These attributes aid in the creation of .idl files, interfaces, type libraries, and other COM elements. В интегрированной среде разработки (IDE) атрибуты поддерживаются мастерами и окно свойств.In the integrated development environment (IDE), attributes are supported by the wizards and by the Properties window.

Хотя атрибуты исключают некоторые из подробного кода, необходимого для написания COM-объектов, для оптимального использования в основных понятиях com требуется фон.While attributes eliminate some of the detailed coding needed to write COM objects, you need a background in COM fundamentals to best use them.

Примечание

Если вы ищете стандартные атрибуты C++, см. раздел атрибуты.If you are looking for C++ standard attributes, see Attributes.

Назначение атрибутовPurpose of Attributes

Атрибуты расширяют C++ в направлениях в невозможности без нарушения классической структуры языка.Attributes extend C++ in directions not currently possible without breaking the classic structure of the language. Атрибуты позволяют поставщикам (разделять библиотеки DLL) динамически расширять функциональность языка.Attributes allow providers (separate DLLs) to extend language functionality dynamically. Основной целью атрибутов является упрощение разработки компонентов COM, а также повышение уровня производительности разработчика компонентов.The primary goal of attributes is to simplify the authoring of COM components, in addition to increasing the productivity level of the component developer. Атрибуты можно применять практически к любой конструкции C++, например к классам, элементам данных или функциям элементов.Attributes can be applied to nearly any C++ construct, such as classes, data members, or member functions. Ниже приведено выделение преимуществ, предоставляемых этой новой технологией:The following is a highlight of benefits provided by this new technology:

  • Предоставляет привычное и простое соглашение о вызовах.Exposes a familiar and simple calling convention.

  • Использует вставленный код, который, в отличие от макросов, распознается отладчиком.Uses inserted code, which, unlike macros, is recognized by the debugger.

  • Позволяет легко создавать производные от базовых классов без подробной реализации утомительным.Allows easy derivation from base classes without burdensome implementation details.

  • Заменяет большой объем кода IDL, требуемый компонентом COM, на несколько кратких атрибутов.Replaces the large amount of IDL code required by a COM component with a few concise attributes.

Например, чтобы реализовать простой приемник событий для универсального класса ATL, можно применить атрибут event_receiver к конкретному классу, например CMyReceiver .For example, to implement a simple event sink for a generic ATL class, you could apply the event_receiver attribute to a specific class such as CMyReceiver. event_receiverЗатем атрибут компилируется компилятором Microsoft C++, который вставляет правильный код в объектный файл.The event_receiver attribute is then compiled by the Microsoft C++ compiler, which inserts the proper code into the object file.

[event_receiver(com)]
class CMyReceiver
{
   void handler1(int i) { ... }
   void handler2(int i, float j) { ... }
}

Затем можно настроить CMyReceiver методы handler1 и handler2 для управления событиями (с помощью встроенной функции __hook) из источника событий, который можно создать с помощью event_source.You can then set up the CMyReceiver methods handler1 and handler2 to handle events (using the intrinsic function __hook) from an event source, which you can create using event_source.

Основные принципы работы атрибутовBasic Mechanics of Attributes

Существует три способа вставки атрибутов в проект.There are three ways to insert attributes into your project. Сначала их можно вставить вручную в исходный код.First, you can insert them manually into your source code. Во вторых, их можно вставить с помощью сетки свойств объекта в проекте.Second, you can insert them using the property grid of an object in your project. Наконец, их можно вставить с помощью различных мастеров.Finally, you can insert them using the various wizards. Дополнительные сведения об использовании окна Свойства и различных мастеров см. в разделе проекты Visual Studio — C++.For more information on using the Properties window and the various wizards, see Visual Studio Projects - C++.

Как и ранее, при построении проекта компилятор анализирует каждый исходный файл C++, создавая объектный файл.As before, when the project is built, the compiler parses each C++ source file, producing an object file. Однако если компилятор встречает атрибут, он анализируется и синтаксически проверен.However, when the compiler encounters an attribute, it is parsed and syntactically verified. Затем компилятор динамически вызывает поставщик атрибута для вставки кода или внесения других изменений во время компиляции.The compiler then dynamically calls an attribute provider to insert code or make other modifications at compile time. Реализация поставщика зависит от типа атрибута.The implementation of the provider differs depending on the type of attribute. Например, атрибуты, связанные с ATL, реализуются с помощью Atlprov.dll.For example, ATL-related attributes are implemented by Atlprov.dll.

На следующем рисунке показана связь между компилятором и поставщиком атрибута.The following figure demonstrates the relationship between the compiler and the attribute provider.

Взаимодействие атрибутов компонентовComponent attribute communication

Примечание

Использование атрибута не изменяет содержимое исходного файла.Attribute usage does not alter the contents of the source file. Код созданного атрибута отображается только во время сеансов отладки.The only time the generated attribute code is visible is during debugging sessions. Кроме того, для каждого исходного файла в проекте можно создать текстовый файл, отображающий результаты подстановки атрибута.In addition, for each source file in the project, you can generate a text file that displays the results of the attribute substitution. Дополнительные сведения об этой процедуре см. в разделе /FX (объединение подставляемого кода) и Отладка внедренного кода.For more information on this procedure, see /Fx (Merge Injected Code) and Debugging Injected Code.

Как и большинство конструкций C++, атрибуты имеют набор характеристик, определяющих их правильное использование.Like most C++ constructs, attributes have a set of characteristics that defines their proper usage. Это называется контекстом атрибута и разрешается в таблице контекста атрибутов для каждого раздела справки по атрибутам.This is referred to as the context of the attribute and is addressed in the attribute context table for each attribute reference topic. Например, атрибут coclass может применяться только к существующему классу или структуре, а не к атрибуту cpp_quote , который можно вставить в любом месте исходного файла C++.For example, the coclass attribute can only be applied to an existing class or structure, as opposed to the cpp_quote attribute, which can be inserted anywhere within a C++ source file.

Сборка атрибутированной программыBuilding an Attributed Program

После помещения Visual C++ атрибутов в исходный код, возможно, потребуется компилятору Microsoft C++ создать библиотеку типов и IDL-файл.After you put Visual C++ attributes into your source code, you may want the Microsoft C++ compiler to produce a type library and .idl file for you. Следующие параметры компоновщика помогают создавать файлы TLB и IDL:The following linker options help you build .tlb and .idl files:

Некоторые проекты содержат несколько независимых IDL-файлов.Some projects contain multiple independent .idl files. Они используются для создания двух или более TLB файлов и при необходимости привязывают их к блоку ресурсов.These are used to produce two or more .tlb files and optionally bind them into the resource block. В настоящее время этот сценарий не поддерживается в Visual C++.This scenario is not currently supported in Visual C++.

Кроме того, компоновщик Visual C++ выводит все сведения об атрибутах, связанных с IDL, в один файл MIDL.In addition, the Visual C++ linker will output all IDL-related attribute information to a single MIDL file. Создавать две библиотеки типов из одного проекта будет невозможно.There will be no way to generate two type libraries from a single project.

Контексты атрибутовAttribute Contexts

Атрибуты C++ можно описать с помощью четырех основных полей: целевой объект, к которому они могут применяться (применяется к), если они являются повторяемыми или нет (повторяемые), необходимое присутствие других атрибутов (обязательных атрибутов) и несовместимость с другими атрибутами (недопустимые атрибуты).C++ attributes can be described using four basic fields: the target they can be applied to (Applies To), if they are repeatable or not (Repeatable), the required presence of other attributes (Required Attributes), and incompatibilities with other attributes (Invalid Attributes). Эти поля перечислены в сопроводительной таблице в справочном разделе каждого атрибута.These fields are listed in an accompanying table in each attribute's reference topic. Каждое из этих полей описано ниже.Each of these fields is described below.

ПрименениеApplies To

В этом поле описаны различные элементы языка C++, которые являются допустимыми целевыми объектами для указанного атрибута.This field describes the different C++ language elements that are legal targets for the specified attribute. Например, если атрибут указывает "class" в поле " применяется к ", это означает, что атрибут может применяться только к юридическим классам C++.For instance, if an attribute specifies "class" in the Applies To field, this indicates that the attribute can only be applied to a legal C++ class. Если атрибут применяется к функции-члену класса, возникнет синтаксическая ошибка.If the attribute is applied to a member function of a class, a syntax error would result.

Дополнительные сведения см. в разделе атрибуты по использованию.For more information, see Attributes by Usage.

ПовторяемыйRepeatable

В этом поле указывается, может ли атрибут быть многократно применен к тому же целевому объекту.This field states whether the attribute can be repeatedly applied to the same target. Большинство атрибутов не повторяется.The majority of attributes are not repeatable.

Обязательные атрибутыRequired Attributes

В этом поле перечислены другие атрибуты, которые должны присутствовать (то есть примененные к тому же целевому объекту) для правильной работы указанного атрибута.This field lists other attributes that need to be present (that is, applied to the same target) for the specified attribute to function properly. Нередко атрибут может иметь какие-либо записи для этого поля.It is uncommon for an attribute to have any entries for this field.

Недопустимые атрибутыInvalid Attributes

В этом поле перечислены другие атрибуты, несовместимые с указанным атрибутом.This field lists other attributes that are incompatible with the specified attribute. Нередко атрибут может иметь какие-либо записи для этого поля.It is uncommon for an attribute to have any entries for this field.

в этом разделеIn This Section

Вопросы и ответы по программированию атрибутовAttribute Programming FAQ
Атрибуты по группамAttributes by Group
Атрибуты по использованиюAttributes by Usage
Алфавитный справочник по атрибутамAttributes Alphabetical Reference