Merge pull request #1445 from SharePoint/dev

March 2018 Release

Author: erwinvanhunen

.gitattributes

@@ -0,0 +1,63 @@
+###############################################################################
+# Set default behavior to automatically normalize line endings.
+###############################################################################
+* text=auto
+
+###############################################################################
+# Set default behavior for command prompt diff.
+#
+# This is need for earlier builds of msysgit that does not have it on by
+# default for csharp files.
+# Note: This is only used by command line
+###############################################################################
+#*.cs     diff=csharp
+
+###############################################################################
+# Set the merge driver for project and solution files
+#
+# Merging from the command prompt will add diff markers to the files if there
+# are conflicts (Merging from VS is not affected by the settings below, in VS
+# the diff markers are never inserted). Diff markers may cause the following 
+# file extensions to fail to load in VS. An alternative would be to treat
+# these files as binary and thus will always conflict and require user
+# intervention with every merge. To do so, just uncomment the entries below
+###############################################################################
+#*.sln       merge=binary
+#*.csproj    merge=binary
+#*.vbproj    merge=binary
+#*.vcxproj   merge=binary
+#*.vcproj    merge=binary
+#*.dbproj    merge=binary
+#*.fsproj    merge=binary
+#*.lsproj    merge=binary
+#*.wixproj   merge=binary
+#*.modelproj merge=binary
+#*.sqlproj   merge=binary
+#*.wwaproj   merge=binary
+
+###############################################################################
+# behavior for image files
+#
+# image files are treated as binary by default.
+###############################################################################
+#*.jpg   binary
+#*.png   binary
+#*.gif   binary
+
+###############################################################################
+# diff behavior for common document formats
+# 
+# Convert binary document formats to text before diffing them. This feature
+# is only available from the command line. Turn it on by uncommenting the 
+# entries below.
+###############################################################################
+#*.doc   diff=astextplain
+#*.DOC   diff=astextplain
+#*.docx  diff=astextplain
+#*.DOCX  diff=astextplain
+#*.dot   diff=astextplain
+#*.DOT   diff=astextplain
+#*.pdf   diff=astextplain
+#*.PDF   diff=astextplain
+#*.rtf   diff=astextplain
+#*.RTF   diff=astextplain

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,7 @@
+Before creating a pull request, make sure that you have read the contribution file located at
+
+https://github.com/SharePoint/PnP-PowerShell/blob/dev/CONTRIBUTING.md
+
 ## Type ##
 - [ ] Bug Fix
 - [ ] New Feature

changelog.md CHANGELOG.mdchangelog.md renamed to CHANGELOG.md

@@ -1,10 +1,94 @@
-# SharePointPnP.PowerShell Changelog #
-
-**2018-02-02**
-* Added Set-PnPSiteDesign and Set-PnPSiteScript cmdlets
-
-**2018-01-05**
-* Added Get-PnPTenantAppCatalogUrl, Start-PnPWorkflowInstance, Get-PnPWorkflowInstance
+# SharePointPnP.PowerShell Changelog
+*Please do not commit changes to this file, it is maintained by the repo owner.*
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
+
+## [2.24.1803.0] - 2018-03-06
+### Added
+- Added Get-PnPTenant cmdlet
+- Added Set-PnPTenant cmdlet
+- Added Set-PnPWebTheme cmdlet
+- Added Invoke-PnPSiteDesign cmdlet
+- Added Read-PnPProvisioningTemplate cmdlet [Rename: see deprecated section]
+- Added Invoke-PnPQuery cmdlet [Rename: see deprecated section]
+- Added Resolve-PnPFolder cmdlet [Rename: see deprecated section]
+- Added New-PnPAzureCertificate cmdlet
+- Added Get-PnPAzureCertificate cmdlet
+- Added Test-PnPOffice365GroupAliasIsUsed cmdlet
+- Added Remove-PnPStoredCredential
+- Added Add-PnPStoredCredential
+- Added Get-PnPHubSite cmdlet
+- Added Set-PnPHubSite cmdlet
+- Added Grant-PnPHubSiteRights cmdlet
+- Added Register-PnPHubSite cmdlet
+- Added Unregister-PnPHubSite cmdlet
+- Added Connect-PnPHubSite cmdlet
+- Added Disconnect-PnPHubSite cmdlet
+- Added Add-PnPTenantTheme cmdlet
+- Added Get-PnPTenantTheme cmdlet
+- Added Remove-PnPTenantTheme cmdlet
+- Added Set-PnPTenantCdnEnabled cmdlet
+- Added Get-PnPTenantCdnEnabled cmdlet
+- Added Get-PnPTenantCdnOrigin cmdlet
+- Added Add-PnPTenantCdnOrigin cmdlet
+- Added Remove-PnPTenantCdnOrigin cmdlet
+- Added Get-PnPTenantCdnPolicies cmdlet
+- Added Set-PnPTenantCdnPolicy cmdlet
+- Added Add-PnPSiteCollectionAppCatalog cmdlet
+- Added Remove-PnPSiteCollectionAppCatalog cmdlet
+- Added Get-PnPNavigationNode cmdlet
+- Added Get-PnPRoleDefinition cmdlet
+- Added Add-PnPRoleDefinition cmdlet
+- Added Remove-PnPRoleDefinition cmdlet
+- Implemented .NET 2.0 Standard project to allow for cross-platform use with PowerShell 6.0
+
+### Changed
+- Added "Formula" dynamic parameter to Add-PnPField to allow creating calculated fields.
+- Updated Set-PnPClientSidePage to support setting the page title
+- Added -Graph [and -LaunchBrowser] option to authenticate with Connect-PnPOnline to the Graph using the PnP O365 Management Shell Azure AD Application 
+- Updated the UnifiedGroup cmdlets to also take an Alias of group as a value for the -Identity parameter
+- Minor documentations updates [thechriskent]
+- Updated Connect-PnPOnline to support connecting using PEM encoded certificate strings
+- Updated Connect-PnPOnline for On-Premises to allow for additional HighTrustCertificate parameters [fowl2]
+- Added -EnableAttachment parameter for Set-PnPList [Laskewitz]
+- Added -Approve parameter for Set-PnPFileCheckedIn [Aproxmiation]
+- Added -EnableModeration for Set-PnPList [Apromixation]
+- Fixed issue where it was not possible to use New-PnPSite when using Connect-PnPOnline with the -UseWebLogin parameter
+- Fixed issue with Copy-PnPFile when copying to a location within the current web where metadata was not being retained
+- Fixed issue with Add-PnPFile when a new file was uploaded and using the cmdlet also field values where set, the version would increase to 2.0 instead of the expected 1.0
+- Fixed issues with Set-PnPTheme cmdlet not accepting site relative urls
+- Move-PnPFolder now returns the folder that has been moved
+- Updated Get-PnPStoredCredentials to support .NET Standard
+- Updated/fixed documentation on various cmdlets
+- Fixed issue with Get-PnPTenantSite not returning all sites in large tenants
+- Added -PnPO365ManagementShell [and -LaunchBrowser] login option to Connect-PnPOnline
+- Changed changelog format
+- Updated Remove-PnPNavigationNode cmdlet to support removal by Id
+- Updated Remove-PnPNavigationNode cmdlet to support the -All parameter
+- Updated Set-PnPList cmdlet to change moderation setting
+- Updated Set-PnPFileCheckedIn to approve the file
+
+### Deprecated
+- [SharePoint Online Only] Deprecated Get-PnPAppInstance, Import-PnPAppPackage, Uninstall-PnPAppPackage. Use Add-PnPApp, Install-PnPApp, Publish-PnPApp, Uninstall-PnPApp, Remove-PnPApp instead where applicable.
+- Deprecated Load-PnPProvisioningTemplate, renaming it to Read-PnPProvisioningTemplate which follows the PowerShell approved verb standard. Load-PnPProvisioningTemplate has been added as an alias for Read-PnPProvisioningTemplate.
+- Deprecated Execute-PnPQuery, renaming it to Invoke-PnPQuery which follows the PowerShell approved verb standard. Execute-PnPQuery has been added as an alias for Invoke-PnPQuery.
+- Deprecated Ensure-PnPFolder, moving functionality to Resolve-PnPFolder which follows the PowerShell approved verb standard. Ensure-PnPFolder has been added as an alias for Resolve-PnPFolder.
+- Documentation/Markdown generation has been removed from build, now points to https://docs.microsoft.com/en-us/powershell/sharepoint/sharepoint-pnp/sharepoint-pnp-cmdlets?view=sharepoint-ps
+- Deprecated Remove-PnPNavigationNode -Title and -Header parameters. Use the Identity parameter instead.
+- Marked -WebTemplate parameter on Get-PnPTenantSite as obsolete. Use -Template instead.
+- Deprecated Get-PnPAzureADManifestKeyCredentials. Use Get-PnPAzureCertificate instead.
+
+## [2.23.1802.0] - 2018-02-05
+### Added
+- Added Set-PnPSiteDesign and Set-PnPSiteScript cmdlets
+
+## [2.22.1801.0]
+### Added
+- Added Get-PnPTenantAppCatalogUrl
+- Start-PnPWorkflowInstance
+- Get-PnPWorkflowInstance
 
 **2017-12-06**
 * Added cmdlets for Site Designs: Add-PnPSiteDesign, Add-PnPSiteScript, Get-PnPSiteDesign, Get-PnPSiteScript, Get-PnPSiteDesignRights, Grant-PnPSiteDesignRights, Remove-PnPSiteDesign, Remove-PnPSiteScript, Revoke-PnPSiteDesignRights

CONTRIBUTING.md

@@ -1,33 +1,25 @@
 # Contribution guidance
 
-
-
-*work in progress*
-
-
-
 All PnP repositories are following up on the standard PnP process on getting started and contribute. 
 
-
 See following PnP wiki page from the main repository for additional details. 
 
-
-
 - For getting started guidance, see [Setting up your environment](https://github.com/OfficeDev/PnP/wiki/Setting-up-your-environment). 
 
-
-
 *Notice that you'll need to update the URLs based on used repository. All community contributions are also more than welcome. 
 Please see following page for additional insights on the model.
 
-
-
 - For contributing to PnP, see [Contributing to Office 365 developer patterns and practices](https://github.com/OfficeDev/PnP/wiki/contributing-to-Office-365-developer-patterns-and-practices)
+---
 
+## Building the source code ##
 
+If you have set up up the projects and you are ready to build the source code, make sure to build the SharePointPnP.PowerShellModuleFilesGenerator project first. This project will be executed after every build and it will generate the required PSD1 and XML files with cmdlet documentation in them.
 
----
+When you build the solution a postbuild script will copy the required files to a folder in your users folder called 
+*C:\Users\\\<YourUserName\>\Documents\WindowsPowerShell\Modules\SharePointPnPPowerShell\<Platform\>*. During build also the help and document files will be generated. If you have a session of PowerShell open in which you have used the PnP Cmdlets, make sure to close this PowerShell session first before you build. You will receive a build error otherwise because it tries to overwrite files that are in use.
 
+To debug the cmdlets: launch PowerShell and attach Visual Studio to the powershell.exe process. In case you want to debug methods in PnP Sites Core, make sure that you open the PnP Sites Core project instead, and then attach Visual Studio to the powershell.exe. In case you see strange debug behavior, like it wants to debug PSReadLine.ps1, uninstall the PowerShell extension from Visual Studio.
 
 ## Code contributions
 In order to succesfully compile the PnP PowerShell solution you will _also_ have to download *and build in Visual Studio* the [PnP-Sites-Core](https://github.com/OfficeDev/PnP-Sites-Core) repository and make the dev branch available. The PowerShell solution depends on it. In order to succesfully 
@@ -46,7 +38,7 @@ A few notes:
 As documentation is autogenerated by building the solution, make sure that you include both help and examples, alike
 
 ```csharp
- [Cmdlet("Get", "SPOStoredCredential")]
+ [Cmdlet(VerbsCommon.Get, "SPOStoredCredential")]
  [CmdletHelp("Returns a stored credential from the Windows Credential Manager", Category = "Base Cmdlets")]
  [CmdletExample(Code = "PS:> Get-SPOnlineStoredCredential -Name O365", 
                 Remarks = "Returns the credential associated with the specified identifier",
@@ -55,13 +47,21 @@ As documentation is autogenerated by building the solution, make sure that you i
   {
   }
 ```
-### Most cmdlets will extend SPOWebCmdlet which provides a few helper objects for you to use, like SelectedWeb and ClientContext
+### Most cmdlets will extend PnPCmdlet or PnPWebCmdlet which provides a few helper objects for you to use, like SelectedWeb and ClientContext
 As most cmdlets are 'web sensitive' (e.g. you can specify a -Web parameter to point to a different subweb), make sure that you use the correct ClientContext. When a user specifies the -Web parameter
-in a cmdlet that extens SPOWebCmdlet, the cmdlet will switch it's internal context to that web, reusing credentials. It is important to use the right context, and the easiest way to do that is to use
+in a cmdlet that extens PnPWebCmdlet, the cmdlet will switch it's internal context to that web, reusing credentials. It is important to use the right context, and the easiest way to do that is to use
+
+```csharp
+var context = ClientContext
+```
+
+alternatively 
 
 ```csharp
 var context = SelectedWeb.Context;
 ```
+
+
 ### Cmdlets will have to work both on-premises and in the cloud
 You can use preprocessor variables ("ONPREMISES" or "SP2013" and "SP2016") to build different cmdlets for the different targets. In cases where it is not possible to provide functionality for either the 
 cloud or on-premises, make sure to remove the full cmdlet from the compiled solution by having #IF(!SP2013) or #IF(SP2013) as the _first line of the cmdlet, before using statements. 
@@ -87,10 +87,11 @@ If only parts of a cmdlet require different behaviour based upon the different v
 The verb of a cmdlet (get-, add-, etc.) should follow acceptable cmdlet standards and should be part of one of the built in verbs classes (VerbsCommon, VerbsData, etc.):
 
 ## Documentation contributions
-If you want to contribute to cmdlet documentation, please do not make a pull request to modify the actual files in the Documentation folder itself. Those files
-are automatically generated based upon comments in the actual classes. So if you want to modify documentation or add an example of a cmdlet, navigate to the
+The PowerShell documentation is located on [docs.microsoft.com](https://docs.microsoft.com/en-us/powershell/sharepoint/sharepoint-pnp/sharepoint-pnp-cmdlets?view=sharepoint-ps)
+
+This documentation is automatically generated based upon statements/attributes in the source code of a cmdlet. If you want to modify documentation or add an example of a cmdlet, navigate to the
 corresponding class where the cmdlet is being implemented and add the comments there. An example can for instance be found in
 
-https://github.com/OfficeDev/PnP-PowerShell/blob/dev/Commands/Fields/AddField.cs
+https://github.com/sharepoint/PnP-PowerShell/blob/dev/Commands/Fields/AddField.cs
 
-Notice the [CmdletHelp("")] and [CmdletExample()] class attributes that describe the cmdlet.
+Notice the [CmdletHelp("")] and [CmdletExample()] class attributes that describe the cmdlet. A description for a parameter is located in the [Parameter(HelpMessage = "") attribute.

Commands/Admin/AddOffice365GroupToSite.cs

@@ -0,0 +1,58 @@
+#if !ONPREMISES
+using Microsoft.Online.SharePoint.TenantAdministration;
+using Microsoft.SharePoint.Client;
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using SharePointPnP.PowerShell.Commands.Base;
+using System.Management.Automation;
+using OfficeDevPnP.Core.Sites;
+
+namespace SharePointPnP.PowerShell.Commands.Admin
+{
+    [Cmdlet(VerbsCommon.Add, "PnPOffice365GroupToSite")]
+    [CmdletHelp("Groupifies a classic team site by creating an Office 365 group for it and connecting the site with the newly created group",
+        DetailedDescription = "This command allows you to add an Office 365 Unified group to an existing classic site collection.",
+        SupportedPlatform = CmdletSupportedPlatform.Online,
+        Category = CmdletHelpCategory.TenantAdmin)]
+    [CmdletExample(
+        Code = @"PS:> Add-PnPOffice365GroupToSite -Url ""https://contoso.sharepoint.com/sites/FinanceTeamsite"" -Alias ""FinanceTeamsite"" -DisplayName = ""My finance team site group""",
+        Remarks = @"This will add a group called MyGroup to the current site collection", SortOrder = 1)]
+    public class AddOffice365GroupToSite: PnPAdminCmdlet
+    {
+        [Parameter(Mandatory = true, HelpMessage = @"Url of the site to be connected to an Office 365 Group.")]
+        public string Url;
+
+        [Parameter(Mandatory = true, HelpMessage = @"Specifies the alias of the group. Cannot contain spaces.")]
+        public string Alias;
+
+        [Parameter(Mandatory = false, HelpMessage = @"The optional description of the group.")]
+        public string Description;
+
+        [Parameter(Mandatory = true, HelpMessage = @"The display name of the group.")]
+        public string DisplayName;
+
+        [Parameter(Mandatory = false, HelpMessage = @"Specifies the classification of the group.")]
+        public string Classification;
+
+        [Parameter(Mandatory = false, HelpMessage = @"Specifies if the group is public. Defaults to false.")]
+        public SwitchParameter IsPublic;
+
+        [Parameter(Mandatory = false, HelpMessage = @"Specifies if the current site home page is kept. Defaults to false.")]
+        public SwitchParameter KeepOldHomePage;
+
+        protected override void ExecuteCmdlet()
+        {
+            var groupifyInformation = new TeamSiteCollectionGroupifyInformation()
+            {
+                Alias = Alias,
+                DisplayName = DisplayName,
+                Description = Description,
+                Classification = Classification,
+                IsPublic = IsPublic,
+                KeepOldHomePage = KeepOldHomePage
+            };
+
+            Tenant.GroupifySite(Url, groupifyInformation);
+        }
+    }
+}
+#endif

Commands/Admin/AddSiteCollectionAppCatalog.cs

@@ -0,0 +1,42 @@
+#if !ONPREMISES
+using Microsoft.Online.SharePoint.TenantAdministration;
+using Microsoft.SharePoint.Client;
+using SharePointPnP.PowerShell.CmdletHelpAttributes;
+using SharePointPnP.PowerShell.Commands.Base;
+using System.Management.Automation;
+using OfficeDevPnP.Core.Sites;
+using SharePointPnP.PowerShell.Commands.Base.PipeBinds;
+using System;
+
+namespace SharePointPnP.PowerShell.Commands.Admin
+{
+    [Cmdlet(VerbsCommon.Add, "PnPSiteCollectionAppCatalog")]
+    [CmdletHelp("Adds a Site Collection scoped App Catalog to a site",
+        SupportedPlatform = CmdletSupportedPlatform.Online,
+        Category = CmdletHelpCategory.TenantAdmin)]
+    [CmdletExample(
+        Code = @"PS:> Add-PnPOffice365GroupToSite -Site ""https://contoso.sharepoint.com/sites/FinanceTeamsite""",
+        Remarks = @"This will add a SiteCollection app catalog to the specified site", SortOrder = 1)]
+    public class AddSiteCollectionAppCatalog: PnPAdminCmdlet
+    {
+        [Parameter(Mandatory = true, HelpMessage = @"Url of the site to add the app catalog to.")]
+        public SitePipeBind Site;
+
+        protected override void ExecuteCmdlet()
+        {
+            string url = null;
+            if(Site.Site != null)
+            {
+                Site.Site.EnsureProperty(s => s.Url);
+                url = Site.Site.Url;
+            } else if(!string.IsNullOrEmpty(Site.Url))
+            {
+                url = Site.Url;
+            }
+            
+            Tenant.GetSiteByUrl(url).RootWeb.TenantAppCatalog.SiteCollectionAppCatalogsSites.Add(url);
+            ClientContext.ExecuteQueryRetry();
+        }
+    }
+}
+#endif