Windows-API-Sätze

  • Artikel

Wichtig

Die Informationen in diesem Thema gelten für alle Versionen von Windows 10 und höher. Wir werden diese Versionen hier als „Windows“ bezeichnen und bei Bedarf auf Ausnahmen hinweisen.

Alle Versionen von Windows verfügen über eine gemeinsame Basis von Betriebssystemkomponenten, die als Core OS bezeichnet wird (in manchen Kontexten wird diese gemeinsame Basis auch als OneCore). In den Core-Betriebssystemkomponenten sind die Win32-APIs in Funktionsgruppen organisiert, die API-Sets genannt werden.

Der Zweck eines API-Sets besteht darin, eine architektonische Trennung von der Host-DLL, in der eine bestimmte Win32-API implementiert ist, und dem Funktionsvertrag, zu dem die API gehört, zu gewährleisten. Die Entkopplung, die API-Sets zwischen Implementierung und Aufträgen bieten, bietet Entwicklern viele technische Vorteile. Vor allem die Verwendung von API-Sets in Ihrem Code kann die Kompatibilität mit Windows-Geräten verbessern.

API-Sets sind speziell auf die folgenden Szenarien ausgerichtet:

  • Obwohl die Win32-API auf PCs in vollem Umfang unterstützt wird, ist nur eine Teilmenge der Win32-API auf anderen Windows-Geräten wie HoloLens, Xbox und anderen Geräten verfügbar. Der Name des API-Sets bietet einen Abfragemechanismus, mit dem Sie eindeutig feststellen können, ob eine API auf einem bestimmten Gerät verfügbar ist.

  • Einige Win32-API-Implementierungen existieren in DLLs mit unterschiedlichen Namen für verschiedene Windows-Geräte. Die Verwendung von API-Set-Namen anstelle von DLL-Namen bei der Erkennung der API-Verfügbarkeit und das verzögerte Laden von APIs bieten eine korrekte Route zur Implementierung, unabhängig davon, wo die API tatsächlich implementiert ist.

Weitere Einzelheiten finden Sie unter API-Set-Ladevorgang und API-Set-Verfügbarkeit erkennen.

Sind API-Sets und Dlls das Gleiche?

Nein – ein API-Set-Name ist ein virtueller Alias für eine physische .dll Datei. Es handelt sich um eine Technik, die die Implementierung verbirgt, so dass Sie als Aufrufer nicht genau wissen müssen, in welchem Modul die Informationen gespeichert sind.

Diese Technik ermöglicht es, Module auf verschiedenen Windows-Versionen und -Editionen zu refaktorisieren (aufzuteilen, zu konsolidieren, umzubenennen usw.). Und Ihre Anwendungen sind immer noch verlinkt und werden zur Runtime immer noch an den richtigen Code weitergeleitet.

Und weshalb haben API-Sets .dll in Ihren Namen? Der Grund dafür ist die Art und Weise, wie der DLL-Loader implementiert ist. Der Loader ist der Teil des Betriebssystems, der DLLs lädt und/oder Verweise auf DLLs auflöst. Und am Frontend verlangt der Loader, dass jeder String, der an LoadLibrary übergeben wird, mit „.dll“ abgeschlossen wird. Aber nach diesem Frontend kann der Loader dieses Suffix entfernen und die API-Set-Datenbank mit der resultierenden Zeichenfolge abfragen.

LoadLibrary (und DelayLoad) ist erfolgreich mit einem API-Set-Namen (mit dem Zusatz „.dll“), aber es gibt nicht unbedingt eine tatsächliche Datei mit diesem Namen irgendwo auf dem PC.

Verknüpfung von Dachbibliotheken

Um es einfacher zu machen, Ihren Code auf die Win32-APIs zu beschränken, die im Core-Betriebssystem unterstützt werden, stellen wir eine Reihe von Dachbibliotheken zur Verfügung. Eine Dachbibliothek mit dem Namen OneCore.lib bietet beispielsweise die Exporte für die Teilmenge der Win32-APIs, die allen Windows-Geräten gemeinsam sind.

Weitere Einzelheiten finden Sie unter Windows-Dachbibliotheken.

API-Set Vertragsnamen

API-Sets werden durch einen aussagekräftigen Vertragsnamen identifiziert, der diesen vom Bibliotheks-Loader erkannten Standardkonventionen folgt.

  • Der Name muss entweder mit der Zeichenfolge api- oder ext- beginnen.
    • Namen, die mit api- beginnen, stehen für APIs, die in allen Windows-Editionen vorhanden sind, die die Versionsanforderungen der API erfüllen.
    • Namen, die mit ext- beginnen, stehen für APIs, die möglicherweise nicht in allen Windows-Editionen vorhanden sind.
  • Der Name muss mit der Sequenz l<n>-<n>-<n> enden, wobei n aus Dezimalziffern besteht.
  • Der Inhalt des Namens kann aus alphanumerischen Zeichen oder Bindestrichen (-) bestehen.
  • Für den Namen wird die Groß-/Kleinschreibung nicht beachtet.

Hier sind einige Beispiele für Namen von API-Set-Aufträgen:

  • 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

Sie können einen API-Set-Namen im Kontext einer Loader-Operation wie LoadLibrary oder P/Invoke anstelle eines DLL-Modulnamens verwenden, um eine korrekte Route zur Implementierung sicherzustellen, egal wo die API auf dem aktuellen Gerät tatsächlich implementiert ist. Wenn Sie dies tun, müssen Sie jedoch die Zeichenfolge .dll an das Ende des Vertragsnamens anhängen. Dies ist eine Anforderung an den Loader, um ordnungsgemäß zu funktionieren, und wird nicht als eigentlicher Bestandteil des Vertragsnamens betrachtet. Obwohl Vertragsnamen in diesem Zusammenhang ähnlich wie DLL-Namen erscheinen, unterscheiden sie sich grundlegend von DLL-Modulnamen und verweisen nicht direkt auf eine Datei auf der Festplatte.

Mit Ausnahme des Anhängens der Zeichenkette .dll in Loader-Operationen sollten API-Set-Vertragsnamen als unveränderliche Kennung betrachtet werden, die einer bestimmten Vertragsversion entspricht.

Identifizierung von API-Sets für Win32-APIs

Um festzustellen, ob eine bestimmte Win32-API zu einem API-Set gehört, sehen Sie sich die Anforderungstabelle in der Referenzdokumentation für die API an. Wenn die API zu einem API-Set gehört, listet die Anforderungstabelle im Artikel den Namen des API-Sets und die Windows-Version auf, in der die API erstmals in das API-Set aufgenommen wurde. Beispiele für APIs, die zu einem API-Set gehören, finden Sie in diesen Artikeln:

In diesem Abschnitt