From 09011a37608c613acc34290c0257905615e82e19 Mon Sep 17 00:00:00 2001 From: Jiwon Lee Date: Thu, 25 Jun 2026 14:39:18 -0700 Subject: [PATCH 1/8] Add network isolation policy to compliance YAML --- .vsts-compliance.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.vsts-compliance.yml b/.vsts-compliance.yml index e093f96..9049ea4 100644 --- a/.vsts-compliance.yml +++ b/.vsts-compliance.yml @@ -39,6 +39,8 @@ resources: extends: template: azure-pipelines/MicroBuild.1ES.Unofficial.yml@MicroBuildTemplate parameters: + settings: + networkIsolationPolicy: Permissive,CFSClean,CFSClean2 pool: name: VSEngSS-MicroBuild2022-1ES sdl: From f4ea89f32892533748666a30b79a170dbda9640c Mon Sep 17 00:00:00 2001 From: Jiwon Lee Date: Thu, 25 Jun 2026 16:59:07 -0700 Subject: [PATCH 2/8] Add NuGet.config for package sources configuration --- NuGet.config | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 NuGet.config diff --git a/NuGet.config b/NuGet.config new file mode 100644 index 0000000..1d9db33 --- /dev/null +++ b/NuGet.config @@ -0,0 +1,7 @@ + + + + + + + From fdb4cb1e7f3fe5c89ec090be4881ddd0ade17d47 Mon Sep 17 00:00:00 2001 From: Jiwon Lee Date: Thu, 25 Jun 2026 17:12:53 -0700 Subject: [PATCH 3/8] Access internal nuget feed Updated the dotnet tool installation command to include a config file and added nuget configuration inputs for package restoration. --- build/build.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/build/build.yml b/build/build.yml index ee9bad4..9332212 100644 --- a/build/build.yml +++ b/build/build.yml @@ -11,7 +11,8 @@ parameters: steps: - pwsh: | - dotnet tool install --tool-path "${env:AGENT_TOOLSDIRECTORY}\nbgv" nbgv + dotnet tool install --tool-path "${env:AGENT_TOOLSDIRECTORY}\nbgv" ` + --configfile "$(Build.SourcesDirectory)\NuGet.config" nbgv $version = & "${env:AGENT_TOOLSDIRECTORY}\nbgv\nbgv.exe" get-version --variable SemVer1 & "${env:AGENT_TOOLSDIRECTORY}\nbgv\nbgv.exe" cloud --version $version displayName: Set cloud build version @@ -21,6 +22,9 @@ steps: - task: NuGetCommand@2 displayName: Restore nuget packages + inputs: + feedsToUse: config + nugetConfigPath: $(Build.SourcesDirectory)\NuGet.config - pwsh: | Install-Module -Name platyPS -Repository PSGallery -SkipPublisherCheck -Force @@ -115,6 +119,8 @@ steps: displayName: Restore nuget packages inputs: restoreSolution: $(Build.SourcesDirectory)\pkg\VSSetup\VSSetup.signproj + feedsToUse: config + nugetConfigPath: $(Build.SourcesDirectory)\NuGet.config - task: VSBuild@1 displayName: Sign packages From 22db17e9d89793858573bf163c70ba215c7d30a1 Mon Sep 17 00:00:00 2001 From: Jiwon Lee Date: Thu, 25 Jun 2026 17:24:43 -0700 Subject: [PATCH 4/8] Add NuGetAuthenticate task Added NuGet authentication step for Azure Artifacts. --- build/build.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/build/build.yml b/build/build.yml index 9332212..5755968 100644 --- a/build/build.yml +++ b/build/build.yml @@ -10,6 +10,9 @@ parameters: DockerProjectName: microsoft-vssetup-powershell steps: +- task: NuGetAuthenticate@1 + displayName: Authenticate to Azure Artifacts + - pwsh: | dotnet tool install --tool-path "${env:AGENT_TOOLSDIRECTORY}\nbgv" ` --configfile "$(Build.SourcesDirectory)\NuGet.config" nbgv From f1c89faaa0cecc3c4e5371385b4d02a57ec351e4 Mon Sep 17 00:00:00 2001 From: Jiwon Lee Date: Thu, 2 Jul 2026 15:16:42 -0700 Subject: [PATCH 5/8] Check in PowerShell help artifacts to remove PSGallery access from build The official build runs under 1ES network isolation and cannot reach the PowerShell Gallery, but build.yml installed platyPS from PSGallery and ran New-ExternalHelp to generate the cmdlet/about help. platyPS is not available on the Setup-Dependencies feed. Generate the help artifacts (Microsoft.VisualStudio.Setup.PowerShell.dll-Help.xml and about_VSSetup.help.txt) once and check them in under src\VSSetup.PowerShell\help. The project copies them to the build output, so the zip and nuspec still get the files without any network access. Add build\Update-Help.ps1 and a CONTRIBUTING note for regenerating them locally when docs\VSSetup changes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 12 + build/Update-Help.ps1 | 40 ++ build/build.yml | 11 - .../VSSetup.PowerShell.csproj | 8 + ...VisualStudio.Setup.PowerShell.dll-Help.xml | 379 ++++++++++++++++++ .../help/about_VSSetup.help.txt | 46 +++ 6 files changed, 485 insertions(+), 11 deletions(-) create mode 100644 build/Update-Help.ps1 create mode 100644 src/VSSetup.PowerShell/help/Microsoft.VisualStudio.Setup.PowerShell.dll-Help.xml create mode 100644 src/VSSetup.PowerShell/help/about_VSSetup.help.txt diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 875fa48..6fcf35e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,6 +17,17 @@ Code analysis and style cop rules are defined for this solution, but are current If you add any commands please update the `Tags` property of the _VSSetup.nuproj_ project as appropriate. This project is used instead of `Publish-Module` from the _PowerShellGet_ module because it works better with the build systems and can be tested on developer machines without also publishing. +## Documentation + +Cmdlet and `about_` help is authored as markdown under _docs\VSSetup_ and compiled into PowerShell help artifacts (_Microsoft.VisualStudio.Setup.PowerShell.dll-Help.xml_ and _about_VSSetup.help.txt_) using [platyPS][platyps]. + +Because the official build runs under network isolation and cannot reach the PowerShell Gallery, these artifacts are **checked in** under _src\VSSetup.PowerShell\help_ and copied to the build output by the project rather than generated during the build. If you change any markdown under _docs\VSSetup_, regenerate and commit the artifacts locally: + +```powershell +Install-Module -Name platyPS -Scope CurrentUser -Force +build\Update-Help.ps1 +``` + ## Building Before you can build this project from the command line with MSBuild or within Visual Studio, you must restore packages including the [embeddable interop types][interop]. @@ -96,3 +107,4 @@ Thank you for your contributions! [samples]: https://aka.ms/setup/configuration/samples [docs]: https://aka.ms/setup/configuration/docs [interop]: https://aka.ms/setup/configuration/interop + [platyps]: https://github.com/PowerShell/platyPS diff --git a/build/Update-Help.ps1 b/build/Update-Help.ps1 new file mode 100644 index 0000000..bdf65a9 --- /dev/null +++ b/build/Update-Help.ps1 @@ -0,0 +1,40 @@ +<# +.SYNOPSIS + Regenerates the checked-in PowerShell help artifacts from the markdown docs. + +.DESCRIPTION + The official build runs under 1ES network isolation and cannot reach the + PowerShell Gallery, so it no longer installs platyPS or runs New-ExternalHelp. + Instead, the generated help artifacts are checked in under + src\VSSetup.PowerShell\help and copied to the build output by the project. + + Run this script locally (outside the isolated build) whenever the cmdlet or + about_ markdown files under docs\VSSetup change, then commit the regenerated + files under src\VSSetup.PowerShell\help. + +.NOTES + Requires the platyPS module. Install it locally with: + Install-Module -Name platyPS -Scope CurrentUser -Force +#> +[CmdletBinding()] +param() + +$ErrorActionPreference = 'Stop' + +$repoRoot = Split-Path -Parent $PSScriptRoot +$docsPath = Join-Path $repoRoot 'docs\VSSetup' +$outputPath = Join-Path $repoRoot 'src\VSSetup.PowerShell\help' + +if (-not (Get-Module -ListAvailable -Name platyPS)) { + throw "platyPS is not installed. Run: Install-Module -Name platyPS -Scope CurrentUser -Force" +} + +Import-Module platyPS + +if (-not (Test-Path -Path $outputPath)) { + $null = New-Item -Path $outputPath -ItemType Directory +} + +New-ExternalHelp -Path $docsPath -OutputPath $outputPath -Force | Out-Null + +Write-Host "Regenerated help artifacts in $outputPath. Review and commit the changes." diff --git a/build/build.yml b/build/build.yml index 5755968..fa98e24 100644 --- a/build/build.yml +++ b/build/build.yml @@ -29,17 +29,6 @@ steps: feedsToUse: config nugetConfigPath: $(Build.SourcesDirectory)\NuGet.config -- pwsh: | - Install-Module -Name platyPS -Repository PSGallery -SkipPublisherCheck -Force - displayName: Install PowerShell modules - -- pwsh: | - New-ExternalHelp -Path docs\VSSetup -OutputPath "src\VSSetup.PowerShell\bin\${env:CONFIGURATION}" -Force - displayName: Compile documentation - env: - CONFIGURATION: ${{ parameters.BuildConfiguration }} - workingDirectory: $(Build.SourcesDirectory) - - task: VSBuild@1 displayName: Build solution inputs: diff --git a/src/VSSetup.PowerShell/VSSetup.PowerShell.csproj b/src/VSSetup.PowerShell/VSSetup.PowerShell.csproj index c248cec..771fe40 100644 --- a/src/VSSetup.PowerShell/VSSetup.PowerShell.csproj +++ b/src/VSSetup.PowerShell/VSSetup.PowerShell.csproj @@ -36,6 +36,14 @@ PreserveNewest + + %(Filename)%(Extension) + PreserveNewest + + + %(Filename)%(Extension) + PreserveNewest +