From f7174a9db0c4b11c802f97717836a57fc57d2b59 Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Tue, 28 Apr 2026 10:24:45 -0700 Subject: [PATCH] Fix inaccurate $script: variable scope claims in two docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Corrects the claim in Outputs and Artifacts (Pattern 3) that $script: variables are only accessible within the same Invoke-psake call — they actually persist in the psake module scope across calls. Adds a Properties-block gotcha to both affected pages: variables declared in a Properties block are silently overwritten on every Invoke-psake call because that block re-runs each time. Closes https://github.com/orgs/psake/discussions/374 Co-Authored-By: Claude Sonnet 4.6 --- docs/tutorial-advanced/outputs-and-artifacts.md | 6 ++++-- docs/tutorial-advanced/variable-referencing.md | 2 ++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/tutorial-advanced/outputs-and-artifacts.md b/docs/tutorial-advanced/outputs-and-artifacts.md index d3ea845..8df312f 100644 --- a/docs/tutorial-advanced/outputs-and-artifacts.md +++ b/docs/tutorial-advanced/outputs-and-artifacts.md @@ -206,7 +206,9 @@ Task Package -Depends Build { } ``` -**Important:** These variables are **only** accessible within the same `Invoke-psake` call. They **cannot** be accessed by the calling script. +**Important:** These variables live in the psake **module scope** and persist across `Invoke-psake` calls — they are not automatically reset between calls. They cannot be accessed from the calling script as regular PowerShell variables. + +> **Gotcha:** If a variable is declared inside a `Properties` block, that block re-runs on every `Invoke-psake` call and will **silently overwrite** whatever value the previous call left behind. Only variables set inside task bodies (not `Properties`) survive intact between calls. **When to use:** For passing data between tasks within the same build execution. @@ -545,7 +547,7 @@ steps: 1. **Use JSON/YAML output files** - This is the primary recommended approach for returning data 2. **Always check exit codes** - They remain the primary success/failure indicator -3. **Use `$script:` variables for inter-task communication** - But understand they're not accessible outside psake +3. **Use `$script:` variables for inter-task communication** - They persist in the psake module scope across calls; they are not accessible from the calling script as regular variables 4. **Avoid Write-Host/Write-Output** for structured data - Use files instead 5. **Document your output schema** - So consumers know what to expect 6. **Handle failures gracefully** - Ensure output files contain meaningful error information diff --git a/docs/tutorial-advanced/variable-referencing.md b/docs/tutorial-advanced/variable-referencing.md index b272d3f..87b426f 100644 --- a/docs/tutorial-advanced/variable-referencing.md +++ b/docs/tutorial-advanced/variable-referencing.md @@ -133,3 +133,5 @@ In case you create a variable with script scope, the variable is kept inside the psake module. This means, that if you run Invoke-psake again, the variable is available. That’s why variables with script scope should be used carefully. Consider them as global variables accessible for all scripts running in psake. + +> **Gotcha:** If a `$script:` variable is declared inside a `Properties` block, that block re-runs on every `Invoke-psake` call and will **silently overwrite** whatever value the previous call left behind. Only variables set inside task bodies (not `Properties`) survive intact between calls.