Tratar a ativação do URI

Saiba como registrar um aplicativo para se tornar o manipulador padrão para um nome de esquema URI (Uniform Resource Identifier). Os aplicativos WinUI 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ê registre um nome de esquema de URI apenas se pretender 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 registrado para o esquema de URI `mailto:` deve abrir uma nova mensagem de e-mail para que o usuário possa redigir um novo e-mail. Para obter mais informações sobre associações de URI, consulte Arquivos, pastas e bibliotecas.

Essas 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 seguintes APIs são usadas neste tópico:

• Windows.ApplicationModel.Activation.ProtocolActivatedEventArgs
• Windows.UI.Xaml.Application.OnActivated
• AppInstance.GetCurrent(). 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 indicar que seu aplicativo lida com o nome do esquema de URI alsdk.

1. No Gerenciador de Soluções, clique duas vezes em package.appxmanifest para abrir o editor do 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 do Protocolo (consulte Manifesto do Pacote AppX para obter detalhes):

2. Insira images\Icon.png como o Logotipo.

3. Insira SDK Sample URI Scheme como o nome de exibição

4. Insira alsdk como 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 lida com o nome do esquema de URI alsdk.

    <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

Os aplicativos que se tornam o padrão para um nome de esquema de URI têm seus ícones exibidos em vários locais em todo o sistema, como no painel de controle de programas padrão. Inclua um ícone 44x44 com seu projeto para essa finalidade. Combine o visual do logotipo do bloco do aplicativo e use a cor de fundo do seu aplicativo em vez de deixar o ícone transparente. Faça o logotipo se estender até a borda, sem espaçamento. Teste seus ícones em planos de fundo brancos. Consulte Ícones e logotipos de aplicativos para obter mais detalhes sobre ícones.

Etapa 3: Manipular o evento ativado

• Windows.UI.Xaml.Application.OnActivated

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 obter mais detalhes sobre como iniciar um aplicativo por meio de um URI, consulte Iniciar o aplicativo padrão para um URI.

É recomendável que os aplicativos criem um novo Frame XAML para cada evento de ativação que abre uma nova página. Dessa forma, a pilha de navegação do novo Frame XAML não conterá nenhum conteúdo anterior que o aplicativo possa ter na janela atual quando suspenso. Aplicativos que decidem usar um único Frame XAML para contratos de inicialização e de arquivo devem limpar as páginas do histórico de navegação do Frame antes de navegar para uma nova página.

Quando iniciados por meio da ativação de protocolo, os aplicativos devem considerar incluir uma interface que permita ao usuário voltar para a página inicial do aplicativo.

Considerações de segurança

Qualquer aplicativo ou site pode invocar seu esquema de URI com cargas arbitrárias, incluindo as mal-intencionadas. Trate todos os parâmetros de URI como entrada não confiável. Siga estas práticas:

• Nunca execute ações irreversíveis (excluir arquivos, modificar dados da conta, enviar mensagens) com base apenas em parâmetros de URI.
• Valide e sanitize todos os parâmetros antes do uso. Verifique se há caracteres inesperados, sequências de atravessamento de caminho (../) e valores fora da faixa esperada.
• Rejeitar esquemas ou hosts inesperados. Se o seu manipulador espera apenas alsdk://action, verifique se o host e o caminho correspondem a uma lista de permissões de padrões conhecidos antes de processá-los.
• Nenhuma identidade de chamador está disponível. Ao contrário de named pipes ou sockets, a ativação via URI não oferece uma maneira confiável de verificar qual processo enviou a URI. Qualquer processo (incluindo malware) pode iniciar seu esquema.
• Evite tratar parâmetros de URI como entrada executável. Não passe valores de consulta de URI diretamente para Process.Start, ShellExecute ou consultas SQL sem higienização.

Recomendamos que os aplicativos criem um novo Frame XAML para cada evento de ativação que abra um novo destino de URI. Dessa forma, a pilha de navegação do novo Frame XAML não conterá nenhum conteúdo anterior que o aplicativo possa ter na janela atual quando suspenso.

Se você decidir que deseja que seus aplicativos usem um único Frame XAML para contratos de inicialização e de protocolo, limpe as páginas do histórico de navegação do Frame antes de navegar para uma nova página. Ao realizar o lançamento via Protocol Contract, considere incluir em seus aplicativos uma interface que permita ao usuário retornar ao topo do aplicativo.

Conteúdo relacionado

• Ativação do protocolo URIHandle em um aplicativo WPF
• Ativação avançada com a API de ciclo de vida do aplicativo
• Lançamento de exemplo de associação UWP
• Programas padrão
• Manipular a ativação do arquivo