Manipular a ativação do URI

APIs importantes

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

Saiba como registrar um aplicativo para ser o manipulador padrão de um nome de esquema de URI (Uniform Resource Identifier). Os aplicativos da área de trabalho do Windows e os aplicativos UWP (Plataforma Universal do Windows) 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ê só se registre 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 de URI mailto: deve abrir uma nova mensagem de email para que o usuário possa redigir um novo email. Para obter mais informações sobre associações de URI, consulte Diretrizes e lista de verificação para tipos de arquivo e URIs.

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

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

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

1. No Gerenciador de Soluções, clique duas vezes em package.appxmanifest para abrir o designer de manifesto. Selecione a guia Declarações e, na lista suspensa Declarações Disponíveis , selecione Protocolo e 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 Manifesto do pacote AppX para obter detalhes):

2. Digite images\Icon.png como o logotipo.

3. Digite 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 alsdk 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: adicione 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 Programas padrão. Inclua um ícone 44x44 com seu projeto para essa finalidade. Combine a aparência do logotipo do bloco do aplicativo e use a cor da tela de fundo do aplicativo em vez de tornar o ícone transparente. Faça com que o logotipo se estenda até a borda sem preenchê-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

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 está configurado para lidar com 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
      }
   }
}

Protected Overrides Sub OnActivated(ByVal args As Windows.ApplicationModel.Activation.IActivatedEventArgs)
   If args.Kind = ActivationKind.Protocol Then
      ProtocolActivatedEventArgs eventArgs = args As ProtocolActivatedEventArgs
      
      ' TODO: Handle URI activation
      ' The received URI is eventArgs.Uri.AbsoluteUri
 End If
End Sub

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 quadro XAML para cada evento de ativação que abre uma nova página. Dessa forma, a backstack de navegação para o novo Quadro XAML não conterá nenhum conteúdo anterior que o aplicativo possa ter na janela atual quando suspenso. Os aplicativos que decidem usar um único quadro XAML para contratos de inicialização e arquivo devem limpar as páginas no diário de navegação do quadro antes de navegar para uma nova página.

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

Comentários

Qualquer aplicativo ou site pode usar o nome do seu esquema de URI, incluindo os maliciosos. Portanto, todos os dados obtidos 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 os aplicativos criem um novo quadro XAML para cada evento de ativação que abre um novo destino de Uri. Dessa forma, a backstack de navegação para o novo Quadro 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 quadro XAML para contratos de inicialização e protocolo, limpe as páginas no diário de navegação do quadro antes de navegar para uma nova página. Quando iniciado por meio do Contrato de Protocolo, considere incluir a interface do usuário em seus aplicativos que permita que o usuário volte para a parte superior do aplicativo.

Tópicos relacionados

Aplicativo de exemplo completo

• Exemplo de lançamento de associação

Conceitos

• Programas padrão
• Tipo de arquivo e modelo de associações de URI

Tarefas

• Iniciar o app padrão para um URI
• Manipular a ativação do arquivo

Diretrizes

• Diretrizes para tipos de arquivo e URIs

Referência

• Manifesto do pacote AppX
• Windows.ApplicationModel.Activation.ProtocolActivatedEventArgs
• Windows.UI.Xaml.Application.OnActivated