Módulos no modelo de Suplemento do SharePoint

A abordagem adotada para implantar artefatos em um ambiente do SharePoint é diferente no novo modelo de suplemento do SharePoint do que era com o Código de Confiança Total. Em um cenário típico de FTC (Código de Confiança Total)/Solução de Farm, os módulos definidos em código declarativo (arquivos XML da estrutura de recursos) foram adicionados aos recursos do SharePoint. Os módulos incluíam a lista de artefatos a serem implantados no servidor do SharePoint. Os módulos foram adicionados aos recursos do SharePoint e implantados por meio das Soluções do SharePoint. Após a ativação do recurso, os artefatos definidos nos módulos foram implantados no ambiente do SharePoint.

Em um cenário de modelo de suplemento do SharePoint, o padrão de provisionamento remoto é usado para implantar artefatos em ambientes do SharePoint.

Terminologia

O termo artefatos é referido ao longo deste artigo. Artefatos referem-se a itens que normalmente são implantados em um ambiente do SharePoint. Os artefatos normalmente incluem:

Arquivos JavaScript
Arquivos CSS
Arquivos de imagem (.jpg, .gif, .png etc.)
Páginas Mestras
Layouts de Página
Itens da Lista

Diretrizes de alto nível

Como regra geral, gostaríamos de fornecer as seguintes diretrizes de alto nível para implantar artefatos em ambientes do SharePoint.

Use o padrão de provisionamento remoto (Modelo de Objeto do Lado do Cliente do SharePoint e API REST do SharePoint) para implantar artefatos em ambientes do SharePoint.
Não use módulos de código declarativo ou arquivos XML de estrutura de recursos para implantar artefatos em ambientes do SharePoint.

Depuração

Uma grande vantagem de usar código para implantar artefatos é que você pode depurar o processo de implantação ao usar código. É impossível depurar o processo de implantação ao usar módulos de código declarativo ou arquivos XML de estrutura de recursos para implantar artefatos em ambientes do SharePoint.

Introdução

Os exemplos de código PnP do Microsoft 365 a seguir demonstram como criar suplementos do SharePoint que usam o padrão de provisionamento remoto para implantar artefatos em um ambiente do SharePoint.

Este exemplo demonstra como criar novas pastas na Biblioteca de Estilos e adicionar arquivos JavaScript e imagens aos novos arquivos.

Branding.ClientSideRendering (exemplo de código PnP do Microsoft 365)
- Consulte os métodos UploadJSFiles e UploadFileToFolder na classe Default.aspx.cs para obter mais detalhes.
- Esses métodos também são exibidos abaixo para referência rápida.

Criar uma pasta e carregar arquivos JavaScript para a pasta

void UploadJSFiles(Web web)
{
  //Delete the folder if it exists
  Microsoft.SharePoint.Client.List list = web.Lists.GetByTitle("Style Library");
  IEnumerable<Folder> results = web.Context.LoadQuery<Folder>(list.RootFolder.Folders.Where(folder => folder.Name == "JSLink-Samples"));
  web.Context.ExecuteQuery();
  Folder samplesJSfolder = results.FirstOrDefault();

  if (samplesJSfolder != null)
  {
      samplesJSfolder.DeleteObject();
      web.Context.ExecuteQuery();
  }

  //Create new folder
  samplesJSfolder = list.RootFolder.Folders.Add("JSLink-Samples");
  web.Context.Load(samplesJSfolder);
  web.Context.ExecuteQuery();

  //Upload JavaScript files to folder
  UploadFileToFolder(web, Server.MapPath("../Scripts/JSLink-Samples/Accordion.js"), samplesJSfolder);
  UploadFileToFolder(web, Server.MapPath("../Scripts/JSLink-Samples/ConfidentialDocuments.js"), samplesJSfolder);
  UploadFileToFolder(web, Server.MapPath("../Scripts/JSLink-Samples/DisableInput.js"), samplesJSfolder);
  UploadFileToFolder(web, Server.MapPath("../Scripts/JSLink-Samples/HiddenField.js"), samplesJSfolder);
  UploadFileToFolder(web, Server.MapPath("../Scripts/JSLink-Samples/PercentComplete.js"), samplesJSfolder);
  UploadFileToFolder(web, Server.MapPath("../Scripts/JSLink-Samples/PriorityColor.js"), samplesJSfolder);
  UploadFileToFolder(web, Server.MapPath("../Scripts/JSLink-Samples/ReadOnlySPControls.js"), samplesJSfolder);
  UploadFileToFolder(web, Server.MapPath("../Scripts/JSLink-Samples/RegexValidator.js"), samplesJSfolder);
  UploadFileToFolder(web, Server.MapPath("../Scripts/JSLink-Samples/SubstringLongText.js"), samplesJSfolder);
  UploadFileToFolder(web, Server.MapPath("../Scripts/JSLink-Samples/DependentFields.js"), samplesJSfolder);

  //Create another folder inside the folder that was just created
  Folder imgsFolder = samplesJSfolder.Folders.Add("imgs");
  web.Context.Load(imgsFolder);
  web.Context.ExecuteQuery();

  //Upload image files to folder
  UploadFileToFolder(web, Server.MapPath("../Scripts/JSLink-Samples/imgs/Confidential.png"), imgsFolder);
}

Criar uma pasta e carregar arquivos de imagem para a pasta

public static void UploadFileToFolder(Web web, string filePath, Folder folder)
{
  //Create a FileStream to the file to upload
  using (FileStream fs = new FileStream(filePath, FileMode.Open))
  {
    //Create FileCreationInformation object to set file metadata
    FileCreationInformation flciNewFile = new FileCreationInformation();

    flciNewFile.ContentStream = fs;
    flciNewFile.Url = System.IO.Path.GetFileName(filePath);
    flciNewFile.Overwrite = true;

    //Upload file to SharePoint
    Microsoft.SharePoint.Client.File uploadFile = folder.Files.Add(flciNewFile);

    //Check in the file
    uploadFile.CheckIn("CSR sample js file", CheckinType.MajorCheckIn);

    folder.Context.Load(uploadFile);
    folder.Context.ExecuteQuery();
  }
}

Este exemplo demonstra como carregar masters pages, definir metadados de master page e aplicar a master page ao site definindo a CustomMasterUrl propriedade no objeto Web.

Branding.ApplyBranding (exemplo de código PnP do Microsoft 365)
- Consulte os métodos UploadPageLayout, CreatePublishingPage e SetSupportCaseContent na classe BrandingHelper.cs para obter mais detalhes.
- Além de criar novos itens no SharePoint, este exemplo demonstra como remover itens. Os métodos que removem itens estão listados abaixo para referência.

Excluir um arquivo

private static void DeleteFile(Web web, string fileName, string serverPath, string serverFolder)
{
  var fileUrl = string.Concat(serverPath, serverFolder, (string.IsNullOrEmpty(serverFolder) ? string.Empty : "/"), fileName);
  var fileToDelete = web.GetFileByServerRelativeUrl(fileUrl);
  fileToDelete.DeleteObject();
  web.Context.ExecuteQuery();
}

Excluir uma pasta

public static void RemoveFolder(ClientContext clientContext, string folder, string path)
{
  var web = clientContext.Web;
  var filePath = web.ServerRelativeUrl.TrimEnd(Program.trimChars) + "/" + path + "/";
  var folderToDelete = web.GetFolderByServerRelativeUrl(string.Concat(filePath, folder));
  Console.WriteLine("Removing folder {0} from {1}", folder, path);
  folderToDelete.DeleteObject();
  clientContext.ExecuteQuery();
}

Cancelar a atribuição de uma master page e excluir a master page

public static void RemoveMasterPage(ClientContext clientContext, string name, string folder)
{
  var web = clientContext.Web;
  clientContext.Load(web, w => w.AllProperties);
  clientContext.ExecuteQuery();

  Console.WriteLine("Deactivating and removing {0} from {1}", name, web.ServerRelativeUrl);

  //set master pages back to the defaults that were being used
  if (web.AllProperties.FieldValues.ContainsKey("OriginalMasterUrl"))
  {
    web.MasterUrl = (string)web.AllProperties["OriginalMasterUrl"];
  }
  if (web.AllProperties.FieldValues.ContainsKey("CustomMasterUrl"))
  {
    web.CustomMasterUrl = (string)web.AllProperties["CustomMasterUrl"];
  }
  web.Update();
  clientContext.ExecuteQuery();

  //now that the master page is set back to its default, re-reference the web from context and delete the custom master pages
  web = clientContext.Web;
  var lists = web.Lists;
  var gallery = web.GetCatalog(116);
  clientContext.Load(lists, l => l.Include(ll => ll.DefaultViewUrl));
  clientContext.Load(gallery, g => g.RootFolder.ServerRelativeUrl);
  clientContext.ExecuteQuery();
  var masterPath = gallery.RootFolder.ServerRelativeUrl.TrimEnd(new char[] { '/' }) + "/";
  DeleteFile(web, name, masterPath, folder);
}

Excluir um layout de página

public static void RemovePageLayout(ClientContext clientContext, string name, string folder)
{
  var web = clientContext.Web;
  var lists = web.Lists;
  var gallery = web.GetCatalog(116);
  clientContext.Load(lists, l => l.Include(ll => ll.DefaultViewUrl));
  clientContext.Load(gallery, g => g.RootFolder.ServerRelativeUrl);
  clientContext.ExecuteQuery();

  Console.WriteLine("Removing page layout {0} from {1}", name, clientContext.Web.ServerRelativeUrl);

  var masterPath = gallery.RootFolder.ServerRelativeUrl.TrimEnd(Program.trimChars) + "/";

  DeleteFile(web, name, masterPath, folder);
}

Este exemplo tem um pouco de tudo. Ele demonstra como ativar os recursos de publicação, carregar layouts de página, criar páginas de publicação, criar listas, tipos de conteúdo e itens de lista, além de criar páginas de publicação e adicionar Web Parts e Partes de Suplemento às páginas. Ele também demonstra como implantar itens de lista no host da Web e no suplemento da Web.

Branding.ClientSideRendering (exemplo de código PnP do Microsoft 365)
- Consulte os métodos na classe Utils.cs para obter exemplos dessas operações.
- Esses métodos estão listados abaixo para referência.

Ativar recursos de publicação de conjunto de sites e nível de site

public static void ActivePublishingFeature(ClientContext ctx)
{
  Guid publishingSiteFeatureId = new Guid("f6924d36-2fa8-4f0b-b16d-06b7250180fa");
  Guid publishingWebFeatureId = new Guid("94c94ca6-b32f-4da9-a9e3-1f3d343d7ecb");

  Site clientSite = ctx.Site;
  ctx.Load(clientSite);

  FeatureCollection clientSiteFeatures = clientSite.Features;
  ctx.Load(clientSiteFeatures);

  //Activate the site feature
  clientSiteFeatures.Add(publishingSiteFeatureId, true, FeatureDefinitionScope.Farm);
  ctx.ExecuteQuery();

  FeatureCollection clientWebFeatures = ctx.Web.Features;
  ctx.Load(clientWebFeatures);

  //Activate the web feature
  clientWebFeatures.Add(publishingWebFeatureId, true, FeatureDefinitionScope.Farm);
  ctx.ExecuteQuery();
}

Criar uma lista

public static List CreateList(ClientContext ctx,
                              int templateType,
                              string title,
                              string url,
                              QuickLaunchOptions quickLaunchOptions)
{
  ListCreationInformation listCreationInfo = new ListCreationInformation
  {
    TemplateType = templateType,
    Title = title,
    Url = url,
    QuickLaunchOption = quickLaunchOptions
  };
  List spList = ctx.Web.Lists.Add(listCreationInfo);
  ctx.Load(spList);
  ctx.ExecuteQuery();

  return spList;
}

Criar um tipo de conteúdo

public static ContentType CreateContentType(ClientContext ctx, string ctyName, string group, string ctyId)
{
  ContentTypeCreationInformation contentTypeCreation = new ContentTypeCreationInformation();
  contentTypeCreation.Name = ctyName;
  contentTypeCreation.Description = "Custom Content Type";
  contentTypeCreation.Group = group;
  contentTypeCreation.Id = ctyId;

  //Add the new content type to the collection
  ContentType ct = ctx.Web.ContentTypes.Add(contentTypeCreation);
  ctx.Load(ct);
  ctx.ExecuteQuery();

  return ct;
}

Carregar um layout de página

public static void UploadPageLayout(ClientContext ctx, string sourcePath, string targetListTitle, string targetUrl)
{
  using (FileStream fs = new FileStream(sourcePath, FileMode.Open, FileAccess.Read))
  {
    byte[] data = new byte[fs.Length];
    fs.Read(data, 0, data.Length);
    using (MemoryStream ms = new MemoryStream())
    {
      ms.Write(data, 0, data.Length);
      var newfile = new FileCreationInformation();
      newfile.Content = ms.ToArray();
      newfile.Url = targetUrl;
      newfile.Overwrite = true;

      List docs = ctx.Web.Lists.GetByTitle(targetListTitle);
      Microsoft.SharePoint.Client.File uploadedFile = docs.RootFolder.Files.Add(newfile);
      uploadedFile.CheckOut();
      uploadedFile.CheckIn("Data storage model", CheckinType.MajorCheckIn);
      uploadedFile.Publish("Data storage model layout.");

      ctx.Load(uploadedFile);
      ctx.ExecuteQuery();
    }
  }
}

Criar uma página de publicação e definir seu layout

public static void CreatePublishingPage(ClientContext clientContext, string pageName, string pagelayoutname, string url, string queryurl)
{
    var publishingPageName = pageName + ".aspx";

    Web web = clientContext.Web;
    clientContext.Load(web);

    List pages = web.Lists.GetByTitle("Pages");
    clientContext.Load(pages.RootFolder, f => f.ServerRelativeUrl);
    clientContext.ExecuteQuery();

    Microsoft.SharePoint.Client.File file =
        web.GetFileByServerRelativeUrl(pages.RootFolder.ServerRelativeUrl + "/" + pageName + ".aspx");
    clientContext.Load(file, f => f.Exists);
    clientContext.ExecuteQuery();
    if(file.Exists)
    {
      file.DeleteObject();
      clientContext.ExecuteQuery();
    }
    PublishingWeb publishingWeb = PublishingWeb.GetPublishingWeb(clientContext, web);
    clientContext.Load(publishingWeb);

    if (publishingWeb != null)
    {
      List publishingLayouts = clientContext.Site.RootWeb.Lists.GetByTitle("Master Page Gallery");

      ListItemCollection allItems = publishingLayouts.GetItems(CamlQuery.CreateAllItemsQuery());
      clientContext.Load(allItems, items => items.Include(item => item.DisplayName).Where(obj => obj.DisplayName == pagelayoutname));
      clientContext.ExecuteQuery();

      ListItem layout = allItems.Where(x => x.DisplayName == pagelayoutname).FirstOrDefault();
      clientContext.Load(layout);

      PublishingPageInformation publishingpageInfo = new PublishingPageInformation()
      {
        Name = publishingPageName,
        PageLayoutListItem = layout,
      };

      PublishingPage publishingPage = publishingWeb.AddPublishingPage(publishingpageInfo);
      publishingPage.ListItem.File.CheckIn(string.Empty, CheckinType.MajorCheckIn);
      publishingPage.ListItem.File.Publish(string.Empty);
      clientContext.ExecuteQuery();
    }
    SetSupportCaseContent(clientContext, "SupportCasesPage", url, queryurl);
}

Criar itens da lista

public static void AddDemoDataToSupportCasesList(ClientContext ctx, List list, string title,
                                                    string status, string csr, string customerID)
{
  ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation();
  ListItem newItem = list.AddItem(itemCreateInfo);
  newItem["Title"] = title;
  newItem["FTCAM_Status"] = status;
  newItem["FTCAM_CSR"] = csr;
  newItem["FTCAM_CustomerID"] = customerID;
  newItem.Update();
  ctx.ExecuteQuery();
}

Provisionar conteúdo em uma página de publicação (Web Part de Conteúdo por Pesquisa, Web Part do Editor de Scripts, Parte de Suplemento) e publicar a página

public static void SetSupportCaseContent(ClientContext ctx, string pageName, string url, string queryurl)
{
  List pages = ctx.Web.Lists.GetByTitle("Pages");
  ctx.Load(pages.RootFolder, f => f.ServerRelativeUrl);
  ctx.ExecuteQuery();

  Microsoft.SharePoint.Client.File file =
      ctx.Web.GetFileByServerRelativeUrl(pages.RootFolder.ServerRelativeUrl + "/" + pageName + ".aspx");
  ctx.Load(file);
  ctx.ExecuteQuery();

  file.CheckOut();

  LimitedWebPartManager limitedWebPartManager = file.GetLimitedWebPartManager(PersonalizationScope.Shared);

  string quicklaunchmenuFormat =
      @"<div><a href='{0}/{1}'>Sample Home Page</a></div>
      <br />
      <div style='font-weight:bold'>CSR Dashboard</div>
      <div class='cdsm_mainmenu'>
          <ul>
              <li><a href='{0}/CSRInfo/{1}'>My CSR Info</a></li>
              <li><a href='{0}/CallQueue/{1}'>Call Queue</a></li>
              <li>
                  <span class='collapse_arrow'></span>
                  <span><a href='{0}/CustomerDashboard/{1}'>Customer Dashboard</a></span>
                  <ul>
                      <li><a href='{0}/CustomerDashboard/Orders{1}'>Recent Orders</a></li>
                      <li><a class='current' href='#'>Support Cases</a></li>
                      <li><a href='{0}/CustomerDashboard/Notes{1}'>Notes</a></li>
                  </ul>
              </li>
          </ul>
      </div>
      <div class='cdsm_submenu'>
      </div>";

  string quicklaunchmenu = string.Format(quicklaunchmenuFormat, url, queryurl);

  string qlwebPartXml = "<?xml version=\"1.0\" encoding=\"utf-8\"?><webParts><webPart xmlns=\"http://schemas.microsoft.com/WebPart/v3\"><metaData><type name=\"Microsoft.SharePoint.WebPartPages.ScriptEditorWebPart, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c\" /><importErrorMessage>Cannot import this web part.</importErrorMessage></metaData><data><properties><property name=\"Content\" type=\"string\"><![CDATA[" + quicklaunchmenu + "]]></property><property name=\"ChromeType\" type=\"chrometype\">None</property></properties></data></webPart></webParts>";
  WebPartDefinition qlWpd = limitedWebPartManager.ImportWebPart(qlwebPartXml);
  WebPartDefinition qlWpdNew = limitedWebPartManager.AddWebPart(qlWpd.WebPart, "SupportCasesZoneLeft", 0);
  ctx.Load(qlWpdNew);

  //Customer Dropdown List Script web part
  string dpwebPartXml = System.IO.File.ReadAllText(System.Web.Hosting.HostingEnvironment.ApplicationPhysicalPath + "Assets/CustomerDropDownlist.webpart");
  WebPartDefinition dpWpd = limitedWebPartManager.ImportWebPart(dpwebPartXml);
  WebPartDefinition dpWpdNew = limitedWebPartManager.AddWebPart(dpWpd.WebPart, "SupportCasesZoneTop", 0);
  ctx.Load(dpWpdNew);

  //Support Case CBS Info web part
  string cbsInfoWebPartXml = System.IO.File.ReadAllText(System.Web.Hosting.HostingEnvironment.ApplicationPhysicalPath + "Assets/SupportCaseCBSWebPartInfo.webpart");
  WebPartDefinition cbsInfoWpd = limitedWebPartManager.ImportWebPart(cbsInfoWebPartXml);
  WebPartDefinition cbsInfoWpdNew = limitedWebPartManager.AddWebPart(cbsInfoWpd.WebPart, "SupportCasesZoneMiddle", 0);
  ctx.Load(cbsInfoWpdNew);

  //Support Case Content By Search web part
  string cbswebPartXml = System.IO.File.ReadAllText(System.Web.Hosting.HostingEnvironment.ApplicationPhysicalPath + "Assets/SupportCase CBS Webpart/SupportCaseCBS.webpart");
  WebPartDefinition cbsWpd = limitedWebPartManager.ImportWebPart(cbswebPartXml);
  WebPartDefinition cbsWpdNew = limitedWebPartManager.AddWebPart(cbsWpd.WebPart, "SupportCasesZoneMiddle", 1);
  ctx.Load(cbsWpdNew);

  //Support Cases App Part
  string appPartXml = System.IO.File.ReadAllText(System.Web.Hosting.HostingEnvironment.ApplicationPhysicalPath + "Assets/SupportCaseAppPart.webpart");
  WebPartDefinition appPartWpd = limitedWebPartManager.ImportWebPart(appPartXml);
  WebPartDefinition appPartdNew = limitedWebPartManager.AddWebPart(appPartWpd.WebPart, "SupportCasesZoneBottom", 0);
  ctx.Load(appPartdNew);

  //Get Host Web Query String and show support case list web part
  string querywebPartXml = System.IO.File.ReadAllText(System.Web.Hosting.HostingEnvironment.ApplicationPhysicalPath + "Assets/GetHostWebQueryStringAndShowList.webpart");
  WebPartDefinition queryWpd = limitedWebPartManager.ImportWebPart(querywebPartXml);
  WebPartDefinition queryWpdNew = limitedWebPartManager.AddWebPart(queryWpd.WebPart, "SupportCasesZoneBottom", 1);
  ctx.Load(queryWpdNew);


  file.CheckIn("Data storage model", CheckinType.MajorCheckIn);
  file.Publish("Data storage model");
  ctx.Load(file);
  ctx.ExecuteQuery();
}

Consulte e FillHostWebSupportCasesToThreshold os FillAppWebNotesListToThreshold métodos na classe SharePointService.cs para obter mais detalhes sobre como implantar itens de lista no host da Web e no suplemento da Web.

Importante

As mesmas abordagens da Web de Host e Suplemento demonstradas neste exemplo podem ser aplicadas a qualquer tipo de artefato para implantá-los no local apropriado.

Adicionar itens de lista a uma lista no host da Web

public string FillHostWebSupportCasesToThreshold()
{
  using (var clientContext = SharePointContext.CreateUserClientContextForSPHost())
  {
    List supportCasesList = clientContext.Web.Lists.GetByTitle("Support Cases");
    ListItemCreationInformation itemCreateInfo = new ListItemCreationInformation();
    for (int i = 0; i < 500; i++)
    {
      ListItem newItem = supportCasesList.AddItem(itemCreateInfo);
      newItem["Title"] = "Wrong product received." + i.ToString();
      newItem["FTCAM_Status"] = "Open";
      newItem["FTCAM_CSR"] = "bjones";
      newItem["FTCAM_CustomerID"] = "thresholds test";
      newItem.Update();
      if (i % 100 == 0)
        clientContext.ExecuteQuery();
    }
    clientContext.ExecuteQuery();


    clientContext.Load(supportCasesList, l => l.ItemCount);
    clientContext.ExecuteQuery();

    if(supportCasesList.ItemCount>=5000)
      return "The Host Web Support Cases List has " + supportCasesList.ItemCount + " items, and exceeds the threshold.";
    else
      return 500 + " items have been added to the Host Web Support Cases List. " +
        "There are " + (5000 - supportCasesList.ItemCount) + " items left to add.";
  }
}

Adicionar itens de lista a uma lista no site do suplemento

public string FillAppWebNotesListToThreshold()
{
  using (var clientContext = SharePointContext.CreateUserClientContextForSPAppWeb())
  {
    List notesList = clientContext.Web.Lists.GetByTitle("Notes");

    var itemCreateInfo = new ListItemCreationInformation();
    for (int i = 0; i < 500; i++)
    {
      ListIgit pushientContext.ExecuteQuery();
    }
    clientContext.ExecuteQuery();

    clientContext.Load(notesList, l => l.ItemCount);
    clientContext.ExecuteQuery();

    if (notesList.ItemCount >= 5000)
      return "The Add-in Web Notes List has " + notesList.ItemCount + " items, and exceeds the threshold.";
    else
      return 500 + " items have been added to the Add-in Web Notes List. " +
                        "There are " + (5000-notesList.ItemCount) + " items left to add.";
  }
}

Páginas mestras (receita de suplemento do SharePoint)
Artigos de orientação em https://aka.ms/OfficeDevPnPGuidance
Referências no MSDN em https://aka.ms/OfficeDevPnPMSDN
Vídeos em https://aka.ms/OfficeDevPnPVideos

Exemplos de PnP

Aplicável a

Microsoft 365 Multilocatário (MT)
Microsoft 365 Dedicado (D) parcialmente
SharePoint 2013 local, parcialmente

Os padrões para dedicados e locais são idênticos às técnicas de modelo do suplemento do SharePoint, mas há diferenças nas possíveis tecnologias que podem ser usadas.

Last updated on 2026-08-24