Manipular 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). Aplicativos da área de trabalho do Windows e 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 ser aberto para 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 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.GetActivatedEventArgs
Nota
No Windows, determinadas URIs e extensões de arquivo são reservadas 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 reservados e tipos de arquivo para obter uma lista alfabética de esquemas de Uri que você não pode registrar para seus aplicativos 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 somente para os nomes de esquema de URI listados no manifesto do pacote. Veja como você indica que seu aplicativo manipula o nome do esquema de URI alsdk.
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 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):
| Campo | Descrição |
|---|---|
| logo | Especifique o logotipo usado para identificar o nome do esquema de URI no 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 no Definir programas padrão no painel de controle . |
| Nome | Escolha um nome para o esquema Uri. |
| Observação O Nome deve estar em todas as letras minúsculas. | |
| Tipos de arquivo reservados e proibidos Consulte Nomes de esquema de URI reservados e tipos de arquivo para uma lista alfabética de esquemas de URI que você não pode registrar para seus aplicativos do Windows 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 especificado, a cadeia de caracteres deve ter entre 1 e 256 caracteres de comprimento, deve terminar com ".exe", e não pode conter esses caracteres: >, <, :, ", |, ?ou *. Caso especificado, o ponto de entrada também será 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 de protocolo. Normalmente, esse é o nome totalmente qualificado para namespace de um tipo do Windows Runtime. Se não for especificado, o ponto de entrada do aplicativo será usado. |
| Página Inicial | A página web que gerencia 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. |
| de Visualização Desejada (somente Windows) | Especifique o campo Modo de Exibição Desejado para indicar a quantidade de espaço que a janela do aplicativo precisa quando ele é iniciado para o nome do esquema de URI. Os valores possíveis para modo de exibição desejado são Padrão, Menos Uso, Meia Utilização, Mais Usoou Uso Mínimo. 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. Configurar o Modo de Exibição Desejado não garante um comportamento específico de janela para o aplicativo de destino. Família de dispositivos móveis: não é compatível com a Vista Desejada na família de dispositivos móveis. |
Insira
images\Icon.pngcomo o logotipo do .Insira
SDK Sample URI Schemecomo o nome de exibiçãoInsira
alsdkcomo nome .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
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. Corresponda à 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 a paginá-lo. Teste seus ícones em planos de fundo brancos. Consulte ícones e logotipos do aplicativo para obter mais detalhes sobre ícones.
Etapa 3: Manipular o evento ativado
Nota
Em um aplicativo WinUI, em App.OnLaunched (ou de fato a qualquer momento) você pode chamar (AppInstance.GetActivatedEventArgs) para recuperar os args de evento ativados e verificá-los para determinar como o aplicativo foi ativado. Consulte Migração de funcionalidade de ciclo de vida do aplicativo para obter mais informações sobre diferenças de ciclo de vida entre aplicativos UWP e WinUI.
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 lidar com eventos de ativação do 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
}
}
Nota
Quando iniciado por meio do Contrato de Protocolo, certifique-se de que o botão Voltar leve o usuário de volta para a tela que iniciou o aplicativo e não para o 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 Frame XAML para cada evento de ativação que abre uma nova página. Dessa forma, o backstack de navegação para o novo Frame XAML não conterá nenhum conteúdo anterior que o aplicativo possa ter na janela atual quando o aplicativo for suspenso. Os aplicativos que decidem usar um único Frame de XAML para Contratos de Inicialização e Arquivo devem limpar as páginas no diário 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.
Observações
Qualquer aplicativo ou site pode usar o nome do seu esquema de URI, incluindo aplicativos ou sites mal-intencionados. 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, 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.
Nota
Se você estiver criando um novo nome de esquema de URI para seu aplicativo, siga as diretrizes em RFC 4395. Isso garante que seu nome atenda aos padrões de esquemas de URI.
Nota
Quando um aplicativo UWP é iniciado por meio do Contrato de Protocolo, verifique se o botão Voltar leva o usuário de volta para a tela que iniciou o aplicativo e não para o conteúdo anterior do aplicativo.
Recomendamos que os aplicativos criem um novo Frame XAML para cada evento de ativação que abre um novo destino de Uri. Dessa forma, a pilha de navegação para o novo quadro XAML não conterá nenhum conteúdo anterior que o aplicativo poderia ter tido 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 de um Contrato de Protocolo, considere incluir uma interface de usuário nos seus aplicativos que permita ao usuário voltar para o início do aplicativo.
Conteúdo relacionado
Windows developer