Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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-Satzes besteht darin, eine Architekturtrennung zwischen der Host-DLL bereitzustellen, in der eine bestimmte Win32-API implementiert ist, und dem Funktionsvertrag, zu dem die API gehört. 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 gesamte Breite der Win32-API auf PCs unterstützt wird, ist nur eine Teilmenge der Win32-API auf anderen Windows Geräten wie HoloLens, XBOX und anderen Geräten verfügbar. Mit einem API-Satznamen erhalten Sie eine stabile Frage, damit Ihre App zur Laufzeit erkennen kann, ob eine Funktion auf dem aktuellen Gerät verfügbar ist. Die Abfrage selbst wird von der IsApiSetImplemented-Funktion ausgeführt.
Einige Win32-API-Implementierungen existieren in DLLs mit unterschiedlichen Namen für verschiedene Windows-Geräte. Die Verwendung von API-Satznamen anstelle von DLL-Namen beim Erkennen der API-Verfügbarkeit und verzögerung des Ladens von APIs bietet eine richtige 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-Sätze und DLLs dasselbe?
Nein – ein API-Satzname identifiziert einen Vertrag und keine Datei. Zur Laufzeit löst das Ladeprogramm diesen Vertrag über das API-Set-Schema auf dem aktuellen Gerät auf und leitet den Verweis auf die DLL weiter, die die Implementierung hostet. 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 Apps werden weiterhin verknüpft und zur Laufzeit weiterhin dem richtigen Code zugeordnet.
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 er erkennt anhand eines Modulnamens, der so geschrieben ist, wie Dateinamen in einer Importtabelle geschrieben werden, was geladen werden soll. API-Setnamen folgen derselben Konvention, sodass sie an den gleichen Ort passen.
Das Ladeprogramm erkennt einen Namen, der mit api- oder ext- beginnt, und leitet ihn an die API-Set-Runtime weiter, eine Erweiterung des Ladeprogramms, die Kontrakte über das Schema auflöst. Ab diesem Punkt wird der Name von API-Set-Benennungsregeln und nicht als Dateiname analysiert, sodass das .dll Suffix nicht Teil des Vertragsnamens ist, der aufgelöst wird.
Sie können den Namen eines API-Sets an LoadLibrary übergeben oder ihn als Ziel für verzögertes Laden verwenden. Der Vorgang ist erfolgreich, wenn das Schema auf dem aktuellen Gerät diesen Vertrag einem verwendbaren Host zuordnet; es gibt nicht unbedingt eine tatsächliche Datei mit diesem Namen an einer beliebigen Stelle auf dem PC. Wenn der Kontrakt dem aktuellen Gerät nicht zugeordnet ist, schlägt ein direkter Aufruf von LoadLibrary fehl. Eine verzögert geladene Referenz verhält sich anders: Der Prozess wird dennoch geladen, und das Fehlen zeigt sich erst später, wenn die API aufgerufen wird.
In jedem Fall ist ein erfolgreiches Verknüpfen oder Laden für sich genommen kein Beleg dafür, dass eine Implementierung vorhanden ist. Informationen dazu finden Sie unter Erkennen der VERFÜGBARKEIT von API-Sätze.
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. Mit einer Dachbibliothek können Sie eine einzelne Bibliothek verknüpfen, anstatt die einzelne Importbibliothek für jede api zu identifizieren, die Sie aufrufen.
Weitere Informationen sowie Hinweise zur Auswahl der Umbrella-Bibliothek, die zu Ihrem Ziel passt, finden Sie unter Windows-Umbrella-Bibliotheken.
API-Set Vertragsnamen
API-Sätze werden durch einen Vertragsnamen identifiziert, der konventionen folgt, die vom Bibliotheksladeprogramm erkannt werden.
Für alle Vertragsnamen gelten diese Konventionen:
- Der Name beginnt entweder mit der Zeichenfolge api- oder ext-.
- Der Inhalt des Namens kann aus alphanumerischen Zeichen oder Bindestrichen (-) bestehen. Eine Tilde (~) wird nur als Trennzeichen vor einem Gruppennamen angezeigt.
- Für den Namen wird die Groß-/Kleinschreibung nicht beachtet.
Zwei Formen des Vertragsnamens werden verwendet, und Sie können auf eines der beiden Arten stoßen.
Ein versionierter Vertragsname endet mit der Sequenz l<n>-<n>-<n>, wobei n aus Dezimalziffern besteht – zum Beispiel ext-ms-win-core-samplefeature-l1-1-0. Die nachfolgenden Nummern identifizieren eine bestimmte Version des Vertrags, und ein Name in diesem Formular sollte als unveränderlicher Bezeichner für diese Version betrachtet werden.
Ein Vertragsalias hat keine Version – zum Beispiel api-win-core-samplefeature. Er identifiziert den Vertrag selbst und nicht eine Version davon. Wenn ein Vertrag seine individuell verfügbaren Funktionen in benannten Gruppen organisiert, wird eine Gruppe durch Anfügen des Gruppennamens an den Vertragsalias adressiert, getrennt durch eine Tilde: api-win-core-samplefeature~AdvancedOperations.
Die samplefeature hier verwendeten Namen sind illustrative Namen für eine fiktive Windows Komponente.
Die Api- und Ext-Präfixe
Das Präfix ist eine Benennungskonvention. Ursprünglich sollte zwischen Verträgen unterschieden werden, die in jeder geeigneten Edition vorhanden sind (api-), und Verträgen, die möglicherweise fehlen (ext-). Diese Unterscheidung wurde nicht konsistent angewendet, und die Rolle eines Vertrags kann sich im Laufe der Zeit ändern, ohne dass der Vertrag umbenannt wird.
Das Ladeprogramm weist dem Präfix keine Bedeutung zu; es löst API- und Ext-Namen nach denselben Regeln auf. Die Verfügbarkeit wird nicht vom Präfix abgeleitet. Fragen Sie sie stattdessen ab – siehe Erkennen der VERFÜGBARKEIT von API-Sätze.
Verwenden eines Vertragsnamens
Zwei verschiedene Arten von Vorgängen verwenden einen Vertragsnamen.
Ladevorgänge wie LoadLibrary oder P/Invoke nehmen den Vertragsnamen an der gleichen Stelle an, an der ein DLL-Modulname ordnungsmäßig angezeigt wird. Eine angefügte .dll Komponente ist in diesem Kontext konventionell, ist jedoch nicht für die Auflösung von API-Setnamen erforderlich und ist nicht Teil des Vertragsnamens. Verwenden Sie einen Vertragsnamen anstelle eines physischen DLL-Modulnamens, um eine korrekte Route zur Implementierung sicherzustellen, unabhängig davon, wo die API tatsächlich auf dem aktuellen Gerät implementiert ist. Es muss keine Datei mit diesem Vertragsnamen auf dem Datenträger vorhanden sein.
Beispiele für Verfügbarkeitsabfragen lassen das .dll-Suffix konventionell weg und verwenden das Formular, das der Art und Weise entspricht, wie die API adressiert wird:
| API-Oberfläche | Abfrageformular | Example |
|---|---|---|
| Benannte Gruppe | <contract>~<group> |
api-win-core-samplefeature~AdvancedOperations |
| Standardgruppe | Vertragsalias, ohne ~Default |
api-win-core-samplefeature |
| Versionierter Vertrag | Vollständiger Name des versionierten Vertrags | ext-ms-win-core-samplefeature-l1-1-0 |
Ein Gruppenname kann nicht mit einem versionsierten Vertragsnamen kombiniert werden.
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:
Wenn der Header der API eine Is<APIName>Present Hilfsfunktion bereitstellt, bevorzugen Sie diese Hilfsfunktion, wenn Sie die Verfügbarkeit testen. Er enthält bereits den richtigen Namen für den API-Satz oder die Gruppe, der die API enthält. Weitere Informationen finden Sie unter Erkennen der Verfügbarkeit von API-Sätze.