From 6abc0a6148424f74b534a6d836a23ef974c669a2 Mon Sep 17 00:00:00 2001 From: Timothy Wamalwa Date: Sat, 27 May 2023 14:29:08 +0300 Subject: [PATCH 1/3] Reviewed script by adding commands with their corresponding paths and methods to the hash table --- tools/ExamplesGenerator.ps1 | 177 ++++++++++++++++-------------------- 1 file changed, 80 insertions(+), 97 deletions(-) diff --git a/tools/ExamplesGenerator.ps1 b/tools/ExamplesGenerator.ps1 index 1a0dace973b..225aee7fda4 100644 --- a/tools/ExamplesGenerator.ps1 +++ b/tools/ExamplesGenerator.ps1 @@ -7,7 +7,7 @@ Param( [hashtable]$BetaCommandGetVariantList= @{}, [hashtable]$V1CommandListVariantList= @{}, [hashtable]$BetaCommandListVariantList= @{}, - [string] $ModuleMappingConfigPath = (Join-Path $PSScriptRoot "..\config\ModulesMapping.jsonc"), + [string] $ModuleMappingConfigPath = (Join-Path $PSScriptRoot "..\config\\ModulesMapping.jsonc"), [string] $FolderForExamplesToBeReviewed = (Join-Path $PSScriptRoot "..\examplesreport"), [string] $ExamplesToBeReviewed = "ExamplesToBeReviewed.csv", $MetaDataJsonFile = (Join-Path $PSScriptRoot "../src/Authentication/Authentication/custom/common/MgCommandMetadata.json") @@ -87,17 +87,20 @@ function Get-Files { #Extract command over here $Command = [System.IO.Path]::GetFileNameWithoutExtension($File) #Extract URI path - $UriPath = $null + $CommandValue = $null if($GraphProfile -eq "beta"){ - $UriPath = $BetaCommandGetVariantList[$Command] + $CommandValue = $BetaCommandGetVariantList[$Command] + }else{ - $UriPath = $V1CommandGetVariantList[$Command] + $CommandValue = $V1CommandGetVariantList[$Command] } - if ($UriPath) { - $Method = $UriPaths.Method - Get-ExternalDocsUrl -GraphProfile $GraphProfile -Url -UriPath $UriPath -Command $Command -OpenApiContent $OpenApiContent -GraphProfilePath $GraphProfilePath -Method $Method -Module $Module - } + if ($CommandValue) { + $CommandValueParams = $CommandValue.Split(",") + $ApiPath = $CommandValueParams[0] + $Method = $CommandValueParams[1] + Get-ExternalDocsUrl -GraphProfile $GraphProfile -Url -UriPath $ApiPath -Command $Command -OpenApiContent $OpenApiContent -GraphProfilePath $GraphProfilePath -Method $Method.Trim() -Module $Module + } } } @@ -125,7 +128,6 @@ function Get-ExternalDocsUrl { [System.Object] $Method = "GET", [string] $GraphProfilePath = (Join-Path $PSScriptRoot "..\src\Users\v1.0\examples") ) - if ($GenerationMode -eq "manual") { if (-not([string]::IsNullOrEmpty($ManualExternalDocsUrl))) { @@ -139,94 +141,54 @@ function Get-ExternalDocsUrl { if ($OpenApiContent.openapi && $OpenApiContent.info.version) { foreach ($Path in $OpenApiContent.paths) { - $MethodName = $Method | Out-String - $ExternalDocUrl = $Path[$UriPath].values.externalDocs.url - - if ([string]::IsNullOrEmpty($ExternalDocUrl)) { - $PathSplit = $UriPath.Split("/") - $PathToAppend = $PathSplit[$PathSplit.Count - 1] - if ($PathToAppend.StartsWith("{") -or $PathToAppend.StartsWith("$")) { - #skip - } - else { - $PathRebuild = "/" + $PathSplit[0] - for ($i = 1; $i -lt $PathSplit.Count - 1; $i++) { - $PathRebuild += $PathSplit[$i] + "/" + $ExternalDocUrl = $null + switch($Method){ + "GET" { + $ExternalDocUrl = $path[$UriPath].get.externalDocs.url + if ([string]::IsNullOrEmpty($ExternalDocUrl)) { + $GETApiPath = Extract-PathFromListVariant -GraphProfile $GraphProfile -Command $Command + if(-not([string]::IsNullOrEmpty($GETApiPath))){ + $ExternalDocUrl = $Path[$GETApiPath].get.externalDocs.url + } } - $RebuiltPath = $PathRebuild + "microsoft.graph." + $PathToAppend - $ExternalDocUrl = $path[$RebuiltPath].get.externalDocs.url + } + "POST" { + $ExternalDocUrl = $Path[$UriPath].post.externalDocs.url + if ([string]::IsNullOrEmpty($ExternalDocUrl)) { + $POSTApiPath = Extract-PathFromListVariant -GraphProfile $GraphProfile -Command $Command + if(-not([string]::IsNullOrEmpty($POSTApiPath))){ + $ExternalDocUrl = $Path[$POSTApiPath].post.externalDocs.url + } + } + } + "PATCH" { + $ExternalDocUrl = $Path[$UriPath].patch.externalDocs.url if ([string]::IsNullOrEmpty($ExternalDocUrl)) { - $UriPath2 = $null - if($GraphProfile -eq "beta"){ - $UriPath2 = $BetaCommandListVariantList[$Command] - }else{ - $UriPath2 = $V1CommandListVariantList[$Command] - } - if(-not([string]::IsNullOrEmpty($UriPath2))){ - $ExternalDocUrl = $Path[$UriPath2].get.externalDocs.url - } - + $PATCHApiPath = Extract-PathFromListVariant -GraphProfile $GraphProfile -Command $Command + if(-not([string]::IsNullOrEmpty($PATCHApiPath))){ + $ExternalDocUrl = $Path[$PATCHApiPath].patch.externalDocs.url + } } } - } - if ($MethodName -eq "POST") { - $ExternalDocUrl = $Path[$UriPath].post.externalDocs.url - if ([string]::IsNullOrEmpty($ExternalDocUrl)) { - $UriPath3 = $null - if($GraphProfile -eq "beta"){ - $UriPath3 = $BetaCommandListVariantList[$Command] - }else{ - $UriPath3 = $V1CommandListVariantList[$Command] + "DELETE" { + $ExternalDocUrl = $Path[$UriPath].delete.externalDocs.url + if ([string]::IsNullOrEmpty($ExternalDocUrl)) { + $DELETEApiPath = Extract-PathFromListVariant -GraphProfile $GraphProfile -Command $Command + if(-not([string]::IsNullOrEmpty($DELETEApiPath))){ + $ExternalDocUrl = $Path[$DELETEApiPath].delete.externalDocs.url + } } - if(-not([string]::IsNullOrEmpty($UriPath3))){ - $ExternalDocUrl = $Path[$UriPath3].post.externalDocs.url - } - } - } - - if ($MethodName -eq "PATCH") { - $ExternalDocUrl = $Path[$UriPath].patch.externalDocs.url - if ([string]::IsNullOrEmpty($ExternalDocUrl)) { - $UriPath4 = $null - if($GraphProfile -eq "beta"){ - $UriPath4 = $BetaCommandListVariantList[$Command] - }else{ - $UriPath4 = $V1CommandListVariantList[$Command] - } - if(-not([string]::IsNullOrEmpty($UriPath4))){ - $ExternalDocUrl = $Path[$UriPath4].post.externalDocs.url - } - } - } - - if ($MethodName -eq "DELETE") { - $ExternalDocUrl = $Path[$UriPath].delete.externalDocs.url - if ([string]::IsNullOrEmpty($ExternalDocUrl)) { - $UriPath5 = $null - if($GraphProfile -eq "beta"){ - $UriPath5 = $BetaCommandListVariantList[$Command] - }else{ - $UriPath5 = $V1CommandListVariantList[$Command] - } - if(-not([string]::IsNullOrEmpty($UriPath5))){ - $ExternalDocUrl = $Path[$UriPath5].post.externalDocs.url - } - } - } - - if ($MethodName -eq "PUT") { - $ExternalDocUrl = $Path[$UriPath].put.externalDocs.url - if ([string]::IsNullOrEmpty($ExternalDocUrl)) { - $UriPath6 = $null - if($GraphProfile -eq "beta"){ - $UriPath6 = $BetaCommandListVariantList[$Command] - }else{ - $UriPath6 = $V1CommandListVariantList[$Command] + } + "PUT" { + $ExternalDocUrl = $Path[$UriPath].put.externalDocs.url + if ([string]::IsNullOrEmpty($ExternalDocUrl)) { + $PUTApiPath = Extract-PathFromListVariant -GraphProfile $GraphProfile -Command $Command + if(-not([string]::IsNullOrEmpty($PUTApiPath))){ + $ExternalDocUrl = $Path[$PUTApiPath].put.externalDocs.url + } } - if(-not([string]::IsNullOrEmpty($UriPath6))){ - $ExternalDocUrl = $Path[$UriPath6].post.externalDocs.url - } - } + } + } if (-not([string]::IsNullOrEmpty($ExternalDocUrl))) { Start-WebScrapping -GraphProfile $GraphProfile -ExternalDocUrl $ExternalDocUrl -Command $Command -GraphProfilePath $GraphProfilePath -UriPath $UriPath -Module $Module @@ -238,6 +200,25 @@ function Get-ExternalDocsUrl { } } +function Extract-PathFromListVariant{ + param( + [ValidateSet("beta", "v1.0")] + [string] $GraphProfile = "v1.0", + [string] $Command = "Get-MgUser" + ) + $ListApiPath = $null + $ListCommandValue = $null + if($GraphProfile -eq "beta"){ + $ListCommandValue = $BetaCommandListVariantList[$Command] + }else{ + $ListCommandValue = $V1CommandListVariantList[$Command] + } + if(-not([string]::IsNullOrEmpty($ListCommandValue))){ + $ListCommandValueParams = $ListCommandValue.Split(",") + $ListApiPath = $ListCommandValueParams[0] + } + return $ListApiPath +} function Start-WebScrapping { param( [ValidateSet("beta", "v1.0")] @@ -407,19 +388,20 @@ foreach($Data in $DeserializedContent) if($Data.ApiVersion -eq "beta") { if((-not($Data.Variants[0].Contains("List")))){ - $Beta = $BetaCommandGetVariantList.Add($Data.Command, $Data.Uri) + $BetaAPIPathAndMethod = $Data.Uri,$Data.Method -join "," + $Beta = $BetaCommandGetVariantList.Add($Data.Command, $BetaAPIPathAndMethod) }else{ - $Beta1 = $BetaCommandListVariantList.Add($Data.Command, $Data.Uri) + $Beta1 = $BetaCommandListVariantList.Add($Data.Command, $BetaAPIPathAndMethod) } } if($Data.ApiVersion -eq "v1.0") { - + $V1APIPathAndMethod = $Data.Uri,$Data.Method -join "," if((-not($Data.Variants[0].Contains("List")))){ - $V1 = $V1CommandGetVariantList.Add($Data.Command, $Data.Uri) + $V1 = $V1CommandGetVariantList.Add($Data.Command, $V1APIPathAndMethod) }else{ - $V11 = $V1CommandListVariantList.Add($Data.Command, $Data.Uri) + $V11 = $V1CommandListVariantList.Add($Data.Command, $V1APIPathAndMethod) } } } @@ -459,4 +441,5 @@ Start-Generator -ModulesToGenerate $ModulesToGenerate -GenerationMode "auto" #4. Test for beta updates from api reference #Start-Generator -GenerationMode "manual" -ManualExternalDocsUrl "https://docs.microsoft.com/graph/api/serviceprincipal-post-approleassignedto?view=graph-rest-beta" -GraphCommand "New-MgBetaServicePrincipalAppRoleAssignedTo" -GraphModule "Applications" -Profile "beta" -#Write-Host -ForegroundColor Green "-------------Done-------------" \ No newline at end of file +#Write-Host -ForegroundColor Green "-------------Done-------------" +#Start-Generator -GenerationMode "manual" -ManualExternalDocsUrl "https://learn.microsoft.com/en-us/graph/api/federatedidentitycredential-delete?view=graph-rest-1.0&tabs=powershell" -GraphCommand "Remove-MgBetaApplicationFederatedIdentityCredential" -GraphModule "Applications" -Profile "beta" \ No newline at end of file From 72cd9db5934a06c5bf3ef0336d2374f1c6cdf1fb Mon Sep 17 00:00:00 2001 From: Timothy Wamalwa Date: Mon, 29 May 2023 15:05:53 +0300 Subject: [PATCH 2/3] Reviewed script --- tools/ExamplesGenerator.ps1 | 68 ++++++++++++++++++++++++++++++++----- 1 file changed, 60 insertions(+), 8 deletions(-) diff --git a/tools/ExamplesGenerator.ps1 b/tools/ExamplesGenerator.ps1 index 225aee7fda4..7f3ae79e10e 100644 --- a/tools/ExamplesGenerator.ps1 +++ b/tools/ExamplesGenerator.ps1 @@ -233,8 +233,12 @@ function Start-WebScrapping { ) $ExampleFile = "$GraphProfilePath/$Command.md" $url = $ExternalDocUrl - - $Description = "This example shows how to use the $Command Cmdlet.`r`n`r`To learn about permissions for this resource, see the [permissions reference](/graph/permissions-reference)." + $DescriptionCommand = $Command + if($GraphProfile -eq "beta"){ + $DescriptionCommand= $Command.Replace("-MgBeta", "-Mg") + } + + $Description = "This example shows how to use the $DescriptionCommand Cmdlet.`r`n`r`To learn about permissions for this resource, see the [permissions reference](/graph/permissions-reference)." $WebResponse = Invoke-WebRequest -Uri $url $HeaderList = New-Object -TypeName 'System.Collections.ArrayList'; $ExampleList = New-Object -TypeName 'System.Collections.ArrayList'; @@ -277,7 +281,10 @@ function Update-ExampleFile { [ValidateNotNullOrEmpty()] [string] $ExternalDocUrl = "https://learn.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0&tabs=powershell" ) - + $CommandPattern = $Command + if($GraphProfile -eq "beta"){ + $CommandPattern = $Command.Replace("-MgBeta", "-Mg") + } $Content = Get-Content -Path $ExampleFile $SearchText = "Example" $SearchTextForNewImports = "{{ Add description here }}" @@ -303,12 +310,15 @@ function Update-ExampleFile { $HeadCount = $HeaderList.Count $ExampleCount = $ExampleList.Count $WrongExamplesCount = 0; + $SkippedExample = -1 + $ContainsRightExamples = $False + #===========================Importing new examples into files ============================================# if ($ReplaceEverything -and $ExampleCount -gt 0 -and $HeadCount -eq $ExampleCount) { Clear-Content $ExampleFile -Force for ($d = 0; $d -lt $HeaderList.Count; $d++) { $CodeValue = $ExampleList[$d].Trim() - if($CodeValue.Contains($Command)){ + if($CodeValue.Contains($CommandPattern)){ $TitleValue = "### " + $HeaderList[$d].Trim() $Code = "``````powershell`r$CodeValue`r`n``````" @@ -319,12 +329,16 @@ function Update-ExampleFile { $TotalText = $TotalText.Replace("Microsoft.Graph", "Microsoft.Graph.Beta") } Add-Content -Path $ExampleFile -Value $TotalText + $ContainsRightExamples = $True }else{ $WrongExamplesCount++ + $SkippedExample++ } } } + #The code below updates existing examples + #------------------------------------------------------------# $PatternToSearch = "Import-Module Microsoft.Graph.$Module" if(($Content | Select-String -pattern $SearchText) -and ($Content | Select-String -pattern "This example shows")){ $ContainsPatternToSearch = $False @@ -335,12 +349,14 @@ function Update-ExampleFile { } if($ContainsPatternToSearch){ Clear-Content $ExampleFile -Force - #Replace everything + for ($d = 0; $d -lt $HeaderList.Count; $d++) { + #We should only add the correct examples from external docs link + if($ExampleList[$d].Contains($CommandPattern)){ $CodeValue = $ExampleList[$d].Trim() $TitleValue = "### " + $HeaderList[$d].Trim() $Code = "``````powershell`r$CodeValue`r`n``````" - + $TotalText = "$TitleValue`r`n`n$Code`r`n$Description`r`n" if($GraphProfile -eq "beta"){ #Replace examples to match the new beta naming convention @@ -348,8 +364,14 @@ function Update-ExampleFile { $TotalText = $TotalText.Replace("Microsoft.Graph", "Microsoft.Graph.Beta") } Add-Content -Path $ExampleFile -Value $TotalText + }else{ + $SkippedExample++ + } + } + + }else{ Clear-Content $ExampleFile -Force #Replace everything with boiler plate code @@ -358,7 +380,37 @@ function Update-ExampleFile { } } - if($WrongExamplesCount -gt 0){ + #The code below corrects the numbering of the example headers/title if there is a situation where + #some examples are wrong(which are left out) and some are right + #-----------------------------------------------------------------------------------------------# + $AvailableCorrectExamples = 1 + if($SkippedExample -gt -1){ + $NewContent = Get-Content -Path $ExampleFile + foreach($C in $NewContent){ + if($C.Contains("Example")){ + $SearchString = $c.Split(":") + $StringToReplace = $SearchString[0] + $ReplacementString = "### Example $AvailableCorrectExamples" + (Get-Content -Path $ExampleFile) -replace $StringToReplace, $ReplacementString | Set-Content $ExampleFile + $AvailableCorrectExamples++ + } + } + if(-not(Test-Path -PathType Container $FolderForExamplesToBeReviewed)){ + New-Item -ItemType Directory -Force -Path $FolderForExamplesToBeReviewed + } + if (-not (Test-Path "$FolderForExamplesToBeReviewed\$ExamplesToBeReviewed")) { + "Command, ExternalDocsUrl, ApiVersion" | Out-File -FilePath "$FolderForExamplesToBeReviewed\$ExamplesToBeReviewed" -Encoding ASCII + } + + $File = Get-Content "$FolderForExamplesToBeReviewed\$ExamplesToBeReviewed" + $containsWord = $File | % { $_ -match "$Command, $ExternalDocUrl, $GraphProfile, $UriPath" } + if (-not($containsWord -contains $true)) { + "$Command, $ExternalDocUrl, $GraphProfile, $UriPath" | Out-File -FilePath "$FolderForExamplesToBeReviewed\$ExamplesToBeReviewed" -Append -Encoding ASCII + } + } + #-----------------------------------------------------------------------------------------------------------------------------------------------------------------# + if(($WrongExamplesCount -gt 0) -and -not($ContainsRightExamples)){ + Clear-Content $ExampleFile -Force $DefaultBoilerPlate = "### Example 1: {{ Add title here }}`r`n``````powershell`r`n PS C:\> {{ Add code here }}`r`n`n{{ Add output here }}`r`n```````n`n{{ Add description here }}`r`n`n### Example 2: {{ Add title here }}`r`n``````powershell`r`n PS C:\> {{ Add code here }}`r`n`n{{ Add output here }}`r`n```````n`n{{ Add description here }}`r`n`n" Add-Content -Path $ExampleFile -Value $DefaultBoilerPlate.Trim() #Log api path api version and equivalent external doc url giving wron examples @@ -442,4 +494,4 @@ Start-Generator -ModulesToGenerate $ModulesToGenerate -GenerationMode "auto" #4. Test for beta updates from api reference #Start-Generator -GenerationMode "manual" -ManualExternalDocsUrl "https://docs.microsoft.com/graph/api/serviceprincipal-post-approleassignedto?view=graph-rest-beta" -GraphCommand "New-MgBetaServicePrincipalAppRoleAssignedTo" -GraphModule "Applications" -Profile "beta" #Write-Host -ForegroundColor Green "-------------Done-------------" -#Start-Generator -GenerationMode "manual" -ManualExternalDocsUrl "https://learn.microsoft.com/en-us/graph/api/federatedidentitycredential-delete?view=graph-rest-1.0&tabs=powershell" -GraphCommand "Remove-MgBetaApplicationFederatedIdentityCredential" -GraphModule "Applications" -Profile "beta" \ No newline at end of file +#Start-Generator -GenerationMode "manual" -ManualExternalDocsUrl "https://docs.microsoft.com/graph/api/meetingattendancereport-get?view=graph-rest-1.0" -GraphCommand "Get-MgBetaCommunicationCallAudioRoutingGroup" -GraphModule "CloudCommunications" -Profile "beta" \ No newline at end of file From ac6ffeb4d2209bfa08e04e7371913f5862995a0a Mon Sep 17 00:00:00 2001 From: Tim Date: Tue, 30 May 2023 21:22:12 +0300 Subject: [PATCH 3/3] Update tools/ExamplesGenerator.ps1 Co-authored-by: Peter Ombwa --- tools/ExamplesGenerator.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/ExamplesGenerator.ps1 b/tools/ExamplesGenerator.ps1 index 7f3ae79e10e..fb52924ebb6 100644 --- a/tools/ExamplesGenerator.ps1 +++ b/tools/ExamplesGenerator.ps1 @@ -7,7 +7,7 @@ Param( [hashtable]$BetaCommandGetVariantList= @{}, [hashtable]$V1CommandListVariantList= @{}, [hashtable]$BetaCommandListVariantList= @{}, - [string] $ModuleMappingConfigPath = (Join-Path $PSScriptRoot "..\config\\ModulesMapping.jsonc"), + [string] $ModuleMappingConfigPath = (Join-Path $PSScriptRoot "..\config\ModulesMapping.jsonc"), [string] $FolderForExamplesToBeReviewed = (Join-Path $PSScriptRoot "..\examplesreport"), [string] $ExamplesToBeReviewed = "ExamplesToBeReviewed.csv", $MetaDataJsonFile = (Join-Path $PSScriptRoot "../src/Authentication/Authentication/custom/common/MgCommandMetadata.json")