en-US/about_tcs.core.help.txt
|
TOPIC about_tcs.core SHORT DESCRIPTION Shared configuration, update checks, telemetry, HTTP helpers, secrets and utilities for tcs modules. LONG DESCRIPTION tcs.core is the base module for the TheCodeSaiyan PowerShell suite (tcs.azure, tcs.confluence, tcs.jira, tcs.intune.packaging, tcs.utils). Use its commands instead of re-implementing them in each module. Each tcs module calls Get-ModuleConfig when it loads. The settings file for a module is: <ApplicationData>/PowerShell/Config/<ModuleName>/Module.Config.json It is created with defaults the first time the module loads and is changed with Set-ModuleConfig. Set-ModuleConfig -Setting changes any setting, including a module's own settings from its Config/Module.Defaults.json, and -Reset restores the module's own defaults. A setting with an invalid value falls back to its default; the other settings are still used. Update check Get-ModuleStatus checks the PowerShell Gallery for a newer version at most once every UpdateCheckIntervalHours (default 24). Telemetry Anonymous usage events (command name, duration, success, exception type, PowerShell and OS version and a random installation ID). No user, machine, path or error text is sent. Nothing is sent until a TelemetryUri is configured, or when a module's Telemetry setting is $false. Wrap a command body in Invoke-TcsCommand to record it: function Get-Widget { [CmdletBinding()] param([string]$Name) Invoke-TcsCommand -ScriptBlock { Get-Item -Path $Name } } Pipeline functions use Start-TcsTelemetry in begin, Invoke-TcsCommand -Token in process and Complete-TcsTelemetry in end. Only the outermost command of a module is reported; commands it calls in the same module are skipped. A run is failed when the body throws or writes an error. Terminating errors are rethrown unchanged and telemetry never breaks the command. Inside the script block, $PSBoundParameters and $MyInvocation describe the script block: copy them to a variable first if the body needs them. Invoke-TelemetryCollection still works for existing commands. Its -ModulePath, -Minimal and -Stage 'In-Progress' are deprecated. The telemetry API key is stored encrypted and shown as '********'. Secrets Protect-ConfigValue and Unprotect-ConfigValue use DPAPI on Windows and AES-256 with HMAC-SHA256 on Linux and macOS. Set-ModuleSecret, Get-ModuleSecret and Remove-ModuleSecret save a SecureString or PSCredential per module and name, encrypted, in <ModuleName>/Secrets/<Name>.json in the settings folder. HTTP Invoke-WithRetry retries a script block, with -RetryOnStatusCode (for example 429, 502, 503, 504), -ShouldRetry, Retry-After support and -JitterPercent. Non-terminating errors are only retried with -RetryOnNonTerminatingError (or -ErrorAction Stop in the script block). Get-HttpErrorDetail returns the status code, body and Retry-After of a failed request on Windows PowerShell 5.1 and PowerShell 7. New-BasicAuthHeader builds a Basic Authorization header from a credential. ConvertTo-QueryString builds an escaped query string. Utilities Write-Log, New-DynamicParameter, New-TemporaryDirectory, Test-IsElevated and ConvertTo-CamelCase, ConvertTo-PascalCase, ConvertTo-SnakeCase and ConvertTo-KebabCase (with -PreserveAcronyms on PascalCase and camelCase). Get-ParameterValues and ConvertTo-HashTable are deprecated and planned for removal in 1.0. ENVIRONMENT VARIABLES TCS_TELEMETRY_OPTOUT=1 Turns telemetry off for all tcs modules. TCS_SKIP_UPDATE_CHECK=1 Turns the gallery update check off. TCS_CONFIG_ROOT Moves the settings folder. TCS_TELEMETRY_URI Overrides the telemetry endpoint. TCS_TELEMETRY_APIKEY Overrides the telemetry API key. TCS_MACHINE_KEY_PATH Linux/macOS LocalMachine protection key location. EXAMPLES Turn off update warnings for tcs.core: Set-ModuleConfig -ModuleName tcs.core -UpdateWarning $false Change a module-specific setting: Set-ModuleConfig -ModuleName tcs.jira -Setting @{ PageSize = 100 } Turn off telemetry for every tcs module: $env:TCS_TELEMETRY_OPTOUT = '1' Save and read a token for a module: Set-ModuleSecret -ModuleName tcs.jira -Name ApiToken -SecureString (Read-Host -AsSecureString) $token = Get-ModuleSecret -ModuleName tcs.jira -Name ApiToken Retry throttled requests: Invoke-WithRetry -ScriptBlock { Invoke-RestMethod -Uri $uri } -RetryOnStatusCode 429, 503 -DelaySeconds 1 -BackoffMultiplier 2 Protect a secret for the current user: $protected = Protect-ConfigValue -Value 'P@ssw0rd' Unprotect-ConfigValue -EncryptedValue $protected SEE ALSO Get-ModuleConfig Set-ModuleConfig Get-ModuleStatus Invoke-TcsCommand Start-TcsTelemetry Complete-TcsTelemetry Invoke-TelemetryCollection Invoke-WithRetry Get-HttpErrorDetail New-BasicAuthHeader ConvertTo-QueryString Set-ModuleSecret Get-ModuleSecret Remove-ModuleSecret Protect-ConfigValue https://github.com/ntatschner/TheCodeSaiyan-PowerShell-tcs.core KEYWORDS tcs TheCodeSaiyan Configuration Telemetry |