Einrichten einer kontinuierlichen Integration für Ihre WinUI-App

Sie können GitHub-Aktionen verwenden, um fortlaufende Integrationsbuilds für WinUI-Projekte einzurichten. In diesem Artikel befassen wir uns mit verschiedenen Möglichkeiten, dies zu tun. Außerdem zeigen wir Ihnen, wie Sie diese Aufgaben mithilfe der Befehlszeile ausführen, damit Sie in jedes andere Buildsystem integriert werden können.

Voraussetzungen

Schritt 1: Einrichten Ihres Zertifikats

MSIX-Apps müssen angemeldet sein, um installiert zu werden. Falls Sie bereits über ein Zertifikat verfügen, können Sie diesen Schritt überspringen. Sie können ganz einfach ein Testzertifikat erstellen, indem Sie Ihre App in Visual Studio öffnen, mit der rechten Maustaste auf Ihr WinUI-Projekt klicken und "Package and Publish ->Create App Packages" auswählen.

Wählen Sie dann Weiter aus, um zur Signaturmethode Seite zu wechseln, und klicken Sie auf die Schaltfläche Erstellen..., um ein neues Zertifikat zu erstellen. Wählen Sie den Herausgebernamen aus, und das Kennwortfeldleer lassen und das Zertifikat erstellen.

Schließen/abbrechen Sie dann die Dialogfelder, und beachten Sie, dass in Ihrem Projekt eine neue PFX- Datei erstellt wurde. Dies ist das Zertifikat, mit dem Sie Ihren MSIX signieren können!

Schritt 2: Fügen Sie Ihr Zertifikat zu den Geheimnissen der Aktionen hinzu

Sie sollten die Übermittlung von Zertifikaten an Ihr Repository vermeiden, wenn möglich, und Git ignoriert sie standardmäßig. Um die sichere Behandlung vertraulicher Dateien wie Zertifikate zu verwalten, unterstützt GitHub geheimen Schlüssel.

So laden Sie ein Zertifikat für Ihren automatisierten Build hoch:

  1. Codieren Sie Ihr Zertifikat als Base 64-Zeichenfolge: Öffnen Sie PowerShell in das Verzeichnis, das Ihr Zertifikat enthält, und führen Sie den folgenden Befehl aus, und ersetzen Sie den PFX-Dateinamen durch den Dateinamen Ihres Zertifikats.
$pfx_cert = Get-Content 'App1_TemporaryKey.pfx' -AsByteStream

[System.Convert]::ToBase64String($pfx_cert) | Out-File 'App1_TemporaryKey_Base64.txt'
  1. Wechseln Sie in Ihrem GitHub-Repository zur Seite Einstellungen, und klicken Sie links auf Geheime Schlüssel.
  2. Klicken Sie auf Neuen Repositoryschlüssel, nennen Sie ihn BASE64_ENCODED_PFX, und kopieren/einfügen Sie den Text aus der Textdatei in der PowerShell-Ausgabe in den geheimen Wert.

Schritt 3: Einrichten ihres Workflows

Wechseln Sie als Nächstes in Ihrem Repository zur Registerkarte "Aktionen", und erstellen Sie einen neuen Workflow. Wählen Sie die Option einen Workflow selbst einrichten anstelle einer der Workflowvorlagen.

Kopieren/fügen Sie Folgendes in Ihre Workflowdatei ein, und aktualisieren Sie dann...

  1. Solution_Name als Name Ihrer Lösung
  2. dotnet-version to 8.0.x (oder die .NET-Version, auf die Ihr Projekt abzielt)

Hinweis

Ersetzen Sie im Schritt, in dem das Artefakt hochgeladen wird (der letzte Schritt unten), env.Solution_Name durch github.workspace (Ordner "GitHub Actions Workspace"), wenn die Buildausgabe nicht in einem Ordner landet, der Ihre Lösung enthält.

# This workflow will build, sign, and package a WinUI MSIX desktop application
# built on .NET.

name: WinUI MSIX app

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:

  build:

    strategy:
      matrix:
        configuration: [Release]
        platform: [x64, x86]

    runs-on: windows-latest  # For a list of available runner types, refer to
                             # https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on

    env:
      Solution_Name: your-solution-name                         # Replace with your solution name, i.e. App1.sln.

    steps:
    - name: Checkout
      uses: actions/checkout@v4
      with:
        fetch-depth: 0

    # Install the .NET workload
    - name: Install .NET
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: 8.0.x

    # Add  MSBuild to the PATH: https://github.com/microsoft/setup-msbuild
    - name: Setup MSBuild.exe
      uses: microsoft/setup-msbuild@v2

    # Restore the application to populate the obj folder with RuntimeIdentifiers
    - name: Restore the application
      run: msbuild $env:Solution_Name /t:Restore /p:Configuration=$env:Configuration
      env:
        Configuration: ${{ matrix.configuration }}

    # Decode the base 64 encoded pfx and save the Signing_Certificate
    - name: Decode the pfx
      run: |
        $pfx_cert_byte = [System.Convert]::FromBase64String("${{ secrets.BASE64_ENCODED_PFX }}")
        $certificatePath = "GitHubActionsWorkflow.pfx"
        [IO.File]::WriteAllBytes("$certificatePath", $pfx_cert_byte)

    # Create the app package by building and packaging the project
    - name: Create the app package
      run: msbuild $env:Solution_Name /p:Configuration=$env:Configuration /p:Platform=$env:Platform /p:UapAppxPackageBuildMode=$env:Appx_Package_Build_Mode /p:AppxBundle=$env:Appx_Bundle /p:PackageCertificateKeyFile=GitHubActionsWorkflow.pfx /p:AppxPackageDir="$env:Appx_Package_Dir" /p:GenerateAppxPackageOnBuild=true
      env:
        Appx_Bundle: Never
        Appx_Package_Build_Mode: SideloadOnly
        Appx_Package_Dir: Packages\
        Configuration: ${{ matrix.configuration }}
        Platform: ${{ matrix.platform }}

    # Remove the pfx
    - name: Remove the pfx
      run: Remove-Item -path GitHubActionsWorkflow.pfx

    # Upload the MSIX package: https://github.com/marketplace/actions/upload-a-build-artifact
    - name: Upload MSIX package
      uses: actions/upload-artifact@v4
      with:
        name: MSIX Package - ${{ matrix.platform }}
        path: ${{ env.Solution_Name }}\\Packages

Schritt 4: Bestätigen Sie den Workflow und beobachten Sie seine Ausführung!

Übertragen Sie die Workflow-Datei in Ihren Hauptbranch, wechseln Sie dann zur Registerkarte "Aktionen" in Ihrem GitHub-Repository und beobachten Sie, wie der Workflow ausgeführt wird! Sie sollte erfolgreich ausgeführt werden und Artefakte erstellen, die Ihre integrierte MSIX-App enthalten.

Kompilieren über die Befehlszeile

Wenn Sie Ihre Lösung mithilfe der Befehlszeile oder eines anderen CI-Systems erstellen möchten, führen Sie MSBuild mit diesen Argumenten aus. Die GenerateAppxPackageOnBuild Eigenschaft bewirkt, dass das MSIX-Paket generiert wird.

/p:AppxPackageDir="Packages"
/p:UapAppxPackageBuildMode=SideloadOnly
/p:AppxBundle=Never
/p:GenerateAppxPackageOnBuild=true

Schritt 1: Einrichten ihres Workflows

Wechseln Sie in Ihrem GitHub-Repository zur Registerkarte "Aktionen", und erstellen Sie einen neuen Workflow. Wählen Sie die Option einen Workflow selbst einrichten anstelle einer der Workflowvorlagen.

Kopieren/fügen Sie Folgendes in Ihre Workflowdatei ein, und aktualisieren Sie dann...

  1. Solution_Name als Name Ihrer Lösung
  2. dotnet-version bis 8.0.x (oder die .NET-Version, auf die Ihr Projekt abzielt)

Hinweis

Ersetzen Sie im Schritt, in dem das Artefakt hochgeladen wird (der letzte Schritt unten), env.Solution_Name durch github.workspace (Ordner "GitHub Actions Workspace"), wenn die Buildausgabe nicht in einem Ordner landet, der Ihre Lösung enthält.

# This workflow will build and publish a WinUI unpackaged desktop application
# built on .NET.

name: WinUI unpackaged app

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:

  build:

    strategy:
      matrix:
        configuration: [Release]
        platform: [x64, x86]

    runs-on: windows-latest  # For a list of available runner types, refer to
                             # https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on

    env:
      Solution_Name: your-solution-name                         # Replace with your solution name, i.e. App1.sln.

    steps:
    - name: Checkout
      uses: actions/checkout@v4
      with:
        fetch-depth: 0

    # Install the .NET workload
    - name: Install .NET
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: 8.0.x

    # Add  MSBuild to the PATH: https://github.com/microsoft/setup-msbuild
    - name: Setup MSBuild.exe
      uses: microsoft/setup-msbuild@v2

    # Restore the application to populate the obj folder with RuntimeIdentifiers
    - name: Restore the application
      run: msbuild $env:Solution_Name /t:Restore /p:Configuration=$env:Configuration
      env:
        Configuration: ${{ matrix.configuration }}

    # Create the app by building and publishing the project
    - name: Create the app
      run: msbuild $env:Solution_Name /t:Publish /p:Configuration=$env:Configuration /p:Platform=$env:Platform
      env:
        Configuration: ${{ matrix.configuration }}
        Platform: ${{ matrix.platform }}

    # Upload the app
    - name: Upload app
      uses: actions/upload-artifact@v4
      with:
        name: Upload app - ${{ matrix.platform }}
        path: ${{ env.Solution_Name }}\\bin

Schritt 2: Übernehmen Sie den Workflow, und beobachten Sie, wie er abläuft!

Übertragen Sie die Workflow-Datei in Ihren Hauptbranch, wechseln Sie dann zur Registerkarte "Aktionen" in Ihrem GitHub-Repository und beobachten Sie, wie der Workflow ausgeführt wird! Sie sollte erfolgreich ausgeführt werden und Artefakte erstellen, die Ihre integrierte App enthalten.

Kompilieren über die Befehlszeile

Wenn Sie Ihre Lösung mithilfe der Befehlszeile oder eines anderen CI-Systems erstellen möchten, führen Sie MSBuild mit dem /t:Publish Argument aus.

Azure Pipelines

Wenn Ihr Team Azure DevOps verwendet, können Sie WinUI 3-Apps mit Azure Pipelines erstellen. Die folgende YAML-Pipeline erstellt eine verpackte MSIX WinUI-App auf einem Windows-Agent:

trigger:
  - main

pool:
  vmImage: 'windows-latest'

variables:
  solution: '**/*.sln'
  buildPlatform: 'x64'
  buildConfiguration: 'Release'

steps:
- task: UseDotNet@2
  displayName: 'Install .NET SDK'
  inputs:
    packageType: 'sdk'
    version: '8.0.x'

- task: NuGetToolInstaller@1

- task: NuGetCommand@2
  inputs:
    restoreSolution: '$(solution)'

- task: VSBuild@1
  displayName: 'Build MSIX package'
  inputs:
    solution: '$(solution)'
    platform: '$(buildPlatform)'
    configuration: '$(buildConfiguration)'
    msbuildArgs: |
      /p:AppxBundlePlatforms="$(buildPlatform)"
      /p:AppxPackageDir="$(Build.ArtifactStagingDirectory)\AppxPackages\\"
      /p:AppxBundle=Never
      /p:UapAppxPackageBuildMode=SideloadOnly
      /p:GenerateAppInstallerFile=false

- task: PublishBuildArtifacts@1
  displayName: 'Publish MSIX artifacts'
  inputs:
    PathtoPublish: '$(Build.ArtifactStagingDirectory)\AppxPackages'
    ArtifactName: 'msix-package'

Hinweis

Entfernen Sie bei entpackten Builds die /p:Appx* MSBuild-Argumente, und verwenden Sie dotnet publish anstelle von VSBuild. Ausführliche Informationen finden Sie im obigen Befehlszeilenabschnitt.

Zum Signieren von MSIX-Paketen in einer Pipeline speichern Sie Ihr Zertifikat in Azure Pipelines sicheren Dateien, und verwenden Sie die DownloadSecureFile-Aufgabe, um während des Builds darauf zuzugreifen.

Important

Speichern Sie niemals Signaturzertifikate oder deren Kennwörter in der Quellcodeverwaltung. Verwenden Sie Pipelineschlüsselvariablen für das Zertifikatkennwort und Azure Pipelines Sichere Dateien für das Zertifikat selbst.

  • Last updated on