Pakketupdates downloaden en installeren vanuit de Store

Vanaf Windows 10 versie 1607 kunt u methoden van de StoreContext-klasse in de Windows.Services.Store-naamruimte gebruiken om programmatisch te controleren op pakketupdates voor de huidige app uit de Microsoft Store en de bijgewerkte pakketten te downloaden en te installeren. U kunt ook query's uitvoeren op pakketten die u hebt gemarkeerd als verplicht in partnercentrum en functionaliteit in uw app uitschakelen totdat de verplichte update is geïnstalleerd.

Met aanvullende StoreContext-methoden die zijn geïntroduceerd in Windows 10, versie 1803, kunt u pakketupdates op de achtergrond downloaden en installeren (zonder dat er een gebruikersinterface voor meldingen voor de gebruiker wordt weergegeven), een optioneel pakket verwijderen en informatie ophalen over pakketten in de download- en installatiewachtrij voor uw app.

Met deze functies kunt u uw gebruikersbestand automatisch up-to-date houden met de nieuwste versie van uw app, optionele pakketten en gerelateerde services in de Store.

Pakketupdates downloaden en installeren met de machtiging van de gebruiker

In dit codevoorbeeld ziet u hoe u de methode GetAppAndOptionalStorePackageUpdatesAsync gebruikt om alle beschikbare pakketupdates uit de Store te detecteren en vervolgens de methode RequestDownloadAndInstallStorePackageUpdatesAsync aan te roepen om de updates te downloaden en te installeren. Wanneer u deze methode gebruikt om updates te downloaden en te installeren, wordt in het besturingssysteem een dialoogvenster weergegeven waarin de gebruiker om toestemming wordt gevraagd voordat de updates worden gedownload.

Notitie

Deze methoden ondersteunen vereiste en optionele pakketten voor uw app. Optionele pakketten zijn handig voor invoegtoepassingen voor downloadbare inhoud (DLC), waarbij uw grote app wordt verdeeld voor beperkingen van de grootte of voor het verzenden van extra inhoud, gescheiden van uw kern-app. Als u toestemming wilt krijgen om een app te verzenden die gebruikmaakt van optionele pakketten (inclusief DLC-invoegtoepassingen) naar de Store, raadpleegt u de ondersteuning voor Windows-ontwikkelaars.

In dit codevoorbeeld wordt ervan uitgegaan:

• De code wordt uitgevoerd in de context van een pagina.
• De pagina bevat een voortgangsbalk met de naam downloadProgressBar om de status voor de downloadbewerking te tonen.
• Het codebestand heeft een using-instructie voor de naamruimten Windows.Services.Store, Windows.Threading.Tasks en Windows.UI.Popups .
• De app is een app met één gebruiker die alleen wordt uitgevoerd in de context van de gebruiker die de app heeft gestart. Gebruik voor een app voor meerdere gebruikers de methode GetForUser om een StoreContext-object op te halen in plaats van de 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();
        }
    }
}

Notitie

Als u alleen de beschikbare pakketupdates wilt downloaden (maar niet installeren), gebruikt u de methode RequestDownloadStorePackageUpdatesAsync .

Voortgangsgegevens voor downloaden en installeren weergeven

Wanneer u de methode RequestDownloadStorePackageUpdatesAsync of RequestDownloadAndInstallStorePackageUpdatesAsync aanroept , kunt u een voortgangshandler toewijzen die één keer wordt aangeroepen voor elke stap in het downloadproces (of download- en installatieproces) voor elk pakket in deze aanvraag. De handler ontvangt een StorePackageUpdateStatus-object dat informatie biedt over het updatepakket dat de voortgangsmelding heeft gegenereerd. In het vorige voorbeeld wordt het veld PackageDownloadProgress van het object StorePackageUpdateStatus gebruikt om de voortgang van het download- en installatieproces weer te geven.

Houd er rekening mee dat wanneer u RequestDownloadAndInstallStorePackageUpdatesAsync aanroept om pakketupdates in één bewerking te downloaden en te installeren, het veld PackageDownloadProgress tijdens het downloaden van een pakket wordt verhoogd van 0.0 tot 0.8 en vervolgens tijdens de installatie toeneemt van 0,8 tot 1.0. Als u het percentage dat wordt getoond in uw aangepaste voortgangs-UI rechtstreeks koppelt aan de waarde van het veld PackageDownloadProgress, zal uw interface 80% weergeven wanneer het pakket is gedownload en het besturingssysteem het installatiedialoogvenster toont. Als u wilt dat uw aangepaste voortgangsgebruikersinterface 100% weergeeft wanneer het pakket is gedownload en klaar is om te worden geïnstalleerd, kunt u de code wijzigen om 100% toe te wijzen aan uw voortgangsgebruikersinterface wanneer het veld PackageDownloadProgress 0.8 bereikt.

Pakketupdates op de achtergrond downloaden en installeren

Vanaf Windows 10 versie 1803 kunt u de methoden TrySilentDownloadStorePackageUpdatesAsync en TrySilentDownloadAndInstallStorePackageUpdatesAsync gebruiken om pakketupdates op de achtergrond te downloaden en installeren, zonder dat er een gebruikersinterface voor meldingen wordt weergegeven aan de gebruiker. Deze bewerking slaagt alleen als de gebruiker de instelling Update-apps automatisch heeft ingeschakeld in de Store en de gebruiker zich niet in een netwerk met datalimiet bevindt. Voordat u deze methoden aanroept, kunt u eerst de eigenschap CanSilentlyDownloadStorePackageUpdates controleren om te bepalen of aan deze voorwaarden wordt voldaan.

In dit codevoorbeeld ziet u hoe u de methode GetAppAndOptionalStorePackageUpdatesAsync gebruikt om alle beschikbare pakketupdates te detecteren en vervolgens de methoden TrySilentDownloadStorePackageUpdatesAsync en TrySilentDownloadAndInstallStorePackageUpdatesAsync aan te roepen om de updates op de achtergrond te downloaden en te installeren.

In dit codevoorbeeld wordt ervan uitgegaan:

• Het codebestand heeft een using-instructie voor de naamruimten Windows.Services.Store en System.Threading.Tasks .
• De app is een app met één gebruiker die alleen wordt uitgevoerd in de context van de gebruiker die de app heeft gestart. Gebruik voor een app voor meerdere gebruikers de methode GetForUser om een StoreContext-object op te halen in plaats van de Methode GetDefault .

Notitie

De methoden IsNowAGoodTimeToRestartApp, RetryDownloadAndInstallLater en RetryInstallLater die worden aangeroepen door de code in dit voorbeeld zijn tijdelijke aanduidingen die naar behoefte moeten worden geïmplementeerd volgens het ontwerp van uw eigen app.

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;
    }
}

Verplichte pakketupdates

Wanneer u een pakket inzending maakt in Partnercentrum voor een app die is gericht op Windows 10, versie 1607 of hoger, kunt u het pakket markeren als verplicht en de datum en tijd waarop het verplicht wordt. Wanneer deze eigenschap is ingesteld en uw app detecteert dat de pakketupdate beschikbaar is, kan uw app bepalen of het updatepakket verplicht is en het gedrag ervan wijzigen totdat de update is geïnstalleerd (uw app kan bijvoorbeeld functies uitschakelen).

Notitie

De verplichte status van een pakketupdate wordt niet afgedwongen door Microsoft en het besturingssysteem biedt geen gebruikersinterface om aan te geven dat een verplichte app-update moet worden geïnstalleerd. Ontwikkelaars zijn bedoeld om de verplichte instelling te gebruiken om verplichte app-updates in hun eigen code af te dwingen.

Om een pakketindiening als verplicht te markeren:

1. Meld u aan bij Partnercentrum en navigeer naar de overzichtspagina voor uw app.
2. Klik op de naam van de inzending die de pakketupdate bevat die u verplicht wilt maken.
3. Navigeer naar de pagina Pakketten voor de inzending. Selecteer onderaan deze pagina de optie Deze update verplicht maken en kies vervolgens de dag en tijd waarop de pakketupdate verplicht wordt. Deze optie is van toepassing op alle UWP-pakketten in de inzending.

Zie App-pakketten uploaden voor meer informatie.

Notitie

Als u een pakketvlucht maakt, kunt u de pakketten markeren als verplicht met behulp van een vergelijkbare gebruikersinterface op de pagina Pakketten voor de vlucht. In dit geval is de verplichte pakketupdate alleen van toepassing op de klanten die deel uitmaken van de vluchtgroep.

Codevoorbeeld voor verplichte pakketten

In het volgende codevoorbeeld ziet u hoe u kunt bepalen of updatepakketten verplicht zijn. Normaal gesproken moet u uw app-ervaring probleemloos downgraden voor de gebruiker als een verplichte pakketupdate niet kan worden gedownload of geïnstalleerd.

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()
{
}

Optionele pakketten verwijderen

Vanaf Windows 10 versie 1803 kunt u de methoden RequestUninstallStorePackageAsync of RequestUninstallStorePackageByStoreIdAsync gebruiken om een optioneel pakket (inclusief een DLC-pakket) voor de huidige app te verwijderen. Als u bijvoorbeeld een app hebt met inhoud die is geïnstalleerd via optionele pakketten, kunt u een gebruikersinterface bieden waarmee gebruikers de optionele pakketten kunnen verwijderen om schijfruimte vrij te maken.

In het volgende codevoorbeeld ziet u hoe u RequestUninstallStorePackageAsync aanroept. In dit voorbeeld wordt ervan uitgegaan:

• Het codebestand heeft een using-instructie voor de naamruimten Windows.Services.Store en System.Threading.Tasks .
• De app is een app met één gebruiker die alleen wordt uitgevoerd in de context van de gebruiker die de app heeft gestart. Gebruik voor een app voor meerdere gebruikers de methode GetForUser om een StoreContext-object op te halen in plaats van de 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;
                }
        }
    };
}

Downloadwachtrijgegevens ophalen

Vanaf Windows 10 versie 1803 kunt u de methoden GetAssociatedStoreQueueItemsAsync en GetStoreQueueItemsAsync gebruiken voor informatie over de pakketten die zich in de huidige download- en installatiewachtrij van de Store bevinden. Deze methoden zijn handig als uw app of game grote optionele pakketten (inclusief DLC's) ondersteunt die uren of dagen kunnen duren voordat het downloaden en installeren is voltooid en u de case wilt afhandelen waarin een klant uw app of game sluit voordat het download- en installatieproces is voltooid. Wanneer de klant uw app of game opnieuw start, kan uw code deze methoden gebruiken om informatie te krijgen over de status van de pakketten die zich nog in de download- en installatiewachtrij bevinden, zodat u de status van elk pakket aan de klant kunt weergeven.

In het volgende codevoorbeeld ziet u hoe u GetAssociatedStoreQueueItemsAsync aanroept om de lijst met in-progress pakketupdates voor de huidige app op te halen en statusgegevens voor elk pakket op te halen. In dit voorbeeld wordt ervan uitgegaan:

• Het codebestand heeft een using-instructie voor de naamruimten Windows.Services.Store en System.Threading.Tasks .
• De app is een app met één gebruiker die alleen wordt uitgevoerd in de context van de gebruiker die de app heeft gestart. Gebruik voor een app voor meerdere gebruikers de methode GetForUser om een StoreContext-object op te halen in plaats van de Methode GetDefault .

Notitie

De methoden MarkUpdateInProgressInUI, RemoveItemFromUI, MarkInstallCompleteInUI, MarkInstallErrorInUI en MarkInstallPausedInUI die door de code in dit voorbeeld worden aangeroepen, zijn tijdelijke aanduidingen die zo nodig moeten worden geïmplementeerd volgens het ontwerp van uw eigen app.

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;
    }
}

Verwante onderwerpen

• Optionele pakketten en gerelateerde sets samenstellen