Add -FromUnixTime to Get-Date to allow Unix time input

[jackdcasey]

PR Summary

My proposal, is to add a -FromUnixTime switch to Get-Date.

This allows the input of a Unix timestamp into Get-Date. This is currently impossible, as the default unit for a numeric input is ticks.

Adding this switch would allow the user to specify if the input is Unix time, while also keeping full previous compatibility with ticks.

Here is an example output with, and without the switch:

> Get-Date -Date 1584947314 -FromUnixTime

 Monday, March 23, 2020 7:08:34 AM

> Get-Date -Date 1584947314

 Monday, January 1, 0001 12:02:38 AM

PR Context

Closes #11719

PR Checklist

• PR has a meaningful title
  • Use the present tense and imperative mood when describing your changes
• Summarized changes
• Make sure all .h, .cpp, .cs, .ps1 and .psm1 files have the correct copyright header
• This PR is ready to merge and is not Work in Progress.
  • If the PR is work in progress, please add the prefix WIP: or [ WIP ] to the beginning of the title (the WIP bot will keep its status check at Pending while the prefix is present) and remove the prefix when the PR is ready.
• Breaking changes
  • None
  • OR
  • Experimental feature(s) needed
    • Experimental feature name(s):
• User-facing changes
  • Not Applicable
  • OR
  • Documentation needed
    • Issue filed: Get-Date, add documentation on -FromUnixTime parameter MicrosoftDocs/PowerShell-Docs#5727
• Testing - New and feature
  • N/A or can only be tested interactively
  • OR
  • Make sure you've added a new test if existing tests do not effectively test the code changed
• Tooling
  • I have considered the user experience from a tooling perspective and don't believe tooling will be impacted.
  • OR
  • I have considered the user experience from a tooling perspective and enumerated concerns in the summary. This may include:
    • Impact on PowerShell Editor Services which is used in the PowerShell extension for VSCode (which runs in a different PS Host).
    • Impact on Completions (both in the console and in editors) - one of PowerShell's most powerful features.
    • Impact on PSScriptAnalyzer (which provides linting & formatting in the editor extensions).
    • Impact on EditorSyntax (which provides syntax highlighting with in VSCode, GitHub, and many other editors).

[jackdcasey]

Upon specifying UTC in the tests, I noticed a small inconsistency.

When specifying the DateTime with ticks, or with unix time, the kind was set as Unspecified instead of Utc.

This was causing issues when combined with the -AsUTC parameter. When performing the conversion, the ToUniversalTime() method is called. This caused inconsistencies, as the local offset would be applied. The documentation for this method confirms this behaviour:

Unspecified | The current DateTime object is assumed to be a local time, and the conversion is performed as if Kind were Local.

To get around this, we can set the kind to Utc explicitly when using ticks or unix time. I've made the following change to facilitate this:

dateToUse = Date

to

dateToUse = DateTime.SpecifyKind(Date, DateTimeKind.Utc);

[iSazonov]

@jackdcasey Please create new issue in PowerShell-Docs repo for the new parameter and add reference in the PR description. Thanks!

[jackdcasey]

Opened issue in MicrosoftDocs/PowerShell-Docs: MicrosoftDocs/PowerShell-Docs#5727

[iSazonov]

@jackdcasey Thanks for your contribution!

[jackdcasey]

@iSazonov Thank you for all the help!

[ghost]

🎉v7.1.0-preview.2 has been released which incorporates this pull request.:tada:

Handy links:

• Release Notes

[aetos382]

Negative UnixTime is not supported?

PS /> Get-Date -Date -1 -FromUnixTime
Get-Date: Cannot bind parameter 'Date'. Cannot convert value "-1" to type "System.DateTime". Error: "String '-1' was not recognized as a valid DateTime."

[iSazonov]

@aetos382 No. If you have a feature request please open new issue.