Aggiunta del supporto I miei contatti a un'applicazione

  • Articolo

Importante

I miei contatti non è più supportato nelle versioni di Windows 11 e Windows 10 con KB5034203 applicate.

Nota

A partire dall'aggiornamento di Windows 10 (maggio 2019) (versione 1903), le nuove installazioni di -Windows 10 non visualizzeranno più i contatti nella barra delle applicazioni per impostazione predefinita. Gli utenti possono abilitare la funzionalità facendo clic con il pulsante destro del mouse sulla barra delle applicazioni e premendo "Mostra contatti sulla barra delle applicazioni". Gli sviluppatori sono scoraggiati dall'aggiungere supporto a I miei contatti nelle applicazioni e li si invita a visitare il blog per sviluppatori Windows per altre informazioni sull'ottimizzazione delle app per Windows 10.

La funzionalità I miei contatti consente agli utenti di aggiungere contatti da un'applicazione direttamente alla barra delle applicazioni, creando un nuovo oggetto contatto con cui possono interagire in diversi modi. Questo articolo illustra come aggiungere il supporto per questa funzionalità, consentendo agli utenti di aggiungere contatti direttamente dall'app. Quando i contatti vengono aggiunti, diventano disponibili nuovi tipi di interazione utente, ad esempio la condivisione e le notifiche sui contatti personali.

My people chat

Requisiti

Panoramica

È necessario eseguire tre operazioni per consentire all'applicazione di usare la funzionalità I miei contatti:

  1. Dichiarare il supporto per il contratto di attivazione shareTarget nel manifesto dell'applicazione.
  2. Annotare i contatti che gli utenti possono condividere con l'app.
  3. Supportare più istanze dell'applicazione in esecuzione contemporaneamente. Gli utenti devono essere in grado di interagire con una versione completa dell'applicazione durante l'uso in un pannello dei contatti. Possono anche usarlo in più pannelli di contatto contemporaneamente. Per supportare questo problema, l'applicazione deve essere in grado di eseguire più visualizzazioni contemporaneamente. Per informazioni su come eseguire questa operazione, vedere l'articolo "Mostrare più visualizzazioni per un'app".

Al termine, l'applicazione verrà visualizzata nel pannello dei contatti per i contatti con annotazioni.

Dichiarazione del supporto per il contratto

Per dichiarare il supporto per il contratto I miei contatti, aprire l'applicazione in Visual Studio. In Esplora soluzioni fare clic con il pulsante destro del mouse sul file Package.appxmanifest e selezionare Apri con. Dal menu selezionare Editor XML (testo) e fare clic su OK. Apportare le modifiche seguenti al manifesto:

Prima

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10">

	<Applications>
	    <Application Id="MyApp"
	      Executable="$targetnametoken$.exe"
	      EntryPoint="My.App">
	    </Application>
	</Applications>

Dopo

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap4="http://schemas.microsoft.com/appx/manifest/uap/windows10/4">

	<Applications>
	    <Application Id="MyApp"
	      Executable="$targetnametoken$.exe"
	      EntryPoint="My.App">
	      <Extensions>
	        <uap4:Extension Category="windows.contactPanel" />
	      </Extensions>
	    </Application>
	</Applications>

Con questa aggiunta, l'applicazione può ora essere avviata tramite il contratto windows.ContactPanel, che consente di interagire con i pannelli di contatto.

Annotazione dei contatti

Per consentire la visualizzazione dei contatti dall'app nella barra delle applicazioni tramite il riquadro I miei contatti, è necessario scriverli nell'archivio contatti di Windows. Per informazioni su come scrivere i contatti, vedere l'esempio di scheda contatto.

L'applicazione deve anche scrivere un'annotazione in ogni contatto. Le annotazioni sono parti di dati dell'applicazione associate a un contatto. L'annotazione deve contenere la classe attivabile corrispondente alla visualizzazione desiderata nel membro ProviderProperties e dichiarare il supporto per l'operazione ContactProfile.

È possibile annotare i contatti in qualsiasi momento mentre l'app è in esecuzione, ma in genere conviene annotare i contatti non appena vengono aggiunti all'archivio contatti di Windows.

if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 5))
{
	// Create a new contact annotation
	ContactAnnotation annotation = new ContactAnnotation();
	annotation.ContactId = myContact.Id;

	// Add appId and contact panel support to the annotation
	String appId = "MyApp_vqvv5s4y3scbg!App";
	annotation.ProviderProperties.Add("ContactPanelAppID", appId);
	annotation.SupportedOperations = ContactAnnotationOperations.ContactProfile;

	// Save annotation to contact annotation list
	// Windows.ApplicationModel.Contacts.ContactAnnotationList 
	await contactAnnotationList.TrySaveAnnotationAsync(annotation));
}

"appId" è il nome della famiglia di pacchetti, seguito da '!' e dall'ID classe attivabile. Per trovare il nome della famiglia di pacchetti, aprire Package.appxmanifest usando l'editor predefinito e cercare nella scheda "Packaging". In questo caso, "App" è la classe attivabile corrispondente alla visualizzazione di avvio dell'applicazione.

Consentire ai contatti di invitare nuovi utenti potenziali

Per impostazione predefinita, l'applicazione verrà visualizzata solo nel pannello dei contatti per i contatti annotati in modo specifico. Ciò consente di non fare confusione con i contatti con i quali non è possibile interagire tramite l'app. Se si desidera che l'applicazione venga visualizzata per i contatti che l'applicazione non conosce (ad esempio per invitare gli utenti ad aggiungere tale contatto al proprio account), è possibile aggiungere quanto segue al manifesto:

Prima

<Applications>
	<Application Id="MyApp"
	  Executable="$targetnametoken$.exe"
	  EntryPoint="My.App">
	  <Extensions>
    	<uap4:Extension Category="windows.contactPanel" />
	  </Extensions>
	</Application>
</Applications>

Dopo

<Applications>
	<Application Id="MyApp"
	  Executable="$targetnametoken$.exe"
	  EntryPoint="My.App">
	  <Extensions>
		<uap4:Extension Category="windows.contactPanel">
	    	<uap4:ContactPanel SupportsUnknownContacts="true" />
		</uap4:Extension>
	  </Extensions>
	</Application>
</Applications>

Con questa modifica, l'applicazione verrà visualizzata come opzione disponibile nel pannello dei contatti per tutti i contatti aggiunti dall'utente. Quando l'applicazione viene attivata usando il contratto del pannello di contatto, è necessario verificare se il contatto è conosciuto dall'applicazione. In caso contrario, dovrebbe essere visualizzata la nuova esperienza utente dell'app.

My People contact panel

Supporto per le app di posta elettronica

Nel caso di app di posta elettronica non è necessario annotare manualmente ogni contatto. Se si dichiara il supporto per il riquadro contatti e per il protocollo mailto:, l'applicazione verrà visualizzata automaticamente per gli utenti con un indirizzo di posta elettronica.

Esecuzione nel pannello dei contatti

Ora che l'applicazione viene visualizzata nel pannello contatti per alcuni o tutti gli utenti, è necessario gestire l'attivazione con il contratto del pannello dei contatti.

override protected void OnActivated(IActivatedEventArgs e)
{
    if (e.Kind == ActivationKind.ContactPanel)
    {
        // Create a Frame to act as the navigation context and navigate to the first page
        var rootFrame = new Frame();

        // Place the frame in the current Window
        Window.Current.Content = rootFrame;

        // Navigate to the page that shows the Contact UI.
        rootFrame.Navigate(typeof(ContactPage), e);

        // Ensure the current window is active
        Window.Current.Activate();
    }
}

Quando l'applicazione viene attivata con questo contratto, riceverà un oggetto ContactPanelActivatedEventArgs. Contiene l'ID del contatto con cui l'applicazione sta tentando di interagire all'avvio e un oggetto ContactPanel. È consigliabile mantenere un riferimento a questo oggetto ContactPanel, perché consentirà di interagire con il pannello.

L'oggetto ContactPanel ha due eventi per i quali l'applicazione deve restare in ascolto:

  • L'evento LaunchFullAppRequested viene inviato quando l'utente ha richiamato l'elemento dell'interfaccia utente che richiede l'avvio dell'applicazione completa nella propria finestra. L'applicazione è responsabile dell'avvio stesso, passando tutto il contesto necessario. È possibile eseguire questa operazione come meglio si preferisce, ad esempio tramite l'avvio del protocollo.
  • L'evento Closing viene inviato quando l'applicazione sta per essere chiusa, consentendo di salvare qualsiasi contesto.

L'oggetto ContactPanel consente anche di impostare il colore di sfondo dell'intestazione del pannello di contatto (se non impostato, usa per impostazione predefinita il tema di sistema) e di chiudere a livello di codice il pannello dei contatti.

Supporto del badging delle notifiche

Se si desidera che i contatti aggiunti alla barra delle applicazioni vengano notificati quando arrivano nuove notifiche dall'app correlate a tale contatto, è necessario includere il parametro hint-people nelle notifiche di tipo avviso popup ed espressive di I miei contatti.

People notification badging

Per notificare un contatto, il nodo avviso popup di primo livello deve includere il parametro hint-people per indicare l'invio o il contatto correlato. Per il parametro è possibile specificare uno qualsiasi dei valori riportati di seguito:

Ecco un esempio di come identificare se una notifica di tipo avviso popup è correlata a un contatto specifico:

<toast hint-people="mailto:johndoe@mydomain.com">
    <visual lang="en-US">
        <binding template="ToastText01">
            <text>John Doe posted a comment.</text>
        </binding>
    </visual>
</toast>

Nota

Se l'app usa le API ContactStore e usa la proprietà StoredContact.RemoteId per collegare i contatti archiviati nel PC con i contatti archiviati in remoto, è essenziale che il valore della proprietà RemoteId sia stabile e univoco. Ciò significa che l'ID remoto deve identificare in modo coerente un singolo account utente e deve contenere un tag univoco per garantire che non sia in conflitto con gli ID remoti di altri contatti nel PC, inclusi i contatti di proprietà di altre app. Se gli ID remoti usati dall'app non sono necessariamente stabili e univoci, è possibile usare la classe RemoteIdHelper illustrata più avanti in questo argomento per aggiungere un tag univoco a tutti gli ID remoti prima di aggiungerli al sistema. In alternativa, è possibile scegliere di non usare affatto la proprietà RemoteId e creare invece una proprietà estesa personalizzata in cui archiviare gli ID remoti per i contatti.

Classe PinnedContactManager

PinnedContactManager viene usato per gestire i contatti aggiunti alla barra delle applicazioni. Questa classe consente di aggiungere e rimuovere contatti, determinare se un contatto è bloccato e determinare se l'aggiunta in una determinata superficie è supportata dal sistema in cui è attualmente in esecuzione l'applicazione.

È possibile recuperare l'oggetto PinnedContactManager usando il metodo GetDefault:

PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();

Aggiunta e rimozione di contatti

È ora possibile aggiungere e rimuovere contatti usando PinnedContactManager appena creato. I metodi RequestPinContactAsync e RequestUnpinContactAsync forniscono all'utente finestre di dialogo di conferma, quindi devono essere chiamati dal thread ASTA (Application Single Threaded Apartment).

async void PinContact (Contact contact)
{
    await pinnedContactManager.RequestPinContactAsync(contact,
                                                      PinnedContactSurface.Taskbar);
}

async void UnpinContact (Contact contact)
{
    await pinnedContactManager.RequestUnpinContactAsync(contact,
                                                        PinnedContactSurface.Taskbar);
}

È anche possibile aggiungere più contatti contemporaneamente:

async Task PinMultipleContacts(Contact[] contacts)
{
    await pinnedContactManager.RequestPinContactsAsync(
        contacts, PinnedContactSurface.Taskbar);
}

Nota

Attualmente non è disponibile alcuna operazione batch per rimuovere i contatti.

Nota:

Vedi anche