Een uitgepakte WinUI 3-app distribueren

Met uitgepakte distributie kunt u een WinUI 3-app verzenden zonder MSIX, handig voor bedrijfsscenario's waarbij MSIX-implementatie niet beschikbaar is of voor ontwikkelaars die liever een traditionele installatie op basis van mappen hebben.

Belangrijk

Bekijk deze beperkingen voordat u begint. Uitgepakte WinUI 3-apps hebben beperkingen die van invloed zijn op uw distributiestrategie:

  • No single-file EXE — De Windows App SDK runtime en WinUI 3-afhankelijkheden moeten bestaan als afzonderlijke bestanden. De .NET publicatiefunctie voor één bestand (PublishSingleFile) kan deze niet bundelen in één uitvoerbaar bestand. U distribueert altijd een map met bestanden (of verpakt deze in een traditioneel installatieprogramma zoals WiX of Inno Setup).
  • Runtime-afhankelijkheid: de Windows App SDK runtime moet aanwezig zijn op de computer van de gebruiker. U moet het runtime-installatieprogramma bundelen met uw app of gebruikmaken van zelfstandige implementatie (waardoor de uitvoer aanzienlijk toeneemt). Zie Deploying the Windows App SDK runtime hieronder.
  • No package identity — Zonder een pakketmanifest kan uw app geen op manifest gebaseerde Windows-functies gebruiken: geen automatische updates via app-installatieprogramma of Store, geen registratie van achtergrondtaken en geen koppelingen naar bestandstypen of aanpassing van menutegel starten via pakketmanifest. (Traditionele Win32-mechanismen zoals door het installatieprogramma geschreven registervermeldingen en snelkoppelingen werken nog steeds.)
  • Geen MSIX/pakketidentiteit Store-indiening — Dit distributiemodel heeft geen pakketidentiteit; het komt niet in aanmerking voor MSIX-indiening bij de Microsoft Store. (U kunt een traditioneel installatieprogramma indienen bij de Store via het pad voor het indienen van het MSI- of EXE-installatieprogramma, maar dat is een afzonderlijke werkstroom van wat in dit artikel wordt beschreven.)

Als dit een probleem is, kunt u overwegen om uw app te verpakken (aanbevolen voor de meeste apps) of pakketten met externe locatie om pakketidentiteit toe te voegen zonder een volledige MSIX-conversie.

Zie Voor meer informatie over alle verpakkingsopties de voor- en nadelen van het verpakken van uw app.

Als u ervoor kiest om een nieuwe of bestaande WinUI-app uit te pakken, voert u de volgende stappen uit:

Zoek in het .csproj bestand het eerste bestaande PropertyGroup-element, dat ook , OutputTypeen andere eigenschappen bevatTargetFramework.

  • Voeg de eigenschap WindowsPackageType project toe aan dit element PropertyGroup. Stel de waarde ervan in op None.
<Project ...>
  ...
  <PropertyGroup>
    <WindowsPackageType>None</WindowsPackageType><!-- add this -->
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    ...
  </PropertyGroup> 
  ...
</Project>

Om de app te starten vanuit Visual Studio (met Debugging of Zonder foutopsporing), selecteer het Unpackaged startprofiel in de vervolgkeuzelijst Start. Als het profiel Package is geselecteerd, ziet u een implementatiefout in Visual Studio. Deze stap is niet nodig als u de toepassing (.exe) start vanaf de opdrachtregel of vanuit Windows Verkenner.

Visual Studio - Uitklaplijst openen met niet-verpakt startprofiel voor C#-toepassing gemarkeerd

De bootstrapper-API

Door de projecteigenschap <WindowsPackageType>None</WindowsPackageType> in te stellen, zorgt de auto-initializer ervoor dat een versie van de Windows App SDK wordt gezocht en geladen die het meest geschikt is voor uw app.

Als u geavanceerde behoeften hebt (zoals aangepaste foutafhandeling of om een specifieke versie van de Windows App SDK te laden), kunt u in plaats daarvan de bootstrapper-API expliciet aanroepen. Zie Gebruik de Windows App SDK runtime voor apps die zijn verpakt met externe locatie of uitgepakt en Tutorial: gebruik de bootstrapper-API in een app die is verpakt met externe locatie of uitgepakt die gebruikmaakt van de Windows App SDK.

Zie De implementatiearchitectuur en het overzicht voor frameworkafhankelijke apps voor meer informatie over de bootstrapper.

De Windows App SDK runtime implementeren

Uitgepakte WinUI 3-apps zijn afhankelijk van de Windows App SDK runtime die op de computer van de gebruiker wordt geïnstalleerd. U hebt twee opties om ervoor te zorgen dat de runtime aanwezig is:

Option 1: Windows App SDK runtime-installatieprogramma (.exe) (aanbevolen)

Neem het Windows App SDK runtime-installatieprogramma naast uw app op. Het runtime-installatieprogramma is een herdistribueerbaar .exe waarmee de vereiste Windows App SDK runtimepakketten worden geïnstalleerd. Download deze vanaf de pagina Windows App SDK releases en bundel deze met uw eigen installatie- of installatiescript. Zie Gebruik de Windows App SDK runtime voor apps die zijn verpakt met externe locatie of uitgepakt voor volledige richtlijnen.

Gebruikers moeten het runtime-installatieprogramma eenmaal uitvoeren. Voor volgende app-updates is geen herinstallatie van de runtime vereist, tenzij de vereiste Windows App SDK versie wordt gewijzigd.

Optie 2: Zelfstandige implementatie

Stel <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained> in uw projectbestand in om de Windows App SDK runtime rechtstreeks te bundelen in de uitvoermap van uw app. Hierdoor wordt de runtime-afhankelijkheid verwijderd. Gebruikers hoeven niets afzonderlijk te installeren.

<PropertyGroup>
  <WindowsPackageType>None</WindowsPackageType>
  <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
</PropertyGroup>

De afweging: uw uitvoermap is aanzienlijk groter (de volledige runtime is ingesloten) en bij elke app-update wordt het volledige runtime-pakket meegenomen. Gebruik deze optie voor eenvoudige distributiescenario's of wanneer u niet kunt bepalen wat er op de doelcomputer is geïnstalleerd.

→ Deploy unpackaged apps die gebruikmaken van de Windows App SDK voor de volledige runtime-implementatieverwijzing.

Beperking voor één enkel bestands-EXE

Belangrijk

Uitgepakte WinUI 3-apps kunnen niet worden gepubliceerd als exe met één bestand. De Windows App SDK runtime en verschillende WinUI 3-afhankelijkheden moeten bestaan als afzonderlijke bestanden. De .NET publicatiefunctie voor één bestand kan deze niet bundelen in één uitvoerbaar bestand.

Als een distributie met één bestand belangrijk is voor uw scenario, kunt u de volgende alternatieven overwegen:

  • MSIX-pakketten gebruiken : gebruikers krijgen één installatie-ervaring (App Installer verwerkt alle bestanden) en u krijgt geschiktheid voor Store, pakketidentiteit en ingebouwde updates
  • Gebruik een traditioneel installatieprogramma (WiX, Inno Setup) - verpakt de uitvoermap in één EXE-installatieprogramma waarmee alle vereiste bestanden transparant worden geëxtraheerd en geïnstalleerd
  • Gebruik een ander framework — WPF- en WinForms-apps met dotnet publish --self-contained -p:PublishSingleFile=truecan produceren een EXE met één bestand, hoewel sommige systeemeigen afhankelijkheden mogelijk nog steeds worden geëxtraheerd tijdens runtime

Overwegingen voor distributie voor uitgepakte apps

Uitgepakte WinUI 3-apps hebben geen pakketidentiteit, wat betekent dat ze geen toegang hebben tot bepaalde Windows functies:

  • Geen automatische update via App-installatieprogramma of Windows Store
  • Geen achtergrondtaakregistratie via pakketmanifest
  • Geen bestandstypekoppelingen of protocolhandlers via pakketmanifest
  • Geen aanpassing van Startmenu-tegels via pakketmanifest

Als u deze functies nodig hebt, kunt u overwegen om pakketten te verpakken met een externe locatie als een middelste pad waarmee pakketidentiteit wordt toegevoegd zonder dat een volledige MSIX-conversie is vereist.

→ Publiceer uw eerste Windows-app voor een volledig overzicht van distributieopties voor WinUI 3 en andere Windows app-frameworks.

  • Last updated on