Merge pull request #985 from pkbullock/dev

added documentation for polyglots
pnp · Feb 19, 2024 · 2f4c58e · 2f4c58e
2 parents 47e818e + 449468f
commit 2f4c58e
Show file tree

Hide file tree

Showing 8 changed files with 83 additions and 66 deletions.
diff --git a/docs/includes/overview-polyglots.md b/docs/includes/overview-polyglots.md
@@ -0,0 +1 @@
+The simplest way to get to the notebooks, is to navigate to the GitHub repository, the following notebooks are available, to use these, you will need to *clone the repository* and open the notebooks and run within Visual Studio Code. To setup the notebooks, please see [Setting up to run the Polyglot Notebooks](../using-the-framework/setting-up-to-use-polyglot-samples.md)
diff --git a/docs/notebooks/Getting-Started-with-PnP-Framework.ipynb b/docs/notebooks/Getting-Started-with-PnP-Framework.ipynb
@@ -57,6 +57,9 @@
     "var certPath = config[\"certificatePath\"];\n",
     "var tenantName = config[\"azureTenantName\"];\n",
     "\n",
+    "// SharePoint Online Site URL\n",
+    "var siteUrl = config[\"siteUrl\"];\n",
+    "\n",
     "// To setup an Azure AD app, please visit XXX"
    ]
   },
@@ -73,9 +76,6 @@
    },
    "outputs": [],
    "source": [
-    "// SharePoint Online Site URL\n",
-    "string siteUrl = \"https://contoso.sharepoint.com/sites/pnpcoresdktest\";\n",
-    "\n",
     "var authManager = new AuthenticationManager(appId, certPath, certPassword, tenantName);\n",
     "using (var clientContext = authManager.GetContext(siteUrl))\n",
     "{\n",

diff --git a/docs/notebooks/Getting-Started-with-PnP-Provisioning.ipynb b/docs/notebooks/Getting-Started-with-PnP-Provisioning.ipynb
@@ -11,7 +11,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 2,
    "metadata": {
     "dotnet_interactive": {
      "language": "csharp"
@@ -20,7 +20,17 @@
      "kernelName": "csharp"
     }
    },
-   "outputs": [],
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "<div><div></div><div></div><div><strong>Installed Packages</strong><ul><li><span>Microsoft.Extensions.Configuration, 7.0.0</span></li><li><span>Microsoft.Extensions.Configuration.Json, 7.0.0</span></li><li><span>Microsoft.SharePointOnline.CSOM, 16.1.23814.12000</span></li><li><span>PnP.Framework, 1.13.0</span></li></ul></div></div>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
    "source": [
     "#r \"nuget: Microsoft.SharePointOnline.CSOM, 16.1.23814.12000\"\n",
     "#r \"nuget: PnP.Framework, 1.13.0\"\n",
@@ -31,6 +41,7 @@
     "using Microsoft.Extensions.Configuration.Json;\n",
     "using Microsoft.SharePoint.Client;\n",
     "using PnP.Framework;\n",
+    "using PnP.Framework.Provisioning.Model;\n",
     "using PnP.Framework.Provisioning.Providers;\n",
     "using PnP.Framework.Provisioning.Providers.Xml;\n",
     "using PnP.Framework.Provisioning.ObjectHandlers;\n",
@@ -42,7 +53,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 9,
    "metadata": {
     "dotnet_interactive": {
      "language": "csharp"
@@ -55,13 +66,16 @@
    "source": [
     "// Credentials\n",
     "var config = new ConfigurationBuilder()\n",
-    "    .AddJsonFile(Path.Combine(File.Directory.GetCurrentDirectory(),\"appsettings.json\"))\n",
+    "    .AddJsonFile(File.Path.Combine(File.Directory.GetCurrentDirectory(),\"appsettings.json\"))\n",
     "    .Build();\n",
     "var appId = config[\"azureAppId\"];\n",
     "\n",
     "var certPassword = config[\"certificatePassword\"];\n",
     "var certPath = config[\"certificatePath\"];\n",
-    "var tenantName = config[\"azureTenantName\"];"
+    "var tenantName = config[\"azureTenantName\"];\n",
+    "\n",
+    "// SharePoint Online Site URL\n",
+    "var siteUrl = config[\"siteUrl\"];"
    ]
   },
   {
@@ -85,8 +99,6 @@
    },
    "outputs": [],
    "source": [
-    "// SharePoint Online Site URL\n",
-    "string siteUrl = \"https://capadevtest.sharepoint.com/sites/pnpcoresdktest\";\n",
     "string path = \"pnpframework-sample-template.xml\";\n",
     "\n",
     "var authManager = new AuthenticationManager(appId, certPath, certPassword, tenantName);\n",
@@ -101,22 +113,19 @@
     "    // Output the template as XML to the file System\n",
     "    XMLTemplateProvider provider = new XMLFileSystemTemplateProvider(\".\",\"\");\n",
     "    provider.SaveAs(template,path);\n",
-    "\n",
     "}\n"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Example creating a template in memory and applying a template to a SharePoint Site\n",
-    "\n",
-    "Note: Sample not yet operational, work in progress..."
+    "## Example creating a template in memory and applying a template to a SharePoint Site"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 8,
    "metadata": {
     "dotnet_interactive": {
      "language": "csharp"
@@ -127,9 +136,6 @@
    },
    "outputs": [],
    "source": [
-    "// SharePoint Online Site URL\n",
-    "string siteUrl = \"https://capadevtest.sharepoint.com/sites/pnpcoresdktest\";\n",
-    "\n",
     "var authManager = new AuthenticationManager(appId, certPath, certPassword, tenantName);\n",
     "using (var clientContext = authManager.GetContext(siteUrl))\n",
     "{\n",
@@ -140,23 +146,28 @@
     "    template.Scope = Model.ProvisioningTemplateScope.RootSite;\n",
     "    template.BaseSiteTemplate = \"SITEPAGEPUBLISHING#0\";\n",
     "\n",
-    "    template.SiteFields.Add(new Model.Field() { SchemaXml = \"<Field Type='Text' DisplayName='Example Field' Name='ExampleField' />\" });\n",
-    "    template.ContentTypes.Add(new Model.ContentType() { Id = \"0x0101001234567890\", Name = \"Example Content Type\", Group = \"Provisioned Group\" });\n",
-    "    template.Lists.Add(new ListInstance() { Title = \"Example List\", TemplateType = 100, Url = \"Lists/ExampleList\", ContentTypesEnabled = true });\n",
+    "    var listInstance = new ListInstance() { Title = \"Example List\", \n",
+    "                                            TemplateType = 100,  // Document Library 101\n",
+    "                                            Url = \"Lists/ExampleList\", \n",
+    "                                            ContentTypesEnabled = true,\n",
+    "                                            FieldRefs = { new FieldRef(\"Title\") },\n",
+    "                                            EnableVersioning = true,\n",
+    "                                            MaxVersionLimit = 250,\n",
+    "                                            OnQuickLaunch = true\n",
+    "    };\n",
+    "        \n",
+    "    template.Lists.Add(listInstance);\n",
     "    \n",
-    "    // Serialize the site template to an XML file\n",
+    "    // Optionally - Serialize the site template to an XML file and save it to the file system\n",
     "    string templateFileName = \"ExampleTemplatePnPFramework.xml\";\n",
     "    XMLTemplateProvider provider = new XMLFileSystemTemplateProvider(\".\", \"\");\n",
     "    provider.SaveAs(template, templateFileName);\n",
     "\n",
-    "    \n",
-    "\n",
+    "    // Apply the template to the target site\n",
     "    var applyingInformation = new ProvisioningTemplateApplyingInformation();\n",
-    "    applyingInformation.HandlersToProcess = Handlers.All;\n",
-    "    \n",
+    "        \n",
     "    clientContext.Web.ApplyProvisioningTemplate(template, applyingInformation);\n",
     "   \n",
-    "\n",
     "    // Delete the XML file\n",
     "    System.IO.File.Delete(templateFileName);\n",
     "};\n"

diff --git a/docs/notebooks/appsettings.sample.json b/docs/notebooks/appsettings.sample.json
@@ -2,5 +2,6 @@
     "azureAppId":"<app-id>",
     "certificatePassword":"<cert-password>",
     "certificatePath":"C:\\temp\\PolyGlot\\pnpframework-polyglot.pfx",
-    "azureTenantName":"contoso.onmicrosoft.com"
+    "azureTenantName":"contoso.onmicrosoft.com",
+    "siteUrl": "https://contoso.sharepoint.com/sites/pnpframeworktest"
 }
diff --git a/docs/using-the-framework/pnp-provisioning/getting-started.md b/docs/using-the-framework/pnp-provisioning/getting-started.md
@@ -20,27 +20,9 @@ The PnP Provisioning templates are based on an XML schema that captures the stru
 
 The PolyGlot samples provide working examples of how to interact with SharePoint, that can be ran against your Microsoft 365 tenant, written in C#.
 
-### Settings File
-
-To keep credentials away from the PolyGlot Notebooks, we have setup a seperate file to contain these, copy the `appsettings.sample.json` file to `appsettings.json` and update the values to match your environment.
-
-```json
-{
-    "azureAppId":"<app-id>",
-    "certificatePassword":"<cert-password>",
-    "certificatePath":"C:\\temp\\PolyGlot\\pnpframework-polyglot.pfx",
-    "azureTenantName":"contoso.onmicrosoft.com"
-}
-
-```
-
-You will need to create an Azure AD App Registration and generate a certificate, assign permissions to SharePoint within the app. For these notebooks, we have kept access to this for the time being.
-
-*There is more coming on how to do this.*
-
 ## Samples available
 
-The simplest way to get to the notebooks, is to navigate to the GitHub repository, the following notebooks are available, to use these, you will need to *clone the repository* and open the notebooks in Visual Studio Code, using the [Extension - PolyGlot Notebooks by Microsoft](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-vscode).
+[!INCLUDE [DISCLAIMER](../../includes/overview-polyglots.md)]
 
 Examples:
 

diff --git a/docs/using-the-framework/setting-up-to-use-polyglot-samples.md b/docs/using-the-framework/setting-up-to-use-polyglot-samples.md
@@ -0,0 +1,37 @@
+# Setting up to run the Polyglot Notebooks
+
+The Polyglot Notebooks are a great way to get started with the PnP Framework, with runnable samples and you can adjust the code and explore the framework. There are a few things you need to do to get started.
+
+## Prerequisites
+
+- [Visual Studio Code](https://code.visualstudio.com/)
+- [Install .Net 7 SDK](https://dotnet.microsoft.com/en-us/download)
+- [.NET Interactive Notebooks Extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-vscode)
+
+## Configuring the Notebooks for your tenant
+
+The Polyglot Notebooks are designed to be run against your tenant, but you will need to configure these settings file to do this.
+
+### Settings File
+
+To keep credentials away from the PolyGlot Notebooks, we have setup a seperate file to contain these, copy the `appsettings.sample.json` file to `appsettings.json` and update the values to match your environment.
+
+```json
+{
+    "azureAppId":"<app-id>",
+    "certificatePassword":"<cert-password>",
+    "certificatePath":"C:\\temp\\PolyGlot\\pnpframework-polyglot.pfx",
+    "azureTenantName":"contoso.onmicrosoft.com",
+    "siteUrl" : "https://contoso.sharepoint.com/sites/contoso"
+}
+
+```
+
+You will need to create an Azure AD App Registration and generate a certificate, assign permissions to SharePoint within the app. For these notebooks, we have kept access to this for the time being.
+
+
+*There is more coming on how to do this.*
+
+## Running the Notebooks
+
+...
diff --git a/docs/using-the-framework/toc.yml b/docs/using-the-framework/toc.yml
@@ -1,6 +1,9 @@
 - name: Getting started
   href: readme.md
 
+- name: Setting up PolyGlot Notebooks
+  href: setting-up-to-use-polyglot-samples.md
+
 - name: "PnP Provisioning"
   href: pnp-provisioning/getting-started.md
 

diff --git a/docs/using-the-framework/working-with-sharepoint/getting-started.md b/docs/using-the-framework/working-with-sharepoint/getting-started.md
@@ -6,27 +6,9 @@ The following samples show how to work with Microsoft SharePoint using the PnP F
 
 The PolyGlot samples provide working examples of how to interact with SharePoint, that can be ran against your Microsoft 365 tenant, written in C#.
 
-### Settings File
-
-To keep credentials away from the PolyGlot Notebooks, we have setup a seperate file to contain these, copy the `appsettings.sample.json` file to `appsettings.json` and update the values to match your environment.
-
-```json
-{
-    "azureAppId":"<app-id>",
-    "certificatePassword":"<cert-password>",
-    "certificatePath":"C:\\temp\\PolyGlot\\pnpframework-polyglot.pfx",
-    "azureTenantName":"contoso.onmicrosoft.com"
-}
-
-```
-
-You will need to create an Azure AD App Registration and generate a certificate, assign permissions to SharePoint within the app. For these notebooks, we have kept access to this for the time being.
-
-*There is more coming on how to do this.*
-
 ## Samples available
 
-The simplest way to get to the notebooks, is to navigate to the GitHub repository, the following notebooks are available, to use these, you will need to *clone the repository* and open the notebooks in Visual Studio Code, using the [Extension - PolyGlot Notebooks by Microsoft](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-vscode).
+[!INCLUDE [DISCLAIMER](../../includes/overview-polyglots.md)]
 
 Examples:
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		The simplest way to get to the notebooks, is to navigate to the GitHub repository, the following notebooks are available, to use these, you will need to clone the repository and open the notebooks and run within Visual Studio Code. To setup the notebooks, please see [Setting up to run the Polyglot Notebooks](../using-the-framework/setting-up-to-use-polyglot-samples.md)