Merge pull request #2961 from pnp/dev

2.0 Merge to master

.github/workflows/nightlyrelease.yml

@@ -16,6 +16,8 @@ jobs:
         dotnet-version: | 
           3.1.301
           5.x
+          6.x
+          7.x
     - uses: actions/checkout@v2
       with:
         ref: dev

CONTRIBUTING.md

@@ -1,59 +1,3 @@
 # Contribution guidance
 
-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/PnP/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 Microsoft 365 Developer Patterns and Practices](https://github.com/PnP/PnP/wiki/contributing-to-Office-365-developer-patterns-and-practices)
----
-
-## Building the source code ##
-Once you have downloaded the code, in the folder with the PnP PowerShell source code, open the solution file PnP.PowerShell.sln.
-
-When you build the solution a post build script will generate and copy the required files to a folder in your users folder called 
-`C:\Users\[YourUserName]\Documents\PowerShell\Modules\PnP.PowerShell`. 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.
-
-## Keeping your fork up to date
-Before starting on any new submissions, please ensure your fork is up to date with the upstream repository. This avoids frustration and challenges for us to validate and test your submission. Steps on how to easily keep your fork up to date can be found [on this wiki page](https://github.com/pnp/PnP-PowerShell/wiki/Update-your-fork-with-the-latest-code).
-
-## Code contributions
-In order to successfully compile the PnP PowerShell solution you will _also_ have to download *and build in Visual Studio* the [PnP-Framework](https://github.com/pnp/pnpframework) repository and make the dev branch available. **The PowerShell solution depends on it**. In order to successfully 
-compile it, make sure that PnP-Sites-Core is located at the same level as PnP-PowerShell and you open the solution file `pnpframework.sln` located in the Core subfolder of the sourcecode.
-
-So:
-```
-c:\[YOUR REPO FOLDER]\pnpframework
-c:\[YOUR REPO FOLDER]\powershell
-```
-
-The reason for this is that the PnP-PowerShell library will have references to the release and debug builds of the PnP Framework library.
-
-A few notes:
-
-### 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 extends 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 use common verbs
-
-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
-The PowerShell documentation is located on https://docs.microsoft.com/powershell/sharepoint/sharepoint-pnp/sharepoint-pnp-cmdlets?view=sharepoint-ps
+Please have a look at [our documentation](https://pnp.github.io/powershell/articles/gettingstartedcontributing.html) to learn how you can contribute to PnP PowerShell!

MIGRATE-1.0-to-2.0.md

@@ -0,0 +1,93 @@
+# Updating from PnP PowerShell 1.x to 2.x
+
+The 2.x version of PnP PowerShell is based exclusively on .NET 6.0, which means that it will not work on older PowerShell editions like PowerShell 5.1 or ISE.
+
+- The 1.x version of PnP PowerShell was based on .NET Framework 4.6.2 and .NET 3.1.
+
+- We had to update the module to .NET 6.0 because Microsoft removed support for .NET 3.1 in early December 2022.
+
+- We decided to drop support for .NET Framework it is not actively developed, doesn't work across-platforms and only receives maintainence and security updates. So, it would add additional code complexity and maintainabilty issues for us going forward in the future.
+
+- The 2.x version of PnP PowerShell will work only on PowerShell 7.2.x or later versions.
+
+## Steps to update from 1.x to 2.x
+
+- Download and install the PowerShell version from [this GitHub releases link](https://aka.ms/powershell-release?tag=lts)
+
+Or
+
+- For Windows environments, please use [this link](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.2)
+
+- For Linux based environments, please use [this link](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux?view=powershell-7.2)
+
+- For Mac OS envoronments, please use [this link](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-macos?view=powershell-7.2)
+
+Once the PowerShell 7.2.x or later is downloaded and installed in the environment, you can install the PnP PowerShell module like you normally do.
+
+```powershell
+Install-Module -Name "PnP.PowerShell"
+```
+
+If you want to install or update to the latest nightly built prerelease of PnP PowerShell, run:
+
+```powershell
+Install-Module -Name "PnP.PowerShell" -AllowPrerelease
+```
+
+## Changes needed in Azure DevOps/GitHub Actions/Pipelines
+
+If you are using PnP PowerShell in Azure Devops, GitHub Actions or other pipeline infrastructure, you will have to update your PowerShell version from v5 to v7.2.x or later.
+
+Recommend referring to these 2 links:
+
+- [DevOps Snack: Change PowerShell version in YAML](https://microsoft-bitools.blogspot.com/2021/02/devops-snack-change-powershell-version.html)
+- [How to enable PowerShell core in Azure Pipeline?](https://theautomationcode.com/how-to-enable-powershell-core-in-azure-pipeline/)
+
+## Changes needed in Azure Functions
+
+Using PnP PowerShell in Azure functions ? You might be required to change the PnP PowerShell version used.
+
+- If the Azure function is based on PowerShell 7.0 runtime, then you should keep using PnP PowerShell 1.x versions. The latest version is 1.12.0. The PowerShell 7.0 based runtime is deprecated and not supported anymore by Microsoft. You should consider updating to the 7.2 based runtime.
+
+- If the Azure function is based on PowerShell 7.2 runtime, you should update the PnP PowerShell to the 2.x version. It is currently only available as a nightly build, so you need to explicitly specify the version like `2.0.1-nightly`. This will fix the error that you might be currently facing:  [Could not load type 'Microsoft.Extensions.Logging.Abstractions.Internal.NullScope' from assembly 'Microsoft.Extensions.Logging.Abstractions'](https://github.com/pnp/powershell/issues/2136)
+
+## Breaking changes
+
+| **Cmdlet** | **Obsolete parameter** | **Replacement parameter** | **Comment** |
+| ----------- | ---------------------- | -------------------- | --------------------- |
+| New-PnPTenantSite | Force | - | The parameter was obsolete and not used. It has been removed. |
+| Set-PnPTenantSite | BlockDownloadOfNonViewableFiles | AllowDownloadingNonWebViewableFiles | The parameter was obsolete and hence removed. Use `AllowDownloadingNonWebViewableFiles` |
+| Connect-PnPOnline | NoTelemetry | - | The parameter was obsolete and hence removed. Use `$env:PNP_DISABLETELEMETRY` environment variable or `Disable-PnPTelemetry/Enable-PnPTelemetry` cmdlet |
+| Connect-PnPOnline | NoVersionCheck | - | The parameter was obsolete and hence removed. Use `$env:PNPPOWERSHELL_UPDATECHECK` environment variable |
+| Disconnect-PnPOnline | Connection | - | The parameter was obsolete and hence removed. |
+| Request-PnPAccessToken | Resource | Scopes | The parameter was obsolete and hence removed. Use `Scopes` instead |
+| Copy-PnPFile | SkipSourceFolderName | - | The parameter was obsolete and has no effect currently nor was it used |
+| Get-PnPMicrosoft365Group | ExcludeSiteUrl | IncludeSiteUrl | The parameter was obsolete and hence removed. The site url is now excluded by default. Use `IncludeSiteUrl` instead to include the site url of the underlying SharePoint site. |
+| Get-PnPMicrosoft365Group | IncludeClassification | - | The parameter was obsolete and hence removed. The site classification is now included by default. |
+| Get-PnPMicrosoft365Group | IncludeHasTeam | - | The parameter was obsolete and hence removed. The `HasTeam` is now included by default. |
+| New-PnPGroup | OnlyAllowMembersViewMembership | - | The parameter was obsolete and hence removed. It is now done by default. Use `DisallowMembersViewMembership` to disallow group members viewing membership |
+| New-PnPGroup | SetAssociatedGroup | - | The parameter was obsolete and hence removed. Use `Set-PnPGroup` cmdlet instead. |
+| Convert-PnPSiteTemplate | - | - | We have removed support for `2019-03` provisioning schema. Use `2019-09` or later versions |
+| Get-PnPSiteTemplate | NoBaseTemplate | - | The parameter was obsolete and hence removed. Use of this parameter is generally not required/recommended. It will use the connected web template |
+| New-PnPSiteTemplateFromFolder | NoBaseTemplate | - | We have removed support for `2019-03` provisioning schema. Use `2019-09` or later versions |
+| Add-PnPTeamsChannel | Private | ChannelType | The parameter was obsolete and hence removed. Use `-ChannelType` instead |
+| New-PnPTeamsTeam | Owner | Owners | The parameter was obsolete and hence removed. Use `-Owners` instead which supports setting multiple owner of a Teams team |
+| Export-PnPTaxonomy | - | - | The cmdlet does not support export of taxonomy using `UTF-7` encoding. If `UTF-7` is specified, it will switch to `UTF-8` encoding |
+| Get-PnPField | ReturnTyped | - | The cmdlet will always return the typed object of the field. |
+| Get-PnPUserProfileProperty | - | - | Additional user profile properties are no longer returned under UserProfileProperties but instead will be directly under the returned instance |
+| Get-PnPFlowEnvironment | - | - | The alias on the cmdlet has been removed. Use `PnPPowerPlatformEnvironment` instead. |
+
+## Other notable changes
+
+- We have removed support for `2019-03` version of the PnP Provisioning schema from all provisioning related cmdlets. You should be using atleast `2019-09` or a later version of the schema.
+- The `-Web` parameter, which was marked obsolete, was used in certain Web level cmdlets. We have removed that. You should use `Connect-PnPOnline -Url [subweburl]` instead to connect to a Web.
+
+## Changes to output type
+
+- When using `Add-PnPTeamsTab` cmdlet, if you specify the `-Type SharePointPageAndList`, then `-WebSiteUrl` is mandatory.
+- When using `Add-PnPTeamsTab` cmdlet, if you specify the `-Type Planner`, then `-ContentUrl` is mandatory.
+- The output type of `Get-PnPAzureADGroupOwner` has changed to `PnP.PowerShell.Commands.Model.Microsoft365User`
+- The output type of `Get-PnPAzureADGroupMember` has changed to `PnP.PowerShell.Commands.Model.Microsoft365User`
+- The output type of `Get-PnPAzureADGroup` has changed to `PnP.PowerShell.Commands.Model.Graph.Group`
+- The output type of `New-PnPAzureADGroup` has changed to `PnP.PowerShell.Commands.Model.Graph.Group`
+- The output type of `Get-PnPUserProfileProperty` has changed to `SortedDictionary<string, object>`

README.md

@@ -1,6 +1,6 @@
 # PnP PowerShell
 
-**PnP PowerShell** is a .NET Core 3.1 / .NET Framework 4.6.2 based PowerShell Module providing over 650 cmdlets that work with Microsoft 365 environments such as SharePoint Online, Microsoft Teams, Microsoft Project, Security & Compliance, Azure Active Directory, and more.
+**PnP PowerShell** is a .NET 6 based PowerShell Module providing over 650 cmdlets that work with Microsoft 365 environments such as SharePoint Online, Microsoft Teams, Microsoft Project, Security & Compliance, Azure Active Directory, and more.
 
 Last version | Last nightly version
 -------------|---------------------
@@ -10,11 +10,31 @@ This module is a successor of the [PnP-PowerShell](https://github.com/pnp/pnp-po
 
 For more information about installing or upgrading to this module, please refer to the documentation at https://pnp.github.io/powershell/articles/index.html
 
+## IMPORTANT - New PnP PowerShell 2.x
+
+As the technologies behind PowerShell evolve, so will the PnP PowerShell module. 
+Since Microsoft is not supporting .NET 3.1 since December 2022, and .NET Framework not actively developed (and not cross platform), we are currently working on PnP PowerShell 2.x. 
+
+Therefore, **this new version going forward will not support PowerShell 5.1 nor the ISE**. 
+
+PnP PowerShell 2.x is already available should you wish to update now, and we have created a [guide](https://github.com/pnp/powershell/blob/dev/MIGRATE-1.0-to-2.0.md) for that purpose. If you are still using PowerShell 5.1 or the ISE, and want to use the latest major or nightly release, you will need to specify the required version like below: 
+
+`Install-Module PnP.PowerShell -RequiredVersion 1.12.0 -Force` or `Install-Module PnP.PowerShell -AllowPrerelease -RequiredVersion 1.12.80-nightly -Force`
+
+Both (1.x and 2.x) can be installed in the same machine with no conflict.
+
 ## Supportability and SLA
 
 This library is open-source and community provided library with active community providing support for it. This is not Microsoft provided module so there's no SLA or direct support for this open-source component from Microsoft. Please report any issues using the [issues list](https://github.com/pnp/powershell/issues).
 
 ---
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
 
-<img src="https://pnptelemetry.azurewebsites.net/pnp-powershell/readme" /> 
+
+<img src="https://m365-visitor-stats.azurewebsites.net/pnp-powershell/readme" />
+
+
+## Updating from 1.x to 2.x
+
+Please refer to [this page](MIGRATE-1.0-to-2.0.md) while performing an update from your 1.x version to 2.x version of PnP PowerShell.
+

build/Build-Debug.ps1

@@ -35,7 +35,7 @@ else {
 	$buildVersion = $versionObject.Patch + 1;
 }
 
-$configuration = "netcoreapp3.1"
+$configuration = "net6.0-windows"
 
 $version = "$($versionObject.Major).$($versionObject.Minor).$buildVersion"
 
@@ -91,7 +91,6 @@ if ($LASTEXITCODE -eq 0) {
 
 	$corePath = "$destinationFolder/Core"
 	$commonPath = "$destinationFolder/Common"
-	$frameworkPath = "$destinationFolder/Framework"
 
 	$assemblyExceptions = @("System.Memory.dll");
 
@@ -109,19 +108,13 @@ if ($LASTEXITCODE -eq 0) {
 		New-Item -Path $destinationFolder -ItemType Directory -Force | Out-Null
 		New-Item -Path "$destinationFolder\Core" -ItemType Directory -Force | Out-Null
 		New-Item -Path "$destinationFolder\Common" -ItemType Directory -Force | Out-Null
-		if (!$IsLinux -and !$IsMacOs) {
-			New-Item -Path "$destinationFolder\Framework" -ItemType Directory -Force | Out-Null
-		}
 
 		Write-Host "Copying files to $destinationFolder" -ForegroundColor Yellow
 
 		$commonFiles = [System.Collections.Generic.Hashset[string]]::new()
 		Copy-Item -Path "$PSScriptRoot/../resources/*.ps1xml" -Destination "$destinationFolder"
-		Get-ChildItem -Path "$PSScriptRoot/../src/ALC/bin/Debug/netstandard2.0" | Where-Object { $_.Extension -in '.dll', '.pdb' } | Foreach-Object { if (!$assemblyExceptions.Contains($_.Name)) { [void]$commonFiles.Add($_.Name) }; Copy-Item -LiteralPath $_.FullName -Destination $commonPath }
+		Get-ChildItem -Path "$PSScriptRoot/../src/ALC/bin/Debug/net6.0" | Where-Object { $_.Extension -in '.dll', '.pdb' } | Foreach-Object { if (!$assemblyExceptions.Contains($_.Name)) { [void]$commonFiles.Add($_.Name) }; Copy-Item -LiteralPath $_.FullName -Destination $commonPath }
 		Get-ChildItem -Path "$PSScriptRoot/../src/Commands/bin/Debug/$configuration" | Where-Object { $_.Extension -in '.dll', '.pdb' -and -not $commonFiles.Contains($_.Name) } | Foreach-Object { Copy-Item -LiteralPath $_.FullName -Destination $corePath }
-		if (!$IsLinux -and !$IsMacOs) {
-			Get-ChildItem -Path "$PSScriptRoot/../src/Commands/bin/Debug/net462" | Where-Object { $_.Extension -in '.dll', '.pdb' -and -not $commonFiles.Contains($_.Name) } | Foreach-Object { Copy-Item -LiteralPath $_.FullName -Destination $frameworkPath }
-		}
 	}
 	Catch {
 		Write-Error "Cannot copy files to $destinationFolder. Maybe a PowerShell session is still using the module or PS modules are hosted in a OneDrive synced location. In the latter case, manually delete $destinationFolder and try again."
@@ -140,36 +133,21 @@ if ($LASTEXITCODE -eq 0) {
 			else {
 				$destinationFolder = "$documentsFolder/PowerShell/Modules/PnP.PowerShell"
 			}
-			if ($PSVersionTable.PSVersion.Major -eq 5) {
-				Write-Host "Importing Framework version of assembly"
-				Import-Module -Name "$destinationFolder/Framework/PnP.PowerShell.dll" -DisableNameChecking
-			}
-			else {
-				Write-Host "Importing dotnet core version of assembly"
-				Import-Module -Name "$destinationFolder/Core/PnP.PowerShell.dll" -DisableNameChecking
-			}
+			Write-Host "Importing dotnet core version of assembly"
+			Import-Module -Name "$destinationFolder/Core/PnP.PowerShell.dll" -DisableNameChecking
 			$cmdlets = get-command -Module PnP.PowerShell | ForEach-Object { "`"$_`"" }
 			$cmdlets -Join ","
 		}
 		$cmdletsString = Start-ThreadJob -ScriptBlock $scriptBlock | Receive-Job -Wait
 
 		$manifest = "@{
-	NestedModules =  if (`$PSEdition -eq 'Core')
-	{
-		'Core/PnP.PowerShell.dll'
-	}
-	else
-	{
-		'Framework/PnP.PowerShell.dll'
-	}
+	NestedModules =  'Core/PnP.PowerShell.dll'
 	ModuleVersion = '$version'
 	Description = 'Microsoft 365 Patterns and Practices PowerShell Cmdlets'
 	GUID = '0b0430ce-d799-4f3b-a565-f0dca1f31e17'
 	Author = 'Microsoft 365 Patterns and Practices'
 	CompanyName = 'Microsoft 365 Patterns and Practices'
 	CompatiblePSEditions = @(`"Core`",`"Desktop`")
-	PowerShellVersion = '5.1'
-	DotNetFrameworkVersion = '4.6.2'
 	ProcessorArchitecture = 'None'
 	FunctionsToExport = '*'  
 	CmdletsToExport = @($cmdletsString)
@@ -194,4 +172,4 @@ if ($LASTEXITCODE -eq 0) {
 }
 
 $env:PnPCoreSdkPath = $localPnPCoreSdkPathValue
-$env:PnPFrameworkPath = $localPnPFrameworkPathValue
+$env:PnPFrameworkPath = $localPnPFrameworkPathValue