Windows API sets

All versions of Windows 10 share a common base of OS components that is called the core OS (in some contexts this common base is also called OneCore). In core OS components, Win32 APIs are organized into functional groups called API sets.

The purpose of an API set is to provide an architectural separation from the host DLL in which a given Win32 API is implemented and the functional contract to which the API belongs. The decoupling that API sets provide between implementation and contracts offers many engineering advantages for developers. In particular, using API sets in your code can improve compatibility with all Windows 10 devices.

API sets specifically address the following scenarios:

Although the full breadth of the Win32 API is supported on PCs, only a subset of the Win32 API is available on other Windows 10 devices such as HoloLens, Xbox, and other devices running Windows 10x. The API set name provides a query mechanism to cleanly detect whether an API is available on any given device.

Some Win32 API implementations exist in DLLs with different names across different Windows 10 devices. Using API set names instead of DLL names when detecting API availability and delay loading APIs provide a correct route to the implementation no matter where the API is actually implemented.

Linking to umbrella libraries

To make it easier to restrict your code to Win32 APIs that are supported in the core OS, we provide a series of umbrella libraries. For example, an umbrella library named OneCore.lib provides the exports for the subset of Win32 APIs that are common to all Windows 10 devices.

The APIs in an umbrella library may be implemented across a range of modules. The umbrella library abstracts those details away from you, making your code more portable across Windows 10 versions and devices. Instead of linking to libraries such as kernel32.lib and advapi32.lib, simply link your desktop app or driver with the umbrella library that contains the set of core OS APIs that you’re interested in.

API set contract names

API sets are identified by a strong contract name that follows these standard conventions recognized by the library loader.

• The name must begin either with the string api- or ext-.
  • Names that begin with api- represent APIs that are guaranteed to exist on all Windows 10 versions.
  • Names that begin with ext- represent APIs that may not exist on all Windows 10 versions.
• The name must end with the sequence l — — , where n consists of decimal digits.
• The body of the name can be alphanumeric characters, or dashes (—).
• The name is case insensitive.

Here are some examples of API set contract names:

• api-ms-win-core-ums-l1-1-0
• ext-ms-win-com-ole32-l1-1-5
• ext-ms-win-ntuser-window-l1-1-0
• ext-ms-win-ntuser-window-l1-1-1

You can use an API set name in the context of a loader operation such as LoadLibrary or P/Invoke instead of a DLL module name to ensure a correct route to the implementation no matter where the API is actually implemented on the current device. However, when you do this you must append the string .dll at the end of the contract name. This is a requirement of the loader to function properly, and is not considered actually a part of the contract name. Although contract names appear similar to DLL names in this context, they are fundamentally different from DLL module names and do not directly refer to a file on disk.

Except for appending the string .dll in loader operations, API set contract names should be considered an immutable identifier that corresponds to a specific contract version.

Identifying API sets for Win32 APIs

To identify whether a particular Win32 API belongs to an API set, review the requirements table in the reference documentation for the API. If the API belongs to an API set, the requirements table in the article lists the API set name and the Windows version in which the API was first introduced to the API set. For examples of APIs that belong to an API set, see these articles:

Пошаговое руководство. Вызов API Windows (Visual Basic) Walkthrough: Calling Windows APIs (Visual Basic)

Windows API — это библиотеки динамической компоновки (DLL), которые являются частью операционной системы Windows. Windows APIs are dynamic-link libraries (DLLs) that are part of the Windows operating system. Они используются для выполнения задач, когда трудно писать эквивалентные процедуры. You use them to perform tasks when it is difficult to write equivalent procedures of your own. Например, Windows предоставляет функцию с именем FlashWindowEx , которая позволяет сделать строку заголовка для приложения альтернативой светлой и темной тени. For example, Windows provides a function named FlashWindowEx that lets you make the title bar for an application alternate between light and dark shades.

Преимущество использования API-интерфейсов Windows в коде состоит в том, что они могут сэкономить время разработки, поскольку они содержат десятки полезных функций, которые уже написаны и ожидают использования. The advantage of using Windows APIs in your code is that they can save development time because they contain dozens of useful functions that are already written and waiting to be used. Недостаток заключается в том, что API Windows может быть трудно работать с и унфоргивинг в случае неправильной работы. The disadvantage is that Windows APIs can be difficult to work with and unforgiving when things go wrong.

Интерфейсы API Windows представляют особую категорию взаимодействия. Windows APIs represent a special category of interoperability. Интерфейсы API Windows не используют управляемый код, не имеют встроенных библиотек типов и используют типы данных, отличные от используемых в Visual Studio. Windows APIs do not use managed code, do not have built-in type libraries, and use data types that are different than those used with Visual Studio. Из-за этих различий и, поскольку интерфейсы API Windows не являются объектами COM, взаимодействия с API Windows и платформа .NET Framework выполняются с помощью вызова неуправляемого кода или PInvoke. Because of these differences, and because Windows APIs are not COM objects, interoperability with Windows APIs and the .NET Framework is performed using platform invoke, or PInvoke. Платформенный вызов — это служба, которая позволяет управляемому коду вызывать неуправляемые функции, реализованные в библиотеках DLL. Platform invoke is a service that enables managed code to call unmanaged functions implemented in DLLs. Дополнительные сведения см. в разделе Использование неуправляемых функций DLL. For more information, see Consuming Unmanaged DLL Functions. Вы можете использовать PInvoke в Visual Basic, используя либо Declare инструкцию, либо применяя DllImport атрибут к пустой процедуре. You can use PInvoke in Visual Basic by using either the Declare statement or applying the DllImport attribute to an empty procedure.

Вызовы Windows API были важной частью Visual Basic программирования в прошлом, но они редко требуются для Visual Basic .NET. Windows API calls were an important part of Visual Basic programming in the past, but are seldom necessary with Visual Basic .NET. Везде, где это возможно, следует использовать управляемый код из платформа .NET Framework для выполнения задач, а не вызовов Windows API. Whenever possible, you should use managed code from the .NET Framework to perform tasks, instead of Windows API calls. В этом пошаговом руководстве содержатся сведения о ситуациях, в которых требуется использовать API Windows. This walkthrough provides information for those situations in which using Windows APIs is necessary.

Отображаемые на компьютере имена или расположения некоторых элементов пользовательского интерфейса Visual Studio могут отличаться от указанных в следующих инструкциях. Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. Это зависит от имеющегося выпуска Visual Studio и используемых параметров. The Visual Studio edition that you have and the settings that you use determine these elements. Дополнительные сведения см. в разделе Персонализация среды IDE. For more information, see Personalizing the IDE.

Вызовы API с помощью Declare API Calls Using Declare

Наиболее распространенным способом вызова API Windows является использование Declare инструкции. The most common way to call Windows APIs is by using the Declare statement.

Объявление процедуры DLL To declare a DLL procedure

Определите имя функции, которую необходимо вызвать, а также ее аргументы, типы аргументов и возвращаемое значение, а также имя и расположение библиотеки DLL, содержащей ее. Determine the name of the function you want to call, plus its arguments, argument types, and return value, as well as the name and location of the DLL that contains it.

Полные сведения о API Windows см. в документации по пакету SDK для Win32 в Windows API Platform SDK. For complete information about the Windows APIs, see the Win32 SDK documentation in the Platform SDK Windows API. Дополнительные сведения о константах, используемых API Windows, см. в файлах заголовков, таких как Windows. h, входящих в состав пакета Platform SDK. For more information about the constants that Windows APIs use, examine the header files such as Windows.h included with the Platform SDK.

Откройте новый проект приложения Windows, щелкнув создать в меню файл , а затем выбрав пункт проект. Open a new Windows Application project by clicking New on the File menu, and then clicking Project. Откроется диалоговое окно Новый проект . The New Project dialog box appears.

Выберите приложение Windows в списке шаблонов проектов Visual Basic. Select Windows Application from the list of Visual Basic project templates. Отобразится новый проект. The new project is displayed.

Добавьте следующую Declare функцию либо в класс, либо в модуль, в котором требуется использовать библиотеку DLL: Add the following Declare function either to the class or module in which you want to use the DLL:

Части инструкции DECLARE Parts of the Declare Statement

Declare Инструкция включает следующие элементы. The Declare statement includes the following elements.

Модификатор Auto Auto modifier

Auto Модификатор указывает среде выполнения преобразовать строку на основе имени метода в соответствии с правилами среды CLR (или именем псевдонима, если оно указано). The Auto modifier instructs the runtime to convert the string based on the method name according to common language runtime rules (or alias name if specified).

Ключевые слова lib и Alias Lib and Alias keywords

Имя, следующее за Function ключевым словом, — это имя, которое программа использует для доступа к импортируемой функции. The name following the Function keyword is the name your program uses to access the imported function. Оно может совпадать с реальным именем вызываемой функции, или можно использовать любое допустимое имя процедуры, а затем применить Alias ключевое слово, чтобы указать реальное имя вызываемой функции. It can be the same as the real name of the function you are calling, or you can use any valid procedure name and then employ the Alias keyword to specify the real name of the function you are calling.

Укажите Lib ключевое слово, а затем имя и расположение библиотеки DLL, содержащей вызываемую функцию. Specify the Lib keyword, followed by the name and location of the DLL that contains the function you are calling. Указывать путь к файлам, расположенным в системных каталогах Windows, не требуется. You do not need to specify the path for files located in the Windows system directories.

Используйте Alias ключевое слово, если имя вызываемой функции не является допустимым Visual Basic именем процедуры или конфликтует с именами других элементов в приложении. Use the Alias keyword if the name of the function you are calling is not a valid Visual Basic procedure name, or conflicts with the name of other items in your application. Alias Указывает на истинное имя вызываемой функции. Alias indicates the true name of the function being called.

Объявления аргументов и типов данных Argument and Data Type Declarations

Объявите аргументы и их типы данных. Declare the arguments and their data types. Эта часть может быть сложной, поскольку типы данных, используемые Windows, не соответствуют типам данных Visual Studio. This part can be challenging because the data types that Windows uses do not correspond to Visual Studio data types. Visual Basic выполняет большой объем работы, преобразуя аргументы в совместимые типы данных, процесс, называемый упаковкой. Visual Basic does a lot of the work for you by converting arguments to compatible data types, a process called marshaling. Можно явно управлять упаковкой аргументов с помощью MarshalAsAttribute атрибута, определенного в System.Runtime.InteropServices пространстве имен. You can explicitly control how arguments are marshaled by using the MarshalAsAttribute attribute defined in the System.Runtime.InteropServices namespace.

Предыдущие версии Visual Basic позволяли объявлять параметры As Any , то есть могут использоваться данные любого типа данных. Previous versions of Visual Basic allowed you to declare parameters As Any , meaning that data of any data type could be used. Visual Basic требует, чтобы для всех инструкций использовался конкретный тип данных Declare . Visual Basic requires that you use a specific data type for all Declare statements.

Константы Windows API Windows API Constants

Некоторые аргументы являются сочетаниями констант. Some arguments are combinations of constants. Например, API, MessageBox показанный в этом пошаговом руководстве, принимает целочисленный аргумент Typ с именем, который управляет отображением окна сообщения. For example, the MessageBox API shown in this walkthrough accepts an integer argument called Typ that controls how the message box is displayed. Можно определить числовое значение этих констант, изучив #define инструкции в файле WinUser. h. You can determine the numeric value of these constants by examining the #define statements in the file WinUser.h. Числовые значения обычно отображаются в шестнадцатеричном виде, поэтому для их добавления и преобразования в десятичный формат может потребоваться калькулятор. The numeric values are generally shown in hexadecimal, so you may want to use a calculator to add them and convert to decimal. Например, если вы хотите объединить константы для стиля с восклицательным знаком MB_ICONEXCLAMATION 0x00000030, а стиль «да/нет MB_YESNO », можно добавить числа и получить результат 0x00000034 или 52 Decimal. For example, if you want to combine the constants for the exclamation style MB_ICONEXCLAMATION 0x00000030 and the Yes/No style MB_YESNO 0x00000004, you can add the numbers and get a result of 0x00000034, or 52 decimal. Хотя вы можете использовать десятичный результат непосредственно, лучше объявить эти значения как константы в приложении и объединить их с помощью Or оператора. Although you can use the decimal result directly, it is better to declare these values as constants in your application and combine them using the Or operator.

Объявление констант для вызовов API Windows To declare constants for Windows API calls

Обратитесь к документации по функции Windows, которую вы вызываете. Consult the documentation for the Windows function you are calling. Определите имена констант, которые он использует, и имя h файла, содержащего числовые значения для этих констант. Determine the name of the constants it uses and the name of the .h file that contains the numeric values for these constants.

Используйте текстовый редактор, например Блокнот, для просмотра содержимого файла заголовка (. h) и поиска значений, связанных с используемыми константами. Use a text editor, such as Notepad, to view the contents of the header (.h) file, and find the values associated with the constants you are using. Например, MessageBox API использует константу MB_ICONQUESTION для отображения вопросительного знака в окне сообщения. For example, the MessageBox API uses the constant MB_ICONQUESTION to show a question mark in the message box. Определение для MB_ICONQUESTION находится в файле WinUser. h и выглядит следующим образом: The definition for MB_ICONQUESTION is in WinUser.h and appears as follows:

#define MB_ICONQUESTION 0x00000020L

Добавьте эквивалентные Const операторы в класс или модуль, чтобы сделать эти константы доступными для приложения. Add equivalent Const statements to your class or module to make these constants available to your application. Пример: For example:

Вызов процедуры DLL To call the DLL procedure

Добавьте кнопку с именем Button1 в форму запуска проекта, а затем дважды щелкните ее, чтобы просмотреть код. Add a button named Button1 to the startup form for your project, and then double-click it to view its code. Появится обработчик событий для кнопки. The event handler for the button is displayed.

Добавьте код в Click обработчик событий для добавленной кнопки, чтобы вызвать процедуру и предоставить соответствующие аргументы: Add code to the Click event handler for the button you added, to call the procedure and provide the appropriate arguments:

Запустите проект, нажав клавишу F5. Run the project by pressing F5. Появится окно сообщения с кнопками Да и нет . The message box is displayed with both Yes and No response buttons. Щелкните один из них. Click either one.

Маршалирование данных Data Marshaling

Visual Basic автоматически преобразует типы данных параметров и возвращаемые значения для вызовов API Windows, но можно использовать MarshalAs атрибут, чтобы явно указать неуправляемые типы данных, которые ОЖИДАЕТ API. Visual Basic automatically converts the data types of parameters and return values for Windows API calls, but you can use the MarshalAs attribute to explicitly specify unmanaged data types that an API expects. Дополнительные сведения о маршалинге взаимодействия см. в разделе Маршалинг взаимодействия. For more information about interop marshaling, see Interop Marshaling.

Использование Declare и MarshalAs в вызове API To use Declare and MarshalAs in an API call

Определите имя функции, которую необходимо вызвать, а также ее аргументы, типы данных и возвращаемое значение. Determine the name of the function you want to call, plus its arguments, data types, and return value.

Чтобы упростить доступ к MarshalAs атрибуту, добавьте Imports оператор в начало кода для класса или модуля, как показано в следующем примере: To simplify access to the MarshalAs attribute, add an Imports statement to the top of the code for the class or module, as in the following example:

Добавьте прототип функции для импортированной функции в класс или модуль, который вы используете, и примените MarshalAs атрибут к параметрам или возвращаемому значению. Add a function prototype for the imported function to the class or module you are using, and apply the MarshalAs attribute to the parameters or return value. В следующем примере вызов API, который принимает тип, void* маршалируется как AsAny : In the following example, an API call that expects the type void* is marshaled as AsAny :

Вызовы API с помощью DllImport API Calls Using DllImport

DllImport Атрибут предоставляет второй способ вызова функций в библиотеках DLL без библиотек типов. The DllImport attribute provides a second way to call functions in DLLs without type libraries. DllImport примерно эквивалентно использованию оператора, Declare но обеспечивает более полный контроль над вызовом функций. DllImport is roughly equivalent to using a Declare statement but provides more control over how functions are called.

DllImport С большинством вызовов API Windows можно использовать, если вызов ссылается на общий (иногда называемый статическим) метод. You can use DllImport with most Windows API calls as long as the call refers to a shared (sometimes called static) method. Нельзя использовать методы, для которых требуется экземпляр класса. You cannot use methods that require an instance of a class. В отличие от Declare инструкций DllImport вызовы не могут использовать MarshalAs атрибут. Unlike Declare statements, DllImport calls cannot use the MarshalAs attribute.

Вызов API Windows с помощью атрибута DllImport To call a Windows API using the DllImport attribute

Откройте новый проект приложения Windows, щелкнув создать в меню файл , а затем выбрав пункт проект. Open a new Windows Application project by clicking New on the File menu, and then clicking Project. Откроется диалоговое окно Новый проект . The New Project dialog box appears.

Выберите приложение Windows в списке шаблонов проектов Visual Basic. Select Windows Application from the list of Visual Basic project templates. Отобразится новый проект. The new project is displayed.

Добавьте кнопку с именем Button2 в форму запуска. Add a button named Button2 to the startup form.

Дважды щелкните, Button2 чтобы открыть представление кода для формы. Double-click Button2 to open the code view for the form.

Чтобы упростить доступ к DllImport , добавьте Imports оператор в начало кода для класса формы Startup: To simplify access to DllImport , add an Imports statement to the top of the code for the startup form class:

Объявите пустую функцию перед End Class оператором для формы и назовите функцию MoveFile . Declare an empty function preceding the End Class statement for the form, and name the function MoveFile .

Примените Public Shared модификаторы и к объявлению функции и задайте параметры в MoveFile зависимости от аргументов, используемых функцией Windows API: Apply the Public and Shared modifiers to the function declaration and set parameters for MoveFile based on the arguments the Windows API function uses:

Функция может иметь любое допустимое имя процедуры; DllImport атрибут указывает имя в библиотеке DLL. Your function can have any valid procedure name; the DllImport attribute specifies the name in the DLL. Он также обрабатывает упаковку взаимодействия для параметров и возвращаемых значений, поэтому можно выбирать типы данных Visual Studio, аналогичные типам данных, используемым API. It also handles interoperability marshaling for the parameters and return values, so you can choose Visual Studio data types that are similar to the data types the API uses.

Примените DllImport атрибут к пустой функции. Apply the DllImport attribute to the empty function. Первый параметр — это имя и расположение библиотеки DLL, содержащей вызываемую функцию. The first parameter is the name and location of the DLL containing the function you are calling. Указывать путь к файлам, расположенным в системных каталогах Windows, не требуется. You do not need to specify the path for files located in the Windows system directories. Второй параметр — это именованный аргумент, указывающий имя функции в API Windows. The second parameter is a named argument that specifies the name of the function in the Windows API. В этом примере DllImport атрибут принудительно MoveFile перенаправляет вызовы в MoveFileW в KERNEL32.DLL. In this example, the DllImport attribute forces calls to MoveFile to be forwarded to MoveFileW in KERNEL32.DLL. MoveFileW Метод копирует файл из пути src в путь dst . The MoveFileW method copies a file from the path src to the path dst .

Добавьте код в Button2_Click обработчик событий для вызова функции: Add code to the Button2_Click event handler to call the function:

Создайте файл с именем Test.txt и поместите его в каталог К:\тмп на жестком диске. Create a file named Test.txt and place it in the C:\Tmp directory on your hard drive. При необходимости создайте каталог tmp. Create the Tmp directory if necessary.

Нажмите клавишу F5 для запуска приложения. Press F5 to start the application. Откроется Главная форма. The main form appears.

Нажмите кнопку Button2. Click Button2. Если файл можно переместить, отображается сообщение «файл перемещен успешно». The message «The file was moved successfully» is displayed if the file can be moved.