Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Importante
Le informazioni contenute in questo argomento si applicano a tutte le versioni di Windows 10 e versioni successive. Queste versioni verranno indicate qui come "Windows", richiamando eventuali eccezioni, se necessario.
Tutte le versioni di Windows condividono una base comune di componenti del sistema operativo (OS) chiamati sistema operativo core (in alcuni contesti questa base comune è anche denominata OneCore). Nei componenti principali del sistema operativo, le API Win32 sono organizzate in gruppi funzionali denominati set di API.
Lo scopo di un set di API è fornire una separazione dell'architettura tra la DLL host in cui viene implementata una determinata API Win32 e il contratto funzionale a cui appartiene l'API. Il disaccoppiamento offerto dai set di API tra implementazione e contratti offre molti vantaggi di progettazione per gli sviluppatori. In particolare, l'uso di set di API nel codice può migliorare la compatibilità con i dispositivi Windows.
I set di API riguardano in modo specifico gli scenari seguenti:
Anche se l'intera ampiezza dell'API Win32 è supportata nei PC, solo un subset dell'API Win32 è disponibile in altri dispositivi Windows, ad esempio HoloLens, XBOX e altri dispositivi. Un nome del set di API offre un aspetto stabile da chiedere, in modo che l'app possa rilevare in fase di esecuzione se una funzionalità è disponibile nel dispositivo corrente. La query stessa viene eseguita dalla funzione IsApiSetImplemented .
Alcune implementazioni dell'API Win32 esistono nelle DLL con nomi diversi in dispositivi Windows diversi. L'uso dei nomi dei set di API anziché dei nomi dll quando rileva la disponibilità dell'API e ritarda il caricamento delle API fornisce una route corretta all'implementazione indipendentemente dalla posizione in cui viene effettivamente implementata l'API.
Per altre informazioni, vedere Operazione del caricatore del set di API e Rilevare la disponibilità del set di API.
I set di API e le DLL sono la stessa cosa?
No: un nome del set di API identifica un contratto, non un file. In fase di esecuzione il caricatore risolve il contratto tramite lo schema del set di API nel dispositivo corrente e instrada il riferimento alla DLL che ospita l'implementazione. Si tratta di una tecnica di nascondimento dell'implementazione, in cui il chiamante non deve sapere esattamente quale modulo ospita le informazioni.
La tecnica consente il refactoring dei moduli (suddivisione, consolidamento, ridenominazione e così via) in diverse versioni e edizioni di Windows. E le app continuano a collegarsi e vengono comunque instradate al codice corretto in fase di esecuzione.
Allora perché i set di API hanno .dll nei loro nomi? Il motivo è il modo in cui viene implementato il caricatore DLL. Il caricatore è la parte del sistema operativo che carica le DLL e/o risolve i riferimenti alle DLL e identifica cosa caricare da un nome di modulo digitato nel modo in cui i nomi dei file vengono digitati in una tabella di importazione. I nomi dei set di API seguono la stessa convenzione in modo che si adattino nella stessa posizione.
Il caricatore riconosce un nome che inizia con api- o ext- e lo instrada al runtime del set di API, un'estensione del caricatore che risolve i contratti tramite lo schema. Da questo punto il nome viene analizzato dalle regole di denominazione del set di API anziché come nome file, quindi il .dll suffisso non fa parte del nome del contratto da risolvere.
È possibile passare un nome del set di API a LoadLibrary o usarlo come destinazione di caricamento ritardato. L'operazione ha esito positivo quando lo schema nel dispositivo corrente esegue il mapping del contratto a un host utilizzabile; non esiste necessariamente un file effettivo con quel nome in qualsiasi punto del PC. Se il contratto non è mappato nel dispositivo corrente, un loadLibrary diretto ha esito negativo. Un riferimento con caricamento ritardato si comporta in modo diverso: il processo viene ancora caricato e l'assenza viene visualizzata in un secondo momento, quando viene chiamata l'API.
In entrambi i casi, un collegamento o un caricamento riuscito non è da solo la prova che è presente un'implementazione. Per determinare questa operazione, vedere Rilevare la disponibilità del set di API.
Collegamento di librerie generiche
Per semplificare la limitazione del codice alle API Win32 supportate nel sistema operativo principale, forniamo una serie di librerie generiche. Una libreria generica consente di collegare una singola libreria invece di identificare la singola libreria di importazione per ogni API chiamata.
Per ulteriori dettagli e per scegliere la libreria umbrella più adatta alla destinazione prevista, vedi librerie umbrella di Windows.
Nomi di contratto del set di API
I set di API sono identificati da un nome di contratto che segue le convenzioni riconosciute dal caricatore di libreria.
Tutti i nomi di contratto condividono queste convenzioni:
- Il nome inizia con la stringa api- o ext-.
- Il corpo del nome può essere costituito da caratteri alfanumerici o trattini (-). Una tilde (~) viene visualizzata solo come separatore prima di un nome di gruppo.
- Il nome non distingue tra maiuscole e minuscole.
Sono in uso due forme del nome del contratto ed è possibile incontrare l’una o l’altra.
Un nome di contratto versionato termina con la sequenza l<n>->n<->n<, dove n è costituito da cifre decimali, ad esempio ext-ms-win-core-samplefeature-l1-1-0. I numeri finali identificano una versione specifica del contratto e un nome in questo formato deve essere considerato un identificatore non modificabile per tale versione.
Un alias del contratto non include alcuna versione, ad esempio api-win-core-samplefeature. Identifica il contratto stesso anziché una versione di esso. Quando un contratto organizza le funzionalità disponibili singolarmente in gruppi denominati, un gruppo viene indirizzato aggiungendo il nome del gruppo all'alias del contratto, separato da una tilde: api-win-core-samplefeature~AdvancedOperations.
I samplefeature nomi usati qui sono nomi illustrativi per un componente fittizio Windows.
Prefissi api- ed ext-
Il prefisso è una convenzione di denominazione. Originariamente era destinato a distinguere i contratti presenti in ogni edizione idonea (api-) dai contratti che potrebbero essere assenti (ext-). Tale distinzione non è stata applicata in modo coerente e il ruolo di un contratto può cambiare nel tempo senza rinominare il contratto.
Il caricatore non assegna alcun significato al prefisso; risolve i nomi api e ext-name in base alle stesse regole. Non dedurre la disponibilità dal prefisso. Interrogala invece: vedi Rilevare la disponibilità del set API.
Uso di un nome di contratto
Due diversi tipi di operazioni richiedono un nome di contratto.
Le operazioni del caricatore, ad esempio LoadLibrary o P/Invoke, accettano il nome del contratto nella stessa posizione in cui viene normalmente visualizzato un nome di modulo DLL. Un oggetto aggiunto .dll è convenzionale in tale contesto, ma non è richiesto dalla risoluzione dei nomi del set di API e non fa parte del nome del contratto. Usare un nome di contratto anziché un nome di modulo DLL fisico per garantire una route corretta all'implementazione indipendentemente dalla posizione in cui l'API viene effettivamente implementata nel dispositivo corrente. Non è necessario che sia presente un file con il nome del contratto su disco.
Gli esempi di query di disponibilità omettono convenzionalmente il suffisso .dll e usano il modulo che corrisponde alla modalità di gestione dell'API:
| Superficie delle API | Modulo query | Example |
|---|---|---|
| Gruppo con nome | <contract>~<group> |
api-win-core-samplefeature~AdvancedOperations |
| Gruppo predefinito | Alias del contratto, senza ~Default |
api-win-core-samplefeature |
| Contratto versionato | Nome completo del contratto con versioni | ext-ms-win-core-samplefeature-l1-1-0 |
Un nome di gruppo non può essere combinato a un nome di contratto con versione.
Identificazione dei set di API per le API Win32
Per identificare se una particolare API Win32 appartiene a un set di API, esaminare la tabella dei requisiti nella documentazione di riferimento per l'API. Se l'API appartiene a un set di API, la tabella dei requisiti nell'articolo elenca il nome del set di API e la versione di Windows in cui l'API è stata introdotta per la prima volta nel set di API. Per esempi di API che appartengono a un set di API, vedere gli articoli seguenti:
Se l'header dell'API fornisce una funzione di supporto Is<APIName>Present, preferisci questa funzione quando verifichi la disponibilità. Contiene già il nome corretto per il set di API o il gruppo che contiene l'API. Per altre informazioni, vedere Rilevare la disponibilità dei set di API.