Agregar compatibilidad con Mis allegados a una aplicación

  • Artículo

Importante

Mis Allegados ya no se admite en versiones de Windows 11 y Windows 10 con la actualización KB5034203.

Nota:

A partir de la actualización de mayo de 2019 de Windows 10 (versión 1903), en las nuevas instalaciones de Windows 10 ya no aparecerá "Personas en la barra de tareas" de forma predeterminada. Los clientes pueden habilitar la característica haciendo clic con el botón derecho en la barra de tareas y pulsando "Mostrar Allegados en la barra de tareas". No se recomienda que los desarrolladores añadan la funcionalidad compatible con Mis allegados a sus aplicaciones y deben acceder al blog para desarrolladores de Windows para obtener más información sobre la optimización de aplicaciones en Windows 10.

La característica Mis allegados permite a los usuarios anclar contactos a través de una aplicación directamente a la barra de tareas, lo que crea un nuevo objeto de contacto con el que poder interactuar de varias maneras. En este artículo se indica cómo añadir la funcionalidad de esta característica, que permite a los usuarios anclar contactos directamente por medio de la aplicación. Cuando se anclan contactos, los nuevos tipos de interacción del usuario quedan disponibles, como el sistema de uso compartido de Mis allegados y las notificaciones.

My people chat

Requisitos

Información general

Hay tres cosas que debe hacer para permitir que la aplicación use la característica Mis allegados:

  1. Declare la compatibilidad con el contrato de activación de shareTarget en el manifiesto de la aplicación.
  2. Anote los contactos con los que los usuarios pueden compartir a través de la aplicación.
  3. Admita varias instancias de la aplicación que se ejecutan al mismo tiempo. Los usuarios deben poder interactuar con la versión completa de la aplicación mientras la usan en un panel de contactos. Además, pueden usarla en varios paneles de contacto a la vez. Para que esto funcione, la aplicación debe poder ejecutar varias vistas simultáneamente. Para obtener información sobre cómo hacerlo, consulte el artículo Mostrar varias vistas en una aplicación.

Cuando lo haya hecho, la aplicación saldrá en el panel de contactos con los contactos anotados.

Declaración de compatibilidad en el contrato

Para declarar la compatibilidad en el contrato de Mis allegados, abra la aplicación en Visual Studio. En el Explorador de soluciones, haga clic con el botón derecho en Package.appxmanifest y seleccione Abrir con. En el menú, seleccione Editor de XML (texto) y haga clic en Aceptar. Realice los siguientes cambios en el manifiesto:

Antes

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

Después

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

Al añadir esto, la aplicación se podrá iniciar a través del contrato windows.ContactPanel, que le permitirá interactuar con los paneles de contactos.

Anotación de contactos

Para que los contactos de la aplicación aparezcan en la barra de tareas a través del panel Mis allegados, debe escribirlos en el almacén de contactos de Windows. Para saber cómo escribir contactos, consulte el ejemplo de integración de tarjeta de contacto.

La aplicación también debe escribir una anotación en cada contacto. Las anotaciones son fragmentos de datos de la aplicación que están asociados a un contacto. La anotación debe incluir la clase activable correspondiente en el modo de vista deseado en el miembro ProviderProperties y declarar la compatibilidad en la operación ContactProfile .

Puede anotar los contactos en cualquier momento mientras se ejecuta la aplicación, pero por lo general tendrá que anotar los contactos tan pronto como se añadan al almacén de contactos de 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));
}

El "appId" es el nombre de la familia del paquete, seguido de '!' y el ID de clase activable. Para buscar el nombre de familia del paquete, abra Package.appxmanifest con el editor predeterminado y busque en la pestaña "Packaging" ("Empaquetado"). Aquí, "App" es la clase activable correspondiente en el modo de vista de inicio de la aplicación.

Permitir que los contactos inviten a nuevos posibles usuarios

De forma predeterminada, la aplicación solo aparecerá en el panel de contactos con los contactos que haya anotado específicamente. Esto sirve para evitar que haya confusión con los contactos con los que no es posible interactuar a través de la aplicación. Si desea que la aplicación aparezca con los contactos que la aplicación no reconoce (para invitar a los usuarios a que añadan el contacto en cuestión a su cuenta, por ejemplo), puede incluir lo siguiente al manifiesto:

Antes

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

Después

<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 este cambio, la aplicación aparecerá como una opción disponible en el panel de contactos con todos los contactos que el usuario haya anclado. Cuando la aplicación se activa mediante el contrato del panel de contactos, es necesario comprobar si el contacto es uno de los que la aplicación reconoce. Si no es así, debería abrir el nuevo entorno de usuario de la aplicación.

My People contact panel

Compatibilidad con aplicaciones de correo electrónico

Si escribe una aplicación de correo electrónico, no es necesario anotar cada contacto de forma manual. Si declara compatibilidad con el panel de contactos y el protocolo mailto:, los usuarios verán la aplicación automáticamente con una dirección de correo electrónico.

Ejecución en el panel de contactos

Cuando algunos o todos los usuarios puedan ver la aplicación en el panel de contactos, deberá controlar la activación con el contrato del panel de contactos.

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();
    }
}

Cuando la aplicación se activa con este contrato, se recibirá un objeto ContactPanelActivatedEventArgs. Este incluye el ID del contacto con el que la aplicación intentará interactuar al iniciarse y un objeto ContactPanel. Debe conservar la referencia a este objeto ContactPanel, ya que le permitirá interactuar con el panel.

El objeto ContactPanel tiene dos eventos que la aplicación debe tener en cuenta:

  • El evento LaunchFullAppRequested se envía cuando el usuario ha invocado el elemento de IU, por el que se solicita que toda la aplicación se abra en una ventana propia. La aplicación se encarga de iniciarse por sí sola, pasando todo el contexto necesario. Sin embargo, tiene la libertad de hacerlo usted mismo (por ejemplo, mediante la ejecución del protocolo).
  • El evento Closing se envía cuando la aplicación está a punto de cerrarse, lo que le permite guardar cualquier contexto.

El objeto ContactPanel también le permite elegir el color de fondo del encabezado del panel de contactos (si no se especifica, se aplicará de forma predeterminada según el tema del sistema) y cerrar mediante programación el panel de contactos.

Opción de distintivos para notificaciones

Si desea que los contactos anclados a la barra de tareas se vean como distintivos cuando lleguen nuevas notificaciones de la aplicación relacionadas con esa persona, deberá incluir el parámetro hint-people en las notificaciones del sistema y las y las notificaciones expresivas de Mis allegados.

People notification badging

Para asignar un distintivo a un contacto, en el nodo de notificación de nivel superior deberá incluir el parámetro hint-people para indicar el envío o el contacto relacionado. Este parámetro puede tener cualquiera de los siguientes valores:

Este es un ejemplo de cómo identificar si una notificación está relacionada con una persona específica:

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

Si la aplicación usa las API de ContactStore y usa la propiedad StoredContact.RemoteId para vincular contactos almacenados en el equipo con contactos almacenados de forma remota, es importante que el valor de la propiedad RemoteId sea estable y único. Esto significa que el ID remoto debe identificar de forma coherente una sola cuenta de usuario y debe contener una etiqueta única para garantizar que no entra en conflicto con los ID remotos de otros contactos del equipo, incluidos los contactos que pertenecen a otras aplicaciones. Si no se garantiza que los ID remotos usados por la aplicación sean estables y únicos, puede usar la clase RemoteIdHelper, que se indica más adelante en este apartado, para añadir una etiqueta única a todos los ID remotos antes de añadirlos al sistema. O bien, puede no usar la propiedad RemoteId y, en su lugar, crear una propiedad extendida personalizada en la que almacenar ID remotos para los contactos.

La clase PinnedContactManager

La PinnedContactManager se usa para administrar los contactos que van a ir anclados a la barra de tareas. Esta clase le permite anclar y desanclar contactos, determinar si un contacto está anclado y comprobar si el anclaje en una superficie determinada es compatible con el sistema en el que la aplicación se está ejecutando en ese momento.

Puede recuperar el objeto PinnedContactManager mediante el método GetDefault:

PinnedContactManager pinnedContactManager = PinnedContactManager.GetDefault();

Anclar y desanclar contactos

Ahora puede anclar y desanclar contactos mediante el PinnedContactManager que acaba de crear. Los métodos RequestPinContactAsync y RequestUnpinContactAsync crean cuadros de diálogo de confirmación para el usuario, por lo que deben llamarse a través del subproceso de Application Single-Threaded Apartment (ASTA o UI).

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

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

También puede anclar varios contactos al mismo tiempo:

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

Nota:

Actualmente, no hay existe ninguna operación por lotes para desanclar contactos.

Nota:

Consulte también