Remplacer SharePoint fichiers déployés à l’aide de modules dans des solutions de batterie de serveurs

Si vous avez déployé des fichiers de façon déclarative à l’aide de modules dans des solutions de batterie de serveurs, découvrez comment les transformer en nouvelles solutions qui met à jour les références aux fichiers et fournissent des fonctionnalités similaires à l’aide du modèle objet client (CSOM). Dans le passé, les modules étaient utilisés pour déployer des fichiers tels que des pages maîtres et des mises en page.

Important

Les solutions de batterie de serveurs ne peuvent pas être migrées vers SharePoint Online. En appliquant les techniques et le code décrits dans cet article, vous pouvez créer une nouvelle solution avec des fonctionnalités similaires que fournissent vos solutions de batterie de serveurs, mettre à jour les références aux fichiers, puis déployer la nouvelle solution sur SharePoint Online. Vous pouvez ensuite désactiver la fonctionnalité et retirer la solution de batterie précédente.

Le code dans cet article requiert un code supplémentaire pour offrir une solution totalement fonctionnelle. Par exemple, cet article n’explique pas comment s’authentifier auprès de Office 365, comment implémenter la gestion des exceptions requise, etc. Pour plus d’exemples de code, reportez-vous à la rubrique Pratiques et modèles de développement Office 365.

Notes

Le code dans cet article est fourni tel quel, sans garantie d’aucune sorte, expresse ou implicite, y compris mais sans s’y limiter, aucune garantie implicite d’adéquation à un usage particulier, à une qualité marchande ou une absence de contrefaçon.

Cet article explique comment utiliser le processus de transformation pour :

  • Télécharger et mettre à jour les références aux pages maîtres
  • Télécharger et mettre à jour les références aux mises en page

Utilisez ce processus de transformation dans les cas ci-après :

  • Vos solutions de batterie de serveurs existantes utilisaient des modules pour déployer des fichiers.
  • Vous souhaitez remplacer les pages maîtres et les mises en page dans les solutions de batterie de serveurs par de nouvelles pages maîtres et mises en page afin qu’elles soient migrées vers SharePoint Online.
  • Vous avez définie des types de contenu de document sur des pages maîtres ou des mises en page dans votre solution de batterie de serveurs de manière déclarative.

Avant de commencer

Dans l’idéal, vous devez examiner vos solutions de batterie de serveurs existantes, en savoir plus sur les techniques décrites dans cet article, puis planifier l’application de ces techniques à vos scénarios. Si vous ne connaissez pas les solutions de batterie de serveurs ou si vous n’avez pas de solution de batterie existante à travailler, il peut vous être utile d’en savoir plus sur les solutions de batterie de serveurs.

Pour plus d’informations, voir Créer des solutions de batterie de serveurs dans SharePoint.

Activer les fonctionnalités de publication sur la collection de sites et le site

Avant d’exécutez votre exemple de code, activez les fonctionnalités de publication sur la collection de sites et le site avec les procédures suivantes.

Pour activer la fonctionnalité Infrastructure SharePoint Server Publishing sur la collection de sites

  1. Ouvrez votre site SharePoint site web et Paramètres > site Paramètres.

  2. Dans Administration de la collection de sites, choisissez les fonctionnalités de la collection de sites.

  3. On SharePoint Server Publishing Infrastructure, choose Activate.

Pour activer la fonctionnalité SharePoint Server Publishing sur le site

  1. Ouvrez votre site SharePoint site web et Paramètres > site Paramètres.

  2. Dans Actions du site, choisissez Gérer les fonctionnalités du site.

  3. On SharePoint Server Publishing, choose Activate.

Configurer votre projet Visual Studio projet

  1. Téléchargez l’exemple de projet. Choisissez View Raw pour commencer à télécharger l’exemple de projet, extrayez les fichiers du fichier zip, puis accédez au dossier Module9/ModuleReplacement.

  2. Ouvrez ModuleReplacement.sln.

  3. Ouvrez settings.xml. Examinez et mettez à jour les attributs suivants pour répondre à vos besoins :

    • Élément masterPage : utilise l’attribut de fichier pour spécifier la nouvelle page maître à déployer dans la galerie de pages maîtres, et l’attribut remplace l’attribut pour spécifier la page maître existante dans la galerie de pages maîtres.

    • Élément pageLayout : utilise l’attribut de fichier pour spécifier le nouveau fichier de mise en page, l’attribut remplace pour spécifier le fichier de mise en page existant et plusieurs autres attributs pour spécifier des informations de mise en page supplémentaires.

        <?xml version="1.0" encoding="utf-8" ?>
        <branding>
          <masterPages>
               <masterPage file="contoso_app.master" replaces="contoso.master"/>
          </masterPages>
          <pageLayouts>
               <pageLayout file="ContosoWelcomeLinksApp.aspx" replaces="ContosoWelcomeLinks.aspx" title="Contoso Welcome Links add-in" associatedContentTypeName="Contoso Web Page" defaultLayout="true" />
          </pageLayouts>
        </branding>
    
    
  4. Dans MasterPageGalleryFiles.cs, les classes MasterPageGalleryFile et LayoutFile définissent des objets métier qui stockent des informations sur les nouvelles pages maîtres et mises en page à télécharger sur SharePoint.

Télécharger et mettre à jour les références aux pages maîtres

Pour télécharger et mettre à jour des références aux nouvelles pages maîtres sur votre site SharePoint site :

  1. Dans Program.cs, ajoutez l’instruction using suivante.

         using System.Security;
    
  2. Dans Program.cs, ajoutez les méthodes suivantes pour effectuer l’authentification à Office 365.

static SecureString GetPassword()
      {
          SecureString sStrPwd = new SecureString();
          try
          {
              Console.Write("Password: ");

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

              }
              Console.WriteLine("");
          }
          catch (Exception e)
          {
              sStrPwd = null;
              Console.WriteLine(e.Message);
          }

          return sStrPwd;
      }

      static string GetUserName()
      {
          string strUserName = string.Empty;
          try
          {
              Console.Write("Username: ");
              strUserName = Console.ReadLine();
          }
          catch (Exception e)
          {
              Console.WriteLine(e.Message);
              strUserName = string.Empty;
          }
          return strUserName;
      }
  1. Dans Program.cs, ajoutez le code suivant à la méthode Main, qui effectue les tâches suivantes :

    1. Charge le settings.xml fichier.

    2. Obtient une référence à la galerie de pages maîtres à l’aide de GetCatalog (116).

      Les pages maîtres sont téléchargées vers la galerie de pages maîtres. L’identificateur du modèle de liste de la galerie de pages maîtres est 116. Pour plus d’informations, voir ListTemplate, élément (site). D’autres détails sur la galerie de pages maîtres sont chargés, y compris l’utilisation de List.ContentTypes pour obtenir les types de contenu associés à la galerie de pages maîtres.

    3. Charge les propriétés de l’objet Web, notamment Web.ContentTypes, Web.MasterUrl et Web.CustomMasterUrl.

    4. Définit parentMasterPageContentTypeId sur l’ID de type de contenu des pages maîtres. Pour plus d’informations, voir Hiérarchie des types de contenu de base.

    5. Obtient le type de contenu des pages maîtres à partir de la galerie de pages maîtres. Ce type de contenu est utilisé pour définir le type de contenu de la nouvelle page maître plus loin dans cet article.

      static void Main(string[] args)
          { 
              string userName = GetUserName();
              SecureString pwd = GetPassword();
      
          // End program if no credentials were entered.
              if (string.IsNullOrEmpty(userName) || (pwd == null))
              return;
      
              using (var clientContext = new ClientContext("http://sharepoint.contoso.com"))
              {
      
                  clientContext.AuthenticationMode = ClientAuthenticationMode.Default;
                  clientContext.Credentials = new SharePointOnlineCredentials(userName, pwd);
      
                  XDocument settings = XDocument.Load("settings.xml");
      
                  // Get a reference to the Master Page Gallery which will be used to upload new master pages. 
      
                  Web web = clientContext.Web;
                  List gallery = web.GetCatalog(116);
                  Folder folder = gallery.RootFolder;
      
                  // Load additional Master Page Gallery properties.
                  clientContext.Load(folder);
                  clientContext.Load(gallery,
                                      g => g.ContentTypes,
                                      g => g.RootFolder.ServerRelativeUrl);
      
                  // Load the content types and master page information from the web.
                  clientContext.Load(web,
                                      w => w.ContentTypes,
                                      w => w.MasterUrl,
                                      w => w.CustomMasterUrl);
                  clientContext.ExecuteQuery();
      
                  // Get the content type for the master page from the Master Page Gallery using the content type ID for masterpages (0x010105).
                  const string parentMasterPageContentTypeId = "0x010105";  
                  ContentType masterPageContentType = gallery.ContentTypes.FirstOrDefault(ct => ct.StringId.StartsWith(parentMasterPageContentTypeId));
                  UploadAndSetMasterPages(web, folder, clientContext, settings, masterPageContentType.StringId);
      
              }
      
          }
      
  2. Dans Program.cs, ajoutez la méthode UploadAndSetMasterPages, qui crée une liste d’objets métier MasterPageGalleryFile en :

    1. Lecture de tous les éléments masterPage définis dans settings.xml.

    2. Pour chaque élément masterPage, qui spécifie une page maître à télécharger sur SharePoint, chargez les valeurs d’attribut dans un objet métier MasterPageGalleryFile.

    3. Pour chaque objet métier MasterPageGalleryFile dans la liste, appelez UploadAndSetMasterPage.

      
      private static void UploadAndSetMasterPages(Web web, Folder folder, ClientContext clientContext, XDocument settings, string contentTypeId)
      {
          IList<MasterPageGalleryFile> masterPages = (from m in settings.Descendants("masterPage")
                                                      select new MasterPageGalleryFile
                                                      {
                                                          File = (string)m.Attribute("file"),
                                                          Replaces = (string)m.Attribute("replaces"),
                                                          ContentTypeId = contentTypeId
                                                      }).ToList();
          foreach (MasterPageGalleryFile masterPage in masterPages)
          {
              UploadAndSetMasterPage(web, folder, clientContext, masterPage);
          }
      }
      
  3. Dans Program.cs, ajoutez la méthode UploadAndSetMasterPage, qui effectue les tâches suivantes :

    1. Vérifie la page maître.

    2. Charge le nouveau fichier à l’aide de FileCreationInformation.

    3. Obtient l’élément de liste associé au fichier nouvellement téléchargé.

    4. Définit différentes propriétés sur l’élément de liste, y compris la définition de l’ID de type de contenu de l’élément de liste sur l’ID de type de contenu de la page maître.

    5. Vérifie, publie et approuve la nouvelle page maître.

    6. Si la page maître du site actuel ou l’URL de la page maître personnalisée est définie sur l’ancienne page maître, met à jour Web.MasterUrl ouWeb.CustomMasterUrl pour utiliser l’URL de la page maître nouvellement téléchargée.

      private static void UploadAndSetMasterPage(Web web, Folder folder, ClientContext clientContext, MasterPageGalleryFile masterPage)
      {
          using (var fileReadingStream = System.IO.File.OpenRead(masterPage.File))
          {
              // If necessary, ensure that the master page is checked out.
              PublishingHelper.CheckOutFile(web, masterPage.File, folder.ServerRelativeUrl);
      
      // Use the FileCreationInformation class to upload the new file.
              var fileInfo = new FileCreationInformation();
              fileInfo.ContentStream = fileReadingStream;
              fileInfo.Overwrite = true;
              fileInfo.Url = masterPage.File;
              File file = folder.Files.Add(fileInfo);
      
      // Get the list item associated with the newly uploaded master page file.
              ListItem item = file.ListItemAllFields;
              clientContext.Load(file.ListItemAllFields);
              clientContext.Load(file,
                                  f => f.CheckOutType,
                                  f => f.Level,
                                  f => f.ServerRelativeUrl);
              clientContext.ExecuteQuery();
      
      item["ContentTypeId"] = masterPage.ContentTypeId;
              item["UIVersion"] = Convert.ToString(15);
              item["MasterPageDescription"] = "Master Page Uploaded using CSOM";
              item.Update();
              clientContext.ExecuteQuery();
      
      // If necessary, check in, publish, and approve the new master page file. 
              PublishingHelper.CheckInPublishAndApproveFile(file);
      
      // On the current site, update the master page references to use the new master page. 
              if (web.MasterUrl.EndsWith("/" + masterPage.Replaces))
              {
                  web.MasterUrl = file.ServerRelativeUrl;
              }
              if (web.CustomMasterUrl.EndsWith("/" + masterPage.Replaces))
              {
                  web.CustomMasterUrl = file.ServerRelativeUrl;
              }
              web.Update();
              clientContext.ExecuteQuery();
          }
      }
      

Télécharger et mettre à jour les références aux mises en page

Notes

Les exemples de code de cette section s’appuient sur les exemples de code de la section précédente de cet article.

Pour remplacer les mises en page déployées à l’aide de modules dans des solutions de batterie de serveurs et pour charger et mettre à jour des références afin d’utiliser les nouveaux fichiers de mise en page :

  1. Mettez à jour la méthode Main avec le code suivant. Ce code contient des étapes supplémentaires pour télécharger et mettre à jour des références aux fichiers de mise en page, notamment :

    1. Définition de parentPageLayoutContentTypeId sur l’ID de type de contenu de la mise en page.

    2. Obtention d’un type de contenu qui correspond à parentPageLayoutContentTypeId à partir de la galerie de pages maîtres.

    3. Appel de UploadPageLayoutsAndUpdateReferences.

                  static void Main(string[] args)
          { 
              string userName = GetUserName();
              SecureString pwd = GetPassword();
      
          // End program if no credentials were entered.
              if (string.IsNullOrEmpty(userName) || (pwd == null))
              return;
      
              using (var clientContext = new ClientContext("http://sharepoint.contoso.com"))
              {
      
                  clientContext.AuthenticationMode = ClientAuthenticationMode.Default;
                  clientContext.Credentials = new SharePointOnlineCredentials(userName, pwd);
      
                  XDocument settings = XDocument.Load("settings.xml");
      
                  // Get a reference to the Master Page Gallery, which will be used to upload new master pages. 
      
                  Web web = clientContext.Web;
                  List gallery = web.GetCatalog(116);
                  Folder folder = gallery.RootFolder;
      
                  // Load additional Master Page Gallery properties. 
                  clientContext.Load(folder);
                  clientContext.Load(gallery,
                                      g => g.ContentTypes,
                                      g => g.RootFolder.ServerRelativeUrl);
      
                  // Load the content types and master page information from the web.
                  clientContext.Load(web,
                                      w => w.ContentTypes,
                                      w => w.MasterUrl,
                                      w => w.CustomMasterUrl);
                  clientContext.ExecuteQuery();
      
                  // Get the content type for the master page from the Master Page Gallery using the content type ID for masterpages (0x010105).
                  const string parentMasterPageContentTypeId = "0x010105";  
                  ContentType masterPageContentType = gallery.ContentTypes.FirstOrDefault(ct => ct.StringId.StartsWith(parentMasterPageContentTypeId));
                  UploadAndSetMasterPages(web, folder, clientContext, settings, masterPageContentType.StringId);
      
              // Get the content type ID for the page layout, and then update references to the page layouts.
              const string parentPageLayoutContentTypeId = "0x01010007FF3E057FA8AB4AA42FCB67B453FFC100E214EEE741181F4E9F7ACC43278EE811"; 
              ContentType pageLayoutContentType = gallery.ContentTypes.FirstOrDefault(ct => ct.StringId.StartsWith(parentPageLayoutContentTypeId));
              UploadPageLayoutsAndUpdateReferences(web, folder, clientContext, settings, pageLayoutContentType.StringId);
              }
      
          }
      
  2. Dans Program.cs, ajoutez la méthode UploadPageLayoutsAndUpdateReferences, qui effectue les étapes suivantes :

    1. Lit les informations de remplacement de mise en page en lisant les éléments pagelayout à partir de settings.xml, en stockant les informations de remplacement de mise en page dans des objets métier LayoutFile et en ajoutant tous les objets métier à une liste.

    2. Pour chaque mise en page à remplacer :

      • Interroge les types de contenu du site à l’aide de Web.ContentTypes pour trouver un type de contenu correspondant où le nom du type de contenu du site est égal à l’associatedContentTypeName spécifié dans settings.xml pour la nouvelle mise en page.

      • Appelle UploadPageLayout.

      • Appelle UpdatePages pour mettre à jour les pages existantes afin d’utiliser les nouvelles mises en page.

                private static void UploadPageLayoutsAndUpdateReferences(Web web, Folder folder, ClientContext clientContext, XDocument settings, string contentTypeId)
        {
            // Read the replacement settings stored in pageLayout elements in settings.xml.
            IList<LayoutFile> pageLayouts = (from m in settings.Descendants("pageLayout")
                                        select new LayoutFile
                                        {
                                            File = (string)m.Attribute("file"),
                                            Replaces = (string)m.Attribute("replaces"),
                                            Title = (string)m.Attribute("title"),
                                            ContentTypeId = contentTypeId,
                                            AssociatedContentTypeName = (string)m.Attribute("associatedContentTypeName"),
                                            DefaultLayout = m.Attribute("defaultLayout") != null &amp;&amp; (bool)m.Attribute("defaultLayout")
                                        }).ToList();
        // Update the content type association.
                    foreach (LayoutFile pageLayout in pageLayouts)
            {
                ContentType associatedContentType =
                    web.ContentTypes.FirstOrDefault(ct => ct.Name == pageLayout.AssociatedContentTypeName);
                pageLayout.AssociatedContentTypeId = associatedContentType.StringId;                
                UploadPageLayout(web, folder, clientContext, pageLayout);
            }
        
                    UpdatePages(web, clientContext, pageLayouts);
                }
        
        
  3. Dans Program.cs, ajoutez la méthode UploadPageLayout, qui effectue les tâches suivantes :

    1. Vérifie le fichier de mise en page.

    2. Charge le nouveau fichier à l’aide de FileCreationInformation.

    3. Obtient l’élément de liste associé au fichier nouvellement téléchargé.

    4. Définit différentes propriétés sur l’élément de liste, y compris ContentTypeId et PublishingAssociatedContentType.

    5. Vérifie, publie et approuve le nouveau fichier de mise en page.

    6. Pour supprimer les références à l’ancien fichier de mise en page, appelle PublishingHelper.UpdateAvailablePageLayouts pour mettre à jour le XML stocké dans la propriété PageLayouts sur le site actuel.

    7. Si la valeur d’attribut defaultLayout du fichier de mise en page nouvellement téléchargé à partir de settings.xml est définie sur true, utilise PublishingHelper.SetDefaultPageLayout pour mettre à jour le XML stocké dans la propriété DefaultPageLayout sur le site actuel.

       private static void UploadPageLayout(Web web, Folder folder, ClientContext clientContext, LayoutFile pageLayout)
       {
           using (var fileReadingStream = System.IO.File.OpenRead(pageLayout.File))
           {
               PublishingHelper.CheckOutFile(web, pageLayout.File, folder.ServerRelativeUrl);
               // Use FileCreationInformation to upload the new page layout file.
               var fileInfo = new FileCreationInformation();
               fileInfo.ContentStream = fileReadingStream;
               fileInfo.Overwrite = true;
               fileInfo.Url = pageLayout.File;
               File file = folder.Files.Add(fileInfo);
               // Get the list item associated with the newly uploaded file.
               ListItem item = file.ListItemAllFields;
               clientContext.Load(file.ListItemAllFields);
               clientContext.Load(file,
                                   f => f.CheckOutType,
                                   f => f.Level,
                                   f => f.ServerRelativeUrl);
               clientContext.ExecuteQuery();
      
       item["ContentTypeId"] = pageLayout.ContentTypeId;
               item["Title"] = pageLayout.Title;
               item["PublishingAssociatedContentType"] = string.Format(";#{0};#{1};#", pageLayout.AssociatedContentTypeName, pageLayout.AssociatedContentTypeId);
               item.Update();
               clientContext.ExecuteQuery();
      
       PublishingHelper.CheckInPublishAndApproveFile(file);
      
       PublishingHelper.UpdateAvailablePageLayouts(web, clientContext, pageLayout, file);
      
       if (pageLayout.DefaultLayout)
               {
                   PublishingHelper.SetDefaultPageLayout(web, clientContext, file);
               }
           }
       }
      
  4. Dans Program.cs, ajoutez la méthode UpdatePages, qui effectue les tâches suivantes :

    1. Obtient la bibliothèque pages, puis obtient tous les éléments de liste dans la bibliothèque de pages.

    2. Pour chaque élément de liste, utilise le champ PublishingPageLayout de l’élément de liste pour rechercher une mise en page correspondante à mettre à jour, qui a été spécifiée dans settings.xml et est maintenant stockée dans les pageslayouts . Si le champ PublishingPageLayout de l’élément de liste doit être mis à jour pour faire référence à la nouvelle mise en page :

      • Vérifie le fichier de l’élément de liste à l’aide de PublishingHelper.CheckOutFile.

      • Met à jour l’URL de la mise en page pour faire référence au nouveau fichier de mise en page, puis met à jour le champ PublishingPageLayout de l’élément de liste.

      • Vérifie, publie et approuve le fichier référencé par l’élément de liste.

        private static void UpdatePages(Web web, ClientContext clientContext, IList<LayoutFile> pageLayouts)
        {
            // Get the Pages Library, and then get all the list items in it.
            List pagesList = web.Lists.GetByTitle("Pages");
            var allItemsQuery = CamlQuery.CreateAllItemsQuery();
            ListItemCollection items = pagesList.GetItems(allItemsQuery);
            clientContext.Load(items);
            clientContext.ExecuteQuery();
            foreach (ListItem item in items)
            {
                // Only update those pages that are using a page layout which is being replaced.
                var pageLayout = item["PublishingPageLayout"] as FieldUrlValue;
                if (pageLayout != null)
                {
                    LayoutFile matchingLayout = pageLayouts.FirstOrDefault(p => pageLayout.Url.EndsWith("/" + p.Replaces));
                    if (matchingLayout != null)
                    {
                        // Check out the page so that we can update the page layout. 
                        PublishingHelper.CheckOutFile(web, item);
        
        // Update the pageLayout reference.
                        pageLayout.Url = pageLayout.Url.Replace(matchingLayout.Replaces, matchingLayout.File);
                        item["PublishingPageLayout"] = pageLayout;
                        item.Update();
                        File file = item.File;
        
        // Get the file and other attributes so that you can check in the file.
                        clientContext.Load(file,
                            f => f.Level,
                            f => f.CheckOutType);
                        clientContext.ExecuteQuery();
        
                        PublishingHelper.CheckInPublishAndApproveFile(file);
                    }
                }
            }
        }
        

Voir aussi