Merge pull request #488 from OfficeDev/dev

October 2016 Release

Author: erwinvanhunen

.github/ISSUE_TEMPLATE.md

@@ -1,8 +1,8 @@
 ###Notice: many issues / bugs reported are actually related to the PnP Core Library which is used behind the scenes. Consider carefully where to report an issue:###
 
-1. Is the issue related to Apply-SPOProvisioningTemplate or Get-SPOProvisioningTemplate? Then report the issue here: https://github.com/officedev/PnP-Sites-Core/issues. Those cmdlets are merely thin wrappers around the code provided there and your issue has a greater chance of being handled correctly when you report it in that repository.
-2. Is the issue related to the cmdlet itself, its parameters, the syntax, or do you suspect it's the code of the cmdlet that is causing the issue? Then please continue reporting the issue here.
-3. If you think that the functionality might be related to the underlying libraries that the cmdlet is calling (We realize that that might be difficult to determine), please first double check the code of the cmdlet, which can be found here: https://github.com/OfficeDev/PnP-PowerShell/tree/master/Commands. If related to the cmdlet, continue reporting the issue here, otherwise report the issue at https://github.com/officedev/PnP-Sites-Core/issues
+1. **Are you using ```Apply-SPOProvisioningTemplate``` or ```Get-SPOProvisioningTemplate```**? The issue is most likely related to the Provisioning Engine. The Provisioning engine is _not_ located in the PowerShell repo. Please report the issue here: https://github.com/officedev/PnP-Sites-Core/issues.
+2. **Is the issue related to the cmdlet itself, its parameters, the syntax, or do you suspect it's the code of the cmdlet that is causing the issue?** Then please continue reporting the issue in this repo.
+3. **If you think that the functionality might be related to the underlying libraries that the cmdlet is calling** (We realize that that might be difficult to determine), please first double check the code of the cmdlet, which can be found here: https://github.com/OfficeDev/PnP-PowerShell/tree/master/Commands. If related to the cmdlet, continue reporting the issue here, otherwise report the issue at https://github.com/officedev/PnP-Sites-Core/issues
 
 ### Reporting an Issue or Missing Feature
 Please confirm what it is that your reporting
@@ -16,8 +16,16 @@ Please describe what you see instead. Please provide samples of HTML output or s
 ### Steps to reproduce behavior
 Please include complete code samples in-line or linked from [gists](https://gist.github.com/)
 
-### What version of the PnP-PowerShell Cmdlets are you using?
-Example: March PnP-PowerShell SharePoint Online (V16), December PnP-PowerShell SharePoint On-Premises (V15)
+### Which version of the PnP-PowerShell Cmdlets are you using?
+- [ ] PnP PowerShell for SharePoint 2013
+- [ ] PnP PowerShell for SharePoint 2016
+- [ ] PnP PowerShell for SharePoint Online
+
+### What is the version of the Cmdlet module you are running?
+(you can retrieve this by executing ```Get-Module -Name *pnppowershell* -ListAvailable```)
 
 ### How did you install the PnP-PowerShell Cmdlets? 
-Example: Via MSI installer, From the PowerShell Gallery, other
+- [ ] MSI Installed downloaded from GitHub
+- [ ] Installed through the PowerShell Gallery with Install-Module
+- [ ] Other means
+

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Type ##
+- [ ] Bug Fix
+- [ ] New Feature
+- [ ] Sample
+
+## Related Issues? ##
+Fixes #X, partially fixes #Y, mentioned in #Z, etc.
+
+## What is in this Pull Request ? ##
+Please describe the changes in the PR. 
+
+### Guidance ###
+* You can delete this section when you are submitting the pull request.* 
+* *Please update this PR information accordingly. We use this as part of our release notes in monthly communications.*
+* **Please target your PR to Dev branch. If you do not target the Dev branch we will not accept this PR.**

Binaries/SharePointPnPPowerShell2013.msi

@@ -10,6 +10,9 @@ namespace SharePointPnP.PowerShell.Commands.Base
     [CmdletExample(
       Code = @"PS:> Execute-SPOQuery -RetryCount 5",
       Remarks = @"This will execute any queued actions / changes on the SharePoint Client Side Object Model Context and will retry 5 times in case of throttling.", SortOrder = 1)]
+    [CmdletExample(
+      Code = @"PS:> Execute-SPOQuery -RetryWait 10",
+      Remarks = @"This will execute any queued actions / changes on the SharePoint Client Side Object Model Context and delay the execution with 10 seconds when it needs to retry the execution.", SortOrder = 2)]
 
     public class ExecuteSPOQuery : SPOCmdlet
     {

Binaries/SharePointPnPPowerShell2016.msi

@@ -11,6 +11,9 @@ namespace SharePointPnP.PowerShell.Commands.Base
     [CmdletExample(Code = "PS:> Get-SPOnlineStoredCredential -Name O365", 
         Remarks = "Returns the credential associated with the specified identifier",
         SortOrder = 1)]
+    [CmdletExample(Code = "PS:> Get-SPOnlineStoredCredential -Name testEnvironment -Type OnPrem", 
+        Remarks = "Gets the credential associated with the specified identifier from the credential manager and then will return a credential that can be used for on-premises authentication",
+        SortOrder = 2)]
     public class GetStoredCredential : PSCmdlet
     {
         [Parameter(Mandatory = true, HelpMessage = "The credential to retrieve.")]

Binaries/SharePointPnPPowerShellOnline.msi

@@ -35,7 +35,16 @@ internal static SPOnlineConnection InstantiateSPOnlineConnection(Uri url, string
                 realm = GetRealmFromTargetUrl(url);
             }
 
-            var context = PnPClientContext.ConvertFrom(authManager.GetAppOnlyAuthenticatedContext(url.ToString(), realm, clientId, clientSecret), retryCount, retryWait * 1000);
+            PnPClientContext context = null;
+            if (url.DnsSafeHost.Contains("spoppe.com"))
+            {
+                context = PnPClientContext.ConvertFrom(authManager.GetAppOnlyAuthenticatedContext(url.ToString(), realm, clientId, clientSecret, acsHostUrl: "windows-ppe.net", globalEndPointPrefix: "login"), retryCount, retryWait * 1000);
+            }
+            else
+            {
+                context = PnPClientContext.ConvertFrom(authManager.GetAppOnlyAuthenticatedContext(url.ToString(), realm, clientId, clientSecret), retryCount, retryWait * 1000);
+            }
+
             context.ApplicationName = Properties.Resources.ApplicationName;
             context.RequestTimeout = requestTimeout;
 #if !ONPREMISES

Commands/Base/ExecuteQuery.cs

@@ -10,45 +10,51 @@ namespace SharePointPnP.PowerShell.Commands.Branding
     [CmdletHelp("Adds a custom action to a web", Category = CmdletHelpCategory.Branding)]
     [CmdletExample(Code = @"$cUIExtn = ""<CommandUIExtension><CommandUIDefinitions><CommandUIDefinition Location=""""Ribbon.List.Share.Controls._children""""><Button Id=""""Ribbon.List.Share.GetItemsCountButton"""" Alt=""""Get list items count"""" Sequence=""""11"""" Command=""""Invoke_GetItemsCountButtonRequest"""" LabelText=""""Get Items Count"""" TemplateAlias=""""o1"""" Image32by32=""""_layouts/15/images/placeholder32x32.png"""" Image16by16=""""_layouts/15/images/placeholder16x16.png"""" /></CommandUIDefinition></CommandUIDefinitions><CommandUIHandlers><CommandUIHandler Command=""""Invoke_GetItemsCountButtonRequest"""" CommandAction=""""javascript: alert('Total items in this list: '+ ctx.TotalListItems);"""" EnabledScript=""""javascript: function checkEnable() { return (true);} checkEnable();""""/></CommandUIHandlers></CommandUIExtension>""
 
-Add-SPOCustomAction -Name 'GetItemsCount' -Title 'Invoke GetItemsCount Action' -Description 'Adds custom action to custom list ribbon' -Group 'Microsoft.SharePoint.Client.UserCustomAction.group' -Location 'CommandUI.Ribbon' -CommandUIExtension $cUIExtn",
+Add-SPOCustomAction -Name 'GetItemsCount' -Title 'Invoke GetItemsCount Action' -Description 'Adds custom action to custom list ribbon' -Group 'SiteActions' -Location 'CommandUI.Ribbon' -CommandUIExtension $cUIExtn",
     Remarks = @"Adds a new custom action to the custom list template, and sets the Title, Name and other fields with the specified values. On click it shows the number of items in that list. Notice: escape quotes in CommandUIExtension.",
     SortOrder = 1)]
+    [CmdletRelatedLink(
+        Text ="UserCustomAction", 
+        Url = "https://msdn.microsoft.com/en-us/library/office/microsoft.sharepoint.client.usercustomaction.aspx")]
+    [CmdletRelatedLink(
+        Text ="BasePermissions",
+        Url = "https://msdn.microsoft.com/en-us/library/office/microsoft.sharepoint.client.basepermissions.aspx")]
     public class AddCustomAction : SPOWebCmdlet
     {
-        [Parameter(Mandatory = true)]
+        [Parameter(Mandatory = true, HelpMessage = "The name of the custom action")]
         public string Name = string.Empty;
 
-        [Parameter(Mandatory = true)]
+        [Parameter(Mandatory = true, HelpMessage = "The title of the custom action")]
         public string Title = string.Empty;
 
-        [Parameter(Mandatory = true)]
+        [Parameter(Mandatory = true, HelpMessage = "The description of the custom action")]
         public string Description = string.Empty;
 
-        [Parameter(Mandatory = true)]
+        [Parameter(Mandatory = true, HelpMessage = "The group where this custom action needs to be added like 'SiteActions'")]
         public string Group = string.Empty;
 
-        [Parameter(Mandatory = true)]
+        [Parameter(Mandatory = true, HelpMessage = "The actual location where this custom action need to be added like 'CommandUI.Ribbon'")]
         public string Location = string.Empty;
 
         [Parameter(Mandatory = false, HelpMessage = "Sequence of this CustomAction being injected. Use when you have a specific sequence with which to have multiple CustomActions being added to the page.")]
         public int Sequence = 0;
 
-        [Parameter(Mandatory = false)]
+        [Parameter(Mandatory = false, HelpMessage = "The URL, URI or ECMAScript (JScript, JavaScript) function associated with the action")]
         public string Url = string.Empty;
 
-        [Parameter(Mandatory = false)]
+        [Parameter(Mandatory = false, HelpMessage = "The URL of the image associated with the custom action")]
         public string ImageUrl = string.Empty;
 
-        [Parameter(Mandatory = false)]
+        [Parameter(Mandatory = false, HelpMessage = "XML fragment that determines user interface properties of the custom action")]
         public string CommandUIExtension = string.Empty;
 
-        [Parameter(Mandatory = false)]
+        [Parameter(Mandatory = false, HelpMessage = "The identifier of the object associated with the custom action.")]
         public string RegistrationId = string.Empty;
 
-        [Parameter(Mandatory = false)]
+        [Parameter(Mandatory = false, HelpMessage = "A string array that contain the permissions needed for the custom action")]
         public PermissionKind[] Rights;
 
-        [Parameter(Mandatory = false)]
+        [Parameter(Mandatory = false, HelpMessage = "Specifies the type of object associated with the custom action")]
         public UserCustomActionRegistrationType RegistrationType;
 
         [Parameter(Mandatory = false, HelpMessage = "The scope of the CustomAction to add to. Either Web or Site; defaults to Web. 'All' is not valid for this command.")]

Commands/Base/GetStoredCredential.cs

@@ -0,0 +1,105 @@
+using OfficeDevPnP.Core.Framework.Provisioning.Connectors;
+using OfficeDevPnP.Core.Framework.Provisioning.Model;
+using OfficeDevPnP.Core.Framework.Provisioning.Providers;
+using OfficeDevPnP.Core.Framework.Provisioning.Providers.Xml;
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Management.Automation;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace SharePointPnP.PowerShell.Commands.Branding
+{
+    [Cmdlet("Add", "SPOFileToProvisioningTemplate")]
+    [CmdletHelp("Adds a file to an in-memory PnP Provisioning Template",
+        Category = CmdletHelpCategory.Branding)]
+    [CmdletExample(
+       Code = @"PS:> Add-SPOFileToProvisioningTemplate -Path template.pnp -Source $sourceFilePath -Folder $targetFolder",
+       Remarks = "Adds a file to an in-memory PnP Provisioning Template",
+       SortOrder = 1)]
+    [CmdletExample(
+       Code = @"PS:> Add-SPOFileToProvisioningTemplate -Path template.pnp -Source $sourceFilePath -Folder $targetFolder -Container $container",
+       Remarks = "Adds a file to an in-memory PnP Provisioning Template with a custom container for the file",
+       SortOrder = 2)]
+    public class AddFileToProvisioningTemplate : PSCmdlet
+    {
+        [Parameter(Mandatory = true, Position = 0, HelpMessage = "Filename of the .PNP Open XML provisioning template to read from, optionally including full path.")]
+        public string Path;
+
+        [Parameter(Mandatory = true, Position = 1, HelpMessage = "The file to add to the in-memory template, optionally including full path.")]
+        public string Source;
+
+        [Parameter(Mandatory = true, Position = 2, HelpMessage = "The target Folder for the file to add to the in-memory template.")]
+        public string Folder;
+
+        [Parameter(Mandatory = false, Position = 3, HelpMessage = "The target Container for the file to add to the in-memory template, optional argument.")]
+        public string Container;
+
+        [Parameter(Mandatory = false, Position = 4, HelpMessage = "Allows you to specify ITemplateProviderExtension to execute while loading the template.")]
+        public ITemplateProviderExtension[] TemplateProviderExtensions;
+
+        protected override void ProcessRecord()
+        {
+            if (String.IsNullOrEmpty(Source))
+            {
+                throw new ArgumentNullException("Source");
+            }
+
+            if (String.IsNullOrEmpty(Folder))
+            {
+                throw new ArgumentNullException("Folder");
+            }
+
+            // Load the template
+            ProvisioningTemplate template = LoadProvisioningTemplate
+                .LoadProvisioningTemplateFromFile(Path,
+                SessionState.Path.CurrentFileSystemLocation.Path,
+                TemplateProviderExtensions);
+
+            if (template == null)
+            {
+                throw new ApplicationException("Invalid template file!");
+            }
+
+            // Load the file and add it to the .PNP file
+            using (FileStream fs = new FileStream(Source, FileMode.Open, FileAccess.Read, FileShare.Read))
+            {
+                Folder = Folder.Replace("\\", "/");
+
+                String fileName = Source.IndexOf("\\") > 0 ? Source.Substring(Source.LastIndexOf("\\") + 1) : Source;
+                String container = !String.IsNullOrEmpty(Container) ? Container : String.Empty;
+                String source = !String.IsNullOrEmpty(container) ? (container + "/" + fileName) : fileName;
+
+                template.Connector.SaveFileStream(fileName, container, fs);
+
+                if (template.Connector is ICommitableFileConnector)
+                {
+                    ((ICommitableFileConnector)template.Connector).Commit();
+                }
+
+                template.Files.Add(new OfficeDevPnP.Core.Framework.Provisioning.Model.File {
+                    Src = source,
+                    Folder = Folder,
+                    Overwrite = true,
+                });
+
+                // Determine the output file name and path
+                string outFileName = System.IO.Path.GetFileName(Path);
+                string outPath = new System.IO.FileInfo(Path).DirectoryName;
+
+                // Save the template back to the storage
+                var fileSystemConnector = new FileSystemConnector(outPath, "");
+                ITemplateFormatter formatter = XMLPnPSchemaFormatter.LatestFormatter;
+
+                XMLTemplateProvider provider = new XMLOpenXMLTemplateProvider(
+                      Path, fileSystemConnector);
+                var templateFileName = outFileName.Substring(0, outFileName.LastIndexOf(".", StringComparison.Ordinal)) + ".xml";
+
+                provider.SaveAs(template, templateFileName, formatter, TemplateProviderExtensions);
+            }
+        }
+    }
+}

Commands/Base/SPOnlineConnectionHelper.cs

@@ -10,16 +10,22 @@ namespace SharePointPnP.PowerShell.Commands.Branding
     [CmdletHelp("Adds a link to a JavaScript snippet/block to a web or site collection",
         DetailedDescription = "Specify a scope as 'Site' to add the custom action to all sites in a site collection.",
         Category = CmdletHelpCategory.Branding)]
+    [CmdletExample(Code = "PS:> Add-SPOJavaScriptBlock -Name myAction -script '<script>Alert(\"This is my Script block\");</script>' -Sequence 9999 -Scope Site",
+                Remarks = "Add a JavaScript code block  to all pages within the current site collection under the name myAction and at order 9999",
+                SortOrder = 1)]
+    [CmdletExample(Code = "PS:> Add-SPOJavaScriptBlock -Name myAction -script '<script>Alert(\"This is my Script block\");</script>'",
+                Remarks = "Add a JavaScript code block  to all pages within the current web under the name myAction",
+                SortOrder = 2)]
     public class AddJavaScriptBlock : SPOWebCmdlet
     {
         [Parameter(Mandatory = true, HelpMessage = "The name of the script block. Can be used to identify the script with other cmdlets or coded solutions")]
         [Alias("Key")]
         public string Name = string.Empty;
 
-        [Parameter(Mandatory = true, HelpMessage = "The javascript block to add")]
+        [Parameter(Mandatory = true, HelpMessage = "The javascript block to add to the specified scope")]
         public string Script = null;
 
-        [Parameter(Mandatory = false)]
+        [Parameter(Mandatory = false, HelpMessage = "A sequence number that defines the order on the page")]
         public int Sequence = 0;
 
         [Parameter(Mandatory = false)]
@@ -32,7 +38,7 @@ public class AddJavaScriptBlock : SPOWebCmdlet
 
         protected override void ExecuteCmdlet()
         {
-            // Following code to handle desprecated parameter
+            // Following code to handle deprecated parameter
             CustomActionScope setScope;
 
             if (MyInvocation.BoundParameters.ContainsKey("SiteScoped"))
@@ -44,14 +50,21 @@ protected override void ExecuteCmdlet()
                 setScope = Scope;
             }
 
-            if (setScope == CustomActionScope.Web)
+            if (setScope != CustomActionScope.All)
             {
-                SelectedWeb.AddJsBlock(Name, Script, Sequence);
+                if (setScope == CustomActionScope.Web)
+                {
+                    SelectedWeb.AddJsBlock(Name, Script, Sequence);
+                }
+                else
+                {
+                    var site = ClientContext.Site;
+                    site.AddJsBlock(Name, Script, Sequence);
+                }
             }
             else
             {
-                var site = ClientContext.Site;
-                site.AddJsBlock(Name, Script, Sequence);
+                WriteError(new ErrorRecord(new Exception("Scope parameter can only be set to Web or Site"),"INCORRECTVALUE",ErrorCategory.InvalidArgument, this));
             }
         }
     }

Commands/Branding/AddCustomAction.cs

@@ -60,7 +60,7 @@ protected override void ExecuteCmdlet()
                     break;
 
                 case CustomActionScope.All:
-                    WriteWarning("CustomActionScope All is not supported for adding JavaScriptLinks");
+                    WriteError(new ErrorRecord(new Exception("Scope parameter can only be set to Web or Site"), "INCORRECTVALUE", ErrorCategory.InvalidArgument, this));
                     break;
             }
         }