Gérer l’activation des URI

  • Article

API importantes

Découvrez comment inscrire une application afin qu’elle devienne le gestionnaire par défaut d’un nom de schéma d’URI (Uniform Resource Identifier). Tant les applications de bureau Windows que les applications de plateforme Windows universelle (UWP) peuvent s’inscrire pour devenir gestionnaire par défaut pour un nom de schéma d’URI. Si l’utilisateur choisit votre application en tant que gestionnaire par défaut pour un nom de schéma d’URI, celle-ci sera activée à chaque lancement de ce type d’URI.

Nous vous recommandons de vous inscrire pour un nom de schéma d’URI uniquement si vous pensez gérer tous les lancements d’URI pour ce type de schéma d’URI. Si vous choisissez de vous inscrire pour un nom de schéma d’URI, vous devez fournir à l’utilisateur final la fonctionnalité attendue lorsque votre application est activée pour ce schéma d’URI. Par exemple, une application qui s’inscrit pour le nom de schéma d’URI mailto: doit ouvrir un nouveau message électronique de sorte que l’utilisateur puisse composer un nouveau message électronique. Pour plus d’informations sur les associations d’URI, voir Recommandations et liste de vérification des types de fichier et des URI.

Ces étapes montrent comment s’inscrire à un nom de schéma d’URI personnalisé, alsdk://et comment activer votre application lorsque l’utilisateur lance un alsdk:// URI.

Notes

Dans les applications UWP, certains URI et extensions de fichiers sont réservés pour une utilisation par les applications intégrées et le système d’exploitation. Toute tentative d’inscription de votre application avec une extension de fichier ou un URI réservés sera ignorée. Pour obtenir la liste alphabétique des schémas d’URI que vous ne pouvez pas inscrire pour vos applications UWP parce qu’ils sont réservés ou interdits, voir Noms de schéma d’URI réservé et types de fichier.

Étape 1 : spécifier le point d’extension dans le manifeste du package

L’application reçoit des événements d’activation uniquement pour les noms de schémas d’URI répertoriés dans le manifeste du package. Voici comment indiquer que votre application gère le nom du schéma d’URI alsdk .

  1. Dans l’Explorateur de solutions, double-cliquez sur package.appxmanifest pour ouvrir le concepteur de manifeste. Sélectionnez l’onglet Déclarations. Dans la liste déroulante Déclarations disponibles, sélectionnez Protocole, puis cliquez sur Ajouter.

    Voici une brève description de chacun des champs que vous pouvez remplir dans le concepteur de manifeste pour le protocole (voir Manifeste du package AppX pour plus de détails) :

Champ Description
Logo Spécifiez le logo qui est utilisé pour identifier le nom de schéma d’URI dans Définir les programmes par défaut du Panneau de configuration. Si aucune valeur n’est spécifiée pour Logo, le petit logo de l’application est utilisé.
Nom complet Spécifiez le nom d’affichage pour identifier le nom de schéma d’URI dans Définir les programmes par défaut du Panneau de configuration.
Nom Choisissez le nom du schéma d’URI.
Remarque Le nom doit être entièrement en minuscules.
Types de fichier réservé et interdit Pour obtenir la liste alphabétique des schémas d’URI que vous ne pouvez pas inscrire pour vos applications UWP parce qu’ils sont réservés ou interdits, voir Noms de schéma d’URI réservé et types de fichier.
Exécutable Spécifie l’exécutable de lancement par défaut pour le protocole. En l’absence de spécification, le fichier exécutable de l’application est utilisé. Si elle est spécifiée, la chaîne doit comporter entre 1 et 256 caractères, doit se terminer par « .exe » et ne peut pas contenir les caractères suivants : >, <, : , , « , | , ?, ou *. En cas de spécification, le Point d’entrée est également utilisé. Si le Point d’entrée n’est pas spécifié, le point d’entrée défini pour l’application est utilisé.
Point d’entrée Spécifie la tâche qui gère l’extension de protocole. Il s’agit généralement du nom complet de l’espace de noms d’un type Windows Runtime. En l’absence de spécification, le point d’entrée de l’application est utilisé.
Page d’accueil La page web qui gère le point d’extensibilité.
Groupe de ressources Une balise que vous pouvez utiliser pour regrouper les activations d’extensions à des fins de gestion des ressources.
Affichage souhaité (Windows uniquement) Spécifiez le champ Affichage souhaité pour indiquer la quantité d’espace nécessaire à la fenêtre de l’application quand elle est lancée pour le nom de schéma d’URI. Les valeurs possibles du champ Affichage souhaité sont Default, UseLess, UseHalf, UseMore ou UseMinimum.
Remarque Windows tient compte de différents facteurs pour déterminer la taille finale de la fenêtre de l’application cible, par exemple, la préférence de l’application source, le nombre d’applications à l’écran, l’orientation de l’écran, etc. La définition du champ Affichage souhaité ne garantit pas un comportement de fenêtrage spécifique pour l’application cible.
Famille d’appareils mobiles : Affichage souhaité n’est pas pris en charge dans la famille d’appareils mobiles.

  1. Entrez images\Icon.png comme Logo.

  2. Entrez SDK Sample URI Scheme comme Nom d’affichage.

  3. Entrez alsdk comme Nom.

  4. Appuyez sur Ctrl+S pour enregistrer la modification dans package.appxmanifest.

    Cette opération ajoute un élément Extension tel que celui-ci dans le manifeste du package. La catégorie windows.protocol indique que l’application gère le nom de schéma d’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>

Étape 2 : Ajouter les icônes appropriées

Les icônes des applications qui deviennent la valeur par défaut pour un nom de schéma d’URI sont affichées à différents endroits dans le système, par exemple dans le panneau de configuration Programmes par défaut. Incluez une icône 44x44 avec votre projet à cet effet. Reproduisez l’apparence du logo de la vignette de l’application et utilisez la couleur d’arrière-plan de celle-ci au lieu de rendre l’icône transparente. Faites en sorte que le logo s’étende jusqu’au bord sans remplissage. Testez vos icônes sur des arrière-plans blancs. Pour plus d’informations sur les icônes et les logos d’application, consultez Icônes d’application et logos .

Étape 3 : Gérer l’événement activé

Le gestionnaire d’événements OnActivated reçoit tous les événements d’activation. La propriété Kind indique le type d’événement d’activation. Cet exemple est configuré pour gérer les événements d’activation de protocole .

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

Notes

Lorsqu’il est lancé via le contrat de protocole, assurez-vous que le bouton Précédent ramène l’utilisateur à l’écran qui a lancé l’application et non au contenu précédent de l’application.

Le code suivant lance l’application par programmation via son URI :

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

Pour plus d’informations sur le lancement d’une application via un URI, consultez Lancer l’application par défaut pour un URI.

Il est recommandé aux applications de créer une trame XAML pour chaque événement d’activation qui ouvre une nouvelle page. De cette façon, le backstack de navigation pour le nouveau cadre XAML ne contiendra aucun contenu précédent que l’application pourrait avoir sur la fenêtre actuelle lors de sa suspension. Les applications qui décident d’utiliser un seul Frame XAML pour le lancement et les contrats de fichier doivent effacer les pages du journal de navigation du Frame avant de naviguer vers une nouvelle page.

En cas de lancement via l’activation de protocole, les applications doivent envisager d’inclure une interface utilisateur permettant à l’utilisateur de revenir à la première page de l’application.

Remarques

N’importe quelle application ou n’importe quel site web peut utiliser votre nom de schéma d’URI, y compris des applications et sites malveillants. Par conséquent, toute donnée reçue dans cet URI peut provenir d’une source non approuvée. Nous vous recommandons de ne jamais effectuer une action permanente en fonction des paramètres que vous recevez dans un URI. Par exemple, les paramètres d’URI peuvent être utilisés pour lancer l’application sur la page de compte d’un utilisateur, mais nous vous recommandons de ne jamais les utiliser pour modifier directement le compte de l’utilisateur.

Notes

Si vous créez un nouveau nom de schéma d’URI pour votre application, veillez à suivre les instructions de la RFC 4395. Cela permet de garantir que votre nom respecte les normes applicables aux schémas d’URI.

Notes

Lorsqu’il est lancé via le contrat de protocole, assurez-vous que le bouton Précédent ramène l’utilisateur à l’écran qui a lancé l’application et non au contenu précédent de l’application.

Nous recommandons aux applications de créer une trame XAML pour chaque événement d’activation qui ouvre une nouvelle cible URI. De cette façon, le backstack de navigation pour le nouveau cadre XAML ne contiendra aucun contenu précédent que l’application pourrait avoir sur la fenêtre actuelle lors de sa suspension.

Si vous décidez que vos applications doivent utiliser un seul Frame XAML pour le lancement et les contrats de protocole, effacez les pages du journal de navigation du Frame avant de naviguer vers une nouvelle page. En cas de lancement via le contrat de protocole, envisagez d’inclure une interface utilisateur permettant à l’utilisateur de revenir en haut de l’application.

Compléter l’exemple d’application

Concepts

Tâches

Consignes

Référence