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:

  • EXE met één bestand - Uitgepakt, zelfstandige WinUI 3-apps ondersteunen PublishSingleFile (Windows App SDK 1.5 en hoger). Dit produceert één distribueerbaar EXE; afhankelijkheden worden bij de eerste lancering geëxtraheerd naar een tijdelijke map. Specifieke MSBuild-eigenschappen zijn vereist. Zie EXE met één bestand hieronder. Frameworkafhankelijke apps en verpakte apps ondersteunen PublishSingleFile niet.
  • 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 Het overzicht van Windows apps verpakken en implementeren voor meer informatie over alle verpakkingsopties.

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.

éénbestands-EXE

Beginnend met Windows App SDK 1.5, uitgepakte, zelfstandige WinUI 3-apps ondersteunen het .NET PublishSingleFile implementatiemodel. Dit produceert één distribueerbaar EXE-bestand: alle afhankelijkheden worden gebundeld in de EXE en geëxtraheerd naar een tijdelijke map bij de eerste lancering.

Belangrijk

PublishSingleFile wordt niet ondersteund voor verpakte apps (MSIX of verpakt met externe locatie) of voor frameworkafhankelijke apps. Beide voorwaarden ( uitgepakt en zelfstandig) zijn vereist.

Vereiste MSBuild-eigenschappen

De Windows App SDK bevat een build-time validatiedoel (WindowsAppSDKSingleFileVerifyConfiguration) dat uw projectconfiguratie controleert wanneer PublishSingleFile deze is ingesteld. De volgende eigenschappen zijn vereist:

<PropertyGroup>
  <WindowsPackageType>None</WindowsPackageType>
  <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
  <SelfContained>true</SelfContained>
  <EnableMsixTooling>true</EnableMsixTooling>
  <IncludeAllContentForSelfExtract>true</IncludeAllContentForSelfExtract>
  <PublishSingleFile>true</PublishSingleFile>
</PropertyGroup>

De build geeft fouten als EnableMsixTooling, WindowsPackageType=None of IncludeAllContentForSelfExtract ontbreken, en waarschuwingen als WindowsAppSDKSelfContained of SelfContained ontbreken.

Note

Extractiegedrag:IncludeAllContentForSelfExtract=true betekent dat afhankelijkheden worden geëxtraheerd naar een tijdelijke map op de computer van de gebruiker bij de eerste start. De app is geen binair bestand met nulextractie. De enkele EXE is handig om te distribueren, maar de geëxtraheerde bestanden moeten aanwezig zijn om uit te voeren. De WindowsAppSdkUndockedRegFreeWinRTInitialize automatische initialisatiefunctie zorgt ervoor dat de geëxtraheerde runtime wordt gezocht. Als u zich ervoor afmeldt, moet u de MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY omgevingsvariabele AppContext.BaseDirectory instellen op vóór de programmavermelding.

Alternatieven als extractie van één bestand niet acceptabel is

Als u één binair bestand met nulextractie nodig hebt of als extractiegedrag niet acceptabel is in uw implementatieomgeving, kunt u het volgende 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
  • Een ander framework gebruiken: ondersteuning voor WPF- en WinForms-apps PublishSingleFile met een bredere set configuraties

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