diff --git a/CHANGELOG.md b/CHANGELOG.md index d54ab71b61..26ce9562ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,8 +2,18 @@ # 1.22.126.1 +*TeamsTenantDialPlan + * Fixed an issue where the Export only extracted the first + normalization rule. + FIXES #1695 * DEPENDENCIES + * Updated all Microsoft.Graph * to 1.9.2; * Updated Microsoft.Teams to version 3.1.0; +* MISC + * Update automatic cmdlet documentation generation functions and prereqs. + * Adding cmdlet documentation to website + * Fixed an issue with the Export-M365DSCConfiguration cmdlet where it + would throw an error if no parameters were passed. # 1.22.119.2 diff --git a/Modules/Microsoft365DSC/DSCResources/MSFT_AADConditionalAccessPolicy/MSFT_AADConditionalAccessPolicy.psm1 b/Modules/Microsoft365DSC/DSCResources/MSFT_AADConditionalAccessPolicy/MSFT_AADConditionalAccessPolicy.psm1 index 6227697f4e..c27f57e018 100644 --- a/Modules/Microsoft365DSC/DSCResources/MSFT_AADConditionalAccessPolicy/MSFT_AADConditionalAccessPolicy.psm1 +++ b/Modules/Microsoft365DSC/DSCResources/MSFT_AADConditionalAccessPolicy/MSFT_AADConditionalAccessPolicy.psm1 @@ -1493,21 +1493,21 @@ function Set-TargetResource if ($IncludeDevices -or $ExcludeDevices) { #create and provision Device condition object if used - if (-not $conditions.Contains("Platforms")) + if (-not $conditions.Contains("Devices")) { - $conditions.Add("Platforms", @{ - ExcludePlatforms = @() - IncludePlatforms = @() + $conditions.Add("Devices", @{ + ExcludeDevices = @() + IncludeDevices = @() }) } else { - $conditions.Platforms.Add("ExcludeDevices", @()) - $conditions.Platforms.Add("IndludeDevices", @()) + $conditions.Devices.Add("ExcludeDevices", @()) + $conditions.Devices.Add("IndludeDevices", @()) } - $conditions.Platforms.IncludeDevices = $IncludeDevices + $conditions.Devices.IncludeDevices = $IncludeDevices #no translation or conversion needed - $conditions.Platforms.ExcludeDevices = $ExcludeDevices + $conditions.Devices.ExcludeDevices = $ExcludeDevices #no translation or conversion needed } Write-Verbose -Message "Set-Targetresource: process risk levels and app types" diff --git a/Modules/Microsoft365DSC/DSCResources/MSFT_IntuneAppProtectionPolicyiOS/MSFT_IntuneAppProtectionPolicyiOS.psm1 b/Modules/Microsoft365DSC/DSCResources/MSFT_IntuneAppProtectionPolicyiOS/MSFT_IntuneAppProtectionPolicyiOS.psm1 index 6ebb2a6b8d..a872669ff7 100644 --- a/Modules/Microsoft365DSC/DSCResources/MSFT_IntuneAppProtectionPolicyiOS/MSFT_IntuneAppProtectionPolicyiOS.psm1 +++ b/Modules/Microsoft365DSC/DSCResources/MSFT_IntuneAppProtectionPolicyiOS/MSFT_IntuneAppProtectionPolicyiOS.psm1 @@ -887,7 +887,7 @@ function Get-M365DSCIntuneAppProtectionPolicyiOSAssignmentJSON [System.String[]] $Assignments, - [Parameter(Mandatory = $true)] + [Parameter(Mandatory = $false)] [System.String[]] $Exclusions ) diff --git a/Modules/Microsoft365DSC/DSCResources/MSFT_TeamsTenantDialPlan/MSFT_TeamsTenantDialPlan.psm1 b/Modules/Microsoft365DSC/DSCResources/MSFT_TeamsTenantDialPlan/MSFT_TeamsTenantDialPlan.psm1 index 2415064bb5..2d9f7c5758 100644 --- a/Modules/Microsoft365DSC/DSCResources/MSFT_TeamsTenantDialPlan/MSFT_TeamsTenantDialPlan.psm1 +++ b/Modules/Microsoft365DSC/DSCResources/MSFT_TeamsTenantDialPlan/MSFT_TeamsTenantDialPlan.psm1 @@ -433,14 +433,7 @@ function Export-TargetResource if ($results.NormalizationRules.Count -gt 0) { - if ($results.NormalizationRules.GetType().Name -eq "Hashtable") - { - $results.NormalizationRules = Get-M365DSCNormalizationRulesAsString $results.NormalizationRules - } - else - { - $results.NormalizationRules = Get-M365DSCNormalizationRulesAsString $results.NormalizationRules[0] - } + $results.NormalizationRules = Get-M365DSCNormalizationRulesAsString $results.NormalizationRules } $currentDSCBlock = " TeamsTenantDialPlan " + (New-Guid).ToString() + "`r`n" $currentDSCBlock += " {`r`n" @@ -591,7 +584,7 @@ function Get-M365DSCNormalizationRulesAsString [OutputType([System.String])] param( [Parameter(Mandatory = $true)] - [System.Collections.Hashtable] + [System.Object[]] $Params ) @@ -599,23 +592,29 @@ function Get-M365DSCNormalizationRulesAsString { return $null } - $currentProperty = "@(MSFT_TeamsVoiceNormalizationRule{`r`n" - foreach ($key in $params.Keys) + $currentProperty = "@(" + + foreach ($rule in $params) { - if ($key -eq 'Priority') - { - $currentProperty += " " + $key + " = " + $params[$key] + "`r`n" - } - elseif ($key -eq "IsInternalExtension") - { - $currentProperty += " " + $key + " = `$" + $params[$key] + "`r`n" - } - else + $currentProperty += "MSFT_TeamsVoiceNormalizationRule{`r`n" + foreach ($key in $rule.Keys) { - $currentProperty += " " + $key + " = '" + $params[$key] + "'`r`n" + if ($key -eq 'Priority') + { + $currentProperty += " " + $key + " = " + $rule[$key] + "`r`n" + } + elseif ($key -eq "IsInternalExtension") + { + $currentProperty += " " + $key + " = `$" + $rule[$key] + "`r`n" + } + else + { + $currentProperty += " " + $key + " = '" + $rule[$key] + "'`r`n" + } } + $currentProperty += " }" } - $currentProperty += " })" + $currentProperty += ")" return $currentProperty } diff --git a/Modules/Microsoft365DSC/Dependencies/Manifest.psd1 b/Modules/Microsoft365DSC/Dependencies/Manifest.psd1 index 2ef4896312..bf5b039c76 100644 --- a/Modules/Microsoft365DSC/Dependencies/Manifest.psd1 +++ b/Modules/Microsoft365DSC/Dependencies/Manifest.psd1 @@ -10,55 +10,55 @@ }, @{ ModuleName = "Microsoft.Graph.Applications" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.Graph.Authentication" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.Graph.DeviceManagement" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.Graph.DeviceManagement.Administration" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.Graph.DeviceManagement.Enrolment" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.Graph.Devices.CorporateManagement" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.Graph.Groups" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.Graph.Identity.DirectoryManagement" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.Graph.Identity.Governance" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.Graph.Identity.SignIns" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.Graph.Planner" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.Graph.Teams" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.Graph.Users" - RequiredVersion = "1.9.1" + RequiredVersion = "1.9.2" }, @{ ModuleName = "Microsoft.PowerApps.Administration.PowerShell" diff --git a/Modules/Microsoft365DSC/Microsoft365DSC.psd1 b/Modules/Microsoft365DSC/Microsoft365DSC.psd1 index c824ab9752..86024a5102 100644 --- a/Modules/Microsoft365DSC/Microsoft365DSC.psd1 +++ b/Modules/Microsoft365DSC/Microsoft365DSC.psd1 @@ -3,7 +3,7 @@ # # Generated by: Microsoft Corporation # -# Generated on: 2022-01-20 +# Generated on: 2022-01-26 @{ @@ -11,7 +11,7 @@ # RootModule = '' # Version number of this module. - ModuleVersion = '1.22.119.2' + ModuleVersion = '1.22.126.1' # Supported PSEditions # CompatiblePSEditions = @() @@ -131,19 +131,18 @@ IconUri = 'https://github.com/microsoft/Microsoft365DSC/blob/Dev/Modules/Microsoft365DSC/Dependencies/Images/Logo.png?raw=true' # ReleaseNotes of this module - ReleaseNotes = " - * EXOOrganizationConfig - * Added support for the new SendFromAliasEnabled parameter; - * Fixed issue where the name of the parameter in the module and - in the schema differed; - FIXES #1689 - * EXORoleAssignmentPolicy - * Fixed logic to update roles assigned to an existing policy; - FIXES #1538 - MISC - * Updated logic for Report generation so that it no longer requires the - same module version as defined in the configuration installed on the - system where the report is being generated from." + ReleaseNotes = "*TeamsTenantDialPlan + * Fixed an issue where the Export only extracted the first + normalization rule. + FIXES #1695 + * DEPENDENCIES + * Updated all Microsoft.Graph * to 1.9.2; + * Updated Microsoft.Teams to version 3.1.0; + * MISC + * Update automatic cmdlet documentation generation functions and prereqs. + * Adding cmdlet documentation to website + * Fixed an issue with the Export-M365DSCConfiguration cmdlet where it + would throw an error if no parameters were passed." # Flag to indicate whether the module requires explicit user acceptance for install/update # RequireLicenseAcceptance = $false diff --git a/Modules/Microsoft365DSC/Modules/M365DSCAgent.psm1 b/Modules/Microsoft365DSC/Modules/M365DSCAgent.psm1 index cef3d616db..61ba686653 100644 --- a/Modules/Microsoft365DSC/Modules/M365DSCAgent.psm1 +++ b/Modules/Microsoft365DSC/Modules/M365DSCAgent.psm1 @@ -2,6 +2,9 @@ .Description This function tests the configuration of the agent +.Example +Test-M365DSCAgent + .Functionality Public #> @@ -128,6 +131,12 @@ Specifies that a PFX export should be created for the generated certificate. .Parameter Password Specifies the password for the PFX file. +.Example +Set-M365DSCAgentCertificateConfiguration -KeepCertificate + +.Example +Set-M365DSCAgentCertificateConfiguration -GeneratePFX -Password 'P@ssword123!' + .Functionality Public #> diff --git a/Modules/Microsoft365DSC/Modules/M365DSCLogEngine.psm1 b/Modules/Microsoft365DSC/Modules/M365DSCLogEngine.psm1 index 8f715d4be0..33f89b439a 100644 --- a/Modules/Microsoft365DSC/Modules/M365DSCLogEngine.psm1 +++ b/Modules/Microsoft365DSC/Modules/M365DSCLogEngine.psm1 @@ -177,6 +177,12 @@ Specify if the results should be anonymized. .Parameter Url (Anonymize=True) The url that should be renamed. +.Example +Export-M365DSCDiagnosticData -ExportFilePath C:\Temp\DSCLogsExport.zip -NumberOfDays 3 + +.Example +Export-M365DSCDiagnosticData -ExportFilePath C:\Temp\DSCLogsExport.zip -Anonymize -Server spfe -Domain contoso.com -Url sharepoint.contoso.com + .Functionality Public #> diff --git a/Modules/Microsoft365DSC/Modules/M365DSCPermissions.psm1 b/Modules/Microsoft365DSC/Modules/M365DSCPermissions.psm1 index 34c476980b..7a919d95d9 100644 --- a/Modules/Microsoft365DSC/Modules/M365DSCPermissions.psm1 +++ b/Modules/Microsoft365DSC/Modules/M365DSCPermissions.psm1 @@ -8,6 +8,9 @@ both for reading and updating. .Parameter ResourceNameList An array of resource names for which the permissions should be determined. +.Example +Get-M365DSCCompiledPermissionList -ResourceNameList @('O365User', 'AADApplication') + .Functionality Public #> @@ -88,6 +91,12 @@ Specifies that the permissions should be determined for all resources. .Parameter Type For which action should the permissions be updated: Read or Update. +.Example +Update-M365DSCAllowedGraphScopes -ResourceNameList @('O365User', 'AADApplication') -Type 'Read' + +.Example +Update-M365DSCAllowedGraphScopes -All -Type 'Update' -Environment 'Global' + .Functionality Public #> @@ -170,6 +179,9 @@ It is compiling a permissions list based on all used Graph cmdlets in the resour retrieving the permissions for these cmdlets from the Graph. Then it updates the settings.json file +.Example +Update-M365DSCResourcesSettingsJSON + .Functionality Public #> diff --git a/Modules/Microsoft365DSC/Modules/M365DSCReport.psm1 b/Modules/Microsoft365DSC/Modules/M365DSCReport.psm1 index e0b59c87dc..e4182bcd26 100644 --- a/Modules/Microsoft365DSC/Modules/M365DSCReport.psm1 +++ b/Modules/Microsoft365DSC/Modules/M365DSCReport.psm1 @@ -306,6 +306,12 @@ The path to the exported DSC configuration that the report should be created for .Parameter OutputPath The output path of the report. +.Example +New-M365DSCReportFromConfiguration -Type 'HTML' -ConfigurationPath 'C:\DSC\' -OutputPath 'C:\Dsc\M365Report.html' + +.Example +New-M365DSCReportFromConfiguration -Type 'Excel' -ConfigurationPath 'C:\DSC\' -OutputPath 'C:\Dsc\M365Report.xlsx' + .Functionality Public #> @@ -705,6 +711,12 @@ Specifies that file that contains a custom header for the report. .Parameter Delta An array with difference, already compiled from another source. +.Example +New-M365DSCDeltaReport -Source 'C:\DSC\Source.ps1' -Destination 'C:\DSC\Destination.ps1' -OutputPath 'C:\Dsc\DeltaReport.html' + +.Example +New-M365DSCDeltaReport -Source 'C:\DSC\Source.ps1' -Destination 'C:\DSC\Destination.ps1' -OutputPath 'C:\Dsc\DeltaReport.html' -DriftOnly $true + .Functionality Public #> diff --git a/Modules/Microsoft365DSC/Modules/M365DSCTelemetryEngine.psm1 b/Modules/Microsoft365DSC/Modules/M365DSCTelemetryEngine.psm1 index 92f3e59aa8..01f39100fe 100644 --- a/Modules/Microsoft365DSC/Modules/M365DSCTelemetryEngine.psm1 +++ b/Modules/Microsoft365DSC/Modules/M365DSCTelemetryEngine.psm1 @@ -231,6 +231,9 @@ Specifies the Instrumention Key to be used to send the telemetry to. .Parameter ProjectName Specifies the name of the project to store the telemetry data under. +.Example +Set-M365DSCTelemetryOption -Enabled $false + .Functionality Public #> @@ -274,6 +277,9 @@ function Set-M365DSCTelemetryOption .Description This function gets the configuration for the M365DSC telemetry feature +.Example +Get-M365DSCTelemetryOption + .Functionality Public #> diff --git a/Modules/Microsoft365DSC/Modules/M365DSCUtil.psm1 b/Modules/Microsoft365DSC/Modules/M365DSCUtil.psm1 index 5bd79fb54e..def2d36f17 100644 --- a/Modules/Microsoft365DSC/Modules/M365DSCUtil.psm1 +++ b/Modules/Microsoft365DSC/Modules/M365DSCUtil.psm1 @@ -77,7 +77,7 @@ function Get-TeamByName $loopCounter = 0 do { - $team = Get-Team -DisplayName $TeamName + $team = Get-Team -DisplayName $TeamName | Where-Object -FilterScript {$_.DisplayName -eq $TeamName} if ($null -eq $team) { Start-Sleep 5 @@ -859,6 +859,15 @@ Specifies the password of the PFX file which is used for authentication. .Parameter CertificatePath Specifies the path of the PFX file which is used for authentication. +.Example +Export-M365DSCConfiguration -Components @("AADApplication", "AADConditionalAccessPolicy", "AADGroupsSettings") -Credential $Credential + +.Example +Export-M365DSCConfiguration -Mode 'Default' -ApplicationId '2560bb7c-bc85-415f-a799-841e10ec4f9a' -TenantId 'contoso.sharepoint.com' -ApplicationSecret 'abcdefghijkl' + +.Example +Export-M365DSCConfiguration -Components @("AADApplication", "AADConditionalAccessPolicy", "AADGroupsSettings") -Credential $Credential -Path 'C:\DSC\Config.ps1' + .Functionality Public #> @@ -942,21 +951,11 @@ function Export-M365DSCConfiguration $data = [System.Collections.Generic.Dictionary[[String], [String]]]::new() $data.Add("Event", "Extraction") - if (-not [System.String]::IsNullOrEmpty($TenantId)) - { - $data.Add("Tenant", $TenantId) - } - else - { - $tenant = $Credential.UserName.Split('@')[1] - $data.Add("Tenant", $tenant) - } $data.Add("Path", [System.String]::IsNullOrEmpty($Path)) $data.Add("FileName", $null -ne [System.String]::IsNullOrEmpty($FileName)) $data.Add("Components", $null -ne $Components) $data.Add("Workloads", $null -ne $Workloads) $data.Add("MaxProcesses", $null -ne $MaxProcesses) - Add-M365DSCTelemetryEvent -Data $data #endregion $outdatedOrMissingAssemblies = Test-M365DSCDependencies @@ -994,6 +993,17 @@ function Export-M365DSCConfiguration $Credential = Get-Credential } + if (-not [System.String]::IsNullOrEmpty($TenantId)) + { + $data.Add("Tenant", $TenantId) + } + else + { + $tenant = $Credential.UserName.Split('@')[1] + $data.Add("Tenant", $tenant) + } + + Add-M365DSCTelemetryEvent -Data $data if ($LaunchWebUI) { explorer "https://export.microsoft365dsc.com" @@ -1098,6 +1108,9 @@ function Confirm-M365DSCDependencies .Description This function re-imports all M365DSC dependencies, if not properly done before +.Example +Import-M365DSCDependencies + .Functionality Public #> @@ -1870,6 +1883,9 @@ function ConvertTo-SPOUserProfilePropertyInstanceString .Description This function downloads and installs the Dev branch of Microsoft365DSC on the local machine +.Example +Install-M365DSCDevBranch + .Functionality Public #> @@ -2088,6 +2104,12 @@ Specifies the credentials that will be used for authentication. .Parameter HeaderFilePath Specifies that file that contains a custom header for the report. +.Example +Assert-M365DSCBlueprint -BluePrintUrl 'C:\DS\blueprint.m365' -OutputReportPath 'C:\DSC\BlueprintReport.html' + +.Example +Assert-M365DSCBlueprint -BluePrintUrl 'C:\DS\blueprint.m365' -OutputReportPath 'C:\DSC\BlueprintReport.html' -Credentials $credentials -HeaderFilePath 'C:\DSC\ReportCustomHeader.html' + .Functionality Public #> @@ -2194,6 +2216,9 @@ function Assert-M365DSCBlueprint .Description This function checks if new versions are available for the M365DSC dependencies +.Example +Test-M365DSCDependenciesForNewVersions + .Functionality Public #> @@ -2267,6 +2292,12 @@ This function installs all missing M365DSC dependencies .Parameter Force Specifies that all dependencies should be forcefully imported again. +.Example +Update-M365DSCDependencies + +.Example +Update-M365DSCDependencies -Force + .Functionality Public #> @@ -2621,6 +2652,9 @@ function Get-M365DSCExportContentForResource This function check if the currently installed version of M365DSC is the most recent one, available in the PowerShell Gallery +.Example +Test-M365DSCNewVersionAvailable + .Functionality Public #> @@ -2743,6 +2777,9 @@ function Get-M365DSCComponentsForAuthenticationType .Description This function gets all available M365DSC resources in the module +.Example +Get-M365DSCAllResources + .Functionality Public #> @@ -2802,6 +2839,9 @@ This function returns the used workloads for the specified DSC resources .Parameter ResourceNames Specifies the resources for which the workloads should be determined. +.Example +Get-M365DSCWorkloadsListFromResourceNames -ResourceNames O365User + .Functionality Public #> @@ -3000,6 +3040,13 @@ function New-M365DSCCmdletDocumentation $null = $output.AppendLine("**$($cmd.OutputType)**") $null = $output.AppendLine('') } + else + { + $null = $output.AppendLine('## Output') + $null = $output.AppendLine('') + $null = $output.AppendLine('This function does not generate any output.') + $null = $output.AppendLine('') + } $ast = $cmd.ScriptBlock.Ast $parameters = $null @@ -3040,6 +3087,18 @@ function New-M365DSCCmdletDocumentation $null = $output.AppendLine('This function does not have any input parameters.') } + if ($helpInfo.examples.example.Count -ne 0) + { + $null = $output.AppendLine('## Examples') + $null = $output.AppendLine('') + foreach ($example in $helpInfo.examples.example) + { + $null = $output.AppendLine($example.title) + $null = $output.AppendLine("``$($example.code)``") + $null = $output.AppendLine('') + } + } + $savePath = Join-Path -Path $OutputPath -ChildPath "$commandName.md" $null = Out-File ` -InputObject ($output.ToString() -replace '\r?\n', "`r`n") ` diff --git a/docs/docs/user-guide/cmdlets/Assert-M365DSCBlueprint.md b/docs/docs/user-guide/cmdlets/Assert-M365DSCBlueprint.md new file mode 100644 index 0000000000..0afdc91cd3 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Assert-M365DSCBlueprint.md @@ -0,0 +1,32 @@ +# Assert-M365DSCBlueprint + +## Description + +This function compares a created export with the specified M365DSC Blueprint + +## Output + +This function does not generate any output. + +## Parameters + +| Parameter | Required | DataType | Default Value | Allowed Values | Description | +| --- | --- | --- | --- | --- | --- | +| BluePrintUrl | True | String | | | Specifies the url to the blueprint to which the tenant should be compared. | +| OutputReportPath | True | String | | | Specifies the path of the report that will be created. | +| Credentials | True | PSCredential | | | Specifies the credentials that will be used for authentication. | +| HeaderFilePath | False | String | | | Specifies that file that contains a custom header for the report. | + +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Assert-M365DSCBlueprint -BluePrintUrl 'C:\DS\blueprint.m365' -OutputReportPath 'C:\DSC\BlueprintReport.html'` + + +-------------------------- EXAMPLE 2 -------------------------- + +`Assert-M365DSCBlueprint -BluePrintUrl 'C:\DS\blueprint.m365' -OutputReportPath 'C:\DSC\BlueprintReport.html' -Credentials $credentials -HeaderFilePath 'C:\DSC\ReportCustomHeader.html'` + + + diff --git a/docs/docs/user-guide/cmdlets/Export-M365DSCConfiguration.md b/docs/docs/user-guide/cmdlets/Export-M365DSCConfiguration.md new file mode 100644 index 0000000000..dc7277698e --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Export-M365DSCConfiguration.md @@ -0,0 +1,49 @@ +# Export-M365DSCConfiguration + +## Description + +This is the main Microsoft365DSC.Reverse function that extracts the DSC configuration from an existing Microsoft 365 Tenant. + +## Output + +This function does not generate any output. + +## Parameters + +| Parameter | Required | DataType | Default Value | Allowed Values | Description | +| --- | --- | --- | --- | --- | --- | +| LaunchWebUI | False | SwitchParameter | | | Adding this parameter will open the WebUI in a browser. | +| Path | False | String | | | Specifies the path in which the exported DSC configuration should be stored. | +| FileName | False | String | | | Specifies the name of the file in which the exported DSC configuration should be stored. | +| ConfigurationName | False | String | | | Specifies the name of the configuration that will be generated. | +| Components | False | String[] | | | Specifies the components for which an export should be created. | +| Workloads | False | String[] | | AAD, SPO, EXO, INTUNE, SC, OD, O365, PLANNER, PP, TEAMS | Specifies the workload for which an export should be created for all resources. | +| Mode | False | String | Default | Lite, Default, Full | Specifies the mode of the export: Lite, Default or Full. | +| MaxProcesses | False | Object | | | Specifies the maximum number of processes that should run simultanious. | +| GenerateInfo | False | Boolean | | | Specifies if each exported resource should get a link to the Wiki article of the resource. | +| ApplicationId | False | String | | | Specifies the application id to be used for authentication. | +| TenantId | False | String | | | Specifies the id of the tenant. | +| ApplicationSecret | False | String | | | Specifies the application secret of the application to be used for authentication. | +| CertificateThumbprint | False | String | | | Specifies the thumbprint to be used for authentication. | +| Credential | False | PSCredential | | | Specifies the credentials to be used for authentication. | +| CertificatePassword | False | PSCredential | | | Specifies the password of the PFX file which is used for authentication. | +| CertificatePath | False | String | | | Specifies the path of the PFX file which is used for authentication. | + +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Export-M365DSCConfiguration -Components @("AADApplication", "AADConditionalAccessPolicy", "AADGroupsSettings") -Credential $Credential` + + +-------------------------- EXAMPLE 2 -------------------------- + +`Export-M365DSCConfiguration -Mode 'Default' -ApplicationId '2560bb7c-bc85-415f-a799-841e10ec4f9a' -TenantId 'contoso.sharepoint.com' -ApplicationSecret 'abcdefghijkl'` + + +-------------------------- EXAMPLE 3 -------------------------- + +`Export-M365DSCConfiguration -Components @("AADApplication", "AADConditionalAccessPolicy", "AADGroupsSettings") -Credential $Credential -Path 'C:\DSC\Config.ps1'` + + + diff --git a/docs/docs/user-guide/cmdlets/Export-M365DSCDiagnosticData.md b/docs/docs/user-guide/cmdlets/Export-M365DSCDiagnosticData.md new file mode 100644 index 0000000000..37ef8c3867 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Export-M365DSCDiagnosticData.md @@ -0,0 +1,37 @@ +# Export-M365DSCDiagnosticData + +## Description + +This function creates a ZIP package with a collection of troubleshooting information, +like Verbose logs, M365DSC event log, PowerShell version, OS versions and LCM config. +It is also able to anonymize this information (as much as possible), so important +information isn't shared. + +## Output + +This function does not generate any output. + +## Parameters + +| Parameter | Required | DataType | Default Value | Allowed Values | Description | +| --- | --- | --- | --- | --- | --- | +| ExportFilePath | True | String | | | The file path to the ZIP file that should be created. | +| NumberOfDays | False | UInt32 | 7 | | The number of days of logs that should be exported. | +| Anonymize | False | SwitchParameter | | | Specify if the results should be anonymized. | +| Server | True | String | | | (Anonymize=True) The server name that should be renamed. | +| Domain | True | String | | | (Anonymize=True) The domain that should be renamed. | +| Url | True | String | | | (Anonymize=True) The url that should be renamed. | + +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Export-M365DSCDiagnosticData -ExportFilePath C:\Temp\DSCLogsExport.zip -NumberOfDays 3` + + +-------------------------- EXAMPLE 2 -------------------------- + +`Export-M365DSCDiagnosticData -ExportFilePath C:\Temp\DSCLogsExport.zip -Anonymize -Server spfe -Domain contoso.com -Url sharepoint.contoso.com` + + + diff --git a/docs/docs/user-guide/cmdlets/Get-M365DSCAllResources.md b/docs/docs/user-guide/cmdlets/Get-M365DSCAllResources.md new file mode 100644 index 0000000000..c95bc347b7 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Get-M365DSCAllResources.md @@ -0,0 +1,22 @@ +# Get-M365DSCAllResources + +## Description + +This function gets all available M365DSC resources in the module + +## Output + +This function outputs information as the following type: +**System.String[]** + +## Parameters + +This function does not have any input parameters. +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Get-M365DSCAllResources` + + + diff --git a/docs/docs/user-guide/cmdlets/Get-M365DSCCompiledPermissionList.md b/docs/docs/user-guide/cmdlets/Get-M365DSCCompiledPermissionList.md new file mode 100644 index 0000000000..450756db51 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Get-M365DSCCompiledPermissionList.md @@ -0,0 +1,26 @@ +# Get-M365DSCCompiledPermissionList + +## Description + +This function lists all Graph permissions required for the specified resources, +both for reading and updating. + +## Output + +This function outputs information as the following type: +**System.Collections.Hashtable** + +## Parameters + +| Parameter | Required | DataType | Default Value | Allowed Values | Description | +| --- | --- | --- | --- | --- | --- | +| ResourceNameList | True | String[] | | | An array of resource names for which the permissions should be determined. | + +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Get-M365DSCCompiledPermissionList -ResourceNameList @('O365User', 'AADApplication')` + + + diff --git a/docs/docs/user-guide/cmdlets/Get-M365DSCTelemetryOption.md b/docs/docs/user-guide/cmdlets/Get-M365DSCTelemetryOption.md new file mode 100644 index 0000000000..a8e37ba5fc --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Get-M365DSCTelemetryOption.md @@ -0,0 +1,21 @@ +# Get-M365DSCTelemetryOption + +## Description + +This function gets the configuration for the M365DSC telemetry feature + +## Output + +This function does not generate any output. + +## Parameters + +This function does not have any input parameters. +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Get-M365DSCTelemetryOption` + + + diff --git a/docs/docs/user-guide/cmdlets/Get-M365DSCWorkloadsListFromResourceNames.md b/docs/docs/user-guide/cmdlets/Get-M365DSCWorkloadsListFromResourceNames.md new file mode 100644 index 0000000000..77dcc690ff --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Get-M365DSCWorkloadsListFromResourceNames.md @@ -0,0 +1,25 @@ +# Get-M365DSCWorkloadsListFromResourceNames + +## Description + +This function returns the used workloads for the specified DSC resources + +## Output + +This function outputs information as the following type: +**System.Boolean** + +## Parameters + +| Parameter | Required | DataType | Default Value | Allowed Values | Description | +| --- | --- | --- | --- | --- | --- | +| ResourceNames | True | String[] | | | Specifies the resources for which the workloads should be determined. | + +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Get-M365DSCWorkloadsListFromResourceNames -ResourceNames O365User` + + + diff --git a/docs/docs/user-guide/cmdlets/Import-M365DSCDependencies.md b/docs/docs/user-guide/cmdlets/Import-M365DSCDependencies.md new file mode 100644 index 0000000000..ef5b444962 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Import-M365DSCDependencies.md @@ -0,0 +1,21 @@ +# Import-M365DSCDependencies + +## Description + +This function re-imports all M365DSC dependencies, if not properly done before + +## Output + +This function does not generate any output. + +## Parameters + +This function does not have any input parameters. +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Import-M365DSCDependencies` + + + diff --git a/docs/docs/user-guide/cmdlets/Install-M365DSCDevBranch.md b/docs/docs/user-guide/cmdlets/Install-M365DSCDevBranch.md new file mode 100644 index 0000000000..231817d4f4 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Install-M365DSCDevBranch.md @@ -0,0 +1,21 @@ +# Install-M365DSCDevBranch + +## Description + +This function downloads and installs the Dev branch of Microsoft365DSC on the local machine + +## Output + +This function does not generate any output. + +## Parameters + +This function does not have any input parameters. +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Install-M365DSCDevBranch` + + + diff --git a/docs/docs/user-guide/cmdlets/New-M365DSCDeltaReport.md b/docs/docs/user-guide/cmdlets/New-M365DSCDeltaReport.md new file mode 100644 index 0000000000..48addfe2f3 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/New-M365DSCDeltaReport.md @@ -0,0 +1,36 @@ +# New-M365DSCDeltaReport + +## Description + +This function creates a delta HTML report between two provided exported +DSC configurations + +## Output + +This function does not generate any output. + +## Parameters + +| Parameter | Required | DataType | Default Value | Allowed Values | Description | +| --- | --- | --- | --- | --- | --- | +| Source | False | String | | | The source DSC configuration to compare from. | +| Destination | False | String | | | The destination DSC configuration to compare with. | +| OutputPath | False | String | | | The output path of the delta report. | +| DriftOnly | False | Boolean | | | Specifies that only difference should be in the report. | +| IsBlueprintAssessment | False | Boolean | | | Specifies that the report is a comparison with a Blueprint. | +| HeaderFilePath | False | String | | | Specifies that file that contains a custom header for the report. | +| Delta | False | Array | | | An array with difference, already compiled from another source. | + +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`New-M365DSCDeltaReport -Source 'C:\DSC\Source.ps1' -Destination 'C:\DSC\Destination.ps1' -OutputPath 'C:\Dsc\DeltaReport.html'` + + +-------------------------- EXAMPLE 2 -------------------------- + +`New-M365DSCDeltaReport -Source 'C:\DSC\Source.ps1' -Destination 'C:\DSC\Destination.ps1' -OutputPath 'C:\Dsc\DeltaReport.html' -DriftOnly $true` + + + diff --git a/docs/docs/user-guide/cmdlets/New-M365DSCReportFromConfiguration.md b/docs/docs/user-guide/cmdlets/New-M365DSCReportFromConfiguration.md new file mode 100644 index 0000000000..b4a09b8cc2 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/New-M365DSCReportFromConfiguration.md @@ -0,0 +1,32 @@ +# New-M365DSCReportFromConfiguration + +## Description + +This function creates a report from the specified exported configuration, +either in HTML or Excel format + +## Output + +This function does not generate any output. + +## Parameters + +| Parameter | Required | DataType | Default Value | Allowed Values | Description | +| --- | --- | --- | --- | --- | --- | +| Type | True | String | | Excel, HTML | The type of report that should be created: Excel or HTML. | +| ConfigurationPath | True | String | | | The path to the exported DSC configuration that the report should be created for. | +| OutputPath | True | String | | | The output path of the report. | + +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`New-M365DSCReportFromConfiguration -Type 'HTML' -ConfigurationPath 'C:\DSC\' -OutputPath 'C:\Dsc\M365Report.html'` + + +-------------------------- EXAMPLE 2 -------------------------- + +`New-M365DSCReportFromConfiguration -Type 'Excel' -ConfigurationPath 'C:\DSC\' -OutputPath 'C:\Dsc\M365Report.xlsx'` + + + diff --git a/docs/docs/user-guide/cmdlets/Set-M365DSCAgentCertificateConfiguration.md b/docs/docs/user-guide/cmdlets/Set-M365DSCAgentCertificateConfiguration.md new file mode 100644 index 0000000000..cd1ba5cf12 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Set-M365DSCAgentCertificateConfiguration.md @@ -0,0 +1,33 @@ +# Set-M365DSCAgentCertificateConfiguration + +## Description + +This function configures the LCM with a self signed encryption certificate + +## Output + +This function outputs information as the following type: +**System.String** + +## Parameters + +| Parameter | Required | DataType | Default Value | Allowed Values | Description | +| --- | --- | --- | --- | --- | --- | +| KeepCertificate | False | SwitchParameter | | | Specifies that the temporarily created CER file should not be deleted. | +| ForceRenew | False | SwitchParameter | | | Specifies that a new certificate should be forcefully created. | +| GeneratePFX | False | SwitchParameter | | | Specifies that a PFX export should be created for the generated certificate. | +| Password | False | String | Temp!P@ss123 | | Specifies the password for the PFX file. | + +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Set-M365DSCAgentCertificateConfiguration -KeepCertificate` + + +-------------------------- EXAMPLE 2 -------------------------- + +`Set-M365DSCAgentCertificateConfiguration -GeneratePFX -Password 'P@ssword123!'` + + + diff --git a/docs/docs/user-guide/cmdlets/Set-M365DSCTelemetryOption.md b/docs/docs/user-guide/cmdlets/Set-M365DSCTelemetryOption.md new file mode 100644 index 0000000000..ac9c6626cf --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Set-M365DSCTelemetryOption.md @@ -0,0 +1,26 @@ +# Set-M365DSCTelemetryOption + +## Description + +This function configures the telemetry feature of M365DSC + +## Output + +This function does not generate any output. + +## Parameters + +| Parameter | Required | DataType | Default Value | Allowed Values | Description | +| --- | --- | --- | --- | --- | --- | +| Enabled | False | Boolean | | | Enables or disables telemetry collection. | +| InstrumentationKey | False | String | | | Specifies the Instrumention Key to be used to send the telemetry to. | +| ProjectName | False | String | | | Specifies the name of the project to store the telemetry data under. | + +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Set-M365DSCTelemetryOption -Enabled $false` + + + diff --git a/docs/docs/user-guide/cmdlets/Test-M365DSCAgent.md b/docs/docs/user-guide/cmdlets/Test-M365DSCAgent.md new file mode 100644 index 0000000000..0510577826 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Test-M365DSCAgent.md @@ -0,0 +1,21 @@ +# Test-M365DSCAgent + +## Description + +This function tests the configuration of the agent + +## Output + +This function does not generate any output. + +## Parameters + +This function does not have any input parameters. +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Test-M365DSCAgent` + + + diff --git a/docs/docs/user-guide/cmdlets/Test-M365DSCDependenciesForNewVersions.md b/docs/docs/user-guide/cmdlets/Test-M365DSCDependenciesForNewVersions.md new file mode 100644 index 0000000000..1ecd2fefb2 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Test-M365DSCDependenciesForNewVersions.md @@ -0,0 +1,21 @@ +# Test-M365DSCDependenciesForNewVersions + +## Description + +This function checks if new versions are available for the M365DSC dependencies + +## Output + +This function does not generate any output. + +## Parameters + +This function does not have any input parameters. +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Test-M365DSCDependenciesForNewVersions` + + + diff --git a/docs/docs/user-guide/cmdlets/Test-M365DSCNewVersionAvailable.md b/docs/docs/user-guide/cmdlets/Test-M365DSCNewVersionAvailable.md new file mode 100644 index 0000000000..3ede86f477 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Test-M365DSCNewVersionAvailable.md @@ -0,0 +1,22 @@ +# Test-M365DSCNewVersionAvailable + +## Description + +This function check if the currently installed version of M365DSC is the most recent one, +available in the PowerShell Gallery + +## Output + +This function does not generate any output. + +## Parameters + +This function does not have any input parameters. +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Test-M365DSCNewVersionAvailable` + + + diff --git a/docs/docs/user-guide/cmdlets/Update-M365DSCAllowedGraphScopes.md b/docs/docs/user-guide/cmdlets/Update-M365DSCAllowedGraphScopes.md new file mode 100644 index 0000000000..5f063fb26f --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Update-M365DSCAllowedGraphScopes.md @@ -0,0 +1,32 @@ +# Update-M365DSCAllowedGraphScopes + +## Description + +This function updates the required permissions in the Graph API for the specified resources and type + +## Output + +This function does not generate any output. + +## Parameters + +| Parameter | Required | DataType | Default Value | Allowed Values | Description | +| --- | --- | --- | --- | --- | --- | +| ResourceNameList | False | String[] | | | An array of resource names for which the permissions should be determined. | +| All | False | SwitchParameter | | | Specifies that the permissions should be determined for all resources. | +| Type | True | String | | Read, Update | For which action should the permissions be updated: Read or Update. | +| Environment | True | String | Global | Global, China, USGov, USGovDoD, Germany | | + +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Update-M365DSCAllowedGraphScopes -ResourceNameList @('O365User', 'AADApplication') -Type 'Read'` + + +-------------------------- EXAMPLE 2 -------------------------- + +`Update-M365DSCAllowedGraphScopes -All -Type 'Update' -Environment 'Global'` + + + diff --git a/docs/docs/user-guide/cmdlets/Update-M365DSCDependencies.md b/docs/docs/user-guide/cmdlets/Update-M365DSCDependencies.md new file mode 100644 index 0000000000..50bc54564c --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Update-M365DSCDependencies.md @@ -0,0 +1,29 @@ +# Update-M365DSCDependencies + +## Description + +This function installs all missing M365DSC dependencies + +## Output + +This function does not generate any output. + +## Parameters + +| Parameter | Required | DataType | Default Value | Allowed Values | Description | +| --- | --- | --- | --- | --- | --- | +| Force | False | SwitchParameter | | | Specifies that all dependencies should be forcefully imported again. | + +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Update-M365DSCDependencies` + + +-------------------------- EXAMPLE 2 -------------------------- + +`Update-M365DSCDependencies -Force` + + + diff --git a/docs/docs/user-guide/cmdlets/Update-M365DSCResourcesSettingsJSON.md b/docs/docs/user-guide/cmdlets/Update-M365DSCResourcesSettingsJSON.md new file mode 100644 index 0000000000..dc0148af15 --- /dev/null +++ b/docs/docs/user-guide/cmdlets/Update-M365DSCResourcesSettingsJSON.md @@ -0,0 +1,24 @@ +# Update-M365DSCResourcesSettingsJSON + +## Description + +This function updates the settings.json files for all resources that use Graph cmdlets. +It is compiling a permissions list based on all used Graph cmdlets in the resource and +retrieving the permissions for these cmdlets from the Graph. Then it updates the +settings.json file + +## Output + +This function does not generate any output. + +## Parameters + +This function does not have any input parameters. +## Examples + +-------------------------- EXAMPLE 1 -------------------------- + +`Update-M365DSCResourcesSettingsJSON` + + + diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 7782e0e0f2..161a4a2dd6 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -7,6 +7,26 @@ nav: - User Guide: - 'Get Started': 'user-guide/get-started/complete-story.md' - Advanced: 'user-guide/advanced/create-blueprint.md' + - Cmdlets: + - 'Assert-M365DSCBlueprint': 'user-guide/cmdlets/Assert-M365DSCBlueprint.md' + - 'Export-M365DSCConfiguration': 'user-guide/cmdlets/Export-M365DSCConfiguration.md' + - 'Export-M365DSCDiagnosticData': 'user-guide/cmdlets/Export-M365DSCDiagnosticData.md' + - 'Get-M365DSCAllResources': 'user-guide/cmdlets/Get-M365DSCAllResources.md' + - 'Get-M365DSCCompiledPermissionList': 'user-guide/cmdlets/Get-M365DSCCompiledPermissionList.md' + - 'Get-M365DSCTelemetryOption': 'user-guide/cmdlets/Get-M365DSCTelemetryOption.md' + - 'Get-M365DSCWorkloadsListFromResourceNames': 'user-guide/cmdlets/Get-M365DSCWorkloadsListFromResourceNames.md' + - 'Import-M365DSCDependencies': 'user-guide/cmdlets/Import-M365DSCDependencies.md' + - 'Install-M365DSCDevBranch': 'user-guide/cmdlets/Install-M365DSCDevBranch.md' + - 'New-M365DSCDeltaReport': 'user-guide/cmdlets/New-M365DSCDeltaReport.md' + - 'New-M365DSCReportFromConfiguration': 'user-guide/cmdlets/New-M365DSCReportFromConfiguration.md' + - 'Set-M365DSCAgentCertificateConfiguration': 'user-guide/cmdlets/Set-M365DSCAgentCertificateConfiguration.md' + - 'Set-M365DSCTelemetryOption': 'user-guide/cmdlets/Set-M365DSCTelemetryOption.md' + - 'Test-M365DSCAgent': 'user-guide/cmdlets/Test-M365DSCAgent.md' + - 'Test-M365DSCDependenciesForNewVersions': 'user-guide/cmdlets/Test-M365DSCDependenciesForNewVersions.md' + - 'Test-M365DSCNewVersionAvailable': 'user-guide/cmdlets/Test-M365DSCNewVersionAvailable.md' + - 'Update-M365DSCAllowedGraphScopes': 'user-guide/cmdlets/Update-M365DSCAllowedGraphScopes.md' + - 'Update-M365DSCDependencies': 'user-guide/cmdlets/Update-M365DSCDependencies.md' + - 'Update-M365DSCResourcesSettingsJSON': 'user-guide/cmdlets/Update-M365DSCResourcesSettingsJSON.md' - Contributing: - 'Guidelines': 'contributing/contribution-guidelines.md' - 'Getting started': 'contributing/getting-started.md'