Note sulla versione del canale stabile per Windows App SDK 1.0

  • Articolo

Il canale stabile fornisce versioni di Windows App SDK supportati per l'uso da parte delle app negli ambienti di produzione. Le app che usano la versione stabile del Windows app SDK possono anche essere pubblicate in Microsoft Store.

Collegamenti importanti:

Ultime note sulla versione del canale Stabile

Vedere Download per Windows App SDK.

Nota

Le estensioni di Visual Studio (VSIX) di Windows App SDK non vengono più distribuite come download separato. Sono disponibili in Visual Studio Marketplace all'interno di Visual Studio.

Version 1.0.4

Si tratta di una versione di manutenzione di Windows App SDK che include delle correzioni di bug critiche per la versione 1.0.

Correzioni di bug (1.0.4)

  • È stato risolto un problema che causava l'uso di AppBars quando veniva usato come Page.TopAppBar o Page.BottomAppBar per non eseguire il rendering sullo schermo.
  • Correzione del problema per cui le app con un nome di pacchetto di 12 caratteri o meno che usano un controllo WinUI da MUXControls.dll si arresteranno immediatamente in modo anomalo. Per altre informazioni, vedere il problema 6360 su GitHub.
  • Correzione dei problemi di input tattile che causano problemi con i tasti di scelta rapida e altri scenari. Per altre informazioni, vedere il problema 6291 su GitHub.
  • È stato risolto un problema che causava l'errore di distribuzione delle app in pacchetto con MSIX o distribuite come self-contained.
  • Sono stati risolti problemi che causano un arresto anomalo delle app durante un'operazione di trascinamento della selezione. Per altre informazioni, vedere il problema 7002 su GitHub.

Versione 1.0.3

Si tratta di una versione di manutenzione di Windows App SDK che include delle correzioni di bug critiche per la versione 1.0.

Correzioni di bug (1.0.3)

  • È stato risolto un problema che causava l'arresto anomalo delle app C# con WebView2 all'avvio quando il runtime C/C++ (CRT) non è installato.
  • Correzione dei problemi di input tattile che causano problemi con i tasti di scelta rapida e altri scenari. Per altre informazioni, vedere il problema 6291 su GitHub.

Nota: in genere non si aggiungono funzionalità in una versione di manutenzione, ma la correzione WebView2 di questa versione richiede l'aggiornamento alla versione più recente di WebView2 SDK (da 1020.46 a 1185.39). Per altre informazioni sul runtime WebView2, vedere Note sulla versione per WebView2 SDK 1.0.1185.39 e Distribuzione dell'app e WebView2 Runtime .

Versione 1.0.2

Si tratta di una versione di manutenzione di Windows App SDK che include delle correzioni di bug critiche per la versione 1.0.

Correzioni di bug (1.0.2)

  • Correzione del problema del ciclo di layout che causa l'arresto anomalo di un'app durante lo scorrimento fino al termine di un controllo ListView. Per altre informazioni, vedere il problema 6218 su GitHub.
  • È stato risolto un problema che causava l'arresto anomalo delle app C# all'avvio quando il runtime C/C++ (CRT) non è installato. Tuttavia, CRT è ancora necessario per le app C# che usano WebView2. Per altre informazioni, vedere il problema 2117 su GitHub.
  • È stato risolto un problema per cui le applicazioni con MSIX a progetto singolo non generavano un file con estensione appinstaller. Per altre informazioni, vedere il problema 1821 su GitHub.
  • È stato risolto un problema per cui le applicazioni WinUI non supportavano .NET 6 dotnet build.

Versione 1.0.1

Si tratta di una versione di manutenzione di Windows App SDK che include correzioni di bug critiche e supporto per più finestre per la versione 1.0.

Correzioni di bug (1.0.1)

  • È stato risolto un problema che causava la mancata compilazione di MddBootstrapAutoinitializer con implicitUsing abilitati. Per altre informazioni, vedere il problema 1686 su GitHub.
  • È stato risolto un problema a causa del quale lo stato attivo in WebView2 andrebbe perduto in modo imprevisto causando problemi di input e selezione. Per ottenere altre informazioni, vedere questo problema 5615 & problema 5570 su GitHub.
  • È stato risolto un problema che causava l'impossibilità di fare clic sulla barra degli strumenti in-app in Visual Studio quando si usa una barra del titolo personalizzata in un'app WinUI 3.
  • È stato risolto un problema che causava la mancata visualizzazione del layout di snap quando si usa una barra del titolo personalizzata in un'app WinUI 3. Per ottenere altre informazioni, vedere questo problema 6333 & problema 6246 su GitHub.
  • È stato risolto un problema che causava un'eccezione durante l'impostazione della proprietà Window.ExtendsContentIntoTitleBar quando Window.SetTitlebar è stato chiamato con un UIElement ancora in fase di caricamento.
  • È stato risolto un problema per cui le app MSIX a progetto singolo non supportavano dotnet build.
  • È stato risolto un problema che causava l'installazione di app non in pacchetto dopo l'installazione di un'app in pacchetto. Per altre informazioni, vedere il problema 1871 su GitHub.
  • Correzione del problema di riduzione delle prestazioni durante le operazioni di trascinamento del mouse.
  • Correzione dell'arresto anomalo durante la chiamata a GetWindowIdFromWindow() nelle app non in pacchetto. Vedere la discussione 1891 su GitHub per ulteriori informazioni.

Le limitazioni e i problemi noti per la versione 1.0 si applicano anche alla versione 1.0.1.

Inoltre, per le app con barre del titolo personalizzate, sono state apportate modifiche in questa versione (e sono stati risolti numerosi problemi) che includono correzioni alla finestra di vetro usata per le operazioni di trascinamento della selezione. La raccomandazione consiste nell'usare i valori e i comportamenti predefiniti (dare loro un tentativo!). Se la barra del titolo usa i margini in modo che i pulsanti di didascalia predefiniti siano interattivi, è consigliabile visualizzare l'area di trascinamento impostando lo sfondo della barra del titolo su rosso e quindi modificando i margini per estendere l'area di trascinamento ai controlli didascalia.

Nuove funzionalità

Abbiamo stabilizzato e abilitato la creazione di più finestre nello stesso thread nelle applicazioni WinUI 3. Per altre informazioni, vedere problema n. 5918.

Version 1.0

Nelle sezioni seguenti vengono descritte le funzionalità nuove e aggiornate, le limitazioni e i problemi noti per 1.0.

WinUI 3

WinUI 3 è un framework di esperienza utente nativa per Windows App SDK. In questa versione sono state aggiunte più nuove funzionalità da Windows App SDK 0.8 e sono stati stabilizzati problemi dalle versioni di anteprima 1.0.

Nuove funzionalità e aggiornamenti

  • Sono stati aggiunti nuovi controlli (PipsPager, Expander, BreadcrumbBar) e sono stati aggiornati i controlli esistenti per riflettere gli stili di Windows più recenti di WinUI 2.6.
  • La creazione di pacchetti MSIX a progetto singolo è supportata in WinUI creando una nuova applicazione usando il modello "App vuota, inclusa nel pacchetto...".
  • È ora supportata la distribuzione di app WinUI 3 non in pacchetto nelle versioni di Windows 1809 e successive. Per maggiori informazioni, consultare la sezione Creazione del primo progetto WinUI 3 (Windows App SDK).
  • I progetti WinUI 3 ora possono impostare la versione di destinazione su Windows 10, versione 1809. In precedenza, potevano essere impostati solo a partire dalla versione 1903.
  • Nella barra degli strumenti in app, Ricaricamento rapido & nella struttura ad albero visuale live per le app in pacchetto WinUI sono supportate in Visual Studio 2022 Preview 5 e GA.

Limitazioni importanti:

  • Problemi noti per le applicazioni WinUI incluse nel pacchetto e non incluse nel pacchetto :

    • Errore di runtime nelle app C++ o C# che fanno riferimento a un componente Windows Runtime C++:

      • Per risolvere il problema, aggiungere la destinazione seguente alla fine del .vcxproj del componente Windows Runtime:
      <Target Name="GetPriIndexName">
<PropertyGroup>
    <!-- Winmd library targets use the default root namespace of the project for the App package name -->
    <PriIndexName Condition="'$(RootNamespace)' != ''">$(RootNamespace)</PriIndexName>
    <!-- If RootNamespace is empty fall back to TargetName -->
    <PriIndexName Condition="$(PriIndexName) == ''">$(TargetName)</PriIndexName>
</PropertyGroup>
</Target>
      • L'errore previsto sarà simile all'errore di origine winRT - 0x80004005 : 'Impossibile individuare la risorsa da 'ms-appx:///BlankPage.xaml'.'.

  • Problemi noti per le applicazioni WinUI con MSIX a progetto singolo (app vuota, modello incluso nel pacchetto):

    • Voce di menu di Pacchetto mancante & pubblicazione menu fino al riavvio di Visual Studio: quando si crea una nuova app con MSIX a progetto singolo in Visual Studio 2019 e Visual Studio 2022 usando il modello di progetto App vuota, In pacchetto (WinUI 3 in Desktop), il comando per pubblicare il progetto non viene visualizzato nel menu finché non si chiude e si riapri Visual Studio.
    • Un'app C# con MSIX a progetto singolo non verrà compilata senza il componente facoltativo "C++ (v14x) strumenti per piattaforma UWP (Universal Windows Platform) ". Per altre informazioni, vedere Installazione degli strumenti per Windows App SDK.
    • Potenziale errore di run-time in un'app con MSIX a progetto singolo che utilizza i tipi definiti in un componente Windows Runtime a cui si fa riferimento: per risolvere, aggiungere manualmente voci di classe attivabili al appxmanifest.xml.
      • L'errore previsto nelle applicazioni C# è "COMException: Classe non registrata (0x80040154 (REGDB_E_CLASSNOTREG)).
      • L'errore previsto nelle applicazioni C++/WinRT è "winrt::hresult_class_not_registered".

  • Problemi noti per le app WinUI 3 non inclusa nel pacchetto (app non inclusa nel pacchetto ):

  • Problemi noti per creazione di pacchetti e distribuzione di applicazioni WinUI :

    • Il Package comando non è supportato nelle app WinUI con MSIX a progetto singolo (app vuota, modello incluso nel pacchetto). Usare invece il Package & Publish comando per creare un pacchetto MSIX.
    • Per creare un pacchetto NuGet da una libreria di classi C# con il Pack comando , assicurarsi che l'elemento attivo Configuration sia Release.
    • Il Pack comando non è supportato nei componenti Windows Runtime C++ per creare un pacchetto NuGet.

Per altre informazioni o per iniziare a sviluppare con WinUI, vedere:

Windowing

Windows App SDK fornisce una classe AppWindow che evolve la precedente e intuitiva classe di anteprima Windows.UI.WindowManagement.AppWindow, ma la rende anche disponibile per tutte le applicazioni Windows, comprese quelle Win32, WPF e WinForms.

Nuove funzionalità:

  • AppWindow è un'API di windows di alto livello che consente scenari di windowing facili da usare che si integrano bene con l'esperienza utente di Windows e con altre app. Rappresenta un'astrazione generale di un contenitore gestito dal sistema del contenuto di un'app. È il contenitore in cui è ospitato il contenuto; e rappresenta l'entità con cui gli utenti interagiscono quando ridimensionano e spostano l'app sullo schermo. Per gli sviluppatori che hanno familiarità con Win32, AppWindow può essere vista come un'astrazione di alto livello di HWND.
  • DisplayArea rappresenta un'astrazione generale di un HMONITOR, segue gli stessi principi di AppWindow.
  • DisplayAreaWatcher consente a uno sviluppatore di osservare le modifiche nella topologia di visualizzazione ed enumerare DisplayAreas attualmente definito nel sistema.

Per maggiori informazioni, consultare la sezione Gestione delle app Windows (Windows App SDK).

Input

Queste sono le API di input che supportano WinUI e forniscono una superficie API di livello inferiore per gli sviluppatori per ottenere interazioni di input più avanzate.

Nuove funzionalità:

  • API puntatore: PointerPoint, PointerPointProperties e PointerEventArgs per supportare il recupero delle informazioni sugli eventi del puntatore con le API di input XAML.
  • API InputPointerSource: rappresenta un oggetto registrato per segnalare l'input del puntatore e fornisce la gestione degli eventi di input e cursore del puntatore per l'API SwapChainPanel di XAML.
  • API cursore: consente agli sviluppatori di modificare la bitmap del cursore.
  • API GestureRecognizer: consente agli sviluppatori di riconoscere determinati movimenti, ad esempio trascinamento, tenere premuto e fare clic quando vengono specificate informazioni sul puntatore.

Limitazioni importanti:

  • Tutte le funzioni statiche di fabbrica di PointerPoint sono state rimosse: GetCurrentPoint, GetCurrentPointTransformed, GetIntermediatePoints e GetIntermediatePointsTransformed.
  • Windows App SDK non supporta il recupero di oggetti PointerPoint con ID puntatore. È invece possibile utilizzare la funzione membro PointerPointGetTransformedPoint per recuperare una versione trasformata di un oggetto PointerPoint. Per i punti intermedi, è possibile utilizzare le funzioni membro PointerEventArgsGetIntermediatePoints e GetTransformedIntermediatePoints.
  • L'uso diretto dell'API dell'SDK della piattaforma Windows.UI.Core.CoreDragOperation non funzionerà con le applicazioni WinUI.
  • Le proprietà PointerPoint RawPosition e ContactRectRaw sono state rimosse perché hanno fatto riferimento a valori non stimati, che erano uguali ai valori normali nel sistema operativo. Utilizzare invece Position e ContactRect. La stima del puntatore viene ora gestita con l'oggetto API Microsoft.UI.Input.PointerPredictor .

Ciclo di vita dell'app

La maggior parte delle funzionalità del ciclo di vita delle app esiste già nella piattaforma UWP ed è stata inserita in Windows App SDK per l'uso da parte dei tipi di app desktop, in particolare le app console non incluse nel pacchetto, le app Win32, le app Windows Form e le app WPF. L'implementazione Windows app SDK di queste funzionalità non può essere usata nelle app UWP, perché esistono funzionalità equivalenti nella piattaforma UWP stessa.

Importante

Se si sta lavorando a un'app UWP, fare riferimento a Eseguire la migrazione dalla piattaforma UWP a SDK per app di Windows.

Le app non UWP possono anche essere inserite in pacchetti MSIX. Anche se queste app possono usare alcune delle funzionalità del ciclo di vita delle app Windows app SDK, devono usare l'approccio manifesto in cui è disponibile. Ad esempio, non possono usare le API Windows App SDK RegisterForXXXActivation e devono invece registrarsi per l'attivazione avanzata tramite il manifesto.

Tutti i vincoli per le app in pacchetto si applicano anche alle app WinUI, incluse in un pacchetto, e ci sono considerazioni aggiuntive, come descritto di seguito.

Considerazioni importanti:

  • Attivazione avanzata: GetActivatedEventArgs

  • Registrazione/Annullamento della registrazione per l'attivazione avanzata

  • Creazione di istanze singole/multiple

    • App non incluse nel pacchetto: completamente utilizzabile.
    • App non incluse nel pacchetto: completamente utilizzabile.
    • app WinUI: se un'app vuole rilevare altre istanze e reindirizzare un'attivazione, deve farlo il prima possibile e prima di inizializzare qualsiasi finestra e così via. A tale scopo, l'app deve definire DISABLE_XAML_GENERATED_MAIN e scrivere un main personalizzato (C#) o WinMain (C++) in cui può eseguire il rilevamento e il reindirizzamento.
    • RedirectActivationToAsync è una chiamata asincrona e non è consigliabile attendere una chiamata asincrona se l'app è in esecuzione in una STA. Per Windows Form e app WinUI C#, si può dichiarare Main come asincrono, se necessario. Per le app WinUI e C# WPF C++ non è possibile dichiarare Main come asincrona, quindi è necessario spostare la chiamata di reindirizzamento a un altro thread per assicurarsi di non bloccare la STA.
    • Per altre informazioni, vedere Creazione di istanze dell'app con l'API ciclo di vita dell'app.

  • Notifiche di alimentazione/stato

Problema noto:

  • Le associazioni tipo di file codificano in modo non corretto %1 come %251 quando si imposta il modello della riga di comando del gestore verbo, che arresta in modo anomalo le app Win32 non incluse nel pacchetto. È possibile modificare manualmente il valore del Registro di sistema in modo che sia %1 come soluzione alternativa parziale. Se il percorso del file di destinazione contiene uno spazio, l'operazione avrà comunque esito negativo e non è disponibile alcuna soluzione alternativa per tale scenario.
  • Questi bug a istanza singola/multipla verranno corretti in una patch di manutenzione imminente:
    • Il reindirizzamento appInstance non funziona quando viene compilato per x86
    • La registrazione di una chiave, l'annullamento della registrazione e la registrazione causa l'arresto anomalo dell'app

DWriteCore

DWriteCore è l'implementazione Windows App SDK DirectWrite (DirectWrite è l'API DirectX per il rendering di testo di alta qualità, i tipi di carattere struttura indipendenti dalla risoluzione e il supporto completo di testo e layout Unicode). DWriteCore è una forma di DirectWrite, eseguibile su Windows fino alla versione 10 1809 (10.0; Build 17763), che offre opportunità per l'uso su più piattaforme.

Funzionalità:

DWriteCore contiene tutte le funzionalità di DirectWrite, con alcune eccezioni.

Limitazioni importanti:

  • DWriteCore non contiene le seguenti funzionalità di DirectWrite:
    • Tipi di carattere per sessione
    • Tipi di carattere definiti dall'utente finale (EUDC)
    • API di streaming dei tipi di carattere
  • Il supporto dell'API di rendering di basso livello è parziale.
  • DWriteCore non interagisce con Direct2D, ma è possibile usare IDWriteGlyphRunAnalysis e IDWriteBitmapRenderTarget.

Per altre informazioni, vedi Panoramica di DWriteCore.

MRT Core

MRT Core è una versione semplificata del moderno Sistema di gestione delle risorse di Windows che viene distribuito come parte di Windows App SDK.

Limitazioni importanti:

  • Nei progetti .NET i file di risorse copiati nella cartella del progetto non vengono indicizzati in F5 se l'app è già stata compilata. Come soluzione alternativa, ricompilare l'app. Per altre informazioni, vedere il problema 1503.

  • Nei progetti .NET, quando un file di risorse viene aggiunto al progetto usando l'interfaccia utente di Visual Studio, i file potrebbero non essere indicizzati per impostazione predefinita. Per altre informazioni, vedere il problema 1786. Per risolvere questo problema, rimuovere le voci seguenti nel file CSPROJ:

    <ItemGroup>
    <Content Remove="<image file name>" />
</ItemGroup>
<ItemGroup>
    <PRIResource Remove="<resw file name>" />
</ItemGroup>

  • Per le app WinUI C++ non incluse nel pacchetto, l'URI della risorsa non viene compilato correttamente. Per risolvere questo problema, aggiungere quanto segue in vcxproj:

    <!-- Add the following after <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> -->

<PropertyGroup>
    <AppxPriInitialPath></AppxPriInitialPath>   
</PropertyGroup>

Per altre informazioni, vedere Gestire le risorse con MRT Core.

Distribuzione

Nuove funzionalità e aggiornamenti:

Limitazioni importanti:

  • Il wrapper .NET per l'API del programma di avvio automatico è destinato solo alle applicazioni .NET senza pacchetti per semplificare l'accesso a Windows App SDK.
  • Solo le app MSIX incluse nel pacchetto con attendibilità totale o che dispongono della funzionalità con restrizioni packageManagement hanno l'autorizzazione per usare l'API di distribuzione per installare le dipendenze del pacchetto Main e Singleton. Il supporto per le app incluse nel pacchetto con attendibilità parziale sarà disponibile nelle versioni successive.
  • Quando F5 testa un'app x86 che usa il metodo DeploymentManager.Initialize in un sistema x64, verificare che il framework x64 sia installato per la prima volta eseguendo WindowsAppRuntimeInstall.exe. In caso contrario, si verifica un errore NOT_FOUND a causa di Visual Studio che non distribuisce il framework x64, il quale in genere si verifica tramite la distribuzione dello Store o il trasferimento locale.

Altre limitazioni e problemi noti

  • Nessun supporto per qualsiasi configurazione di compilazione cpu: quando si aggiunge Windows App SDK a un'applicazione o a un componente .NET esistente che supporta Qualsiasi CPU, è necessario specificare l'architettura desiderata: x86 o x64 arm64.

  • Aggiornamento da .NET 5 a .NET 6: quando si esegue l'aggiornamento nell'interfaccia utente di Visual Studio, è possibile che si verifichino errori di compilazione. Come soluzione alternativa, aggiornare manualmente il file di TargetFrameworkPackage progetto con quanto segue:

      <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>

  • L'app MSIX a progetto singolo C# non viene compilata se gli strumenti UWP C++ non sono installati. Se si dispone di un progetto MSIX a progetto singolo C#, sarà necessario installare il componente facoltativo C++ (v14x) Strumenti per la piattaforma UWP (Universal Windows Platform).

  • Il linguaggio VSIX successivo non viene installato in Visual Studio 2019 quando vengono installate più versioni di Visual Studio 2019. Se sono installate più versioni di Visual Studio 2019 (ad esempio Release e Preview) e quindi si installa Windows App SDK VSIX sia per C++ che per C#, la seconda installazione avrà esito negativo. Per risolvere il problema, disinstallare Strumenti per la creazione di pacchetti MSIX a progetto singolo per Visual Studio 2019 dopo il primo linguaggio VSIX. Visualizzare questo feedback per altre informazioni su questo problema.

  • Un'alternativa a DispatcherQueue.TryEnqueue (per riprendere l'esecuzione nel thread della coda del dispatcher) consiste nell'usare la funzione helper resume_foreground nella Libreria di implementazione di Windows (WIL):

    1. Per prima cosa, aggiungere un riferimento al progetto al pacchetto NuGet Microsoft.Windows.ImplementationLibrary.
    2. Aggiungere #include <wil/cppwinrt_helpers.h> al proprio pch.h.
    3. Aggiungere #include <winrt/Microsoft.UI.Dispatching.h> al proprio pch.h.
    4. Ora co_await wil::resume_foreground(your_dispatcherqueue);.