Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions .build/gallery-tags.ps1
Original file line number Diff line number Diff line change
@@ -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_<name> and PSCommand_<name> 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)"
}
27 changes: 24 additions & 3 deletions Build/Test-ReleasePackage.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -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/<Name>/<version>/) 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.
Expand Down Expand Up @@ -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"
Expand Down
97 changes: 53 additions & 44 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,22 @@ 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

- `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
- HTTP 500 errors are retried only for calls that are safe to repeat
- `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 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.

Expand All @@ -34,11 +39,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`,
Expand All @@ -54,18 +54,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
Expand All @@ -82,48 +75,36 @@ 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

- `Get-CWCLauncURL` now forwards to `Get-CWCRemoteWorkforceLaunchURL` with a warning; removal in v1.0

### 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<version>` 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/<ModuleName>/<version>/`. 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
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`
- `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
Expand All @@ -133,18 +114,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`
Expand All @@ -171,7 +153,34 @@ 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<version>` 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/<ModuleName>/<version>/`. 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`. `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;
`-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]

Expand Down
2 changes: 1 addition & 1 deletion ConnectWiseControlAPI_Functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading
Loading