Introducción a Azure WebJobs para sitios de Office 365
Con Office 365, si está ejecutando y usando el servicio de SharePoint Online, debe replantearse la forma en que ejecuta lo que solían ser los trabajos del temporizador en las soluciones de granja de servidores tradicionales.
En el desarrollo tradicional de SharePoint, se usan trabajos de temporizador para realizar tareas programadas en granjas de servidores de SharePoint. Una técnica que se usa habitualmente consiste en desarrollar trabajos de temporizador personalizados para realizar de manera continua o iterativa determinadas tareas en su entorno. Con Office 365 y SharePoint Online, no tiene el privilegio de implementar sus soluciones de granja de servidores, que es donde normalmente residen los trabajos de temporizador tradicionales. En su lugar, tiene que encontrar otra manera de programar las tareas, lo que nos lleva a Azure WebJobs.
En este artículo se describen los conceptos básicos para empezar a crear trabajos personalizados para sitios de Office 365 y cómo puede crear un trabajo web de Azure (Azure WebJob) para que actúe como un trabajo programado para la instalación de Office 365 (o local) de SharePoint.
Compilar el trabajo web mediante Visual Studio
Para compilar un nuevo trabajo web, lo único que debe hacer es crear una nueva aplicación de consola y asegurarse de agregar los ensamblados necesarios al proyecto. En este ejemplo, usamos Visual Studio.
Paso 1: Crear la aplicación de consola
Para empezar, cree un nuevo proyecto y asegúrese de elegir la plantilla aplicación de consola. Además, asegúrese de elegir .NET Framework 4.5 o posterior.
Paso 2: Agregar los ensamblados específicos de SharePoint desde NuGet
Si usa Visual Studio, el cuadro de diálogo del administrador de paquetes NuGet puede tener un aspecto ligeramente distinto al de versiones anteriores de Visual Studio, pero el concepto es el mismo.
Vaya a Tools>Administrador de paquetes NuGet >Administrar paquetes NuGet para la solucióny busque Aplicación para SharePoint.
Instale el paquete llamado AppForSharePointOnlineWebToolkit.
El kit de herramientas instala las clases auxiliares necesarias para trabajar con el modelo de objetos del lado cliente (CSOM) de SharePoint.
Asegúrese de que el paquete NuGet ha funcionado asegurándose de que aparecen las dos clases nuevas siguientes en el proyecto de aplicación de consola:
- SharePointContext.cs
- TokenHelper.cs
Paso 3: Agregar el código necesario para ejecutar el trabajo en su sitio de Office 365
Al llegar a este punto ya ha creado la aplicación de consola y ha agregado los ensamblados necesarios que le permitirán comunicarse fácilmente con SharePoint. Los pasos siguientes son hacer uso de estas clases auxiliares para ejecutar comandos en el entorno de SharePoint mediante la aplicación de consola.
Nota:
En el ejemplo finalizado, usará un enfoque de cuenta y contraseña (como una cuenta de servicio). Las opciones de autenticación se describen más adelante en este artículo.
Conectar las llamadas a la colección de sitios de SharePoint Online
El código siguiente muestra cómo conectar la llamada al sitio ahora que ha agregado las clases auxiliares del paquete NuGet.
static void Main(string[] args)
{
using (ClientContext context = new ClientContext("https://redacted.sharepoint.com"))
{
// Use default authentication mode
context.AuthenticationMode = ClientAuthenticationMode.Default;
// Specify the credentials for the account that will execute the request
context.Credentials = new SharePointOnlineCredentials(GetSPOAccountName(), GetSPOSecureStringPassword());
// TODO: Add your logic here!
}
}
private static SecureString GetSPOSecureStringPassword()
{
try
{
Console.WriteLine(" - > Entered GetSPOSecureStringPassword()");
var secureString = new SecureString();
foreach (char c in ConfigurationManager.AppSettings["SPOPassword"])
{
secureString.AppendChar(c);
}
Console.WriteLine(" - > Constructed the secure password");
return secureString;
}
catch
{
throw;
}
}
private static string GetSPOAccountName()
{
try
{
Console.WriteLine(" - > Entered GetSPOAccountName()");
return ConfigurationManager.AppSettings["SPOAccount"];
}
catch
{
throw;
}
}
Puede ver en la aplicación de ejemplo que se han agregado dos métodos auxiliares para capturar el nombre de la cuenta y la contraseña de la cuenta desde el archivo app.config. Estos se explican en la sección de autenticación más adelante en este artículo.
En cuanto al método Principal Eso es todo lo que se necesita para conectarlo todo al portal. Antes de profundizar en cómo puede manipular SharePoint desde el código, vamos a analizar las opciones de autenticación.
Consideración de las opciones de autenticación
Tiene dos opciones para la autenticación. Las siguientes secciones describen estos enfoques comúnmente utilizados y cómo se diferencian.
Opción 1: Usar una cuenta de servicio (nombre de usuario y contraseña)
Este enfoque es bastante sencillo y le permite simplemente escribir una cuenta y una contraseña para su espacio empresarial de Office 365 y, después, usar, por ejemplo, CSOM para ejecutar código en sus sitios. Esto es lo que se hizo también en el código de ejemplo anterior.
Crear una nueva cuenta de servicio en Office 365
Para que esto funcione, debe crear una cuenta específica que actúe como una cuenta de servicio para esta aplicación específica o una cuenta de aplicación de servicio genérica que puedan usar todos los trabajos y servicios.
Para esta demostración, hemos creado una nueva cuenta denominada SP WebJob.
Dependiendo de los permisos que deba tener el trabajo, deberá editar los permisos de la cuenta cuando la configure.
Almacenar credenciales en app.config
En el archivo app.config del proyecto, puede especificar las credenciales para que se puedan capturar fácilmente desde el archivo ejecutable de código. Este es el aspecto de app.config:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<startup>
<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" />
</startup>
<appSettings>
<add key="SPOAccount" value="spwebjob@redacted.onmicrosoft.com"/>
<add key="SPOPassword" value="redacted"/>
</appSettings>
</configuration>
Puede ver los dos valores en el archivo app.config:
- SPOAccount
- SPOPassword
Si revisa el primer fragmento de código, esta configuración procede del archivo app.config. Solo tiene que tener en cuenta que esto significa almacenar el nombre de la cuenta y la contraseña en texto no cifrado en app.config. Debe tomar una decisión en sus propios proyectos sobre cómo y dónde almacenar y proteger las contraseñas si elige este enfoque.
Ejecutar el trabajo en la cuenta especificada
Una vez que se ejecuta la aplicación, se ejecuta con la cuenta especificada en el constructor SharePointOnlineCredentials().
En el ejemplo anterior, el WebJob está ejecutando acciones en una lista personalizada en uno de los sitios hospedados en una colección de sitios de SharePoint Online.
Gracias a esto, puede obtener una buena rastreabilidad de los cambios realizados en el portal por su cuenta de servicio. Este es el motivo por el que es importante asignar un nombre a la cuenta de forma inteligente; todos sabrán que el servicio realizó automáticamente las modificaciones simplemente examinando los metadatos modificados o creados.
Opción 2: Usar OAuth e incluir tokens de autenticación en las solicitudes para evitar especificar la cuenta o contraseña
En una entrada de blog de Kirk Evans llamada Crear un complemento de SharePoint como un trabajo de temporizador, explica cómo puede usar y pasar tokens de acceso para evitar configuraciones de nombre de usuario y contraseña, en caso de que no quiera almacenar las contraseñas y credenciales en la aplicación.
Extender el código con CSOM
En este momento, tiene una aplicación de consola en funcionamiento que puede autenticar y ejecutar solicitudes a los sitios de Office 365. Aún no se ha hecho nada sofisticado en el código, por lo que este es un fragmento de código de ejemplo para extraer información de una lista denominada Traducciones automáticas. La lógica del código determina si hay elementos en la lista que no se han traducido. Después, ejecutará una llamada a un servicio de traducción y traducirá el texto al idioma de salida deseado.
static void Main(string[] args)
{
try
{
Console.WriteLine("Initiating Main()");
using (ClientContext context = new ClientContext("https://redacted.sharepoint.com"))
{
Console.WriteLine("New ClientContext('https://redacted.sharepoint.com') opened. ");
context.AuthenticationMode = ClientAuthenticationMode.Default;
context.Credentials = new SharePointOnlineCredentials(GetSPOAccountName(), GetSPOSecureStringPassword());
Console.WriteLine("Authentication Mode and Credentials configured");
List translationlist = context.Web.Lists.GetByTitle("Automatic Translations");
context.Load(translationlist);
context.ExecuteQuery();
Console.WriteLine("TranslationList fetched, loaded and ExecuteQuery'ed");
if (translationlist != null && translationlist.ItemCount > 0)
{
Console.WriteLine("The list exist, let's do some magic");
CamlQuery camlQuery = new CamlQuery();
camlQuery.ViewXml =
@"<View>
<Query>
<Where><Eq><FieldRef Name='IsTranslated' /><Value Type='Boolean'>0</Value></Eq></Where>
</Query>
</View>";
ListItemCollection listItems = translationlist.GetItems(camlQuery);
context.Load(listItems);
context.ExecuteQuery();
Console.WriteLine("Query for listItems executed.");
foreach (ListItem item in listItems)
{
item["Output"] = TranslatorHelper.GetTranslation(item["Title"], item["Target Language"], item["Original Language"]);
item["IsTranslated"] = true;
item.Update();
}
context.ExecuteQuery();
Console.WriteLine("Updated all the list items you found. Carry on...");
}
}
}
catch (Exception ex)
{
Console.WriteLine("ERROR: " + ex.Message);
Console.WriteLine("ERROR: " + ex.Source);
Console.WriteLine("ERROR: " + ex.StackTrace);
Console.WriteLine("ERROR: " + ex.InnerException);
}
}
La clase TranslatorHelper es una clase auxiliar que invoca una API de traducción personalizada, pero no se discutirá en detalle en este mensaje porque está fuera del alcance de este artículo.
Nota:
Como se ve en el código, se trata de una demostración y, definitivamente, no se usa en producción. Revíselo y ajústelo según sus estándares de codificación y principios de seguridad. Sin embargo, se agregan todas las adiciones Console.WriteLine para que pueda revisar fácilmente la ejecución de los trabajos desde el Azure Portal. Más adelante en este artículo encontrará más información sobre el registro y la supervisión.
Publicación del trabajo web en Azure
Cuando haya desarrollado el trabajo web y esté listo para implementarlo en su entorno de Azure (en un sitio web de Azure), tiene dos opciones principales, como se describe en las secciones siguientes.
Opción 1: Cargar un archivo ZIP con los archivos binarios de WebJob en el Azure Portal
Usando el portal de Azure donde almacena todas sus maravillas en Azure, puede subir un archivo zip que contiene la salida de la compilación de Visual Studio. Esta es una manera sencilla de compilar y enviar el código a otra persona que realizará la implementación por usted.
Creación del archivo ZIP
Solo tiene que tomar todos los archivos de salida de la compilación de Visual Studio (normalmente en la carpeta bin/Debug o bin/Release).
Comprímalos para obtener un buen archivo ZIP para el trabajo web.
Buscar un sitio web donde se debe implementar el trabajo
Ahora que tiene el paquete, el siguiente paso es ir al Azure Portal e iniciar sesión.
Desde allí, debe crear un sitio web nuevo o usar uno existente. Este sitio web es el host de su trabajo web.
Si se desplaza hacia abajo en el panel de configuración de su sitio web, encontrará un icono llamado WebJobs en el encabezadoOperaciones.
Haga clic en el área donde apunta la flecha.
Cargar el trabajo de WebJobs
Cargue el trabajo web eligiendo el signo [+ Agregar].
Elija un nombre y cómo se debe ejecutar el trabajo y, a continuación, cargue el archivo ZIP real.
Importante
La alternativa Cómo ejecutar actualmente solo ofrece a petición o continua, pero pronto también habrá compatibilidad paraprogramada, que es la opción preferible. En la sección Publicar directamente en Azure, puede programarla desde Visual Studio.
Ahora puede ejecutar el trabajo web desde el Azure Portal.
Opción 2: Publicar directamente en Azure desde Visual Studio
Puede usar las herramientas de Visual Studio para publicar rápidamente los cambios directamente en el servicio hospedado. También puede programar el trabajo exactamente como desea que se ejecute directamente desde los diálogos de Visual Studio.
Publicación del trabajo web desde Visual Studio
Nota:
Estos cuadros de diálogo pueden diferir ligeramente si ejecuta una versión anterior de Visual Studio. Además, si lo hace por primera vez, puede obtener un cuadro de diálogo de inicio de sesión para iniciar sesión en su cuenta de Azure.
Haga clic con el botón derecho en el proyecto y, a continuación, elija Publicar como Azure WebJob.
Agregar Azure WebJob
Esto le lleva a un nuevo cuadro de diálogo en el que puede configurar el trabajo. Si desea un trabajo recurrente que se ejecute en un horario (por ejemplo, una vez cada noche), puede configurar la programación directamente desde los diálogos.
Asegúrese de que el nombre de WebJob sea adecuado para la web.
Seleccione el modo de ejecución de su WebJob. Si desea que se produzca a una hora específica todos los días, elija Ejecutar según una programación.
¿Debe ser un trabajo periódico o un trabajo único? Dado que quiere simular un trabajo de temporizador, debe ser periódico y, si se ejecutará cada noche, sin ninguna fecha de finalización.
Puede programar la periodicidad hasta cada minuto si lo desea.
Indique la fecha de inicio y hora, así como lazona horaria.
Elija Aceptar. Visual Studio envía el siguiente mensaje: Instalar paquete de NuGet para la publicación de WebJobs.
Esto agrega realmente un nuevo archivo denominado webjob-publish-settings.json al proyecto, que contiene la configuración del trabajo.
El archivo tiene el siguiente aspecto:
{ "$schema": "http://schemastore.org/schemas/json/webjob-publish-settings.json", "webJobName": "Zimmergren-O365-WebJobSample", "startTime": "2015-01-09T01:00:00+01:00", "endTime": null, "jobRecurrenceFrequency": "Day", "interval": 1, "runMode": "Scheduled" }Nota:
No necesita este archivo en este momento porque ya ha diseñado la programación mediante los diálogos.
Seleccionar destino de publicación o implementación
El siguiente paso del cuadro de diálogo es indicar dónde publicar o implementar el trabajo web. Puede importar un perfil de publicación o seleccionar sitios web de Azure para autenticarse y seleccionar uno de los sitios existentes.
En el Azure Portal, elija Importar y especifique el archivo de perfil de publicación que descargó del sitio web de Azure.
Publicar
Una vez hecho esto, solo tiene que elegir Publicar. A continuación, el cuadro de diálogo actividad de publicación webmuestra el progreso de la implementación del trabajo web.
Cuando haya terminado, debería ver el trabajo web en el Azure Portal.
El estado del trabajo web ahora se muestra como Completado. Diría fallo/error si hubiera emitido alguna excepción no controlada o hubiera proporcionado un comportamiento incorrecto.
Escriba sigue indicando a petición, pero este trabajo se ejecuta una vez cada hora ahora.
Supervisión del trabajo y revisión de registros
Si ha completado todos los pasos anteriores, ahora tiene un trabajo que funciona como una tarea programada en la nube, realizando acciones hacia sus sitios de Office 365.
Si desea revisar cuándo se ejecutó el trabajo por última vez, cuál fue el resultado de cada ejecución del trabajo o qué ocurrió durante la ejecución del trabajo, puede elegir el vínculo en Registros cuando esté en la información general de WebJobs.
Esto proporciona información general de todas las ejecuciones de los trabajos seleccionados, incluido el estado / resultado.
Al elegir el vínculo resaltado, puede profundizar en una ejecución específica para revisar los registros del trabajo y asegurarse de que todo parece correcto. Esto es probablemente más relevante si el trabajo realmente causó un error y necesitó investigar qué salió mal, o si el resultado del trabajo es incorrecto o no es el esperado.
También puede ver que las instrucciones Console.WriteLine que usamos en la aplicación de consola para esta demostración ahora aparecen en el registro de ejecución del trabajo.
Vea también
- Entrada de blog original sobre Azure WebJobs de Tobias Zimmergren
- Desarrollo e implementación de WebJobs mediante Visual Studio: Azure App Service
- Trabajo sencillo del temporizador remoto que interactúa con SharePoint Online vídeo de Andrew Connell en Channel9
- Usar Microsoft Azure WebJobs con Office 365
- Marco de trabajo del temporizador remoto PnP