Gerir a ativação de URI

Saiba como registrar um aplicativo para se tornar o manipulador padrão para um nome de esquema URI (Uniform Resource Identifier). Os aplicativos da área de trabalho do Windows e os aplicativos da Plataforma Universal do Windows (UWP) podem se registrar para ser um manipulador padrão para um nome de esquema de URI. Se o usuário escolher seu aplicativo como o manipulador padrão para um nome de esquema de URI, seu aplicativo será ativado sempre que esse tipo de URI for iniciado.

Recomendamos que você se registre apenas para um nome de esquema de URI se espera lidar com todas as inicializações de URI para esse tipo de esquema de URI. Se você optar por se registrar para um nome de esquema de URI, deverá fornecer ao usuário final a funcionalidade esperada quando seu aplicativo for ativado para esse esquema de URI. Por exemplo, um aplicativo que se registra para o nome do esquema mailto: URI deve abrir uma nova mensagem de email para que o usuário possa compor um novo email. Para saber mais sobre associações de URI, veja Arquivos, pastas e bibliotecas.

Estas etapas mostram como se registrar para um nome de esquema de URI personalizado, alsdk://e como ativar seu aplicativo quando o usuário inicia um URI alsdk://.

APIs importantes

As APIs a seguir são usadas neste tópico:

• Windows.ApplicationModel.Activation.ProtocolActivatedEventArgs
• Windows.UI.Xaml.Application.OnActivated
• AppInstance.GetActivatedEventArgs

Etapa 1: Especificar o ponto de extensão no manifesto do pacote

O aplicativo recebe eventos de ativação somente para os nomes de esquema de URI listados no manifesto do pacote. Veja como você indica que seu aplicativo lida com o nome do esquema de URI alsdk.

1. No Explorador de Soluções, clique duas vezes em package.appxmanifest para abrir o editor de manifesto. Selecione a guia Declarações e, na lista suspensa Declarações Disponíveis, selecione Protocolo e, em seguida, clique em Adicionar.

   Aqui está uma breve descrição de cada um dos campos que você pode preencher no designer de manifesto para o protocolo (consulte AppX Package Manifest para obter detalhes):

2. Introduza images\Icon.png como o logótipo .

3. Digite SDK Sample URI Scheme como o Nome de exibição

4. Digite alsdk como o nome .

5. Pressione Ctrl+S para salvar a alteração em package.appxmanifest.

   Isso adiciona um elemento Extension como este ao manifesto do pacote. A categoria windows.protocol indica que o aplicativo manipula o nome do esquema de URI .

    <Applications>
        <Application Id= ... >
            <Extensions>
                <uap:Extension Category="windows.protocol">
                  <uap:Protocol Name="alsdk">
                    <uap:Logo>images\icon.png</uap:Logo>
                    <uap:DisplayName>SDK Sample URI Scheme</uap:DisplayName>
                  </uap:Protocol>
                </uap:Extension>
          </Extensions>
          ...
        </Application>
   </Applications>

Etapa 2: adicionar os ícones apropriados

As aplicações que se tornam o padrão para um nome de esquema de URI têm os seus ícones exibidos em vários locais do sistema, tal como no Painel de Controle Programas Padrão. Inclua um ícone 44x44 no seu projeto para este fim. Corresponda à aparência do ícone do aplicativo e utilize a cor de fundo do seu aplicativo em vez de deixar o ícone transparente. Faça com que o logotipo se estenda até a borda sem acolchoá-lo. Teste seus ícones em fundos brancos. Consulte ícones e logotipos de aplicativos para obter mais detalhes sobre ícones.

Etapa 3: Manipular o evento ativado

Em aplicativos UWP, o manipulador de eventos OnActivated recebe todos os eventos de ativação. A propriedade Kind indica o tipo de evento de ativação. Este exemplo é configurado para manipular eventos de ativação de protocolo .

public partial class App
{
   protected override void OnActivated(IActivatedEventArgs args)
  {
      if (args.Kind == ActivationKind.Protocol)
      {
         ProtocolActivatedEventArgs eventArgs = args as ProtocolActivatedEventArgs;
         // TODO: Handle URI activation
         // The received URI is eventArgs.Uri.AbsoluteUri
      }
   }
}

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs const& args)
{
    if (args.Kind() == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
    {
        auto protocolActivatedEventArgs{ args.as<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs>() };
        // TODO: Handle URI activation  
        auto receivedURI{ protocolActivatedEventArgs.Uri().RawUri() };
    }
}

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs^ args)
{
   if (args->Kind == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
   {
      Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^ eventArgs =
          dynamic_cast<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^>(args);
      
      // TODO: Handle URI activation  
      // The received URI is eventArgs->Uri->RawUri
   }
}

O código a seguir inicia programaticamente o aplicativo por meio de seu URI:

   // Launch the URI
   var uri = new Uri("alsdk:");
   var success = await Windows.System.Launcher.LaunchUriAsync(uri)

Para mais detalhes sobre como iniciar uma aplicação via URI, consulte Iniciar a aplicação padrão para um URI.

É recomendável que os aplicativos criem um novo Quadro XAML para cada evento de ativação que abra uma nova página. Dessa forma, o backstack de navegação para a nova Frame XAML não conterá qualquer conteúdo anterior que a aplicação possa ter na janela atual quando a execução for suspensa. As aplicações que decidam usar um único Frame para contratos de início e de ficheiros devem limpar o diário de navegação do Frame antes de navegar para uma nova página.

Quando iniciados por meio da ativação do protocolo, os aplicativos devem considerar a inclusão da interface do usuário que permite que o usuário volte para a página superior do aplicativo.

Observações

Qualquer aplicativo ou site pode usar seu nome de esquema de URI, incluindo os mal-intencionados. Portanto, todos os dados que você obtém no URI podem vir de uma fonte não confiável. Recomendamos que você nunca execute uma ação permanente com base nos parâmetros recebidos no URI. Por exemplo, os parâmetros de URI podem ser usados para iniciar o aplicativo na página da conta de um usuário, mas recomendamos que você nunca os use para modificar diretamente a conta do usuário.

Recomendamos que as aplicações criem um novo Quadro de XAML para cada evento de ativação que abra um novo URI de destino. Dessa forma, o backstack de navegação para a nova Frame XAML não conterá qualquer conteúdo anterior que a aplicação possa ter na janela atual quando a execução for suspensa.

Se decidir que deseja que os seus aplicativos usem um único XAML Frame para contratos de inicialização e protocolo, limpe as páginas no histórico de navegação do Frame antes de navegar para uma nova página. Quando iniciado por meio do Contrato de Protocolo, considere incluir nos seus aplicativos uma interface que permita ao usuário voltar ao início do aplicativo.

Conteúdo relacionado

• Exemplo de lançamento do UWP da Associação
• Programas padrão
• Manipular a ativação de ficheiros