Merge pull request #1403 from Badgerati/develop

v2.11.0

.devcontainer/devcontainer.json

@@ -0,0 +1,19 @@
+{
+  "name": "Codespace with PowerShell, Pester, Invoke-Build, and .NET 8",
+  "image": "mcr.microsoft.com/vscode/devcontainers/base:ubuntu",
+  "features": {
+    "ghcr.io/devcontainers/features/powershell:1": {},
+    "ghcr.io/devcontainers/features/dotnet:1": {
+      "version": "8.0"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-vscode.powershell",
+        "pspester.pester-test"
+      ]
+    }
+  },
+  "postCreateCommand": "pwsh -Command 'Install-Module -Name InvokeBuild,Pester -Force -SkipPublisherCheck; sleep 5; Invoke-Build Build   '"
+}

.github/CONTRIBUTING.md

@@ -30,6 +30,7 @@ The following is a set of guidelines for contributing to Pode on GitHub. These a
       - [Where-Object](#where-object)
       - [Select-Object](#select-object)
       - [Measure-Object](#measure-object)
+      - [New-Object](#new-object)
 
 ## Code of Conduct
 
@@ -245,3 +246,15 @@ Instead of using the `Measure-Object` commandlet, please use either the `.Length
 (@(1, 2, 3)).Length
 (@{ Name = 'Rick' }).Count
 ```
+
+#### New-Object
+
+Instead of using the `New-Object` commandlet, please use `::new()` as this is far faster than the former.
+
+```powershell
+# instead of
+$stream = New-Object System.IO.MemoryStream
+
+# do this
+$stream = [System.IO.MemoryStream]::new()
+```

.github/workflows/PSScriptAnalyzer.yml

@@ -3,7 +3,7 @@
 # separate terms of service, privacy policy, and support
 # documentation.
 #
-# https://github.com/microsoft/action-psscriptanalyzer
+# https://github.com/microsoft/psscriptanalyzer-action
 # For more information on PSScriptAnalyzer in general, see
 # https://github.com/PowerShell/PSScriptAnalyzer
 
@@ -48,15 +48,11 @@ jobs:
       - name: Run PSScriptAnalyzer
         uses: microsoft/psscriptanalyzer-action@6b2948b1944407914a58661c49941824d149734f
         with:
-          # Check https://github.com/microsoft/action-psscriptanalyzer for more info about the options.
-          # The below set up runs PSScriptAnalyzer to your entire repository and runs some basic security rules.
-          path: .\
+          path: .\src
           recurse: true
-          # Include your own basic security rules. Removing this option will run all the rules
-          includeRule: '"PSAvoidUsingCmdletAliases" ,"PSAvoidUsingPlainTextForPassword","PSAvoidUsingWriteHost","PSAvoidUsingInvokeExpression","PSUseShouldProcessForStateChangingFunctions","PSAvoidUsingUsernameAndPasswordParams","PSUseProcessBlockForPipelineCommand","PSAvoidUsingConvertToSecureStringWithPlainText","PSUseSingularNouns","PSReviewUnusedParameter"'
+          settings: .\PSScriptAnalyzerSettings.psd1
           output: results.sarif
 
-      # Upload the SARIF file generated in the previous step
       - name: Upload SARIF results file
         uses: github/codeql-action/upload-sarif@v3
         with:

.github/workflows/ci-no-build-needed.yml

@@ -12,7 +12,8 @@ on:
     - 'src/**'
     - 'tests/**'
     - '.github/workflows/ci-docs.yml'
-    - '.github/workflows/ci-pwsh*.yml'
+    - '.github/workflows/ci-pwsh_lts.yml'
+    - '.github/workflows/ci-pwsh7_2.yml'
     - '.github/workflows/ci-powershell.yml'
     - '.github/workflows/ci-coverage.yml'
     - '.github/workflows/PSScriptAnalyzer.yml'
@@ -30,7 +31,8 @@ on:
     - 'src/**'
     - 'tests/**'
     - '.github/workflows/ci-docs.yml'
-    - '.github/workflows/ci-pwsh*.yml'
+    - '.github/workflows/ci-pwsh_lts.yml'
+    - '.github/workflows/ci-pwsh7_2.yml'
     - '.github/workflows/ci-powershell.yml'
     - '.github/workflows/ci-coverage.yml'
     - '.github/workflows/PSScriptAnalyzer.yml'

.github/workflows/ci-pwsh_preview.yml

@@ -28,7 +28,7 @@ env:
   POWERSHELL_VERSION: 'Preview'
 
 jobs:
-  build:
+  build-preview:
     runs-on: ${{ matrix.os }}
 
     strategy:

.github/workflows/label-issue-project.yml

@@ -10,7 +10,7 @@ jobs:
     name: Add issue to project
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/[email protected].1
+      - uses: actions/[email protected].2
         with:
           project-url: https://github.com/users/Badgerati/projects/2
           github-token: ${{ secrets.PROJECT_TOKEN }}

.github/workflows/open-issue-project.yml

@@ -10,7 +10,7 @@ jobs:
     name: Add issue to project
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/[email protected].1
+      - uses: actions/[email protected].2
         with:
           project-url: https://github.com/users/Badgerati/projects/2
           github-token: ${{ secrets.PROJECT_TOKEN }}

.gitignore

@@ -265,3 +265,4 @@ examples/PetStore/data/PetData.json
 
 packers/choco/pode.nuspec
 packers/choco/tools/ChocolateyInstall.ps1
+docs/Getting-Started/Samples.md

.vscode/settings.json

@@ -21,6 +21,7 @@
     "powershell.codeFormatting.whitespaceBetweenParameters": false,
     "powershell.codeFormatting.whitespaceInsideBrace": true,
     "powershell.scriptAnalysis.settingsPath": "PSScriptAnalyzerSettings.psd1",
+    "powershell.scriptAnalysis.enable": true,
     "files.trimTrailingWhitespace": true,
     "files.associations": {
         "*.pode": "html"

PSScriptAnalyzerSettings.psd1

@@ -1,15 +1,33 @@
-# PSScriptAnalyzerSettings.psd1
 @{
-    Severity     = @('Error', 'Warning', 'Information')
+    Severity            = @('Error', 'Warning', 'Information')
+    IncludeDefaultRules = $true
 
-    Rules = @{
+    CustomRulePath      = @(
+        './analyzers/AvoidNewObjectRule.psm1'
+    )
+
+    Rules               = @{
         PSReviewUnusedParameter = @{
             CommandsToTraverse = @(
-                'Where-Object','Remove-PodeRoute'
+                'Where-Object',
+                'Remove-PodeRoute'
             )
         }
+        AvoidNewObjectRule      = @{
+            Severity = 'Warning'
+        }
     }
-    ExcludeRules = @('PSAvoidUsingCmdletAliases' ,'PSAvoidUsingPlainTextForPassword','PSAvoidUsingWriteHost','PSAvoidUsingInvokeExpression','PSUseShouldProcessForStateChangingFunctions',
-    'PSAvoidUsingUsernameAndPasswordParams','PSUseProcessBlockForPipelineCommand','PSAvoidUsingConvertToSecureStringWithPlainText','PSUseSingularNouns','PSReviewUnusedParameter' )
+
+    ExcludeRules        = @(
+        'PSAvoidUsingPlainTextForPassword',
+        'PSUseShouldProcessForStateChangingFunctions',
+        'PSAvoidUsingUsernameAndPasswordParams',
+        'PSUseProcessBlockForPipelineCommand',
+        'PSAvoidUsingConvertToSecureStringWithPlainText',
+        'PSReviewUnusedParameter',
+        'PSAvoidAssignmentToAutomaticVariable',
+        'PSUseBOMForUnicodeEncodedFile',
+        'PSAvoidTrailingWhitespace'
+    )
 
 }

README.md

@@ -26,9 +26,16 @@
 
 Pode is a Cross-Platform framework for creating web servers to host [REST APIs](https://badgerati.github.io/Pode/Tutorials/Routes/Overview/), [Web Pages](https://badgerati.github.io/Pode/Tutorials/Routes/Examples/WebPages/), and [SMTP/TCP](https://badgerati.github.io/Pode/Servers/) Servers. Pode also allows you to render dynamic files using [`.pode`](https://badgerati.github.io/Pode/Tutorials/Views/Pode/) files, which are just embedded PowerShell, or other [Third-Party](https://badgerati.github.io/Pode/Tutorials/Views/ThirdParty/) template engines. Plus many more features, including [Azure Functions](https://badgerati.github.io/Pode/Hosting/AzureFunctions/) and [AWS Lambda](https://badgerati.github.io/Pode/Hosting/AwsLambda/) support!
 
-<p align="center">
-    <img src="https://github.com/Badgerati/Pode/blob/develop/images/example_code_readme.svg?raw=true" width="70%" />
-</p>
+```powershell
+
+Start-PodeServer -ScriptBlock {
+    Add-PodeEndPoint -Address localhost -port 32005 -Protocol Http
+    Add-PodeRoute -Method Get -Path '/ping' -ScriptBlock {
+        Write-PodeJsonResponse -Value @{value = 'pong' }
+    }
+}
+
+```
 
 See [here](https://badgerati.github.io/Pode/Getting-Started/FirstApp) for building your first app! Don't know HTML, CSS, or JavaScript? No problem! [Pode.Web](https://github.com/Badgerati/Pode.Web) is currently a work in progress, and lets you build web pages using purely PowerShell!
 
@@ -49,8 +56,9 @@ Then navigate to `http://127.0.0.1:8000` in your browser.
 * Cross-platform using PowerShell Core (with support for PS5)
 * Docker support, including images for ARM/Raspberry Pi
 * Azure Functions, AWS Lambda, and IIS support
-* OpenAPI, Swagger, and ReDoc support
-* Listen on a single or multiple IP address/hostnames
+* OpenAPI specification version 3.0.x and 3.1.0
+* OpenAPI documentation with Swagger, Redoc, RapidDoc, StopLight, OpenAPI-Explorer and RapiPdf
+* Listen on a single or multiple IP(v4/v6) address/hostnames
 * Cross-platform support for HTTP(S), WS(S), SSE, SMTP(S), and TCP(S)
 * Host REST APIs, Web Pages, and Static Content (with caching)
 * Support for custom error pages
@@ -73,6 +81,8 @@ Then navigate to `http://127.0.0.1:8000` in your browser.
 * Support for File Watchers
 * In-memory caching, with optional support for external providers (such as Redis)
 * (Windows) Open the hosted server as a desktop application
+* FileBrowsing support
+* Localization (i18n) in Arabic, German, Spanish, France, Italian, Japanese, Korean, Polish, Portuguese, and Chinese
 
 ## 📦 Install
 

analyzers/AvoidNewObjectRule.psm1

@@ -0,0 +1,38 @@
+function Measure-AvoidNewObjectRule {
+    [CmdletBinding()]
+    [OutputType([Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.Language.ScriptBlockAst]
+        $ScriptBlockAst
+    )
+
+    # Initialize an empty array to collect diagnostic records
+    $diagnostics = @()
+
+    try {
+        # Traverse the AST to find all instances of New-Object cmdlet
+        $ScriptBlockAst.FindAll({
+                param($Ast)
+                $Ast -is [System.Management.Automation.Language.CommandAst] -and
+                $Ast.CommandElements[0].Extent.Text -eq 'New-Object'
+            }, $true) | ForEach-Object {
+            $diagnostics += [PSCustomObject]@{
+                Message    = "Avoid using 'New-Object' and use '::new()' instead."
+                Extent     = $_.Extent
+                RuleName   = 'AvoidNewObjectRule'
+                Severity   = 'Warning'
+                ScriptName = $FileName
+            }
+        }
+
+        # Return the diagnostic records
+        return $diagnostics
+    }
+    catch {
+        $PSCmdlet.ThrowTerminatingError($PSItem)
+    }
+}
+
+Export-ModuleMember -Function Measure-AvoidNewObjectRule

docs/Getting-Started/Debug.md

@@ -174,3 +174,75 @@ The steps to attach to the Pode process are as follows:
 5. You'll also be able to query variables as well, such as `$WebEvent` and other variables you might have created.
 
 6. When you are done debugging the current request, hit the `d` key.
+
+
+
+## Managing Runspace Names
+
+### Internal Runspace Naming
+
+In Pode, internal runspaces are automatically assigned distinct names. This built-in naming convention is crucial for identifying and managing runspaces efficiently, particularly during debugging or when monitoring multiple concurrent processes.
+
+Pode uses specific naming patterns for its internal runspaces, which include:
+
+- **Pode_Web_Listener_1**
+- **Pode_Signals_Broadcaster_1**
+- **Pode_Signals_Listener_1**
+- **Pode_Web_KeepAlive_1**
+- **Pode_Files_Watcher_1**
+- **Pode_Main_Logging_1**
+- **Pode_Timers_Scheduler_1**
+- **Pode_Schedules_[Schedule Name]_1** – where `[Schedule Name]` is the name of the schedule.
+- **Pode_Tasks_[Task Name]_1** – where `[Task Name]` is the name of the task.
+
+These default names are automatically assigned by Pode, making it easier to identify the purpose of each runspace during execution.
+
+### Customizing Runspace Names
+
+By default, Pode’s Tasks, Schedules, and Timers label their associated runspaces with their own names (as shown above). This simplifies the identification of runspaces when debugging or reviewing logs.
+
+However, if a different runspace name is needed, Pode allows you to customize it. Inside the script block of `Add-PodeTask`, `Add-PodeSchedule`, or `Add-PodeTimer`, you can use the `Set-PodeCurrentRunspaceName` cmdlet to assign any custom name you prefer.
+
+```powershell
+Set-PodeCurrentRunspaceName -Name 'Custom Runspace Name'
+```
+
+This cmdlet sets a custom name for the runspace, making it easier to track during execution.
+
+#### Example
+
+Here’s an example that demonstrates how to set a custom runspace name in a Pode task:
+
+```powershell
+Add-PodeTask -Name 'Test2' -ScriptBlock {
+    param($value)
+    # Set a custom name for the current runspace
+    Set-PodeCurrentRunspaceName -Name 'My Fancy Runspace'
+    Start-Sleep -Seconds 10
+    "A $($value) is never late, it arrives exactly when it means to" | Out-Default
+}
+```
+
+In this example, the `Set-PodeCurrentRunspaceName` cmdlet assigns the custom name `'My Fancy Runspace'` to the task's runspace. This is especially useful for debugging or when examining logs, as the custom name makes the runspace more recognizable.
+
+### Retrieving Runspace Names
+
+Pode also provides the `Get-PodeCurrentRunspaceName` cmdlet to retrieve the name of the current runspace. This is particularly helpful when you need to log or display the runspace name dynamically during execution.
+
+```powershell
+Get-PodeCurrentRunspaceName
+```
+
+This cmdlet returns the name of the current runspace, allowing for easier tracking and management in complex scenarios with multiple concurrent runspaces.
+
+#### Example
+
+Here’s an example that uses `Get-PodeCurrentRunspaceName` to output the runspace name during the execution of a schedule:
+
+```powershell
+Add-PodeSchedule -Name 'TestSchedule' -Cron '@hourly' -ScriptBlock {
+    Write-PodeHost "Runspace name: $(Get-PodeCurrentRunspaceName)"
+}
+```
+
+In this example, the schedule outputs the name of the runspace executing the script block every hour. This can be useful for logging and monitoring purposes when dealing with multiple schedules or tasks.

docs/Getting-Started/FirstApp.md

@@ -36,6 +36,16 @@ Success, saved package.json
 Import-Module -Name Pode -MaximumVersion 2.99.99
 ```
 
+* To ensure that any errors during the import process are caught and handled appropriately, use a try-catch block:
+
+```powershell
+try {
+    Import-Module -Name 'Pode' -MaximumVersion 2.99.99 -ErrorAction Stop
+} catch {
+    # exception management code
+}
+```
+
 * Within your `server.ps1` file, first you need to start the Server. This is where the main script will go that defines how the server should function:
 
 ```powershell