Introducción a la plataforma de Microsoft Teams con C#/.NET y app Studio

La plataforma de desarrolladores de Microsoft Teams facilita la tarea de ampliar Teams e integrar sus propias aplicaciones y servicios sin problemas en el área de trabajo de Microsoft Teams. A continuación, estas aplicaciones pueden distribuirse a su empresa o a equipos de todo el mundo.

Para ampliar Microsoft Teams, tendrá que crear una aplicación de Microsoft Teams. Una aplicación de Microsoft Teams es una aplicación web que hospeda. A continuación, esta aplicación se puede integrar en el área de trabajo del usuario en Teams.

Este tutorial le ayudará a empezar a crear una aplicación de Microsoft Teams con C# en .NET. Puede probar la aplicación cargándose en un equipo para el que tenga permisos o en un inquilino de prueba creado con el programa de desarrolladores de Office.

Preparar el entorno de desarrollo

Lo primero que debe hacer es preparar el entorno de desarrollo. Deberá asegurarse de que la carga de aplicaciones personalizada esté habilitada para la organización de Office 365 en la que desea crear la aplicación. Si necesita un inquilino de desarrollo dedicado, puede registrarse para el programa de desarrolladores de Office 365. Para obtener más información, vea configurar el entorno de desarrollo.

Obtener requisitos previos

Para completar este tutorial, necesita obtener las siguientes herramientas:

Si ve una opción para agregar git a la ruta de acceso durante la instalación, elija esta opción. Será útil.

gitEjecute lo siguiente en una ventana de terminal para comprobar la instalación:

Nota

Use la ventana de terminal que le resulte más cómoda en su plataforma. Estos ejemplos usan Bash, pero se ejecutarán en la mayoría de las plataformas.

$ git --version
git version 2.17.1.windows.2

Asegúrese de iniciar la versión más reciente de Visual Studio e instale las actualizaciones si se muestran.

Puede seguir usando esta ventana de terminal para ejecutar los comandos que se indican a continuación en este tutorial.

Descargar el ejemplo

Hemos proporcionado un sencillo Hola a todos. muestra en C# para empezar. En una ventana de terminal, ejecute el siguiente comando para clonar el repositorio de muestra en el equipo local:

git clone https://github.com/OfficeDev/msteams-samples-hello-world-csharp.git

Sugerencia

Puede bifurcar este repositorio si desea modificar y proteger los cambios en github para futuras referencias.

Compilar y ejecutar el ejemplo

Una vez que el repositorio se haya clonado, use Visual Studio para abrir el archivo Microsoft.Teams.Samples.HelloWorld.sln de solución desde el directorio raíz del ejemplo y haga clic en Build Solution desde el Build menú. Puede ejecutar el ejemplo presionando F5 o eligiendo Start Debugging en el Debug menú.

Cuando se inicie la aplicación, verá una ventana del explorador abierta con la raíz de la aplicación iniciada. Puede navegar a las siguientes direcciones URL para comprobar que todas las direcciones URL de la aplicación se cargan:

Nota

Si recibe un error como Could not find a part of the path … bin\roslyn\csc.exe , intente actualizar el paquete con el comando Update-Package Microsoft.CodeDom.Providers.DotNetCompilerPlatform -r . Vea esta pregunta en stackoverflow para obtener más información.

Hospedar la aplicación de ejemplo

Recuerde que las aplicaciones de Microsoft Teams son aplicaciones web que exponen una o más capacidades. Para que la plataforma de Microsoft Teams cargue la aplicación, la aplicación debe ser accesible desde Internet. Para hacer que la aplicación sea accesible desde Internet, debe hospedar la aplicación. Puede hospedarlo en Microsoft Azure de forma gratuita o crear un túnel para el proceso local en el equipo de desarrollo mediante ngrok . Cuando termine de hospedar la aplicación, anote su dirección URL raíz. Tendrá un aspecto similar a: https://yourteamsapp.ngrok.io o https://yourteamsapp.azurewebsites.net .

Túnel mediante ngrok

Para realizar pruebas rápidas, puede ejecutar la aplicación en el equipo local y crear un túnel a través de un punto de conexión Web. ngrok es una herramienta gratuita que le permite hacer justamente eso. Con ngrok puede obtener una dirección web como https://d0ac14a5.ngrok.io (esta dirección URL es solo un ejemplo). Puede Descargar e instalar ngrok para su entorno. Asegúrese de agregarlo a una ubicación en el PATH .

Una vez instalado, puede abrir una nueva ventana de terminal y ejecutar el siguiente comando para crear un túnel. En el ejemplo se usa el puerto 3333, por lo que debe asegurarse de especificarlo aquí.

ngrok http 3333 -host-header=localhost:3333

Ngrok escuchará solicitudes de Internet y las enrutará a la aplicación que se ejecuta en el puerto 3333. Para comprobarlo, abra el explorador y vaya a https://d0ac14a5.ngrok.io/hello para cargar la página Hello de la aplicación. Asegúrese de usar la dirección de reenvío que muestra ngrok en la sesión de consola en lugar de esta dirección URL.

Nota

Si ha usado un puerto diferente en el paso de compilación y ejecutar anterior, asegúrese de que usa el mismo número de puerto para configurar el ngrok túnel.

Sugerencia

Es aconsejable ejecutar ngrok en una ventana de terminal diferente para mantenerla en ejecución sin interferir con la aplicación que, posteriormente, se debe detener, volver a crear y volver a ejecutar. La ngrok sesión devolverá información de depuración útil en esta ventana.

La aplicación solo estará disponible durante la sesión actual en el equipo de desarrollo. Si el equipo está apagado o entra en suspensión, el servicio dejará de estar disponible. Recuerde esto cuando comparta la aplicación para que la prueben otros usuarios. Si tiene que reiniciar el servicio, devolverá una nueva dirección y tendrá que actualizar todos los sitios que usen esa dirección. La versión de pago de Ngrok no tiene esta limitación.

Hospedar en Azure

Microsoft Azure le permite hospedar su aplicación .NET en un nivel gratuito mediante una infraestructura compartida. Esto será suficiente para ejecutar este Hello World ejemplo. Consulte creación de una nueva cuenta gratuita para obtener más información.

Visual Studio tiene compatibilidad integrada para la implementación de aplicaciones en diferentes proveedores, incluido Azure.

Visual Studio

Usar App Studio para actualizar el paquete de la aplicación

App Studio es una aplicación de Microsoft teams que se puede instalar desde la tienda Teams. Simplifica la creación y el registro de una aplicación.

Para instalar App Studio en Teams, haga clic en el icono App Store situado en la parte inferior de la barra izquierda y busque App Studio.

Finding App Studio in the Store View

Una vez que encuentre el icono de App Studio, haga clic en él y elija instalar en el cuadro de diálogo que aparece.

Installing App Studio

Una vez instalado App Studio, haga clic en la pestaña del editor de manifiestos para empezar a crear el paquete de la aplicación para la aplicación de Teams.

App Studio

El ejemplo incluye su propio manifiesto predefinido y está diseñado para compilar un paquete de la aplicación cuando se crea el proyecto. En .NET esto se hace en Visual Studio y en el nodo JS esto se hace escribiendo gulp en la línea de comandos en el directorio raíz del proyecto.

$ gulp
[13:39:27] Using gulpfile ~\documents\github\msteams-samples-hello-world-nodejs\gulpfile.js
[13:39:27] Starting 'clean'...
[13:39:27] Starting 'generate-manifest'...
[13:39:27] Finished 'generate-manifest' after 11 ms
[13:39:27] Finished 'clean' after 21 ms
[13:39:27] Starting 'default'...
Build completed. Output in manifest folder
[13:39:27] Finished 'default' after 62 μs

El nombre del paquete de la aplicación generado es helloworldapp.zip. Puede buscar este archivo si la ubicación no está clara en la herramienta que está usando.

En la siguiente parte de este tutorial, va a modificar este paquete de la aplicación seleccionando el icono importar una aplicación existente en el editor de manifiestos.

Importing an existing app

Una vez que se ha importado el paquete de la aplicación, App Studio debería tener el siguiente aspecto:

Importing the app package

Haga clic en el icono de la aplicación recién importada, Hello World.

Newly imported app view

Hay una lista de pasos en el lado izquierdo del editor de manifiestos y, a la derecha, una lista de propiedades que deben rellenarse para cada uno de estos pasos. Desde que empezó con una aplicación de muestra, gran parte de la información ya se ha rellenado. Los pasos siguientes le guiarán por el cambio de las partes que todavía deben actualizarse.

Detalles de la aplicación

Haga clic en la entrada detalles de la aplicación en detalles. Haga clic en el botón generar para crear un nuevo identificador de aplicación.

El nuevo identificador de la aplicación debe tener un aspecto similar al siguiente: 2322041b-72bf-459d-b107-f4f335bc35bd .

Mire el resto de los detalles de la aplicación en el panel de la derecha y familiarícese con algunas de las entradas, como información de desarrolladores y Personalización de marca. Estas secciones son importantes si está escribiendo una nueva aplicación para la distribución.

Capacidades: pestañas

Las pestañas se encuentran entre los elementos más simples para agregar a una aplicación de Teams. La aplicación de ejemplo ya admite varias pestañas y puede habilitarlas de la siguiente manera.

Ficha equipo

La aplicación solo puede tener una pestaña de equipo.

Adding a Teams tab

En este ejemplo, la ficha equipo es donde se encuentra la página de configuración. Haga clic en el símbolo ... al final de la entrada y elija Editar en la lista desplegable. Cambie la dirección URL a https://yourteamsapp.ngrok.io/configure donde yourteamsapp.ngrok.io se debe reemplazar la dirección URL que usó al hospedar la aplicación.

Pestañas personales

La aplicación puede tener hasta 16 pestañas, incluida la pestaña equipo.

Las pestañas personales se representan de forma diferente a la ficha equipo. Debe ver la ficha Hello que ya aparece en la lista de pestañas personales. En el momento tiene un valor de marcador de posición com.contoso.helloworld.hellotab . Haga clic en el símbolo ... al final de la entrada y elija Editar en la lista desplegable. Aparecerá el siguiente cuadro de diálogo.

Adding a personal tab dialog

Hay dos campos que debe actualizar con la dirección URL de la aplicación.

  • Cambiar la dirección URL del contenido a https://yourteamsapp.ngrok.io/hello
  • Cambiar la dirección URL del sitio web a https://yourteamsapp.ngrok.io/hello

Donde yourteamsapp.ngrok.io se debe reemplazar por la dirección URL que ha usado anteriormente al hospedar la aplicación.

Bots

Los bots son la forma más común de agregar funcionalidad a la aplicación. La muestra Hello World ya tiene un bot como parte de la muestra, pero todavía no se ha registrado con Microsoft.

Adding a bot

El bot que se importó desde el ejemplo no tiene un identificador de aplicación asociado todavía. Tendrá que crear un nuevo bot para que App Studio pueda crear un nuevo identificador de aplicación y registrarlo en Microsoft. Tenga en cuenta que este es el identificador de la aplicación para bot, que es diferente del identificador de aplicación que se ha creado para la aplicación en un paso anterior. Cada bot en una aplicación requiere su propio identificador de aplicación.

Haga clic en el botón eliminar situado junto al Bot importado en la lista de robots.

Ahora no quedan bots para mostrar. Haga clic en configurar. Se mostrará el cuadro de diálogo configurar un bot .

Adding a bot dialog

Agregue un nombre de bot, por ejemplo Contoso bot , y seleccione los tres botones bajo ámbito.

Elija crear bot para salir del cuadro de diálogo. App Studio dedicará un momento a registrar el bot con Microsoft y, a continuación, deberá mostrar el nuevo bot en la lista de robots. Ahora sería un buen momento para abrir un archivo de texto en el Bloc de notas y copiar y pegar el nuevo identificador de bot en él. Necesitará este identificador más adelante.

Haga clic en generar nueva contraseñay anote la contraseña en el mismo archivo de texto que anotó con el identificador de la aplicación de bot en. Esta es la única vez que se mostrará su contraseña, por lo que debe asegurarse de hacerlo ahora.

Actualice la dirección del punto de conexión del bot con https://yourteamsapp.ngrok.io/api/messages , donde yourteamsapp.ngrok.io debe reemplazarse por la dirección URL que usó al hospedar la aplicación.

Ahora sería un buen momento para guardar el archivo de texto si todavía no lo ha hecho. Esta información se agregará a la aplicación hospedada más adelante en este tutorial, lo que permitirá la comunicación segura con el bot.

Extensiones de mensajería

Las extensiones de mensajería permiten a los usuarios solicitar información de su servicio y publicarla, en forma de tarjetas, directamente en la conversación del canal. Las extensiones de mensajería aparecen a lo largo de la parte inferior del cuadro de redacción.

Haga clic en extensiones de mensajería en funcionalidades en la columna izquierda de App Studio para comenzar a configurar la extensión de mensajería.

Adding a messaging extension

La extensión de mensajería de muestra aparece en el panel de la derecha, en extensiones de mensajería. Haga clic en eliminar de nuevo para quitar esta entrada y, a continuación, haga clic en el botón configurar siguiendo los mismos pasos que siguió para los bots. Se mostrará el cuadro de diálogo de la extensión de mensajería .

Seleccione la pestaña usar bot existente y, a continuación, Seleccione uno de los bots existentes. En el menú desplegable, seleccione el bot que creó en la sección anterior. Agregue un nombre de bot y haga clic en Guardar para cerrar el cuadro de diálogo.

En la sección comando , haga clic en Agregar. Estamos agregando un comando basado en la búsqueda, por lo que debe elegir la opción permitir que los usuarios consulten su servicio...

En el cuadro de diálogo nuevo comando , escriba los siguientes valores.

En nuevo comando:

  • Identificador de comando = getRandomText
  • Title = obtener texto aleatorio para divertirse
  • Description = obtiene texto e imágenes aleatorios

En parámetro:

  • Name = cardTitle
  • Title = título de la tarjeta
  • Description = título de la tarjeta para usar

Una vez que haya introducido la información, haga clic en Guardar para cerrar el cuadro de diálogo.

Registrar la aplicación en Microsoft Teams

Ya ha completado la especificación de los detalles de la aplicación, pero quedan dos pasos. En primer lugar, debe usar la sección probar y distribuir de App Studio para instalar la aplicación en Teams y, en segundo lugar, debe actualizar la aplicación hospedada con el identificador de aplicación y la contraseña de su bot. Recuerde que el ejemplo espera usar el mismo identificador de aplicación y la misma contraseña para el bot y la extensión de mensajería.

Haga clic en el elemento probar y distribuir en Finalizar en la columna izquierda de App Studio.

Testing your app

Para cargar la aplicación en Teams, haga clic en el botón instalar en probar y distribuir.

Adding a messaging extension dialog

Haga clic en el cuadro de búsqueda en la sección Agregar a un equipo y seleccione un equipo al que desee agregar la aplicación de ejemplo. Normalmente querrá configurar un equipo especial para realizar las pruebas.

Haga clic en el botón instalar situado en la parte inferior del cuadro de diálogo.

Esto finaliza la parte de App Studio de este tutorial. Ahora debería ver que la aplicación se está ejecutando en Teams, pero el bot y la extensión de mensajería no funcionarán hasta que actualice el entorno de aplicaciones hospedadas para conocer los identificadores de aplicación y las contraseñas.

The finished app

Actualizar las credenciales de la aplicación hospedada

La aplicación de ejemplo requiere que se establezcan las siguientes variables de entorno en los valores que ha anotado anteriormente.

Abra el appsettings.jsen el archivo. Actualice el valor MicrosoftAppId con el identificador de bot que guardó anteriormente. Actualice MicrosoftAppPassword con la contraseña de bot que guardó anteriormente.

Setting the keys

Una vez realizados estos cambios, reconstruya la aplicación. Si usa ngrok, ejecute la aplicación localmente y, si hospeda en Azure, vuelva a implementar la aplicación.

Configurar la pestaña de la aplicación

Una vez que haya instalado la aplicación en un equipo, tendrá que configurarla para mostrar el contenido. Vaya a un canal del equipo en el que haya instalado la aplicación de ejemplo y haga clic en el botón "+" para agregar una nueva pestaña. A continuación, puede elegir Hello World en la lista Agregar una pestaña . A continuación, se mostrará un cuadro de diálogo de configuración. Este cuadro de diálogo le permitirá elegir la pestaña que desea mostrar en este canal. Una vez que seleccione la pestaña y haga clic en Save , puede ver la Hello World ficha cargada con la pestaña que eligió.

Screenshot of configure

Probar el bot en Microsoft Teams

Ahora puede interactuar con el bot en Teams. Elija un canal del equipo en el que haya registrado la aplicación y escriba @your-bot-name . Esto se denomina una ** @ mención**. Cualquier mensaje que envíe al bot se le enviará como respuesta.

Bot responses

Probar la extensión de mensajería

Para probar la extensión de mensajería, puede hacer clic en los tres puntos situados debajo del cuadro de entrada en la vista de conversación. Se mostrará un menú con la aplicación "Hola a todos" . Al hacer clic en él, verá una serie de textos aleatorios que aparecen. Puede elegir una de ellas y se insertará en la conversación.

Messaging extension menu Messaging extension result

Elija uno de los textos aleatorios y verá una tarjeta con formato y lista para enviar con su propio mensaje en la parte inferior.

Messaging extension send