Aggiunta del supporto I miei contatti a un'applicazioneAdding My People support to an application

Nota

A partire da Windows 10 May 2019 Update (versione 1903), le nuove installazioni di Windows 10 non visualizzeranno più' people nella barra delle applicazioni ' per impostazione predefinita.As of the Windows 10 May 2019 Update (version 1903), new Windows 10 installations will no longer show ‘People in the taskbar’ by default. I clienti possono abilitare la funzionalità facendo clic con il pulsante destro del mouse sulla barra delle applicazioni e scegliendo "Mostra persone sulla barra delle applicazioni".Customers can enable the feature by right-clicking on the taskbar and pressing “Show People on the taskbar.” Gli sviluppatori sono sconsigliati di aggiungere il supporto personale alle applicazioni e dovrebbero visitare il Blog per sviluppatori Windows per altre informazioni sull'ottimizzazione delle app per Windows 10.Developers are discouraged from adding My People support to their applications, and should visit the Windows Developer Blog for more information about optimizing apps for Windows 10.

La funzionalità My People consente agli utenti di aggiungere contatti da un'applicazione direttamente alla relativa barra delle applicazioni, creando un nuovo oggetto contatto con cui è possibile interagire in diversi modi.The My People feature allows users to pin contacts from an application directly to their taskbar, which creates a new contact object that they can interact with in several ways. Questo articolo illustra come è possibile aggiungere il supporto per questa funzionalità, consentendo agli utenti di bloccare i contatti direttamente dall'app.This article shows how you can add support for this feature, allowing users to pin contacts directly from your app. Quando i contatti vengono aggiunti, i nuovi tipi di interazione utente diventano disponibili, ad esempio la condivisione e le notifichedegli utenti.When contacts are pinned, new types of user interaction become available, such as My People sharing and notifications.

Chat persone

RequisitiRequirements

PanoramicaOverview

Per consentire all'applicazione di usare la funzionalità My People, è necessario eseguire tre operazioni:There are three things you need to do to enable your application to use the My People feature:

  1. Dichiarare il supporto per il contratto di attivazione shareTarget nel manifesto dell'applicazione.Declare support for the shareTarget activation contract in your application manifest.
  2. Annotare i contatti che gli utenti possono condividere con l'app.Annotate the contacts that the users can share to using your app.
  3. Supportare più istanze dell'applicazione in esecuzione nello stesso momento.Support multiple instances of your application running at the same time. Gli utenti devono essere in grado di interagire con una versione completa dell'applicazione durante l'utilizzo in un pannello contatto.Users must be able to interact with a full version of your application while using it in a contact panel. Possono anche usarla in più pannelli di contatto.They may even use it in multiple contact panels at once. Per supportare questa operazione, l'applicazione deve essere in grado di eseguire contemporaneamente più visualizzazioni.To support this, your application needs to be able to run multiple views simultaneously. Per informazioni su come eseguire questa operazione, vedere l'articolo "visualizzare più visualizzazioni per un'app".To learn how to do this, see the article "show multiple views for an app".

Al termine dell'operazione, l'applicazione verrà visualizzata nel pannello contatto per i contatti con annotazioni.When you’ve done this, your application will appear in the contact panel for annotated contacts.

Dichiarazione del supporto per il contrattoDeclaring support for the contract

Per dichiarare il supporto per il contratto personale, aprire l'applicazione in Visual Studio.To declare support for the My People contract, open your application in Visual Studio. Dal Esplora soluzionifare clic con il pulsante destro del mouse su Package. appxmanifest e scegliere Apri con.From the Solution Explorer, right click Package.appxmanifest and select Open With. Dal menu selezionare editor XML (testo) e fare clic su OK.From the menu, select XML (Text) Editor) and click OK. Apportare le modifiche seguenti al manifesto:Make the following changes to the manifest:

PrimaBefore

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

DopoAfter

<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, è ora possibile avviare l'applicazione tramite le finestre. Contratto ContactPanel , che consente di interagire con i pannelli contatto.With this addition, your application can now be launched through the windows.ContactPanel contract, which allows you to interact with contact panels.

Annotazione di contattiAnnotating contacts

Per consentire la visualizzazione dei contatti dall'applicazione nella barra delle applicazioni tramite il riquadro personale, è necessario scriverli nell'archivio contatti di Windows.To allow contacts from your application to appear in the taskbar via the My People pane, you need to write them to the Windows contact store. Per informazioni su come scrivere i contatti, vedere l' esempio di scheda contatto.To learn how to write contacts, see the Contact Card sample.

L'applicazione deve inoltre scrivere un'annotazione per ogni contatto.Your application must also write an annotation to each contact. Le annotazioni sono parti di dati dell'applicazione associate a un contatto.Annotations are pieces of data from your application that are associated with a contact. L'annotazione deve contenere la classe attivabile corrispondente alla visualizzazione desiderata nel membro ProviderProperties e dichiarare il supporto per l'operazione ContactProfile .The annotation must contain the activatable class corresponding to your desired view in its ProviderProperties member, and declare support for the ContactProfile operation.

È possibile annotare i contatti in qualsiasi momento mentre l'app è in esecuzione, ma in genere è necessario annotare i contatti non appena vengono aggiunti all'archivio contatti di Windows.You can annotate contacts at any point while your app is running, but generally you should annotate contacts as soon as they are added to the Windows contact store.

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'!'The “appId” is the Package Family Name, followed by ‘!’ e l'ID della classe attivabile.and the activatable class ID. Per trovare il nome della famiglia di pacchetti, aprire Package. appxmanifest usando l'editor predefinito ed esaminare la scheda "packaging". Qui, "app" è la classe attivabile che corrisponde alla visualizzazione di avvio dell'applicazione.To find your Package Family Name, open Package.appxmanifest using the default editor, and look in the “Packaging” tab. Here, “App” is the activatable class corresponding to the application startup view.

Consenti ai contatti di invitare nuovi utenti potenzialiAllow contacts to invite new potential users

Per impostazione predefinita, l'applicazione verrà visualizzata solo nel pannello contatto per i contatti che sono stati annotati in modo specifico.By default, your application will only appear in the contact panel for contacts that you have specifically annotated. Questo consente di evitare confusione con i contatti che non possono interagire con l'app.This is to avoid confusion with contacts that can’t be interacted with through your app. Se si vuole che l'applicazione venga visualizzata per i contatti di cui l'applicazione non è a conoscenza (per invitare gli utenti ad aggiungere il contatto al proprio account, ad esempio), è possibile aggiungere quanto segue al manifesto:If you want your application to appear for contacts that your application doesn’t know about (to invite users to add that contact to their account, for instance), you can add the following to your manifest:

PrimaBefore

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

DopoAfter

<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 contatto per tutti i contatti aggiunti dall'utente.With this change, your application will appear as an available option in the contact panel for all contacts that the user has pinned. Quando l'applicazione viene attivata usando il contratto del pannello di contatto, è necessario verificare se il contatto è uno di cui l'applicazione è a conoscenza.When your application is activated using the contact panel contract, you should check to see if the contact is one your application knows about. In caso contrario, è consigliabile visualizzare la nuova esperienza utente dell'app.If not, you should show your app’s new user experience.

Pannello dei contatti I miei contatti

Supporto per le app di posta elettronicaSupport for email apps

Se si sta scrivendo un'app di posta elettronica, non è necessario annotare manualmente ogni contatto.If you are writing an email app, you don’t need to annotate every contact manually. Se si dichiara il supporto per il riquadro dei contatti e per il protocollo mailto:, l'applicazione verrà visualizzata automaticamente per gli utenti con un indirizzo di posta elettronica.If you declare support for the contact pane and for the mailto: protocol, your application will automatically appear for users with an email address.

In esecuzione nel pannello contattoRunning in the contact panel

Ora che l'applicazione viene visualizzata nel pannello contatto per alcuni o tutti gli utenti, è necessario gestire l'attivazione con il contratto del pannello di contatto.Now that your application appears in the contact panel for some or all users, you need to handle activation with the contact panel contract.

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.When your application is activated with this contract, it will receive a ContactPanelActivatedEventArgs object. Contiene l'ID del contatto a cui l'applicazione sta provando a interagire all'avvio e un oggetto ContactPanel .This contains the ID of the Contact that your application is trying to interact with on launch, and a ContactPanel object. È consigliabile tenere un riferimento a questo oggetto ContactPanel, che consentirà di interagire con il pannello.You should keep a reference to this ContactPanel object, which will allow you to interact with the panel.

L'oggetto ContactPanel ha due eventi che l'applicazione deve ascoltare:The ContactPanel object has two events your application should listen for:

  • L'evento LaunchFullAppRequested viene inviato quando l'utente ha richiamato l'elemento dell'interfaccia utente che richiede che l'applicazione completa venga avviata in una finestra.The LaunchFullAppRequested event is sent when the user has invoked the UI element that requests that your full application be launched in its own window. L'applicazione è responsabile dell'avvio, passando tutti i contesti necessari.Your application is responsible for launching itself, passing along all necessary context. È possibile eseguire questa operazione, ad esempio tramite l'avvio del protocollo.You are free to do this however you’d like (for example, via protocol launch).
  • L' evento di chiusura viene inviato quando l'applicazione sta per essere chiusa, consentendo di salvare qualsiasi contesto.The Closing event is sent when your application is about to be closed, allowing you to save any context.

L'oggetto ContactPanel consente inoltre di impostare il colore di sfondo dell'intestazione del pannello di contatto (se non impostato, per impostazione predefinita il tema del sistema) e per chiudere il pannello di contatto a livello di codice.The ContactPanel object also allows you to set the background color of the contact panel header (if not set, it will default to the system theme) and to programmatically close the contact panel.

Supporto di promuovere presso di notificaSupporting notification badging

Se si desidera che i contatti aggiunti alla barra delle applicazioni vengano aggiunti quando le nuove notifiche arrivano dall'app correlate a tale persona, è necessario includere il parametro hint-people nelle notifiche di tipo avviso popup e le notifiche di personeespressive.If you want contacts pinned to the taskbar to be badged when new notifications arrive from your app that are related to that person, then you must include the hint-people parameter in your toast notifications and expressive My People notifications.

Notifiche persone promuovere presso

Per aggiungere un badge a un contatto, il nodo di primo livello del popup deve includere il parametro hint-people per indicare il contatto mittente o correlato.To badge a contact, the top-level toast node must include the hint-people parameter to indicate the sending or related contact. Questo parametro può avere uno dei valori seguenti:This parameter can have any of the following values:

  • Indirizzo di posta elettronicaEmail address
    • ad esempioE.g. mailto:johndoe@mydomain.commailto:johndoe@mydomain.com
  • Numero di telefonoTelephone number
    • ad esempioE.g. Tel: 888-888-8888tel:888-888-8888
  • ID remotoRemote ID
    • ad esempioE.g. RemoteID: 1234remoteid:1234

Di seguito è riportato un esempio di come identificare una notifica di tipo avviso popup correlata a un utente specifico:Here is an example of how to identify a toast notification is related to a specific person:

<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 contatti archiviati nel PC con contatti archiviati in remoto, è fondamentale che il valore per la proprietà RemoteId sia stabile e univoco.If your app uses the ContactStore APIs and uses the StoredContact.RemoteId property to link contacts stored on the PC with contacts stored remotely, it is essential that the value for the RemoteId property is both stable and unique. Questo 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.This means that the remote ID must consistently identify a single user account and should contain a unique tag to guarantee that it does not conflict with the remote IDs of other contacts on the PC, including contacts that are owned by other apps. 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.If the remote IDs used by your app are not guaranteed to be stable and unique, you can use the RemoteIdHelper class shown later in this topic in order to add a unique tag to all of your remote IDs before you add them to the system. In alternativa, è possibile scegliere di non usare la proprietà RemoteId e invece di creare una proprietà estesa personalizzata in cui archiviare gli ID remoti per i contatti.Or you can choose to not use the RemoteId property at all and instead you create a custom extended property in which to store remote IDs for your contacts.

Classe PinnedContactManagerThe PinnedContactManager class

PinnedContactManager viene usato per gestire i contatti aggiunti alla barra delle applicazioni.The PinnedContactManager is used to manage which contacts are pinned to the taskbar. Questa classe consente di aggiungere e Rimuovi i contatti, determinare se un contatto è bloccato e determinare se il blocco su una determinata area è supportato dal sistema in cui è attualmente in esecuzione l'applicazione.This class lets you pin and unpin contacts, determine whether a contact is pinned, and determine if pinning on a particular surface is supported by the system your application is currently running on.

È possibile recuperare l'oggetto PinnedContactManager usando il metodo GetDefault :You can retrieve the PinnedContactManager object using the GetDefault method:

PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();

Aggiunta e sblocco di contattiPinning and unpinning contacts

È ora possibile aggiungere e Rimuovi i contatti usando il PinnedContactManager appena creato.You can now pin and unpin contacts using the PinnedContactManager you just created. I metodi RequestPinContactAsync e RequestUnpinContactAsync forniscono all'utente le finestre di dialogo di conferma, pertanto devono essere chiamate dal thread dell'applicazione a thread singolo (asta o interfaccia utente).The RequestPinContactAsync and RequestUnpinContactAsync methods provide the user with confirmation dialogs, so they must be called from your Application Single-Threaded Apartment (ASTA, or UI) thread.

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:You can also pin multiple contacts at the same time:

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

Nota

Attualmente non è disponibile alcuna operazione batch per l'apertura dei contatti.There is currently no batch operation for unpinning contacts.

Nota:Note:

Vedere ancheSee also