Ejemplo de aplicación de consola de aprovisionamiento

Artículo
04/08/2023

Para admitir el nuevo modelo de complementos, el programa de patrones y prácticas (PnP) de Office 365 Developer introdujo un marco de aprovisionamiento que permite a los usuarios:

Crear plantillas de sitio personalizadas con solo señalar un modelo de sitio.
Conservar el modelo como una plantilla de aprovisionamiento.
Aplicar la plantilla personalizada a colecciones de sitios existentes, según sea necesario.

Nota:

El marco de aprovisionamiento de PnP & motor de aprovisionamiento de PnP son soluciones de código abierto con una comunidad activa que proporciona soporte técnico para él. No hay ningún contrato de nivel de servicio para el soporte de la herramienta de código abierto de Microsoft.

En este ejemplo, creamos una aplicación de consola básica que implementa clases en la biblioteca de aprovisionamiento principal de PnP para habilitar el motor de aprovisionamiento PnP y realizar estas tareas esenciales de aprovisionamiento:

Diseñar y modelar la personalización del sitio. Puede ser un nuevo diseño de sitio o puede apuntar a un sitio existente y guardarlo como una plantilla de aprovisionamiento.
Guardar y conservar el modelo de sitio como plantilla de aprovisionamiento para poder volver a utilizarlo.
Aplicar la plantilla de aprovisionamiento a una colección de sitios nueva o existente.

Nota:

Este tutorial de ejemplo complementa una muestra disponible actualmente en GitHub en Introducción al motor de aprovisionamiento de PnP. El código (Program.cs) y los archivos de solución de la muestra están disponibles para su descarga. También hay una presentación en vídeo de 20 minutos sobre este proceso (con código ligeramente distinto) disponible en el sitio de Microsoft Channel 9: Introducción al motor de aprovisionamiento de PnP.

Crear y preparar un proyecto de Visual Studio

Para empezar, cree un proyecto de Visual Studio. En este ejemplo, para simplificar, creamos una aplicación de consola básica que implementa el motor de aprovisionamiento PnP mediante la biblioteca principal de PnP del marco de aprovisionamiento. Sin embargo, para admitir la solución de ejemplo, necesitamos descargar e instalar el marco de aprovisionamiento de la biblioteca principal de PnP.

Abra Visual Studio y diríjase a Archivo>Nuevo>Proyecto.
En el Asistente para nuevos proyectos, seleccione Visual C# y luego elija Aplicación de consola.
Asigne un nombre Programa al proyecto y luego seleccione Aceptar. (Puede asignar el nombre que quiera al proyecto, pero tenga en cuenta que en este tutorial se hará referencia al proyecto como Programa).
Descargar e instalar la biblioteca principal de PnP que está disponible como un paquete de NuGet en paquetes SharePointPnPCore.

Nota:

Hay tres versiones de la biblioteca. Una versión es la biblioteca SharePointPnPCoreOnline, que está destinada a SharePoint Online y Office 365. Las otras versiones son SharePointPnPCore2013 y SharePointPnPCore2016, que están destinadas a las versiones locales de SharePoint 2013 y 2016 respectivamente.
Instale el cliente de NuGet yendo al instalador del cliente NuGet.
Una vez se haya instalado el cliente NuGet, ejecute el Administrador de paquetes NuGet. Haga clic derecho en el nodo referencias en el Explorador de soluciones de Visual Studio y después seleccione Administrar paquetes NuGet.
En el Administrador de paquetes, elija Examinar y después escriba el término de búsqueda SharePoint PnP para mostrar la biblioteca SharePointPnPCoreOnline.
Siga las instrucciones para descargar e instalar la biblioteca SharePointPnPCoreOnline.

Una vez se haya hecho la referencia a la biblioteca principal de PnP en el proyecto de Visual Studio, todos los miembros de la biblioteca están disponibles como métodos de extensión en las instancias de objeto existentes, por ejemplo, las instancias web y lista.

Asegúrese de que el archivo Program.cs contiene todos las instrucciones using siguientes.

using Microsoft.SharePoint.Client;
using OfficeDevPnP.Core.Framework.Provisioning.Connectors;
using OfficeDevPnP.Core.Framework.Provisioning.Model;
using OfficeDevPnP.Core.Framework.Provisioning.ObjectHandlers;
using OfficeDevPnP.Core.Framework.Provisioning.Providers.Xml;
using System;
using System.Net;
using System.Security;
using System.Threading;

Crear, extraer y conservar la plantilla de aprovisionamiento

Después de configurar el proyecto, puede crear las personalizaciones del sitio. Puede hacerlo manualmente o señalando a un sitio cuyo diseño quiera usar. Solo tiene que guardar el diseño del sitio seleccionado como una plantilla de aprovisionamiento, o bien, puede usar una combinación de ambos métodos. Para este ejemplo, simplemente señalaremos a un sitio existente y guardaremos el aspecto compuesto y los objetos del sitio (pero no su contenido) como una plantilla de aprovisionamiento.

Para empezar, es necesario conectarse al sitio que queremos modelar como plantilla de aprovisionamiento. Empezaremos por recopilar de información de conexión, incluidos el nombre de usuario, la contraseña y la dirección URL de origen.

Recopile la información de conexión del usuario. En la rutina del programa Main, hacemos tres cosas: recopilar la información de conexión, OBTENER la plantilla de aprovisionamiento y APLICAR la plantilla de aprovisionamiento. La mayor carga del trabajo la realizan los métodos GetProvisioningTemplate y ApplyProvisioningTemplate que se definen a continuación.

static void Main(string[] args)
{
  ConsoleColor defaultForeground = Console.ForegroundColor;

  // Collect information
  string templateWebUrl = GetInput("Enter the URL of the template site: ", false, defaultForeground);
  string targetWebUrl = GetInput("Enter the URL of the target site: ", false, defaultForeground);
  string userName = GetInput("Enter your user name:", false, defaultForeground);
  string pwdS = GetInput("Enter your password:", true, defaultForeground);
  SecureString pwd = new SecureString();
  foreach (char c in pwdS.ToCharArray()) pwd.AppendChar(c);

  // GET the template from existing site and serialize
  // Serializing the template for later reuse is optional
  ProvisioningTemplate template = GetProvisioningTemplate(defaultForeground, templateWebUrl, userName, pwd);

  // APPLY the template to new site from
  ApplyProvisioningTemplate(targetWebUrl, userName, pwd, template);

  // Pause and modify the UI to indicate that the operation is complete
  Console.ForegroundColor = ConsoleColor.White;
  Console.WriteLine("We're done. Press Enter to continue.");
  Console.ReadLine();
}

Cree y use un método GetInput privado para obtener las credenciales de usuario necesarias.

private static string GetInput(string label, bool isPassword, ConsoleColor defaultForeground)
{
  Console.ForegroundColor = ConsoleColor.Green;
  Console.WriteLine("{0} : ", label);
  Console.ForegroundColor = defaultForeground;

  string value = "";

  for (ConsoleKeyInfo keyInfo = Console.ReadKey(true); keyInfo.Key != ConsoleKey.Enter; keyInfo = Console.ReadKey(true))
  {
    if (keyInfo.Key == ConsoleKey.Backspace)
    {
      if (value.Length > 0)
      {
        value = value.Remove(value.Length - 1);
        Console.SetCursorPosition(Console.CursorLeft - 1, Console.CursorTop);
        Console.Write(" ");
        Console.SetCursorPosition(Console.CursorLeft - 1, Console.CursorTop);
      }
    }
    else if (keyInfo.Key != ConsoleKey.Enter)
    {
      if (isPassword)
      {
        Console.Write("*");
      }
      else
      {
        Console.Write(keyInfo.KeyChar);
      }
      value += keyInfo.KeyChar;
    }
  }
  Console.WriteLine("");

  return value;
}

Seleccione el sitio que usará como modelo para la plantilla de aprovisionamiento. Mientras realiza la función GET en el sitio de origen con una sola línea de código, observe GetProvisioningTemplate(), que es el método GET que se ha definido.

private static ProvisioningTemplate GetProvisioningTemplate(ConsoleColor defaultForeground, string webUrl, string userName, SecureString pwd)
{
  using (var ctx = new ClientContext(webUrl))
  {
    // ctx.Credentials = new NetworkCredentials(userName, pwd);
    ctx.Credentials = new SharePointOnlineCredentials(userName, pwd);
    ctx.RequestTimeout = Timeout.Infinite;

    // Just to output the site details
    Web web = ctx.Web;
    ctx.Load(web, w => w.Title);
    ctx.ExecuteQueryRetry();

    Console.ForegroundColor = ConsoleColor.White;
    Console.WriteLine("Your site title is:" + ctx.Web.Title);
    Console.ForegroundColor = defaultForeground;

    ProvisioningTemplateCreationInformation ptci
            = new ProvisioningTemplateCreationInformation(ctx.Web);

    // Create FileSystemConnector to store a temporary copy of the template
    ptci.FileConnector = new FileSystemConnector(@"c:\temp\pnpprovisioningdemo", "");
    ptci.PersistComposedLookFiles = true;
    ptci.ProgressDelegate = delegate(String message, Int32 progress, Int32 total)
    {
        // Only to output progress for console UI
        Console.WriteLine("{0:00}/{1:00} - {2}", progress, total, message);
    };

    // Execute actual extraction of the template
    ProvisioningTemplate template = ctx.Web.GetProvisioningTemplate(ptci);

    // We can serialize this template to save and reuse it
    // Optional step
    XMLTemplateProvider provider =
            new XMLFileSystemTemplateProvider(@"c:\temp\pnpprovisioningdemo", "");
    provider.SaveAs(template, "PnPProvisioningDemo.xml");

    return template;
  }
}

En el fragmento de código anterior, se define también una variable ProvisioningTemplateCreationInformation: pcti. La variable nos permite almacenar información sobre los objetos que podemos guardar junto con la plantilla.

Cree un objeto conector del sistema de archivos de modo que podamos almacenar una copia temporal de la plantilla de aprovisionamiento que vamos a aplicar en otro sitio.

Nota:

Este paso es opcional. No es necesario serializar la plantilla de aprovisionamiento en XML. En esta fase, la plantilla es simplemente código C#. La serialización no solo es opcional, sino que también puede usar cualquier formato de serialización que quiera.
Ejecute la extracción de la plantilla de aprovisionamiento usando solo esta línea de código:
```
ProvisioningTemplate template = ctx.Web.GetProvisioningTemplate(ptci);
```
(Opcional) Guarde y almacene una versión serializada de la plantilla de aprovisionamiento para poder volver a utilizarla. Puede serializar la plantilla aprovisionamiento en cualquier formato que prefiera. En este ejemplo, hemos serializado en un archivo XML denominado PnPProvisioningDemo.xml. El archivo es un objeto XMLFileSystemTemplateProvider para el que proporcionamos una ubicación del sistema de archivos.

Aplicar la plantilla de aprovisionamiento a un sitio nuevo o existente.

Después de extraer, guardar y conservar la plantilla aprovisionamiento, el siguiente y último paso es aplicar la plantilla de aprovisionamiento a una nueva colección de sitios de SharePoint mediante el método ApplyProvisioningTemplate.

Obtener las credenciales para el sitio de destino.

// ctx.Credentials = new NetworkCredentials(userName, pwd);
ctx.Credentials = new SharePointOnlineCredentials(userName, pwd);
ctx.RequestTimeout = Timeout.Infinite;

Capture los objetos del sitio que se almacenaron con el método ProvisioningTemplateCreationInformation usando el método complementario ProvisioningTemplateApplyingInformation.

ProvisioningTemplateApplyingInformation ptai = new ProvisioningTemplateApplyingInformation();
ptai.ProgressDelegate = delegate(String message, Int32 progress, Int32 total)
{
  Console.WriteLine("{0:00}/{1:00} - {2}", progress, total, message);
};

Obtenga una asociación para el conector de archivos para los activos.

// Associate file connector for assets
FileSystemConnector connector = new FileSystemConnector(@"c:\temp\pnpprovisioningdemo", "");
template.Connector = connector;

(Opcional) Dado que la plantilla de aprovisionamiento es una instancia de objeto, podemos escribir código para personalizar los objetos del sitio en cualquier momento. En este caso, vamos a agregar una nueva lista "contact".

// Because the template is actual object, we can modify this using code as needed
template.Lists.Add(new ListInstance()
{
  Title = "PnP Sample Contacts",
  Url = "lists/PnPContacts",
  TemplateType = (Int32)ListTemplateType.Contacts,
  EnableAttachments = true
});

Aplique la plantilla de aprovisionamiento en el nuevo sitio con una línea de código.
```
web.ApplyProvisioningTemplate(template, ptai);
```

La implementación completa del método ApplyProvisioningTemplate() se encuentra a continuación.

private static void ApplyProvisioningTemplate(string targetWebUrl, string userName, SecureString pwd, ProvisioningTemplate template)
{
  using (var ctx = new ClientContext(targetWebUrl))
  {
    // ctx.Credentials = new NetworkCredentials(userName, pwd);
    ctx.Credentials = new SharePointOnlineCredentials(userName, pwd);
    ctx.RequestTimeout = Timeout.Infinite;

    Web web = ctx.Web;

    ProvisioningTemplateApplyingInformation ptai = new ProvisioningTemplateApplyingInformation();
    ptai.ProgressDelegate = delegate (String message, Int32 progress, Int32 total)
    {
      Console.WriteLine("{0:00}/{1:00} - {2}", progress, total, message);
    };

    // Associate file connector for assets
    FileSystemConnector connector = new FileSystemConnector(@"c:\temp\pnpprovisioningdemo", "");
    template.Connector = connector;

    // Because the template is actual object, we can modify this using code as needed
    template.Lists.Add(new ListInstance()
    {
      Title = "PnP Sample Contacts",
      Url = "lists/PnPContacts",
      TemplateType = (Int32)ListTemplateType.Contacts,
      EnableAttachments = true
    });

    web.ApplyProvisioningTemplate(template, ptai);
  }
}

Vea también

Aprovisionamiento remoto de PnP

Ejemplo de aplicación de consola de aprovisionamiento

Crear y preparar un proyecto de Visual Studio

Crear, extraer y conservar la plantilla de aprovisionamiento

Aplicar la plantilla de aprovisionamiento a un sitio nuevo o existente.

Vea también

Recursos adicionales