Compartilhar via

Manipular a ativação do URI

  • Artigo

APIs importantes

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.

Observação

Em aplicativos UWP, determinados URIs e extensões de arquivo são reservados para uso por aplicativos internos e pelo sistema operacional. As tentativas de registrar seu aplicativo com um URI reservado ou extensão de arquivo serão ignoradas. Consulte Nomes de esquema de URI reservado e tipos de arquivo para obter uma lista alfabética de esquemas de URI que você não pode registrar para seus aplicativos UWP porque eles são reservados ou proibidos.

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):

Campo Descrição
Logotipo Especifique o logotipo usado para identificar o nome do esquema de URI em Definir Programas Padrão no Painel de Controle. Se nenhum logotipo for especificado, o logotipo pequeno do aplicativo será usado.
Nome de Exibição Especifique o nome de exibição para identificar o nome do esquema de URI em Definir programas padrão no Painel de controle.
Nome Escolha um nome para o esquema de Uri.
Observação O nome deve estar em letras minúsculas.
Tipos de arquivo reservados e proibidos Consulte Nomes de esquema de URI reservado e tipos de arquivo para obter uma lista alfabética de esquemas de URI que você não pode registrar para seus aplicativos UWP porque eles são reservados ou proibidos.
Executável Especifica o executável de inicialização padrão para o protocolo. Se não for especificado, o executável do aplicativo será usado. Se especificada, a cadeia de caracteres deve ter entre 1 e 256 caracteres de comprimento, deve terminar com ".exe" e não pode conter estes caracteres: >, <, :, ", |, ? ou *. Se especificado, o ponto de entrada também é usado. Se o ponto de entrada não for especificado, o ponto de entrada definido para o aplicativo será usado.
Ponto de entrada Especifica a tarefa que manipula a extensão do protocolo. Normalmente, esse é o nome totalmente qualificado para namespace de um tipo do Tempo de Execução do Windows. Se não for especificado, o ponto de entrada do aplicativo será usado.
Página inicial A página da Web que manipula o ponto de extensibilidade.
Grupo de recursos Uma marca que você pode usar para agrupar ativações de extensão para fins de gerenciamento de recursos.
Exibição desejada (somente Windows) Especifique o campo Exibição desejada para indicar a quantidade de espaço que a janela do aplicativo precisa quando é iniciada para o nome do esquema de URI. Os valores possíveis para a Exibição desejada são Default, UseLess, UseHalf, UseMore ou UseMinimum.
Observação O Windows leva em conta vários fatores diferentes ao determinar o tamanho final da janela do aplicativo de destino, por exemplo, a preferência do aplicativo de origem, o número de aplicativos na tela, a orientação da tela e assim por diante. Definir o Modo de Exibição Desejado não garante um comportamento de janela específico para o aplicativo de destino.
Família de dispositivos móveis: a Exibição desejada não é compatível com a família de dispositivos móveis.

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

  2. Digite SDK Sample URI Scheme como o nome de exibição

  3. Insira alsdk como Nome.

  4. 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
   }
}

Observação

Quando iniciado por meio do Contrato de Protocolo, certifique-se de que o botão Voltar leve o usuário de volta à tela que iniciou o aplicativo e não ao conteúdo anterior do aplicativo.

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.

Observação

Se você estiver criando um novo nome de esquema de URI para seu aplicativo, siga as diretrizes no RFC 4395. Isso garante que seu nome atenda aos padrões para esquemas de URI.

Observação

Quando iniciado por meio do Contrato de Protocolo, certifique-se de que o botão Voltar leve o usuário de volta à tela que iniciou o aplicativo e não ao conteúdo anterior do aplicativo.

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.

Aplicativo de exemplo completo

Conceitos

Tarefas

Diretrizes

Referência