Gestire l'attivazione di URI

  • Articolo

API importanti

Scopri come registrare un’app in modo che diventi il gestore predefinito per un nome di schema URI (Uniform Resource Identifier). Sia le app desktop di Windows che le app piattaforma UWP (Universal Windows Platform) possono essere registrate come gestore predefinito per un nome di schema URI. Se l'utente sceglie l'app come gestore predefinito per un nome di schema URI, l'app verrà attivata ogni volta che viene avviato quel tipo di URI.

È consigliabile registrarsi solo per un nome di schema URI se si prevede di gestire tutti i lanci URI per quel tipo di schema URI. Se si sceglie di eseguire la registrazione per un nome di schema URI, è necessario fornire all'utente finale la funzionalità prevista quando l'app viene attivata per lo schema URI. Ad esempio, un'app che esegue la registrazione per il nome dello schema URI mailto: deve essere aperta a una nuova e-mail di posta elettronica in modo che l'utente possa comporre una nuova e-mail. Per maggiori informazioni sulle associazioni URI, vedere Linee guida ed elenco di controllo per i tipi di file e gli URI.

Questi passaggi illustrano come eseguire la registrazione per un nome di schema URI personalizzato, alsdk://e come attivare l'app quando l'utente avvia un alsdk:// URI.

Nota

Nelle app UWP alcuni URI ed estensioni di file sono riservati per l'uso da parte di app predefinite e del sistema operativo. I tentativi di registrare l'app con un URI o un'estensione di file riservata verranno ignorati. Vedere Nomi di schemi URI riservati e tipi di file per un elenco alfabetico di schemi URI che non possono registrare per le app UWP perché sono riservate o non consentite.

Passaggio 1: Specificare il punto di estensione nel manifesto del pacchetto

L'app riceve gli eventi di attivazione solo per i nomi degli schemi URI elencati nel manifesto del pacchetto. Ecco come indicare che l'app gestisce il nome dello schema alsdk URI.

  1. In Esplora soluzioni fare doppio clic su package.appxmanifest per aprire il designer del manifesto. Selezionare la scheda Dichiarazioni e nel menu a discesa Dichiarazioni disponibili selezionare Protocollo e fare clic su Aggiungi.

    Di seguito è riportata una breve descrizione di ognuno dei campi che è possibile compilare nella finestra di progettazione del manifesto per il protocollo (vedere Manifesto del pacchetto AppX per informazioni dettagliate):

Campo Descrizione
Logo Specificare il logo utilizzato per identificare il nome dello schema URI in Imposta programmi predefiniti sul Pannello di controllo. Se non viene specificato alcun logo, viene usato il logo piccolo per l'app.
Nome visualizzato Specificare il nome visualizzato per identificare il nome dello schema URI in Imposta programmi predefiniti sul Pannello di controllo.
Nome Scegliere un nome per lo schema URI.
Nota Il nome deve essere in lettere minuscole.
Tipi di file riservati e non consentiti Vedere Nomi di schemi URI riservati e tipi di file per un elenco alfabetico di schemi URI che non si possono registrare per le app UWP perché sono riservate o non consentite.
File eseguibile Specifica il file eseguibile di avvio predefinito per il protocollo. Se non specificato, viene usato il file eseguibile dell'app. Se specificato, la stringa deve avere una lunghezza compresa tra 1 e 256 caratteri, deve terminare con ".exe" e non può contenere questi caratteri: > , <, :, ", |, ?, o *. Se specificato, viene utilizzato anche il punto di ingresso. Se il punto di ingresso non viene specificato, viene usato il punto di ingresso definito per l'app.
Punto di accesso Specifica l'attività che gestisce l'estensione del protocollo. Si tratta in genere del nome completo dello spazio dei nomi di un tipo Windows Runtime. Se non specificato, viene usato il punto di ingresso per l'app.
Pagina iniziale Pagina web che gestisce il punto di estendibilità.
Gruppo di risorse Tag che è possibile usare per raggruppare le attivazioni dell'estensione per scopi di gestione delle risorse.
Vista desiderata (solo Windows) Specificare il campo Vista desiderata per indicare la quantità di spazio necessaria per la finestra dell'app quando viene avviata per il nome dello schema URI. I valori possibili per Desired View sono Default, UseLess, UseHalf, UseMore o UseMinimum.
Nota Windows tiene conto di più fattori diversi quando determina le dimensioni finali della finestra dell'app di destinazione, ad esempio la preferenza dell'app di origine, il numero di app sullo schermo, l'orientamento dello schermo e così via. L'impostazione della Vista desiderata non garantisce un comportamento della finestra specifico per l'app di destinazione.
Famiglia di dispositivi mobili: Vista desiderata non è supportato nella famiglia di dispositivi mobili.

  1. Immettere images\Icon.png come Logo.

  2. Immettere SDK Sample URI Scheme come nome visualizzato

  3. Immettere alsdk in Nome.

  4. Premere CTRL+S per salvare la modifica in package.appxmanifest.

    In questo modo viene aggiunto un elemento Estensione come questo al manifesto del pacchetto. La categoria windows.protocol indica che l'app gestisce il nome alsdk dello schema 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>

Passaggio 2: Aggiungere le icone appropriate

Le app che diventano l'impostazione predefinita per un nome di schema URI hanno le icone visualizzate in varie posizioni nel sistema, ad esempio nel pannello di controllo Programmi predefiniti. Includere un'icona 44x44 con il progetto a questo scopo. Trovare la corrispondenza con l'aspetto del logo del riquadro dell'app e usare il colore di sfondo dell'app invece di rendere trasparente l'icona. Fare in modo che il logo si estenda al bordo senza riempimento. Testare le icone su sfondi bianchi. Per maggiori informazioni sulle icone, vedere Icone e logo dell'app.

Passaggio 3: Gestire l'evento attivato

Il gestore eventi OnActivated riceve tutti gli eventi di attivazione. La proprietà Kind indica il tipo di evento di attivazione. Questo esempio è configurato per gestire gli eventi di attivazione del Protocollo.

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

Nota

Quando viene avviato tramite contratto protocollo, assicurarsi che il pulsante Indietro riporti l'utente alla schermata che ha avviato l'app e non al contenuto precedente dell'app.

Il codice seguente avvia l'app a livello di codice tramite il relativo URI:

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

Per altre informazioni su come avviare un'app tramite un URI, vedere Avviare l'app predefinita per un URI.

È consigliabile che le app creino un nuovo Frame XAML per ogni evento di attivazione che apre una nuova pagina. In questo modo, il backstack di spostamento per il nuovo Frame XAML non conterrà alcun contenuto precedente che l'app potrebbe avere nella finestra corrente quando è sospesa. Le app che decidono di usare un singolo Frame XAML per Launch e File Contracts devono cancellare le pagine nel journal di spostamento Frame prima di passare a una nuova pagina.

Quando viene avviata tramite l'attivazione del protocollo, le app devono prendere in considerazione l'inclusione dell'interfaccia utente che consente all'utente di tornare alla pagina superiore dell'app.

Osservazioni:

Qualsiasi app o sito web può usare il nome dello schema URI, inclusi quelli dannosi. Di conseguenza, tutti i dati che si ottengono nell'URI potrebbero provenire da un'origine non attendibile. È consigliabile non eseguire mai un'azione permanente in base ai parametri ricevuti nell'URI. Ad esempio, i parametri URI possono essere usati per avviare l'app nella pagina dell'account di un utente, ma è consigliabile non usarli mai per modificare direttamente l'account dell'utente.

Nota

Se stai creando un nuovo nome di schema URI per la tua app, assicurati di seguire le indicazioni in RFC 4395. Ciò garantisce che il nome soddisfi gli standard per gli schemi URI.

Nota

Quando viene avviato tramite contratto protocollo, assicurarsi che il pulsante Indietro riporti l'utente alla schermata che ha avviato l'app e non al contenuto precedente dell'app.

È consigliabile che le app creino un nuovo Frame XAML per ogni evento di attivazione che apre un nuovo target Uri. In questo modo, il backstack di spostamento per il nuovo Frame XAML non conterrà alcun contenuto precedente che l'app potrebbe avere nella finestra corrente quando è sospesa.

Se si decide di volerei che le app usino un singolo Frame XAML per contratti di avvio e protocollo, cancellare le pagine nel journal di navigazione Frame prima di passare a una nuova pagina. Quando viene avviato tramite contratto protocollo, prendere in considerazione l'inclusione dell'interfaccia utente nelle app che consente all'utente di tornare all'inizio dell'app.

Completare l'app di esempio

Concetti

Attività

Linee guida

Riferimento