Baixar e instalar atualizações de pacotes pela Loja

A partir do Windows 10, versão 1607, você pode usar métodos da classe StoreContext no namespace Windows.Services.Store para verificar programaticamente se há atualizações de pacote para o aplicativo atual da Microsoft Store e baixar e instalar os pacotes atualizados. Você também pode consultar pacotes marcados como obrigatórios no Partner Center e desabilitar a funcionalidade em seu aplicativo até que a atualização obrigatória seja instalada.

Outros métodos StoreContext introduzidos no Windows 10, versão 1803, permitem baixar e instalar atualizações de pacote silenciosamente (sem exibir uma interface do usuário de notificação para o usuário), desinstalar um pacote opcionale obter informações sobre pacotes na fila de download e instalação do aplicativo.

Esses recursos ajudam você a manter sua base de usuários atualizada automaticamente com a versão mais recente do seu aplicativo, pacotes opcionais e serviços relacionados na Loja.

Baixar e instalar atualizações de pacote com a permissão do usuário

Este exemplo de código demonstra como usar o método GetAppAndOptionalStorePackageUpdatesAsync para descobrir todas as atualizações de pacote disponíveis da Loja e, em seguida, chamar o método RequestDownloadAndInstallStorePackageUpdatesAsync para baixar e instalar as atualizações. Ao usar esse método para baixar e instalar atualizações, o sistema operacional exibe uma caixa de diálogo que solicita a permissão do usuário antes de baixar as atualizações.

Observação

Esses métodos dão suporte aos pacotes necessários e opcionais para seu aplicativo. Pacotes opcionais são úteis para complementos de DLC (conteúdo baixável), dividindo seu aplicativo grande para restrições de tamanho ou para enviar conteúdo adicional separado do seu aplicativo principal. Para obter permissão para enviar um aplicativo que usa pacotes opcionais (incluindo complementos de DLC) para a Loja, consulte suporte ao desenvolvedor do Windows.

Este exemplo de código pressupõe:

• O código é executado no contexto de uma página .
• A página contém uma ProgressBar chamada downloadProgressBar para fornecer o status do processo de download.
• O arquivo de código tem uma instrução usando para os namespaces Windows.Services.Store, Windows.Threading.Tasks, e Windows.UI.Popups.
• O aplicativo é um aplicativo de usuário único que é executado somente no contexto do usuário que iniciou o aplicativo. Para um aplicativo multiusuário, use o método GetForUser para obter um objeto StoreContext em vez do método 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();
        }
    }
}

Observação

Para baixar apenas as atualizações de pacotes disponíveis (mas não instalá-las), use o método RequestDownloadStorePackageUpdatesAsync .

Exibir informações de progresso de download e instalação

Quando você chama o método RequestDownloadStorePackageUpdatesAsync ou RequestDownloadAndInstallStorePackageUpdatesAsync, pode atribuir um manipulador de Progresso que é chamado uma vez para cada etapa no processo de download (ou download e instalação) de cada pacote nesta solicitação. O manipulador recebe um objeto StorePackageUpdateStatus que fornece informações sobre o pacote de atualização que gerou a notificação de progresso. O exemplo anterior usa o campo PackageDownloadProgress do objeto StorePackageUpdateStatus para exibir o progresso do processo de download e instalação.

Lembre-se de que quando você chama RequestDownloadAndInstallStorePackageUpdatesAsync para baixar e instalar atualizações de pacote em uma única operação, o campo PackageDownloadProgress aumenta de 0,0 para 0,8 durante o processo de download de um pacote e, em seguida, aumenta de 0,8 para 1,0 durante a instalação. Portanto, se você mapear a porcentagem mostrada na interface do usuário de progresso personalizado diretamente para o valor do campo PackageDownloadProgress, sua interface do usuário mostrará 80% quando o pacote terminar de baixar e o sistema operacional exibir a caixa de diálogo de instalação. Se quiser que a interface do usuário de progresso personalizado exiba 100% quando o pacote for baixado e pronto para ser instalado, você poderá modificar seu código para atribuir 100% à interface do usuário de progresso quando o campo PackageDownloadProgress atingir 0,8.

Baixar e instalar atualizações de pacote silenciosamente

A partir do Windows 10, versão 1803, você pode usar os métodos TrySilentDownloadStorePackageUpdatesAsync e TrySilentDownloadAndInstallStorePackageUpdatesAsync para baixar e instalar atualizações de pacote silenciosamente, sem exibir uma interface de notificação ao usuário. Essa operação só terá êxito se o usuário tiver habilitado a configuração Atualizar aplicativos automaticamente na Microsoft Store e o usuário não estiver usando uma rede com cobrança por uso. Antes de chamar esses métodos, primeiro você pode verificar a propriedade CanSilentlyDownloadStorePackageUpdates para determinar se essas condições são atendidas no momento.

Este exemplo de código demonstra como usar o método GetAppAndOptionalStorePackageUpdatesAsync para descobrir todas as atualizações de pacote disponíveis e chamar os métodos TrySilentDownloadStorePackageUpdatesAsync e TrySilentDownloadAndInstallStorePackageUpdatesAsync métodos para baixar e instalar as atualizações silenciosamente.

Este exemplo de código pressupõe:

• O arquivo de código tem uma instrução usando para os namespaces Windows.Services.Store e System.Threading.Tasks.
• O aplicativo é um aplicativo de usuário único que é executado somente no contexto do usuário que iniciou o aplicativo. Para um aplicativo multiusuário, use o método GetForUser para obter um objeto StoreContext em vez do método GetDefault .

Observação

O método IsNowAGoodTimeToRestartApp, RetryDownloadAndInstallLater, e o método RetryInstallLater chamados pelo código neste exemplo são métodos de espaço reservado que devem ser implementados conforme necessário de acordo com o design do seu próprio aplicativo.

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

Atualizações de pacote obrigatórias

Ao criar uma submissão de pacote no Partner Center para um aplicativo voltado para o Windows 10, versão 1607 ou posterior, você pode marcar o pacote como obrigatório, especificando a data e a hora em que ele se tornará obrigatório. Quando essa propriedade é definida e seu aplicativo descobre que a atualização do pacote está disponível, seu aplicativo pode determinar se o pacote de atualização é obrigatório e alterar seu comportamento até que a atualização seja instalada (por exemplo, seu aplicativo pode desabilitar recursos).

Observação

O status obrigatório de uma atualização de pacote não é imposto pela Microsoft e o sistema operacional não fornece uma interface do usuário para indicar aos usuários que uma atualização obrigatória do aplicativo deve ser instalada. Os desenvolvedores devem usar a configuração obrigatória para impor atualizações de aplicativo obrigatórias em seu próprio código.

Para marcar um envio de pacote como obrigatório:

1. Entre no do Partner Center e navegue até a página de visão geral do aplicativo.
2. Clique no nome do envio que contém a atualização de pacote que você deseja tornar obrigatória.
3. Navegue para a página pacotes para o envio. Próximo à parte inferior desta página, selecione Tornar essa atualização obrigatória e escolha o dia e a hora em que a atualização do pacote se torna obrigatória. Essa opção se aplica a todos os pacotes UWP no envio.

Para obter mais informações, consulte Carregar pacotes de aplicativos.

Observação

Se você criar um pacote de voo , poderá marcar os pacotes como obrigatórios usando uma interface do usuário semelhante na página Pacotes para o voo. Nesse caso, a atualização obrigatória do pacote se aplica somente aos clientes que fazem parte do grupo de voos.

Exemplo de código para pacotes obrigatórios

O exemplo de código a seguir demonstra como determinar se os pacotes de atualização são obrigatórios. Normalmente, você deve reduzir gradualmente a experiência do aplicativo se uma atualização de pacote obrigatória não for baixada ou instalada com êxito.

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

Desinstalar pacotes opcionais

A partir do Windows 10, versão 1803, você pode usar os métodos RequestUninstallStorePackageAsync ou RequestUninstallStorePackageByStoreIdAsync para desinstalar um pacote opcional (incluindo um pacote DLC) para o aplicativo atual. Por exemplo, se você tiver um aplicativo com conteúdo instalado por meio de pacotes opcionais, convém fornecer uma interface do usuário que permita aos usuários desinstalar os pacotes opcionais para liberar espaço em disco.

O exemplo de código a seguir demonstra como chamar RequestUninstallStorePackageAsync. Este exemplo pressupõe:

• O arquivo de código tem uma instrução usando para os namespaces Windows.Services.Store e System.Threading.Tasks.
• O aplicativo é um aplicativo de usuário único que é executado somente no contexto do usuário que iniciou o aplicativo. Para um aplicativo multiusuário, use o método GetForUser para obter um objeto StoreContext em vez do método 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;
                }
        }
    };
}

Obter informações da fila de download

A partir do Windows 10, versão 1803, você pode usar os métodos GetAssociatedStoreQueueItemsAsync e GetStoreQueueItemsAsync para obter informações sobre os pacotes que estão na fila de download e instalação atual da Loja. Esses métodos são úteis se seu aplicativo ou jogo dá suporte a grandes pacotes opcionais (incluindo DLCs) que podem levar horas ou dias para baixar e instalar, e você deseja lidar normalmente com o caso em que um cliente fecha seu aplicativo ou jogo antes que o processo de download e instalação seja concluído. Quando o cliente inicia seu aplicativo ou jogo novamente, seu código pode usar esses métodos para obter informações sobre o estado dos pacotes que ainda estão na fila de download e instalação para que você possa exibir o status de cada pacote para o cliente.

O exemplo de código a seguir demonstra como chamar GetAssociatedStoreQueueItemsAsync para obter a lista de atualizações de pacote em andamento para o aplicativo atual e recuperar informações de status para cada pacote. Este exemplo pressupõe:

• O arquivo de código tem uma instrução usando para os namespaces Windows.Services.Store e System.Threading.Tasks.
• O aplicativo é um aplicativo de usuário único que é executado somente no contexto do usuário que iniciou o aplicativo. Para um aplicativo multiusuário, use o método GetForUser para obter um objeto StoreContext em vez do método GetDefault .

Observação

As métodos MarkUpdateInProgressInUI, RemoveItemFromUI, MarkInstallCompleteInUI, MarkInstallErrorInUIe MarkInstallPausedInUI, chamados pelo código neste exemplo, são métodos temporários que devem ser implementados conforme necessário de acordo com o design do seu próprio aplicativo.

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

Tópicos relacionados

• Pacotes opcionais e autoria de conjuntos relacionados