Windows versioni e panoramica dell'SDK

Quando si inizia a creare app Windows, si noteranno riferimenti a diversi numeri di versione, ovvero la versione del sistema operativo Windows, l'SDK Windows e il SDK per app di Windows. Non preoccuparti: per la maggior parte dei nuovi progetti, Visual Studio imposta impostazioni predefinite sensibili e non dovrai pensare a questo aspetto. Tuttavia, quando è necessario specificare come destinazione una versione specifica del sistema operativo, comprendere perché un'API non è disponibile o configurare il file di progetto, questo articolo spiega in che modo i componenti si integrano e quali scelte effettuare.

Definizioni

denominazione della versione del sistema operativo Windows

Windows 11 fornisce aggiornamenti principali delle funzionalità usando il modello di denominazione YYHX:

• YY = anno di calendario a due cifre
• H1 = prima metà dell'anno; H2 = seconda metà dell'anno

La maggior parte delle versioni principali è stata rilasciata storicamente in autunno (H2), ma si verificano anche le versioni H1.

Regola: Il numero di build del sistema operativo nel dispositivo dell'utente determina le API della piattaforma disponibili in fase di esecuzione.

Corrispondenza tra Windows SDK e le versioni del sistema operativo

Ogni famiglia di versioni Windows SDK corrisponde a una versione del sistema operativo Windows. Il numero di build principale dell'SDK corrisponde in genere al numero di build del sistema operativo, anche se alcuni aggiornamenti delle funzionalità del sistema operativo (recapitati come pacchetti di abilitazione) condividono la stessa famiglia SDK di una versione precedente.

Regola: L'installazione di un determinato SDK Windows concede l'accesso in fase di compilazione a tutte le API da tale versione del sistema operativo e a tutte le versioni precedenti. Le API sono cumulative.

versioni di SDK per app di Windows

Il SDK per app di Windows è indipendente sia dal sistema operativo Windows che dall'SDK di Windows. Viene distribuito secondo una cadenza di rilascio propria come pacchetto NuGet.

Regola: È possibile usare le SDK per app di Windows più recenti nelle versioni precedenti del sistema operativo (fino al valore minimo indicato). La versione SDK per app di Windows non deve corrispondere alla versione del sistema operativo Windows o Windows SDK.

Per la matrice di supporto completa, vedere SDK per app di Windows versioni supportate Windows.

Correlazione dei tre componenti

Your App (.exe / .msix)
  │
  ├── References: Windows App SDK (NuGet package, e.g., 2.2)
  │     • Provides: WinUI 3, app lifecycle, windowing, push notifications
  │     • Updated: independently via NuGet
  │     • Constraint: has a minimum supported OS version
  │
  ├── Compiled against: Windows SDK (e.g., 10.0.26100)
  │     • Provides: Win32, WinRT, COM API declarations
  │     • Updated: with Visual Studio or standalone installer
  │     • Constraint: determines which APIs are visible at compile time
  │
  └── Runs on: Windows OS (e.g., Windows 11 24H2, build 26100)
        • Provides: actual API implementations at runtime
        • Updated: Windows Update
        • Constraint: determines which APIs are callable at runtime

Relazioni chiave:

1. SDK per app di Windows non sostituisce Windows SDK. È necessario entrambi.
2. La versione di Windows SDK può essere più recente del sistema operativo in cui viene eseguita l'app (usare i controlli di runtime per le API più recenti).
3. La versione SDK per app di Windows è completamente indipendente: aggiornarla senza cambiare altro.
4. Non è possibile chiamare un'API della piattaforma in fase di esecuzione se la build del sistema operativo dell'utente è precedente alla build che l'ha introdotta, indipendentemente dall'SDK compilato.

Configurazione del file di progetto

Le proprietà di MSBuild nel file di progetto controllano la piattaforma di destinazione. I nomi delle proprietà differiscono leggermente tra C# e C++:

File di progetto C# (con estensione csproj)

Nei progetti .NET in stile SDK (utilizzati dai modelli WinUI 3 e SDK per app di Windows), la versione della piattaforma Windows è integrata nel Target Framework Moniker (TFM):

<PropertyGroup>
    <!-- The TFM includes the Windows SDK version you compile against -->
    <TargetFramework>net8.0-windows10.0.26100.0</TargetFramework>

    <!-- The minimum OS version your app supports -->
    <SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>

    <!-- Or equivalently: -->
    <!-- <TargetPlatformMinVersion>10.0.19041.0</TargetPlatformMinVersion> -->
</PropertyGroup>

<ItemGroup>
    <!-- Windows App SDK (independent of the above) -->
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="2.2.0" />
</ItemGroup>

File di progetto C++ (.vcxproj)

<PropertyGroup>
    <!-- Note: C++ uses "WindowsTargetPlatform" prefix -->
    <WindowsTargetPlatformVersion>10.0.26100.0</WindowsTargetPlatformVersion>
    <WindowsTargetPlatformMinVersion>10.0.17763.0</WindowsTargetPlatformMinVersion>
</PropertyGroup>

Guida decisionale: scelta delle versioni

Usare le regole seguenti per selezionare le versioni per un nuovo progetto:

1. Imposta la versione della piattaforma Windows nel TFM sull'SDK di Windows stabile più recente (ad esempio, net8.0-windows10.0.26100.0). Ciò offre il set più ampio di API disponibili in fase di compilazione e attiva gli avvisi dell'analizzatore di compatibilità della piattaforma per le API non disponibili nella versione minima del sistema operativo supportata.
2. Impostare SupportedOSPlatformVersion (o TargetPlatformMinVersion) in base al pubblico:
   • App aziendali con dispositivi gestiti: corrispondono al sistema operativo minimo supportato dall'organizzazione.
   • App consumer (copertura più ampia): 10.0.19041.0 (Windows 10 2004) o 10.0.17763.0 (Windows 10 1809).
   • App che usano funzionalità di una versione specifica del sistema operativo: impostata sul numero di build di tale versione.
3. Usare sempre la SDK per app di Windows stabile più recente. Non c'è alcuna penalità di compatibilità; supporta di nuovo Windows 10 1809.
4. Non usare mai versioni di anteprima/SDK sperimentale nell'ambiente di produzione.

Controlli di disponibilità dell'API di runtime

Quando la versione della piattaforma Windows nel TFM è superiore a SupportedOSPlatformVersion, alcune API visibili in fase di compilazione potrebbero non essere presenti sul dispositivo dell'utente. L'analizzatore di compatibilità della piattaforma .NET avvisa di questi in fase di compilazione, ma è anche necessario controllare la disponibilità in fase di esecuzione prima di chiamarli.

Modello: Controllare il contratto API (API WinRT)

using Windows.Foundation.Metadata;

if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 15))
{
    // Safe to call APIs introduced in this contract version.
    // For example, use a newer composition API:
}
else
{
    // Fallback for older OS versions
}

Modello: verificare la presenza di un tipo specifico

if (ApiInformation.IsTypePresent("Windows.UI.Composition.SceneVisual"))
{
    // Safe to use SceneVisual
}

Modello: verificare la presenza di un metodo specifico

if (ApiInformation.IsMethodPresent("Windows.Storage.StorageFile", "GetFileFromPathForUserAsync"))
{
    // Safe to call this method
}

Regola: Se si ignorano questi controlli e si chiama un'API non disponibile, l'app avrà esito negativo in fase di esecuzione. L'errore esatto dipende dal tipo di API. Le eccezioni comuni includono TypeLoadException, MissingMethodExceptiono un errore specifico della piattaforma.

Domande comuni

"Quale SDK di Windows è consigliabile usare?"

Usare l'SDK di Windows più recente (attualmente 10.0.26100). È sempre possibile eseguire la compilazione in base a un SDK più recente rispetto al valore minimo di destinazione, ma influisce solo su ciò che è visibile in fase di compilazione.

"È necessario aggiornare Windows SDK quando si aggiorna il SDK per app di Windows?"

No. Sono indipendenti. È possibile eseguire l'aggiornamento Microsoft.WindowsAppSDK dalla versione 1.7 alla 1.8 senza modificare la versione di Windows SDK.

"L'app è destinata Windows 10. Posso usare il SDK per app di Windows?"

Yes. Il SDK per app di Windows supporta Windows 10 versione 1809 (build 17763) e versioni successive. Imposta il tuo SupportedOSPlatformVersion in base a ciò.

"Cosa accade se si esegue la compilazione in SDK 10.0.26100, ma l'utente esegue Windows 11 22H2 (build 22621)?"

Le API introdotte tra la build 22621 e la versione 26100 saranno visibili nel codice, ma avranno esito negativo in fase di esecuzione, a meno che non vengano aggiunti controlli di disponibilità dell'API. Le API della versione 22621 e precedenti funzionano normalmente.

"Come è possibile sapere quale numero di build ha introdotto un'API specifica?"

Controllare la pagina di riferimento dell'API in Microsoft Learn. La sezione Requisiti elenca la build minima del sistema operativo (come versione del contratto API o Windows versione).

Riepilogo delle regole

Contenuti correlati

• Rilasci di Windows supportati da SDK per app di Windows
• Note sulla versione dell'SDK Windows App
• Archivio di Windows SDK
• App adattabili alla versione
• Configurare l'ambiente di sviluppo