Remplacer les fichiers SharePoint déployés à l’aide de modules dans des solutions de batterie de serveurs
Si vous avez déployé des fichiers de manière déclarative à l’aide de modules dans des solutions de batterie de serveurs, découvrez comment les transformer en nouvelles solutions qui mettent à jour les références aux fichiers et fournissent des fonctionnalités similaires à l’aide du modèle objet client (CSOM). Auparavant, les modules étaient utilisés pour déployer des fichiers tels que des pages master et des mises en page.
Importante
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 à celles fournies par vos solutions de batterie de serveurs, mettre à jour les références aux fichiers, puis la nouvelle solution peut être déployée 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 ne décrit pas comment s’authentifier avec 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.
Remarque
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 :
- Charger et mettre à jour les références aux pages master
- Charger et mettre à jour les références aux mises en page
Utilisez ce processus de transformation dans les cas suivants :
- Vos solutions de batterie de serveurs existantes ont utilisé des modules pour déployer des fichiers.
- Vous souhaitez remplacer master pages et mises en page dans les solutions de batterie de serveurs par de nouvelles master pages et mises en page afin qu’elles puissent être migrées vers SharePoint Online.
- Vous avez défini des types de contenu de document sur master pages ou mises en page dans votre solution de batterie de serveurs de manière déclarative.
Avant de commencer
Dans l’idéal, vous devez passer en revue 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 n’êtes pas familiarisé avec les solutions de batterie de serveurs ou si vous n’avez pas de solution de batterie de serveurs existante à utiliser, il peut ê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écuter votre exemple de code, activez les fonctionnalités de publication sur la collection de sites et le site à l’aide des procédures suivantes.
Pour activer la fonctionnalité Infrastructure de publication SharePoint Server sur la collection de sites
Ouvrez votre site SharePoint et accédez à Paramètres>Paramètres du site.
Dans Administration de collection de sites, choisissez Fonctionnalités de la collection de sites.
Dans Infrastructure de publication SharePoint Server, choisissez Activer.
Pour activer la fonctionnalité de publication SharePoint Server sur le site
Ouvrez votre site SharePoint et accédez à Paramètres>Paramètres du site.
Dans Actions du site, choisissez Gérer les fonctionnalités du site.
Dans Publication SharePoint Server, choisissez Activer.
Configurer votre projet Visual Studio
Téléchargez l’exemple de projet. Choisissez Afficher brut pour commencer à télécharger l’exemple de projet, extraire les fichiers du fichier zip, puis accédez au dossier Module9/ModuleReplacement.
Ouvrez ModuleReplacement.sln.
Ouvrez settings.xml. Passez en revue et mettez à jour les attributs suivants pour répondre à vos besoins :
élément masterPage : utilise l’attribut file pour spécifier la nouvelle page master à déployer dans la galerie de pages maîtres, et l’attribut remplace pour spécifier la page master existante dans la galerie de pages maîtres.
élément pageLayout : utilise l’attribut file 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>Dans MasterPageGalleryFiles.cs, les classes MasterPageGalleryFile et LayoutFile définissent des objets métier qui stockent des informations sur les nouvelles pages master et mises en page à charger dans SharePoint.
Charger et mettre à jour les références aux pages master
Pour charger et mettre à jour les références aux nouvelles pages master sur votre site SharePoint :
Dans Program.cs, ajoutez l’instruction using suivante.
using System.Security;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;
}
Dans Program.cs, ajoutez le code suivant à la méthode Main , qui effectue les tâches suivantes :
Charge le fichier settings.xml.
Obtient une référence à la galerie de pages maîtres à l’aide de GetCatalog (116).
Les pages maîtres sont chargées dans 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, consultez ListTemplate, élément (Site) . D’autres détails sur la galerie de pages maîtres sont chargés, notamment l’utilisation de List.ContentTypes pour obtenir les types de contenu associés à la galerie de pages maîtres.
Charge les propriétés de l’objet Web, notamment Web.ContentTypes, Web.MasterUrl et Web.CustomMasterUrl.
Définit parentMasterPageContentTypeId sur l’ID de type de contenu de master pages. Pour plus d’informations, consultez Hiérarchie des types de contenu de base.
Obtient le type de contenu des pages master à 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 master 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); } }
Dans Program.cs, ajoutez la méthode UploadAndSetMasterPages , qui crée une liste d’objets métier MasterPageGalleryFile en :
Lecture de tous les éléments masterPage définis dans settings.xml.
Pour chaque élément masterPage, qui spécifie une page master à charger dans SharePoint, chargez les valeurs d’attribut dans un objet métier MasterPageGalleryFile.
Pour chaque objet métier MasterPageGalleryFile de 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); } }
Dans Program.cs, ajoutez la méthode UploadAndSetMasterPage , qui effectue les tâches suivantes :
Extrait la page master.
Charge le nouveau fichier à l’aide de FileCreationInformation.
Obtient l’élément de liste associé au fichier nouvellement chargé.
Définit différentes propriétés de l’élément de liste, notamment 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 master.
Archive, publie et approuve la nouvelle page master.
Si la page master du site actuel ou l’URL de page de master personnalisée est définie sur l’ancienne page master, met à jour Web.MasterUrl ouWeb.CustomMasterUrl pour utiliser l’URL de la page master qui vient d’être 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(); } }
Charger et mettre à jour les références aux mises en page
Remarque
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 les références pour utiliser les nouveaux fichiers de mise en page :
Mettez à jour la méthode Main avec le code suivant. Ce code contient des étapes supplémentaires pour charger et mettre à jour les références aux fichiers de mise en page, notamment :
Définition de parentPageLayoutContentTypeId sur l’ID de type de contenu de la mise en page.
Obtention d’un type de contenu qui correspond à parentPageLayoutContentTypeId à partir de la galerie de pages maîtres.
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); } }
Dans Program.cs, ajoutez la méthode UploadPageLayoutsAndUpdateReferences , qui effectue les étapes suivantes :
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 les objets métier LayoutFile et en ajoutant tous les objets métier à une liste.
Pour chaque mise en page à remplacer :
Interroge les types de contenu du site à l’aide de Web.ContentTypes pour rechercher un type de contenu correspondant où le nom du type de contenu du site est égal au 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 && (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); }
Dans Program.cs, ajoutez la méthode UploadPageLayout , qui effectue les tâches suivantes :
Extrait le fichier de mise en page.
Charge le nouveau fichier à l’aide de FileCreationInformation.
Obtient l’élément de liste associé au fichier nouvellement chargé.
Définit différentes propriétés sur l’élément de liste, notamment ContentTypeId et PublishingAssociatedContentType.
Archive, publie et approuve le nouveau fichier de mise en page.
Pour supprimer les références à l’ancien fichier de mise en page, appelle PublishingHelper.UpdateAvailablePageLayouts pour mettre à jour le code XML stocké dans la propriété PageLayouts sur le site actuel.
Si la valeur de l’attribut defaultLayout du fichier de mise en page nouvellement chargé à partir de settings.xml est définie sur true, utilise PublishingHelper.SetDefaultPageLayout pour mettre à jour le code XML stocké dans la propriété DefaultPageLayout sur le site actif.
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); } } }
Dans Program.cs, ajoutez la méthode UpdatePages , qui effectue les tâches suivantes :
Obtient la bibliothèque Pages , puis obtient tous les éléments de liste dans la bibliothèque Pages .
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 mises en page . Si le champ PublishingPageLayout de l’élément de liste doit être mis à jour pour faire référence à la nouvelle mise en page :
Extrait le fichier de l’élément de liste à l’aide de PublishingHelper.CheckOutFile.
Mises à 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.
Archive, 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); } } } }