Merge pull request #1149 from SharePoint/dev

October 2017 Intermediate Release 1

Author: erwinvanhunen

Commands/Admin/GetTenantSite.cs

@@ -11,7 +11,7 @@
 namespace SharePointPnP.PowerShell.Commands
 {
     [Cmdlet(VerbsCommon.Get, "PnPTenantSite", SupportsShouldProcess = true)]
-    [CmdletHelp(@"Uses the tenant API to retrieve site information.",
+    [CmdletHelp(@"Retrieve site information.", "Use this cmdlet to retrieve site information from your tenant administration.",
         Category = CmdletHelpCategory.TenantAdmin,
         SupportedPlatform = CmdletSupportedPlatform.Online,
         OutputType = typeof(Microsoft.Online.SharePoint.TenantAdministration.SiteProperties),

Commands/Admin/GetTimeZoneId.cs

@@ -8,6 +8,7 @@ namespace SharePointPnP.PowerShell.Commands
 {
     [Cmdlet(VerbsCommon.Get, "PnPTimeZoneId")]
     [CmdletHelp("Returns a time zone ID",
+        "In order to create a new classic site you need to specify the timezone this site will use. Use the cmdlet to retrieve a list of possible values.",
          Category = CmdletHelpCategory.TenantAdmin,
          OutputType = typeof(IEnumerable<Zone>),
          OutputTypeDescription =

Commands/Admin/GetWebTemplates.cs

@@ -8,6 +8,7 @@ namespace SharePointPnP.PowerShell.Commands
 {
     [Cmdlet(VerbsCommon.Get, "PnPWebTemplates")]
     [CmdletHelp(@"Returns the available web templates.", 
+        "Will list all available templates one can use to create a classic site.",
         Category = CmdletHelpCategory.TenantAdmin,
         SupportedPlatform = CmdletSupportedPlatform.Online,
         OutputType =typeof(Microsoft.Online.SharePoint.TenantAdministration.SPOTenantWebTemplateCollection),

Commands/Admin/NewSite.cs

@@ -15,9 +15,9 @@ namespace SharePointPnP.PowerShell.Commands
 {
     [Cmdlet(VerbsCommon.New, "PnPSite")]
     [CmdletHelp("BETA: This cmdlet is using early release APIs. Notice that functionality and parameters can change. Creates a new site collection",
+        "The New-PnPSite cmdlet creates a new site collection for the current tenant. Currently only 'modern' sites like Communication Site and the Modern Team Site are supported. If you want to create a classic site, use New-PnPTenantSite.",
         OutputType = typeof(string),
         OutputTypeDescription = "Returns the url of the newly created site collection",
-        DetailedDescription = @"The New-PnPSite cmdlet creates a new site collection for the current tenant. Currently only 'modern' sites like Communication Site and the Modern Team Site are supported. If you want to create a classic site, use New-PnPTenantSite.",
         Category = CmdletHelpCategory.TenantAdmin, SupportedPlatform = CmdletSupportedPlatform.Online)]
     [CmdletExample(
         Code = @"PS:> New-PnPSite -Type CommunicationSite -Title Contoso -Url https://tenant.sharepoint.com/sites/contoso",
@@ -47,25 +47,25 @@ namespace SharePointPnP.PowerShell.Commands
         Code = @"PS:> New-PnPSite -Type TeamSite -Title Contoso -Alias contoso -IsPublic",
         Remarks = @"This will create a new Modern Team Site collection with the title 'Contoso' and the url 'https://tenant.sharepoint.com/sites/contoso' and sets the site to public.",
         SortOrder = 7)]
-    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Title", Mandatory = true, HelpMessage = @"Specifies the title of the new site collection", ParameterSetName = "CommunicationBuiltInDesign")]
+    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Title", Mandatory = true, HelpMessage = @"Specifies the title of the new site collection", ParameterSetName = "Communication Site With Built-in Design")]
     [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Title", Mandatory = true, HelpMessage = @"Specifies the title of the new site collection", ParameterSetName = "CommunicationCustomInDesign")]
-    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Url", Mandatory = true, HelpMessage = @"Specifies the full url of the new site collection", ParameterSetName = "CommunicationBuiltInDesign")]
+    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Url", Mandatory = true, HelpMessage = @"Specifies the full url of the new site collection", ParameterSetName = "Communication Site With Built-in Design")]
     [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Url", Mandatory = true, HelpMessage = @"Specifies the full url of the new site collection", ParameterSetName = "CommunicationCustomInDesign")]
-    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Description", Mandatory = false, HelpMessage = @"Specifies the description of the new site collection", ParameterSetName = "CommunicationBuiltInDesign")]
+    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Description", Mandatory = false, HelpMessage = @"Specifies the description of the new site collection", ParameterSetName = "Communication Site With Built-in Design")]
     [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Description", Mandatory = false, HelpMessage = @"Specifies the description of the new site collection", ParameterSetName = "CommunicationCustomInDesign")]
-    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Classification", Mandatory = false, HelpMessage = @"Specifies the classification of the new site collection", ParameterSetName = "CommunicationBuiltInDesign")]
+    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Classification", Mandatory = false, HelpMessage = @"Specifies the classification of the new site collection", ParameterSetName = "Communication Site With Built-in Design")]
     [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Classification", Mandatory = false, HelpMessage = @"Specifies the classification of the new site collection", ParameterSetName = "CommunicationCustomInDesign")]
-    [CmdletAdditionalParameter(ParameterType = typeof(SwitchParameter), ParameterName = "AllowFileSharingForGuestUsers", Mandatory = false, HelpMessage = @"Specifies if guest users can share files in the new site collection", ParameterSetName = "CommunicationBuiltInDesign")]
+    [CmdletAdditionalParameter(ParameterType = typeof(SwitchParameter), ParameterName = "AllowFileSharingForGuestUsers", Mandatory = false, HelpMessage = @"Specifies if guest users can share files in the new site collection", ParameterSetName = "Communication Site With Built-in Design")]
     [CmdletAdditionalParameter(ParameterType = typeof(SwitchParameter), ParameterName = "AllowFileSharingForGuestUsers", Mandatory = false, HelpMessage = @"Specifies if guest users can share files in the new site collection", ParameterSetName = "CommunicationCustomInDesign")]
-    [CmdletAdditionalParameter(ParameterType = typeof(OfficeDevPnP.Core.Sites.CommunicationSiteDesign), ParameterName = "SiteDesign", Mandatory = false, HelpMessage = @"Specifies the site design of the new site collection. Defaults to 'Topic'", ParameterSetName = "CommunicationBuiltInDesign")]
+    [CmdletAdditionalParameter(ParameterType = typeof(OfficeDevPnP.Core.Sites.CommunicationSiteDesign), ParameterName = "SiteDesign", Mandatory = false, HelpMessage = @"Specifies the site design of the new site collection. Defaults to 'Topic'", ParameterSetName = "Communication Site With Built-in Design")]
     [CmdletAdditionalParameter(ParameterType = typeof(GuidPipeBind), ParameterName = "SiteDesignId", Mandatory = true, HelpMessage = @"Specifies the site design id to use for the new site collection. If specified will override SiteDesign", ParameterSetName = "CommunicationCustomInDesign")]
-    [CmdletAdditionalParameter(ParameterType = typeof(uint), ParameterName = "Lcid", Mandatory = false, HelpMessage = @"Specifies the language of the new site collection. Defaults to the current language of the web connected to.", ParameterSetName = "CommunicationBuiltInDesign")]
+    [CmdletAdditionalParameter(ParameterType = typeof(uint), ParameterName = "Lcid", Mandatory = false, HelpMessage = @"Specifies the language of the new site collection. Defaults to the current language of the web connected to.", ParameterSetName = "Communication Site With Built-in Design")]
     [CmdletAdditionalParameter(ParameterType = typeof(uint), ParameterName = "Lcid", Mandatory = false, HelpMessage = @"Specifies the language of the new site collection. Defaults to the current language of the web connected to.", ParameterSetName = "CommunicationCustomInDesign")]
-    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Title", Mandatory = true, HelpMessage = @"Specifies the title of the new site collection", ParameterSetName = "TeamSite")]
-    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Alias", Mandatory = true, HelpMessage = @"Specifies the alias of the new site collection", ParameterSetName = "TeamSite")]
-    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Description", Mandatory = false, HelpMessage = @"Specifies the description of the new site collection", ParameterSetName = "TeamSite")]
-    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Classification", Mandatory = false, HelpMessage = @"Specifies the classification of the new site collection", ParameterSetName = "TeamSite")]
-    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "IsPublic", Mandatory = false, HelpMessage = @"Specifies if new site collection is public. Defaults to false.", ParameterSetName = "TeamSite")]
+    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Title", Mandatory = true, HelpMessage = @"Specifies the title of the new site collection", ParameterSetName = "Team Site")]
+    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Alias", Mandatory = true, HelpMessage = @"Specifies the alias of the new site collection", ParameterSetName = "Team Site")]
+    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Description", Mandatory = false, HelpMessage = @"Specifies the description of the new site collection", ParameterSetName = "Team Site")]
+    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "Classification", Mandatory = false, HelpMessage = @"Specifies the classification of the new site collection", ParameterSetName = "Team Site")]
+    [CmdletAdditionalParameter(ParameterType = typeof(string), ParameterName = "IsPublic", Mandatory = false, HelpMessage = @"Specifies if new site collection is public. Defaults to false.", ParameterSetName = "Team Site")]
     public class NewSite : PnPCmdlet, IDynamicParameters
     {
         [Parameter(Mandatory = true, HelpMessage = "@Specifies with type of site to create.")]
@@ -138,27 +138,27 @@ protected override void ExecuteCmdlet()
 
         public class CommunicationSiteParameters
         {
-            [Parameter(Mandatory = true, ParameterSetName = "CommunicationBuiltInDesign")]
+            [Parameter(Mandatory = true, ParameterSetName = "Communication Site With Built-in Design")]
             [Parameter(Mandatory = true, ParameterSetName = "CommunicationCustomInDesign")]
             public string Title;
 
-            [Parameter(Mandatory = true, ParameterSetName = "CommunicationBuiltInDesign")]
+            [Parameter(Mandatory = true, ParameterSetName = "Communication Site With Built-in Design")]
             [Parameter(Mandatory = true, ParameterSetName = "CommunicationCustomInDesign")]
             public string Url;
 
-            [Parameter(Mandatory = false, ParameterSetName = "CommunicationBuiltInDesign")]
+            [Parameter(Mandatory = false, ParameterSetName = "Communication Site With Built-in Design")]
             [Parameter(Mandatory = false, ParameterSetName = "CommunicationCustomInDesign")]
             public string Description;
 
-            [Parameter(Mandatory = false, ParameterSetName = "CommunicationBuiltInDesign")]
+            [Parameter(Mandatory = false, ParameterSetName = "Communication Site With Built-in Design")]
             [Parameter(Mandatory = false, ParameterSetName = "CommunicationCustomInDesign")]
             public string Classification;
 
-            [Parameter(Mandatory = false, ParameterSetName = "CommunicationBuiltInDesign")]
+            [Parameter(Mandatory = false, ParameterSetName = "Communication Site With Built-in Design")]
             [Parameter(Mandatory = false, ParameterSetName = "CommunicationCustomInDesign")]
             public SwitchParameter AllowFileSharingForGuestUsers;
 
-            [Parameter(Mandatory = false, ParameterSetName = "CommunicationBuiltInDesign")]
+            [Parameter(Mandatory = false, ParameterSetName = "Communication Site With Built-in Design")]
             public OfficeDevPnP.Core.Sites.CommunicationSiteDesign SiteDesign = OfficeDevPnP.Core.Sites.CommunicationSiteDesign.Topic;
 
             [Parameter(Mandatory = true, ParameterSetName = "CommunicationCustomInDesign")]
@@ -171,19 +171,19 @@ public class CommunicationSiteParameters
 
         public class TeamSiteParameters
         {
-            [Parameter(Mandatory = true, ParameterSetName = "TeamSite")]
+            [Parameter(Mandatory = true, ParameterSetName = "Team Site")]
             public string Title;
 
-            [Parameter(Mandatory = true, ParameterSetName = "TeamSite")]
+            [Parameter(Mandatory = true, ParameterSetName = "Team Site")]
             public string Alias;
 
-            [Parameter(Mandatory = false, ParameterSetName = "TeamSite")]
+            [Parameter(Mandatory = false, ParameterSetName = "Team Site")]
             public string Description;
 
-            [Parameter(Mandatory = false, ParameterSetName = "TeamSite")]
+            [Parameter(Mandatory = false, ParameterSetName = "Team Site")]
             public string Classification;
 
-            [Parameter(Mandatory = false, ParameterSetName = "TeamSite")]
+            [Parameter(Mandatory = false, ParameterSetName = "Team Site")]
             public SwitchParameter IsPublic;
         }
     }

Commands/Admin/NewTenantSite.cs

@@ -12,7 +12,7 @@ namespace SharePointPnP.PowerShell.Commands
 {
     [Cmdlet(VerbsCommon.New, "PnPTenantSite")]
     [CmdletHelp("Creates a new site collection for the current tenant",
-        DetailedDescription = @"The New-PnPTenantSite cmdlet creates a new site collection for the current company. However, creating a new SharePoint
+        @"The New-PnPTenantSite cmdlet creates a new site collection for the current company. However, creating a new SharePoint
 Online site collection fails if a deleted site with the same URL exists in the Recycle Bin. If you want to use this command for an on-premises farm, please refer to http://blogs.msdn.com/b/vesku/archive/2014/06/09/provisioning-site-collections-using-sp-app-model-in-on-premises-with-just-csom.aspx ",
         Category = CmdletHelpCategory.TenantAdmin)]
     [CmdletExample(

Commands/Admin/RemoveTenantSite.cs

@@ -10,7 +10,8 @@
 namespace SharePointPnP.PowerShell.Commands
 {
     [Cmdlet(VerbsCommon.Remove, "PnPTenantSite", ConfirmImpact = ConfirmImpact.High, SupportsShouldProcess = true)]
-    [CmdletHelp("Removes a site collection from the current tenant",
+    [CmdletHelp("Removes a site collection",
+        "Removes a site collection which is listed in your tenant administration site.",
         SupportedPlatform = CmdletSupportedPlatform.Online,
          Category = CmdletHelpCategory.TenantAdmin)]
     [CmdletExample(

Commands/Admin/SetTenantSite.cs

@@ -12,7 +12,8 @@
 namespace SharePointPnP.PowerShell.Commands
 {
     [Cmdlet(VerbsCommon.Set, "PnPTenantSite")]
-    [CmdletHelp(@"Uses the tenant API to set site information.",
+    [CmdletHelp(@"Set site information.",
+        "Sets site properties for existing sites.",
         SupportedPlatform = CmdletSupportedPlatform.Online,
         Category = CmdletHelpCategory.TenantAdmin)]
     [CmdletExample(

Commands/Apps/AddApp.cs

@@ -0,0 +1,37 @@
+#if !ONPREMISES
+using OfficeDevPnP.Core.ALM;
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using System.Management.Automation;
+
+namespace SharePointPnP.PowerShell.Commands.Apps
+{
+    [Cmdlet(VerbsCommon.Add, "PnPApp")]
+    [CmdletHelp("Add/uploads an available app to the app catalog",
+        Category = CmdletHelpCategory.Apps, SupportedPlatform = CmdletSupportedPlatform.Online,
+        OutputType = typeof(AppMetadata))]
+    [CmdletExample(Code = @"PS:> Add-PnPApp -Path ./myapp.sppkg", Remarks = @"This will upload the specified app package to the app catalog", SortOrder = 1)]
+    public class AddApp : PnPCmdlet
+    {
+        [Parameter(Mandatory = true, Position = 0, ValueFromPipeline = true, HelpMessage = "Specifies the Id or an actual app metadata instance")]
+        public string Path;
+
+        protected override void ExecuteCmdlet()
+        {
+            if (!System.IO.Path.IsPathRooted(Path))
+            {
+                Path = System.IO.Path.Combine(SessionState.Path.CurrentFileSystemLocation.Path, Path);
+            }
+
+            var fileInfo = new System.IO.FileInfo(Path);
+
+            var bytes = System.IO.File.ReadAllBytes(Path);
+
+            var manager = new AppManager(ClientContext);
+
+            var result = manager.Add(bytes, fileInfo.Name);
+
+            WriteObject(result);
+        }
+    }
+}
+#endif

Commands/Apps/GetApp.cs

@@ -0,0 +1,47 @@
+#if !ONPREMISES
+using System.Collections.Generic;
+using System.Linq;
+using System.Management.Automation;
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using SharePointPnP.PowerShell.Commands.Base.PipeBinds;
+using OfficeDevPnP.Core.ALM;
+
+namespace SharePointPnP.PowerShell.Commands.Apps
+{
+    [Cmdlet(VerbsCommon.Get, "PnPApp")]
+    [CmdletHelp("Returns the available apps from the app catalog",
+        Category = CmdletHelpCategory.Apps,
+        OutputType = typeof(List<AppMetadata>), SupportedPlatform = CmdletSupportedPlatform.Online)]
+    [CmdletExample(Code = @"PS:> Get-PnPAvailableApp", Remarks = @"This will return all available app metadata from the tenant app catalog. It will list the installed version in the current site.", SortOrder = 1)]
+    [CmdletExample(Code = @"PS:> Get-PnPAvailableApp -Identity 2646ccc3-6a2b-46ef-9273-81411cbbb60f", Remarks = @"This will the specific app metadata from the app catalog.", SortOrder = 2)]
+    public class GetApp : PnPCmdlet
+    {
+        [Parameter(Mandatory = false, Position = 0, ValueFromPipeline = true, HelpMessage = "Specifies the Id of an app which is available in the app catalog")]
+        public GuidPipeBind Identity;
+
+        protected override void ExecuteCmdlet()
+        {
+            var manager = new AppManager(ClientContext);
+
+            var apps = manager.GetAvailable();
+            if (MyInvocation.BoundParameters.ContainsKey("Identity"))
+            {
+                var app = apps.FirstOrDefault(a => a.Id == Identity.Id);
+                
+                if (app != null)
+                {
+                    WriteObject(app);
+                }
+                else
+                {
+                    throw new System.Exception("App not found");
+                }
+            }
+            else
+            {
+                WriteObject(apps);
+            }
+        }
+    }
+}
+#endif

Commands/Apps/GetAppInstance.cs

@@ -8,7 +8,8 @@
 namespace SharePointPnP.PowerShell.Commands.Apps
 {
     [Cmdlet(VerbsCommon.Get, "PnPAppInstance")]
-    [CmdletHelp("Returns a SharePoint AddIn Instance in the site",
+    [CmdletHelp("Returns a SharePoint AddIn Instance",
+        "Returns a SharePoint App/Addin that has been installed in the current site",
         Category = CmdletHelpCategory.Apps,
         OutputType = typeof(List<AppInstance>),
         OutputTypeLink = "https://msdn.microsoft.com/en-us/library/microsoft.sharepoint.client.appinstance.aspx")]