[bcullman]

Background

The Upgrade Octopus Server step swallowed download failures and emitted PowerShell formatting objects through its success output. Those objects could become part of the value passed to msiexec, causing malformed installer arguments and leaving the deployment apparently hung.

Further investigation also found that the existing single-stream WebClient.DownloadFile() request could fail after transferring a substantial portion of a large installer. The same installer downloaded successfully using bounded HTTP range requests.

Results

The updated step:

• Downloads the installer in bounded 32 MiB ranges.
• Retries a failed range from the current downloaded length.
• Requires HTTP 206 responses with the expected Content-Range.
• Validates the final file length and Authenticode signature.
• Removes an incomplete installer when downloading fails.
• Does not stop Octopus Server until the installer is completely downloaded and validated.
• Waits for msiexec and rejects nonzero exit codes.
• Attempts to restart Octopus Server after installation failure.
• Preserves the primary installation error if service recovery also fails.
• Removes the temporary installer after successful or failed installation.
• Adds isolated regression coverage for downloading, retry, validation, installation, cleanup, recovery, and template metadata.

Before

A failed WebClient download was caught but not rethrown. Formatting records from Format-List were written to the success stream alongside the temporary filename and could be passed to:

msiexec /i $tempFile /quiet

The installer process was not explicitly awaited or checked for a nonzero exit code.

After

Download failures are terminating and cannot reach service shutdown or MSI execution.

During a test-server upgrade, one range request failed after more than 503 MB had been downloaded. The step resumed from the downloaded length, completed and validated the 874,090,496-byte installer, installed the requested Octopus Server version, restarted the service, removed the temporary installer, and completed successfully.

Pre-requisites

• The existing nonzero template GUID is preserved.
• Version is incremented from 10 to 11.
• $Meta.ExportedAt and $Meta.OctopusVersion are updated.
• Parameter names do not start with $.
• Existing parameter names are not namespace-prefixed. They are intentionally preserved to avoid breaking consumers of the existing template.
• LastModifiedBy is updated to bcullman.
• LastModifiedDate is updated.
• Step-template best practices have been applied.
• No new category was created.

Validation

• 15 focused Pester tests passed.
• Step-template JSON lint passed.
• All 4 repository Jasmine specs passed.
• The complete repository build passed.
• git diff --check passed.
• Clean unpack reproduced the tested 179-line PowerShell script exactly.
• Semantic comparison confirmed that the template ID, parameters, defaults, description, category, and other unrelated properties remain unchanged.

Fixes #1710

[github-actions]

Review this PR in Hyponome for a side-by-side diff of the step-template JSON and any embedded scripts.