From 19c76720a36f9cdfd0816229c24a9709635ba266 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 31 Jan 2026 01:32:27 +0000 Subject: [PATCH 1/4] Add custom logging documentation for psake output handlers Covers overriding individual message type handlers and replacing the entire output routing logic via psake-config.ps1. https://claude.ai/code/session_0184Z4DLZ8Db72rkpca4kQwP --- docs/tutorial-advanced/custom-logging.md | 71 ++++++++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 72 insertions(+) create mode 100644 docs/tutorial-advanced/custom-logging.md diff --git a/docs/tutorial-advanced/custom-logging.md b/docs/tutorial-advanced/custom-logging.md new file mode 100644 index 0000000..fc3ca47 --- /dev/null +++ b/docs/tutorial-advanced/custom-logging.md @@ -0,0 +1,71 @@ +# Custom Logging + +psake routes all internal messages through configurable output handlers. You can override these handlers in your `psake-config.ps1` file to integrate with your own logging system. + +## Default Handlers + +psake ships with handlers for six message types: + +| Type | Default Behavior | +|------|-----------------| +| `heading` | Cyan colored output | +| `default` | `Write-Output` | +| `debug` | `Write-Debug` | +| `warning` | Yellow colored output | +| `error` | Red colored output | +| `success` | Green colored output | + +Unknown message types fall back to the `default` handler. + +## Override Specific Message Types + +To customize how individual message types are handled, override entries in `$config.outputHandlers` in your `psake-config.ps1`: + +```powershell +# psake-config.ps1 + +# Send warnings to a log file instead of the console +$config.outputHandlers.warning = { + Param($output) + Add-Content -Path "build-warnings.log" -Value $output +} + +# Suppress debug messages entirely +$config.outputHandlers.debug = { + Param($output) + # do nothing +} +``` + +Each handler receives a single `$output` parameter containing the message string. + +## Override All Logging + +To replace the entire routing logic, override `$config.outputHandler` (singular). This script block receives both the message and its type, giving you full control: + +```powershell +# psake-config.ps1 + +$config.outputHandler = { + Param($output, $type) + # Route everything through your custom logger + Write-MyBuildLog -Message $output -Level $type +} +``` + +When you override `outputHandler`, the individual `outputHandlers` entries are bypassed entirely. + +## Example: Log to a File + +```powershell +# psake-config.ps1 + +$config.outputHandler = { + Param($output, $type) + $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss" + $line = "[$timestamp] [$type] $output" + Add-Content -Path "build.log" -Value $line + # Still write to console + Write-Host $line +} +``` diff --git a/sidebars.ts b/sidebars.ts index 21cc354..525d4c7 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -41,6 +41,7 @@ const sidebars: SidebarsConfig = { 'tutorial-advanced/access-functions-in-another-file', 'tutorial-advanced/build-script-resilience', 'tutorial-advanced/debug-script', + 'tutorial-advanced/custom-logging', 'tutorial-advanced/logging-errors', 'tutorial-advanced/outputs-and-artifacts', 'tutorial-advanced/print-psake-task-name', From a5cd444d6de4d706a050caa74191dc3bc9a8a6b2 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 31 Jan 2026 01:58:56 +0000 Subject: [PATCH 2/4] Add psake-config.ps1 documentation Explains how psake discovers and loads the config file, lists all available configuration properties, and links to the custom logging doc for output handler details. https://claude.ai/code/session_0184Z4DLZ8Db72rkpca4kQwP --- docs/tutorial-advanced/custom-logging.md | 2 +- docs/tutorial-basics/psake-config.md | 81 ++++++++++++++++++++++++ sidebars.ts | 1 + 3 files changed, 83 insertions(+), 1 deletion(-) create mode 100644 docs/tutorial-basics/psake-config.md diff --git a/docs/tutorial-advanced/custom-logging.md b/docs/tutorial-advanced/custom-logging.md index fc3ca47..3946600 100644 --- a/docs/tutorial-advanced/custom-logging.md +++ b/docs/tutorial-advanced/custom-logging.md @@ -1,6 +1,6 @@ # Custom Logging -psake routes all internal messages through configurable output handlers. You can override these handlers in your `psake-config.ps1` file to integrate with your own logging system. +psake routes all internal messages through configurable output handlers. You can override these handlers in your [`psake-config.ps1`](../tutorial-basics/psake-config.md) file to integrate with your own logging system. ## Default Handlers diff --git a/docs/tutorial-basics/psake-config.md b/docs/tutorial-basics/psake-config.md new file mode 100644 index 0000000..3b4c35c --- /dev/null +++ b/docs/tutorial-basics/psake-config.md @@ -0,0 +1,81 @@ +# psake Configuration File + +psake loads a `psake-config.ps1` file at the start of every build to set default values for your build environment. You can use this file to change psake's default build file name, framework version, task name format, output handlers, and more. + +## How psake Finds the Config File + +psake searches for `psake-config.ps1` in two locations, in order: + +1. **The build script's directory** — the folder containing the build file passed to `Invoke-psake` +2. **The psake module directory** — the folder where `psake.psm1` is installed + +The first file found wins. If neither location contains a config file, psake uses its built-in defaults. + +This means you can place a `psake-config.ps1` next to your `psakefile.ps1` to customize settings per-project, or place one alongside the psake module for machine-wide defaults. + +## Configuration Properties + +Inside `psake-config.ps1`, you set properties on the `$config` variable. Here is every available property: + +| Property | Type | Default | Description | +|----------|------|---------|-------------| +| `buildFileName` | `string` | `"psakefile.ps1"` | Default build file name when none is specified | +| `legacyBuildFileName` | `string` | `"default.ps1"` | Fallback build file name (legacy support) | +| `framework` | `string` | `"4.0"` | .NET Framework version to target | +| `taskNameFormat` | `string` or `scriptblock` | `"Executing {0}"` | Format string or scriptblock for task name display | +| `verboseError` | `bool` | `$false` | Show detailed error information | +| `coloredOutput` | `bool` | `$true` | Enable colored console output | +| `modules` | `string[]` | `$null` | Module paths to auto-load before build execution | +| `moduleScope` | `string` | — | Scope for loaded modules | +| `outputHandler` | `scriptblock` | *(routes to outputHandlers)* | Master handler that receives all output | +| `outputHandlers` | `hashtable` | *(see below)* | Per-type output handlers | + +## Minimal Example + +```powershell title="psake-config.ps1" +# Use a different default build file name +$config.buildFileName = "build.ps1" + +# Target .NET 4.8 +$config.framework = "4.8" + +# Show detailed errors +$config.verboseError = $true +``` + +## Task Name Formatting + +`taskNameFormat` accepts either a format string or a scriptblock: + +```powershell title="psake-config.ps1" +# Format string — {0} is replaced with the task name +$config.taskNameFormat = "Executing {0}" + +# Scriptblock — receives the task name as a parameter +$config.taskNameFormat = { + param($taskName) + "Executing $taskName at $(Get-Date)" +} +``` + +## Auto-Loading Modules + +Use `$config.modules` to load PowerShell modules before any tasks run: + +```powershell title="psake-config.ps1" +# Load all modules from a folder +$config.modules = @(".\modules\*.psm1") + +# Load specific modules +$config.modules = @(".\modules\*.psm1", ".\my_module.psm1") +``` + +## Output Handlers + +psake routes all internal messages through configurable output handlers. For a full guide on customizing logging, see [Custom Logging](../tutorial-advanced/custom-logging.md). + +## See Also + +- [Custom Logging](../tutorial-advanced/custom-logging.md) — Override psake's output handlers +- [Configuration Reference](../reference/configuration-reference.md) — Full reference for `Invoke-psake` parameters and build script settings +- [Structure of a psake Build Script](../tutorial-advanced/structure-of-a-psake-build-script.md) — How build scripts are organized diff --git a/sidebars.ts b/sidebars.ts index 525d4c7..c2ffc98 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -20,6 +20,7 @@ const sidebars: SidebarsConfig = { 'tutorial-basics/run-psake', 'tutorial-basics/tasks', 'tutorial-basics/parameters-properties', + 'tutorial-basics/psake-config', ], // Guides - How-to guides, examples, and best practices From 2fe2203ae20aaacaec5d1e1182bd4fe537c4a2bb Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 31 Jan 2026 02:17:09 +0000 Subject: [PATCH 3/4] Move psake-config doc to Advanced Techniques and clarify scope - Moved from tutorial-basics to tutorial-advanced since this is an uncommon, advanced topic - Added note that most projects don't need a config file - Added "Partial Overrides" section explaining that missing properties keep their defaults - Fixed cross-reference links https://claude.ai/code/session_0184Z4DLZ8Db72rkpca4kQwP --- docs/tutorial-advanced/custom-logging.md | 2 +- .../psake-config.md | 16 ++++++++++++---- sidebars.ts | 2 +- 3 files changed, 14 insertions(+), 6 deletions(-) rename docs/{tutorial-basics => tutorial-advanced}/psake-config.md (80%) diff --git a/docs/tutorial-advanced/custom-logging.md b/docs/tutorial-advanced/custom-logging.md index 3946600..770b5af 100644 --- a/docs/tutorial-advanced/custom-logging.md +++ b/docs/tutorial-advanced/custom-logging.md @@ -1,6 +1,6 @@ # Custom Logging -psake routes all internal messages through configurable output handlers. You can override these handlers in your [`psake-config.ps1`](../tutorial-basics/psake-config.md) file to integrate with your own logging system. +psake routes all internal messages through configurable output handlers. You can override these handlers in your [`psake-config.ps1`](./psake-config.md) file to integrate with your own logging system. ## Default Handlers diff --git a/docs/tutorial-basics/psake-config.md b/docs/tutorial-advanced/psake-config.md similarity index 80% rename from docs/tutorial-basics/psake-config.md rename to docs/tutorial-advanced/psake-config.md index 3b4c35c..30b01eb 100644 --- a/docs/tutorial-basics/psake-config.md +++ b/docs/tutorial-advanced/psake-config.md @@ -2,6 +2,10 @@ psake loads a `psake-config.ps1` file at the start of every build to set default values for your build environment. You can use this file to change psake's default build file name, framework version, task name format, output handlers, and more. +:::note +Most projects do not need a `psake-config.ps1` file. psake's built-in defaults work well for the majority of use cases. Only create one if you need to change a specific default. +::: + ## How psake Finds the Config File psake searches for `psake-config.ps1` in two locations, in order: @@ -13,6 +17,10 @@ The first file found wins. If neither location contains a config file, psake use This means you can place a `psake-config.ps1` next to your `psakefile.ps1` to customize settings per-project, or place one alongside the psake module for machine-wide defaults. +## Partial Overrides + +Your config file does not need to set every property. psake initializes all properties to their defaults before loading your config file, so any property you omit keeps its default value. You only need to set the properties you want to change. + ## Configuration Properties Inside `psake-config.ps1`, you set properties on the `$config` variable. Here is every available property: @@ -72,10 +80,10 @@ $config.modules = @(".\modules\*.psm1", ".\my_module.psm1") ## Output Handlers -psake routes all internal messages through configurable output handlers. For a full guide on customizing logging, see [Custom Logging](../tutorial-advanced/custom-logging.md). +psake routes all internal messages through configurable output handlers. For a full guide on customizing logging, see [Custom Logging](./custom-logging.md). ## See Also -- [Custom Logging](../tutorial-advanced/custom-logging.md) — Override psake's output handlers -- [Configuration Reference](../reference/configuration-reference.md) — Full reference for `Invoke-psake` parameters and build script settings -- [Structure of a psake Build Script](../tutorial-advanced/structure-of-a-psake-build-script.md) — How build scripts are organized +- [Custom Logging](./custom-logging.md) — Override psake's output handlers +- [Configuration Reference](../reference/configuration-reference) — Full reference for `Invoke-psake` parameters and build script settings +- [Structure of a psake Build Script](./structure-of-a-psake-build-script.md) — How build scripts are organized diff --git a/sidebars.ts b/sidebars.ts index c2ffc98..eadf34c 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -20,7 +20,6 @@ const sidebars: SidebarsConfig = { 'tutorial-basics/run-psake', 'tutorial-basics/tasks', 'tutorial-basics/parameters-properties', - 'tutorial-basics/psake-config', ], // Guides - How-to guides, examples, and best practices @@ -43,6 +42,7 @@ const sidebars: SidebarsConfig = { 'tutorial-advanced/build-script-resilience', 'tutorial-advanced/debug-script', 'tutorial-advanced/custom-logging', + 'tutorial-advanced/psake-config', 'tutorial-advanced/logging-errors', 'tutorial-advanced/outputs-and-artifacts', 'tutorial-advanced/print-psake-task-name', From 461fef22a29012f5347f521f5723f32faafad663 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 31 Jan 2026 02:31:50 +0000 Subject: [PATCH 4/4] Update logging-errors doc to reflect pluggable logging support The previous intro stated psake had no way to log errors to a file, which is no longer true with the outputHandlers feature. Updated to describe the default behavior and link to the custom logging doc. https://claude.ai/code/session_0184Z4DLZ8Db72rkpca4kQwP --- docs/tutorial-advanced/logging-errors.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/tutorial-advanced/logging-errors.md b/docs/tutorial-advanced/logging-errors.md index 71707b5..55cc4dc 100644 --- a/docs/tutorial-advanced/logging-errors.md +++ b/docs/tutorial-advanced/logging-errors.md @@ -1,12 +1,10 @@ # Logging Errors -The latest version of **psake** no longer provides a way to log errors to a -file. Most builds are executed by a continuous integration server which already -logs all console output so it's redundant to provide that same functionality in -psake. If an error does occur detailed error information is emitted to the -console so that it will get saved by whatever CI server is running psake. +By default, psake does not log errors to a file. When an error occurs, detailed error information is emitted to the console. Most CI servers capture all console output, so this is usually sufficient. -Here is an example of an error from a psake build script: +If you need to route errors to a file or custom logger, you can override psake's error output handler. See [Custom Logging](./custom-logging.md) for details. + +Here is an example of the default error output from a psake build script: ```powershell ----------------------------------------------------------------------