Dystrybuowanie rozpakowanej aplikacji WinUI 3

Rozpakowana dystrybucja umożliwia dostarczanie aplikacji WinUI 3 bez pliku MSIX — przydatne w scenariuszach dla przedsiębiorstw, w których wdrożenie MSIX nie jest dostępne, lub dla deweloperów, którzy preferują tradycyjną instalację opartą na folderach.

Ważna

Przed rozpoczęciem zapoznaj się z tymi ograniczeniami. Rozpakowane aplikacje WinUI 3 mają ograniczenia wpływające na strategię dystrybucji:

  • Pojedynczy plik EXE — niepakietowane, autonomiczne aplikacje WinUI 3 obsługują PublishSingleFile (Zestaw SDK do aplikacji systemu Windows 1.5 i nowsze wersje). Powoduje to utworzenie pojedynczego pliku EXE dystrybucyjnego; zależności są wyodrębniane do katalogu tymczasowego podczas pierwszego uruchamiania. Wymagane są określone właściwości programu MSBuild — zobacz plik EXE z pojedynczym plikiem poniżej. Aplikacje zależne od platformy .NET i aplikacje spakietowane nie obsługują PublishSingleFile.
  • Zależność czasu wykonywania — środowisko uruchomieniowe Zestaw SDK do aplikacji systemu Windows musi być zainstalowane na komputerze użytkownika. Musisz powiązać instalatora środowiska uruchomieniowego z aplikacją lub użyć wdrożenia samodzielnego (co znacznie zwiększa rozmiar danych wyjściowych). Zobacz Deploying the Zestaw SDK do aplikacji systemu Windows runtime poniżej.
  • Brak tożsamości pakietu — bez manifestu pakietu aplikacja nie może korzystać z funkcji systemu Windows opartych na manifeście: brak automatycznych aktualizacji za pośrednictwem Instalatora aplikacji lub Sklepu, brak rejestracji zadań w tle oraz brak skojarzeń typów plików ani możliwości dostosowywania kafelka menu Start za pośrednictwem manifestu pakietu. (Tradycyjne mechanizmy Win32, takie jak wpisy rejestru napisane przez instalatora i skróty, nadal działają).
  • No przesyłanie pliku MSIX/package-identity Store — ten model dystrybucji nie ma tożsamości pakietu; nie kwalifikuje się do przesłania pliku MSIX do Microsoft Store. (Możesz przesłać tradycyjny instalator do Sklepu za pośrednictwem ścieżki przesyłania instalatora MSI lub EXE, ale jest to oddzielny przepływ pracy od tego, co opisano w tym artykule).

Jeśli te ograniczenia są problemem, rozważ spakowanie aplikacji (zalecane dla większości aplikacji) lub pakowanie z lokalizacją zewnętrzną w celu dodania tożsamości pakietu bez pełnej konwersji MSIX.

Aby uzyskać szczegółowe informacje na temat wszystkich opcji tworzenia pakietów, zobacz Artykuł Package and deploy Windows apps overview (Tworzenie pakietów i wdrażanie aplikacji Windows — omówienie).

Jeśli zdecydujesz się rozpakować nową lub istniejącą aplikację WinUI, wykonaj następujące kroki:

.csproj W pliku znajdź pierwszy istniejący element PropertyGroup, który zawiera również OutputType, TargetFramework i inne właściwości.

  • Dodaj właściwość WindowsPackageType project do tego elementu PropertyGroup. Ustaw jej wartość na wartość None.
<Project ...>
  ...
  <PropertyGroup>
    <WindowsPackageType>None</WindowsPackageType><!-- add this -->
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    ...
  </PropertyGroup> 
  ...
</Project>

Aby uruchomić aplikację z Visual Studio (Debugging lub Bez debugowania), wybierz profil uruchamiania Unpackaged z listy rozwijanej Start. Jeśli wybrano profil Package, w Visual Studio zostanie wyświetlony błąd wdrożenia. Ten krok nie jest konieczny, jeśli uruchomisz aplikację (.exe) z wiersza polecenia lub w Eksploratorze plików Windows.

Visual Studio — rozpocznij pracę z wyróżnionym profilem uruchamiania rozpakowanego w języku C#

Interfejs API programu inicjjącego

Ustawienie właściwości projektu <WindowsPackageType>None</WindowsPackageType> spowoduje, że auto-initializer zlokalizuje i załaduje wersję Zestaw SDK do aplikacji systemu Windows, która jest najbardziej odpowiednia dla Twojej aplikacji.

Jeśli masz zaawansowane potrzeby (takie jak niestandardowa obsługa błędów lub ładowanie określonej wersji Zestaw SDK do aplikacji systemu Windows), możesz jawnie wywołać interfejs API programu inicjatora. Aby uzyskać więcej informacji, zobacz Użyj środowiska uruchomieniowego Zestaw SDK do aplikacji systemu Windows dla aplikacji spakowanych z lokalizacją zewnętrzną lub niespakowanych, oraz Samouczek: Użyj interfejsu API programu inicjatora w aplikacji spakowanej z lokalizacją zewnętrzną lub niespakowanej, która używa Zestaw SDK do aplikacji systemu Windows.

Aby uzyskać więcej informacji na temat programu rozruchowego, zobacz Architektura wdrażania i omówienie aplikacji zależnych od platformy.

Wdrażanie środowiska uruchomieniowego Zestaw SDK do aplikacji systemu Windows

Rozpakowane aplikacje WinUI 3 zależą od środowiska uruchomieniowego Zestaw SDK do aplikacji systemu Windows instalowanego na komputerze użytkownika. Dostępne są dwie opcje zapewnienia, że środowisko uruchomieniowe jest obecne:

Option 1: instalator środowiska uruchomieniowego Zestaw SDK do aplikacji systemu Windows (.exe) (zalecane)

Dołącz instalatora środowiska uruchomieniowego Zestaw SDK do aplikacji systemu Windows obok aplikacji. Instalator środowiska uruchomieniowego jest pakietem redystrybucyjnym .exe, który instaluje wymagane pakiety środowiska uruchomieniowego Zestaw SDK do aplikacji systemu Windows. Pobierz go ze strony wydań Zestaw SDK do aplikacji systemu Windows i dołącz go do własnego instalatora lub skryptu instalacyjnego. Aby uzyskać pełne wskazówki, zapoznaj się z Użyj środowiska uruchomieniowego Zestaw SDK do aplikacji systemu Windows dla aplikacji zapakowanych z zewnętrzną lokalizacją lub nieopakowanych.

Użytkownicy muszą uruchomić instalatora środowiska uruchomieniowego raz. Kolejne aktualizacje aplikacji nie wymagają ponownej instalacji środowiska uruchomieniowego, chyba że zmieni się wymagana wersja Zestaw SDK do aplikacji systemu Windows.

Opcja 2. Samodzielne wdrażanie

Ustaw <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained> w pliku projektu, aby powiązać środowisko uruchomieniowe Zestaw SDK do aplikacji systemu Windows bezpośrednio z folderem wyjściowym aplikacji. Spowoduje to usunięcie zależności środowiska uruchomieniowego — użytkownicy nie muszą instalować niczego oddzielnie.

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

Kompromis: folder wyjściowy jest znacznie większy (uwzględniane jest pełne środowisko uruchomieniowe), a każda aktualizacja aplikacji niesie ze sobą pełny ładunek środowiska uruchomieniowego. Użyj tej opcji w przypadku prostych scenariuszy dystrybucji lub gdy nie możesz kontrolować tego, co jest zainstalowane na maszynie docelowej.

→ Upakowywanie rozpakowanych aplikacji korzystających z Zestaw SDK do aplikacji systemu Windows w celu uzyskania pełnej dokumentacji wdrożenia środowiska uruchomieniowego.

Jednoplikowy plik EXE

Począwszy od wersji Zestaw SDK do aplikacji systemu Windows 1.5, niepakietowane, autonomiczne aplikacje WinUI 3 obsługują model wdrażania .NET PublishSingleFile. Spowoduje to utworzenie pojedynczego pliku EXE dystrybucyjnego — wszystkie zależności są połączone z plikiem EXE i wyodrębnione do katalogu tymczasowego podczas pierwszego uruchomienia.

Ważna

PublishSingleFile nie jest obsługiwane w przypadku aplikacji spakietowanych (MSIX lub spakietowanych z lokalizacją zewnętrzną) ani aplikacji zależnych od środowiska uruchomieniowego. Oba warunki — niepakietowane i samodzielne — są wymagane.

Wymagane właściwości programu MSBuild

Zestaw SDK do aplikacji systemu Windows zawiera cel walidacji w czasie kompilacji (WindowsAppSDKSingleFileVerifyConfiguration), który sprawdza konfigurację projektu, gdy ustawiono PublishSingleFile. Wymagane są następujące właściwości:

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

Kompilacja zgłasza błędy, jeśli brakuje EnableMsixTooling, WindowsPackageType=None lub IncludeAllContentForSelfExtract, oraz WindowsAppSDKSelfContained, jeśli brakuje SelfContained lub .

Note

Sposób rozpakowywania:IncludeAllContentForSelfExtract=true oznacza, że zależności są rozpakowywane do katalogu tymczasowego na komputerze użytkownika przy pierwszym uruchomieniu — aplikacja nie jest plikiem binarnym niewymagającym rozpakowywania. Pojedynczy plik EXE jest wygodny do dystrybucji, ale wyodrębnione pliki muszą być obecne do uruchomienia. Automatyczny inicjalizator WindowsAppSdkUndockedRegFreeWinRTInitialize odpowiada za lokalizowanie wyodrębnionego środowiska wykonawczego; jeśli z niego zrezygnujesz, musisz ustawić zmienną środowiskową MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY na wartość AppContext.BaseDirectory przed uruchomieniem programu.

Alternatywy, jeśli wyodrębnianie pojedynczego pliku jest niedopuszczalne

Jeśli potrzebujesz pojedynczego pliku binarnego niewymagającego rozpakowywania lub jeśli sposób rozpakowywania nie jest akceptowalny w Twoim środowisku wdrożeniowym, rozważ:

  • Korzystanie z pakietu MSIX — użytkownicy uzyskują jedno środowisko instalatora (Instalator aplikacji obsługuje wszystkie pliki) i uzyskujesz uprawnienia do sklepu, tożsamość pakietu i wbudowane aktualizacje
  • Użyj tradycyjnego instalatora (WiX, Inno Setup) — zawijaj folder wyjściowy w jednym instalatorze EXE, który wyodrębnia i instaluje wszystkie wymagane pliki w przezroczysty sposób
  • Użyj innego środowiska — aplikacje WPF i WinForms obsługują PublishSingleFile w szerszym zakresie konfiguracji

Zagadnienia dotyczące dystrybucji dla niezapakowanych aplikacji

Rozpakowane aplikacje WinUI 3 nie mają tożsamości pakietu, co oznacza, że nie mogą uzyskać dostępu do niektórych funkcji Windows:

  • Brak automatycznej aktualizacji za pośrednictwem Instalatora aplikacji lub Microsoft Store
  • Brak rejestracji zadań w tle za pośrednictwem manifestu pakietu
  • Brak skojarzeń typów plików ani procedur obsługi protokołów za pośrednictwem manifestu pakietu
  • Brak możliwości dostosowywania kafelka menu Start przez manifest pakietu

Jeśli potrzebujesz tych funkcji, rozważ pakowanie z lokalizacją zewnętrzną jako ścieżką środkową, która dodaje tożsamość pakietu bez konieczności pełnej konwersji MSIX.

Opublikuj swoją pierwszą aplikację Windows aby uzyskać pełny przegląd opcji dystrybucji dla WinUI 3 i innych platform aplikacji Windows.

  • Last updated on