functions/timehelpers.ps1
|
#region set of functions for converting times to and from Universal time Function ConvertTo-UTCTime { [cmdletbinding()] [alias("tout")] [OutputType([Datetime],[System.String])] Param( [Parameter(ValueFromPipeline, HelpMessage = "Enter a Datetime value")] [ValidateNotNullOrEmpty()] [datetime]$DateTime = $(Get-Date), [switch]$AsString ) Begin { Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Starting $($MyInvocation.MyCommand)" } #begin Process { Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Converting $DateTime to UTC" $utc = $datetime.ToUniversalTime() if ($AsString) { "{0:u}" -f $utc } else { $utc } } #process End { Write-Verbose "[$((Get-Date).TimeOfDay) END ] Ending $($MyInvocation.MyCommand)" } #end } #close ConvertTo-UTCTime Function ConvertFrom-UTCTime { [cmdletbinding()] [alias("frut")] [OutputType([datetime])] Param( [Parameter(Mandatory, HelpMessage = "Enter a Universal Datetime value", ValueFromPipeline)] [ValidateNotNullOrEmpty()] [datetime]$DateTime ) Begin { Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Starting $($MyInvocation.MyCommand)" } #begin Process { Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Converting $DateTime UTC to local time" $DateTime.ToLocalTime() } #process End { Write-Verbose "[$((Get-Date).TimeOfDay) END ] Ending $($MyInvocation.MyCommand)" } #end } #close ConvertFrom-UTCTime #endregion #region time zone related commands # convert a foreign time to local time Function ConvertTo-LocalTime { [cmdletbinding()] [alias("clt")] [OutputType("DateTime")] Param( [Parameter(Position = 0, Mandatory, HelpMessage = "Enter a non local date time")] [datetime]$Datetime, [Parameter(Position = 1, Mandatory, HelpMessage = "Enter the location's' UTC Offset", ValueFromPipelineByPropertyName)] [Alias("offset")] [timespan]$UTCOffset, [Parameter(HelpMessage = "Indicate that the foreign location is using Daylight Saving Time")] [alias("dst")] [switch]$DaylightSavingTime ) Begin { Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Starting $($MyInvocation.MyCommand)" } #begin Process { Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Converting $Datetime (UTC $UTCOffset) to local time " $u = ($Datetime).addminutes( - ($UTCOffset.TotalMinutes)) Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] UTC is $u" if ($DaylightSavingTime) { Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Accounting for DST" $u.ToLocalTime().AddHours(-1) } else { $u.ToLocalTime() } } #process End { Write-Verbose "[$((Get-Date).TimeOfDay) END ] Ending $($MyInvocation.MyCommand)" } #end } #close ConvertTo-LocalTime <# list time zones [System.TimeZoneinfo]::GetSystemTimeZones() | Out-GridView or Get-TimeZone -listavailable time zone IDs are case sensitive #> # http://worldtimeapi.org Function Get-MyTimeInfo { [cmdletbinding()] [OutputType("myTimeInfo", "String")] [alias("gti")] Param( [Parameter(Position = 0)] [ValidateNotNullOrEmpty()] #limit this to no more than 5 locations [System.Collections.Specialized.OrderedDictionary]$Locations = [ordered]@{ Singapore = "Singapore Standard Time"; Seattle = "Pacific Standard Time"; Stockholm = "Central Europe Standard Time"; }, [ValidateNotNullOrEmpty()] [string]$HomeTimeZone = "Eastern Standard Time", [Parameter(HelpMessage = "Specify the datetime value to use. The default is now.")] [ValidateNotNullOrEmpty()] [datetime]$DateTime = $(Get-Date), #Display the results as a formatted table. This parameter has an alias of ft. [Alias("ft")] [switch]$AsTable, #Display the results as a formatted list. This parameter has an alias of fl. [Alias("fl")] [switch]$AsList ) Write-Verbose "Starting $($MyInvocation.MyCommand)" $now = $DateTime $utc = $now.ToUniversalTime() Write-Verbose "Getting world clock settings for $Now [UTC: $UTC]" $hash = [Ordered]@{ Now = $now Home = [System.TimeZoneinfo]::ConvertTimeBySystemTimeZoneId($now, $HomeTimeZone) UTC = $UTC } $locations.GetEnumerator() | ForEach-Object { Write-Verbose "Getting time for $($_.key)" $remote = [System.TimeZoneinfo]::ConvertTimeBySystemTimeZoneId($now, $_.value) Write-Verbose $remote $hash.Add($_.key, $remote) } $hash.add("IsDaylightSavings", $now.IsDaylightSavingTime()) $tobj = New-Object -TypeName PSObject -Property $hash $tobj.PSObject.TypeNames.insert(0, "myTimeInfo") $cities = $tobj.PSObject.properties.where( {$_.name -notmatch 'utc|now'}).Name if ($AsTable) { Write-Verbose "Formatting output as a table" $tobj | Format-Table -GroupBy @{Name = "Now"; expression = {"$($_.Now) `n UTC: $($_.utc)"}} -Property $cities | Out-String } elseif ($AsList) { Write-Verbose "Formatting output as a list" $tobj | Format-List -GroupBy @{Name = "Now"; expression = {"$($_.Now) `n UTC: $($_.utc)"}} -Property $cities | Out-String } else { Write-Verbose "Writing object to the pipeline" $tobj } Write-Verbose "Ending $($MyInvocation.MyCommand)" } #end function Function Get-TZData { [cmdletbinding()] [OutputType("PSCustomObject", "TimeZoneData")] Param( [Parameter(Position = 0, Mandatory, ValueFromPipeline, HelpMessage = "Enter a timezone location like Pacific/Auckland. It is case sensitive.")] [string]$TimeZoneArea, [parameter(HelpMessage = "Return raw, unformatted data.")] [switch]$Raw ) Begin { Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Starting $($MyInvocation.MyCommand)" $base = "http://worldtimeapi.org/api/timezone" } #begin Process { Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Getting time zone information for $TimeZoneArea " $target = "$base/$TimeZoneArea" Try { $data = Invoke-RestMethod -Uri $target -DisableKeepAlive -UseBasicParsing -ErrorAction Stop -ErrorVariable e if ($data.utc_offset -match "\+") { $offset = ($data.utc_offset.substring(1) -as [timespan]) } else { $offset = ($data.utc_offset -as [timespan]) } } Catch { Throw $e.innerexception } if ($data -AND $Raw -AND ($psEdition -eq 'Core')) { #PowerShell Core automatically converts datetime strings and I want to preserve the raw value $toUTC = ([datetime]$data.datetime).ToUniversalTime().AddHours($offset.hours) [string]$dtstring = "{0:s}.{2:ffffff}{1}" -f ([datetime]$toUTC.datetime), ($data.utc_offset),([datetime]$toUTC.DateTime) $data | Select-Object week_number, utc_offset, unixtime, timezone, @{Name = "dst_until"; expression = {"{0:s}+00:00" -f ([datetime]$data.dst_until).ToUniversalTime() }}, @{Name = "dst_from"; expression = {"{0:s}+00:00" -f ([datetime]$data.dst_from).ToUniversalTime() }}, dst, day_of_year, day_of_week, @{Name = "datetime"; expression = {$dtstring}}, abbreviation } elseif ($data -AND $Raw -AND ($psEdition -eq 'Desktop')) { $data } elseif ($data) { [PSCustomObject]@{ PSTypename = "TimeZoneData" Timezone = $data.timezone Abbreviation = $data.abbreviation Offset = $offset DaylightSavingTime = $data.dst Time = ([datetime]"1/1/1970").AddSeconds($data.unixtime).addhours($offset.hours) } } } #process End { Write-Verbose "[$((Get-Date).TimeOfDay) END ] Ending $($MyInvocation.MyCommand)" } #end } #close Get-TZData Function Get-TZList { [cmdletbinding(DefaultParameterSetName = "zone")] [OutputType("string")] Param( [Parameter(Position = 0, Mandatory, ValueFromPipeline, HelpMessage = "Specify a timezone area", ParameterSetName = "zone")] [ValidateSet('Africa', 'America', 'Antarctica', 'Asia', 'Atlantic', 'Australia', 'Europe', 'Indian', 'Pacific')] [string]$TimeZoneArea, [Parameter(HelpMessage = "Get a list of all timezone areas", ParameterSetName = "all")] [switch]$All ) Begin { Write-Verbose "[$((Get-Date).TimeOfDay) BEGIN ] Starting $($MyInvocation.MyCommand)" $base = "http://worldtimeapi.org/api/timezone" } #begin Process { if ($all) { Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Getting all time zones " $target = $base } else { Write-Verbose "[$((Get-Date).TimeOfDay) PROCESS] Getting time zones for $TimeZoneArea " $target = "$base/$TimeZoneArea" } #because of the way the data is returned and in order to write this to the pipeline #so it can be passed to another command, it appears necessary to add a Foreach-Object #output Invoke-RestMethod -Uri $target -DisableKeepAlive -UseBasicParsing | Foreach-Object {$_} } #process End { Write-Verbose "[$((Get-Date).TimeOfDay) END ] Ending $($MyInvocation.MyCommand)" } #end } #close Get-TZList #endregion |