Compartir a través de

Desarrollo de un complemento de Project Online mediante el modelo de objetos de JavaScript (JSOM)

En este artículo se describe Microsoft Project Online desarrollo de complementos para mejorar su experiencia con el Project Online. El proyecto de desarrollo se implementa como un tutorial. El complemento usado para este artículo lee y muestra los nombres de proyecto y los identificadores de los proyectos publicados de la cuenta de Project Online y le permite explorar en profundidad para recuperar las tareas asociadas a proyectos individuales.

En tiempo de ejecución, la lista de complementos es similar a la siguiente ilustración:

Captura de pantalla que muestra una lista de proyectos y tareas de JSOM

El foco del ejemplo es la interacción con el Project Online, realizando consultas y estableciendo el contexto para cada solicitud del servicio. Los elementos de la interfaz de usuario reciben una atención mínima. En su lugar, las listas de origen proporcionan comentarios sobre la interfaz de usuario.

Nota:

Los archivos de origen del complemento de ejemplo, un proyecto de Visual Studio, están disponibles en: https://github.com/OfficeDev/Project-JSOM-List-Projects-Tasks..... Mantenga los archivos de origen a mano como referencia mientras lee el artículo, ya que cada uno complementa al otro. Los archivos de la compilación del proyecto de Visual Studio y son ejecutables con cambios mínimos, sustituyendo la dirección URL del inquilino de Project Online a la carpeta PWA.

Información previa

Project Online es un servicio de Office 365 que proporciona a las empresas una solución de gestión de carteras de proyectos (PPM) y oficina de gestión de proyectos (PMO) para coordinar y administrar carteras, programas y proyectos. Project Online es una oferta diferente a las ediciones de escritorio de Project; sin embargo, Project Online todavía contiene la funcionalidad para mantener y realizar un seguimiento de los detalles del proyecto a lo largo de la vida de un proyecto. Project Online se basa en SharePoint Online.

Un complemento hospedado de Project Online consta de JavaScript y archivos de recursos que interactúan con la API Client-Side-Object-Model. Cuando el usuario visita el complemento, JavaScript y los recursos se descargan y ejecutan en el explorador. El complemento realiza llamadas asincrónicas a Project Online para interactuar con el servicio, ya sea crear, recuperar, actualizar o eliminar datos.

Project Online realiza una acción más para proteger la información que pertenece a otros inquilinos del complemento; es decir, Project Online crea un sitio aislado para interactuar con las solicitudes del complemento. No se ejecuta ningún código personalizado en el host de Project Online.

La configuración de desarrollo para complementos de Project Online usa el tipo de proyecto Complemento de SharePoint de Visual Studio. El complemento está escrito en JavaScript y usa el modelo de objetos de JavaScript de Project (JSOM) para interactuar con el servicio de Project Online. El JSOM hereda gran parte de su funcionalidad del JSOM de SharePoint.

Nota:

Los complementos se pueden publicar y vender en la Tienda Office o implementarse en un catálogo de aplicaciones privadas en SharePoint. Para obtener más información, vea Implementar y publicar el complemento de Office.

El complemento usado en este artículo es un ejemplo para desarrolladores; no está pensado para su uso en un entorno de producción. El propósito principal es mostrar un ejemplo de desarrollo de aplicaciones para Project Online.

Requisitos previos

Agregue los siguientes elementos a un entorno de Windows compatible:

Nota:

.NET Framework estándar es el marco correcto para usar. No use el "Perfil de cliente de.NET Framework 4".

Configuración del proyecto de Visual Studio

La configuración de la aplicación consiste en crear un nuevo proyecto, vincular las bibliotecas adecuadas y declarar los espacios de nombres necesarios. Visual Studio presenta varios tipos de proyectos de desarrollo. La sección es breve y muy básica. El valor es que la información se combina en un solo lugar.

Seleccionar un proyecto de Visual Studio

Para crear un proyecto del tipo adecuado para el complemento, debe realizar los pasos siguientes. Las palabras clave encontradas en la pantalla tienen un atributo bold :

  1. En el menú Archivo, elija Archivo>nuevo>proyecto.

  2. En plantillas instaladas en el panel izquierdo, seleccioneComplementos web de C#>Office/SharePoint>.

  3. En la parte superior del panel central, seleccione .NET Framework 4 o posterior; la versión actual es la 4.6.

  4. En los tipos de aplicación del panel central, elija Complemento de SharePoint.

  5. En la sección inferior, especifique un nombre y una ubicación para el proyecto, así como un nombre de la solución.

  6. También en la sección inferior, active la casilla Crear directorio para la solución.

  7. Haga clic en Aceptar para crear un proyecto inicial.

El Asistente para Visual Studio hace algunas preguntas de seguimiento sobre el sitio de configuración de Project Online (denominado Configuración de SharePoint en los diálogos) en un par de diálogos que siguen. Estas son las preguntas:

  1. ¿Qué sitio de SharePoint desea usar para depurar el complemento? Especifique la dirección URL del sitio de PWA, como https://contoso.sharepoint.com/sites/pwa.

  2. ¿Cómo desea hospedar el complemento de SharePoint? Elija [X] Hospedado en SharePoint.

    Para obtener más información sobre los complementos de SharePoint, incluidas las opciones de hospedaje, vea Complementos de SharePoint.

  3. Haga clic en Siguiente.

El segundo cuadro de diálogo adicional le pide que especifique la versión de SharePoint Online para el complemento:

  1. ¿Cuál es la versión más antigua de SharePoint a la que quiere que se dirija el complemento? Elija [X] S harePoint-Online.

  2. Haga clic en Finalizar.

Visual Studio crea el proyecto y accede al sitio de Project Online.

Habilitación de la instalación local en el sitio de Project Online

La instalación local es el mecanismo para probar y depurar Project Online complementos. Necesita dos scripts para la instalación local: uno para habilitar la instalación local en el sitio de Project Online y otro para deshabilitar la instalación local una vez que termine de probar y depurar el complemento.

Para obtener más información sobre cómo configurar la instalación de prueba, consulte Habilitar la instalación local de aplicaciones en la colección de sitios que no son para desarrolladores.

Nota:

La instalación local de aplicaciones es una característica para desarrolladores o pruebas. No está pensado para su uso en producción. No realice la transferencia local de aplicaciones con regularidad ni mantenga habilitada la instalación local de aplicaciones durante más tiempo del que usa activamente la característica.

Adición de contenido al proyecto de complemento

Después de crear un proyecto y configurar el mecanismo de depuración, agregar contenido a la aplicación incluye las siguientes tareas:

  • Establecer el ámbito de la aplicación

  • Vinculación de la biblioteca JSOM

  • Adición de elementos de interfaz de usuario al complemento

  • Inicialización y conexión al servicio Project Online

  • Recuperación de proyectos y detalles/propiedades

  • Mostrar proyectos

  • Mostrar tareas para un proyecto

El proyecto del complemento consta de muchos archivos. En este ejemplo, tendrá que editar los siguientes archivos:

  • AppManifest.xml

  • Default.aspx

  • App.js

  • App.css : opcional; contiene definiciones de estilo desarrolladas para el complemento

Si cambia el inquilino de Project Online, como pasar de una prueba a un sitio de suscripción, puede actualizar las propiedades del proyecto, incluida la conexión del servidor y la dirección URL del sitio, mediante la ventana Propiedades disponible a través del comando Ver>ventana propiedades.

También puede agregar archivos al proyecto. Si es así, deberá actualizar el archivo Elements.xml ubicado en el mismo grupo (Contenido, Imágenes, Páginas o Scripts) para incluir los nuevos archivos. Para obtener más información sobre los archivos de proyecto, vea Explorar la estructura del manifiesto de la aplicación y el paquete de un complemento de SharePoint.

Establecimiento del ámbito de la aplicación

El complemento necesita ámbito o niveles de permisos definidos antes de que el servicio devuelva información en los resultados de la consulta. Para este complemento, use el siguiente ámbito para el proyecto de Visual Studio. Este cambio se realiza en el archivo AppManifest.xml en la pestaña Permisos:

Ámbito Permiso
Varios proyectos (Project Server)
 Lectura

Guarde el archivo después de establecer el ámbito de la aplicación. De lo contrario, no se devolverá ningún dato del servicio.

Las bibliotecas de Project Online en tiempo de ejecución, PS.js y PS.debug.js, son proporcionadas por Project Online y siempre son la versión más reciente. Los complementos de JavaScript que usan JSOM deben vincularse a una de estas bibliotecas. Las definiciones de vinculación se agregan en el archivo Default.aspx. Los comandos para usar los PS.js o PS.debug.js forman parte del código que se encuentra en el archivo App.js.

Agregue el siguiente comando para PS.js o PS.debug.js definición en el <asp:Content ContentPlaceHolderID="PlaceHolderAdditionalPageHead" elemento que sigue a "SharePoint:ScriptLink" para sp.js.

<SharePoint:ScriptLink name="PS.js" runat="server" OnDemand="false" LoadAfterUI="true" Localizable="false" />

Nota:

El atributo OnDemand para PS.js o PS.debug.js establecido en false.

Adición de elementos de interfaz de usuario al complemento

El complemento de ejemplo consta de algunos componentes. Las descripciones de elementos estáticos se encuentran en el archivo Default.aspx. Las descripciones de elementos dinámicos y el código de todos los componentes se encuentran en el archivo App.js. Para obtener comentarios sobre los componentes, consulte las listas de código fuente. Esta es una lista de los componentes de la interfaz de usuario en el complemento:

  • Título

  • Verbiage introductorio

  • Botón para quitar tareas de la tabla

  • Tabla que muestra el identificador y el nombre del proyecto, así como la información de la tarea.

  • Botón Tareas (clonado una vez para cada proyecto) que importa datos de tareas en la tabla.

Para obtener más información sobre la interfaz de usuario, como el título y la parte de encabezado de la tabla del proyecto, consulte el archivo de proyecto Default.aspx.

Inicializar y conectarse al sistema host

El archivo App.js contiene el código JavaScript. El complemento carga PS.js en el explorador y, a continuación, llama a la función initializePage. InitializePage recupera un contexto para el punto de conexión Project Online e inicia la función loadProjects.

    'use strict';
    SP.SOD.executeOrDelayUntilScriptLoaded(initializePage, "PS.js");
    //Project PWA Context and published projects in PWA
    var projContext;
    var projects;
    function initializePage() {
        //Get the Project context for this web
        projContext = PS.ProjectContext.get_current();
        loadProjects();
    }
    //General CSOM failure event handler
    //Invoked when ExecuteQueryAsync returns unsuccessfully
    function onRequestFailed(sender, args) {
        alert("Failed to execute: " + args.get_message());
        return;
    };

Recuperar los proyectos

La función loadProjects consulta al servicio los nombres de proyecto y los identificadores.

La aplicación recupera el nombre del proyecto y el identificador del proyecto. Hay disponible otra información sobre el proyecto a la que se puede acceder modificando el método load para identificar explícitamente las propiedades que se van a recuperar. En el código se proporciona un ejemplo como comentario.

Si la consulta se realiza correctamente, el complemento continúa llamando a displayProjects.

    //Query CSOM and get the list of projects in PWA
    function loadProjects() {
        projects = projContext.get_projects();
    //Request to server - identifies what to retrieve
        projContext.load(projects, 'Include(Name, Id)');
        //Notice to server to execute query
        projContext.executeQueryAsync(displayProjects, onRequestFailed);
        // Syntax for requesting more fields to pull down from server
        // projContext.load(projects, 'Include(Name, Description, StartDate, 
        // Id, IsCheckedOut)');
    }

Mostrar los proyectos

La función displayProjects crea una tabla, una fila por proyecto y un botón para mostrar las tareas del proyecto específico.

    //Display the projects with names and ids in a table
    function displayProjects() {
        //Current published project and ID
        var p, projId;
        //Project table rows to publish collectively
        var pTable = []; 
        var pEnum = projects.getEnumerator();
        //Build a 3-column table, with one project per row.
        while (pEnum.moveNext()) {
            p = pEnum.get_current();
        
            //Items used in getting information for table rows:
            //Current published project object, and ID and name
            // var project = p;
            // var projId = p.get_id();
            // var projName = p.get_name();
        
            //Continue processing/working with project object as needed.
        }
    }

Nota:

El bucle while tiene acceso a las propiedades id. y name. Esto es ligeramente diferente al proyecto de código fuente que llama a una función que, a su vez, tiene acceso a las mismas propiedades.

Mostrar las tareas de un proyecto

Las tareas, aunque forman parte del complemento, no forman parte de la carga inicial. Si el usuario está interesado en las tareas asociadas a un proyecto, hacer clic en el botón "Mostrar tareas" hace que las tareas se muestren en la lista mediante el controlador de eventos btnLoadTasks.

El controlador de eventos btnLoadTasks, con el identificador de proyecto adecuado, solicita las tareas del proyecto especificado desde el servidor. Una vez recuperado, btnLoadTasks pasa la lista de tareas a displayTasks para presentar las tareas en pantalla.

    //Query CSOM and get the list of tasks for a specific project
    function btnLoadTasks(pid) {
        //Event handler for the "Show tasks" buttons. 
        //
        //The project ID is the sole argument and is used to get the appropriate task 
        //info from the service.
        //The project ID is also the button name, and is used to identify where to place
        //the task information in the table.
        //
        //Project ID to pass to the event handler
        var projId = pid;
        //
        //Get the project reference
        var pProj = projects.getById(projId);
        //
        //Get the tasks collection reference associated with the project.
        var tasks = pProj.get_tasks();
        //
        projContext.load(tasks, 'Include(Id, Name, Start, ScheduledStart, Completion)');
        //
        //If the query succeeds, displayTasks presents the tasks to the user.
        projContext.executeQueryAsync(function () { displayTasks(tasks, projId) }, onRequestFailed);
    }

La función displayTasks muestra las tareas asociadas a un proyecto especificado inmediatamente debajo de la entrada del proyecto.

    //Insert tasks for the specified project immediately underneath the project entry 
    //in the table.
    function displayTasks(tasks, projId) {
        //selected project ID
        var pId = projId;
        //individual task
        var t;
        //Task table rows to publish collectively
        var tTable = [];
        var tEnum = tasks.getEnumerator();
        //Build table one task per row.
        while (tEnum.moveNext()) {
            t = tEnum.get_current();
            //
            //Items used in getting information for table rows:
            //Current task object, and ID and name
            // var task = t;
            // var taskId = t.get_id();
            // var taskName = t.get_name();
            
            //Continue processing/working with task object as needed.
        }
    }

Nota:

El bucle while tiene acceso al identificador de tarea y a las propiedades de nombre. Esto es ligeramente diferente al proyecto de código fuente que llama a una función que, a su vez, tiene acceso a las mismas propiedades.

A continuación se muestra la salida de ejemplo para las tareas de un único proyecto.

Captura de pantalla que muestra la salida de una tarea de proyecto

Vea también

Para conocer la documentación y los ejemplos relacionados con Project Online y el desarrollo de aplicaciones con CSOM, consulte el Portal de desarrollo del proyecto.