Passar parâmetros de instalação para seu aplicativo por meio do Instalador de Aplicativo

Ao distribuir seu aplicativo usando o MSIX, você pode configurar seu aplicativo para que os parâmetros de cadeia de caracteres de consulta definidos no uri de download/instalação sejam passados para seu aplicativo quando ele for iniciado, depois que um usuário clicar no uri de download/instalação. Isso funciona se é a primeira vez que um usuário está instalando o aplicativo ou se o aplicativo foi instalado anteriormente. Este artigo mostra como configurar seu aplicativo empacotado MSIX e seu uri de download/instalação para aproveitar essa funcionalidade. Isso pode ser útil se você quiser acompanhar ou lidar com instalações diferentes com base na origem, no tipo de download etc. e funcionará para downloads na Web e em qualquer outro caso em que um usuário clique no URI, por exemplo, em uma campanha de email. Para obter mais detalhes, confira esta postagem no blog.

Configurar seu aplicativo para ativação de protocolo

A primeira coisa a fazer é registrar seu aplicativo para que ele seja iniciado usando um protocolo personalizado definido. Quando esse protocolo é invocado, seu aplicativo é iniciado e todos os prameters especificados no uri são passados para os argumentos de evento de ativação do aplicativo quando ele é iniciado. Você pode registrar o protocolo adicionando uma entrada de extensão de protocolo no nó Extensões de Aplicativo no arquivo appxmanifest.xml do MSIX:

<Application>
...
   <Extensions>
     <uap:Extension Category="windows.protocol">
        <uap:Protocol Name="my-custom-protocol"/>
     </uap:Extension>
   </Extensions>
  
...
</Application>

Se você estiver usando o Projeto de Empacotamento do Windows, também poderá definir um protocolo personalizado usando o editor de manifesto padrão clicando duas vezes no arquivo package.appxmanifest , navegando até a guia Declarações e selecionando Protocolo em Declarações Disponíveis:

Protocol declaration in package.appxmanifest

Escrever código para lidar com parâmetros quando seu aplicativo for iniciado após a instalação

Você precisará implementar o código em seu aplicativo para lidar com os parâmetros de instalação que serão passados para seu aplicativo quando ele for iniciado. O código de exemplo a seguir usa o método AppInstance.GetActivatedEventArgs para determinar o tipo de ativação usado para instanciar um aplicativo (você também pode lidar com os parâmetros usando um método diferente). Quando o aplicativo for iniciado/ativado com parâmetros de consulta de um uri de instalação (consulte a definição na próxima seção), o tipo de ativação será uma ativação de protocolo, conforme definido pelo protocolo personalizado declarado em seu uri de appxmanifest.xml e download/instalação. Os args de evento de ativação serão do tipo ProtocolActivatedEventArgs e é isso que o código a seguir usa:


using Windows.ApplicationModel;
using Windows.ApplicationModel.Activation;

public static void Main(string[] cmdArgs)
{
            
    var activationArgs = AppInstance.GetActivatedEventArgs();
    switch (activationArgs.Kind)
    {
        //Install parameters will be passed in during a protocol activation
        case ActivationKind.Protocol:
        HandleProtocolActivation(activationArgs as ProtocolActivatedEventArgs);
        break;
        case ActivationKind.Launch:
        //Regular launch activation type
        HandleLaunch(activationArgs as LaunchActivatedEventArgs);
        break;
        default:
        break;
     }       
    

     static void HandleProtocolActivation(ProtocolActivatedEventArgs args)
     {

         if (args.Uri != null)
        {
            //Handle the installation parameters in the protocol uri
            handleInstallParameter(args.Uri.ToString());

        }
            
}

Adicionar seu protocolo de ativação personalizado e parâmetros ao uri de instalação

Depois que o aplicativo estiver configurado para lidar com os parâmetros de instalação, você poderá personalizar o uri de download/instalação do aplicativo para conter parâmetros definidos exclusivamente que serão passados para o aplicativo no início, depois que um usuário clicar no uri. O uri deve conter:

  1. O protocolo ms-appinstaller que invoca o Instalador de Aplicativos.
  2. O activationUri de parâmetro exclusivo que aponta para o protocolo personalizado do aplicativo e os parâmetros de instalação que você deseja passar para seu aplicativo quando ele é iniciado.
  3. O protocolo personalizado do aplicativo e o parâmetro e seu valor.

No uris de exemplo abaixo, defini um protocolo personalizado my-custom-protocol, um parâmetro my-parameter e dei-lhe o valor my-param-value. Quando o aplicativo for iniciado após um usuário clicar no uri, ele receberá a parte da cadeia de caracteres de consulta do uri após a ativaçãoUri, nesse caso, que será my-custom-protocol:?my-parameter=my-param-value.

ms-appinstaller:?source=https://contoso.com/myapp.appinstaller&activationUri=my-custom-protocol:?my-parameter=my-param-value
ms-appinstaller:?source=https://contos.com/myapp.msix&activationUri=my-custom-protocol:?my-parameter=my-param-value