Modules/M365DSCReport.psm1
|
$Script:ReportCSS = @'
<style> body { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; background-color: #f8f9fa; color: #212529; margin: 0; padding: 20px; } .report-container { max-width: 1200px; margin: auto; background-color: #ffffff; border: 1px solid #dee2e6; border-radius: 5px; padding: 40px; box-shadow: 0 0 10px rgba(0,0,0,0.1); } h1, h2, h3 { color: #005a9e; } h1 { text-align: center; border-bottom: 2px solid #005a9e; padding-bottom: 10px; margin-top: 0; } h2 { border-bottom: 1px solid #ccc; padding-bottom: 5px; margin-top: 0; } table .resource-icon { width: 20%; text-align: center; vertical-align: middle; } .comparison-text { text-align: center; font-style: italic; color: #4d6477; margin: 40px 0 20px 0; } .comparison-text ul { display: inline-block; text-align: left; margin-top: 5px; padding-left: 20px; } .logo-container { text-align: center; margin-bottom: 20px; } .workload-section { margin-bottom: 30px; } .workload-header { background-color: #f0f0f0; padding: 15px; border-left: 4px solid #005a9e; margin-bottom: 15px; border-radius: 3px; } .workload-header h3 { margin: 0; color: #005a9e; } .workload-header img { height: 40px; width: auto; } .toc { background-color: #e9ecef; padding: 5px 15px 5px; border-radius: 5px; border: 1px solid #dee2e6; } .toc ul { list-style-type: none; padding: 0; margin: 0; } .toc li { margin-bottom: 10px; } .toc a { text-decoration: none; color: #005a9e; font-weight: bold; } .toc a:hover { text-decoration: underline; } .resource-table { width: 100%; border-collapse: collapse; margin-top: 20px; border: 1px solid #dee2e6; h1, h2, h3 { color: #ffffff; } } .resource-table th, .resource-table td { padding: 8px 12px; text-align: left; border: 1px solid #dee2e6; } .resource-table .resource-header { background-color: #005a9e; color: #ffffff; text-align: center; } .drift-table { width: 100%; border-collapse: collapse; margin-top: 20px; border: 1px solid #dee2e6; h1, h2, h3 { color: #ffffff; } } .drift-table th, .drift-table td { padding: 8px 12px; text-align: left; border: 1px solid #dee2e6; } .drift-table .drift-header { background-color: #005a9e; color: #ffffff; text-align: center; } .drift-table .drift-subheader { background-color: #e9ecef; font-weight: bold; text-align: center; } .property-name { text-align: left; font-weight: bold; width: 25%; } .property-value { text-align: left; width: 75%; max-width: 600px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } .drift-table .value-cell { width: 27.5%; } .level-L1 { background-color: #F6CECE; } .level-L2 { background-color: #F7F8E0; } .level-L3 { background-color: #FFFFFF; } .emoticon { font-size: 1.2em; } .no-discrepancies { text-align: center; font-size: 1.2em; color: #28a745; margin-top: 20px; padding: 20px; background-color: #e9f7ef; border: 1px solid #a3d9b8; border-radius: 5px; } </style> '@ # Shared lookup table mapping resource name prefixes to workload names and icon file names. # The first matching prefix wins. $Script:WorkloadMapping = [ordered]@{ 'AAD' = @{ WorkloadName = 'Azure Active Directory'; IconName = 'AzureAD.jpg' } 'ADO' = @{ WorkloadName = 'Azure DevOps'; IconName = 'AzureDevOps.png' } 'Azure' = @{ WorkloadName = 'Azure'; IconName = 'Azure.png' } 'Commerce' = @{ WorkloadName = 'Commerce'; IconName = $null } 'Defender' = @{ WorkloadName = 'Microsoft Defender'; IconName = 'SecurityAndCompliance.png' } 'EXO' = @{ WorkloadName = 'Exchange Online'; IconName = 'Exchange.jpg' } 'Fabric' = @{ WorkloadName = 'Microsoft Fabric'; IconName = $null } 'Intune' = @{ WorkloadName = 'Intune'; IconName = 'Intune.jpg' } 'M365DSC' = @{ WorkloadName = 'Microsoft365DSC'; IconName = $null } 'O365' = @{ WorkloadName = 'Office 365'; IconName = 'Office365.jpg' } 'OD' = @{ WorkloadName = 'OneDrive'; IconName = 'OneDrive.jpg' } 'Planner' = @{ WorkloadName = 'Planner'; IconName = 'Planner.png' } 'PP' = @{ WorkloadName = 'Power Platform'; IconName = 'PowerApps.jpg' } 'SC' = @{ WorkloadName = 'Security & Compliance'; IconName = 'SecurityAndCompliance.png' } 'Sentinel' = @{ WorkloadName = 'Sentinel'; IconName = $null } 'SH' = @{ WorkloadName = 'Services Hub'; IconName = $null } 'SPO' = @{ WorkloadName = 'SharePoint Online'; IconName = 'SharePoint.jpg' } 'Teams' = @{ WorkloadName = 'Microsoft Teams'; IconName = 'Teams.jpg' } 'Viva' = @{ WorkloadName = 'Microsoft Viva'; IconName = $null } } # Base64 data URIs of the report icons, keyed by file name. Missing icons are cached as $null. $Script:IconCache = @{} <# .DESCRIPTION This function HTML-encodes a value so tenant data is shown as text in the HTML reports. .PARAMETER Value The value to encode. $null returns an empty string. .FUNCTIONALITY Internal, Hidden #> function ConvertTo-M365DSCHtmlText { [CmdletBinding()] [OutputType([System.String])] param ( [Parameter()] [AllowNull()] [System.Object] $Value ) if ($null -eq $Value) { return '' } return [System.Net.WebUtility]::HtmlEncode([System.String]$Value) } <# .DESCRIPTION This function converts a property value into plain text for the CSV and Excel reports. Array elements are written on separate lines. The entries of a CIM instance are written as 'Name: Value' lines, and nested entries are prefixed with their path. CIM instances in an array are separated by an empty line. .PARAMETER Value The value to convert. .PARAMETER Prefix The path of the value inside its parent CIM instance. Empty for the property value itself. .FUNCTIONALITY Internal, Hidden #> function ConvertTo-M365DSCReportText { [CmdletBinding()] [OutputType([System.String])] param ( [Parameter()] [AllowNull()] [System.Object] $Value, [Parameter()] [System.String] $Prefix = '' ) if ($Value -is [System.Collections.IDictionary]) { $lines = @() foreach ($key in ($Value.Keys | Sort-Object)) { if ($key -eq 'CIMInstance') { continue } $name = $key if (-not [System.String]::IsNullOrEmpty($Prefix)) { $name = "$Prefix.$key" } $entry = $Value[$key] if ($entry -is [System.Collections.IDictionary] -or $entry -is [System.Array]) { $text = ConvertTo-M365DSCReportText -Value $entry -Prefix $name if ([System.String]::IsNullOrEmpty($text)) { $text = "$($name):" } $lines += $text } else { $lines += "$($name): $entry" } } return $lines -join "`n" } if ($Value -is [System.Array]) { $items = @() $separator = "`n" for ($i = 0; $i -lt $Value.Count; $i++) { $item = $Value[$i] if ($item -is [System.Collections.IDictionary] -or $item -is [System.Array]) { $itemPrefix = '' if (-not [System.String]::IsNullOrEmpty($Prefix)) { $itemPrefix = "$Prefix[$i]" } elseif ($item -is [System.Collections.IDictionary]) { $separator = "`n`n" } $items += ConvertTo-M365DSCReportText -Value $item -Prefix $itemPrefix } elseif ([System.String]::IsNullOrEmpty($Prefix)) { $items += [System.String]$item } else { $items += "$Prefix[$i]: $item" } } return $items -join $separator } return [System.String]$Value } <# .DESCRIPTION This function generates HTML workload sections by grouping resources .FUNCTIONALITY Internal, Hidden #> function New-M365DSCWorkloadSection { [CmdletBinding()] [OutputType([System.String])] param ( [Parameter(Mandatory = $true)] [Array] $Resources, [Parameter(Mandatory = $true)] [ScriptBlock] $ResourceRenderer ) $output = [System.Text.StringBuilder]::new() # Group by workload $resourcesByWorkload = @{} foreach ($resource in $Resources) { $workload = Get-M365WorkloadName -ResourceName $resource.ResourceName if (-not $resourcesByWorkload.ContainsKey($workload)) { $resourcesByWorkload[$workload] = @() } $resourcesByWorkload[$workload] += $resource } # Process each workload group foreach ($workload in ($resourcesByWorkload.Keys | Sort-Object)) { $workloadResources = $resourcesByWorkload[$workload] $firstResource = $workloadResources[0] [void]$output.AppendLine("<div class='workload-section'>") [void]$output.AppendLine("<div class='workload-header'>") $iconPath = Get-IconPath -ResourceName $firstResource.ResourceName if (-not [System.String]::IsNullOrEmpty($iconPath)) { [void]$output.AppendLine("<img src='$iconPath' alt='$workload' style='vertical-align: middle; margin-right: 10px;' />") } [void]$output.AppendLine("<h3 style='display: inline;'>$workload</h3>") [void]$output.AppendLine('</div>') foreach ($resource in $workloadResources) { $resourceOutput = & $ResourceRenderer $resource [void]$output.Append($resourceOutput) } [void]$output.AppendLine('</div>') } return $output.ToString() } <# .DESCRIPTION This function creates a Markdown report from the specified exported configuration. Every resource instance lands in one document, unless SplitByResource is specified. .FUNCTIONALITY Internal, Hidden #> function New-M365DSCConfigurationToMarkdown { [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [AllowEmptyCollection()] [Array] $ParsedContent, [Parameter(Mandatory = $true)] [System.String] $OutputPath, [Parameter()] [System.String] $OrganizationName, [Parameter()] [System.String] $TenantGuid, [Parameter()] [Switch] $IncludeAllInformation, [Parameter()] [Switch] $SplitByResource ) Initialize-M365DSCDllLoader -ErrorAction Stop $OutputPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($OutputPath) if ($SplitByResource -and [System.IO.Path]::GetExtension($OutputPath) -eq '.md') { $outputFolder = Split-Path -Path $OutputPath -Parent Write-Warning -Message "A split Markdown report is written to a folder. Using '$outputFolder' instead of '$OutputPath'." $OutputPath = $outputFolder } $resources = [System.Collections.Generic.List[System.Collections.IDictionary]]::new() foreach ($resource in $ParsedContent) { if ($resource -isnot [System.Collections.IDictionary]) { throw "ParsedContent contains a $($resource.GetType().Name). Every entry has to be a dictionary." } $resources.Add($resource) } $request = [Microsoft365DSC.Reporting.ReportRequest]::new() $request.Resources = $resources $request.OutputPath = $OutputPath $request.ModuleRoot = Split-Path -Path $PSScriptRoot -Parent $request.OrganizationName = $OrganizationName $request.TenantGuid = $TenantGuid $request.IncludeAllInformation = $IncludeAllInformation.IsPresent $request.SplitByResource = $SplitByResource.IsPresent $request.Warn = [System.Action[System.String]] { param($Message) Write-Warning -Message $Message } $null = [Microsoft365DSC.Reporting.ReportConverterRegistry]::Convert('Markdown', $request) } <# .DESCRIPTION This function creates a new HTML document from the specified exported configuration .FUNCTIONALITY Internal, Hidden #> function New-M365DSCConfigurationToHTML { [CmdletBinding()] [OutputType([System.String])] param ( [Parameter()] [Array] $ParsedContent, [Parameter()] [System.String] $OutputPath, [Parameter()] [System.String] $TemplateName ) if ([System.String]::IsNullOrEmpty($TemplateName)) { $TemplateName = 'Configuration Report' } Initialize-M365DSCDllLoader -ErrorAction Stop Write-Output 'Generating HTML report' $fullHTML = [System.Text.StringBuilder]::new() [void]$fullHTML.Append('<!DOCTYPE html>') [void]$fullHTML.Append('<html>') [void]$fullHTML.Append('<head><meta charset="utf-8"><title>Configuration Report</title>') [void]$fullHTML.Append($Script:ReportCSS) [void]$fullHTML.Append('</head>') [void]$fullHTML.Append('<body>') [void]$fullHTML.Append("<div class='report-container'>") [void]$fullHTML.Append('<h1>' + (ConvertTo-M365DSCHtmlText -Value $TemplateName) + '</h1>') [void]$fullHTML.Append("<div class='logo-container'><img src='" + (Get-IconPath -ResourceName 'Promo') + "' alt='Microsoft365DSC Slogan' width='500' /></div>") [void]$fullHTML.Append('<h2>Template Details</h2>') # Reference cell, because the renderer runs in a child scope of New-M365DSCWorkloadSection. $progress = @{ Current = 0 Total = $ParsedContent.Count } if ($ParsedContent.Count -gt 0) { $workloadSections = New-M365DSCWorkloadSection -Resources $ParsedContent -ResourceRenderer { param($resource) $percentage = [math]::Round(($progress.Current / $progress.Total) * 100, 2) Write-Progress -Activity 'Processing generated DSC Object' -Status ("{0:N2}% completed - $($resource.ResourceName)" -f $percentage) -PercentComplete $percentage $progress.Current++ $partHTML = [System.Text.StringBuilder]::new() [void]$partHTML.Append("<table class='resource-table'>") [void]$partHTML.Append("<tr><td class='resource-header' colspan='2'>") [void]$partHTML.Append('<strong>' + (ConvertTo-M365DSCHtmlText -Value $resource.ResourceName) + " '" + (ConvertTo-M365DSCHtmlText -Value $resource.ResourceInstanceName) + "'</strong>") [void]$partHTML.Append('</td></tr>') foreach ($property in ($resource.Keys | Sort-Object)) { if ($property -notin @('ResourceName', 'ResourceInstanceName') -and -not [Microsoft365DSC.Utilities.Utilities]::IsAuthenticationProperty($property)) { [void]$partHTML.Append("<tr><td class='property-name'>" + (ConvertTo-M365DSCHtmlText -Value $property) + '</td>') $value = "`$null" if ($null -ne $resource.$property) { if ($resource.$property -is [array] -or $resource.$property -is [hashtable]) { if ($resource.$property -and (($resource.$property -is [hashtable]) -or ($resource.$property -is [array] -and $resource.$property.Count -gt 0 -and ($resource.$property[0] -is [hashtable]))) ) { $value = Convert-ObjectToHtmlList -InputObject $resource.$property -ParentName $property } else { $components = @($resource.$property) if ($components.Count -gt 0 -and -not [System.String]::IsNullOrEmpty(($components -join ''))) { $value = '<ul>' foreach ($comp in $components) { $value += '<li>' + (ConvertTo-M365DSCHtmlText -Value $comp) + '</li>' } $value += '</ul>' } } } else { if (-not [System.String]::IsNullOrEmpty($resource.$property)) { $value = ConvertTo-M365DSCHtmlText -Value ($resource.$property).ToString() } } } [void]$partHTML.Append("<td class='property-value'>" + $value + '</td></tr>') } } [void]$partHTML.Append('</table><br />') return $partHTML.ToString() } [void]$fullHTML.Append($workloadSections) } Write-Progress -Activity 'Processing generated DSC Object' -Completed [void]$fullHTML.Append('</div>') # Close report-container [void]$fullHTML.Append('</body>') [void]$fullHTML.Append('</html>') if (-not [System.String]::IsNullOrEmpty($OutputPath)) { Write-Output 'Saving HTML report' $fullHTML.ToString() | Out-File -LiteralPath $OutputPath } Write-Output 'Completed generating HTML report' } <# .DESCRIPTION This function creates a new JSON file from the specified exported configuration .FUNCTIONALITY Internal, Hidden #> function New-M365DSCConfigurationToJSON { [CmdletBinding()] param ( [Parameter()] [Array] $ParsedContent, [Parameter(Mandatory = $true)] [System.String] $OutputPath ) Initialize-M365DSCDllLoader -ErrorAction Stop $resources = @() foreach ($resource in $ParsedContent) { $copy = [ordered]@{} foreach ($property in $resource.Keys) { if (-not [Microsoft365DSC.Utilities.Utilities]::IsAuthenticationProperty($property)) { $copy[$property] = $resource[$property] } } $resources += $copy } $jsonContent = ConvertTo-Json -InputObject $resources -Depth 25 $jsonContent | Out-File -LiteralPath $OutputPath } <# .DESCRIPTION This function gets the workload name from a resource name .FUNCTIONALITY Internal, Hidden #> function Get-M365WorkloadName { [CmdletBinding()] [OutputType([System.String])] param ( [Parameter(Mandatory = $true)] [System.String] $ResourceName ) foreach ($prefix in $Script:WorkloadMapping.Keys) { if ($ResourceName.StartsWith($prefix)) { return $Script:WorkloadMapping[$prefix].WorkloadName } } return 'Other' } <# .DESCRIPTION This function gets the URL to the logo of the workload of the specified resource .FUNCTIONALITY Internal, Hidden #> function Get-IconPath { [CmdletBinding()] [OutputType([System.String])] param ( [Parameter(Mandatory = $true)] [System.String] $ResourceName ) if ($ResourceName.StartsWith('Promo')) { return Get-Base64EncodedImage -IconName 'Promo.png' } foreach ($prefix in $Script:WorkloadMapping.Keys) { if ($ResourceName.StartsWith($prefix)) { $iconName = $Script:WorkloadMapping[$prefix].IconName if ($null -ne $iconName) { return Get-Base64EncodedImage -IconName $iconName } return $null } } return $null } <# .DESCRIPTION This function returns a string containing mime-type and base64 encoded image to embed into DSC report directly. .FUNCTIONALITY Internal, Hidden #> function Get-Base64EncodedImage { [CmdletBinding()] [OutputType([System.String])] param ( [Parameter()] [string] $IconName ) if ([System.String]::IsNullOrEmpty($IconName)) { return $null } if ($Script:IconCache.ContainsKey($IconName)) { return $Script:IconCache[$IconName] } $iconPath = [System.IO.Path]::Combine($PSScriptRoot, '..', 'Dependencies', 'Images', $IconName) if (-not [System.IO.File]::Exists($iconPath)) { Write-Verbose -Message "Report icon '$IconName' was not found at '$iconPath'." $Script:IconCache[$IconName] = $null return $null } $mimeType = switch ([System.IO.Path]::GetExtension($iconPath).ToLowerInvariant()) { '.png' { 'image/png' } { $_ -in @('.jpg', '.jpeg') } { 'image/jpeg' } default { 'application/octet-stream' } } $base64EncodedImage = [System.Convert]::ToBase64String([System.IO.File]::ReadAllBytes($iconPath)) $Script:IconCache[$IconName] = "data:$($mimeType);base64,$($base64EncodedImage)" return $Script:IconCache[$IconName] } <# .SYNOPSIS Returns the property rows of every resource of a parsed configuration. .DESCRIPTION Lists the properties of each resource with their report text, key properties first and the rest in alphabetical order. ResourceName and the authentication properties are skipped. Empty values are returned as '$null'. .PARAMETER ParsedContent Specifies the parsed resources of the configuration. .PARAMETER ReportType Specifies the report type named in the log entry of a failed conversion. .OUTPUTS System.Management.Automation.PSCustomObject[]. One object per resource with the ResourceName and its Properties, each with the Property, Value and IsKey members. .FUNCTIONALITY Internal, Hidden #> function Get-M365DSCReportPropertyRow { [CmdletBinding()] [OutputType([System.Management.Automation.PSCustomObject[]])] param ( [Parameter()] [System.Array] $ParsedContent, [Parameter(Mandatory = $true)] [System.String] $ReportType ) Initialize-M365DSCDllLoader -ErrorAction Stop $keyNames = @('Identity', 'Name', 'IsSingleInstance', 'DisplayName') $resources = @() foreach ($resource in $ParsedContent) { $properties = @() # Key properties first, then the rest, in a stable order foreach ($property in ($resource.Keys | Sort-Object -Property { $_ -notin $keyNames }, { $_ })) { if ($property -eq 'ResourceName' -or [Microsoft365DSC.Utilities.Utilities]::IsAuthenticationProperty($property)) { continue } $value = $null try { if ([System.String]::IsNullOrEmpty($resource.$property)) { $value = "`$null" } else { $value = ConvertTo-M365DSCReportText -Value $resource.$property } } catch { New-M365DSCLogEntry -Message "Error during conversion to $($ReportType):" ` -Exception $_ ` -Source $($MyInvocation.MyCommand.Source) } $properties += [PSCustomObject]@{ Property = $property Value = $value IsKey = $property -in $keyNames } } $resources += [PSCustomObject]@{ ResourceName = $resource.ResourceName Properties = $properties } } return $resources } <# .DESCRIPTION This function creates a new Excel document from the specified exported configuration .FUNCTIONALITY Internal, Hidden #> function New-M365DSCConfigurationToExcel { [CmdletBinding()] param ( [Parameter()] [Array] $ParsedContent, [Parameter(Mandatory = $true)] [System.String] $OutputPath ) $OutputPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($OutputPath) # Collect every row first and write them to the sheet in one call $rows = @() $keyRows = @() $resourceRanges = @() $row = 2 foreach ($resource in (Get-M365DSCReportPropertyRow -ParsedContent $ParsedContent -ReportType 'Excel')) { $beginRow = $row foreach ($propertyRow in $resource.Properties) { $rows += , @($resource.ResourceName, $propertyRow.Property, $propertyRow.Value) if ($propertyRow.IsKey) { $keyRows += $row } $row++ } $resourceRanges += "A$($beginRow):C$($row)" } try { $excel = New-Object -ComObject excel.application } catch [System.Runtime.InteropServices.COMException] { throw 'Excel is not installed on this machine. Please install Excel to use this feature.' } $workbook = $null $report = $null $usedRange = $null try { $excel.Visible = $false $excel.DisplayAlerts = $false $workbook = $excel.Workbooks.Add() $report = $workbook.Worksheets.Item(1) $report.Name = 'Report' $report.Cells.Item(1, 1) = 'Component Name' $report.Cells.Item(1, 1).Font.Size = 18 $report.Cells.Item(1, 1).Font.Bold = $True $report.Cells.Item(1, 2) = 'Property' $report.Cells.Item(1, 2).Font.Size = 18 $report.Cells.Item(1, 2).Font.Bold = $True $report.Cells.Item(1, 3) = 'Value' $report.Cells.Item(1, 3).Font.Size = 18 $report.Cells.Item(1, 3).Font.Bold = $True $report.Range('A1:C1').Borders.Weight = -4138 if ($rows.Count -gt 0) { $values = [System.Object[,]]::new($rows.Count, 3) for ($i = 0; $i -lt $rows.Count; $i++) { for ($column = 0; $column -lt 3; $column++) { $values[$i, $column] = $rows[$i][$column] } } $lastRow = $rows.Count + 1 $report.Range("A2:C$lastRow").Value2 = $values $report.Range("C2:C$lastRow").HorizontalAlignment = -4131 } foreach ($keyRow in $keyRows) { $keyFont = $report.Range("A$($keyRow):C$($keyRow)").Font $keyFont.ColorIndex = 10 $keyFont.Bold = $true } foreach ($resourceRange in $resourceRanges) { $report.Range($resourceRange).Borders[8].Weight = -4138 } $usedRange = $report.UsedRange $usedRange.EntireColumn.AutoFit() | Out-Null $workbook.SaveAs($OutputPath) } finally { # Close Excel and release the COM objects try { if ($null -ne $workbook) { $workbook.Close($false) } $excel.Quit() } catch { Write-Verbose -Message "Could not close Excel cleanly: $($_.Exception.Message)" } foreach ($comObject in @($usedRange, $report, $workbook, $excel)) { if ($null -ne $comObject) { [void][System.Runtime.InteropServices.Marshal]::ReleaseComObject($comObject) } } [System.GC]::Collect() [System.GC]::WaitForPendingFinalizers() } } <# .DESCRIPTION This function creates a new CSV file from the specified exported configuration .FUNCTIONALITY Internal, Hidden #> function New-M365DSCConfigurationToCSV { [CmdletBinding()] param ( [Parameter()] [Array] $ParsedContent, [Parameter(Mandatory = $true)] [System.String] $OutputPath, [Parameter()] [System.String] $Delimiter = ',' ) $row = 0 $csvOutput = @() foreach ($resource in (Get-M365DSCReportPropertyRow -ParsedContent $ParsedContent -ReportType 'CSV')) { if ($row -gt 0) { Write-Verbose -Message 'add separator-line in CSV-file between resources' $csvOutput += [PSCustomObject][ordered]@{ 'Component Name' = '======================' Property = $null Value = $null } $row++ } foreach ($propertyRow in $resource.Properties) { $csvOutput += [PSCustomObject][ordered]@{ 'Component Name' = $resource.ResourceName Property = $propertyRow.Property Value = $propertyRow.Value } $row++ } } $csvOutput | Export-Csv -LiteralPath $OutputPath -Encoding utf8BOM -Delimiter $Delimiter -NoTypeInformation } <# .SYNOPSIS Generates a report file from an exported DSC configuration. .DESCRIPTION Parses a DSC configuration file and renders a report in the requested output format. Supports Excel, HTML, JSON, Markdown, and CSV output types. .PARAMETER Type Specifies the report output format. .PARAMETER ConfigurationPath Specifies the source DSC configuration file path. .PARAMETER OutputPath Specifies the destination report file path. A Markdown report that is split by resource is written to a folder instead of a file. .PARAMETER IncludeAllInformation Specifies that the report carries every property the resource supports, set or not, with its attribute, data type, allowed values and description, and the permissions of the resource. Without it, a report carries the name, data type and value of every property the configuration sets. Only available when Type is Markdown. .PARAMETER SplitByResource Specifies that every resource instance becomes its own document, in a folder per workload below OutputPath. Without it, the whole configuration lands in a single document. Only available when Type is Markdown. .PARAMETER OrganizationName Specifies the tenant domain name that is replaced by a portable token in every value. Only available when Type is Markdown. .PARAMETER TenantGuid Specifies the tenant identifier that is replaced by a portable token in every value. Only available when Type is Markdown. .EXAMPLE PS> New-M365DSCReportFromConfiguration -Type 'HTML' -ConfigurationPath 'C:\DSC\ConfigName.ps1' -OutputPath 'C:\Dsc\M365Report.html' .EXAMPLE PS> New-M365DSCReportFromConfiguration -Type 'Excel' -ConfigurationPath 'C:\DSC\ConfigName.ps1' -OutputPath 'C:\Dsc\M365Report.xlsx' .EXAMPLE PS> New-M365DSCReportFromConfiguration -Type 'JSON' -ConfigurationPath 'C:\DSC\ConfigName.ps1' -OutputPath 'C:\Dsc\M365Report.json' .FUNCTIONALITY Public #> function New-M365DSCReportFromConfiguration { [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [ValidateSet('Excel', 'HTML', 'JSON', 'Markdown', 'CSV')] [System.String] $Type, [Parameter(Mandatory = $true)] [System.String] $ConfigurationPath, [Parameter(Mandatory = $true)] [System.String] $OutputPath ) dynamicparam # 'Delimiter' requires Type = 'CSV', the other parameters require Type = 'Markdown' { $paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new() if ($Type -eq 'Markdown') { foreach ($markdownParam in @( @{ Name = 'IncludeAllInformation'; Type = [Switch] } @{ Name = 'SplitByResource'; Type = [Switch] } @{ Name = 'OrganizationName'; Type = [System.String] } @{ Name = 'TenantGuid'; Type = [System.String] } )) { $markdownAttr = [System.Management.Automation.ParameterAttribute]::new() $markdownAttr.Mandatory = $false $markdownCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new() $markdownCollection.Add($markdownAttr) $paramDictionary.Add($markdownParam.Name, [System.Management.Automation.RuntimeDefinedParameter]::New( $markdownParam.Name, $markdownParam.Type, $markdownCollection)) } } if ($Type -eq 'CSV') { $delimiterAttr = [System.Management.Automation.ParameterAttribute]::new() $delimiterAttr.Mandatory = $false $attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new() $attributeCollection.Add($delimiterAttr) $delimiterParam = [System.Management.Automation.RuntimeDefinedParameter]::New('Delimiter', [System.String], $attributeCollection) $delimiterParam.Value = ';' # default value, comma makes a mess when importing a CSV-file in Excel $paramDictionary.Add('Delimiter', $delimiterParam) $PSBoundParameters.Add('Delimiter', $delimiterParam.Value) } return $paramDictionary } begin { if ($PSBoundParameters.ContainsKey('Delimiter')) { $Delimiter = $PSBoundParameters.Delimiter } $markdownParameters = @{ } foreach ($markdownParam in @('IncludeAllInformation', 'SplitByResource', 'OrganizationName', 'TenantGuid')) { if ($PSBoundParameters.ContainsKey($markdownParam)) { $markdownParameters.$markdownParam = $PSBoundParameters.$markdownParam } } } process # required with DynamicParam { if (-not (Test-Path -LiteralPath $ConfigurationPath -PathType Leaf)) { Write-Error -Message "Cannot find configuration file: $ConfigurationPath. Please make sure the file exists!" return } # Validate that the latest version of the module is installed. Test-M365DSCModuleValidity #Ensure the proper dependencies are installed in the current environment. Confirm-M365DSCDependencies #region Telemetry $data = [System.Collections.Generic.Dictionary[[System.String], [System.Object]]]::new() $data.Add('Event', 'Report') $data.Add('Type', $Type) Add-M365DSCTelemetryEvent -Data $data -Type 'NewReport' #endregion [Array] $parsedContent = Initialize-M365DSCReporting -ConfigurationPath $ConfigurationPath if ($null -ne $parsedContent) { switch ($Type) { 'Excel' { New-M365DSCConfigurationToExcel -ParsedContent $parsedContent -OutputPath $OutputPath } 'HTML' { $templateName = [System.IO.Path]::GetFileNameWithoutExtension($ConfigurationPath) New-M365DSCConfigurationToHTML -ParsedContent $parsedContent -OutputPath $OutputPath -TemplateName $templateName } 'JSON' { New-M365DSCConfigurationToJSON -ParsedContent $parsedContent -OutputPath $OutputPath } 'Markdown' { New-M365DSCConfigurationToMarkdown -ParsedContent $parsedContent -OutputPath $OutputPath @markdownParameters } 'CSV' { New-M365DSCConfigurationToCSV -ParsedContent $parsedContent -OutputPath $OutputPath -Delimiter $Delimiter } } } else { Write-Warning -Message 'Parsed content was null. No report was generated.' } } } <# .SYNOPSIS Determines the preferred key property name for a CIM instance hashtable. .DESCRIPTION Inspects known key candidates in priority order and returns the property name used as the instance key. .PARAMETER CIMInstance Specifies the CIM instance hashtable to inspect. .FUNCTIONALITY Internal .OUTPUTS System.String #> function Get-M365DSCCIMInstanceKey { [CmdletBinding()] [OutputType([System.String])] param ( [Parameter(Mandatory = $true)] [System.Collections.Hashtable] $CIMInstance ) $primaryKey = '' if ($CIMInstance.ContainsKey('IsSingleInstance')) { $primaryKey = '' } elseif ($CIMInstance.ContainsKey('DisplayName')) { $primaryKey = 'DisplayName' } elseif ($CIMInstance.ContainsKey('Identity')) { $primaryKey = 'Identity' } elseif ($CIMInstance.ContainsKey('Id')) { $primaryKey = 'Id' } elseif ($CIMInstance.ContainsKey('Name')) { $primaryKey = 'Name' } elseif ($CIMInstance.ContainsKey('Title')) { $primaryKey = 'Title' } elseif ($CIMInstance.ContainsKey('CdnType')) { $primaryKey = 'CdnType' } elseif ($CIMInstance.ContainsKey('Usage')) { $primaryKey = 'Usage' } elseif ($CIMInstance.ContainsKey('odataType')) { $primaryKey = 'odataType' } elseif ($CIMInstance.ContainsKey('dataType')) { $primaryKey = 'dataType' } elseif ($CIMInstance.ContainsKey('Dmn')) { $primaryKey = 'Dmn' } elseif ($CIMInstance.ContainsKey('EmergencyDialString')) { $primaryKey = 'EmergencyDialString' } else { $primaryKey = @($CIMInstance.Keys)[0] } return $primaryKey } <# .SYNOPSIS Creates a delta report between two configuration sources. .DESCRIPTION Compares source and destination configurations, evaluates drifted resources and properties, and renders a report in HTML or JSON format. Optional variable substitution support can be applied during comparison. .PARAMETER Source Specifies the source configuration file path. .PARAMETER Destination Specifies the destination configuration file path. .PARAMETER OutputPath Specifies the destination report file path. .PARAMETER DriftOnly Indicates that only drifted properties should be included. .PARAMETER IsBlueprintAssessment Indicates that report generation is running as a blueprint assessment. .PARAMETER HeaderFilePath Specifies a custom header file path for HTML output. .PARAMETER Delta Specifies a precomputed delta structure to render. .PARAMETER Type Specifies the report format. .PARAMETER ExcludedProperties Specifies property names to exclude from comparison. .PARAMETER ExcludedResources Specifies resource names to exclude from comparison. .PARAMETER UseVariableSubstitution Indicates that variable substitution should be applied during comparison. .PARAMETER SourceConfigurationDataPath Specifies the source configuration data file path used for substitution. .PARAMETER DestinationConfigurationDataPath Specifies the destination configuration data file path used for substitution. .PARAMETER ExcludedSubstitutionProperties Specifies property names excluded from variable substitution. .EXAMPLE PS> New-M365DSCDeltaReport -Source 'C:\DSC\Source.ps1' -Destination 'C:\DSC\Destination.ps1' -OutputPath 'C:\DSC\DeltaReport.html' .EXAMPLE PS> New-M365DSCDeltaReport -Source 'C:\DSC\Source.ps1' -Destination 'C:\DSC\Destination.ps1' -OutputPath 'C:\DSC\DeltaReport.html' -DriftOnly $true .EXAMPLE PS> New-M365DSCDeltaReport -Source 'C:\DSC\Source.ps1' -Destination 'C:\DSC\Destination.ps1' -OutputPath 'C:\DSC\DeltaReport.html' -IsBlueprintAssessment $true .EXAMPLE PS> New-M365DSCDeltaReport -Source 'C:\DSC\Source.ps1' -Destination 'C:\DSC\Destination.ps1' -OutputPath 'C:\DSC\DeltaReport.html' -HeaderFilePath 'C:\DSC\CustomHeader.html' ` -SourceConfigurationDataPath 'C:\DSC\SourceConfigData.psd1' -DestinationConfigurationDataPath 'C:\DSC\DestinationConfigData.psd1' -ExcludedSubstitutionProperties @('TenantEnvironment') .FUNCTIONALITY Public #> function New-M365DSCDeltaReport { [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [System.String] $Source, [Parameter(Mandatory = $true)] [System.String] $Destination, [Parameter()] [System.String] $OutputPath, [Parameter()] [System.Boolean] $DriftOnly = $false, [Parameter()] [System.Boolean] $IsBlueprintAssessment = $false, [Parameter()] [System.String] $HeaderFilePath, [Parameter()] [Array] $Delta, [Parameter()] [System.String] [ValidateSet('HTML', 'JSON')] $Type = 'HTML', [Parameter()] [Array] $ExcludedProperties, [Parameter()] [Array] $ExcludedResources, [Parameter(ParameterSetName = 'VariableSubstitution')] [Switch] $UseVariableSubstitution, [Parameter(ParameterSetName = 'VariableSubstitution')] [System.String] $SourceConfigurationDataPath, [Parameter(ParameterSetName = 'VariableSubstitution')] [System.String] $DestinationConfigurationDataPath, [Parameter(ParameterSetName = 'VariableSubstitution')] [System.String[]] $ExcludedSubstitutionProperties ) # Validate that the latest version of the module is installed. Test-M365DSCModuleValidity if ((Test-Path -LiteralPath $Source) -eq $false) { Write-Error "Cannot find file specified in parameter Source: $Source. Please make sure the file exists!" return } if ((Test-Path -LiteralPath $Destination) -eq $false) { Write-Error "Cannot find file specified in parameter Destination: $Destination. Please make sure the file exists!" return } if ($OutputPath -and (Test-Path -LiteralPath $OutputPath) -eq $true) { Write-Warning "File specified in parameter OutputPath already exists and will be overwritten: $OutputPath" Write-Warning "Make sure you specify a file that does not exist if you don't want the file to be overwritten!" } if ($PSBoundParameters.ContainsKey('HeaderFilePath') -and -not [System.String]::IsNullOrEmpty($HeaderFilePath) -and ` (Test-Path -LiteralPath $HeaderFilePath) -eq $false) { Write-Error "Cannot find file specified in parameter HeaderFilePath: $HeaderFilePath. Please make sure the file exists!" return } #Ensure the proper dependencies are installed in the current environment. Confirm-M365DSCDependencies Initialize-M365DSCDllLoader -ErrorAction Stop #region Telemetry $data = [System.Collections.Generic.Dictionary[[System.String], [System.Object]]]::new() $data.Add('Event', 'DeltaReport') Add-M365DSCTelemetryEvent -Data $data -Type 'CompareConfigurations' #endregion Write-Verbose -Message 'Obtaining Delta between the source and destination configurations' if (-not $PSBoundParameters.ContainsKey('Delta')) { if ($null -eq $Script:DscResourceInfo) { $Script:DscResourceInfo = Get-M365DSCResourceSchema } #region ConfigurationData variable substitution $effectiveSource = $Source $effectiveDestination = $Destination $tempPaths = @() if ($UseVariableSubstitution) { # Build a map of ConfigurationData paths: key = file path, value = config data path $configDataMap = @{} if (-not [System.String]::IsNullOrEmpty($SourceConfigurationDataPath)) { $configDataMap[$Source] = $SourceConfigurationDataPath } if (-not [System.String]::IsNullOrEmpty($DestinationConfigurationDataPath)) { $configDataMap[$Destination] = $DestinationConfigurationDataPath } # Auto-detect ConfigurationData.psd1 when no explicit path was provided foreach ($filePath in @($Source, $Destination)) { if (-not $configDataMap.ContainsKey($filePath)) { $resolvedFilePath = (Resolve-Path -LiteralPath $filePath -ErrorAction Stop).ProviderPath $autoPath = Join-Path -Path (Split-Path -Path $resolvedFilePath -Parent) -ChildPath 'ConfigurationData.psd1' if (Test-Path -LiteralPath $autoPath) { $configDataMap[$filePath] = $autoPath } } } foreach ($filePath in @($Source, $Destination)) { if (-not $configDataMap.ContainsKey($filePath)) { continue } $configDataFile = $configDataMap[$filePath] if (-not (Test-Path -LiteralPath $configDataFile)) { Write-Warning -Message "ConfigurationData file not found at '$configDataFile'. Skipping variable substitution for '$filePath'." continue } Write-Verbose -Message "Importing ConfigurationData from '$configDataFile' for '$filePath'" $configData = Import-PowerShellDataFile -LiteralPath $configDataFile # Collect all string properties from NonNodeData $substitutions = @{} if ($null -ne $configData.NonNodeData) { $nonNodeEntries = @() if ($configData.NonNodeData -is [System.Array]) { $nonNodeEntries = $configData.NonNodeData } else { $nonNodeEntries = @($configData.NonNodeData) } $ExcludedSubstitutionProperties += [Microsoft365DSC.Utilities.Utilities]::AuthenticationPropertyNames + 'TenantGuid' $ExcludedSubstitutionProperties = $ExcludedSubstitutionProperties | Select-Object -Unique foreach ($entry in $nonNodeEntries) { if ($entry -is [System.Collections.IDictionary]) { foreach ($key in $entry.Keys) { if ($ExcludedSubstitutionProperties -contains $key) { Write-Verbose -Message " Skipping excluded property '$key'" continue } $value = $entry[$key] if ($key -eq 'OrganizationName') { $substitutions["`$OrganizationName"] = $value continue } if ($value -is [System.String] -and -not [System.String]::IsNullOrEmpty($value)) { $substitutions["`$ConfigurationData.NonNodeData.$key"] = $value } } } } } if ($substitutions.Count -eq 0) { continue } $content = [System.IO.File]::ReadAllText((Resolve-Path -LiteralPath $filePath).ProviderPath) $hasSubstitutions = $false foreach ($varName in ($substitutions.Keys | Sort-Object -Property Length -Descending)) { if ($content.Contains($varName)) { Write-Verbose -Message " Replacing $varName with '$($substitutions[$varName])'" $replacement = $substitutions[$varName] $content = $content.Replace('$(' + $varName + ')', $replacement) # Bare form must not match inside a longer name, e.g. .Domain in .DomainName $content = [System.Text.RegularExpressions.Regex]::Replace($content, [System.Text.RegularExpressions.Regex]::Escape($varName) + '(?!\w)', { param($m) $replacement }) $hasSubstitutions = $true } } if ($hasSubstitutions) { $tempPath = Join-Path -Path ([System.IO.Path]::GetTempPath()) -ChildPath ("M365DSCDelta_$([System.Guid]::NewGuid()).ps1") [System.IO.File]::WriteAllText($tempPath, $content) $tempPaths += $tempPath if ($filePath -eq $Source) { $effectiveSource = $tempPath } else { $effectiveDestination = $tempPath } } } } #endregion $desiredSplat = @{ ConfigurationPath = $effectiveDestination IncludeComments = $false DscResourceInfo = $Script:DscResourceInfo } if ($IsBlueprintAssessment) { $desiredSplat.IncludeComments = $true } # Parse the blueprint file, pass to other comparison functions as object (including comments aka metadata) try { [Array]$desiredConfiguration = Initialize-M365DSCReporting @desiredSplat [Array]$sourceReporting = Initialize-M365DSCReporting -ConfigurationPath $effectiveSource } finally { # Clean up temp files if created foreach ($tempPath in $tempPaths) { if (Test-Path -LiteralPath $tempPath) { Remove-Item -LiteralPath $tempPath -Force } } } # The comparison runs on the schema the module ships, and resolves resource keys from it. Initialize-M365DSCSchemaCache # PostProcessing callbacks are resource code, so they cannot come from the schema and are # collected here for the resources the configurations mention. $compareParameters = [System.Collections.Generic.Dictionary[System.String, Microsoft365DSC.Compare.ResourceCompareParameters]]::new() foreach ($resourceName in @($sourceReporting.ResourceName) + @($desiredConfiguration.ResourceName) | Select-Object -Unique) { if ([System.String]::IsNullOrEmpty($resourceName) -or $compareParameters.ContainsKey($resourceName)) { continue } $schemaEntry = [Microsoft365DSC.Cache.CacheManager]::FilterLoadedCimClassesByName("MSFT_$resourceName") if ($null -eq $schemaEntry -or -not $schemaEntry['HasPostProcessing']) { continue } try { $customCompareParams = Get-M365DSCResourceComparisonParameters -ResourceName $resourceName } catch { Write-Warning -Message "Failed to retrieve custom comparison parameters for $resourceName`: $_. Using default comparison." continue } if ($null -eq $customCompareParams -or $customCompareParams.Count -eq 0) { continue } $parameters = [Microsoft365DSC.Compare.ResourceCompareParameters]::new() $parameters.ExcludedProperties = [System.String[]] $customCompareParams.ExcludedProperties $parameters.IncludedProperties = [System.String[]] $customCompareParams.IncludedProperties $parameters.PostProcessing = $customCompareParams.PostProcessing $parameters.Rules = [Microsoft365DSC.Compare.CompareRule]::ParseAll($customCompareParams.CompareRules) $existingArgs = @() if ($null -ne $customCompareParams.PostProcessingArgs) { $existingArgs = @($customCompareParams.PostProcessingArgs) } $parameters.PostProcessingArgs = [System.Object[]] ($existingArgs + @{ IsReport = $true }) $compareParameters.Add($resourceName, $parameters) } if ($null -eq $sourceReporting) { $sourceReporting = @() } if ($null -eq $desiredConfiguration) { $desiredConfiguration = @() } [Array]$Delta = [Microsoft365DSC.Compare.ConfigurationComparer]::Compare( $sourceReporting, $desiredConfiguration, [Microsoft365DSC.Cache.CacheManager]::Schema, $ExcludedProperties, $ExcludedResources, $compareParameters) | ForEach-Object -Process { $_.ToHashtable() } } if ($Type -eq 'HTML') { $reportSB = [System.Text.StringBuilder]::new() $ReportTitle = 'Microsoft365DSC - Delta Report' $headerTitle = 'Delta Report' if ($IsBlueprintAssessment) { $ReportTitle = 'Microsoft365DSC - Blueprint Assessment Report' $headerTitle = 'Blueprint Assessment Report' } [void]$reportSB.AppendLine('<!DOCTYPE html>') [void]$reportSB.AppendLine("<html><head><meta charset='utf-8'><title>$ReportTitle</title>") [void]$reportSB.AppendLine($Script:ReportCSS) [void]$reportSB.AppendLine("</head><body><div class='report-container'>") #region Custom Header if (-not [System.String]::IsNullOrEmpty($HeaderFilePath)) { try { $headerContent = Get-Content -LiteralPath $HeaderFilePath -Raw -ErrorAction Stop [void]$reportSB.AppendLine($headerContent) } catch { New-M365DSCLogEntry -Message 'Error while reading the custom header file:' ` -Exception $_ ` -Source $($MyInvocation.MyCommand.Source) } } #endregion [void]$reportSB.AppendLine("<h1>$headerTitle</h1>") [void]$reportSB.AppendLine("<div class='logo-container'>") [void]$reportSB.AppendLine("<img src='" + (Get-IconPath -ResourceName 'Promo') + "' alt='Microsoft365DSC Slogan' width='500' />") [void]$reportSB.AppendLine('</div>') if (-not $IsBlueprintAssessment) { [void]$reportSB.AppendLine("<div class='comparison-text'>") [void]$reportSB.AppendLine('<p><strong>Comparison between the following configurations:</strong></p>') [void]$reportSB.AppendLine('<ul>') [void]$reportSB.AppendLine("<li><strong>Source: </strong>$(ConvertTo-M365DSCHtmlText -Value $Source)</li>") [void]$reportSB.AppendLine("<li><strong>Destination: </strong>$(ConvertTo-M365DSCHtmlText -Value $Destination)</li>") [void]$reportSB.AppendLine('</ul>') [void]$reportSB.AppendLine("<p>Report generated on: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')</p>") [void]$reportSB.AppendLine('</div>') } [array]$resourcesMissingInSource = $Delta | Where-Object -FilterScript { $_.Properties.ParameterName -eq '_IsInConfiguration_' -and ` $_.Properties.ValueInSource -eq 'Absent' } [array]$resourcesMissingInDestination = $Delta | Where-Object -FilterScript { $_.Properties.ParameterName -eq '_IsInConfiguration_' -and ` $_.Properties.ValueInDestination -eq 'Absent' } [array]$resourcesInDrift = $Delta | Where-Object -FilterScript { $_.Properties.ParameterName -ne '_IsInConfiguration_' } # Combine the per-property entries of each instance into copies $combinedResourcesInDrift = [ordered]@{} foreach ($resource in $resourcesInDrift) { $instanceKey = "$($resource.ResourceName)|$($resource.ResourceInstanceName)|$($resource.KeyValue)" if ($combinedResourcesInDrift.Contains($instanceKey)) { $combinedResourcesInDrift[$instanceKey].Properties += $resource.Properties } else { $combinedResourcesInDrift[$instanceKey] = @{ ResourceName = $resource.ResourceName ResourceInstanceName = $resource.ResourceInstanceName Key = $resource.Key KeyValue = $resource.KeyValue Properties = @($resource.Properties) } } } $resourcesInDrift = $combinedResourcesInDrift.Values if ($resourcesInDrift.Count -eq 0 -and ($DriftOnly -or ` ($resourcesMissingInSource.Count -eq 0 -and $resourcesMissingInDestination.Count -eq 0))) { [void]$reportSB.AppendLine('<p class="no-discrepancies"><strong>No discrepancies have been found!</strong></p>') } elseif (-not $DriftOnly) { [void]$reportSB.AppendLine('<div class="toc">') [void]$reportSB.AppendLine('<h2>Table of Contents</h2>') [void]$reportSB.AppendLine('<ul>') if ($resourcesMissingInSource.Count -gt 0) { [void]$reportSB.AppendLine("<li><a href='#Source'>Resources Missing in the Source</a>") [void]$reportSB.AppendLine(" <strong>(</strong>$($resourcesMissingInSource.Count)<strong>)</strong></li>") } if ($resourcesMissingInDestination.Count -gt 0) { [void]$reportSB.AppendLine("<li><a href='#Destination'>Resources Missing in the Destination</a>") [void]$reportSB.AppendLine(" <strong>(</strong>$($resourcesMissingInDestination.Count)<strong>)</strong></li>") } if ($resourcesInDrift.Count -gt 0) { [void]$reportSB.AppendLine("<li><a href='#Drift'>Resources Configured Differently</a>") [void]$reportSB.AppendLine(" <strong>(</strong>$($resourcesInDrift.Count)<strong>)</strong></li>") } [void]$reportSB.AppendLine('</ul></div>') } if ($resourcesMissingInSource.Count -gt 0 -and -not $DriftOnly) { [void]$reportSB.AppendLine('<br /><hr /><br />') [void]$reportSB.AppendLine("<a id='Source'></a><h2>Resources missing in the source</h2>") $workloadSection = New-M365DSCWorkloadSection -Resources $resourcesMissingInSource -ResourceRenderer { param($resource) $sb = [System.Text.StringBuilder]::new() [void]$sb.AppendLine("<table class='resource-table'>") [void]$sb.AppendLine('<tr>') [void]$sb.AppendLine("<td class='resource-header'>") [void]$sb.AppendLine("<h3>$(ConvertTo-M365DSCHtmlText -Value $resource.ResourceName) - $(ConvertTo-M365DSCHtmlText -Value $resource.Key) = $(ConvertTo-M365DSCHtmlText -Value $resource.KeyValue)</h3>") [void]$sb.AppendLine('</td>') [void]$sb.AppendLine('</tr>') $presence = $resource.Properties | Select-Object -First 1 if ($null -ne $presence._Metadata_Level) { $emoticon = switch ($presence._Metadata_Level) { 'L1' { '🟥' } 'L2' { '🟨' } 'L3' { '🟦' } } [void]$sb.AppendLine("<tr><td><span class='emoticon'>$emoticon</span> $($presence._Metadata_Info)</td></tr>") } [void]$sb.AppendLine('</table>') return $sb.ToString() } [void]$reportSB.Append($workloadSection) } if ($resourcesMissingInDestination.Count -gt 0 -and -not $DriftOnly) { [void]$reportSB.AppendLine('<br /><hr /><br />') [void]$reportSB.AppendLine("<a id='Destination'></a><h2>Resources missing in the destination</h2>") $workloadSection = New-M365DSCWorkloadSection -Resources $resourcesMissingInDestination -ResourceRenderer { param($resource) $sb = [System.Text.StringBuilder]::new() [void]$sb.AppendLine("<table class='resource-table'>") [void]$sb.AppendLine('<tr>') [void]$sb.AppendLine("<td class='resource-header'>") [void]$sb.AppendLine("<h3>$(ConvertTo-M365DSCHtmlText -Value $resource.ResourceName) - $(ConvertTo-M365DSCHtmlText -Value $resource.Key) = $(ConvertTo-M365DSCHtmlText -Value $resource.KeyValue)</h3>") [void]$sb.AppendLine('</td>') [void]$sb.AppendLine('</tr>') [void]$sb.AppendLine('</table>') return $sb.ToString() } [void]$reportSB.Append($workloadSection) } if ($resourcesInDrift.Count -gt 0) { [void]$reportSB.AppendLine('<br /><hr /><br />') [void]$reportSB.AppendLine("<a id='Drift'></a><h2>Resources with differences</h2>") $SourceLabel = 'Source Value' $DestinationLabel = 'Destination Value' if ($IsBlueprintAssessment) { $SourceLabel = "Tenant's Current Value" $DestinationLabel = "Blueprint's Value" } $workloadSection = New-M365DSCWorkloadSection -Resources $resourcesInDrift -ResourceRenderer { param($resource) $sb = [System.Text.StringBuilder]::new() [void]$sb.AppendLine("<table class='drift-table'>") [void]$sb.AppendLine('<tr>') [void]$sb.AppendLine("<td class='drift-header' colspan='3'>") [void]$sb.AppendLine("<h3>$(ConvertTo-M365DSCHtmlText -Value $resource.ResourceName) - $(ConvertTo-M365DSCHtmlText -Value $resource.ResourceInstanceName)</h3>") [void]$sb.AppendLine('</td></tr>') [void]$sb.AppendLine('<tr>') [void]$sb.AppendLine("<td class='drift-subheader'><strong>Property</strong></td>") [void]$sb.AppendLine("<td class='drift-subheader'><strong>$SourceLabel</strong></td>") [void]$sb.AppendLine("<td class='drift-subheader'><strong>$DestinationLabel</strong></td>") [void]$sb.AppendLine('</tr>') foreach ($drift in $resource.Properties) { if ($drift.ParameterName -notlike '_metadata_*') { $cellStyle = '' $emoticon = '' if ($drift._Metadata_Level -eq 'L1') { $cellStyle = 'level-L1' $emoticon = '🟥' } elseif ($drift._Metadata_Level -eq 'L2') { $cellStyle = 'level-L2' $emoticon = '🟨' } elseif ($drift._Metadata_Level -eq 'L3') { $cellStyle = 'level-L3' $emoticon = '🟦' } $hasDeltaValue = $drift.ContainsKey('DeltaValue') -and $null -ne $drift.DeltaValue $additionalAttribute = '' if ($hasDeltaValue) { $additionalAttribute = 'rowspan="2"' } [void]$sb.AppendLine('<tr>') [void]$sb.AppendLine("<td class='property-name' $additionalAttribute>") [void]$sb.AppendLine("$(ConvertTo-M365DSCHtmlText -Value $drift.ParameterName)</td>") [void]$sb.AppendLine("<td class='value-cell $cellStyle'>") [void]$sb.AppendLine("$(ConvertTo-M365DSCHtmlText -Value $drift.ValueInSource)</td>") [void]$sb.AppendLine("<td class='value-cell'>") [void]$sb.AppendLine("$(ConvertTo-M365DSCHtmlText -Value $drift.ValueInDestination)</td>") [void]$sb.AppendLine('</tr>') if ($hasDeltaValue) { [System.String[]]$deltaValues = $drift.DeltaValue.Split("; ") [System.String[]]$destinationValues = $deltaValues | Where-Object -FilterScript { $_.StartsWith('<= ') } | ForEach-Object -Process { $_.Substring(3) } [System.String[]]$sourceValues = $deltaValues | Where-Object -FilterScript { $_.StartsWith('=> ') } | ForEach-Object -Process { $_.Substring(3) } [void]$sb.AppendLine('<tr>') [void]$sb.AppendLine("<td class='value-cell'>") if ($sourceValues.Count -gt 0) { [void]$sb.AppendLine("<strong>Delta:</strong><ul><li>$(($sourceValues | ForEach-Object { ConvertTo-M365DSCHtmlText -Value $_ }) -join '</li><li>')</li></ul>") } [void]$sb.AppendLine("</td>") [void]$sb.AppendLine("<td class='value-cell'>") if ($destinationValues.Count -gt 0) { [void]$sb.AppendLine("<strong>Delta:</strong><ul><li>$(($destinationValues | ForEach-Object { ConvertTo-M365DSCHtmlText -Value $_ }) -join '</li><li>')</li></ul>") } [void]$sb.AppendLine("</td>") [void]$sb.AppendLine('</tr>') } if ($null -ne $drift._Metadata_Level) { [void]$sb.AppendLine("<tr><td colspan='3'><span class='emoticon'>$emoticon</span> $($drift._Metadata_Info)</td></tr>") } } } [void]$sb.AppendLine('</table><hr/>') return $sb.ToString() } [void]$reportSB.Append($workloadSection) } [void]$reportSB.AppendLine('</div></body></html>') if (-not [System.String]::IsNullOrEmpty($OutputPath)) { $reportSB.ToString() | Out-File -LiteralPath $OutputPath } else { return $reportSB.ToString() } } elseif ($Type -eq 'JSON') { if ($null -eq $Delta) { $Delta = @() } $jsonDelta = ConvertTo-Json -InputObject $Delta -Depth 25 if (-not [System.String]::IsNullOrEmpty($OutputPath)) { $jsonDelta | Out-File -LiteralPath $OutputPath } else { return $jsonDelta } } } <# .DESCRIPTION This function prepares the configuration for further parsing of the data .FUNCTIONALITY Internal, Hidden #> function Initialize-M365DSCReporting { param ( [Parameter(Mandatory = $true)] [System.String] $ConfigurationPath, [Parameter()] [Switch] $IncludeComments, [Parameter()] [System.Object[]] $DscResourceInfo ) if ((Test-Path -LiteralPath $ConfigurationPath -PathType Leaf) -eq $false) { Write-Error "Cannot find configuration file: $ConfigurationPath. Please make sure the file exists!" return } $ConfigurationPath = (Resolve-Path -LiteralPath $ConfigurationPath).ProviderPath Write-Verbose -Message "Loading file '$ConfigurationPath'" $fileContent = [System.IO.File]::ReadAllText($ConfigurationPath) try { $startPosition = $fileContent.IndexOf(' -ModuleVersion') if ($startPosition -gt 0) { $endPosition = $fileContent.IndexOf("`n", $startPosition) $fileContent = $fileContent.Remove($startPosition, $endPosition - $startPosition) } } catch { Write-Warning -Message "Error trying to remove Module Version: $($_.Exception | Out-String)" } $params = @{ Content = $fileContent } if ($IncludeComments) { $params.Add('IncludeComments', $true) } if ($PSBoundParameters.ContainsKey('DscResourceInfo')) { $params.Add('DscResourceInfo', $DscResourceInfo) } $parsedContent = ConvertTo-DSCObject @params if ($null -eq $parsedContent) { Write-Warning -Message "No configuration found in $ConfigurationPath. Either the configuration was empty or the file was not a valid DSC configuration." } return $parsedContent } <# .DESCRIPTION This function recursively converts a PowerShell object into an HTML list, flattening nested properties. .FUNCTIONALITY Internal, Hidden #> function Convert-ObjectToHtmlList { [CmdletBinding()] param( [Parameter(Mandatory = $true)] $InputObject, [Parameter()] [System.String] $ParentName = '', [Parameter()] [switch] $NoIndent ) $output = '' if ($InputObject -is [array]) { if (-not $NoIndent) { $output += '<ul>' } for ($i = 0; $i -lt $InputObject.Count; $i++) { $item = $InputObject[$i] $itemName = "$ParentName[$i]" if ($item -is [hashtable]) { $output += Convert-ObjectToHtmlList -InputObject $item -ParentName $itemName -NoIndent if ($i -lt $InputObject.Count - 1) { $output += '<hr/>' } } else { $output += "<li><strong>$(ConvertTo-M365DSCHtmlText -Value $itemName):</strong> $(ConvertTo-M365DSCHtmlText ($item | Out-String))</li>" } } if (-not $NoIndent) { $output += '</ul>' } } elseif ($InputObject -is [hashtable]) { if (-not $NoIndent) { $output += '<ul>' } foreach ($key in ($InputObject.Keys | Sort-Object)) { if ($key -ne 'CIMInstance') { $value = $InputObject.$key $childName = if ([System.String]::IsNullOrEmpty($ParentName)) { $key } else { "$ParentName.$key" } if ($value -is [hashtable] -or $value -is [array]) { $output += Convert-ObjectToHtmlList -InputObject $value -ParentName $childName -NoIndent } else { $output += "<li><strong>$(ConvertTo-M365DSCHtmlText -Value $childName):</strong> $(ConvertTo-M365DSCHtmlText ($value | Out-String))</li>" } } } if (-not $NoIndent) { $output += '</ul>' } } else { $output = "$(if ($NoIndent) { '' } else { '<ul>' })<li>$(ConvertTo-M365DSCHtmlText ($InputObject | Out-String))</li>$(if ($NoIndent) { '' } else { '</ul>' })" } return $output } Export-ModuleMember -Function @( 'New-M365DSCDeltaReport', 'New-M365DSCReportFromConfiguration', 'Get-M365DSCCIMInstanceKey' ) |