Chiamare le API Windows Runtime nelle app desktop

Configurare un progetto di .NET

.NET 6 e versioni successive: usare l'opzione Moniker del framework di destinazione

Specificare un Target Framework Moniker (TFM) specifico della versione del sistema operativo Windows nel file di progetto. In questo modo viene aggiunto un riferimento al pacchetto di destinazione Windows SDK appropriato in fase di compilazione.

1. In Visual Studio selezionare Project > [ProjectName] Proprietà.

2. Nella pagina delle proprietà trovare Application > General selezionandolo nel riquadro di spostamento a sinistra o scorrere verso di esso.

3. Scegliere le impostazioni per:

   1. FrameworkTarget : inizialmente impostato sulla versione .NET selezionata al momento della creazione del progetto, ma è possibile modificarla qui.
   2. Target OS : lasciare questa opzione impostata su Windows.
   3. Versione del sistema operativo di destinazione: selezionare la versione per il set di API che si vuole usare, in genere la versione più recente.
   4. Versione del sistema operativo supportata (facoltativo): vedere la sezione successiva per altre informazioni.

impostazioni del framework

Nel Moniker del Framework di Destinazione, questi valori si traducono nel modo seguente:

• Framework di destinazione - net10.0
• Sistema operativo di destinazione - -windows
• Versione del sistema operativo di destinazione - 10.0.22621.0

<TargetFramework>net10.0-windows10.0.22621.0</TargetFramework>
<!-- If set... -->
<SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>

È anche possibile impostare i valori modificando manualmente il file di progetto.

1. In Visual Studio fare clic con il pulsante destro del mouse sul project in Esplora soluzioni e scegliere Edit Project File.

2. Sostituire il valore TargetFramework con un TFM specifico della versione Windows.

   Destinazione	TFM
   Windows 11 versione 24H2	net10.0-windows10.0.26100.0
   Windows 11 versione 22H2	net10.0-windows10.0.22621.0
   Windows 11 (versione iniziale)	net10.0-windows10.0.22000.0
   Windows 10 versione 2004	net10.0-windows10.0.19041.0
   Windows 10 versione 1903	net10.0-windows10.0.18362.0
   Windows 10 versione 1809	net10.0-windows10.0.17763.0

   Nota

   I valori visualizzati sono per .NET 10. Aggiornare in base alle esigenze per altre versioni di .NET: net8.0, net9.0.

   Esempio:

   <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
       <OutputType>WinExe</OutputType>
       <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
     </PropertyGroup>
   </Project>
   

3. Salva e chiudi il file di progetto.

Supporto di una versione minima Windows

Per consentire l'esecuzione dell'app in una versione Windows precedente alla destinazione TFM, impostare il SupportedOSVersion (SupportedOSPlatformVersion), come illustrato nella sezione precedente. Per ulteriori informazioni, vedi Framework di destinazione: Supportare le versioni precedenti del sistema operativo.

Quando usi una serie di versioni del sistema operativo, proteggi le chiamate alle API che non sono disponibili in tutte le versioni utilizzando i controlli ApiInformation. Per altre informazioni, vedere App adattive per la versione.

Quando è impostato SupportedOSVersion, Visual Studio restituirà un avviso per le API che richiedono un controllo di runtime. Ad esempio, se la versione di destinazione è 19041 e la versione minima è 17763, verrà visualizzato un avviso simile al seguente quando si chiama AppInfo.Current.

CA1416	Using platform dependent API on a component makes the code no longer work across all platforms.

This call site is reachable on: 'Windows' 10.0.17763.0 and later. 'AppInfo.Current' is only supported on: 'Windows' 10.0.19041.0 and later.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <SupportedOSPlatformVersion>10.0.17763.0</SupportedOSPlatformVersion>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
  </PropertyGroup>
</Project>

API WinRT non supportate in .NET 6 e versioni successive

In .NET 6 e nelle versioni successive, varie API WinRT nel Windows.UI namespace non sono supportate. Usare le API equivalenti nel namespace Microsoft.UI (fornito dal SDK per app di Windows):

.NET Core 3.x o .NET Framework: installare il pacchetto NuGet

Se l'app è destinata a .NET Core 3.x o .NET Framework, installare il pacchetto NuGet Microsoft.Windows.SDK.Contracts:

1. In Visual Studio fare clic con il pulsante destro del mouse sul progetto e scegliere Gestisci pacchetti NuGet.

2. Cerca Microsoft.Windows.SDK.Contracts.

3. Selezionare la versione del pacchetto corrispondente alla destinazione minima Windows:

   Versione del pacchetto	destinazione Windows
   10.0.19041.xxxx	Windows 10 versione 2004
   10.0.18362.xxxx	Windows 10 versione 1903
   10.0.17763.xxxx	Windows 10 versione 1809
   10.0.17134.xxxx	Windows 10 versione 1803

4. Fare clic su Installa.

Supporto multi-target per .NET 6+ e versioni precedenti di .NET

Configurare il file di progetto per usare l'approccio TFM per .NET 6+ e il pacchetto NuGet per le versioni precedenti:

<Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFrameworks>netcoreapp3.1;net8.0-windows10.0.19041.0</TargetFrameworks>
    <UseWPF>true</UseWPF>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Condition="'$(TargetFramework)' == 'netcoreapp3.1'"
                     Include="Microsoft.Windows.SDK.Contracts"
                     Version="10.0.19041.0"/>
  </ItemGroup>
</Project>

Compilazione condizionale

Quando si effettua il multi-targeting in .NET 6+ e versioni meno recenti, usare la compilazione condizionale per scrivere codice specifico della versione in un singolo progetto. Per altre informazioni, vedere Framework di destinazione : Simboli del preprocessore.

#if NET6_0_OR_GREATER
    // Code that uses .NET 6+ APIs or TFM-available WinRT APIs
#else
    // Fallback code for .NET Core 3.x / .NET Framework
#endif

Configurare un progetto C++ (Win32)

Usare C++/WinRT per usare le API WinRT dalle app desktop C++.

• Installare il Microsoft.Windows. CppWinRT pacchetto NuGet.
• Poiché C++/WinRT usa le funzionalità dello standard C++17, assicurarsi che la proprietà del progetto C/C++ > Language > C++ Language Standard sia impostata su ISO C++17 Standard (/std:c++17) o versione successiva in Visual Studio.

Per altre informazioni, vedere Visual Studio supporto per C++/WinRT.