From 962938c086279a9791bb4fa59210890fa0ab4528 Mon Sep 17 00:00:00 2001 From: Chris Taylor Date: Tue, 10 Nov 2026 21:45:12 -0700 Subject: [PATCH 1/2] Fix package review findings before the 0.5.0 release - Connect-CWC accepts server and credentials by position again - Keep CWC.* ErrorIds on Windows PowerShell 5.1 when a read fails - Build adds the Gallery's command tags; the package check verifies them - Write the about_ConnectWiseControlAPI help topic (it was empty) - CHANGELOG: document the Get-CWCSession default group change and move repository entries to a Development section Co-Authored-By: Claude --- .build/gallery-tags.ps1 | 45 ++++++++ Build/Test-ReleasePackage.ps1 | 27 ++++- CHANGELOG.md | 81 +++++++------- ConnectWiseControlAPI_Functions.md | 2 +- Docs/Connect-CWC.md | 15 ++- Docs/Get-CWCLastContact.md | 4 +- Docs/Update-CWCSessionName.md | 2 +- README.md | 4 +- Tests/ConnectWiseControlAPI.Module.Tests.ps1 | 31 ++++++ Tests/ConnectWiseControlAPI.Public.Tests.ps1 | 50 +++++++++ build.yaml | 2 + source/Public/Authentication/Connect-CWC.ps1 | 11 +- .../Public/PageService/Get-CWCLastContact.ps1 | 3 +- .../Public/PageService/Invoke-CWCCommand.ps1 | 8 +- .../PageService/Remove-CWCSessionNote.ps1 | 3 +- source/en-US/ConnectWiseControlAPI-help.xml | 28 ++--- .../about_ConnectWiseControlAPI.help.txt | 100 ++++++++++++++++++ 17 files changed, 338 insertions(+), 78 deletions(-) create mode 100644 .build/gallery-tags.ps1 diff --git a/.build/gallery-tags.ps1 b/.build/gallery-tags.ps1 new file mode 100644 index 0000000..4ec752d --- /dev/null +++ b/.build/gallery-tags.ps1 @@ -0,0 +1,45 @@ +# Custom build task (loaded automatically by build.ps1 from the .build/ folder). +# +# The PowerShell Gallery lists a module's commands, and finds a module by command name +# (Find-Module -Command, Find-PSResource -CommandName), from package tags: PSIncludes_Function plus +# PSFunction_ and PSCommand_ for each exported function. PowerShellGet v2 (Publish-Module) added +# them while packing; Publish-PSResource does not. The release publishes with Publish-PSResource, so the +# build writes them into the built manifest. The source manifest keeps only the topic tags. + +# Synopsis: Adds the Gallery's command tags (PSFunction_*, PSCommand_*) to the built module manifest. +task Add_Gallery_Command_Tags { + $sourcePath = Join-Path -Path $BuildRoot -ChildPath 'source' + $sourceManifest = @(Get-ChildItem -Path $sourcePath -Filter '*.psd1' -File) + if ($sourceManifest.Count -ne 1) { + throw "Expected one module manifest in source/, found $($sourceManifest.Count)." + } + $moduleName = $sourceManifest[0].BaseName + + $builtRoot = Join-Path -Path $BuildRoot -ChildPath (Join-Path -Path 'output' -ChildPath $moduleName) + $builtManifest = @(Get-ChildItem -Path $builtRoot -Filter "$moduleName.psd1" -Recurse -File) + if ($builtManifest.Count -ne 1) { + throw "Expected one built manifest under $builtRoot, found $($builtManifest.Count)." + } + $manifestPath = $builtManifest[0].FullName + + $data = Import-PowerShellDataFile -Path $manifestPath + $functions = @($data.FunctionsToExport | Where-Object { $_ -and $_ -ne '*' } | Sort-Object) + if ($functions.Count -eq 0) { throw "The built manifest $manifestPath lists no functions to export." } + + $topicTags = @($data.PrivateData.PSData.Tags | Where-Object { $_ -notmatch '^PS(Includes|Function|Command)_' }) + $tags = @($topicTags) + 'PSIncludes_Function' + $tags += $functions | ForEach-Object { "PSFunction_$_" } + $tags += $functions | ForEach-Object { "PSCommand_$_" } + + # NuGet limits the tags field to 4000 characters; PSModule is added when the package is made + $length = ($tags -join ' ').Length + if ($length -gt 3900) { throw "The tag list is $length characters; the Gallery allows 4000." } + + Update-Metadata -Path $manifestPath -PropertyName 'PrivateData.PSData.Tags' -Value $tags + + $written = @((Import-PowerShellDataFile -Path $manifestPath).PrivateData.PSData.Tags) + if (Compare-Object -ReferenceObject $tags -DifferenceObject $written) { + throw "The tags in $manifestPath do not match the tags that were written." + } + Write-Build Green " $($functions.Count) functions tagged ($($tags.Count) tags, $length characters)" +} diff --git a/Build/Test-ReleasePackage.ps1 b/Build/Test-ReleasePackage.ps1 index e2b391a..ee407e7 100644 --- a/Build/Test-ReleasePackage.ps1 +++ b/Build/Test-ReleasePackage.ps1 @@ -5,10 +5,11 @@ .DESCRIPTION Used by .github/workflows/release.yml after the build and the tests, and safe to run locally. It: 1. packs the built module (output///) into a .nupkg in a temporary folder repository - 2. pushes that .nupkg to a second temporary repository with Publish-PSResource -NupkgPath, the same call + 2. checks the package's version and that it has the tags the Gallery lists and finds commands by + 3. pushes that .nupkg to a second temporary repository with Publish-PSResource -NupkgPath, the same call the workflow uses for the real publish - 3. saves the package from the second repository, as Install-Module would - 4. imports the saved copy in PowerShell 7 and in Windows PowerShell 5.1 and checks the version, the number + 4. saves the package from the second repository, as Install-Module would + 5. imports the saved copy in PowerShell 7 and in Windows PowerShell 5.1 and checks the version, the number of exported functions and that the import shows no warnings With -PackagePath the checked .nupkg is copied there, so the workflow can publish that exact file. @@ -74,6 +75,26 @@ try { if ($Package.Name -ne "$ModuleName.$Version.nupkg") { throw "Unexpected package name '$($Package.Name)'." } $PackageHash = (Get-FileHash -Path $Package.FullName -Algorithm SHA256).Hash + # The Gallery lists and finds commands by these package tags (the build adds them to the manifest) + Add-Type -AssemblyName System.IO.Compression.FileSystem + $Zip = [IO.Compression.ZipFile]::OpenRead($Package.FullName) + try { + $Entry = $Zip.Entries | Where-Object { $_.FullName -eq "$ModuleName.nuspec" } + if (-not $Entry) { throw "The package has no $ModuleName.nuspec." } + $Reader = New-Object System.IO.StreamReader($Entry.Open()) + try { $Nuspec = [xml]$Reader.ReadToEnd() } finally { $Reader.Dispose() } + } finally { + $Zip.Dispose() + } + $PackageTags = @("$($Nuspec.package.metadata.tags)" -split '\s+') + $ExpectedTags = @('PSModule', 'PSIncludes_Function') + + @($Manifest.FunctionsToExport | ForEach-Object { "PSFunction_$_"; "PSCommand_$_" }) + $MissingTags = @($ExpectedTags | Where-Object { $PackageTags -notcontains $_ }) + if ($MissingTags) { throw "The package is missing Gallery tags: $($MissingTags -join ', ')" } + if ("$($Nuspec.package.metadata.version)" -ne $Version) { + throw "The package version '$($Nuspec.package.metadata.version)' is not '$Version'." + } + Publish-PSResource -NupkgPath $Package.FullName -Repository $PushRepository Save-PSResource -Name $ModuleName -Version $Version -Repository $PushRepository -Path $Saved -TrustRepository $SavedManifest = Join-Path $Saved "$ModuleName/$Version/$ModuleName.psd1" diff --git a/CHANGELOG.md b/CHANGELOG.md index 1035adf..a8662ed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [0.5.0] - 2026-11-10 -Versions now have three parts (`0.5.0`); the build needs that. The previous release was 0.4.0.0. +Version numbers now have three parts (`0.5.0`). The previous release was 0.4.0.0, which had 21 commands; this +release has 32. ### Breaking changes @@ -19,6 +20,8 @@ Versions now have three parts (`0.5.0`); the build needs that. The previous rele old connection - `Get-CWCLastContact` returns an error when no connection event is found, instead of the current time - `Get-CWCAuditLog` `-StartDate`/`-EndDate` default to the last 24 hours +- `Get-CWCSession -Type Support` and `-Type Meeting` without `-Group` read the `All Sessions` and `All Meetings` + groups. Before, they read `All Machines`, which holds Access sessions - HTTP 500 errors are retried only for calls that are safe to repeat Details are in the sections below. @@ -34,11 +37,6 @@ Details are in the sections below. ### Added -- GitHub community files: CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue templates, PR template -- `.editorconfig` for consistent editor formatting -- `.gitattributes` for line ending normalization and diff drivers -- `.PSScriptAnalyzerSettings.psd1` with 60+ rules targeting PS 5.1+ compatibility -- `CHANGELOG.md` (this file) - `Connect-CWC -ApiSecret`: second authentication method using the RESTful API Manager extension's `RESTfulAuthenticationSecret` (sent as `CTRLAuthHeader`). Works with MFA-enforced servers. `Get-CWCSessionDetail`, `Update-CWCSessionName`, `New-CWCSession`, `Add-CWCSessionNote`, @@ -54,18 +52,11 @@ Details are in the sections below. logged out. Errors carry ErrorIds `CWC.MfaRequired`, `CWC.MfaCodeRejected`, `CWC.LoginFailed`, `CWC.LoginThrottled`. Logins are never retried. Requests that fail on an MFA connection with a permission or anti-forgery error say the login may have expired -- Failed requests no longer keep the login cookie on the request object stored in `$Error` -- `Connect-CWC` reuses a cached connection only for the same server, auth method and identity (user or - secret); anything else reconnects, even without `-Force`. Before, the old connection was silently kept - and later commands went to the previous server or ran as the previous user. If connecting to a - different server, method or identity fails, the module is left disconnected; a failed `-Force` refresh - of the same connection keeps it +- `Get-Help about_ConnectWiseControlAPI`: an overview of the three ways to sign in, the ErrorIds and what to + check when upgrading from 0.4 - `Find-CWCSession` (`-Filter`/`-Name`/`-GUID`; API secret only), `New-CWCSession`, `Add-CWCSessionNote`, `Send-CWCSessionMessage`, `Send-CWCToolboxItem`. On credentials connections the last three queue session events (AddedNote 32, QueuedMessage 45, QueuedTool 47) and take `-Group` -- Live smoke test script `Tests/Live/Invoke-CWCLiveSmokeTest.ps1` (read-only by default; `-AllowWrites` - acts on one chosen test session and cleans up its notes; `-MfaUserName` tests the MFA login; `-TotpTestRole` tests the TOTP login with a temporary user it - creates and deletes; `-MfaNegativeProbes` records the raw failed-login codes) - `Get-CWCRemoteWorkforceLaunchURL` (by `-GUID`, pipeline, or `-SessionName`), replacing `Get-CWCLauncURL` - `Get-CWCRemoteWorkforceSession` lists the calling user's assigned machines (`GetRemoteWorkforceSessions`) - `Initialize-CWCRemoteWorkforceSessionGroup` creates/repairs the extension's session group @@ -82,8 +73,6 @@ Details are in the sections below. (`InitiatedJoin`). `-UrlOnly` returns the URL instead (for macOS/Linux or custom launchers), using a 5-minute delegated token when the role allows it. The token is never written to any output stream. Credentials connections only; launching is Windows only -- Live discovery script `Tests/Live/Invoke-CWCHostLaunchDiscovery.ps1` (read-only; redacts secrets; - `-Launch` opens the client for one test session) ### Deprecated @@ -91,22 +80,11 @@ Details are in the sections below. ### Changed -- CI moved from AppVeyor to GitHub Actions (`.github/workflows/ci.yml`): Pester on PowerShell 7 and Windows - PowerShell 5.1, PSScriptAnalyzer, `Test-ModuleManifest` and a docs-drift check. `Tests/test-local.ps1` runs the - same stages locally. `Tests/appveyor.pester.ps1` removed. -- Releases are published by a workflow (`.github/workflows/release.yml`): pushing a tag `v` checks the - tag against the manifest and this changelog, builds, runs every test stage, checks the package installs on - both editions, publishes to the PowerShell Gallery after the owner approves, and creates the GitHub Release. - A manual run is a dry run that publishes nothing. -- Repository layout follows the GitHub-Template (Sampler): the module source moved from `ConnectWiseControlAPI/` to - `source/` (`Extensions/Remote Workforce` is now `Extensions/RemoteWorkforce`) and `./build.ps1` builds the - published module into `output///`. Module-level setup moved from the `.psm1` to - `source/prefix.ps1`. The published module is unchanged: same 32 functions, PowerShell 3.0+, same help. CI and - `Tests/test-local.ps1` test the built module on PowerShell 7 and Windows PowerShell 5.1. -- Repo files aligned with the GitHub-Template: `AGENTS.md` (agent guide; `CLAUDE.md` now points to it), - `pr-validation.yml`, `dependabot.yml`, `copilot-instructions.md`, `.vscode/` settings, `.github/PowerShell-StyleGuide.md` -- Expanded `.gitignore` to cover OS files, IDEs, build artifacts, and secrets -- Updated `README.md` links to use local community files instead of external GitHub-Template references +- `Connect-CWC` reuses a cached connection only for the same server, auth method and identity (user or + secret); anything else reconnects, even without `-Force`. Before, the old connection was silently kept + and later commands went to the previous server or ran as the previous user. If connecting to a + different server, method or identity fails, the module is left disconnected; a failed `-Force` refresh + of the same connection keeps it - `Connect-CWC` validates credentials with `PageService/GetEligibleHosts` (any permission) instead of `Get-CWCSessionGroup` (requires ManageSessionGroups), so non-admin accounts can connect - `Get-CWCAuditLog` `-StartDate`/`-EndDate` default to the last 24 hours; `-IncludeSessionCaptures` is @@ -123,7 +101,8 @@ Details are in the sections below. - `Connect-CWC` reports a failed login with its likely causes. Wrong credentials are not rejected with a 401: the request runs as an anonymous user and fails with "Needs permission". A local failure (e.g. a PowerShell error) is reported as such instead of being blamed on the credentials -- Removed the unloaded `WIP/Invoke-CWCSession.ps1` prototype, superseded by `Enter-CWCSession` +- `Get-CWCSessionGroup` calls the documented `GetSessionGroups` (POST) method instead of the undocumented + `session-groups` GET route. Both return the same data on ScreenConnect 26.7.6 - `Get-CWCLastContact` returns an error when no connection event is found, instead of the current time - `-Group` accepts the path parts of a nested session group (e.g. `'Clients','Acme'`) on every session function that takes it; a single group name works as before @@ -133,18 +112,19 @@ Details are in the sections below. - `Invoke-CWCCommand` waits 1, 2, 3 … up to 5 seconds between polls of the rate-limited session details - `Enter-CWCSession` takes `-Name` from the pipeline (e.g. from `Get-CWCSession`) and then skips its session lookup -- `Build/Update-Help.ps1` regenerates `Docs/` and the MAML help in one step ### Fixed +- `Get-CWCSession -Type Support` and `-Type Meeting` without `-Group` read `All Machines`, the Access group; + they now read `All Sessions` and `All Meetings` +- Failed requests no longer keep the login cookie on the request object stored in `$Error` + Endpoint calls audited against the ScreenConnect server's `Services/*.ashx` source: - `Invoke-CWCWake` called `PageService.AddEventToSessions`, which no longer exists; it now queues wake events (type 43) through `AddSessionEvents` - `Get-CWCAuditLog` sent 6 arguments to `QueryAuditLog`, which takes 5 (the capture flag landed in the event-type slot); local times were also sent with a `Z` suffix and are now converted to UTC -- `Get-CWCSessionGroup` now calls the documented `GetSessionGroups` (POST) method instead of the - undocumented `session-groups` GET route (both return the same data on ScreenConnect 26.7.6; not a bug fix) - `Add-CWCRemoteWorkforceRequiredRole` now calls the extension's own `EnsureRemoteWorkforceSecurityRoleExists` instead of building the role with `CreateRole`: it is idempotent, honors the extension's `RoleName`/`SessionGroupName` settings, and sets `IsRoleCreated` @@ -171,7 +151,32 @@ Extension calls audited against the Remote Workforce 1.3.16 `App_Extensions/2c4f - `Get-CWCLauncURL` sent 6 arguments to `GetLaunchUrlForSessionId`, which takes 1 (the session ID), including a plaintext password the server never used -- The `Launcher` extension folder was the Remote Workforce extension; functions moved under `Remote Workforce/` + +### Development + +Changes to the repository. They do not change the published module. + +- CI moved from AppVeyor to GitHub Actions (`.github/workflows/ci.yml`): Pester on PowerShell 7 and Windows + PowerShell 5.1, PSScriptAnalyzer, `Test-ModuleManifest` and a docs-drift check. `Tests/test-local.ps1` runs the + same stages locally. `Tests/appveyor.pester.ps1` removed +- Releases are published by a workflow (`.github/workflows/release.yml`): pushing a tag `v` checks the + tag against the manifest and this changelog, builds, runs every test stage, checks the package installs on + both editions, publishes to the PowerShell Gallery after the owner approves, and creates the GitHub Release. + A manual run is a dry run that publishes nothing +- Repository layout follows the GitHub-Template (Sampler): the module source moved from `ConnectWiseControlAPI/` to + `source/` (`Extensions/Remote Workforce` is now `Extensions/RemoteWorkforce`; the `Launcher` extension folder + was the Remote Workforce extension) and `./build.ps1` builds the published module into + `output///`. Module-level setup moved from the `.psm1` to `source/prefix.ps1`. The build + adds the tags the Gallery lists and finds commands by. CI and `Tests/test-local.ps1` test the built module +- `Build/Update-Help.ps1` regenerates `Docs/` and the MAML help in one step +- Repo files aligned with the GitHub-Template: `AGENTS.md` (agent guide; `CLAUDE.md` points to it), community + files (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue and PR templates), `pr-validation.yml`, `dependabot.yml`, + `copilot-instructions.md`, `.vscode/` settings, `.editorconfig`, `.gitattributes`, an expanded `.gitignore`, + `.PSScriptAnalyzerSettings.psd1` and `.github/PowerShell-StyleGuide.md` +- Live test scripts: `Tests/Live/Invoke-CWCLiveSmokeTest.ps1` (read-only by default; `-AllowWrites` acts on one + chosen test session and cleans up its notes; `-MfaUserName` and `-TotpTestRole` test the MFA and TOTP logins) + and `Tests/Live/Invoke-CWCHostLaunchDiscovery.ps1` (read-only; redacts secrets) +- Removed the unloaded `WIP/Invoke-CWCSession.ps1` prototype, superseded by `Enter-CWCSession` ## [0.4.0.0] diff --git a/ConnectWiseControlAPI_Functions.md b/ConnectWiseControlAPI_Functions.md index deba413..d3581d5 100644 --- a/ConnectWiseControlAPI_Functions.md +++ b/ConnectWiseControlAPI_Functions.md @@ -33,7 +33,7 @@ Shows current audit settings Pull audit log information ### [Get-CWCLastContact](Docs/Get-CWCLastContact.md) -Returns the date the machine last connected to the control server. +Returns the date the machine last connected to the ScreenConnect server. ### [Get-CWCLauncURL](Docs/Get-CWCLauncURL.md) DEPRECATED. diff --git a/Docs/Connect-CWC.md b/Docs/Connect-CWC.md index 98b3e5a..7210dd7 100644 --- a/Docs/Connect-CWC.md +++ b/Docs/Connect-CWC.md @@ -14,29 +14,28 @@ Connects to a ConnectWise ScreenConnect server. ### Credentials (Default) ``` -Connect-CWC -Server -Credentials [-Force] +Connect-CWC [-Server] [-Credentials] [-Force] [] ``` ### TotpSecret ``` -Connect-CWC -Server -Credentials -TotpSecret [-Force] [] +Connect-CWC [-Server] [-Credentials] -TotpSecret [-Force] [] ``` ### OneTimeCode ``` -Connect-CWC -Server -Credentials -OneTimeCode [-Force] [] +Connect-CWC [-Server] [-Credentials] -OneTimeCode [-Force] [] ``` ### Mfa ``` -Connect-CWC -Server -Credentials [-Mfa] [-Force] - [] +Connect-CWC [-Server] [-Credentials] [-Mfa] [-Force] [] ``` ### ApiSecret ``` -Connect-CWC -Server -ApiSecret [-Origin ] [-Force] [] +Connect-CWC [-Server] -ApiSecret [-Origin ] [-Force] [] ``` ## DESCRIPTION @@ -113,7 +112,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: Named +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -128,7 +127,7 @@ Parameter Sets: Credentials, TotpSecret, OneTimeCode, Mfa Aliases: Required: True -Position: Named +Position: 2 Default value: None Accept pipeline input: False Accept wildcard characters: False diff --git a/Docs/Get-CWCLastContact.md b/Docs/Get-CWCLastContact.md index 741c1e3..cd2b054 100644 --- a/Docs/Get-CWCLastContact.md +++ b/Docs/Get-CWCLastContact.md @@ -8,7 +8,7 @@ schema: 2.0.0 # Get-CWCLastContact ## SYNOPSIS -Returns the date the machine last connected to the control server. +Returns the date the machine last connected to the ScreenConnect server. ## SYNTAX @@ -17,7 +17,7 @@ Get-CWCLastContact -GUID [-Quiet] [-Seconds ] [-Group ] ``` ## DESCRIPTION -Returns the date the machine last connected to the control server. +Returns the date the machine last connected to the ScreenConnect server. ## EXAMPLES diff --git a/Docs/Update-CWCSessionName.md b/Docs/Update-CWCSessionName.md index 8493453..baea85e 100644 --- a/Docs/Update-CWCSessionName.md +++ b/Docs/Update-CWCSessionName.md @@ -17,7 +17,7 @@ Update-CWCSessionName [-GUID] [-NewName] [[-Group] ] [ ``` ## DESCRIPTION -Updates the name of a session on the control server. +Updates the name of a session on the ScreenConnect server. ## EXAMPLES diff --git a/README.md b/README.md index f2dcb79..ba0aca6 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ A PowerShell wrapper for the ConnectWise ScreenConnect (formerly ConnectWise Con This module makes it easy to leverage PowerShell to automate tasks in ScreenConnect. ConnectWise renamed Control back to ScreenConnect. The module keeps its name and its `CWC` command names, so -existing scripts keep working. +scripts don't need renaming. Version 0.5.0 does change some behaviour: see [Upgrading from 0.4](#upgrading-from-04). @@ -58,6 +58,8 @@ Install-Module 'ConnectWiseControlAPI' old connection. * `Get-CWCLastContact` returns an error when it finds no connection event. Before, it returned the current time. * `Get-CWCAuditLog` covers the last 24 hours unless you pass `-StartDate` and `-EndDate`. +* `Get-CWCSession -Type Support` and `-Type Meeting` without `-Group` read the `All Sessions` and `All Meetings` + groups. Before, they read `All Machines`, which holds Access sessions. * A request that fails with HTTP 500 is repeated only when repeating is safe (reads and "set to value" updates). The full list is in the [changelog](CHANGELOG.md). diff --git a/Tests/ConnectWiseControlAPI.Module.Tests.ps1 b/Tests/ConnectWiseControlAPI.Module.Tests.ps1 index 23b80b5..bfe21e2 100644 --- a/Tests/ConnectWiseControlAPI.Module.Tests.ps1 +++ b/Tests/ConnectWiseControlAPI.Module.Tests.ps1 @@ -74,6 +74,37 @@ Describe 'Module: ConnectWiseControlAPI' { @($Listed | Group-Object | Where-Object Count -gt 1 | ForEach-Object Name) | Should -BeNullOrEmpty @($Listed | Sort-Object) | Should -Be $Expected } + + It 'ships an about topic that has content' { + # An empty about_ file shows a blank topic in Get-Help; it shipped that way until 0.5.0 was reviewed + $About = Join-Path (Split-Path -Parent $ManifestPath) 'en-US/about_ConnectWiseControlAPI.help.txt' + $About | Should -Exist + $Text = Get-Content -Path $About -Raw + $Text | Should -Match '(?m)^TOPIC\s+about_ConnectWiseControlAPI' + $Text | Should -Match 'SHORT DESCRIPTION' + (Get-Content -Path $About | Where-Object { $_.Length -gt 80 }) | Should -BeNullOrEmpty + } + + It 'built manifest has the tags the Gallery uses to list and find commands' -ForEach @( + @{ Expected = $ExpectedFunctions } + ) { + $Data = Import-PowerShellDataFile -Path $ManifestPath + $Listed = @($Data.FunctionsToExport) + if ($Listed.Count -eq 1 -and $Listed[0] -eq '*') { + Set-ItResult -Skipped -Because 'the build adds these tags; the source manifest has only the topic tags' + return + } + # PowerShellGet v2 (0.4.0.0) added these when packing; Publish-PSResource does not, so the build does. + $Tags = @($Data.PrivateData.PSData.Tags) + $Tags | Should -Contain 'PSIncludes_Function' + foreach ($Function in $Expected) { + $Tags | Should -Contain "PSFunction_$Function" + $Tags | Should -Contain "PSCommand_$Function" + } + @($Tags | Group-Object | Where-Object Count -GT 1) | Should -BeNullOrEmpty + # NuGet limits the tags field to 4000 characters + ($Tags -join ' ').Length | Should -BeLessThan 3900 + } } Context 'Module Import' { diff --git a/Tests/ConnectWiseControlAPI.Public.Tests.ps1 b/Tests/ConnectWiseControlAPI.Public.Tests.ps1 index e06aaf2..3822805 100644 --- a/Tests/ConnectWiseControlAPI.Public.Tests.ps1 +++ b/Tests/ConnectWiseControlAPI.Public.Tests.ps1 @@ -66,6 +66,30 @@ Describe 'Connect-CWC' { } } + Context 'Positional parameters (0.4.0.0 compatibility)' { + It 'accepts server and credentials by position' { + InModuleScope 'ConnectWiseControlAPI' -Parameters @{ cred = $cred } { + param($cred) + Connect-CWC 'server.example.com' $cred + $script:CWCServerConnection.Server | Should -Be 'server.example.com' + $script:CWCServerConnection.AuthType | Should -Be 'Credentials' + } + } + + It 'has Server at position 0 and Credentials at position 1 in every credential parameter set' { + $Sets = (Get-Command Connect-CWC).ParameterSets + foreach ($Set in $Sets) { + ($Set.Parameters | Where-Object Name -EQ 'Server').Position | Should -Be 0 -Because $Set.Name + } + foreach ($Set in ($Sets | Where-Object Name -NE 'ApiSecret')) { + ($Set.Parameters | Where-Object Name -EQ 'Credentials').Position | Should -Be 1 -Because $Set.Name + } + # The secret is never positional + ($Sets.Parameters | Where-Object { $_.Name -in 'ApiSecret', 'TotpSecret', 'OneTimeCode' }).Position | + ForEach-Object { $_ | Should -BeLessThan 0 } + } + } + Context 'Validation call' { It 'validates with GetEligibleHosts (works for non-admin accounts)' { InModuleScope 'ConnectWiseControlAPI' -Parameters @{ cred = $cred } { @@ -275,6 +299,32 @@ Describe 'Connect-CWC' { # ============================================================================= # PageService # ============================================================================= +Describe 'ErrorId survives a failed read' { + # These functions re-report an error they caught. Write-Error $_ replaces the ErrorId on Windows PowerShell 5.1 + # (it becomes WriteErrorException), so they must use $PSCmdlet.WriteError($_). + BeforeEach { + InModuleScope 'ConnectWiseControlAPI' { $script:CWCServerConnection = $null } + $SessionID = [guid]::NewGuid() + } + + It ' reports CWC.NotConnected when not connected' -ForEach @( + @{ Name = 'Get-CWCLastContact'; Call = { param($ID) Get-CWCLastContact -GUID $ID -ErrorAction Stop } } + @{ Name = 'Invoke-CWCCommand'; Call = { + param($ID) Invoke-CWCCommand -GUID $ID -Command 'hostname' -ErrorAction Stop + } + } + @{ Name = 'Remove-CWCSessionNote'; Call = { + param($ID) Remove-CWCSessionNote -GUID $ID -All -Confirm:$false -ErrorAction Stop + } + } + ) { + $Caught = $null + try { & $Call $SessionID } catch { $Caught = $_ } + $Caught | Should -Not -BeNullOrEmpty + $Caught.FullyQualifiedErrorId | Should -BeLike 'CWC.NotConnected,*' + } +} + Describe 'Connect-CWC -ApiSecret' { BeforeEach { diff --git a/build.yaml b/build.yaml index 24701e6..085d626 100644 --- a/build.yaml +++ b/build.yaml @@ -27,6 +27,8 @@ BuildWorkflow: - Clean - Assert_RequiredModule_Versions - Build_ModuleOutput_ModuleBuilder + # .build/gallery-tags.ps1: the tags the Gallery lists and finds commands by + - Add_Gallery_Command_Tags #################################################### # Sampler Pipeline Configuration # diff --git a/source/Public/Authentication/Connect-CWC.ps1 b/source/Public/Authentication/Connect-CWC.ps1 index 16f9cdb..e32007c 100644 --- a/source/Public/Authentication/Connect-CWC.ps1 +++ b/source/Public/Authentication/Connect-CWC.ps1 @@ -110,14 +110,15 @@ function Connect-CWC { #> [CmdletBinding(DefaultParameterSetName = 'Credentials')] param( - [Parameter(Mandatory = $True)] + # Positions 0 and 1 keep 0.4-style calls working: Connect-CWC 'server' $Credentials + [Parameter(Mandatory = $True, Position = 0)] [ValidateNotNullOrEmpty()] [string]$Server, - [Parameter(Mandatory = $True, ParameterSetName = 'Credentials')] - [Parameter(Mandatory = $True, ParameterSetName = 'Mfa')] - [Parameter(Mandatory = $True, ParameterSetName = 'OneTimeCode')] - [Parameter(Mandatory = $True, ParameterSetName = 'TotpSecret')] + [Parameter(Mandatory = $True, Position = 1, ParameterSetName = 'Credentials')] + [Parameter(Mandatory = $True, Position = 1, ParameterSetName = 'Mfa')] + [Parameter(Mandatory = $True, Position = 1, ParameterSetName = 'OneTimeCode')] + [Parameter(Mandatory = $True, Position = 1, ParameterSetName = 'TotpSecret')] [pscredential]$Credentials, [Parameter(Mandatory = $True, ParameterSetName = 'Mfa')] diff --git a/source/Public/PageService/Get-CWCLastContact.ps1 b/source/Public/PageService/Get-CWCLastContact.ps1 index 6db3be4..fbf61bc 100644 --- a/source/Public/PageService/Get-CWCLastContact.ps1 +++ b/source/Public/PageService/Get-CWCLastContact.ps1 @@ -50,7 +50,8 @@ function Get-CWCLastContact { try { $SessionDetails = Get-CWCSessionDetail -Group $Group -GUID $GUID -Include 'Events' -ErrorAction Stop } catch { - Write-Error $_ + # WriteError keeps the ErrorId (CWC.*) on Windows PowerShell 5.1; Write-Error $_ replaces it there + $PSCmdlet.WriteError($_) return } diff --git a/source/Public/PageService/Invoke-CWCCommand.ps1 b/source/Public/PageService/Invoke-CWCCommand.ps1 index f191291..5118ace 100644 --- a/source/Public/PageService/Invoke-CWCCommand.ps1 +++ b/source/Public/PageService/Invoke-CWCCommand.ps1 @@ -77,8 +77,10 @@ function Invoke-CWCCommand { } } catch { - # Not queued: don't report success or poll for output that will never come - return Write-Error $_ + # Not queued: don't report success or poll for output that will never come. + # WriteError keeps the ErrorId (CWC.*) on Windows PowerShell 5.1; Write-Error $_ replaces it there. + $PSCmdlet.WriteError($_) + return } if ($NoWait) { return } @@ -100,7 +102,7 @@ function Invoke-CWCCommand { # Events only, with a growing delay (1, 2, 3 ... 5 s): GetSessionDetails is rate limited. try { $SessionDetails = Get-CWCSessionDetail -Group $Group -GUID $GUID -Include 'Events' -ErrorAction Stop } catch { - Write-Error $_ + $PSCmdlet.WriteError($_) return } diff --git a/source/Public/PageService/Remove-CWCSessionNote.ps1 b/source/Public/PageService/Remove-CWCSessionNote.ps1 index 6ad9bfc..1f623a2 100644 --- a/source/Public/PageService/Remove-CWCSessionNote.ps1 +++ b/source/Public/PageService/Remove-CWCSessionNote.ps1 @@ -72,7 +72,8 @@ function Remove-CWCSessionNote { if ($All) { try { $Events = @((Get-CWCSessionDetail -Group $Group -GUID $GUID -Include 'Events' -ErrorAction Stop).Events) } catch { - Write-Error $_ + # WriteError keeps the ErrorId (CWC.*) on Windows PowerShell 5.1; Write-Error $_ replaces it there + $PSCmdlet.WriteError($_) return } # A deleted note stays in the event list; its DeletedEvent points back at it diff --git a/source/en-US/ConnectWiseControlAPI-help.xml b/source/en-US/ConnectWiseControlAPI-help.xml index c83234f..1e29b22 100644 --- a/source/en-US/ConnectWiseControlAPI-help.xml +++ b/source/en-US/ConnectWiseControlAPI-help.xml @@ -264,7 +264,7 @@ Connect-CWC - + Server ScreenConnect server hostname, e.g. screenconnect.example.com. A leading http(s):// is removed. HTTPS is always used. @@ -276,7 +276,7 @@ None - + Credentials Username and password of a ScreenConnect user account. @@ -302,7 +302,7 @@ Connect-CWC - + Server ScreenConnect server hostname, e.g. screenconnect.example.com. A leading http(s):// is removed. HTTPS is always used. @@ -314,7 +314,7 @@ None - + Credentials Username and password of a ScreenConnect user account. @@ -353,7 +353,7 @@ Connect-CWC - + Server ScreenConnect server hostname, e.g. screenconnect.example.com. A leading http(s):// is removed. HTTPS is always used. @@ -365,7 +365,7 @@ None - + Credentials Username and password of a ScreenConnect user account. @@ -403,7 +403,7 @@ Connect-CWC - + Server ScreenConnect server hostname, e.g. screenconnect.example.com. A leading http(s):// is removed. HTTPS is always used. @@ -415,7 +415,7 @@ None - + Credentials Username and password of a ScreenConnect user account. @@ -452,7 +452,7 @@ Connect-CWC - + Server ScreenConnect server hostname, e.g. screenconnect.example.com. A leading http(s):// is removed. HTTPS is always used. @@ -502,7 +502,7 @@ - + Server ScreenConnect server hostname, e.g. screenconnect.example.com. A leading http(s):// is removed. HTTPS is always used. @@ -514,7 +514,7 @@ None - + Credentials Username and password of a ScreenConnect user account. @@ -1229,11 +1229,11 @@ open $Url # macOS Get CWCLastContact - Returns the date the machine last connected to the control server. + Returns the date the machine last connected to the ScreenConnect server. - Returns the date the machine last connected to the control server. + Returns the date the machine last connected to the ScreenConnect server. @@ -4626,7 +4626,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { - Updates the name of a session on the control server. + Updates the name of a session on the ScreenConnect server. diff --git a/source/en-US/about_ConnectWiseControlAPI.help.txt b/source/en-US/about_ConnectWiseControlAPI.help.txt index e69de29..8f1d302 100644 --- a/source/en-US/about_ConnectWiseControlAPI.help.txt +++ b/source/en-US/about_ConnectWiseControlAPI.help.txt @@ -0,0 +1,100 @@ +TOPIC + about_ConnectWiseControlAPI + +SHORT DESCRIPTION + PowerShell commands for the ConnectWise ScreenConnect (formerly ConnectWise + Control) web API. + +LONG DESCRIPTION + The module wraps the ScreenConnect web API: sessions, session groups, + commands, notes, messages, users, the audit log and the Remote Workforce + extension. It runs on Windows PowerShell 5.1 and PowerShell 7. The server + must use https. + + ConnectWise renamed Control back to ScreenConnect. The module keeps the + name ConnectWiseControlAPI and the CWC prefix on its commands. + + List the commands: + + Get-Command -Module ConnectWiseControlAPI + +SIGNING IN + Run Connect-CWC once per PowerShell session. Every other command uses that + connection. There are three ways to sign in. + + A user account without MFA: + + Connect-CWC -Server sc.example.com -Credentials $Cred + + A user account with MFA. -Mfa asks for the one-time code, -OneTimeCode + takes it as a parameter, and -TotpSecret computes the authenticator-app + code for unattended scripts. The password and the secret are not kept: + + Connect-CWC -Server sc.example.com -Credentials $Cred -Mfa + Connect-CWC -Server sc.example.com -Credentials $Cred -TotpSecret $Key + + An MFA login expires. Run Connect-CWC again when a command reports that + the login may have expired. + + The secret of the RESTful API Manager extension. It works on servers where + every account requires MFA, for these commands only: Find-CWCSession, + Get-CWCSessionDetail, Update-CWCSessionName, New-CWCSession, + Add-CWCSessionNote, Send-CWCSessionMessage, Send-CWCToolboxItem and + Invoke-CWCCommand (which queues the command and does not return output): + + Connect-CWC -Server sc.example.com -ApiSecret $Secret + + A command that needs the other kind of connection returns an error that + names it. + +ERRORS + Most commands report failures as non-terminating errors. Add + -ErrorAction Stop to catch them. Errors from API calls carry an ErrorId at + the start of + $_.FullyQualifiedErrorId: + + CWC.NotConnected Connect-CWC has not been run + CWC.AuthModeMismatch The command needs the other kind of connection + CWC.Http The server answered with that HTTP status + CWC.NoResponse The server did not answer + CWC.MfaRequired The account needs a one-time code + CWC.MfaCodeRejected The one-time code was wrong or has expired + CWC.LoginFailed The sign-in was rejected + CWC.LoginThrottled Too many sign-in attempts; wait before retrying + + Example: + + try { + Get-CWCSession -Type Access -ErrorAction Stop + } catch { + if ($_.FullyQualifiedErrorId -like 'CWC.NotConnected*') { + Write-Warning 'Run Connect-CWC first.' + } + } + +REMOVING THINGS + Remove-CWCSession, Remove-CWCSessionNote and Remove-CWCHostFromSession ask + for confirmation. In an unattended script add -Confirm:$false; without it + the command fails and removes nothing. + +UPGRADING FROM 0.4 + Check these before updating scripts written for 0.4.0.0: + + - The Remove-* commands above ask for confirmation by default. + - Connect-CWC without -Force switches to a different server, sign-in method + or user. Before, it kept the old connection. + - Get-CWCLastContact returns an error when it finds no connection event. + Before, it returned the current time. + - Get-CWCAuditLog covers the last 24 hours unless -StartDate and -EndDate + are given. + - Get-CWCSession -Type Support and -Type Meeting without -Group read the + 'All Sessions' and 'All Meetings' groups. Before, they read + 'All Machines'. + - A request that fails with HTTP 500 is repeated only when repeating is + safe. + +SEE ALSO + Connect-CWC + Get-CWCSession + https://github.com/christaylorcodes/ConnectWiseControlAPI + CHANGELOG.md in that repository has the full list of changes. From 8a5aaefa57ac44e2d7b29e560ea3477d9c953260 Mon Sep 17 00:00:00 2001 From: Chris Taylor Date: Tue, 10 Nov 2026 22:04:34 -0700 Subject: [PATCH 2/2] Address review of the package fixes - ErrorId tests keep the error non-terminating, so they fail against Write-Error $_ on Windows PowerShell 5.1 (the first version did not) - about topic, CHANGELOG, README: say what Remove-* does without -Confirm:$false in each kind of host; MFA-only ErrorIds are marked; the HTTP 500 note no longer claims 0.4 retried - CHANGELOG: restore two entries dropped in the restructure Co-Authored-By: Claude --- CHANGELOG.md | 22 +++++++------ README.md | 6 ++-- Tests/ConnectWiseControlAPI.Public.Tests.ps1 | 32 ++++++++++++++----- .../about_ConnectWiseControlAPI.help.txt | 22 +++++++++---- 4 files changed, 56 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a8662ed..66cafa9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,14 +15,16 @@ release has 32. ### Breaking changes - `Remove-CWCSession`, `Remove-CWCSessionNote` and `Remove-CWCHostFromSession` ask for confirmation by default. - Unattended scripts must add `-Confirm:$false`; without it they fail and remove nothing + Unattended scripts must add `-Confirm:$false`. Without it, a session started with `-NonInteractive` fails at + the prompt and removes nothing; other unattended hosts may wait at the prompt or take its default answer (Yes) - `Connect-CWC` without `-Force` switches to a different server, sign-in method or user instead of keeping the old connection - `Get-CWCLastContact` returns an error when no connection event is found, instead of the current time - `Get-CWCAuditLog` `-StartDate`/`-EndDate` default to the last 24 hours - `Get-CWCSession -Type Support` and `-Type Meeting` without `-Group` read the `All Sessions` and `All Meetings` groups. Before, they read `All Machines`, which holds Access sessions -- HTTP 500 errors are retried only for calls that are safe to repeat +- A read or "set to value" update that gets HTTP 500 is retried 3 times (after 2, 4 and 8 seconds) before it + fails. 0.4.0.0 failed at once. Commands, wakes, deletes and user creation are never retried Details are in the sections below. @@ -91,10 +93,10 @@ Details are in the sections below. deprecated (the server no longer accepts it) and now only emits a warning - All API calls go through one internal helper that builds the endpoint and serializes arguments the same way everywhere (single items, empty lists and nested event entries) -- HTTP 500 retries are limited to calls that are safe to repeat (reads, "set to value" updates). Before, - a 500 returned after the server had acted could queue a second command, wake, delete or user. Retries - now wait 2, 4 and 8 seconds (3 retries); the old 2-32 ms waits gave a struggling server no time to - recover. A final 500 error now includes the server's error message +- HTTP 500 answers are retried for calls that are safe to repeat (reads, "set to value" updates): 3 retries, + waiting 2, 4 and 8 seconds. Calls that act (commands, wakes, deletes, user creation) are never retried, so + one request cannot act twice. 0.4.0.0 had retry code that never ran. A final 500 error includes the server's + error message - Session event type numbers are kept in one table, verified against a live server's web client - **Breaking:** `Remove-CWCSession` prompts by default (`ConfirmImpact = 'High'`), confirms each session separately and rejects an empty GUID. Unattended scripts must add `-Confirm:$false` @@ -172,10 +174,12 @@ Changes to the repository. They do not change the published module. - Repo files aligned with the GitHub-Template: `AGENTS.md` (agent guide; `CLAUDE.md` points to it), community files (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue and PR templates), `pr-validation.yml`, `dependabot.yml`, `copilot-instructions.md`, `.vscode/` settings, `.editorconfig`, `.gitattributes`, an expanded `.gitignore`, - `.PSScriptAnalyzerSettings.psd1` and `.github/PowerShell-StyleGuide.md` + `.PSScriptAnalyzerSettings.psd1` and `.github/PowerShell-StyleGuide.md`. `README.md` links point at the local + community files. This `CHANGELOG.md` is new - Live test scripts: `Tests/Live/Invoke-CWCLiveSmokeTest.ps1` (read-only by default; `-AllowWrites` acts on one - chosen test session and cleans up its notes; `-MfaUserName` and `-TotpTestRole` test the MFA and TOTP logins) - and `Tests/Live/Invoke-CWCHostLaunchDiscovery.ps1` (read-only; redacts secrets) + chosen test session and cleans up its notes; `-MfaUserName` and `-TotpTestRole` test the MFA and TOTP logins; + `-MfaNegativeProbes` records the raw failed-login codes) and `Tests/Live/Invoke-CWCHostLaunchDiscovery.ps1` + (read-only; redacts secrets; `-Launch` opens the client for one test session) - Removed the unloaded `WIP/Invoke-CWCSession.ps1` prototype, superseded by `Enter-CWCSession` ## [0.4.0.0] diff --git a/README.md b/README.md index ba0aca6..c26ccd1 100644 --- a/README.md +++ b/README.md @@ -53,14 +53,16 @@ Install-Module 'ConnectWiseControlAPI' 0.5.0 changes some behaviour. Check your scripts before you update: * `Remove-CWCSession`, `Remove-CWCSessionNote` and `Remove-CWCHostFromSession` ask for confirmation by default. - Unattended scripts must add `-Confirm:$false`; without it they fail and remove nothing. + Unattended scripts must add `-Confirm:$false`. Without it, a session started with `-NonInteractive` fails at the + prompt and removes nothing; other unattended hosts may wait at the prompt or take its default answer (Yes). * `Connect-CWC` without `-Force` now switches to a different server, sign-in method or user. Before, it kept the old connection. * `Get-CWCLastContact` returns an error when it finds no connection event. Before, it returned the current time. * `Get-CWCAuditLog` covers the last 24 hours unless you pass `-StartDate` and `-EndDate`. * `Get-CWCSession -Type Support` and `-Type Meeting` without `-Group` read the `All Sessions` and `All Meetings` groups. Before, they read `All Machines`, which holds Access sessions. -* A request that fails with HTTP 500 is repeated only when repeating is safe (reads and "set to value" updates). +* A read or "set to value" update that gets HTTP 500 is retried 3 times (after 2, 4 and 8 seconds) before it fails. + 0.4 failed at once. Commands, wakes, deletes and user creation are never retried. The full list is in the [changelog](CHANGELOG.md). diff --git a/Tests/ConnectWiseControlAPI.Public.Tests.ps1 b/Tests/ConnectWiseControlAPI.Public.Tests.ps1 index 3822805..bb25858 100644 --- a/Tests/ConnectWiseControlAPI.Public.Tests.ps1 +++ b/Tests/ConnectWiseControlAPI.Public.Tests.ps1 @@ -307,21 +307,37 @@ Describe 'ErrorId survives a failed read' { $SessionID = [guid]::NewGuid() } - It ' reports CWC.NotConnected when not connected' -ForEach @( - @{ Name = 'Get-CWCLastContact'; Call = { param($ID) Get-CWCLastContact -GUID $ID -ErrorAction Stop } } + # The error must stay non-terminating here: with -ErrorAction Stop even Write-Error $_ kept the ErrorId, so a + # test that used Stop would pass against the broken code. + It ' reports CWC.NotConnected as its own non-terminating error' -ForEach @( + @{ Name = 'Get-CWCLastContact'; Call = { param($ID, $Quiet) Get-CWCLastContact -GUID $ID @Quiet } } @{ Name = 'Invoke-CWCCommand'; Call = { - param($ID) Invoke-CWCCommand -GUID $ID -Command 'hostname' -ErrorAction Stop + param($ID, $Quiet) Invoke-CWCCommand -GUID $ID -Command 'hostname' @Quiet } } @{ Name = 'Remove-CWCSessionNote'; Call = { - param($ID) Remove-CWCSessionNote -GUID $ID -All -Confirm:$false -ErrorAction Stop + param($ID, $Quiet) Remove-CWCSessionNote -GUID $ID -All -Confirm:$false @Quiet } } ) { - $Caught = $null - try { & $Call $SessionID } catch { $Caught = $_ } - $Caught | Should -Not -BeNullOrEmpty - $Caught.FullyQualifiedErrorId | Should -BeLike 'CWC.NotConnected,*' + # -ErrorVariable +Name appends to an existing list, so the records come back to this scope + $Reported = New-Object System.Collections.ArrayList + & $Call $SessionID @{ ErrorAction = 'SilentlyContinue'; ErrorVariable = '+Reported' } + $Ids = @($Reported | ForEach-Object { $_.FullyQualifiedErrorId } | Where-Object { $_ }) + $Ids | Should -Not -BeNullOrEmpty + # The last record is the one the function itself wrote + $Ids[-1] | Should -Be "CWC.NotConnected,$Name" + $Ids | Where-Object { $_ -like '*WriteErrorException*' } | Should -BeNullOrEmpty + } + + It ' does not throw with -ErrorAction Ignore' -ForEach @( + @{ Name = 'Get-CWCLastContact'; Call = { param($ID) Get-CWCLastContact -GUID $ID -ErrorAction Ignore } } + @{ Name = 'Invoke-CWCCommand'; Call = { + param($ID) Invoke-CWCCommand -GUID $ID -Command 'hostname' -ErrorAction Ignore + } + } + ) { + { & $Call $SessionID } | Should -Not -Throw } } diff --git a/source/en-US/about_ConnectWiseControlAPI.help.txt b/source/en-US/about_ConnectWiseControlAPI.help.txt index 8f1d302..477e319 100644 --- a/source/en-US/about_ConnectWiseControlAPI.help.txt +++ b/source/en-US/about_ConnectWiseControlAPI.help.txt @@ -49,19 +49,24 @@ SIGNING IN ERRORS Most commands report failures as non-terminating errors. Add - -ErrorAction Stop to catch them. Errors from API calls carry an ErrorId at - the start of - $_.FullyQualifiedErrorId: + -ErrorAction Stop to catch them. Errors from API calls carry an ErrorId + at the start of $_.FullyQualifiedErrorId: CWC.NotConnected Connect-CWC has not been run CWC.AuthModeMismatch The command needs the other kind of connection CWC.Http The server answered with that HTTP status CWC.NoResponse The server did not answer + + An MFA sign-in (-Mfa, -OneTimeCode or -TotpSecret) can also report: + CWC.MfaRequired The account needs a one-time code CWC.MfaCodeRejected The one-time code was wrong or has expired CWC.LoginFailed The sign-in was rejected CWC.LoginThrottled Too many sign-in attempts; wait before retrying + A failed sign-in without MFA, or with -ApiSecret, has no CWC ErrorId; + read its message. + Example: try { @@ -74,8 +79,10 @@ ERRORS REMOVING THINGS Remove-CWCSession, Remove-CWCSessionNote and Remove-CWCHostFromSession ask - for confirmation. In an unattended script add -Confirm:$false; without it - the command fails and removes nothing. + for confirmation. In an unattended script add -Confirm:$false. Without it, + a session started with -NonInteractive fails at the prompt and removes + nothing. Other unattended hosts may wait at the prompt, or take its + default answer (Yes) when they read answers from redirected input. UPGRADING FROM 0.4 Check these before updating scripts written for 0.4.0.0: @@ -90,8 +97,9 @@ UPGRADING FROM 0.4 - Get-CWCSession -Type Support and -Type Meeting without -Group read the 'All Sessions' and 'All Meetings' groups. Before, they read 'All Machines'. - - A request that fails with HTTP 500 is repeated only when repeating is - safe. + - A read or "set to value" update that gets HTTP 500 is retried 3 times + (after 2, 4 and 8 seconds) before it fails. 0.4 failed at once. + Commands, wakes, deletes and user creation are never retried. SEE ALSO Connect-CWC