tiPS.psm1
|
#Requires -Version 3.0 Set-StrictMode -Version Latest # All module functions that reference a file path in the module should use this variable, rather than PSScriptRoot. New-Variable -Name 'PSModuleRoot' -Value $PSScriptRoot -Option Constant -Scope Script if (-not ('tiPS.PowerShellTip' -as [type])) { [string] $assemblyFilePath = Resolve-Path -Path "$script:PSModuleRoot/Classes/tiPSClasses.dll" Add-Type -Path $assemblyFilePath } function StartModuleUpdateIfNeeded { [CmdletBinding()] [OutputType([void])] Param ( [Parameter(Mandatory = $true, HelpMessage = 'The tiPS configuration to use to determine if the module should be updated.')] [ValidateNotNullOrEmpty()] [tiPS.Configuration] $Config ) # For performance reasons, check if we should never update the module before doing anything else. if ($Config.AutoUpdateCadence -eq [tiPS.ModuleAutoUpdateCadence]::Never) { return } [DateTime] $modulesLastUpdateDate = ReadModulesLastUpdateDateOrDefault [TimeSpan] $timeSinceLastUpdate = [DateTime]::Now - $modulesLastUpdateDate [int] $daysSinceLastUpdate = $timeSinceLastUpdate.Days [bool] $moduleUpdateNeeded = $false switch ($Config.AutoUpdateCadence) { ([tiPS.ModuleAutoUpdateCadence]::Never) { $moduleUpdateNeeded = $false; break } ([tiPS.ModuleAutoUpdateCadence]::Daily) { $moduleUpdateNeeded = $daysSinceLastUpdate -ge 1; break } ([tiPS.ModuleAutoUpdateCadence]::Weekly) { $moduleUpdateNeeded = $daysSinceLastUpdate -ge 7 ; break } ([tiPS.ModuleAutoUpdateCadence]::BiWeekly) { $moduleUpdateNeeded = $daysSinceLastUpdate -ge 14; break } ([tiPS.ModuleAutoUpdateCadence]::Monthly) { $moduleUpdateNeeded = $daysSinceLastUpdate -ge 30; break } } if ($moduleUpdateNeeded) { UpdateModule } else { Write-Debug "An auto-update of the tiPS module is not needed at this time." } } function UpdateModule { [CmdletBinding()] [OutputType([void])] Param() Write-Verbose "Updating the tiPS module in a background job." Start-Job -ScriptBlock { Write-Verbose "Updating the tiPS module." [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 Update-Module -Name 'tiPS' -Force Write-Verbose "Removing all but the latest version of the tiPS module to keep the modules directory clean." $latestModuleVersion = Get-InstalledModule -Name 'tiPS' $allModuleVersions = Get-InstalledModule -Name 'tiPS' -AllVersions $allModuleVersions | Where-Object { $_.Version -ne $latestModuleVersion.Version } | Uninstall-Module -Force } [DateTime] $todayWithoutTime = [DateTime]::Now.Date # Exclude the time for a better user experience. WriteModulesLastUpdateDate -ModulesLastUpdateDate $todayWithoutTime } function ReadModulesLastUpdateDateOrDefault { [CmdletBinding()] [OutputType([DateTime])] Param() [DateTime] $modulesLastUpdateDate = [DateTime]::MinValue [string] $moduleUpdateDateFilePath = GetModulesLastUpdateDateFilePath if (Test-Path -Path $moduleUpdateDateFilePath -PathType Leaf) { [string] $modulesLastUpdateDateString = [System.IO.File]::ReadAllText($moduleUpdateDateFilePath) $modulesLastUpdateDate = [DateTime]::Parse($modulesLastUpdateDateString) } return $modulesLastUpdateDate } function WriteModulesLastUpdateDate { [CmdletBinding()] [OutputType([void])] Param ( [DateTime] $ModulesLastUpdateDate ) [string] $moduleUpdateDateFilePath = GetModulesLastUpdateDateFilePath Write-Verbose "Writing modules last update date '$ModulesLastUpdateDate' to '$moduleUpdateDateFilePath'." $ModulesLastUpdateDate.ToString() | Set-Content -Path $moduleUpdateDateFilePath -Force -NoNewline } function GetModulesLastUpdateDateFilePath { [CmdletBinding()] [OutputType([string])] Param() [string] $appDataDirectoryPath = Get-TiPSDataDirectoryPath [string] $moduleUpdateDateFilePath = Join-Path -Path $appDataDirectoryPath -ChildPath 'ModulesLastUpdateDate.txt' return $moduleUpdateDateFilePath } function WriteAutomaticPowerShellTipIfNeeded { [CmdletBinding()] [OutputType([void])] Param ( [Parameter(Mandatory = $true, HelpMessage = 'The tiPS configuration used to determine if a tip should be written.')] [ValidateNotNullOrEmpty()] [tiPS.Configuration] $Config ) # For performance reasons, check if we should never write a tip before doing anything else. if ($Config.AutoWritePowerShellTipCadence -eq [tiPS.WritePowerShellTipCadence]::Never) { return } [DateTime] $lastAutomaticTipWrittenDate = ReadLastAutomaticTipWrittenDateOrDefault [TimeSpan] $timeSinceLastAutomaticTipWritten = [DateTime]::Now - $lastAutomaticTipWrittenDate [int] $daysSinceLastAutomaticTipWritten = $timeSinceLastAutomaticTipWritten.Days [bool] $shouldShowTip = $false switch ($Config.AutoWritePowerShellTipCadence) { ([tiPS.WritePowerShellTipCadence]::Never) { $shouldShowTip = $false; break } ([tiPS.WritePowerShellTipCadence]::EverySession) { $shouldShowTip = $true; break } ([tiPS.WritePowerShellTipCadence]::Daily) { $shouldShowTip = $daysSinceLastAutomaticTipWritten -ge 1; break } ([tiPS.WritePowerShellTipCadence]::Weekly) { $shouldShowTip = $daysSinceLastAutomaticTipWritten -ge 7; break } } if ($shouldShowTip) { [bool] $isSessionInteractive = TestPowerShellSessionIsInteractive if (-not $isSessionInteractive) { Write-Verbose "tiPS is configured to write an automatic tip now, but this session is non-interactive. tiPS will only write automatic tips when it is imported into an interactive PowerShell session. This prevents a tip from being written at unexpected times, such as when the user or an automated process runs PowerShell scripts." return } WriteAutomaticPowerShellTip } else { Write-Debug "Showing a tiPS PowerShell tip is not needed at this time." } } function WriteAutomaticPowerShellTip { [CmdletBinding()] [OutputType([void])] Param() Write-PowerShellTip [DateTime] $todayWithoutTime = [DateTime]::Now.Date # Exclude the time for a better user experience. WriteLastAutomaticTipWrittenDate -LastAutomaticTipWrittenDate $todayWithoutTime } function TestPowerShellSessionIsInteractive { [CmdletBinding()] [OutputType([bool])] Param() if (-not [Environment]::UserInteractive) { Write-Debug "The [Environment]::UserInteractive property shows this PowerShell session is not interactive." return $false } [string[]] $typicalNonInteractiveCommandLineArguments = @( '-Command' '-c' '-EncodedCommand' '-e' '-ec' '-File' '-f' '-NonInteractive' ) [string[]] $commandLineArgs = [Environment]::GetCommandLineArgs() Write-Debug "The PowerShell command line arguments are '$commandLineArgs'." [string[]] $nonInteractiveArgMatches = $commandLineArgs | Where-Object { $_ -in $typicalNonInteractiveCommandLineArguments } [bool] $isNonInteractive = $null -ne $nonInteractiveArgMatches -and $nonInteractiveArgMatches.Count -gt 0 if ($isNonInteractive) { return $false } return $true } function ReadLastAutomaticTipWrittenDateOrDefault { [CmdletBinding()] [OutputType([DateTime])] Param() [DateTime] $lastAutomaticTipWrittenDate = [DateTime]::MinValue [string] $lastAutomaticTipWrittenDateFilePath = GetLastAutomaticTipWrittenDateFilePath if (Test-Path -Path $lastAutomaticTipWrittenDateFilePath -PathType Leaf) { [string] $lastAutomaticTipWrittenDateString = [System.IO.File]::ReadAllText($lastAutomaticTipWrittenDateFilePath) $lastAutomaticTipWrittenDate = [DateTime]::Parse($lastAutomaticTipWrittenDateString) } return $lastAutomaticTipWrittenDate } function WriteLastAutomaticTipWrittenDate { [CmdletBinding()] [OutputType([void])] Param ( [DateTime] $LastAutomaticTipWrittenDate ) [string] $lastAutomaticTipWrittenDateFilePath = GetLastAutomaticTipWrittenDateFilePath Write-Verbose "Writing last automatic tip Written date '$LastAutomaticTipWrittenDate' to '$lastAutomaticTipWrittenDateFilePath'." $LastAutomaticTipWrittenDate.ToString() | Set-Content -Path $lastAutomaticTipWrittenDateFilePath -Force -NoNewline } function GetLastAutomaticTipWrittenDateFilePath { [CmdletBinding()] [OutputType([string])] Param() [string] $appDataDirectoryPath = Get-TiPSDataDirectoryPath [string] $lastAutomaticTipWrittenDateFilePath = Join-Path -Path $appDataDirectoryPath -ChildPath 'LastAutomaticTipWrittenDate.txt' return $lastAutomaticTipWrittenDateFilePath } function GetConfigurationFilePath { [CmdletBinding()] [OutputType([string])] Param() [string] $appDataDirectoryPath = Get-TiPSDataDirectoryPath [string] $configFilePath = Join-Path -Path $appDataDirectoryPath -ChildPath 'tiPSConfiguration.json' return $configFilePath } function ReadConfigurationFromFileOrDefault { [CmdletBinding()] [OutputType([tiPS.Configuration])] Param() $config = [tiPS.Configuration]::new() [string] $configFilePath = GetConfigurationFilePath if (Test-Path -Path $configFilePath -PathType Leaf) { Write-Verbose "Reading configuration from '$configFilePath'." $config = [System.IO.File]::ReadAllText($configFilePath) | ConvertFrom-Json } return $config } function WriteConfigurationToFile { [CmdletBinding()] [OutputType([void])] Param ( [tiPS.Configuration] $Config ) [string] $configFilePath = GetConfigurationFilePath if (-not (Test-Path -Path $configFilePath -PathType Leaf)) { New-Item -Path $configFilePath -ItemType File -Force > $null } Write-Verbose "Writing configuration to '$configFilePath'." $Config | ConvertTo-Json -Depth 100 | Set-Content -Path $configFilePath -Force } function InitializeModule { [CmdletBinding()] [OutputType([void])] Param() Write-Debug 'Reading all tips from JSON file and storing them in a $Tips variable for access by other module functions.' [hashtable] $tipHashTable = ReadAllPowerShellTipsFromJsonFile New-Variable -Name 'Tips' -Value $tipHashtable -Option Constant -Scope Script Write-Debug 'Reading in configuration from JSON file and storing it in a $TiPSConfiguration variable for access by other module functions.' [tiPS.Configuration] $config = ReadConfigurationFromFileOrDefault New-Variable -Name 'TiPSConfiguration' -Value $config -Scope Script Write-Debug "Checking if we should write a PowerShell tip, and writing one if needed." WriteAutomaticPowerShellTipIfNeeded -Config $script:TiPSConfiguration Write-Debug 'Checking if the module needs to be updated, and updating it if needed.' StartModuleUpdateIfNeeded -Config $script:TiPSConfiguration } function GetPowerShellProfileFilePaths { [string[]] $profileFilePaths = @() # The $PROFILE variable may not exist depending on the host or the context in which PowerShell was started. if (Test-Path -Path variable:PROFILE) { $profileFilePaths = @( $PROFILE.CurrentUserAllHosts $PROFILE.CurrentUserCurrentHost $PROFILE.AllUsersAllHosts $PROFILE.AllUsersCurrentHost ) } return ,$profileFilePaths } function GetPowerShellProfileFilePathsThatExist { [string[]] $powerShellProfileFilePaths = GetPowerShellProfileFilePaths [string[]] $profileFilePathsThatExist = $powerShellProfileFilePaths | Where-Object { Test-Path -Path $_ -PathType Leaf } return ,$profileFilePathsThatExist } function GetPowerShellProfileFilePathToAddImportTo { [string] $profileFilePath = [string]::Empty # The $PROFILE variable may not exist depending on the host or the context in which PowerShell was started. if (Test-Path -Path variable:PROFILE) { $profileFilePath = $PROFILE.CurrentUserAllHosts } return $profileFilePath } function GetImportStatementToAddToPowerShellProfile { return 'Import-Module -Name tiPS # Added by tiPS to get automatic tips and updates.' } function ReadAllPowerShellTipsFromJsonFile { [CmdletBinding()] [OutputType([System.Collections.Specialized.OrderedDictionary])] Param() [string] $powerShellTipsJsonFilePath = Join-Path -Path $script:PSModuleRoot -ChildPath 'PowerShellTips.json' Write-Verbose "Reading PowerShell tips from '$powerShellTipsJsonFilePath'." [tiPS.PowerShellTip[]] $tipObjects = [System.IO.File]::ReadAllText($powerShellTipsJsonFilePath) | # Use .NET method instead of Get-Content for performance. ConvertFrom-Json [hashtable] $tipHashtable = [ordered]@{} foreach ($tip in $tipObjects) { $tipHashtable[$tip.Id] = $tip } return $tipHashtable } function WritePowerShellTipToTerminal { [CmdletBinding()] [OutputType([void])] [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '')] Param ( [Parameter(Mandatory = $true, HelpMessage = 'The PowerShell Tip to write to the terminal.')] [ValidateNotNullOrEmpty()] [tiPS.PowerShellTip] $Tip ) [ConsoleColor] $headerColor = [ConsoleColor]::Cyan [ConsoleColor] $tipTextColor = [ConsoleColor]::White [ConsoleColor] $exampleColor = [ConsoleColor]::Yellow [ConsoleColor] $urlsColor = [ConsoleColor]::Green [ConsoleColor] $minPowerShellVersionColor = [ConsoleColor]::Red # Calculate how many header characters to put on each side of the title to make it look nice. [int] $numberOfCharactersInHeader = 90 [int] $headerContentLength = $Tip.Title.Length + 2 + $Tip.Category.ToString().Length + 3 [int] $numberOfHeaderCharactersOnEachSideOfTitle = [Math]::Floor(($numberOfCharactersInHeader - ($headerContentLength)) / 2) [int] $additionalHeaderCharacterNeeded = 0 if ($headerContentLength % 2 -eq 1) { $additionalHeaderCharacterNeeded = 1 } [string] $header = ('-' * $numberOfHeaderCharactersOnEachSideOfTitle) + ' ' + $Tip.Title + ' ' + '[' + $Tip.Category + '] ' + ('-' * ($numberOfHeaderCharactersOnEachSideOfTitle + $additionalHeaderCharacterNeeded)) Write-Host $header -ForegroundColor $headerColor Write-Host $Tip.TipText -ForegroundColor $tipTextColor if (-not [string]::IsNullOrWhiteSpace($Tip.Example)) { Write-Host 'Example: ' -ForegroundColor $exampleColor -NoNewline Write-Host $Tip.Example -ForegroundColor $exampleColor } if ($Tip.UrlsAreProvided) { Write-Host 'More information: ' -ForegroundColor $urlsColor -NoNewline Write-Host $Tip.Urls -ForegroundColor $urlsColor } if ($Tip.MinPowerShellVersionIsProvided) { Write-Host 'Required PowerShell version or greater: ' -ForegroundColor $minPowerShellVersionColor -NoNewline Write-Host $Tip.MinPowerShellVersion -ForegroundColor $minPowerShellVersionColor } Write-Host ('-' * $numberOfCharactersInHeader) -ForegroundColor $headerColor } function Add-TiPSImportToPowerShellProfile { <# .SYNOPSIS Adds the tiPS Import-Module statement to the user's PowerShell profile file. .DESCRIPTION This function edits the user's PowerShell profile file to import the tiPS module, which can provide automatic tips and updates. If the profile already imports the tiPS module, then no changes are made. Only the default PowerShell profile paths are searched to see if the tiPS module is already imported; if it is imported from a dot-sourced script, the function will not detect that and will add an import statement directly to the profile file. .INPUTS None. You cannot pipe objects to the function. .OUTPUTS None. The function does not return any objects. .EXAMPLE Add-TiPSImportToPowerShellProfile This example edits the PowerShell profile to add a tiPS Import-Module statement. #> [CmdletBinding(SupportsShouldProcess = $true)] [OutputType([void])] Param() Process { [bool] $moduleImportStatementIsAlreadyInProfile = Test-PowerShellProfileImportsTiPS if ($moduleImportStatementIsAlreadyInProfile) { Write-Verbose "PowerShell profile already imports the tiPS module, so no changes are necessary." return } [string] $profileFilePath = GetPowerShellProfileFilePathToAddImportTo [string] $contentToAddToProfile = GetImportStatementToAddToPowerShellProfile if ([string]::IsNullOrWhiteSpace($profileFilePath)) { Write-Error "Could not determine the PowerShell profile file path." return } if (-not (Test-Path -Path $profileFilePath -PathType Leaf)) { if ($PSCmdlet.ShouldProcess("PowerShell profile '$profileFilePath'", 'Create')) { Write-Verbose "Creating PowerShell profile '$profileFilePath'." New-Item -Path $profileFilePath -ItemType File -Force > $null } } if ($PSCmdlet.ShouldProcess("PowerShell profile '$profileFilePath'", 'Update')) { Write-Verbose "Adding '$contentToAddToProfile' to PowerShell profile '$profileFilePath'." Add-Content -Path $profileFilePath -Value $contentToAddToProfile -Force } } } function Get-PowerShellTip { <# .SYNOPSIS Get a PowerShellTip object. If no parameters are specified, a random tip is returned. .DESCRIPTION Get a PowerShellTip object. If no parameters are specified, a random tip is returned. .PARAMETER Id The ID of the tip to retrieve. If not supplied, a random tip will be returned. .PARAMETER AllTips Return all tips. .INPUTS You can pipe a [string] of the ID of the tip to retrieve, or a PsCustomObject with a [string] 'Id' property. .OUTPUTS A [tiPS.PowerShellTip] object representing the PowerShell tip. If the -AllTips switch is provided, a [System.Collections.Specialized.OrderedDictionary] is returned. .EXAMPLE Get-PowerShellTip Get a random tip. .EXAMPLE Get-PowerShellTip -Id '2023-07-16-powershell-is-open-source' Get the tip with the specified ID. If no tip with the specified ID exists, an error is written. .EXAMPLE Get-PowerShellTip -AllTips Get all tips. .EXAMPLE '2023-07-16-powershell-is-open-source' | Get-PowerShellTip Pipe a [string] of the ID of the tip to retrieve. .EXAMPLE [PSCustomObject]@{ Id = '2023-07-16-powershell-is-open-source' } | Get-PowerShellTip Pipe an object with a [string] 'Id' property. #> [CmdletBinding(DefaultParameterSetName = 'Default')] [OutputType([tiPS.PowerShellTip], ParameterSetName = 'Default')] [OutputType([System.Collections.Specialized.OrderedDictionary], ParameterSetName = 'AllTips')] Param ( [Parameter(ParameterSetName = 'Default', Mandatory = $false, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = 'The ID of the tip to retrieve. If not supplied, a random tip will be returned.')] [string] $Id, [Parameter(ParameterSetName = 'AllTips', Mandatory = $false, HelpMessage = 'Return all tips.')] [switch] $AllTips ) Process { if ($AllTips) { return ReadAllPowerShellTipsFromJsonFile } if ([string]::IsNullOrWhiteSpace($Id)) { $Id = $script:Tips.Keys | Get-Random -Count 1 } else { if (-not $script:Tips.ContainsKey($Id)) { Write-Error "A tip with ID '$Id' does not exist." return } } [tiPS.PowerShellTip] $tip = $script:Tips[$Id] return $tip } } function Get-TiPSConfiguration { <# .SYNOPSIS Get the tiPS module configuration for the current user. .DESCRIPTION Get the tiPS module configuration for the current user. .INPUTS None. You cannot pipe objects to the function. .OUTPUTS A [tiPS.Configuration] object containing all of the tiPS module configuration for the current user. .EXAMPLE Get-TiPSConfiguration Get the tiPS module configuration. #> [CmdletBinding()] [OutputType([tiPS.Configuration])] Param() return $script:TiPSConfiguration } function Get-TiPSDataDirectoryPath { <# .SYNOPSIS Get the tiPS data directory path. .DESCRIPTION Get the tiPS data directory path where the tiPS module stores all of its data for the current user. .INPUTS None. You cannot pipe objects to the function. .OUTPUTS A [string] of the directory path. .EXAMPLE Get-TiPSDataDirectoryPath Get the tiPS data directory path. #> [CmdletBinding()] [OutputType([string])] Param() [string] $usersLocalAppDataPath = [System.Environment]::GetFolderPath([System.Environment+SpecialFolder]::LocalApplicationData) [string] $appDataDirectoryPath = Join-Path -Path $usersLocalAppDataPath -ChildPath ( Join-Path -Path 'PowerShell' -ChildPath 'tiPS') return $appDataDirectoryPath } function Remove-TiPSImportFromPowerShellProfile { <# .SYNOPSIS Removes the tiPS Import-Module statement from the user's PowerShell profile file. .DESCRIPTION This function edits the user's PowerShell profile file to remove the Import-Module statement that is used to import the tiPS module. If the profile does not import the tiPS module, then no changes are made. Only the default PowerShell profile paths are searched to see if the tiPS module is imported; if it is imported from a dot-sourced script, the function will not detect the import statement and it will not be removed. This function will only remove the tiPS import statement added by the Add-TiPSImportToPowerShellProfile function. If you manually added the import statement to your profile, this function may not remove it. .INPUTS None. You cannot pipe objects to the function. .OUTPUTS None. The function does not return any objects. .EXAMPLE Remove-TiPSImportFromPowerShellProfile This example edits the PowerShell profile to remove the tiPS Import-Module statement. #> [CmdletBinding(SupportsShouldProcess = $true)] [OutputType([void])] Param() Process { [bool] $moduleImportStatementIsInProfile = Test-PowerShellProfileImportsTiPS if (-not $moduleImportStatementIsInProfile) { Write-Verbose "The PowerShell profiles do not import the tiPS module, so no changes are necessary." return } [string[]] $profileFilePathsThatExist = GetPowerShellProfileFilePathsThatExist [string] $contentToRemoveFromProfile = GetImportStatementToAddToPowerShellProfile [bool] $atLeastOneProfileFileModified = $false foreach ($profileFilePath in $profileFilePathsThatExist) { [string] $fileContents = Get-Content -Path $profileFilePath -Raw if ($fileContents.Contains($contentToRemoveFromProfile)) { if ($PSCmdlet.ShouldProcess("PowerShell profile '$profileFilePath'", 'Update')) { Write-Verbose "Removing '$contentToRemoveFromProfile' from PowerShell profile '$profileFilePath'." [string] $updatedFileContents = $fileContents -replace $contentToRemoveFromProfile, '' Set-Content -Path $profileFilePath -Value $updatedFileContents -Force } $atLeastOneProfileFileModified = $true } } if (-not $atLeastOneProfileFileModified) { Write-Warning "One of the PowerShell profiles does import the tiPS module, but not with the expected import statement '$contentToRemoveFromProfile'. Run 'Test-PowerShellProfileImportsTiPS -Verbose' to see which profile files import the tiPS module, and then manually remove the statement from the file." } } } function Set-TiPSConfiguration { <# .SYNOPSIS Set the tiPS configuration. .DESCRIPTION Set the entire or partial tiPS configuration. .PARAMETER Configuration The tiPS configuration object to set. All configuration properties are updated to match the provided object. No other properties may be provided when this parameter is used. .PARAMETER AutomaticallyUpdateModule Whether to automatically update the tiPS module at session startup. The module update is performed in a background job, so it does not block the PowerShell session from starting. This also means that the new module version will not be used until the next time the module is imported, or the next time a PowerShell session is started. Old versions of the module are automatically deleted after a successful update. Valid values are Never, Daily, Weekly, Monthly, and Yearly. Default is Never. .PARAMETER AutomaticallyWritePowerShellTip Whether to automatically write a PowerShell tip at session startup. Valid values are Never, Daily, Weekly, Monthly, and Yearly. Default is Never. .INPUTS You can pipe a [tiPS.Configuration] object containing the tiPS configuration to set, or a PsCustomObject with AutomaticallyUpdateModule and/or AutomaticallyWritePowerShellTip properties. .OUTPUTS None. The function does not return any objects. .EXAMPLE Set-TiPSConfiguration -Configuration $config Set the tiPS configuration. .EXAMPLE Set-TiPSConfiguration -AutomaticallyUpdateModule Weekly Set the tiPS configuration to automatically update the tiPS module every 7 days. .EXAMPLE Set-TiPSConfiguration -AutomaticallyWritePowerShellTip Daily Set the tiPS configuration to automatically write a PowerShell tip every day. .EXAMPLE Set-TiPSConfiguration -AutomaticallyUpdateModule Never -AutomaticallyWritePowerShellTip Never Set the tiPS configuration to never automatically update the tiPS module or write a PowerShell tip. #> [CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'PartialConfiguration')] [OutputType([void])] Param ( [Parameter(Mandatory = $true, ParameterSetName = 'EntireConfiguration', ValueFromPipeline = $true)] [ValidateNotNullOrEmpty()] [tiPS.Configuration] $Configuration, [Parameter(Mandatory = $false, ParameterSetName = 'PartialConfiguration', ValueFromPipelineByPropertyName = $true)] [tiPS.ModuleAutoUpdateCadence] $AutomaticallyUpdateModule = [tiPS.ModuleAutoUpdateCadence]::Never, [Parameter(Mandatory = $false, ParameterSetName = 'PartialConfiguration', ValueFromPipelineByPropertyName = $true)] [tiPS.WritePowerShellTipCadence] $AutomaticallyWritePowerShellTip = [tiPS.WritePowerShellTipCadence]::Never ) Process { # If the entire Configuration object parameter is passed in, set it and return. if ($PSBoundParameters.ContainsKey('Configuration')) { if ($PSCmdlet.ShouldProcess('tiPS configuration', 'Set')) { $script:TiPSConfiguration = $Configuration WriteConfigurationToFile -Config $script:TiPSConfiguration } } # If the AutomaticallyUpdateModule parameter is passed in, set it. if ($PSBoundParameters.ContainsKey('AutomaticallyUpdateModule')) { if ($PSCmdlet.ShouldProcess('tiPS configuration AutoUpdateCadence property', 'Set')) { $script:TiPSConfiguration.AutoUpdateCadence = $AutomaticallyUpdateModule WriteConfigurationToFile -Config $script:TiPSConfiguration } } # If the AutomaticallyWritePowerShellTip parameter is passed in, set it. if ($PSBoundParameters.ContainsKey('AutomaticallyWritePowerShellTip')) { if ($PSCmdlet.ShouldProcess('tiPS configuration AutoWritePowerShellTipCadence property', 'Set')) { $script:TiPSConfiguration.AutoWritePowerShellTipCadence = $AutomaticallyWritePowerShellTip WriteConfigurationToFile -Config $script:TiPSConfiguration } } [bool] $automaticActionsAreConfigured = $script:TiPSConfiguration.AutoUpdateCadence -ne [tiPS.ModuleAutoUpdateCadence]::Never -or $script:TiPSConfiguration.AutoWritePowerShellTipCadence -ne [tiPS.WritePowerShellTipCadence]::Never if ($automaticActionsAreConfigured) { [bool] $tiPSModuleIsImportedByPowerShellProfile = Test-PowerShellProfileImportsTiPS if (-not $tiPSModuleIsImportedByPowerShellProfile) { Write-Warning "tiPS can only perform automatic actions when it is imported into the current PowerShell session. Run 'Edit-ProfileToImportTiPS' to update your PowerShell profile import tiPS automatically when a new session starts, or manually add 'Import-Module -Name tiPS' to your profile file. If you are importing the module in a different way, such as in a script that is dot-sourced into your profile, you can ignore this warning." } } } } function Test-PowerShellProfileImportsTiPS { <# .SYNOPSIS Tests whether the PowerShell profile imports the tiPS module. .DESCRIPTION Tests whether the PowerShell profile imports the tiPS module. Returns true if it finds an 'Import-Module -Name tiPS' statement in the profile, false otherwise. This only looks in the default PowerShell profile paths. If the tiPS module is imported from a dot-sourced file then this will return false. .INPUTS None. You cannot pipe objects to the function. .OUTPUTS System.Boolean representing if the tiPS module is imported by the PowerShell profile or not. .EXAMPLE Test-PowerShellProfileImportsTiPS Tests whether the PowerShell profile imports the tiPS module, returning true if it does and false otherwise. .EXAMPLE Test-PowerShellProfileImportsTiPS -Verbose Tests whether the PowerShell profile imports the tiPS module, returning true if it does and false otherwise. If true, the verbose output will list the profile file paths and the lines that import the tiPS module. If false, the verbose output will list the profile file paths that it checked. #> [CmdletBinding()] [OutputType([System.Boolean])] Param() [string[]] $profileFilePathsThatExist = GetPowerShellProfileFilePathsThatExist if ($null -eq $profileFilePathsThatExist -or $profileFilePathsThatExist.Count -eq 0) { Write-Verbose "No PowerShell profile files exist." return $false } [string] $requiredContentRegex = 'Import-Module\s.*tiPS' [Microsoft.PowerShell.Commands.MatchInfo] $results = Select-String -Path $profileFilePathsThatExist -Pattern $requiredContentRegex if ($null -ne $results) { Write-Verbose "The tiPS module is imported by the following profile lines:" $results | ForEach-Object { Write-Verbose " $($_.Path): $($_.Line)" } return $true } Write-Verbose "The tiPS module is not imported directly by any of the PowerShell profiles: $profileFilePathsThatExist" return $false } function Write-PowerShellTip { <# .SYNOPSIS Write a PowerShell tip to the terminal. .DESCRIPTION Write a PowerShell tip to the terminal. If no tip is specified, a random tip will be written. The tip is written to the terminal using the Write-Host cmdlet so that colours can be applied. Thus, the tip is not written to the pipeline and cannot be captured in a variable. If you want to capture the tip in a variable, use the Get-PowerShellTip function. .PARAMETER Id The ID of the tip to write. If not supplied, a random tip will be written. If no tip with the specified ID exists, an error is written. .INPUTS You can pipe a [string] of the ID of the tip to write, or a PsCustomObject with a [string] 'Id' property. .OUTPUTS None. The function does not return any objects. .EXAMPLE Write-PowerShellTip Write a random tip to the terminal. .EXAMPLE Write-PowerShellTip -Id '2023-07-16-powershell-is-open-source' Write the tip with the specified ID. #> [CmdletBinding()] [Alias('Tips')] [OutputType([void])] Param ( [Parameter(Mandatory = $false, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, HelpMessage = 'The ID of the tip to write. If not supplied, a random tip will be written.')] [string] $Id ) Process { [tiPS.PowerShellTip] $tip = Get-PowerShellTip -Id $Id WritePowerShellTipToTerminal -Tip $tip } } Write-Debug 'Now that all types and functions are imported, initializing the module.' InitializeModule # Function and Alias exports are defined in the modules manifest (.psd1) file. |