Windows API-uppsättningar

Alla versioner av Windows delar en gemensam bas av operativsystemkomponenter (OS) som kallas core OS- (i vissa sammanhang kallas den här gemensamma basen även OneCore). I viktiga OS-komponenter är Win32-API:er ordnade i funktionella grupper som kallas API-uppsättningar.

Syftet med en API-uppsättning är att tillhandahålla en arkitekturavgränsning mellan värd-DLL där ett visst Win32-API implementeras och det funktionella kontrakt som API:et tillhör. Den avkoppling som API-uppsättningar ger mellan implementering och kontrakt erbjuder många tekniska fördelar för utvecklare. I synnerhet kan användning av API-uppsättningar i koden förbättra kompatibiliteten med Windows-enheter.

API-uppsättningar hanterar specifikt följande scenarier:

• Även om den fullständiga bredden i Win32-API:et stöds på datorer är endast en delmängd av Win32-API:et tillgänglig på andra Windows enheter som HoloLens, XBOX och andra enheter. Ett API-uppsättningsnamn ger dig en stabil sak att fråga om, så att din app vid körning kan identifiera om en funktion är tillgänglig på den aktuella enheten. Själva frågan utförs av funktionen IsApiSetImplemented .

• Vissa Win32 API-implementeringar finns i DLL:er med olika namn på olika Windows-enheter. Användning av API-uppsättningsnamn i stället för DLL-namn vid identifiering av API-tillgänglighet och fördröjning vid inläsning av API:er ger en korrekt väg till implementeringen oavsett var API:et faktiskt implementeras.

Mer information finns i API set loader operation och Detect API set availability.

Är API-uppsättningar och DLL:er samma sak?

Nej – ett API-uppsättningsnamn identifierar ett kontrakt, inte en fil. Vid körningen löser inläsaren kontraktet via API-uppsättningens schema på den aktuella enheten och dirigerar referensen till den DLL som är värd för implementeringen. Det är en implementeringsgömningsteknik där du som anropare inte behöver veta exakt vilken modul som är värd för informationen.

Tekniken gör att moduler kan omstruktureras (delas upp, konsolideras, byta namn och så vidare) i olika Windows-versioner och utgåvor. Och dina appar länkar fortfarande och dirigeras fortfarande till rätt kod vid körning.

Så varför har API-uppsättningar .dll i sina namn? Orsaken är hur DLL-inläsare implementeras. Inläsaren är den del av operativsystemet som läser in DLL:er och/eller löser referenser till DLL:er och identifierar vad som ska läsas in med ett modulnamn som stavas hur filnamn stavas i en importtabell. API-uppsättningsnamn följer samma konvention så att de får plats på samma plats.

Inläsaren identifierar ett namn som börjar med api- eller ext- och dirigerar det till API-uppsättningens körningstid, ett tillägg för inläsaren som löser kontrakt via schemat. Från den tidpunkten tolkas namnet enligt API-uppsättningens namngivningsregler i stället för som ett filnamn, så suffixet .dll ingår inte i kontraktnamnet som matchas.

Du kan skicka ett API-uppsättningsnamn till LoadLibrary eller använda det som ett mål för fördröjningsbelastning. Åtgärden lyckas när schemat på den aktuella enheten mappar kontraktet till en användbar värd. Det finns inte nödvändigtvis en faktisk fil med det namnet någonstans på datorn. Om kontraktet inte är mappat på den aktuella enheten misslyckas ett direkt anrop till LoadLibrary. En referens som fördröjningsläses fungerar annorlunda: processen läses ändå in, och avsaknaden märks först senare, när API:et anropas.

Hur som helst är en lyckad länk eller belastning inte i sig bevis på att en implementering finns. Information om hur du fastställer detta finns i Identifiera tillgänglighet för API-uppsättningar.

Länka samlingsbibliotek

För att göra det enklare att begränsa koden till Win32-API:er som stöds i kärnoperativsystemet tillhandahåller vi en serie paraplybibliotek. Med ett paraplybibliotek kan du länka ett enda bibliotek i stället för att identifiera det enskilda importbiblioteket för varje API som du anropar.

Mer information och om du vill välja det paraplybibliotek som matchar det du riktar in dig på finns Windows paraplybibliotek.

Namn på API-uppsättningskontrakt

API-uppsättningar identifieras med ett kontraktnamn som följer konventioner som identifieras av biblioteksinläsaren.

Alla kontraktsnamn delar dessa konventioner:

• Namnet börjar antingen med strängen api- eller ext-.
• Namnets brödtext kan vara alfanumeriska tecken eller bindestreck (-). En tilde (~) visas bara som avgränsare före ett gruppnamn.
• Namnet är skiftlägesokänsligt.

Två former av kontraktnamn används och du kan stöta på någon av dem.

Ett versionshanterat kontraktsnamn slutar med sekvensen l<n>->n>-<n<, där n består av decimala siffror – till exempel ext-ms-win-core-samplefeature-l1-1-0. De avslutande numren identifierar en specifik version av kontraktet, och ett namn i det här formuläret bör betraktas som en oföränderlig identifierare för den versionen.

Ett kontraktsalias innehåller ingen version – till exempel api-win-core-samplefeature. Det identifierar själva kontraktet i stället för en version av det. När ett kontrakt organiserar sina individuellt tillgängliga funktioner i namngivna grupper adresseras en grupp genom att gruppnamnet läggs till efter kontraktaliaset, åtskilt med ett tilde-tecken: api-win-core-samplefeature~AdvancedOperations

Namnen samplefeature som används här är illustrativa namn för en fiktiv Windows komponent.

api- och ext-prefixen

Prefixet är en namngivningskonvention. Det var ursprungligen avsett att skilja kontrakt som finns på varje kvalificerande utgåva (api-) från kontrakt som kan vara frånvarande (ext-). Den skillnaden tillämpades inte konsekvent, och ett kontrakts roll kan ändras över tid utan att kontraktet byter namn.

Inläsaren tilldelar ingen betydelse för prefixet. den löser api- och ext-namn med samma regler. Härled inte tillgänglighet från prefixet. Fråga i stället—se Identifiera tillgängliga API-uppsättningar.

Använda ett kontraktnamn

Två olika typer av operationer använder ett kontraktsnamn.

Inläsningsåtgärder, till exempel LoadLibrary eller P/Invoke, tar kontraktnamnet på samma plats där ett DLL-modulnamn vanligtvis visas. Ett tillagt .dll är vedertaget i det sammanhanget, men det krävs inte för namnmatchning för API-uppsättningar och ingår inte i kontraktsnamnet. Använd ett kontraktnamn i stället för ett fysiskt DLL-modulnamn för att säkerställa en korrekt väg till implementeringen oavsett var API:et faktiskt implementeras på den aktuella enheten. Det behöver inte finnas någon fil med det kontraktsnamnet på disken.

Exempel på tillgänglighetsfråga utelämnar konventionellt.dll-suffixet och använder formuläret som matchar hur API:et hanteras:

Ett gruppnamn kan inte kombineras med namnet på ett versionshanterat kontrakt.

Identifiera API-uppsättningar för Win32-API:er

Om du vill ta reda på om ett visst Win32-API tillhör en API-uppsättning läser du kravtabellen i referensdokumentationen för API:et. Om API:et tillhör en API-uppsättning visar kravtabellen i artikeln API-uppsättningens namn och den Windows-version där API:et först introducerades i API-uppsättningen. Exempel på API:er som tillhör en API-uppsättning finns i följande artiklar:

• AllowSetForegroundWindow
• FindWindowEx
• GetClassFile

Om API:ets huvud tillhandahåller en Is<APIName>Present hjälpfunktion föredrar du den hjälpen när du testar tillgängligheten. Den innehåller redan rätt namn för API-uppsättningen eller gruppen som bär API:et. Mer information finns i Identifiera tillgänglighet för API-uppsättningar.

I det här avsnittet

• API-inläsningsåtgärd
• Identifiera tillgänglighet för API-uppsättningar
• Windows-samlingsbibliotek