Freigeben über

Herunterladen und Installieren von Paketupdates aus dem Store

Ab Windows 10, Version 1607, können Sie Methoden der StoreContext Klasse im Windows.Services.Store Namespace verwenden, um programmgesteuert nach Paketupdates für die aktuelle App aus dem Microsoft Store zu suchen und die aktualisierten Pakete herunterzuladen und zu installieren. Sie können auch Pakete abfragen, die Sie im Partner Center als obligatorisch gekennzeichnet haben, und Funktionen in Ihrer App deaktivieren, bis das obligatorische Update installiert ist.

Zusätzliche StoreContext- Methoden, die in Windows 10, Version 1803 eingeführt wurden, ermöglichen es Ihnen, Paketupdates im Hintergrund herunterzuladen und zu installieren (ohne dem Benutzer eine Benachrichtigungsbenutzeroberfläche anzuzeigen), einen optionalen Paket-zu deinstallieren und Informationen zu Paketen in der Download- und Installationswarteschlange für Ihre App zu erhalten.

Diese Features helfen Ihnen, Ihre Benutzerbasis automatisch auf dem neuesten Stand zu halten, mit der neuesten Version Ihrer App, optionalen Paketen und zugehörigen Diensten im Store.

Herunterladen und Installieren von Paketupdates mit der Berechtigung des Benutzers

In diesem Codebeispiel wird veranschaulicht, wie Sie mit der GetAppAndOptionalStorePackageUpdatesAsync--Methode alle verfügbaren Paketupdates aus dem Store ermitteln und dann die RequestDownloadAndInstallStorePackageUpdatesAsync- Methode aufrufen, um die Updates herunterzuladen und zu installieren. Wenn Sie diese Methode zum Herunterladen und Installieren von Updates verwenden, zeigt das Betriebssystem ein Dialogfeld an, das die Berechtigung des Benutzers vor dem Herunterladen der Updates anfragt.

Hinweis

Diese Methoden unterstützen erforderliche und optionale Pakete für Ihre App. Optionale Pakete sind nützlich für Download-Content-Add-Ons (DLC), um Ihre große App aufgrund von Größenbeschränkungen aufzuteilen oder um zusätzliche Inhalte bereitzustellen, die von Ihrer Kern-App getrennt sind. Wie Sie die Berechtigung zum Einreichen einer App, die optionale Pakete (einschließlich DLC-Add-Ons) im Store verwendet, erhalten, erfahren Sie unter Windows-Entwicklersupport.

In diesem Codebeispiel wird davon ausgegangen:

  • Der Code wird im Kontext einer Seiteausgeführt.
  • Die Seite enthält einen Fortschrittsbalken namens downloadProgressBar zur Bereitstellung des Status für den Downloadvorgang.
  • Die Codedatei verfügt über eine mit-Anweisung für die Windows.Services.Store, Windows.Threading.Tasksund Windows.UI.Popups Namespaces.
  • Die App ist eine Einzelbenutzer-App, die nur im Kontext des Benutzers ausgeführt wird, der die App gestartet hat. Verwenden Sie für eine Mehrbenutzer-Appdie Methode GetForUser, um ein StoreContext-Objekt abzurufen, anstelle der Methode GetDefault.
private StoreContext context = null;

public async Task DownloadAndInstallAllUpdatesAsync()
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
    }

    // Get the updates that are available.
    IReadOnlyList<StorePackageUpdate> updates =
        await context.GetAppAndOptionalStorePackageUpdatesAsync();

    if (updates.Count > 0)
    {
        // Alert the user that updates are available and ask for their consent
        // to start the updates.
        MessageDialog dialog = new MessageDialog(
            "Download and install updates now? This may cause the application to exit.", "Download and Install?");
        dialog.Commands.Add(new UICommand("Yes"));
        dialog.Commands.Add(new UICommand("No"));
        IUICommand command = await dialog.ShowAsync();

        if (command.Label.Equals("Yes", StringComparison.CurrentCultureIgnoreCase))
        {
            // Download and install the updates.
            IAsyncOperationWithProgress<StorePackageUpdateResult, StorePackageUpdateStatus> downloadOperation =
                context.RequestDownloadAndInstallStorePackageUpdatesAsync(updates);

            // The Progress async method is called one time for each step in the download
            // and installation process for each package in this request.
            downloadOperation.Progress = async (asyncInfo, progress) =>
            {
                await this.Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal,
                () =>
                {
                    downloadProgressBar.Value = progress.PackageDownloadProgress;
                });
            };

            StorePackageUpdateResult result = await downloadOperation.AsTask();
        }
    }
}

Hinweis

Um nur die verfügbaren Paketupdates herunterzuladen (aber nicht zu installieren), verwenden Sie die RequestDownloadStorePackageUpdatesAsync--Methode.

Anzeigen von Download- und Installationsstatusinformationen

Wenn Sie die RequestDownloadStorePackageUpdatesAsync- oder RequestDownloadAndInstallStorePackageUpdatesAsync-Methode aufrufen, können Sie einen Progress-Handler zuweisen, der für jeden Schritt im Downloadprozess (oder Download und Installation) für jedes Paket in dieser Anforderung einmal aufgerufen wird. Der Handler empfängt ein StorePackageUpdateStatus--Objekt, das Informationen über das Updatepaket liefert, das die Fortschrittsbenachrichtigung ausgelöst hat. Im vorherigen Beispiel wird das PackageDownloadProgress Feld des StorePackageUpdateStatus- Objekts verwendet, um den Fortschritt des Download- und Installationsprozesses anzuzeigen.

Beachten Sie, dass, wenn Sie RequestDownloadAndInstallStorePackageUpdatesAsync aufrufen, um Paketupdates in einem einzigen Vorgang herunterzuladen und zu installieren, sich das Feld PackageDownloadProgress während des Herunterladens eines Pakets von 0,0 auf 0,8 erhöht und während der Installation von 0,8 auf 1,0. Daher, wenn Sie den in der benutzerdefinierten Fortschrittsanzeige angezeigten Prozentsatz direkt dem Wert des Felds PackageDownloadProgress zuordnen, zeigt Ihre Benutzeroberfläche 80% an, sobald das Herunterladen des Pakets abgeschlossen ist und das Betriebssystem das Installationsdialogfeld anzeigt. Wenn die benutzerdefinierte Fortschrittsanzeige 100% anzeigen soll, wenn das Paket heruntergeladen ist und bereit zur Installation, können Sie den Code so ändern, dass 100% auf die Fortschrittsanzeige angewendet wird, wenn das PackageDownloadProgress Feld 0,8 erreicht.

Herunterladen und Installieren von Paketupdates stillschweigend

Ab Windows 10, Version 1803, können Sie die TrySilentDownloadStorePackageUpdatesAsync- und TrySilentDownloadAndInstallStorePackageUpdatesAsync-Methoden verwenden, um Paketupdates im Hintergrund herunterzuladen und zu installieren, ohne dem Benutzer eine Benutzeroberfläche für Benachrichtigungen anzuzeigen. Dieser Vorgang wird nur erfolgreich ausgeführt, wenn der Benutzer die Einstellung Apps automatisch aktualisieren im Store aktiviert hat und sich nicht in einer getakteten Datenverbindung befindet. Bevor Sie diese Methoden aufrufen, können Sie zuerst die CanSilentlyDownloadStorePackageUpdates-Eigenschaft überprüfen, um zu ermitteln, ob diese Bedingungen derzeit erfüllt sind.

In diesem Codebeispiel wird veranschaulicht, wie Sie mit der GetAppAndOptionalStorePackageUpdatesAsync- Methode alle verfügbaren Paketupdates ermitteln und dann die TrySilentDownloadStorePackageUpdatesAsync- und TrySilentDownloadAndInstallStorePackageUpdatesAsync- Methoden aufrufen, um die Updates lautlos herunterzuladen und zu installieren.

In diesem Codebeispiel wird davon ausgegangen:

  • Die Codedatei verfügt über eine mit-Anweisung für die Namespaces Windows.Services.Store und System.Threading.Tasks.
  • Die App ist eine Einzelbenutzer-App, die nur im Kontext des Benutzers ausgeführt wird, der die App gestartet hat. Verwenden Sie für eine Mehrbenutzer-Appdie Methode GetForUser, um ein StoreContext-Objekt abzurufen, anstelle der Methode GetDefault.

Hinweis

Die IsNowAGoodTimeToRestartApp, RetryDownloadAndInstallLaterund RetryInstallLater Methoden, die vom Code in diesem Beispiel aufgerufen werden, sind Platzhaltermethoden, die bei Bedarf entsprechend dem Design Ihrer eigenen App implementiert werden sollen.

private StoreContext context = null;

public async Task DownloadAndInstallAllUpdatesInBackgroundAsync()
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
    }

    // Get the updates that are available.
    IReadOnlyList<StorePackageUpdate> storePackageUpdates =
        await context.GetAppAndOptionalStorePackageUpdatesAsync();

    if (storePackageUpdates.Count > 0)
    {

        if (!context.CanSilentlyDownloadStorePackageUpdates)
        {
            return;
        }

        // Start the silent downloads and wait for the downloads to complete.
        StorePackageUpdateResult downloadResult =
            await context.TrySilentDownloadStorePackageUpdatesAsync(storePackageUpdates);

        switch (downloadResult.OverallState)
        {
            case StorePackageUpdateState.Completed:
                // The download has completed successfully. At this point, confirm whether your app
                // can restart now and then install the updates (for example, you might only install
                // packages silently if your app has been idle for a certain period of time). The
                // IsNowAGoodTimeToRestartApp method is not implemented in this example, you should
                // implement it as needed for your own app.
                if (IsNowAGoodTimeToRestartApp())
                {
                    await InstallUpdate(storePackageUpdates);
                }
                else
                {
                    // Retry/reschedule the installation later. The RetryInstallLater method is not  
                    // implemented in this example, you should implement it as needed for your own app.
                    RetryInstallLater();
                    return;
                }
                break;
            // If the user cancelled the download or you can't perform the download for some other
            // reason (for example, Wi-Fi might have been turned off and the device is now on
            // a metered network) try again later. The RetryDownloadAndInstallLater method is not  
            // implemented in this example, you should implement it as needed for your own app.
            case StorePackageUpdateState.Canceled:
            case StorePackageUpdateState.ErrorLowBattery:
            case StorePackageUpdateState.ErrorWiFiRecommended:
            case StorePackageUpdateState.ErrorWiFiRequired:
            case StorePackageUpdateState.OtherError:
                RetryDownloadAndInstallLater();
                return;
            default:
                break;
        }
    }
}

private async Task InstallUpdate(IReadOnlyList<StorePackageUpdate> storePackageUpdates)
{
    // Start the silent installation of the packages. Because the packages have already
    // been downloaded in the previous method, the following line of code just installs
    // the downloaded packages.
    StorePackageUpdateResult downloadResult =
        await context.TrySilentDownloadAndInstallStorePackageUpdatesAsync(storePackageUpdates);

    switch (downloadResult.OverallState)
    {
        // If the user cancelled the installation or you can't perform the installation  
        // for some other reason, try again later. The RetryInstallLater method is not  
        // implemented in this example, you should implement it as needed for your own app.
        case StorePackageUpdateState.Canceled:
        case StorePackageUpdateState.ErrorLowBattery:
        case StorePackageUpdateState.OtherError:
            RetryInstallLater();
            return;
        default:
            break;
    }
}

Obligatorische Paketaktualisierungen

Wenn Sie eine Paketübermittlung im Partner Center für eine App erstellen, die auf Windows 10, Version 1607 oder höher ausgerichtet ist, können Sie das Paket als obligatorische und das Datum und die Uhrzeit markieren, zu dem es obligatorisch wird. Wenn diese Eigenschaft festgelegt ist und Ihre App feststellt, dass das Paketupdate verfügbar ist, kann Ihre App bestimmen, ob das Updatepaket obligatorisch ist und das Verhalten ändern, bis das Update installiert ist (z. B. kann Ihre App Features deaktivieren).

Hinweis

Der obligatorische Status eines Paketupdates wird von Microsoft nicht erzwungen, und das Betriebssystem stellt keine Benutzeroberfläche bereit, um Benutzern anzugeben, dass ein obligatorisches App-Update installiert werden muss. Entwickler sollen die obligatorische Einstellung verwenden, um obligatorische App-Updates in ihrem eigenen Code zu erzwingen.

So markieren Sie eine Paketeinreichung als verpflichtend:

  1. Melden Sie sich bei Partner Center an, und navigieren Sie zur Übersichtsseite für Ihre App.
  2. Klicken Sie auf den Namen der Einreichung, die das Paketupdate enthält, das Sie verpflichtend machen möchten.
  3. Navigieren Sie zur Seite Pakete für die Übermittlung. Wählen Sie unten auf dieser Seite Dieses Update obligatorisch machen und wählen Sie dann den Tag und die Uhrzeit aus, zu der das Paketupdate obligatorisch wird. Diese Option gilt für alle UWP-Pakete in der Übermittlung.

Weitere Informationen finden Sie unter Hochladen von App-Paketen.

Hinweis

Wenn Sie ein Flugpaketerstellen, können Sie die Pakete als obligatorisch kennzeichnen, indem Sie eine ähnliche Benutzeroberfläche auf der Seite Pakete für den Flug verwenden. In diesem Fall gilt das obligatorische Paketupdate nur für die Kunden, die Teil der Test-Flight-Gruppe sind.

Codebeispiel für obligatorische Pakete

Im folgenden Codebeispiel wird veranschaulicht, wie ermittelt wird, ob Updatepakete obligatorisch sind. In der Regel sollten Sie die App-Erfahrung ordnungsgemäß für den Benutzer herabstufen, wenn ein obligatorisches Paketupdate nicht erfolgreich heruntergeladen oder installiert wird.

private StoreContext context = null;

// Downloads and installs package updates in separate steps.
public async Task DownloadAndInstallAllUpdatesAsync()
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
    }  

    // Get the updates that are available.
    IReadOnlyList<StorePackageUpdate> updates =
        await context.GetAppAndOptionalStorePackageUpdatesAsync();

    if (updates.Count != 0)
    {
        // Download the packages.
        bool downloaded = await DownloadPackageUpdatesAsync(updates);

        if (downloaded)
        {
            // Install the packages.
            await InstallPackageUpdatesAsync(updates);
        }
    }
}

// Helper method for downloading package updates.
private async Task<bool> DownloadPackageUpdatesAsync(IEnumerable<StorePackageUpdate> updates)
{
    bool downloadedSuccessfully = false;

    IAsyncOperationWithProgress<StorePackageUpdateResult, StorePackageUpdateStatus> downloadOperation =
        this.context.RequestDownloadStorePackageUpdatesAsync(updates);

    // The Progress async method is called one time for each step in the download process for each
    // package in this request.
    downloadOperation.Progress = async (asyncInfo, progress) =>
    {
        await this.Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal,
        () =>
        {
            downloadProgressBar.Value = progress.PackageDownloadProgress;
        });
    };

    StorePackageUpdateResult result = await downloadOperation.AsTask();

    switch (result.OverallState)
    {
        case StorePackageUpdateState.Completed:
            downloadedSuccessfully = true;
            break;
        default:
            // Get the failed updates.
            var failedUpdates = result.StorePackageUpdateStatuses.Where(
                status => status.PackageUpdateState != StorePackageUpdateState.Completed);

            // See if any failed updates were mandatory
            if (updates.Any(u => u.Mandatory && failedUpdates.Any(
                failed => failed.PackageFamilyName == u.Package.Id.FamilyName)))
            {
                // At least one of the updates is mandatory. Perform whatever actions you
                // want to take for your app: for example, notify the user and disable
                // features in your app.
                HandleMandatoryPackageError();
            }
            break;
    }

    return downloadedSuccessfully;
}

// Helper method for installing package updates.
private async Task InstallPackageUpdatesAsync(IEnumerable<StorePackageUpdate> updates)
{
    IAsyncOperationWithProgress<StorePackageUpdateResult, StorePackageUpdateStatus> installOperation =
        this.context.RequestDownloadAndInstallStorePackageUpdatesAsync(updates);

    // The package updates were already downloaded separately, so this method skips the download
    // operation and only installs the updates; no download progress notifications are provided.
    StorePackageUpdateResult result = await installOperation.AsTask();

    switch (result.OverallState)
    {
        case StorePackageUpdateState.Completed:
            break;
        default:
            // Get the failed updates.
            var failedUpdates = result.StorePackageUpdateStatuses.Where(
                status => status.PackageUpdateState != StorePackageUpdateState.Completed);

            // See if any failed updates were mandatory
            if (updates.Any(u => u.Mandatory && failedUpdates.Any(failed => failed.PackageFamilyName == u.Package.Id.FamilyName)))
            {
                // At least one of the updates is mandatory, so tell the user.
                HandleMandatoryPackageError();
            }
            break;
    }
}

// Helper method for handling the scenario where a mandatory package update fails to
// download or install. Add code to this method to perform whatever actions you want
// to take, such as notifying the user and disabling features in your app.
private void HandleMandatoryPackageError()
{
}

Optionale Pakete deinstallieren

Ab Windows 10, Version 1803, können Sie das RequestUninstallStorePackageAsync- oder RequestUninstallStorePackageByStoreIdAsync- Methoden verwenden, um ein optionales paket (einschließlich eines DLC-Pakets) für die aktuelle App zu deinstallieren. Wenn Sie beispielsweise über eine App mit Inhalten verfügen, die über optionale Pakete installiert sind, sollten Sie eine Benutzeroberfläche bereitstellen, mit der Benutzer die optionalen Pakete deinstallieren können, um Speicherplatz freizugeben.

Im folgenden Codebeispiel wird veranschaulicht, wie die Methode RequestUninstallStorePackageAsyncaufgerufen wird. In diesem Beispiel wird davon ausgegangen:

  • Die Codedatei verfügt über eine mit-Anweisung für die Namespaces Windows.Services.Store und System.Threading.Tasks.
  • Die App ist eine Einzelbenutzer-App, die nur im Kontext des Benutzers ausgeführt wird, der die App gestartet hat. Verwenden Sie für eine Mehrbenutzer-Appdie Methode GetForUser, um ein StoreContext-Objekt abzurufen, anstelle der Methode GetDefault.
public async Task UninstallPackage(Windows.ApplicationModel.Package package)
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
    }

    var storeContext = StoreContext.GetDefault();
    IAsyncOperation<StoreUninstallStorePackageResult> uninstallOperation =
        storeContext.RequestUninstallStorePackageAsync(package);

    // At this point, you can update your app UI to show that the package
    // is installing.

    uninstallOperation.Completed += (asyncInfo, status) =>
    {
        StoreUninstallStorePackageResult result = uninstallOperation.GetResults();
        switch (result.Status)
        {
            case StoreUninstallStorePackageStatus.Succeeded:
                {
                    // Update your app UI to show the package as uninstalled.
                    break;
                }
            default:
                {
                    // Update your app UI to show that the package uninstall failed.
                    break;
                }
        }
    };
}

Download-Warteschlangeninformationen abrufen

Ab Windows 10, Version 1803, können Sie die GetAssociatedStoreQueueItemsAsync- und GetStoreQueueItemsAsync- Methoden verwenden, um Informationen zu den Paketen abzurufen, die sich in der aktuellen Download- und Installationswarteschlange im Store befinden. Diese Methoden sind nützlich, wenn Ihre App oder Ihr Spiel große optionale Pakete (einschließlich DLCs) unterstützt, die Stunden oder Tage dauern können, um sie herunterzuladen und zu installieren, und Sie möchten den Fall ordnungsgemäß behandeln, in dem ein Kunde Ihre App oder Ihr Spiel schließt, bevor der Download- und Installationsprozess abgeschlossen ist. Wenn der Kunde Ihre App oder Ihr Spiel erneut startet, kann Ihr Code diese Methoden verwenden, um Informationen zum Status der Pakete abzurufen, die sich noch in der Download- und Installationswarteschlange befinden, damit Sie den Status jedes Pakets für den Kunden anzeigen können.

Im folgenden Codebeispiel wird veranschaulicht, wie Sie GetAssociatedStoreQueueItemsAsync aufrufen, um die Liste der laufenden Paketupdates für die aktuelle App abzurufen und den Status für jedes Paket abzuleiten. In diesem Beispiel wird davon ausgegangen:

  • Die Codedatei verfügt über eine mit-Anweisung für die Namespaces Windows.Services.Store und System.Threading.Tasks.
  • Die App ist eine Einzelbenutzer-App, die nur im Kontext des Benutzers ausgeführt wird, der die App gestartet hat. Verwenden Sie für eine Mehrbenutzer-Appdie Methode GetForUser, um ein StoreContext-Objekt abzurufen, anstelle der Methode GetDefault.

Hinweis

Die MarkUpdateInProgressInUI, RemoveItemFromUI, MarkInstallCompleteInUI, MarkInstallErrorInUIund MarkInstallPausedInUI Methoden, die vom Code in diesem Beispiel aufgerufen werden, sind Platzhaltermethoden, die gemäß dem Design Ihrer eigenen App nach Bedarf implementiert werden sollen.

private StoreContext context = null;

private async Task GetQueuedInstallItemsAndBuildInitialStoreUI()
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
    }

    // Get the Store packages in the install queue.
    IReadOnlyList<StoreQueueItem> storeUpdateItems = await context.GetAssociatedStoreQueueItemsAsync();

    foreach (StoreQueueItem storeItem in storeUpdateItems)
    {
        // In this example we only care about package updates.
        if (storeItem.InstallKind != StoreQueueItemKind.Update)
            continue;

        StoreQueueItemStatus currentStatus = storeItem.GetCurrentStatus();
        StoreQueueItemState installState = currentStatus.PackageInstallState;
        StoreQueueItemExtendedState extendedInstallState =
            currentStatus.PackageInstallExtendedState;

        // Handle the StatusChanged event to display current status to the customer.
        storeItem.StatusChanged += StoreItem_StatusChanged;

        switch (installState)
        {
            // Download and install are still in progress, so update the status for this  
            // item and provide the extended state info. The following methods are not
            // implemented in this example; you should implement them as needed for your
            // app's UI.
            case StoreQueueItemState.Active:
                MarkUpdateInProgressInUI(storeItem, extendedInstallState);
                break;
            case StoreQueueItemState.Canceled:
                RemoveItemFromUI(storeItem);
                break;
            case StoreQueueItemState.Completed:
                MarkInstallCompleteInUI(storeItem);
                break;
            case StoreQueueItemState.Error:
                MarkInstallErrorInUI(storeItem);
                break;
            case StoreQueueItemState.Paused:
                MarkInstallPausedInUI(storeItem, installState, extendedInstallState);
                break;
        }
    }
}

private void StoreItem_StatusChanged(StoreQueueItem sender, object args)
{
    StoreQueueItemStatus currentStatus = sender.GetCurrentStatus();
    StoreQueueItemState installState = currentStatus.PackageInstallState;
    StoreQueueItemExtendedState extendedInstallState = currentStatus.PackageInstallExtendedState;

    switch (installState)
    {
        // Download and install are still in progress, so update the status for this  
        // item and provide the extended state info. The following methods are not
        // implemented in this example; you should implement them as needed for your
        // app's UI.
        case StoreQueueItemState.Active:
            MarkUpdateInProgressInUI(sender, extendedInstallState);
            break;
        case StoreQueueItemState.Canceled:
            RemoveItemFromUI(sender);
            break;
        case StoreQueueItemState.Completed:
            MarkInstallCompleteInUI(sender);
            break;
        case StoreQueueItemState.Error:
            MarkInstallErrorInUI(sender);
            break;
        case StoreQueueItemState.Paused:
            MarkInstallPausedInUI(sender, installState, extendedInstallState);
            break;
    }
}